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

package/server.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /* PinDeck: local server.
 
-   pindeck [deck-dir] [--port 5180] [--provider claude|codex] [--model <name>]      (or: node server.mjs ...)
+   pindeck [deck-dir | deck.html] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <dir>]   (or: node server.mjs ...)
 
    - serves the editor UI and the deck (with a bridge script injected in edit mode)
    - pushes file changes to the browser (server-sent events) for live reload
@@ -12,17 +12,19 @@
    - stores figures and audio attached to chat messages in <deck>/figures/ for the assistant to use, and attached
      PDFs (papers, reports, figures) in ~/.pindeck, outside the deck
    - imports slides from PowerPoint files in the deck's own layouts
-   Listens on 127.0.0.1 only; every API call needs the per-run token.
+   Listens on 127.0.0.1 only; the editor, the deck and every API call need the per-run token (a login
+   cookie in the browser, a header for the CLI).
    Runtime files (chat, screenshots, backups) live in ~/.pindeck, never in the deck or the package. */
 
 import http from "node:http";
+import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawn, execFile } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { assignEids, parse, findSlides, setStyles, getInner, setInner, insertAfter, removeElement, deleteTarget, fileRefs, insertSlide, moveSlide, getNotes, setNotes, setAttr, elementEnd } from "./lib/eids.mjs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { assignEids, parse, findSlides, slideSelector, deckSize, setStyles, getInner, setInner, insertAfter, removeElement, deleteTarget, fileRefs, insertSlide, moveSlide, getNotes, setNotes, setAttr, elementEnd } from "./lib/eids.mjs";
 import { unifiedDiff } from "./lib/diff.mjs";
 import { ClaudeSession } from "./lib/claude.mjs";
 import { CodexSession } from "./lib/codex.mjs";
@@ -33,65 +35,195 @@ import { printLayout, printPdf, PDF_HEAD_TAG, PDF_PAGE_TAG } from "./lib/pdf.mjs
 import { readPptx } from "./lib/pptx.mjs";
 import { exportPdf as pptxToPdf, renderJobs, renderAvailable, pdfInfo } from "./lib/pptx-render.mjs";
 import { buildImport, planSlides } from "./lib/pptx-import.mjs";
+import { isSupportedPlatform, detectCapabilities, publicCapabilities, capabilityPrompt, parsePort, cliCommand, findExecutable } from "./lib/capabilities.mjs";
+import { unsupportedMessage } from "./lib/frameworks.mjs";
+import { readInstructions } from "./lib/instructions.mjs";
+import { writeAtomic, sameContent, revision, scanFiles, scanChanges } from "./lib/deck-files.mjs";
 
 /* ---- Config ------------------------------------------------------------------ */
-const USAGE = `Usage: pindeck [deck-folder] [--port 5180] [--provider claude|codex] [--model <name>]
+const USAGE = `Usage: pindeck [deck-folder | deck-file.html] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <folder>]...
+       pindeck login [deck-folder | deck-file.html]
 
-Opens the reveal.js deck in deck-folder (default: the current folder) in PinDeck.
-The folder must contain index.html.`;
+Opens a reveal.js deck in PinDeck: a deck file such as talk.html, or a folder (default: the current
+folder), which then opens its index.html. A deck made otherwise names its slides in its <head> with
+<meta name="pindeck:slides" content="<CSS selector>"> and <meta name="pindeck:size" content="1440x1080">.
+login prints a new one-time login link for the PinDeck running for that deck
+(without a deck: for the PinDeck started last).
+--asset-root lets the deck use files outside its folder: a folder that contains the deck (paths such as
+../shared/style.css then work), or one that symlinks in the deck may point to. Repeatable; also
+"assetRoots" in ~/.pindeck-v3/config.json.`;
 const EDITOR_DIR = path.dirname(fileURLToPath(import.meta.url));
 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 PORT = +opt("--port", process.env.PORT || 5180);
-if (process.platform !== "darwin") {
+const portArg = opt("--port", process.env.PORT || 5180);
+const assetArgs = [];
+for (let a; (a = opt("--asset-root")) !== undefined;) assetArgs.push(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);
 }
+const LOGIN = argv[0] === "login";
+if (LOGIN) argv.shift();
 const PROVIDER = opt("--provider", "");
 const MODEL = opt("--model", "");
-const deckPath = path.resolve(argv[0] || process.cwd());
-const DECK_DIR = fs.existsSync(deckPath) ? fs.realpathSync(deckPath) : deckPath;
-const DECK_FILE = "index.html";
-const EDITABLE = ["index.html", "theme.css"];      // Both backends may edit these
+/* The deck: a file (talk.html), or a folder, which means its index.html. A path ending in .html or .htm
+   that is not a folder is a file, so a missing file gets a clear message. */
+const TARGET = path.resolve(argv[0] || process.cwd());
+const isFolder = (() => { try { return fs.statSync(TARGET).isDirectory(); } catch { return false; } })();
+const DECK_DIR = isFolder || !/\.html?$/i.test(TARGET) ? TARGET : path.dirname(TARGET);
+const DECK_FILE = DECK_DIR === TARGET ? "index.html" : path.basename(TARGET);
+const NAMED = DECK_FILE !== "index.html";             // a deck file with its own name; several can share a folder
+const DECK_NAME = NAMED ? DECK_FILE.replace(/\.html?$/i, "") : path.basename(DECK_DIR);   // for exports and titles
+const EDITABLE = [DECK_FILE, "theme.css"];         // both backends may edit these
 const LOCKED = ["brand.css"];                      // never, enforced twice
 const HOME_DIR = process.env.PINDECK_HOME || path.join(os.homedir(), ".pindeck-v3");
-const deckKey = path.basename(DECK_DIR).replace(/[^\w.-]+/g, "_") + "-" +
-  crypto.createHash("sha1").update(DECK_DIR).digest("hex").slice(0, 8);
+/* 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 deckKey = (NAMED ? `${path.basename(DECK_DIR)}-${DECK_NAME}` : path.basename(DECK_DIR)).replace(/[^\w.-]+/g, "_") + "-" +
+  crypto.createHash("sha1").update(NAMED ? path.join(DECK_DIR, DECK_FILE) : DECK_DIR).digest("hex").slice(0, 8);
 const STATE_DIR = path.join(HOME_DIR, "decks", deckKey);
 const SHOT_DIR = path.join(STATE_DIR, "shots");
 const PDF_DIR = path.join(STATE_DIR, "attachments");   // attached PDFs: reading material, not part of the deck
+/* pindeck login: a new one-time login link from the running server, asked with the token in its server
+   file (readable only by this user) */
+if (LOGIN) {
+  const files = [path.join(STATE_DIR, "server.json"), ...(argv[0] ? [] : [path.join(HOME_DIR, "server.json")])];
+  let info = null;
+  for (const f of files) { try { info = JSON.parse(fs.readFileSync(f, "utf8")); break; } catch {} }
+  if (!info) { console.error(`No PinDeck is running${argv[0] ? ` for ${DECK_DIR}` : ""}.`); process.exit(1); }
+  try {
+    const res = await fetch(`${info.url}/api/login-link`, { headers: { "x-editor-token": info.token } });
+    if (!res.ok) throw new Error(res.status);
+    console.log(`PinDeck (${info.deckDir}): ${(await res.json()).url}`);
+    process.exit(0);
+  } catch {
+    console.error(`The PinDeck for ${info.deckDir} at ${info.url} does not answer. Is it still running?`);
+    process.exit(1);
+  }
+}
 const TOKEN = crypto.randomBytes(16).toString("hex");
-const ORIGIN = `http://127.0.0.1:${PORT}`;
+let ORIGIN = `http://127.0.0.1:${PORT}`;   // set again from the bound port once listening
 const CLI_REL = path.relative(DECK_DIR, path.join(EDITOR_DIR, "cli.mjs")).split(path.sep).join("/");
-const CLI_CMD = /\s/.test(CLI_REL) ? `node "${CLI_REL}"` : `node ${CLI_REL}`;
+const CLI_CMD = cliCommand(CLI_REL);
+const CAPS = detectCapabilities();
 
