castle-web-cli 0.4.229 → 0.4.231

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 (259) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +860 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -0,0 +1,151 @@
1
+ # The hub content pack
2
+
3
+ **Format 1** (2026-10-02). What lets a door lead to a separately published deck:
4
+ the hub game's client half as **data**, versioned and content-addressed, paired
5
+ with the server bundle it was published beside, and mounted by the town's engine
6
+ without evaluating anything the game shipped. Design: `cauldron-game-server`
7
+ `docs/HUB.md` (decision 2, "Doors: the handoff", Trust and safety tier 0). Feasibility
8
+ and file pointers: `docs/internal/hub-door-spike.md` (door spike branch).
9
+
10
+ A published deck's HTML is not that: it carries the engine, the behavior and system
11
+ registries (populated eagerly by the deck's own code) and the entry, so mounting
12
+ it means running it. The pack is a second artifact beside the HTML and the server
13
+ bundle.
14
+
15
+ ## The document
16
+
17
+ One JSON document; its identity is the SHA-256 of its bytes (lower-case hex), the
18
+ **pack hash**. The CLI writes it canonically (object keys sorted, no whitespace,
19
+ `cli/src/contentPack.ts`), so the same content always hashes the same.
20
+
21
+ ```jsonc
22
+ {
23
+ "format": "castle.hub-pack",
24
+ "version": 1, // this document's format; the engine refuses one it does not know
25
+ "contract": 1, // the hub contract the deck declared (hub.contract)
26
+ "kit": { "alias": "castle.hub-game", "version": "<import version or builtin kit version>" },
27
+ "engine": { "castle.physics-3d": "<version>", … }, // the import pins the content was authored against
28
+ "places": { "main": { /* the place's public manifest */ }, "race": { … } },
29
+ "files": { "scenes/main.scene": { "sha256": "…", "text": "…" }, … },
30
+ "media": { "drawings/sky.png": { "sha256": "…", "type": "image/png", "base64": "…" } },
31
+ "audio": { "sounds/horn.wav": { "sha256": "…", "type": "audio/wav", "base64": "…" } } // optional (2026-10-03)
32
+ }
33
+ ```
34
+
35
+ - **`places`** are the deck's places as `readManifest` reads them (contract §1, §3):
36
+ title, scene, players, arrival, result, sign. The town reads a destination's
37
+ numbers from here, not from the door.
38
+ - **`files`** are the text files the places draw: each place's scene, then
39
+ everything those name, followed to a fixed point — blueprints, `.pxmodel` models
40
+ and the models they reference, `.pxart`/`.sprite` art, images. Paths are the
41
+ deck's own (`scenes/main.scene`, `imports/castle.physics-3d/models/crate.pxmodel`),
42
+ so nothing inside a file is rewritten. Every entry carries its own SHA-256: the
43
+ engine keys parse caches by it, so the same model in two packs, or in two
44
+ releases of one, parses once.
45
+ - **`media`** are images only (`png jpg jpeg gif webp`), inline as base64 in
46
+ format 1. Video is not part of Tier 0 v1.
47
+ - **`audio`** (optional, added 2026-10-03 without a new pack version) are the
48
+ place's sounds: exactly the files the places' `idle.sounds` list (contract
49
+ v1.6, §6), and nothing else, inline as base64 with their type by lower-case
50
+ extension (`.mp3` `audio/mpeg`, `.wav` `audio/wav`, `.m4a` `audio/mp4`). The
51
+ validator refuses a file no place lists. The town's engine hands them to the
52
+ place as `data:` URLs (`content.audio`), and a place mounted from a pack plays
53
+ only these, never the town's own files. A pack with no sounds has no `audio`
54
+ key and is byte for byte what it was. It is a new key rather than more
55
+ `media`, and the version stays 1, because older readers ignore keys they do
56
+ not know: an older town engine's validator (`validatePack` reads only
57
+ `files`, `media` and `places`) and ghost's (which checks only that `files`,
58
+ `media` and `engine` are objects) both accept such a pack, and the game is
59
+ silent on that town, as it was before. An older engine would refuse an
60
+ audio type inside `media`.
61
+ - **Never in a pack:** code of any kind (`.js`/`.jsx`/`.ts`, behaviors, systems,
62
+ HTML), `castle.json` beyond `places`, the avatar blueprints (the town's engine
63
+ draws every player as its platform avatar, contract §11), `theme.style`.
64
+
65
+ Budgets (the exporter refuses, the engine refuses again): 4 MB per pack, 600
66
+ files (text, media and audio together), 3 MB of media, 1 MB of audio and 256 KB
67
+ per sound (the check's sound budget, inside the 4 MB), 1 MB and 1500 actors per
68
+ scene (the check's scene budget),
69
+ paths `[A-Za-z0-9_./@-]`, no `..`, no leading `/`.
70
+
71
+ ## Who makes it
72
+
73
+ The kit, never the CLI: `castle.json` → `"onPack": "scripts/pack.mjs"` beside
74
+ `onCheck`. The CLI knows only that an import may export a **content pack** — a
75
+ data artifact it hashes, budgets, stores and publishes — not what is in one.
76
+ `scripts/pack.mjs` default-exports `pack({ deckDir, self, outFile })`, writes the
77
+ pack to `outFile` and returns `{ errors, summary }`; it runs after every check
78
+ passes. `code/client/packFormat.js` holds the format's version, budgets and the
79
+ one validator the exporter and the engine both run.
80
+
81
+ - `castle-web check` builds the pack too, so a deck that cannot pack fails before
82
+ anyone publishes it.
83
+ - `castle-web save-deck` builds it, writes it to `.castle/content-pack/<hash>.json`
84
+ and publishes it **with the server bundle** (below).
85
+
86
+ ## Paired release
87
+
88
+ A running game session keeps the server bundle it started with, and its content
89
+ must match (HUB.md, Version pinning). So the pack rides the server bundle's own
90
+ publish: `saveCauldronServerBundle(deckId, uploadId, config, contentPackUploadId)`.
91
+ Ghost writes the server bundle and the pack's hash into one row in one statement,
92
+ so a release is one id naming both, activated atomically; a failed upload leaves
93
+ the previous release whole. The client HTML still publishes separately, but the
94
+ hub never loads it — a door loads the pack.
95
+
96
+ Ghost does not take a pack yet (child card filed off the hub design card). Until it
97
+ does, `save-deck` builds and stores the pack locally and says the pairing was not
98
+ published; nothing else about publishing changes. When ghost has it:
99
+
100
+ | ghost | what |
101
+ | --- | --- |
102
+ | `createCauldronContentPackUploadConfig(deckId)` | a presigned POST like the server bundle's |
103
+ | `saveCauldronServerBundle(…, contentPackUploadId)` | reads the upload, hashes it, checks `format`/`version`, the 4 MB cap and that `places` parses; stores it immutable at `content-packs/<hash>.json` (public CDN, `Access-Control-Allow-Origin: *`, `Cache-Control: immutable`), and writes `content_pack_sha256` + `{contract, kit}` on the bundle row with the server bundle; returns `contentPackSha256` |
104
+ | `CauldronHubHandoff.bundleHash` | **the destination release's pack hash** (was: the server bundle's sha256), plus `contentUrl`, that pack's immutable URL. A destination release with no pack is `unavailable`: it is not a hub game |
105
+ | `cauldron_hub_doors.kit_version` | the contract version the door was curated against (`"1"`); acquisition is `unavailable` when the destination's current pack names another contract, so an engine upgrade that would break older content shuts the door instead of mounting it |
106
+
107
+ The pinned session's row names its pack, so a republish mid-visit changes nothing
108
+ for players already inside, and `Hub.back()` into a pad instance still pinned to the
109
+ old release loads the old pack (from cache).
110
+
111
+ ## Mounting it
112
+
113
+ The town's engine is the one that runs; the pack is data it reads (Tier 0).
114
+
115
+ 1. **Resolve.** On a door, the hub client asks the host for the destination
116
+ (`Hub.go`; on `castle-web serve`, the dev resolver below) and gets
117
+ `{ bundleHash, contentUrl, … }`.
118
+ 2. **Fetch and verify.** The bytes are fetched, hashed (`crypto.subtle`), and refused
119
+ unless the hash is `bundleHash`. A verified pack is cached by hash for the page's
120
+ life (at most 3 packs; the oldest not in use is dropped).
121
+ 3. **Validate** (`code/client/pack.js`): format and contract versions this engine
122
+ reads, the budgets above, every place's scene present and JSON, every file JSON
123
+ where it must be, component names `[A-Z][A-Za-z0-9]*`. The engine's behavior
124
+ registry is fixed: a component naming one of its behaviors runs that behavior
125
+ with the props as data; any other component is inert data (a server reads it).
126
+ Nothing in a pack is evaluated.
127
+ 4. **Mount** under the door's cover: the runtime's content is swapped for the
128
+ pack's (`runtime.requestedContent`, physics-3d) together with its scene, so its
129
+ paths never meet the town's — two decks' `scenes/main.scene` and their import
130
+ aliases stay apart. The engine's own avatar files are laid over the pack's.
131
+ 5. **Unmount** is the same swap back. Scene nodes are released (or parked, for the
132
+ town the player will walk back into: `residentScenes` keys are content-qualified),
133
+ shared model builds are released by reference count, and the pack's file map,
134
+ sprites and media URLs go with the content object. A failure at 1-3 keeps the
135
+ door shut: nobody left, the cover lifts on the town.
136
+
137
+ ## On `castle-web serve`
138
+
139
+ The dev serve is the door table and ghost for one machine. A town lists the
140
+ decks beside it it may reach, by name, in `castle.json` → `devDecks`
141
+ (`{ "race": "../hub-race" }`), and a `HubDoor` actor whose `to` is `deck:race`
142
+ leads there (the door's own `title`, `minPlayers`, `maxPlayers`, `lateJoin` say who
143
+ may go through, as the door table's row will). Going through, the client asks the
144
+ serve (`GET /__castle/content-pack/resolve?deck=race`); the serve builds that
145
+ deck's pack with its own kit's `onPack`, serves it at
146
+ `/__castle/content-pack/<hash>.json`, and runs that deck's server for sessions
147
+ keyed `deck:race/hub.main.<instance>`. So the trip is the production shape — a
148
+ different deck's server, its content mounted by hash — with the serve standing in
149
+ for ghost, and only for decks the town's author listed. Editing the destination
150
+ deck takes effect on the next trip (a new pack hash). `experiments/hub-town` and
151
+ `experiments/hub-race` are the worked example.