castle-web-cli 0.4.239 → 0.4.240

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (386) hide show
  1. package/dist/agent.js +5 -1
  2. package/dist/api.d.ts +20 -0
  3. package/dist/api.js +57 -0
  4. package/dist/bundle.d.ts +38 -1
  5. package/dist/bundle.js +309 -13
  6. package/dist/castle-host/host.js +163 -11
  7. package/dist/castleJson.d.ts +10 -0
  8. package/dist/castleJson.js +46 -2
  9. package/dist/check.js +5 -2
  10. package/dist/devSessionServer.js +4 -1
  11. package/dist/devSessionStorage.d.ts +1 -0
  12. package/dist/devSessionStorage.js +32 -7
  13. package/dist/importOrder.d.ts +2 -0
  14. package/dist/importOrder.js +29 -0
  15. package/dist/index.js +6 -3
  16. package/dist/init.js +24 -2
  17. package/dist/platformDoc.js +2 -1
  18. package/dist/playPagePolicy.js +5 -1
  19. package/dist/resetLeaderboards.d.ts +8 -1
  20. package/dist/resetLeaderboards.js +43 -8
  21. package/dist/save-deck.d.ts +32 -2
  22. package/dist/save-deck.js +240 -39
  23. package/kits/base/CLAUDE.md +1 -1
  24. package/kits/base/castle.json +1 -1
  25. package/kits/base/sdk/README.md +174 -6
  26. package/kits/base/sdk/analytics.d.ts +8 -0
  27. package/kits/base/sdk/analytics.js +92 -0
  28. package/kits/base/sdk/castle.d.ts +5 -1
  29. package/kits/base/sdk/castle.js +2 -0
  30. package/kits/base/sdk/commands.d.ts +48 -0
  31. package/kits/base/sdk/commands.js +1 -0
  32. package/kits/base/sdk/debugConsole.d.ts +17 -0
  33. package/kits/base/sdk/debugConsole.js +154 -0
  34. package/kits/base/sdk/experiments.js +24 -1
  35. package/kits/base/sdk/hostRetry.d.ts +7 -0
  36. package/kits/base/sdk/hostRetry.js +57 -0
  37. package/kits/base/sdk/hub.d.ts +20 -2
  38. package/kits/base/sdk/hub.js +99 -13
  39. package/kits/base/sdk/multiplayer.d.ts +2 -0
  40. package/kits/base/sdk/multiplayer.js +168 -26
  41. package/kits/base/sdk/reconnectBudget.d.ts +6 -0
  42. package/kits/base/sdk/reconnectBudget.js +41 -1
  43. package/kits/base/sdk/runtime.js +36 -19
  44. package/kits/base/sdk/server/hub.d.ts +19 -0
  45. package/kits/base/sdk/server/hub.js +12 -0
  46. package/kits/base/sdk/server/platformHandle.d.ts +1 -0
  47. package/kits/base/sdk/server/wrapper.d.ts +1 -1
  48. package/kits/base/sdk/server/wrapper.js +26 -1
  49. package/kits/base/sdk/transport.d.ts +2 -1
  50. package/kits/base/sdk/transport.js +35 -0
  51. package/kits/hub-game/CLAUDE.md +66 -19
  52. package/kits/hub-game/code/client/act.js +9 -6
  53. package/kits/hub-game/code/client/actCore.js +26 -6
  54. package/kits/hub-game/code/client/actGateLog.js +36 -0
  55. package/kits/hub-game/code/client/actionOverflow.js +29 -8
  56. package/kits/hub-game/code/client/actionRailSurface.js +186 -0
  57. package/kits/hub-game/code/client/actionRailTree.js +173 -0
  58. package/kits/hub-game/code/client/askSurface.js +85 -0
  59. package/kits/hub-game/code/client/askTree.js +51 -0
  60. package/kits/hub-game/code/client/attention.js +31 -6
  61. package/kits/hub-game/code/client/ballot.js +42 -5
  62. package/kits/hub-game/code/client/ballotSurface.js +115 -0
  63. package/kits/hub-game/code/client/ballotTree.js +180 -0
  64. package/kits/hub-game/code/client/catchingUp.js +19 -0
  65. package/kits/hub-game/code/client/celebrate.js +66 -0
  66. package/kits/hub-game/code/client/chrome.js +473 -53
  67. package/kits/hub-game/code/client/companion.js +93 -23
  68. package/kits/hub-game/code/client/companionDress.js +1 -1
  69. package/kits/hub-game/code/client/cornerSurface.js +106 -0
  70. package/kits/hub-game/code/client/cornerTree.js +83 -0
  71. package/kits/hub-game/code/client/decor.js +20 -11
  72. package/kits/hub-game/code/client/deviceStorage.js +121 -0
  73. package/kits/hub-game/code/client/disguise.js +23 -0
  74. package/kits/hub-game/code/client/disguiseDraw.js +87 -0
  75. package/kits/hub-game/code/client/dockSurface.js +206 -0
  76. package/kits/hub-game/code/client/dockTree.js +232 -0
  77. package/kits/hub-game/code/client/earned.js +29 -0
  78. package/kits/hub-game/code/client/emoteSurface.js +188 -0
  79. package/kits/hub-game/code/client/emoteTree.js +264 -0
  80. package/kits/hub-game/code/client/farAvatars.js +4 -3
  81. package/kits/hub-game/code/client/fpsTelemetry.js +3 -1
  82. package/kits/hub-game/code/client/grab.js +121 -50
  83. package/kits/hub-game/code/client/holdShow.js +19 -0
  84. package/kits/hub-game/code/client/hookLayer.js +96 -12
  85. package/kits/hub-game/code/client/hubControls.js +7 -1
  86. package/kits/hub-game/code/client/hudSurface.js +11 -3
  87. package/kits/hub-game/code/client/hudTree.js +7 -4
  88. package/kits/hub-game/code/client/idle.js +21 -3
  89. package/kits/hub-game/code/client/invites.js +24 -3
  90. package/kits/hub-game/code/client/keys.js +15 -0
  91. package/kits/hub-game/code/client/labelsNear.js +8 -1
  92. package/kits/hub-game/code/client/layoutCache.js +57 -8
  93. package/kits/hub-game/code/client/loadingCover.js +53 -4
  94. package/kits/hub-game/code/client/menuIcons.js +15 -0
  95. package/kits/hub-game/code/client/menuSurface.js +102 -0
  96. package/kits/hub-game/code/client/menuTree.js +135 -0
  97. package/kits/hub-game/code/client/modelLook.js +41 -0
  98. package/kits/hub-game/code/client/pickerSurface.js +152 -0
  99. package/kits/hub-game/code/client/pickerTree.js +163 -0
  100. package/kits/hub-game/code/client/pushVisit.js +4 -2
  101. package/kits/hub-game/code/client/quality.js +188 -29
  102. package/kits/hub-game/code/client/qualityEntry.js +10 -1
  103. package/kits/hub-game/code/client/quickChatSurface.js +222 -0
  104. package/kits/hub-game/code/client/quickChatTree.js +201 -0
  105. package/kits/hub-game/code/client/rehello.js +75 -0
  106. package/kits/hub-game/code/client/renderVisibility.js +17 -0
  107. package/kits/hub-game/code/client/replay.js +118 -0
  108. package/kits/hub-game/code/client/role.js +3 -0
  109. package/kits/hub-game/code/client/safeLayout.js +441 -56
  110. package/kits/hub-game/code/client/safeStyle.js +13 -10
  111. package/kits/hub-game/code/client/say.js +2 -0
  112. package/kits/hub-game/code/client/soundSurface.js +77 -0
  113. package/kits/hub-game/code/client/soundTree.js +74 -0
  114. package/kits/hub-game/code/client/soundscape.js +12 -9
  115. package/kits/hub-game/code/client/soundscapeCues.js +1 -1
  116. package/kits/hub-game/code/client/state.js +67 -1
  117. package/kits/hub-game/code/client/stuckSurface.js +76 -0
  118. package/kits/hub-game/code/client/stuckTree.js +67 -0
  119. package/kits/hub-game/code/client/talk.js +42 -12
  120. package/kits/hub-game/code/client/talkTree.js +4 -2
  121. package/kits/hub-game/code/client/textAskSurface.js +147 -0
  122. package/kits/hub-game/code/client/textAskTree.js +67 -0
  123. package/kits/hub-game/code/client/tiers.js +252 -27
  124. package/kits/hub-game/code/client/together.js +4 -1
  125. package/kits/hub-game/code/client/uiDom.js +86 -8
  126. package/kits/hub-game/code/client/uiTree.js +33 -4
  127. package/kits/hub-game/code/client/vehicle.js +72 -51
  128. package/kits/hub-game/code/client/weakestTier.js +75 -31
  129. package/kits/hub-game/code/client/wear.js +159 -5
  130. package/kits/hub-game/code/client/worldLabels.js +205 -25
  131. package/kits/hub-game/code/companionSpec.js +4 -2
  132. package/kits/hub-game/code/server/act.js +3 -0
  133. package/kits/hub-game/code/server/actGate.js +83 -0
  134. package/kits/hub-game/code/server/actions.js +71 -15
  135. package/kits/hub-game/code/server/actors.js +20 -5
  136. package/kits/hub-game/code/server/analytics.js +35 -3
  137. package/kits/hub-game/code/server/ask.js +39 -3
  138. package/kits/hub-game/code/server/ballot.js +167 -4
  139. package/kits/hub-game/code/server/celebrate.js +64 -0
  140. package/kits/hub-game/code/server/companion.js +17 -2
  141. package/kits/hub-game/code/server/decor.js +11 -2
  142. package/kits/hub-game/code/server/disguise.js +63 -0
  143. package/kits/hub-game/code/server/earned.js +6 -2
  144. package/kits/hub-game/code/server/friendBests.js +13 -4
  145. package/kits/hub-game/code/server/friendsAmong.js +67 -8
  146. package/kits/hub-game/code/server/grab.js +12 -2
  147. package/kits/hub-game/code/server/heldOffers.js +142 -0
  148. package/kits/hub-game/code/server/holdShow.js +98 -0
  149. package/kits/hub-game/code/server/hub.js +851 -45
  150. package/kits/hub-game/code/server/idle.js +110 -9
  151. package/kits/hub-game/code/server/index.js +9 -0
  152. package/kits/hub-game/code/server/labels.js +13 -3
  153. package/kits/hub-game/code/server/manifest.js +94 -6
  154. package/kits/hub-game/code/server/menu.js +26 -3
  155. package/kits/hub-game/code/server/npcs.js +55 -9
  156. package/kits/hub-game/code/server/observe.js +67 -6
  157. package/kits/hub-game/code/server/players.js +8 -1
  158. package/kits/hub-game/code/server/replay.js +135 -0
  159. package/kits/hub-game/code/server/storageLimit.js +4 -1
  160. package/kits/hub-game/code/server/townDay.js +74 -0
  161. package/kits/hub-game/code/server/vehicle.js +3 -0
  162. package/kits/hub-game/code/server/vis.js +26 -4
  163. package/kits/hub-game/code/server/wallet.js +677 -0
  164. package/kits/hub-game/code/server/wear.js +13 -3
  165. package/kits/hub-game/code/server/writerLease.js +191 -0
  166. package/kits/hub-game/code/shared/act.js +1 -1
  167. package/kits/hub-game/code/shared/expression.js +6 -0
  168. package/kits/hub-game/code/shared/replay.js +37 -0
  169. package/kits/hub-game/code/systems/hub.js +427 -54
  170. package/kits/hub-game/docs/analytics.md +16 -2
  171. package/kits/hub-game/docs/contract.md +942 -99
  172. package/kits/hub-game/docs/home-pieces.md +5 -6
  173. package/kits/hub-game/docs/observed-progress.md +49 -1
  174. package/kits/hub-game/docs/vehicle-preset.md +23 -0
  175. package/kits/hub-game/index.html +1 -0
  176. package/kits/hub-game/models/hats/baker-cap.pxmodel +3 -3
  177. package/kits/hub-game/models/hats/bat-clip.pxmodel +3 -3
  178. package/kits/hub-game/models/hats/beekeeper.pxmodel +3 -3
  179. package/kits/hub-game/models/hats/cap.pxmodel +3 -3
  180. package/kits/hub-game/models/hats/captain.pxmodel +3 -3
  181. package/kits/hub-game/models/hats/chef-toque.pxmodel +3 -3
  182. package/kits/hub-game/models/hats/crooked-top.pxmodel +3 -3
  183. package/kits/hub-game/models/hats/delivery-cap.pxmodel +3 -3
  184. package/kits/hub-game/models/hats/fire-helmet.pxmodel +3 -3
  185. package/kits/hub-game/models/hats/flower-crown.pxmodel +3 -3
  186. package/kits/hub-game/models/hats/foam-crown.pxmodel +3 -3
  187. package/kits/hub-game/models/hats/hard-hat.pxmodel +3 -3
  188. package/kits/hub-game/models/hats/lantern.pxmodel +3 -3
  189. package/kits/hub-game/models/hats/laurel.pxmodel +3 -3
  190. package/kits/hub-game/models/hats/lighthouse.pxmodel +3 -3
  191. package/kits/hub-game/models/hats/nurse-cap.pxmodel +3 -3
  192. package/kits/hub-game/models/hats/police-cap.pxmodel +3 -3
  193. package/kits/hub-game/models/hats/sailor.pxmodel +3 -3
  194. package/kits/hub-game/models/hats/souwester.pxmodel +3 -3
  195. package/kits/hub-game/models/hats/straw.pxmodel +3 -3
  196. package/kits/hub-game/models/hats/sunflower.pxmodel +3 -3
  197. package/kits/hub-game/models/hats/sweatband.pxmodel +3 -3
  198. package/kits/hub-game/models/hats/teacher-beret.pxmodel +3 -3
  199. package/kits/hub-game/models/hats/witch.pxmodel +3 -3
  200. package/kits/hub-game/models/hold-show/daisy.pxmodel +231 -0
  201. package/kits/hub-game/models/hold-show/moonflower.pxmodel +171 -0
  202. package/kits/hub-game/models/hold-show/rose.pxmodel +191 -0
  203. package/kits/hub-game/models/hold-show/square/daisy.pxmodel +233 -0
  204. package/kits/hub-game/models/hold-show/square/moonflower.pxmodel +173 -0
  205. package/kits/hub-game/models/hold-show/square/rose.pxmodel +193 -0
  206. package/kits/hub-game/models/hold-show/square/sunflower.pxmodel +313 -0
  207. package/kits/hub-game/models/hold-show/square/tulip.pxmodel +133 -0
  208. package/kits/hub-game/models/hold-show/sunflower.pxmodel +311 -0
  209. package/kits/hub-game/models/hold-show/tulip.pxmodel +131 -0
  210. package/kits/hub-game/package-lock.json +3 -3
  211. package/kits/hub-game/package.json +4 -3
  212. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +1 -0
  213. package/kits/hub-game/scripts/fixtures/hud-surface.json +12 -12
  214. package/kits/hub-game/scripts/fixtures/talk-surface.json +8 -8
  215. package/kits/hub-game/scripts/gen-hats.mjs +1 -1
  216. package/kits/hub-game/scripts/gen-hold-show.mjs +27 -0
  217. package/kits/hub-game/scripts/pack.mjs +89 -23
  218. package/kits/hub-game/scripts/test-act-client.mjs +5 -0
  219. package/kits/hub-game/scripts/test-act-core.mjs +32 -0
  220. package/kits/hub-game/scripts/test-act-gate.mjs +186 -0
  221. package/kits/hub-game/scripts/test-action-rail-crowded-dom.mjs +7 -1
  222. package/kits/hub-game/scripts/test-action-rail-default-dom.mjs +102 -0
  223. package/kits/hub-game/scripts/test-action-rail-never-silent-dom.mjs +50 -0
  224. package/kits/hub-game/scripts/test-action-rail-surface.mjs +368 -0
  225. package/kits/hub-game/scripts/test-action-rail-town-jobs-dom.mjs +118 -0
  226. package/kits/hub-game/scripts/test-actions-client.mjs +5 -3
  227. package/kits/hub-game/scripts/test-actions.mjs +24 -0
  228. package/kits/hub-game/scripts/test-actors.mjs +19 -0
  229. package/kits/hub-game/scripts/test-again-corner-dom.mjs +59 -0
  230. package/kits/hub-game/scripts/test-analytics.mjs +79 -0
  231. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +25 -8
  232. package/kits/hub-game/scripts/test-ask-client.mjs +9 -0
  233. package/kits/hub-game/scripts/test-ask-surface.mjs +188 -0
  234. package/kits/hub-game/scripts/test-attention.mjs +43 -1
  235. package/kits/hub-game/scripts/test-ballot-sheet-dom.mjs +71 -0
  236. package/kits/hub-game/scripts/test-ballot-surface.mjs +276 -0
  237. package/kits/hub-game/scripts/test-ballot.mjs +420 -3
  238. package/kits/hub-game/scripts/test-ban-join.mjs +1 -1
  239. package/kits/hub-game/scripts/test-celebrate-client.mjs +62 -0
  240. package/kits/hub-game/scripts/test-celebrate.mjs +116 -0
  241. package/kits/hub-game/scripts/test-chat.mjs +73 -0
  242. package/kits/hub-game/scripts/test-companion-client.mjs +203 -21
  243. package/kits/hub-game/scripts/test-companion.mjs +110 -3
  244. package/kits/hub-game/scripts/test-control-layout-dom.mjs +57 -10
  245. package/kits/hub-game/scripts/test-corner-surface.mjs +268 -0
  246. package/kits/hub-game/scripts/test-decor-client.mjs +59 -3
  247. package/kits/hub-game/scripts/test-decor.mjs +27 -0
  248. package/kits/hub-game/scripts/test-device-class.mjs +4 -1
  249. package/kits/hub-game/scripts/test-disguise-client.mjs +281 -0
  250. package/kits/hub-game/scripts/test-disguise.mjs +176 -0
  251. package/kits/hub-game/scripts/test-dock-surface.mjs +404 -0
  252. package/kits/hub-game/scripts/test-door-stay-client.mjs +602 -0
  253. package/kits/hub-game/scripts/test-door-stay.mjs +613 -0
  254. package/kits/hub-game/scripts/test-earned-client.mjs +119 -0
  255. package/kits/hub-game/scripts/test-emote-surface.mjs +616 -0
  256. package/kits/hub-game/scripts/test-fps-telemetry.mjs +39 -4
  257. package/kits/hub-game/scripts/test-friend-bests.mjs +38 -12
  258. package/kits/hub-game/scripts/test-ghost-click-dom.mjs +75 -0
  259. package/kits/hub-game/scripts/test-grab-client.mjs +29 -2
  260. package/kits/hub-game/scripts/test-grab-orbit.mjs +260 -11
  261. package/kits/hub-game/scripts/test-grab.mjs +10 -1
  262. package/kits/hub-game/scripts/test-hats.mjs +28 -0
  263. package/kits/hub-game/scripts/test-held-offers.mjs +394 -0
  264. package/kits/hub-game/scripts/test-high-only.mjs +3 -3
  265. package/kits/hub-game/scripts/test-hold-show-client.mjs +175 -0
  266. package/kits/hub-game/scripts/test-hold-show.mjs +355 -0
  267. package/kits/hub-game/scripts/test-hub-controls.mjs +3 -1
  268. package/kits/hub-game/scripts/test-hub-idle.mjs +348 -0
  269. package/kits/hub-game/scripts/test-hub-leaving.mjs +21 -0
  270. package/kits/hub-game/scripts/test-hub-ops.mjs +119 -0
  271. package/kits/hub-game/scripts/test-hub-trip.mjs +240 -4
  272. package/kits/hub-game/scripts/test-hud-clear.mjs +83 -0
  273. package/kits/hub-game/scripts/test-hud-rate.mjs +2 -1
  274. package/kits/hub-game/scripts/test-idle.mjs +160 -0
  275. package/kits/hub-game/scripts/test-invites-client.mjs +53 -0
  276. package/kits/hub-game/scripts/test-labels.mjs +11 -0
  277. package/kits/hub-game/scripts/test-landscape-layout.mjs +20 -0
  278. package/kits/hub-game/scripts/test-loading-cover.mjs +67 -1
  279. package/kits/hub-game/scripts/test-manifest.mjs +27 -0
  280. package/kits/hub-game/scripts/test-menu-client.mjs +54 -5
  281. package/kits/hub-game/scripts/test-menu-surface.mjs +236 -0
  282. package/kits/hub-game/scripts/test-npcs.mjs +128 -0
  283. package/kits/hub-game/scripts/test-observed.mjs +171 -3
  284. package/kits/hub-game/scripts/test-pack.mjs +166 -0
  285. package/kits/hub-game/scripts/test-picker-surface.mjs +321 -0
  286. package/kits/hub-game/scripts/test-placeat-server.mjs +395 -0
  287. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  288. package/kits/hub-game/scripts/test-pointer-clear-dom.mjs +82 -0
  289. package/kits/hub-game/scripts/test-progress-reset.mjs +184 -6
  290. package/kits/hub-game/scripts/test-push-visit.mjs +9 -0
  291. package/kits/hub-game/scripts/test-quality.mjs +312 -9
  292. package/kits/hub-game/scripts/test-quick-chat-surface.mjs +511 -0
  293. package/kits/hub-game/scripts/test-rehello.mjs +237 -0
  294. package/kits/hub-game/scripts/test-rejoin-yaw.mjs +138 -0
  295. package/kits/hub-game/scripts/test-relations-among.mjs +13 -7
  296. package/kits/hub-game/scripts/test-relations-refresh.mjs +90 -2
  297. package/kits/hub-game/scripts/test-replay-client.mjs +110 -0
  298. package/kits/hub-game/scripts/test-replay.mjs +178 -0
  299. package/kits/hub-game/scripts/test-resume-held.mjs +13 -0
  300. package/kits/hub-game/scripts/test-resume-pose-server.mjs +43 -5
  301. package/kits/hub-game/scripts/test-role-client.mjs +2 -1
  302. package/kits/hub-game/scripts/test-safe-act.mjs +233 -0
  303. package/kits/hub-game/scripts/test-safe-caption.mjs +364 -0
  304. package/kits/hub-game/scripts/test-safe-layout.mjs +79 -0
  305. package/kits/hub-game/scripts/test-safe-prompt.mjs +163 -0
  306. package/kits/hub-game/scripts/test-sound-surface.mjs +256 -0
  307. package/kits/hub-game/scripts/test-soundscape.mjs +85 -2
  308. package/kits/hub-game/scripts/test-stuck-surface.mjs +174 -0
  309. package/kits/hub-game/scripts/test-stuck.mjs +31 -0
  310. package/kits/hub-game/scripts/test-talk-surface.mjs +23 -6
  311. package/kits/hub-game/scripts/test-talk-walk-dom.mjs +123 -0
  312. package/kits/hub-game/scripts/test-text-ask-surface.mjs +273 -0
  313. package/kits/hub-game/scripts/test-tiers.mjs +453 -3
  314. package/kits/hub-game/scripts/test-toast-no-row-dom.mjs +71 -0
  315. package/kits/hub-game/scripts/test-together.mjs +11 -0
  316. package/kits/hub-game/scripts/test-town-day.mjs +90 -0
  317. package/kits/hub-game/scripts/test-try-on.mjs +39 -0
  318. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +49 -2
  319. package/kits/hub-game/scripts/test-ui-tree.mjs +28 -0
  320. package/kits/hub-game/scripts/test-vehicle-client.mjs +68 -1
  321. package/kits/hub-game/scripts/test-vis.mjs +145 -0
  322. package/kits/hub-game/scripts/test-wallet.mjs +650 -0
  323. package/kits/hub-game/scripts/test-weakest-tier.mjs +135 -1
  324. package/kits/hub-game/scripts/test-world-labels.mjs +340 -0
  325. package/kits/hub-game/scripts/test-writer-lease-server.mjs +234 -0
  326. package/kits/hub-game/scripts/test-writer-lease.mjs +281 -0
  327. package/kits/hub-game/scripts/writer-storage-fixture.mjs +37 -0
  328. package/kits/hub-game/tools/hubScene/export.mjs +6 -5
  329. package/kits/hub-game/tools/hubScene/hubdata.mjs +10 -0
  330. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +36 -2
  331. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +10 -2
  332. package/kits/multiplayer-3d/castle.json +5 -5
  333. package/kits/multiplayer-3d/code/client/resumeGate.js +49 -2
  334. package/kits/multiplayer-3d/code/server/ownership.js +25 -6
  335. package/kits/multiplayer-3d/code/server/world.js +19 -4
  336. package/kits/multiplayer-3d/code/systems/multiplayer.js +67 -11
  337. package/kits/multiplayer-3d/package-lock.json +1 -1
  338. package/kits/multiplayer-3d/package.json +2 -1
  339. package/kits/multiplayer-3d/scripts/test-ground-half.mjs +56 -0
  340. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +54 -3
  341. package/kits/multiplayer-3d/scripts/test-owned-moves.mjs +190 -0
  342. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +191 -5
  343. package/kits/multiplayer-3d/scripts/test-resync-reconnect.mjs +68 -0
  344. package/kits/physics-2d/castle.json +2 -2
  345. package/kits/physics-2d/engine/scene.js +10 -2
  346. package/kits/physics-3d/CLAUDE.md +14 -0
  347. package/kits/physics-3d/behaviors/Player.jsx +39 -3
  348. package/kits/physics-3d/castle.json +3 -3
  349. package/kits/physics-3d/docs/engine-model-cache.md +109 -0
  350. package/kits/physics-3d/docs/engine-player.md +76 -0
  351. package/kits/physics-3d/docs/engine-skip-work.md +16 -0
  352. package/kits/physics-3d/docs/pxmodel-format.md +5 -1
  353. package/kits/physics-3d/engine3d/gait.js +16 -8
  354. package/kits/physics-3d/engine3d/groundsize.js +23 -0
  355. package/kits/physics-3d/engine3d/kithooks.js +50 -0
  356. package/kits/physics-3d/engine3d/look.js +110 -17
  357. package/kits/physics-3d/engine3d/lookbake.js +19 -1
  358. package/kits/physics-3d/engine3d/materialpresets.js +3 -2
  359. package/kits/physics-3d/engine3d/modelcache.js +280 -0
  360. package/kits/physics-3d/engine3d/modelcachedigest.js +37 -0
  361. package/kits/physics-3d/engine3d/modelcachegate.js +69 -0
  362. package/kits/physics-3d/engine3d/modelrefs.js +13 -0
  363. package/kits/physics-3d/engine3d/optimize.js +20 -9
  364. package/kits/physics-3d/engine3d/playerRun.js +26 -1
  365. package/kits/physics-3d/engine3d/pxmodel.js +7 -3
  366. package/kits/physics-3d/engine3d/templatecache.js +722 -0
  367. package/kits/physics-3d/engine3d/world3d.js +211 -17
  368. package/kits/physics-3d/package-lock.json +1 -1
  369. package/kits/physics-3d/package.json +2 -1
  370. package/kits/physics-3d/play/behaviors/Player.js +43 -3
  371. package/kits/physics-3d/scripts/render.mjs +56 -8
  372. package/kits/physics-3d/scripts/template-cache-fixtures.mjs +37 -0
  373. package/kits/physics-3d/scripts/template-cache-v1-bytes.json +49 -0
  374. package/kits/physics-3d/scripts/test-gait.mjs +53 -9
  375. package/kits/physics-3d/scripts/test-ground-half.mjs +120 -0
  376. package/kits/physics-3d/scripts/test-model-cache.mjs +600 -0
  377. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1 -0
  378. package/kits/physics-3d/scripts/test-sleeping-models.mjs +384 -0
  379. package/kits/physics-3d/scripts/test-template-cache-minified.mjs +106 -0
  380. package/kits/physics-3d/scripts/test-template-cache.mjs +519 -0
  381. package/kits/physics-3d/scripts/test-wall-slide.mjs +272 -0
  382. package/kits/physics-3d/systems/physics3d.js +51 -2
  383. package/kits/real-time/castle.json +2 -2
  384. package/kits/real-time/code/client/connection.js +3 -0
  385. package/package.json +2 -2
  386. package/vendor/three/examples/jsm/libs/fflate.module.js +2672 -0
@@ -1,6 +1,6 @@
1
1
  # The hub-game contract
2
2
 
