pindeck 2.9.0 → 2.10.0

package/server.mjs

@@ -24,7 +24,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { spawn, execFile } from "node:child_process";
 import { fileURLToPath, pathToFileURL } 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 { 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 { formatLayout, formatPin } from "./lib/layout.mjs";
@@ -33,21 +33,29 @@ 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 { writeAtomic, sameContent, revision } from "./lib/deck-files.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] [--model <name>]
-       pindeck login [deck-folder]
+const USAGE = `Usage: pindeck [deck-folder | deck-file.html] [--port 5180] [--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 folder: for the PinDeck started last).`;
+(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/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 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)) {
@@ -58,13 +66,21 @@ if (!isSupportedPlatform(process.platform)) {
 const LOGIN = argv[0] === "login";
 if (LOGIN) argv.shift();
 const MODEL = opt("--model", process.env.CLAUDE_MODEL || "");
-const DECK_DIR = path.resolve(argv[0] || process.cwd());
-const DECK_FILE = "index.html";
-const EDITABLE = ["index.html", "theme.css"];      // Claude 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"];         // Claude may edit these
 const LOCKED = ["brand.css"];                      // never, enforced twice
 const HOME_DIR = process.env.PINDECK_HOME || path.join(os.homedir(), ".pindeck");
-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
@@ -107,6 +123,13 @@ 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);
+}
 /* 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
@@ -134,6 +157,22 @@ const MIME = { html: "text/html; charset=utf-8", css: "text/css; charset=utf-8",
   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 });
@@ -147,6 +186,25 @@ function writeDeckFile(rel, data, manual = true) {
   writeAtomic(abs, data);
 }
 const snapshot = (files) => Object.fromEntries(files.map((f) => [f, readDeck(f)]));
+/* 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) => {
@@ -239,15 +297,25 @@ const CHROME = CAPS.chromePath;   // null when Chrome features are unavailable (
 /* 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(`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.map((a) => a.startsWith(ORIGIN + "/") ? chromeStart(profile, a) : a)]);
+      `--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;
@@ -267,7 +335,7 @@ function chrome(args, done) {
   });
 }
 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`);
@@ -311,21 +379,21 @@ const measure = (slide) => measureInEditor(slide).catch((e) => {
    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 (!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 layoutProfile = profile("layout"), printProfile = profile("print");
     const html = await printLayout(CHROME, chromeStart(layoutProfile,
-      `${ORIGIN}/deck/${DECK_FILE}?editor=pdf&print-pdf&pdfSeparateFragments=${split}&showHiddenSlides=${!!includeHidden}`), 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, chromeStart(printProfile, `${ORIGIN}/deck/__pindeck-print-${id}.html`), out, printProfile); }
+    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 };
@@ -381,6 +449,37 @@ if (MODELS.includes(fileConfig.model)) settings.model = fileConfig.model;
 else if (fileConfig.model !== undefined) console.warn(`config.json: unknown model "${fileConfig.model}" (use ${MODELS.join(" or ")}); using ${DEFAULTS.model}.`);
 if (EFFORTS.includes(fileConfig.effort)) settings.effort = fileConfig.effort;
 else if (fileConfig.effort !== undefined) console.warn(`config.json: unknown effort "${fileConfig.effort}" (use ${EFFORTS.join(", ")}); using ${DEFAULTS.effort}.`);
+/* 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;
+}
 const saveSettings = () => fs.writeFile(CONFIG_FILE, JSON.stringify({ ...fileConfig, model: settings.model, effort: settings.effort }, null, 2) + "\n", () => {});
 const completeSettings = () => {   // create or complete the file (at start, once the port is bound)
   if (fileConfig.model !== settings.model || fileConfig.effort !== settings.effort) saveSettings();
@@ -389,22 +488,46 @@ if (MODEL) settings.model = MODEL;   // --model on the command line: this run on
 
 const status = () => ({ busy: state.busy, model: state.model, sessionId: state.sessionId, settings: { ...settings },
   running: session.running, 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) + capabilityPrompt(CAPS, 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, together with the deck's AGENTS.md (the
-   name other coding agents read). 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. */
+   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() {
   return ["CLAUDE.md", "AGENTS.md"].map((name) => {
-    let s;
-    try { s = fs.readFileSync(path.join(DECK_DIR, name), "utf8").trim(); } catch { return ""; }
+    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("");
 }
@@ -413,11 +536,12 @@ const session = new ClaudeSession({
   cwd: DECK_DIR,
   env: () => ({ DECK_EDITOR_URL: ORIGIN, DECK_EDITOR_TOKEN: TOKEN }),
   args: () => [
-    "--append-system-prompt", systemPrompt + deckInstructions(),
+    "--append-system-prompt", systemPrompt + slidesInstructions() + deckInstructions(),
     "--setting-sources", "", "--strict-mcp-config",   // no settings files, no MCP servers or connectors
     "--permission-mode", "default",
-    "--allowedTools", "Read", "Glob", "Grep", ...EDITABLE.map((f) => `Edit(./${f})`), `Bash(${CLI_CMD}:*)`,
-    "--disallowedTools", ...LOCKED.flatMap((f) => [`Edit(./${f})`, `Write(./${f})`]),
+    // any file in the deck folder (Edit rules cover Write too; Write is named as well, to be explicit)
+    "--allowedTools", "Read", "Glob", "Grep", "Edit(./**)", "Write(./**)", `Bash(${CLI_CMD}:*)`,
+    "--disallowedTools", ...lockedPaths().flatMap((f) => [`Edit(./${f})`, `Write(./${f})`]),
     ...(settings.model ? ["--model", settings.model] : []),
     ...(settings.effort ? ["--effort", settings.effort] : []),
   ],
@@ -492,7 +616,9 @@ function handleEvent(ev) {
 }
 
 function startTurn(promptText, userEntry) {
-  state.turn = { id: userEntry.id, before: snapshot([...EDITABLE, ...LOCKED]) };
+  // every deck file as it is now: Claude 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();
   ensureSession();
@@ -516,11 +642,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 Claude replaced (nothing refers to them any more) are
   // deleted; undo brings them back with the turn
   const deletedFiles = [];
@@ -530,11 +658,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: "claude", before: turn.before, after, files, deletedFiles, undone: false };
+  const t = { id: turn.id, kind: "claude", 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();
 }
 
@@ -593,7 +723,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;
 }
 
@@ -620,7 +750,7 @@ 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 (!out) return { text: `${tmp} (${size}). Read it; add a figures/ name to save it into the deck.` };
   const buf = fs.readFileSync(tmp);
@@ -670,6 +800,14 @@ function scheduleFlush() {
       };
       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, rev: deckRev() });
   }, 120);
