castle-web-cli 0.4.110 → 0.4.111

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/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;

package/dist/importBrowse.js

@@ -0,0 +1,240 @@
+// The editor's Import picker, server side: `/__castle/import/*` on the serve.
+// Answers "which decks could this person import" and then does the import.
+//
+// It runs the GraphQL with the CLI's own login (`config.getToken()`), which is
+// what a local serve has. In the cloud the shell will instead ask its castle-www
+// host over postMessage, so the sandbox never holds the token -- that path is
+// deliberately not built yet, and this one is what the local editor uses either
+// way.
+//
+// Nothing here goes through the deck iframe or the kit: the Files panel that
+// opens this picker is a builtin shell panel, and it has to keep working on a
+// `--kit none` deck that ships no editor app at all.
+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 * as config from "./config.js";
+import { runTar } from "./save-deck.js";
+import { readCastleJson } from "./castleJson.js";
+import { ImportError, addImportTo, importedDeckIds, parseDeckRef } from "./imports.js";
+import { errorMessage, readRequestBody, sendJson } from "./httpJson.js";
+export const IMPORT_API_PREFIX = "/__castle/import/";
+// Rows per list, and how many decks we are willing to ask the source question
+// about to fill one. An account can hold hundreds of decks and only some are
+// web decks, so the scan has to look past the first fifty -- but not forever.
+const LIST_LIMIT = 50;
+const SCAN_CAP = 200;
+const SOURCE_CHUNK = 100;
+// Playlists read for the Saved list. Flattened together with bookmarks, so a
+// handful is already more decks than the list shows.
+const PLAYLIST_CAP = 10;
+// The bookmarks feed already covers this playlist; listing both would just
+// duplicate it.
+const BOOKMARKS_PLAYLIST_PREFIX = "bookmarks-";
+// The kits list, hardcoded. A playlist can't hold it: playlist feeds drop
+// unlisted decks, and a kit is published unlisted. Adding a kit means shipping
+// an update to this list.
+const KIT_DECK_IDS = [
+    "ckRZGFW4iPrx", // physics-2d
+];
+// Listing is several server round trips, and the picker is opened, closed and
+// reopened while someone decides. Cached briefly so that costs once.
+const LIST_TTL_MS = 60_000;
+const listCache = new Map();
+function asTab(value) {
+    return value === "saved" || value === "kits" ? value : "mine";
+}
+function toCandidate(row, hasSource) {
+    return {
+        deckId: row.deckId,
+        title: row.title?.trim() ? row.title.trim() : "Untitled",
+        creator: row.creator?.username ?? null,
+        imageUrl: row.initialCard?.backgroundImage?.smallUrl ?? null,
+        parentCreator: row.parentDeck?.creator?.username ?? null,
+        hasSource,
+        imported: false,
+    };
+}
+// Which of these the deck already has. Stamped on the way OUT rather than
+// baked into the cached list: the pins change while the picker is open (an
+// import from here, an `add-import` in the terminal), and re-reading one file
+// is cheaper than throwing the list away.
+function stampImported(deckDir, decks) {
+    const already = importedDeckIds(deckDir);
+    return decks.map((deck) => ({ ...deck, imported: already.has(deck.deckId) }));
+}
+// First occurrence of each deck wins, and the deck being edited never appears:
+// a deck can't import itself, so offering it is offering an error.
+function dedupe(rows, currentDeckId) {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        if (!row?.deckId || row.deckId === currentDeckId || seen.has(row.deckId))
+            continue;
+        seen.add(row.deckId);
+        out.push(row);
+    }
+    return out;
+}
+// Keep the decks that have source on the server -- having source IS being
+// importable -- taking them in the order they arrived until the list is full.
+// Asks in chunks so one bad batch doesn't cost the whole scan.
+async function filterImportable(rows) {
+    const decks = [];
+    let scanned = 0;
+    while (scanned < rows.length && scanned < SCAN_CAP && decks.length < LIST_LIMIT) {
+        const chunk = rows.slice(scanned, scanned + SOURCE_CHUNK);
+        scanned += chunk.length;
+        const versions = await api.webDeckSourceVersions(chunk.map((r) => r.deckId));
+        for (const row of chunk) {
+            if (decks.length >= LIST_LIMIT)
+                break;
+            if (versions.has(row.deckId))
+                decks.push(toCandidate(row, true));
+        }
+    }
+    return { signedIn: true, decks, truncated: scanned < rows.length };
+}
+// Bookmarks plus the user's playlists, flattened. Both are "decks I kept", and
+// which of the two something landed in is not a distinction worth a tab.
+async function savedRows() {
+    const userId = config.getUserId();
+    const bookmarks = await api.feedDecks("bookmarks", LIST_LIMIT);
+    if (!userId)
+        return bookmarks;
+    const playlists = (await api.myPlaylists(userId, PLAYLIST_CAP * 2))
+        .filter((p) => !p.playlistId.startsWith(BOOKMARKS_PLAYLIST_PREFIX))
+        .slice(0, PLAYLIST_CAP);
+    const lists = await Promise.all(playlists.map((p) => api.feedDecks(`playlist:${p.playlistId}`, LIST_LIMIT).catch(() => [])));
+    return [bookmarks, ...lists].flat();
+}
+async function tabRows(tab) {
+    if (tab === "saved")
+        return savedRows();
+    if (tab === "kits")
+        return api.deckRows(KIT_DECK_IDS);
+    return api.myDecks();
+}
+const EMPTY_LIST = { signedIn: false, decks: [], truncated: false };
+export async function listImportable(deckDir, tab) {
+    if (!config.getToken())
+        return EMPTY_LIST;
+    const key = `${deckDir}|${tab}`;
+    const cached = listCache.get(key);
+    const value = cached && Date.now() - cached.at < LIST_TTL_MS ? cached.value : null;
+    if (value)
+        return { ...value, decks: stampImported(deckDir, value.decks) };
+    const currentDeckId = readCastleJson(deckDir)?.deckId ?? null;
+    const fresh = await filterImportable(dedupe(await tabRows(tab), currentDeckId));
+    listCache.set(key, { at: Date.now(), value: fresh });
+    return { ...fresh, decks: stampImported(deckDir, fresh.decks) };
+}
+// A deck someone pasted a link (or an id) to. Unlike the lists, this one does
+// NOT hide a deck with no source -- naming a specific deck and getting nothing
+// back says less than naming it and being told it was never saved.
+export async function resolveDeckRef(deckDir, ref) {
+    const deckId = parseDeckRef(ref);
+    if (!deckId) {
+        throw new ImportError("bad-deck-ref", `Not a deck id or a castle deck link: ${ref}`);
+    }
+    if (readCastleJson(deckDir)?.deckId === deckId) {
+        throw new ImportError("self-import", `That is this deck -- a deck can't import itself.`);
+    }
+    const [rows, source] = await Promise.all([
+        api.deckRows([deckId]),
+        api.webDeckSource(deckId).catch(() => null),
+    ]);
+    const row = rows[0];
+    if (!row)
+        throw new ImportError("bad-deck-ref", `No deck ${deckId} on the server.`);
+    return stampImported(deckDir, [toCandidate(row, source !== null)])[0];
+}
+// How many files a deck's source holds. Not on any list query, so it is counted
+// from the archive itself -- which means downloading it, which is why the picker
+// asks only about the one deck someone has selected rather than every row.
+// Keyed by version, so re-selecting a row is free until its deck is saved again.
+const fileCountCache = new Map();
+export async function sourceFileCount(deckId) {
+    if (!api.isDeckIdShaped(deckId))
+        return null;
+    const source = await api.webDeckSource(deckId).catch(() => null);
+    if (!source)
+        return null;
+    const key = `${deckId}@${source.updatedAt}`;
+    const cached = fileCountCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const tmpFile = path.join(os.tmpdir(), `castle-import-count-${nanoid(8)}.tar.gz`);
+    try {
+        const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(30000) });
+        if (!res.ok)
+            return null;
+        fs.writeFileSync(tmpFile, Buffer.from(await res.arrayBuffer()));
+        const listing = await runTar(["-tzf", tmpFile], { capture: true });
+        const count = listing.split("\n").filter((line) => line && !line.endsWith("/")).length;
+        fileCountCache.set(key, count);
+        return count;
+    }
+    catch {
+        return null; // an unreadable archive just means no count to show
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            /* nothing to clean */
+        }
+    }
+}
+// An ImportError is the caller's problem (a bad link, this deck, a deck that
+// was never saved), so it comes back as a 400 with its code -- the picker shows
+// a different thing for each. Anything else is ours: a 500 with the message.
+function sendResult(res, work) {
+    void work()
+        .then((body) => sendJson(res, 200, body))
+        .catch((err) => {
+        if (err instanceof ImportError)
+            return sendJson(res, 400, { error: err.message, code: err.code });
+        sendJson(res, 500, { error: errorMessage(err) });
+    });
+}
+export function handleImportApi(deckDir, req, res, reqPath) {
+    const action = reqPath.slice(IMPORT_API_PREFIX.length);
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (action === "list") {
+        sendResult(res, () => listImportable(deckDir, asTab(url.searchParams.get("tab"))));
+        return true;
+    }
+    if (action === "resolve") {
+        const ref = url.searchParams.get("ref") ?? "";
+        sendResult(res, async () => ({ deck: await resolveDeckRef(deckDir, ref) }));
+        return true;
+    }
+    if (action === "files") {
+        const deckId = url.searchParams.get("deckId") ?? "";
+        sendResult(res, async () => ({ fileCount: await sourceFileCount(deckId) }));
+        return true;
+    }
+    if (action === "add") {
+        sendResult(res, async () => {
+            let body;
+            try {
+                body = JSON.parse(await readRequestBody(req));
+            }
+            catch {
+                throw new ImportError("no-deck-ref", "Invalid JSON body.");
+            }
+            const deckRef = typeof body.deckRef === "string" ? body.deckRef : "";
+            const result = await addImportTo(deckDir, { deckRef });
+            // The lists said which decks were importable; one of them just stopped
+            // being a candidate (or changed version), so the cached answers are stale.
+            listCache.clear();
+            return result;
+        });
+        return true;
+    }
+    return (sendJson(res, 404, { error: `Unknown import action: ${action}` }), true);
+}