3
- **Version 1.157** (2026-10-20; v1 plus the optional additions under "Changes in
3
+ **Version 1.205** (2026-10-30; v1 plus the optional additions under "Changes in
4
4
  v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
5
5
  `cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
6
6
  contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
@@ -112,8 +112,9 @@ reading the saved deck, treats the same list as no unlocks at all.
112
112
 
113
113
  | field | type | rule |
114
114
  | --- | --- | --- |
115
+ | `holdShow` | true | v1.182, top-level only: exposes `hub.holdShow` and `hub.holdShowing` for visit-only right-hand flowers (§11). Only `true` is valid; absent means neither API exists. |
115
116
  | `frameBatch` | true | v1.106, top-level: paced player envelopes from the first packet, one normal frame per player per tick, FIFO replay paced against an aggregate byte bucket. Visit controls take priority over replay. Requires updated real-time and multiplayer-3d decoder imports; ACK timing never bypasses pacing. Absent key preserves existing bytes and order. |
116
- | `fpsTelemetry` | absent | Optional main-place FPS summaries; requires `analytics: true`, a full lowercase `buildSha` and the main `scene`. Client message `hub-fps` carries only validated numeric measurements and that fixed scene; Ghost stamps pinned build attribution on kind 26. See [analytics](analytics.md). |
117
+ | `fpsTelemetry` | absent | Optional main-place FPS summaries; requires `analytics: true`, a full lowercase `buildSha` and the main `scene`. Client message `hub-fps` carries validated numeric measurements and that fixed scene, plus optional v1.178 `quality: "hide" \| "skip"` for active `hub.quality` Low (omitted otherwise); Ghost v1.178 is required because older Ghost refuses the unknown key; Ghost stamps pinned build attribution on kind 26. See [analytics](analytics.md). |
117
118
  | `loadTelemetry` | true | v1.138, main place only; requires `analytics: true` and `analyticsV111: true`. The server reports kind 27 `load_abandoned` for a transport connection that leaves or waits 30 s without arriving (checked on every transport tick, before the simulation exists too); the snapshot's `hubPlace.loadTelemetry` tells the browser to send `{ k: 'hub-load', stage: 4 }` once when its body is placed before `hub-arrived`. Not in houses. See [analytics](analytics.md#load-abandoned-v1138). |
118
119
  | `analyticsV111` | true | v1.111, main place only and requires `analytics: true`: Ghost-owned invite lifecycle, arrival-source and public-join-failure events. Server-config/pin only; no host-spec or client-wire field. Absent preserves all v1.93 behavior and emits none of kinds 21–25. See [analytics](analytics.md). |
119
120
  | `contract` | integer | `1`. A deck naming a version the kit does not know is refused (check fails; the server logs and runs nothing). |
@@ -138,18 +139,22 @@ reading the saved deck, treats the same list as no unlocks at all.
138
139
  | `resume` | true or object | v1.72, a place's (`hub.resume` or `hub.places.<id>.resume`), valid only on a place with `result`: `true` says the place's game handles a player's return within a round, so a player the platform let go and who comes back under the same player id is arrived again once (§12, `hub-hello`). The visit goes on: one result per visit (a second `hub.result` is refused, a result reported in `leave` included), one deadline from the first arrival, the end sent again to an ended visit, and the first door kept. v1.89 also accepts exactly `{ keep: true }`: retain the player entry for a same-id reconnect within 60 seconds of observed absence, with no `leave` or `arrive`; see §12. Other values, extra object keys, or the key on a place without `result` are manifest errors. Absent: a game takes no same-id re-hello and no late greet (unchanged), with no extra state, message, field or listener; existing wire bytes stay identical. |
139
140
  | `resumeVisibility` | true | v1.116, per place, server-only, and valid only with `resume: { keep: true }` and an exported `resume` hook: preserve an authenticated player's per-viewer `hub.hide/show` overrides during that retained visit's strictly less than 60-second absence. On return the stale replay and action dispatch are held, the authored `resume` hook runs before the next authored `step`, and the resulting whole override is sent (§10/§12). Blocked preparation or a synchronous hook throw ends and forgets only the affected retained visit before authored stepping; the place never waits. The hook must synchronously rebuild current masks before returning or first awaiting. The trusted account must still match; changed identity receives only a clear. Explicit travel, expiry, shutdown and ordinary forget delete the cache. Disconnected targets remain ignored. Any value but `true`, or use with another retention mode, is a manifest error. Absent: resume ordering, cleanup and wire behavior stay unchanged. No new public manifest or wire field. |
140
141
  | `resumeArrivalPose` | true | v1.117, optional per place: preserve only the last server pose/facing for a same-player-id, same signed-in account reconnect strictly within 60 wall-clock seconds. Ordinary immediate `leave` and fresh `arrive` still run; the pose replaces normal placement after `arrive`. Result places also require `resume: true`. Cannot combine with `resume: { keep: true }`, `resumePose`, or `houseResume`. Server-only; absent leaves state, lifecycle and wire bytes unchanged. See §12. |
141
- | `resumePose` | true | v1.98, per non-result place only: retain a same-id visit and its last pose/facing for strictly less than five wall-clock minutes, restoring before hello replay or the deck step. No leave/arrive on retention; explicit kit travel, expiry and shutdown still leave, and new IDs may restore a server-stored pose for the same account/place within ten minutes of departure; kit travel clears it. Absent: no retention state or behavior change. Server-only; no new wire fields. See §12. |
142
+ | `writerLease` | true | v1.192, optional per place: newest instance to claim an account owns its per-player saves. Requires the host save API; otherwise pass-through. Server-only. See Writer leases below. |
143
+ | `resumePose` | true | v1.98, per non-result place only: retain a same-id visit and its last pose/facing for strictly less than five wall-clock minutes, restoring before hello replay or the deck step. No leave/arrive on retention; explicit kit travel, expiry and shutdown still leave, and new IDs may restore a server-stored pose for the same account/place within ten minutes of departure; kit travel clears it, and so does a drop right after the player's own Back (v1.173 `hub-back`, §12). Absent: no retention state or behavior change. Server-only; no new wire fields. See §12. |
144
+ | `resumeWindowSec` | integer | v1.199, per place without a result: a whole number of seconds, 1 to 180, that Castle holds a dropped player's visit for. On a capable host Ghost pins it into the session as `reconnectWindowMs`, and the kit then retains the same visit and pose through that deadline (inclusive) with no leave or arrival hook, as it does for the Town ("Door resume window"). Any other value, or the key with `result`, `resumePose`, `houseResume` or `resumeArrivalPose`, is a manifest error. Absent, an older Ghost or a host without reconnect grace: no window, and a drop ends the visit as before. Server-only; no wire change. |
145
+ | `heldOffers` | true | v1.180, per place, server-only: `hub.actions`, `hub.ask` and `hub.menu` offers made to a retained player are kept while they are away and replayed with fresh versions on their resume hello; calls made while away are recorded, not sent, and the latest is delivered at resume. Kept only for the same transport id, signed-in account and visit body (§12 "Held offers"). Only `true`; any other value is a manifest error, and so is the key in a place with no resume mode (`resume: { keep: true }`, `resumePose`, `houseResume`, or a place without a result, which a host may pin a reconnect window on; `resumeArrivalPose` has none). Absent: offers are pruned while disconnected and places re-offer from their resume hook, with identical behaviour and bytes. |
142
146
  | `talkLog` | true | v1.101, per place: NPC talk input and replies append to the platform’s private indefinite archive. Authored answers/openings wait for durable acknowledgment; model input/reply commit with their jobs. No player read API or TTL. Requires a host/runtime that offers transcript support; unavailable writes stop the answer. Absent key performs no archive requests and preserves existing protocol. |
143
147
  | `under13Choices` | true | Authored mind taps lead both published `childAsks` and legacy choices, including here (v1.150, §13). Otherwise published mind `childAsks` take precedence in every place (v1.142); otherwise v1.101, per place: NPC conversations for a player whose trusted server identity has `under13 === true` offer three canned lines and hide the text field. Both authored and model admission paths reject other words. Missing age stamp defaults false. Absent key preserves existing UI and protocol bytes; no client age inference. |
144
148
  | `freshFriends` | true | v1.99, per place: positive and negative friend permissions expire after 31 seconds. Expired entries revalidate before returning a friend; refusal, malformed reply or a 900 ms timeout returns no friends. The shared read latch preserves the 31-second minimum read gap. Server-only `hub.freshFriends === true` is exposed only in opted-in places; absent keys retain existing cache, API and wire behavior. |
145
149
  | `menu` | boolean | v1.79, a place's (`hub.menu` or `hub.places.<id>.menu`): only `true` enables a private place menu (§9). Any other value is a manifest error. Absent: no API, menu hook lookup, private state, chrome, message, snapshot or delta key; existing wire bytes stay identical. |
146
150
  | `ask` | boolean | v1.75, a place's (`hub.ask` or `hub.places.<id>.ask`): only `true` enables a private text prompt (§9). Any other value is a manifest error. Absent: no API, answer hook lookup, private state, chrome, message, snapshot or delta key; existing behavior and wire bytes stay identical. |
147
- | `ballot` | boolean or object | v1.68, a place's (the main block or a place under `places`). `true` (the card with no lines: faces and options only), or `{ lines }`: at most 32 lines, each `{ id, text, about }` -- `id` `[a-z0-9-]`, 1-24 characters, never twice; `text` 1-40 characters on one line (trimmed); `about` `"face"` (said about a player whose face is tapped first: "I saw them by the boat") or `"self"` (said by the speaker alone: "Not me!"). Any other key, here or in a line, is a manifest error. These lines are the only words a player can send through the card (§6, "The choice card"). `false` or absent: no card, no message, no snapshot field, no chrome; the place is sent and drawn exactly what it was. The client is told the lines in `hubPlace.ballot`. |
151
+ | `ballot` | boolean or object | v1.68, a place's (the main block or a place under `places`). `true` (the card with no lines: faces and options only), or `{ lines }`: at most 32 lines, each `{ id, text, about }` -- `id` `[a-z0-9-]`, 1-24 characters, never twice; `text` 1-40 characters on one line (trimmed); `about` `"face"` (said about a player whose face is tapped first: "I saw them by the boat") or `"self"` (said by the speaker alone: "Not me!"). Any other key, here or in a line, is a manifest error. These lines are the only words a player can send through the card (§6, "The choice card"). `false` or absent: no card, no message, no snapshot field, no chrome; the place is sent and drawn exactly what it was. The client is told the lines in `hubPlace.ballot`. v1.179: the object may also carry `keepAway: true` (anything else is a manifest error; absent is the default), allowed only in a place that retains a dropped visit -- `resume: { keep: true }`, `resumePose`, `houseResume`, or a place without `result` or `resumeArrivalPose` (which a host's pinned reconnect window retains); elsewhere it is a manifest error. A player the place is still retaining keeps their face on the others' cards, marked away (§6). Server-only: `hubPlace.ballot` is still `{ lines }`. |
148
152
  | `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
149
153
  | `quality` | `{ low: { decor, players, labels, spawned, farMindsHz, physicsHz? } }` | v1.137, root only, requires `tiers: true`; client-only Low build/draw budgets. Unknown keys refused. See "v1.137 hub.quality" below. `physicsHz` is reserved, no effect yet. Absent quality preserves previous behavior and bytes. |
150
- | `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes (v1.69: and its kit sky is not drawn on Low). v1.30: an actor in a scene file may carry `"tier": "keep"` -- a field of the actor beside `id` and `components`, not a component -- and is then drawn on every tier at any distance, whatever its components; a place's ground (paving, grass, merged dressing: plain `Transform`/`Shape`/`Model`) needs it, or Low draws the place standing on nothing. The mark is read from the scene file, so it says nothing of an actor spawned while playing (those were never hidden); v1.63: `"tier": "near"` instead treats a non-NPC actor as scenery on Low, whatever its components: its node is taken out beyond 30 m of its bounds (the same sized test as static scenery) and put back within that distance. High never hides it; NPCs retain their own 20 m rule, and `keep` wins (the field carries one mark). v1.69: `"tier": "low"` draws an authored actor only on Low, at any distance, without the decoration/scenery/NPC distance rules; High removes its node from the scene graph, and switching back to Low restores its original parent. On High the node is drawn in the one frame that built it (a scene load, or the actor's rebuild): the tier rules run before the engine builds nodes. The place's per-viewer hiding and visibility cells still apply on Low. Low also draws no `engine.sky` dome at all (no drawing, zone stepping or texture uploads), in whatever scene plays, the frame of a scene load included; High draws the zone skies as authored. Both change on the frame after Graphics or the auto judge changes tier. A scene may therefore provide the kit sky for High and a cheap sky actor marked `"tier": "low"` for Low. No physics-3d change: while Low, hub-game puts an own `sky` of null on the scene runtime, over the getter the engine reads each frame, and deletes it on leaving Low; a device that is never Low has no such property. A scene with no low mark draws on High exactly as before, and a scene without the sky key draws on Low exactly as before. Labels, colliders and server state are untouched. Any other value, or none, is an actor as before. The scene editor has no control for it (it is written in the file) and keeps it through a save, and a duplicated actor carries it. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. v1.64: a scene file may carry a top-level `cells` key beside `engine` and `actors` -- `{ version: 1, eyeMax, hysteresis, cells: [{ id, outline: [[x, z], ...], sees: [ids], why? }] }`, outlines partitioning the ground (x east, z south), `sees` the cells visible from somewhere in that one -- and an actor a `cell` field beside `id` (`"n-plaza"`, or a list for one spanning several). On Low only, an eye outside every outline or at a non-finite place has no cell, whatever the hysteresis; otherwise the camera's cell is the one its x, z is in, kept while the eye is inside it or within `hysteresis` m of it. An authored, tagged actor none of whose cells that cell sees is not drawn, `"tier": "keep"` and `"tier": "near"` included: keep exempts distance, not what is in the way (a list is drawn when any of its cells is seen). Only an inert actor is ever out for its cell: every component it has now is one of `Transform`, `Shape`, `Model`, `Solid`, `Lookable`, `RouteAnchor`, `WalkSurface` (`CELL_INERT`; a Lookable's words are read from the scene data either way) and none is in the backstop `CELL_PROTECTED` (`HubDoor`, `HubPad`, `HubNpc`, `Body`, `Player`, `Ball`, `HubSpin`, `TownHats`, `TownStamp`, `TownHatMat`, `TownWardrobeMat`, `TownWardrobeItem`, `TownWardrobe`). Anything that reacts to a player or the server or that something moves (a seat, a sign, a court piece, a statue, any other `Hub*`/`Town*` or unknown component), or an actor with no components, is never out for its cell, whatever its `cell` or `tier` says, and the other Low rules apply to it as before. This is decided from the actor's current components on every look, never remembered: an actor replaced under the same id, or given a component while playing, is decided again on the next look. An eye above `eyeMax` or with no cell, or a game through a door: the cells hide nothing. A malformed table (another version, a cell without a string id, an outline of three or more finite pairs or a `sees` of known ids that includes its own, a duplicate id, a non-finite `eyeMax`/`hysteresis`) is no table; a `cell` that is empty, not strings, or names an unknown id is no cell. `?hubcells=1` shows an overlay (the cell, what is out and why, the last change). Nothing on the wire; a scene without the key is drawn exactly as before. `false` or absent: none of it. |
154
+ | `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged; v1.202: an auto Low whose 10 s median is still over 40 ms halves the renderer's and composer's pixel ratio, never under 1, for one more window, keeps it only if that median is at most 0.8x the slow one and otherwise puts both back for the visit, and remembers kept or refused beside the device's low mark; a pick by hand, High, or a deck with `weakestTier` never does it), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes (v1.69: and its kit sky is not drawn on Low). v1.30: an actor in a scene file may carry `"tier": "keep"` -- a field of the actor beside `id` and `components`, not a component -- and is then drawn on every tier at any distance, whatever its components; a place's ground (paving, grass, merged dressing: plain `Transform`/`Shape`/`Model`) needs it, or Low draws the place standing on nothing. The mark is read from the scene file, so it says nothing of an actor spawned while playing (those were never hidden); v1.63: `"tier": "near"` instead treats a non-NPC actor as scenery on Low, whatever its components: its node is taken out beyond 30 m of its bounds (the same sized test as static scenery) and put back within that distance. High never hides it; NPCs retain their own 20 m rule, and `keep` wins (the field carries one mark). v1.69: `"tier": "low"` draws an authored actor only on Low, at any distance, without the decoration/scenery/NPC distance rules; High removes its node from the scene graph, and switching back to Low restores its original parent. On High the node is drawn in the one frame that built it (a scene load, or the actor's rebuild): the tier rules run before the engine builds nodes. The place's per-viewer hiding and visibility cells still apply on Low. Low also draws no `engine.sky` dome at all (no drawing, zone stepping or texture uploads), in whatever scene plays, the frame of a scene load included; High draws the zone skies as authored. Both change on the frame after Graphics or the auto judge changes tier. A scene may therefore provide the kit sky for High and a cheap sky actor marked `"tier": "low"` for Low. No physics-3d change: while Low, hub-game puts an own `sky` of null on the scene runtime, over the getter the engine reads each frame, and deletes it on leaving Low; a device that is never Low has no such property. A scene with no low mark draws on High exactly as before, and a scene without the sky key draws on Low exactly as before. Labels, colliders and server state are untouched. Any other value, or none, is an actor as before. The scene editor has no control for it (it is written in the file) and keeps it through a save, and a duplicated actor carries it. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. v1.64: a scene file may carry a top-level `cells` key beside `engine` and `actors` -- `{ version: 1, eyeMax, hysteresis, cells: [{ id, outline: [[x, z], ...], sees: [ids], why? }] }`, outlines partitioning the ground (x east, z south), `sees` the cells visible from somewhere in that one -- and an actor a `cell` field beside `id` (`"n-plaza"`, or a list for one spanning several). On Low only, an eye outside every outline or at a non-finite place has no cell, whatever the hysteresis; otherwise the camera's cell is the one its x, z is in, kept while the eye is inside it or within `hysteresis` m of it. An authored, tagged actor none of whose cells that cell sees is not drawn, `"tier": "keep"` and `"tier": "near"` included: keep exempts distance, not what is in the way (a list is drawn when any of its cells is seen). Only an inert actor is ever out for its cell: every component it has now is one of `Transform`, `Shape`, `Model`, `Solid`, `Lookable`, `RouteAnchor`, `WalkSurface` (`CELL_INERT`; a Lookable's words are read from the scene data either way) and none is in the backstop `CELL_PROTECTED` (`HubDoor`, `HubPad`, `HubNpc`, `Body`, `Player`, `Ball`, `HubSpin`, `TownHats`, `TownStamp`, `TownHatMat`, `TownWardrobeMat`, `TownWardrobeItem`, `TownWardrobe`). Anything that reacts to a player or the server or that something moves (a seat, a sign, a court piece, a statue, any other `Hub*`/`Town*` or unknown component), or an actor with no components, is never out for its cell, whatever its `cell` or `tier` says, and the other Low rules apply to it as before. This is decided from the actor's current components on every look, never remembered: an actor replaced under the same id, or given a component while playing, is decided again on the next look. An eye above `eyeMax` or with no cell, or a game through a door: the cells hide nothing. A malformed table (another version, a cell without a string id, an outline of three or more finite pairs or a `sees` of known ids that includes its own, a duplicate id, a non-finite `eyeMax`/`hysteresis`) is no table; a `cell` that is empty, not strings, or names an unknown id is no cell. `?hubcells=1` shows an overlay (the cell, what is out and why, the last change). Nothing on the wire; a scene without the key is drawn exactly as before. `false` or absent: none of it. |
151
155
  | `yourGames` | boolean | v1.54, the deck's (not a place's). `true`: signed-in players in towns get private hearted/recent door rows, account hearts and an arrival offer (§5). `false` or absent: no command, message, UI or storage read; the deck draws exactly what it did. |
152
156
  | `spawnCap` | integer | v1.161, deck-only and server-only: 96..192, how many `hub.spawn` copies may be alive at once in each of the deck's places (§4, §10). Any other value, or one under a place, is refused, by the publish check too. Absent: 96, and the manifest and wire are byte-identical. Low tier's client-side `quality.low.spawned` cap is unchanged. |
157
+ | `wallet` | `{ name, start? }` | v1.185, deck-only and server-only: one coin wallet per account on conditional storage, for `hub.wallet` (§4, §14 "Coins"). `name` is a short id (`[a-z][a-z0-9_-]{0,23}`) naming the storage prefix; `start` a non-negative safe integer, the coins a new account has (default 0). Unknown keys, any other value, or one under a place are refused. Absent: no `hub.wallet`, and the manifest and wire are byte-identical. |
153
158
  | `safeInsets` | boolean | v1.123, deck-only and client-only. `true`: §9 safe edges, reserved host corners and complete measured chrome. Absent/false preserves the previous rendering; no server or `hubPlace` field. |
154
159
  | `playCards` | boolean | v1.122, the deck's. `true`: §6 play cards go to mutual friends and party members anywhere in the layer; strangers must be within 12 m in x/z when the phrase arrives. At most one stranger card is retained at a time, and each stranger can offer one per 60 s across all doors. Absent/false preserves the v1.11 cards and cooldown per player and door. Bubbles, feed and block filtering are unchanged. |
155
160
  | `cues` | boolean | v1.23, the deck's (not a place's). `true`, in a town (a place with no `result`): (a) while someone in the roster with a known user id is not named by the host as a friend, the host is asked for the player's friends again a few times in the ~16 s after they were first seen (at about 1, 3, 9 and 15 s -- v1.32; 1, 5, 10, 16 in v1.31; 2, 6, 11 and 17 s before, when the host learned who is in a town only on its heartbeat; those here when the player came in count from then), because the host names a friend only once it knows both are in the town (within a few seconds in the same layer, on its heartbeat across layers) -- never while an ask is out, at most two such asks in any 8 s and 2 s apart however many come in (one in 4 s before v1.32), stopping when the host names them or they leave, the ordinary 20 s ask after that, and a friend already here when the player came in is announced as one who arrives later is ("amy is here · People to join", pointed to), once per friend per session and not where "You're next to amy" said it; (b) the chat field's placeholder says who reads a line ("To your follows…"; the whole sentence is its accessible label) or, disabled, "Friends only" with one sentence as its note and label whatever the reason, so neither tells which it is (v1.29: "Typed chat is for friends who follow each other. Emotes work with everyone."; before v1.29 "No follows here" / "Chat not available" and the longer notes), and the host is asked for chat peers within about a second of someone coming in; (c) "Let's play…" names the door of the speaker's open party proposal before the door they stand by; (d) a party that gains a member says so ("You joined amy's party", "bo joined your party"); (e) v1.29: a player back from a game through one of the town's doors is asked, for 20 s and after any invitation or party proposal, "Play <door> again?" -- Play again is the Doors list's Go for that door (onto its pad; in a party, and for a door that is not `solo`, "Play <door> again together?" / Go together, which proposes it to the party), Not now puts it away. Who is a friend is only what `Hub.friends` already says, and a party is the place's own; chat's rules are ghost's, unchanged. `false` or absent: none of it -- the deck is sent and draws exactly what it did. |
@@ -219,7 +224,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
219
224
  | `shutdown(hub)` | v1.2: the session is stopping. Anyone still here has had `leave` first; return a promise to finish writing (awaited up to 1.5 s, inside the host's own grace) |
220
225
  | `grab(hub, playerId, actorId, op)` | v1.3, a place with `grab`: a player grabbed (`op` `"grab"`) or threw (`"throw"`) a loose object (§6). Return `false` to a grab to refuse it (the player lets go at once); a throw is only told. A hook that throws refuses the grab |
221
226
  | `emote(hub, playerId, id)` | v1.6, a place with `idle.emotes`: a player asked to play emote `id` (§6). Return `false` to refuse it (nobody sees it); a hook that throws refuses it |
222
- | `npcReact(hub, npc, playerId, { emote })` | v1.47: a nearby free NPC may answer this player's emote (§6, §13). Return `false` to leave it alone, null or undefined for its props and the kit's defaults, or `{ emote, line }` to replace either. `emote` is one of the original five kit ids or null for no motion (also at v1.158 expression places); `line` is public speech, cut to 80 characters, or null for none. Errors are logged once and use the defaults. Async results are unsupported and ignored; rejected promises are caught with fixed log text. No model is called |
227
+ | `npcReact(hub, npc, playerId, { emote })` | v1.47: a nearby free NPC may answer this player's emote (§6, §13). Return `false` to leave it alone, null or undefined for its props and the kit's defaults, or `{ emote, line }` to replace either. The request's `emote` may be any id that played, v1.174 a place's `"yawn"` included; the answer's `emote` is one of the original five kit ids or null for no motion (also at v1.158 expression places); `line` is public speech, cut to 80 characters, or null for none. Errors are logged once and use the defaults. Async results are unsupported and ignored; rejected promises are caught with fixed log text. No model is called |
223
228
  | `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). v1.158 `idle.expression` also calls this with `seatId: null` for sit-anywhere, independently of `idle.seats`. Return `false` to refuse; a hook that throws refuses |
224
229
  | `action(hub, playerId, id)` | v1.74, a place with `actions: true`: an arrived, connected player pressed an id in their current offer, carrying a safe-integer `n` equal to that offer's current version (§9). Stale, removed, another player's, malformed or over-budget presses are silently dropped. Six presses/s with a burst of eight per player; dropped or refused presses spend tokens too. The return is ignored; throws and rejections are contained and logged once. Async hooks are neither serialised nor cancelled when the player leaves. |
225
230
  | `menu(hub, playerId, id)` | v1.79, only with `menu: true`: an arrived, connected player picked an item in their current, last-sent menu with its safe-integer `n`, or closed the sheet (`id: "close"`). Stale, unknown, malformed and over-budget picks are dropped; readOnly refuses item picks but still delivers close. Six attempts/s, burst eight per player, including dropped presses. Return ignored; throws/rejections contained and logged once. Async hooks are neither serialised nor cancelled on leave. |
@@ -233,7 +238,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
233
238
  | `npcContext(hub, npc, playerId)` | v1.8: what an NPC's mind should know right now while `playerId` talks to it (§13 notes): a string of at most 700 characters, or null for none. Read when the conversation opens and every second while it lasts |
234
239
  | `npcAsks(hub, npc, playerId)` | v1.80: questions the place keeps on offer while this player talks to the NPC's mind (§13): `{ persistentAsks: string[] }` or null. Re-read with each notes check; up to two strings, trimmed and cut to 40 characters, deduplicated after cutting. Private to that player in `hub-npc-notes`; lead the three-chip refill row and may return after being sent while still offered. Null clears them. Synchronous; async results are ignored and rejected promises caught; errors log once with fixed words. Absent: no new message key or refill behavior |
235
240
  | `npcHeard(hub, npc, playerId, { text, conversation })` | v1.8: a turn to an NPC's mind was admitted; `text` is the player's own words (§13), for place state a conversation may change. v1.47: `conversation` is captured at admission and matches `npcOpening`'s; after the send settles, the hook runs only if that conversation still belongs to the same account and body |
236
- | `npcOpening(hub, npc, playerId, { met, greeting, conversation })` | v1.37: what an NPC says first when `playerId` opens its chat, and what they might ask it (§13): `{ text, asks, more }`, a string (the words alone), or null. `text` is cut at 240 characters; `asks` is up to three questions of at most 40 characters each (longer ones are cut, repeats and extras dropped). v1.46: `more` is up to nine later questions with the same cut, deduped against `asks`; sent only when non-empty. Shown in that player's panel at once, to them alone, with no model called. A tap on a question sends it as the player's own words by the ordinary path (range, budget and age rules unchanged); after a reply the chips return (§13). `met`: this player has said something to this NPC since the place's server started (by account; a place that remembers longer keeps its own record); kept only where the hook exists. With a mind and `npcContext`, the opening is added to that conversation's notes so the mind knows what it said. An NPC with no mind and an opening says no `npcLine` hello as well. v1.46: no hook or no usable text gives a mind the kit's default opening; a body without a mind keeps its hello line. A hook's text and questions are its own, with no defaults added. v1.47: `conversation` is an integer increasing with every open of this NPC, so a place can match later words to its opening. `greeting` is this speaker's cached next greeting or null; when present it replaces the opening text, keeping the place's asks and more (§13). Async results are unsupported and ignored; rejected promises are caught and logged once with fixed text. v1.148: `authored: true` (with non-empty `asks`) says the place answers those asks itself through `npcLine` `why: 'authored'`, so a speaker under 13 may tap them (§13) |
241
+ | `npcOpening(hub, npc, playerId, { met, greeting, conversation })` | v1.37: what an NPC says first when `playerId` opens its chat, and what they might ask it (§13): `{ text, asks, more }`, a string (the words alone), or null. `text` is cut at 240 characters; `asks` is up to three questions of at most 40 characters each (longer ones are cut, repeats and extras dropped). v1.46: `more` is up to nine later questions with the same cut, deduped against `asks`; sent only when non-empty. Shown in that player's panel at once, to them alone, with no model called. A tap on a question sends it as the player's own words by the ordinary path (range, budget and age rules unchanged); after a reply the chips return (§13). `met`: this player has said something to this NPC since the place's server started (by account; a place that remembers longer keeps its own record); kept only where the hook exists. With a mind and `npcContext`, the opening is added to that conversation's notes so the mind knows what it said. An NPC with no mind and an opening says no `npcLine` hello as well. v1.46: no hook or no usable text gives a mind the kit's default opening; a body without a mind keeps its hello line. A hook's text and questions are its own, with no defaults added. v1.47: `conversation` is an integer increasing with every open of this NPC, so a place can match later words to its opening. `greeting` is this speaker's cached next greeting or null; when present it replaces the opening text, keeping the place's asks and more (§13). Async results are unsupported and ignored; rejected promises are caught and logged once with fixed text. v1.148: `authored: true` (with non-empty `asks`) says the place answers those asks itself through `npcLine` `why: 'authored'`, so a speaker under 13 may tap them (§13); v1.175: so may anyone else while their inspect is pending or refused |
237
242
  | `npcTools(hub, npc, playerId)` | v1.66: what an NPC's mind may look up while it answers this player (§13 tools): up to 8 `{ name, description, input_schema }`, read when a turn is admitted and sent with it. `name` matches `^[A-Za-z][A-Za-z0-9_]{0,31}$` and is not `perform_action` or `capture_claim`; `description` is 1-300 characters; `input_schema` a JSON-schema object of at most 1 KiB; the list at most 6 KiB. A bad entry is dropped, never the turn; a hook that throws or returns no entries leaves the turn as it was. Without it a turn is sent exactly as before |
238
243
  | `npcTool(hub, npc, playerId, name, input)` | v1.66: the mind's one lookup for a turn this place admitted (§13 tools): `name` is one the turn declared, `input` the mind's object. Return a string or a JSON value (or a promise of one), at most 1 KiB once serialized; it goes to the mind alone. Answered within 1.5 s or the mind answers without it. Must never carry player-typed text. Called at most once per turn, and only for that turn's speaker |
239
244
 
@@ -241,11 +246,13 @@ of any of these. Every hook gets `hub`, the place's context, first:
241
246
 
242
247
  | member | what |
243
248
  | --- | --- |
249
+ | `hub.record(playerId, op)` | v1.163: server-authoritative private trace recording; `start` → boolean, `stop` → fresh `{ v: 1, step, ms, poses }` or null, `cancel` → true. At most eight recordings, one per connected arrived player, 192 samples and 600000 ms; see §10. No manifest key. |
250
+ | `hub.replay(viewerId, slot, spec \| null)` | v1.163: send one of two private non-solid ghosts to a connected, hello'd arrived viewer. `{ trace, look?, label?, color?, offsetMs? }`; four shown ghosts per rolling second, clears unbudgeted. Boolean; invalid/refused calls warn once and leave state unchanged. See §10 and §12. |
244
251
  | `hub.owner` | v1.67: the platform owner user id string on an owner door instance, null otherwise; dev-only `hub.house.devOwner: "first"` keeps the first arrival as owner for the session (below) |
245
- | `hub.actions(playerId, items \| null)` | v1.74, present only in a place with `actions: true`: privately offer 0..3 `{ id, label }` chips. Unique ids match `[a-z][a-z0-9_-]{0,23}`; labels are strings of 1..16 characters (code points), no control, direction or zero-width characters, and cannot be only whitespace. Items must be plain objects with own `id` and `label` properties; each is read once, validated and copied; unknown keys are refused. `null` or `[]` clears. Invalid calls throw `TypeError` before changing state. Unknown, disconnected or not-arrived players return false; otherwise true. Calls record the newest list; a changed recorded list advances that player's safe-integer version `n`, including a change to null. The tick coalesces ordinary deliveries to at most four offers a second per player (250 ms apart), newest wins; equal last-sent and current lists send nothing. Leave drops chips; the session's counter is kept. A fresh hello immediately replays the current offer once (or null), with its current `n`. |
246
- | `hub.companion(playerId, spec \| null)` | v1.71, present only with either companion manifest form: one private follower per arrived player. `spec` is a plain object with only own `look` (required, `"lantern"` or `"bird"`), optional `say` (string, 1..80 code points, at most 240 UTF-16 units, non-blank, no control, bidi, zero-width characters or newlines), optional `dress` (v1.78, bird only; enum slots and defaults in §9), optional `pose` (v1.78, bird only; only `"show"`), and optional `at` (scene actor id string, 1..64 characters; unknown ids are ignored by the client). Fields are read once, validated and copied. Invalid calls throw `TypeError` before changing state; an absent or not-arrived player returns false, otherwise true. `null` clears; equal specs change and send nothing. Ordinary tick sends coalesce to at most four/s per player, newest wins; a spec changed back to the last-sent one keeps that version. Fresh hello replays the current spec; leave forgets it, retaining the place session's version counter. The place authors every line; nothing a player typed may be passed to `say`. The line is never shown to anyone else. |
247
- | `hub.menu(playerId, spec \| null)` | v1.79, present only with `menu: true`: privately offer the sheet described in §9. Null closes it. Validate and copy before changing state; invalid calls throw TypeError. Unknown, disconnected or not-arrived players return false; otherwise true. Every changed spec advances that player's safe-integer version `n`; equal re-sends send nothing. Tick coalesces to four ordinary offers/s; a fresh hello replays an open menu or a pending close once, and sends nothing for an unused menu or an already delivered close. Leave forgets the menu, retaining the counter to prevent reused versions. |
248
- | `hub.ask(playerId, spec \| null)` | v1.75, present only with `ask: true`: one private prompt per player, replaced by a new spec. A plain object has exactly own `id`, `title`, `max`; each field is read once, validated and copied. Ids match `[a-z][a-z0-9_-]{0,23}`; titles are 1..32 code points, not whitespace-only, with no control, Bidi_Control or zero-width characters; `max` is a safe integer 1..32 code points. `null` closes. Invalid calls throw `TypeError` before changing state; unknown, disconnected or not-arrived players return false, otherwise true. Every changed recorded prompt, including null, advances safe-integer `n` from one session counter. Tick deliveries coalesce to at most four/s per player, newest wins, equal last-sent/current content and version suppressed. Leave forgets; a fresh hello replays the current prompt or null once with its `n`. Accepted answers consume and queue the close before calling the hook; it shares the tick delivery budget. |
252
+ | `hub.actions(playerId, items \| null)` | v1.74, present only in a place with `actions: true`: privately offer 0..3 `{ id, label }` chips. Unique ids match `[a-z][a-z0-9_-]{0,23}`; labels are strings of 1..16 characters (code points), no control, direction or zero-width characters, and cannot be only whitespace. Items must be plain objects with own `id` and `label` properties; each is read once, validated and copied; unknown keys are refused. `null` or `[]` clears. Invalid calls throw `TypeError` before changing state. Unknown, disconnected or not-arrived players return false; otherwise true. Calls record the newest list; a changed recorded list advances that player's safe-integer version `n`, including a change to null. The tick coalesces ordinary deliveries to at most four offers a second per player (250 ms apart), newest wins; equal last-sent and current lists send nothing. Leave drops chips; the session's counter is kept. A fresh hello immediately replays the current offer once (or null), with its current `n`. v1.180 `heldOffers: true`: a held visit away takes calls (true), recorded unsent, and its resume hello replays the latest under a fresh `n` (§12 "Held offers"). |
253
+ | `hub.companion(playerId, spec \| null)` | v1.71, present only with either companion manifest form: one private follower per arrived player. `spec` is a plain object with only own `look` (required, `"lantern"` or `"bird"`), optional `say` (string, 1..80 code points, at most 240 UTF-16 units, non-blank, no control, bidi, zero-width characters or newlines), optional `dress` (v1.78, bird only; enum slots and defaults in §9), optional `pose` (v1.78, bird only; only `"show"`), optional own `shown: true` (v1.181, bird only; publishes dress enums to everyone in the place, §9; gate on server-only `hub.companionShown === true`), and optional `at` (scene actor id string, 1..64 characters; unknown ids are ignored by the client). Fields are read once, validated and copied. Invalid calls throw `TypeError` before changing state; an absent or not-arrived player returns false, otherwise true. `null` clears; equal specs change and send nothing. Ordinary tick sends coalesce to at most four/s per player, newest wins; a spec changed back to the last-sent one keeps that version. Fresh hello replays the current spec; leave forgets it, retaining the place session's version counter. The place authors every line; nothing a player typed may be passed to `say`. The line is never shown to anyone else. |
254
+ | `hub.menu(playerId, spec \| null)` | v1.79, present only with `menu: true`: privately offer the sheet described in §9. Null closes it. Validate and copy before changing state; invalid calls throw TypeError. Unknown, disconnected or not-arrived players return false; otherwise true. Every changed spec advances that player's safe-integer version `n`; equal re-sends send nothing. Tick coalesces to four ordinary offers/s; a fresh hello replays an open menu or a pending close once, and sends nothing for an unused menu or an already delivered close. Leave forgets the menu, retaining the counter to prevent reused versions. v1.180 `heldOffers: true`: a held visit away takes calls (true), recorded unsent, and its resume hello replays an open menu or pending close under the next `n` (§12 "Held offers"). |
255
+ | `hub.ask(playerId, spec \| null)` | v1.75, present only with `ask: true`: one private prompt per player, replaced by a new spec. A plain object has exactly own `id`, `title`, `max`; each field is read once, validated and copied. Ids match `[a-z][a-z0-9_-]{0,23}`; titles are 1..32 code points, not whitespace-only, with no control, Bidi_Control or zero-width characters; `max` is a safe integer 1..32 code points. `null` closes. Invalid calls throw `TypeError` before changing state; unknown, disconnected or not-arrived players return false, otherwise true. Every changed recorded prompt, including null, advances safe-integer `n` from one session counter. Tick deliveries coalesce to at most four/s per player, newest wins, equal last-sent/current content and version suppressed. Leave forgets; a fresh hello replays the current prompt or null once with its `n` (v1.180 `heldOffers: true`: a held visit away takes calls, true and unsent, and its resume hello replays the latest under a fresh `n`, §12 "Held offers"). Accepted answers consume and queue the close before calling the hook; it shares the tick delivery budget. |
249
256
  | `hub.decor` | v1.67, present only in a place declaring `decor`: private `button`, `open`, `close` and `update` (§10 Decorating) |
250
257
  | `hub.session`, `hub.sim` | the Castle session and the multiplayer-3d simulation |
251
258
  | `hub.place` | `{ id, title, scene, manifest }` |
@@ -253,44 +260,52 @@ of any of these. Every hook gets `hub`, the place's context, first:
253
260
  | `hub.players()` | `[{ playerId, username, userId, at, arrivedAt }]` for players with bodies (`userId` v1.2, null for an anonymous player). `at` is the client's last accepted report: an input, never evidence of where a player walked (v1.141, `hub.observed`) |
254
261
  | `hub.actorsWith(component)` | scene actors carrying a component: `[{ id, props, t, shape, body }]`: `props` the component's, `t` the Transform, `shape` the Shape's `{ kind, width, height, depth, radius }` or null, `body` the Body type or null (v1.1: a marker need not repeat its actor's size) |
255
262
  | `hub.placeAt(playerId, at, facingDeg?)` | move a player's body; reaches the client as a clamp |
256
- | `hub.observed(playerId)` | v1.141: the kit's observed position, `{ at, step, ok, travel, since, speed }` (copies), or null for a player with no body here. Once a tick, after physics and before any authored `step`, each body's move is checked against a walker's allowance (the scene Player's `speed` × the player's `hub.tune` speed × 1.25) and spent from one signed walking credit: funded, unfunded or rejected; `travel` counts only funded walking since the last reset (a placement, a new body). A door scores from this, never from `player.at` or `hub.players()[i].at`. Lazy: nothing is kept until a place first calls this or `hub.station`. See [observed progress](observed-progress.md) |
263
+ | `hub.observed(playerId)` | v1.141: the kit's observed position, `{ at, step, ok, travel, since, speed }` (copies), or null for a player with no body here. Once a tick, after physics and before any authored `step`, each body's move is checked against a walker's allowance (the scene Player's `speed` × the player's `hub.tune` speed × 1.25; v1.165: a driver's is `max(car.speed, car.reverse)` × 1.25) and spent from one signed walking credit: funded, unfunded or rejected; `travel` counts only funded walking since the last reset (a placement, a new body). A door scores from this, never from `player.at` or `hub.players()[i].at`. Lazy: nothing is kept until a place first calls this or `hub.station`. See [observed progress](observed-progress.md) |
264
+ | `hub.observed(playerId)` while driving | v1.165: while a player is in the driving state (`hub.drive`, §6 Cars), the allowance follows `max(car.speed, car.reverse)` × 1.25, and `speed` reads it; otherwise it is the walker allowance above (riders included). The tick the driving state changes fills the credit at the lower of the two; a walker's tune change does not. Decks without cars get identical bytes and behaviour. See [observed progress](observed-progress.md), Drivers and riders |
257
265
  | `hub.station(id, { at: { x, y, z }, radius, height? } \| null)` | v1.141: declare (or with `null` remove) a vertical cylinder a door scores, `height` 2 by default; id 1-64 letters, digits, `_ . : -`; at most 64; radius and height above 0 and at most 200 m. The same shape again changes nothing; a new shape zeroes every player's dwell there. True when taken; a bad call warns once and returns false |
258
266
  | `hub.dwell(playerId, id)` | v1.141: `{ inside, entered, ms }` at a station, or null. `entered` only after the player walked out beyond `radius + 0.25` m and back within `radius` by funded steps (the player's signed walking credit not below zero); `ms` the sim time they have stayed entered on funded, present ticks. A reset, an unfunded step or a rejection clears it, and a placement elsewhere clears it at once, inside the same tick (the next pass resets at the placement's destination) |
259
- | `hub.hold(playerId, at?, facingDeg?)` / `hub.release(playerId)` | hold a player still (§8) |
267
+ | `hub.hold(playerId, at?, facingDeg?, { turnCamera }?)` / `hub.release(playerId)` | hold a player still; `turnCamera: true` turns them to the held facing (v1.190, §8) |
260
268
  | `hub.setHud(spec, playerId?)` | the declared HUD, for everyone or one player (§9) |
261
- | `hub.hide(actorId, options?)` / `hub.show(actorId, options?)` | server-declared actor visibility (§10); v1.62 `{ to: [playerIds], clear?: boolean }` overrides visibility for those connected viewers only. `clear: true` restores their shared view. True when taken; invalid actor/options or more than 256 overrides per player warn once and return false, changing nothing. Without options, the shared operation is unchanged |
269
+ | `hub.hide(actorId, options?)` / `hub.show(actorId, options?)` | server-declared actor visibility (§10); v1.62 `{ to: [playerIds], clear?: boolean }` overrides visibility for those connected viewers only. `clear: true` restores their shared view. v1.184 `hub.hide(actorId, { to, solid: true })` draws it hidden for those viewers but leaves its collider in place on their clients (a wall they cannot see but still bump into); `solid` is a boolean, hide-only (`hub.show` refuses `solid: true`), and ignored with `clear: true`. True when taken; invalid actor/options or more than 256 overrides per player warn once and return false, changing nothing. Without options, the shared operation is unchanged |
262
270
  | `hub.move(actorId, { x, y, z, rotationY }, { overMs }?)` | move a kinematic scene actor, at once or in a straight line over `overMs`; any subset of the fields (§10, v1.1) |
263
271
  | `hub.tint(actorId, color)` | paint a Shape actor `#rrggbb` for everyone; `null` puts back its authored colour (§10, v1.1) |
264
272
  | `hub.pose(actorId)` | where an actor's body is now: `{ x, y, z, rotationY, velocity, owner }` (`owner` the player whose client simulates a loose object, or null), or null (§10, v1.3) |
265
273
  | `hub.reset(actorId, { x, y, z, rotationY }?)` | put a loose (dynamic) object back where it was authored, or at a point, at rest, taking it from the client simulating it (§10, v1.3) |
266
- | `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2); at most 96 copies alive, or the deck's `spawnCap` (v1.161, up to 192) |
274
+ | `hub.spawn(fromActorId, { x, y, z, rotationY }?, { carer }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2); at most 96 copies alive, or the deck's `spawnCap` (v1.161, up to 192); v1.162: `carer` names the player the copy goes with |
267
275
  | `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back; kept while driving and applied on getting out (v1.160) |
268
276
  | `hub.drive(playerId, car)` / `hub.drive(playerId, null, at?)` | v1.160: drive or respray a car; get everyone out, optionally placing the driver at `{ x, z, y?, facing? }`; boolean (§6 Cars) |
269
277
  | `hub.ride(playerId, driverId, seat)` / `hub.ride(playerId, null)` | v1.160: join a free passenger seat (1-based) within 6 m, or get out beside it; boolean (§6 Cars) |
270
278
  | `hub.vehicle(playerId)` | v1.160: `{ driver: true, car }`, `{ driver: false, of, seat }`, or null (§6 Cars) |
271
- | `hub.drop(playerId?)` / `hub.holding(playerId)` | v1.3: whoever holds an object lets go (default: everyone; a goal, a whistle), returning how many were told; the actor id a player holds, or null (§6) |
279
+ | `hub.drop(playerId?)` / `hub.holding(playerId)` | v1.3: whoever holds an object lets go (default: everyone; a goal, a whistle), returning how many registered holds ended; a named player in the place is always told, even with no hold the place registered (v1.191); the actor id a player holds, or null (§6) |
272
280
  | `hub.keepFor(actorId, playerId \| null)` | v1.27: keep a loose (dynamic) object of a place with `grab` for one player: nobody else is offered it or may grab it, and the `grab` hook is not asked about their tries; `null` makes it anyone's again. Returns whether it is now kept as asked: an actor that is not a dynamic one of the scene, a player who is not here, or a place without `grab` is warned about once, returns `false` and changes nothing (§6) |
273
281
  | `hub.emotesFor(playerId, ids \| null)` | v1.158, only at an `idle.expression` place: replace this arrived player’s visit-only grants with declared role emote ids; null clears. Unknown ids warn once and are dropped; duplicates are removed. True when valid, false for an absent player or invalid list. Only changed lists are sent, privately (§6). |
274
- | `hub.emote(playerId, id)` | v1.6, a place with `idle.emotes`: play a kit emote (`"wave"`, `"dance"`, `"cheer"`, `"bow"`, `"spin"`) on a player's avatar for everyone, without the hook or the rate a player's own request has; v1.158 at an `idle.expression` place also accepts the five new kit ids and any declared role id, regardless of that player's grants. True when it took (§6) |
282
+ | `hub.emote(playerId, id)` | v1.6, a place with `idle.emotes`: play a kit emote (`"wave"`, `"dance"`, `"cheer"`, `"bow"`, `"spin"`) on a player's avatar for everyone, without the hook or the rate a player's own request has; v1.158 at an `idle.expression` place also accepts the five new kit ids and any declared role id, regardless of that player's grants; v1.174 at any such place also plays the place-only `"yawn"` 🥱 (a benched or idle player dozing), which no picker offers and no client may request. True when it took (§6) |
275
283
  | `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6); v1.158 an `idle.expression` ground sitter returns the string `'ground'` |
