castle-web-cli 0.4.229 → 0.4.230

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 (232) 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 +779 -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/devSessionChild.js +3 -1
  19. package/dist/devSessionServer.d.ts +14 -1
  20. package/dist/devSessionServer.js +229 -44
  21. package/dist/experimentAssignment.d.ts +15 -0
  22. package/dist/experimentAssignment.js +41 -0
  23. package/dist/importCheckHook.d.ts +40 -0
  24. package/dist/importCheckHook.js +171 -0
  25. package/dist/importRegression.d.ts +15 -0
  26. package/dist/importRegression.js +100 -0
  27. package/dist/importTrust.d.ts +2 -0
  28. package/dist/importTrust.js +27 -0
  29. package/dist/importUpdateHook.d.ts +18 -0
  30. package/dist/importUpdateHook.js +31 -8
  31. package/dist/importUpdateHookRunner.js +19 -7
  32. package/dist/imports.d.ts +16 -0
  33. package/dist/imports.js +141 -31
  34. package/dist/index.js +3 -1
  35. package/dist/init.d.ts +3 -0
  36. package/dist/init.js +125 -8
  37. package/dist/install.js +4 -1
  38. package/dist/localPaths.js +4 -0
  39. package/dist/login.js +2 -2
  40. package/dist/platformDoc.js +3 -8
  41. package/dist/playPagePolicy.js +3 -1
  42. package/dist/remix.js +5 -0
  43. package/dist/routerTaskReport.d.ts +28 -0
  44. package/dist/routerTaskReport.js +56 -0
  45. package/dist/save-deck.d.ts +18 -0
  46. package/dist/save-deck.js +142 -6
  47. package/dist/serve.d.ts +8 -0
  48. package/dist/serve.js +94 -13
  49. package/dist/serverBundle.d.ts +1 -1
  50. package/dist/serverBundle.js +5 -1
  51. package/dist/webSourceSync.d.ts +2 -0
  52. package/dist/webSourceSync.js +2 -0
  53. package/kits/base/CLAUDE.md +2 -3
  54. package/kits/base/castle.json +1 -1
  55. package/kits/base/sdk/README.md +258 -52
  56. package/kits/base/sdk/agent.js +4 -4
  57. package/kits/base/sdk/avatar.d.ts +12 -0
  58. package/kits/base/sdk/avatar.js +23 -0
  59. package/kits/base/sdk/castle.d.ts +5 -0
  60. package/kits/base/sdk/castle.js +3 -0
  61. package/kits/base/sdk/commands.d.ts +208 -0
  62. package/kits/base/sdk/commands.js +16 -0
  63. package/kits/base/sdk/context.d.ts +6 -0
  64. package/kits/base/sdk/experiments.d.ts +15 -0
  65. package/kits/base/sdk/experiments.js +83 -0
  66. package/kits/base/sdk/hub.d.ts +85 -0
  67. package/kits/base/sdk/hub.js +107 -0
  68. package/kits/base/sdk/multiplayer.d.ts +45 -1
  69. package/kits/base/sdk/multiplayer.js +106 -4
  70. package/kits/base/sdk/server/hub.d.ts +169 -0
  71. package/kits/base/sdk/server/hub.js +125 -0
  72. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  73. package/kits/base/sdk/server/storage.d.ts +55 -2
  74. package/kits/base/sdk/server/wrapper.d.ts +32 -2
  75. package/kits/base/sdk/server/wrapper.js +90 -11
  76. package/kits/base/sdk/transport.d.ts +2 -1
  77. package/kits/base/sdk/transport.js +13 -1
  78. package/kits/hub-game/.prettierrc +5 -0
  79. package/kits/hub-game/CLAUDE.md +146 -0
  80. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  84. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  96. package/kits/hub-game/castle.json +96 -0
  97. package/kits/hub-game/code/client/attention.js +133 -0
  98. package/kits/hub-game/code/client/avatar.js +288 -0
  99. package/kits/hub-game/code/client/cabinets.js +90 -0
  100. package/kits/hub-game/code/client/chat.js +135 -0
  101. package/kits/hub-game/code/client/chrome.js +1001 -0
  102. package/kits/hub-game/code/client/doorFrame.js +15 -0
  103. package/kits/hub-game/code/client/firstJoin.js +14 -0
  104. package/kits/hub-game/code/client/grab.js +241 -0
  105. package/kits/hub-game/code/client/hookLayer.js +230 -0
  106. package/kits/hub-game/code/client/idle.js +326 -0
  107. package/kits/hub-game/code/client/keys.js +48 -0
  108. package/kits/hub-game/code/client/pack.js +232 -0
  109. package/kits/hub-game/code/client/packFormat.js +397 -0
  110. package/kits/hub-game/code/client/say.js +127 -0
  111. package/kits/hub-game/code/client/sha256.js +80 -0
  112. package/kits/hub-game/code/client/sound.js +147 -0
  113. package/kits/hub-game/code/client/state.js +131 -0
  114. package/kits/hub-game/code/client/talk.js +259 -0
  115. package/kits/hub-game/code/client/together.js +365 -0
  116. package/kits/hub-game/code/client/wear.js +149 -0
  117. package/kits/hub-game/code/server/actors.js +627 -0
  118. package/kits/hub-game/code/server/blocks.js +103 -0
  119. package/kits/hub-game/code/server/cabinets.js +309 -0
  120. package/kits/hub-game/code/server/game.js +137 -0
  121. package/kits/hub-game/code/server/grab.js +247 -0
  122. package/kits/hub-game/code/server/history.js +96 -0
  123. package/kits/hub-game/code/server/hub.js +1904 -0
  124. package/kits/hub-game/code/server/idle.js +412 -0
  125. package/kits/hub-game/code/server/index.js +64 -0
  126. package/kits/hub-game/code/server/labels.js +59 -0
  127. package/kits/hub-game/code/server/manifest.js +527 -0
  128. package/kits/hub-game/code/server/npcs.js +745 -0
  129. package/kits/hub-game/code/server/party.js +381 -0
  130. package/kits/hub-game/code/server/place.js +43 -0
  131. package/kits/hub-game/code/server/say.js +83 -0
  132. package/kits/hub-game/code/server/wear.js +142 -0
  133. package/kits/hub-game/code/systems/hub.js +2230 -0
  134. package/kits/hub-game/docs/content-pack.md +151 -0
  135. package/kits/hub-game/docs/contract.md +1139 -0
  136. package/kits/hub-game/docs/style.md +137 -0
  137. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  138. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  139. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  140. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  141. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  142. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  143. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  144. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  145. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  146. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  147. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  148. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  149. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  150. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  154. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  155. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  156. package/kits/hub-game/eslint.config.js +20 -0
  157. package/kits/hub-game/fonts.generated.js +9 -0
  158. package/kits/hub-game/index.html +22 -0
  159. package/kits/hub-game/main.jsx +6 -0
  160. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  161. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  162. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  164. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  165. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  167. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  168. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  169. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  170. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  171. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  172. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  173. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  174. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  175. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  176. package/kits/hub-game/package-lock.json +365 -0
  177. package/kits/hub-game/package.json +32 -0
  178. package/kits/hub-game/scenes/main.scene +318 -0
  179. package/kits/hub-game/scripts/check.mjs +339 -0
  180. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  181. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  182. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  183. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  184. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  185. package/kits/hub-game/scripts/pack.mjs +192 -0
  186. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  187. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  188. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  189. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  190. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  191. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  192. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  193. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  194. package/kits/hub-game/scripts/test-door.mjs +56 -0
  195. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  196. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  197. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  198. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  199. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  200. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  201. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  202. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  203. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  204. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  205. package/kits/hub-game/scripts/test-party.mjs +286 -0
  206. package/kits/hub-game/scripts/test-say.mjs +149 -0
  207. package/kits/hub-game/scripts/test-together.mjs +183 -0
  208. package/kits/hub-game/theme.style +3 -0
  209. package/kits/multiplayer-3d/castle.json +5 -5
  210. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  211. package/kits/multiplayer-3d/code/server/players.js +4 -1
  212. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  213. package/kits/multiplayer-3d/code/server/world.js +20 -7
  214. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  215. package/kits/physics-2d/castle.json +2 -2
  216. package/kits/physics-2d/engine/art.js +13 -0
  217. package/kits/physics-2d/engine/assets.js +4 -2
  218. package/kits/physics-2d/engine/scene.js +25 -5
  219. package/kits/physics-3d/CLAUDE.md +6 -1
  220. package/kits/physics-3d/castle.json +3 -3
  221. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  222. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  223. package/kits/physics-3d/engine3d/materials.js +29 -1
  224. package/kits/physics-3d/engine3d/world3d.js +65 -1
  225. package/kits/physics-3d/systems/physics3d.js +5 -2
  226. package/kits/real-time/castle.json +2 -2
  227. package/kits/real-time/code/client/connection.js +77 -7
  228. package/kits/real-time/code/client/gameHooks.js +63 -3
  229. package/kits/real-time/code/client/messages.js +7 -0
  230. package/kits/real-time/code/server/gameHooks.js +24 -0
  231. package/kits/real-time/code/server/session.js +390 -22
  232. package/package.json +2 -2
