castle-web-cli 0.4.54 → 0.4.56

package/dist/agent-prompts.d.ts

@@ -1,5 +1,5 @@
 export interface PromptMessage {
-    role: 'user' | 'assistant';
+    role: "user" | "assistant";
     text: string;
 }
 export interface PromptTask {
@@ -28,6 +28,6 @@ export declare function buildTaskPrompt(opts: {
     progressPath: string;
     notesPath: string;
     depsSummary?: string;
-    backend?: 'cursor' | 'claude';
+    backend?: "cursor" | "claude";
 }): string;
 export declare const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";

package/dist/agent-prompts.js

@@ -14,10 +14,10 @@ Hard rules:
 - You NEVER edit files or run state-changing commands. All building and fixing happens through background task agents -- always hand the longer work to them.
 - You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
-- The whole goal: get every piece of work TESTABLE as soon as possible. So start every task as early as possible, run them in parallel, and make any dependent task wait on the FEWEST things possible. \`after:\` is ONLY a true output dependency -- the waiting task literally consumes another's result (the files it makes, the actors that must already exist). NEVER use \`after:\` just because two tasks edit the same file -- they make surgical, targeted edits and run together fine; serializing for file-contention is wasted time. If a step has a do-now part and a depends-on-others part, SPLIT it: the do-now part runs immediately in parallel, only the dependent part waits, and it waits on the least possible.
-- ALWAYS wire parallel work into gameplay. Anything a parallel task PRODUCES that won't show up in actual play on its own -- art files, a behavior nothing references yet, a scene nothing loads -- you MUST also spawn a separate WAITING task that wires it in (\`after:\` the task that made it): point the actors at the drawings, attach the behavior, load the scene. Without the wire-in task the work stays invisible and the user can never see or test it -- which defeats the whole point. Art is the example: ONE task draws the sprites in parallel; a SEPARATE task places them in the scene (\`after:\` the drawing task), waiting only on the drawings + the actors existing, never on unrelated features like score. Never leave made-but-unwired output, and never count on the maker task to wire its own output in.
+- The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.
+- Dissolve those information-dependencies with a CONTRACT decided up front, instead of serializing tasks. Before spawning, pin the shared names the tasks will agree on -- scene file names, behavior names, drawing file names, tags -- and give each parallel task the exact names it must CREATE or REFERENCE. Then they all run at once and converge to a working game with NO follow-up wiring task: the scene task places actors referencing behaviors and drawings by their agreed names before those files even exist; the behavior tasks create those behavior names; the drawing tasks create those drawing files. (Art: pin drawings/ship.drawing up front -> the scene task points an actor at it while another task draws it, in parallel; no place-it-later task.) Fall back to a separate waiting wire-in task (\`after:\` the maker, on the least possible) ONLY when a task truly needs another's actual produced output, not just its agreed name. Working out this breakdown -- what to parallelize, which names to pin up front -- is the core of your job and differs per game.
 - Write each task prompt for the quickest viable, testable change that still delivers a meaningful step up. Dive deep only if the user asked.
-- Real, editable assets: drawings (drawings/*.drawing pixel art) for game objects, characters, and scenery, placed as real actors; data-driven UI (health/score/HUD) and effects stay code. Get the game playable instantly with placeholder blocks (block.drawing + tint) -- even for pong/breakout -- with the real drawings made in parallel and placed once the core exists (the art split above). Never say "greybox" or other dev jargon to the user.
+- Real, editable assets: drawings (drawings/*.drawing pixel art) for game objects, characters, and scenery as real actors; data-driven UI (health/score/HUD) and effects stay code. Get the game playable instantly with placeholder blocks (block.drawing + tint) -- even for pong/breakout -- then bring in the real drawings (wired in per the rule above). Never say "greybox" or other dev jargon to the user.
 - To spawn a background task, include a fenced block in your reply:
 
 \`\`\`castle-task
@@ -29,7 +29,7 @@ the deck's own docs for framework/API detail, so never restate recipes,
 file layouts, or implementation steps.
 \`\`\`
 
-- Use \`after:\` only when a task truly builds on or would conflict with another (it may reference tasks spawned in this same reply, by title). Independent tasks must NOT wait on each other.
+- Use \`after:\` only for the fallback case above -- a task that genuinely needs another's produced output (it may reference tasks spawned in this same reply, by title). Never for file-contention; independent tasks must NOT wait on each other.
 
 Keeping the board clean. The background-tasks list below IS the board the user sees -- every row, with its id and status. Be diligent about removing rows that no longer belong, using these two fences:
 
@@ -59,20 +59,20 @@ Conversation style:
 function renderTranscript(messages) {
     const recent = messages.slice(-TRANSCRIPT_LIMIT);
     if (recent.length === 0)
-        return '(no conversation yet)';
+        return "(no conversation yet)";
     return recent
-        .map((m) => `${m.role === 'user' ? 'user' : 'you'}: ${m.text}`)
-        .join('\n\n');
+        .map((m) => `${m.role === "user" ? "user" : "you"}: ${m.text}`)
+        .join("\n\n");
 }
 function renderTasks(tasks) {
     if (tasks.length === 0)
-        return '(none yet)';
+        return "(none yet)";
     return tasks
         .map((t) => {
-        const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : '';
+        const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : "";
         return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}`;
     })
