castle-web-cli 0.4.75 → 0.4.77

package/dist/castle-host/host.js

@@ -26,13 +26,19 @@ const COMMAND_NAMES = [
     "time.getServerTime",
     "pass.has",
     "pass.offer",
+    "portal.open",
+    "portal.prefetch",
 ];
 // Platform/capability commands: NOT serviced by graphqlFetch. They're dispatched
 // to the host's optional platformHandler (mobile renders native UI; web shows an
 // upsell). A host with no platformHandler returns the command's normalized
 // "unavailable" outcome rather than an error — capability divergence is the
 // host's concern, never a deck-facing gate.
-const PLATFORM_COMMAND_NAMES = ["pass.offer"];
+const PLATFORM_COMMAND_NAMES = [
+    "pass.offer",
+    "portal.open",
+    "portal.prefetch",
+];
 function isCommandName(value) {
     return (typeof value === "string" &&
         COMMAND_NAMES.includes(value));
@@ -98,6 +104,8 @@ function runCommand(ctx, command, params, caps) {
         // Platform commands are handled above; listed here to keep the switch
         // exhaustive over CommandName.
         case "pass.offer":
+        case "portal.open":
+        case "portal.prefetch":
             return runPlatformCommand(ctx, command, params, caps);
     }
 }
@@ -110,8 +118,12 @@ async function runPlatformCommand(ctx, command, params, caps) {
     switch (command) {
         case "pass.offer":
             return passesOffer(ctx, params, caps);
+        case "portal.open":
+            return portalOpen(ctx, params, caps);
+        case "portal.prefetch":
+            return portalPrefetch(ctx, params, caps);
         default:
-            return unavailableOutcome(command);
+            return unavailableOutcome();
     }
 }
 async function passHas(ctx, params, caps) {
@@ -154,13 +166,55 @@ function normalizePassOutcome(value) {
     }
     return { status: "cancelled" };
 }
