castle-web-cli 0.4.122 → 0.4.124

package/dist/agent-prompts.js

@@ -63,6 +63,7 @@ comma-separated active-task titles or ids, or \`all\`
 - Never claim the board is cleared without actually emitting the fence.
 - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it.
 - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
+- The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you NEVER run \`restore-version\`: going back is the user's own decision, not something you do on their behalf.
 
 Asking with options (the \`\`\`ask block). When you need the user to settle a few choices at once, emit ONE fenced block tagged \`ask\` containing JSON -- it renders inline in the chat as grouped options they tap and submit together (far better than stacking questions they can only half-answer). Reach for it to pin a direction fast when their ask is vague ("make me a game" -> ask what kind), NOT to interrogate. Options only, no free text.
 
@@ -233,7 +234,7 @@ 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 wrapUp = opts.backend === "claude" || opts.backend === "smith"
-        ? `\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.`
+        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the \`castle-web save-version\` for your paths, 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\`).${quickReference}${layout}${deckSource}
 
@@ -247,6 +248,9 @@ Operating rules:
 - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
 - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.
 - Do this one task completely, then stop. Do not expand scope.
+- SAVE A VERSION when your change is done, so the user can see and undo it: \`castle-web save-version -m "<short description of what you changed>" <each path you touched>\`. Name those paths explicitly -- a bare \`save-version\` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.
+- Overlap with the other agents working in this deck is fine and expected -- do not try to avoid it or wait for them. Saving only your own paths is all that is asked of you; nothing anyone has written is lost by your save.
+- 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.
@@ -264,7 +268,7 @@ phase: wiring the paddle to touch
   - \`phase\` -- a SHORT, plain-language line for this moment ("wiring the paddle to touch", "drawing the flag"). No file or code names. Update \`avatar\` and \`phase\` together each time your stage changes -- a few times across the task, not every turn. (You may also include \`progress: NN\` here, but the progress file above is the primary progress channel.)
 - Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, NO file/behavior names or implementation notes -- those are for you, not the player. Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
 - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
-- Never touch files under .castle/ other than those two paths.`;
+- Never touch files under .castle/ other than those two paths. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
 }
 // Appended to claude task agents' system prompt (portable replacement for the
 // machine-specific /goal slash command): commit to autonomous completion.

package/dist/castleJson.d.ts

@@ -20,3 +20,5 @@ export declare const DEFAULT_MAIN = "main.jsx";
 export declare function deckMainFile(dir: string): string;
 export declare function readCastleJson(dir: string): CastleJson | null;
 export declare function readCastleJsonOrThrow(dir: string): CastleJson | null;
+export declare function ensureVisiblePath(deckDir: string, rel: string): boolean;
+export declare function ensureVisibleGlob(deckDir: string, glob: string, probe: string): boolean;

package/dist/castleJson.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import picomatch from 'picomatch';
 export const DEFAULT_STARTER_SCENE = 'scenes/main.scene';
 export function deckStarterScene(dir) {
     const declared = readCastleJson(dir)?.starterScene;
@@ -32,3 +33,41 @@ export function readCastleJsonOrThrow(dir) {
         throw new Error(`Could not read ${file}: ${e instanceof Error ? e.message : String(e)}`);
     });
 }