@@ -768,7 +906,7 @@ function deletePlan(eid) {
    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 = EDITABLE.filter((f) => (readDeck(f) ?? null) !== (expect[f] ?? null));
+  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 || [];
@@ -794,11 +932,7 @@ function undo(res) {
   if (!t) return json(res, 409, { error: "Nothing to undo." });
   const diverged = undoConflicts(t, "undo");
   if (diverged.length) return conflict(res, "undo", diverged);
-  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 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;
@@ -1037,23 +1171,35 @@ const server = http.createServer(async (req, res) => {
       const f = safeJoin(path.join(EDITOR_DIR, "public"), p.slice(8));
       return f ? serveFile(res, f, null, req) : text(res, 403, "Forbidden");
     }
-    if (p.startsWith("/deck/") && !ok) return text(res, 403, "Not logged in");
+    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, null, req);
+      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);
       });
     }
@@ -1170,14 +1316,16 @@ const server = http.createServer(async (req, res) => {
       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 });
     }
@@ -1269,7 +1417,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);
@@ -1284,11 +1432,7 @@ const server = http.createServer(async (req, res) => {
       const diverged = undoConflicts(t, "redo");
       if (diverged.length) return conflict(res, "redo", diverged);
       state.redo.pop();
-      for (const f of EDITABLE) {
-        if (readDeck(f) === t.after[f]) continue;
-        if (t.after[f] != null) writeDeck(f, t.after[f]);
-        else fs.rmSync(path.join(DECK_DIR, f), { force: true });
-      }
+      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 || []) writeDeckFile(rel, data, false);
       t.undone = false;
@@ -1422,11 +1566,13 @@ 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") {