package/dist/init.js CHANGED
@@ -3,13 +3,14 @@ import * as path from 'path';
3
3
  import { CLAUDE_MD_PLATFORM_SECTION } from './platformDoc.js';
4
4
  import { installDeps } from './install.js';
5
5
  import { deckMainFile, deckStarterScene, STARTER_THEME_FILES } from './castleJson.js';
6
- import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, writeImportVersion, } from './imports.js';
6
+ import { addImportTo, builtinKitDigest, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, writeBuiltinStamp, writeImportVersion, } from './imports.js';
7
7
  import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
8
8
  import { kitFromAlias, shippedKitAlias } from './kitCatalog.js';
9
9
  import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
10
10
  import { SDK_PACKAGE } from './sdkResolve.js';
11
11
  import { serve } from './serve.js';
12
12
  import { createVersion } from './versions.js';
13
+ import { resolveFileInside } from './importUpdateHook.js';
13
14
  // Default kit imported by `init` when no --kit is given. `none`/`bare` skips the
14
15
  // framework and produces the minimal index.html + game.js stub below.
15
16
  const DEFAULT_KIT = 'physics-2d';
@@ -19,13 +20,10 @@ const DEFAULT_KIT = 'physics-2d';
19
20
  // A framework kit imports it too, so a kit deck has it as well.