+// Add `<rel>/**` to the deck's editor.visiblePaths so files created in a
+// newly-made folder show in the curated Files tree.
+export function ensureVisiblePath(deckDir, rel) {
+    return ensureVisibleGlob(deckDir, `${rel}/**`, `${rel}/__probe__`);
+}
+// Add `glob` to the deck's editor.visiblePaths. Only touches a deck that is
+// ALREADY curated (non-empty visiblePaths) -- when visiblePaths is empty
+// everything is visible, and adding a glob would wrongly start hiding things.
+// No-op if an existing glob already covers `probe`, a path the new glob would
+// match. Returns whether it wrote.
+export function ensureVisibleGlob(deckDir, glob, probe) {
+    const file = path.join(deckDir, 'castle.json');
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return false; // no castle.json yet (deck never saved) -> treat as not curated
+    }
+    const visible = data.editor && Array.isArray(data.editor.visiblePaths)
+        ? data.editor.visiblePaths.filter((v) => typeof v === 'string')
+        : null;
+    if (!visible || visible.length === 0)
+        return false; // not curated -> all visible
+    if (visible.includes(glob))
+        return false;
+    if (picomatch(visible)(probe))
+        return false; // already covered
+    visible.push(glob);
+    data.editor.visiblePaths = visible;
+    try {
+        fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/diffText.d.ts

@@ -0,0 +1,14 @@
+export type DiffOp = {
+    kind: 'same' | 'add' | 'remove';
+    text: string;
+};
+/** True for content that is not text: a NUL byte, or bytes that aren't UTF-8. */
+export declare function looksBinary(content: Buffer): boolean;
+/** Every line of both sides, in order, marked same / add / remove. */
+export declare function diffOps(beforeText: string, afterText: string): DiffOp[] | null;
+/**
+ * A unified diff of two texts, or null when the change is too large to be worth
+ * rendering as one. Header lines are the caller's business -- this is only the
+ * hunks.
+ */
+export declare function unifiedDiff(beforeText: string, afterText: string): string[] | null;

package/dist/diffText.js

@@ -0,0 +1,138 @@
+// A small unified-diff generator, for `show-version`.
+//
+// Deliberately not a dependency: the only diff this CLI needs is between two
+// blobs it already has, and a hand-rolled line diff is a few dozen lines with
+// no supply chain attached.
+//
+// Shape of the algorithm: strip the common head and tail first -- a real edit
+// usually touches a few lines in a long file, so this leaves a small middle --
+// then run a longest-common-subsequence over what remains. The LCS table is
+// quadratic, so a middle that stays large after trimming reports a summary
+// instead of a patch rather than eating memory.
+const CONTEXT_LINES = 3;
+const MAX_DIFF_LINES = 2000;
+/** True for content that is not text: a NUL byte, or bytes that aren't UTF-8. */
+export function looksBinary(content) {
+    const sample = content.subarray(0, 8000);
+    if (sample.includes(0))
+        return true;
+    // A lone replacement char means the decoder hit a byte sequence that isn't
+    // valid UTF-8 -- unless the file genuinely contains one, which is rare enough
+    // to accept and harmless to treat as binary.
+    return sample.toString('utf8').includes('�');
+}
+function splitLines(text) {
+    const lines = text.split('\n');
+    // A trailing newline yields a final empty element that is not a line.
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+// Ops for the middle section, by LCS backtracking.
+function diffMiddle(before, after) {
+    const rows = before.length;
+    const cols = after.length;
+    const table = Array.from({ length: rows + 1 }, () => new Array(cols + 1).fill(0));
+    for (let i = rows - 1; i >= 0; i--) {
+        for (let j = cols - 1; j >= 0; j--) {
+            table[i][j] =
+                before[i] === after[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < rows && j < cols) {
+        if (before[i] === after[j]) {
+            ops.push({ kind: 'same', text: before[i] });
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            ops.push({ kind: 'remove', text: before[i] });
+            i++;
+        }
+        else {
+            ops.push({ kind: 'add', text: after[j] });
+            j++;
+        }
+    }
+    while (i < rows)
+        ops.push({ kind: 'remove', text: before[i++] });
+    while (j < cols)
+        ops.push({ kind: 'add', text: after[j++] });
+    return ops;
+}
+/** Every line of both sides, in order, marked same / add / remove. */
+export function diffOps(beforeText, afterText) {
+    const before = splitLines(beforeText);
+    const after = splitLines(afterText);
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head++;
+    let tail = 0;
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail]) {
+        tail++;
+    }
+    const beforeMiddle = before.slice(head, before.length - tail);
+    const afterMiddle = after.slice(head, after.length - tail);
+    if (beforeMiddle.length > MAX_DIFF_LINES || afterMiddle.length > MAX_DIFF_LINES)
+        return null;
+    return [
+        ...before.slice(0, head).map((text) => ({ kind: 'same', text })),
+        ...diffMiddle(beforeMiddle, afterMiddle),
+        ...before.slice(before.length - tail).map((text) => ({ kind: 'same', text })),
+    ];
+}
+function opsToHunks(ops) {
+    const changedAt = ops.map((op) => op.kind !== 'same');
+    const hunks = [];
+    let beforeLine = 1;
+    let afterLine = 1;
+    let current = null;
+    for (let index = 0; index < ops.length; index++) {
+        const op = ops[index];
+        // A same-line belongs to a hunk when a change is within CONTEXT_LINES of it
+        // on either side; that is what turns scattered edits into readable blocks.
+        const near = op.kind !== 'same' ||
+            changedAt.slice(Math.max(0, index - CONTEXT_LINES), index + CONTEXT_LINES + 1).some(Boolean);
+        if (near) {
+            if (!current)
+                current = { beforeStart: beforeLine, afterStart: afterLine, lines: [], beforeCount: 0, afterCount: 0 };
+            current.lines.push(`${op.kind === 'add' ? '+' : op.kind === 'remove' ? '-' : ' '}${op.text}`);
+            if (op.kind !== 'add')
+                current.beforeCount++;
+            if (op.kind !== 'remove')
+                current.afterCount++;
+        }
+        else if (current) {
+            hunks.push(current);
+            current = null;
+        }
+        if (op.kind !== 'add')
+            beforeLine++;
+        if (op.kind !== 'remove')
+            afterLine++;
+    }
+    if (current)
+        hunks.push(current);
+    return hunks;
+}
+/**
+ * A unified diff of two texts, or null when the change is too large to be worth
+ * rendering as one. Header lines are the caller's business -- this is only the
+ * hunks.
+ */
+export function unifiedDiff(beforeText, afterText) {
+    const ops = diffOps(beforeText, afterText);
+    if (!ops)
+        return null;
+    const out = [];
+    for (const hunk of opsToHunks(ops)) {
+        out.push(`@@ -${hunk.beforeStart},${hunk.beforeCount} +${hunk.afterStart},${hunk.afterCount} @@`);
+        out.push(...hunk.lines);
+    }
+    return out;
+}

package/dist/headlessCover.d.ts

@@ -0,0 +1,13 @@
+import { type PlaytestBrowserManager } from "./native/playtest-browser.js";
+export interface HeadlessCoverResult {
+    ok: boolean;
+    outPath?: string;
+    error?: string;
+    installedMs?: number;
+}
+export declare function captureCoverHeadless(opts: {
+    serveUrl: string;
+    outPath: string;
+    manager?: PlaytestBrowserManager;
+    onProgress?: (message: string) => void;
+}): Promise<HeadlessCoverResult>;

package/dist/headlessCover.js

@@ -0,0 +1,99 @@
+// Capture a deck's cover with a real browser instead of asking the page to
+// draw itself.
+//
+// The in-page path (the SDK's html2canvas compositing) re-implements CSS
+// rendering in JS, so it inherits a support list: a WebGL canvas is blank
+// unless the deck happened to pass `preserveDrawingBuffer`, and any element
+// using `filter` / `clip-path` / `mask-image` / a blend mode is dropped. Both
+// fail SILENTLY -- the capture succeeds and returns a plausible image that is
+// missing part of the game -- and both put the burden on the deck to know a
+// platform quirk.
+//
+// Screenshotting through the browser removes that whole class: the engine
+// composites the frame it was already going to composite, so whatever the deck
+// legitimately renders is what lands in the cover. This is the same move the
+// mobile app made for its exp-web snapshots (WKWebView takeSnapshot / PixelCopy)
+// -- ask the platform for its pixels rather than re-deriving them.
+//
+// It buys correctness, not judgment: a cold headless load sees the deck's FIRST
+// moments, where the in-page path saw whatever the creator had on screen. That
+// is why this is the fallback for an unattended save rather than a replacement
+// for the editor's capture button -- see `SETTLE_MS`.
+import fs from "fs";
+import path from "path";
+import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
+// The card is 5:7; this is the same fixed viewport the playtest tool uses, so a
+// deck laid out for one is laid out for the other.
+const VIEWPORT = { width: 500, height: 700 };
+// Retina-ish, so a cover holds up scaled down in a feed and blown up on a deck
+// page. 2x of a 500x700 card is 1000x1400.
+const SCALE = 2;
+const NAV_TIMEOUT_MS = 20_000;
+// Long enough for a deck to boot, load assets and render real frames -- a cover
+// of frame zero is a loading screen. Deliberately generous: this runs once per
+// save, never in a player's path.
+const SETTLE_MS = 3_500;
+// The card the SDK mounts (`initCard`) or a deck marks itself. Falling back to
+// the whole viewport keeps a deck that does neither from getting no cover at
+// all -- the viewport IS the card in play mode.
+const CARD_SELECTOR = "#castle-card, [data-castle-card]";
+// Grab the deck's cover from `serveUrl` and write it to `<projectDir>/.castle`.
+// Never throws; a failure is reported, not raised.
+export async function captureCoverHeadless(opts) {
+    const manager = opts.manager ?? createPlaytestBrowserManager();
+    const outcome = await manager.withBrowser((browser) => shoot(browser, opts.serveUrl), { onProgress: opts.onProgress });
+    if (!outcome.ok)
+        return { ok: false, error: outcome.error };
+    if (!outcome.value.png)
+        return { ok: false, error: outcome.value.error ?? "capture produced no image" };
+    try {
+        fs.mkdirSync(path.dirname(opts.outPath), { recursive: true });
+        fs.writeFileSync(opts.outPath, outcome.value.png);
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    return { ok: true, outPath: opts.outPath, installedMs: outcome.installedMs };
+}
+async function shoot(browser, serveUrl) {
+    const context = await browser.newContext({
+        viewport: { ...VIEWPORT },
+        deviceScaleFactor: SCALE,
+        // A cover is a still of a game: give it a touch-shaped context, since decks
+        // are phone-first and some branch their controls on it.
+        hasTouch: true,
+        isMobile: true,
+    });
+    try {
+        const page = await context.newPage();
+        // `/index.html`, NOT `/`: the serve's root is the editor shell, and the deck
+        // itself is what the shell loads into its iframe (see serve.ts). Pointing at
+        // `/` photographs the editor. `?edit=0` then asks for the play surface, so
+        // the deck renders in its card with no editor UI -- which is what a cover is.
+        const url = `${serveUrl.replace(/\/$/, "")}/index.html?edit=0`;
+        await page.goto(url, { waitUntil: "domcontentloaded", timeout: NAV_TIMEOUT_MS });
+        // Let it boot and actually draw. `waitForTimeout` rather than a load event:
+        // a deck is a game, and "loaded" says nothing about whether it has rendered
+        // anything worth showing.
+        await page.waitForTimeout(SETTLE_MS);
+        // A deck that failed to build renders vite's error overlay, and a browser
+        // screenshots that just as faithfully as it screenshots a game -- so without
+        // this, a broken deck publishes a cover of its own stack trace. The in-page
+        // path could not do this (nothing renders, so nothing is captured), so it is
+        // a failure mode this approach introduces and has to close itself.
+        const broken = await page.$("vite-error-overlay");
+        if (broken)
+            return { error: "the deck is showing a build error, so there is nothing to photograph" };
+        const card = await page.$(CARD_SELECTOR);
+        // Element screenshot clips to the card for us. Without a card, the viewport
+        // IS the card in play mode, so shoot that.
+        const png = card ? await card.screenshot({ type: "png" }) : await page.screenshot({ type: "png" });
+        return { png };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        await context.close().catch(() => undefined);
+    }
+}

package/dist/ide.d.ts

@@ -1,6 +1,7 @@
 import * as http from 'http';
 import { Duplex } from 'stream';
 import { type RawData } from 'ws';
+import { COVER_FILE } from './localPaths.js';
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
 export declare const VENDOR_PREFIX = "/__castle/vendor/";
@@ -8,7 +9,7 @@ export declare const FAVICON_FILES: string[];
 export declare const FAVICON_LINK_TAGS: string;
 export declare const FILES_API_PREFIX = "/__castle/files/";
 export declare const COVER_API_PATH = "/__castle/cover";
-export declare const COVER_FILE = "preview.png";
+export { COVER_FILE };
 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

@@ -16,10 +16,13 @@ import headlessPkg from '@xterm/headless';
 import { SerializeAddon } from '@xterm/addon-serialize';
 import { WebSocketServer } from 'ws';
 import { IMPORTS_DIR, importStatuses, updateImport } from './imports.js';
+import { ensureVisibleGlob, ensureVisiblePath } from './castleJson.js';
 import { readEditorConfig, resolveFileTypes, } from './editorConfig.js';
 import { UNSUPPORTED_MEDIA } from './unsupportedMedia.js';
 import { IMPORT_API_PREFIX, handleImportApi } from './importBrowse.js';
 import { readRequestBody, sendJson } from './httpJson.js';
+import { COVER_FILE } from './localPaths.js';
+import { applyVersionRestore, createVersion, NotOnThisLine, pendingChanges, UnsavedChanges, versionSummaries, } from './versions.js';
 import { envForUserShell, installCliShims } from './byo-auth.js';
 const HeadlessTerminal = headlessPkg.Terminal;
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -135,15 +138,34 @@ export const FAVICON_LINK_TAGS = [
 // 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/';
-// The deck's local cover image. Its own endpoint rather than a files/upload,
-// because this file is written over and over (once per automatic capture) and
-// upload deliberately refuses to clobber. A cover is platform vocabulary, not a
-// kit's -- `save-deck` is what publishes preview.png -- so it belongs here.
+// The deck's local cover image. Nothing in THIS shell posts here any more --
+// covers are captured headlessly by `save-deck` (see headlessCover.ts), which
+// photographs the deck with a real browser instead of asking the page to
+// rasterize itself. The endpoint stays because the shell is baked into the
+// sandbox image: a warm sandbox keeps running an older shell that still posts
+// its automatic captures here, and accepting them is cheaper than making those
+// requests 404. `save-deck` still reads preview.png as a last-resort fallback.
+//
+// Its own endpoint rather than a files/upload because this file is written over
+// and over and upload deliberately refuses to clobber. A cover is platform
+// vocabulary, not a kit's, so it belongs here.
 export const COVER_API_PATH = '/__castle/cover';
-export const COVER_FILE = 'preview.png';
+// Re-exported so `save-deck` and anything else that already asks the serve for
+// the cover's name keeps working.
+export { COVER_FILE };
 // 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']);
+// Never writable through the files API, whatever the tree shows. `.castle` holds
+// the deck's private state, and since build 1 that includes the version store --
+// the one place where losing bytes loses history rather than a file. The list
+// above is about what the tree SHOWS and could reasonably change; this is about
+// what a write may touch, so the store stays safe if it ever does.
+//
+// A guard, not a lock: the directory keeps its normal permissions. Making it
+// read-only and unlocking around writes races with concurrent processes, gets
+// clobbered by tools, and still would not stop a raw shell write.
+const PROTECTED_WRITE_DIRS = new Set(['.castle']);
 // Ceiling on one uploaded file. A deck is saved whole (source tar + bundle), so
 // a huge asset is a problem for the deck long before it is a problem here --
 // refuse it at the door with a message rather than let it land and break `save`.
@@ -197,6 +219,12 @@ function resolveDeckPath(deckDir, requestedPath, opts = {}) {
         return { ok: false, error: `Path outside the deck: ${requestedPath}` };
     }
     const parts = normalized.split(path.sep);
+    if (opts.mutation && parts.some((p) => PROTECTED_WRITE_DIRS.has(p))) {
+        return {
+            ok: false,
+            error: `${requestedPath} is the deck's own state (the version store lives here) and is not writable.`,
+        };
+    }
     if (parts.some((p) => FILES_IGNORE_DIRS.has(p))) {
         return { ok: false, error: `Protected deck path: ${requestedPath}` };
     }
@@ -347,6 +375,61 @@ function sendFailure(res, action, rel, err) {
     const message = err instanceof Error ? err.message : String(err);
     sendJson(res, 500, { error: `Could not ${action} ${rel}: ${message}` });
 }
+// The version panel's three calls, on the same store the `save-version` /
+// `restore-version` commands use -- the editor is another way to run them, not
+// a second history.
+function handleVersionsList(deckDir, res) {
+    try {
+        // The history and what is outstanding against it, together: the panel shows
+        // them as one picture, and two calls could disagree about the moment.
+        sendJson(res, 200, { versions: versionSummaries(deckDir), pending: pendingChanges(deckDir) });
+    }
+    catch (e) {
+        sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+    }
+}
+// Saves everything dirty: the panel has no path selection, so partial saves
+// stay a CLI and agent thing.
+function handleVersionSave(deckDir, req, res) {
+    withJsonBody(req, res, (body) => {
+        const message = typeof body.message === 'string' ? body.message : '';
+        try {
+            const { version } = createVersion(deckDir, { message });
+            sendJson(res, 200, { ok: true, id: version?.id ?? null });
+        }
+        catch (e) {
+            sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+}
+// 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) {
+    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);
+            sendJson(res, 200, {
+                ok: true,
+                restored: outcome.applied.length,
+                offChain: outcome.offChain,
+                alreadyThere: outcome.alreadyThere,
+            });
+        }
+        catch (e) {
+            // Both refusals are answers, not faults: the caller asked for something
+            // this history can't do, and the message says which.
+            const refused = e instanceof UnsavedChanges || e instanceof NotOnThisLine;
+            const message = e instanceof Error ? e.message : String(e);
+            sendJson(res, refused ? 409 : 500, {
+                error: e instanceof UnsavedChanges ? `${message}\nSave a version first.` : message,
+            });
+        }
+    });
+}
 function handleFilesWrite(deckDir, req, res) {
     withMutationPath(deckDir, req, res, (target, body) => {
         if (typeof body.contents !== 'string') {
@@ -362,44 +445,6 @@ function handleFilesWrite(deckDir, req, res) {
         }
     });
 }
-// Add `<rel>/**` to the deck's editor.visiblePaths so files created in a
-// newly-made folder show in the curated Files tree.
-function ensureVisiblePath(deckDir, rel) {
-    return ensureVisibleGlob(deckDir, `${rel}/**`, `${rel}/__probe__`);
-}
-// Add `glob` to the deck's editor.visiblePaths. Only touches a deck that is
-// ALREADY curated (non-empty visiblePaths) -- when visiblePaths is empty
-// everything is visible, and adding a glob would wrongly start hiding things.
-// No-op if an existing glob already covers `probe`, a path the new glob would
-// match. Returns whether it wrote.
-function ensureVisibleGlob(deckDir, glob, probe) {
-    const file = path.join(deckDir, 'castle.json');
-    let data;
-    try {
-        data = JSON.parse(fs.readFileSync(file, 'utf8'));
-    }
-    catch {
-        return false; // no castle.json yet (deck never saved) -> treat as not curated
-    }
-    const visible = data.editor && Array.isArray(data.editor.visiblePaths)
-        ? data.editor.visiblePaths.filter((v) => typeof v === 'string')
-        : null;
-    if (!visible || visible.length === 0)
-        return false; // not curated -> all visible
-    if (visible.includes(glob))
-        return false;
-    if (picomatch(visible)(probe))
-        return false; // already covered
-    visible.push(glob);
-    data.editor.visiblePaths = visible;
-    try {
-        fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function handleFilesMkdir(deckDir, req, res) {
     withMutationPath(deckDir, req, res, (target) => {
         try {
@@ -688,6 +733,18 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         })();
         return true;
     }
+    if (action === 'versions') {
+        handleVersionsList(deckDir, res);
+        return true;
+    }
+    if (action === 'save-version') {
+        handleVersionSave(deckDir, req, res);
+        return true;
+    }
+    if (action === 'restore-version') {
+        handleVersionRestore(deckDir, req, res);
+        return true;
+    }
     if (action === 'list') {
         // `?all=1` returns the unfiltered listing (the "show hidden files & folders"
         // toggle) -- still minus the always-ignored dirs (node_modules/.castle/...),

package/dist/imports.js

@@ -5,7 +5,7 @@ import * as api from './api.js';
 import { runTar } from './save-deck.js';
 import { normalizeDeckPackageJson } from './normalize.js';
 import { getKitsDir } from './localPaths.js';
-import { readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
+import { ensureVisibleGlob, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
 // Adding another deck as a dependency (`castle-web add-import`; removing one is a
 // later command). Deliberately NOT `get-deck`: that one
 // replaces THIS deck's own source from the server (and carries guards for the
@@ -485,7 +485,7 @@ export async function addImportTo(dir, options = {}) {
     const declaredMain = tryReadCastleJson(importDir)?.main;
     let adoptedMain = null;
     if (typeof declaredMain === 'string' && declaredMain.trim()) {
-        const { isPristineBareDeck, adoptImportEntry, writeStarterScene } = await import('./init.js');
+        const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme } = await import('./init.js');
         if (isPristineBareDeck(targetDir)) {
             adoptImportEntry(targetDir, alias, declaredMain.trim());
             adoptedMain = declaredMain.trim();
@@ -500,6 +500,14 @@ export async function addImportTo(dir, options = {}) {
                     console.warn(`Adopted ${alias} but could not write its starter scene: ${e instanceof Error ? e.message : String(e)}`);
                 }
             }
+            // Same for the kit's starter theme.style (skips on its own if the deck
+            // already has one or the kit ships none).
+            try {
+                writeStarterTheme(targetDir, importDir);
+            }
+            catch (e) {
+                console.warn(`Adopted ${alias} but could not write its starter theme.style: ${e instanceof Error ? e.message : String(e)}`);
+            }
         }
     }
     // An import's packages have to be ON DISK, not just named in package.json:
@@ -557,9 +565,41 @@ export async function addImport(dir, options = {}) {
 // `update-import` and the serve-start auto update come through here, so there
 // is one path that replaces an import's files rather than two that have to be
 // kept in step. `log` is how the caller labels the lines it produces.
+// A kit update can introduce deck-level starter content that an existing deck
+// predates. Same additive spirit as syncImportDependencies (which adds a kit's
+// new package deps to the deck's own package.json on update): seed the kit's
+// `theme.style` at the deck root when the deck has none. The engine reads it
+// from the deck root only -- it is the creator's file, like scenes/ -- so
+// without this, decks scaffolded before the kit shipped one would never get
+// it. Never overwrites: a deck that has the file keeps it, whatever the kit
+// ships. Also registers the file in a curated deck's editor.visiblePaths so it
+// shows in the Files tree (the same courtesy mkdir/upload extend).
+function seedKitTheme(deckDir, alias, log) {
+    const importDir = path.join(deckDir, IMPORTS_DIR, alias);
+    // Only kits (imports that declare an entry in castle.json `main`) seed deck
+    // content -- a plain deck import that happens to carry a theme.style of its
+    // own must not set this deck's palette.
+    const main = tryReadCastleJson(importDir)?.main;
+    if (typeof main !== 'string' || !main.trim())
+        return;
+    const src = path.join(importDir, 'theme.style');
+    const dest = path.join(deckDir, 'theme.style');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    try {
+        fs.copyFileSync(src, dest);
+    }
+    catch (e) {
+        console.warn(`Could not seed theme.style from ${alias}: ${e instanceof Error ? e.message : String(e)}`);
+        return;
+    }
+    ensureVisibleGlob(deckDir, 'theme.style', 'theme.style');
+    log(`Seeded theme.style from ${alias} (new in this version; the deck's to edit)`);
+}
 async function applyImportUpdate(deckDir, alias, update, source, log) {
     await placeImport(deckDir, alias, update.deckId, source, update.via);
     log(`Updated ${alias} (${update.from} -> ${source.updatedAt})`);
+    seedKitTheme(deckDir, alias, log);
     // Its own dependencies may have moved too.
     const transitive = await addTransitiveImports(deckDir, alias, importedDeckIds(deckDir));
     for (const t of transitive)