castle-web-cli 0.4.208 → 0.4.209

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 (53) hide show
  1. package/dist/api.d.ts +5 -0
  2. package/dist/castle-host/host.js +151 -0
  3. package/dist/castleJson.d.ts +4 -0
  4. package/dist/castleJson.js +3 -1
  5. package/dist/devSessionServer.js +1 -0
  6. package/dist/editorConfig.d.ts +12 -0
  7. package/dist/editorConfig.js +72 -6
  8. package/dist/init.js +1 -1
  9. package/dist/native/loop.js +1 -1
  10. package/dist/native/playtest-executor.js +36 -4
  11. package/dist/native/playtest-remote.d.ts +1 -0
  12. package/dist/native/playtest-remote.js +61 -5
  13. package/dist/native/playtest.d.ts +35 -2
  14. package/dist/native/playtest.js +162 -18
  15. package/dist/platformDoc.d.ts +1 -0
  16. package/dist/platformDoc.js +24 -3
  17. package/dist/playUrl.d.ts +3 -0
  18. package/dist/playUrl.js +12 -0
  19. package/dist/save-deck.js +1 -0
  20. package/dist/shell/assets/{index-b_bebkRb.css → index-BCrgYh76.css} +1 -1
  21. package/dist/shell/assets/{index-C6SXXPwm.js → index-DzLbNBc7.js} +68 -68
  22. package/dist/shell/index.html +2 -2
  23. package/kits/base/CLAUDE.md +1 -0
  24. package/kits/base/castle.json +1 -1
  25. package/kits/base/sdk/README.md +70 -7
  26. package/kits/base/sdk/castle.d.ts +1 -0
  27. package/kits/base/sdk/commands.d.ts +48 -0
  28. package/kits/base/sdk/commands.js +25 -0
  29. package/kits/base/sdk/multiplayer.d.ts +3 -0
  30. package/kits/base/sdk/multiplayer.js +13 -0
  31. package/kits/base/sdk/multiplayerVoice.d.ts +67 -0
  32. package/kits/base/sdk/multiplayerVoice.js +309 -0
  33. package/kits/base/sdk/transport.d.ts +2 -1
  34. package/kits/base/sdk/transport.js +15 -1
  35. package/kits/multiplayer-2d/castle.json +2 -2
  36. package/kits/multiplayer-2d/code/systems/multiplayer.js +7 -1
  37. package/kits/multiplayer-3d/castle.json +2 -2
  38. package/kits/multiplayer-3d/code/systems/multiplayer.js +8 -4
  39. package/kits/physics-2d/castle.json +1 -1
  40. package/kits/physics-2d/editors/SceneEditor.jsx +18 -4
  41. package/kits/physics-2d/systems/media.js +3 -5
  42. package/kits/physics-3d/castle.json +2 -2
  43. package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
  44. package/kits/physics-3d/engine3d/pxmodel.js +7 -0
  45. package/kits/real-time/CLAUDE.md +3 -0
  46. package/kits/real-time/castle.json +1 -1
  47. package/kits/real-time/code/client/connection.js +17 -2
  48. package/kits/real-time/code/client/gameHooks.js +5 -0
  49. package/kits/real-time/code/client/joinOverlay.js +23 -5
  50. package/kits/real-time/code/client/messages.js +4 -0
  51. package/kits/real-time/code/server/persist.js +19 -10
  52. package/kits/real-time/code/server/session.js +19 -0
  53. package/package.json +2 -2
@@ -12,6 +12,9 @@ export declare const PLAYTEST_MAX_CONSOLE_TEXT_BYTES: number;
12
12
  export declare const PLAYTEST_FAILURE_CONSOLE_TEXT_MAX_BYTES = 1024;
13
13
  export declare const PLAYTEST_FAILURE_OUTPUT_MAX_BYTES: number;
14
14
  export type PlaytestActionType = "down" | "move" | "up" | "tap" | "key";