-        .join('\n');
+        .join("\n");
 }
 export function buildRouterPrompt(opts) {
     return `${ROUTER_RULES}
@@ -98,14 +98,14 @@ export function userTurnInstruction(opts) {
     }
     parts.push(`The user just said:\n\n${opts.text}`);
     if (opts.attachments && opts.attachments.length > 0) {
-        parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(', ')}. Open them with your read tool and take them into account; pass the paths along to task agents that need them.`);
+        parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(", ")}. Open them with your read tool and take them into account; pass the paths along to task agents that need them.`);
     }
-    return parts.join('\n\n');
+    return parts.join("\n\n");
 }
 export function buildTaskPrompt(opts) {
     const deps = opts.depsSummary
         ? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
-        : '';
+        : "";
     // Claude-only: collapsing the wrap-up (progress 90 + restart + notes) into
     // one shell call reliably saves 1-2 serial ~7s turns there. Cursor's
     // composer sometimes reacts to the same rule with MORE calls, so it stays
@@ -113,9 +113,9 @@ export function buildTaskPrompt(opts) {
     // (We deliberately do NOT tell agents to overwrite files via `cat > … <<EOF`
     // -- blind whole-file rewrites made parallel agents clobber each other's
     // edits. Read-then-edit is slower but safe; that is the right tradeoff.)
-    const wrapUp = opts.backend === 'claude'
+    const wrapUp = opts.backend === "claude"
         ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
-        : '';
+        : "";
     return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions, and reload the served deck after changes (\`npm run restart\`).
 
 Your task (id ${opts.taskId}): ${opts.title}
@@ -137,4 +137,4 @@ Operating rules:
 }
 // Appended to claude task agents' system prompt (portable replacement for the
 // machine-specific /goal slash command): commit to autonomous completion.
-export const CLAUDE_TASK_SYSTEM_REMINDER = 'Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.';
+export const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";

package/dist/bundle.js

@@ -1,10 +1,11 @@
 import * as path from 'path';
 import { build } from 'vite';
 import { viteSingleFile } from 'vite-plugin-singlefile';
+import { sceneFilesPlugin } from './vitePlugins.js';
 export async function bundleProject(dir) {
     const result = await build({
         root: dir,
-        plugins: [viteSingleFile()],
+        plugins: [viteSingleFile(), sceneFilesPlugin()],
         build: {
             write: false,
             rollupOptions: {

package/dist/serve.js

@@ -6,6 +6,7 @@ import { createServer } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
 import { createIdeServer, DECK_FOCUS_SCRIPT } from './ide.js';
 import { createAgentServer } from './agent.js';
+import { sceneFilesPlugin } from './vitePlugins.js';
 import * as config from './config.js';
 function isPortFree(port) {
     return new Promise((resolve) => {
@@ -194,7 +195,7 @@ export async function serve(dir, options = {}) {
     process.on('exit', () => agentServer.shutdown());
     const vite = await createServer({
         root: projectDir,
-        plugins: [castlePlugin(wsPort, ideServer, agentServer)],
+        plugins: [castlePlugin(wsPort, ideServer, agentServer), sceneFilesPlugin()],
         server: {
             port,
             strictPort: true,

package/dist/vitePlugins.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function sceneFilesPlugin(): Plugin;

package/dist/vitePlugins.js

@@ -0,0 +1,27 @@
+import * as fs from 'fs';
+// Safety net for `.scene` / `.drawing` files imported as JS modules.
+//
+// These files are DATA (JSON), not modules. The blessed way to read them is the
+// engine's file APIs (`scene.readFromFile(name)` / the `?raw` glob in
+// engine/files.js). But agents sometimes still write a plain
+// `import scene from './scenes/main.scene'`, which Vite would otherwise serve as
+// raw JSON-as-JS and the browser throws "Unexpected token ':'". This plugin
+// makes that import resolve to the parsed object so it just works.
+//
+// `?raw` (and any other query suffix) is left untouched so the engine's
+// `import.meta.glob(..., { query: '?raw' })` still gets raw text.
+export function sceneFilesPlugin() {
+    return {
+        name: 'castle-scene-files',
+        load(id) {
+            const [filePath, query] = id.split('?');
+            if (query !== undefined)
+                return null;
+            if (filePath.endsWith('.scene') || filePath.endsWith('.drawing')) {
+                const text = fs.readFileSync(filePath, 'utf-8');
+                return `export default JSON.parse(${JSON.stringify(text)});\n`;
+            }
+            return null;
+        },
+    };
+}

package/kits/basic-2d/CLAUDE.md

@@ -17,7 +17,7 @@ The deck is already serving when you start (`castle-web init` set that up; see `
 1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), `npm run restart`, then add the next piece. Do NOT write the whole game in one shot.
 2. **After every edit:** `npm run restart` (no hot reload). The served page refreshes and the user sees the change.
 3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual drawings (`drawings/*.drawing`) and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into drawings.
