castle-web-cli 0.4.156 → 0.4.158

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 (243) hide show
  1. package/dist/agent-failures.d.ts +1 -0
  2. package/dist/agent-failures.js +6 -4
  3. package/dist/agent-prompts.js +4 -0
  4. package/dist/agent.d.ts +11 -0
  5. package/dist/agent.js +175 -15
  6. package/dist/bundle.js +8 -2
  7. package/dist/castle-host/host.js +114 -8
  8. package/dist/castleJson.js +6 -1
  9. package/dist/check.d.ts +1 -0
  10. package/dist/check.js +25 -0
  11. package/dist/devSessionServer.js +31 -7
  12. package/dist/imports.js +1 -19
  13. package/dist/index.js +15 -1
  14. package/dist/init.d.ts +2 -2
  15. package/dist/init.js +78 -42
  16. package/dist/mcpPlaytest.d.ts +1 -0
  17. package/dist/mcpPlaytest.js +182 -0
  18. package/dist/metering.d.ts +24 -0
  19. package/dist/metering.js +87 -0
  20. package/dist/sdkResolve.d.ts +3 -0
  21. package/dist/sdkResolve.js +55 -0
  22. package/dist/serve.js +50 -4
  23. package/dist/serverBundle.js +8 -3
  24. package/dist/shell/assets/{index-DsDkYFvP.js → index-BuSYLy-C.js} +64 -64
  25. package/dist/shell/assets/{index-DwezawBs.css → index-DfZmu3XC.css} +1 -1
  26. package/dist/shell/index.html +2 -2
  27. package/dist/vitePlugins.d.ts +1 -0
  28. package/dist/vitePlugins.js +20 -0
  29. package/kits/base/CLAUDE.md +196 -0
  30. package/kits/{blank → base}/castle.json +5 -2
  31. package/kits/base/editorHost.js +172 -0
  32. package/kits/{blank → base}/node_modules/.package-lock.json +3 -2
  33. package/kits/{blank → base}/package-lock.json +7 -4
  34. package/kits/{blank → base}/package.json +4 -2
  35. package/kits/base/sdk/README.md +569 -0
  36. package/kits/base/sdk/castle.d.ts +27 -0
  37. package/kits/base/sdk/castle.js +16 -0
  38. package/kits/base/sdk/commands.d.ts +181 -0
  39. package/kits/base/sdk/commands.js +16 -0
  40. package/kits/base/sdk/context.d.ts +17 -0
  41. package/kits/base/sdk/context.js +15 -0
  42. package/kits/base/sdk/errors.d.ts +22 -0
  43. package/kits/base/sdk/errors.js +16 -0
  44. package/kits/base/sdk/files.d.ts +15 -0
  45. package/kits/base/sdk/files.js +52 -0
  46. package/kits/base/sdk/haptics.d.ts +6 -0
  47. package/kits/base/sdk/haptics.js +36 -0
  48. package/kits/base/sdk/leaderboard.d.ts +26 -0
  49. package/kits/base/sdk/leaderboard.js +296 -0
  50. package/kits/base/sdk/lifecycle.d.ts +4 -0
  51. package/kits/base/sdk/lifecycle.js +13 -0
  52. package/kits/base/sdk/multiplayer.d.ts +43 -0
  53. package/kits/base/sdk/multiplayer.js +464 -0
  54. package/kits/base/sdk/multiplayerProtocol.d.ts +51 -0
  55. package/kits/base/sdk/multiplayerProtocol.js +5 -0
  56. package/kits/base/sdk/passes.d.ts +7 -0
  57. package/kits/base/sdk/passes.js +84 -0
  58. package/kits/base/sdk/portal.d.ts +7 -0
  59. package/kits/base/sdk/portal.js +35 -0
  60. package/kits/base/sdk/runtime.d.ts +62 -0
  61. package/kits/base/sdk/runtime.js +970 -0
  62. package/kits/base/sdk/saveQueue.d.ts +27 -0
  63. package/kits/base/sdk/saveQueue.js +205 -0
  64. package/kits/base/sdk/server/platformHandle.d.ts +25 -0
  65. package/kits/base/sdk/server/platformHandle.js +1 -0
  66. package/kits/base/sdk/server/wrapper.d.ts +28 -0
  67. package/kits/base/sdk/server/wrapper.js +109 -0
  68. package/kits/base/sdk/storage.d.ts +16 -0
  69. package/kits/base/sdk/storage.js +323 -0
  70. package/kits/base/sdk/time.d.ts +17 -0
  71. package/kits/base/sdk/time.js +120 -0
  72. package/kits/base/sdk/transport.d.ts +17 -0
  73. package/kits/base/sdk/transport.js +141 -0
  74. package/kits/base/sdk/types.d.ts +3 -0
  75. package/kits/base/sdk/types.js +1 -0
  76. package/kits/base/sdk/user.d.ts +10 -0
  77. package/kits/base/sdk/user.js +45 -0
  78. package/kits/multiplayer-2d/.prettierrc +5 -0
  79. package/kits/multiplayer-2d/CLAUDE.md +129 -0
  80. package/kits/multiplayer-2d/behaviors/Box.jsx +92 -0
  81. package/kits/multiplayer-2d/behaviors/Player.jsx +86 -0
  82. package/kits/multiplayer-2d/blueprints/crate.scene +13 -0
  83. package/kits/multiplayer-2d/blueprints/other-player.scene +13 -0
  84. package/kits/multiplayer-2d/blueprints/player.scene +15 -0
  85. package/kits/multiplayer-2d/blueprints/wall.scene +12 -0
  86. package/kits/multiplayer-2d/castle.json +39 -0
  87. package/kits/multiplayer-2d/code/client/avatars.js +79 -0
  88. package/kits/multiplayer-2d/code/client/poses.js +168 -0
  89. package/kits/multiplayer-2d/code/server/index.js +26 -0
  90. package/kits/multiplayer-2d/code/server/limits.js +99 -0
  91. package/kits/multiplayer-2d/code/server/ownership.js +177 -0
  92. package/kits/multiplayer-2d/code/server/players.js +127 -0
  93. package/kits/multiplayer-2d/code/server/sceneBodies.js +98 -0
  94. package/kits/multiplayer-2d/code/server/world.js +337 -0
  95. package/kits/multiplayer-2d/code/systems/multiplayer.js +424 -0
  96. package/kits/multiplayer-2d/eslint.config.js +21 -0
  97. package/kits/multiplayer-2d/fonts.generated.js +9 -0
  98. package/kits/multiplayer-2d/index.html +25 -0
  99. package/kits/multiplayer-2d/main.jsx +10 -0
  100. package/kits/multiplayer-2d/package-lock.json +351 -0
  101. package/kits/multiplayer-2d/package.json +30 -0
  102. package/kits/multiplayer-2d/scenes/main.scene +20 -0
  103. package/kits/multiplayer-2d/test/two-client-test.mjs +341 -0
  104. package/kits/multiplayer-2d/theme.style +4 -0
  105. package/kits/multiplayer-3d/.prettierrc +5 -0
  106. package/kits/multiplayer-3d/CLAUDE.md +215 -0
  107. package/kits/multiplayer-3d/blueprints/ball.scene +21 -0
  108. package/kits/multiplayer-3d/blueprints/other-player.scene +21 -0
  109. package/kits/multiplayer-3d/castle.json +43 -0
  110. package/kits/multiplayer-3d/code/client/avatars.js +136 -0
  111. package/kits/multiplayer-3d/code/client/nameTags.js +101 -0
  112. package/kits/multiplayer-3d/code/client/poses.js +220 -0
  113. package/kits/multiplayer-3d/code/server/index.js +23 -0
  114. package/kits/multiplayer-3d/code/server/limits.js +107 -0
  115. package/kits/multiplayer-3d/code/server/ownership.js +157 -0
  116. package/kits/multiplayer-3d/code/server/players.js +114 -0
  117. package/kits/multiplayer-3d/code/server/sceneBodies.js +88 -0
  118. package/kits/multiplayer-3d/code/server/world.js +306 -0
  119. package/kits/multiplayer-3d/code/systems/multiplayer.js +427 -0
  120. package/kits/multiplayer-3d/eslint.config.js +20 -0
  121. package/kits/multiplayer-3d/fonts.generated.js +9 -0
  122. package/kits/multiplayer-3d/index.html +22 -0
  123. package/kits/multiplayer-3d/main.jsx +9 -0
  124. package/kits/multiplayer-3d/package-lock.json +368 -0
  125. package/kits/multiplayer-3d/package.json +32 -0
  126. package/kits/multiplayer-3d/scenes/main.scene +409 -0
  127. package/kits/multiplayer-3d/theme.style +3 -0
  128. package/kits/physics-2d/CLAUDE.md +6 -0
  129. package/kits/physics-2d/castle.json +7 -1
  130. package/kits/physics-2d/editors/behaviorRegistry.js +5 -0
  131. package/kits/physics-2d/editors/editorRegistry.jsx +3 -1
  132. package/kits/physics-2d/engine/files.js +9 -5
  133. package/kits/physics-2d/engine/systemRegistry.js +2 -0
  134. package/kits/physics-2d/engine/ui.module.css +11 -0
  135. package/kits/physics-2d/package-lock.json +8 -2
  136. package/kits/physics-2d/package.json +2 -2
  137. package/kits/physics-3d/CLAUDE.md +4 -4
  138. package/kits/physics-3d/behaviors/Shape.jsx +1 -1
  139. package/kits/physics-3d/blueprints/crate.scene +1 -1
  140. package/kits/physics-3d/blueprints/door.scene +4 -4
  141. package/kits/physics-3d/blueprints/pillar.scene +1 -1
  142. package/kits/physics-3d/blueprints/platform.scene +1 -1
  143. package/kits/physics-3d/blueprints/statue.scene +1 -1
  144. package/kits/physics-3d/blueprints/wall.scene +1 -1
  145. package/kits/physics-3d/castle.json +8 -11
  146. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  147. package/kits/physics-3d/engine3d/materials.js +3 -3
  148. package/kits/physics-3d/engine3d/modelFiles.js +4 -2
  149. package/kits/physics-3d/engine3d/world3d.js +1 -1
  150. package/kits/physics-3d/fonts.generated.js +9 -0
  151. package/kits/physics-3d/main.jsx +1 -1
  152. package/kits/physics-3d/package-lock.json +85 -2
  153. package/kits/physics-3d/package.json +6 -2
  154. package/kits/physics-3d/scenes/main.scene +1 -1
  155. package/kits/physics-3d/scenes/model-lab.scene +1 -1
  156. package/kits/real-time/.prettierrc +5 -0
  157. package/kits/real-time/CLAUDE.md +60 -0
  158. package/kits/real-time/castle.json +19 -0
  159. package/kits/real-time/code/client/clock.js +68 -0
  160. package/kits/real-time/code/client/connection.js +134 -0
  161. package/kits/real-time/code/client/gameHooks.js +50 -0
  162. package/kits/real-time/code/client/interpolate.js +82 -0
  163. package/kits/real-time/code/client/messages.js +55 -0
  164. package/kits/real-time/code/client/ownership.js +94 -0
  165. package/kits/real-time/code/client/smooth.js +54 -0
  166. package/kits/real-time/code/server/blockDelta.js +48 -0
  167. package/kits/real-time/code/server/gameHooks.js +47 -0
  168. package/kits/real-time/code/server/limits.js +35 -0
  169. package/kits/real-time/code/server/session.js +251 -0
  170. package/kits/real-time/eslint.config.js +22 -0
  171. package/kits/real-time/index.html +45 -0
  172. package/kits/real-time/package.json +14 -0
  173. package/kits/{tabletop → turn-based}/CLAUDE.md +42 -49
  174. package/kits/turn-based/blueprints/board.scene +15 -0
  175. package/kits/turn-based/blueprints/square.scene +25 -0
  176. package/kits/turn-based/castle.json +37 -0
  177. package/kits/turn-based/code/behaviors/Board.jsx +169 -0
  178. package/kits/turn-based/code/behaviors/Square.jsx +26 -0
  179. package/kits/turn-based/code/server/index.js +152 -0
  180. package/kits/turn-based/drawings/square.sprite +25 -0
  181. package/kits/turn-based/eslint.config.js +12 -0
  182. package/kits/turn-based/fonts.generated.js +9 -0
  183. package/kits/{tabletop → turn-based}/index.html +5 -3
  184. package/kits/{tabletop → turn-based}/main.jsx +2 -2
  185. package/kits/{tabletop → turn-based}/package-lock.json +17 -4
  186. package/kits/{tabletop → turn-based}/package.json +5 -2
  187. package/kits/turn-based/room.js +289 -0
  188. package/kits/turn-based/scenes/main.scene +227 -0
  189. package/kits/{tabletop → turn-based}/testing.js +131 -99
  190. package/kits/turn-based/theme.style +3 -0
  191. package/package.json +1 -1
  192. package/kits/blank/CLAUDE.md +0 -198
  193. package/kits/tabletop/castle.json +0 -34
  194. package/kits/tabletop/room.js +0 -269
  195. /package/kits/{blank → base}/index.html +0 -0
  196. /package/kits/{blank → base}/node_modules/castle-web-fonts/README.md +0 -0
  197. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.d.ts +0 -0
  198. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.js +0 -0
  199. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.d.ts +0 -0
  200. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.js +0 -0
  201. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +0 -0
  202. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.js +0 -0
  203. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +0 -0
  204. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +0 -0
  205. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +0 -0
  206. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.js +0 -0
  207. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +0 -0
  208. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.js +0 -0
  209. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +0 -0
  210. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +0 -0
  211. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +0 -0
  212. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +0 -0
  213. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +0 -0
  214. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.js +0 -0
  215. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +0 -0
  216. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.js +0 -0
  217. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +0 -0
  218. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.js +0 -0
  219. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.d.ts +0 -0
  220. /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.js +0 -0
  221. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +0 -0
  222. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/FONTS.md +0 -0
  223. /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +0 -0
  224. /package/kits/{blank → base}/node_modules/castle-web-fonts/package.json +0 -0
  225. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  226. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  227. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  228. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  229. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  230. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  231. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/SOURCE.txt +0 -0
  232. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  233. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  234. /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  235. /package/kits/physics-3d/drawings/{crate.pxart → crate.sprite} +0 -0
  236. /package/kits/physics-3d/drawings/{door-edge.pxart → door-edge.sprite} +0 -0
  237. /package/kits/physics-3d/drawings/{door.pxart → door.sprite} +0 -0
  238. /package/kits/physics-3d/drawings/{face.pxart → face.sprite} +0 -0
  239. /package/kits/physics-3d/drawings/{floor.pxart → floor.sprite} +0 -0
  240. /package/kits/physics-3d/drawings/{platform.pxart → platform.sprite} +0 -0
  241. /package/kits/physics-3d/drawings/{statue.pxart → statue.sprite} +0 -0
  242. /package/kits/physics-3d/drawings/{wall.pxart → wall.sprite} +0 -0
  243. /package/kits/{tabletop → turn-based}/.prettierrc +0 -0
