castle-web-cli 0.4.169 → 0.4.171

package/dist/headlessCover.js

@@ -54,7 +54,7 @@ const CARD_SELECTOR = "#castle-card, [data-castle-card]";
 export async function captureCoverHeadless(opts) {
     const remoteGrant = contentGrantFromBrowserUrl(opts.serveUrl);
     if (remoteGrant) {
-        return captureCoverRemote(remoteGrant, opts.outPath);
+        return captureCoverRemote(remoteGrant, opts.outPath, opts.remoteBudgetMs ?? REMOTE_CAPTURE_BUDGET_MS, opts.signal);
     }
     // 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
@@ -94,8 +94,9 @@ export async function captureCoverHeadless(opts) {
             await manager.shutdown().catch(() => undefined);
     }
 }
-async function captureCoverRemote(contentGrant, outPath) {
-    const signal = AbortSignal.timeout(REMOTE_CAPTURE_BUDGET_MS);
+async function captureCoverRemote(contentGrant, outPath, budgetMs, callerSignal) {
+    const budgetSignal = AbortSignal.timeout(Math.max(1, budgetMs));
+    const signal = callerSignal ? AbortSignal.any([budgetSignal, callerSignal]) : budgetSignal;
     try {
         const result = await api.runBrowserJob(contentGrant, { kind: 'cover' }, signal);
         const pngBase64 = result.pngBase64;
@@ -117,10 +118,11 @@ async function captureCoverRemote(contentGrant, outPath) {
         if (signal.aborted) {
             return {
                 ok: false,
-                error: `remote cover gave up after ${REMOTE_CAPTURE_BUDGET_MS / 1000}s`,
+                outcome: 'timed_out',
+                error: `remote cover gave up after ${budgetMs / 1000}s`,
             };
         }
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        return { ok: false, outcome: 'capture_failed', error: error instanceof Error ? error.message : String(error) };
     }
 }
 // Resolve with `work`, or with null if the budget runs out first. The loser is

package/dist/ide.d.ts

@@ -9,6 +9,16 @@ export declare const FAVICON_LINK_TAGS: string;
 export declare const FILES_API_PREFIX = "/__castle/files/";
 export declare const COVER_API_PATH = "/__castle/cover";
 export { COVER_FILE };
+export declare function resolveDeckPath(deckDir: string, requestedPath: unknown, opts?: {
+    mutation?: boolean;
+}): {
+    ok: true;
+    abs: string;
+    rel: string;
+} | {
+    ok: false;
+    error: string;
+};
 export interface IdeServer {
     /** Serve the IDE page + its static assets. Returns true if it handled the request. */
     handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse, reqPath: string): boolean;

package/dist/ide.js

@@ -1,7 +1,7 @@
-// IDE backend for `castle-web serve`: serves the shell UI (a dockview workspace
-// bundled from `src/shell/` into `dist/shell/`) and runs the terminal panel's
-// PTY. The deck loads in an iframe inside the shell; an agent CLI can be driven
-// in the terminal panel right next to the live deck.
+// IDE backend for `castle-web serve`: serves the shell UI (the flow
+// workbench bundled from `src/shell/` into `dist/shell/`) and runs the
+// terminal panel's PTY. The deck loads in an iframe inside the shell; an
+// agent CLI can be driven in the terminal panel right next to the live deck.
 //
 // Backend pattern ported from castle-cli's `ide` branch: @lydell/node-pty for
 // the PTY, an @xterm/headless screen + @xterm/addon-serialize so a reconnecting
@@ -226,7 +226,7 @@ function isImportPath(rel) {
 // writeProjectFile guards so the builtin editor can't escape the deck. Callers
 // that are about to CHANGE the file pass `mutation`, which additionally refuses
 // anything a dependency owns.
-function resolveDeckPath(deckDir, requestedPath, opts = {}) {
+export function resolveDeckPath(deckDir, requestedPath, opts = {}) {
     if (typeof requestedPath !== 'string' || requestedPath.trim() === '') {
         return { ok: false, error: 'Missing file path.' };
     }
@@ -482,6 +482,15 @@ function handleVersionRestore(deckDir, req, res, restart) {
         }
     });
 }
+// A curated deck hides anything not covered by editor.visiblePaths. Writes,
+// moves, and uploads already mkdir parent dirs; they also have to register the
+// dest folder or a new path lands on disk and stays invisible in Files.
+function ensureFileParentVisible(deckDir, rel) {
+    const dir = path.posix.dirname(rel);
+    if (dir === '.')
+        return ensureVisibleGlob(deckDir, rel, rel);
+    return ensureVisiblePath(deckDir, dir);
+}
 function handleFilesWrite(deckDir, req, res) {
     withMutationPath(deckDir, req, res, (target, body) => {
         if (typeof body.contents !== 'string') {
@@ -490,7 +499,8 @@ function handleFilesWrite(deckDir, req, res) {
         try {
             fs.mkdirSync(path.dirname(target.abs), { recursive: true });
             fs.writeFileSync(target.abs, body.contents, 'utf8');
-            sendJson(res, 200, { ok: true, path: target.rel });
+            const visiblePathAdded = ensureFileParentVisible(deckDir, target.rel);
+            sendJson(res, 200, { ok: true, path: target.rel, visiblePathAdded });
         }
         catch (err) {
             sendFailure(res, 'write', target.rel, err);
@@ -571,10 +581,7 @@ function handleFilesUpload(deckDir, req, res) {
         catch (err) {
             return sendFailure(res, 'upload', target.rel, err);
         }
-        const dir = path.posix.dirname(target.rel);
-        const visiblePathAdded = dir === '.'
-            ? ensureVisibleGlob(deckDir, target.rel, target.rel)
-            : ensureVisiblePath(deckDir, dir);
+        const visiblePathAdded = ensureFileParentVisible(deckDir, target.rel);
         sendJson(res, 200, { ok: true, path: target.rel, visiblePathAdded });
     }, (err) => {
         if (err instanceof RangeError)
@@ -703,7 +710,8 @@ function handleFilesRename(deckDir, req, res) {
         try {
             fs.mkdirSync(path.dirname(to.abs), { recursive: true });
             fs.renameSync(from.abs, to.abs);
-            sendJson(res, 200, { ok: true, path: to.rel });
+            const visiblePathAdded = ensureFileParentVisible(deckDir, to.rel);
+            sendJson(res, 200, { ok: true, path: to.rel, visiblePathAdded });
         }
         catch (err) {
             sendFailure(res, 'rename', from.rel, err);

package/dist/index.js

@@ -62,6 +62,10 @@ function readPositionals() {
     }
     return out;
 }
+function readImportFileArgs() {
+    const positionals = readPositionals();
+    return { deckDir: path.resolve(positionals[1] ?? '.'), relPosix: positionals[0] ?? '' };
+}
 function getFlagValue(flag) {
     const idx = args.indexOf(flag);
     return idx >= 0 ? args[idx + 1] : undefined;
@@ -89,7 +93,7 @@ function getServeSocketPort(dir) {
 }
 function usage() {
     console.log(`Usage:
-  castle-web init <dir> [--kit NAME]   (kits: physics-2d (default), physics-3d, none)
+  castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME]   (kits: physics-2d (default), physics-3d, none)
   castle-web init <dir> --remix <deckId> [--deck-id ID] [--card-id ID]   (starts from a published deck instead of a kit)
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
@@ -130,7 +134,7 @@ async function main() {
         case 'init': {
             const dir = findPositionalDir();
             if (dir === '.') {
-                console.error('Usage: castle-web init <dir> [--kit NAME | --remix DECK_ID]');
+                console.error('Usage: castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME | --remix DECK_ID]');
                 process.exit(1);
             }
             const kit = getFlagValue('--kit');
@@ -177,8 +181,8 @@ async function main() {
         }
         case 'fork-import-file': {
             // `castle-web fork-import-file <imports/...> [dir]`
-            const positionals = readPositionals();
-            const result = forkImportFile(path.resolve(positionals[1] ?? '.'), positionals[0] ?? '');
+            const { deckDir, relPosix } = readImportFileArgs();
+            const result = forkImportFile(deckDir, relPosix);
             if (!result.ok) {
                 console.error(result.error);
                 process.exit(1);
@@ -187,8 +191,8 @@ async function main() {
             break;
         }
         case 'revert-import-file': {
-            const positionals = readPositionals();
-            const result = revertImportFile(path.resolve(positionals[1] ?? '.'), positionals[0] ?? '');
+            const { deckDir, relPosix } = readImportFileArgs();
+            const result = revertImportFile(deckDir, relPosix);
             if (!result.ok) {
                 console.error(result.error);
                 process.exit(1);

package/dist/init.d.ts

@@ -19,7 +19,7 @@ export declare function init(dir: string, opts?: {
     serve?: boolean;
     /** Remix this published deck instead of starting from a kit. */
     remixOf?: string;
-    /** The identity the server already minted for a remix. */
+    /** The identity the server already minted for this new deck. */
     deckId?: string;
     cardId?: string;
 }): Promise<void>;

package/dist/init.js

@@ -55,7 +55,7 @@ if (!(await mountEditorRoute())) startGame(initCard());
 // 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.26';
+const PUBLISHED_SDK_VERSION = '0.4.28';
 // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
 // face can ship without a cli release, and a caret range means an existing
 // deck's next install picks it up. Nothing here has to move when it does.
@@ -651,6 +651,16 @@ export async function init(dir, opts = {}) {
     else {
         scaffoldFromKitImport(kit, projectDir);
     }
+    if (!opts.remixOf && (opts.deckId || opts.cardId)) {
+        // Apply server identity before install/version 1, so retries and a restore
+        // to the original scaffold cannot allocate a second deck or card.
+        const configPath = path.join(projectDir, 'castle.json');
+        writeJsonFile(configPath, {
+            ...readJsonFile(configPath),
+            ...(opts.deckId ? { deckId: opts.deckId } : {}),
+            ...(opts.cardId ? { cardId: opts.cardId } : {}),
+        });
+    }
     if (!opts.remixOf) {
         console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     }

package/dist/remix.js

@@ -1,9 +1,7 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-import { nanoid } from 'nanoid';
 import * as api from './api.js';
-import { runTar } from './save-deck.js';
+import { downloadSourceArchive, runTar } from './save-deck.js';
 // Scaffolding a deck from another published deck, for `init --remix`.
 // Dropped from the copied castle.json. `autoUpdateWhenImported` is the parent's
 // promise to ITS importers, which a remix hasn't made.
@@ -34,17 +32,7 @@ export async function fetchParentSource(parentDeckId) {
         console.error(`Deck ${parentDeckId} has no saved source to remix. Only decks saved by the web CLI can be remixed.`);
         process.exit(1);
     }
-    console.log(`Fetching ${source.archiveUrl}`);
-    const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(60000) });
-    if (!res.ok) {
-        throw new Error(`Archive fetch failed: HTTP ${res.status}`);
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    console.log(`Archive: ${(buf.length / 1024).toFixed(1)}KB (updated ${source.updatedAt})`);
-    // Read and untarred out of, never moved out of: in a sandbox the deck is on a
-    // different filesystem from tmp, and a rename across that is EXDEV.
-    const archivePath = path.join(os.tmpdir(), `castle-remix-${nanoid(8)}.tar.gz`);
-    fs.writeFileSync(archivePath, buf);
+    const archivePath = await downloadSourceArchive(source, 'castle-remix');
     // `./castle.json`, because archiveSource packs with `-C <dir> .`.
     const text = await runTar(['-xzOf', archivePath, './castle.json'], { capture: true });
     return { archivePath, castleJson: parseJson(text) };

package/dist/save-deck.d.ts

@@ -1,10 +1,13 @@
+import * as api from './api.js';
 export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
 export declare const SAVE_STAGE_TELEMETRY_PREFIX = "CASTLE_SAVE_TELEMETRY ";
+export declare const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = "CASTLE_SAVE_COVER_SELECTION ";
 export type SaveStage = 'bundle' | 'cover' | 'scene_upload_config' | 'scene_upload' | 'content_publish' | 'server_publish' | 'source_archive' | 'source_upload_config' | 'source_upload' | 'source_commit';
 export declare function runTar(args: string[], opts?: {
     capture?: boolean;
 }): Promise<string>;
 export declare function archiveSource(projectDir: string): Promise<Buffer>;
+export declare function downloadSourceArchive(source: api.WebDeckSource, namePrefix: string): Promise<string>;
 export type SaveVisibility = 'unlisted' | 'private';
 export interface SaveDeckOptions {
     title?: string;

package/dist/save-deck.js

@@ -7,7 +7,8 @@ import * as api from './api.js';
 import * as config from './config.js';
 import { bundleProject } from './bundle.js';
 import { resolveServerConfig } from './castleJson.js';
-import { COVER_FILE } from './ide.js';
+import { selectSaveCover } from './saveCover.js';
+import { COVER_FILE } from './localPaths.js';
 import { buildServerBundle } from './serverBundle.js';
 // `imports/` is derived state like node_modules: a dependency's files belong to
 // the deck that published them, and castle.json's import pins are enough to fetch
@@ -20,6 +21,7 @@ export const SOURCE_ARCHIVE_EXCLUDES = ['node_modules', 'dist', '.castle', '.git
 // adding machine output to interactive local saves. Old CLIs ignore the env, so releases remain
 // independently deployable.
 export const SAVE_STAGE_TELEMETRY_PREFIX = 'CASTLE_SAVE_TELEMETRY ';
+export const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = 'CASTLE_SAVE_COVER_SELECTION ';
 function emitSaveStage(stage, outcome, startedAtMs, fields = {}) {
     if (process.env.CASTLE_SAVE_STAGE_TELEMETRY !== '1')
         return;
@@ -90,6 +92,21 @@ export async function archiveSource(projectDir) {
         }
     }
 }
+// Written to tmp and read or untarred out of there, never moved out: in a sandbox
+// the deck is on a different filesystem from tmp, and a rename across that is EXDEV.
+// The caller owns the file it gets back.
+export async function downloadSourceArchive(source, namePrefix) {
+    console.log(`Fetching ${source.archiveUrl}`);
+    const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(60000) });
+    if (!res.ok) {
+        throw new Error(`Archive fetch failed: HTTP ${res.status}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    console.log(`Archive: ${(buf.length / 1024).toFixed(1)}KB (updated ${source.updatedAt})`);
+    const file = path.join(os.tmpdir(), `${namePrefix}-${nanoid(8)}.tar.gz`);
+    fs.writeFileSync(file, buf);
+    return file;
+}
 async function uploadPresignedFile(uploadConfig, file, contentType, timeoutMs, label) {
     const formData = new FormData();
     formData.append('Content-Type', contentType);
@@ -166,83 +183,24 @@ async function publishServerBundle(projectDir, deckId) {
     writePublishedServerBundleState(projectDir, { deckId, sha256: bundle.sha256 });
     console.log(`Server bundle published${saved ? ` as ${saved.version}` : ''} (sha256 ${bundle.sha256}).`);
 }
-// Publish the deck's local cover, if it has one, and return the file id for the
-// card. The editor writes `preview.png` as you play (see the serve's cover
-// endpoint); this is the moment it becomes public.
-//
-// 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.
-async function runningServeUrl(projectDir) {
-    try {
-        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
-        const parsed = JSON.parse(raw);
-        const port = parsed.port;
-        if (process.env.CASTLE_SANDBOX_ID && typeof port === 'number') {
-            try {
-                const response = await fetch(`http://localhost:${port}/__castle/browser-content-grant`, { signal: AbortSignal.timeout(2_000) });
-                const body = (await response.json());
-                if (response.ok && typeof body.url === 'string')
-                    return body.url;
-            }
-            catch {
-                // Fall through to the existing best-effort local capture path.
-            }
-        }
-        if (typeof parsed.contentPlayUrl === 'string')
-            return parsed.contentPlayUrl;
-        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 = await 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) {
     try {
-        const captured = await captureAutomaticCover(projectDir);
-        const coverPath = captured ?? path.join(projectDir, COVER_FILE);
-        if (captured)
+        const selected = await selectSaveCover(projectDir, { onProgress: (message) => console.log(message) });
+        if (process.env.CASTLE_SAVE_STAGE_TELEMETRY === '1') {
+            console.log(`${SAVE_COVER_SELECTION_TELEMETRY_PREFIX}${JSON.stringify({
+                event: 'castle_web_save_cover_selected',
+                outcome: selected.outcome,
+                capture_outcome: selected.captureOutcome,
+                duration_ms: selected.durationMs,
+            })}`);
+        }
+        if (selected.outcome === 'remote' || selected.outcome === 'local_browser')
             console.log('Captured a cover from the running deck.');
-        else if (fs.existsSync(coverPath))
+        else if (selected.outcome === 'editor')
             console.log('Using the cover captured in the editor.');
-        if (!fs.existsSync(coverPath))
+        if (!selected.path)
             return null;
-        const base64 = fs.readFileSync(coverPath).toString('base64');
+        const base64 = fs.readFileSync(selected.path).toString('base64');
         const file = await api.uploadBase64(base64, COVER_FILE);
         return file?.fileId ?? null;
     }
@@ -411,6 +369,15 @@ export async function saveDeck(dir, opts = {}) {
         else if (code === 'DECK_INVALID_PERMISSIONS') {
             console.error('You do not have permission to save this deck.');
         }
+        else if (code === 'DECK_DELETED') {
+            // The deck this workspace points at was deleted somewhere else -- the app,
+            // the cloud editor, another machine. The server refuses the write rather
+            // than publishing into a deck nobody can reach, so say what happened and
+            // what recovers the code, which is still here and untouched.
+            console.error(`This deck was deleted (${castleJson?.deckId}), so it can no longer be saved to.\n` +
+                'Your files are unchanged. To publish them as a new deck, remove the ' +
+                '"deckId" and "cardId" fields from castle.json and save again.');
+        }
         else {
             throw e;
         }

package/dist/saveCover.d.ts

@@ -0,0 +1,18 @@
+export type SaveCoverOutcome = 'remote' | 'local_browser' | 'editor' | 'none';
+export interface SaveCoverSelection {
+    outcome: SaveCoverOutcome;
+    captureOutcome: 'succeeded' | 'timed_out' | 'capture_failed' | 'not_attempted';
+    path?: string;
+    durationMs: number;
+}
+export interface SaveCoverOptions {
+    totalBudgetMs?: number;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+    onProgress?: (message: string) => void;
+}
+export declare function runningServeUrl(projectDir: string, options?: Pick<SaveCoverOptions, 'fetch'> & {
+    signal?: AbortSignal;
+}): Promise<string | null>;
+/** Select exactly the automatic cover that save-deck would upload, without uploading it. */
+export declare function selectSaveCover(projectDir: string, options?: SaveCoverOptions): Promise<SaveCoverSelection>;

package/dist/saveCover.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import { COVER_FILE } from './localPaths.js';
+import { contentGrantFromBrowserUrl } from './native/playtest-remote.js';
+export async function runningServeUrl(projectDir, options = {}) {
+    try {
+        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        const port = parsed.port;
+        if (process.env.CASTLE_SANDBOX_ID && typeof port === 'number') {
+            try {
+                const response = await (options.fetch ?? globalThis.fetch)(`http://localhost:${port}/__castle/browser-content-grant`, { signal: options.signal ? AbortSignal.any([AbortSignal.timeout(2_000), options.signal]) : AbortSignal.timeout(2_000) });
+                const body = (await response.json());
+                if (response.ok && typeof body.url === 'string')
+                    return body.url;
+            }
+            catch {
+                // The serve metadata below remains a valid local fallback.
+            }
+        }
+        if (typeof parsed.contentPlayUrl === 'string')
+            return parsed.contentPlayUrl;
+        return typeof port === 'number' ? `http://localhost:${port}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Select exactly the automatic cover that save-deck would upload, without uploading it. */
+export async function selectSaveCover(projectDir, options = {}) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const totalBudgetMs = options.totalBudgetMs ?? 15_000;
+    const deadlineMs = startedAt + totalBudgetMs;
+    const signal = AbortSignal.timeout(Math.max(1, totalBudgetMs));
+    const serveUrl = await runningServeUrl(projectDir, { ...options, signal });
+    const outPath = path.join(projectDir, '.castle', 'headless-cover.png');
+    const isRemote = Boolean(serveUrl && contentGrantFromBrowserUrl(serveUrl));
+    let captureOutcome = 'not_attempted';
+    // If cloud grant discovery consumed the caller budget, do not reinterpret its localhost
+    // metadata fallback as permission to start a new 60-second local-browser attempt.
+    if (serveUrl && !signal.aborted) {
+        const { captureCoverHeadless } = await import('./headlessCover.js');
+        const result = await captureCoverHeadless({
+            serveUrl,
+            outPath,
+            onProgress: options.onProgress,
+            ...(isRemote ? { remoteBudgetMs: Math.max(1, deadlineMs - now()), signal } : {}),
+        });
+        captureOutcome = result.outcome ?? (result.ok ? 'succeeded' : 'capture_failed');
+        if (result.ok && fs.existsSync(outPath)) {
+            return { outcome: isRemote ? 'remote' : 'local_browser', captureOutcome: 'succeeded', path: outPath, durationMs: Math.max(0, now() - startedAt) };
+        }
+    }
+    if (process.env.CASTLE_SANDBOX_ID && signal.aborted)
+        captureOutcome = 'timed_out';
+    const localPath = path.join(projectDir, COVER_FILE);
+    return fs.existsSync(localPath)
+        ? { outcome: 'editor', captureOutcome, path: localPath, durationMs: Math.max(0, now() - startedAt) }
+        : { outcome: 'none', captureOutcome, durationMs: Math.max(0, now() - startedAt) };
+}

package/dist/serve.js

@@ -762,16 +762,25 @@ export async function serve(dir, options = {}) {
             : options.host === '::'
                 ? '::1'
                 : options.host;
-    // Content origins follow --host: a serve bound to a tailnet/LAN address is
-    // being viewed from another device, where loopback is that device's own.
-    const contentBindHost = !options.host ||
+    // Content proxies must listen where a remote browser can reach them. Binding
+    // the shell to 0.0.0.0 / :: means a phone on LAN/tailnet opens the shell; its
+    // content iframes need those same interfaces — the phone's 127.0.0.1 is itself.
+    const contentListenHost = options.host === '0.0.0.0' || options.host === '::'
+        ? options.host
+        : !options.host || options.host === 'localhost'
+            ? '127.0.0.1'
+            : options.host;
+    // Playtest / serve.json still advertise loopback: Chromium on this machine
+    // cannot navigate to 0.0.0.0, and same-machine Safari keeps the prior origins.
+    // Remote browsers get the Host they used via ServeSecurity.contentOrigins.
+    const contentAdvertiseHost = !options.host ||
         options.host === 'localhost' ||
         options.host === '0.0.0.0' ||
         options.host === '::'
         ? '127.0.0.1'
         : options.host;
-    security.setLocalContentHost(contentBindHost);
-    const localContentServers = await startLocalContentServers(contentBindHost, upstreamHost, port, security, new Set([port]));
+    security.setLocalContentHost(contentAdvertiseHost);
+    const localContentServers = await startLocalContentServers(contentListenHost, upstreamHost, port, security, new Set([port]));
     process.on('exit', () => {
         for (const server of localContentServers)
             server.close();
@@ -1318,6 +1327,10 @@ function trustedBridgeContentOrigin(security, request, role, value) {
         return null;
     if (origin === security.localContentOrigin(role) || origin === request.headers.origin)
         return origin;
+    // Phone / LAN / tailnet: contentOrigins remints against the shell Host header.
+    const expected = security.contentOrigins(request)[role === 'edit' ? 'editOrigin' : 'playOrigin'];
+    if (origin === expected)
+        return origin;
     const url = new URL(origin);
     const synthetic = {
         headers: { ...request.headers, host: url.host },

package/dist/serveSecurity.d.ts

@@ -50,7 +50,17 @@ export declare class ServeSecurity {
         editOrigin: string;
         playOrigin: string;
     };
-    localContentOrigin(role: ContentRole): string;
+    /**
+     * Origin a browser should use for a local content role.
+     *
+     * When the shell was opened via a LAN / tailnet hostname (or any non-loopback
+     * Host the serve already accepted), content iframes must use that same host —
+     * `127.0.0.1` is the *phone's* loopback, not the machine running the serve.
+     * Loopback / wildcard request hosts keep the advertised localContentHost
+     * (playtest and same-machine Safari).
+     */
+    localContentOrigin(role: ContentRole, requestHost?: string): string;
+    private contentHostForBrowser;
     /** A short-lived play URL for one shared-browser admission attempt. */
     browserContentOrigin(role?: ContentRole): string | null;
     localContentProxyHeaders(role: ContentRole): Record<string, string>;

package/dist/serveSecurity.js

@@ -41,6 +41,20 @@ function hostWithoutPort(host) {
         return host.slice(0, host.indexOf(']') + 1).toLowerCase();
     return host.split(':')[0].toLowerCase();
 }
+/** Strip brackets so callers can compare / classify the bare hostname. */
+function bareHostname(host) {
+    const h = hostWithoutPort(host).toLowerCase();
+    return h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
+}
+/** IPv6 literals need brackets in an origin URL. */
+function formatHostForOrigin(host) {
+    const bare = bareHostname(host);
+    return bare.includes(':') ? `[${bare}]` : bare;
+}
+function isLoopbackHostname(host) {
+    const bare = bareHostname(host);
+    return bare === 'localhost' || bare === '127.0.0.1' || bare === '::1';
+}
 function requestOrigin(req) {
     const forwarded = req.headers['x-forwarded-proto'];
     const protocol = typeof forwarded === 'string' ? forwarded.split(',')[0] : 'http';
@@ -80,7 +94,8 @@ export class ServeSecurity {
             throw new Error('edit and play content ports must be distinct');
         this.localContentPorts = ports;
     }
-    // The host a browser should use to reach deck content; see contentBindHost.
+    // Loopback host advertised to same-machine consumers (playtest, serve.json).
+    // Remote browsers get the Host they used; see localContentOrigin(role, host).
     setLocalContentHost(host) {
         this.localContentHost = host;
     }
@@ -276,17 +291,36 @@ window.fetch=function(input,init){
             // Safari on macOS 15 asks DNS to resolve `*.localhost`, where it fails.
             // Dedicated loopback ports are still distinct browser origins and need no DNS.
             if (!cloud || !contentDomain)
-                return this.localContentOrigin(role);
+                return this.localContentOrigin(role, host);
             const label = this.mintContentLabel(role, sandboxId, expiresAtSeconds);
             return `https://${label}.${contentDomain}`;
         };
         return { editOrigin: originFor('edit'), playOrigin: originFor('play') };
     }
-    localContentOrigin(role) {
+    /**
+     * Origin a browser should use for a local content role.
+     *
+     * When the shell was opened via a LAN / tailnet hostname (or any non-loopback
+     * Host the serve already accepted), content iframes must use that same host —
+     * `127.0.0.1` is the *phone's* loopback, not the machine running the serve.
+     * Loopback / wildcard request hosts keep the advertised localContentHost
+     * (playtest and same-machine Safari).
+     */
+    localContentOrigin(role, requestHost) {
         const port = this.localContentPorts?.[role];
         if (!port)
             throw new Error('local content ports are not configured');
-        return `http://${this.localContentHost}:${port}`;
+        const host = this.contentHostForBrowser(requestHost);
+        return `http://${formatHostForOrigin(host)}:${port}`;
+    }
+    contentHostForBrowser(requestHost) {
+        if (!requestHost)
+            return this.localContentHost;
+        const bare = bareHostname(requestHost);
+        if (!bare || bare === '0.0.0.0' || bare === '::' || isLoopbackHostname(bare)) {
+            return this.localContentHost;
+        }
+        return bare;
     }
     /** A short-lived play URL for one shared-browser admission attempt. */
     browserContentOrigin(role = 'play') {