284
+ | `hub.sitOn(playerId, seatId \| null)` | v1.194, a place with `idle.seats`: seat an arrived player on a shown, free seat at any distance, or stand them with `null`; boolean (§6) |
285
+ | `hub.resetFences(playerIds)` | v1.195: `[{ playerId, resetGeneration }]` (account ids, one per account) for a `conditionalWrite` touching one or two players here, from the observed progress markers; null when any is unknown (§14) |
286
+ | `hub.townDay(nowMs?)` / `hub.townDayStart(day)` / `hub.townDayFrom(storedDay, nowMs?)` | v1.200: the Town's day number (the America/Los_Angeles date as days since 1970-01-01, the scale of `Math.floor(ms / 86400000)`), the epoch ms its LA midnight begins, and a stored day number clamped to today for the switch from UTC days (§14) |
276
287
  | `hub.sound(actorId, file, { loop, volume, radius }?)` | v1.6, a place with `idle.sounds`: play one of them at a scene actor for everyone, `volume` 0-1 (default 1), silent `radius` metres away (1-60, default 20); a loop plays until `hub.sound(actorId, null)`; true when it took (§6) |
277
288
  | `hub.danceIdle(actorId, { bpm, floors })` | v1.109, a place with `idle.emotes`: after starting a sound loop at `actorId`, give its tempo (30–300 BPM) and 1–16 axis-aligned floor bounds `{ x, z, halfX, halfZ }` (positive half sizes at most 100 m; coordinates within ±1,000,000 m). Returns true when valid. `hub.danceIdle(actorId, null)` clears it. Replacing/stopping the loop invalidates the previous clock. No emote, scoring hook or cooldown is triggered. |
278
289
  | `hub.cue({ player } or { actor, radius? }, name)` | v1.50, a deck with `soundscape.cues: true`: a named synthesised cue for one connected player or near a scene actor, radius 1–60 m (default 12); true when sent, otherwise false and warn once. Six cues/s with burst six per player, or shared per place for actor broadcasts; closed `CUE_NAMES`, no files (§6). v1.60 `busker-jig`/`busker-waltz` loop at an actor within radius under a 25 s re-send lease, one loop per client, or play one full-gain pass to a player. |
279
290
  | `hub.shot(playerId, shot \| null)` | v1.61: send one connected player an orbit-camera moment shot `{ look: { x, y, z }, distance, pitch, yaw }`. Look coordinates, distance and angles must be finite, distance > 0 (metres); angles are degrees, pitch capped at ±89. Invalid shots warn once and act as `null` (clear). True when sent, otherwise false and warn once. Four changed shots/s per player, burst four; equal poses suppressed for 1 s, repeated clears suppressed, clears bypass the budget. The place scene needs the orbit key (`cameraControl: "orbit"`); without it the client does nothing and stores nothing for later. The orbit camera blends to the pose and holds until changed or cleared; the shot pose is not collided. The client clears on travel, leave, scene load/place change and disconnect, preserving any shot subsequently assigned by deck client code. A held pose is privately renewed every 2 s of simulation time and immediately on a fresh join, without spending the rate budget or equal-send refusal. Each accepted pose message refreshes a 5 s client lease; equal renewals keep the same shot object and do not restart the blend. Renewals restore a shot lost to a disconnect, but never re-create one the client dropped for a scene load, travel, round end or a deck's own `orbitShot`; only a fresh `hub.shot` call does that. Successful travel and round end stop server renewals while preserving the rate budget. A shot not renewed for 5 s is cleared on the first watcher run, including after a background-tab pause, so it cannot outlive its server or connection. A clear stops renewals. No manifest opt-in or storage/frame work when unused. |
280
291
  | `hub.ballot(playerIds \| null, spec \| null)` | v1.68, a deck that declares `ballot` in some place (absent otherwise), in a place with it: show, change or take down the choice card (§6). `null` for everyone here (later joiners too); a list for those connected players (unknown or disconnected ids are ignored), whose card then replaces the shared one for them, as `setHud` does. `spec` null clears: for a list, those players fall back to the shared card; for everyone, every card goes, players' own included. `spec` is `{ title, text, until, mode, faces, options, lines, feed, picked }`, all optional: `title` ≤ 40 and `text` ≤ 120 characters on one line; `until` a simulation time (`hub.now`) the card counts down to; `mode` `"talk"` (default), `"vote"` or `"reveal"`; `faces` up to 24 `{ playerId, note?, off?, votes?, mark? }` (different players; `note` ≤ 24 characters, `off: true` greyed and not tappable, `votes` 0-99 shown as a tally, `mark` `'#rrggbb'`); `options` up to 6 `{ id, text }` (`id` as a line's, `text` ≤ 32: "Skip"); `lines` the manifest line ids offered now (default all); `feed` up to 6 `{ from, to, line }` the card's recent said lines (`to` a player for a `face` line, null or absent for a `self` one); `picked` `{ face }` or `{ option }` (one of the card's), what this viewer has locked in. True when taken; an invalid spec, a bad list or a place of the deck without `ballot` warns once and returns false, changing nothing. Other keys are refused. |
292
+ | `hub.disguise(playerId, { look?, to? } \| null)` / `hub.disguised(playerId)` | server-only visit disguise and copy read: a scene Model replaces the avatar for selected viewers; without look, hide only name/mark/role tags (§11, v1.196) |
281
293
  | `hub.mark(playerId, { text, color })` | a coloured tag over a player's avatar for everyone: a team, who is it; `null` clears it (§11, v1.1) |
282
294
  | `hub.wear(playerId, { kind, color, rarity })` | put a wearable on a player's avatar, kept on their account in every hub place where the host runs the hub: `kind` `"halo"`, `"aura"`, `"orbit"` or, v1.24, a hat `"hat-<id>"`, `color` `#rrggbb`, `rarity` 0-9; `null` takes it off; true when taken (§11, v1.4) |
283
- | `hub.friendsAmong(playerId, userIds)` | v1.36: `Promise<string[]>`, the subset of candidate decimal user-id strings that are this connected player's friends (a guest's too: a guest is over 13 like any other player). Deduped, capped at 100; ghost applies mutual follows, age, blocks and the hub gate. Every refusal (including an unknown op), absent hub ops or failure resolves `[]`. Empty answers cached per player for 40 s, non-empty answers for 10 min; requests within that window intersect the cached answer with their candidates, and never send another op inside 31 s. Optional per-place `freshFriends: true` (v1.99) instead bounds both TTLs to 31 s and exposes the server-only freshness flag. On by use, no manifest key |
284
- | `hub.friendBests(key, { better: 'higher' or 'lower' })` | v1.57: a helper with `report(playerId, best): Promise<void>` and `friendFor(playerId): Promise<{ userId, username, best } or null>`. Signed-in players only, finite numbers. `report` keeps each user's best in a top-100 deck-storage index `fb:<key>` of `{ userId, username, best, at }` (20-character username, `at` wall-clock milliseconds), through one serialized writer per key per layer. Cross-layer lost updates are acceptable. Index reads cache for 60 s; `friendFor` caches empty membership for 40 s and non-empty membership for 10 min per player per visit, and selects the best friend from the index. Leaving clears the visit cache. Both methods swallow failures. Keys are 1–60 letters, digits, `_`, `.`, `:`, `-`; use one direction per key. No manifest key, reads or writes until used |
295
+ | `hub.friendsAmong(playerId, userIds)` | v1.36: `Promise<string[]>`, the subset of candidate decimal user-id strings that are this connected player's friends (a guest's too: a guest is over 13 like any other player). Deduped, capped at 100; ghost applies mutual follows, age, blocks and the hub gate. Every refusal (including an unknown op), absent hub ops or failure resolves `[]`. Empty answers cached per player for 40 s, non-empty answers for 10 min; requests within that window intersect the cached answer with their candidates, and never send another op inside 31 s. v1.166: an account's first read in a session that comes back empty is cached 5 s and gets one early re-read even inside the 31 s gap; a read begun within that first read's minute holds the next op until the minute ends, so at most two ops go out in it (ghost allows two a minute per player per session); later empty answers keep 40 s and the gap. Optional per-place `freshFriends: true` (v1.99) instead bounds both TTLs to 31 s and exposes the server-only freshness flag. On by use, no manifest key |
296
+ | `hub.friendBests(key, { better: 'higher' or 'lower' })` | v1.57: a helper with `report(playerId, best): Promise<void>` and `friendFor(playerId): Promise<{ userId, username, best } or null>`. Signed-in players only, finite numbers. `report` keeps each user's best in a top-100 deck-storage index `fb:<key>` of `{ userId, username, best, at }` (20-character username, `at` wall-clock milliseconds), through one serialized writer per key per layer. Cross-layer lost updates are acceptable. Index reads cache for 60 s; `friendFor` caches empty membership for 40 s (v1.166: an empty answer from the session's first minute only until `friendsAmong` may read again, 5 s after the provisional first) and non-empty membership for 10 min per player per visit, and selects the best friend from the index. Leaving clears the visit cache. Both methods swallow failures. Keys are 1–60 letters, digits, `_`, `.`, `:`, `-`; use one direction per key. No manifest key, reads or writes until used |
285
297
  | `hub.leaving(playerId, text)` | v1.52: the line this player reads when leaving this place; a string, trimmed and cut at 120 characters, `null` or empty clears it. The latest call wins; true when taken, otherwise false and warn once. Sent to this player alone, only on change; never in a snapshot (§5) |
286
298
  | `hub.tryOn(playerId, { kind, color, rarity } \| null)` | v1.28: show a wearable on a player in this place only, instead of the one they own, until `null`, their leaving or the place's end. Never saved: nothing goes to ghost, the wearable on the account is neither read nor changed, and no other place hears of it. The same shape and refusals as `hub.wear`; true when taken (§11) |
287
299
  | `hub.role(playerId, spec \| null)` | v1.157: set a visit-only role `{ id, label, color, hat?, top?, tool? }`; true when taken, false and logged once when refused. Null or no second argument clears; no host calls (§11) |
288
300
  | `hub.roleOf(playerId)` | v1.157: a copy of the current role spec, or null for none or a player not here (§11) |
