castle-web-cli 0.4.123 → 0.4.125

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/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,144 @@
+// 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;
+// A ceiling on the whole capture, because this runs inside somebody's "Push to
+// Castle". The steps below are individually bounded, but a browser is a big
+// dependency and this is a cover -- nothing here is worth making a creator
+// watch a spinner for. Whatever is unfinished at this point is abandoned and
+// the save proceeds without a cover.
+const CAPTURE_BUDGET_MS = 60_000;
+// 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) {
+    // A manager we made is a manager we must close. `withBrowser` deliberately
+    // leaves the browser RUNNING so the next call reuses it -- right for the
+    // agent, which holds one manager for its whole session, and fatal here:
+    // `save-deck` is one-shot, and a live browser connection keeps node's event
+    // loop alive, so the command finishes its work and then never exits. The
+    // caller waits out its own timeout on a process that is done. (The manager's
+    // idle timer is unref'd precisely so it isn't what holds a one-shot open --
+    // the browser connection is.)
+    //
+    // A manager passed IN belongs to the caller; closing it would kill a browser
+    // they are still using.
+    const owned = !opts.manager;
+    const manager = opts.manager ?? createPlaytestBrowserManager();
+    try {
+        const outcome = await withBudget(manager.withBrowser((browser) => shoot(browser, opts.serveUrl), {
+            onProgress: opts.onProgress,
+        }), CAPTURE_BUDGET_MS);
+        if (!outcome)
+            return { ok: false, error: `capture gave up after ${CAPTURE_BUDGET_MS / 1000}s` };
+        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 };
+    }
+    finally {
+        if (owned)
+            await manager.shutdown().catch(() => undefined);
+    }
+}
+// Resolve with `work`, or with null if the budget runs out first. The loser is
+// abandoned rather than cancelled -- the shutdown in the caller's `finally` is
+// what actually stops the browser it was using.
+function withBudget(work, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(null), ms);
+        timer.unref?.();
+        void work.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+    });
+}
+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.js

@@ -16,6 +16,7 @@ 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';
@@ -137,10 +138,17 @@ 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';
 // Re-exported so `save-deck` and anything else that already asks the serve for
 // the cover's name keeps working.
@@ -437,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 {

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)

package/dist/index.js

@@ -9,7 +9,7 @@ import { addImport, updateImport } from './imports.js';
 import { listDecks } from './list-decks.js';
 import { getCliVersion, init } from './init.js';
 import { install } from './install.js';
-import { connectWS, savePreviewImage, takeScreenshot } from './preview.js';
+import { connectWS, takeScreenshot } from './preview.js';
 import { listVersions, restoreVersion, saveVersion, showVersion } from './versions.js';
 const args = process.argv.slice(2);
 const command = args[0];
@@ -91,7 +91,6 @@ function usage() {
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
-  castle-web save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private]
   castle-web get-deck [dir] [--deck-id ID] [--force]   (replaces the source if the deck is already there)
   castle-web list-decks [dir] [--kind mine|saved|kits]   (decks this one could import; ids are what add-import takes)
@@ -242,13 +241,6 @@ async function main() {
             console.log(`Saved ${outFile}`);
             return;
         }
-        case 'save-preview-image': {
-            const dir = findPositionalDir();
-            const wsPort = getWsPort(dir);
-            const noRestart = args.includes('--no-restart');
-            await savePreviewImage(dir, wsPort, noRestart);
-            return;
-        }
         case 'login':
             await login();
             break;

package/dist/init.d.ts

@@ -9,6 +9,7 @@ export declare function isPristineBareDeck(dir: string): boolean;
 export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
 export declare function getCliVersion(): string;
 export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
+export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;

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.13';
+const PUBLISHED_SDK_VERSION = '0.4.14';
 // 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';
@@ -281,6 +281,19 @@ export function writeStarterScene(projectDir, kitDir, alias) {
     fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
     writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), scene ? rewrite(scene) : { name: 'Main', actors: [] });
 }