20
21
  export const BASE_KIT = 'base';
21
22
  export const BASE_ALIAS = shippedKitAlias(BASE_KIT);
22
- // A bare deck lays itself out, so it starts as a fill deck (platformDoc.ts,
23
- // "Fit the stage"); a kit deck's entry is the kit's, and follows its guide.
24
23
  const INDEX_HTML = `<!DOCTYPE html>
25
24
  <html>
26
25
  <head>
27
26
  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
28
- <meta name="castle-display" content="layout=fill">
29
27
  <title>My Castle Game</title>
30
28
  </head>
31
29
  <body>
@@ -43,7 +41,7 @@ function startGame(card) {
43
41
  el.style.cssText = \`
44
42
  width: 100%; height: 100%;
45
43
  display: flex; align-items: center; justify-content: center;
46
- font-family: system-ui; color: #fff; font-size: calc(6 * var(--castle-unit));
44
+ font-family: system-ui; color: #fff; font-size: 24px;
47
45
  \`;
48
46
  el.textContent = 'Hello Castle!';
49
47
  card.appendChild(el);
@@ -55,12 +53,12 @@ function startGame(card) {
55
53
  if (!(await mountEditorRoute())) startGame(initCard());
56
54
  `;
57
55
  // Every bare scaffold `init` has written, so isPristineBareDeck still knows an
58
- // untouched deck made before the scaffold became a fill deck.
56
+ // untouched deck made while the scaffold was a fill deck (Sept 29-30, 2026).
59
57
  const BARE_SCAFFOLDS = [
60
58
  { html: INDEX_HTML, js: GAME_JS },
61
59
  {
62
- html: INDEX_HTML.replace(' <meta name="castle-display" content="layout=fill">\n', ''),
63
- js: GAME_JS.replace('calc(6 * var(--castle-unit))', '24px'),
60
+ html: INDEX_HTML.replace(' <title>', ' <meta name="castle-display" content="layout=fill">\n <title>'),
61
+ js: GAME_JS.replace('font-size: 24px;', 'font-size: calc(6 * var(--castle-unit));'),
64
62
  },
65
63
  ];
66
64
  // Registry version of castle-web-sdk to inject when scaffolding from a
@@ -348,6 +346,87 @@ export function writeStarterTheme(projectDir, kitDir) {
348
346
  fs.copyFileSync(src, dest);
349
347
  }
350
348
  }