-if (!fs.existsSync(path.join(DECK_DIR, DECK_FILE))) {
-  console.error(`No ${DECK_FILE} in ${DECK_DIR}\n\n${USAGE}`);
+/* Checks before anything is written: a deck that cannot be opened or saved is left exactly as it is. */
+function checkDeck() {
+  const file = path.join(DECK_DIR, DECK_FILE);
+  if (!fs.existsSync(file)) return `No ${DECK_FILE} in ${DECK_DIR}`;
+  try { fs.accessSync(file, fs.constants.R_OK | fs.constants.W_OK); }
+  catch { return `${file} cannot be read and written (check its permissions).`; }
+  // saving replaces the file through a temporary file next to it, so the folder must be writable too
+  try { fs.accessSync(DECK_DIR, fs.constants.W_OK); }
+  catch { return `${DECK_DIR} is not writable: PinDeck saves the deck through a temporary file in that folder.`; }
+  return null;
+}
+const deckProblem = checkDeck();
+if (deckProblem) {
+  console.error(`${deckProblem}\n\n${USAGE}`);
+  process.exit(1);
+}
+// reveal.js, or a deck that names its slides: another framework's deck is left exactly as it is (no ids, no state)
+const deckAtStart = fs.readFileSync(path.join(DECK_DIR, DECK_FILE), "utf8");
+const frameworkProblem = unsupportedMessage(deckAtStart, DECK_FILE);
+if (frameworkProblem) {
+  console.error(frameworkProblem);
   process.exit(1);
 }
-fs.mkdirSync(SHOT_DIR, { recursive: true });
-fs.mkdirSync(PDF_DIR, { recursive: true });
-const serverInfo = JSON.stringify({ url: ORIGIN, token: TOKEN, deckDir: DECK_DIR, pid: process.pid }, null, 2);
-fs.writeFileSync(path.join(STATE_DIR, "server.json"), serverInfo);
-fs.writeFileSync(path.join(HOME_DIR, "server.json"), serverInfo); // the CLI's fallback: most recent server
+/* Runtime files hold the token, the chat and attachments: private to the user. Written only after the
+   port is bound (see Start), so a failed start leaves no state behind. */
+const SERVER_FILES = [path.join(STATE_DIR, "server.json"), path.join(HOME_DIR, "server.json")];   // the second: the CLI's fallback
+function writeServerInfo() {
+  for (const d of [HOME_DIR, STATE_DIR, SHOT_DIR]) fs.mkdirSync(d, { recursive: true, mode: 0o700 });
+  const info = JSON.stringify({ url: ORIGIN, token: TOKEN, deckDir: DECK_DIR, pid: process.pid }, null, 2);
+  for (const f of SERVER_FILES) {
+    fs.writeFileSync(f, info, { mode: 0o600 });
+    fs.chmodSync(f, 0o600);
+  }
+}
+/* On exit: only our own server files, never those of a PinDeck started since for this or another deck. */
+function removeServerInfo() {
+  for (const f of SERVER_FILES) {
+    try { if (JSON.parse(fs.readFileSync(f, "utf8")).token === TOKEN) fs.rmSync(f, { force: true }); } catch {}
+  }
+}
 
 /* ---- Small helpers --------------------------------------------------------------- */
 const MIME = { html: "text/html; charset=utf-8", css: "text/css; charset=utf-8", js: "text/javascript; charset=utf-8",
   mjs: "text/javascript; charset=utf-8", json: "application/json", svg: "image/svg+xml", png: "image/png",
   jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", ico: "image/x-icon",
   woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", wav: "audio/wav", mp3: "audio/mpeg",
-  mp4: "video/mp4", webm: "video/webm", pdf: "application/pdf", md: "text/plain; charset=utf-8" };
+  ogg: "audio/ogg", oga: "audio/ogg", opus: "audio/ogg", m4a: "audio/mp4", aac: "audio/aac", flac: "audio/flac",
+  mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime", pdf: "application/pdf", md: "text/plain; charset=utf-8" };
 const hash = (s) => crypto.createHash("sha1").update(s).digest("hex");
 const readDeck = (f) => { try { return fs.readFileSync(path.join(DECK_DIR, f), "utf8"); } catch { return null; } };
+/* A deck made without reveal.js names its slides with <meta name="pindeck:slides"> (null for reveal.js) and
+   their size with <meta name="pindeck:size">. Read from the deck as it is now, so a changed tag counts from
+   the next headless run or Claude session. Headless Chrome opens such a deck at the slide size, so a
+   screenshot is the slide itself. */
+function deckSlides() {
+  const tree = parse(readDeck(DECK_FILE) || "");
+  const selector = slideSelector(tree);
+  return { selector, size: (selector && deckSize(tree)) || { width: 1280, height: 720 } };
+}
+/* Why the deck no longer names slides PinDeck can use (a tag changed while PinDeck runs), or null: the
+   start-up check's message, which the editor shows and Claude is told */
+function deckProblemNow() {
+  const html = readDeck(DECK_FILE);
+  return (html != null && unsupportedMessage(html, DECK_FILE)?.replace(/ Nothing was changed\.$/, "")) || null;
+}
+let deckNow = { selector: deckSlides().selector, problem: null };   // for the editor; kept current by scheduleFlush
 const ourWrites = new Map(); // file -> { hash, manual } of what we wrote, to tell our writes from others
 function writeDeck(f, content, manual = false) {
   ourWrites.set(f, { hash: hash(content), manual });
-  fs.writeFileSync(path.join(DECK_DIR, f), content);
+  writeAtomic(path.join(DECK_DIR, f), content);
+}
+/* Other files PinDeck writes into the deck (uploads, imported pictures, undo/redo of deleted files) */
+function writeDeckFile(rel, data, manual = true) {
+  const abs = path.join(DECK_DIR, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  ourWrites.set(rel, { hash: hash(data.toString("utf8")), manual });   // manual: no slide reload for a new file
+  writeAtomic(abs, data);
 }
 const snapshot = (files) => Object.fromEntries(files.map((f) => [f, readDeck(f)]));
-const json = (res, code, obj) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(obj)); };
+/* A change (a Claude turn or a hand edit) keeps each file it touched as it was before and after: text as
+   a string, or as a Buffer from a scan of the whole deck (null: the file did not exist). */
+const changeFiles = (t) => [...new Set([...Object.keys(t.before), ...Object.keys(t.after)])];
+const isText = (v) => v == null || typeof v === "string" || !v.includes(0);
+const asText = (v) => (v == null ? "" : String(v));
+const isAs = (rel, v) => sameContent(path.join(DECK_DIR, rel), v ?? null);
+function putDeckFile(rel, v) {   // undo and redo: back to v (null: remove the file)
+  if (v == null) return fs.rmSync(path.join(DECK_DIR, rel), { force: true });
+  fs.mkdirSync(path.dirname(path.join(DECK_DIR, rel)), { recursive: true });
+  writeDeck(rel, v);
+}
+function fileChange(rel, before, after) {
+  if (!isText(before) || !isText(after)) return { file: rel, added: 0, removed: 0, binary: true };
+  const d = unifiedDiff(asText(before), asText(after), rel);
+  return { file: rel, added: d.added, removed: d.removed };
+}
+const fileDiff = (rel, before, after) => (!isText(before) || !isText(after)
+  ? `Binary file ${rel} ${before == null ? "added" : after == null ? "deleted" : "changed"}`
+  : unifiedDiff(asText(before), asText(after), rel).text);
+/* The revision of the editable files: sent with every API answer, checked on the editor's changes */
+const deckRev = () => revision(DECK_DIR, EDITABLE);
+const json = (res, code, obj) => {
+  res.writeHead(code, { "content-type": "application/json", "x-deck-rev": deckRev() });
+  res.end(JSON.stringify(obj));
+};
+/* A change from the editor made on files that have changed since it loaded them: refused (409), nothing
+   written. The editor keeps the user's text and reloads. Requests without a revision (older tabs, the
+   notes sent while the tab closes) are not checked. */
+function staleEdit(res, b) {
+  if (b.rev == null || b.rev === deckRev()) return false;
+  json(res, 409, { code: "stale", rev: deckRev(),
+    error: "The deck changed outside PinDeck since this slide was shown, so your change was not saved. The slide has been reloaded." });
+  return true;
+}
 const text = (res, code, s) => { res.writeHead(code, { "content-type": "text/plain; charset=utf-8" }); res.end(s); };
 async function body(req) {
   let s = "";
@@ -115,12 +247,13 @@ setInterval(() => { for (const res of clients) res.write(": ping\n\n"); }, 20000
 let backedUp = false;
 function runEidPass() {
   const html = readDeck(DECK_FILE);
+  if (html == null) return { changed: false, assigned: [] };   // being replaced by another program: next time
   const r = assignEids(html);
   if (r.changed) {
     if (!backedUp) {
       const ts = new Date().toISOString().replace(/[:.]/g, "-");
-      fs.mkdirSync(path.join(STATE_DIR, "backups"), { recursive: true });
-      fs.writeFileSync(path.join(STATE_DIR, "backups", `index-${ts}.html`), html);
+      fs.mkdirSync(path.join(STATE_DIR, "backups"), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(path.join(STATE_DIR, "backups", `index-${ts}.html`), html, { mode: 0o600 });
       backedUp = true;
     }
     writeDeck(DECK_FILE, r.html);
@@ -137,11 +270,12 @@ function runEidPass() {
 let gitFilter = null;   // null: not checked yet
 const git = (args, cb) => execFile("git", ["-C", DECK_DIR, ...args], { encoding: "utf8" }, (err, out) => cb(err, (out || "").trim()));
 function refreshGit() {
-  const run = () => git(["hash-object", `--path=${DECK_FILE}`, DECK_FILE], (e1, cleaned) => {
+  // another git command (an IDE's `git status`) may hold the index lock: try again a few times, checking afresh
+  const run = (tries = 3) => git(["hash-object", `--path=${DECK_FILE}`, DECK_FILE], (e1, cleaned) => {
     if (e1 || !cleaned) return;
     git(["ls-files", "-s", "--", DECK_FILE], (e2, entry) => {
       const staged = entry.split(/\s+/)[1];
-      if (!e2 && staged === cleaned) git(["add", "--", DECK_FILE], () => {});
+      if (!e2 && staged === cleaned) git(["add", "--", DECK_FILE], (e3) => { if (e3 && tries > 1) setTimeout(() => run(tries - 1), 300); });
     });
   });
   if (gitFilter === null) {
@@ -163,23 +297,29 @@ function resolveSlide(spec) {
 }
 
 /* ---- Headless Chrome (screenshots, and layout when no editor tab is open) --------------- */
-const CHROME = [process.env.CHROME_BIN,
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-  "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"].find((p) => p && fs.existsSync(p));
+const CHROME = CAPS.chromePath;   // null when Chrome features are unavailable (see lib/capabilities.mjs)
 /* Headless Chrome on macOS often lingers long after it has written its output, so we
    watch the output and stop Chrome as soon as `done(stdout, stderr)` says we have it. */
 let chromeSeq = 0;
+/* The page gets the window's size too. Chrome lays it out about 87 px shorter than the window (room for
+   a toolbar it does not draw) and grows it only for the screenshot itself, too late for some versions
+   to lay the slide out again, so shot and dump lay the deck out for this size (see bridge.js). */
+function sized(url, size) {
+  const u = new URL(url);
+  u.searchParams.set("width", size.width);
+  u.searchParams.set("height", size.height);
+  return u.href;
+}
 function chrome(args, done) {
-  if (!CHROME) return Promise.reject(new Error("No Chrome/Chromium found (set CHROME_BIN)."));
+  if (!CHROME) return Promise.reject(new Error(`Screenshots are not available: ${CAPS.screenshot.reason}.`));
   return new Promise((resolve, reject) => {
     // a profile per run: concurrent runs must not share one
     const profile = path.join(STATE_DIR, "chrome", `p${process.pid}-${++chromeSeq}`);
+    const { size } = deckSlides();
     const proc = spawn(CHROME, ["--headless=new", "--disable-gpu", "--hide-scrollbars", "--no-first-run",
       "--no-default-browser-check", "--disable-extensions", "--mute-audio", `--user-data-dir=${profile}`,
-      "--window-size=1280,720", "--force-device-scale-factor=1", "--virtual-time-budget=5000", ...args]);
+      `--window-size=${size.width},${size.height}`, "--force-device-scale-factor=1", "--virtual-time-budget=5000",
+      ...args.map((a) => a.startsWith(ORIGIN + "/") ? chromeStart(profile, sized(a, size)) : a)]);
     let out = "", err = "", finished = false;
     const finish = (fn, v) => {
       if (finished) return;
@@ -193,12 +333,13 @@ function chrome(args, done) {
     proc.stdout.on("data", (d) => { out += d; check(); });
     proc.stderr.on("data", (d) => { err += d; check(); });
     proc.on("error", (e) => finish(reject, e));
-    proc.on("exit", () => (done(out, err) ? finish(resolve, out) : finish(reject, new Error("Chrome exited without output."))));
+    // "close", not "exit": at exit Chrome's last output (the line saying the file is written) may still be unread
+    proc.on("close", () => (done(out, err) ? finish(resolve, out) : finish(reject, new Error("Chrome exited without output."))));
     const timer = setTimeout(() => finish(reject, new Error("Chrome timed out.")), 25000);
   });
 }
 const deckUrl = (mode, params = {}) =>
-  `${ORIGIN}/deck/${DECK_FILE}?` + new URLSearchParams({ editor: mode, showHiddenSlides: "true", ...params });
+  `${ORIGIN}${DECK_PAGE}?` + new URLSearchParams({ editor: mode, showHiddenSlides: "true", ...params });
 async function takeShot(slide) {
   const pins = state.pins.filter((p) => p.slide.eid === slide.eid).map((p) => ({ n: p.n, eid: p.eid, at: p.at, point: p.point }));
   const out = path.join(SHOT_DIR, `${slide.eid.replace(/[^\w-]/g, "_")}-${Date.now()}.png`);
@@ -232,26 +373,31 @@ function measureInEditor(slide) {
     pending.set(id, { resolve, reject, t });
   });
 }
-const measure = (slide) => measureInEditor(slide).catch(() => measureHeadless(slide));
+const measure = (slide) => measureInEditor(slide).catch((e) => {
+  if (CAPS.headlessLayout.available) return measureHeadless(slide);
+  throw Object.assign(new Error(`Layout needs the editor open in a browser (${e.message}); ` +
+    `headless layout is not available: ${CAPS.headlessLayout.reason}.`), { status: 503 });
+});
 
 /* PDF export. handout: one page per slide, build steps in their final state.
    presentation: one page per build step (a slide with two clicks gives three pages).
    Files go to <deck>/export/. One export at a time. */
 let exportQueue = Promise.resolve(), snapSeq = 0;
-const snapshots = new Map();   // id -> static print layout, served at /deck/__pindeck-print-<id>.html
+const snapshots = new Map();   // id -> static print layout, served next to the deck page as __pindeck-print-<id>.html
 function exportPdf(kind, includeHidden = false) {
-  if (!CHROME) return Promise.reject(new Error("PDF export needs Chrome or Chromium (set CHROME_BIN)."));
+  if (!CAPS.pdfExport.available) return Promise.reject(Object.assign(new Error(`PDF export is not available: ${CAPS.pdfExport.reason}.`), { status: 501 }));
   const split = kind === "presentation";
-  const name = `${path.basename(DECK_DIR)}-${split ? "presentation" : "handout"}.pdf`;
+  const name = `${DECK_NAME}-${split ? "presentation" : "handout"}.pdf`;
   const out = path.join(DECK_DIR, "export", name);
   const profile = (step) => path.join(STATE_DIR, "chrome", `pdf-${process.pid}-${Date.now()}-${step}`);
   const run = async () => {
     fs.mkdirSync(path.dirname(out), { recursive: true });
-    const html = await printLayout(CHROME,
-      `${ORIGIN}/deck/${DECK_FILE}?editor=pdf&print-pdf&pdfSeparateFragments=${split}&showHiddenSlides=${!!includeHidden}`, profile("layout"));
+    const layoutProfile = profile("layout"), printProfile = profile("print");
+    const html = await printLayout(CHROME, chromeStart(layoutProfile,
+      `${ORIGIN}${DECK_PAGE}?editor=pdf&print-pdf&pdfSeparateFragments=${split}&showHiddenSlides=${!!includeHidden}`), layoutProfile);
     const id = `${process.pid}-${++snapSeq}`;
     snapshots.set(id, html);
-    try { await printPdf(CHROME, `${ORIGIN}/deck/__pindeck-print-${id}.html`, out, profile("print")); }
+    try { await printPdf(CHROME, chromeStart(printProfile, `${ORIGIN}${DECK_BASE}__pindeck-print-${id}.html`), out, printProfile); }
     finally { snapshots.delete(id); }
     return { kind: split ? "presentation" : "handout", path: out, rel: path.relative(DECK_DIR, out),
       url: `/deck/export/${encodeURIComponent(name)}`, bytes: fs.statSync(out).size };
@@ -273,9 +419,17 @@ try {
   const saved = JSON.parse(fs.readFileSync(CHAT_FILE, "utf8"));
   Object.assign(state, { chat: saved.chat || [], seq: saved.seq || 0, sessionId: saved.sessionId || null, provider: saved.provider || "claude", handover: saved.handover || "", sessionArchive: saved.sessionArchive || [] });
 } catch {}
-const saveChat = () => fs.writeFileSync(CHAT_FILE,
-  JSON.stringify({ chat: state.chat.slice(-400), seq: state.seq, sessionId: state.sessionId,
-    provider: state.provider, handover: state.handover, sessionArchive: state.sessionArchive.slice(-50) }));
+/* Saved shortly after the last change, in one atomic write: overlapping writes could leave a broken file. */
+let chatTimer = null;
+function writeChat() {
+  clearTimeout(chatTimer);
+  chatTimer = null;
+  try {
+    writeAtomic(CHAT_FILE, JSON.stringify({ chat: state.chat.slice(-400), seq: state.seq, sessionId: state.sessionId,
+      provider: state.provider, handover: state.handover, sessionArchive: state.sessionArchive.slice(-50) }));
+  } catch (e) { console.error(e.message); }
+}
+const saveChat = () => { chatTimer ??= setTimeout(writeChat, 100); };
 function addEntry(entry) {
   entry.id = ++state.seq;
   entry.time = Date.now();
@@ -291,56 +445,120 @@ const changeLabel = (t) => (t ? (t.kind === "manual" ? t.label : "AI change") :
 const CONFIG_FILE = path.join(HOME_DIR, "config.json");
 let fileConfig = {};
 try { fileConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8")); }
-catch (e) { if (e.code !== "ENOENT") console.warn("Invalid PinDeck configuration; using defaults."); }
+catch (e) { if (e.code !== "ENOENT") console.warn(`${CONFIG_FILE} is not valid JSON; using the defaults.`); }
 const settings = migrateSettings(fileConfig);
 let effortPreferences = Object.fromEntries(Object.entries(fileConfig.effortPreferences || {}).filter(([, value]) => typeof value === "string"));
 // Preserve the legacy selection as the first model-specific preference.
 if (settings.effort) effortPreferences[`${settings.provider}:${settings.model}`] = settings.effort;
 if (PROVIDER) {
-  if (!["claude", "codex"].includes(PROVIDER)) throw new Error("Use --provider claude or codex.");
+  if (!["claude", "codex"].includes(PROVIDER)) { console.error(`Unknown provider "${PROVIDER}": use claude or codex.\n\n${USAGE}`); process.exit(2); }
   settings.provider = PROVIDER;
   if (!MODEL && PROVIDER !== fileConfig.provider) settings.model = PROVIDER === "claude" ? "sonnet" : "";
 }
-if (MODEL) settings.model = MODEL;
+if (MODEL) settings.model = MODEL;   // --model on the command line: this run only, not saved
 // A saved chat belongs to its provider, never to whichever CLI happens to be selected now.
 if (state.provider !== settings.provider) { state.sessionId = null; state.handover = ""; }
 state.provider = settings.provider;
+/* Asset roots (--asset-root, and "assetRoots" in config.json): folders outside the deck whose files the
+   deck may use. The outermost one that contains the deck is served at /files/, with the deck page inside
+   it, so a relative path such as ../shared/style.css reaches its file. Every file served, from the deck
+   or from /files/, must really lie (after following symlinks) inside the deck folder or an asset root:
+   a symlink that leads anywhere else is refused. */
+const expandHome = (p) => (p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p);
+const ASSET_ROOTS = [...assetArgs, ...(Array.isArray(fileConfig.assetRoots) ? fileConfig.assetRoots : [])].map((r) => {
+  const abs = path.resolve(expandHome(String(r)));
+  let st = null;
+  try { st = fs.statSync(abs); } catch {}
+  if (!st?.isDirectory()) { console.error(`Asset root ${abs} is not a folder.\n\n${USAGE}`); process.exit(2); }
+  return abs;
+});
+const within = (dir, p) => p === dir || p.startsWith(dir + path.sep);
+const realOr = (p) => { try { return fs.realpathSync(p); } catch { return p; } };
+const SERVE_ROOT = ASSET_ROOTS.filter((r) => within(r, DECK_DIR)).sort((a, b) => a.length - b.length)[0] || null;
+const ALLOWED_REAL = [DECK_DIR, ...ASSET_ROOTS].map(realOr);
+const encPath = (rel) => rel.split(path.sep).filter(Boolean).map(encodeURIComponent).join("/");
+/* The deck page's URL, and the folder URL its relative paths resolve against */
+const DECK_PAGE = SERVE_ROOT ? `/files/${[encPath(path.relative(SERVE_ROOT, DECK_DIR)), encodeURIComponent(DECK_FILE)].filter(Boolean).join("/")}`
+  : `/deck/${encodeURIComponent(DECK_FILE)}`;
+const DECK_BASE = DECK_PAGE.slice(0, DECK_PAGE.lastIndexOf("/") + 1);
+/* A file to serve: inside its base by path, and inside the deck or an asset root once symlinks are
+   followed. null: refuse. A missing file passes, and is answered 404. */
+function servable(base, rel) {
+  const f = safeJoin(base, rel);
+  if (!f) return null;
+  let real;
+  try { real = fs.realpathSync(f); } catch { return f; }
+  return ALLOWED_REAL.some((d) => within(d, real)) ? f : null;
+}
+
 let catalog = { claude: { models: [] }, codex: { models: [] } }, discovering = null;
 let session = null, starting = null;
 const status = () => ({ busy: state.busy, switching: state.switching, model: state.model, sessionId: state.sessionId, settings: { ...settings },
-  running: !!session?.running, provider: settings.provider, models: catalog, deck: DECK_DIR, deckFile: DECK_FILE, chrome: !!CHROME,
+  running: !!session?.running, provider: settings.provider, models: catalog, deck: DECK_DIR, deckFile: DECK_FILE,
+  chrome: CAPS.screenshot.available, slideSelector: deckNow.selector, deckProblem: deckNow.problem,
+  capabilities: publicCapabilities(CAPS), rev: deckRev(),
   undo: changeLabel(liveTurns().at(-1)), redo: changeLabel(state.redo.at(-1)) });
 const pushStatus = () => broadcast("status", status());
 
 const systemPrompt = fs.readFileSync(path.join(EDITOR_DIR, "lib/system-prompt.md"), "utf8")
-  .replaceAll("{{CLI}}", CLI_CMD);
+  .replaceAll("{{CLI}}", CLI_CMD).replaceAll("{{DECK}}", DECK_FILE) + capabilityPrompt(CAPS, CLI_CMD) +
+  // a template's own notes usually say index.html; other decks may share this folder
+  (NAMED ? `\n\n## This deck's file\nThe slides are in ${DECK_FILE}. Where the deck's notes below say index.html, they mean ` +
+    `${DECK_FILE}. Other .html files in this folder are other decks: do not edit them.\n` : "") +
+  (ASSET_ROOTS.length ? `\n\n## Files outside the deck folder\nThe deck may use files in ${ASSET_ROOTS.join(", ")}: refer to ` +
+    `them with paths relative to ${DECK_FILE} (such as ../shared/style.css). You can read them; do not edit them, ` +
+    `other decks may use them too.\n` : "");
+/* For a deck made without reveal.js: what its slides are, from its selector as it is at each session start */
+function slidesInstructions() {
+  const { selector } = deckSlides();
+  return selector ? `\n\n## Slides of this deck\nThis deck is not made with reveal.js: its slides are the elements matching the ` +
+    `CSS selector \`${selector}\` (<meta name="pindeck:slides">), and the deck's own script shows them. Where these ` +
+    `instructions say <section> or reveal.js, read an element matching that selector, and that script. A new slide is ` +
+    `a new such element next to the others; keep the pindeck meta tags. Hidden slides (data-visibility="hidden") are ` +
+    `left out of PinDeck's PDF exports; whether presenting skips them depends on the deck's script.\n` : "";
+}
+/* What Claude may never change, whatever the edit rules allow: the locked brand files, vendored libraries,
+   git's own files, and other decks in this folder (a named deck shares its folder with them). Deny rules
+   win over allow rules; a locked file changed anyway is restored after the turn (lock 2 in finishTurn). */
+function lockedPaths() {
+  let others = [];
+  try { others = fs.readdirSync(DECK_DIR).filter((f) => /\.html?$/i.test(f) && f !== DECK_FILE); } catch {}
+  return [...LOCKED, "vendor/**", ".git/**", ...others];
+}
 /* Claude Code loads no settings files (--setting-sources ""): an allow rule in the user's, the deck's
    or a parent repo's settings would let Claude run more than PinDeck grants (and the user's hooks and
-   MCP servers have no place in a slide editor). That also skips the deck's CLAUDE.md, so it goes into
-   the system prompt instead, read afresh at each session start. */
+   MCP servers have no place in a slide editor). That also skips CLAUDE.md files, so the deck's own go
+   into the system prompt instead, read afresh at each session start: CLAUDE.md and AGENTS.md (the name
+   other coding agents read), with their @path imports (lib/instructions.mjs). Parent folders' files are
+   not loaded; a deck imports shared rules explicitly. Decks copied from the example call the CLI as
+   `node ../cli.mjs`, which is right only next to PinDeck: that becomes this server's command. */
 function deckInstructions() {
-  try { return `\n\n## The deck's CLAUDE.md\n${fs.readFileSync(path.join(DECK_DIR, "CLAUDE.md"), "utf8").trim()}\n`; }
-  catch { return ""; }
+  return ["CLAUDE.md", "AGENTS.md"].map((name) => {
+    const s = readInstructions(path.join(DECK_DIR, name));
+    return s ? `\n\n## The deck's ${name}\n${s.replace(/node \.\.\/cli\.mjs\b/g, () => CLI_CMD)}\n` : "";
+  }).join("");
 }
-const agentTools = createDeckTools({ deckDir: DECK_DIR, readDirs: [SHOT_DIR, PDF_DIR],
-  cliFile: path.join(EDITOR_DIR, "cli.mjs"), pdfTextFile: path.join(EDITOR_DIR, "lib/pdf-text.jxa.js"),
-  env: { DECK_EDITOR_URL: ORIGIN, DECK_EDITOR_TOKEN: TOKEN } });
+// a function: ORIGIN is known only once the port is bound
+const agentEnv = () => ({ DECK_EDITOR_URL: ORIGIN, DECK_EDITOR_TOKEN: TOKEN });
+const agentTools = createDeckTools({ deckDir: DECK_DIR, deckFile: DECK_FILE, readDirs: [SHOT_DIR, PDF_DIR, ...ASSET_ROOTS],
+  locked: lockedPaths, cliFile: path.join(EDITOR_DIR, "cli.mjs"), pdfTextFile: path.join(EDITOR_DIR, "lib/pdf-text.jxa.js"),
+  env: agentEnv });
 const codexInstructions = () => systemPrompt.replace(/## Attached files[\s\S]*?## Hand edits/, `## Tools and attachments
 Figures and audio are already saved under figures/. Keep their paths and use the deck's existing figure/audio patterns. Do not rename or move attachments.
 Use pindeck_read for text files, images and PDF pages (supply page: 1, then further pages as needed).
-Use pindeck_edit for exact replacements in index.html and theme.css. Never change brand.css.
+Use pindeck_edit for exact replacements in ${DECK_FILE}, theme.css and the deck's other files, and pindeck_write to create a new file in the deck folder. Never change brand.css.
 Use pindeck_command with separate command and args for layout, shot, slides, pdf or pdf-figure.
 Do not use shell commands, native file edits, or other tools to bypass these restrictions.
 When context mentions Read, use pindeck_read. Read screenshots with pindeck_read.
 Read README.md and the deck instructions below for conventions. Use layout after every visual change.
 PDF tables should be reconstructed as HTML; pdf-figure renders figures. Audio is embedded by path.
 
-## Hand edits`) + deckInstructions();
+## Hand edits`) + slidesInstructions() + deckInstructions();
 function makeSession(choice) {
   let initial = null;
   const options = {
     cwd: DECK_DIR,
-    env: { DECK_EDITOR_URL: ORIGIN, DECK_EDITOR_TOKEN: TOKEN },
+    env: agentEnv,
     onEvent: ev => {
       if (ev.type === "system" && ev.subtype === "init") initial = ev;
       if (session === agent) handleEvent(ev);
@@ -351,40 +569,57 @@ function makeSession(choice) {
       pushStatus();
     },
   };
+  /* Claude Code: any file in the deck folder (Edit rules cover Write too; Write is named as well, to be
+     explicit), PinDeck's own commands, never the locked paths. Deny rules win over allow rules. */
   const agent = choice.provider === "codex" ? new CodexSession({ ...options, settings: choice,
     instructions: codexInstructions(), tools: agentTools }) : new ClaudeSession({ ...options,
-    args: ["--append-system-prompt", systemPrompt + deckInstructions(),
-      "--setting-sources", "", "--strict-mcp-config", "--safe-mode", "--disable-slash-commands",
-      "--permission-mode", "default", "--tools", "Read,Glob,Grep,Edit,Bash",
-      "--allowedTools", "Read", "Glob", "Grep", ...EDITABLE.map(f => `Edit(./${f})`), ...["layout", "shot", "slides", "pdf", "pdf-figure"].map(command => `Bash(${CLI_CMD} ${command}:*)`),
-      "--disallowedTools", ...LOCKED.flatMap(f => [`Edit(./${f})`, `Write(./${f})`]),
+    args: () => ["--append-system-prompt", systemPrompt + slidesInstructions() + deckInstructions(),
+      "--setting-sources", "", "--strict-mcp-config", "--safe-mode", "--disable-slash-commands",   // no settings files, no MCP servers or connectors
+      "--permission-mode", "default", "--tools", "Read,Glob,Grep,Edit,Write,Bash",
+      "--allowedTools", "Read", "Glob", "Grep", "Edit(./**)", "Write(./**)",
+      ...["layout", "shot", "slides", "pdf", "pdf-figure"].map(command => `Bash(${CLI_CMD} ${command}:*)`),
+      "--disallowedTools", ...lockedPaths().flatMap((f) => [`Edit(./${f})`, `Write(./${f})`]),
       ...(choice.model ? ["--model", choice.model] : []), ...(choice.effort ? ["--effort", choice.effort] : [])],
   });
   agent.initialEvent = () => initial;
   return agent;
 }
+const providerAvailable = (provider) => detectCapabilities()[provider];
+/* Every backend process that is stopped is waited for on exit: the discovery helpers, the session a switch
+   replaced, the current one. */
+const retiring = new Set(), discoveryAgents = new Set();
+function retire(agent) {
+  if (!agent) return;
+  const stopped = agent.stop();
+  retiring.add(stopped);
+  stopped.finally(() => retiring.delete(stopped));
+}
 async function discoverModels() {
   if (discovering) return discovering;
   discovering = Promise.all(["claude", "codex"].map(async provider => {
+    if (!providerAvailable(provider).available) { catalog[provider] = { models: [], error: providerAvailable(provider).reason }; return; }
     const agent = makeSession({ provider, model: "", effort: null });
+    discoveryAgents.add(agent);
     try {
       if (provider === "codex") await agent.connect(); else await agent.start();
       catalog[provider] = { models: curateModels(provider, agent.models || []), error: null };
     } catch (e) { catalog[provider] = { models: [], error: e.message }; }
-    finally { agent.stop(); }
+    finally { discoveryAgents.delete(agent); retire(agent); }
   })).then(() => { pushStatus(); return catalog; }).finally(() => { discovering = null; });
   return discovering;
 }
 async function ensureSession() {
   if (starting) return starting;
-  if (session?.running) return;
+  if (session?.running || quitting) return;
+  const available = providerAvailable(settings.provider);
+  if (!available.available) throw new Error(available.reason);
   starting = (async () => {
     if (!catalog[settings.provider].models.length) await discoverModels();
     Object.assign(settings, selectModel(catalog, settings, {}));
     const agent = makeSession({ ...settings });
     session = agent;
     try { await agent.start(state.sessionId); if (session === agent) pushStatus(); }
-    catch (e) { agent.stop(); throw e; }
+    catch (e) { retire(agent); throw e; }
   })().finally(() => { starting = null; });
   return starting;
 }
@@ -415,12 +650,12 @@ async function changeSettings(requested) {
     if (reuse) candidate.settings = choice;
     session = candidate;
     if (!reuse && candidate.initialEvent()) handleEvent(candidate.initialEvent());
-    if (!reuse) old?.stop();
+    if (!reuse) retire(old);
     saveChat();
     addEntry({ kind: "notice", text: changingProvider
       ? `Switched to ${choice.provider === "codex" ? "OpenAI / ChatGPT" : "Claude"} · ${summary ? "Conversation summary will be shared" : "New conversation"}.`
       : `Model: ${choice.model}${choice.effort ? ` · ${choice.effort} effort` : ""}. The conversation continues.` });
-  } catch (e) { if (session !== candidate) candidate.stop(); throw e; }
+  } catch (e) { if (session !== candidate) retire(candidate); throw e; }
   finally { state.busy = false; state.switching = false; pushStatus(); }
 }
 
@@ -433,7 +668,7 @@ function toolSummary(name, input = {}) {
   };
   switch (name) {
     case "pindeck_read": return { name: "Read", detail: base(input.path) };
-    case "pindeck_edit": return { name: "Edit", detail: base(input.path) };
+    case "pindeck_edit": case "pindeck_write": return { name: "Edit", detail: base(input.path) };
     case "pindeck_command": return { name: input.command || "Command", detail: (input.args || []).join(" ") };
     case "Read": return { name: "Read", detail: base(input.file_path) };
     case "Edit": case "MultiEdit": case "Write": return { name: "Edit", detail: base(input.file_path) };
@@ -480,7 +715,9 @@ function handleEvent(ev) {
 }
 
 function startTurn(promptText, userEntry) {
-  state.turn = { id: userEntry.id, before: snapshot([...EDITABLE, ...LOCKED]) };
+  // every deck file as it is now: the assistant may change any of them (not brand.css or vendor/), and undo
+  // takes back all it changed
+  state.turn = { id: userEntry.id, before: snapshot([...EDITABLE, ...LOCKED]), scan: scanFiles(DECK_DIR) };
   state.busy = true;
   pushStatus();
   const turn = state.turn;
@@ -509,11 +746,13 @@ function finishTurn({ error, cost, duration, denials = [] }) {
   }
   toolEntries.clear();
   const eid = runEidPass();
-  const after = snapshot(EDITABLE);
-  const files = EDITABLE.map((f) => {
-    const d = unifiedDiff(turn.before[f] ?? "", after[f] ?? "", f);
-    return { file: f, added: d.added, removed: d.removed };
-  }).filter((f) => f.added || f.removed);
+  const { changed, tooLarge } = scanChanges(turn.scan, scanFiles(DECK_DIR));
+  const before = {}, after = {};
+  for (const [rel, c] of Object.entries(changed)) { before[rel] = c.before; after[rel] = c.after; }
+  // the deck file and theme.css first, then the rest by name
+  const order = (rel) => (EDITABLE.includes(rel) ? EDITABLE.indexOf(rel) : EDITABLE.length);
+  const files = Object.keys(changed).sort((a, b) => order(a) - order(b) || a.localeCompare(b))
+    .map((rel) => fileChange(rel, before[rel], after[rel]));
   // after a hand-off: imported pictures that the assistant replaced (nothing refers to them any more) are
   // deleted; undo brings them back with the turn
   const deletedFiles = [];
@@ -523,11 +762,13 @@ function finishTurn({ error, cost, duration, denials = [] }) {
     deletedFiles.push({ rel, data: fs.readFileSync(abs) });
     fs.rmSync(abs, { force: true });
   }
-  const t = { id: turn.id, kind: "agent", provider: settings.provider, before: turn.before, after, files, deletedFiles, undone: false };
+  const t = { id: turn.id, kind: "agent", provider: settings.provider, before, after, files, deletedFiles, undone: false };
   if (files.length) { state.turns.push(t); state.redo = []; }
   addEntry({ kind: "turn", turnId: files.length ? t.id : null, files, error, cost, duration,
     denials, restored, newIds: eid.assigned.length });
   if (deletedFiles.length) addEntry({ kind: "notice", text: `Removed ${deletedFiles.map((f) => f.rel).join(", ")}: replaced, and no longer used.` });
+  if (tooLarge.length) addEntry({ kind: "notice", text: `${tooLarge.join(", ")} changed in this turn but ${tooLarge.length > 1 ? "are" : "is"} ` +
+    `too large to keep a copy of (over 2 MB): Undo leaves ${tooLarge.length > 1 ? "them" : "it"} as ${tooLarge.length > 1 ? "they are" : "it is"}.` });
   pushStatus();
 }
 
@@ -586,7 +827,7 @@ function buildPrompt({ text: userText, pins = [], selection, layouts = [], curre
   for (const L of layouts) ctx.push("Layout:\n" + formatLayout(L));
   if (screenshot) ctx.push(`Screenshot of slide ${screenshot.slide} with the pin markers: ${screenshot.path} (Read it).`);
   if (attachments.length) ctx.push("Attached files (the user added them to this message; they are saved in the deck folder, " +
-    "use these paths relative to index.html):\n" + attachments.map((a) => formatAttachment(a) + formatDrop(a)).join("\n"));
+    `use these paths relative to ${DECK_FILE}):\n` + attachments.map((a) => formatAttachment(a) + formatDrop(a)).join("\n"));
   return (ctx.length ? `<editor-context>\n${ctx.join("\n\n")}\n</editor-context>\n\n` : "") + userText;
 }
 
@@ -595,7 +836,7 @@ function buildPrompt({ text: userText, pins = [], selection, layouts = [], curre
    screenshots folder, for the assistant to look at before choosing; with one, into the deck. */
 async function pdfFigure({ file = "", page = "1", box = "", out = "", width = "", cancelled = () => false }) {
   const bad = (t, status = 400) => ({ status, text: t });
-  if (process.platform !== "darwin") return bad("Rendering PDF pages needs macOS (PDFKit).", 501);
+  if (!CAPS.pdfPages.available) return bad(CAPS.pdfPages.reason, 501);
   const abs = [path.isAbsolute(file) ? file : path.join(DECK_DIR, file), path.join(PDF_DIR, path.basename(file))]
     .map((f) => path.resolve(f)).find((f) => /\.pdf$/i.test(f) && fs.existsSync(f) &&
       [DECK_DIR, PDF_DIR].some((d) => f.startsWith(d + path.sep)));
@@ -613,24 +854,31 @@ async function pdfFigure({ file = "", page = "1", box = "", out = "", width = ""
   if (out && fs.existsSync(path.join(DECK_DIR, out)) && !state.pdfFigures.has(out)) return bad(`${out} exists already; choose another name.`, 409);
   const tmp = path.join(SHOT_DIR, `pdf-${slug(path.basename(abs, ".pdf"))}-p${n}-${Date.now()}.png`);
   await renderJobs(abs, [{ page: n, out: tmp, box: pts, scale }], STATE_DIR, { slideWidth: pw });
-  if (!fs.existsSync(tmp)) return bad("PDFKit did not write the picture.", 500);
+  if (!fs.existsSync(tmp)) return bad("The PDF page could not be rendered.", 500);
   const size = `${Math.round(pts[2] * scale)} × ${Math.round(pts[3] * scale)} px`;
   if (cancelled()) return bad("The request was cancelled before the figure could be saved.", 409);
   if (!out) return { text: `${tmp} (${size}). Read it; add a figures/ name to save it into the deck.` };
   const buf = fs.readFileSync(tmp);
   fs.rmSync(tmp, { force: true });
-  fs.mkdirSync(path.join(DECK_DIR, "figures"), { recursive: true });
-  ourWrites.set(out, { hash: hash(buf.toString("utf8")), manual: true });   // no slide reload for a new file
-  fs.writeFileSync(path.join(DECK_DIR, out), buf);
+  writeDeckFile(out, buf);
   state.pdfFigures.add(out);
   return { text: `${out} (${size})` };
 }
 
-/* ---- File watching -------------------------------------------------------------------------- */
-let changed = new Set(), flush = null, eidTimer = null;
-fs.watch(DECK_DIR, { recursive: true }, (_ev, file) => {
-  if (!file || /(^|\/)\.|\.bak$|~$|^export[\/]/.test(file)) return;
-  changed.add(file.split(path.sep).join("/"));
+/* ---- File watching --------------------------------------------------------------------------
+   Changes are collected for 120 ms and sent to the editor with the deck's revision, so a tab that missed
+   events (reconnect) can still tell that it shows an old state. Dot files (PinDeck's temporary files,
+   editors' swap files), backups and export/ are ignored. If the watcher fails (folder replaced, too many
+   files), it is started again and the editor told to reload everything. */
+let changed = new Set(), flush = null, eidTimer = null, watcher = null;
+function onFileEvent(_ev, file) {
+  if (!file) { changed.add(DECK_FILE); return scheduleFlush(); }   // some systems omit the name: assume the deck
+  file = String(file).split(path.sep).join("/");
+  if (/(^|\/)\.|\.bak$|~$|^export\//.test(file)) return;
+  changed.add(file);
+  scheduleFlush();
+}
+function scheduleFlush() {
   clearTimeout(flush);
   flush = setTimeout(() => {
     const files = [...changed];
@@ -646,14 +894,79 @@ fs.watch(DECK_DIR, { recursive: true }, (_ev, file) => {
     if (external) {
       state.notes = [...new Set([...state.notes,
         "The deck files changed outside this chat since your last turn (edited by hand or by another tool). Re-read before editing."])];
-      // new elements from a hand edit get ids once the file is quiet
+      // new elements from a hand edit get ids once the file is quiet: unchanged for 800 ms and present
       clearTimeout(eidTimer);
-      eidTimer = setTimeout(() => { if (!state.busy) runEidPass(); }, 800);
+      const seen = hash(readDeck(DECK_FILE) ?? "");
+      const pass = () => {
+        if (state.busy) return;
+        const now = readDeck(DECK_FILE);
+        if (now == null || hash(now) !== seen) return;   // still being written; its own event comes
+        runEidPass();
+      };
+      eidTimer = setTimeout(pass, 800);
+    }
+    if (files.includes(DECK_FILE)) {   // the slide tags, by hand or by Claude: tell both when they stop working
+      const now = { selector: deckSlides().selector, problem: deckProblemNow() };
+      if (now.selector !== deckNow.selector || now.problem !== deckNow.problem) {
+        if (now.problem) state.notes = [...new Set([...state.notes, `PinDeck cannot use the deck's slides now: ${now.problem}`])];
+        deckNow = now;
+        pushStatus();
+      }
     }
     // manual: only drag/resize writes, which the browser already shows; no reload of the visible slide
-    broadcast("files", { files, manual });
+    broadcast("files", { files, manual, rev: deckRev() });
   }, 120);
-});
+}
+/* Linux: Node's recursive watch follows files by inode there, and loses a file once it is replaced by a
+   rename, the way most editors and PinDeck itself save: later changes to index.html went unseen. Watching
+   every folder (inotify on directories) keeps working; folders created later are added as they appear.
+   Hidden folders (.git) and node_modules are skipped. */
+function watchFolders(root, onEvent) {
+  const watchers = new Map(), tree = new EventEmitter();
+  const add = (dir) => {
+    if (watchers.has(dir)) return;
+    let w;
+    try {
+      w = fs.watch(dir, (ev, name) => {
+        if (name == null) return onEvent(ev, null);
+        const abs = path.join(dir, String(name));
+        if (ev === "rename") { try { if (fs.statSync(abs).isDirectory()) scan(abs); } catch {} }
+        onEvent(ev, path.relative(root, abs));
+      });
+    } catch (e) {
+      if (dir === root) throw e;
+      return;
+    }
+    w.on("error", (e) => {
+      try { w.close(); } catch {}
+      watchers.delete(dir);
+      if (dir === root) tree.emit("error", e);   // a removed subfolder just drops out
+    });
+    watchers.set(dir, w);
+  };
+  const scan = (dir) => {
+    add(dir);
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch {}
+    for (const d of entries) if (d.isDirectory() && !d.name.startsWith(".") && d.name !== "node_modules") scan(path.join(dir, d.name));
+  };
+  scan(root);
+  tree.close = () => { for (const w of watchers.values()) try { w.close(); } catch {} watchers.clear(); };
+  return tree;
+}
+function startWatcher() {
+  watcher = process.platform === "linux" ? watchFolders(DECK_DIR, onFileEvent)
+    : fs.watch(DECK_DIR, { recursive: true }, onFileEvent);
+  watcher.on("error", (e) => {
+    console.error(`Watching ${DECK_DIR} failed (${e.message}); starting again.`);
+    try { watcher.close(); } catch {}
+    setTimeout(() => {
+      if (quitting) return;
+      try { startWatcher(); } catch (e2) { console.error(`Cannot watch ${DECK_DIR}: ${e2.message}`); }
+      broadcast("files", { files: [...EDITABLE], manual: false, rev: deckRev(), resync: true });
+    }, 1000);
+  });
+}
 
 /* ---- Hand edits ----------------------------------------------------------------------------------------- */
 function recordHandEdit(before, html, label, note, { manual = true, deletedFiles = [], addedFiles = [], chat = true } = {}) {
@@ -690,21 +1003,42 @@ function deletePlan(eid) {
   return { ...target, html: rest, files };
 }
 
-/* ---- Undo (assistant turns and hand edits share one history) ---------------------------------------- */
+/* ---- Undo (assistant turns and hand edits share one history) ---------------------------------------
+   Undo puts back the files as they were before a change, Redo as they were after it. Both first check that
+   every file they touch is exactly as that change left it (or, for Redo, as the undo left it): the editable
+   files, and the pictures or audio files they would delete or bring back. Anything else means the files
+   were changed since, by hand or by another program, and going back would silently throw that work away.
+   Then nothing is written and the answer is 409 with the files that differ. */
+function undoConflicts(t, direction) {
+  const expect = direction === "undo" ? t.after : t.before;
+  const files = changeFiles(t).filter((rel) => !isAs(rel, expect[rel]));
+  // undo brings deleted files back (their place must be free, or hold the same bytes) and removes added
+  // ones (which must be unchanged); redo the other way round
+  const comeBack = direction === "undo" ? t.deletedFiles || [] : t.addedFiles || [];
+  const go = direction === "undo" ? t.addedFiles || [] : t.deletedFiles || [];
+  for (const { rel, data } of comeBack) {
+    const abs = path.join(DECK_DIR, rel);
+    if (fs.existsSync(abs) && !sameContent(abs, data)) files.push(rel);
+  }
+  for (const { rel, data } of go) {
+    const abs = path.join(DECK_DIR, rel);
+    if (fs.existsSync(abs) && !sameContent(abs, data)) files.push(rel);
+  }
+  return files;
+}
+function conflict(res, direction, files) {
+  json(res, 409, { code: "diverged", files,
+    error: `${files.join(", ")} changed since then (edited outside PinDeck?), so ${direction === "undo" ? "Undo" : "Redo"} was not done: ` +
+      `it would overwrite those changes. Reload to see the files as they are.` });
+}
 function undo(res) {
   if (state.busy) return json(res, 409, { error: "Wait until the assistant has finished." });
   const t = liveTurns().at(-1);
   if (!t) return json(res, 409, { error: "Nothing to undo." });
-  const edited = EDITABLE.some((f) => readDeck(f) !== t.after[f]);
-  for (const f of EDITABLE) {
-    if (readDeck(f) === t.before[f]) continue;
-    if (t.before[f] != null) writeDeck(f, t.before[f]);
-    else fs.rmSync(path.join(DECK_DIR, f), { force: true });   // the change created the file
-  }
-  for (const { rel, data } of t.deletedFiles || []) {   // files deleted with an element come back too
-    fs.mkdirSync(path.dirname(path.join(DECK_DIR, rel)), { recursive: true });
-    fs.writeFileSync(path.join(DECK_DIR, rel), data);
-  }
+  const diverged = undoConflicts(t, "undo");
+  if (diverged.length) return conflict(res, "undo", diverged);
+  for (const rel of changeFiles(t)) if (!isAs(rel, t.before[rel])) putDeckFile(rel, t.before[rel] ?? null);   // null: the change created it
+  for (const { rel, data } of t.deletedFiles || []) writeDeckFile(rel, data, false);   // files deleted with an element come back too
   for (const { rel } of t.addedFiles || []) fs.rmSync(path.join(DECK_DIR, rel), { force: true });   // imported figures go
   t.undone = true;
   state.redo.push(t);
@@ -712,7 +1046,6 @@ function undo(res) {
     ? `The user undid their hand edit (${t.label}); ${DECK_FILE} is back to the state before it.`
     : `The user undid your change from turn ${t.id}; ${t.files.map((f) => f.file).join(" and ")} are back to the state before it. Re-read before editing.`);
   broadcast("undone", { turnId: t.id, undone: true });
-  if (edited) addEntry({ kind: "notice", text: "Undone. Edits made after that change were reverted too." });
   pushStatus();
   return json(res, 200, {});
 }
@@ -724,7 +1057,6 @@ function undo(res) {
 const IMPORT_DIR = path.join(STATE_DIR, "imports");
 const IMPORT_MAX = 500 * 1024 * 1024;
 let lastImport = null;   // { id, name, dir, model, render: Promise<pdf path | null>, renderError }
-fs.rmSync(IMPORT_DIR, { recursive: true, force: true });
 
 function startImport(name, buf) {
   const model = readPptx(buf);   // first: a file that cannot be read leaves the previous import as it was
@@ -771,12 +1103,7 @@ async function applyImport(imp, numbers, afterEid, refine = false) {
   const ls = html0.lastIndexOf("\n", after.start - 1) + 1;
   const indent = /^\s*$/.test(html0.slice(ls, after.start)) ? html0.slice(ls, after.start) : "";
   const html = assignEids(html0.slice(0, end) + r.fragments.map((f) => `\n\n${indent}` + f).join("") + html0.slice(end)).html;
-  for (const f of r.files) {
-    const abs = path.join(DECK_DIR, f.rel);
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    ourWrites.set(f.rel, { hash: hash(f.data.toString("utf8")), manual: true });   // no reload for each new file
-    fs.writeFileSync(abs, f.data);
-  }
+  for (const f of r.files) writeDeckFile(f.rel, f.data);   // manual: no reload for each new file
   const all = findSlides(parse(html));
   const first = afterIdx + 1, last = afterIdx + r.fragments.length;
   const eids = all.slice(first, last + 1).map((s) => s.attrs["data-eid"]?.value);
@@ -834,68 +1161,172 @@ async function refineImport(imp, pdf, plans, eids, first) {
 
 /* ---- HTTP ------------------------------------------------------------------------------------- */
 const BRIDGE_TAG = `<script src="/editor/bridge.js"></script>\n</body>`;
-const HOSTS = new Set([`127.0.0.1:${PORT}`, `localhost:${PORT}`]);
+/* 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. */
+const goodHost = (h) => /^(127\.0\.0\.1|localhost)(:\d{1,5})?$/.test(h);
 
-function serveFile(res, file, transform) {
-  fs.readFile(file, (err, data) => {
+/* Who may read the editor, the deck and the API. The token never appears in a page or on a command line,
+   where other users of a shared server could read it (ps, curl). A browser logs in once with a one-time
+   code (printed at start, or by `pindeck login`) and then holds the token in an HttpOnly cookie; the CLI
+   and Claude send it in a header. Browsers share cookies across all ports of a host, so the cookie name
+   carries this server's port. */
+const loginCodes = new Map();   // code -> expiry (ms)
+function loginCode(ttl) {
+  const now = Date.now();
+  for (const [c, exp] of loginCodes) if (exp < now) loginCodes.delete(c);
+  const code = crypto.randomBytes(16).toString("hex");
+  loginCodes.set(code, now + ttl);
+  return code;
+}
+const loginUrl = (code, next = "/") => `${ORIGIN}/login?` + new URLSearchParams({ code, ...(next !== "/" ? { next } : {}) });
+const cookieName = () => `pindeck-${PORT}`;
+const sameSecret = (a) => typeof a === "string" && a.length === TOKEN.length &&
+  crypto.timingSafeEqual(Buffer.from(a), Buffer.from(TOKEN));
+function cookie(req, name) {
+  for (const part of String(req.headers.cookie || "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+  }
+  return null;
+}
+const authed = (req) => sameSecret(req.headers["x-editor-token"]) || sameSecret(cookie(req, cookieName()));
+const LOGIN_PAGE = `<!doctype html><meta charset="utf-8"><title>PinDeck</title>
+<body style="font:16px system-ui,sans-serif;max-width:36em;margin:4em auto;padding:0 1em">
+<h1>Log in to PinDeck</h1><p>Open the login link that PinDeck printed when it started. Links work once;
+for a new one, run <code>pindeck login</code> in the deck folder (or <code>node server.mjs login</code> in a
+PinDeck checkout).</p>`;
+/* A one-time code: set the cookie, then go on with a same-origin navigation (a redirect from a cross-site
+   start, such as a file:// page or a link in a terminal, would not carry a SameSite=Strict cookie). */
+function login(res, url) {
+  const code = url.searchParams.get("code") || "";
+  const exp = loginCodes.get(code);
+  loginCodes.delete(code);
+  if (!exp || exp < Date.now()) {
+    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. "));
+  }
+  let next = url.searchParams.get("next") || "/";
+  if (!next.startsWith("/") || next.startsWith("//") || next.includes("\\")) 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");
+  res.end(`<!doctype html><meta charset="utf-8"><title>PinDeck</title><script>location.replace(${to})</script>`);
+}
+/* Headless Chrome gets a start page in its own profile folder (0700) instead of a URL with a secret on
+   its command line: the page sends it to a one-time login code, which leads on to the target. */
+function chromeStart(profile, target) {
+  fs.mkdirSync(profile, { recursive: true, mode: 0o700 });
+  const start = path.join(profile, "pindeck-start.html");
+  const to = loginUrl(loginCode(120000), target.slice(ORIGIN.length)).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  fs.writeFileSync(start, `<!doctype html><meta http-equiv="refresh" content="0;url=${to}">`, { mode: 0o600 });
+  return pathToFileURL(start).href;
+}
+
+/* Files with a length and byte ranges: Safari plays audio and video only from servers that answer a
+   Range request with 206, and seeking needs it everywhere. Transformed (HTML) files are sent whole. */
+function serveFile(res, file, transform, req) {
+  const type = MIME[path.extname(file).slice(1).toLowerCase()] || "application/octet-stream";
+  if (transform) return fs.readFile(file, (err, data) => {
     if (err) return text(res, 404, "Not found");
-    const ext = path.extname(file).slice(1).toLowerCase();
-    res.writeHead(200, { "content-type": MIME[ext] || "application/octet-stream", "cache-control": "no-store" });
-    res.end(transform ? transform(String(data)) : data);
+    const out = Buffer.from(transform(String(data)));
+    res.writeHead(200, { "content-type": type, "content-length": out.length, "cache-control": "no-store" });
+    res.end(out);
+  });
+  fs.stat(file, (err, st) => {
+    if (err || !st.isFile()) return text(res, 404, "Not found");
+    const headers = { "content-type": type, "accept-ranges": "bytes", "cache-control": "no-store" };
+    let start = 0, end = st.size - 1, code = 200;
+    const range = /^bytes=(\d*)-(\d*)$/.exec(String(req?.headers.range || "").trim());   // one range only
+    if (range && (range[1] || range[2])) {
+      if (range[1]) { start = +range[1]; if (range[2]) end = Math.min(+range[2], end); }
+      else start = Math.max(0, st.size - +range[2]);   // suffix: the last n bytes
+      if (start > end || start >= st.size) {
+        res.writeHead(416, { ...headers, "content-range": `bytes */${st.size}` });
+        return res.end();
+      }
+      code = 206;
+      headers["content-range"] = `bytes ${start}-${end}/${st.size}`;
+    }
+    headers["content-length"] = st.size ? end - start + 1 : 0;
+    res.writeHead(code, headers);
+    if (!st.size) return res.end();
+    const stream = fs.createReadStream(file, { start, end });
+    stream.on("error", () => res.destroy());
+    res.on("close", () => stream.destroy());
+    stream.pipe(res);
   });
 }
 
+let ready = false;
 const server = http.createServer(async (req, res) => {
-  // only pages opened as 127.0.0.1 or localhost: another site's name pointed at 127.0.0.1 (DNS rebinding)
-  // must not read the editor page, its token or the deck
-  if (!HOSTS.has(String(req.headers.host || "").toLowerCase())) return text(res, 403, "Bad host");
+  if (!ready) return text(res, 503, "PinDeck is starting. Reload in a moment.");
+  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 {
-    // UI and deck files (read-only)
-    if (req.method === "GET" && (p === "/" || p === "/index.html"))
-      return serveFile(res, path.join(EDITOR_DIR, "public/index.html"), (s) => s.replace("%%TOKEN%%", TOKEN));
+    if (req.method === "GET" && p === "/login") return login(res, url);
+    // UI and deck files (read-only); the editor's own scripts and styles hold nothing secret
+    const ok = authed(req);
+    if (req.method === "GET" && (p === "/" || p === "/index.html")) {
+      if (!ok) { res.writeHead(403, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }); return res.end(LOGIN_PAGE); }
+      return serveFile(res, path.join(EDITOR_DIR, "public/index.html"), null, req);
+    }
     if (req.method === "GET" && p.startsWith("/editor/")) {
       const f = safeJoin(path.join(EDITOR_DIR, "public"), p.slice(8));
-      return f ? serveFile(res, f) : text(res, 403, "Forbidden");
+      return f ? serveFile(res, f, null, req) : text(res, 403, "Forbidden");
     }
+    if ((p.startsWith("/deck/") || p.startsWith("/files/")) && !ok) return text(res, 403, "Not logged in");
     let snap;
-    if (req.method === "GET" && (snap = p.match(/^\/deck\/__pindeck-print-([\w-]+)\.html$/))) {
+    if (req.method === "GET" && (snap = p.match(/^\/(?:deck|files)\/(?:.*\/)?__pindeck-print-([\w-]+)\.html$/))) {
       const html = snapshots.get(snap[1]);
       if (!html) return text(res, 404, "Not found");
       res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
       return res.end(html);
     }
-    if (req.method === "GET" && p.startsWith("/deck/")) {
-      const f = safeJoin(DECK_DIR, p.slice(6) || DECK_FILE);
-      if (!f) return text(res, 403, "Forbidden");
+    // /deck/: the deck folder; /deck/ alone is the deck page. With an asset root the page lives under
+    // /files/, so that ../ paths reach the root: /deck/ alone redirects there.
+    if (req.method === "GET" && p === "/deck/" && SERVE_ROOT) {
+      res.writeHead(302, { location: DECK_PAGE + url.search, "cache-control": "no-store" });
+      return res.end();
+    }
+    const deckPath = req.method === "GET" && (p.startsWith("/deck/") ? servable(DECK_DIR, p.slice(6) || DECK_FILE)
+      : p.startsWith("/files/") && SERVE_ROOT ? servable(SERVE_ROOT, p.slice(7)) : undefined);
+    if (deckPath === null) return text(res, 403, "Forbidden");
+    if (deckPath) {
+      const f = deckPath;
       const mode = url.searchParams.get("editor");
-      if (!mode || !f.endsWith(".html")) return serveFile(res, f);
+      if (!mode || !/\.html?$/i.test(f)) return serveFile(res, f, null, req);
       return serveFile(res, f, (s) => {
         // headless runs must not stream media, or Chrome never finishes the page
         if (mode === "shot" || mode === "dump" || mode === "pdf") s = s.replace(/\bpreload="(auto|metadata)"/g, 'preload="none"');
-        if (mode === "pdf") return s.replace(/<\/head>/i, PDF_HEAD_TAG).replace(/<\/body>/i, PDF_PAGE_TAG);
+        if (mode === "pdf") {
+          s = s.replace(/<\/head>/i, PDF_HEAD_TAG).replace(/<\/body>/i, PDF_PAGE_TAG);
+          // a deck that names its slides (in the file as it is now) is laid out by the bridge; reveal.js lays out its own
+          return slideSelector(parse(s)) ? s.replace(/<\/body>/i, BRIDGE_TAG) : s;
+        }
         return s.replace(/<\/body>/i, BRIDGE_TAG);
       });
     }
 
-    // API: token required; POSTs must come from the editor page itself
+    // API: token required (header or login cookie); POSTs must come from the editor page itself
     if (!p.startsWith("/api/")) return text(res, 404, "Not found");
-    const tok = req.headers["x-editor-token"] || url.searchParams.get("t");
-    if (tok !== TOKEN) return text(res, 403, "Bad token");
+    if (!ok) return text(res, 403, "Bad token");
     const origin = req.headers.origin;
-    if (req.method === "POST" && origin && origin !== ORIGIN && origin !== `http://localhost:${PORT}`)
+    if (req.method === "POST" && origin && origin.toLowerCase() !== `http://${host}`)
       return text(res, 403, "Bad origin");
 
     if (p === "/api/events") {
       res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
-      res.write(`event: hello\ndata: ${JSON.stringify({ chat: state.chat, status: status(),
+      res.write(`event: hello\ndata: ${JSON.stringify({ chat: state.chat, status: status(), rev: deckRev(),
         turns: state.turns.map((t) => ({ id: t.id, undone: t.undone })) })}\n\n`);
       clients.add(res);
       req.on("close", () => clients.delete(res));
       return;
     }
     if (p === "/api/ping") return json(res, 200, { ok: true });
+    if (p === "/api/login-link") return json(res, 200, { url: loginUrl(loginCode(3600000)) });
+    if (p === "/api/status") return json(res, 200, status());
     if (p === "/api/current" && req.method === "POST") { state.current = await body(req); return json(res, 200, {}); }
     if (p === "/api/pins" && req.method === "POST") { state.pins = (await body(req)).pins || []; return json(res, 200, {}); }
     if (p === "/api/measure-result" && req.method === "POST") {
@@ -907,6 +1338,9 @@ const server = http.createServer(async (req, res) => {
 
     if (p === "/api/message" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is still working." });
+      // checked again here: the claude or codex command may have been installed (or removed) since the start
+      const backend = providerAvailable(settings.provider);
+      if (!backend.available) return json(res, 503, { code: `${settings.provider}-unavailable`, error: backend.reason });
       const b = await body(req);
       if (state.busy) return json(res, 409, { error: "The assistant is still working." });
       if (typeof b.text !== "string" || !b.text.trim()) return json(res, 400, { error: "Empty message." });
@@ -953,18 +1387,16 @@ const server = http.createServer(async (req, res) => {
       const buf = Buffer.concat(chunks);
       if (kind === "pdf") {
         if (buf.subarray(0, 5).toString() !== "%PDF-") return json(res, 415, { error: `${original} is not a PDF.` });
-        fs.mkdirSync(PDF_DIR, { recursive: true });
+        fs.mkdirSync(PDF_DIR, { recursive: true, mode: 0o700 });
         const abs = attachPath(original, PDF_DIR);
-        fs.writeFileSync(abs, buf);
+        fs.writeFileSync(abs, buf, { mode: 0o600 });
         state.uploads.add(abs);
         let info = null;
-        if (process.platform === "darwin") { try { info = await pdfInfo(abs, STATE_DIR); } catch {} }
+        if (CAPS.pdfPages.available) { try { info = await pdfInfo(abs, STATE_DIR); } catch {} }
         return json(res, 200, { path: abs, kind, bytes: buf.length, pages: info?.pages, pageSize: info?.sizes[0] });
       }
       const rel = attachPath(original);
-      fs.mkdirSync(path.join(DECK_DIR, "figures"), { recursive: true });
-      ourWrites.set(rel, { hash: hash(buf.toString("utf8")), manual: true });   // no slide reload for a new file
-      fs.writeFileSync(path.join(DECK_DIR, rel), buf);
+      writeDeckFile(rel, buf);
       state.uploads.add(rel);
       return json(res, 200, { path: rel, kind, bytes: buf.length, url: `/deck/${rel}` });
     }
@@ -987,21 +1419,25 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/slide-hidden" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
-      const slides = findSlides(parse(before[DECK_FILE]));
+      const tree = parse(before[DECK_FILE]), slides = findSlides(tree);
       const index = slides.findIndex((s) => s.attrs["data-eid"]?.value === b.eid);
       if (index < 0) return json(res, 404, { error: "Slide not found in the file." });
       const r = setAttr(before[DECK_FILE], b.eid, "data-visibility", b.hidden ? "hidden" : null);
       if (!r.changed) return json(res, 200, { unchanged: true });
+      const skipped = slideSelector(tree) ? "left out of PDF exports (whether presenting skips them depends on the deck's script)"
+        : "skipped when presenting and in PDF exports";
       const turnId = recordHandEdit(before, r.html, `${b.hidden ? "Hid" : "Showed"} slide ${index + 1}`,
         `The user ${b.hidden ? "hid" : "showed again"} slide ${index + 1} (${b.eid}). Hidden slides carry ` +
-        `data-visibility="hidden": they stay in the file but are skipped when presenting and in PDF exports.`,
+        `data-visibility="hidden": they stay in the file but are ${skipped}.`,
         { manual: true, chat: false });   // the editor reloads the slide itself; undo is in the toolbar
       return json(res, 200, { turnId, index });
     }
     if (p === "/api/move-slide" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const r = moveSlide(before[DECK_FILE], b.eid, b.before ?? null);
       if (r.error) return json(res, 409, { error: r.error });
@@ -1014,6 +1450,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/add-slide" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       if (!["content", "section", "duplicate"].includes(b.kind)) return json(res, 400, { error: "Unknown slide kind." });
       const before = snapshot(EDITABLE);
       const r = insertSlide(before[DECK_FILE], b.kind, b.after);
@@ -1028,6 +1465,7 @@ const server = http.createServer(async (req, res) => {
       return json(res, 200, { turnId, index: r.index, eid });
     }
     if (p === "/api/import" && req.method === "POST") {
+      if (!CAPS.pptxImport.available) return json(res, 501, { code: "unavailable", error: CAPS.pptxImport.reason });
       const name = path.basename(decodeURIComponent(String(req.headers["x-filename"] || "slides.pptx")));
       if (!/\.pptx$/i.test(name)) return json(res, 415, { error: "Choose a PowerPoint file (.pptx). Save older .ppt files as .pptx first." });
       const chunks = [];
@@ -1053,6 +1491,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/import-apply" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const imp = lastImport;
       if (!imp || imp.id !== b.id) return json(res, 410, { error: "This import has expired. Choose the file again." });
       const numbers = (b.slides || []).filter((n) => imp.model.slides.some((s) => s.n === n));
@@ -1068,7 +1507,7 @@ const server = http.createServer(async (req, res) => {
         if (starting || !session?.running) { session?.stop(); finishTurn({ error: "Stopped." }); return json(res, 200, {}); }
         Promise.resolve(session.interrupt()).catch(() => {});
         setTimeout(() => {
-          if (state.busy && state.turn === interruptedTurn) { session.stop(); finishTurn({ error: "Stopped." }); }
+          if (state.busy && state.turn === interruptedTurn) { session?.stop(); finishTurn({ error: "Stopped." }); }
         }, 5000); // force only if the interrupted turn does not answer
       }
       return json(res, 200, {});
@@ -1087,7 +1526,7 @@ const server = http.createServer(async (req, res) => {
     if ((m = p.match(/^\/api\/turn\/(\d+)\/diff$/))) {
       const t = state.turns.find((t) => t.id === +m[1]);
       if (!t) return text(res, 404, "No such change");
-      return text(res, 200, EDITABLE.map((f) => unifiedDiff(t.before[f] ?? "", t.after[f] ?? "", f).text).filter(Boolean).join("\n\n"));
+      return text(res, 200, changeFiles(t).map((rel) => fileDiff(rel, t.before[rel] ?? null, t.after[rel] ?? null)).filter(Boolean).join("\n\n"));
     }
     if ((m = p.match(/^\/api\/turn\/(\d+)\/undo$/)) && req.method === "POST") {
       const t = liveTurns().at(-1);
@@ -1099,18 +1538,12 @@ const server = http.createServer(async (req, res) => {
       if (state.busy) return json(res, 409, { error: "Wait until the assistant has finished." });
       const t = state.redo.at(-1);
       if (!t) return json(res, 409, { error: "Nothing to redo." });
-      if (EDITABLE.some((f) => (readDeck(f) ?? null) !== (t.before[f] ?? null))) {
-        state.redo = [];
-        pushStatus();
-        return json(res, 409, { error: "The files changed since the undo, so it cannot be redone." });
-      }
+      const diverged = undoConflicts(t, "redo");
+      if (diverged.length) return conflict(res, "redo", diverged);
       state.redo.pop();
-      for (const f of EDITABLE) if (t.after[f] != null) writeDeck(f, t.after[f]);
+      for (const rel of changeFiles(t)) if (!isAs(rel, t.after[rel])) putDeckFile(rel, t.after[rel] ?? null);
       for (const { rel } of t.deletedFiles || []) fs.rmSync(path.join(DECK_DIR, rel), { force: true });
-      for (const { rel, data } of t.addedFiles || []) {
-        fs.mkdirSync(path.dirname(path.join(DECK_DIR, rel)), { recursive: true });
-        fs.writeFileSync(path.join(DECK_DIR, rel), data);
-      }
+      for (const { rel, data } of t.addedFiles || []) writeDeckFile(rel, data, false);
       t.undone = false;
       state.notes.push(t.kind === "manual" ? `The user redid their hand edit: ${t.label}.`
         : `The user redid your change from turn ${t.id} after undoing it.`);
@@ -1128,6 +1561,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/delete" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const plan = deletePlan(b.eid);
       if (!plan) return json(res, 404, { error: "Element not found in the file." });
       const before = snapshot(EDITABLE);
@@ -1147,6 +1581,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/edit" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const r = setStyles(before[DECK_FILE], b.ops || []);
       if (r.missing.length) return json(res, 404, { error: `No element ${r.missing.join(", ")} in ${DECK_FILE}.` });
@@ -1168,6 +1603,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/notes" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const r = setNotes(before[DECK_FILE], b.eid, b.text, !!b.html);
       if (!r) return json(res, 404, { error: "Slide not found in the file." });
@@ -1182,6 +1618,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/text" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const r = setInner(before[DECK_FILE], b.eid, b.path || [], String(b.html ?? ""));
       if (!r) return json(res, 404, { error: `No element ${b.eid} in ${DECK_FILE}.` });
@@ -1197,6 +1634,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/split" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const r1 = setInner(before[DECK_FILE], b.eid, [], String(b.html ?? ""));
       if (!r1) return json(res, 404, { error: `No element ${b.eid} in ${DECK_FILE}.` });
@@ -1209,6 +1647,7 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/remove" && req.method === "POST") {
       if (state.busy) return json(res, 409, { error: "The assistant is working. Wait until it has finished." });
       const b = await body(req);
+      if (staleEdit(res, b)) return;
       const before = snapshot(EDITABLE);
       const html = removeElement(before[DECK_FILE], b.eid);
       if (html == null) return json(res, 404, { error: `No element ${b.eid} in ${DECK_FILE}.` });
@@ -1220,13 +1659,14 @@ const server = http.createServer(async (req, res) => {
     if (p === "/api/export" && req.method === "POST") {
       const b = await body(req);
       try { return json(res, 200, await exportPdf(b.kind, b.includeHidden)); }
-      catch (e) { return json(res, 500, { error: String(e.message || e) }); }
+      catch (e) { return json(res, e.status || 500, { error: String(e.message || e) }); }
     }
 
     // CLI endpoints (used by both backends via cli.mjs)
     if (p === "/api/pdf") {
       const kind = url.searchParams.get("slide") || url.searchParams.get("kind") || "handout";
       if (!["handout", "presentation"].includes(kind)) return text(res, 400, 'Use "handout" or "presentation".');
+      if (!CAPS.pdfExport.available) return text(res, 501, `PDF export is not available: ${CAPS.pdfExport.reason}.`);
       const r = await exportPdf(kind, url.searchParams.get("all") === "1");
       return text(res, 200, r.path);
     }
@@ -1236,15 +1676,21 @@ const server = http.createServer(async (req, res) => {
       return text(res, r.status || 200, r.text);
     }
     if (p === "/api/slides") {
-      return text(res, 200, slideList().map((s) => `${String(s.index + 1).padStart(2)}  ${s.eid}`).join("\n"));
+      const list = slideList(), why = !list.length && deckProblemNow();
+      if (why) return text(res, 409, why);
+      return text(res, 200, list.map((s) => `${String(s.index + 1).padStart(2)}  ${s.eid}`).join("\n"));
     }
     if (p === "/api/layout" || p === "/api/shot") {
       const slide = resolveSlide(url.searchParams.get("slide"));
-      if (!slide) return text(res, 404, `No slide "${url.searchParams.get("slide")}". Use \`${CLI_CMD} slides\`.`);
+      if (!slide) return text(res, 404, deckProblemNow() || `No slide "${url.searchParams.get("slide")}". Use \`${CLI_CMD} slides\`.`);
       if (!slide.eid) runEidPass();
       const s2 = slide.eid ? slide : resolveSlide(String(slide.index + 1));
-      if (p === "/api/shot") return text(res, 200, await takeShot(s2));
-      return text(res, 200, formatLayout(await measure(s2)));
+      if (p === "/api/shot") {
+        if (!CAPS.screenshot.available) return text(res, 501, `Screenshots are not available: ${CAPS.screenshot.reason}.`);
+        return text(res, 200, await takeShot(s2));
+      }
+      try { return text(res, 200, formatLayout(await measure(s2))); }
+      catch (e) { if (e.status) return text(res, e.status, e.message); throw e; }
     }
     return text(res, 404, "Not found");
   } catch (e) {
@@ -1255,13 +1701,38 @@ const server = http.createServer(async (req, res) => {
   }
 });
 
-/* ---- Start ------------------------------------------------------------------------------------- */
-const first = runEidPass();
-if (first.changed) console.log(`Added ${first.assigned.length} element ids to ${DECK_FILE} (backup in ${path.join(STATE_DIR, "backups")}).`);
+/* ---- Start ----------------------------------------------------------------------------------------
+   The port is bound first. Only then does PinDeck write anything: its state folder and server files, and
+   the element ids in the deck. A port in use or another failure to listen leaves deck and state untouched. */
+let quitting = false;
+server.on("error", (e) => {
+  if (ready) 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", () => {
-  console.log(`PinDeck: ${ORIGIN}/`);
+  PORT = server.address().port;
+  ORIGIN = `http://127.0.0.1:${PORT}`;
+  try {
+    writeServerInfo();
+    fs.rmSync(IMPORT_DIR, { recursive: true, force: true });
+    const first = runEidPass();
+    if (first.changed) console.log(`Added ${first.assigned.length} element ids to ${DECK_FILE} (backup in ${path.join(STATE_DIR, "backups")}).`);
+    startWatcher();
+  } catch (e) {
+    console.error(`PinDeck could not open the deck: ${e.message}`);
+    removeServerInfo();
+    process.exit(1);
+  }
+  ready = true;
+  console.log(`PinDeck: ${loginUrl(loginCode(3600000))}`);
+  console.log("  (a one-time login link, valid for an hour; for a new one: pindeck login)");
   console.log(`Deck: ${DECK_DIR}`);
-  if (!CHROME) console.log("No Chrome found: screenshots are disabled (set CHROME_BIN).");
+  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})`);
   discoverModels().then(() => {
     if (!settings.model) {
       const models = catalog[settings.provider].models;
@@ -1271,6 +1742,22 @@ server.listen(PORT, "127.0.0.1", () => {
     pushStatus();
   });
 });
-const quit = () => { session?.stop(); setTimeout(() => process.exit(0), 300); };
+/* Ctrl+C or SIGTERM: stop taking requests, let the backend end (it gets end of input, then SIGTERM, then
+   SIGKILL), then exit. At most 6 s; a second Ctrl+C exits at once. A running turn is not resumed later. */
+async function quit() {
+  if (quitting) process.exit(1);
+  quitting = true;
+  try { watcher?.close(); } catch {}
+  clearTimeout(flush); clearTimeout(eidTimer);
+  for (const res of clients) res.end();
+  for (const w of pending.values()) { clearTimeout(w.t); w.reject(new Error("PinDeck is stopping")); }
+  server.close();
+  server.closeAllConnections?.();
+  removeServerInfo();
+  for (const agent of [...discoveryAgents, session]) retire(agent);
+  await Promise.race([Promise.all(retiring), new Promise((r) => setTimeout(r, 6000))]);
+  if (chatTimer) writeChat();
+  process.exit(0);
+}
 process.on("SIGINT", quit);
 process.on("SIGTERM", quit);