castle-web-cli 0.4.129 → 0.4.131

package/dist/agent-prompts.js

@@ -897,12 +897,12 @@ export function buildTaskPrompt(opts) {
     // -- 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 wrapUpList = opts.plan
-        ? "the 90-progress write, the `castle-web save-version` for your paths, the final `npm run restart`, writing the notes file, and the handoff lines"
-        : "the 90-progress write, the `castle-web save-version` for your paths, the final `npm run restart`, and writing the notes file";
+        ? "the 90-progress write, the `castle-web save-version` for your paths, writing the notes file, and the handoff lines"
+        : "the 90-progress write, the `castle-web save-version` for your paths, and writing the notes file";
     const wrapUp = opts.backend === "claude" || opts.backend === "smith"
         ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} 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\`).${quickReference}${layout}${deckSource}
+    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. Do not reload the served deck -- the person applies your changes when they are ready. \`npm run restart\` exists, but it is HIGHLY flow breaking: it reloads every panel they have open, including the one they are working in. Use it only when a change clearly requires restarting their whole experience.${quickReference}${layout}${deckSource}
 
 Your task (id ${opts.taskId}): ${opts.title}
 
@@ -919,7 +919,7 @@ Operating rules:
 - NEVER run \`restore-version\`. Going back to an earlier version is the user's decision alone -- not yours, not even to undo your own work. If your change is wrong, fix it forward.
 - Other task agents may be editing this same deck IN PARALLEL. When you change an existing file, READ it first and make a targeted edit to just the part you need -- never overwrite a whole file you have not read. A blind full-file rewrite clobbers other agents' in-flight changes. Being a bit slower and careful here is the right tradeoff.
 - Favor real, editable assets: for game objects, characters, and scenery, make pixel-art drawings and place them as real actors in the scene rather than code-drawn shapes -- it keeps the deck editable in the editor and remixable. (Data-driven UI like health bars, score/text, and HUD gauges, plus dynamic things like bullets/particles/effects, stay procedural -- don't force those into drawings.)
-- Respect art ownership: if YOUR task is to create art, make it as real, editable drawing files (NOT hand-written pixel grids or code-drawn shapes), following the deck's CLAUDE.md / AGENTS.md for the drawing format and exact command. But if your prompt only REFERENCES drawing names (a sibling task is creating them in parallel), point the scene at those names and do NOT create the drawing files yourself -- two agents drawing the same sprites clobber each other. The deck's CLAUDE.md / AGENTS.md is the source of truth for how to make art. Reference the intended drawing name from the scene right away (the actor renders a plain-block fallback until the file exists), and remember newly written drawing files need \`npm run restart\` before the kit picks them up.
+- Respect art ownership: if YOUR task is to create art, make it as real, editable drawing files (NOT hand-written pixel grids or code-drawn shapes), following the deck's CLAUDE.md / AGENTS.md for the drawing format and exact command. But if your prompt only REFERENCES drawing names (a sibling task is creating them in parallel), point the scene at those names and do NOT create the drawing files yourself -- two agents drawing the same sprites clobber each other. The deck's CLAUDE.md / AGENTS.md is the source of truth for how to make art. Reference the intended drawing name from the scene right away (the actor renders a plain-block fallback until the file exists); a newly written drawing file shows up for the person on their next reload, which is theirs to trigger.
 - Castle decks are played on phones -- any control you build MUST be touch-friendly by default: respond to touch and drag on the canvas (and tap where natural), never keyboard-only. Keep keyboard working too as a bonus, but a control that only works with a keyboard is broken for most players. (Use the kit's pointer/touch input -- see its CLAUDE.md.)
 - Narrate in plain prose as you work -- the user watches your output stream live. Lead with a short sentence saying what you're about to do BEFORE your first tool call (never open with a silent tool call), then keep dropping a brief plain line every few steps as you go. A line of thinking or a quick "now wiring the paddle to the keys" is exactly what they want to see.
 - Update your progress VERY frequently: write a bare integer 0-100 to ${opts.progressPath} (e.g. \`echo 30 > ${opts.progressPath}\`) every time you advance -- at least every 10 points, or every 20 for properly small tasks. Start near 10, write 90 just before wrapping up. Never let it sit stale while you work.

package/dist/filesChanged.d.ts

@@ -22,4 +22,6 @@ export declare function installFilesChangedWatcher(opts: {
     broadcast: (msg: FilesChangedMessage) => void;
     /** Drop Vite transform caches (so `import.meta.glob` rescans new files). */
     invalidate: () => void;
+    /** Records what was broadcast, so we can see what fires and when. */
+    log?: (line: string) => void;
 }): void;

package/dist/filesChanged.js

@@ -14,7 +14,7 @@ const IGNORED_SEGMENTS = new Set(['node_modules', '.castle', '.git']);
 const DEBOUNCE_MS = 100;
 const MAX_WAIT_MS = 500;
 export function installFilesChangedWatcher(opts) {
-    const { vite, projectDir, broadcast, invalidate } = opts;
+    const { vite, projectDir, broadcast, invalidate, log } = opts;
     const pending = new Map();
     let debounceTimer = null;
     let maxTimer = null;
@@ -45,7 +45,11 @@ export function installFilesChangedWatcher(opts) {
             for (const p of change.affected)
                 affected.add(p);
         }
-        broadcast({ type: 'files_changed', changes, affected: [...affected].sort() });
+        const affectedList = [...affected].sort();
+        log?.(`[watch] ${changes
+            .map((c) => `${c.event} ${c.path}${c.affected.length ? ` (+${c.affected.length})` : ''}`)
+            .join(', ')} | affected ${affectedList.length}\n`);
+        broadcast({ type: 'files_changed', changes, affected: affectedList });
     };
     const schedule = () => {
         if (debounceTimer)

package/dist/ide.js

@@ -414,13 +414,24 @@ function handleVersionSave(deckDir, req, res) {
 // Never forced. Unsaved work that a restore would overwrite comes back as a 409
 // naming the files, which the panel shows -- saving a version first is the fix,
 // and it is one click away in the same panel.
-function handleVersionRestore(deckDir, req, res) {
+function handleVersionRestore(deckDir, req, res, restart) {
     withJsonBody(req, res, (body) => {
         if (typeof body.id !== 'string' || !body.id) {
             return sendJson(res, 400, { error: 'Missing version id.' });
         }
         try {
             const outcome = applyVersionRestore(deckDir, body.id);
+            // A restore rewrites the deck wholesale, so every panel rendering it is
+            // showing the wrong thing. Reload them from here rather than from the
+            // panel that clicked Restore: a restore can DELETE a file, and a reload
+            // racing ahead of Vite's invalidation asks for a module that no longer
+            // exists. `restart` invalidates first, then broadcasts, in that order.
+            //
+            // After the response, not before: dropping every transform means the
+            // whole deck is rebuilt on the next load, and the panel that clicked
+            // Restore should not sit waiting on that.
+            if (!outcome.alreadyThere)
+                setImmediate(() => restart?.());
             sendJson(res, 200, {
                 ok: true,
                 restored: outcome.applied.length,
@@ -684,7 +695,7 @@ function handleFilesDelete(deckDir, req, res) {
 // The builtin Files + code-editor backend: list / read / write deck files and
 // report kit-owned editor extensions. Paths are deck-relative; resolveDeckPath
 // rejects traversal and protected dirs.
-function handleFilesApi(deckDir, req, res, reqPath) {
+function handleFilesApi(deckDir, req, res, reqPath, restart) {
     const action = reqPath.slice(FILES_API_PREFIX.length);
     if (action === 'info') {
         const config = readEditorConfig(deckDir);
@@ -751,7 +762,7 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         return true;
     }
     if (action === 'restore-version') {
-        handleVersionRestore(deckDir, req, res);
+        handleVersionRestore(deckDir, req, res, restart);
         return true;
     }
     if (action === 'list') {
@@ -1060,7 +1071,7 @@ export function createIdeServer(opts) {
             return handleCoverApi(deckDir, req, res);
         }
         if (reqPath.startsWith(FILES_API_PREFIX)) {
-            return handleFilesApi(deckDir, req, res, reqPath);
+            return handleFilesApi(deckDir, req, res, reqPath, opts.restart);
         }
         if (reqPath.startsWith(IMPORT_API_PREFIX)) {
             return handleImportApi(deckDir, req, res, reqPath, opts.restart);

package/dist/importBrowse.js

@@ -38,6 +38,7 @@ const BOOKMARKS_PLAYLIST_PREFIX = 'bookmarks-';
 // an update to this list.
 const KIT_DECK_IDS = [
     'ckRZGFW4iPrx', // physics-2d
+    'JH0SclbPVP0y', // physics-3d
 ];
 // Listing is several server round trips, and the picker is opened, closed and
 // reopened while someone decides. Cached briefly so that costs once.

package/dist/index.js

@@ -87,7 +87,7 @@ function getWsPort(dir) {
 }
 function usage() {
     console.log(`Usage:
