castle-web-cli 0.4.161 → 0.4.163

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 (66) hide show
  1. package/dist/agent.js +56 -5
  2. package/dist/devSessionChild.js +23 -0
  3. package/dist/devSessionServer.js +49 -4
  4. package/dist/init.js +1 -1
  5. package/dist/platformDoc.js +2 -1
  6. package/dist/shell/assets/index-BJO7LVCM.js +422 -0
  7. package/dist/shell/index.html +1 -1
  8. package/kits/base/castle.json +1 -1
  9. package/kits/base/package-lock.json +1 -1
  10. package/kits/base/sdk/README.md +12 -1
  11. package/kits/base/sdk/multiplayer.d.ts +2 -0
  12. package/kits/base/sdk/multiplayer.js +59 -16
  13. package/kits/base/sdk/multiplayerProtocol.d.ts +3 -0
  14. package/kits/base/sdk/multiplayerProtocol.js +13 -0
  15. package/kits/base/sdk/server/platformHandle.d.ts +3 -0
  16. package/kits/base/sdk/server/wrapper.d.ts +3 -0
  17. package/kits/base/sdk/server/wrapper.js +42 -0
  18. package/kits/blank/.castle/agent/children.json +1 -0
  19. package/kits/blank/.castle/agent/messages.json +9 -0
  20. package/kits/blank/.castle/agent/pending-sends.json +1 -0
  21. package/kits/blank/.castle/agent/tasks/index.md +2 -0
  22. package/kits/blank/.castle/docs/platform.md +36 -0
  23. package/kits/blank/node_modules/.vite/deps/_metadata.json +8 -0
  24. package/kits/blank/node_modules/.vite/deps/package.json +3 -0
  25. package/package.json +1 -1
  26. package/dist/shell/assets/index-DMSoTyXh.js +0 -441
  27. package/kits/base/node_modules/.package-lock.json +0 -28
  28. package/kits/base/node_modules/castle-web-fonts/README.md +0 -114
  29. package/kits/base/node_modules/castle-web-fonts/dist/catalog.d.ts +0 -18
  30. package/kits/base/node_modules/castle-web-fonts/dist/catalog.js +0 -142
  31. package/kits/base/node_modules/castle-web-fonts/dist/face.d.ts +0 -1
  32. package/kits/base/node_modules/castle-web-fonts/dist/face.js +0 -52
  33. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +0 -3
  34. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.js +0 -10
  35. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +0 -3
  36. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +0 -10
  37. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +0 -3
  38. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.js +0 -10
  39. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +0 -3
  40. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.js +0 -10
  41. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +0 -3
  42. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +0 -10
  43. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +0 -3
  44. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +0 -10
  45. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +0 -3
  46. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.js +0 -10
  47. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +0 -3
  48. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.js +0 -10
  49. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +0 -3
  50. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.js +0 -10
  51. package/kits/base/node_modules/castle-web-fonts/dist/index.d.ts +0 -16
  52. package/kits/base/node_modules/castle-web-fonts/dist/index.js +0 -15
  53. package/kits/base/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +0 -393
  54. package/kits/base/node_modules/castle-web-fonts/licenses/FONTS.md +0 -64
  55. package/kits/base/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +0 -95
  56. package/kits/base/node_modules/castle-web-fonts/package.json +0 -47
  57. package/kits/base/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  58. package/kits/base/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  59. package/kits/base/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  60. package/kits/base/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  61. package/kits/base/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  62. package/kits/base/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  63. package/kits/base/node_modules/castle-web-fonts/woff2/SOURCE.txt +0 -2
  64. package/kits/base/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  65. package/kits/base/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  66. package/kits/base/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
@@ -10,7 +10,7 @@
10
10
  <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
11
11
  <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
12
12
  <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
13
- <script type="module" crossorigin src="/__castle/ide/assets/index-DMSoTyXh.js"></script>
13
+ <script type="module" crossorigin src="/__castle/ide/assets/index-BJO7LVCM.js"></script>
14
14
  <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-DfZmu3XC.css">
15
15
  </head>
16
16
  <body>
@@ -7,7 +7,7 @@
7
7
  "title": "base",
8
8
  "deckId": "yRcmH4_aYllE",
9
9
  "cardId": "zkFdingmIm3m",