@@ -1,64 +1,56 @@
1
- // Everything a deck needs to test its server from a plain node script: a
2
- // `MultiplayerServerSession` double, a movable clock, the room conformance
3
- // suite, and the resolver hook that makes `@imports/` mean the same thing under
4
- // `node` as it does in the deck.
1
+ // Test support for a deck's server: a `MultiplayerServerSession` double, a
2
+ // movable clock, the room conformance suite, and an `@imports/` resolver hook.
5
3
  //
6
- // Run it from the deck directory, with this file as the `--import`:
4
+ // Run from the deck directory with this file as the `--import`:
7
5
  //
8
- // node --import ./imports/castle.tabletop/testing.js tools/check.mjs
9
- //
10
- // See "the @imports resolver" below for why that flag is needed at all.
6
+ // node --import ./imports/castle.turn-based/testing.js tools/check.mjs
11
7
 
12
8
  import { register } from 'node:module';
13
9
  import * as path from 'node:path';
14
10
  import { pathToFileURL } from 'node:url';
15
- import { restoreNow, setNow } from './room.js';
11
+ import * as Room from './room.js';
16
12
 
17
13
  // --- the @imports resolver ------------------------------------------------
18
14
  //
19
- // `@imports/<alias>/...` is a Castle specifier: the CLI's vite plugin rewrites
20
- // it to `<deck root>/imports/<alias>/...` for the dev server and for both
21
- // bundlers. A deck's test script is neither -- it is `node tools/check.mjs` --
22
- // so without this hook a server module written the blessed way cannot be
23
- // imported by the tests that are supposed to check it, and the deck ends up
24
- // with a relative path in production to keep node happy.
15
+ // `@imports/<alias>/...` is a Castle specifier. The CLI's vite plugin rewrites
16
+ // it to `<deck root>/imports/<alias>/...` for the dev server and both bundlers,
17
+ // but a test script runs under plain node, which does not. This hook does the
18
+ // same rewrite there.
25
19
  //