-  castle-web init <dir> [--kit NAME]   (kits: physics-2d (default), basic-2d, none)
+  castle-web init <dir> [--kit NAME]   (kits: physics-2d (default), physics-3d, none)
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
@@ -106,7 +106,7 @@ function usage() {
 
 Kits:
   physics-2d  Actor / behavior / scene framework for 2D games with matter-js physics (RigidBody / Collider / Joints on top of Layout / Drawing / Camera). Default if --kit is omitted.
-  basic-2d    The physics-free predecessor of physics-2d; being retired.
+  physics-3d  The same model in 3D: three.js rendering and rapier physics, with a scene editor and a voxel model editor. Built on physics-2d, which it imports.
   none        Minimal vite + canvas setup with the castle-web SDK and no kit.
 
 After init, read the scaffolded deck's CLAUDE.md (also AGENTS.md) for the kit's full author guide.`);
@@ -225,9 +225,15 @@ async function main() {
             const ws = new WS(`ws://localhost:${wsPort}`);
             ws.on('open', () => {
                 ws.send(JSON.stringify({ type: 'restart' }));
-                setTimeout(() => { ws.close(); process.exit(0); }, 100);
+                setTimeout(() => {
+                    ws.close();
+                    process.exit(0);
+                }, 100);
+            });
+            ws.on('error', () => {
+                console.error('Could not connect. Is castle-web serve running?');
+                process.exit(1);
             });
-            ws.on('error', () => { console.error('Could not connect. Is castle-web serve running?'); process.exit(1); });
             break;
         }
         case 'screenshot': {

package/dist/init.js

@@ -38,7 +38,7 @@ const DEFAULT_KIT = 'physics-2d';
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = '0.4.14';
+const PUBLISHED_SDK_VERSION = '0.4.15';
 // The account the first-party kits are (to be) published under, so a kit
 // imported from the CLI's copy is named the same as one fetched from the server.
 const KIT_AUTHOR = 'castle';
@@ -347,6 +347,51 @@ function withoutFileTypes(editor) {
 // been published: an unpublished one can only be named as the CLI's own copy,
 // while a published one is pinned by deckId so the deck can be told about kit
 // releases and take them, without waiting for a CLI release.
+// One kit copied into `imports/<alias>/`, then the same again for every kit IT
+// imports -- all of them side by side at the deck root, never nested.
+//
+// Flattening is not a tidiness choice: a kit refers to its own dependencies as
+// `@imports/<alias>/...`, which resolves against the deck being served, and
+// there is only ever one deck. A kit left inside another kit's `imports/` sits
+// one level too deep and nothing it names resolves. `addImportTo` already
+// flattens this way for fetched decks (see addTransitiveImports); this is the
+// same rule for the copies the CLI ships.
+//
+// A dependency the CLI does not ship keeps the pin the kit declared, and
+// `install` fetches it from the server (restoreMissingImports) -- so a kit may
+// depend on any published deck, not only on its neighbours in kits/.
+function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
+    if (copied.has(alias))
+        return;
+    copied.set(alias, kitDir);
+    const importDir = path.join(projectDir, IMPORTS_DIR, alias);
+    const nestedImports = path.join(kitDir, IMPORTS_DIR);
+    fs.mkdirSync(importDir, { recursive: true });
+    fs.cpSync(kitDir, importDir, {
+        recursive: true,
+        verbatimSymlinks: true,
+        // The kit's own `imports/` is left behind with the rest of its derived
+        // state: its contents are being re-placed at the deck root instead.
+        filter: (src) => src === kitDir || (src !== nestedImports && !KIT_COPY_EXCLUDE.has(path.basename(src))),
+    });
+    const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
+    pins[alias] = makeKitPin(kitConfig, kit);
+    const kitPins = (kitConfig.imports ?? {});
+    for (const [depAlias, depPin] of Object.entries(kitPins)) {
+        if (copied.has(depAlias) || pins[depAlias])
+            continue;
+        const depKit = depAlias.startsWith(`${KIT_AUTHOR}.`)
+            ? depAlias.slice(KIT_AUTHOR.length + 1)
+            : depAlias;
+        const depKitDir = path.join(getKitsDir(), depKit);
+        if (fs.existsSync(depKitDir) && fs.statSync(depKitDir).isDirectory()) {
+            copyKitImport(projectDir, depKitDir, depKit, depAlias, pins, copied);
+        }
+        else {
+            pins[depAlias] = depPin;
+        }
+    }
+}
 function scaffoldFromKitImport(kit, projectDir) {
     const kitDir = requireKitDir(kit);
     // Qualified like any other import (`<author>.<deck>`), and qualified NOW even
@@ -355,15 +400,10 @@ function scaffoldFromKitImport(kit, projectDir) {
     // kits under the castle account turns the pin into a deckId; the name it is
     // already known by stays put.
     const alias = `${KIT_AUTHOR}.${kit}`;
-    const importDir = path.join(projectDir, IMPORTS_DIR, alias);
-    fs.mkdirSync(importDir, { recursive: true });
-    fs.cpSync(kitDir, importDir, {
-        recursive: true,
-        verbatimSymlinks: true,
-        filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
-    });
+    const pins = {};
+    const copied = new Map();
+    copyKitImport(projectDir, kitDir, kit, alias, pins, copied);
     const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
-    const kitPkg = readJsonFile(path.join(kitDir, 'package.json')) ?? {};
     const title = typeof kitConfig.title === 'string' ? kitConfig.title : kit;
     writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
     writeStarterScene(projectDir, kitDir, alias);
@@ -379,16 +419,22 @@ function scaffoldFromKitImport(kit, projectDir) {
     // types too, which a copy taken at scaffold time never could.
     writeJsonFile(path.join(projectDir, 'castle.json'), {
         ...(kitConfig.editor ? { editor: withoutFileTypes(kitConfig.editor) } : {}),
-        imports: { [alias]: makeKitPin(kitConfig, kit) },
+        imports: pins,
     });
     // The kit's code runs from THIS deck's node_modules, so its dependencies are
     // declared here (see syncImportDependencies, which does the same for imports
-    // added later).
+    // added later). Every copied kit contributes, the scaffolding kit first, so
+    // where two of them name the same package the one being scaffolded from wins.
     const { sdkRef, cliCommand } = resolveScaffoldRefs();
     const dependencies = {};
-    for (const [name, range] of Object.entries(kitPkg.dependencies ?? {})) {
-        dependencies[name] =
-            name === 'castle-web-sdk' && String(range).startsWith('file:') ? sdkRef : String(range);
+    for (const depKitDir of copied.values()) {
+        const depPkg = readJsonFile(path.join(depKitDir, 'package.json')) ?? {};
+        for (const [name, range] of Object.entries(depPkg.dependencies ?? {})) {
+            if (dependencies[name] !== undefined)
+                continue;
+            dependencies[name] =
+                name === 'castle-web-sdk' && String(range).startsWith('file:') ? sdkRef : String(range);
+        }
     }
     writeJsonFile(path.join(projectDir, 'package.json'), {
         name: path.basename(projectDir),
@@ -399,7 +445,9 @@ function scaffoldFromKitImport(kit, projectDir) {
     });
     fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias));
     appendCommonInstructions(projectDir);
-    lockImportTree(importDir);
+    for (const importedAlias of copied.keys()) {
+        lockImportTree(path.join(projectDir, IMPORTS_DIR, importedAlias));
+    }
 }
 // The scaffold as version 1, so a creator can always get back to the pristine
 // deck. AFTER the install: it rewrites package.json and writes a lockfile, so a

package/dist/native/loop.js

@@ -313,7 +313,7 @@ const ROLE_FRAMING = {
         // actually running `npm run restart` in a real shell (they have no
         // native restart tool, and naming one there would misdirect them into
         // hallucinating a tool call that doesn't exist for their backend).
-        "Prefer the restart tool over running `npm run restart` in bash -- it does the same reload in this same process, instantly, without spawning a node process just to send one message.",
+        "A native restart tool exists, and is preferable to running `npm run restart` in bash when you do need one. But reloading is HIGHLY flow breaking either way -- it reloads every panel the person has open, including the one they are working in -- so do not reload after ordinary file changes. Use it only when a change clearly requires restarting their whole experience.",
         "Work to completion, then reply with your final message text.",
     ].join(" "),
 };

package/dist/native/tools.js

@@ -551,7 +551,7 @@ const TOOLS = [
     },
     {
         name: "restart",
-        description: "Reload the deck in every connected browser tab, dropping Vite's stale module cache first (same effect as `npm run restart`, applied in-process). Call this after file changes instead of running `npm run restart` via bash.",
+        description: "Reload the deck in every connected browser tab, dropping Vite's stale module cache first (same effect as `npm run restart`, applied in-process). HIGHLY flow breaking: it reloads every panel the person has open, including the one they are working in. Do NOT call it after ordinary file changes -- the person applies those when they are ready. Use it only when a change clearly requires restarting their whole experience.",
         parameters: { type: "object", properties: {} },
         // Task-only: the router never edits the deck, so it never has a reason
         // to reload it.

package/dist/serve.d.ts

@@ -1,3 +1,4 @@
+export declare function appendCapped(file: string, line: string): void;
 export declare function serve(dir: string, options?: {
     port?: string;
     host?: string;

package/dist/serve.js

@@ -12,6 +12,24 @@ import { autoUpdateImports } from './imports.js';
 import * as config from './config.js';
 import { graphql as castleGraphql } from './api.js';
 import { executeCommand } from './castle-host/host.js';
+// The log is a tail, not an archive: append, and once it passes the cap drop
+// whole lines off the front until it is back under.
+const LOG_MAX_BYTES = 2 * 1024 * 1024;
+const LOG_KEEP_BYTES = Math.floor(LOG_MAX_BYTES * 0.8);
+export function appendCapped(file, line) {
+    try {
+        fs.appendFileSync(file, line);
+        if (fs.statSync(file).size <= LOG_MAX_BYTES)
+            return;
+        const text = fs.readFileSync(file, 'utf8');
+        const cut = text.length - LOG_KEEP_BYTES;
+        const nl = text.indexOf('\n', cut);
+        fs.writeFileSync(file, text.slice(nl < 0 ? cut : nl + 1));
+    }
+    catch {
+        // logging must never take the serve down
+    }
+}
 function isPortFree(port) {
     return new Promise((resolve) => {
         const srv = net.createServer();
@@ -361,6 +379,7 @@ export async function serve(dir, options = {}) {
         projectDir,
         broadcast,
         invalidate: () => invalidateModuleCaches(vite),
+        log: (line) => appendCapped(logFile, line),
     });
     await vite.listen();
     // The PTY WebSocket upgrade is handled directly on Vite's HTTP server rather
@@ -535,7 +554,7 @@ function startWSServer(port, projectDir, logFile, screenshotsDir, viteHolder) {
                 }
                 if (msg.type === 'log') {
                     const line = `[${msg.level}] ${msg.msg}\n`;
-                    fs.appendFileSync(logFile, line);
+                    appendCapped(logFile, line);
                     if (msg.level === 'error')
                         process.stderr.write(line);
                     else