349
+ // The kit's `starterFiles` (castleJson.ts): files it authors that a deck
350
+ // starting from it owns from then on -- a server module to fill in, a blueprint
351
+ // to edit. Each lands at the same relative path in the deck, verbatim, and
352
+ // never over a file the deck already has. A declared path gets the same guard
353
+ // an update hook's does (`resolveFileInside`), since a kit's castle.json is
354
+ // somebody else's word for which files to copy.
355
+ //
356
+ // Read and written rather than `copyFileSync`, which would carry the mode
357
+ // across: when adopting a kit by add-import the source is a locked import, and
358
+ // the deck's copy has to be writable.
359
+ export function writeStarterFiles(projectDir, kitDir) {
360
+ const declared = readJsonFile(path.join(kitDir, 'castle.json'))?.starterFiles;
361
+ if (declared === undefined)
362
+ return [];
363
+ if (!Array.isArray(declared)) {
364
+ console.warn(`Warning: ${kitDir}'s starterFiles is not a list -- skipping it.`);
365
+ return [];
366
+ }
367
+ const written = [];
368
+ for (const entry of declared) {
369
+ const src = typeof entry === 'string' ? resolveFileInside(kitDir, entry) : null;
370
+ if (!src) {
371
+ console.warn(`Warning: starter file ${JSON.stringify(entry)} is not a file inside the kit -- skipping it.`);
372
+ continue;
373
+ }
374
+ const rel = toPosixPath(path.relative(kitDir, src));
375
+ const dest = path.join(projectDir, rel);
376
+ if (fs.existsSync(dest))
377
+ continue;
378
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
379
+ fs.writeFileSync(dest, fs.readFileSync(src));
380
+ written.push(rel);
381
+ }
382
+ return written;
383
+ }
384
+ // Never taken from a kit's `starterConfig`. The pins and the deck's identity
385
+ // are the deck's own; `editor` and `server` are `adoptKitConfig`'s, which
386
+ // rewrites them for the deck; and the rest are statements a deck makes about
387
+ // ITSELF to the decks importing it, which a deck starting from a kit has not
388
+ // made just because the kit did.
389
+ const STARTER_CONFIG_RESERVED = new Set([
390
+ 'imports',
391
+ 'editor',
392
+ 'server',
393
+ 'deckId',
394
+ 'cardId',
395
+ 'publishedVersion',
396
+ 'title',
397
+ 'autoUpdateWhenImported',
398
+ 'importWhenRemixed',
399
+ 'onUpdate',
400
+ 'onCheck',
401
+ 'main',
402
+ 'starterScene',
403
+ 'starterFiles',
404
+ 'starterConfig',
405
+ ]);
406
+ // The kit's `starterConfig` (castleJson.ts), merged into the deck's castle.json
407
+ // one top-level key at a time, for keys the deck does not have yet. Runs after
408
+ // `adoptKitConfig`, so a block that adopts first is kept.
409
+ export function adoptStarterConfig(deckDir, kitDir) {
410
+ const starter = readJsonFile(path.join(kitDir, 'castle.json'))?.starterConfig;
411
+ if (starter === undefined)
412
+ return [];
413
+ if (!starter || typeof starter !== 'object' || Array.isArray(starter)) {
414
+ console.warn(`Warning: ${kitDir}'s starterConfig is not an object -- skipping it.`);
415
+ return [];
416
+ }
417
+ const configPath = path.join(deckDir, 'castle.json');
418
+ const deckConfig = readJsonFile(configPath) ?? {};
419
+ const added = [];
420
+ for (const [key, value] of Object.entries(starter)) {
421
+ if (STARTER_CONFIG_RESERVED.has(key) || key in deckConfig)
422
+ continue;
423
+ deckConfig[key] = value;
424
+ added.push(key);
425
+ }
426
+ if (added.length > 0)
427
+ writeJsonFile(configPath, deckConfig);
428
+ return added;
429
+ }
351
430
  // A bare deck's own guide. Its `## Quick reference` is HERE rather than in the
352
431
  // base kit for one reason: this is the only place a claim like "there is no
353
432
  // scene format" is true. Every deck imports base now, kit decks included, so
@@ -508,6 +587,9 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
508
587
  if (typeof pin.deckId === 'string') {
509
588
  writeImportVersion(importDir, { deckId: pin.deckId, version: pin.version });
510
589
  }
590
+ else if (pin.source === 'builtin' && typeof pin.version === 'string') {
591
+ writeBuiltinStamp(importDir, { source: 'builtin', kit, version: pin.version, digest: builtinKitDigest(kitDir) });
592
+ }
511
593
  const kitPins = (kitConfig.imports ?? {});
512
594
  for (const [depAlias, depPin] of Object.entries(kitPins)) {
513
595
  if (copied.has(depAlias) || pins[depAlias])
@@ -522,6 +604,37 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
522
604
  }
523
605
  }
524
606
  }
