castle-web-cli 0.4.151 → 0.4.153

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 (98) hide show
  1. package/dist/castle-host/host.js +11 -3
  2. package/dist/castleJson.d.ts +1 -0
  3. package/dist/castleJson.js +14 -0
  4. package/dist/ide.js +4 -0
  5. package/dist/imports.js +18 -12
  6. package/dist/init.js +28 -12
  7. package/dist/platformDoc.js +68 -0
  8. package/dist/save-deck.js +14 -9
  9. package/dist/serve.js +91 -18
  10. package/dist/serveSecurity.d.ts +6 -0
  11. package/dist/serveSecurity.js +38 -4
  12. package/dist/shell/assets/{index-Dlhc3eZW.js → index-DsDkYFvP.js} +2 -2
  13. package/dist/shell/index.html +1 -1
  14. package/kits/blank/castle.json +1 -1
  15. package/kits/blank/node_modules/.package-lock.json +13 -0
  16. package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
  17. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  18. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  19. package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  20. package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
  21. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  22. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  23. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  24. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  25. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  26. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  27. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  28. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  29. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  30. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  31. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  32. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  33. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  34. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  35. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  36. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  37. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  38. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  39. package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  40. package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
  41. package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  42. package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  43. package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  44. package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
  45. package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  46. package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  47. package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  48. package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  49. package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  50. package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  51. package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  52. package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  53. package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  54. package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  55. package/kits/blank/package-lock.json +10 -1
  56. package/kits/blank/package.json +3 -1
  57. package/kits/physics-2d/CLAUDE.md +158 -40
  58. package/kits/physics-2d/castle.json +3 -2
  59. package/kits/physics-2d/editors/SingleEditor.jsx +52 -19
  60. package/kits/physics-2d/editors/StyleEditor.jsx +139 -40
  61. package/kits/physics-2d/editors/deckFont.js +88 -0
  62. package/kits/physics-2d/editors/fontPreview.js +66 -0
  63. package/kits/physics-2d/editors/styleEditor.module.css +30 -3
  64. package/kits/physics-2d/editors/styleTheme.js +13 -2
  65. package/kits/physics-2d/engine/ScenePlayer.jsx +17 -2
  66. package/kits/physics-2d/engine/SceneUI.jsx +8 -0
  67. package/kits/physics-2d/engine/files.js +20 -9
  68. package/kits/physics-2d/engine/fonts.js +79 -0
  69. package/kits/physics-2d/engine/scene.js +6 -0
  70. package/kits/physics-2d/fonts.generated.js +9 -0
  71. package/kits/physics-2d/main.jsx +11 -0
  72. package/kits/physics-2d/package-lock.json +8 -1
  73. package/kits/physics-2d/package.json +1 -0
  74. package/kits/physics-2d/theme.style +2 -1
  75. package/kits/physics-3d/castle.json +1 -1
  76. package/kits/physics-3d/engine3d/PxModelEditor.jsx +3 -4
  77. package/kits/physics-3d/engine3d/Scene3DEditor.jsx +12 -8
  78. package/kits/physics-3d/engine3d/editorChrome.jsx +11 -6
  79. package/kits/physics-3d/engine3d/modelFiles.js +4 -5
  80. package/kits/physics-3d/package-lock.json +8 -1
  81. package/kits/physics-3d/package.json +1 -0
  82. package/kits/tabletop/.prettierrc +8 -0
  83. package/kits/tabletop/CLAUDE.md +309 -0
  84. package/kits/tabletop/castle.json +34 -0
  85. package/kits/tabletop/index.html +20 -0
  86. package/kits/tabletop/main.jsx +8 -0
  87. package/kits/tabletop/package-lock.json +341 -0
  88. package/kits/tabletop/package.json +29 -0
  89. package/kits/tabletop/room.js +269 -0
  90. package/kits/tabletop/testing.js +569 -0
  91. package/package.json +1 -1
  92. package/kits/blank/.castle/agent/children.json +0 -1
  93. package/kits/blank/.castle/agent/messages.json +0 -9
  94. package/kits/blank/.castle/agent/pending-sends.json +0 -1
  95. package/kits/blank/.castle/agent/tasks/index.md +0 -2
  96. package/kits/blank/.castle/docs/platform.md +0 -36
  97. package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
  98. package/kits/blank/node_modules/.vite/deps/package.json +0 -3