-4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.load(targetSceneData)`; wire the transition deck-side (e.g. import the target `.scene` JSON and call `scene.load` on play / win / level change).
+4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.loadFromFile('gameover.scene')` (reads the file and transitions) on play / win / level change. NEVER `import` a `.scene` file as a module — scene files are data, not modules; use `scene.readFromFile` / `scene.loadFromFile`.
 
 Card size is **500 wide × 700 tall** (origin top-left, +y is down).
 
@@ -107,6 +107,9 @@ Rules: every actor needs a unique `id` (any string) and almost always a `Layout`
 - `scene.spawnActor({ components: { Layout: {...}, MyBehavior: {...} } })` — add a new actor at runtime. Returns the actor (with auto-minted `id` and `runtime = {}`). Use this; don't push to `scene.data.actors` by hand.
 - `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
 - `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
+- `scene.load(sceneData)` — replace the running scene with the given scene data object.
+- `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
+- `scene.loadFromFile(name)` — read a scene file and transition the running scene to it. The way to switch screens/levels and to restart, e.g. `scene.loadFromFile('main.scene')`.
 - `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
 
 ## Input shortcuts

package/kits/basic-2d/engine/ScenePlayer.jsx

@@ -19,13 +19,22 @@ export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
     configureSceneCanvas(canvas, ctx);
     const runtime = makeScene(sceneData, behaviorClasses, drawings).clone();
     runtimeRef.current = runtime;
+    // Store BOTH the physical code ('KeyX', 'ArrowLeft', 'Space') and the
+    // logical key ('x', 'ArrowLeft', ' ') so behaviors can match either. Codes
+    // are what the kit docs/examples use; keeping key too is forgiving.
     const onKeyDown = (event) => {
+      runtime.keys.add(event.code);
       runtime.keys.add(event.key);
     };
     const onKeyUp = (event) => {
+      runtime.keys.delete(event.code);
       runtime.keys.delete(event.key);
     };
     const onPointerDown = (event) => {
+      // The play surface listens on window keydown, so it only gets keys when
+      // its document/iframe holds focus. Grab focus on any click into the game
+      // (and on mount below) so the keyboard works inside the launcher embed.
+      canvas.focus();
       runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, true);
       canvas.setPointerCapture(event.pointerId);
     };
@@ -46,6 +55,7 @@ export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
     canvas.addEventListener('pointermove', onPointerMove);
     canvas.addEventListener('pointerup', onPointerUp);
     canvas.addEventListener('pointercancel', onPointerUp);
+    canvas.focus();
     const stopLoop = startPlayerLoop(canvas, ctx, runtime);
     return () => {
       stopLoop();
@@ -61,7 +71,11 @@ export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
   }, []);
   return (
     <div style={{ position: 'fixed', inset: 0, background: '#000' }}>
-      <canvas ref={canvasRef} style={{ width: '100%', height: '100%', display: 'block' }} />
+      <canvas
+        ref={canvasRef}
+        tabIndex={0}
+        style={{ width: '100%', height: '100%', display: 'block', outline: 'none' }}
+      />
       <SceneUI getRuntime={getRuntime} />
       <TouchControls getKeys={getKeys} />
     </div>

package/kits/basic-2d/engine/scene.js

@@ -1,8 +1,23 @@
+import { initialFiles, parseJsonFile } from './files';
+
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
 
 export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
 
+// Resolve a scene-file name to its key in the loaded file map. Accepts
+// 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
+// `.scene` extension and a leading `scenes/` are both optional.
+function resolveSceneFileKey(name) {
+  const key = String(name).replace(/^\.?\//, '');
+  const candidates = [key];
+  if (!key.endsWith('.scene')) candidates.push(`${key}.scene`);
+  for (const candidate of [...candidates]) {
+    if (!candidate.startsWith('scenes/')) candidates.push(`scenes/${candidate}`);
+  }
+  return candidates.find((candidate) => initialFiles[candidate] !== undefined) ?? key;
+}
+
 export class SceneRuntime {
   constructor(sceneData, behaviors, drawings) {
     this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
@@ -35,6 +50,26 @@ export class SceneRuntime {
     }
   }
 
+  // Read and parse a scene file by name, returning its scene data. Use this
+  // instead of `import x from './scenes/foo.scene'` -- scene files are data, not
+  // JS modules, so importing them is unsupported.
+  readFromFile(name) {
+    const key = resolveSceneFileKey(name);
+    const text = initialFiles[key];
+    if (text === undefined) {
+      throw new Error(`scene file not found: ${name}`);
+    }
+    const { value, error } = parseJsonFile(key, text);
+    if (error) throw new Error(error);
+    return value;
+  }
+
+  // Transition the running scene to the scene stored in the named file (read it
+  // fresh, then load it). The building block for "go to scene" / restart.
+  loadFromFile(name) {
+    this.load(this.readFromFile(name));
+  }
+
   clone() {
     return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.drawings);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.54",
+  "version": "0.4.56",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"