607
+ // The imports a kit names that the deck does not pin yet, pinned and placed as
608
+ // `init` would place them (a shipped kit copied, anything else pinned for
609
+ // `install` to fetch). For a builtin kit refreshed under the deck: a newer
610
+ // copy can name dependencies the old one did not. Returns the aliases added.
611
+ export function addKitDependencies(deckDir, kitDir) {
612
+ const configPath = path.join(deckDir, 'castle.json');
613
+ const config = readJsonFile(configPath) ?? {};
614
+ const pins = { ...(config.imports ?? {}) };
615
+ const before = new Set(Object.keys(pins));
616
+ const copied = new Map();
617
+ const kitPins = ((readJsonFile(path.join(kitDir, 'castle.json')) ?? {}).imports ?? {});
618
+ for (const [depAlias, depPin] of Object.entries(kitPins)) {
619
+ if (pins[depAlias])
620
+ continue;
621
+ const depKit = kitFromAlias(depAlias);
622
+ const depKitDir = path.join(getKitsDir(), depKit);
623
+ if (fs.existsSync(depKitDir) && fs.statSync(depKitDir).isDirectory()) {
624
+ copyKitImport(deckDir, depKitDir, depKit, depAlias, pins, copied);
625
+ }
626
+ else {
627
+ pins[depAlias] = depPin;
628
+ }
629
+ }
630
+ const added = Object.keys(pins).filter((alias) => !before.has(alias));
631
+ if (added.length) {
632
+ writeJsonFile(configPath, { ...readJsonFile(configPath), imports: pins });
633
+ for (const alias of copied.keys())
634
+ lockImportTree(path.join(deckDir, IMPORTS_DIR, alias));
635
+ }
636
+ return added;
637
+ }
525
638
  // `add-import <kit>`: the same copy `init --kit` makes, into an existing deck
526
639
  // that does not have the kit yet (the caller refuses one that does). Kits the
527
640
  // deck already pins are left as they are, which is what keeps a bare deck's
@@ -599,6 +712,7 @@ function scaffoldFromKitImport(kit, projectDir) {
599
712
  writeStarterTheme(projectDir, kitDir);
600
713
  writeJsonFile(path.join(projectDir, 'castle.json'), { imports: pins });
601
714
  adoptKitConfig(projectDir, kitDir, alias);
715
+ adoptStarterConfig(projectDir, kitDir);
602
716
  // The kit's code runs from THIS deck's node_modules, so its dependencies are
603
717
  // declared here (see syncImportDependencies, which does the same for imports
604
718
  // added later). Every copied kit contributes, the scaffolding kit first, so
@@ -628,6 +742,9 @@ function scaffoldFromKitImport(kit, projectDir) {
628
742
  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias, !!kitConfig.server));
629
743
  appendPlatformSection(projectDir);
630
744
  ensureAgentsSymlink(projectDir);
745
+ // Last, so a starter file never stands in for one the scaffold writes
746
+ // (package.json, CLAUDE.md) -- it skips any path already on disk.
747
+ writeStarterFiles(projectDir, kitDir);
631
748
  for (const importedAlias of copied.keys()) {
632
749
  lockImportTree(path.join(projectDir, IMPORTS_DIR, importedAlias));
633
750
  }
package/dist/install.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { execSync, spawn } from 'child_process';
2
2
  import * as fs from 'fs';
3
3
  import * as path from 'path';
4
- import { restoreMissingImports, syncImportDependencies } from './imports.js';
4
+ import { refreshStaleBuiltinImports, restoreMissingImports, syncImportDependencies, } from './imports.js';
5
5
  import { normalizeDeckPackageJson } from './normalize.js';
6
6
  import { writePlatformDocs } from './platformDoc.js';
7
7
  // Probed in the deck, where the install itself runs: Corepack's pnpm shim refuses