@@ -128,7 +128,11 @@ function runCommand(ctx, command, params, caps) {
128
128
  async function multiplayerGetSession(ctx, params, caps) {
129
129
  const request = multiplayerSessionRequest(params);
130
130
  const deckId = requireDeckId(ctx, "multiplayer.getSession");
131
- const data = await graphql(caps.graphqlFetch, CAULDRON_MULTIPLAYER_SESSION_QUERY, { deckId, mode: request.mode, key: request.key ?? null, partyId: ctx.partyId ?? null }, "multiplayer.getSession");
131
+ // Which shared session a play belongs to is the host's call, not the deck's,
132
+ // the way `shared.cpp` reads the party off the engine rather than the scene.
133
+ // A play that arrived through a party stays inside it; otherwise public.
134
+ const mode = request.mode === "public" && ctx.partyId ? "party" : request.mode;
135
+ const data = await graphql(caps.graphqlFetch, CAULDRON_MULTIPLAYER_SESSION_QUERY, { deckId, mode, key: request.key ?? null, partyId: ctx.partyId ?? null }, "multiplayer.getSession");
132
136
  return multiplayerSessionResult(data.getCauldronMultiplayerSession);
133
137
  }
134
138
  function multiplayerSessionRequest(params) {
@@ -303,7 +307,11 @@ async function sharedDeckStorageLoad(ctx, params, gql) {
303
307
  // 'user' read: an explicit userId targets another player's public bucket;
304
308
  // otherwise the current player's. 'deck' scope ignores userId.
305
309
  const userId = scope === "user" ? asOptionalString(params.userId) ?? ctx.userId : null;
306
- const data = await graphql(gql, SHARED_DECK_STORAGE_QUERY, { deckId, sessionId: ctx.sessionId, userId, keys: asKeys(params.keys) }, "sharedDeckStorage.load");
310
+ const data = await graphql(gql, SHARED_DECK_STORAGE_QUERY,
311
+ // No sessionId: a play session is not a shared world. Sending one makes the
312
+ // key per-play, so a deck-scoped read finds nothing in play while the
313
+ // editor, which has no session, looks right.
314
+ { deckId, sessionId: null, userId, keys: asKeys(params.keys) }, "sharedDeckStorage.load");
307
315
  return { blob: data.sharedDeckStorage ?? {} };
308
316
  }
309
317
  async function sharedDeckStorageUpdate(ctx, params, gql) {
@@ -312,7 +320,7 @@ async function sharedDeckStorageUpdate(ctx, params, gql) {
312
320
  // 'user'-scope writes are forced to the current player — the deck cannot
313
321
  // write another player's bucket.
314
322
  const userId = scope === "user" ? requireUserId(ctx, "sharedDeckStorage.update") : null;
315
- await graphql(gql, UPDATE_SHARED_DECK_STORAGE_MUTATION, { deckId, sessionId: ctx.sessionId, userId, updates: asUpdates(params.updates) }, "sharedDeckStorage.update");
323
+ await graphql(gql, UPDATE_SHARED_DECK_STORAGE_MUTATION, { deckId, sessionId: null, userId, updates: asUpdates(params.updates) }, "sharedDeckStorage.update");
316
324
  return { ok: true };
317
325
  }
318
326
  async function leaderboardFetch(ctx, params, caps) {
@@ -1,3 +1,4 @@
1
+ export declare const STARTER_STYLE_FILES: string[];
1
2
  export declare const IMPORTS_DIR = "imports";
2
3
  export interface DeckImport {
3
4
  deckId?: string;
@@ -5,6 +5,20 @@ import picomatch from 'picomatch';
5
5
  // module with no imports of its own, because both the import machinery and the
6
6
  // fork overlay need it and importing it from either of those would close a
7
7
  // cycle.
8
+ // Root-level style files a kit ships as a deck's starting point, seeded into a
9
+ // deck at scaffold (init.ts `writeStarterTheme`) and when an import newly brings
10
+ // them (imports.ts `seedKitTheme`).
11
+ //
12
+ // Naming kit files in cli/ is the standing exception to "nothing here hardcodes
13
+ // a kit's vocabulary": a file the DECK owns but the kit authors has to be copied
14
+ // out by someone, and only the CLI is there at scaffold time. Keep the list
15
+ // short, and to inert data at the deck root.
16
+ //
17
+ // They move TOGETHER, which is why this is a list and not one filename:
18
+ // `theme.style` names the deck's font, `fonts.generated.js` is what carries that
19
+ // face's bytes into the bundle, and a deck given the first without the second
20
+ // renders in the fallback while claiming otherwise.
21
+ export const STARTER_STYLE_FILES = ['theme.style', 'fonts.generated.js'];
8
22
  export const IMPORTS_DIR = 'imports';
9
23
  export const DEFAULT_STARTER_SCENE = 'scenes/main.scene';
10
24
  export const DEFAULT_SERVER_TICK_RATE = 20;
package/dist/ide.js CHANGED
@@ -777,6 +777,10 @@ function handleFilesApi(deckDir, req, res, reqPath, restart, invalidate) {
777
777
  try {
778
778
  await updateImport(deckDir, { alias: body.alias });
779
779
  sendJson(res, 200, { ok: true, alias: body.alias });
780
+ // An import is code, and updating it can delete a module the shell
781
+ // still holds, so this needs the same invalidate-then-reload a version
782
+ // restore gets. After the response: the panel shouldn't wait on it.
783
+ setImmediate(() => restart?.());
780
784
  }
781
785
  catch (e) {
782
786
  sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
package/dist/imports.js CHANGED
@@ -6,7 +6,7 @@ import { runTar } from './save-deck.js';
6
6
  import { normalizeDeckPackageJson } from './normalize.js';
7
7
  import { getKitsDir } from './localPaths.js';
8
8
  import { writePlatformDocs } from './platformDoc.js';
9
- import { ensureVisibleGlob, IMPORTS_DIR, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
9
+ import { ensureVisibleGlob, IMPORTS_DIR, STARTER_STYLE_FILES, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
10
10
  // Adding another deck as a dependency (`castle-web add-import`; removing one is a
11
11
  // later command). Deliberately NOT `get-deck`: that one
12
12
  // replaces THIS deck's own source from the server (and carries guards for the
@@ -626,19 +626,25 @@ function seedKitTheme(deckDir, alias, log) {
626
626
  const main = tryReadCastleJson(importDir)?.main;
627
627
  if (typeof main !== 'string' || !main.trim())
628
628
  return;
629
- const src = path.join(importDir, 'theme.style');
630
- const dest = path.join(deckDir, 'theme.style');
631
- if (!fs.existsSync(src) || fs.existsSync(dest))
632
- return;
633
- try {
634
- fs.copyFileSync(src, dest);
629
+ const seeded = [];
630
+ for (const name of STARTER_STYLE_FILES) {
631
+ const src = path.join(importDir, name);
632
+ const dest = path.join(deckDir, name);
633
+ if (!fs.existsSync(src) || fs.existsSync(dest))
634
+ continue;
635
+ try {
636
+ fs.copyFileSync(src, dest);
637
+ }
638
+ catch (e) {
639
+ console.warn(`Could not seed ${name} from ${alias}: ${e instanceof Error ? e.message : String(e)}`);
640
+ continue;
641
+ }
642
+ ensureVisibleGlob(deckDir, name, name);
643
+ seeded.push(name);
635
644
  }
636
- catch (e) {
637
- console.warn(`Could not seed theme.style from ${alias}: ${e instanceof Error ? e.message : String(e)}`);
645
+ if (seeded.length === 0)
638
646
  return;
639
- }
640
- ensureVisibleGlob(deckDir, 'theme.style', 'theme.style');
641
- log(`Seeded theme.style from ${alias} (new in this version; the deck's to edit)`);
647
+ log(`Seeded ${seeded.join(' + ')} from ${alias} (new in this version; the deck's to edit)`);
642
648
  }
643
649
  async function applyImportUpdate(deckDir, alias, update, source, log) {
644
650
  await placeImport(deckDir, alias, update.deckId, source, update.via);
package/dist/init.js CHANGED
@@ -2,7 +2,7 @@ import * as fs from 'fs';
2
2
  import * as path from 'path';
3
3
  import { CLAUDE_MD_PLATFORM_SECTION } from './platformDoc.js';
4
4
  import { installDeps } from './install.js';
5
- import { deckMainFile, deckStarterScene } from './castleJson.js';
5
+ import { deckMainFile, deckStarterScene, STARTER_STYLE_FILES } from './castleJson.js';
6
6
  import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, } from './imports.js';
7
7
  import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
8
8
  import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath, } from './localPaths.js';
@@ -47,6 +47,14 @@ export const BARE_DOCS_KIT = 'blank';
47
47
  // globally-installed castle-web (not from inside the workspace). Bumped
48
48
  // alongside cli/sdk version bumps.
49
49
  const PUBLISHED_SDK_VERSION = '0.4.19';
50
+ // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
51
+ // face can ship without a cli release, and a caret range means an existing
52
+ // deck's next install picks it up. Nothing here has to move when it does.
53
+ // Every deck gets it, used or not -- the platform guide tells the agent to
54
+ // import a Castle face, and an import that fails to resolve makes that a lie.
55
+ // Costs a deck node_modules space and no bundle bytes: a deck inlines only the
56
+ // faces it names (see castle-web-fonts' own scripts/verify.mjs).
57
+ const FONTS_RANGE = '^1.0.0';
50
58
  // The account the first-party kits are (to be) published under, so a kit
51
59
  // imported from the CLI's copy is named the same as one fetched from the server.
52
60
  const KIT_AUTHOR = 'castle';
@@ -132,6 +140,7 @@ function makePackageJson(projectDir) {
132
140
  'save-deck': `${cliCommand} save-deck .`,
133
141
  },
134
142
  dependencies: {
143
+ 'castle-web-fonts': FONTS_RANGE,
135
144
  'castle-web-sdk': sdkRef,
136
145
  },
137
146
  };
@@ -290,18 +299,25 @@ export function writeStarterScene(projectDir, kitDir, alias) {
290
299
  fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
291
300
  writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), rewrite(scene));
292
301
  }
293
- // A kit may ship a starter `theme.style` (deck-level styling, e.g. the color
294
- // palette). Like the starter scene, it is deck content: the engine reads it
295
- // from the DECK root, and it is the creator's to edit -- so it gets seeded once
296
- // at scaffold time rather than living read-only in the import. Copied verbatim
297
- // (its values are palette ids/hexes, never kit file paths, so no ref
298
- // rewriting). Exported for the same two scaffold paths as writeStarterScene.
302
+ // A kit may ship starter style files (deck-level styling: the color palette,
303
+ // the deck font). Like the starter scene, they are deck content: the engine
304
+ // reads them from the DECK root, and they are the creator's to edit -- so they
305
+ // get seeded once at scaffold time rather than living read-only in the import.
306
+ // Copied verbatim (their values are palette ids, hexes and font names, never
307
+ // kit file paths, so no ref rewriting). Exported for the same two scaffold paths
308
+ // as writeStarterScene.
309
+ //
310
+ // The set is STARTER_STYLE_FILES (castleJson.ts), which says why these two
311
+ // travel together: a deck given the record without the generated module renders
312
+ // in the fallback while claiming otherwise.
299
313
  export function writeStarterTheme(projectDir, kitDir) {
300
- const src = path.join(kitDir, 'theme.style');
301
- const dest = path.join(projectDir, 'theme.style');
302
- if (!fs.existsSync(src) || fs.existsSync(dest))
303
- return;
304
- fs.copyFileSync(src, dest);
314
+ for (const name of STARTER_STYLE_FILES) {
315
+ const src = path.join(kitDir, name);
316
+ const dest = path.join(projectDir, name);
317
+ if (!fs.existsSync(src) || fs.existsSync(dest))
318
+ continue;
319
+ fs.copyFileSync(src, dest);
320
+ }
305
321
  }
306
322
  function makeBareClaudeMd(alias) {
307
323
  return `# Castle deck (no kit)
@@ -143,6 +143,37 @@ const COMMON_SECTIONS = `## Imports are read-only
143
143
 
144
144
  - **Load static assets (drawings, audio, etc.) through the bundler — never runtime-\`fetch\` a loose file path.** Use a static \`import\`, \`import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })\`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so \`fetch('drawings/qb.svg')\` looks like it works locally — but \`save-deck\` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw \`fetch\`.
145
145
 
146
+ ## Fonts
147
+
148
+ - **A deck that renders text should reach for a Castle font first.** Castle ships the licensed faces from the Classic engine as web fonts, and every deck already has them installed. Import the ones you want by name and the bundler inlines those faces and no others:
149
+
150
+ \`\`\`js
151
+ import { installTektur } from 'castle-web-fonts';
152
+
153
+ installTektur(); // now: font-family: 'Tektur'
154
+ const family = await installTektur(); // resolves to 'Tektur', once it can be drawn with
155
+ \`\`\`
156
+
157
+ Choose the faces that fit what the deck IS -- there is no house default to fall back on, and any of the nine is a better answer than not choosing. Two or three is the common shape: one for body and UI, one display face for titles, sometimes a third for a specific effect.
158
+
159
+ | face | character | good for |
160
+ |---|---|---|
161
+ | \`DMSans\` | clean geometric sans, low contrast | body, UI, HUD |
162
+ | \`Piazzolla\` | sturdy text serif, readable at length | body text, narrative, prose-heavy decks |
163
+ | \`CourierPrime\` | monospace typewriter serif | code, terminals, typewriter effects |
164
+ | \`Tektur\` | condensed squarish techno | sci-fi, arcade, HUD numerals |
165
+ | \`Bore\` | very heavy wide grotesque | impact headlines, scores, big titles |
166
+ | \`Synco\` | light wide geometric, unusual joins | retro-modernist titles |
167
+ | \`Glacier\` | slanted condensed hand-cut italic | informal, energetic display |
168
+ | \`HelicoCentrica\` | blackletter-flavored roman, pointed serifs | medieval, fantasy, ornate |
169
+ | \`YatraOne\` | high-contrast brushy display (also Devanagari) | bold headlines, South Asian text |
170
+
171
+ Each face has one weight and one style, as in Classic; asking for bold or italic gets the browser's synthesized version.
172
+ - **Prefer these over \`system-ui\` or a webfont URL** when nothing says otherwise. A system stack renders as a different typeface on every device, and a font-CDN URL costs a network round trip and breaks offline -- where these are bundled into the deck and paint on the first frame. That is a default, not a rule: when someone names a face they want, or describes a look the nine don't reach, use what they asked for. Install it as a package so the bundler inlines it the same way -- \`@fontsource/<face>\`, and take its \`latin-\` entry point, since the plain one pulls every unicode subset (\`@fontsource/inter/400.css\` inlines 288 KB where \`latin-400.css\` inlines 72). Don't link a font CDN from the page.
173
+ - **Import the named export per face. Never build a lookup keyed by a font name** (\`FONTS[name]()\`, \`installers[theme.font]\`): no bundler can tell which key gets read, so that inlines all nine faces -- 495 KB -- into the deck. Faces run 12-90 KB each; two or three is normal, all nine is not. When the name has to come from data (a theme file, a saved setting), resolve it to a real import in a generated module rather than at runtime.
174
+ - **Drawing text to a canvas means waiting for the face first.** Canvas 2D does not trigger a font load, so \`ctx.font = '20px Piazzolla'\` before the face is ready silently falls back to the default -- and never repaints when the font lands, so it looks right after a warm reload and wrong on a cold first paint. \`await installPiazzolla()\` before the first frame. CSS needs no such care.
175
+ - If the deck is built on a kit that sets a deck font of its own, that is the deck's body/UI face already -- don't install a second face to do the same job. A display face on top of it is still an ordinary import. Its guide says which is which.
176
+
146
177
  ## Touch controls
147
178
 
148
179
  - **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.
@@ -152,6 +183,43 @@ const COMMON_SECTIONS = `## Imports are read-only
152
183
  - **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.
153
184
  - **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.
154
185
  - 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.
186
+
187
+ ## Multiplayer
188
+
189
+ - **A deck becomes multiplayer by having a \`server/index.js\`** — no flag, no dashboard. The file's presence is the opt-in, and deleting it turns multiplayer off on the next \`save-deck\`. Castle runs that file as a real server process, one per session, shared by the players in it. Options live in \`castle.json\` under \`server\`: \`main\` (defaults to \`server/index.js\`), \`maxPlayers\` (max 24), and \`tickRate\` (max 30; 0, the default, means no tick).
190
+ - **The server module default-exports lifecycle callbacks**, each taking the session first:
191
+
192
+ \`\`\`js
193
+ export default {
194
+ onStart(session) {}, // once, before anyone joins
195
+ onPlayerJoin(session, player) {}, // player: { playerId, userId, username, isAnonymous }
196
+ onPlayerLeave(session, player) {},
197
+ onMessage(session, player, data) {}, // data is what the client sent, already parsed
198
+ onTick(session, dtSeconds) {}, // only when castle.json sets server.tickRate > 0
199
+ onReplaced(session) {}, // you published a new version; this session keeps the old one
200
+ };
201
+ \`\`\`
202
+
203
+ \`session\` gives you \`send(playerId, data)\`, \`broadcast(data, { except })\`, \`disconnect(playerId, reason)\`, \`players\`, \`sessionId\`, \`deckId\`, and \`mode\`.
204
+ - **Player identity comes from Castle, not from the client.** The \`player\` passed to your callbacks is authenticated by the platform, so a client cannot claim to be someone else by putting a name in a message. Trust \`player.userId\`; never trust identity inside \`data\`.
205
+ - **The server is authoritative — put the rules there.** Deck code runs on the player's phone and can be modified, so validate every move on the server and send back state for clients to render. \`playerId\` identifies a connection (stable across a reconnect) while \`userId\` identifies the account, and one account can be in a session twice from two tabs.
206
+ - **The client joins with \`Multiplayer.join\`:**
207
+
208
+ \`\`\`js
209
+ import { Multiplayer } from 'castle-web-sdk';
210
+
211
+ const conn = await Multiplayer.join({ mode: 'named', key: 'lobby-1' });
212
+ conn.onMessage((data) => { /* from your server */ });
213
+ conn.onRoster(({ players, you }) => { /* who is here */ });
214
+ conn.send({ move: 'left' });
215
+ \`\`\`
216
+
217
+ \`named\` puts everyone passing the same \`key\` in one session, which is how you build room codes and invite links. \`public\` drops a player into a shared session for the deck; \`party\` uses the Castle party they are already in.
218
+ - **Always handle \`conn.isSolo\`.** When a player cannot join — signed out, blocked, private deck, or no capacity free — the SDK returns a working single-player connection instead of throwing. Keep the deck playable on its own rather than gating the whole game behind other people showing up.
219
+ - **What the server may and may not do.** Roughly 128MB of memory, no filesystem that survives, and **no network access at all**: no \`fetch\`, no database, no third-party API. Keep state in memory and send it to clients. A session ends once its last player leaves and nothing persists between sessions, so use \`sharedDeckStorage\` for anything that must outlive one.
220
+ - **Limits worth designing around.** Messages from a client are capped at 16KB and about 30 per second; server broadcasts at 64KB. Sending 20–30 updates per second means sending deltas rather than whole-world snapshots, and every player's phone pays for whatever you broadcast.
221
+ - **Test multiplayer locally with no setup.** \`castle-web serve\` runs your server file alongside the deck; open the play URL in two tabs and they share a session. Editing anything under \`server/\` restarts it and clients reconnect, so you exercise your reconnect path constantly. Server \`console.log\` goes to the serve's logs, not the browser console.
222
+ - **Publishing does not disturb games in progress.** \`save-deck\` bundles and publishes \`server/\`, but sessions already running keep the code they started with (they get \`onReplaced\`, so you can prompt players), and the next new session picks up the new version.
155
223
  `;
156
224
  export function platformGuide(deckDir) {
157
225
  return `${COMMON_SECTIONS.trimEnd()}
package/dist/save-deck.js CHANGED
@@ -202,15 +202,15 @@ async function captureAutomaticCover(projectDir) {
202
202
  return outPath;
203
203
  }
204
204
  async function uploadLocalCover(projectDir) {
205
- const captured = await captureAutomaticCover(projectDir);
206
- const coverPath = captured ?? path.join(projectDir, COVER_FILE);
207
- if (captured)
208
- console.log('Captured a cover from the running deck.');
209
- else if (fs.existsSync(coverPath))
210
- console.log('Using the cover captured in the editor.');
211
- if (!fs.existsSync(coverPath))
212
- return null;
213
205
  try {
206
+ const captured = await captureAutomaticCover(projectDir);
207
+ const coverPath = captured ?? path.join(projectDir, COVER_FILE);
208
+ if (captured)
209
+ console.log('Captured a cover from the running deck.');
210
+ else if (fs.existsSync(coverPath))
211
+ console.log('Using the cover captured in the editor.');
212
+ if (!fs.existsSync(coverPath))
213
+ return null;
214
214
  const base64 = fs.readFileSync(coverPath).toString('base64');
215
215
  const file = await api.uploadBase64(base64, COVER_FILE);
216
216
  return file?.fileId ?? null;
@@ -274,6 +274,11 @@ export async function saveDeck(dir, opts = {}) {
274
274
  const isNew = !castleJson;
275
275
  const cardId = castleJson?.cardId ?? nanoid(12);
276
276
  const deckId = castleJson?.deckId ?? nanoid(12);
277
+ // Capturing and uploading the cover depends only on the already-running serve. Start it as
278
+ // soon as the bundle has passed, while the independent scene upload is being authorized and
279
+ // transferred. The promise is deliberately non-throwing: a thumbnail must never make the
280
+ // content upload fail or create an unhandled rejection if that upload exits early.
281
+ const backgroundImageFileIdPromise = uploadLocalCover(projectDir);
277
282
  // Upload scene data to S3
278
283
  const configs = await api.createSceneDataUploadConfig([cardId]);
279
284
  if (!configs?.length) {
@@ -307,7 +312,7 @@ export async function saveDeck(dir, opts = {}) {
307
312
  deckInput.visibility = 'unlisted';
308
313
  if (opts.caption !== undefined)
309
314
  deckInput.caption = opts.caption;
310
- const backgroundImageFileId = await uploadLocalCover(projectDir);
315
+ const backgroundImageFileId = await backgroundImageFileIdPromise;
311
316
  try {
312
317
  const cardInput = {
313
318
  cardId,
package/dist/serve.js CHANGED
@@ -55,7 +55,7 @@ async function findFreePort(startPort) {
55
55
  }
56
56
  throw new Error(`No free port found starting from ${startPort}`);
57
57
  }
58
- function listenLocalContentServer(upstreamHost, upstreamPort, role, security, reserved) {
58
+ function listenLocalContentServer(bindHost, upstreamHost, upstreamPort, role, security, reserved) {
59
59
  const upstreamHeaders = (req) => ({
60
60
  ...req.headers,
61
61
  ...security.localContentProxyHeaders(role),
@@ -81,11 +81,12 @@ function listenLocalContentServer(upstreamHost, upstreamPort, role, security, re
81
81
  });
82
82
  server.on('upgrade', (req, socket, head) => {
83
83
  const multiplayer = isDevMultiplayerUpgrade(req);
84
- if (!isViteClientUpgrade(req) && !multiplayer) {
84
+ const legacyContent = isLegacyContentSocketUpgrade(req);
85
+ if (!isViteClientUpgrade(req) && !multiplayer && !legacyContent) {
85
86
  socket.destroy();
86
87
  return;
87
88
  }
88
- if (multiplayer && !isSameOriginUpgrade(req)) {
89
+ if ((multiplayer || legacyContent) && !isSameOriginUpgrade(req)) {
89
90
  socket.destroy();
90
91
  return;
91
92
  }
@@ -98,7 +99,7 @@ function listenLocalContentServer(upstreamHost, upstreamPort, role, security, re
98
99
  // of the cloud serve contract and must never occupy a future deck port by
99
100
  // convention. Retry the vanishingly rare case where port 0 selects the
100
101
  // main Vite port before Vite itself has bound it.
101
- server.listen(0, '127.0.0.1', () => {
102
+ server.listen(0, bindHost, () => {
102
103
  server.off('error', reject);
103
104
  const address = server.address();
104
105
  const port = typeof address === 'object' && address ? address.port : 0;
@@ -108,7 +109,7 @@ function listenLocalContentServer(upstreamHost, upstreamPort, role, security, re
108
109
  }
109
110
  if (reserved.has(port)) {
110
111
  server.close(() => {
111
- void listenLocalContentServer(upstreamHost, upstreamPort, role, security, reserved).then(resolve, reject);
112
+ void listenLocalContentServer(bindHost, upstreamHost, upstreamPort, role, security, reserved).then(resolve, reject);
112
113
  });
113
114
  return;
114
115
  }
@@ -134,6 +135,15 @@ function proxyViteClientUpgrade(req, socket, head, upstreamHost, upstreamPort, h
134
135
  socket.write(upstreamHead);
135
136
  if (head.length)
136
137
  upstreamSocket.write(head);
138
+ // A piped socket with no error handler takes the whole serve down when a
139
+ // client resets its connection -- a tab closing hard, or a script exiting
140
+ // mid-frame. Tear down the pair instead.
141
+ const drop = () => {
142
+ socket.destroy();
143
+ upstreamSocket.destroy();
144
+ };
145
+ socket.on('error', drop);
146
+ upstreamSocket.on('error', drop);
137
147
  socket.pipe(upstreamSocket).pipe(socket);
138
148
  });
139
149
  upstream.on('response', (response) => {
@@ -162,12 +172,21 @@ function isDevMultiplayerUpgrade(req) {
162
172
  return false;
163
173
  }
164
174
  }
165
- async function startLocalContentServers(upstreamHost, upstreamPort, security, reserved) {
175
+ const LEGACY_CONTENT_WS_PATH = '/__castle/ws-legacy';
176
+ function isLegacyContentSocketUpgrade(req) {
177
+ try {
178
+ return new URL(req.url || '/', 'http://localhost').pathname === LEGACY_CONTENT_WS_PATH;
179
+ }
180
+ catch {
181
+ return false;
182
+ }
183
+ }
184
+ async function startLocalContentServers(bindHost, upstreamHost, upstreamPort, security, reserved) {
166
185
  const servers = [];
167
186
  const ports = {};
168
187
  try {
169
188
  for (const role of ['edit', 'play']) {
170
- const listening = await listenLocalContentServer(upstreamHost, upstreamPort, role, security, reserved);
189
+ const listening = await listenLocalContentServer(bindHost, upstreamHost, upstreamPort, role, security, reserved);
171
190
  servers.push(listening.server);
172
191
  ports[role] = listening.port;
173
192
  reserved.add(listening.port);
@@ -334,8 +353,23 @@ window.__castleShellOrigin=(function(){
334
353
  res.end(JSON.stringify({ ticket: security.issueTicket(endpoint) }));
335
354
  return;
336
355
  }
356
+ // SDK <=0.4.16 discovers a direct socket here. Admit it through a
357
+ // one-use role-bound path so old editors keep saving while the play
358
+ // capability retains the same no-write boundary as the modern bridge.
359
+ if (reqPath === '/__castle/ws-port') {
360
+ if (!contentRole || req.method !== 'GET') {
361
+ res.writeHead(404).end();
362
+ return;
363
+ }
364
+ const ticket = security.issueLegacyContentTicket(contentRole);
365
+ res.writeHead(200, {
366
+ 'content-type': 'application/json',
367
+ 'cache-control': 'no-store',
368
+ });
369
+ res.end(JSON.stringify({ path: `${LEGACY_CONTENT_WS_PATH}?ticket=${ticket}` }));
370
+ return;
371
+ }
337
372
  if (reqPath === '/__castle/auth' ||
338
- reqPath === '/__castle/ws-port' ||
339
373
  reqPath === '/__castle/context') {
340
374
  res.writeHead(404).end();
341
375
  return;
@@ -478,6 +512,13 @@ const DEFAULT_PORT = 5757;
478
512
  // them (an import listing goes on to the browser's castle-www host and its
479
513
  // GraphQL scans); an unanswered id just sits in the map until this expires.
480
514
  const PENDING_REQUEST_TTL_MS = 30_000;
515
+ const BRIDGED_CONTENT_MESSAGES = new Set([
516
+ 'log',
517
+ 'screenshot_response',
518
+ 'write_file',
519
+ 'castle_command',
520
+ ]);
521
+ const LEGACY_CONTENT_MESSAGES = new Set([...BRIDGED_CONTENT_MESSAGES, 'ping']);
481
522
  function readServeJson(projectDir) {
482
523
  try {
483
524
  const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
@@ -697,7 +738,16 @@ export async function serve(dir, options = {}) {
697
738
  : options.host === '::'
698
739
  ? '::1'
699
740
  : options.host;
700
- const localContentServers = await startLocalContentServers(upstreamHost, port, security, new Set([port]));
741
+ // Content origins follow --host: a serve bound to a tailnet/LAN address is
742
+ // being viewed from another device, where loopback is that device's own.
743
+ const contentBindHost = !options.host ||
744
+ options.host === 'localhost' ||
745
+ options.host === '0.0.0.0' ||
746
+ options.host === '::'
747
+ ? '127.0.0.1'
748
+ : options.host;
749
+ security.setLocalContentHost(contentBindHost);
750
+ const localContentServers = await startLocalContentServers(contentBindHost, upstreamHost, port, security, new Set([port]));
701
751
  process.on('exit', () => {
702
752
  for (const server of localContentServers)
703
753
  server.close();
@@ -938,29 +988,47 @@ async function serveDetached(projectDir, options) {
938
988
  }
939
989
  function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security, multiplayer) {
940
990
  // The control socket is upgraded directly on Vite's HTTP server. Browser
941
- // clients use the named path and a one-use ticket. The root path is accepted
991
+ // shell clients use the named path and a one-use ticket; pre-bridge SDKs use
992
+ // a separate ticket carrying their content role. The root path is accepted
942
993
  // only from loopback clients with no Origin so older CLI versions can read
943
994
  // wsPort from a new serve.json and continue to connect during rollout.
944
995
  const wss = new WebSocketServer({
945
996
  noServer: true,
946
997
  maxPayload: 12 * 1024 * 1024,
947
998
  });
999
+ const legacyRoles = new WeakMap();
948
1000
  const handleUpgrade = (req, socket, head) => {
949
1001
  const pathname = new URL(req.url || '/', 'http://localhost').pathname;
950
1002
  const hasOrigin = Boolean(req.headers.origin);
951
1003
  const isNamedPath = pathname === '/__castle/ws';
952
1004
  const isLegacyCliPath = pathname === '/' && !hasOrigin;
953
- if (!isNamedPath && !isLegacyCliPath)
1005
+ const isLegacyContentPath = pathname === LEGACY_CONTENT_WS_PATH;
1006
+ if (!isNamedPath && !isLegacyCliPath && !isLegacyContentPath)
954
1007
  return false;
955
1008
  const loopback = req.socket.remoteAddress === '127.0.0.1' || req.socket.remoteAddress === '::1';
956
- const authorized = hasOrigin
957
- ? isNamedPath && isSameOriginUpgrade(req) && security.consumeTicket(req, 'serve')
958
- : loopback;
1009
+ let legacyRole = null;
1010
+ let authorized;
1011
+ if (isLegacyContentPath) {
1012
+ legacyRole = security.consumeLegacyContentTicket(req);
1013
+ const assertedRole = security.verifyContentRequest(req);
1014
+ authorized =
1015
+ legacyRole !== null &&
1016
+ (assertedRole === legacyRole || (assertedRole === null && isSameOriginUpgrade(req)));
1017
+ }
1018
+ else {
1019
+ authorized = hasOrigin
1020
+ ? isNamedPath && isSameOriginUpgrade(req) && security.consumeTicket(req, 'serve')
1021
+ : loopback;
1022
+ }
959
1023
  if (!authorized) {
960
1024
  socket.destroy();
961
1025
  return true;
962
1026
  }
963
- wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
1027
+ wss.handleUpgrade(req, socket, head, (ws) => {
1028
+ if (legacyRole)
1029
+ legacyRoles.set(ws, legacyRole);
1030
+ wss.emit('connection', ws, req);
1031
+ });
964
1032
  return true;
965
1033
  };
966
1034
  const clients = new Set();
@@ -985,6 +1053,7 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
985
1053
  wss.on('connection', (ws, req) => {
986
1054
  clients.add(ws);
987
1055
  const multiplayerUrl = devMultiplayerUrl(req);
1056
+ const legacyRole = legacyRoles.get(ws) ?? null;
988
1057
  ws.on('message', (raw) => {
989
1058
  try {
990
1059
  const text = Array.isArray(raw)
@@ -996,6 +1065,8 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
996
1065
  let bridgeRole = null;
997
1066
  let bridgeContentOrigin = null;
998
1067
  if (msg.type === 'deck_bridge') {
1068
+ if (legacyRole)
1069
+ return;
999
1070
  if ((msg.role !== 'edit' && msg.role !== 'play') ||
1000
1071
  !msg.message ||
1001
1072
  typeof msg.message !== 'object')
@@ -1003,10 +1074,12 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
1003
1074
  bridgeRole = msg.role;
1004
1075
  bridgeContentOrigin = trustedBridgeContentOrigin(security, req, bridgeRole, msg.contentOrigin);
1005
1076
  msg = msg.message;
1006
- const allowed = new Set(['log', 'screenshot_response', 'write_file', 'castle_command']);
1007
- if (!allowed.has(String(msg.type)))
1077
+ if (!BRIDGED_CONTENT_MESSAGES.has(String(msg.type)))
1008
1078
  return;
1009
1079
  }
1080
+ else if (legacyRole && !LEGACY_CONTENT_MESSAGES.has(String(msg.type))) {
1081
+ return;
1082
+ }
1010
1083
  // Liveness. A client asks so it can tell a live connection from one that
1011
1084
  // died without a close -- the state a sleeping laptop or a dropped
1012
1085
  // network leaves behind, which `readyState` reports as OPEN forever.
@@ -1110,7 +1183,7 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
1110
1183
  }
1111
1184
  }
1112
1185
  if (msg.type === 'write_file') {
1113
- if (bridgeRole === 'play') {
1186
+ if ((bridgeRole ?? legacyRole) === 'play') {
1114
1187
  ws.send(JSON.stringify({
1115
1188
  type: 'write_file_response',
1116
1189
  requestId: msg.requestId,
@@ -20,12 +20,18 @@ export declare class ServeSecurity {
20
20
  private readonly serveNonce;
21
21
  private readonly tickets;
22
22
  private localContentPorts;
23
+ private localContentHost;
23
24
  constructor(publicPort: number, localContentPorts?: LocalContentPorts);
24
25
  setLocalContentPorts(ports: LocalContentPorts): void;
26
+ setLocalContentHost(host: string): void;
25
27
  authorizeHttp(req: http.IncomingMessage): boolean;
26
28
  rejectHttpAuth(res: http.ServerResponse): void;
27
29
  issueTicket(endpoint: SocketEndpoint): string;
30
+ /** One-use admission for an SDK that predates the shell's MessagePort bridge. */
31
+ issueLegacyContentTicket(role: ContentRole): string;
28
32
  consumeTicket(req: http.IncomingMessage, endpoint: SocketEndpoint): boolean;
33
+ /** Consume and recover the edit/play role bound to a legacy content ticket. */
34
+ consumeLegacyContentTicket(req: http.IncomingMessage): ContentRole | null;
29
35
  private pruneTickets;
30
36
  shellBootstrap(req: http.IncomingMessage): string;
31
37
  contentOrigins(req: http.IncomingMessage): {