10
- "publishedVersion": "2026-09-02T05:55:03.005Z",
10
+ "publishedVersion": "2026-09-03T02:17:00.583Z",
11
11
  "provides": [
12
12
  "castle-web-sdk"
13
13
  ]
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "../../sdk": {
16
16
  "name": "castle-web-sdk",
17
- "version": "0.4.24",
17
+ "version": "0.4.25",
18
18
  "dev": true,
19
19
  "devDependencies": {
20
20
  "eslint": "^9.0.0",
@@ -54,7 +54,18 @@ metadata distinguishes a server `bye`, a replaced server version, an explicit
54
54
 
55
55
  When Castle selects solo fallback, the returned connection has `isSolo === true`,
56
56
  a one-player roster, and no server process. Calls to `send` are accepted but do
57
- nothing. Client frames are limited to 16KB after JSON serialization.
57
+ nothing. Client→server frames are limited to 16 KB on the wire.
58
+
59
+ ### Binary messages
60
+
61
+ Pass any typed array, `DataView`, or `ArrayBuffer` to client `send`, server `send`,
62
+ or server `broadcast` to send its raw bytes. Receivers always get those bytes as a
63
+ `Uint8Array`; reconstruct another view type such as `Float32Array` on receipt.
64
+ Multi-byte values use the sender platform's byte order. Every other payload uses
65
+ JSON. Client→server messages are capped at 16 KB and server→client messages at
66
+ 64 KB, for both JSON and binary frames. A binary frame includes a one-byte protocol
67
+ tag. A published server bundle on an older runtime throws
68
+ `TypeError: This Castle runtime does not support binary multiplayer messages yet.`
58
69
 
59
70
  Server callbacks are the default export from the deck's server entry. They are
60
71
  session-first and receive only platform-trusted player identities:
@@ -31,7 +31,9 @@ export interface MultiplayerConnection {
31
31
  readonly playerId: string;
32
32
  readonly sessionId: string;
33
33
  readonly isSolo: boolean;
34
+ /** Sends byte payloads as binary frames and all other payloads as JSON. */
34
35
  send(data: unknown): void;
36
+ /** Receives binary payloads as Uint8Array values and JSON payloads otherwise. */
35
37
  onMessage(callback: (data: unknown) => void): () => void;
36
38
  onRoster(callback: (roster: MultiplayerRoster) => void): () => void;
37
39
  onStateChange(callback: (state: MultiplayerConnectionState, metadata?: MultiplayerStateMetadata) => void): () => void;
@@ -1,5 +1,5 @@
1
1
  import { CastleError } from "./errors";
2
- import { MAX_CLIENT_FRAME_BYTES, } from "./multiplayerProtocol";
2
+ import { BINARY_MESSAGE_TAG, isBinaryPayload, MAX_CLIENT_FRAME_BYTES, toUint8Array, } from "./multiplayerProtocol";
3
3
  import { hostRequest } from "./transport";
4
4
  const KEEPALIVE_INTERVAL_MS = 25_000;
5
5
  const HELLO_TIMEOUT_MS = 10_000;
@@ -70,7 +70,9 @@ class MultiplayerConnectionImpl {
70
70
  // has no useful branch to take meanwhile, so those messages are dropped.
71
71
  // State arrives in whole snapshots, so the next send past recovery is current.
72
72
  send(data) {
73
- const text = serializeClientMessage(data);
73
+ const payload = isBinaryPayload(data)
74
+ ? serializeClientBinaryMessage(data)
75
+ : serializeClientMessage(data);
74
76
  if (this.currentState === "closed") {
75
77
  throw multiplayerError("MULTIPLAYER_NOT_CONNECTED", "Multiplayer.send requires a connected session.", "Multiplayer.send");
76
78
  }
@@ -78,7 +80,7 @@ class MultiplayerConnectionImpl {
78
80
  return;
79
81
  if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
80
82
  return;
81
- this.socket.send(text);
83
+ this.socket.send(payload);
82
84
  }
83
85
  onMessage(callback) {
84
86
  this.messages.add(callback);
@@ -132,27 +134,48 @@ class MultiplayerConnectionImpl {
132
134
  openSocket(credential, value) {
133
135
  const attempt = ++this.socketAttempt;
134
136
  const socket = new WebSocket(authenticatedUrl(this.baseUrl, credential, value));
137
+ socket.binaryType = "arraybuffer";
135
138
  this.socket = socket;
136
139
  return new Promise((resolve, reject) => {
137
140
  let greeted = false;
141
+ let inbound = Promise.resolve();
142
+ const isCurrent = () => this.socketAttempt === attempt &&
143
+ this.currentState !== "closed" &&
144
+ this.socket === socket;
138
145
  const timeout = setTimeout(() => {
139
146
  reject(new SocketClosedError(1006));
140
147
  closeSocket(socket, 1000, "hello timeout");
141
148
  }, HELLO_TIMEOUT_MS);
142
149
  socket.onmessage = (event) => {
143
- if (this.socketAttempt !== attempt || this.currentState === "closed")
144
- return;
145
- const frame = parsePlatformFrame(event.data);
146
- if (!frame)
147
- return;
148
- if (frame.t === "hello") {
149
- greeted = true;
150
- clearTimeout(timeout);
151
- this.acceptHello(frame);
152
- resolve();
153
- return;
154
- }
155
- this.handleFrame(frame);
150
+ const data = event.data;
151
+ inbound = inbound
152
+ .then(async () => {
153
+ if (!isCurrent())
154
+ return;
155
+ if (data instanceof ArrayBuffer) {
156
+ this.dispatchBinary(data, greeted);
157
+ return;
158
+ }
159
+ if (typeof Blob !== "undefined" && data instanceof Blob) {
160
+ const buffer = await data.arrayBuffer();
161
+ if (!isCurrent())
162
+ return;
163
+ this.dispatchBinary(buffer, greeted);
164
+ return;
165
+ }
166
+ const frame = parsePlatformFrame(data);
167
+ if (!frame)
168
+ return;
169
+ if (frame.t === "hello") {
170
+ greeted = true;
171
+ clearTimeout(timeout);
172
+ this.acceptHello(frame);
173
+ resolve();
174
+ return;
175
+ }
176
+ this.handleFrame(frame);
177
+ })
178
+ .catch(() => { });
156
179
  };
157
180
  socket.onclose = (event) => {
158
181
  clearTimeout(timeout);
@@ -210,6 +233,16 @@ class MultiplayerConnectionImpl {
210
233
  break;
211
234
  }
212
235
  }
236
+ dispatchBinary(buffer, greeted) {
237
+ if (!greeted)
238
+ return;
239
+ const bytes = new Uint8Array(buffer);
240
+ if (bytes.byteLength < 1 || bytes[0] !== BINARY_MESSAGE_TAG)
241
+ return;
242
+ const payload = new Uint8Array(buffer, 1);
243
+ for (const callback of this.messages)
244
+ callListener(callback, payload);
245
+ }
213
246
  acceptRoster(frame) {
214
247
  const players = frame.players.slice();
215
248
  const you = players.find((player) => player.playerId === this.currentPlayerId) ?? null;
@@ -363,6 +396,16 @@ function serializeClientMessage(data) {
363
396
  }
364
397
  return text;
365
398
  }
399
+ function serializeClientBinaryMessage(data) {
400
+ const payload = toUint8Array(data);
401
+ if (payload.byteLength + 1 > MAX_CLIENT_FRAME_BYTES) {
402
+ throw multiplayerError("MULTIPLAYER_MESSAGE_TOO_LARGE", `Multiplayer.send messages are limited to ${MAX_CLIENT_FRAME_BYTES} bytes.`, "Multiplayer.send");
403
+ }
404
+ const frame = new Uint8Array(payload.byteLength + 1);
405
+ frame[0] = BINARY_MESSAGE_TAG;
406
+ frame.set(payload, 1);
407
+ return frame;
408
+ }
366
409
  function authenticatedUrl(baseUrl, credential, value) {
367
410
  const fallback = typeof window === "undefined" ? undefined : window.location.href;
368
411
  const url = new URL(baseUrl, fallback);
@@ -1,5 +1,8 @@
1
1
  export declare const MAX_CLIENT_FRAME_BYTES: number;
2
2
  export declare const MAX_PLAYERS_CAP = 24;
3
+ export declare const BINARY_MESSAGE_TAG = 1;
4
+ export declare function isBinaryPayload(value: unknown): value is ArrayBuffer | ArrayBufferView;
5
+ export declare function toUint8Array(value: ArrayBuffer | ArrayBufferView): Uint8Array;
3
6
  export type SessionType = "named" | "party" | "public";
4
7
  export interface PlayerIdentity {
5
8
  userId: string;
@@ -3,3 +3,16 @@
3
3
  // published and must not pull the server package into deck bundles.
4
4
  export const MAX_CLIENT_FRAME_BYTES = 16 * 1024;
5
5
  export const MAX_PLAYERS_CAP = 24;
6
+ // Binary client wire frames are one tag byte (0x01) followed by the opaque
7
+ // author payload. The frame-size limit includes both the tag and payload.
8
+ export const BINARY_MESSAGE_TAG = 0x01;
9
+ // ArrayBuffer and every ArrayBufferView (typed arrays and DataView) are sent as
10
+ // their raw bytes. Receivers always see a Uint8Array over those bytes.
11
+ export function isBinaryPayload(value) {
12
+ return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
13
+ }
14
+ export function toUint8Array(value) {
15
+ return value instanceof ArrayBuffer
16
+ ? new Uint8Array(value)
17
+ : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
18
+ }
@@ -15,10 +15,13 @@ export interface PlatformSessionConfig {
15
15
  export interface PlatformHandle {
16
16
  send(connId: string, text: string): void;
17
17
  broadcast(text: string): void;
18
+ sendBinary?(connId: string, bytes: Uint8Array | ArrayBuffer): void;
19
+ broadcastBinary?(bytes: Uint8Array | ArrayBuffer): void;
18
20
  disconnect(connId: string, code: string | number): void;
19
21
  on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
20
22
  on(event: "leave", callback: (connId: string) => unknown): void;
21
23
  on(event: "message", callback: (connId: string, text: string) => unknown): void;
24
+ on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
22
25
  on(event: "replaced", callback: () => unknown): void;
23
26
  on(event: "shutdown", callback: (reason?: string) => unknown): void;
24
27
  readonly config: PlatformSessionConfig;
@@ -11,7 +11,9 @@ export interface MultiplayerServerSession {
11
11
  readonly sessionId: string;
12
12
  readonly deckId: string;
13
13
  readonly mode: MultiplayerSessionMode;
14
+ /** Sends bytes as a binary message and all other payloads as JSON. */
14
15
  send(playerId: string, data: unknown): void;
16
+ /** Broadcasts bytes as a binary message and all other payloads as JSON. */
15
17
  broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
16
18
  disconnect(playerId: string, reason?: string): void;
17
19
  }
@@ -20,6 +22,7 @@ export interface MultiplayerServerCallbacks {
20
22
  onStart?: (session: MultiplayerServerSession) => CallbackResult;
21
23
  onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
22
24
  onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
25
+ /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
23
26
  onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
24
27
  onTick?: (session: MultiplayerServerSession) => CallbackResult;
25
28
  onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
@@ -1,3 +1,4 @@
1
+ import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
1
2
  // The publish bundler binds the author's default callbacks export once and
2
3
  // exports the returned one-argument function as `__castleBootSession`.
3
4
  export function createCastleSessionBoot(callbacks) {
@@ -29,6 +30,17 @@ async function bootSession(platformHandle, callbacks) {
29
30
  return;
30
31
  await callbacks.onMessage?.(session, player, parseHandleMessage(text));
31
32
  });
33
+ try {
34
+ platformHandle.on("binaryMessage", async (connId, bytes) => {
35
+ const player = players.get(connId);
36
+ if (!player)
37
+ return;
38
+ await callbacks.onMessage?.(session, player, bytes);
39
+ });
40
+ }
41
+ catch {
42
+ // Older shims may reject event names they do not recognize.
43
+ }
32
44
  platformHandle.on("replaced", async () => {
33
45
  await callbacks.onReplaced?.(session);
34
46
  });
@@ -54,9 +66,28 @@ function createAuthorSession(platformHandle, players) {
54
66
  deckId: platformHandle.config.deckId,
55
67
  mode: platformHandle.config.mode,
56
68
  send(playerId, data) {
69
+ if (isBinaryPayload(data)) {
70
+ requireSendBinary(platformHandle);
71
+ platformHandle.sendBinary(playerId, toUint8Array(data));
72
+ return;
73
+ }
57
74
  platformHandle.send(playerId, stringifyHandleMessage(data));
58
75
  },
59
76
  broadcast(data, options) {
77
+ if (isBinaryPayload(data)) {
78
+ const bytes = toUint8Array(data);
79
+ if (!options?.except) {
80
+ requireBroadcastBinary(platformHandle);
81
+ platformHandle.broadcastBinary(bytes);
82
+ return;
83
+ }
84
+ requireSendBinary(platformHandle);
85
+ for (const playerId of players.keys()) {
86
+ if (playerId !== options.except)
87
+ platformHandle.sendBinary(playerId, bytes);
88
+ }
89
+ return;
90
+ }
60
91
  const text = stringifyHandleMessage(data);
61
92
  if (!options?.except) {
62
93
  platformHandle.broadcast(text);
@@ -72,6 +103,17 @@ function createAuthorSession(platformHandle, players) {
72
103
  },
73
104
  };
74
105
  }
106
+ function requireSendBinary(platformHandle) {
107
+ if (typeof platformHandle.sendBinary !== "function")
108
+ unsupportedBinaryRuntime();
109
+ }
110
+ function requireBroadcastBinary(platformHandle) {
111
+ if (typeof platformHandle.broadcastBinary !== "function")
112
+ unsupportedBinaryRuntime();
113
+ }
114
+ function unsupportedBinaryRuntime() {
115
+ throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
116
+ }
75
117
  function joinedPlayer(connId, identity) {
76
118
  if (typeof connId === "string")
77
119
  return { ...identity, playerId: connId };
@@ -0,0 +1 @@
1
+ []
@@ -0,0 +1,9 @@
1
+ [
2
+ {
3
+ "id": "YzUYA2mw",
4
+ "role": "assistant",
5
+ "text": "Welcome to an early test of Castle's new engine! You're starting with a blank deck, without the official art or scene editors, but if HTML and JavaScript can do it then I can help you build it.\n\nDo you already know what you want to make, or do you want to figure it out together?",
6
+ "at": "2026-08-27T19:05:49.289Z",
7
+ "status": "done"
8
+ }
9
+ ]
@@ -0,0 +1,2 @@
1
+ # tasks
2
+ # <task-id> | <item> | <title> | <created> | <status> | <touching>
@@ -0,0 +1,36 @@
1
+ # Castle platform
2
+
3
+ How every Castle deck works, from the Castle CLI. Written fresh at every serve
4
+ start; the deck's own guide (its kit's CLAUDE.md under imports/) adds what its
5
+ kit provides on top of this.
6
+
7
+ ## Imports are read-only
8
+
9
+ - **`imports/` holds other decks' files and is locked read-only on disk.** Files are mode 0444 and directories 0555, so any shell command that writes, moves, or deletes inside `imports/` fails with `EACCES` / "Permission denied" — that is the lock working, not a broken checkout. Do not `chmod` around it, do not `sudo`, and do not retry the command a different way.
10
+ - **Change an import through the CLI, never the filesystem.** `castle-web add-import <deckIdOrUrl>` adds one and `castle-web update-import [alias]` re-fetches it (`--check` to see if it is outdated, `--revert` to undo). These handle the unlock/relock themselves.
11
+ - **`castle-web list-decks [--kind mine|saved|kits]` is how you find out WHAT can be imported** — one deck per line, starting with the id `add-import` takes, and marked when this deck already has it. `imports/` only shows what is here already; it is not a catalogue.
12
+ - **To change one file of an import, FORK it**: `castle-web fork-import-file <path>` takes this deck's own version of that file, and every reference to the imported path uses your version from then on (`castle-web revert-import-file <path>` drops it and goes back to the import's). Fork only what you actually need to change, and as few files as you can -- a forked file stops taking the import's updates, so the more you fork the less an `update-import` can give you. To build something of your own rather than change theirs, write an ordinary file in this deck instead -- and check first whether the kit already lets a deck file register what you want (its CLAUDE.md names those seams), since that path keeps taking updates and a fork does not. When you do fork, it is often worth forking only to add a hook or registration point and keeping the logic itself in a deck file, so later changes need no further forks; for a quick one-off tweak a plain direct fork is fine.
13
+ - **Deleting the deck directory itself needs the lock released first** (`chmod -R u+w` on the deck dir) — that is the one legitimate reason to touch the modes, and only for a directory being thrown away.
14
+
15
+ ## Assets
16
+
17
+ - **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`.
18
+
19
+ ## Touch controls
20
+
21
+ - **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.
22
+
23
+ ## Fit the card
24
+
25
+ - **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.
26
+ - **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.
27
+ - 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.
28
+
29
+ ## Formats, reloading, editors
30
+
31
+ - **Supported media formats are exactly**: images `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg`, audio `.mp3` `.wav` `.m4a`, video `.mp4` (H.264). Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
32
+ - To add an npm package, put it in `package.json` `dependencies` and run `castle-web install .` (the install `init` ran; it uses whichever package manager made the lockfile).
33
+ - Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.
34
+ - The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.
35
+ - An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.
36
+ - Unprompted, an editor is an offer, never a build: when the same data keeps getting edited by hand, propose one and build on the user's yes. Never during a first build.
@@ -0,0 +1,8 @@
1
+ {
2
+ "hash": "39e56a5d",
3
+ "configHash": "5ff7cbd8",
4
+ "lockfileHash": "78d11399",
5
+ "browserHash": "61f2844b",
6
+ "optimized": {},
7
+ "chunks": {}
8
+ }
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "module"
3
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.161",
3
+ "version": "0.4.163",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "castle-web": "./dist/index.js"