pindeck 3.0.0-beta.3 → 3.2.0-beta.1

package/front.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+/* PinDeck: the front, which is what `pindeck` starts.
+
+   pindeck [deck-dir | deck.html] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <dir>]
+   pindeck login [deck-dir | deck.html]
+
+   One port and one login for several decks. Each deck that is open runs its own deck server (server.mjs, on
+   a private port of 127.0.0.1 with a token of its own) and is reached here as /d/<deck key>/: the front logs
+   the browser in, then passes each request on with that deck's token. A deck starts when it is first asked
+   for (from the editor's deck menu, or a bookmark), so its chat, Claude session and undo stay while it is
+   open, and Claude can go on working in one deck while you edit another. A deck with no editor open for
+   PINDECK_IDLE_MS (30 minutes) is closed; it opens again when asked for.
+
+   The menu lists the decks in the start folder and the asset roots, and in their folders one level down
+   (lib/deck-list.mjs). Only those can be opened: there is no free path entry. */
+
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { isSupportedPlatform, detectCapabilities, publicCapabilities, parsePort } from "./lib/capabilities.mjs";
+import { deckTarget, homeDir, homeWarning } from "./lib/deck-target.mjs";
+import { goodHost, LOGIN_PAGE, createLogin, openOnEnter } from "./lib/login.mjs";
+import { listDecks } from "./lib/deck-list.mjs";
+import { assetRoots } from "./lib/asset-roots.mjs";
+import { registerServer, printLogin } from "./lib/servers.mjs";
+import { USAGE } from "./lib/usage.mjs";
+
+const EDITOR_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.join(EDITOR_DIR, "server.mjs");
+const HOME_DIR = homeDir();
+const IDLE_MS = Number(process.env.PINDECK_IDLE_MS) || 30 * 60000;
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) { console.log(USAGE); process.exit(0); }
+const opt = (name, dflt) => { const i = argv.indexOf(name); return i >= 0 ? argv.splice(i, 2)[1] : dflt; };
+const portArg = opt("--port", process.env.PORT || 5180);
+const PASS = [];   // what every deck server gets: the backend and the asset roots
+for (const name of ["--provider", "--model"]) { const v = opt(name); if (v !== undefined) PASS.push(name, v); }
+const assetArgs = [];
+for (let a; (a = opt("--asset-root")) !== undefined;) { assetArgs.push(a); PASS.push("--asset-root", a); }
+let PORT = parsePort(portArg);   // the port actually bound once listening (--port 0 picks a free one)
+if (PORT === null) { console.error(`Invalid port "${portArg}": use a number from 1 to 65535.\n\n${USAGE}`); process.exit(2); }
+if (!isSupportedPlatform(process.platform)) {
+  const { showPlatformNotice } = await import("./lib/platform-notice.mjs");
+  await showPlatformNotice(PORT);
+  process.exit(0);
+}
+
+/* pindeck login: a new one-time login link from the PinDeck that serves the deck (see lib/servers.mjs), asked
+   with the token in its server file (readable only by this user). With a deck, the link opens that deck. */
+if (argv[0] === "login") await printLogin(HOME_DIR, argv[1] ? deckTarget(argv[1]) : null);
+
+/* The start deck, and the folders whose decks the menu offers. A folder without index.html opens the list
+   of its decks; if it has none, its deck server says why, as for any deck that cannot be opened. */
+const homeNote = homeWarning(HOME_DIR);
+if (homeNote) console.warn(homeNote);
+const START = deckTarget(argv[0] || process.cwd());
+if (process.env.CLAUDE_MODEL)   // PinDeck 2 read it
+  console.warn(`CLAUDE_MODEL is not used by PinDeck 3: choose the model in the editor's model menu, or start with --model ${process.env.CLAUDE_MODEL}.`);
+let fileConfig = {};
+try { fileConfig = JSON.parse(fs.readFileSync(path.join(HOME_DIR, "config.json"), "utf8")); } catch {}
+if (!fileConfig || typeof fileConfig !== "object" || Array.isArray(fileConfig)) fileConfig = {};   // the deck server says why
+// a missing asset root stops the start, before anything is written; one that goes later lists nothing
+const givenRoots = assetRoots(assetArgs, fileConfig);
+if (givenRoots.missing.length) { console.error(`Asset root ${givenRoots.missing[0]} is not a folder.\n\n${USAGE}`); process.exit(2); }
+const ROOTS = [...new Set([START.dir, ...givenRoots.roots])];
+const decksNow = () => listDecks(ROOTS);
+const chooser = !START.named && !fs.existsSync(path.join(START.dir, START.file)) && decksNow().some((d) => !d.problem);
+
+const TOKEN = crypto.randomBytes(16).toString("hex");
+let ORIGIN = `http://127.0.0.1:${PORT}`;   // set again from the bound port once listening
+const { loginCode, loginUrl, authed, login } = createLogin({ token: TOKEN, port: () => PORT, origin: () => ORIGIN });
+const CAPS = detectCapabilities();
+
+/* ---- Deck servers -------------------------------------------------------------------------------- */
+const decks = new Map();   // key -> { key, dir, file, label, proc, url, token, ready, exited, sse, last }
+const labelOf = (d) => (d.file === "index.html" ? path.basename(d.dir) : d.file);
+let quitting = false;
+
+/* Its output goes to this terminal, each line marked with the deck. hold(l): keep the line back for now */
+function forward(stream, label, to, keep, hold = () => false) {
+  let rest = "";
+  const put = (l) => { keep?.(l + "\n"); if (!hold(l)) to.write(`[${label}] ${l}\n`); };
+  stream.on("data", (chunk) => {
+    const lines = (rest + chunk).split("\n");
+    rest = lines.pop();
+    lines.forEach(put);
+  });
+  stream.on("end", () => { if (rest) put(rest); });
+}
+
+/* The deck's server, started once: the promise resolves when it listens, or rejects with what it printed.
+   The start deck's complaints are printed by the front as they are, like those of PinDeck before the front. */
+function openDeck(entry, start = false) {
+  const known = decks.get(entry.key);
+  if (known) return known.ready;
+  const d = { key: entry.key, dir: entry.dir, file: entry.file, label: labelOf(entry), sse: 0, last: Date.now() };
+  decks.set(d.key, d);
+  // its own process group: Ctrl+C reaches the front only, which then ends every deck once
+  d.proc = spawn(process.execPath, [SERVER, entry.file === "index.html" ? entry.dir : path.join(entry.dir, entry.file),
+    "--port", "0", ...PASS], { env: { ...process.env, PINDECK_FRONT: "1", PINDECK_FRONT_URL: ORIGIN },
+    stdio: ["ignore", "pipe", "pipe", "ipc"], detached: true });
+  // what it says before it listens: its reason if it stops; the start deck's warnings once it runs
+  let said = "";
+  const held = [];
+  forward(d.proc.stdout, d.label, process.stdout);
+  forward(d.proc.stderr, d.label, process.stderr, (l) => { if (!d.url) said = (said + l).slice(-20000); },
+    (l) => start && !d.url && held.push(l));
+  d.exited = new Promise((r) => d.proc.once("exit", r));
+  d.ready = new Promise((resolve, reject) => {
+    d.proc.on("message", (m) => {
+      if (!m?.ready) return;
+      Object.assign(d, { url: m.ready.url, token: m.ready.token });
+      for (const l of held.splice(0)) console.error(l);   // a start that went ahead anyway, as PinDeck said it before the front
+      if (!start) console.log(`[${d.label}] opened: ${path.join(d.dir, d.file)}`);
+      resolve(d);
+    });
+    d.proc.once("exit", (code, signal) => {
+      if (decks.get(d.key) === d) decks.delete(d.key);
+      if (d.url && !quitting) console.log(`[${d.label}] closed`);
+      reject(Object.assign(new Error(said.trim() || `The deck server stopped (${code ?? signal}).`), { exitCode: code || 1 }));
+    });
+  });
+  d.ready.catch(() => {});
+  return d.ready;
+}
+
+function stopDeck(d) {
+  try { d.proc.kill("SIGTERM"); } catch {}
+}
+
+/* A deck with no editor open (no event stream) and nothing to do for IDLE_MS is closed */
+setInterval(async () => {
+  for (const d of decks.values()) {
+    if (!d.url || d.sse > 0 || Date.now() - d.last < IDLE_MS) continue;
+    try {
+      const res = await fetch(`${d.url}/api/status`, { headers: { "x-editor-token": d.token } });
+      const st = await res.json();
+      if (st.busy || d.sse > 0 || Date.now() - d.last < IDLE_MS) continue;
+    } catch { continue; }
+    console.log(`[${d.label}] no editor open for ${Math.round(IDLE_MS / 60000)} min: closing it (it opens again when asked for)`);
+    stopDeck(d);
+  }
+}, Math.min(60000, IDLE_MS / 2)).unref();
+
+/* The request, without the front's cookie and with the deck's token, to the deck's server; the answer
+   streamed back (event streams, media ranges and large uploads included) */
+function proxy(req, res, d, rest, anonymous = false) {
+  d.last = Date.now();
+  const headers = { ...req.headers, host: new URL(d.url).host, ...(anonymous ? {} : { "x-editor-token": d.token }) };
+  if (anonymous) delete headers["x-editor-token"];
+  delete headers.cookie;
+  delete headers.origin;   // checked here against the front's address; the deck server checks its own
+  const up = http.request(d.url + rest, { method: req.method, headers }, (r) => {
+    res.writeHead(r.statusCode, r.headers);
+    r.pipe(res);
+    // the deck server stopped mid-answer (an event stream, say): end ours too, or the browser waits forever
+    r.on("aborted", () => res.destroy());
+    r.on("error", () => res.destroy());
+  });
+  up.on("error", () => { if (!res.headersSent) page(res, 502, "This deck stopped answering", "Reload the page to open it again."); else res.destroy(); });
+  if (rest.split("?")[0] === "/api/events") {
+    d.sse++;
+    res.on("close", () => { d.sse--; d.last = Date.now(); });
+  }
+  res.on("close", () => { if (!res.writableFinished) up.destroy(); });
+  req.pipe(up);
+}
+
+/* ---- One event stream per browser -------------------------------------------------------------------
+   Browsers open at most 6 connections to one host and port, and each editor tab held one open for its deck's
+   events: a sixth tab never loaded. The tabs of a browser share one stream through a shared worker
+   (public/events-worker.js): GET /events?stream=<id> holds it, POST /events/subscribe adds a tab's deck (the
+   front opens that deck's events on its server and passes them on, marked with the tab) or removes it. If a
+   deck server stops, the deck is opened again and the tab gets its state afresh (its "hello"). */
+const streams = new Map();   // stream id -> { res, tabs: Map(tab -> { stop() }) }
+function eventStream(res, id) {
+  streams.get(id)?.res.end();   // the worker reconnected: its old stream is done
+  const st = { res, tabs: new Map() };
+  streams.set(id, st);
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+  res.write("event: ready\ndata: {}\n\n");
+  const ping = setInterval(() => res.write(": ping\n\n"), 20000);
+  res.on("close", () => {
+    clearInterval(ping);
+    if (streams.get(id) === st) streams.delete(id);
+    for (const t of st.tabs.values()) t.stop();
+  });
+}
+function follow(st, tab, key) {
+  let stopped = false, up = null, tries = 0;
+  const send = (type, raw) => {
+    if (!stopped && !st.res.writableEnded) st.res.write(`event: deck\ndata: {"tab":${JSON.stringify(tab)},"type":${JSON.stringify(type)},"data":${raw}}\n\n`);
+  };
+  const retry = () => {
+    if (stopped || quitting) return;
+    if (++tries > 20) return send("gone", JSON.stringify({ error: "The deck stopped answering. Reload the page." }));
+    setTimeout(connect, Math.min(5000, 200 * tries));
+  };
+  async function connect() {
+    if (stopped || quitting) return;
+    let d = decks.get(key);
+    try {
+      if (!d) {
+        const entry = START.key === key && !chooser ? { key, dir: START.dir, file: START.file } : decksNow().find((e) => e.key === key);
+        if (!entry || entry.problem) return send("gone", JSON.stringify({ error: entry?.problem || "This deck is not in the deck folder or an asset root (any more)." }));
+        d = entry;
+      }
+      d = await openDeck(d);
+    } catch (e) { return send("gone", JSON.stringify({ error: e.message })); }
+    if (stopped) return;
+    up = http.get(d.url + "/api/events", { headers: { "x-editor-token": d.token } }, (r) => {
+      if (r.statusCode !== 200) { r.resume(); return retry(); }
+      d.sse++;
+      tries = 0;
+      let buf = "", ended = false;
+      r.setEncoding("utf8");
+      r.on("data", (chunk) => {
+        buf += chunk;
+        for (let i; (i = buf.indexOf("\n\n")) >= 0;) {
+          const block = buf.slice(0, i);
+          buf = buf.slice(i + 2);
+          const type = /^event: (.*)$/m.exec(block)?.[1], data = /^data: (.*)$/m.exec(block)?.[1];
+          if (type && data) send(type, data);
+        }
+      });
+      const end = () => {
+        if (ended) return;
+        ended = true;
+        d.sse--;
+        d.last = Date.now();
+        if (!stopped) { send("gone", "{}"); retry(); }
+      };
+      r.on("end", end); r.on("aborted", end); r.on("error", end); r.on("close", end);
+    });
+    up.on("error", retry);
+  }
+  connect();
+  return { stop() { stopped = true; up?.destroy(); } };
+}
+async function readJson(req) {
+  let s = "";
+  for await (const c of req) { s += c; if (s.length > 10000) throw new Error("body too large"); }
+  return s ? JSON.parse(s) : {};
+}
+
+/* ---- HTTP ------------------------------------------------------------------------------------- */
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+const text = (res, code, s) => { res.writeHead(code, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }); res.end(s); };
+const json = (res, code, o) => { res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" }); res.end(JSON.stringify(o)); };
+function page(res, code, title, body) {
+  res.writeHead(code, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+  res.end(`<!doctype html><meta charset="utf-8"><title>${esc(title)} · PinDeck</title>
+<link rel="icon" href="/editor/favicon.svg" type="image/svg+xml"><link rel="stylesheet" href="/editor/front.css">
+<main class="front"><h1>${esc(title)}</h1>${body}</main>`);
+}
+/* The decks for the menu (and the start page without a start deck), with which are open and working */
+const deckList = () => decksNow().map((e) => ({ key: e.key, rel: e.rel, root: e.root, problem: e.problem,
+  open: !!decks.get(e.key)?.url }));
+function chooserPage(res) {
+  const list = deckList(), groups = new Map(ROOTS.map((r) => [r, list.filter((d) => d.root === r)]).filter(([, l]) => l.length));
+  const body = [...groups].map(([root, list]) => `<h2>${esc(root)}</h2><ul>${list.map((d) => d.problem
+    ? `<li class="off" title="${esc(d.problem)}">${esc(d.rel)}<small>${esc(d.problem)}</small></li>`
+    : `<li><a href="/d/${esc(d.key)}/">${esc(d.rel)}</a>${d.open ? " <small>open</small>" : ""}</li>`).join("")}</ul>`).join("");
+  page(res, 200, "Decks", body || "<p>No decks here.</p>");
+}
+const MIME = { html: "text/html; charset=utf-8", css: "text/css; charset=utf-8", js: "text/javascript; charset=utf-8",
+  svg: "image/svg+xml", png: "image/png" };
+function serveEditorFile(res, rel) {
+  const base = path.join(EDITOR_DIR, "public");
+  const f = path.resolve(base, "." + path.posix.normalize("/" + decodeURIComponent(rel)));
+  if (!f.startsWith(base + path.sep)) return text(res, 403, "Forbidden");
+  fs.readFile(f, (err, data) => {
+    if (err) return text(res, 404, "Not found");
+    res.writeHead(200, { "content-type": MIME[path.extname(f).slice(1)] || "application/octet-stream", "cache-control": "no-store" });
+    res.end(data);
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  const host = String(req.headers.host || "").toLowerCase();
+  if (!goodHost(host)) return text(res, 403, "Bad host");
+  try {
+    const url = new URL(req.url, ORIGIN);
+    const p = url.pathname;
+    if (req.method === "GET" && p === "/login") return login(res, url);
+    // the editor's own scripts and styles hold nothing secret; the deck page loads bridge.js from here
+    if (req.method === "GET" && p.startsWith("/editor/")) return serveEditorFile(res, p.slice(8));
+    /* A deck's pages and files under /d/<deck>/v/<token>/: asked for by the deck itself, which runs sandboxed
+       without the login cookie (see VIEW in server.mjs). Passed on without the token, so the deck server's own
+       check of the path is all they get; only to a deck that is open, so they never start one. */
+    const view = /^\/d\/([\w.-]+)(\/v\/.*)$/.exec(p);
+    if (view && !authed(req)) {
+      const d = decks.get(view[1]);
+      if (!d?.url || (req.method !== "GET" && req.method !== "HEAD")) return text(res, 403, "Not logged in");
+      return proxy(req, res, d, view[2] + url.search, true);
+    }
+    if (!authed(req)) {
+      if (req.method === "GET" && /^\/(d\/[^/]+\/(index\.html)?)?$/.test(p)) {
+        res.writeHead(403, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        return res.end(LOGIN_PAGE);
+      }
+      return text(res, 403, "Not logged in");
+    }
+    const origin = req.headers.origin;
+    if (req.method === "POST" && origin && origin.toLowerCase() !== `http://${host}`) return text(res, 403, "Bad origin");
+
+    if (p === "/") {
+      if (chooser) return chooserPage(res);
+      res.writeHead(302, { location: `/d/${START.key}/`, "cache-control": "no-store" });
+      return res.end();
+    }
+    if (p === "/api/ping") return json(res, 200, { ok: true, front: true });
+    if (p === "/api/login-link") return json(res, 200, { url: loginUrl(loginCode(3600000), url.searchParams.get("next") || "/") });
+    if (p === "/api/decks") return json(res, 200, { decks: deckList() });
+    if (p === "/events" && req.method === "GET") {
+      const id = url.searchParams.get("stream") || "";
+      return /^[\w-]{8,64}$/.test(id) ? eventStream(res, id) : text(res, 400, "Bad stream");
+    }
+    if (p === "/events/subscribe" && req.method === "POST") {
+      const b = await readJson(req);
+      const st = streams.get(String(b.stream));
+      const tab = String(b.tab || "");
+      if (!st || !/^\d{1,9}$/.test(tab)) return json(res, 404, { error: "No such stream." });
+      st.tabs.get(tab)?.stop();
+      st.tabs.delete(tab);
+      if (b.on && /^[\w.-]+$/.test(String(b.deck))) st.tabs.set(tab, follow(st, tab, String(b.deck)));
+      return json(res, 200, {});
+    }
+
+    const m = /^\/d\/([\w.-]+)(\/.*)?$/.exec(p);
+    if (!m) return text(res, 404, "Not found");
+    if (!m[2]) {
+      res.writeHead(301, { location: `/d/${m[1]}/${url.search}` });
+      return res.end();
+    }
+    let d = decks.get(m[1]);
+    if (!d) {
+      // only a deck from the list, and only one PinDeck can open
+      const entry = START.key === m[1] && !chooser ? { key: START.key, dir: START.dir, file: START.file }
+        : decksNow().find((e) => e.key === m[1]);
+      if (!entry) return page(res, 404, "No such deck", `<p>It is not in the deck folder or an asset root (any more).</p><p><a href="/">All decks</a></p>`);
+      if (entry.problem) return page(res, 409, "PinDeck cannot open this deck", `<p>${esc(entry.problem)}</p><p><a href="/">All decks</a></p>`);
+      d = entry;
+    }
+    try { d = await openDeck(d); }
+    catch (e) { return page(res, 502, "PinDeck could not open this deck", `<pre>${esc(e.message)}</pre><p><a href="/">All decks</a></p>`); }
+    return proxy(req, res, d, m[2] + url.search);
+  } catch (e) {
+    const bad = e instanceof SyntaxError || e instanceof URIError || e.message === "body too large";
+    if (!res.headersSent) text(res, bad ? 400 : 500, String(e.message || e));
+  }
+});
+
+/* ---- Start ----------------------------------------------------------------------------------------
+   The port is bound first, then the start deck opens (its server checks it before writing anything). If it
+   cannot, the front says why and stops: as before the front, nothing is written. */
+let removeServerInfo = () => {};
+function writeServerInfo() {
+  fs.mkdirSync(HOME_DIR, { recursive: true, mode: 0o700 });
+  removeServerInfo = registerServer(HOME_DIR, { url: ORIGIN, token: TOKEN, deckDir: START.dir, front: true });
+}
+let listening = false;
+server.on("error", (e) => {
+  if (listening) return console.error(e);
+  console.error(e.code === "EADDRINUSE"
+    ? `Port ${PORT} is in use (another PinDeck, or an SSH tunnel?). Choose another with --port, the same on both ends of a tunnel.`
+    : `Cannot listen on 127.0.0.1:${PORT}: ${e.message}`);
+  process.exit(1);
+});
+server.listen(PORT, "127.0.0.1", async () => {
+  listening = true;
+  PORT = server.address().port;
+  ORIGIN = `http://127.0.0.1:${PORT}`;
+  if (!chooser) {
+    try { await openDeck({ key: START.key, dir: START.dir, file: START.file }, true); }
+    catch (e) {
+      console.error(e.message.replace(/\n+$/, ""));
+      process.exit(e.exitCode);   // 2 for a bad argument, as the deck server says
+    }
+  }
+  writeServerInfo();
+  console.log(`PinDeck: ${loginUrl(loginCode(3600000))}`);
+  console.log("  (a one-time login link, valid for an hour; for a new one: pindeck login)");
+  openOnEnter(() => loginUrl(loginCode(3600000)));
+  console.log(chooser ? `Decks: ${START.dir}` : `Deck: ${START.dir}`);
+  console.log(`Server: ${CAPS.label}`);
+  for (const [name, c] of Object.entries(publicCapabilities(CAPS)))
+    if (c && c.available === false) console.log(`  ${name}: off (${c.reason})`);
+});
+
+/* Ctrl+C or SIGTERM: every deck ends as it does on its own (its assistant gets end of input; at most 6 s),
+   then the front. A second Ctrl+C ends them at once. */
+async function quit() {
+  if (quitting) {
+    for (const d of decks.values()) try { process.kill(-d.proc.pid, "SIGKILL"); } catch {}
+    process.exit(1);
+  }
+  quitting = true;
+  server.close();
+  server.closeAllConnections?.();
+  removeServerInfo();
+  const all = [...decks.values()];
+  all.forEach(stopDeck);
+  await Promise.race([Promise.all(all.map((d) => d.exited)), new Promise((r) => setTimeout(r, 7000))]);
+  for (const d of all) if (d.proc.exitCode === null && d.proc.signalCode === null) try { process.kill(-d.proc.pid, "SIGKILL"); } catch {}
+  process.exit(0);
+}
+process.on("SIGINT", quit);
+process.on("SIGTERM", quit);

package/lib/agent-process.mjs

@@ -1,4 +1,5 @@
 /* JSON-line subprocess transport. Requests and notifications never outlive their process. */
+import fs from 'node:fs';
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
 export class AgentProcess {
@@ -21,7 +22,9 @@ export class AgentProcess {
     });
     this.proc.stderr.on('data', d => { this.stderr = (this.stderr + d).slice(-2000); onStderr(String(d)); });
     this.proc.stdin.on('error', e => this.end(e));
-    this.proc.on('error', e => this.end(e));
+    // spawn reports a missing working folder as the binary's ENOENT: name the folder instead
+    this.proc.on('error', e => this.end(e.code === 'ENOENT' && cwd && !fs.existsSync(cwd)
+      ? new Error(`The deck folder ${cwd} is not there any more (moved or deleted).`) : e));
     this.proc.on('exit', (code, signal) => this.end(new Error(`Agent stopped (${signal || code}). ${this.stderr.trim()}`)));
   }
   write(value) { if (this.closed) throw new Error('Agent is not running.'); this.proc.stdin.write(JSON.stringify(value) + '\n'); }

package/lib/agent-tools.mjs

@@ -25,8 +25,11 @@ export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextF
   const roots = () => [deck, ...readDirs.flatMap(d => { try { return [fs.realpathSync(d)]; } catch { return []; } })];
   const inside = (root, file) => file === root || file.startsWith(root + path.sep);
   const envNow = () => (typeof env === 'function' ? env() : env);
-  const isLocked = rel => (typeof locked === 'function' ? locked() : locked)
-    .some(p => p.endsWith('/**') ? rel === p.slice(0, -3) || rel.startsWith(p.slice(0, -2)) : rel === p);
+  // compared regardless of case and Unicode form: on macOS's usual volumes .GIT/config and BRAND.CSS are the
+  // locked files themselves
+  const fold = p => p.normalize('NFC').toLowerCase();
+  const isLocked = rel => (typeof locked === 'function' ? locked() : locked).map(fold)
+    .some(p => p.endsWith('/**') ? fold(rel) === p.slice(0, -3) || fold(rel).startsWith(p.slice(0, -2)) : fold(rel) === p);
   function checked(file, write = false) {
     if (typeof file !== 'string' || !file || file.includes('\0')) throw new Error('Invalid file path.');
     const full = path.resolve(deck, file);

package/lib/asset-roots.mjs

@@ -0,0 +1,22 @@
+/* Asset roots: folders outside the deck whose files the deck may use, from --asset-root (repeatable) and
+   "assetRoots" in config.json. Shared by the front, which lists their decks, and each deck server, which
+   serves their files, so both read them alike. */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const expandHome = (p) => (p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p);
+
+/* { roots, missing }: absolute paths, each once, in the order given; missing: those that are not folders */
+export function assetRoots(args = [], config = {}) {
+  const roots = [], missing = [];
+  for (const r of [...args, ...(Array.isArray(config?.assetRoots) ? config.assetRoots : [])]) {
+    const abs = path.resolve(expandHome(String(r)));
+    if (roots.includes(abs) || missing.includes(abs)) continue;
+    let dir = false;
+    try { dir = fs.statSync(abs).isDirectory(); } catch {}
+    (dir ? roots : missing).push(abs);
+  }
+  return { roots, missing };
+}

package/lib/claude.mjs

@@ -12,11 +12,19 @@ export class ClaudeSession {
     if (this.running) return;
     this.stopped = false;
     const env = typeof this.env === 'function' ? this.env() : this.env;
+    /* The sign-in check: "not signed in" only when the CLI says so. A CLI without `auth status --json` (older
+       than PinDeck's tested versions) or with other output starts anyway; the session then reports any problem. */
+    let signedIn = null;
     try {
       const { stdout } = await exec(process.env.CLAUDE_BIN || 'claude', ['auth', 'status', '--json'],
         { env: { ...process.env, ...env }, timeout: 15000, maxBuffer: 65536 });
-      if (!JSON.parse(stdout).loggedIn) throw new Error('Not signed in.');
-    } catch (e) { throw new Error(e.code === 'ENOENT' ? 'Claude CLI is not installed (or set CLAUDE_BIN).' : 'Claude is not signed in. Run claude auth login, then refresh models.'); }
+      signedIn = JSON.parse(stdout).loggedIn;
+    } catch (e) {
+      if (e.code === 'ENOENT') throw new Error('Claude CLI is not installed (or set CLAUDE_BIN).');
+      if (e.killed) throw new Error('Claude did not answer its sign-in check within 15 s. Try again (Refresh models).');
+      try { signedIn = JSON.parse(e.stdout).loggedIn; } catch {}   // signed out: the CLI answers, and exits 1
+    }
+    if (signedIn === false) throw new Error('Claude is not signed in. Run claude auth login, then refresh models.');
     if (this.stopped) throw new Error('Agent stopped.');
     const transport = new AgentProcess({ binary: process.env.CLAUDE_BIN || 'claude', cwd: this.cwd, env,
       args: ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',

package/lib/deck-files.mjs

@@ -57,17 +57,19 @@ export function revision(dir, files) {
 
 /* The deck's files for undo: every file a turn may change, with its content (bigger files: only size and
    time, too large to keep a copy of). Hidden files and folders (.git), node_modules, and the vendor/ and
-   export/ folders are left out; so are symlinks, which point elsewhere. */
+   export/ folders are left out; so are symlinks, which point elsewhere, and the paths in skip (other decks
+   in the folder: their files and folders, as paths relative to dir). */
 const SKIP_TOP = new Set(["vendor", "export", "node_modules"]);
 export const KEEP_BYTES = 2 * 1024 * 1024;
-export function scanFiles(dir, maxBytes = KEEP_BYTES) {
-  const files = new Map();
+export function scanFiles(dir, { maxBytes = KEEP_BYTES, skip = [] } = {}) {
+  const files = new Map(), skipped = new Set(skip);
   const walk = (rel) => {
     let entries = [];
     try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return; }
     for (const e of entries) {
       if (e.name.startsWith(".") || e.name === "node_modules") continue;
       const r = rel ? `${rel}/${e.name}` : e.name;
+      if (skipped.has(r)) continue;
       if (e.isDirectory()) { if (rel || !SKIP_TOP.has(e.name)) walk(r); continue; }
       if (!e.isFile()) continue;
       try {

package/lib/deck-list.mjs

@@ -0,0 +1,72 @@
+/* The decks the front offers in the editor's deck menu: .html files in the start folder and the asset roots,
+   and in their folders one level down. Reading only: a deck gets its element ids (and PinDeck writes its
+   state) only once it is opened. A file PinDeck cannot open is listed with the reason, as at start-up. */
+
+import fs from "node:fs";
+import path from "node:path";
+import { deckTarget } from "./deck-target.mjs";
+import { unsupportedMessage } from "./frameworks.mjs";
+
+const SKIP = new Set(["node_modules", "export"]);   // dependencies, and PinDeck's own PDF exports
+const MAX_FILES = 300;
+const MAX_BYTES = 5 * 1024 * 1024;
+
+// symlinks count as what they point to
+const kind = (dir, e) => { if (!e.isSymbolicLink()) return e; try { return fs.statSync(path.join(dir, e.name)); } catch { return e; } };
+const htmlFiles = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => /\.html$/i.test(e.name) && !e.name.startsWith(".") && kind(dir, e).isFile()).map((e) => e.name).sort();
+  } catch { return []; }
+};
+const subfolders = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => !e.name.startsWith(".") && !SKIP.has(e.name) && kind(dir, e).isDirectory()).map((e) => e.name).sort();
+  } catch { return []; }
+};
+/* A deck file that is a symlink to a file in another folder cannot be opened: its relative paths (theme.css,
+   figures/) would be looked up beside the link, where the files are not. Why, or null. */
+export function linkProblem(dir, file) {
+  const abs = path.join(dir, file);
+  try {
+    if (!fs.lstatSync(abs).isSymbolicLink()) return null;
+    const real = fs.realpathSync(abs);
+    if (path.dirname(real) === fs.realpathSync(dir)) return null;
+    return `${file} is a link to a deck in another folder: open that deck itself (${real}).`;
+  } catch { return null; }
+}
+
+/* What each file's check found, by path, while its size and modification time stay the same: listing is
+   asked for on every deck menu and every first request for a deck, and reading every deck each time held up
+   the front, which passes on all decks' requests. */
+const checked = new Map();
+
+/* [{ key, dir, file, rel, root, problem }]: rel is the path shown in the menu, relative to its root;
+   problem is null for a deck PinDeck can open. A file under several roots is listed once, under the first. */
+export function listDecks(roots) {
+  const out = [], seen = new Set();
+  for (const root of roots) {
+    for (const dir of [root, ...subfolders(root).map((d) => path.join(root, d))]) {
+      for (const file of htmlFiles(dir)) {
+        const abs = path.join(dir, file);
+        if (seen.has(abs) || out.length >= MAX_FILES) continue;
+        seen.add(abs);
+        let problem = null;
+        try {
+          const st = fs.statSync(abs), known = checked.get(abs);
+          if (known && known.mtimeMs === st.mtimeMs && known.size === st.size) problem = known.problem;
+          else {
+            problem = st.size > MAX_BYTES ? `${file} is larger than 5 MB, too large for a deck.`
+              : unsupportedMessage(fs.readFileSync(abs, "utf8"), file)?.replace(/ Nothing was changed\.$/, "") || null;
+            checked.set(abs, { mtimeMs: st.mtimeMs, size: st.size, problem });
+          }
+          problem = linkProblem(dir, file) || problem;
+        } catch (e) { problem = `${file} cannot be read (${e.code || e.message}).`; }
+        const t = deckTarget(file === "index.html" ? dir : abs);
+        out.push({ key: t.key, dir, file, rel: path.relative(root, abs).split(path.sep).join("/"), root, problem });
+      }
+    }
+  }
+  return out;
+}

package/lib/deck-target.mjs

@@ -0,0 +1,43 @@
+/* Which deck a path names, and where PinDeck keeps that deck's state: shared by the front (pindeck), which
+   lists decks and addresses them as /d/<key>/, and the deck server, which keeps its chat and undo there. */
+
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+
+export const homeDir = (env = process.env) => env.PINDECK_HOME || path.join(os.homedir(), ".pindeck-v3");
+
+/* PinDeck 2 keeps its chats and settings in files of the same names, in other formats: the two versions in one
+   folder (one PINDECK_HOME for both) overwrite each other's. PinDeck 3 saves a provider with every chat and
+   PinDeck 2 never does, so a chat without one was written by version 2: copied over (which works), or written
+   by a PinDeck 2 that uses this folder too (which does not). Returns the warning, or null. */
+export function homeWarning(home) {
+  let decks = [];
+  try { decks = fs.readdirSync(path.join(home, "decks")).slice(0, 500); } catch { return null; }
+  for (const d of decks) {
+    let chat;
+    try { chat = JSON.parse(fs.readFileSync(path.join(home, "decks", d, "chat.json"), "utf8")); } catch { continue; }
+    if (chat && typeof chat === "object" && !("provider" in chat))
+      return `${home} holds a chat written by PinDeck 2 (decks/${d}/chat.json). If PinDeck 2 uses this folder too, ` +
+        `give PinDeck 3 another one (PINDECK_HOME; by default ~/.pindeck-v3): the two versions overwrite each ` +
+        `other's settings and chats. Chats copied over from PinDeck 2 are fine.`;
+  }
+  return null;
+}
+
+/* A file (talk.html), or a folder, which means its index.html. A path ending in .html that is
+   not a folder is a file, so a missing file gets a clear message. */
+export function deckTarget(target) {
+  const abs = path.resolve(target);
+  const isFolder = (() => { try { return fs.statSync(abs).isDirectory(); } catch { return false; } })();
+  const dir = isFolder || !/\.html$/i.test(abs) ? abs : path.dirname(abs);
+  const file = dir === abs ? "index.html" : path.basename(abs);
+  const named = file !== "index.html";   // a deck file with its own name; several can share a folder
+  const name = named ? file.replace(/\.html$/i, "") : path.basename(dir);   // for exports and titles
+  /* State per deck file. A folder's index.html keeps the key it always had, so existing chats and undo
+     histories stay; a named file gets its own, so two decks in one folder never share chat or undo. */
+  const key = (named ? `${path.basename(dir)}-${name}` : path.basename(dir)).replace(/[^\w.-]+/g, "_") + "-" +
+    crypto.createHash("sha1").update(named ? path.join(dir, file) : dir).digest("hex").slice(0, 8);
+  return { dir, file, named, name, key };
+}