15
+ export type PlaytestInput = "mouse" | "touch";
16
+ export declare const PLAYTEST_INPUTS: readonly PlaytestInput[];
17
+ export declare const PLAYTEST_ENTRY_FILE = "index.html";
15
18
  export interface PlaytestActionRaw {
16
19
  t: number;
17
20
  type: PlaytestActionType;
@@ -24,12 +27,19 @@ export interface PlaytestArgs {
24
27
  durationMs: number;
25
28
  actions: PlaytestActionRaw[];
26
29
  screenshots: number[];
30
+ input?: PlaytestInput;
31
+ playFile?: string;
27
32
  }
28
33
  export type TimelineEvent = {
29
34
  t: number;
30
35
  kind: "mousemove" | "mousedown" | "mouseup";
31
36
  x: number;
32
37
  y: number;
38
+ } | {
39
+ t: number;
40
+ kind: "touchstart" | "touchmove" | "touchend";
41
+ x: number;
42
+ y: number;
33
43
  } | {
34
44
  t: number;
35
45
  kind: "keydown" | "keyup";
@@ -47,7 +57,7 @@ export declare function validatePlaytestArgs(args: Record<string, unknown>): {
47
57
  ok: false;
48
58
  error: string;
49
59
  };
50
- export declare function buildTimeline(args: PlaytestArgs): TimelineEvent[];
60
+ export declare function buildTimeline(args: PlaytestArgs, input?: PlaytestInput): TimelineEvent[];
51
61
  export interface PlaytestDiagnostics {
52
62
  rafTicks: number;
53
63
  wallMs: number;
@@ -70,7 +80,20 @@ export declare function captureReport(frames: PlaytestFrame[], d: PlaytestDiagno
70
80
  expectedTicks: number;
71
81
  lines: string[];
72
82
  };
73
- export declare function playtestDeckUrl(serveOrigin: string): string;
83
+ export declare function playtestDeckUrl(serveOrigin: string, playFile?: string | null): string;
84
+ export interface PlayTarget {
85
+ playFile: string | null;
86
+ source: "declared" | "requested" | "entry";
87
+ declared: string | null;
88
+ note?: string;
89
+ }
90
+ export declare function resolvePlayTarget(deckDir: string, requested: string | undefined): {
91
+ ok: true;
92
+ target: PlayTarget;
93
+ } | {
94
+ ok: false;
95
+ error: string;
96
+ };
74
97
  export interface PlaytestConsoleEntry {
75
98
  t: number;
76
99
  phase: "load" | "settle" | "session";
@@ -95,6 +118,8 @@ export type PlaytestInstallEvent = {
95
118
  };
96
119
  export interface PlaytestSessionInput {
97
120
  url: string;
121
+ playFile: string | null;
122
+ input: PlaytestInput;
98
123
  durationMs: number;
99
124
  timeline: TimelineEvent[];
100
125
  signal?: AbortSignal;
@@ -113,6 +138,12 @@ export interface PlaytestSessionResult {
113
138
  truncation?: PlaytestTruncation;
114
139
  diagnostics: PlaytestDiagnostics;
115
140
  browserInstallMs?: number;
141
+ environment?: {
142
+ playFile: string | null;
143
+ input: PlaytestInput;
144
+ note: string;
145
+ };
146
+ unsupported?: boolean;
116
147
  }
117
148
  export interface PlaytestExecutor {
118
149
  runSession(input: PlaytestSessionInput): Promise<PlaytestSessionResult>;
@@ -126,6 +157,7 @@ export interface PlaytestToolContext {
126
157
  };
127
158
  onProgress?: (label: string) => void;
128
159
  onInstallEvent?: (evt: PlaytestInstallEvent) => void;
160
+ defaultInput?: PlaytestInput;
129
161
  }
130
162
  export interface PlaytestToolResult {
131
163
  ok: boolean;
@@ -137,6 +169,7 @@ export interface PlaytestToolResult {
137
169
  playtestFrames?: string[];
138
170
  activitySummary?: string;
139
171
  }
172
+ export declare function environmentLines(target: PlayTarget, input: PlaytestInput, session: Pick<PlaytestSessionResult, "viewport" | "environment">): string[];
140
173
  export declare function runPlaytest(args: Record<string, unknown>, deckDir: string, ctx: PlaytestToolContext | undefined, signal: AbortSignal | undefined): Promise<PlaytestToolResult>;
141
174
  export declare const PLAYTEST_TOOL_DESCRIPTION: string;
142
175
  export declare const PLAYTEST_TOOL_PARAMETERS: Record<string, unknown>;
@@ -17,6 +17,8 @@
17
17
  // iframe posts back to one a Playwright page reports directly.
18
18
  import * as fs from "fs";
19
19
  import * as path from "path";
20
+ import { normalizePlayFile, readEditorConfig } from "../editorConfig.js";
21
+ import { playPagePath } from "../playUrl.js";
20
22
  // -- caps + fixed geometry ------------------------------------------------------
21
23
  // Ratified constants. The viewport is FIXED (not per-deck): every digest and
22
24
  // the schema description both state it, so the model never has to guess
@@ -36,6 +38,8 @@ export const PLAYTEST_MAX_CONSOLE_ENTRIES = 100;
36
38
  export const PLAYTEST_MAX_CONSOLE_TEXT_BYTES = 8 * 1024;
37
39
  export const PLAYTEST_FAILURE_CONSOLE_TEXT_MAX_BYTES = 1_024;
38
40
  export const PLAYTEST_FAILURE_OUTPUT_MAX_BYTES = 40 * 1024;
41
+ export const PLAYTEST_INPUTS = ["mouse", "touch"];
42
+ export const PLAYTEST_ENTRY_FILE = "index.html";
39
43
  function isFiniteNumber(v) {
40
44
  return typeof v === "number" && Number.isFinite(v);
41
45
  }
@@ -160,17 +164,45 @@ export function validatePlaytestArgs(args) {
160
164
  screenshots.push(v);
161
165
  }
162
166
  }
163
- return { ok: true, value: { durationMs, actions, screenshots } };
167
+ let input;
168
+ if (args.input !== undefined) {
169
+ if (!PLAYTEST_INPUTS.includes(args.input)) {
170
+ return { ok: false, error: `input must be one of ${PLAYTEST_INPUTS.join("/")}, got ${JSON.stringify(args.input)}` };
171
+ }
172
+ input = args.input;
173
+ }
174
+ let playFile;
175
+ if (args.playFile !== undefined) {
176
+ if (typeof args.playFile !== "string" || !args.playFile.trim()) {
177
+ return { ok: false, error: "playFile must be a non-empty deck-relative path when given" };
178
+ }
179
+ playFile = args.playFile.trim();
180
+ }
181
+ return {
182
+ ok: true,
183
+ value: {
184
+ durationMs,
185
+ actions,
186
+ screenshots,
187
+ ...(input ? { input } : {}),
188
+ ...(playFile ? { playFile } : {}),
189
+ },
190
+ };
164
191
  }
165
192
  // Expands tap/key sugar into raw primitives and merges in screenshot
166
193
  // requests, stable-sorted by t (ties: actions before screenshots, so a shot
167
194
  // requested at the same timestamp as an action captures its effect).
168
- export function buildTimeline(args) {
195
+ const POINTER_KINDS = {
196
+ mouse: { down: "mousedown", move: "mousemove", up: "mouseup" },
197
+ touch: { down: "touchstart", move: "touchmove", up: "touchend" },
198
+ };
199
+ export function buildTimeline(args, input = "mouse") {
200
+ const kinds = POINTER_KINDS[input];
169
201
  const events = [];
170
202
  for (const a of args.actions) {
171
203
  if (a.type === "tap") {
172
- events.push({ t: a.t, kind: "mousedown", x: a.x, y: a.y });
173
- events.push({ t: a.t, kind: "mouseup", x: a.x, y: a.y });
204
+ events.push({ t: a.t, kind: kinds.down, x: a.x, y: a.y });
205
+ events.push({ t: a.t, kind: kinds.up, x: a.x, y: a.y });
174
206
  }
175
207
  else if (a.type === "key") {
176
208
  const holdMs = a.durationMs ?? PLAYTEST_DEFAULT_KEY_DURATION_MS;
@@ -178,8 +210,7 @@ export function buildTimeline(args) {
178
210
  events.push({ t: a.t + holdMs, kind: "keyup", key: a.key });
179
211
  }
180
212
  else {
181
- const kind = a.type === "down" ? "mousedown" : a.type === "up" ? "mouseup" : "mousemove";
182
- events.push({ t: a.t, kind, x: a.x, y: a.y });
213
+ events.push({ t: a.t, kind: kinds[a.type], x: a.x, y: a.y });
183
214
  }
184
215
  }
185
216
  for (const t of args.screenshots)
@@ -228,8 +259,55 @@ export function captureReport(frames, d) {
228
259
  // (`logs=1`, the postMessage console forwarder for the shell's logs drawer)
229
260
  // is deliberately NOT mirrored: its inject bails on a top-level page, and
230
261
  // Playwright captures console output natively.
231
- export function playtestDeckUrl(serveOrigin) {
232
- return `${serveOrigin.replace(/\/+$/, "")}/index.html?edit=0`;
262
+ export function playtestDeckUrl(serveOrigin, playFile = null) {
263
+ return `${serveOrigin.replace(/\/+$/, "")}${playPagePath(playFile)}`;
264
+ }
265
+ function declaredTarget(deckDir) {
266
+ const config = readEditorConfig(deckDir);
267
+ const declared = config.defaultPlayFile ?? null;
268
+ if (declared) {
269
+ const abs = path.join(path.resolve(deckDir), declared);
270
+ const missing = !fs.existsSync(abs) || !fs.statSync(abs).isFile();
271
+ return {
272
+ playFile: declared,
273
+ source: "declared",
274
+ declared,
275
+ ...(missing
276
+ ? { note: `the deck's defaultPlayFile ${declared} is not a file in this deck. The page was asked for it anyway, as the Play panel asks; what it shows then is up to the deck.` }
277
+ : {}),
278
+ };
279
+ }
280
+ const refused = config.defaultPlayFileRefused;
281
+ return {
282
+ playFile: null,
283
+ source: "entry",
284
+ declared: null,
285
+ ...(refused
286
+ ? { note: `the deck's defaultPlayFile ${JSON.stringify(refused.value)} was not used because ${refused.reason}, so this opened the entry point -- as the Play panel does.` }
287
+ : {}),
288
+ };
289
+ }
290
+ export function resolvePlayTarget(deckDir, requested) {
291
+ const fromDeck = declaredTarget(deckDir);
292
+ const declared = fromDeck.declared;
293
+ if (requested === undefined)
294
+ return { ok: true, target: fromDeck };
295
+ const normalized = normalizePlayFile(deckDir, requested);
296
+ if (!normalized.ok) {
297
+ return { ok: false, error: `playFile ${JSON.stringify(requested)} cannot be opened: ${normalized.reason}` };
298
+ }
299
+ if (normalized.path === PLAYTEST_ENTRY_FILE) {
300
+ return { ok: true, target: { playFile: null, source: "entry", declared } };
301
+ }
302
+ const inside = normalized.path;
303
+ const abs = path.join(path.resolve(deckDir), inside);
304
+ if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
305
+ return {
306
+ ok: false,
307
+ error: `playFile ${JSON.stringify(requested)} is not a file in this deck. Omit playFile to open what the Play panel opens (${declared ?? `${PLAYTEST_ENTRY_FILE}, the entry point`}), or pass "${PLAYTEST_ENTRY_FILE}" for the entry point with no play file.`,
308
+ };
309
+ }
310
+ return { ok: true, target: { playFile: inside, source: "requested", declared } };
233
311
  }
234
312
  const CONSOLE_LOG_CAP = 20;
235
313
  function truncateUtf8(value, maxBytes) {
@@ -271,10 +349,38 @@ function buildFailureOutput(session) {
271
349
  }
272
350
  return truncateUtf8(lines.join("\n"), PLAYTEST_FAILURE_OUTPUT_MAX_BYTES);
273
351
  }
352
+ function openedLine(playFile, target) {
353
+ const panel = target.declared ?? `${PLAYTEST_ENTRY_FILE}, the entry point`;
354
+ if (playFile === null) {
355
+ return `Opened: ${PLAYTEST_ENTRY_FILE}, the deck's entry point with no play file -- how a published deck starts. ${target.declared ? `The user's Play panel opens ${target.declared} instead.` : "The user's Play panel opens the same."}`;
356
+ }
357
+ if (playFile === target.declared) {
358
+ return `Opened: ${playFile}, the deck's defaultPlayFile -- what the user's Play panel opens unless they picked another file in it. A published deck starts at ${PLAYTEST_ENTRY_FILE} with no play file (playFile "${PLAYTEST_ENTRY_FILE}" opens that).`;
359
+ }
360
+ return `Opened: ${playFile}, as requested. The user's Play panel opens ${panel}.`;
361
+ }
362
+ // Says where the frames came from, so a report can name it: a headless
363
+ // preview is evidence about the preview, not about the user's phone.
364
+ export function environmentLines(target, input, session) {
365
+ const actual = session.environment;
366
+ const drove = (actual?.input ?? input) === "touch"
367
+ ? "touch emulated (touchscreen, mobile viewport, pixel ratio 1)"
368
+ : "mouse and keyboard";
369
+ const lines = [
370
+ `Environment: headless Chromium, ${session.viewport.width}x${session.viewport.height} viewport, ${drove}. Not the user's device, browser, or app -- report what this shows as seen in the headless preview.`,
371
+ openedLine(actual ? actual.playFile : target.playFile, target),
372
+ ];
373
+ if (target.note)
374
+ lines.push(`Note: ${target.note}`);
375
+ if (actual)
376
+ lines.push(`Note: ${actual.note}`);
377
+ return lines;
378
+ }
274
379
  function buildDigest(opts) {
275
- const { callIndex, args, session, report, persisted } = opts;
380
+ const { callIndex, args, target, input, session, report, persisted } = opts;
276
381
  const lines = [
277
- `Playtest call ${callIndex}/${PLAYTEST_MAX_CALLS_PER_RUN} -- ${session.viewport.width}x${session.viewport.height} fixed viewport, ${args.durationMs}ms session (${args.actions.length} action(s), ${args.screenshots.length} screenshot(s) requested).`,
382
+ `Playtest call ${callIndex}/${PLAYTEST_MAX_CALLS_PER_RUN} -- ${args.durationMs}ms session (${args.actions.length} action(s), ${args.screenshots.length} screenshot(s) requested).`,
383
+ ...environmentLines(target, input, session),
278
384
  ];
279
385
  lines.push("Frames:");
280
386
  for (const p of persisted)
@@ -296,11 +402,27 @@ function buildDigest(opts) {
296
402
  lines.push(` ${fmtConsolePhase(entry)}`);
297
403
  }
298
404
  const distinctNote = persisted.length > 1 ? `${report.distinct} distinct` : `${report.distinct}`;
299
- const activitySummary = `Playtested ${args.durationMs}ms: ${persisted.length} frame(s), ${distinctNote}` +
405
+ const actualInput = session.environment?.input ?? input;
406
+ const actualFile = session.environment ? session.environment.playFile : target.playFile;
407
+ const activitySummary = `Playtested ${args.durationMs}ms (${actualInput}, ${actualFile ?? PLAYTEST_ENTRY_FILE}): ${persisted.length} frame(s), ${distinctNote}` +
300
408
  (errorCount > 0 ? `, ${errorCount} console error(s)` : "") +
301
409
  (report.starved ? " [CAPTURE STARVED -- retry]" : "");
302
410
  return { text: lines.join("\n"), activitySummary };
303
411
  }
412
+ // The prefix a call's frames are saved under: one past the highest already in
413
+ // the dir, not the budget count. The budget count can repeat -- a refused call
414
+ // is given back, and a retried run starts a fresh budget in the same dir -- and
415
+ // a repeat would overwrite frames a task card already links. Read and written
416
+ // in one synchronous stretch, so concurrent calls cannot pick the same prefix.
417
+ function nextFrameSet(framesDir) {
418
+ let highest = 0;
419
+ for (const name of fs.readdirSync(framesDir)) {
420
+ const match = /^(\d+)-\d+(?:\.\d+)?\.png$/.exec(name);
421
+ if (match)
422
+ highest = Math.max(highest, Number(match[1]));
423
+ }
424
+ return highest + 1;
425
+ }
304
426
  export async function runPlaytest(args, deckDir, ctx, signal) {
305
427
  if (!ctx) {
306
428
  return {
@@ -311,6 +433,11 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
311
433
  const parsed = validatePlaytestArgs(args);
312
434
  if (!parsed.ok)
313
435
  return { ok: false, output: `Error: ${parsed.error}` };
436
+ const resolved = resolvePlayTarget(deckDir, parsed.value.playFile);
437
+ if (!resolved.ok)
438
+ return { ok: false, output: `Error: ${resolved.error}` };
439
+ const target = resolved.target;
440
+ const input = parsed.value.input ?? ctx.defaultInput ?? "mouse";
314
441
  if (ctx.callCount.value >= PLAYTEST_MAX_CALLS_PER_RUN) {
315
442
  return {
316
443
  ok: false,
@@ -319,15 +446,21 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
319
446
  }
320
447
  ctx.callCount.value += 1;
321
448
  const callIndex = ctx.callCount.value;
322
- const timeline = buildTimeline(parsed.value);
449
+ const timeline = buildTimeline(parsed.value, input);
323
450
  const session = await ctx.executor.runSession({
324
- url: playtestDeckUrl(ctx.serveUrl),
451
+ url: playtestDeckUrl(ctx.serveUrl, target.playFile),
452
+ playFile: target.playFile,
453
+ input,
325
454
  durationMs: parsed.value.durationMs,
326
455
  timeline,
327
456
  signal,
328
457
  onProgress: ctx.onProgress,
329
458
  onInstallEvent: ctx.onInstallEvent,
330
459
  });
460
+ if (!session.ok && session.unsupported) {
461
+ ctx.callCount.value -= 1;
462
+ return { ok: false, output: `Error: ${session.error}` };
463
+ }
331
464
  if (!session.ok) {
332
465
  return {
333
466
  ok: false,
@@ -335,20 +468,21 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
335
468
  };
336
469
  }
337
470
  fs.mkdirSync(ctx.framesDir, { recursive: true });
471
+ const frameSet = nextFrameSet(ctx.framesDir);
338
472
  const persisted = [];
339
473
  for (const frame of session.frames) {
340
- const filename = `${callIndex}-${frame.t}.png`;
474
+ const filename = `${frameSet}-${frame.t}.png`;
341
475
  const absPath = path.join(ctx.framesDir, filename);
342
476
  fs.writeFileSync(absPath, frame.png);
343
477
  persisted.push({ t: frame.t, relPath: path.relative(deckDir, absPath).split(path.sep).join("/") });
344
478
  }
345
479
  const report = captureReport(session.frames, session.diagnostics);
346
- const digest = buildDigest({ callIndex, args: parsed.value, session, report, persisted });
480
+ const digest = buildDigest({ callIndex, args: parsed.value, target, input, session, report, persisted });
347
481
  return {
348
482
  ok: true,
349
483
  output: digest.text,
350
484
  images: session.frames.map((f) => ({
351
- label: `playtest call ${callIndex} frame t=${f.t}ms`,
485
+ label: `playtest call ${callIndex} frame t=${f.t}ms (${frameSet}-${f.t}.png)`,
352
486
  dataUrl: `data:image/png;base64,${f.png.toString("base64")}`,
353
487
  })),
354
488
  playtestFrames: persisted.map((p) => p.relPath),
@@ -357,9 +491,10 @@ export async function runPlaytest(args, deckDir, ctx, signal) {
357
491
  }
358
492
  // -- tool schema (model-facing) ------------------------------------------------
359
493
  export const PLAYTEST_TOOL_DESCRIPTION = [
360
- `Load the served deck in a real headless browser, optionally drive timed mouse/keyboard input, and capture screenshots + console/error output. Use this after changing behavior or visuals to actually SEE what you built, not just read the code back.`,
494
+ `Load the served deck in a real headless browser (Chromium, not the user's device), optionally drive timed mouse, touch, or keyboard input, and capture screenshots + console/error output. Use this after changing behavior or visuals to actually SEE what you built, not just read the code back.`,
495
+ `It opens what the user's Play panel opens (the deck's declared play file, else its entry point); playFile opens another deck file instead, and "${PLAYTEST_ENTRY_FILE}" opens the entry point with no play file, as a published deck starts. input "touch" emulates a phone touchscreen: down/move/up/tap arrive as touch events, which touch-only controls need.`,
361
496
  `Coordinates (x/y) are CSS pixels in a FIXED ${PLAYTEST_VIEWPORT.width}x${PLAYTEST_VIEWPORT.height} viewport, regardless of the deck's own canvas size.`,
362
- `durationMs is the session length (ms, up to ${PLAYTEST_MAX_DURATION_MS}). actions (up to ${PLAYTEST_MAX_ACTIONS}) are timed inputs: {t,type:"down"|"move"|"up",x,y} raw mouse primitives, {t,type:"tap",x,y} (down+up sugar), or {t,type:"key",key,durationMs?} (keydown at t, keyup at t+durationMs, default ${PLAYTEST_DEFAULT_KEY_DURATION_MS}ms -- overlapping holds are fine). screenshots (up to ${PLAYTEST_MAX_SHOTS} timestamps in ms) default to [0, durationMs].`,
497
+ `durationMs is the session length (ms, up to ${PLAYTEST_MAX_DURATION_MS}). actions (up to ${PLAYTEST_MAX_ACTIONS}) are timed inputs: {t,type:"down"|"move"|"up",x,y} raw pointer primitives (mouse or touch, per input), {t,type:"tap",x,y} (down+up sugar), or {t,type:"key",key,durationMs?} (keydown at t, keyup at t+durationMs, default ${PLAYTEST_DEFAULT_KEY_DURATION_MS}ms -- overlapping holds are fine). screenshots (up to ${PLAYTEST_MAX_SHOTS} timestamps in ms) default to [0, durationMs].`,
363
498
  `The result is a text digest (frame list, console/error log, capture-health) plus the actual frame images delivered right after. A "capture starved" warning means the CAPTURE wasn't rendering (throttled/dead browser) -- that is not proof the game is broken; retry before concluding anything. This tool is capped at ${PLAYTEST_MAX_CALLS_PER_RUN} calls per run.`,
364
499
  ].join(" ");
365
500
  export const PLAYTEST_TOOL_PARAMETERS = {
@@ -395,6 +530,15 @@ export const PLAYTEST_TOOL_PARAMETERS = {
395
530
  items: { type: "integer" },
396
531
  description: `Up to ${PLAYTEST_MAX_SHOTS} timestamps (ms) to screenshot at. Defaults to [0, durationMs].`,
397
532
  },
533
+ input: {
534
+ type: "string",
535
+ enum: [...PLAYTEST_INPUTS],
536
+ description: `"mouse" (default) or "touch" (emulated touchscreen; down/move/up/tap become touch events).`,
537
+ },
538
+ playFile: {
539
+ type: "string",
540
+ description: `Deck-relative file to open instead of what the Play panel opens. "${PLAYTEST_ENTRY_FILE}" = the entry point with no play file.`,
541
+ },
398
542
  },
399
543
  required: ["durationMs"],
400
544
  };
@@ -2,6 +2,7 @@ export declare const PLATFORM_DOCS_DIR: string;
2
2
  export declare const PLATFORM_DOC_REL: string;
3
3
  export declare const MULTIPLAYER_DOC_REL: string;
4
4
  export declare function everyDeckBullets(deckDir: string): string[];
5
+ export declare const HOST_LIMIT_BULLETS: string[];
5
6
  export type AgentRole = 'router' | 'task';
6
7
  export declare function roleLoadsClaudeMd(role: AgentRole): boolean;
7
8
  export declare function claudeContextEnv(role: AgentRole): NodeJS.ProcessEnv;
@@ -68,6 +68,20 @@ export function everyDeckBullets(deckDir) {
68
68
  MODE_BULLET,
69
69
  ];
70
70
  }
71
+ // Routers are told never to call something impossible without checking their
72
+ // context, so a host limit missing from it gets "fixed" task after task
73
+ // (frustration survey B1). Only facts about the hosts themselves live here;
74
+ // what depends on the SDK (storage caps, which command needs which app build)
75
+ // ships in sdk/README.md, so it cannot go stale when the SDK changes. Each
76
+ // bullet is a claim about castle-client, castle-www or ghost-server code, with
77
+ // pointers in memo 26-09-24-16-30-host-limits-verified-from-code: re-verify
78
+ // one when its host changes.
79
+ export const HOST_LIMIT_BULLETS = [
80
+ "- **Where a deck runs decides what it can do.** The Play panel runs it from this serve; players run the published deck in the Castle app (iOS, Android) or castle.xyz's web player. When something works in one and fails in another, check it against the limits below before another fix: if one covers it, name that limit instead of retrying, and ask where they run it if you do not know. If none does, it is an ordinary deck bug (a runtime `fetch` of a loose file, a control that only answers a mouse) and gets fixed.",
81
+ "- **Microphone and camera are blocked in the Play panel and on castle.xyz**: neither frame is granted them, so `getUserMedia` rejects with `NotAllowedError` whatever the person allows, and no deck change helps. The Android app's published deck can use them; the iOS app is untested.",
82
+ "- **A published deck loads almost nothing from the network.** Its CSP allows images, audio and video only from the deck itself, `data:` or `blob:`, `fetch` only to esm.sh, cdnjs.cloudflare.com and Castle's multiplayer hosts, and no iframes. The Play panel sets no CSP, so a remote URL that works there fails once published. Bundle the file, or let the player pick one with `<input type=\"file\">`.",
83
+ "- **An older Castle app build rejects SDK commands newer than the build**, with a `CastleError` whose `code` is `UNKNOWN_COMMAND`; only an app update fixes that, so the deck should catch it and keep working. Which commands need which app build, and every other limit of a Castle service, is in the SDK reference, `imports/castle.base/sdk/README.md`.",
84
+ ];
71
85
  // The line has to stand on its own to count: this repo's CLAUDE.md names the
72
86
  // path inside a sentence, and prose about the import must not read as a deck
73
87
  // carrying one.
@@ -100,12 +114,14 @@ function deckLoadsGuide(deckDir) {
100
114
  const RESTATEMENT_MARKER = '**Supported media formats are exactly**';
101
115
  // The every-deck bullets after a quick reference that lacks them. Skipped when
102
116
  // the deck's kit is pinned to a version that still restates them, which would
103
- // otherwise say all of it twice.
117
+ // otherwise say all of it twice. No kit ever restated the host limits, so they
118
+ // come either way.
104
119
  function withEveryDeckBullets(deckDir, quickReference) {
105
120
  const own = quickReference.trim();
121
+ const hostLimits = HOST_LIMIT_BULLETS.join('\n');
106
122
  if (own.includes(RESTATEMENT_MARKER))
107
- return quickReference;
108
- const bullets = everyDeckBullets(deckDir).join('\n');
123
+ return `${own}\n\n${hostLimits}`;
124
+ const bullets = [...everyDeckBullets(deckDir), ...HOST_LIMIT_BULLETS].join('\n');
109
125
  return own ? `${own}\n\n${bullets}` : bullets;
110
126
  }
111
127
  // Whether a role's claude process auto-loads the deck's CLAUDE.md, and with it
@@ -213,6 +229,7 @@ const COMMON_SECTIONS = `## Imports are read-only
213
229
 
214
230
  - **Read \`${MULTIPLAYER_DOC_REL}\` before writing or changing a server entry or client netcode by hand.** It carries what this section leaves out: the outbound frame budget in practice, the snapshot pattern, self-healing events, and the reconnect and disconnect handling a hand-rolled session gets wrong. A deck built on the \`castle.multiplayer-2d\` / \`castle.multiplayer-3d\` (or \`castle.turn-based\`) kits already does all of that and normally writes nothing against the raw session API.
215
231
  - **A deck becomes multiplayer by having a server entry** — no flag, no dashboard. The entry is \`castle.json\`'s \`server.main\` when set (a kit deck points it under \`imports/\`), otherwise the first of \`server/index.{js,ts,mjs}\` or \`code/server/index.{js,ts,mjs}\` that exists; removing the entry turns multiplayer off on the next \`save-deck\`. Castle runs that module as a real server process, one per session, shared by the players in it. Other options under \`server\`: \`maxPlayers\` (max 24), and \`tickRate\` (defaults to 20, max 30; 0 turns ticks off).
232
+ - **Voice chat comes with multiplayer; the deck doesn't build it.** Castle runs the call, the microphone prompt and the mute/push-to-talk controls outside the card, so a deck never touches audio or the mic. \`connection.voice\` lets a deck ask the player to join (\`requestJoin()\` shows Castle's prompt), follow \`state\` and \`onSpeaking(playerIds => ...)\` for talking indicators, and \`setMix({ [playerId]: { gain, pan } })\` for proximity chat (gain 0-1, pan -1 to 1). \`state\` is \`"unavailable"\` in solo, in local dev, and wherever voice isn't offered, so draw voice UI only when it isn't. Call \`requestJoin()\` from a player action (a "Join voice" button): if they decline, asking again within 10 seconds answers \`"declined"\` without a prompt. Turn voice off for a deck with \`"voice": { "enabled": false }\` in \`castle.json\`.
216
233
  - **The server module default-exports lifecycle callbacks**, each taking the session first:
217
234
 
218
235
  \`\`\`js
@@ -270,6 +287,10 @@ ${everyDeckBullets(deckDir).filter((b) => !b.includes('PARAMS')).join('\n')}
270
287
  ## Tunable values and the Parameters panel
271
288
 
272
289
  ${everyDeckBullets(deckDir).filter((b) => b.includes('PARAMS')).join('\n')}
290
+
291
+ ## Host limits
292
+
293
+ ${HOST_LIMIT_BULLETS.join('\n')}
273
294
  `;
274
295
  }
275
296
  function platformDoc(deckDir) {
@@ -0,0 +1,3 @@
1
+ export declare function playPagePath(playFile: string | null, opts?: {
2
+ logs?: boolean;
3
+ }): string;
@@ -0,0 +1,12 @@
1
+ // The deck page a play surface loads: the shell's Play panel iframes it, and the
2
+ // playtest tool opens it headless. Both build it here so a task's playtest opens
3
+ // exactly what the user's Play panel opens. `scene` is the query name kits read
4
+ // the play file from; the platform only passes the declared file through.
5
+ export function playPagePath(playFile, opts = {}) {
6
+ const query = ['edit=0'];
7
+ if (opts.logs)
8
+ query.push('logs=1');
9
+ if (playFile)
10
+ query.push(`scene=${encodeURIComponent(playFile)}`);
11
+ return `/index.html?${query.join('&')}`;
12
+ }
package/dist/save-deck.js CHANGED
@@ -173,6 +173,7 @@ async function publishServerBundle(projectDir, deckId) {
173
173
  const saved = await api.saveCauldronServerBundle(deckId, uploadConfig.uploadId, {
174
174
  tickRate: serverConfig.tickRate,
175
175
  maxPlayers: serverConfig.maxPlayers,
176
+ voice: { enabled: serverConfig.voiceEnabled },
176
177
  });
177
178
  // The server hashes what it actually stored. A mismatch means the bytes that
178
179
  // will run in sessions are not the bytes we bundled.