@@ -74,6 +74,9 @@ export async function install(dir) {
74
74
  const restored = await restoreMissingImports(projectDir);
75
75
  for (const alias of restored)
76
76
  console.log(`Restored import ${alias}`);
77
+ // A builtin kit changes under an unchanged CLI version: a copy that differs
78
+ // from this CLI's is replaced, so the deck runs (and later saves) this kit.
79
+ await refreshStaleBuiltinImports(projectDir);
77
80
  // A fetched deck's CLAUDE.md already @imports the platform guide; write it
78
81
  // now rather than leaving the reference dangling until the first serve.
79
82
  writePlatformDocs(projectDir);
@@ -21,6 +21,10 @@ export function getSdkPackagePath() {
21
21
  return path.join(getRepoRoot(), 'sdk');
22
22
  }
23
23
  export function getKitsDir() {
24
+ // Tests stand in a kits directory of their own (scripts/tests/kit-starter-and-check.mjs).
25
+ const override = process.env.CASTLE_WEB_KITS_DIR;
26
+ if (override)
27
+ return override;
24
28
  // Prefer bundled kits (shipped inside the published cli package);
25
29
  // fall back to the workspace `kits/` alongside cli/.
26
30
  const bundled = path.join(getPackageRoot(), 'kits');
package/dist/login.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as api from './api.js';
2
2
  import * as config from './config.js';
3
3
  export async function login() {
4
- const { pollToken, url } = await api.startCLILogin();
4
+ const { pollToken, url, verifier } = await api.startCLILogin();
5
5
  console.log(`Opening browser to log in: ${url}`);
6
6
  const { default: open } = await import('open');
7
7
  await open(url);
@@ -9,7 +9,7 @@ export async function login() {
9
9
  const MAX_POLLS = 600;
10
10
  for (let i = 0; i < MAX_POLLS; i++) {
11
11
  await new Promise((r) => setTimeout(r, 1000));
12
- const user = await api.pollForCLILogin(pollToken);
12
+ const user = await api.pollForCLILogin(pollToken, verifier);
13
13
  if (user) {
14
14
  config.setAuth(user.token, user.userId);
15
15
  console.log(`Logged in as @${user.username}`);
@@ -232,14 +232,9 @@ const COMMON_SECTIONS = `## Imports are read-only
232
232
 
233
233
  - **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch — direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics — a game with no directional movement should have no movement controls at all.
234
234
 
235
- ## Fit the stage
236
-
237
- - **A deck plays inside a stage that clips overflow and does not scroll.** By default the stage is a 5:7 portrait card sized to fit the screen (at most about 450x630px). A deck that declares \`<meta name="castle-display" content="layout=fill">\` in its \`index.html\` \`<head>\` instead gets whatever box the host can give it -- a wide stage on desktop, the full height of a tall phone, the whole screen in fullscreen -- as long as the box's width / height is inside its range (default 9/21 to 21/9; narrow it with \`min-aspect=\` / \`max-aspect=\`, as \`16/9\`, \`16:9\` or \`1.78\`). Outside the range the deck gets the largest in-range box, centered. The SDK exports \`CARD_RATIO\` (= 5 / 7) if you need the exact ratio.
238
- - **Declare fill for a deck you lay out yourself**, unless it is built around a fixed portrait board (a card game, a vertical puzzle) that would only gain empty margins: that is the default for new bare decks, and Castle's web player gives a fill deck a bigger stage and a fullscreen button. A kit deck keeps whatever its kit guide says; don't add the tag to a kit deck whose guide doesn't mention it. Fullscreen belongs to the host: never build a fullscreen button or call \`requestFullscreen\` in a deck.
239
- - **A fill deck has no fixed shape, and must look right at every shape in its range -- including 5:7, which it still gets from hosts that ignore the tag.** Lay out with flex/grid against the stage -- the element \`initCard()\` returns (its \`clientWidth\`/\`clientHeight\`), or \`var(--castle-card-w)\`/\`var(--castle-card-h)\` in CSS -- not against the window: the stage is smaller than the window whenever the host frame is outside the deck's range, and inside \`castle-web serve\`'s own page. Re-layout on \`resize\`; let the playfield use the extra room (a wider view of the world, a bigger board), and anchor HUD to the stage's edges and corners. Don't letterbox the game back into a 5:7 box inside a fill stage -- that just gives up the space.
240
- - **A deck that lays itself out sizes HUD, buttons and text in the card unit, \`var(--castle-unit)\`, not \`vw\`, \`vh\` or \`cqw\`**: \`font-size: calc(5 * var(--castle-unit))\`. It is 1% of the width of the largest 5:7 card that fits in the stage -- the same as \`1vw\` on a card -- so a HUD keeps its card size on a wide stage, where anything in \`vw\` grows to fill a monitor. Canvas code gets the same px value from \`cardUnit(width, height)\` of the stage. A kit deck sizes things the way its kit guide says: a kit's scene editor draws the stage smaller inside the editor, where the unit follows the window instead.
241
- - **A 3D camera keeps its framing across shapes with \`fovForAspect(fov, aspect)\`**: \`camera.fov = fovForAspect(50, width / height)\` on every resize. It keeps \`fov\` at 5:7 and wider and widens it on a stage taller than 5:7, so a tall phone doesn't crop the sides of the scene.
242
- - **The Play panel shows a card deck as a 5:7 card, and a fill deck at the shape picked under it**: Fit (the whole panel), Phone, Card or Landscape, each clamped into the deck's range the way a host would, with the frame's size beside the picker. A new or changed tag takes effect with the next run (Restart), like any other change to the deck. \`npm run screenshot\` captures whatever shape the open deck tab has. Those are a few shapes of many: make the layout's rules (anchors, the card unit, the camera) hold at any shape rather than tuning it pixel by pixel to what the Play panel shows. A fill deck's cover is taken at the card shape (the nearest one its range allows), since a cover is shown as a card.
235
+ ## Fit the card
236
+
237
+ - **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, \`min()\`, \`clamp()\`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports \`CARD_RATIO\` (= 5 / 7) if you need the exact ratio.
243
238
  - **Hand-rolled \`<canvas>\` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times \`devicePixelRatio\` (e.g. \`canvas.width = rect.width * dpr\`), keep the CSS width/height as the layout size, and scale the 2D context (\`ctx.scale(dpr, dpr)\`) so drawing code stays in CSS units — re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.
244
239
  - Exception: deliberate pixel art wants a fixed low-resolution backing store with \`image-rendering: pixelated\` CSS instead — don't DPR-scale that; the crisp chunky look is the point.
245
240
  - **A WebGL canvas must be created with \`preserveDrawingBuffer: true\`, or every in-page capture of the deck comes back blank** — the Play panel's Snap and \`npm run screenshot\` both read the canvas after the frame has been shown, and by then the browser has cleared it, so the image is just the card's background. Pass it through whatever library makes the canvas: \`new THREE.WebGLRenderer({ preserveDrawingBuffer: true })\`, PixiJS \`app.init({ preserveDrawingBuffer: true })\`, or \`canvas.getContext('webgl2', { preserveDrawingBuffer: true })\`. A 2D canvas needs nothing, and kit decks already set it.
@@ -5,6 +5,8 @@
5
5
  // published bundle gets. The two must match; change both together.
6
6
  const CDN_HOSTS = 'https://esm.sh https://cdnjs.cloudflare.com';
7
7
  const PLAY_HOSTS = 'wss://*.play.castle.xyz';
8
+ // Content packs a hub door mounts (kits/hub-game/docs/content-pack.md); connect-src only.
9
+ const CONTENT_PACK_HOSTS = 'https://hosted.castle.games';
8
10
  const DECK_CSP = [
9
11
  "default-src 'self' data: blob:",
10
12
  `script-src 'self' 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' data: blob: ${CDN_HOSTS}`,
@@ -12,7 +14,7 @@ const DECK_CSP = [
12
14
  "font-src 'self' data: blob: https://fonts.gstatic.com",
13
15
  "img-src 'self' data: blob:",
14
16
  "media-src 'self' data: blob:",
15
- `connect-src 'self' data: blob: ${CDN_HOSTS} ${PLAY_HOSTS}`,
17
+ `connect-src 'self' data: blob: ${CDN_HOSTS} ${PLAY_HOSTS} ${CONTENT_PACK_HOSTS}`,
16
18
  "frame-src 'none'",
17
19
  "child-src 'self' blob:",
18
20
  "worker-src 'self' blob:",
package/dist/remix.js CHANGED
@@ -7,6 +7,11 @@ import { downloadSourceArchive, runTar } from './save-deck.js';
7
7
  // promise to ITS importers, which a remix hasn't made -- and `onUpdate` is the
8
8
  // migration it runs in them, naming a module the remix keeps as ordinary source
9
9
  // rather than as a hook.
10
+ //
11
+ // `onCheck`, `starterScene`, `starterFiles` and `starterConfig` are kept on
12
+ // purpose: each names files the remix copied along with it, so they stay true
13
+ // of the remix. A remix of a kit that runs its own check (alias `self`) or that
14
+ // someone starts a deck from should behave as the kit did.
10
15
  const PARENT_ONLY_KEYS = [
11
16
  'deckId',
12
17
  'cardId',
@@ -0,0 +1,28 @@
1
+ import type { PromptTask } from './agent-prompts.js';
2
+ export declare const RESULT_SUMMARY_CHARS = 600;
3
+ export declare const HANDOFF_MAX_CHARS = 200;
4
+ export declare const HANDOFF_MAX_LIST = 8;
5
+ interface TaskReportTarget {
6
+ status: string;
7
+ rejected?: boolean;
8
+ handoffNoDeckFiles?: boolean;
9
+ resultSummary?: string;
10
+ resultSummaryStartsMidWord?: boolean;
11
+ }
12
+ export declare function summarizeTaskResult(finalText: string): {
13
+ resultSummary: string;
14
+ resultSummaryStartsMidWord?: boolean;
15
+ };
16
+ export declare function noDeckFiles(filesLine: string | undefined): boolean;
17
+ export declare function routerTaskReport(task: TaskReportTarget): string | undefined;
18
+ export declare function routerPromptTask(task: TaskReportTarget & {
19
+ id: string;
20
+ title: string;
21
+ progress: number;
22
+ notes: string;
23
+ model?: string;
24
+ effort?: string;
25
+ item?: string;
26
+ }): PromptTask;
27
+ export declare function quotableTaskText(row: Pick<PromptTask, 'error' | 'interrupted' | 'notes' | 'report'>, durable?: string): string;
28
+ export {};
@@ -0,0 +1,56 @@
1
+ export const RESULT_SUMMARY_CHARS = 600;
2
+ // A handoff line is one fact, and a long one is a summary rather than the
3
+ // single fact the prompt asks for.
4
+ export const HANDOFF_MAX_CHARS = 200;
5
+ export const HANDOFF_MAX_LIST = 8;
6
+ export function summarizeTaskResult(finalText) {
7
+ const cutAt = finalText.length - RESULT_SUMMARY_CHARS;
8
+ return {
9
+ resultSummary: finalText.slice(-RESULT_SUMMARY_CHARS),
10
+ resultSummaryStartsMidWord: cutAt > 0
11
+ ? !/\s/.test(finalText[cutAt - 1]) && !/\s/.test(finalText[cutAt])
12
+ : undefined,
13
+ };
14
+ }
15
+ export function noDeckFiles(filesLine) {
16
+ if (!filesLine?.trim())
17
+ return false;
18
+ const none = /^none(?: changed)?(?:\s*\([^)]*\))?$/i;
19
+ if (none.test(filesLine.trim()))
20
+ return true;
21
+ return filesLine.split(',').every((entry) => {
22
+ const file = entry.trim();
23
+ return (none.test(file) ||
24
+ (file.replace(/^\.\//, '').startsWith('.castle/') && !file.split('/').includes('..')));
25
+ });
26
+ }
27
+ export function routerTaskReport(task) {
28
+ if (task.status !== 'done' || task.rejected || task.handoffNoDeckFiles !== true) {
29
+ return undefined;
30
+ }
31
+ const summary = task.resultSummary ?? '';
32
+ const report = (task.resultSummaryStartsMidWord ? summary.replace(/^\S+/, '') : summary)
33
+ .replace(/\s+/g, ' ')
34
+ .trim();
35
+ if (!report)
36
+ return undefined;
37
+ return task.resultSummaryStartsMidWord === undefined ? report : `…${report}`;
38
+ }
39
+ export function routerPromptTask(task) {
40
+ return {
41
+ id: task.id,
42
+ title: task.title,
43
+ status: task.rejected ? 'rejected by user' : task.status,
44
+ progress: task.progress,
45
+ notes: task.notes,
46
+ ...(task.model ? { model: task.model } : {}),
47
+ ...(task.effort ? { effort: task.effort } : {}),
48
+ item: task.item,
49
+ report: routerTaskReport(task),
50
+ };
51
+ }
52
+ export function quotableTaskText(row, durable) {
53
+ return [durable, row.error, row.interrupted, row.notes, row.report]
54
+ .filter((s) => s?.trim())
55
+ .join('\n');
56
+ }
@@ -1,4 +1,5 @@
1
1
  import * as api from './api.js';
2
+ import { type ExperimentConfig } from './castleJson.js';
2
3
  import { type SavePrecondition } from './webSourceSync.js';
3
4
  export { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
4
5
  export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
@@ -15,6 +16,23 @@ export declare function packSourceForSave(projectDir: string, castleJson: string
15
16
  }): Promise<Buffer>;
16
17
  export declare function uploadSource(projectDir: string, deckId: string, expectedS3Key?: string | null, archive?: Buffer): Promise<api.WebDeckSource>;
17
18
  export declare function checkSavePrecondition(projectDir: string, deckId: string, force: boolean): Promise<SavePrecondition>;
19
+ export declare function publishExperiments(deckId: string, title: string, experiments: Record<string, ExperimentConfig>): Promise<void>;
20
+ export declare const EXPERIMENTS_CLEAR_SETTLE_MS = 2000;
21
+ /**
22
+ * A deck that declares no experiments sends null, which is what ends the
23
+ * experiments of a deck whose block was removed: the folder cannot tell whether
24
+ * the saved deck still has one (it may have been saved from another machine),
25
+ * and Ghost writes nothing when there was none.
26
+ *
27
+ * That call is not the save's business, so it is started here and never
28
+ * awaited: the rest of the save goes on at once, and nothing it does can fail
29
+ * the save or print a line. `settle` is for the very end of the save: it gives
30
+ * the call a short while to finish, so the process exiting does not routinely
31
+ * cut it off, then drops it. Exported for the tests.
32
+ */
33
+ export declare function startClearingExperiments(deckId: string): {
34
+ settle(capMs?: number): Promise<void>;
35
+ };
18
36
  export type SaveVisibility = 'unlisted' | 'private';
19
37
  export interface SaveDeckOptions {
20
38
  title?: string;