26
- // The deck root is the working directory, which is the deck's own directory
27
- // when its scripts run from `package.json`. `CASTLE_DECK_ROOT` overrides it.
20
+ // The deck root is the working directory, which is the deck's own directory when
21
+ // its scripts run from `package.json`. `CASTLE_DECK_ROOT` overrides it.
28
22
 
29
23
  const IMPORTS_PREFIX = '@imports/';
30
24
 
31
25
  export async function resolve(specifier, context, nextResolve) {
32
- if (!specifier.startsWith(IMPORTS_PREFIX)) return nextResolve(specifier, context);
26
+ if (!specifier.startsWith(IMPORTS_PREFIX)) {
27
+ return nextResolve(specifier, context);
28
+ }
33
29
  const root = process.env.CASTLE_DECK_ROOT ?? process.cwd();
34
30
  const target = path.join(root, 'imports', specifier.slice(IMPORTS_PREFIX.length));
35
31
  return nextResolve(pathToFileURL(target).href, context);
36
32
  }
37
33
 
38
- // Registering this same module is what lets one `--import` do both jobs. Node
39
- // evaluates the file a second time inside its loader thread to read the hook;
40
- // that copy registers once more and stops there, and nothing here has a
41
- // top-level side effect for the second evaluation to duplicate.
34
+ // Registering this same module lets one `--import` do both jobs. Node evaluates
35
+ // the file a second time in its loader thread; that copy registers once more and
36
+ // stops. Nothing here has a top-level side effect to duplicate.
42
37
  register(import.meta.url);
