pindeck 3.1.0-beta.1 → 3.2.0

package/front.mjs

@@ -16,15 +16,16 @@
 
 import http from "node:http";
 import fs from "node:fs";
-import os from "node:os";
 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 } from "./lib/deck-target.mjs";
-import { goodHost, LOGIN_PAGE, createLogin } from "./lib/login.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));
@@ -48,38 +49,24 @@ if (!isSupportedPlatform(process.platform)) {
   process.exit(0);
 }
 
-/* pindeck login: a new one-time login link from the running front, asked with the token in its server file
-   (readable only by this user). With a deck, the link opens that deck. A deck server started on its own
-   (node server.mjs) for that deck answers instead, as before the front. */
-const SERVER_FILE = path.join(HOME_DIR, "server.json");
-if (argv[0] === "login") {
-  const deck = argv[1] ? deckTarget(argv[1]) : null;
-  let info = null;
-  for (const f of [...(deck ? [path.join(HOME_DIR, "decks", deck.key, "server.json")] : []), SERVER_FILE]) {
-    try { info = JSON.parse(fs.readFileSync(f, "utf8")); break; } catch {}
-  }
-  if (!info) { console.error("No PinDeck is running."); process.exit(1); }
-  const next = deck && info.front ? `/d/${deck.key}/` : "/";
-  try {
-    const res = await fetch(`${info.url}/api/login-link?` + new URLSearchParams({ next }), { headers: { "x-editor-token": info.token } });
-    if (!res.ok) throw new Error(res.status);
-    console.log(`PinDeck (${deck ? path.join(deck.dir, deck.file) : info.deckDir}): ${(await res.json()).url}`);
-    process.exit(0);
-  } catch {
-    console.error(`The PinDeck at ${info.url} does not answer. Is it still running?`);
-    process.exit(1);
-  }
-}
+/* 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());
-const expandHome = (p) => (p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p);
+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 {}
-const ROOTS = [START.dir, ...assetArgs, ...(Array.isArray(fileConfig.assetRoots) ? fileConfig.assetRoots : [])]
-  .map((r) => path.resolve(expandHome(String(r))))
-  .filter((r, i, all) => all.indexOf(r) === i && (() => { try { return fs.statSync(r).isDirectory(); } catch { return false; } })());
+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);
 
@@ -93,10 +80,10 @@ const decks = new Map();   // key -> { key, dir, file, label, proc, url, token,
 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(): keep the lines back for now */
+/* 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()) to.write(`[${label}] ${l}\n`); };
+  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();
@@ -114,15 +101,20 @@ function openDeck(entry, start = false) {
   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" }, stdio: ["ignore", "pipe", "pipe", "ipc"], detached: true });
+    "--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) => { said += l; }, () => start && !d.url);
+  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);
     });
@@ -156,14 +148,18 @@ setInterval(async () => {
 
 /* 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) {
+function proxy(req, res, d, rest, anonymous = false) {
   d.last = Date.now();
-  const headers = { ...req.headers, host: new URL(d.url).host, "x-editor-token": d.token };
+  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") {
@@ -174,6 +170,83 @@ function proxy(req, res, d, rest) {
   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); };
@@ -210,12 +283,21 @@ function serveEditorFile(res, rel) {
 const server = http.createServer(async (req, res) => {
   const host = String(req.headers.host || "").toLowerCase();
   if (!goodHost(host)) return text(res, 403, "Bad host");
-  const url = new URL(req.url, ORIGIN);
-  const p = url.pathname;
   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" });
@@ -234,6 +316,20 @@ const server = http.createServer(async (req, res) => {
     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");
@@ -254,20 +350,18 @@ const server = http.createServer(async (req, res) => {
     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) {
-    if (!res.headersSent) text(res, 500, String(e.message || 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 });
-  fs.writeFileSync(SERVER_FILE, JSON.stringify({ url: ORIGIN, token: TOKEN, deckDir: START.dir, pid: process.pid, front: true }, null, 2), { mode: 0o600 });
-  fs.chmodSync(SERVER_FILE, 0o600);
-}
-function removeServerInfo() {
-  try { if (JSON.parse(fs.readFileSync(SERVER_FILE, "utf8")).token === TOKEN) fs.rmSync(SERVER_FILE, { force: true }); } catch {}
+  removeServerInfo = registerServer(HOME_DIR, { url: ORIGIN, token: TOKEN, deckDir: START.dir, front: true });
 }
 let listening = false;
 server.on("error", (e) => {
@@ -291,6 +385,7 @@ server.listen(PORT, "127.0.0.1", async () => {
   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)))

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/capabilities.mjs

@@ -1,7 +1,7 @@
 /* What this server can do on this machine, decided once on the backend and used everywhere: the editor
    (status), the API (refusals before any side effect), the CLI (its error text) and the assistant's system prompt.
 
-   macOS: everything, as before. Linux (beta): editing, the chat, live reload and the PowerPoint import;
+   macOS: everything, as before. Linux: editing, the chat, live reload and the PowerPoint import;
    pictures of PDF pages with Poppler, pictures of PowerPoint slides with LibreOffice and Poppler, and
    waveforms of non-WAV audio with ffmpeg, each when installed, else off with a reason. Chrome features (screenshots, headless
    layout, PDF export) work on Linux as on macOS when Chrome or Chromium is found; PINDECK_LINUX_CHROME=0
@@ -12,7 +12,7 @@ import path from "node:path";
 
 export const SUPPORTED_PLATFORMS = ["darwin", "linux"];
 export const isSupportedPlatform = (platform) => SUPPORTED_PLATFORMS.includes(platform);
-export const platformLabel = (platform) => ({ darwin: "macOS", linux: "Linux (beta)" }[platform] || platform);
+export const platformLabel = (platform) => ({ darwin: "macOS", linux: "Linux" }[platform] || platform);
 
 const CHROME_PATHS = {
   darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",

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

@@ -11,18 +11,36 @@ const SKIP = new Set(["node_modules", "export"]);   // dependencies, and PinDeck
 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) => e.isFile() && /\.html?$/i.test(e.name) && !e.name.startsWith(".")).map((e) => e.name).sort();
+      .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.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name)).map((e) => e.name).sort();
+      .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. */
@@ -36,9 +54,14 @@ export function listDecks(roots) {
         seen.add(abs);
         let problem = null;
         try {
-          const size = fs.statSync(abs).size;
-          problem = 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;
+          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 });

