castle-web-cli 0.4.109 → 0.4.111

package/dist/agent-failures.d.ts

@@ -1,5 +1,5 @@
 export type FailureKind = "config" | "limit" | "transient" | "no-work" | "spawn" | "timeout" | "exit";
-export type ConfigReason = "no-key" | "bad-key" | "no-credits" | "unknown-model" | "no-tools" | "no-endpoints" | "flagged" | "context-length";
+export type ConfigReason = "no-key" | "bad-key" | "no-credits" | "model-not-allowed" | "unknown-model" | "no-tools" | "no-endpoints" | "flagged" | "context-length";
 export interface AgentFailure {
     kind: FailureKind;
     reason?: ConfigReason;

package/dist/agent-failures.js

@@ -150,6 +150,8 @@ function configCopy(failure) {
             return "OpenRouter rejected this session's API key. The person running this session needs to check it -- reach out to Castle if you need help.";
         case "no-credits":
             return "OpenRouter is out of credits for this session's key. Reach out to Castle to top it up, or switch to a different model in settings.";
+        case "model-not-allowed":
+            return `${model} isn't available on this Castle account. Pick a different model in settings, or run it on your own API key or login.`;
         case "unknown-model": {
             const hint = failure.suggestion ? ` Did you mean "${failure.suggestion}"?` : "";
             return `I can't use the model this session is set to -- OpenRouter doesn't recognize ${model}.${hint} Pick a different model in settings. If you think that model should work, reach out to Castle.`;

package/dist/agent-prompts.js

@@ -26,6 +26,7 @@ What a deck is: a normal web project served by vite -- index.html plus plain JS/
 
 Hard rules:
 - You NEVER edit files or run state-changing commands. All building and fixing happens through background task agents -- always hand the longer work to them.
+- IMPORTS ARE YOURS, and they are the one exception to the rule above. Run \`castle-web list-decks --kind kits\` (also \`mine\` and \`saved\`) to see what this deck can import, and \`castle-web add-import <deckIdOrUrl>\` to add one -- both directly, not through a task. Do NOT claim you can list or import anything until you have actually run these; do not describe imports you have not looked at. \`list-decks\` prints one deck per line starting with the id \`add-import\` takes, and marks the ones this deck already has. A pasted castle.xyz deck link works in place of an id. Everything else about a deck's files still goes to task agents.
 - You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task, and never read files just to learn conventions already covered by the Quick reference.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
 - The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.

package/dist/agent.js

@@ -92,6 +92,23 @@ function normalizeClaudeModel(value) {
         ? value
         : null;
 }
+// A claude run is spawned with an alias (`--model fable`) but reaches the proxy
+// as a concrete id (`claude-fable-5`), and it is the ids the proxy refuses. This
+// is the one place that knows both, so the model picker and the pre-flight
+// refusal can't disagree about which models a user actually has.
+const CLAUDE_MODEL_ID_PREFIXES = {
+    sonnet: "claude-sonnet-",
+    opus: "claude-opus-",
+    fable: "claude-fable-",
+};
+// Blocked when the two prefixes agree as far as the shorter one goes: the proxy
+// may name a family ("claude-fable-") or one model within it.
+function claudeModelBlocked(model, budget) {
+    const id = CLAUDE_MODEL_ID_PREFIXES[model];
+    if (!id || !budget)
+        return false;
+    return budget.blockedModelPrefixes.some((p) => p.startsWith(id) || id.startsWith(p));
+}
 // Free-form, so validation is just "non-empty, not absurdly long" (guards
 // against a stray huge paste landing in settings.json / the CLI argv).
 const OPENROUTER_MODEL_MAX_LEN = 200;
@@ -1654,14 +1671,29 @@ function anyRoleIsCastlePaid(settings) {
     return (runIsCastlePaid(settings.router, settings.routerClaudeModel, null) ||
         runIsCastlePaid(settings.tasks, settings.tasksClaudeModel, null));
 }
-// The proxy 403s a spent-out user mid-stream, which a CLI surfaces as a generic
-// provider error after a spawn. Asking first turns that into one sentence and
-// no spawn. Fails open on every non-answer: the proxy is the real backstop.
-async function budgetRefusal(backend, claudeModel, orAuth) {
+// The proxy 403s a spent-out user -- or one who asked for a model they don't
+// have -- mid-stream, which a CLI surfaces as a generic provider error after a
+// spawn. Asking first turns either into one sentence and no spawn. Fails open on
+// every non-answer: the proxy is the real backstop.
+//
+// Only the claude aliases are checked, which is exactly what the picker offers.
+// A free-form OpenRouter slug naming a restricted model is left to the proxy:
+// resolving an arbitrary slug to what it bills as is its job, not the editor's.
+async function castleSpendRefusal(backend, claudeModel, orAuth) {
     if (!runIsCastlePaid(backend, claudeModel, orAuth))
         return null;
     const budget = await fetchBudget();
-    if (!budget?.blocked)
+    if (!budget)
+        return null;
+    if (claudeModelBlocked(claudeModel, budget)) {
+        return {
+            kind: "config",
+            reason: "model-not-allowed",
+            detail: `${claudeModel} is not available on this Castle account`,
+            model: claudeModel,
+        };
+    }
+    if (!budget.blocked)
         return null;
     return {
         kind: "limit",
@@ -1673,6 +1705,33 @@ async function budgetRefusal(backend, claudeModel, orAuth) {
 // finished run already refreshes. This is for the spend this serve never sees
 // -- a `claude` invoked straight from the sandbox terminal.
 const USAGE_POLL_MS = 60_000;
+const PICKER_CLAUDE_MODELS = ["sonnet", "opus", "fable"];
+/**
+ * Which of the picker's claude models this editor can't use. Gated on the
+ * ANTHROPIC credential specifically, not on `anyRoleIsCastlePaid` (which draws
+ * the usage bar): those two disagree exactly when one role runs on Castle's
+ * OpenRouter key -- or on Castle's cursor key -- while the user's own Anthropic
+ * key or login covers every claude run. Those runs never reach the proxy, so
+ * nothing about them is Castle's to restrict, and the picker must keep offering
+ * the model. A claude run on a fixed alias always resolves through
+ * resolveAnthropicAuth, so no role's settings enter into this.
+ */
+function blockedClaudeModels(budget) {
+    if (resolveAnthropicAuth().mode !== "proxy")
+        return [];
+    return PICKER_CLAUDE_MODELS.filter((m) => claudeModelBlocked(m, budget));
+}
+function usageFrame(budget) {
+    if (!budget)
+        return null;
+    return {
+        usedMicros: budget.usedMicros,
+        limitMicros: budget.limitMicros,
+        resetAtMs: budget.resetAtMs,
+        blocked: budget.blocked,
+        blockedClaudeModels: blockedClaudeModels(budget),
+    };
+}
 /**
  * The editor's daily-usage feed, pushed over the agent socket exactly the way
  * settings are: the current value rides `hello`, and a change is broadcast.
@@ -1689,7 +1748,7 @@ const USAGE_POLL_MS = 60_000;
 function createUsageFeed(opts) {
     let latest = null;
     async function refreshAsync() {
-        const next = opts.castlePaid() ? await fetchBudget() : null;
+        const next = usageFrame(opts.castlePaid() ? await fetchBudget() : null);
         if (JSON.stringify(next ?? null) === JSON.stringify(latest ?? null))
             return;
         latest = next;
@@ -1725,11 +1784,11 @@ async function runAgentTurn(opts) {
     // Deterministic config errors stop here: nothing spawned, no request issued,
     // nothing billed. Returned (not thrown) because the callers' catch paths
     // emit generic "something went wrong" copy, which would bury the specific
-    // reason this pre-flight exists to produce. A spent-out daily budget is the
-    // same shape of answer, and comes second so a misconfigured run is still
-    // reported as misconfigured.
+    // reason this pre-flight exists to produce. What Castle's spend policy
+    // refuses is the same shape of answer, and comes second so a misconfigured
+    // run is still reported as misconfigured.
     const failure = (await preflightOpenrouterRun({ ...opts, orAuth })) ??
-        (await budgetRefusal(opts.backend, opts.claudeModel, orAuth));
+        (await castleSpendRefusal(opts.backend, opts.claudeModel, orAuth));
     if (failure) {
         return {
             ok: false,

package/dist/api.d.ts

@@ -29,14 +29,33 @@ export interface MeProfile {
     } | null;
 }
 export declare function me(): Promise<MeProfile | null>;
-export interface DeckSummary {
+export interface DeckRow {
     deckId: string;
-    title: string;
-    initialCard?: {
-        cardId: string;
+    title: string | null;
+    creator: {
+        username: string;
     } | null;
+    initialCard: {
+        backgroundImage: {
+            smallUrl: string | null;
+        } | null;
+    } | null;
+    parentDeck: {
+        creator: {
+            username: string;
+        } | null;
+    } | null;
+}
+export declare function myDecks(): Promise<DeckRow[]>;
+export declare function feedDecks(feedId: string, limit: number): Promise<DeckRow[]>;
+export interface PlaylistSummary {
+    playlistId: string;
+    title: string;
 }
-export declare function myDecks(): Promise<DeckSummary[]>;
+export declare function myPlaylists(userId: string, limit: number): Promise<PlaylistSummary[]>;
+export declare function isDeckIdShaped(value: string): boolean;
+export declare function webDeckSourceVersions(deckIds: string[]): Promise<Map<string, string>>;
+export declare function deckRows(deckIds: string[]): Promise<DeckRow[]>;
 export declare function updateCardAndDeckV2(deck: Record<string, unknown>, card: Record<string, unknown>): Promise<{
     deckId: string;
     cardId: string;

package/dist/api.js

@@ -51,20 +51,82 @@ export async function me() {
         return null;
     }
 }
+// Everything an import-picker row shows for one deck: what it is, whose it is,
+// what it looks like, and who it was remixed from. One fragment, so the three
+// list queries below can't drift apart.
+const DECK_ROW_FIELDS = `
+  deckId
+  title
+  creator { username }
+  initialCard { backgroundImage { smallUrl } }
+  parentDeck { creator { username } }
+`;
+// The signed-in user's own decks, in the server's order (newest first).
+// Unbounded -- an account can hold hundreds -- so callers page through it
+// themselves rather than the server guessing a cutoff.
 export async function myDecks() {
-    const data = await graphql(`query {
-    me {
-      decks {
-        deckId
-        title
-        initialCard { cardId }
-      }
-    }
-  }`);
+    const data = await graphql(`query { me { decks { ${DECK_ROW_FIELDS} } } }`);
     handleAPIError(data);
     const meData = data.data?.me;
     return meData?.decks ?? [];
 }
+// Any explore feed, as deck rows. `bookmarks` is the saved-decks feed;
+// `playlist:<id>` is one playlist's decks.
+export async function feedDecks(feedId, limit) {
+    const data = await graphql(`query($feedId: ID!, $limit: Int) {
+       paginateFeed(feedId: $feedId, limit: $limit) { ${DECK_ROW_FIELDS} }
+     }`, { feedId, limit });
+    handleAPIError(data);
+    return pickData(data, 'paginateFeed') ?? [];
+}
+// The user's playlists. Their bookmarks playlist is one of these (id
+// `bookmarks-<userId>`), so a caller listing both has to dedupe.
+export async function myPlaylists(userId, limit) {
+    const data = await graphql(`query($userId: ID!, $limit: Int) {
+       playlistsForUser(userId: $userId, limit: $limit) {
+         items { playlistId title }
+       }
+     }`, { userId, limit });
+    handleAPIError(data);
+    const result = data.data?.playlistsForUser;
+    return (result?.items ?? []).filter((p) => p && typeof p.playlistId === 'string');
+}
+// Deck ids are server-issued, but this one builds a query string out of them,
+// so anything that isn't id-shaped is dropped rather than interpolated.
+const DECK_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export function isDeckIdShaped(value) {
+    return DECK_ID_RE.test(value);
+}
+// Ask the same per-deck question about many decks in ONE request, by aliasing
+// the field once per id. The picker asks these about every candidate row, and a
+// request per deck would be dozens of round trips -- 200 aliases answer in about
+// half a second. Results come back in alias order; a deck the server won't
+// answer for (deleted, not visible) is simply absent.
+async function aliasedDeckQuery(deckIds, field) {
+    const ids = deckIds.filter(isDeckIdShaped);
+    if (ids.length === 0)
+        return [];
+    const aliases = ids.map((id, i) => `a${i}: ${field(id)}`).join('\n');
+    const data = await graphql(`query {\n${aliases}\n}`);
+    return Object.values(data.data ?? {}).filter(Boolean);
+}
+// Which of these decks have web source on the server, and at what version.
+// Having source is what makes a deck importable, so this is the picker's filter.
+export async function webDeckSourceVersions(deckIds) {
+    const sources = await aliasedDeckQuery(deckIds, (id) => `webDeckSource(deckId: "${id}") { deckId updatedAt }`);
+    const found = new Map();
+    for (const source of sources) {
+        if (source.deckId && typeof source.updatedAt === 'string') {
+            found.set(source.deckId, source.updatedAt);
+        }
+    }
+    return found;
+}
+// Named decks as picker rows -- for a deck someone pasted a link to, and for
+// the kits list when it is a fixed set of decks rather than a playlist.
+export async function deckRows(deckIds) {
+    return aliasedDeckQuery(deckIds, (id) => `deck(deckId: "${id}") { ${DECK_ROW_FIELDS} }`);
+}
 export async function updateCardAndDeckV2(deck, card) {
     const data = await graphql(`mutation($deck: DeckInput!, $card: CardInput!) {
        updateCardAndDeckV2(deck: $deck, card: $card) {

package/dist/commonInstructions.d.ts

@@ -1 +1 @@
-export declare const COMMON_INSTRUCTIONS = "## Assets (every deck)\n\n- **Load static assets (drawings, audio, etc.) through the bundler \u2014 never runtime-`fetch` a loose file path.** Use a static `import`, `import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so `fetch('drawings/qb.svg')` looks like it works locally \u2014 but `save-deck` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw `fetch`.\n\n## Touch controls (every deck)\n\n- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch \u2014 direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics \u2014 a game with no directional movement should have no movement controls at all.\n\n## Fit the card (every deck)\n\n- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, `min()`, `clamp()`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports `CARD_RATIO` (= 5 / 7) if you need the exact ratio.\n- **Hand-rolled `<canvas>` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times `devicePixelRatio` (e.g. `canvas.width = rect.width * dpr`), keep the CSS width/height as the layout size, and scale the 2D context (`ctx.scale(dpr, dpr)`) so drawing code stays in CSS units \u2014 re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.\n  - Exception: deliberate pixel art wants a fixed low-resolution backing store with `image-rendering: pixelated` CSS instead \u2014 don't DPR-scale that; the crisp chunky look is the point.\n";
+export declare const COMMON_INSTRUCTIONS = "## Imports are read-only (every deck)\n\n- **`imports/` holds other decks' files and is locked read-only on disk.** Files are mode 0444 and directories 0555, so any shell command that writes, moves, or deletes inside `imports/` fails with `EACCES` / \"Permission denied\" \u2014 that is the lock working, not a broken checkout. Do not `chmod` around it, do not `sudo`, and do not retry the command a different way.\n- **Change an import through the CLI, never the filesystem.** `castle-web add-import <deckIdOrUrl>` adds one and `castle-web update-import [alias]` re-fetches it (`--check` to see if it is outdated, `--revert` to undo). These handle the unlock/relock themselves.\n- **`castle-web list-decks [--kind mine|saved|kits]` is how you find out WHAT can be imported** \u2014 one deck per line, starting with the id `add-import` takes, and marked when this deck already has it. `imports/` only shows what is here already; it is not a catalogue.\n- **To change an imported deck's behavior, copy what you need into this deck and edit the copy**, then reference your copy. Editing in place is not available, and an `update-import` would overwrite it anyway.\n- **Deleting the deck directory itself needs the lock released first** (`chmod -R u+w` on the deck dir) \u2014 that is the one legitimate reason to touch the modes, and only for a directory being thrown away.\n\n## Assets (every deck)\n\n- **Load static assets (drawings, audio, etc.) through the bundler \u2014 never runtime-`fetch` a loose file path.** Use a static `import`, `import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so `fetch('drawings/qb.svg')` looks like it works locally \u2014 but `save-deck` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw `fetch`.\n\n## Touch controls (every deck)\n\n- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch \u2014 direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics \u2014 a game with no directional movement should have no movement controls at all.\n\n## Fit the card (every deck)\n\n- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, `min()`, `clamp()`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports `CARD_RATIO` (= 5 / 7) if you need the exact ratio.\n- **Hand-rolled `<canvas>` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times `devicePixelRatio` (e.g. `canvas.width = rect.width * dpr`), keep the CSS width/height as the layout size, and scale the 2D context (`ctx.scale(dpr, dpr)`) so drawing code stays in CSS units \u2014 re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.\n  - Exception: deliberate pixel art wants a fixed low-resolution backing store with `image-rendering: pixelated` CSS instead \u2014 don't DPR-scale that; the crisp chunky look is the point.\n";

package/dist/commonInstructions.js

@@ -2,7 +2,15 @@
 // deck's CLAUDE.md, regardless of kit (or no kit). Single source of truth —
 // edit here, not in the kits. Keep it truly kit-agnostic; kit-specific rules
 // (e.g. Space being reserved for play/stop) live in each kit's own CLAUDE.md.
-export const COMMON_INSTRUCTIONS = `## Assets (every deck)
+export const COMMON_INSTRUCTIONS = `## Imports are read-only (every deck)
+
+- **\`imports/\` holds other decks' files and is locked read-only on disk.** Files are mode 0444 and directories 0555, so any shell command that writes, moves, or deletes inside \`imports/\` fails with \`EACCES\` / "Permission denied" — that is the lock working, not a broken checkout. Do not \`chmod\` around it, do not \`sudo\`, and do not retry the command a different way.
+- **Change an import through the CLI, never the filesystem.** \`castle-web add-import <deckIdOrUrl>\` adds one and \`castle-web update-import [alias]\` re-fetches it (\`--check\` to see if it is outdated, \`--revert\` to undo). These handle the unlock/relock themselves.
+- **\`castle-web list-decks [--kind mine|saved|kits]\` is how you find out WHAT can be imported** — one deck per line, starting with the id \`add-import\` takes, and marked when this deck already has it. \`imports/\` only shows what is here already; it is not a catalogue.
+- **To change an imported deck's behavior, copy what you need into this deck and edit the copy**, then reference your copy. Editing in place is not available, and an \`update-import\` would overwrite it anyway.
+- **Deleting the deck directory itself needs the lock released first** (\`chmod -R u+w\` on the deck dir) — that is the one legitimate reason to touch the modes, and only for a directory being thrown away.
+
+## Assets (every deck)
 
 - **Load static assets (drawings, audio, etc.) through the bundler — never runtime-\`fetch\` a loose file path.** Use a static \`import\`, \`import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })\`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so \`fetch('drawings/qb.svg')\` looks like it works locally — but \`save-deck\` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw \`fetch\`.
 

package/dist/httpJson.d.ts

@@ -0,0 +1,4 @@
+import * as http from "http";
+export declare function sendJson(res: http.ServerResponse, status: number, body: unknown): void;
+export declare function readRequestBody(req: http.IncomingMessage): Promise<string>;
+export declare function errorMessage(err: unknown): string;

package/dist/httpJson.js

@@ -0,0 +1,21 @@
+// The two things every JSON endpoint on the serve needs: read a request body,
+// write a response. Shared by the files API and the import API so they answer
+// in the same shape (and so neither grows its own copy).
+export function sendJson(res, status, body) {
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(JSON.stringify(body));
+}
+export function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/ide.d.ts

@@ -3,6 +3,8 @@ import { Duplex } from "stream";
 import { type RawData } from "ws";
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
+export declare const FAVICON_FILES: string[];
+export declare const FAVICON_LINK_TAGS: string;
 export declare const FILES_API_PREFIX = "/__castle/files/";
 export declare function rawDataToString(data: RawData): string;
 export interface IdeServer {

package/dist/ide.js

@@ -15,6 +15,8 @@ import headlessPkg from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 import { WebSocketServer } from "ws";
 import { IMPORTS_DIR, importStatuses, updateImport } from "./imports.js";
+import { IMPORT_API_PREFIX, handleImportApi } from "./importBrowse.js";
+import { readRequestBody, sendJson } from "./httpJson.js";
 import { envForUserShell, installCliShims } from "./byo-auth.js";
 const HeadlessTerminal = headlessPkg.Terminal;
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -33,12 +35,19 @@ const SHELL_MIME = {
     ".json": "application/json; charset=utf-8",
     ".svg": "image/svg+xml",
     ".png": "image/png",
+    ".ico": "image/x-icon",
     ".jpg": "image/jpeg",
     ".woff": "font/woff",
     ".woff2": "font/woff2",
     ".ttf": "font/ttf",
     ".map": "application/json; charset=utf-8",
 };
+// Does the deck serve this root-level file itself? Vite serves both the deck
+// root and its `public/` dir at `/`, so either location counts.
+function deckHasFile(deckDir, name) {
+    return (fs.existsSync(path.join(deckDir, name)) ||
+        fs.existsSync(path.join(deckDir, "public", name)));
+}
 // Serve a file from the bundled shell dir, guarding against path traversal.
 function serveShellFile(res, asset) {
     const rel = path.normalize(asset).replace(/^(\.\.[/\\])+/, "");
@@ -65,6 +74,22 @@ function serveShellFile(res, asset) {
 // upgrade handler on Vite's HTTP server).
 export const IDE_ASSET_PREFIX = "/__castle/ide/";
 export const PTY_WS_PATH = "/__castle/pty";
+// Castle's favicon (the same files castle.xyz serves), shipped in the shell
+// bundle and also served from the origin root so every page under the serve
+// gets it -- the shell at `/`, the deck page at `/index.html`, and the
+// browser's implicit `/favicon.ico` probe. The deck wins if it ships its own.
+export const FAVICON_FILES = [
+    "favicon.ico",
+    "favicon-16x16.png",
+    "favicon-32x32.png",
+];
+// `<link rel="icon">` tags for the root-served favicons, injected into the deck
+// page (see serve.ts). The shell's own tags live in `src/shell/index.html`.
+export const FAVICON_LINK_TAGS = [
+    '<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />',
+    '<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />',
+    '<link rel="icon" href="/favicon.ico" sizes="any" />',
+].join("\n    ");
 // Builtin Files + code-editor panels talk to the deck through these endpoints
 // (the shell no longer routes file browsing / code editing through the kit
 // iframe). `list`/`read`/`write` operate on files within the deck dir;
@@ -300,21 +325,6 @@ function filterImportedFiles(deckDir, imported) {
     }
     return out;
 }
-function sendJson(res, status, body) {
-    res.writeHead(status, {
-        "content-type": "application/json; charset=utf-8",
-        "cache-control": "no-store",
-    });
-    res.end(JSON.stringify(body));
-}
-function readRequestBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on("data", (c) => chunks.push(c));
-        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-        req.on("error", reject);
-    });
-}
 function withJsonBody(req, res, handler) {
     void (async () => {
         let body;
@@ -782,12 +792,21 @@ export function createIdeServer(opts) {
         // `/` -> the shell's index.html; `/__castle/ide/<asset>` -> bundle assets.
         if (reqPath === "/")
             return serveShellFile(res, "index.html");
+        // Root-served favicons, unless the deck ships its own (then fall through
+        // to Vite, which serves the deck's file).
+        const favicon = FAVICON_FILES.find((name) => reqPath === `/${name}`);
+        if (favicon && !deckHasFile(deckDir, favicon)) {
+            return serveShellFile(res, favicon);
+        }
         if (reqPath.startsWith(IDE_ASSET_PREFIX)) {
             return serveShellFile(res, reqPath.slice(IDE_ASSET_PREFIX.length) || "index.html");
         }
         if (reqPath.startsWith(FILES_API_PREFIX)) {
             return handleFilesApi(deckDir, req, res, reqPath);
         }
+        if (reqPath.startsWith(IMPORT_API_PREFIX)) {
+            return handleImportApi(deckDir, req, res, reqPath);
+        }
         return false;
     }
     function shutdown() {

package/dist/importBrowse.d.ts

@@ -0,0 +1,21 @@
+import * as http from "http";
+export declare const IMPORT_API_PREFIX = "/__castle/import/";
+export interface ImportCandidate {
+    deckId: string;
+    title: string;
+    creator: string | null;
+    imageUrl: string | null;
+    parentCreator: string | null;
+    hasSource: boolean;
+    imported: boolean;
+}
+export interface ImportList {
+    signedIn: boolean;
+    decks: ImportCandidate[];
+    truncated: boolean;
+}
+export type ImportTab = "mine" | "saved" | "kits";
+export declare function listImportable(deckDir: string, tab: ImportTab): Promise<ImportList>;
+export declare function resolveDeckRef(deckDir: string, ref: string): Promise<ImportCandidate>;
+export declare function sourceFileCount(deckId: string): Promise<number | null>;
+export declare function handleImportApi(deckDir: string, req: http.IncomingMessage, res: http.ServerResponse, reqPath: string): boolean;