-function unavailableOutcome(command) {
-    // Only passes exists today; keep this total over future platform commands.
-    if (command === "pass.offer") {
+async function portalOpen(ctx, params, caps) {
+    const targetDeckId = asString(params.targetDeckId, "targetDeckId", "portal.open");
+    // Hosts that can't navigate the feed (dev CLI — no handler; editor) get a
+    // normalized unavailable, never an error.
+    if (!caps.platformHandler)
         return { status: "unavailable" };
+    // Pass the source deckId from trusted context (like pass.offer), never one
+    // the deck supplied, so a deck can't spoof navigating from another deck.
+    const deckId = requireDeckId(ctx, "portal.open");
+    const outcome = await caps.platformHandler("portal.open", { targetDeckId, deckId }, ctx);
+    return normalizePortalOutcome(outcome);
+}
+function normalizePortalOutcome(value) {
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    const status = record.status;
+    const valid = ["navigating", "unavailable"];
+    if (typeof status === "string" && valid.includes(status)) {
+        return { status: status };
     }
     return { status: "unavailable" };
 }
+async function portalPrefetch(ctx, params, caps) {
+    const targetDeckId = asString(params.targetDeckId, "targetDeckId", "portal.prefetch");
+    if (!caps.platformHandler)
+        return { status: "unavailable" };
+    const deckId = requireDeckId(ctx, "portal.prefetch");
+    const outcome = await caps.platformHandler("portal.prefetch", { targetDeckId, deckId }, ctx);
+    return normalizePortalPrefetchOutcome(outcome);
+}
+function normalizePortalPrefetchOutcome(value) {
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    const status = record.status;
+    const valid = [
+        "prefetching",
+        "rejected",
+        "unavailable",
+    ];
+    if (typeof status === "string" && valid.includes(status)) {
+        return { status: status };
+    }
+    return { status: "unavailable" };
+}
+function unavailableOutcome() {
+    return { status: "unavailable" };
+}
 async function deckStorageLoad(ctx, gql) {
     const deckId = requireDeckId(ctx, "deckStorage.load");
     const data = await graphql(gql, DECK_STORAGE_QUERY, { deckId, sessionId: ctx.sessionId }, "deckStorage.load");

package/dist/commonInstructions.d.ts

@@ -1 +1 @@
-export declare const COMMON_INSTRUCTIONS = "## Touch controls (every deck)\n\n- **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 \u2014 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 \u2014 a game with no directional movement should have no movement controls at all.\n";
+export declare const COMMON_INSTRUCTIONS = "## Assets (every deck)\n\n- **Load static assets (drawings, audio, etc.) through the bundler \u2014 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 \u2014 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`.\n\n## Touch controls (every deck)\n\n- **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 \u2014 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 \u2014 a game with no directional movement should have no movement controls at all.\n\n## Fit the card (every deck)\n\n- **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.\n- **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 \u2014 re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.\n  - Exception: deliberate pixel art wants a fixed low-resolution backing store with `image-rendering: pixelated` CSS instead \u2014 don't DPR-scale that; the crisp chunky look is the point.\n";

package/dist/commonInstructions.js

@@ -2,7 +2,17 @@
 // deck's CLAUDE.md, regardless of kit (or no kit). Single source of truth —
 // edit here, not in the kits. Keep it truly kit-agnostic; kit-specific rules
 // (e.g. Space being reserved for play/stop) live in each kit's own CLAUDE.md.
-export const COMMON_INSTRUCTIONS = `## Touch controls (every deck)
+export const COMMON_INSTRUCTIONS = `## Assets (every deck)
+
+- **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\`.
+
+## Touch controls (every deck)
 
 - **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.
+
+## Fit the card (every deck)
+
+- **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.
+- **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.
+  - 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.
 `;

package/dist/filesChanged.d.ts

@@ -0,0 +1,25 @@
+import type { ViteDevServer } from 'vite';
+export interface FileChangeEntry {
+    /** Deck-relative POSIX path. */
+    path: string;
+    event: 'add' | 'change' | 'delete';
+    /**
+     * Deck-relative paths of modules affected via the Vite import graph: the
+     * changed file itself (when it's part of the module graph) plus every
+     * transitive importer. Empty when the file isn't imported by anything.
+     */
+    affected: string[];
+}
+export interface FilesChangedMessage {
+    type: 'files_changed';
+    changes: FileChangeEntry[];
+    /** Union of every change's path + affected set, deduped. */
+    affected: string[];
+}
+export declare function installFilesChangedWatcher(opts: {
+    vite: ViteDevServer;
+    projectDir: string;
+    broadcast: (msg: FilesChangedMessage) => void;
+    /** Drop Vite transform caches (so `import.meta.glob` rescans new files). */
+    invalidate: () => void;
+}): void;

package/dist/filesChanged.js

@@ -0,0 +1,140 @@
+// Serve-side files-changed broadcast. Watches the deck dir through Vite's own
+// chokidar watcher (one watcher for everything), coalesces bursts of fs events
+// into a single `files_changed` message, and folds in the Vite module graph:
+// each change carries the transitive importer closure of the changed file, so
+// consumers can tell "code my bundle depends on changed" apart from "a loose
+// file changed". Vite's own HMR stays fully OFF (`server.hmr: false` in
+// serve.ts) — reload decisions belong to consumers (the kit engine, editors,
+// the shell), not to Vite.
+import * as path from 'path';
+const IGNORED_SEGMENTS = new Set(['node_modules', '.castle', '.git']);
+// Coalescing: a burst of writes (agent editing several files, an editor's
+// debounced saves landing together) becomes one message. DEBOUNCE resets per
+// event; MAX bounds total latency under a sustained stream.
+const DEBOUNCE_MS = 100;
+const MAX_WAIT_MS = 500;
+export function installFilesChangedWatcher(opts) {
+    const { vite, projectDir, broadcast, invalidate } = opts;
+    const pending = new Map();
+    let debounceTimer = null;
+    let maxTimer = null;
+    const flush = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (maxTimer)
+            clearTimeout(maxTimer);
+        debounceTimer = null;
+        maxTimer = null;
+        if (pending.size === 0)
+            return;
+        const changes = [...pending.entries()]
+            .map(([relPath, change]) => ({
+            path: relPath,
+            event: change.event,
+            affected: [...change.affected].sort(),
+        }))
+            .sort((a, b) => a.path.localeCompare(b.path));
+        pending.clear();
+        // New/deleted files can be picked up by `import.meta.glob` importers whose
+        // cached transforms wouldn't rescan; drop caches like `restart` does.
+        if (changes.some((c) => c.event !== 'change'))
+            invalidate();
+        const affected = new Set();
+        for (const change of changes) {
+            affected.add(change.path);
+            for (const p of change.affected)
+                affected.add(p);
+        }
+        broadcast({ type: 'files_changed', changes, affected: [...affected].sort() });
+    };
+    const schedule = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(flush, DEBOUNCE_MS);
+        if (!maxTimer)
+            maxTimer = setTimeout(flush, MAX_WAIT_MS);
+    };
+    vite.watcher.on('all', (watchEvent, absFile) => {
+        const event = watchEvent === 'add' || watchEvent === 'change'
+            ? watchEvent
+            : watchEvent === 'unlink'
+                ? 'delete'
+                : null;
+        if (!event)
+            return; // addDir / unlinkDir
+        const relPath = deckRelative(projectDir, absFile);
+        if (!relPath)
+            return;
+        // Compute the importer closure at event time: for deletes, Vite prunes the
+        // file's graph entry shortly after the event, so waiting until flush would
+        // lose the edges.
+        const affected = importerClosure(vite, projectDir, absFile);
+        const existing = pending.get(relPath);
+        if (existing) {
+            // Merge events: a file created then edited within the window is still an
+            // 'add' for consumers; otherwise the newest event wins.
+            if (!(existing.event === 'add' && event === 'change'))
+                existing.event = event;
+            for (const p of affected)
+                existing.affected.add(p);
+        }
+        else {
+            pending.set(relPath, { event, affected: new Set(affected) });
+        }
+        schedule();
+    });
+}
+// Deck-relative POSIX path, or null when the file is outside the deck or under
+// an ignored directory.
+function deckRelative(projectDir, absFile) {
+    const rel = path.relative(projectDir, absFile);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    const posix = rel.split(path.sep).join('/');
+    if (posix.split('/').some((segment) => IGNORED_SEGMENTS.has(segment)))
+        return null;
+    return posix;
+}
+function clientModuleGraph(vite) {
+    try {
+        const graph = vite
+            .environments?.client?.moduleGraph ?? vite.moduleGraph;
+        return graph ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Deck-relative paths of the changed file's modules plus all transitive
+// importers. Empty when the file isn't part of the module graph.
+function importerClosure(vite, projectDir, absFile) {
+    const graph = clientModuleGraph(vite);
+    if (!graph)
+        return [];
+    let start;
+    try {
+        start = graph.getModulesByFile(absFile);
+    }
+    catch {
+        return [];
+    }
+    if (!start || start.size === 0)
+        return [];
+    const seen = new Set();
+    const files = new Set();
+    const queue = [...start];
+    while (queue.length > 0) {
+        const mod = queue.pop();
+        if (seen.has(mod))
+            continue;
+        seen.add(mod);
+        if (mod.file) {
+            const rel = deckRelative(projectDir, mod.file);
+            if (rel)
+                files.add(rel);
+        }
+        for (const importer of mod.importers ?? [])
+            queue.push(importer);
+    }
+    return [...files];
+}

package/dist/ide.d.ts

@@ -3,6 +3,7 @@ import { Duplex } from "stream";
 import { type RawData } from "ws";
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
+export declare const FILES_API_PREFIX = "/__castle/files/";
 export declare function rawDataToString(data: RawData): string;
 export interface IdeServer {
     /** Serve the IDE page + its static assets. Returns true if it handled the request. */

package/dist/ide.js

@@ -8,6 +8,7 @@
 // client gets a full replay of the current screen + scrollback.
 import * as fs from "fs";
 import * as path from "path";
+import picomatch from "picomatch";
 import { fileURLToPath } from "url";
 import { spawn as spawnPty } from "@lydell/node-pty";
 import headlessPkg from "@xterm/headless";
@@ -62,6 +63,251 @@ function serveShellFile(res, asset) {
 // upgrade handler on Vite's HTTP server).
 export const IDE_ASSET_PREFIX = "/__castle/ide/";
 export const PTY_WS_PATH = "/__castle/pty";
+// Builtin Files + code-editor panels talk to the deck through these endpoints
+// (the shell no longer routes file browsing / code editing through the kit
+// iframe). `list`/`read`/`write` operate on files within the deck dir;
+// `info` reports which extensions the kit owns a rich editor for (so the shell
+// hands those files to the kit iframe and keeps the builtin editor as the
+// default for everything else).
+export const FILES_API_PREFIX = "/__castle/files/";
+// Directories never surfaced in the file list / never read or written through
+// the builtin editor: VCS, deck-private state, and dependency trees.
+const FILES_IGNORE_DIRS = new Set([
+    ".git",
+    ".castle",
+    "node_modules",
+    "dist",
+]);
+// Fallback set of kit-owned rich-editor extensions: the known castle rich
+// content types across kit variants (.pxart in basic-2d, .drawing in older
+// kits). Only used when a kit is present but its getFileKind couldn't be parsed.
+// The builtin code editor renders everything else (and everything on a kitless
+// deck). Kept here -- one place -- rather than baked into the shell, so a future
+// kit manifest can supply it without a shell change.
+const FALLBACK_KIT_EDITOR_EXTS = [".scene", ".pxart", ".drawing"];
+// Extensions that are always code/text, even if a kit's getFileKind mentions
+// them -- these get the builtin editor, never a rich kit editor.
+const CODE_TEXT_KINDS = new Set(["code", "text"]);
+// Parse the kit's `engine/files.js` getFileKind for extensions it maps to a
+// rich (non code/text) kind -- the authoritative, per-deck source of which
+// files the kit owns an editor for. Returns null if the file is absent so the
+// caller can fall back. Matches lines like:
+//   if (path.endsWith('.scene')) return 'scene';
+function parseKitEditorExtensions(deckDir) {
+    let src;
+    try {
+        src = fs.readFileSync(path.join(deckDir, "engine", "files.js"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const exts = [];
+    const re = /endsWith\(\s*['"](\.[^'"]+)['"]\s*\)\s*\)\s*return\s*['"]([^'"]+)['"]/g;
+    for (let m = re.exec(src); m; m = re.exec(src)) {
+        const [, ext, kind] = m;
+        if (!CODE_TEXT_KINDS.has(kind) && !exts.includes(ext))
+            exts.push(ext);
+    }
+    return exts;
+}
+// Resolve a client-supplied deck-relative path to an absolute path inside
+// `deckDir`, rejecting traversal / protected dirs. Mirrors serve.ts's
+// writeProjectFile guards so the builtin editor can't escape the deck.
+function resolveDeckPath(deckDir, requestedPath) {
+    if (typeof requestedPath !== "string" || requestedPath.trim() === "") {
+        return { ok: false, error: "Missing file path." };
+    }
+    const normalized = path.normalize(requestedPath.replace(/\\/g, "/"));
+    if (normalized === "." ||
+        normalized === ".." ||
+        path.isAbsolute(normalized) ||
+        normalized.startsWith(`..${path.sep}`)) {
+        return { ok: false, error: `Path outside the deck: ${requestedPath}` };
+    }
+    const parts = normalized.split(path.sep);
+    if (parts.some((p) => FILES_IGNORE_DIRS.has(p))) {
+        return { ok: false, error: `Protected deck path: ${requestedPath}` };
+    }
+    const abs = path.resolve(deckDir, normalized);
+    const rel = path.relative(deckDir, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { ok: false, error: `Path outside the deck: ${requestedPath}` };
+    }
+    return { ok: true, abs, rel: rel.split(path.sep).join("/") };
+}
+// Recursively list deck files (relative POSIX paths, sorted), skipping the
+// ignore dirs above and dotfiles like .DS_Store.
+function listDeckFiles(deckDir) {
+    const out = [];
+    function walk(dir, prefix) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".DS_Store")
+                continue;
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (FILES_IGNORE_DIRS.has(entry.name))
+                    continue;
+                walk(path.join(dir, entry.name), rel);
+            }
+            else if (entry.isFile()) {
+                out.push(rel);
+            }
+        }
+    }
+    walk(deckDir, "");
+    out.sort((a, b) => a.localeCompare(b));
+    return out;
+}
+function asStringArray(value) {
+    if (Array.isArray(value) && value.every((e) => typeof e === "string")) {
+        return value;
+    }
+    return undefined;
+}
+// Read the deck's `castle.json` `editor` block. Tolerates an absent /
+// unparseable file (returns {}). Folds the legacy top-level `editorExtensions`
+// into `editor.extensions` for decks saved before the `editor` block existed.
+function readEditorConfig(deckDir) {
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(path.join(deckDir, "castle.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const editor = data.editor ?? {};
+    const config = {
+        initialPanels: Array.isArray(editor.initialPanels)
+            ? editor.initialPanels
+            : undefined,
+        hiddenPaths: asStringArray(editor.hiddenPaths),
+        visiblePaths: asStringArray(editor.visiblePaths),
+        extensions: asStringArray(editor.extensions) ?? asStringArray(data.editorExtensions),
+    };
+    return config;
+}
+// Extensions the kit owns a rich editor for. A kitless (bare) deck has no kit
+// entry, so this is empty and the builtin editor renders everything. A deck may
+// override the default list via `castle.json` `editor.extensions`.
+function kitEditorExtensions(deckDir) {
+    const configured = readEditorConfig(deckDir).extensions;
+    if (configured)
+        return configured;
+    // `main.jsx` is the kit entry point; bare decks scaffold game.js + index.html
+    // with no main.jsx, so its absence means "no kit, builtin editor for all".
+    if (!fs.existsSync(path.join(deckDir, "main.jsx")))
+        return [];
+    // Prefer the kit's own getFileKind (authoritative per deck); fall back to the
+    // known rich content types if it couldn't be read/parsed.
+    const parsed = parseKitEditorExtensions(deckDir);
+    if (parsed && parsed.length > 0)
+        return parsed;
+    return FALLBACK_KIT_EDITOR_EXTS;
+}
+// Apply the deck's `editor.hiddenPaths` / `editor.visiblePaths` globs to a file
+// list (deck-relative POSIX paths). Only hidden -> drop matches; only visible ->
+// keep only matches; both -> keep visible, then subtract hidden. No config ->
+// the list passes through unchanged.
+function filterDeckFiles(files, config) {
+    let result = files;
+    if (config.visiblePaths && config.visiblePaths.length > 0) {
+        const isVisible = picomatch(config.visiblePaths);
+        result = result.filter((f) => isVisible(f));
+    }
+    if (config.hiddenPaths && config.hiddenPaths.length > 0) {
+        const isHidden = picomatch(config.hiddenPaths);
+        result = result.filter((f) => !isHidden(f));
+    }
+    return result;
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(JSON.stringify(body));
+}
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function handleFilesWrite(deckDir, req, res) {
+    void (async () => {
+        let body;
+        try {
+            body = JSON.parse(await readRequestBody(req));
+        }
+        catch {
+            return sendJson(res, 400, { error: "Invalid JSON body." });
+        }
+        const resolved = resolveDeckPath(deckDir, body.path);
+        if (!resolved.ok)
+            return sendJson(res, 400, { error: resolved.error });
+        if (typeof body.contents !== "string") {
+            return sendJson(res, 400, { error: "File contents must be a string." });
+        }
+        try {
+            fs.mkdirSync(path.dirname(resolved.abs), { recursive: true });
+            fs.writeFileSync(resolved.abs, body.contents, "utf8");
+            sendJson(res, 200, { ok: true, path: resolved.rel });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, 500, { error: `Could not write ${resolved.rel}: ${message}` });
+        }
+    })();
+}
+// 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) {
+    const action = reqPath.slice(FILES_API_PREFIX.length);
+    if (action === "info") {
+        const config = readEditorConfig(deckDir);
+        sendJson(res, 200, {
+            kitEditorExtensions: kitEditorExtensions(deckDir),
+            initialPanels: config.initialPanels ?? null,
+            hiddenPaths: config.hiddenPaths ?? [],
+            visiblePaths: config.visiblePaths ?? [],
+        });
+        return true;
+    }
+    if (action === "list") {
+        const files = filterDeckFiles(listDeckFiles(deckDir), readEditorConfig(deckDir));
+        sendJson(res, 200, { files });
+        return true;
+    }
+    if (action === "read") {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const resolved = resolveDeckPath(deckDir, url.searchParams.get("path"));
+        if (!resolved.ok)
+            return sendJson(res, 400, { error: resolved.error }), true;
+        try {
+            const contents = fs.readFileSync(resolved.abs, "utf8");
+            sendJson(res, 200, { path: resolved.rel, contents });
+        }
+        catch {
+            sendJson(res, 404, { error: `Not found: ${resolved.rel}` });
+        }
+        return true;
+    }
+    if (action === "write") {
+        handleFilesWrite(deckDir, req, res);
+        return true;
+    }
+    return sendJson(res, 404, { error: `Unknown files action: ${action}` }), true;
+}
 function defaultShell() {
     if (process.platform === "win32") {
         return { command: process.env.COMSPEC ?? "cmd.exe", args: [] };
@@ -252,13 +498,16 @@ export function createIdeServer(opts) {
         wss.handleUpgrade(req, socket, head, (ws) => attachClient(ws));
         return true;
     }
-    function handleHttpRequest(_req, res, reqPath) {
+    function handleHttpRequest(req, res, reqPath) {
         // `/` -> the shell's index.html; `/__castle/ide/<asset>` -> bundle assets.
         if (reqPath === "/")
             return serveShellFile(res, "index.html");
         if (reqPath.startsWith(IDE_ASSET_PREFIX)) {
             return serveShellFile(res, reqPath.slice(IDE_ASSET_PREFIX.length) || "index.html");
         }
+        if (reqPath.startsWith(FILES_API_PREFIX)) {
+            return handleFilesApi(deckDir, req, res, reqPath);
+        }
         return false;
     }
     function shutdown() {

package/dist/init.js

@@ -35,16 +35,53 @@ const DEFAULT_KIT = "basic-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.7";
-// Never copied into a fresh deck: build/dependency junk, and castle.json (a
-// fresh deck has no deckId until its first save-deck).
+const PUBLISHED_SDK_VERSION = "0.4.9";
+// Never copied into a fresh deck: build/dependency junk. castle.json IS copied
+// (the kit ships a config-only one with the editor layout / file filters), but
+// `scaffoldFromKit` strips any identity fields off it first -- a fresh deck has
+// no deckId until its first save-deck, which owns those fields.
 const KIT_COPY_EXCLUDE = new Set([
     "node_modules",
     ".castle",
     "dist",
     ".git",
-    "castle.json",
 ]);
+// Identity fields owned by save-deck, never shipped in a kit's config-only
+// castle.json. Stripped from a copied castle.json (and absent from the bare
+// default) so a fresh deck has no deckId until its first save.
+const CASTLE_JSON_IDENTITY_FIELDS = [
+    "deckId",
+    "cardId",
+    "title",
+    "caption",
+    "visibility",
+];
+// The bare (`--kit none`) deck's default editor config: just the Files panel and
+// a Play panel. No file filtering -- a bare deck is hand-rolled, so the author
+// knows what's there; show everything for now.
+const BARE_CASTLE_JSON = {
+    editor: {
+        initialPanels: [{ type: "files" }, { type: "playtest" }],
+        hiddenPaths: [],
+        visiblePaths: [],
+    },
+};
+// Strip save-deck-owned identity fields from a copied kit castle.json, leaving
+// only its config (the editor block). No-op if the kit shipped no castle.json.
+function stripCastleJsonIdentity(projectDir) {
+    const castlePath = path.join(projectDir, "castle.json");
+    if (!fs.existsSync(castlePath))
+        return;
+    try {
+        const data = JSON.parse(fs.readFileSync(castlePath, "utf8"));
+        for (const field of CASTLE_JSON_IDENTITY_FIELDS)
+            delete data[field];
+        fs.writeFileSync(castlePath, JSON.stringify(data, null, 2) + "\n");
+    }
+    catch {
+        // kit shipped an unparseable castle.json -- leave it for the user to fix
+    }
+}
 // Resolve how a scaffolded deck should reference the sdk + cli. Both the bare
 // and kit scaffold paths go through here so they stay in sync.
 //   workspace mode (sdk/ sits next to cli/, i.e. running from a checkout):
@@ -136,6 +173,7 @@ function scaffoldBare(projectDir) {
     fs.mkdirSync(projectDir, { recursive: true });
     fs.writeFileSync(path.join(projectDir, "index.html"), INDEX_HTML);
     fs.writeFileSync(path.join(projectDir, "game.js"), GAME_JS);
+    fs.writeFileSync(path.join(projectDir, "castle.json"), JSON.stringify(BARE_CASTLE_JSON, null, 2) + "\n");
     fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeClaudeMd());
     appendCommonInstructions(projectDir);
     ensureAgentsSymlink(projectDir);
@@ -170,6 +208,10 @@ function scaffoldFromKit(kit, projectDir) {
         verbatimSymlinks: true,
         filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
     });
+    // The kit ships a config-only castle.json (editor layout / file filters); keep
+    // its config but drop any identity fields so this fresh deck has no deckId
+    // until its first save-deck.
+    stripCastleJsonIdentity(projectDir);
     // The kit's package.json carries the kit's name; rename it to the deck dir.
     // Kit-relative refs to `../../sdk` and `../../cli/dist` only resolve when the
     // deck lives at castle-experimental-web/decks/<name>/. Rewrite both to