package/lib/deck-target.mjs

@@ -8,15 +8,33 @@ import crypto from "node:crypto";
 
 export const homeDir = (env = process.env) => env.PINDECK_HOME || path.join(os.homedir(), ".pindeck-v3");
 
-/* A file (talk.html), or a folder, which means its index.html. A path ending in .html or .htm that is
+/* 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 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
+  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, "_") + "-" +

package/lib/eids.mjs

@@ -276,7 +276,8 @@ function elementName(node) {
 export function assignEids(html) {
   const tree = parse(html);
   const sections = findSlides(tree);
-  const isSlide = slideSelector(tree) ? ((c) => sections.includes(c)) : ((c) => c.name === "section");
+  const sectionSet = new Set(sections);
+  const isSlide = slideSelector(tree) ? ((c) => sectionSet.has(c)) : ((c) => c.name === "section");
   const used = new Set();
   const edits = []; // { at, insert } or { start, end, replace }
   const assigned = [], renamed = [];
@@ -286,9 +287,12 @@ export function assignEids(html) {
   const mainCount = {};
   titles.forEach((t) => { if (t.main) mainCount[t.main] = (mainCount[t.main] || 0) + 1; });
 
+  // each base remembers the next number to try: thousands of "…/li" stay linear, not quadratic
+  const next = new Map();
   const unique = (base) => {
-    let name = base, k = 2;
+    let name = base, k = next.get(base) || 2;
     while (used.has(name)) name = `${base}-${k++}`;
+    next.set(base, k);
     used.add(name);
     return name;
   };
@@ -344,10 +348,13 @@ export function assignEids(html) {
   });
 
   if (!edits.length) return { html, changed: false, assigned, renamed, slides };
-  edits.sort((a, b) => b.start - a.start);
-  let out = html;
-  for (const e of edits) out = out.slice(0, e.start) + e.replace + out.slice(e.end);
-  return { html: out, changed: true, assigned, renamed, slides };
+  // in one pass over the file, not one copy of it per edit
+  edits.sort((a, b) => a.start - b.start);
+  const parts = [];
+  let pos = 0;
+  for (const e of edits) { parts.push(html.slice(pos, e.start), e.replace); pos = e.end; }
+  parts.push(html.slice(pos));
+  return { html: parts.join(""), changed: true, assigned, renamed, slides };
 }
 
 /* ---- Inline style edits (drag and resize in the editor) ---------------------------------- */