301
+ | `hub.holdShow(playerId, spec \| null)` | v1.182, only with top-level `hub.holdShow: true`: set a visit-only `{ shape, color }` flower, or null to clear. Invalid input throws TypeError before any change; absent or not-arrived player returns false, otherwise true (§11) |
302
+ | `hub.holdShowing(playerId)` | v1.182, same opt-in: a copy of the visit's flower spec, or null (§11) |
289
303
  | `hub.wearing(playerId)` | v1.41: the wearable a player here owns, `{ kind, color, rarity }` (a copy), as this place last knew it (a `hub.wear`, or ghost's on the arrival read), or null: none, or a player not here. A try-on shown over it does not change it. For a place to say what someone is wearing (§11) |
290
304
  | `hub.unlock(playerId, itemId)` | v1.53: give a player one of this deck's declared earned items (`hub.unlocks`), for the deed it states. A promise of `{ isNew, earned, saved }` (`earned` what the player now shows, an EarnedItem, or null -- never a home item (v1.70); `saved` false when it is kept in this session only -- a guest, the dev serve -- so `isNew` is true on every visit there and a game need not announce it), or of null when refused: never rejects, and each refusal is logged once and changes nothing. Ghost keeps it for a signed-in player in a curated place; a guest's, and any on the dev serve, lasts the session. A delayed host receipt updates local shown state only while the same session and account still own that player id (§11, v1.112). |
291
305
  | `hub.wearEarned(playerId, { deckId, id } \| null)` | v1.53: the town's choice of which owned earned item a player shows; `null` shows none. Ghost takes it only from the town. Home items resolve null and log `CAULDRON_HUB_EARNED_NOT_WEARABLE` locally when known, without calling the host. A promise of `{ earned, saved }` (`saved` as for `hub.unlock`), or of null when refused (logged once) (§11) |
292
306
  | `hub.unlocksOf(userIds)` | v1.53: always a promise: of the earned items players here own, `{ players: { [userId]: { owned: EarnedItem[] } } }` (ghost answers only for connected players); v1.70 includes home items with `class` and `piece`, which the wardrobe filters out. Or of null where the host has no such read or refuses it (logged once) (§11) |
293
307
  | `hub.earned(playerId)` | v1.53: the EarnedItem `{ deckId, id, class, shape, name, deed, color }` a player here shows, as this place last knew it (a `hub.unlock` or `hub.wearEarned` answer, or ghost's on the arrival read), a copy, or null. `hub.wearing` is unchanged by it (§11) |
308
+ | `hub.wallet.read(playerId)` / `.spend(playerId, { cost, add?, data? })` / `.earn(playerId, amount, { data? }?)` / `.seed(playerId, { coins, owned? })` | v1.185, only with manifest `hub.wallet`: the player's coins (§14 "Coins"). `read` is a promise of `{ coins, owned, data }` (copies, read fresh from storage) or null while the wallet is locked. `spend` takes `cost` coins, optionally adds item `add` to `owned` and shallow-merges `data`; `earn` adds `amount`. Both are promises of `{ ok: true, coins }` or `{ ok: false, why }`, `why` one of `'short'` (not enough coins; never from `earn`), `'owned'` (`add` already owned), `'locked'` (the wallet cannot be used this visit), `'busy'` (not settled now: read again before offering again), or `'full'` (256 owned items, or coins past a safe integer). `seed` enrols an account from a game's old whole save once: it writes only when no wallet row of the account's current reset generation exists yet, else `{ ok: false, why: 'seeded' }`. `read` is also null while a write's outcome is unknown; a call made before a progress reset that has not run yet answers `'busy'`. Item ids are `[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}`; `data` stays a plain JSON object of at most 4 KiB. A bad argument rejects with a TypeError. Anonymous players and dev guests get a session-only wallet starting at `start`. |
294
309
  | `hub.cup(playerId, doorId)` | v1.112, only with top-level `hub.weeklyCup: true`: server-only private result bits for this connected signed-in roster player and door, `{ [occurrenceDay]: { participated, champion } }`, with at most the current and previous weekly occurrence, or `null` while unavailable or a refresh is pending. A copy; never enters a snapshot, delta or client message, and one player's map is never returned for another player id. Refreshed in bounded batches once a minute and fenced to the current session/player/account identity. `champion` can be true only for the previous closed occurrence's rank-one participant, using the earliest valid result to break a score tie. This rolling projection is for presentation, not reward authority. |
295
310
  | `hub.cupNow(doorId)` | v1.112, only with top-level `hub.weeklyCup: true`: the event worker's authoritative epoch milliseconds, advanced by elapsed local wall time from the latest successful paired board read. Server-only. Returns `null` during a refresh and after a malformed or failed paired read, a session replacement, or more than two missed one-minute refresh intervals. Authored Cup schedules fail closed on `null`; they do not fall back to local wall time. |
296
311
  | `hub.cupDeckId` | v1.112, only with top-level `hub.weeklyCup: true`: the trusted saved id of the awarding deck, or `null` when unavailable. Server-only and constant for the context. Match it together with an item id in `hub.unlocksOf` ownership readback; an id from another deck is not this deck's claim. |
@@ -299,12 +314,13 @@ of any of these. Every hook gets `hub`, the place's context, first:
299
314
  | `hub.results(playerId)` | ghost's record of a player's hub results: `{ recent, records, readAt }` -- their newest results across places and their record per place -- or null (dev serve, anonymous). Read at arrival and once a minute for everyone here (§7, v1.5) |
300
315
  | `hub.result(playerId, result)` | the player's result for this visit (§7) |
301
316
  | `hub.end(playerIds?)` | the game is over for these players (default: everyone): they go back through the door |
317
+ | `hub.end([playerId], { door })` | v1.169: the same end, named as this one player's own door (`door` an id as `HubAct.id`; anything else, or more than one player, ends untagged). In a place without `result` a client that took it while offline cancels it and stays (§12 `hub-stay`); an end the player's own Act or action press makes is tagged with that press's id by the kit. |
302
318
  | `hub.doors()` | this place's doors: `[{ id, to, actor, t, props, title, minPlayers, maxPlayers, lateJoin, classic }]`, the destination's numbers from its manifest; `classic` (v1.7) is true for a cabinet, a door to a classic deck, once ghost's board says so |
303
319
  | `hub.go(door, playerIds, { instance }?)` | send players through a door of this place (a town's pad firing) into a new instance, or into `instance`, one an earlier `go` returned (a late join); returns the instance |
304
320
  | `hub.pad(door, playerIds)` | who stands on a pad door's pad; call it as often as they change (each step is fine). Where the host has hub ops the kit tells ghost, which then holds the pad's group; nothing in dev |
305
321
  | `hub.noTrips(playerId)` | v1.156: true for a player whose app cannot go through doors (its host has no `hub.go`: released iOS Castle 1.150 and 1.151 refuse every hub command). The kit already leaves them out of `hub.pad`'s group and of `hub.go`, and says "Update Castle to play" over the door to them alone while `hub.pad` names them; a place that counts its own pads (a countdown, a minimum) leaves them out too and may say the same over its pad. False for everyone else |
306
322
  | `hub.coming(door)` | v1.10: how many members of a party were asked to this door and have not answered yet (§5 parties), so a place may hold its pad's countdown for them; 0 where there are none |
307
- | `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board. v1.112 weekly boards add `event.validResultCount` and `event.last.validResultCount`: distinct participants with any valid durable result in that occurrence, including an outcome without a numeric score, so replays never inflate either count. Numeric matching scores remain required for ranking. Daily-only boards omit both fields. |
323
+ | `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. v1.176 `featuredNext`: the door is featured tomorrow (the rotation's pick for the next hub day, or a door outside the rotation keeping its hand-set flag); absent from a ghost before it, so read only `featuredNext === true` and treat its absence as knowing only today's board. A door taken out of the rotation before midnight can make it stale. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board. v1.112 weekly boards add `event.validResultCount` and `event.last.validResultCount`: distinct participants with any valid durable result in that occurrence, including an outcome without a numeric score, so replays never inflate either count. Numeric matching scores remain required for ranking. Daily-only boards omit both fields. |
308
324
  | `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
309
325
 
310
326
  `hub.go` is how any place launches: in dev it mints `hub.<place>.<random>` and
@@ -397,10 +413,13 @@ resent on a fresh hello. It is never in a snapshot. The client in a game asks
397
413
  `castleSdk.Hub.friends()` on receipt (the next idle tick), again 20 s later,
398
414
  then every 90 s while joined, outside a trip; `UNKNOWN_COMMAND` disables asks as in the town.
399
415
  A place that never calls it sends no flag and its game clients make no ask.
400
- Ghost answers only when that player's own client asked within the last 120 s;
401
- the handoff writes no marker. In pad/exact sessions, ghost also needs the
402
- player in its heartbeat roster (up to about 15 s late). Empty arrival lookups
403
- expire after 40 s so a result-screen or leaving-line lookup can succeed later.
416
+ Ghost answers only when that player's own client asked within the last 120 s,
417
+ or (with the ghost lift after 2026-10-25) the player's own client committed its
418
+ trip into this session; the handoff writes no marker. In pad/exact sessions, a
419
+ client ask also needs the player in ghost's heartbeat roster (up to about 15 s
420
+ late). Empty arrival lookups expire after 40 s so a result-screen or
421
+ leaving-line lookup can succeed later; since v1.166 the first one in a session
422
+ expires after 5 s and is read once more.
404
423
  The seven games wait for a successfully loaded signed-in record before asking;
405
424
  guests, players still loading and unsaved players send no friends request or
406
425
  flag. Under-13 players and every refusal show no comparison.
@@ -516,6 +535,9 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
516
535
  behind costs the rest at most that 1.5 s.
517
536
  - **Arrival facing is contract data**, not scene metadata (M0 gap 9): the body
518
537
  faces `arrival.face`, and the client's camera starts behind it.
538
+ A connection that comes back under a new player id (a drop past the place's
539
+ hold, such as 180 s backgrounded) is not an arrival the player made: its
540
+ `hub-arrived` leaves the camera's yaw and the avatar's facing as they were.
519
541
  - A late joiner arrives the same way, alone.
520
542
  - **A line on leaving (v1.52).** `hub.leaving(playerId, text)` says what is waiting
521
543
  next visit: on Back, a game's end or a door out of the place (not a classic
@@ -664,7 +686,17 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
664
686
  empty or overlong `doorId` or a malformed `owner` outright, and drops a
665
687
  non-string `title` or a party that is not a positive integer. A host Go is
666
688
  client-side like a hub-entry link's trip: the place's server is not told
667
- (no `hub-went` to others). Nothing of
689
+ (no `hub-went` to others). v1.171: a host Go is never acquired again
690
+ from the page (ghost refuses its pad from the page's session); when it
691
+ ends before the host commits its join, the kit tells the host once with
692
+ SDK `Hub.goFailed({ doorId, owner }, why)`, posted as
693
+ `{ castleSdk: 1, hub: { type: "goFailed", doorId, owner?, why } }` (the
694
+ host reads it with `hubGoFailedFrom`): `why` is `"refused"` (`Hub.go`
695
+ gave no handoff), `"content"` (the destination's content would not load)
696
+ or `"join"` (the join was not committed). The host may acquire the door
697
+ again from its own session, where ghost's pad check passes, and post a
698
+ fresh Go, which the kit takes like any other once the place is settled.
699
+ A join the host committed and then lost is not reported. Nothing of
668
700
  the destination is mounted until the host commits the join
669
701
  (`multiplayer.joinState()`); a join it does not commit leaves the player's
670
702
  place as it was: a door's trip rejoins the session it left when that is not
@@ -804,6 +836,15 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
804
836
  placement. `fallY` must sit below
805
837
  everywhere a player stands, or the arrival itself counts as fallen.
806
838
 
839
+ v1.172: the implicit ground reaches 100 m each way from the origin (a
840
+ 60 m plane is drawn). A scene may size it with `"ground": { "half": 150 }`
841
+ at its top level: the half-width in metres, clamped to 1..200 (the world's
842
+ `xz` bounds), the same for the server's ground collider, the client's own
843
+ collider and the drawn plane (2 × `half` wide, its line grid one cell per whole metre of width, about 1 m each).
844
+ A `half` that is not a finite number is no key. `none: true` still means no
845
+ ground, whatever `half` says. Sun shadows and view distance do not follow
846
+ it: a larger ground may need `engine.view`.
847
+
807
848
  A scene with no authored environment -- no top-level `background`,
808
849
  `engine.sky` or `engine.view` key -- gets a pale clear colour and cheap
809
850
  linear ground fog from the hub client. It adds no mesh or render pass and
@@ -865,7 +906,7 @@ player by this API, rather than by a place-wide controller without a car spec.
865
906
  | `speed`, `reverse` | 12, 4 | clamped to 2–16, 1–6 m/s |
866
907
  | `accel`, `brake` | 6, 14 | clamped to 1–20 m/s² |
867
908
  | `turn` | 1.6 | clamped to 0.3–3 rad/s |
868
- | `camDistance`, `camHeight` | Player's × 1.4 | finite positive metres |
909
+ | `camDistance`, `camHeight` | Player's × 1.4; under the orbit key, the orbit's walking distance and height × 1.4 | finite positive metres |
869
910
  | `horn` | absent | file listed in this place's `idle.sounds`; offers Horn |
870
911
 
871
912
  A car is the driver's own predicted capsule, moved by the walk controller's
@@ -899,6 +940,27 @@ draw each rider from the driver's interpolated DRAWN pose, with the local
899
940
  rider's camera following the car and movement/jump input ignored. The place's
900
941
  own Get out action may call `hub.ride(playerId, null)`.
901
942
 
943
+ **Observed progress in a car (v1.165).** While a player drives, their
944
+ `hub.observed` allowance is their car's, `max(car.speed, car.reverse)` × the
945
+ same 1.25 tolerance, the speed the movement clamp already follows (and
946
+ `hub.observed(...).speed` reads it), so a car door can score from stations
947
+ and `travel` as a foot door does. `hub.tune` does not move it while driving.
948
+ The tick the driving state changes (getting in, getting out, a respray to
949
+ another speed) fills the credit at the lower of the old and new allowance and
950
+ holds it to the new cap: getting in buys no credit a walker did not have. A
951
+ walker's tune change is no such change. Getting out is a placement, so a
952
+ reset. A rider keeps the walker's allowance and is excluded from earning while
953
+ riding: adopted on the seat with no travel, no credit and no station entry,
954
+ however slowly the car moves. See [observed progress](observed-progress.md).
955
+
956
+ **A placed driver's heading (v1.165 fix).** A server placement of a driver
957
+ with a facing (`hub.placeAt`, `hub.hold`, the deck's reset or grid) reaches
958
+ the client as its own clamped pose row, which already carries the server's
959
+ facing. The client now gives the car that facing, from rest, when the clamp
960
+ is a placement: the driver is held, or the facing turns the car by more than
961
+ 20°, or the clamp moved it more than 1 m. Before, the car kept the heading the
962
+ player had walked or driven in. No wire field is added.
963
+
902
964
  `hub.drive(playerId, null, at?)` gets the driver and all riders out. The
903
965
  default exit is 1.6 m to the car's left for the driver, and beside each
904
966
  rider's seat for riders. Optional `{ x,z,y?,facing? }` replaces the driver's
@@ -958,7 +1020,11 @@ held (§8) or has not arrived; a player's grab and throw messages are limited to
958
1020
  4 a second. A hold also ends when the place hides the object, when the
959
1021
  multiplayer kit hands it to someone else, when the player is held, on a trip
960
1022
  and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
961
- whistle): the object falls where it is. A place without `grab` draws no button
1023
+ whistle): the object falls where it is. With no id only players the place
1024
+ registered as holding are told; since v1.191 a named player in the place is
1025
+ always sent `hub-drop` (with no `actor` when no hold was registered), so a
1026
+ client holding what the server never heard of lets go too. The return is
1027
+ still the count of registered holds ended. A place without `grab` draws no button
962
1028
  and is sent exactly what it was.
963
1029
 
964
1030
  **A steadier offer (v1.22).** The offer is tested afresh every frame: within
@@ -1083,9 +1149,18 @@ without it draws nothing new and is sent exactly what it was.
1083
1149
  not arrived, and asks the place's `emote` hook, which may refuse it.
1084
1150
  `hub.emote(playerId, id)` plays one on a player from the place itself (an
1085
1151
  NPC's greeting, a goal) and is neither rate-limited nor offered to the hook.
1152
+ v1.174: it also plays `yawn` 🥱 (3 s, model-only: a stretch up with the
1153
+ head tipped back, then a sag that droops forward and a little sideways
1154
+ with a slow nod, then back to rest), for a benched or idle player. Yawn is
1155
+ place-only: no picker or wheel offers it, a client's `hub-emote` for it is
1156
+ refused before the hook, and it plays the existing bow cue where the
1157
+ soundscape is on. An expression place's declared role emote named `yawn`
1158
+ keeps its own definition and grants instead. A client from before v1.174
1159
+ draws nothing for it (no motion, no emoji, no sound) and does not throw.
1086
1160
  v1.47: when a player's emote starts, up to three nearest free `HubNpc`
1087
1161
  bodies within 6 flat metres face them and emote back. Wave, dance, cheer
1088
- and bow answer with the same emote; spin answers with cheer. About one in
1162
+ and bow answer with the same emote; spin answers with cheer; a place's yawn
1163
+ (v1.174) with wave, from the wave lines. About one in
1089
1164
  three also says a short public line (§13). One player's emotes can start
1090
1165
  reactions once every 4 s, and each NPC reacts once every 8 s; the player's
1091
1166
  emote still plays as before. A conversation, follow, authored walk, place
@@ -1115,6 +1190,14 @@ without it draws nothing new and is sent exactly what it was.
1115
1190
  place's own `hub.hold` or `hub.release` of a sitter, a game's end, leaving,
1116
1191
  or the place hiding the seat stands them. `hub.seat(playerId)` says where a
1117
1192
  player sits. Sit and Stand are limited to 3 a second per player.
1193
+ v1.194: `hub.sitOn(playerId, seatId)` seats a player from the place's own
1194
+ server (a meeting's stools, a bench), with no reach check, no rate limit
1195
+ and no `sit` hook; a sitter on another seat or the ground moves to it. It
1196
+ returns `false` and changes nothing for a place without `idle.seats`, a
1197
+ player not here, in a car or held still by the place, or a seat that is not
1198
+ one, is hidden or is taken. Then it is an ordinary seat: everything above
1199
+ stands them. `hub.sitOn(playerId, null)` stands a sitter (`false` if they
1200
+ were not sitting). No wire change.
1118
1201
  - **Sounds** (`idle.sounds`). `hub.sound(actorId, file, { loop, volume,
1119
1202
  radius })` plays one of the files the place lists at a scene actor (or a
1120
1203
  spawned copy) for everyone, its volume falling off in a straight line to
@@ -1559,8 +1642,7 @@ named cue messages, in a deck with `soundscape.cues: true`.
1559
1642
 
1560
1643
  - **The control.** A speaker button in the right column, below the reserved native camera
1561
1644
  corner, opens Mute and a
1562
- volume slider, kept on the device (`localStorage`
1563
- `castle.hub.soundscape.v1`). It sets the level of everything above and of
1645
+ volume slider, kept on the device (`castle.hub.soundscape.v1`). It sets the level of everything above and of
1564
1646
  the place's own sounds (`hub.sound`, v1.6), which without the key play at
1565
1647
  the volume the place gave them.
1566
1648
 
@@ -1736,6 +1818,43 @@ absent; in a deck that declares it elsewhere, a place without it is refused
1736
1818
  as above). Ids are looked up as own properties only (`who`, `words`), so an
1737
1819
  id such as `constructor` names nothing it should not.
1738
1820
 
1821
+ **Away faces (v1.179, `ballot.keepAway`).** In a place whose `ballot` says
1822
+ `keepAway: true` (§1), a player the place is still retaining -- arrived,
1823
+ dropped, inside the place's resume window (§12), not yet forgotten and not
1824
+ let go by a kit trip or their own Back -- can keep their face on the others'
1825
+ cards, drawn with an away mark (`away: true` on the face; the kit draws an
1826
+ "away" tag and adds ", away" to its label). Every send and every tap follows
1827
+ one rule, from current state only, never from what a card carried: a face of
1828
+ T is eligible for viewer V iff T is present now (the ordinary rules: here,
1829
+ and no block among players here hides them), or T is retained away now and
1830
+ the record the kit wrote at the last send T was present holds V, present
1831
+ with T then and not hidden from T by a block then, under the account V is
1832
+ signed in as now, and that record's T account is the account T's retained
1833
+ visit is held for now. The away face is drawn from that record's snapshot of
1834
+ T's username and avatar, taken at the same send under T's account then (an
1835
+ avatar only from a hello made under that account; without one, no record is
1836
+ written and no away face is shown). Any account change on either player id
1837
+ invalidates its records the moment it is seen (any message from that id, a
1838
+ tap naming it, or a send), generations are never reused, and a guest
1839
+ (anonymous or a dev guest) is never in one. "Retained" is read at the tap or
1840
+ send itself: past the resume deadline, or dropped right after their own
1841
+ Back, a player is not retained even before the place lets them go.
1842
+ The kit keeps these records from the place's first tick (before any card),
1843
+ because the host answers blocks only about players here now. A tap on a
1844
+ face counts iff the face is eligible at tap time by the same rule, whatever
1845
+ `away` the card it was made on showed, and is then handed to the `ballot`
1846
+ hook exactly as any (`off`, locks and rule A unchanged); the version does not
1847
+ move when a face turns away or back. Only faces: feed rows from or to an
1848
+ away player are still left off, and `hub.ballot` calls naming them still skip
1849
+ them, so their own card is not kept while they are gone. When the retention
1850
+ ends (expiry, a kit trip, a Back drop, shutdown), the place forgets them as
1851
+ for any leave: the `leave` hook runs, their face goes from every card on the
1852
+ next send and a tap on it is refused, and the deck's votes for them follow
1853
+ its own leave rules. A player who comes back inside the window is sent their
1854
+ card again as after any fresh join. Without the key nothing of this runs or
1855
+ is sent: only present players are on cards, and a tap on a face not on the
1856
+ viewer's card is refused.
1857
+
1739
1858
  **Player contact is not in v1.** Other players are kinematic capsules on every
1740
1859
  client, so nobody can be shoved (M0 gap 4). That is an engine rule, not a
1741
1860
  contract field; a game that needs it waits for it.
@@ -1782,6 +1901,44 @@ hub.result(playerId, { outcome: 'win', score: 16900, stats: { laps: 3 } });
1782
1901
  host's results read itself. A copy: changing it changes nothing. Null on the
1783
1902
  dev serve, for an anonymous player, and until the first read lands.
1784
1903
 
1904
+ ### Public Town wins (v1.205)
1905
+
1906
+ ```js
1907
+ hub.celebrate?.(playerId, { kind: 'win', door: 'race', tokens: 25, streak: 3, unlock: 'stadium-pin' });
1908
+ ```
1909
+
1910
+ Only the Town root server (a `main` place without `result`) exposes this
1911
+ optional method. It returns a promise of a boolean: true when queued, false
1912
+ for an invalid, absent, unsigned or daily-limited player, or an unconfirmed
1913
+ reservation. No client message invokes it. `door` is an authored HubDoor id;
1914
+ `unlock`, if supplied, is a declared earned-item id. `kind` is only `win`,
1915
+ finite `tokens` is floored and clamped to 0..40, and `streak` is 3, 5 or absent.
1916
+
1917
+ Each accepted call reserves one of six celebrations per account per LA day
1918
+ (`hub.townDay`), using an atomic `earn:<userId>:<LA date>:celebrate` counter
1919
+ in deck storage. A failed or dropped reservation may consume a slot and
1920
+ never shows twice. A dev session without storage uses a layer-local count.
1921
+ The layer sends at most one every 4 s, queues three and drops the oldest
1922
+ over that bound. A queued player who leaves, changes account or crosses
1923
+ LA midnight is dropped; recipients and the 25 m distance are checked at send
1924
+ time, and hidden pairs are excluded.
1925
+
1926
+ The private transport message is `{ k: 'celebrate', player, kind, door,
1927
+ tokens, streak?, unlock? }`. Each receiving client plays a token chime through
1928
+ the existing soundscape gates and a pooled coin burst on the avatar for 2.5 s;
1929
+ Low skips the burst. Other viewers see `won <door label> · +<tokens>` for 20 s
1930
+ when tokens are positive, or `won <door label>` when tokens are 0 (no `+0`).
1931
+ A zero-token win still plays the burst outside Low and the usual token chime.
1932
+ The Town calls this for a verified server-read WIN (`stats.played > 0`) on the
1933
+ first win at a door that LA day or a streak reaching exactly 3 or 5, including
1934
+ wins after the daily token cap pays 0. Losses and other repeats stay private.
1935
+ The winner's existing private result ribbon stays at 60 s. Travel, disconnect
1936
+ and disposal clear the transient display. No call adds state fields, messages
1937
+ or resources; snapshots and deltas stay byte-identical even after a call.
1938
+ Older clients ignore the message and keep the private ribbon. No SDK or native
1939
+ host transport change is needed; native drawing of the new moment is a
1940
+ separate host pass.
1941
+
1785
1942
  ## 8. Holding a player still
1786
1943
 
1787
1944
  `hub.hold(playerId, at?, facingDeg?)` pins a body at `at` (default: where it
@@ -1792,6 +1949,16 @@ race's countdown line: `hold` on arrival, `release` at "go". A seat (v1.6, §6)
1792
1949
  is a hold too: the place's `hold` replaces it and its `release` ends it, which
1793
1950
  stands the sitter.
1794
1951
 
1952
+ A held body takes the facing, but the player's own avatar and camera keep
1953
+ theirs. With `{ turnCamera: true }` (v1.190) the held player is sent
1954
+ `hub-hold-face` with the held facing (the body's own when `facingDeg` is left
1955
+ out), and again at `hub.release`: their client turns as a jump does, the
1956
+ camera to look along that facing (`camAngle = PI - facing`) and, under the
1957
+ orbit camera key, the avatar to it (`faceRequest`). A later hold without the
1958
+ option replaces it, so its release turns nothing; any other end of the hold (a
1959
+ seat, the visit's end, leaving) turns nothing. Absent, a hold is exactly as
1960
+ before (v1.85: a face never changes the camera's yaw).
1961
+
1795
1962
  ## 9. The HUD vocabulary
1796
1963
 
1797
1964
  The only way a Tier 0 game puts words on screen (M0 gap 1). Drawn by the hub
@@ -1819,6 +1986,15 @@ The server validates the boolean but does not retain it or send it in `hubPlace`
1819
1986
  Absent or false keeps the previous rendering, creates no layout probe or report,
1820
1987
  and adds no client state key.
1821
1988
 
1989
+ v1.186: the top-left Back corner is reserved in every place, safe insets or
1990
+ not. Without `hub.safeInsets`, the kit's Again control (a game reached with no
1991
+ host trail) stood at 12 px from the left edge (76 px in landscape), inside the
1992
+ 64 × 56 box in portrait and wherever the left safe area exceeds 12 px; there it
1993
+ now stands at the bottom centre, the page bar's primary slot: 12 px from the
1994
+ bottom edge, or 6 px over the bottom safe area where that is higher, under the
1995
+ prompt pill. Back to a door or a town, Again elsewhere, and places with
1996
+ `hub.safeInsets` are unchanged. No key, no wire field.
1997
+
1822
1998
  Safe placement persists through CSS custom properties; animation frames do not
1823
1999
  restore, measure or reapply it. Insets are read on initialization and viewport
1824
2000
  resize/orientation/visual-viewport events. DOM changes coalesce into keep-out
@@ -1829,7 +2005,7 @@ restacks (Act/Jump arriving) never leaves the rail over it for a frame or a
1829
2005
  report.
1830
2006
 
1831
2007
  1. Edge-anchored chrome keeps `max(its existing margin, env(safe-area-inset-*))`
1832
- on that edge. This includes People/Doors, Character, the action column and
2008
+ on that edge. This includes People/Doors, Character, the action rail and
1833
2009
  its open cards, pointers, bubbles, toasts, the result ribbon and HUD. Zero
1834
2010
  insets preserve the existing edge offsets.
1835
2011
  2. The host owns a 64 × 56 CSS px box at each top corner, measured from the
@@ -1840,9 +2016,9 @@ report.
1840
2016
  same boxes for its own controls.
1841
2017
  3. Measured chrome crossing a view edge is pulled inside its safe edge and
1842
2018
  margin. Oversize text wraps; an oversize card keeps its bottom in view and
1843
- scrolls rather than losing its content. This key enables the existing
1844
- action overflow path even without a scene's `hubActionOverflow` key,
1845
- keeping all offers through More/Actions and clear of Shift lock. Round buttons,
2019
+ scrolls rather than losing its content. Action offers use the overflow
2020
+ rail (every place does since v1.187), keeping all offers through
2021
+ More/Actions and clear of Shift lock. Round buttons,
1846
2022
  Character, Shift lock and Decorate use one measured bottom-up stack; a short
1847
2023
  view wraps whole controls into the next column. External cards and controls
1848
2024
  share one current registry with the action solver and its observers, so an
@@ -1936,19 +2112,26 @@ buttons) is not moved.
1936
2112
  ### Action chips (v1.74)
1937
2113
 
1938
2114
  A place with `actions: true` may offer each player up to three buttons with
1939
- `hub.actions(playerId, [{ id: 'start', label: 'Start' }])`. They stack upward
1940
- at the bottom-right, with targets at least 44 px tall, above Character, Grab,
1941
- emotes, speech and the decor button. When that column is full, they move left
1942
- of the measured left edges of the round-control column, with a 12 px gap,
1943
- above any controls sharing the new span. Sound and its open card,
1944
- the HUD, the ask card and Back are upper bounds; other controls sharing the
1945
- chips' column push the stack up wherever they sit in the view. Chips keep
1946
- 12 px view margins and gaps above controls, and trim from the top when the
1947
- second position is full, retrying both positions after each trim and preserving
1948
- the first (bottom) chip whenever it fits.
2115
+ `hub.actions(playerId, [{ id: 'start', label: 'Start' }])`. Since v1.187 every
2116
+ place draws them on the action overflow rail, in landscape as in portrait and
2117
+ with or without `hub.safeInsets`; the scene key `hubActionOverflow` changes
2118
+ nothing. The rail keeps authored order and targets at least 44 px tall. It is
2119
+ placed low and right first, beside or above the measured controls (Character,
2120
+ Grab, emotes, speech, Sound, the decor button and the rest), clear of the
2121
+ host's top corners and the movement stick's half of the view: one row, else
2122
+ two rows, else the first offer and More (the rest), else one Actions button.
2123
+ More and Actions open a sheet listing every offer; it dismisses with Close,
2124
+ Escape or platform Back and holds only local input while open. When no place
2125
+ clears every control, the rail goes over passing text (the prompt, toast,
2126
+ feed, stats and result ribbon, then the HUD title) rather than leaving an
2127
+ offer with no More or Actions. At 844 × 390 three short offers stand in one
2128
+ row with none behind More. Before v1.187 a landscape place without either key
2129
+ stacked the chips upward at the bottom-right and trimmed them from the top
2130
+ when the column was full, so an offer could be lost with no sign of it.
1949
2131
  They yield to open panels, decorating, the choice card and travel.
1950
- Pointer presses do not focus chips; clicks blur them, and
1951
- a chip focused by other means contains its keydown/keyup events. Identical
2132
+ Pointer presses do not focus chips, and a pointer pick in the sheet leaves no
2133
+ chip focused; a chip focused from the keyboard contains its keydown/keyup
2134
+ events. Identical
1952
2135
  received items and `n` keep the existing buttons.
1953
2136
 
1954
2137
  A tap sends `{ k: 'hub-action', id, n }`. It reaches `action` only if `n` is a
@@ -1976,11 +2159,12 @@ restores its current offer.
1976
2159
 
1977
2160
  An action the player chooses is a button (hub.actions); standing somewhere only moves the player. Stand-on pads stay for go doors and race starts.
1978
2161
 
1979
- ### The companion (v1.71, dress and pose v1.78)
2162
+ ### The companion (v1.71, dress and pose v1.78, shown v1.181)
1980
2163
 
1981
2164
  A place with `companion: true` may give each arrived player a floating
1982
2165
  companion with `hub.companion(playerId, { look: 'lantern', say: 'Follow me',
1983
- at: 'gate' })`. The whole spec is private to its owner. **The place authors
2166
+ at: 'gate' })`. By default the whole spec is private to its owner; birds may
2167
+ share dress with `shown: true` (below). **The place authors
1984
2168
  every line; nothing a player typed may be passed to `say`. The line is never
1985
2169
  shown to anyone else.** With the object manifest form, the existing NPC talk protocol also opens a private chat (§13).
1986
2170
 
@@ -1997,7 +2181,8 @@ version with `say` shows the owner's existing speech bubble for 3500 ms plus
1997
2181
  The current line is shown again, once, when the owner's connection comes
1998
2182
  back or their frames stopped for ten seconds (a hidden page), whatever the
1999
2183
  version: a reconnect says it again. No wire change.
2000
- Other players see only a tiny warm glow parented at the avatar's shoulder.
2184
+ Unless the bird is shown (below), other players see only a tiny warm glow
2185
+ parented at the avatar's shoulder.
2001
2186
  The owner's public id draws no second glow. Bodies rebuilt or removed take
2002
2187
  their glows with them; travel hides both follower and glows.
2003
2188
 
@@ -2017,6 +2202,11 @@ height on portrait phones (35% width and 45% height in landscape), with at
2017
2202
  least a 4% screen inset.
2018
2203
  In portrait the whole box stays left of the projected player centre by at
2019
2204
  least 2% of view width, including while the held pose springs to its target.
2205
+ In landscape it stays at least 2% of view width left of the player's
2206
+ projected left side (a 0.4 m half-width at the player's depth); a close shot
2207
+ with no room at 35% even at the farthest depth, such as the House wardrobe,
2208
+ centres the box in the strip left of the player instead (2026-10-25, no
2209
+ version).
2020
2210
  Its built paper bounding-box height at normal scale seeds the distance; the
2021
2211
  transformed paper and worn vertices, including the hat anchor and wing flutter,
2022
2212
  then fit about 33% of the vertical view, reduced as needed for width clearance.
@@ -2043,13 +2233,30 @@ scale, opaque paper and worn materials. The additive glow uses 20% of its normal
2043
2233
  restored afterwards. Show suppresses leading, quieting, stamp twirls and
2044
2234
  temporary hat try-on while keeping the worn item visible. Clearing the pose
2045
2235
  flies back to normal follow.
2046
- Dress and pose are owner-only, never in `hubGlow`, snapshots or deltas; the
2047
- public glow remains presence only. The opted-in server API exposes
2048
- `hub.companionDress === true` for dress and the separate
2049
- `hub.companionPose === true` for pose. A kit with dress support may lack pose
2050
- support; places must gate each field on its own capability. These server-only
2236
+ Dress is shown to others only with optional own `shown: true` (v1.181),
2237
+ which publishes its species, wear and tint enums to everyone in the place
2238
+ through `hubChirp` (§12). Every value other than `true` throws `TypeError`,
2239
+ and a lantern rejects the field. Absent `shown`, dress stays owner-only and
2240
+ wire bytes are unchanged. Pose, `say` and `at` stay owner-only and never enter
2241
+ `hubChirp`; `hubGlow` remains presence only. The opted-in server API exposes
2242
+ `hub.companionDress === true` for dress, the separate
2243
+ `hub.companionPose === true` for pose, and `hub.companionShown === true` for
2244
+ shown. Places must gate each field on its own capability; these server-only
2051
2245
  flags send no wire bytes.
2052
2246
 
2247
+ `shown` selects publication on the server and is omitted from the owner's
2248
+ private `hub-companion` spec, so older clients keep their full follower.
2249
+
2250
+ On web clients a shown bird replaces the bare glow on other players' existing
2251
+ shoulder anchor with a small paper bird, using the same species, tint and
2252
+ accessory models. Its owner keeps their full private follower. Low keeps the
2253
+ glow, coloured by the bird's tint (the usual warm glow when tint is absent).
2254
+ The bird or glow hides with its drawn avatar and for blocked pairs; changing
2255
+ its dress or tier, clearing it and leaving disposes the replaced resources.
2256
+ Shown follows the companion through clear, leave, account change and place end.
2257
+ A `resumePose` retained visit replays it to the same account, including gap-time
2258
+ changes; another account gets it cleared, like the private follower.
2259
+
2053
2260
  Every species uses the same wing rig, head anchor, lead, perch, twirl and
2054
2261
  quiet-follow scaling/opacity. Hummingbird wings flutter faster. Tint paints
2055
2262
  the main body and wing paper, leaving glow, beak and eyes unchanged. A worn
@@ -2060,7 +2267,8 @@ These unlit primitives use no textures, lights or shadows: 30 triangles for
2060
2267
  the lantern, sixteen for the songbird, 40 for the owl, 31 for the parrot,
2061
2268
  30 for the hummingbird (including their glows), eight for a public glow. The paper bird is
2062
2269
  about 0.5 m across, with orange undersides (`#f2a65a`) for its folds and a soft glow behind it. They are nodes,
2063
- never scene actors, so tier rules neither count nor cull them on Low.
2270
+ never scene actors; the private follower stays on every tier, while public
2271
+ shown birds use the Low glow fallback and hide with their drawn avatar.
2064
2272
  Private state arriving before WORLD is held until the place's opt-in is
2065
2273
  known; a keyless WORLD drops it. Reconnect re-hello drops stale private state
2066
2274
  and replays the current companion, including its line. Ordinary sends are
@@ -2198,7 +2406,7 @@ in snapshots or deltas. Before WORLD, offers buffer but draw nothing until
2198
2406
  an opted-in place is known; a keyless WORLD discards them. Reconnect clears
2199
2407
  private client state before the hello replay.
2200
2408
 
2201
- The sheet is phone-first, at most 55% of the viewport height, with an internal
2409
+ The sheet is phone-first, at most 55% of the viewport height (but never under 220 px, or 150 px with `face`, short of the viewport less 24 px, so a short view such as an embedded 574 × 246 frame still shows a row of choices), with an internal
2202
2410
  scroll and the avatar visible above it. A title row has Close (×), then the
2203
2411
  optional note and section titles with square tiles of at least 64 px: 3–4
2204
2412
  columns on portrait phones, more on wide screens. Each tile shows a color
@@ -2229,7 +2437,8 @@ disabled now, and every client (including later joiners) removes it.
2229
2437
  `hub.show(actorId)` puts it back as authored. Only actors of the place's scene
2230
2438
  (M0 gap 2: the race's start gate). On the client a hidden actor is moved far
2231
2439
  below the ground with its collider rather than despawned, so it is meant for
2232
- actors that do not move by physics.
2440
+ actors that do not move by physics (a v1.184 solid private hide, below, keeps
2441
+ its collider in place).
2233
2442
 
2234
2443
  **Per-viewer visibility (v1.62).** `hub.hide(actorId, { to: [playerIds] })`
2235
2444
  and `hub.show(actorId, { to: [playerIds] })` replace the shared visibility for
@@ -2248,6 +2457,24 @@ invalid actor/options or the cap warn once per refusal kind and return false
2248
2457
  without changing anything. Leaving drops that player's overrides, including
2249
2458
  ones set before their first hello, except for the bounded retained visit below.
2250
2459
 
2460
+ **Solid private hides (v1.184).** `hub.hide(actorId, { to: [playerIds],
2461
+ solid: true })` hides the actor from those viewers' eyes only: their clients
2462
+ leave it where it is, collider and all, and draw nothing of it, instead of
2463
+ moving it below the ground. A per-viewer cutaway wall stays a wall the hiding
2464
+ viewer cannot walk through. Everything else on their client still reads it as
2465
+ hidden (grab offers, pads, idle, sound, quality culling). `solid` is optional
2466
+ and defaults to false; when supplied it must be a boolean, or the call is an
2467
+ invalid-options refusal. It is only meaningful on a private hide: the shared
2468
+ `hub.hide(actorId)` takes no options, and `hub.show(..., { to, solid: true })`
2469
+ is refused as invalid options (`solid: false` is accepted and changes
2470
+ nothing). With `clear: true` it is ignored: clearing drops the override
2471
+ whole. A later hide of the same actor for that viewer, solid or not, replaces
2472
+ the earlier one. While the shared state also hides the actor (its server body
2473
+ disabled), the client drops it below the ground as before. The override
2474
+ counts against the same 256-per-player cap, is carried by retained visits
2475
+ like any other override, and the server body is untouched, as for every
2476
+ private call.
2477
+
2251
2478
  Only the client's view changes: server logic that reads `h.hidden` (pads,
2252
2479
  labels, doors and idle) continues to use the shared state. Server bodies and
2253
2480
  grab ownership are unchanged by private calls; a privately shown actor whose
@@ -2353,6 +2580,15 @@ only in the recipients' label overrides, with no spawned actor or shared pose.
2353
2580
  Clear or refresh the label when its target leaves or becomes hidden from its
2354
2581
  viewer; `about: playerId` also applies the kit's block filter to that label.
2355
2582
  Older kits have no capability and callers must fall back to location text.
2583
+ Self-anchored goals (v1.201): `hub.goalSelf === true` advertises `{ at: "self" }`
2584
+ on a private goal, with an optional `rise: n` (metres, finite, above 0, at most
2585
+ 4; anything else is dropped). Each recipient's client points it at its own
2586
+ avatar's predicted Transform, `rise` metres up, every frame, so it cannot trail
2587
+ onto a neighbour the way a server-sent point can; with no local avatar it is not
2588
+ drawn. It is sent once, not refreshed as the player walks. The actor stays its
2589
+ label key and its Transform is not read. Only private goals carry it; shared
2590
+ signs, tags and speech ignore it. A kit without the capability drops the string
2591
+ and points the goal at the actor, so callers keep their v1.128 path there.
2356
2592
 
2357
2593
  v1.39: the distance shown is the player's straight line to the actor unless
2358
2594
  the goal says which to show -- `{ distanceM: n }` is the number of metres
@@ -2484,6 +2720,21 @@ the place despawns is forgotten by every client, pose history included. Bounded:
2484
2720
  returns null and logs once, and a game tries again later. A copy a client
2485
2721
  reports gone (the multiplayer kit's pickup rule) is gone for the game too.
2486
2722
 
2723
+ **A copy's carer (v1.162).** `hub.spawn(fromActorId, at, { carer: playerId })`
2724
+ names the player a copy goes with: a pet that follows its owner, or a piece
2725
+ it wears. Optional; a `carer` that is not a string or not a player in the
2726
+ place at that moment is ignored, and the copy is spawned without one. The
2727
+ carer is kept for the copy's life, including after that player leaves: the
2728
+ place despawns the copy when it means to. The wire carries it only when set,
2729
+ as `carer` on the copy's `spawned` record, so a copy without one is sent in
2730
+ exactly the same bytes as before. Its one effect is on a client: on Low tier,
2731
+ under `hub.quality`, a copy whose carer's avatar is not drawn (outside
2732
+ `quality.low.players` and not exempt) is hidden with that avatar, and drawn
2733
+ again when they are or on High. The local player's own copies are always
2734
+ drawn. The native engine does the same as of castle-client 1d8cefc38e: it
2735
+ ports Low's bystander cap and hides a copy whose carer is culled. Garden-style
2736
+ copies with no one moving them simply leave it out.
2737
+
2487
2738
  **Scenery a scene marks static.** A place's scene may mark actors
2488
2739
  `"static": true` and set `"engine": { "staticActors": true }` (physics-3d
2489
2740
  `CLAUDE.md`): the engine then leaves a marked actor alone until it is told the
@@ -2557,7 +2808,7 @@ with no `HubSpin` is looked through once when it loads and nothing more:
2557
2808
  nothing is registered, turned or touched. A shop that turns its hats lets a
2558
2809
  player try one on with `hub.tryOn` (v1.28), never saved.
2559
2810
 
2560
- ### Decorating (v1.67)
2811
+ ### Decorating (v1.67; v1.164 action tiles)
2561
2812
 
2562
2813
  A place opts in with `hub.decor` (or `hub.places.<id>.decor`):
2563
2814
 
@@ -2613,6 +2864,7 @@ changing state. Specifications contain only these fields:
2613
2864
  id: 'chair', tab: 'furniture', label: 'Chair', template: 'chair-template',
2614
2865
  w: 1, d: 1, layer: 'floor', count: 2,
2615
2866
  // locked: { price: '120 ▲' },
2867
+ // action: true, // v1.164; a button tile that sends pick instead of placing
2616
2868
  }],
2617
2869
  // swatches: [{ id: 'sage', tab: 'walls', label: 'Sage', color: '#779977' }],
2618
2870
  placed: [{ key: 'chair-template-1', item: 'chair', x: 2, z: 3, rot: 0, layer: 'floor' }],
@@ -2646,15 +2898,24 @@ id. `update` may change `grid` like any other named field.
2646
2898
  { op: 'move', key, x, z, rot }
2647
2899
  { op: 'stash', key }
2648
2900
  { op: 'swatch', swatch }
2901
+ { op: 'pick', item } // v1.164; unlocked action tile only
2649
2902
  { op: 'close' }
2650
2903
  ```
2651
2904
 
2652
2905
  Only arrived, connected players receive routing. A button must be offered;
2653
2906
  every other op requires that player's own open catalogue. Items must be
2654
2907
  pickable with spare stock; keys and swatches must belong to that catalogue.
2908
+ `pick` requires an unlocked item with `action: true`, with no stock check;
2909
+ an action item cannot be placed.
2655
2910
  Cells are integers inside the grid, rot 0..3; unknown fields/ops are dropped.
2656
2911
  The server routes at most six ops/s per player with a burst of eight; a hook
2657
2912
  refusal spends its token too. Throws/rejections are logged and contained.
2913
+ (v1.164) An item with `action: true` is a button tile: an unlocked tap sends
2914
+ `pick` and starts no ghost. Its count is still required and may be zero; it
2915
+ shows no ×n chip, and its template, size and layer are validated as usual. A
2916
+ locked one shows its lock and price and sends nothing. Any other `action`
2917
+ value is refused. A catalogue without it sends the same bytes.
2918
+
2658
2919
  **The deck decides ownership, collision, stock consumption and saving.** The
2659
2920
  kit changes no actor for an op, and does not close on a close request: the
2660
2921
  hook calls `hub.decor.close`, or accepts an edit with `hub.spawn/move/despawn`
@@ -2698,8 +2959,81 @@ A saved town draws door games with its own client. A town on a kit before
2698
2959
  v1.67 ignores the private decor message; update and save that town before
2699
2960
  offering a house with decorating through its doors.
2700
2961
 
2962
+ ### Private ghost replay (v1.163)
2963
+
2964
+ `hub.record(playerId, 'start' | 'stop' | 'cancel')` and
2965
+ `hub.replay(viewerId, 0 | 1, spec | null)` are server-only, on by use: no
2966
+ manifest key, host operation or storage. An unused place allocates no replay
2967
+ state and produces byte-identical joins, snapshots, deltas and messages.
2968
+
2969
+ `start` replaces a recording for a connected, hello'd, arrived player with a
2970
+ simulation body, returning true; refusal warns once and returns false. At most
2971
+ eight recordings exist, one per present player. The kit samples authoritative
2972
+ `hub.players()` `at` and the body's facing on its own ticks, initially every
2973
+ 250 ms, including the starting pose. It accepts no deck-supplied positions.
2974
+ At 192 poses it drops alternate samples, keeping the first, and doubles the
2975
+ step (250, 500, 1000, 2000, 4000, 8000 ms). Coordinates are integer
2976
+ centimetres, each within ±100000; yaw is integer degrees in [-180, 180).
2977
+ Nonfinite poses or positions outside that range abort the recording.
2978
+
2979
+ `stop` takes the final authoritative sample and consumes the recording. It
2980
+ returns a fresh plain JSON `{ v: 1, step, ms, poses }`, where `poses` is a flat
2981
+ integer array `[x, y, z, yaw, ...]`, with 2..192 samples, and `ms` is elapsed
2982
+ simulation time. Fewer than two distinct sample times, a missing/invalidated
2983
+ recording, or elapsed time **over 600000 ms (10 minutes)** returns null.
2984
+ The 10-minute limit applies even when the place permits a longer visit.
2985
+ `cancel` drops the recording and returns true.
2986
+
2987
+ Recording captures roster user id/anonymous flag, arrival generation and body
2988
+ object. Any change, departure, travel, end/shutdown or disconnect invalidates
2989
+ it, including a retained short drop/resume between ticks. Each sample and stop
2990
+ checks the captured fence. A resume never continues the old recording.
2991
+
2992
+ `spec` is `{ trace, look?, label?, color?, offsetMs? }`. `trace.v` must be 1;
2993
+ `step` one of the six values above; `poses` an array of safe integers in the
2994
+ same coordinate/yaw bounds, a multiple of four with 2..192 samples; `ms` a
2995
+ positive integer ≤600000, differing from `(samples - 1) * step` by at most one
2996
+ step. Unknown fields are refused. `look` names a scene actor's Model template,
2997
+ as for cars; absent it the kit draws a pale-blue figure. `label` trims to
2998
+ 1..24 Unicode code points without control characters; `color` is `#rrggbb`;
2999
+ `offsetMs` is an integer from 0 through `trace.ms`. Invalid calls warn once,
3000
+ return false and change nothing. At most four accepted calls per viewer per
3001
+ rolling simulation second; clears (null, and every lifecycle clear) are
3002
+ never budgeted, and null on an empty slot returns true and sends nothing. Two entries per viewer, slots 0 and 1, bound each message to
3003
+ roughly 6 KB. The input is copied before sending.
3004
+
3005
+ **Privacy:** delivery is per-viewer only. A ghost has no engine actor, body,
3006
+ collider, spawn or shared motion state. No trace enters snapshots, joins,
3007
+ latches or broadcasts; other and late-joining clients receive no replay bytes.
3008
+ The deck is responsible for friend privacy: obtain candidates through
3009
+ `friendBests(...).friendFor(viewerId)` / `friendsAmong`, fail closed on errors,
3010
+ and never use an arbitrary stored account's trace as a friend candidate.
3011
+ Since v1.163 `friendsAmong` and `friendBests` answers belong to the account
3012
+ they were read for: a player id that comes back as another account never
3013
+ reuses them, and gets `[]`/null until its own read, at most 31 s later.
3014
+
3015
+ Null clears the selected slot. Leave, travel, roster identity/arrival/body
3016
+ change, any disconnect/reconnect, place end and shutdown clear and forget the
3017
+ viewer's entries. A transport leave does so at once, even when real-time keeps
3018
+ the body for a rejoin before the next tick. The server also clears each entry more than 3 seconds after
3019
+ send time + `ms - offsetMs`. A fresh hello has empty client state; **no stale
3020
+ replay is retained or automatically resent**. A deck may explicitly call
3021
+ `replay` from `resume` with elapsed `offsetMs`, but that visit's prior
3022
+ recording remains invalid.
3023
+
3024
+ The kit draws at most two three.js Groups on every quality tier. Figures and
3025
+ Model copies use private translucent materials (opacity 0.4, no depth writes),
3026
+ no shadows and no raycast picking. Labels are small kit-owned sprites. Playback
3027
+ interpolates positions and shortest-arc yaw from the receipt clock plus offset;
3028
+ it holds the final pose, fades for one second, then frees its resources. Clear,
3029
+ travel/reset, fresh hello and scene changes remove both slots.
3030
+
2701
3031
  ## 11. The platform avatar seam
2702
3032
 
3033
+ Private ghost replay (v1.163, §10) draws a separate figure or scene Model
3034
+ template. It does not change any player's platform avatar, role or wearable,
3035
+ and never adds a player or actor to the shared world.
3036
+
2703
3037
  A hub game never draws a player. The kit draws everyone, the local player
2704
3038
  included, as their **avatar**: an id from the kit's set
2705
3039
  (`imports/castle.hub-game/blueprints/avatar-<id>.scene`, v1: `0`-`3`; v1.51:
@@ -3025,6 +3359,31 @@ The account's Look and Earned slots are unchanged.
3025
3359
  first. No manifest key is needed. A place that never calls it sends and
3026
3360
  draws exactly what it did before.
3027
3361
 
3362
+ **Held flowers (v1.182).** With top-level `hub.holdShow: true`, a place may
3363
+ call `hub.holdShow(playerId, { shape: 'daisy', color: '#fff4df' })`.
3364
+ `shape` is exactly `daisy`, `tulip`, `sunflower`, `rose` or `moonflower`;
3365
+ `color` is exactly `#rrggbb` (case-insensitive, copied lowercase). The spec
3366
+ must be a plain object with exactly those two own data fields, read once
3367
+ and copied; inherited fields, accessors and extra fields are invalid. Invalid
3368
+ input throws TypeError before anything changes, even for a missing player.
3369
+ An absent or not-arrived player returns false; otherwise the call returns
3370
+ true. Only null clears; omitting the argument is invalid.
3371
+ `hub.holdShowing(playerId)` returns a copy or null. Repeating the same spec
3372
+ sends nothing; rapid changes coalesce to the latest value at four per second
3373
+ per player. Reads reflect the latest accepted value immediately.
3374
+
3375
+ The flower is gripped in the right hand at 1.2×, fitted like an earned held
3376
+ item, on every quality tier, with square models for boxy sets. It hides the
3377
+ earned held item while set, restoring it on clear; a role tool or grabbed
3378
+ object takes priority, and the flower returns when that ends. Other Earned
3379
+ classes and the account's Look are unchanged. This is this visit only: a
3380
+ retained short drop keeps it and the returning player shows it again; trip,
3381
+ final leave, account change, fresh restart and place end clear it. Absent
3382
+ retained bodies are not drawn. Nothing is saved, put in storage, sent to
3383
+ ghost, or placed in the Earned slot. Older kits have neither method: decks
3384
+ check `typeof hub.holdShow === 'function'` first. Older web clients ignore
3385
+ `hubHoldShow` and `hub-hold-show`; native hosts ignore them until parity.
3386
+
3028
3387
  **The Earned slot (v1.53).** A player has two wearable slots. The **Look**
3029
3388
  (`hub.wear`, above: hats, halos, auras, anything with a rarity) is the town's
3030
3389
  and, later, the shop's. The **Earned** slot holds one small thing a game gave
@@ -3092,6 +3451,50 @@ never takes a hat off:
3092
3451
  are what they were. A client older than v1.53 ignores both and draws the
3093
3452
  Look alone.
3094
3453
 
3454
+ ### Disguise (v1.196)
3455
+
3456
+ Server-only `hub.disguise(playerId, { look?, to? } | null)` replaces a
3457
+ player's visit disguise; `null` clears it. `hub.disguised(playerId)` returns
3458
+ a copy `{ look, to }` or null, with absent options represented as null.
3459
+ No manifest key. `look` names a scene actor with a `Model`, usually a hidden
3460
+ template, validated like a car look. `to` is an array of at most 256 viewer
3461
+ playerId strings, deduplicated and sorted. Without `to`, every other viewer
3462
+ is targeted. An empty array targets nobody else.
3463
+
3464
+ With `look`, targeted viewers see its cloned model under the player's avatar
3465
+ node in place of the avatar model. They do not draw that player's name tag,
3466
+ `hub.mark` tag, role label, wearables (halo, aura, orbit or hats), role pieces,
3467
+ held/earned items, hold-show flowers, emote or speech bubbles, or companion
3468
+ bird/glow. The player sees their own replacement model too, regardless of
3469
+ `to`, with everything else of their own unchanged. Without `look`, only the
3470
+ name tag, mark and role label are hidden from targeted viewers; the avatar
3471
+ and decorations remain. This also hides tags that otherwise show through walls.
3472
+ Deck-made UI naming a player, such as pointers, ballot faces and HUD lists,
3473
+ is the deck's job.
3474
+
3475
+ The op returns true on success. A driver or rider, held player, player who
3476
+ has not arrived or is departing, invalid look, invalid `to`, or invalid shape
3477
+ (including unknown keys) returns false and warns once per reason. A `null`
3478
+ clear is always taken, even for a player held since. `hub.drive`
3479
+ and `hub.ride` refuse a disguised player. Leave, a kit trip, place end,
3480
+ `forget`, and an account change on the id clear the disguise; a drop inside
3481
+ the retained resume window keeps it, as cars do. Body, collider, pose stream,
3482
+ cells, Low culling and observed progress are unchanged.
3483
+
3484
+ A `look` disguise is also refused while the player holds a grabbed scene
3485
+ actor (`hub.holding(playerId)`). Players disguised with a look cannot start a new grab;
3486
+ the usual `hub-grab-deny` makes the client let go. A look-less disguise may
3487
+ be applied during an existing grab: that actor remains drawn and may still
3488
+ be thrown or dropped. This uses grab refusals rather than hiding grabbed
3489
+ actors, with no additional wire field.
3490
+
3491
+ One latched wire field, `hubDisguise`, holds sorted rows
3492
+ `[playerId, look | null, to | null]`, coalesced to at most one change per
3493
+ 250 ms per player. Reads are immediate. A deck that never calls the op gets
3494
+ byte-identical snapshots and deltas, without that key. After first use it is
3495
+ sent, including `[]` after the last clear. Old clients, old hosts and native
3496
+ hosts ignore `hubDisguise` and draw the real avatar and tag.
3497
+
3095
3498
  ### Home unlocks (v1.70/v1.73)
3096
3499
 
3097
3500
  A game may also give a player something for their house. It is never worn or drawn on
@@ -3163,6 +3566,15 @@ it in the decor tray, Rooms tab or pet book according to its class.
3163
3566
 
3164
3567
  ## 12. Wire (kit-internal, listed so a host or bot can speak it)
3165
3568
 
3569
+ ### Private replay (v1.163)
3570
+
3571
+ Server → one viewer only: `{ k: 'hub-replay', slot: 0 | 1, replay: spec | null }`.
3572
+ `spec` is the validated, copied §10 replay spec. This is a one-shot private
3573
+ message: no snapshot field, latch, broadcast or RESEND cache. Every admission's
3574
+ WORLD (not a resync's, `again: 1`), fresh hello and the client's
3575
+ clear/reset/scene lifecycle remove all ghosts. A retained resume
3576
+ may receive only newly authored calls, optionally with `offsetMs`.
3577
+
3166
3578
  ### Vehicles (v1.160)
3167
3579
 
3168
3580
  Only while cars exist, WORLD includes `hubCars`, a dictionary keyed by driver
@@ -3217,12 +3629,16 @@ both shared `labels` and this player's `labelsMe` targets. Protected targets sta
3217
3629
  awake and newly received targets wake immediately. Authored hidden templates below y=-50
3218
3630
  sleep until shown. Four metres around the player's position wake actors before
3219
3631
  crossing a district boundary. Moving actors' bounds follow their current
3220
- Transform. The table is checked each 100 ms and immediately on district changes.
3632
+ Transform. A `HubNpc` actor away from its authored origin (a resident on a walk)
3633
+ also stays live within 20 m of the player in another district, and once live
3634
+ until 22 m, so a walker does not vanish at a district line. The table is checked each 100 ms and immediately on district changes.
3221
3635
 
3222
3636
  Sleeping preserves components, behavior state, serialization and actor ID lookup,
3223
3637
  while behavior, render and collider passes omit the actor. The client restores
3224
3638
  all actors and its original model files on High, scene loads, door trips or
3225
- runtime disposal. The server and other players retain the full town. Weakest's per-runtime
3639
+ runtime disposal. A game reached through a door keeps the profile's capped
3640
+ renderer and composer ratios (Weakest's 0.5, Middle's halves) until High or
3641
+ the town again; only High or leaving the profile puts them back. The server and other players retain the full town. Weakest's per-runtime
3226
3642
  model file views invalidate built nodes while preserving authored look data.
3227
3643
  The look-bake queue suppresses outlines and AO without mutating
3228
3644
  the editor's files; the remaining look work is deferred. Weakest caps its
@@ -3316,6 +3732,8 @@ visit's first (the platform's door then, else none). One still arrived is
3316
3732
  not arrived again, and is re-sent all of the above);
3317
3733
  `{ k: 'hub-dev-classic', on? }` (v1.7; the dev serve's stand-in for classic boards, §4, ignored by any session that is not a dev one);
3318
3734
  `{ k: 'hub-door-jump', door }` (a town's Doors list, §5);
3735
+ `{ k: 'hub-stay', end }` (v1.169: exactly these keys, `end` the number of the door end being stayed, from a client that cancelled its own door end taken while offline: said once placed again and again right after each resume hello until the place answers `hub-stayed` with that `end`; undoes only the player's current stay record whose `end` matches, in a place without `result`, and holds that door shut for the player until a step in which the place does not ask for it; a missing, malformed or mismatched `end` is ignored, and a repeat of the end already stayed is answered `hub-stayed` again and changes nothing);
3736
+ `{ k: 'hub-back' }` (v1.173: exactly this, from a client whose player is leaving a place without `result` by their own Back press (system back, Escape or the kit's or host's Back control), sent just before it asks the host for the way back (`Hub.back`); never for a game's Back (that is `hub-door-quit`), a press that only closes the action overflow or place menu, a press during a trip, or an automatic back (a game end walking back, a place that ended the visit, a failed door's retry). The server sends nothing and changes nothing at once: it arms a mark for that player for 35 s (the SDK's 30 s `Hub.back` timeout and slack; a repeat restarts the window). If the kit sees that connection drop while the mark is fresh (for the same account), it lets the visit go first, as a kit trip's `hub-go` does (out of resume retention, arrival pose and durable pose store, resume pending dropped), so the next entry is a fresh arrival; a mark that goes stale with the player still here (the Back failed) is dropped and the visit is untouched. A kit trip, a place end, a stayed end, a leave and a hello under another account drop the mark. Ignored in a place with `result`, in a place that retains no visit, before the player has arrived, from a player not in the session roster or unknown to the place, and once the player is already departing (a kit trip or a place end). The kit consumes it in every place: it never reaches the place's `message` hook);
3319
3737
  `{ k: 'hub-unstick' }` (v1.33, §5 "Stuck?": only a deck with `hub.stuck` knows it, and only its towns answer, once in 5 s; v1.39, with `ask: true` it moves nobody and asks what the tap would do, answered only by a place with the `unstick` hook, once a second);
3320
3738
  `{ k: 'hub-say', r }` or `{ k: 'hub-say', p }` (v1.11, §6);
3321
3739
  `{ k: 'hub-answer', id, n, text }` (v1.75, §9: exactly these keys; text is a string or null for Cancel, checked against the sender's last-sent and current prompt and limited to two/s, burst four, including dropped attempts; refused text on a current id/version becomes a cancel with null; routed only with `ask: true`, never echoed);
@@ -3332,11 +3750,15 @@ Server → client, in deltas and the WORLD snapshot: `hubPlace` (the place's
3332
3750
  public manifest, with the `fallY` the session catches at, and `grab` (v1.3) only where the place sets it), `hubAv` (player id → avatar; v1.51: always one of `0`-`3`, `avatar % 4` for a player who wears another), `hubAv2` (v1.51, §11: player id → the avatar really worn, for the players who wear `4` or more and by `hubAv`'s rule of who is listed; in the snapshot only while there is such a player, in deltas from the first one on and `{}` once when the last is gone, never sent by a place where nobody has worn one), `hud`, `hidden`, `held`, `labels`, `tints` (v1.1,
3333
3751
  actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDoors` (a town's `[{ id, title }]`, each with `featured: true`, `solo: true` or `need: n` where they apply (v1.14),
3334
3752
  §5), `spawned` (v1.2, copy id → `{ from, x, y, z, rotationY }`) with
3335
- `spawnTemplates` (each template in use → its authored components), `hubWear`
3753
+ `spawnTemplates` (each template in use → its authored components), v1.197
3754
+ `hubDecorTpl` (sorted ids of the templates in use that the scene marks
3755
+ `"decor": true`, sent only by a deck with no `hub.quality` of its own, only
3756
+ once one has a live copy, and `[]` once the last is gone), `hubWear`
3336
3757
  (v1.4, player id → `{ kind, color, rarity }`; only once someone in the place
3337
3758
  has worn one, and like `hubAv` without the players in a hidden pair), and in a
3338
3759
  place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
3339
- `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id, or v1.158 `'ground'` for expression sit-anywhere),
3760
+ `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id, or v1.158 `'ground'` for expression sit-anywhere;
3761
+ v1.183: both, and `held`, like `hubAv` without the players in a hidden pair, whose go by `hub-idle`),
3340
3762
  `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing);
3341
3763
  v1.47 adds `hubNpcEmotes` (NPC actor id → `{ id, at, until }`, simulation ms)
3342
3764
  only after an NPC has emoted back, then latched when it changes, including
@@ -3358,6 +3780,21 @@ only, `hubStuck` (v1.33, `{ to }`: this place answers `hub-unstick`, and `to`
3358
3780
  is its name for its arrival or null, §5; only a town of a deck with
3359
3781
  `hub.stuck`; v1.39, with `hook: true` in a place that has the `unstick`
3360
3782
  hook, and no such key in any other).
3783
+
3784
+ `hubHoldShow` (v1.182, player id → `[shape, color]`) is a latched whole
3785
+ map, like `hubRole`. It appears in snapshots and deltas once anyone in the
3786
+ session has had a flower, including `{}` after the last clears. Deltas send
3787
+ only changed maps, coalescing each player's changes at four per second.
3788
+ A never-called deck, including one without the manifest opt-in, sends
3789
+ identical bytes. Absent bodies and players grabbing an object are omitted
3790
+ from the drawn projection, without losing their visit value. An earned held
3791
+ item stays masked during a grab, including in private earned projections;
3792
+ the account value is unchanged. Hidden pairs
3793
+ follow `hubRole`: `{ k: 'hub-hold-show', hubHoldShow }` carries only flowers
3794
+ the viewer may see, with fresh private replay including empty clears; a
3795
+ snapshot without the key clears only the shared map. Old web clients and
3796
+ native hosts ignore the new key and message (native parity is pending).
3797
+
3361
3798
  `hubRole` (v1.157, player id → `{ id, label, color, hat?, top?, tool? }`,
3362
3799
  §11) is a whole block, latched as `hubTry`: join snapshots include it only
3363
3800
  when non-empty. Deltas send changed blocks only after a role was shown,
@@ -3369,6 +3806,17 @@ with a non-null companion, and nothing else: no look, words or target. Only
3369
3806
  an opted-in place carries it, in snapshots once anyone in this session has
3370
3807
  had a companion (including `[]` after the last clears or leaves), and in
3371
3808
  deltas only when that whole array changes, latched as `hubWear` is.
3809
+ `hubChirp` (v1.181, §9) is a player-id-sorted array of
3810
+ `[playerId, species, wear, tint]` for helloed, arrived players whose companion
3811
+ has `shown: true`. Each default slot is `null`: species defaults to songbird,
3812
+ wear and tint to absent. Only these dress enums are public; `say`, `pose` and
3813
+ `at` never enter this field. It appears in snapshots only once anyone in this
3814
+ session has had a shown companion, including `[]` after the last clears or
3815
+ leaves. Deltas carry it only when the whole array changes, latched as `hubGlow`
3816
+ and `hubWear` are. Dress changes publish with the owner's existing four/s
3817
+ companion coalescing, newest wins. A place that never sets `shown` sends
3818
+ identical wire bytes. Old clients ignore `hubChirp`; native hosts ignore it
3819
+ until parity.
3372
3820
  v1.109 adds the optional latched snapshot field `hubDanceIdle`:
3373
3821
  `{ actor, file, bpm, beatAt, floors: [{ x, z, halfX, halfZ }] }`, or `null`
3374
3822
  to clear. `beatAt` is the playing loop's server simulation time (milliseconds)
@@ -3386,7 +3834,7 @@ Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6
3386
3834
  a one-shot); `{ k: 'hub-went', players, door }` (v1.15, a town: to each player staying, who of the players they may see went through `door`); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
3387
3835
  client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
3388
3836
  `{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
3389
- `{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5; v1.33, after `hub-unstick` too; v1.39, from a place with the `unstick` hook that one carries `stuck: { spot, to }`, whether the player was put at the hook's spot and the name of where they were put, or null),
3837
+ `{ k: 'hub-arrived', facing }`, `{ k: 'hub-hold-face', facing }` (v1.190: a `turnCamera` hold and its release, §8; radians, turned as `hub-jumped`), `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5; v1.33, after `hub-unstick` too; v1.39, from a place with the `unstick` hook that one carries `stuck: { spot, to }`, whether the player was put at the hook's spot and the name of where they were put, or null),
3390
3838
  `{ k: 'hub-unstick-to', spot, to }` (v1.39: the answer to `hub-unstick` with `ask: true`, the same two words for what a tap would do now),
3391
3839
  `{ k: 'hub-party', members, away, invite, proposal }` (v1.10, on change: the other members here as player ids or null for no party, how many are away, `{ from, username }` or null, `{ id, door, by, username, asked }` or null, told only to the proposer and the members asked),
3392
3840
  `{ k: 'hub-where', at }` (v1.9: player id → `{ x, z, where, door, on? }`, the ground spot to 0.1 m, the place's words or null, the door those words name or null, `on` true on its pad), `{ k: 'hub-hud', hud }` (that player's
@@ -3399,7 +3847,10 @@ override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or n
3399
3847
  or null when it is taken down; sent on change and again after a fresh
3400
3848
  `hub-hello` without `again`. `card` is `{ v, mode, title?, text?, until?, faces:
3401
3849
  [{ id, note?, off?, votes?, mark? }], options: [{ id, text }], lines: [ids],
3402
- feed: [{ from, to?, line }], picked?, words?, who: { playerId: { name, avatar? } } }`,
3850
+ feed: [{ from, to?, line }], picked?, words?, who: { playerId: { name, avatar? } } }`
3851
+ (v1.179: a face may carry `away: true`, only in a place with
3852
+ `ballot.keepAway`, for a player the place is retaining while they are gone;
3853
+ a client before it ignores the key and draws the face as any),
3403
3854
  `v` the card's version, an opaque string echoed as it came (§6 rule A: this
3404
3855
  server's epoch and a counter; it moves only when the mode, the faces
3405
3856
  offered or their `off`, the lines offered, the option ids or `picked` change
@@ -3409,18 +3860,21 @@ for that player); `who` the username and avatar index of every player the faces
3409
3860
  manifest line with the hidden names taken out, for each line it changes.
3410
3861
  Never in snapshots or deltas, never sent by a place without `ballot`, which
3411
3862
  also sends no `hubPlace.ballot`),
3412
- `{ k: 'hub-vis', hide: [actorIds], show: [actorIds] }` (v1.62, §10: the
3863
+ `{ k: 'hub-vis', hide: [actorIds], show: [actorIds], solid?: [actorIds] }` (v1.62, §10: the
3413
3864
  viewer's whole private visibility override, replacing their previous lists;
3414
- empty lists restore shared visibility. Sent privately on a changed override
3865
+ empty lists restore shared visibility. v1.184 `solid`, present only when
3866
+ non-empty, names the `hide` ids whose collider stays in place; an older
3867
+ client ignores it and drops them below the ground as before. Sent privately on a changed override
3415
3868
  set and replayed on a fresh `hub-hello` without `again` while overrides exist.
3416
3869
  Never in snapshots or deltas, never sent by a place that uses only shared
3417
3870
  hide/show),
3418
3871
  `{ k: 'hub-leaving', text }` (v1.52, one player's latest leaving line or null,
3419
3872
  on change and replayed on a fresh `hub-hello` without `again` when a line is latched;
3420
- never in a snapshot), `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }` (v1.72: with `again: true` when a resume place says it again, I3),
3421
- `{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
3873
+ never in a snapshot), `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }` (v1.72: with `again: true` when a resume place says it again, I3; v1.169: with `door` when it is the player's own door end in a place without `result`, and its `end`, the player's door-end number for the session),
3874
+ `{ k: 'hub-stayed', end }` (v1.169: to that player alone, answering the `hub-stay` that undid door end `end`, and each repeat of it),
3875
+ `{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor? }` (v1.3: `hub.drop`; no `actor` for a named player with no registered hold, v1.191),
3422
3876
  `{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }` (since v1.17 `disclosure` is always `"participants"` and `hearRange` always 0: a client from before it named the players in that range as a turn's listeners),
3423
- (v1.142) A child mind open may also carry `choices: [{ id, label }]` from that character's published `childAsks` (§13), without prompts; this takes precedence over legacy `choices: string[]` from `under13Choices`. (v1.148) Or `choices: string[]` with `authoredChoices: true`: the place's authored asks for that speaker, answered by the place (§13); these lead bundle chips.
3877
+ (v1.142) A child mind open may also carry `choices: [{ id, label }]` from that character's published `childAsks` (§13), without prompts; this takes precedence over legacy `choices: string[]` from `under13Choices`. (v1.148) Or `choices: string[]` with `authoredChoices: true`: the place's authored asks for that speaker, answered by the place (§13); these lead bundle chips. (v1.175) A mind open without `authoredChoices` whose `npcOpening` was `authored` also carries `fallbackChoices: string[]`, those same asks, which the client may tap (`hub-npc-say`, answered by the place) only while it cannot type (its inspect pending or refused); the server accepts a trimmed exact match from that speaker on that open and still admits their mind turns. (v1.153) A child open with bundle `choices` and no authored taps carries the three canned lines as `fallbackChoices`, on the same terms.
3424
3878
 
3425
3879
  `{ k: 'hub-npc', npc, open, ... }` gains `opening: { text, asks, more? }` where the place's `npcOpening` gave one (v1.37), or a mind gets the kit's default (v1.46; `more` only when non-empty), and `ageOff: true` (2026-10-17) only in the open of a mind sent to a speaker whose trusted server identity has `under13 === true`, in every place whatever `under13Choices` says (absent otherwise, and never in anyone else's message), `{ k: 'hub-npc-line', npc, text, why, op?, rid? }` (`why` v1.8, as `npcLine`'s; v1.46 `op` is the refused mind turn's operation id, absent for other lines; `rid` echoes an authored send's request id, a string of at most 64 characters, only when given), `{ k: 'hub-npc-notes', npc, prefix, persistentAsks? }` (v1.8, §13; v1.80 `persistentAsks` only where the place defines `npcAsks`, up to two private chips, an empty array clears), `{ k: 'hub-npc-opening', npc, text }` (v1.47, a late inspect's greeting for an open panel whose player has not yet sent words, §13), `{ k: 'hub-npc-hooks', hooks: [{ npc, character }] }` (v1.76, due greeting body/character ids for that signed-in player alone, no text, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
3426
3880
  hidden pair that this player may see, laid over the shared `hubAv`; v1.51: stand-ins as `hubAv`'s are, with `hubAv2` beside it in the same message when one of them wears `4` or more, laid over the shared `hubAv2`; the message is whole, so one without `hubAv2` says none of them does), `{ k: 'hub-wear', hubWear }`
@@ -3435,7 +3889,14 @@ map as it is, empty or not),
3435
3889
  it. Once a place has sent one, a client that joins afresh -- a `hub-hello`
3436
3890
  without `again` -- is sent the map as it is, empty or not, so one that comes
3437
3891
  back holds neither a try-on that came off while it was away nor misses one
3438
- that is up; a client keeps it across a snapshot).
3892
+ that is up; a client keeps it across a snapshot),
3893
+ `{ k: 'hub-idle', hubSeated, hubEmotes, held }` (v1.183, the seats, emotes
3894
+ and holds of players in a hidden pair that this player may see, itself
3895
+ included, laid over the shared `hubSeated` and `hubEmotes` and joined to the
3896
+ shared `held`; the message is whole, all three keys every time, and goes only
3897
+ where a hidden pair is or was. Once a place has sent one, a client that joins
3898
+ afresh -- a `hub-hello` without `again` -- is sent it again, empty or not; a
3899
+ client keeps it across a snapshot. Old clients ignore it).
3439
3900
  `{ k: 'hub-role', hubRole }` (v1.157) gives each permitted viewer the
3440
3901
  roles of players in hidden pairs, over the shared `hubRole`. Its effective
3441
3902
  role is `roleMe[playerId] ?? roleAll[playerId]`. It follows `hub-try` replay:
@@ -3449,7 +3910,10 @@ other; the host answers `session.hub.hiddenPair`, and the block lists never
3449
3910
  reach the kit) are taken out of each other's interest sets whatever the
3450
3911
  session's size, so neither is sent the other's pose rows or `in`; the shared
3451
3912
  `hubAv` (and `hubAv2`, v1.51) leaves out every player in such a pair, whose
3452
- avatars go by `hub-av` to each player who may see them. Words can name a player too: the shared `hud`
3913
+ avatars go by `hub-av` to each player who may see them; by the same rule
3914
+ (v1.183) the shared `hubSeated`, `hubEmotes` and `held` leave them out, and
3915
+ their seats, emotes and holds go by `hub-idle`, so nobody learns from them that
3916
+ a hidden partner is here or where they sit. Words can name a player too: the shared `hud`
3453
3917
  and `labels` carry no such player's username (it reads "someone") and no NPC
3454
3918
  line about them, and each player gets the words they may read by `hub-hud` and
3455
3919
  `hub-labels`, so nobody is sent a hidden partner's name, a late joiner's
@@ -3489,8 +3953,8 @@ sent other players' rows about 10 times a second (each its newest), its own
3489
3953
  only as a correction, and every row's id as a short number: `idm` (`[[n,
3490
3954
  playerId], ...]`) names each number the first time that client gets it, and
3491
3955
  `pi` (ms) says how far apart the rows are, which the client draws others
3492
- behind by. Everything else -- objects, `hubAv` (but for Blocks, above),
3493
- `hud`, `held`, labels, pads and `hub.go` -- is still everyone's: only
3956
+ behind by. Everything else -- objects, `hubAv` and `held` (but for Blocks, above),
3957
+ `hud`, labels, pads and `hub.go` -- is still everyone's: only
3494
3958
  drawing is filtered, and the server's simulation has every player. A
3495
3959
  session no bigger than the set is sent one broadcast, as before.
3496
3960
 
@@ -3587,6 +4051,44 @@ needs a pre-hello atomic mask still needs a separate snapshot or client gate
3587
4051
  contract. The option is server-only and adds no key to `hubPlace`; absent
3588
4052
  preserves the existing resume ordering, cleanup and bytes.
3589
4053
 
4054
+ ### Writer leases (v1.192)
4055
+
4056
+ Writer leases are opt-in with `hub.writerLease: true` (or `writerLease: true`
4057
+ on a named place). No deck opts in automatically. Each account claims its own
4058
+ empty user target, `hub:writer:`, once per instance; another instance's claim
4059
+ fences this one's later saves. Reset/undo also loses the writer, and so does a
4060
+ claim the platform refuses, or one still failing after 20 seconds. A lost
4061
+ account stays lost on a same-playerId resume, or while another connected visit
4062
+ of that account remains here. If a fresh connection has a new playerId and all
4063
+ other visits of its lost account are only retained, the kit first forgets those
4064
+ visits through ordinary leave cleanup (including the deck's `leave` hook), then
4065
+ joins the new visit and claims anew before its arrival hooks run. A place must
4066
+ reload the account's saves through `hub.saves` on that fresh arrival; `get`/`list`
4067
+ wait for the new claim. Once the kit has forgotten every visit, a visit back also
4068
+ claims anew.
4069
+ The last departure of a held account keeps the lease for 60 seconds for end
4070
+ saves. A host with no save API (`UNKNOWN_COMMAND`, or a non-retryable
4071
+ `CAULDRON_STORAGE_UNAVAILABLE`) saves as before, without a lease.
4072
+
4073
+ `hub.saves` exposes `enabled`, `deck(userId)`, `fence(userId)`, `ready(userId)`,
4074
+ `lost(userId)`, and `onLost(fn)` (called with the user ID; returns unsubscribe).
4075
+ `deck` returns the raw deck store by identity when disabled or when the host
4076
+ lacks root `claim`/`transaction`. Otherwise its `get`/`list` wait for the claim
4077
+ to commit or give up; `set`/`remove`/`increment`/`transaction`/`conditionalWrite`
4078
+ fence and run in account order. `user(userId)` provides the same wrapper for
4079
+ user-scoped writes. Places must use these views for their per-player writes;
4080
+ shared boards keep their ordinary stores. Root `session.storage` atomic calls
4081
+ are not wrapped and need an explicit `fence`.
4082
+ `hub.wallet` fences its own writes: a lost writer locks that account's wallet
4083
+ with nothing sent.
4084
+
4085
+ A lost writer rejects with `CAULDRON_STORAGE_WRITER_LOST`, invokes `onLost`,
4086
+ and shows a persistent personal HUD line: “You're playing somewhere else, so
4087
+ progress here isn't saved.” Repeated fences fail locally. The fence and the
4088
+ ordinary write are separate requests: a write already past its fence when
4089
+ another instance claims and loads can still land. This one-round-trip window
4090
+ remains; the lease does not make ordinary saves atomic.
4091
+
3590
4092
  ### Town pose retention (v1.98)
3591
4093
 
3592
4094
  A non-result place may set `hub.resumePose: true` (also valid on a named
@@ -3606,9 +4108,17 @@ optional `resume` hook restore its UI without a `leave` or `arrive`.
3606
4108
  At or after five minutes the old visit leaves once; a return then arrives afresh.
3607
4109
  A new player ID still arrives separately and runs the deck's arrival hook. With server deck storage available, its first hello waits for a server-owned pose record keyed by user ID, place, and house owner (if any). A record from an ended visit is consumed only for strictly less than **ten wall-clock minutes** after departure. The full position (including depth) and facing replace normal arrival placement after the hook and before the next deck step, with the usual settling period. The arrival hook rebuilds private UI, including a house's fixed shot. Anonymous players and unpublished sessions without deck storage keep the normal new-ID arrival path. Explicit kit travel clears the stored pose before that socket leaves; a later genuine door return arrives normally.
3608
4110
  Explicit kit travel bypasses retention, and shutdown drains each retained visit
3609
- once. As with result-place retention, unexplained departures, including Back or
3610
- closed tabs, may delay `leave` until expiry because the transport supplies no
3611
- close reason. Absent bodies are not in `hub.players()` and cannot interact.
4111
+ once. As with result-place retention, unexplained departures, such as closed
4112
+ tabs or a client that predates v1.173, may delay `leave` until expiry because
4113
+ the transport supplies no close reason. v1.173: the player's own Back says so
4114
+ first (`{ k: 'hub-back' }`), which only arms a mark for that player (35 s, the
4115
+ SDK's 30 s `Hub.back` timeout and slack; a repeat restarts it). When the kit
4116
+ next sees that connection gone while the mark is fresh, it lets the visit go
4117
+ as kit travel does before anything is kept: no retention at the drop, no
4118
+ arrival pose, the stored pose cleared, so the next entry under the same
4119
+ account (same or new player id) is a fresh arrival. A Back that fails (the
4120
+ player still here when the mark goes stale) changes nothing, and a drop with
4121
+ no fresh mark is resumed as before. Absent bodies are not in `hub.players()` and cannot interact.
3612
4122
  (v1.145) While such a visit is retained for a signed-in player, the kit also
3613
4123
  keeps their private visibility (`hide`/`show` with `to`) and companion, as it
3614
4124
  keeps their HUD and labels: calls naming them meanwhile are taken (and return
@@ -3657,6 +4167,47 @@ with no old private mask replay. This server-only key accepts only `true` or
3657
4167
  absence, adds no public manifest or wire field, and allocates no pose cache when
3658
4168
  absent. Existing modes and absent-key wire bytes are unchanged.
3659
4169
 
4170
+ ### Held offers (v1.180)
4171
+
4172
+ A place with a resume mode may set `hub.heldOffers: true` (also valid on a
4173
+ named place). The resume modes are `resume: { keep: true }`, `resumePose`,
4174
+ `houseResume`, and the reconnect window a host pins on a place without a
4175
+ result; the key does nothing in a session where none of them is in force.
4176
+
4177
+ With it, the place's `hub.actions` chips, `hub.ask` prompt and `hub.menu`
4178
+ sheet for a retained player are kept while that player is away, rather than
4179
+ pruned at the drop. Calls the place makes for them meanwhile return true and
4180
+ are recorded, not sent; the tick sends nothing to them while away. On the
4181
+ player's resume hello (their own fresh hello, or the kit's silent one for a
4182
+ same-connection return) each channel replays its latest offer under a fresh
4183
+ version, so a press, answer or pick on a version sent before the drop is
4184
+ refused. No press, answer or pick is admitted for a held offer before that
4185
+ hello, whatever arrives on the connection first.
4186
+
4187
+ An offer is recorded, sent or pressed only under the id's hold: the
4188
+ signed-in, non-anonymous account on it when the offer was made and the body
4189
+ generation it is shown on. It is sent or pressed only while that account is on
4190
+ the roster row and on that body, with nothing interrupting them since the last
4191
+ replay. Any interruption (the row gone, the body gone, or the body replaced,
4192
+ with or without a tick that saw it away) holds the offers: calls are
4193
+ recorded, nothing is sent or pressed, until a fresh hello (`again: true` is
4194
+ not one) finds the account back on the body the kit took for it; that hello
4195
+ replays every offer under a fresh version. A replaced body never ends the
4196
+ hold by itself; the kit's retained-visit return decides (it takes the body,
4197
+ or the visit expires). The kit checks this on every call, press, answer and
4198
+ pick, every tick and every replay. Anyone else on that id's roster row or
4199
+ visit, with or without a body (another account, a guest, an anonymous
4200
+ identity), ends the hold and drops every offer made under it with no replay,
4201
+ and the id then records, sends and admits nothing on any of the three
4202
+ channels (calls return false) until a fresh hello from whoever is on the row;
4203
+ after it, their own offers start afresh and a later return of the original
4204
+ account finds nothing. The visit ending or expiring ends the hold too. Guests
4205
+ and anonymous players are never held; their offers follow the ordinary rules.
4206
+
4207
+ The key is server-only: no `hubPlace` key and no new wire field. Absent, offers
4208
+ are pruned while disconnected and a place re-offers from its resume hook, with
4209
+ identical behaviour and bytes.
4210
+
3660
4211
  ### A deck's retained-hello signal (v1.89)
3661
4212
 
3662
4213
  A deck may export `resume(hub, { playerId })` alongside its other hooks. Hook
@@ -3937,7 +4488,11 @@ that kit greeting and ignores deck opening text, late `hub-npc-opening`,
3937
4488
  `hub-npc-line` and notes messages. No scripted line is sent to that child.
3938
4489
  The panel shows all 3-4 chips with the reply area and no text box or "or try:"
3939
4490
  caption; typing being off does not remove these object chips. A successful
3940
- inspect still gates sends. A tap displays the label and sends exactly
4491
+ inspect still gates sends: v1.153, until then the panel shows the three
4492
+ canned lines ("What can I do here?", "Tell me about yourself.", "Where should
4493
+ I go next?") in their place, sent by `hub-npc-say` and answered by the place
4494
+ through `npcLine` `why: 'authored'` (the kit's refused line, "<name> smiles and
4495
+ nods.", when the place has none), never a mind turn; they may be asked again. A tap displays the label and sends exactly
3941
4496
  `choice:<id>`, with no notes prefix. Admission checks the raw token against
3942
4497
  that character's `childAsks`, including on replay, and rejects anything else
3943
4498
  with `HUB_NPC_CHOICE_REQUIRED`. Model suggestions are ignored; the authored
@@ -3963,8 +4518,9 @@ of that open's asks from that speaker and answers it through `npcLine` with
3963
4518
  `why: 'authored'`, as for a body with no mind. No model or ghost turn is
3964
4519
  involved, and the kit refuses that speaker's mind turns on this open with
3965
4520
  `HUB_NPC_CHOICE_REQUIRED`. After the place answers, the chips clear; the next
3966
- open brings the place's next asks. Over 13s and unknown ages are unchanged.
3967
- This is how a first-visit welcome's own choices reach a child.
4521
+ open brings the place's next asks. Over 13s and unknown ages are unchanged,
4522
+ except that v1.175 lets them tap the same asks while their inspect is pending
4523
+ or refused (below). This is how a first-visit welcome's own choices reach a child.
3968
4524
 
3969
4525
  **Opening a chat (v1.37, v1.46).** The place's `npcOpening` gives the first
3970
4526
  words and up to three questions, with up to nine more to offer later. A hook
@@ -4057,8 +4613,14 @@ added.
4057
4613
 
4058
4614
  For a mind, the client reads `inspect` when the Chat prompt first shows
4059
4615
  (v1.47), before the panel opens. Pending reads are shared; a success is
4060
- remembered on that net. While it is pending, or if ghost refuses it, only the
4061
- opening is shown: no text box or chips. The tap-only bundle flow above
4616
+ remembered on that net. While it is pending, or if ghost refuses it, no text
4617
+ box is shown, and no chips except the place's own: v1.175, where `npcOpening`
4618
+ returned `authored: true`, a speaker without v1.148 authored taps gets the
4619
+ opening's `asks` as tap-only chips, answered by the place through `npcLine`
4620
+ `why: 'authored'` exactly as v1.148 taps are (`hub-npc-say`, no model or ghost
4621
+ turn); an answered ask leaves the row and the rest stay. Without an authored
4622
+ opening only the opening is shown. Once an inspect succeeds the text box
4623
+ appears and the asks are mind turns as before. The tap-only bundle flow above
4062
4624
  (v1.142) supplies its fixed greeting and authored chips after a successful inspect. A
4063
4625
  speaker the server marks `ageOff` (§12: trusted `under13 === true`; the
4064
4626
  client infers no age) refused it also reads one muted plain line under the
@@ -4242,6 +4804,23 @@ An unsaved local dev deck has no platform storage, so
4242
4804
  its hello does not open a playthrough. `hub.progressPending(userId)` tells a
4243
4805
  place whether that account's marker read or reset hook is still gating private
4244
4806
  progress; with no argument it reports whether any connected player is gated.
4807
+ v1.195: `hub.resetFences(playerIds)` returns the `resetFences` for a
4808
+ `session.storage.conditionalWrite` (sdk README) touching one or two players
4809
+ here: `[{ playerId, resetGeneration }]`, `playerId` the numeric Castle account
4810
+ id, one entry per account (two ids of one account give one fence), each from
4811
+ the marker `hub.progressGeneration` reports. It returns null for anything else:
4812
+ not a list of one or two, a player not here, a guest or anonymous player, or
4813
+ an account with no observed marker (before the first successful read, after a
4814
+ failed one, an unsaved deck). A place given null decides for itself whether to
4815
+ write; the kit never stamps a guessed 0. A reset that commits first refuses
4816
+ the write with `CAULDRON_STORAGE_STALE_RESET_GENERATION` (`committed: false`);
4817
+ the place drops that write, does not retry it as an ordinary write, and calls
4818
+ `hub.refreshProgress(playerId)`, which runs `progressReset` as above. Fences
4819
+ ride only on conditional writes: they need managed targets and a deck with
4820
+ conditional storage enabled, and plain Store writes are never fenced. Older
4821
+ kits have no `hub.resetFences` (feature-check `typeof`); a deck without
4822
+ conditional storage answers the write unsupported; host agents forward the
4823
+ field to Ghost, which enforces it. No wire or manifest change.
4245
4824
  A higher marker clears the kit's per-player progress
4246
4825
  view and calls the optional `progressReset(hub, playerId, resetGeneration,
4247
4826
  { arrived })` server hook for each connected id of that account. The hook may
@@ -4291,15 +4870,118 @@ What the kit and Castle promise, and what they do not:
4291
4870
  `shutdown` gives a stopping session a few seconds to finish its writes; but a
4292
4871
  host that fails sends neither. Write every few seconds, one write per account
4293
4872
  at a time, each carrying the whole save.
4294
- - **Two visits can hold the same account** (two tabs, a late door), and deck
4295
- storage has no compare-and-set: the last write wins. A place that must not
4296
- lose progress to an older visit writes a counter it only ever raises and
4297
- refuses to load over a newer one it has seen; a revision check in Castle's
4298
- storage is filed as a platform gap.
4873
+ - **Two visits can hold the same account** (two tabs, a late door), and an
4874
+ ordinary deck `set` is last-write-wins. A place that must not lose progress
4875
+ to an older visit either writes a counter it only ever raises and refuses to
4876
+ load over a newer one it has seen, or keeps that progress on the SDK's
4877
+ conditional storage (`snapshot` + `conditionalWrite`, gated per deck; see
4878
+ sdk/README.md "Conditional writes and recovery"), whose revision check
4879
+ refuses a write built on an older read. Coins have that already:
4880
+ `hub.wallet` below.
4299
4881
  - **The dev serve:** guests (`dev-guest-<n>`) have storage only once the deck
4300
4882
  has been saved, and every serve reuses those subjects, so dev guests share
4301
4883
  their saves across runs; test persistence as the author, or clear the keys.
4302
4884
 
4885
+ ### The Town's day (v1.200)
4886
+
4887
+ The Town turns its day at midnight in America/Los_Angeles (hub-town `daily.js`).
4888
+ `hub.townDay(nowMs?)` returns that day as a number: the LA calendar date counted
4889
+ in days since 1970-01-01, the same scale as `Math.floor(ms / 86400000)`, so
4890
+ weekday (`new Date(day * 86400000).getUTCDay()`) and week arithmetic over day
4891
+ numbers keeps working and names the LA weekday. `nowMs` defaults to `Date.now()`;
4892
+ a time that is not a finite number, or whose LA date falls outside the Date range, gives NaN. `hub.townDayStart(day)` returns the
4893
+ epoch milliseconds at which that day begins, 07:00 or 08:00 UTC, for a
4894
+ "Tomorrow:" line or a countdown; NaN for a day that is not an integer or is 1e8 or more from day 0.
4895
+ A game that keeps its dailies, streaks or day-keyed storage on this day turns with
4896
+ the Town instead of at 00:00 UTC.
4897
+
4898
+ A game switching from UTC day numbers reads every stored day through
4899
+ `hub.townDayFrom(storedDay, nowMs?)`: a day after today (a UTC day that had
4900
+ already turned when it was written) becomes today, so a streak neither breaks nor
4901
+ counts twice, and a day of yesterday keeps a streak through the game's own rule.
4902
+ A stored day equal to today is today: a last play yesterday after 17:00 PT keeps
4903
+ the streak but that day's daily is not claimed again. Days written on the Town's
4904
+ day are never after today, so the clamp is safe on every read and needs no
4905
+ marker. Values that are not integers pass through unchanged.
4906
+
4907
+ No manifest key, wire field or host call. A deck pinned to an older kit has none
4908
+ of the three; a game written for both calls `hub.townDay?.()` and falls back to
4909
+ its UTC day. A runtime whose `Intl` has no zone data gives the UTC day, as
4910
+ `daily.js` does.
4911
+
4912
+ ### Coins: `hub.wallet` (v1.185)
4913
+
4914
+ A deck that declares `hub.wallet: { name, start? }` (§1) gets
4915
+ `hub.wallet.read/spend/earn/seed` (§4): one wallet per signed-in account kept
4916
+ on the SDK's gated conditional storage, so a purchase made in one room cannot
4917
+ be erased by another room's stale whole-save write.
4918
+
4919
+ - **Storage.** A deck target with its own prefix
4920
+ `wallet:<name>:<userId>:`, holding one key `wallet:<name>:<userId>:state`
4921
+ whose value is `{ v: 1, gen, coins, owned: [itemId], data: {} }`, `gen` the
4922
+ account's reset generation the row was written under. The wallet is
4923
+ the only writer of that prefix; ordinary `set` on it is refused by the
4924
+ platform anyway (`CAULDRON_STORAGE_MANAGED_TARGET`).
4925
+ - **Reads.** The account's reset generation, then a snapshot of the target,
4926
+ then the generation again (a reset between them reads again). `read` always
4927
+ reads fresh; `spend`/`earn` start from the last read or write. `read` is
4928
+ also null while a write's outcome is still unknown (see Lost replies): no
4929
+ balance is true until it settles.
4930
+ - **Writes.** Each `spend`/`earn`/`seed` is one operation, never a whole-save
4931
+ set: a `conditionalWrite` naming the snapshot's access, the target's
4932
+ revision and a reset fence with the generation read before that snapshot,
4933
+ under a fresh operation id. An account's operations run one at a time on
4934
+ each server (at most 16 waiting, past that `'busy'` at once), through the
4935
+ kit's storage queue.
4936
+ - **Conflicts.** A revision conflict means another server wrote first: the
4937
+ stored wallet (the conflict's `current`, else a fresh read) is adopted and
4938
+ the same operation applied once more against it, so a spend that is still
4939
+ short reports `'short'`, an item bought meanwhile `'owned'`. A second
4940
+ conflict in the same call reports `'busy'` with the stored wallet adopted.
4941
+ - **Resets.** A progress reset does not delete a door deck's rows (the
4942
+ platform clears deck scope only for a town's and the House's own keys), so
4943
+ a row whose `gen` is older than the account's generation reads as no
4944
+ wallet: `start` coins, nothing owned, and `seed` allowed again. A stale
4945
+ reset generation (or stale access) on a write drops the cache and reads
4946
+ again; that call reports `'busy'`, since what it was spending is gone. A
4947
+ write still on the wire across a reset is refused by its fence, so it cannot
4948
+ bring the old wallet back. The kit also drops an account's cache on
4949
+ `progressReset`, and a call made before that reset -- one still queued, or
4950
+ one waiting on a conflict's reply -- never runs after it: it reports
4951
+ `'busy'` rather than being applied to the reset wallet. More generally, every
4952
+ call is bound to one reset generation when it is made (the newest any read
4953
+ of that account had seen, else the first one a read sees after it, even
4954
+ inside a first load that retries across a reset) and answers `'busy'`
4955
+ without writing rather than write under any other.
4956
+ - **Lost replies.** A write whose outcome is unknown (a transport error, or a
4957
+ retryable refusal) is looked up with `operation(id)` and otherwise sent
4958
+ again with the identical request (same id and bytes), which returns the
4959
+ original receipt if it committed: up to three times, then `'busy'`, and the
4960
+ same bytes go first on the account's next call; until they settle `read` is
4961
+ null. A recovered receipt is
4962
+ trusted only while the account's generation is unchanged.
4963
+ - **Load before write.** A failed read or a row this kit cannot read (bad
4964
+ JSON, a newer `v`) locks that account's wallet on this server for the visit:
4965
+ `read` is null and every change `'locked'`; it is never overwritten. A
4966
+ progress reset, or the account leaving and coming back, reads again.
4967
+ - **The gate.** Conditional storage is off by default, per deck; enabling it
4968
+ (the admin deck flag `cauldronStorageConditionalWritesEnabled`) is an admin
4969
+ action. Until then, on an older host, and on `castle-web serve` (no
4970
+ `resetGeneration`, and its memory store refuses `conditionalWrite`), the
4971
+ wallet asks `recentOperations` once, finds it unavailable, and every
4972
+ signed-in wallet is locked: `read` null, `spend`/`earn`/`seed` `'locked'`.
4973
+ There is never a fallback to ordinary writes. Anonymous players and dev
4974
+ guests keep a session-only wallet either way, starting at `start`; test
4975
+ buying on the serve as a dev guest, and saving on a QA copy with the flag on.
4976
+ - **Moving a game onto it.** A game that kept coins in its own whole save
4977
+ moves them off at its own next save: on arrival call `seed(playerId,
4978
+ { coins, owned })` from the old save (a second seed, from any room, answers
4979
+ `'seeded'` and changes nothing), then stop writing coins and purchases in the
4980
+ whole save and read them from `hub.wallet`. Seed before the first
4981
+ `spend`/`earn`, which create a fresh wallet at `start`. After a progress
4982
+ reset the game's `progressReset` hook must clear its own old coins before a
4983
+ later arrival seeds again, since `seed` is open once more.
4984
+
4303
4985
  ## Changes from M0
4304
4986
 
4305
4987
  | M0 gap | v1 |
@@ -4589,11 +5271,108 @@ shorter body does not reject every nearby spot. Ground-backed town and game
4589
5271
  placement keeps its existing clearance; walls, unsupported spots, blocks and pads
4590
5272
  still exclude an arrival.
4591
5273
 
5274
+ ### v1.189: push visit end (optional)
5275
+
5276
+ For a place declaring `hub.push: { version: 1 }` on a capable runtime,
5277
+ `hub.push.visit(playerId, { userId, timezone, phase? })` reports visit facts.
5278
+ Absent `phase` starts a visit exactly as before; its only optional value is
5279
+ `"end"`. The place server remembers the authenticated `userId` and `timezone`
5280
+ per player only after the start answers `true`, keeping the live roster identity
5281
+ check. It sends an end once from `leave` (at forget for a retained resume player,
5282
+ not at backgrounding), and for every remembered player at layer shutdown, then
5283
+ clears the remembered entry. Without an accepted start it sends nothing.
5284
+ Calls are fire-and-forget: catch errors, ignore `false`, never retry.
5285
+
5286
+ Ghost keeps the latest end per user, place and join generation; an end older than
5287
+ the start or from an old generation is dropped. An old host-agent or Ghost
5288
+ answers `false` for an end and Ghost derives from the start. The acknowledgement
5289
+ remains `accepted === true`; the start path is unchanged. Landing order: Ghost
5290
+ first, then the host-agent, then the deck save. Within `hub.contract: 1`.
5291
+
4592
5292
  Minor additions are optional unless their entry says they apply to every deck;
4593
5293
  a deck written before them remains valid.
4594
5294
 
4595
5295
  | date | change |
4596
5296
  | --- | --- |
5297
+ | 2026-11-10 | `hub.loadingCover` copy and timing: a return's cover (backgrounded 30 s or more, or a dropped connection, after the first load lifted) is plain black, with no title, words or spinner, while hidden and for its first 2.5 s after the page shows; then it says "Reconnecting…" with the spinner. The first load keeps the deck title. The multiplayer-3d kit's return cover is quiet for the same 2.5 s. Most returns are back sooner (measured 2.1-2.4 s past a 180 s app switch). No wire change. Within `hub.contract: 1`. |
5298
+ | 2026-11-10 | Kit-internal, no deck-facing key or API: a connection that comes back under a new player id on the same page (a drop past the place's hold, such as 180 s backgrounded) keeps the camera yaw and the avatar's facing through the new session's `hub-arrived`, instead of turning to the arrival facing (the Town turned every such return to its spawn bearing). A trip's arrival, the first join and an arrival on another connection face as before. Within `hub.contract: 1`. |
5299
+ | 2026-11-05 | Kit-internal, no deck-facing key or API: a frame stall is not an away (amends v1.169's rule). The multiplayer resume gate also arms on frames that stopped for over 1 s on a visible page with the socket connected, as a low-memory phone's do while it loads a place. A `hub-go` or tagged `hub-end` met under such a gate now counts as met online, and the trip or end goes as it always did. It still counts as met while away when the connection dropped during the away, the transport is not connected, the page is or was hidden since the away began, or the away has lasted 5 s (`STALL_AWAY_MS`, the multiplayer kit's own line between a frame hitch and an away). The first room split's `hub.go(nux)`, sent about 4 s after the join inside the loading window, was dropped on such phones as 'fired while offline', and the Town's 45 s wait then kept the player in the Town (repro on a moto e22, Nov 5). Limit: an app switch under 5 s on a page that fires no `visibilitychange` and keeps its socket counts as online. Within `hub.contract: 1`. |
5300
+ | 2026-11-02 (v1.208) | Kit-internal, no deck-facing key or API: join-retry fences, ownership check and send in one tick; a recovery never supersedes a newer join (05b4565ff..22206ac0a, on top of v1.207). Closes v1.207's limits A and B: `Hub.go`/`Hub.jump` check the Hub acquisition generation after the `forbidden` roster pause, so an older call that a newer go/back/jump overtook answers `cancelled` and asks no more; every `Multiplayer` connection keeps the join attempt that created it, and every acquisition ask (the first, a transport re-ask, a recovery's re-acquisition) goes through one gate that checks the connection is open and owns the newest attempt and sends in the same synchronous step. A connection that does not own the newest attempt neither asks nor closes: it waits until the newer join settles, then stops if that join replaced it or goes on if it was handed back (a destination join that ends without replacing it hands its attempt back). A `Multiplayer.join` overtaken while the old connection leaves rejects `MULTIPLAYER_CONNECTION_CLOSED`, and a `joinDestination` overtaken the same way answers `cancelled`. Limits: tested only against a mocked host bridge and fake sockets; a connection waits without a deadline while a newer destination join's consent sheet is open; a destination join that was itself overtaken hands nothing back. Ships in a later save than v1.207. Within `hub.contract: 1`. |
5301
+ | 2026-11-02 (v1.207) | Kit-internal, no deck-facing key or API: the base kit's SDK asks a join-path host request again when it fails in transit with `CASTLE_HOST_ERROR` (the host could not read the API's reply, e.g. a load balancer 502 while app servers are replaced): `Hub.go`, `Hub.back`, `Hub.jump`, `Multiplayer.join`'s `multiplayer.getSession` (and a recovery's re-acquisition) and `Multiplayer.joinDestination`. It waits `HOST_TRANSPORT_RETRY_MS` = 1, 2, 4, 8 s between asks (five asks, about 15 s of waiting), with one console warning per retry; the last failure is rethrown once the schedule is spent. `Hub.cancel` ends a `Hub.go`/`back`/`jump` wait at once with the usual `cancelled` result, and a newer go/back/jump makes an older one ask no more and answer `cancelled`; a newer `Multiplayer.joinDestination` (or a cancel) ends a destination join's wait with `cancelled`, and any newer `Multiplayer.join`/`joinDestination` stops an older join's retries after its current wait. Not retried: every code ghost answered (`FORBIDDEN`, `LOGIN_REQUIRED`, destination refusals, ...), `CASTLE_HOST_UNAVAILABLE` (the deck's own timeout or no host), any other command; `hub.commit` keeps its own retry. Ghost supersedes a repeated pending acquisition, so asking again is safe. A destination retry only helps hosts that pass the transport error through; castle-www's destination host maps it to `unavailable`. The kit's door content deadline (`LOADING_LIMIT_MS`, 15 s from the ask) can end a trip before the last ask. Stated limits of this version: (A) after a `forbidden` answer, `Hub.go`/`Hub.jump`'s roster pause does not check for a newer go/back/jump, so an older call can ask again after a newer trip began and supersede it; (B) a connection's recovery that re-acquires while a newer `Multiplayer.joinDestination` is pending takes that newer join's generation, so its retries can supersede the destination acquisition. A later change fences both. A deck whose base kit predates it fails on the first error as before. Within `hub.contract: 1`. |
5302
+ | 2026-11-02 (v1.206) | Town purse book: the Town deck's scope gains `tokens:<userId>:book`, the one row of a managed save target per player (deck scope, prefix `tokens:<userId>:`; the trailing colon keeps it off `tokens:<userId>` and every other account's keys): `{ v: 1, total, days: { <YYYY-MM-DD>: { paid: { <claim id>: tokens }, game } } }`. `total` is every token paid through the book, ever (only raised); `paid` is each claim credited that day with what it was granted (the dedup set); `game` is the day's game tokens granted, the daily cap (hub-town `tokens.js` T4, T10). Every recurring payment (game results, door visits, stamps, lanterns, the day's bonuses, gifts, jobs, trades, voyages) whose `earn:` claim answered 1 is credited by a snapshot and one transaction at that revision, so a lost answer is settled by reading again and every failure is retried while its day is payable; days of three days back or more are pruned from `days` (their tokens stay in `total`). A balance is `tokens:<userId>` plus every `paid:` ledger row plus the book's `total`, less hat prices and `spent:<userId>`; the Town's wardrobe reads the row by snapshot, the House's `chirpPurchases` funds by key (`tokens` is already in `HUB_TOWN_PLAYER_NAMESPACES`, and a raw get of a managed row is allowed). Compatibility: the claims are unchanged; deck storage without `snapshot`/`transaction` keeps the old increments of `tokens:<userId>` and `earn:<userId>:<day>:cap`; an absent row adds nothing; an older Town or House reader shows a lower balance, never a higher one; while an older Town layer runs beside a newer one each keeps its own cap count, so a player can be paid up to the cap twice in a day. Ghost's hub user reset and deck progress reset clear the row and its target (Ghost adds `tokens:<userId>:` to the reset prefixes, which lands before the Town save that ships the book); no manifest key, wire field or SDK change. |
5303
+ | 2026-10-31 | NPC Talk: a `hub-npc-open` from a player who stood within the body's `talkRange` of where a walking body was at any time in the last 1.5 s is answered as an open, though the body has since walked out of range (it was refused `why: 'far'`). Such a conversation admits turns within the distance it opened at plus 1 m, rather than `talkRange` plus 1 m. A body standing still, and a press from a player never in range of it, are unchanged. The place's `npcOpening` hook runs as for any open, so a place that walks the body decides whether it stops. No manifest or wire change. Within `hub.contract: 1`. |
5304
+ | 2026-10-30 (v1.205) | §7 server-only `hub.celebrate(playerId, { kind: "win", door, tokens, streak?, unlock? })` on the Town root (capability: the optional method). Sends `celebrate` only to connected players within 25 m, excluding hidden pairs. Tokens clamp to 0..40, streak is 3 or 5 or absent, door and unlock must be declared. Verified participating wins remain eligible at the daily token cap: tokens 0 shows `won <door label>` without `+0` and keeps the burst outside Low. One per layer per 4 s, three queued, oldest dropped; six per account per LA day through an atomic deck counter, including reconnects and concurrent layers. Clients draw one pooled 2.5 s coin burst (skipped on Low), a token chime and a 20 s public ribbon over the winner; the winner keeps the existing 60 s private ribbon. No call = byte-identical snapshots, deltas and messages; older clients ignore the new message. No manifest key or native host mirror change. Within `hub.contract: 1`. |
5305
+ | 2026-10-30 | Town purse: the win bonus is 10 (game 5, first door of the day 10, game cap 80/day unchanged). A signed-in account arriving where TownHatMat enables tokens receives 20 once, outside the cap, through `paid:<userId>:welcome`; `welcome` joins the fixed v1.193 PAID ids in Town and House reads. The cheapest Stadium, Hollow, Sunny and Harbour hats cost 20; all other tiers stay unchanged and owned hats use the lowered prices. Five fixed §11 deeds fill the remaining wearable slots: `stadium-pin`, `hollow-pin`, `sunny-pin`, `harbour-pin` on the first participating win in that district, and `town-champ` at ten distinct doors. Server-read results only (`stats.played > 0`), no purchase, randomness or trade; independent idempotent `earn:<userId>:wins:door:<doorId>` and `earn:<userId>:wins:district:<districtId>` markers keep wins durable across concurrent layers, bounded to one per authored Town door and four districts. Sash reads count at most ten distinct door markers; the old `earn:<userId>:wins` record is preserved and copied into markers without a migration. Grants retry refusal and require unlocksOf ownership readback. `scripts/town_win_items.py` writes the declarations when generating a scene with TownHatMat. No kit wire or manifest schema change. |
5306
+ | 2026-10-27 | `hub.analytics` in a place without `result`: `hub.end` for a player reports that visit's `session_end` (kind 11, and `house_time` in a House) at the end, while the player is still connected, with the connected time up to then and result 0 (2 for a continuation). The drop and leave that follow report nothing more; a v1.169 stay after it starts a continuation (result 2). The way back can keep the ended connection open for minutes, and a one-player place's report after the drop never landed: the first room logged no `session_end` from Oct 21, when its way out moved from `hub.go` to `hub.end`. Result places, trips and drops report as before. No key, no wire field. Within `hub.contract: 1`. |
5307
+ | 2026-10-26 | Without `hub.safeInsets`, a portrait view too short for the corner column (a game on castle.xyz in a short desktop window, 219x290) no longer stacks Quick chat and Emote onto Sound and the native corner: Character, Grab, Emote and Quick chat take the landscape rail's wrapping columns under the ceiling at their portrait sizes, and Emote's row and the Quick chat card open beside their button. A taller portrait view is laid out as before. No manifest or wire change. Within `hub.contract: 1`. |
5308
+ | 2026-10-26 | Layout in small views and town labels. The HUD no longer lies under the right-edge controls (Quick chat, Emote, Grab, Sound) of a small view such as a game in a short desktop window (179x250): where the centred HUD would cover one it is laid out in the lane left of them (beside a Back at the top, or under the host's corner with `hub.safeInsets`), its big line fitted to that lane on one line where it can; a lane under 72 px leaves it centred. With `hub.safeInsets`, the caption family keeps inside the box its stage clips it to (a standalone page's inset card) rather than taking a row below it, and a centred caption whose words are clear but whose box spans a control is narrowed to its words. In a town, a plate behind the player (one walked past, by the player's facing) counts 4 m further when the plate is chosen, so walking past one statue to the next shows the next one's plate. A plate or sign label whose anchor is on screen slides onto the screen instead of being dropped at the edge, and one over the player's own avatar steps just above or beside it; a control under it still drops it and speech lines keep the old rule. No manifest or wire change. Within `hub.contract: 1`. |
5309
+ | 2026-10-28 | `hub.weakestTier`: a game reached through a door keeps the Weakest or Middle profile's capped renderer and composer pixel ratios instead of returning to the device ratio; the town's sleeping actors and model files are still restored at the trip, and High puts the buffers back. Measured on a moto e22 (PowerVR GE8320, auto Weakest) in two production door games: at ratio 1.75 Night Keeper ran 22.9-24.5 fps and Prize Pier 16.9-18.1; at 0.5, 27.5-29.2 and 17.9-19.9. No key, no wire field. Within `hub.contract: 1`. |
5310
+ | 2026-10-30 (v1.204) | Kit-internal, no deck-facing key or API: while the server reads an arrived player's progress (a reset check), it sends that player `{ k: 'hub-progress', catching: true }` at once and `{ k: 'hub-progress', catching: false }` when the read or reset settles. The kit's client refuses a press of Act, the place's menu, text ask or action rail with a line instead of sending it, and after 250 ms dims those controls (Act reads "Catching up"); Jump and movement are untouched. The server keeps refusing anything that could write progress, the place's own messages included, but now hears the kit's own progress-free messages (chat, party, emotes, seats, travel, where, unstick) during the read, and retries a reset hook that threw on the read's cadence. A client that predates it ignores the message. Within `hub.contract: 1`. |
5311
+ | 2026-10-26 (v1.202) | §1 `tiers`: auto Low measures a render resolution step. A device the judge put on Low whose next 10 s Low window still has a median over 40 ms gets the world renderer's and composer's pixel ratio halved (never under 1) for one more window; the lower ratio stays only if that window's median is at most 0.8x the slow one, otherwise both ratios are put back and the visit never tries again. A trial is dropped (ratio put back, baseline measured again) when a frame stops counting (a trip, a scene swap, the page hidden), the scene data changes, or the world is replaced. The outcome is stored on the device's low mark (`castle.hub.tier`: `{ tier: 'low', at, scale: 'kept' \| 'refused' }`), so a later visit within the week applies a kept ratio at once or never tries; a mark without `scale` behaves as before. Leaving Low (High by hand) or a manual pick puts back exactly the ratios it set, unless something else changed them since. Measured: an iPad 7th gen is fill-bound (14 fps at ratio 2, 23 at 1), where the Android phones Low was tuned on are CPU-bound (2-9% at ratio 1). Never with `weakestTier` (its own resolution rule). Only the WebGL canvas changes: the HUD and world labels are DOM and stay at full sharpness; name tags are sprites drawn in the canvas and soften with it. `__hub.tier.scale` reports the state. No manifest key or wire change. Within `hub.contract: 1`. |
5312
+ | 2026-10-26 (v1.201) | §10 private goals accept `at: "self"` with an optional `rise` (0..4 m) when the kit advertises `hub.goalSelf`: each recipient's client draws the goal over its own predicted avatar, so a "You" marker in a tight group never sits on a neighbour. Sent once in the recipient's label override; no actor, pose or shared field. Absent = goals byte-identical. An older kit drops the string `at` and points at the actor, so callers gate on `hub.goalSelf` and keep the v1.128 position path. Within `hub.contract: 1`. |
5313
+ | 2026-10-26 (v1.200) | §14 The Town's day: `hub.townDay(nowMs?)`, `hub.townDayStart(day)` and `hub.townDayFrom(storedDay, nowMs?)` give a game the Town's day (America/Los_Angeles midnight, hub-town `daily.js`) as a day number on the UTC day-number scale, the epoch ms it begins, and the switch-day clamp of a stored UTC day number (a day after today reads as today, so a streak neither breaks nor doubles). Absent = the game keeps its own day; no manifest key, wire field or host call. Older kits lack the methods (`hub.townDay?.()` falls back); a runtime without zone data gives the UTC day. Within `hub.contract: 1`. |
5314
+ | 2026-10-26 (v1.199) | §1 optional place key `resumeWindowSec` (integer 1-180, only on a place without `result`; refused with `resumePose`, `houseResume` or `resumeArrivalPose`). Ghost pins it as `spec.hub.reconnectWindowMs` on a host advertising `supportsHubReconnectGrace`, and the kit's pinned retention keeps the dropped visit and pose through it ("Door resume window"). Absent key, older Ghost or older host: unchanged behaviour and bytes. Server-only. Within `hub.contract: 1`. |
5315
+ | 2026-10-26 (v1.198) | The kit's screen UI tree (`code/client/uiTree.js`), one opt-in node type, no deck-facing key: `slider`, a leaf with `value`, `min` (default 0), `max` (1), `step` (0, continuous), `disabled` (false) and `tint` (a token or CSS colour, default `'gold'`); its value is clamped to [min, max]. Events: `input` `{ value }` on each move while dragged, `release` `{ value }` when let go; while the player holds it a renderer keeps the player's value, not a resent one. `uiDom.js` draws it as a range input with the sound card's look. New root `sound` (`soundTree.js`, `soundSurface.js`): the speaker button and the card with Mute and the volume slider, for a native host (the web chrome still draws its own). Trees without a slider serialize to identical bytes; an older native renderer drops the unknown type, so the card there shows Mute only. |
5316
+ | 2026-10-26 (v1.197) | `hub.quality` Low: the spawned-copy cap (`quality.low.spawned`) also holds in a game reached through the Town's door, under the Town's quality block. A game's scene actor marked `"decor": true` (Transform/Shape/Model only) is a decorative spawn template; a game server with no `hub.quality` of its own sends the ids of such templates with live copies in a new latched field `hubDecorTpl` (only once one has a copy, `[]` after the last), and a Low client under a Town with `hub.quality` counts their copies against the Town's cap, nearest first, as in the Town. No new key. Absent (no Town quality, a High client, or no decor template) = every copy built as before; a scene without decor marks sends identical bytes. An older client ignores `hubDecorTpl` and draws every copy. Authors: mark decorative spawn templates `"decor": true` and hide the template at `ready`; gameplay templates never. Within `hub.contract: 1`. |
5317
+ | 2026-10-25 (v1.196) | §11 `hub.disguise(playerId, { look?, to? } \| null)` / `hub.disguised(playerId)`: a visit-only per-player disguise. A scene Model replaces the avatar and hides its tags and decorations for selected viewers (default: everyone else); the player sees their own look with other decorations unchanged. Without look, hide only name, mark and role tags. Refused for drivers/riders, held, absent or departing players and invalid shapes; drive/ride refuse disguised players. Leave, trip, end, forget and account changes clear it; retained resume keeps it. Latched `hubDisguise` rows coalesce per player at 250 ms; never-called places keep identical bytes. Old and native hosts draw the real avatar/tag; deck-made naming UI remains the deck's job. Within `hub.contract: 1`. |
5318
+ | 2026-10-26 | `hub.weakestTier`: on Weakest and Middle, a sleeping actor's shared model build is kept and waking reuses it, so returning to a district does not rebuild its models. After a fifteen-second join grace period, sleeping districts' builds are prepared one slice (about 4 ms, at least one build) every 100 ms, nearest the camera first, without competing with the initial engine model-load pass. Parked builds are released when no actors sleep, on a scene change or on world disposal. No key, no wire field. Within `hub.contract: 1`. |
5319
+ | 2026-10-25 | `hub.weakestTier`: on Weakest and Middle, a `HubNpc` resident that has walked off its authored spot stays drawn within 20 m of the player even across a district line, and once drawn until 22 m; before, it was drawn only inside the player's district or within the four-metre apron, so a schedule walker popped in and out at district lines. A resident at its spot and every other actor follow the district rule as before. No key, no wire field. Within `hub.contract: 1`. |
5320
+ | 2026-10-25 | Edge goal and friend pointer chips also keep beside a shown Sit / Stand button (low in the middle, or in the landscape rail), as they keep beside the Act/Jump pair: a chip on the bottom edge lay on it. A chip clear of it, or with no Sit shown, is placed exactly as before. No key, no wire field. |
5321
+ | 2026-10-25 | Edge goal and friend pointer chips keep beside the Act/Jump pair and a shown Character button, as they keep beside quick chat, emotes, grab and sound, never on them. With safe chrome (`hub.safeInsets`), a pointer chip the safe layout would move down onto a control (it moves only down, capped at the bottom edge) takes the nearest place clear of every band, else of every control, else keeps its own place: a landscape phone's goal chip at the pair's height landed on the chat button. A move clear of the controls, and every other surface, is placed exactly as before. No key, no wire field. |
5322
+ | 2026-10-25 (v1.195) | §14 `hub.resetFences(playerIds)`: the `resetFences` for a `session.storage.conditionalWrite` touching one or two players here, one `{ playerId, resetGeneration }` per Castle account from the markers the kit already reads (v1.92); null for a guest, an absent player, a bad list or any unknown marker, never a guessed 0. A stale-reset refusal is dropped, not retried as an ordinary write, and the place calls `hub.refreshProgress`. Fences need conditional storage (managed targets, deck flag); plain Store writes are unchanged. Older kits lack the op; a deck without conditional storage refuses the write; host agents forward the field. No wire or manifest change. Within `hub.contract: 1`. |
5323
+ | 2026-10-25 (v1.194) | §6 `hub.sitOn(playerId, seatId \| null)`: a place with `idle.seats` seats an arrived player on a shown, free HubSeat from its server (a meeting's stools, a bench) at any distance, with no sit budget and no `sit` hook, or stands them with `null`; boolean. Refused for a held, absent or driving/riding player, a taken, hidden or non-seat actor. Afterwards an ordinary seat hold (Stand, input, door jump, hold/release, end and leaving stand them). Rides the existing `hubSeated` and `held`, so old and native clients draw it unchanged. A place that never calls it is unchanged. Within `hub.contract: 1`. |
5324
+ | 2026-10-25 (v1.189) | Optional `phase: "end"` on `hub.push.visit`, sent once by the place server from leave or at forget for a retained resume player, and for every remembered player at layer shutdown, only after an accepted start. Ghost keeps the latest end per user, place and join generation; an end older than the start or from an old generation is dropped. An old host-agent or Ghost answers `false` and Ghost derives from the start; no retry, start unchanged. Landing order: Ghost first, then the host-agent, then the deck save. Within `hub.contract: 1`. |
5325
+ | 2026-10-25 (v1.188) | Optional invite entry in Character: a scene with `engine.hubInviteRail: true` also reads the authenticated viewer's invite gate through `Hub.inviteAvailable()`, once per connection, scene and identity lifetime without retries. Only `ok` with `available: true` shows the row; pending, false, errors and old hosts hide it. Stale reads and picks are fenced; the existing five-use share flow is unchanged. Without the marker, no request or behavior change. No manifest or wire change. Within `hub.contract: 1`. |
5326
+ | 2026-10-25 (v1.180) | §1 optional place key `heldOffers: true` (§12 "Held offers"), only in a place with a resume mode (`resume: { keep: true }`, `resumePose`, `houseResume`, or a place without a result a host may pin); any other value, or the key without a resume mode, is a manifest error. `hub.actions`, `hub.ask` and `hub.menu` offers made to a retained player are kept while away; calls made meanwhile return true and are recorded, not sent; the resume hello replays the latest of each under a fresh version, and presses, answers and picks on older versions, or before that hello, are refused. An offer is kept only while the transport id, the signed-in non-anonymous account it was made for and the body generation still match, checked on every press, tick and replay; any roster row on the id for another account (with or without a body), an anonymous identity, or an account or body change ends the hold and drops every offer with no replay. Replaces the retired v1.149 and v1.151. Server-only: old clients and native hosts see the existing `hub-actions`, `hub-ask` and `hub-menu` messages; absent key keeps behaviour and bytes identical. Within `hub.contract: 1`. |
5327
+ | 2026-10-25 | `hub.placeAt` wins over the move reports its client sent before it heard of the placement: a report that could not have come from a client that has applied the placement (farther from the spot than the movement limit allows since it, or, within 500 ms of it, nearer where the player stood before by more than the 0.6 m slack) moves nothing, its state block is still kept, and each snapshot goes on carrying the correction; the first report a client that applied it could have sent (eased part of the way and walking on included) is taken and ends the wait, and 4 s is the backstop. A `hub.placeAt` within the slack of where the body stands (a place that puts a player where they are each tick) arms nothing. Those reports used to pull the body back toward where the player stood under the movement clamp, and the clamped row sent back put the client there too, for good (0.6 to 1.2 m short, a whole walk back on a client slow to hear). Any other placement (a hold, a jump, an arrival, a car, a pose restore) ends the wait at any distance; the movement clamp and everything after the wait are unchanged. A leave before the next server step after a placement (`hub.placeAt`, a hold, an arrival) now stores the placed pose for `resumePose`, not the one the previous step recorded. No manifest or wire change. Within `hub.contract: 1`. |
5328
+ | 2026-10-25 (v1.179) | §1 `ballot.keepAway: true` (only `true` or absent; only in a place that retains a dropped visit: `resume: { keep: true }`, `resumePose`, `houseResume`, or a place without `result` or `resumeArrivalPose`, which a host's pinned reconnect window retains; any other value or place is a manifest error), §6 "Away faces", §12 `hub-ballot-card` face `away?`: a player the place is still retaining (dropped inside the resume window, not yet forgotten) keeps their face on the others' cards with `away: true`, drawn with an "away" tag; a tap on it is taken and handed to the `ballot` hook as for a present player. One eligibility rule decides every send and tap, from current state only: a face is eligible iff its player is present now, or retained away and the kit's record from the last send they were present holds the viewer, unblocked then, under both players' current signed-in accounts; the away face is drawn from that record's username/avatar snapshot, any account change on either id invalidates its records, guests are never in one, and a tap counts iff the face is eligible at tap time, whatever the card showed. When the retention ends the place forgets them as for any leave (the face goes, the `leave` hook runs); on their return their own card is replayed as before. `hubPlace.ballot` is unchanged (server-only key). Compatibility: a client or native host before it ignores the unknown face key and draws the face as an ordinary one, still tappable; absent the key, the server sends the same bytes as before and takes the same taps. Within `hub.contract: 1`. |
5329
+ | 2026-10-25 (v1.185) | §1 `hub.wallet: { name, start? }`, §4 `hub.wallet.read/spend/earn/seed`, §14 "Coins": one coin wallet per signed-in account on the SDK's gated conditional storage (deck target `wallet:<name>:<userId>:`, one key `...:state` = `{ v: 1, gen, coins, owned, data }`, `gen` the reset generation it was written under; a progress reset deletes no door-deck row, so an older `gen` reads as a fresh wallet). Every spend or earn is a `conditionalWrite` naming the snapshot access, the target revision and a reset fence with the generation read before the snapshot, one writer per account; a revision conflict adopts the stored wallet and applies the operation once more (still short = `'short'`, a second conflict = `'busy'`), a stale reset generation drops the cache and rereads, a call made before a progress reset never runs after it (`'busy'`), and a lost reply is retried with the identical request (`read` is null until it settles). A failed read or unreadable row locks the wallet for the visit; storage without the API or with the deck's flag off (off by default; enabling it is an admin action) locks every signed-in wallet (`read` null, changes `'locked'`), never falling back to an ordinary set. Anonymous players and dev guests get a session-only wallet. `seed` enrols an account once from a game's old whole-save coins. Absent key = no API, same bytes and behaviour. Within `hub.contract: 1`. |
5330
+ | 2026-10-25 (v1.184) | §4/§10/§12 `hub.hide(actorId, { to: [playerIds], solid: true })`: a private hide that draws the actor hidden for those viewers but keeps its collider in place on their clients, so a per-viewer cutaway wall stays solid. Boolean, hide-only (`hub.show` refuses `solid: true`), ignored with `clear: true`; a non-boolean is an invalid-options refusal. Private `hub-vis` gains `solid: [actorIds]` only when non-empty, so places that never pass it send byte-identical messages; older clients ignore it. Retained-visit replays carry it. Server bodies unchanged. |
5331
+ | 2026-10-25 (v1.182) | Optional top-level `hub.holdShow: true` exposes `hub.holdShow` / `hub.holdShowing`: five tinted right-hand flower shapes, visit-only with retained-drop continuity, yielding to role tools and grabs while hiding earned held items. Latched `hubHoldShow` tuple maps coalesce at four changes per second per player; never-called decks retain identical bytes. Town's Posy gives her daily greeting's matching flower. Old clients ignore the additions; native hosts ignore `hubHoldShow` until parity. Within `hub.contract: 1`. |
5332
+ | 2026-10-25 | On a desktop keyboard, a talk panel's field focused as it opens (a first visit's greeter sheet opens on arrival) no longer takes the movement keys until the player types in it or points at it: while it is empty, W, A, S, D, the arrows and Space, pressed alone, reach the game unentered and do not lock input; any other key is the field's, and from then on every key is. A phone keeps its keyboard down as before. "Stuck?" is not offered while a talk panel, a choice card, an ask or a menu is open. No manifest or wire change; the UI tree schema is unchanged. Within `hub.contract: 1`. |
5333
+ | 2026-10-25 (v1.183) | §12 blocks reach seats, emotes and holds: the shared `hubSeated`, `hubEmotes` and `held` leave out every player in a hidden pair, by `hubAv`'s rule, and each player is told alone of those it may see, itself included, by a whole `{ k: 'hub-idle', hubSeated, hubEmotes, held }`, sent again to a client that joins afresh once the place has sent one. A blocker no longer learns from them that the hidden player is here or which seat they sit on. A place with no hidden pair is sent exactly what it was and never a `hub-idle`; an old client ignores it and does not see the pair's seats, emotes or holds. A deck changes nothing |
5334
+ | 2026-10-25 | §6 grabbing: the pickup's ease-in, from where an object lay to its hold point, is now bounded by the multiplayer kit's acknowledgements as the aimed throw's swing is (never more than 0.5 m from any position the server's body may be at), with or without the orbit camera key, so reports bunched by the network no longer break multiplayer-3d's owned-object move bound and drop a fresh hold. It falls back to the old carry at the carry speed 2 s after the grab, and throughout with a multiplayer kit without acknowledgements. Client only; no manifest key, no wire change. |
5335
+ | 2026-10-25 (v1.181) | §4/§9 optional own bird-only `shown: true`, gated by server-only `hub.companionShown === true`, publishes dress enums to everyone in the place; lanterns and other values throw `TypeError`. §12 latched `hubChirp`: sorted `[playerId, species, wear, tint]` rows for helloed, arrived owners, default slots `null`, snapshots only after first use (including `[]` after clear/leave), deltas only on whole-array change with the owner's four/s coalescing. Web draws a small dressed paper bird at others' shoulder glow anchor; Low keeps a tint-coloured glow, avatar hiding and blocked pairs hide it, replaced resources are disposed. The owner's full follower, speech, pose and target stay private; shown follows clear, leave, account change, place end and same-account `resumePose` replay. Town and House gate shown on the capability. Absent shown preserves wire bytes; old clients and native hosts ignore `hubChirp` until parity. Within `hub.contract: 1`. |
5336
+ | 2026-10-25 | The toast is drawn only in a row clear of every control, the action chips and the overflow rail included; while no row of the view is, it is not drawn, and it comes back when one is. It is the rule the transient caption lanes carry (hidden while no lane fits). At 509 × 218 with the town's offers the toast stood on Invite a friend; it now waits. No key, no wire field. |
5337
+ | 2026-10-25 | Safe chrome (`hub.safeInsets`) re-reads the safe-area insets when they change at an unchanged view size (an Android keyboard or nav bar, an iOS rotation that keeps the size), not only on a resize: the chrome kept a stale inset, about 30 px on the right on a moto. The documented inset behaviour (§9 safe edges), restored; no key, no wire field. |
5338
+ | 2026-10-25 | Goal pointers keep the place the world layout gives them: the frame's HUD clearance pass no longer shifts a pointer for the prompt pill after the world layout has placed it clear of the HUD, the prompt and every control, which lifted the house pointer onto Invite a friend (844 × 390), Chat with Chirp (509 × 218) or Character (412 × 870). Without a world layout the pass is unchanged. No key, no wire field. |
5339
+ | 2026-10-25 | Action overflow rail: when no place clears every obstacle, the rail is placed over passing text (the prompt, toast, feed, stats and result ribbon, then the HUD title) before it would be hidden, so an offer is never dropped with no More or Actions button. A crowded 509 × 218 frame showed no offer; it now shows the first and More. The legacy landscape chip stack is unchanged. No key, no wire field. |
5340
+ | 2026-10-25 | The follower's Chat button (the invisible tap area over a companion) treats the action overflow rail and its sheet as controls and is not drawn over them, so a follower walking under the rail no longer takes a chip's tap. No key, no wire field. |
5341
+ | 2026-10-25 | §9 choice sheet (web): a scrolling sheet, or a landscape column, fades at its bottom edge while more is below and not once its end is in view; picking a face brings only the first row of lines into view, so the picked face and the About hint stay on the sheet. No key, no wire field; the UI-tree choice card is unchanged. |
5342
+ | 2026-10-25 | Decorate tray: tiles are 72 px wide and a piece's name wraps to two 11 px lines instead of an ellipsis; its unlock line is 10 px. Every House piece name and unlock line now shows whole. No key, no wire field. |
5343
+ | 2026-10-25 (v1.186) | §9 the Back corner is reserved in every door: without `hub.safeInsets`, the kit's Again control moves to the bottom centre wherever it would meet the top-left 64 × 56 box (portrait, or a left safe area over 12 px); in landscape with no left inset it keeps its place. Back with a ticket title, and safe-inset places, are unchanged. No key, no wire field. |
5344
+ | 2026-10-25 (v1.190) | §8 `hub.hold(playerId, at?, facingDeg?, { turnCamera: true })`: the held player is sent `hub-hold-face` with the held facing on the hold and again at `hub.release`, and their client turns as `hub-jumped` does (the camera to `PI - facing`; under the orbit key the avatar via `faceRequest`). A later hold without the option takes the release turn away; other ends of a hold turn nothing. Absent the option, holds, the wire and v1.85's rule are unchanged. The native host mirrors the turn. |
5345
+ | 2026-10-25 (v1.191) | §4/§6 `hub.drop(playerId)` with an explicit id always sends that player `hub-drop` when they are in the place, even with no hold the place registered (then without `actor`), so a client holding an object the server never heard of lets go. `hub.drop()` with no id, the return value (registered holds ended) and grab budgets are unchanged. |
5346
+ | 2026-10-25 (v1.192) | Writer leases: `writerLease: true` (the hub block or a named place; only `true` or absent) makes the newest instance to claim an account the only one that saves it. Each account claims its own empty user target (`hub:writer:`) once per instance; another instance's claim fences this one, whose later per-player writes reject with `CAULDRON_STORAGE_WRITER_LOST` (no network call) and whose visits see the personal HUD line "You're playing somewhere else, so progress here isn't saved." A claim refused, still failing after 20 s, or a reset/undo also loses the writer; the last departure keeps the lease 60 s for end saves. A fresh connection (new player id) of a lost account with no other connected visit here forgets that account's retained visits through ordinary leave cleanup (the deck's `leave` hook included) and claims anew before its arrival hooks; a same-player-id resume, or a fresh visit beside a connected lost one, stays lost. `hub.saves` adds `enabled`, `deck(userId)`, `user(userId)`, `fence(userId)`, `ready(userId)`, `lost(userId)` and `onLost(fn)`; places route per-player writes through `deck`/`user`, `fence` before root `session.storage` atomic calls, and reload an account's saves on every fresh arrival (`get`/`list` wait for the claim); `hub.wallet` fences its own writes. Compatibility: absent, nothing changes (raw stores by identity, no claim, no notice, retention as before); a host without root `claim`/`transaction`, or one answering `UNKNOWN_COMMAND` or a non-retryable `CAULDRON_STORAGE_UNAVAILABLE`, saves as before without a lease. Server-only: no client manifest key or wire field (the notice uses the existing `hub-hud`). A write already past its fence when another instance claims can still land (about one round trip). No deck opts in yet. |
5347
+ | 2026-10-25 (v1.193) | Town purse paid ledger: the Town deck's scope gains `paid:<userId>:<paymentId>`, an integer tokens count for one once-only payment, set once (a repeatable `set`) and never lowered or removed. Payment ids are the fixed list `bell:1`..`bell:7`, `bell:encore:1`..`bell:encore:7` and `errand:cat` (hub-town `tokens.js` `PAID`, T9). A balance is `tokens:<userId>` plus every ledger row, less hat prices and `spent:<userId>`; the Town's wardrobe read and the House's `chirpPurchases` funds read the rows by key. Each payment marks its old claim (`<earn key>:ledger`), raises it, then sets its row, so a layer on older code reads it as claimed. Ghost adds `paid` to `HUB_TOWN_PLAYER_NAMESPACES` (door-deck reads) and to the hub user reset. Compatibility: absent rows, the balance is exactly the old one; an older Town or House reader, or a Ghost without the namespace, shows a lower balance, never a higher one; this House against a Ghost without the namespace has its funds read refused, so Ghost lands first. Gifts, the day's bonuses and game results keep the old claim-then-credit path. No manifest key, wire field or SDK change. |
5348
+ | 2026-10-25 (v1.187) | §9 Action chips: every place draws its `hub.actions` offers on the action overflow rail. A landscape place without `hub.safeInsets` or the `hubActionOverflow` scene key leaves the bottom-right column, which trimmed offers from the top with no sign, for the rail portrait and safe-inset places already used: one row, two rows, the first offer and More, then Actions, with a sheet listing all. At 844 × 390 three short offers stand in one row; in a crowded 509 × 218 frame an offer the column dropped is now behind More. The rail now also yields to open panels, sounds the chip cue on a press and leaves no focus behind after a pointer press, as the column did, in every place. The scene key is a no-op. No wire field. |
5349
+ | 2026-10-25 | Chat with Chirp: the chat flight holds the companion on the sightline between the camera and the player, at the depth where its paper is about a tenth of view height (the active lens, as the show pose is sized), facing the camera, instead of 1.3 m beyond the player where a 6 m orbit (and more so the tablet camera) drew it tiny. Panel lift, 0.9 m camera clearance and closing back to following are unchanged; a camera too close behind the player, or facing away, keeps the old spot. No version, manifest or wire change |
5350
+ | 2026-10-25 (v1.177) | Two deck SDK commands for hub notifications, answered by the host. `hub.pushPermission` (`Hub.pushPermission()`): params `{}` (any key answers unavailable), result `{ status: 'granted' \| 'denied' \| 'unavailable' }`; interactive (the SDK waits on the player's OS permission answer with no timer of its own) with a 120 s `COMMAND_TIMEOUTS_MS` entry; a deck asks it only from a deliberate tap after a committed personal promise. `hub.pushDestination` (`Hub.pushDestination()`): params `{}`, result `{ notificationId: string, townDeckId: string }` or `{ status: 'unavailable' }`, the default command timeout; it reads the native push hint that opened this town, once, after an authenticated join. Both answer `{ status: 'unavailable' }` whenever the host's `cauldron_hub_push` gate is off, and unless the user is signed in (not anonymous) in a joined session (deck, session and user known) for which Ghost answers `hubPushCapability(deckId, sessionId) === 1`. Two wire fields, both optional: host to deck, the response envelope gains `hubPushReceipt` (a string of 32 lowercase hex), present only on a mobile host's ok `hub.pushDestination` response that carries a hint; deck to host, once the SDK has resolved that still-pending mobile request with a string `notificationId` and `townDeckId` and a receipt matching `/^[0-9a-f]{32}$/`, it sends `{ castleSdk: 1, hubPushReceipt: { requestId, token } }` once (a request already cancelled or timed out sends none; a missing native bridge is swallowed). The native host holds the hint for 25 s (the SDK's 15 s command timeout plus a 10 s return margin), consumes it only on a matching receipt, and otherwise releases it unconsumed for a later read. Compatibility: an old SDK never sends either command and ignores the unknown `hubPushReceipt` field, so the hint expires; a new SDK on web, on an old native host, or against an old Ghost (no `hubPushCapability`, so the query errors) gets `{ status: 'unavailable' }` (the SDK itself turns a host's `UNKNOWN_COMMAND` and an absent host's `CASTLE_HOST_UNAVAILABLE` into it; other errors still reject); an old host drops the receipt envelope, which carries no command; with `cauldron_hub_push` off, both commands answer unavailable. No manifest key; the kit does not call either command yet. Within `hub.contract: 1`. |
5351
+ | 2026-10-25 | `hub.loadingCover`: a connection that comes back under a new player id (a drop past the place's hold, such as 180 s backgrounded) keeps the cover up until the place's arrival has placed the player: `hub-arrived` and then the state block carrying the player's clamped row, plus one frame for it to reach the body. A `resumePose` restore and the arrival's first HUD are therefore under the cover rather than shown at the scene's spawn just after it lifts. The wait starts at the first draw that would otherwise lift the cover and ends after 6 s at most, so a place that sends no restore or HUD is not kept covered. A return under the same player id, the first join and trips lift as before. No manifest or wire change. Within `hub.contract: 1`. |
5352
+ | 2026-10-25 (v1.176) | §4 `hub.board` may carry `featuredNext`: the door is featured tomorrow, by the rotation's pick for the next hub day or, outside the rotation, its hand-set flag. Additive; absent from an older ghost, where a deck knows only today's `featured`. |
5353
+ | 2026-10-25 (v1.172) | §5 a scene's implicit ground may be sized: `"ground": { "half": n }` at the scene file's top level is its half-width in metres, clamped to 1..200, read by multiplayer-3d's server ground collider, physics-3d's client collider and its drawn plane (2n wide). Anything but a finite number is no key. Absent key = today's 100 m collider and 60 m drawn plane, same bytes on both sides. The native engine reads the same key and rule (castle-client, not yet). Within `hub.contract: 1`. |
5354
+ | 2026-10-25 | §9 place menu on a short view: the 55% height cap (40% with `face`) is at least 220 px (150 px with `face`), and never more than the view less 24 px, on the DOM sheet and the UI tree alike. At 574 × 246 a tile sheet showed its title and note over a 14 px list; it now shows a row of tiles. Views 400 px tall or more are unchanged; full-height row sheets are unchanged. No manifest or wire change; a sizing fix with no contract version. Within `hub.contract: 1`. |
5355
+ | 2026-10-25 | What is worn (`hub.wear` pieces, role outfit pieces, earned pins) follows its avatar's model when a seat, a bed, a car or an emote moves the model rig: each piece takes the rig's pose over its standing one, so a role hat stays on a seated head instead of floating 0.45 m above it. Standing pieces are drawn as before. No manifest or wire change; a fix with no contract version. Within `hub.contract: 1`. |
5356
+ | 2026-10-25 | Vehicle preset (v1.160) under the orbit camera key: the car's `camDistance`/`camHeight` now place the camera, as they always did under the follow camera and as the native host does. The driver and riders are chased from behind the car's heading (eased at 4/s), looking 0.438 m over it; without a car `cam`, 1.4 × the orbit's walking distance and height. The kit no longer writes the Player's `camDistance`/`camHeight` there, so a ride leaves the player's orbit zoom and tilt as they were. Follow-camera places are unchanged. No manifest or wire change; a parity fix with no contract version. Within `hub.contract: 1`. |
5357
+ | 2026-10-25 (v1.153) | §12 and §13: an under-13 speaker at a mind with published `childAsks` whose inspect is pending or refused (a place ghost does not let children talk to) no longer gets an empty row with no text box and no hint. Their open also carries `fallbackChoices`, the three canned lines ("What can I do here?", "Tell me about yourself.", "Where should I go next?"), which the client shows in place of the bundle chips until an inspect succeeds; a tap goes by `hub-npc-say` and the place answers it through `npcLine` `why: 'authored'`, as v1.148 taps are, with the kit's refused line ("<name> smiles and nods.") when the place returns none. They may be asked again; no mind turn or ghost call is made. Once an inspect succeeds the bundle chips and their checked mind turns are exactly as before; v1.148 authored taps still lead and carry no fallback. Old clients ignore the field. Within `hub.contract: 1`. |
5358
+ | 2026-10-25 (v1.175) | §12 and §13: a mind's authored opening asks show while the speaker's inspect is pending or refused. Where `npcOpening` returns `authored: true`, a mind's open for a speaker without v1.148 authored taps (over 13 or unstamped) carries `fallbackChoices: string[]`, the opening's `asks`. While the client cannot type (inspect pending or refused) it shows them as tap-only chips and sends a tap by `hub-npc-say`; the kit admits a trimmed exact match on that open and answers it through `npcLine` `why: 'authored'`, never a mind turn. An answered ask leaves the row. Typing still waits for a successful inspect, after which the asks are mind turns exactly as before, and the speaker's mind turns are admitted as before throughout. Under-13 speakers, minds without an authored opening and bodies without a mind are unchanged; old clients ignore the field. Within `hub.contract: 1`. |
5359
+ | 2026-10-25 | `hub.safeInsets`: an act prompt (such as "Talk to Rowan, the greeter") no longer covers a control or the look caption. It keeps its place when that is clear of every control, the HUD, the host's corners and the transient text before it; otherwise its whole pill goes to the nearest row and lane clear of those, of the HUD prompt's place and of other act prompts, by the transient caption's rule, also off the unplaced cards and transient text after it, and it is not drawn while no lane fits or once a later surface or the settled action rail lands on its lane (on a landscape phone it sat over Character, Jump and Act at 740x360, and over Jump and the look caption at 844x390). Toasts, the ribbon, world labels, pointers, cards, chips and the action rail are placed as before (they still make way for the act prompt's old place), and only the transient caption family also keeps its words off its new place. No manifest or wire change. Within `hub.contract: 1`. |
5360
+ | 2026-10-25 (v1.174) | `hub.emote(playerId, "yawn")`: a kit emote only a place plays, at any place with `idle.emotes` (not only `idle.expression`): 🥱 for 3 s, model-only, a stretch up with the head tipped back, then a sag forward and a little sideways with a slow nod, then back to rest, for a benched or tagged-out player. For everyone, without the hook or the rate, as the original five; it rides `hubEmotes` as `{ id: "yawn", at, until }`. No picker or wheel offers it (both trees byte-identical) and a client's `{ k: 'hub-emote', id: 'yawn' }` is refused before the hook; without `idle.emotes` `hub.emote` refuses it. A free NPC answers it with wave and the wave lines; `npcReact` hears `emote: "yawn"`, and answer ids stay the original five. It reuses the bow cue; no new asset or synthesis. A declared role emote named `yawn` keeps its own definition and grants. A client from before v1.174 resolves no definition for the id, so it draws no motion, emoji or sound and does not throw. The native engine does not do it yet. Within `hub.contract: 1`. |
5361
+ | 2026-10-25 | Hats (`hub.wear` `"hat-<id>"`, §11): every hat model is drawn with the avatars' own look (outline 0.03, rim 0, ao 0.12, the same outline colour), where it had a thinner ink line, a rim light and darker shading than the body under it. Shapes, colours and fits are unchanged; halos, auras and orbits keep their glow. No manifest or wire change. Within `hub.contract: 1`. |
5362
+ | 2026-10-25 (v1.173) | §12 a player's own Back ends the visit, so the next entry is a fresh arrival; resume applies to drops only. In a place without `result`, the client says `{ k: 'hub-back' }` (no other fields) just before `Hub.back` when the player leaves by their own Back press (system back, Escape, or the kit's or host's Back control, all one path); never for a game's Back (`hub-door-quit` as before), a press that only closes the action overflow or the place menu, a press while a trip is under way, or an automatic back (a game end walking back, a place that ended the visit and leaves by its way back, a failed door's retry). The server sends nothing and only arms a per-player mark for 35 s (the SDK's 30 s `Hub.back` timeout plus slack); a repeat restarts the window. When the kit next sees that player's connection gone (or replaced) while the mark is fresh and for the same account, it first lets the visit go exactly as a kit trip (`hub-go`) does: the player is marked departing for resume, their arrival pose (`resumeArrivalPose`) and durable pose (`resumePose`) are cleared and any pending resume is dropped, so the drop is not retained and a return under the same account, same or new player id, is placed at the arrival. A Back that fails leaves the player here with nothing changed: once the window passes the mark is dropped, and a later drop resumes as before. A kit trip, a place end, a stayed end, a leave and a hello under another account drop the mark. Ignored in a place with `result`, in a place that retains no visit, before arrival, from a player not in the session roster or unknown to the place, and once the player is already departing (a kit trip or a place end). Also: a durable pose read discarded because its player departed no longer holds the arrival group. The kit consumes `hub-back` in every place and never passes it to the place's `message` hook; old servers pass it to the place's `message` hook (where it is unknown) and old clients never send it, so their Backs still resume as drops. Native hosts, which drive Back presses too, should send it on the place's connection before their own back. Within `hub.contract: 1`. |
5363
+ | 2026-10-25 | `hub.safeInsets`: the HUD prompt (such as "Tap Rowan and tell him what you like.") no longer covers a control. It keeps its place beside the bottom-right column when that place is clear of every control; otherwise its whole line goes to the nearest row and lane clear of every control, the HUD and the host's corners, by the transient caption's rule, and it keeps its old place while no lane fits, since it is never hidden (on a landscape phone at 740x360 it lay over People); a moved prompt also keeps off the unplaced cards and transient text, and goes back to its old place when a card, toast, chip or the action rail is placed onto its new one. Toasts, the ribbon, world labels, cards and chips are placed as before (they still make way for the prompt's old place), and only the transient caption family also keeps its words off the prompt's new place. No manifest or wire change. Within `hub.contract: 1`. |
5364
+ | 2026-10-26 | Earned badges (v1.53) read further off. Another player's badge gives one brief sparkle the first time that player is within 20 m of this one in a place (not again until the next scene load; never on this player's own badge; counted but not drawn on the Low tier, so Low adds no draw call). On a phone-size viewport (shorter side at most 540 CSS px) a badge more than 10 m from the camera is drawn bigger in step with its distance, up to 2.5 times, so it is never smaller on screen than it is at 10 m; pins, other earned classes and every larger screen keep their size. No name-tag suffix. No manifest or wire change. The native engine does not do it yet. Within `hub.contract: 1`. |
5365
+ | 2026-10-25 | `hub.safeInsets`: the transient caption family (the engine's look caption with its presence line, such as "2 here · a boat shed", the engine's score line, the feed and stats) is no longer left under the controls. Its words keep their place when they are clear of every control, the HUD and the host's corners; otherwise the line is narrowed to its words and moved to the nearest row and lane wide enough for them, and it is not drawn while no lane fits (on a landscape phone at 844x390 or 740x360 it ran under Actions/Talk, or under Character, Jump and Act). The toast and the result ribbon take the same lane rule for their whole pill, clear of the controls, cards, the HUD, the host's corners and each other (back from a scored door in the embedded Town view, about 562x240, both were pushed down onto Jump and the caption). World labels, pointers, cards and chips are placed as before. No manifest or wire change. Within `hub.contract: 1`. |
5366
+ | 2026-10-25 (v1.171) | §5 a host Go (SDK `Hub.onGo`, v1.155) that ends before the host commits its join is reported to the host once: the kit calls SDK `Hub.goFailed({ doorId, owner }, why)`, posted one-way as `{ castleSdk: 1, hub: { type: "goFailed", doorId, owner?, why } }` (`owner` only for a House door; `why` `"refused"` when `Hub.go` gave no handoff, `"content"` when the destination's content would not load, `"join"` when the join was not committed, e.g. a play proxy `not_running` (4404) after the SDK's own tries). Hosts parse it with host-side `hubGoFailedFrom`. The host may acquire the door again from its own session, where ghost's pad check passes, and post a fresh Go; the kit never asks `Hub.go` again for a host Go itself (since 6a193af99). A join the host committed and then lost, a pad's own go and a cabinet are never reported. An SDK without `Hub.goFailed` sends nothing, and hosts that predate it ignore it; the native host does not act on it yet (castle-client, behind `cauldron_hub_native`). Every deck, no key; nothing new on the place's wire. Within `hub.contract: 1`. |
5367
+ | 2026-10-25 (v1.170) | `hub.quality` Low: the name tag of a bystander culled by `quality.low.players` is not drawn while its avatar is culled, and comes back with it; the player's own tag is untouched. Name tags do not count under `quality.low.labels`. High and decks without `hub.quality` draw every tag as before. No key, no wire field. The native engine does not do it yet. Within `hub.contract: 1`. |
5368
+ | 2026-10-24 (v1.169) | A player's own door end can be stayed. `hub.end([playerId], { door })` (one player, `door` a `HubAct.id`-shaped id) names an end as that player's own walk-in; an end a player's own Act press (`hub-act`) or action chip (`hub-action`) makes while its hook runs is tagged with that id by the kit. Only in a place without `result`, the client hears `{ k: 'hub-end', why, door, end }`, `end` a per-player counter that only rises for the session (a let-go, a resume hello or a fresh hello never resets it); a repeat of a tagged end already in force says nothing. A client that met such an end while away (the multiplayer resume gate armed or the transport not connected when it arrived, which a message drained in the drain that releases the gate is; never the gate's two-second return tail), or whose way back for it was pending or failed while away, cancels it: no Back retry, any acquisition given back by `Hub.cancel`, the cover lifts on the place, and once placed again in that session it sends `{ k: 'hub-stay', end }`, and again right after each resume hello, until the server answers `{ k: 'hub-stayed', end }` (placement alone proves nothing: the resume gate can give up while the socket is down). It drops what it owes on a newer end it takes, a session change, a new player id or a trip. The server applies a stay only when its `end` matches the player's current stay record, then answers `hub-stayed`; a repeat of an end already stayed is answered again and changes nothing, so an old stay can never undo a newer door end. It un-ends only an entry ended by that tagged end (`ended`, `endAgain`, `endWhy` cleared, out of the resume and Act departing sets, so Act, actions, ask, decor and companion are replayed and the pose store keeps the pose again) and holds that door shut for the player until a step in which the place no longer asks for it (they stepped off). The tag and the hold survive the client's resume hello, and the stay takes the visit's pose lease again (`resumePose`). The server keeps one stay record per player, which exists exactly while their latest end was their own door end: any other end for them (a kick, a timer, `hub.end()` for everyone, whether or not they are still here) deletes it. A drop still lets the ended visit go (no stored pose); a resume hello under the same account within the place's resume window arrives afresh still ended by that door, and only its `hub-stay` puts the player back where the end left them (a `houseResume` guest at the arrival, as a resume does). A `hub-stay` heard before arrival (including one that reaches the server before the resume hello, or during the hello's progress read, which drops other client messages) is applied once arrival has placed the player. Any other hello, or none in the window, drops the record; applying a stay deletes it. Inside a press only a one-player list naming the presser is tagged. A kick, timer, `hub.end()` for everyone or for several players, any end since the door, and every game end (`result`, v1.72 `again`) complete as before. A pad's `hub-go` met while away (the same rule) in a place without `result` is dropped and answered with `hub-shut` once placed again. Old servers pass `hub-stay` to the place's `message` hook and old clients ignore `door` and `end`; native hosts ignore `hub-end`'s `door` and `end`, `hub-stay` and `hub-stayed` until parity. Within `hub.contract: 1`. |
5369
+ | 2026-10-24 (v1.168) | `hub.quality` Low: a `hub.mark` tag or role label whose avatar is culled by `quality.low.players` is not drawn, as a v1.162 carer copy. Marks and role labels count under `quality.low.labels`, ranked nearest first with the world labels by their avatar's Transform; pointers, party, near-rule captions and the player's own mark and role consume no slots. High and decks without `hub.quality` draw the same labels as before. No key, no wire field. The native engine does not do it yet. Within `hub.contract: 1`. |
5370
+ | 2026-10-24 (v1.167) | The kit's screen UI tree (`code/client/uiTree.js`, drawn by `uiDom.js` on web and by the host's native renderer), three opt-in node shapes, no deck-facing key: a side of `s.pad` may be an edge value `[min, add]` = max(min, that side's safe-area inset + add), with plain numbers still the default (a pad holding one is written as four sides); `s.aspect`, a number, width / height, default none; shadow preset `'glow'` = `0 0 0 3px rgba(255,216,74,0.5)`, default none. The place menu's tiles are square (`aspect: 1`) and its sheet and the choice card's stand on the view's bottom edge with `pad` bottom `[12, 0]`, as the DOM's `max(12px, env(safe-area-inset-bottom))`; a chosen ballot face or line chip is `shadow: 'glow'`. Trees that do not set them serialize to identical bytes; native renderers draw all three. |
5371
+ | 2026-10-24 (v1.166) | §4 `friendsAmong`: an account's first read in a session that comes back empty (a refusal included) is provisional: cached 5 s, with one early re-read even inside the 31 s gap, so a door entered from a Town pad finds a friend once ghost has marked the session. A read begun within that first read's minute holds the next op until the minute ends: at most two ops per player per session in the first minute (ghost's per-session limit). Later empty answers keep 40 s and the gap; non-empty answers keep 10 min. `friendBests` keeps such an early empty answer only until `friendsAmong` may read again. A rejoin in the same session is no new first. `freshFriends` places unchanged. No key, no wire field, nothing new stored; every failure still answers no friends. Within `hub.contract: 1`. |
5372
+ | 2026-10-24 (v1.165) | §4 observed progress, §6 Cars: while a player drives (`hub.drive`), their `hub.observed` allowance is `max(car.speed, car.reverse)` × 1.25, the speed the movement clamp already follows, instead of the walker's; `hub.tune` does not change it while driving. The pass that sees a driving-state change (in, out, a respray) fills that tick's credit at the lower of the two and holds the credit to the new cap, so getting in buys nothing; getting out stays a placement (a reset); a walker's tune change is no transition, so places without cars are unchanged. Riders keep the walker's allowance and are excluded from earning while riding (no travel, no credit, no station entry, at any car speed). Client fix: a driver's car takes the facing of the server's clamped placement row (held, a turn over 20° or a move over 1 m), from rest, so `hub.placeAt`/`hub.hold` with a facing turn the kart. No manifest or wire change. Within `hub.contract: 1`. |
5373
+ | 2026-10-24 (v1.164) | §10 Decorating: an item's optional `action: true` makes a button tile that sends a stock-free `pick { item }` op (no ghost, no count chip; locks and the shared op budget still apply); an action cannot be placed. Absent key = same bytes and behaviour. Within `hub.contract: 1`. |
5374
+ | 2026-10-24 (v1.163) | §4/§10 server-only `hub.record` and per-viewer `hub.replay`, on by use with no manifest key. Eight authoritative recordings, 192 quantized poses and a 10-minute limit; two private non-solid ghosts per viewer, four calls/s, no actor/body/shared state. Any drop invalidates recording and clears replay; no retained RESEND. Decks own friend privacy through friendBests/friendsAmong. Unused wire bytes and storage unchanged. Within `hub.contract: 1`. |
5375
+ | 2026-10-24 (v1.162) | §10 `hub.spawn(fromActorId, at, { carer })`: an optional player id a copy goes with (a pet, its worn piece), kept for the copy's life; one not a string or not a player in the place is ignored. The wire carries `carer` on the copy's `spawned` record only when set. Client-only effect: on Low under `hub.quality` the copy is hidden while its carer's avatar is culled and restored with it or on High; the local player's copies are always drawn. The native engine ignores it today. Absent option = same bytes and behaviour. Within `hub.contract: 1`. |
4597
5376
  | 2026-10-21 | `hub.safeInsets`: the character sheet's landscape strip (one row of tiles with its own Close, at 844x390 and similar) is no longer moved or narrowed by the safe layout around the controls it covers: it stays where it fits itself and still counts as an obstacle for other cards. Before, a visible prompt such as "Talk to Rowan" could push it into a side lane and clip it off the right edge with its Close. The portrait and lane sheets are placed as before. No manifest or wire change. Within `hub.contract: 1`. |
4598
5377
  | 2026-10-21 | §5 invite actions: a place action whose id is `invite-friend`, `share-win` or `share-town` (a pick that calls `hub.invite`) is drawn, and its pick sent, only in a place with `invite` while the host's `Hub.canInvite` answer allows this socket's player; otherwise the other actions are drawn as before. A share the host then refuses shows "Sharing is unavailable here." instead of nothing; a stale socket, player or account still cancels silently. No manifest or wire change. Within `hub.contract: 1`. |
4599
5378
  | 2026-10-20 (v1.161) | §1 `hub.spawnCap`: a deck may raise `hub.spawn`'s cap on copies alive in a place from 96 to at most 192 (an integer 96..192, root only, refused otherwise by the manifest and the publish check). The spawn rate and burst, and Low tier's client-side `quality.low.spawned` cap, are unchanged. Absent key = same bytes and behaviour. Within `hub.contract: 1`. |
@@ -4652,7 +5431,7 @@ a deck written before them remains valid.
4652
5431
  | 2026-10-07 (v1.81) | §10 a goal may carry `edge: false`: a hint hovers over its on-screen destination and disappears off screen or behind the camera. The two nearest drawable goals are chosen, so hidden hints never displace edge-drawn goals. Only exactly false on a goal with `to` is stored and sent; keys absent are byte-identical. Hub places only; no editor, classic or other Cauldron deck changes. |
4653
5432
  | 2026-10-07 (v1.80) | §13 a place may keep chips on offer after a reply with optional synchronous `npcAsks(hub, npc, playerId) -> { persistentAsks: string[] } \| null`. Re-read with the mind's notes; up to two trimmed, distinct strings cut to 40 characters, invalid entries dropped. Only the talking player's `hub-npc-notes` carries the offer; changes issue notes even when the prefix stays the same, and null clears it. The latest offer leads suggestions or unused opening questions in the existing three-chip row and is exempt from sent questions staying gone while still offered. Throws and rejected async results are caught and logged once without private words; the conversation's bound speaker is rechecked before delivery. Without the hook, no new message key or refill path; notes wire bytes stay identical. Older clients ignore the key. |
4654
5433
  | 2026-10-07 (v1.79) | §1/§4/§9/§12 private place menu: `menu: true` enables `hub.menu(playerId, spec \| null)` and a versioned item/close hook. A phone bottom sheet has up to eight sections and 48 total items, color/icon tiles, selection and readOnly; walking is held while open. Private offers coalesce to four/s; stale/unknown picks drop, six/s burst eight. Keys absent preserve existing behavior and wire bytes. |
4655
- | 2026-10-07 (v1.78) | §4/§9 owner-only bird `pose: 'show'` flies to a camera-relative left view at about one-third screen height fitted from paper and worn vertices (excluding glow) under the active orbit lens, with a 4% screen inset; upright camera-basis orientation, shallow side angle and gentle turn, portrait centre at 27% width / 40% height with a player margin, raised wing flutter and reduced glow; proportional species hats and neck accessories in every pose, with opaque paper and full scale from the first approach frame; hides temporary hat try-on and returns to follow when cleared; absent pose preserves wire bytes and lantern rejects pose. Owner-only bird `dress`: fixed species, wear and tint enums; empty/default dress omitted with literal v1.71 wire compatibility; lantern rejects dress. Folded-paper owl, parrot and hummingbird share the songbird rig, glow, motion and quiet opacity; worn accessories hide during hat try-on and dress rebuilds dispose all resources. `hub.companionDress` gates dress and the separate `hub.companionPose` gates pose, preserving fallback for dress-only kits; show reaches its target in 0.7 s and keeps the full geometry at least `near + 0.15` away in camera depth; `hubGlow` stays presence only. |
5434
+ | 2026-10-07 (v1.78) | §4/§9 owner-only bird `pose: 'show'` flies to a camera-relative left view at about one-third screen height fitted from paper and worn vertices (excluding glow) under the active orbit lens, with a 4% screen inset; upright camera-basis orientation, shallow side angle and gentle turn, portrait centre at 27% width / 40% height with a player margin (amended 2026-10-25, no version: in landscape the box also stays 2% of view width left of the player's left side, a 0.4 m half-width at its depth, and a close shot with no room at the usual spot, such as the House wardrobe, centres it in the strip left of the player), raised wing flutter and reduced glow; proportional species hats and neck accessories in every pose, with opaque paper and full scale from the first approach frame; hides temporary hat try-on and returns to follow when cleared; absent pose preserves wire bytes and lantern rejects pose. Owner-only bird `dress`: fixed species, wear and tint enums; empty/default dress omitted with literal v1.71 wire compatibility; lantern rejects dress. Folded-paper owl, parrot and hummingbird share the songbird rig, glow, motion and quiet opacity; worn accessories hide during hat try-on and dress rebuilds dispose all resources. `hub.companionDress` gates dress and the separate `hub.companionPose` gates pose, preserving fallback for dress-only kits; show reaches its target in 0.7 s and keeps the full geometry at least `near + 0.15` away in camera depth; `hubGlow` stays presence only. |
4656
5435
  | 2026-10-07 (v1.77) | §11 and §12 a harbour boat deed's first unlock names its destination: a home item whose `piece` (or id, when it has none) starts with `boat-` sends private `{ k: 'hub-home-unlock', to: 'boat' }` and the client says "Sent to your boat at the Harbour". Every other home item sends exactly `{"k":"hub-home-unlock"}` and says "Sent to your house"; a repeat unlock sends nothing, as before. An older client ignores `to` and says "Sent to your house", which is acceptable. Decks without a boat deed, and keys-absent decks, send and receive the same bytes as before. |
4657
5436
  | 2026-10-07 (v1.76) | §13 personalised walk-up bubble: a signed-in inspect privately offers physical mind body/character ids via `hub-npc-hooks`, never text. Idle approach reads `status` with reserved `greeting:<character>` once per character per session; opening chat first drops the hooks without reading, failures never retry. Ghost consumes the due hook transactionally; the server checks the captured account/body, returned character and cleaned line, then speaks through only the nearest eligible body within Chat range plus 2 m, to the speaker alone for 7 s. Guests, owners, virtual companions, busy bodies and stale/null results say nothing. Greeting cache stays for the next chat opening and notes. No public text, snapshots, logs or place hooks; no editor or classic deck changes. |
4658
5437
  | 2026-10-07 (v1.75) | §1 place-only `ask: true`; §4 private `hub.ask(playerId, spec \| null)` and `answer(hub, playerId, id, text)`; §9 phone-first single-line prompt, OK/Enter and Cancel, keyboard-aware card and walking/orbit input lock released on every close. §12 private `hub-ask` prompts/closures and `hub-answer` submissions, checked against both current and last-sent versions and ids, limited to two/s, burst four, dropped attempts included. Plain specs have exactly own id/title/max read once, validated and copied; titles and answers reject whitespace-only, control, Bidi_Control and zero-width text. Every changed prompt advances the session counter; tick offers coalesce to four/s, equal sent/current content and version suppressed; fresh hello replays once and leave forgets. A current answer with refused text consumes as Cancel, passing only null. An accepted answer consumes and queues its close before the hook runs; hook errors are contained and logged once without text. Typed text reaches only the place server hook, is never echoed or retained by the kit, and a place must never show it to another player. Absent keys add no API, hook lookup, private state, chrome or wire bytes. |
@@ -4755,6 +5534,28 @@ looping dance poses without server emotes or beat traffic. Manual emotes retain
4755
5534
  their existing call-answer and cooldown behavior. See §4's verb table and the
4756
5535
  wire shape above.
4757
5536
 
5537
+ ### Door resume window (v1.199)
5538
+
5539
+ A place without a result may set `hub.resumeWindowSec` (also in a `hub.places`
5540
+ block, though Ghost reads only the main place) to a whole number of seconds
5541
+ from 1 to 180. It is how a game behind a door keeps a player who switched apps
5542
+ for 30 s or 3 min where they were, rather than starting them over.
5543
+
5544
+ Ghost keeps the number with the saved config and, when it creates a session on
5545
+ a host that advertises `supportsHubReconnectGrace`, pins
5546
+ `reconnectWindowMs = resumeWindowSec x 1000` into `spec.hub` (the probe the
5547
+ Town's grace uses). The key itself never reaches the host. The host retains the
5548
+ participant and token through that inclusive deadline, and the kit's existing
5549
+ pinned retention (the Town's path) keeps the same visit, body and pose: no
5550
+ `leave`, no `arrive`, no second arrival hook, and `heldOffers` and
5551
+ `ballot.keepAway` apply as on any place with a pinned window. Past the deadline
5552
+ the host refuses the token and the next join is a fresh arrival.
5553
+
5554
+ The Town keeps its own 180 s whatever it declares; owner houses keep
5555
+ `houseResume`'s. The key cannot combine with `result`, `resumePose`,
5556
+ `houseResume` or `resumeArrivalPose`. Absent, on an older Ghost, or on a host
5557
+ without grace, nothing is pinned and a drop ends the visit exactly as before.
5558
+
4758
5559
  ### v1.115: owner-house reconnect retention
4759
5560
 
4760
5561
  Optional place key `hub.houseResume: true` (also in a `hub.places` block), only
@@ -4778,6 +5579,9 @@ while the owner's pose is restored. No arrival hook is repeated and no guest
4778
5579
  ownership, deed or owner tools are granted. Stored cold guest poses are not
4779
5580
  restored over the arrival. New host support is required; source landing alone
4780
5581
  does not activate this key.
5582
+ Client side (no version): time the browser reports offline does not spend the
5583
+ SDK's 30 s reconnect budget, so a player whose network drops with the page
5584
+ running keeps retrying its token until the host's hold ends and the host refuses it.
4781
5585
 
4782
5586
 
4783
5587
  ### Optional chat report and block scene marker
@@ -4816,8 +5620,9 @@ Old clients ignore fit and draw the authored distance.
4816
5620
  A scene with `engine.hubInviteRail: true` adds **Invite a friend** to the existing
4817
5621
  Character menu in an invite-enabled town or House when the host's
4818
5622
  `Hub.canInvite` says yes for the trusted roster account: the account it names
4819
- (v1.146), or else `User.getCurrent()`, must be that player's own. A guest counts
4820
- like any over-13 player. Unresolved, missing or mismatched identity keeps it hidden. Inside games the entry is hidden. The entry uses the existing
5623
+ (v1.146), or else `User.getCurrent()`, must be that player's own. The v1.188
5624
+ gate read additionally requires an authenticated, non-anonymous viewer.
5625
+ Unresolved, missing or mismatched identity keeps it hidden. Inside games the entry is hidden. The entry uses the existing
4821
5626
  five-use share flow (`Hub.invite()`), including text derived from the root deck title, native
4822
5627
  Share gesture and explicit Copy link fallback. A server refusal shows “Sharing
4823
5628
  is unavailable here.” and does not retry minting. Existing arrival, follow, Undo
@@ -4825,9 +5630,14 @@ and reconnect behavior is unchanged.
4825
5630
 
4826
5631
  This marker adds no manifest key or kit contract version. It follows the existing
4827
5632
  House/win-chip capability checks; viewer eligibility remains enforced by the
4828
- trusted host and server when minting. It does not claim to read the viewer's
4829
- feature gate before rendering. Without the marker the Character menu has no
4830
- Invite row and makes no additional host requests.
5633
+ trusted host and server when minting. As of v1.188, it also reads the viewer's
5634
+ feature gate through `Hub.inviteAvailable()` and requires the exact answer
5635
+ `{ status: 'ok', available: true }` before rendering. This read is attempted at
5636
+ most once per connection, scene and identity lifetime, without retries. Pending,
5637
+ false, unavailable and failed answers keep the entry hidden; old hosts hide it.
5638
+ A scene, connection or identity change fences both the answer and a stale pick.
5639
+ Without the marker the Character menu has no Invite row and makes no additional
5640
+ host requests.
4831
5641
 
4832
5642
  The Character sheet and the invite dialog fit the viewport with or without the
4833
5643
  marker: the sheet sits fixed over the right-side lane, capped to the height
@@ -4899,6 +5709,13 @@ error/retry controls; restarting restores the cover. WebGL context
4899
5709
  loss or a no-op draw cannot clear it. Intentional session exits and terminal
4900
5710
  join failures leave existing recovery controls accessible. Both the ordinary and play-only entries support it;
4901
5711
  the development editor does not draw it.
5712
+ Client side (no version): a return under a new player id also waits, at most
5713
+ 6 s, for the place's arrival to place the player (`hub-arrived`, then the
5714
+ clamped row), so a restored `resumePose` and its HUD land under the cover.
5715
+ A return's cover (any raised after the first load's lifted) shows no title,
5716
+ words or spinner while the page is hidden and for 2.5 s after it shows again,
5717
+ then "Reconnecting…" with the spinner; the multiplayer kit's own cover is quiet
5718
+ the same way.
4902
5719
 
4903
5720
  This is a deck-level, client-only boolean, with no new wire fields. Absent or
4904
5721
  false preserves existing drawing and connection behavior. Older kits retain
@@ -5043,13 +5860,26 @@ Tests: `scripts/test-menu.mjs`, `scripts/test-menu-client.mjs`.
5043
5860
  anyone who chatted or emoted at this player in the last 10 s. Not-drawn bystanders keep their
5044
5861
  state and appear when they come nearer. The server still sends every player (no wire change in
5045
5862
  v1.137); a server-side cap is a later version.
5863
+ v1.168: a not-drawn bystander's `hub.mark` tag and role label are not drawn either (the
5864
+ v1.162 carer rule for labels); they come back with the avatar. The player's own are always drawn.
5865
+ v1.170: nor is its name tag (the multiplayer kit's sprite over the body); it comes back with the
5866
+ avatar, and the player's own is untouched. Name tags do not count under `quality.low.labels`.
5046
5867
  - quality.low.labels (0-30): nearest world labels shown on Low. Never capped: pointers (quest, door,
5047
5868
  home arrows) and the player's own party. The labels kit's three-nearest-door rule still wins inside
5048
5869
  its 12/14 m; door labels admitted by that rule are exempt and consume no quality slots.
5870
+ v1.168: `hub.mark` tags and role labels count too, ranked with the world labels by their avatar's
5871
+ distance and drawn after them; the player's own and their party's consume no slots. The native
5872
+ engine does not apply either v1.168 rule yet (a later port).
5049
5873
  - quality.low.spawned (0-64): caps only hub.spawn templates that declare "decor": true; a Low client
5050
5874
  builds those nearest first and the rest when they come within range. Templates without it are
5051
5875
  gameplay (gems, tiles, pickups) and a Low client builds every one. A cap on a deck with no decor
5052
5876
  templates is a no-op and logs a warning, not an error. The server and other clients are unaffected.
5877
+ v1.197: the cap also holds in a game reached through the Town's door, under the Town's
5878
+ `quality.low.spawned` (the game's own manifest supplies none). Such a game marks its decorative
5879
+ templates `"decor": true` in its scene as here; its server, having no quality block, names them in
5880
+ `hubDecorTpl` instead of in the templates' components, so an older client ignores them and draws
5881
+ every copy. A Town without `hub.quality`, a High client, or a game with no decor template builds
5882
+ every copy as before. Hide the template itself at `ready` (it is drawn where it is parked otherwise).
5053
5883
  - quality.low.farMindsHz (1-60): per-frame NPC talk and prompt work for far NPCs runs at this rate on
5054
5884
  Low. Far = past lowActorDistance and not within talk range of this player and not in a
5055
5885
  conversation with this player, so a line caused by the player's own action shows at once.
@@ -5063,8 +5893,9 @@ Tests: `scripts/test-menu.mjs`, `scripts/test-menu-client.mjs`.
5063
5893
  High to Low hides (no teardown). A device never rises on its own, as today.
5064
5894
  - **What never differs by tier** (unchanged from hub.tiers): pads, doors, colliders, positions,
5065
5895
  physics, server state, what other players see you do. Everything in hub.quality is client-only.
5066
- - Telemetry: quality telemetry is deferred. The client exposes "skip" | "hide" at
5067
- `__hub.tier.quality`; the fps report (v1.132) keeps its existing payload.
5896
+ - Telemetry (v1.178): the fps report (v1.132) optionally carries `quality: "hide" | "skip"`
5897
+ for active Low mode; absent quality or High omits the key. `__hub.tier.quality`
5898
+ also exposes the configured mode locally.
5068
5899
  - Gate (seat, added to qa-standards): a Low client in a door round sees every gameplay spawn and
5069
5900
  every pad, door and collider at the same position as a High client, proved by one Gem Rush round on
5070
5901
  the TECNO on Low against a Metal High partner.
@@ -5093,11 +5924,13 @@ server script source to discover targets. Computed ids, aliased
5093
5924
  APIs and arbitrary helpers cannot be proved by the kit's current source checks;
5094
5925
  mark such targets `"tier": "keep"` (or choose decor `"hide"`).
5095
5926
 
5096
- Quality telemetry is deferred: Ghost owns the FPS variants map and overwrites
5097
- caller flags with owner/guest attribution. No caller field preserves quality
5098
- without changing the existing measurement meanings. The v1.132 FPS message and
5099
- kind-26 record remain unchanged. Opted-in clients expose `__hub.tier.quality`
5100
- (`"skip"` or `"hide"`) for local inspection and a later telemetry version.
5927
+ v1.178: the v1.132 `hub-fps` message optionally carries `quality: "hide" | "skip"`
5928
+ for the deck's active `hub.quality` Low mode at the end of the window. Other
5929
+ values refuse the report. The kit sends kind 26 with `quality: 1` for hide or
5930
+ `quality: 2` for skip; absent sends no quality key and preserves existing bytes.
5931
+ Flags stay 0; median, p10, tier, avatars and final are unchanged. Ghost stores
5932
+ variant `hub:quality` alongside existing variants. Ghost must carry v1.178
5933
+ (live); an older Ghost refuses the unknown key.
5101
5934
 
5102
5935
  Tests: `scripts/test-quality.mjs`, plus the existing tiers, manifest, avatars,
5103
5936
  labels, NPCs, actors and FPS telemetry tests.
@@ -5145,3 +5978,13 @@ an eight-slot emote wheel with paged extras, five RP basics, sit-anywhere
5145
5978
  emotes granted per visit with `hub.emotesFor`. Definitions are public; grants
5146
5979
  are private and sent only on change. Absent expression preserves the old
5147
5980
  five-emote picker, behavior and wire bytes. See §6 for bounds and lifecycle.
5981
+
5982
+ ### v1.163 private ghost replay
5983
+
5984
+ `hub.record` and `hub.replay` (§10) add server-authoritative bounded traces and
5985
+ kit-owned private playback. `hub-replay` (§12) goes only to its viewer; no actor,
5986
+ body, shared state, host storage or manifest key. Any disconnect, including a
5987
+ retained short drop, invalidates recording and clears ghosts. Resume may
5988
+ explicitly reissue playback with elapsed `offsetMs`, never continue recording.
5989
+ Recordings over 600000 ms are invalidated even in longer-duration places.
5990
+ Friend privacy remains the deck's responsibility through friendBests/friendsAmong.