+// A kit may ship a starter `theme.style` (deck-level styling, e.g. the color
+// palette). Like the starter scene, it is deck content: the engine reads it
+// from the DECK root, and it is the creator's to edit -- so it gets seeded once
+// at scaffold time rather than living read-only in the import. Copied verbatim
+// (its values are palette ids/hexes, never kit file paths, so no ref
+// rewriting). Exported for the same two scaffold paths as writeStarterScene.
+export function writeStarterTheme(projectDir, kitDir) {
+    const src = path.join(kitDir, 'theme.style');
+    const dest = path.join(projectDir, 'theme.style');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    fs.copyFileSync(src, dest);
+}
 function makeImportedKitClaudeMd(alias) {
     return `# Castle deck
 
@@ -354,6 +367,7 @@ function scaffoldFromKitImport(kit, projectDir) {
     const title = typeof kitConfig.title === 'string' ? kitConfig.title : kit;
     writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
     writeStarterScene(projectDir, kitDir, alias);
+    writeStarterTheme(projectDir, kitDir);
     // The deck's own castle.json: the kit's editor config (panel layout, file
     // filters) as a starting point -- it is the deck's to edit from here -- plus
     // the import pin.

package/dist/preview.d.ts

@@ -1,4 +1,3 @@
 import type { WebSocket as WSClient } from 'ws';
 export declare function connectWS(wsPort: number): Promise<WSClient>;
 export declare function takeScreenshot(ws: WSClient): Promise<string>;
-export declare function savePreviewImage(dir: string, wsPort: number, noRestart?: boolean): Promise<void>;

package/dist/preview.js

@@ -1,7 +1,3 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as api from './api.js';
-import * as config from './config.js';
 export async function connectWS(wsPort) {
     const { default: WS } = await import('ws');
     return new Promise((resolve, reject) => {
@@ -45,57 +41,3 @@ export function takeScreenshot(ws) {
         ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
     });
 }
-function waitForRestart(ws) {
-    return new Promise((resolve) => {
-        ws.send(JSON.stringify({ type: 'restart' }));
-        setTimeout(resolve, 2000);
-    });
-}
-// The shared declaration (castleJson.ts) rather than a local copy of the two
-// fields this file reads, so it can't drift from what the rest of the CLI
-// believes castle.json contains.
-function readCastleJson(projectDir) {
-    const castleJsonPath = path.join(projectDir, 'castle.json');
-    if (!fs.existsSync(castleJsonPath))
-        return null;
-    return JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
-}
-async function captureAndUpload(projectDir, ws, castleJson) {
-    // A deck has no cardId until its first save, and the cover IS that card's
-    // background -- so there is nothing to set it on yet. Both callers reach here
-    // right after a save, so this is the never-saved edge, not the normal path.
-    // Reported back so a caller doesn't record a cover that was never set.
-    const { cardId } = castleJson;
-    if (!cardId) {
-        ws.close();
-        console.log('Preview skipped: save the deck first.');
-        return false;
-    }
-    const base64 = await takeScreenshot(ws);
-    ws.close();
-    fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
-    console.log('Saved preview.png');
-    const file = await api.uploadBase64(base64, 'preview.png');
-    await api.updateCardCustomBackgroundImage(cardId, file.fileId);
-    console.log('Set deck preview image.');
-    return true;
-}
-export async function savePreviewImage(dir, wsPort, noRestart = false) {
-    const projectDir = path.resolve(dir);
-    const castleJson = readCastleJson(projectDir);
-    if (!castleJson) {
-        console.error('No castle.json found. Save the deck first.');
-        process.exit(1);
-    }
-    if (!config.getToken()) {
-        console.error('Not logged in. Run `castle-web login` first.');
-        process.exit(1);
-    }
-    const ws = await connectWS(wsPort);
-    if (!noRestart)
-        await waitForRestart(ws);
-    // Asking for this by name is choosing a cover, so it goes to the card's
-    // CUSTOM slot -- the one that takes precedence over the cover a save
-    // publishes. Clearing it is an editor action (Deck settings -> Clear cover).
-    await captureAndUpload(projectDir, ws, castleJson);
-}

package/dist/save-deck.js

@@ -79,8 +79,59 @@ async function uploadSource(projectDir, deckId) {
 //
 // Never fatal: a deck that saves but whose cover upload failed is a deck that
 // saved. Losing the push over a thumbnail would be the wrong trade.
+// The deck's own serve, if one is running -- the URL a headless cover capture
+// loads. No serve means no deck to photograph, which is a normal state (a save
+// from a script), not an error.
+function runningServeUrl(projectDir) {
+    try {
+        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
+        const port = JSON.parse(raw).port;
+        return typeof port === 'number' ? `http://localhost:${port}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Photograph the running deck with a real browser, into a scratch file.
+//
+// This OUTRANKS the editor's `preview.png`, and deliberately: both are the
+// AUTOMATIC cover (a creator's hand-picked one lives in the card's custom slot
+// and outranks both), so the question is only which automatic capture is better
+// -- and the in-page one silently drops a WebGL canvas that lacks
+// `preserveDrawingBuffer`, plus anything using `filter`/`clip-path`/`mask`. A
+// browser compositing its own frame has no such list.
+//
+// `preview.png` does have one real advantage -- it is whatever the creator last
+// had on screen, where this is a cold load -- so it stays the fallback. But a
+// cover that is missing the game beats a cover of the opening seconds only if
+// you never look at it, and nobody looks at an unattended capture. Writing to a
+// scratch file rather than over `preview.png` keeps that fallback intact.
+async function captureAutomaticCover(projectDir) {
+    const serveUrl = runningServeUrl(projectDir);
+    if (!serveUrl)
+        return null;
+    const outPath = path.join(projectDir, '.castle', 'headless-cover.png');
+    const { captureCoverHeadless } = await import('./headlessCover.js');
+    const result = await captureCoverHeadless({
+        serveUrl,
+        outPath,
+        onProgress: (message) => console.log(message),
+    });
+    if (!result.ok) {
+        // Never fatal, same as the upload below: a deck that saved without a cover
+        // is a deck that saved.
+        console.log(`Cover capture skipped: ${result.error}`);
+        return null;
+    }
+    return outPath;
+}
 async function uploadLocalCover(projectDir) {
-    const coverPath = path.join(projectDir, COVER_FILE);
+    const captured = await captureAutomaticCover(projectDir);
+    const coverPath = captured ?? path.join(projectDir, COVER_FILE);
+    if (captured)
+        console.log('Captured a cover from the running deck.');
+    else if (fs.existsSync(coverPath))
+        console.log('Using the cover captured in the editor.');
     if (!fs.existsSync(coverPath))
         return null;
     try {

package/dist/serve.js

@@ -239,6 +239,22 @@ export async function serve(dir, options = {}) {
             console.warn(`auto-update: skipped -- ${e instanceof Error ? e.message : String(e)}`);
         });
     }
+    // Start pulling the headless browser now, in the background.
+    //
+    // `save-deck` photographs the deck with it to make the deck's cover, and the
+    // binary is a ~250MB one-time download. Left lazy, that download lands inside
+    // the creator's first "Push to Castle" -- the one moment they are watching a
+    // spinner and least want an unexplained wait. A serve means someone is editing
+    // a deck they will probably push, so this is the cheapest place to get ahead
+    // of it.
+    //
+    // Fire-and-forget and single-flight: it shares one download with the agent's
+    // playtest tool, so this is free when that already pulled it, and every
+    // failure is swallowed -- the capture re-detects and reports properly at the
+    // point it actually matters.
+    void import('./native/playtest-browser.js')
+        .then((m) => m.createPlaytestBrowserManager().prewarm())
+        .catch(() => undefined);
     // Close stdin when not attached to a TTY so the process can be cleanly
     // backgrounded with `&` (otherwise stdin reads can block or hold the parent).
     if (!process.stdin.isTTY) {