43
38
 
44
39
  // --- the session double ---------------------------------------------------
45
40
  //
46
41
  // A stand-in for `MultiplayerServerSession`, so a deck's server callbacks can be
47
- // driven from a plain node script. It copies the real wrapper
48
- // (`sdk/src/server/wrapper.ts`) where the copying matters, because the details
49
- // it gets right are exactly the ones a room gets wrong:
42
+ // driven from a plain node script. It follows the real wrapper
43
+ // (`sdk/src/server/wrapper.ts`) on four points:
50
44
  //
51
- // - the joining player is in `session.players` BEFORE `onPlayerJoin` runs;
52
- // - the leaving player is OUT of it before `onPlayerLeave` runs;
53
- // - players are keyed by `playerId`, which is a connection, not an account --
54
- // two tabs of one account are two players;
55
- // - every message crosses as JSON, so a payload that holds a live reference to
56
- // the server's own state arrives as a copy, and one that cannot be
57
- // stringified throws here rather than in production.
45
+ // - the joining player is in `session.players` before `onPlayerJoin` runs;
46
+ // - the leaving player is out of it before `onPlayerLeave` runs;
47
+ // - players are keyed by `playerId`, which is a connection. Two tabs of one
48
+ // account are two players;
49
+ // - messages cross as JSON, so a payload holding a live reference to server
50
+ // state arrives as a copy, and an unstringifiable one throws here.
58
51
  //
59
- // It is not a transport: callbacks run synchronously, and a callback that
60
- // returns a promise is not awaited. That is enough for room and rule tests, and
61
- // a two-client game over the real socket is still the thing that proves a deck.
52
+ // It is not a transport. Callbacks run synchronously and a returned promise is
53
+ // not awaited; a two-client game over the real socket is the wider test.
62
54
 
63
55
  let sessionCounter = 0;
64
56
 
@@ -77,10 +69,13 @@ export function createSessionHarness(server, options = {}) {
77
69
  join: (playerId, identity) => joinPlayer(server, session, players, playerId, identity),
78
70
  leave: (player) => leavePlayer(server, session, players, player),
79
71
  message: (player, data) => messageFrom(server, session, players, player, data),
72
+
80
73
  // Every message this player has been sent, oldest first, already decoded.
81
- sent: (playerId) => outbox.filter((entry) => entry.playerId === playerId).map((e) => e.data),
82
- // The last one, optionally the last one matching a predicate -- a deck that
83
- // sends more than one kind of message asks for the kind it renders.
74
+ sent: (playerId) =>
75
+ outbox.filter((entry) => entry.playerId === playerId).map((entry) => entry.data),
76
+
77
+ // The last one, or the last one a test function accepts. A deck that sends
78
+ // several kinds of message asks for the kind it renders.
84
79
  last: (playerId, match) => lastSent(outbox, playerId, match),
85
80
  };
86
81
  harness.start();
@@ -101,21 +96,27 @@ function createSession(sessionId, options, players, outbox) {
101
96
  broadcast(data, broadcastOptions) {
102
97
  const encoded = encode(data);
103
98
  for (const playerId of players.keys()) {
104
- if (playerId !== broadcastOptions?.except) outbox.push({ playerId, data: encoded });
99
+ if (playerId !== broadcastOptions?.except) {
100
+ outbox.push({ playerId, data: encoded });
101
+ }
105
102
  }
106
103
  },
107
104
  disconnect(playerId) {
108
105
  const player = players.get(playerId);
109
- if (player) players.delete(playerId);
106
+ if (player) {
107
+ players.delete(playerId);
108
+ }
110
109
  return player ?? null;
111
110
  },
112
111
  };
113
112
  }
114
113
 