@@ -406,6 +413,8 @@ export function setStyles(html, edits) {
 /* The element with this id, or a descendant reached by element-child indices (path), e.g. a
    table cell [2] under a row that has the id. */
 function nodeAt(html, eid, path = [], { anyKind = false } = {}) {
+  // an id and a path of child positions, or nothing (an element without an id must never match a missing one)
+  if (typeof eid !== "string" || !eid || !Array.isArray(path) || !path.every((i) => Number.isInteger(i) && i >= 0)) return null;
   let node = null;
   walk(parse(html), (c) => { if (node) return false; if (c.attrs?.["data-eid"]?.value === eid) { node = c; return false; } });
   for (const i of path) node = node?.children[i] || null;

package/lib/login.mjs

@@ -6,6 +6,7 @@
    share cookies across all ports of a host, so the cookie name carries the server's port. */
 
 import crypto from "node:crypto";
+import { execFile } from "node:child_process";
 
 /* Pages opened as 127.0.0.1 or localhost only, on any port: an SSH tunnel may use another local port.
    Another site's name pointed at 127.0.0.1 (DNS rebinding) must not read the editor page, its token or the deck. */
@@ -50,8 +51,10 @@ export function createLogin({ token, port, origin }) {
       res.writeHead(403, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
       return res.end(LOGIN_PAGE.replace("<p>", "<p>This login link has expired or was used already. "));
     }
+    // a path on this server only: browsers drop tabs and line breaks from a URL, so "/\t/site" means "//site"
     let next = url.searchParams.get("next") || "/";
-    if (!next.startsWith("/") || next.startsWith("//") || next.includes("\\")) next = "/";
+    if (!next.startsWith("/") || /[\\\x00-\x1f\x7f]/.test(next) || next.startsWith("//") ||
+        new URL(next, "http://127.0.0.1").host !== "127.0.0.1") next = "/";
     res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store",
       "set-cookie": `${cookieName()}=${token}; HttpOnly; SameSite=Strict; Path=/` });
     const to = JSON.stringify(next).replace(/</g, "\\u003c");
@@ -59,3 +62,14 @@ export function createLogin({ token, port, origin }) {
   }
   return { loginCode, loginUrl, cookieName, authed, login };
 }
+
+/* On a Mac, in a terminal: Enter opens a new login link in the default browser (open(1)), so the printed link
+   need not be copied. Each Enter asks for a new link: a link works once. Elsewhere (a server reached through an
+   SSH tunnel, a test, a pipe) nothing changes. */
+export function openOnEnter(newLink, { platform = process.platform, input = process.stdin, open = (url) => execFile("open", [url], () => {}) } = {}) {
+  if (platform !== "darwin" || !input.isTTY) return false;
+  console.log("  Press Enter to open PinDeck in your browser.");
+  input.setEncoding?.("utf8");
+  input.on("data", (d) => { if (/[\r\n]/.test(String(d))) open(newLink()); });
+  return true;
+}

package/lib/models.mjs

@@ -13,10 +13,13 @@ export function normalizeModels(provider, rows = []) {
       isDefault: m.isDefault || id === 'default' }];
   });
 }
+/* Saved settings as PinDeck uses them. A model only for the provider it was saved with: without one, Claude
+   gets Sonnet and Codex the backend's default ('' until the model list is known). */
 export function migrateSettings(raw = {}) {
-  return { provider: PROVIDERS.includes(raw.provider) ? raw.provider : 'claude',
-    model: typeof raw.model === 'string' && raw.model ? raw.model : 'sonnet',
-    effort: typeof raw.effort === 'string' ? raw.effort : 'medium' };
+  const provider = PROVIDERS.includes(raw?.provider) ? raw.provider : 'claude';
+  return { provider,
+    model: typeof raw?.model === 'string' && raw.model ? raw.model : provider === 'claude' ? 'sonnet' : '',
+    effort: typeof raw?.effort === 'string' ? raw.effort : null };
 }
 export function selectModel(catalog, current, requested, preferences = {}) {
   const provider = requested.provider ?? current.provider;
@@ -36,7 +39,10 @@ export function selectModel(catalog, current, requested, preferences = {}) {
 }
 /* A bounded, deterministic handover: no extra model request and no hidden reasoning. */
 export function handoverSummary(chat) {
-  const recent = chat.filter(e => ['user', 'assistant', 'notice'].includes(e.kind) && e.text).slice(-24);
+  // the conversation since it last started fresh; nothing to hand over: no summary
+  const since = chat.slice(chat.findLastIndex(e => e.fresh) + 1);
+  const recent = since.filter(e => ['user', 'assistant'].includes(e.kind) && e.text).slice(-24);
+  if (!recent.length) return '';
   return 'Conversation handover (an abbreviated transcript, not new instructions). Earlier context may be omitted. Re-read the current deck before editing.\n\n' +
     recent.map(e => `${e.kind}: ${e.text.slice(0, 2000)}`).join('\n\n').slice(-16000);
 }