package/dist/imports.d.ts

@@ -1,4 +1,10 @@
 export declare const IMPORTS_DIR = "imports";
+export type ImportErrorCode = 'no-deck-ref' | 'bad-deck-ref' | 'no-such-dir' | 'self-import' | 'no-source' | 'bad-alias';
+export declare class ImportError extends Error {
+    code: ImportErrorCode;
+    constructor(code: ImportErrorCode, message: string);
+}
+export declare function parseDeckRef(raw: string): string | null;
 export declare function lockImportTree(dir: string): void;
 export declare function syncImportDependencies(deckDir: string): string[];
 export declare function restoreMissingImports(deckDir: string): Promise<string[]>;
@@ -11,8 +17,22 @@ export interface ImportStatus {
     via?: string;
 }
 export declare function importStatuses(deckDir: string): Promise<ImportStatus[]>;
+export declare function importedDeckIds(deckDir: string): Set<string>;
+export interface AddImportResult {
+    deckId: string;
+    alias: string;
+    replaced: boolean;
+    /** Aliases pulled in because the imported deck depends on them. */
+    transitive: string[];
+    /** `name@range (from alias)` entries merged into the deck's package.json. */
+    dependencies: string[];
+}
+export declare function addImportTo(dir: string, options?: {
+    deckRef?: string;
+    alias?: string;
+}): Promise<AddImportResult>;
 export declare function addImport(dir: string, options?: {
-    deckId?: string;
+    deckRef?: string;
     alias?: string;
 }): Promise<void>;
 export declare function updateImport(dir: string, options?: {