115
- // Messages cross the real transport as text, so they cross this one as text too.
116
- // Encoding per recipient would be truer still, but a broadcast that shared one
117
- // mutable object between players is the bug this is guarding against and one
118
- // copy already prevents it.
114
+ // Messages cross the real transport as text, so they cross this one as text
115
+ // too. A server that sends a live reference to its own state hands the test a
116
+ // copy, the same as production, and an unstringifiable payload throws here.
117
+ // A broadcast encodes once, not once per recipient. The bug this guards
118
+ // against is a broadcast handing every recipient one shared mutable object,
119
+ // and one copy is enough to prevent that.
119
120
  function encode(data) {
120
121
  const text = JSON.stringify(data);
121
122
  if (text === undefined) {
@@ -138,7 +139,9 @@ function joinPlayer(server, session, players, playerId, identity = {}) {
138
139
 
139
140
  function leavePlayer(server, session, players, player) {
140
141
  const known = players.get(player.playerId);
141
- if (!known) return null;
142
+ if (!known) {
143
+ return null;
144
+ }
142
145
  players.delete(player.playerId); // out of the roster before the callback
143
146
  server.onPlayerLeave?.(session, known);
144
147
  return known;
@@ -146,15 +149,27 @@ function leavePlayer(server, session, players, player) {
146
149
 
147
150
  function messageFrom(server, session, players, player, data) {
148
151
  const known = players.get(player.playerId);
149
- if (!known) return; // upstream drops messages from a connection it has closed
152
+
153
+ // The platform drops messages from a connection it has already closed, so a
154
+ // test that sends after a leave gets the same silence here.
155
+ if (!known) {
156
+ return;
157
+ }
158
+
150
159
  server.onMessage?.(session, known, encode(data));
151
160
  }
152
161
 
162
+ // Searched backwards, so the newest matching message wins. A deck usually sends
163
+ // several views to one player over a check.
153
164
  function lastSent(outbox, playerId, match) {
154
165
  for (let i = outbox.length - 1; i >= 0; i--) {
155
166
  const entry = outbox[i];
156
- if (entry.playerId !== playerId) continue;
157
- if (!match || match(entry.data)) return entry.data;
167
+ if (entry.playerId !== playerId) {
168
+ continue;
169
+ }
170
+ if (!match || match(entry.data)) {
171
+ return entry.data;
172
+ }
158
173
  }
159
174
  return null;
160
175
  }
@@ -162,20 +177,21 @@ function lastSent(outbox, playerId, match) {
162
177
  // A clock the kit's rooms read, that a test can move. `advance` is how a check
163
178
  // ages a table past an idle window without waiting minutes for it.
164
179
  export function createTestClock(startAt = Date.now()) {
165
- let t = startAt;
180
+ let time = startAt;
166
181
  const clock = {
167
- now: () => t,
182
+ now: () => time,
168
183
  advance: (ms) => {
169
- t += ms;
170
- return t;
184
+ time += ms;
185
+ return time;
171
186
  },
172
187
  set: (at) => {
173
- t = at;
174
- return t;
188
+ time = at;
189
+ return time;
175
190
  },
191
+
176
192
  // Point the kit's clock at this one, and back at the wall clock after.
177
- install: () => setNow(clock.now),
178
- uninstall: () => restoreNow(),
193
+ install: () => Room.setClock(clock.now),
194
+ uninstall: () => Room.setClock(null),
179
195
  };
180
196
  return clock;
181
197
  }
@@ -184,24 +200,25 @@ export function createTestClock(startAt = Date.now()) {
184
200
  //
185
201
  // The room rules, checked against a real deck's server.
186
202
  //
187
- // Every deck built on this kit should run these. They are the same rules for
188
- // everyone -- who gets a seat, what a drop does, what an arrival is handed --
189
- // so writing them once per deck only produces three chances to get them wrong.
190
- // The check named "a seated player dropping leaves the game standing" is the one
191
- // that matters most: it is the bug the kit exists to make unrepresentable, and
192
- // it shipped in a deck.
203
+ // Every deck built on this kit should run these. The rules are the same for
204
+ // every deck -- who gets a seat, what a drop does, what an arrival is handed --
205
+ // so they are checked once here instead of rewritten per deck.
206
+ //
207
+ // The check named "a seated player dropping leaves the game standing" covers
208
+ // the bug this kit was extracted to prevent. A shipped deck cleared the board
209
+ // when a seated player's connection dropped.
193
210
  //
194
211
  // The deck supplies four hooks, all small:
195
212
  //
196
- // play(harness, seated) make ONE move the server will accept, from
213
+ // play(harness, seated) make one move the server will accept, from
197
214
  // whichever seated player is allowed to make it.
198
215
  // Called more than once in a row.
199
216
  // junk(harness, player) send things the server must refuse: an illegal
200
217
  // move, a malformed body, an unknown type. It is
201
218
  // always called with `seated[0]`, who may not be
202
219
  // the side to move -- so every message in it has
203
- // to be one BOTH seats would be refused.
204
- // snapshot(harness, playerId) the PUBLIC game -- board, turn, counts, whose
220
+ // to be one that either seat would be refused.
221
+ // snapshot(harness, playerId) the public game -- board, turn, counts, whose
205
222
  // win. Not the seat list, the names, or the
206
223
  // watcher count, which change for reasons that
207
224
  // are not the game changing; and not a player's
@@ -214,22 +231,51 @@ export function createTestClock(startAt = Date.now()) {
214
231
 
215
232
  export function checkRoom(options) {
216
233
  const ctx = { ...options, minPlayers: options.minPlayers ?? options.seats, results: [] };
234
+
235
+ // The whole run happens on the movable clock, so the idle and grace windows
236
+ // pass in zero real time. The wall clock is restored even if a scenario throws.
217
237
  const clock = createTestClock();
218
238
  clock.install();
219
239
  try {
220
- for (const scenario of SCENARIOS) scenario(ctx, clock);
240
+ for (const scenario of SCENARIOS) {
241
+ scenario(ctx, clock);
242
+ }
221
243
  } finally {
222
244
  clock.uninstall();
223
245
  }
224
- return { results: ctx.results, failures: ctx.results.filter((r) => !r.ok).length };
246
+ return { results: ctx.results, failures: ctx.results.filter((result) => !result.ok).length };
225
247
  }
226
248
 
249
+ // The scenarios, in run order. Each is a plain function defined below; the
250
+ // names double as the printed check list.
251
+ const SCENARIOS = [
252
+ hooksWork,
253
+ seating,
254
+ twoTabsOfOneAccount,
255
+ dropDoesNotDestroy,
256
+ watcherIsPromoted,
257
+ reconnectKeepsItsSeat,
258
+ presentOutranksGhost,
259
+ reconnectAloneKeepsTheGame,
260
+ loneArrivalGetsACleanTable,
261
+ staleTableIsCleared,
262
+ recentTableIsKept,
263
+ coveredTableSurvivesALongThink,
264
+ refusedMessagesDoNotRefreshTheClock,
265
+ acceptedMovesDoRefreshTheClock,
266
+ partyTableIsNeverCleared,
267
+ namedBehavesLikePublic,
268
+ sessionsDoNotLeak,
269
+ ];
270
+
227
271
  // Prints one line per check and returns the failure count, so a deck's test
228
272
  // script is `process.exit(printRoomChecks(checkRoom({...})))`.
229
273
  export function printRoomChecks(outcome) {
230
- for (const r of outcome.results) {
231
- const detail = r.ok ? '' : `\n got ${json(r.actual)}\n want ${r.label}`;
232
- console.log(`${r.ok ? 'ok ' : 'FAIL'} ${r.name}${detail}`);
274
+ for (const result of outcome.results) {
275
+ const detail = result.ok
276
+ ? ''
277
+ : `\n got ${json(result.actual)}\n want ${result.label}`;
278
+ console.log(`${result.ok ? 'ok ' : 'FAIL'} ${result.name}${detail}`);
233
279
  }
234
280
  console.log(outcome.failures === 0 ? '\nroom checks passed' : `\n${outcome.failures} FAILED`);
235
281
  return outcome.failures;
@@ -257,7 +303,9 @@ let counter = 0;
257
303
  function seatedTable(ctx, mode = 'public') {
258
304
  const harness = createSessionHarness(ctx.server, { mode, sessionId: `check-${++counter}` });
259
305
  const seated = [];
260
- for (let i = 0; i < ctx.seats; i++) seated.push(harness.join(`${harness.sessionId}-p${i}`));
306
+ for (let i = 0; i < ctx.seats; i++) {
307
+ seated.push(harness.join(`${harness.sessionId}-p${i}`));
308
+ }
261
309
  return { harness, seated };
262
310
  }
263
311
 
@@ -284,12 +332,16 @@ function dropsToUncover(ctx) {
284
332
 
285
333
  function leaveSome(table, count) {
286
334
  const gone = table.seated.slice(-count);
287
- for (const player of gone) table.harness.leave(player);
335
+ for (const player of gone) {
336
+ table.harness.leave(player);
337
+ }
288
338
  return gone;
289
339
  }
290
340
 
291
341
  function leaveAll(table) {
292
- for (const player of table.seated) table.harness.leave(player);
342
+ for (const player of table.seated) {
343
+ table.harness.leave(player);
344
+ }
293
345
  }
294
346
 
295
347
  // --- scenarios ------------------------------------------------------------
@@ -315,8 +367,8 @@ function seating(ctx) {
315
367
  check(ctx, 'past the last seat, an arrival watches', ctx.seatOf(harness, watcher.playerId), null);
316
368
  }
317
369
 
318
- // Seating by connection rather than by account is also what makes two-tab local
319
- // testing work at all.
370
+ // Seats belong to connections, so two tabs of one account can play each other
371
+ // locally.
320
372
  function twoTabsOfOneAccount(ctx) {
321
373
  const harness = createSessionHarness(ctx.server, { sessionId: `check-${++counter}` });
322
374
  const a = harness.join('tab-a', { userId: 'one-account', username: 'nikki' });
@@ -498,8 +550,8 @@ function acceptedMovesDoRefreshTheClock(ctx, clock) {
498
550
  );
499
551
  }
500
552
 
501
- // A party spins up its own session and a new one arrives constantly, so what a
502
- // party session holds belongs to the people showing up. Nothing is cleared.
553
+ // Every party gets its own session, so whatever a party session holds belongs
554
+ // to that party. Nothing in it is ever cleared.
503
555
  function partyTableIsNeverCleared(ctx, clock) {
504
556
  const table = playedTable(ctx, 'party');
505
557
  const before = ctx.snapshot(table.harness, table.seated[0].playerId);
@@ -514,8 +566,8 @@ function partyTableIsNeverCleared(ctx, clock) {
514
566
  );
515
567
  }
516
568
 
517
- // `named` is what a local serve reports for every session, so it is the branch a
518
- // serve actually exercises. It must behave like public, not like party.
569
+ // A local serve reports `named` for every session, so that is the branch a serve
570
+ // exercises. It must behave like public, not like party.
519
571
  function namedBehavesLikePublic(ctx, clock) {
520
572
  const table = playedTable(ctx, 'named');
521
573
  leaveAll(table);
@@ -547,23 +599,3 @@ function sessionsDoNotLeak(ctx) {
547
599
  freshGame(ctx)
548
600
  );
549
601
  }
550
-
551
- const SCENARIOS = [
552
- hooksWork,
553
- seating,
554
- twoTabsOfOneAccount,
555
- dropDoesNotDestroy,
556
- watcherIsPromoted,
557
- reconnectKeepsItsSeat,
558
- presentOutranksGhost,
559
- reconnectAloneKeepsTheGame,
560
- loneArrivalGetsACleanTable,
561
- staleTableIsCleared,
562
- recentTableIsKept,
563
- coveredTableSurvivesALongThink,
564
- refusedMessagesDoNotRefreshTheClock,
565
- acceptedMovesDoRefreshTheClock,
566
- partyTableIsNeverCleared,
567
- namedBehavesLikePublic,
568
- sessionsDoNotLeak,
569
- ];
@@ -0,0 +1,3 @@
1
+ {
2
+ "palette": "endesga-64"
3
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.156",
3
+ "version": "0.4.158",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "castle-web": "./dist/index.js"
@@ -1,198 +0,0 @@
1
- # blank kit
2
-
3
- The authoring guide for a deck built on no framework -- a plain browser
4
- project. This kit ships no code, only this document: `## Files` covers what the
5
- deck holds, `## Editors` covers building a visual editor for a file type the
6
- deck defines. The rules that hold for every Castle deck are the platform's, in
7
- `.castle/docs/platform.md` (written by the serve at every start).
8
-
9
- ## Quick reference
10
-
11
- <!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
12
-
13
- - A plain browser project: `index.html` + `game.js` (an ES module) + `package.json` + `castle.json` (editor config). No kit: nothing in this deck comes from a framework, and there is no scene, behavior, sprite, or level format unless the deck defines one. Build directly with DOM, canvas, WebGL, React, Pixi, Three, or any installed package.
14
- - `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Storage`, `SharedStorage`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Portal`, `Lifecycle` — come from the same package; the full reference is `node_modules/castle-web-sdk/README.md`.
15
- - Vite serves and bundles the deck: ES modules, JSX, JSON, CSS and npm packages all work with no build step of your own — don't add one.
16
- - Call `Lifecycle.ready()` once the first real frame is painted, so the Castle feed reveals the deck right away instead of after a timeout.
17
- - There is no `check` script: verifying a change means the Play panel, the forwarded console in `.castle/logs.txt`, and `npm run screenshot` (needs a live panel; a canvas needs `preserveDrawingBuffer: true` or the capture is blank).
18
- - Details: `## Files` and `## Editors` in this file (`imports/castle.blank/CLAUDE.md`). The rules every deck plays by -- the card, touch, assets and formats, imports, reloading -- are the platform's: `.castle/docs/platform.md`, written by the serve.
19
-
20
- ## Files
21
-
22
- ```text
23
- index.html entry page; loads game.js as a module
24
- game.js the game (any layout of modules under it is fine)
25
- package.json scripts + dependencies
26
- castle.json editor config + import pins; gets a deckId on first save-deck
27
- imports/ other decks this one imports, read-only. `castle.blank` (this
28
- guide) is always here; `castle-web add-import` adds more
29
- .castle/ runtime state: serve.json (the live serve), logs.txt (forwarded
30
- console output), screenshots/
31
- ```
32
-
33
- `castle.json` → `editor`:
34
-
35
- - `initialPanels` — what the workspace opens with (`files`, `playtest`).
36
- - `visiblePaths` / `hiddenPaths` — the Files panel filter. `[]` shows every
37
- file, which is a bare deck's default; nothing needs adding for new files to
38
- appear.
39
- - `fileTypes` — the deck's own file types; see `## Editors`.
40
- - `defaultPlayFile` — what the play panel opens with. A bare deck has none: it
41
- plays `index.html`.
42
-
43
- Scripts: `npm run screenshot` captures the open page; `npm run save-deck`
44
- publishes (the deck is then at `https://castle.xyz/d/<deckId>`) and also
45
- photographs the running deck for its cover; `npm run restart` reloads every
46
- panel (`.castle/docs/platform.md` says when not to).
47
-
48
- ## Editors
49
-
50
- An editor is a visual authoring surface for a file type. This deck has none
51
- built in — the code editor opens everything — but it can add its own: declare
52
- a file type in `castle.json`, write one module, and have the entry answer the
53
- editor route. The Files panel then opens that type in your editor with a
54
- code/visual toggle. Reach for one when the deck accumulates content someone
55
- will keep iterating on by hand — level layouts, dialogue, item or word
56
- catalogs, tuning values — where editing raw JSON in the code editor is the
57
- bottleneck.
58
-
59
- ### The three steps
60
-
61
- 1. **Declare the type** in `castle.json` under `editor.fileTypes`:
62
-
63
- ```json
64
- "editor": {
65
- "fileTypes": [
66
- { "ext": ".dialogue", "label": "Dialogue", "new": "New dialogue",
67
- "icon": "file", "editor": "editors/DialogueEditor.js", "data": "json" }
68
- ]
69
- }
70
- ```
71
-
72
- These are ALL the fields that exist — do not invent others:
73
- - `ext` — the extension, with the dot. One entry per extension. Pick one
74
- that is the deck's own (`.dialogue`, `.levels`), not `.json`: a type
75
- claims every file with that extension.
76
- - `label` — display name in the tab and pickers.
77
- - `new` — the entry in the Files panel's New menu; omit it and the type
78
- can't be created there.
79
- - `icon` — for that entry and the file's tree row, from the shell's set:
80
- `globe`, `layer-group`, `code`, `file`, `image`, `music`, `film`. An
81
- unknown name falls back to a generic icon.
82
- - `editor` — the module that edits this type, as a path from the deck
83
- root, under `editors/`. Omit it to leave the type to the code editor.
84
- - `data` — how the file behaves when a module imports it: `"json"` (the
85
- import yields the parsed object) or `"text"` (the raw string). Omit for
86
- an ordinary JS module. See the gotcha below before relying on it.
87
- - `unsupported` — a refusal: why this deck must NOT be built on this
88
- format, shown when someone tries to upload one. Only for formats you
89
- recognize and reject.
90
-
91
- 2. **Write the module** at the declared path. There is no host component
92
- here, so the shape is yours; a default export that mounts into an element
93
- is the simplest:
94
-
95
- ```js
96
- // editors/DialogueEditor.js
97
- const EMPTY = { lines: [] };
98
-
99
- export default function mount(el, { path, text, onChange }) {
100
- let doc;
101
- try { doc = text.trim() ? JSON.parse(text) : EMPTY; } catch { doc = EMPTY; }
102
- const save = (next) => onChange(JSON.stringify(next, null, 2));
103
- // ...render doc into el, call save(next) on every edit...
104
- }
105
- ```
106
-
107
- 3. **Answer the editor route in the entry.** The shell opens a declared type
108
- as an iframe of the deck's own page at
109
- `/index.html?file=<path>&editorModule=<module>`, so `game.js` has to branch
110
- on `file` before it starts the game:
111
-
112
- ```js
113
- import { setup, initCard, isEdit, writeFile, fileUrl } from 'castle-web-sdk';
114
-
115
- const editors = import.meta.glob('./editors/*.js');
116
-
117
- async function mountEditor(file, editorModule) {
118
- const load = editors[`./${editorModule}`];
119
- if (!load) throw new Error(`no editor module ${editorModule}`);
120
- const [mod, text] = await Promise.all([load(), fetch(fileUrl(file)).then((r) => r.text())]);
121
- let pending;
122
- const onChange = (next) => {
123
- clearTimeout(pending);
124
- pending = setTimeout(() => writeFile(file, next), 300);
125
- };
126
- document.body.style.margin = '0';
127
- mod.default(document.body, { path: file, text, onChange });
128
- }
129
-
130
- setup();
131
- const params = new URLSearchParams(location.search);
132
- const file = params.get('file');
133
- if (isEdit() && file) {
134
- mountEditor(file, params.get('editorModule'));
135
- } else {
136
- startGame(initCard());
137
- }
138
- ```
139
-
140
- Read the file with `fetch(fileUrl(path))` and save it with
141
- `writeFile(path, text)`, debounced — both are SDK calls that only work
142
- while editing on the serve, which is the only place an editor runs. Load
143
- the module through `import.meta.glob` so the bundler knows about it; a
144
- dynamic `import(editorModule)` of a runtime string does not bundle. The
145
- editor branch skips `initCard()`: it fills the panel, not a 5:7 card.
146
-
147
- That's the whole integration. Nothing auto-reloads: the person opens the file
148
- (or reloads its panel) when they are ready.
149
-
150
- ### Gotchas
151
-
152
- - **Declare the glob and the mount function ABOVE the branch that calls them.**
153
- A `const` is in its temporal dead zone until its own line runs, so a
154
- `mountEditor(...)` called from higher up throws `Cannot access 'editors'
155
- before initialization` the moment it reads the map -- the function hoists, the
156
- `const` does not. Keep the dispatch last, as above.
157
- - **A `new:`-created file starts EMPTY.** Your editor must render a sensible
158
- default on empty text (as `EMPTY` above) and write the real document back
159
- on first edit — a module that throws on `""` is a blank panel.
160
- - **`data:` takes effect at serve start.** The serve reads the declared data
161
- types once, when it starts — and `init` started it before your type
162
- existed — so play code that `import`s a `.dialogue` file gets a parse error
163
- until the serve process restarts. Either import the content as text and
164
- parse it yourself (`import raw from './dialogue/main.dialogue?raw'`, or
165
- `import.meta.glob('./dialogue/*.dialogue', { query: '?raw', import: 'default', eager: true })`
166
- — no declaration needed, and it bundles), or declare `data` and accept that
167
- the module import works after the next serve start. The editor route is
168
- unaffected: it reads through `fileUrl`.
169
- - **Editors are edit-time only.** They must never run in play, and play code
170
- must never import from `editors/`. Keep logic both sides need (parsing,
171
- defaults) in a plain module both import.
172
- - **Reading media/binary files:** point an `<img>`/`<audio>` at
173
- `fileUrl(path)`; `fetch(fileUrl(path))` is for text.
174
- - **Design for a phone.** The editor renders in a panel that is often
175
- phone-width. Touch first: direct tap/drag on the content, big hit targets,
176
- no hover-only or keyboard-only affordances, no fixed-wide toolbars. Scroll
177
- vertically inside the panel rather than overflowing it. The shell is dark;
178
- nothing of its theme reaches the iframe, so set your own background and
179
- text colors rather than inheriting the page default.
180
- - **The code view stays reachable** (the tab's view toggle), so don't build
181
- a raw-JSON fallback mode into the editor itself.
182
- - **Imported editors.** If this deck imports another deck that declares a
183
- type, the shell hands the entry that deck's module as
184
- `editorModule=imports/<alias>/editors/...`. A second
185
- `import.meta.glob('./imports/*/editors/*.{js,jsx}')` alongside the deck's
186
- own lets the same dispatcher load it. `imports/` is read-only: to change an
187
- imported editor, copy it into your own `editors/` and declare the same
188
- `ext` yourself — the deck's own declaration wins.
189
-
190
- ### When to build one
191
-
192
- Content the creator (or you) keeps returning to edit by hand — a catalog of
193
- entities, level data, sequences, dialogue — earns an editor once it's clear
194
- iteration will continue. Data that is written once, or generated by code,
195
- stays code. A value that is tuned while playing belongs in the game's own UI
196
- or a debug overlay, not in a file editor. Never let building one delay a
197
- playable change the user asked for — it rides alongside, and it needs the
198
- user's yes first.
@@ -1,34 +0,0 @@
1
- {
2
- "title": "tabletop",
3
- "editor": {
4
- "initialPanels": [
5
- {
6
- "width": 400,
7
- "column": [
8
- {
9
- "type": "files"
10
- }
11
- ]
12
- },
13
- {
14
- "type": "editor",
15
- "file": "room.js"
16
- }
17
- ],
18
- "hiddenPaths": [],
19
- "visiblePaths": [
20
- "room.js",
21
- "testing.js"
22
- ]
23
- },
24
- "imports": {
25
- "castle.physics-2d": {
26
- "deckId": "ckRZGFW4iPrx",
27
- "version": "2026-08-28T19:17:29.217Z"
28
- }
29
- },
30
- "main": "main.jsx",
31
- "autoUpdateWhenImported": true,
32
- "deckId": "7rrXIMh-giTm",
33
- "cardId": "rkhXyRo-pwhX"
34
- }