pindeck 3.4.0 → 4.1.0-beta.1

package/server.mjs

@@ -10,20 +10,20 @@
    - answers `cli.mjs layout|shot|slides|pdf|pdf-figure` for the assistant's self-checks, exports and PDF figures
    - exports the deck as a PDF handout or a PDF presentation (build steps on separate pages)
    - stores figures and audio attached to chat messages in <deck>/figures/ for the assistant to use, and attached
-     PDFs (papers, reports, figures) in ~/.pindeck-v3, outside the deck
+     PDFs (papers, reports, figures) in ~/.pindeck-v4, outside the deck
    - imports slides from PowerPoint files in the deck's own layouts
    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-v3, never in the deck or the package. */
+   Runtime files (chat, screenshots, backups) live in ~/.pindeck-v4, never in the deck or the package. */
 
 import http from "node:http";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { spawn, execFile } from "node:child_process";
+import { spawn, execFile, execFileSync } from "node:child_process";
 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, decode } from "./lib/eids.mjs";
+import { assignEids, parse, findSlides, slideSelector, deckSize, setStyles, getInner, getOuter, setInner, insertAfter, removeElement, deleteTarget, fileRefs, insertSlide, moveSlide, getNotes, setNotes, setAttr, elementEnd, decode } from "./lib/eids.mjs";
 import { unifiedDiff } from "./lib/diff.mjs";
 import { ClaudeSession } from "./lib/claude.mjs";
 import { CodexSession } from "./lib/codex.mjs";
@@ -44,12 +44,14 @@ import { assetRoots } from "./lib/asset-roots.mjs";
 import { registerServer, printLogin, alive } from "./lib/servers.mjs";
 import { goodHost, presentHost, LOGIN_PAGE, createLogin, openOnEnter } from "./lib/login.mjs";
 import { USAGE } from "./lib/usage.mjs";
+import { indexDeck, commentFromPin, locate, loadReview, saveReview, packet, request as commentsRequest, reviewFiles } from "./lib/review.mjs";
 
 /* ---- Config ------------------------------------------------------------------ */
 /* Started by the front (pindeck, front.mjs) for one of the decks it serves: the front logs browsers in and
    prints the links; this server tells it its address over IPC. */
 const FRONT = !!process.env.PINDECK_FRONT && !!process.send;
 const EDITOR_DIR = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(fs.readFileSync(path.join(EDITOR_DIR, "package.json"), "utf8")).version;
 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; };
@@ -70,9 +72,21 @@ const MODEL = opt("--model", "");
 if (process.env.CLAUDE_MODEL && !LOGIN && !FRONT)   // PinDeck 2 read it; behind the front, the front says so
   console.warn(`CLAUDE_MODEL is not used by PinDeck 3: choose the model in the editor's model menu, or start with --model ${process.env.CLAUDE_MODEL}.`);
 /* The deck: a file (talk.html), or a folder, which means its index.html (see lib/deck-target.mjs) */
-const { dir: DECK_DIR, file: DECK_FILE, named: NAMED, name: DECK_NAME, key: deckKey } = deckTarget(argv[0] || process.cwd());
-const EDITABLE = [DECK_FILE, "theme.css"];         // both backends may edit these
-const LOCKED = ["brand.css"];                      // never, enforced twice
+const { dir: DECK_DIR, file: DECK_FILE, named: NAMED, name: DECK_NAME, key: deckKey, source: SOURCE } = deckTarget(argv[0] || process.cwd());
+/* A Quarto deck (SOURCE: talk.qmd): DECK_FILE is what Quarto renders from it, build output. The assistant edits
+   the sources; PinDeck renders after every change (see Quarto below) and adds its element ids to the output. */
+const OUTPUTS = SOURCE ? [DECK_FILE, DECK_FILE.replace(/\.html$/i, "_files"), ".quarto"] : [];
+const isOutput = (rel) => OUTPUTS.some((o) => rel === o || rel.startsWith(o + "/"));
+const EDITABLE = SOURCE ? [SOURCE, DECK_FILE] : [DECK_FILE, "theme.css"];   // both backends may edit these (a Quarto deck: its source)
+/* A Quarto deck's format extensions (_extensions/[<org>/]<name>/, e.g. Ocean) carry their own brand.css and vendor/ */
+function extensionBrands() {
+  try {
+    return fs.readdirSync(path.join(DECK_DIR, "_extensions"), { recursive: true }).map((f) => String(f).split(path.sep).join("/"))
+      .filter((f) => /(^|\/)brand\.css$/.test(f) && !f.includes("vendor/")).map((f) => `_extensions/${f}`);
+  } catch { return []; }
+}
+const BRANDS = SOURCE ? extensionBrands() : [];
+const LOCKED = ["brand.css", ...BRANDS];           // never, enforced twice
 const HOME_DIR = homeDir();
 const STATE_DIR = path.join(HOME_DIR, "decks", deckKey);
 const SHOT_DIR = path.join(STATE_DIR, "shots");
@@ -92,6 +106,34 @@ const CLI_REL = path.relative(DECK_DIR, path.join(EDITOR_DIR, "cli.mjs")).split(
 const CLI_CMD = cliCommand(CLI_REL);
 const CAPS = detectCapabilities();
 
+/* ---- Quarto ----------------------------------------------------------------------------------------
+   `quarto render <source>` makes DECK_FILE. One render at a time; a change to a source while one runs renders
+   again when it ends. What the assistant checks (shot, layout, slides, pdf) waits for the render, so it always
+   sees its last edit. Quarto's own errors go to the chat, and to the assistant. */
+const QUARTO = SOURCE ? findExecutable(process.env.QUARTO_BIN || "quarto") : null;
+const RENDER_TIMEOUT = 180000;
+const SOURCE_FILE = /\.(qmd|md|scss|css|ya?ml|bib|csl|lua|js|html?|png|jpe?g|gif|svg|webp|pdf|mp4|wav|mp3)$/i;   // what a render reads
+/* Quarto's message, without colours and its JavaScript stack: what says what is wrong in the source */
+const quartoError = (stderr) => `Quarto could not render ${SOURCE}:\n` + String(stderr).replace(/\x1b\[[0-9;]*m/g, "")
+  .split(/\nStack trace:|\n\s+at /)[0].trim().split("\n").slice(-25).join("\n");
+function renderSync() {
+  console.log(`Rendering ${SOURCE} with Quarto…`);
+  try { execFileSync(QUARTO.path, ["render", SOURCE], { cwd: DECK_DIR, stdio: ["ignore", "ignore", "pipe"], timeout: RENDER_TIMEOUT }); }
+  catch (e) { return quartoError(e.stderr || e.message); }
+  return fs.existsSync(path.join(DECK_DIR, DECK_FILE)) ? null
+    : `Quarto rendered ${SOURCE}, but not to ${DECK_FILE} beside it (an output-dir in _quarto.yml?). PinDeck needs the HTML next to its source.`;
+}
+let startRenderError = null;   // a failed render at start with an older output: PinDeck opens that, the assistant fixes the source
+if (SOURCE && !LOGIN) {
+  if (!QUARTO.path) { console.error(`${SOURCE} is a Quarto deck, and Quarto is not installed (${QUARTO.reason}). Install it from https://quarto.org.`); process.exit(1); }
+  const mtime = (f) => { try { return fs.statSync(path.join(DECK_DIR, f)).mtimeMs; } catch { return 0; } };
+  if (mtime(DECK_FILE) < mtime(SOURCE)) {
+    const failed = renderSync();
+    if (failed && !fs.existsSync(path.join(DECK_DIR, DECK_FILE))) { console.error(failed); process.exit(1); }
+    if (failed) { console.error(failed + `\nOpening the last render of ${SOURCE}.`); startRenderError = failed; }
+  }
+}
+
 /* 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);
@@ -304,13 +346,14 @@ function refreshGit() {
 }
 function slideList() {
   const html = readDeck(DECK_FILE);
-  return findSlides(parse(html)).map((s, index) => ({ index, eid: s.attrs["data-eid"]?.value || null }));
+  return findSlides(parse(html)).map((s, index) => ({ index, eid: s.attrs["data-eid"]?.value || null, id: s.attrs.id?.value || null }));
 }
 function resolveSlide(spec) {
   const slides = slideList();
   if (!spec || spec === "current") return slides[state.current?.index ?? 0] || slides[0];
   if (/^\d+$/.test(spec)) return slides[+spec - 1];
-  return slides.find((s) => s.eid === spec) || slides.find((s) => s.eid && s.eid.startsWith(spec));
+  // or the slide's own id attribute (Quarto's heading anchor, which stays when the title changes)
+  return slides.find((s) => s.eid === spec) || slides.find((s) => s.id === spec) || slides.find((s) => s.eid && s.eid.startsWith(spec));
 }
 
 /* ---- Headless Chrome (screenshots, and layout when no editor tab is open) --------------- */
@@ -544,7 +587,8 @@ const status = () => ({ busy: state.busy, switching: state.switching, preparing:
   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(), view: VIEW.slice(1) + "/",
-  undo: changeLabel(liveTurns().at(-1)), undoId: liveTurns().at(-1)?.id ?? null, redo: changeLabel(state.redo.at(-1)) });
+  undo: changeLabel(liveTurns().at(-1)), undoId: liveTurns().at(-1)?.id ?? null, redo: changeLabel(state.redo.at(-1)),
+  source: SOURCE, rendering: !!rendering, renderError });
 /* Pushed to the editors on every change. The model lists (both providers' catalogs) go along only when they
    changed since the last push: the editor keeps the last ones it got. */
 let catalogSent = "";
@@ -563,6 +607,19 @@ const systemPrompt = fs.readFileSync(path.join(EDITOR_DIR, "lib/system-prompt.md
   (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` : "");
+/* A Quarto deck: what to edit, and how its output relates to the source */
+const quartoInstructions = () => SOURCE ? `\n\n## This deck is made with Quarto
+${DECK_FILE} is rendered by Quarto from ${SOURCE}: it is build output, locked, and overwritten by every render. Make every ` +
+  `change in ${SOURCE} (Quarto Markdown: \`##\` headings start slides and become the slides' id attributes, \`::: {.notes}\` holds ` +
+  `speaker notes, \`::: {.incremental}\` and \`. . .\` make build steps, \`{ojs}\` cells are Observable JS; when you change a ` +
+  `slide's title, keep its id by adding \`{#<old id>}\` to the heading, so comments and links still find the slide), or in the files it uses ` +
+  `(its .scss theme, figures). Where these instructions say to edit ${DECK_FILE} or theme.css, edit ${SOURCE} or its stylesheet ` +
+  `instead. Pins and element ids (data-eid) name elements of the rendered HTML: read ${DECK_FILE} to see what they are, then ` +
+  `find the matching text in ${SOURCE}. PinDeck renders after every change you save; ${CLI_CMD} shot, layout and slides wait ` +
+  `for that render, and report Quarto's error if it fails. Interactive OJS output is drawn in the browser, so screenshots show it ` +
+  `only once its libraries have loaded.\n` + (BRANDS.length ? `The deck's look comes from a Quarto format extension (` +
+  BRANDS.map((b) => b.replace(/\/brand\.css$/, "/")).join(", ") + `): read its README.md for the slide layouts and classes. ` +
+  `Its brand.css and vendor/ are locked, like brand.css in an HTML deck; its theme.css takes the talk's own styles.\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();
@@ -577,7 +634,7 @@ function slidesInstructions() {
    win over allow rules; a locked file changed anyway is restored after the turn (lock 2 in finishTurn). */
 function lockedPaths() {
   const { files, folders } = otherDecks();
-  return [...LOCKED, "vendor/**", ".git", ".git/**", ...files, ...folders.map((f) => `${f}/**`)];
+  return [...LOCKED, "vendor/**", ...BRANDS.map((b) => b.replace(/brand\.css$/, "vendor/**")), ".git", ".git/**", ".pindeck", ".pindeck/**", ...OUTPUTS.flatMap((o) => [o, `${o}/**`]), ...files, ...folders.map((f) => `${f}/**`)];
 }
 /* The other decks in this deck's folder: its other .html files, and the subfolders that hold a deck of their
    own (as the deck menu lists them). Neither the assistant nor this deck's undo touches them. */
@@ -588,7 +645,7 @@ function otherDecks() {
     .map((d) => path.relative(DECK_DIR, d.dir).split(path.sep).join("/")))];
   return { files, folders };
 }
-const scanDeck = () => { const { files, folders } = otherDecks(); return scanFiles(DECK_DIR, { skip: [...files, ...folders] }); };
+const scanDeck = () => { const { files, folders } = otherDecks(); return scanFiles(DECK_DIR, { skip: [...files, ...folders, ...OUTPUTS] }); };
 
 /* Decks that share a folder share its files (theme.css, figures/): while the assistant of one works, that of
    another may change them too. Each deck server keeps the times of its turns in a file of its own under
@@ -642,13 +699,13 @@ const codexInstructions = () => systemPrompt.replace(/## Attached files[\s\S]*?#
 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 ${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.
+Use pindeck_command with separate command and args for layout, shot, slides, element (the HTML of data-eid ids), pdf, pdf-figure, resolve or reply.
 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`) + slidesInstructions() + deckInstructions();
+## Hand edits`) + slidesInstructions() + quartoInstructions() + deckInstructions();
 function makeSession(choice) {
   let initial = null;
   const options = {
@@ -670,11 +727,11 @@ function makeSession(choice) {
     instructions: codexInstructions(), tools: agentTools }) : new ClaudeSession({ ...options,
     // a tool the rules do not allow comes to PinDeck (--permission-prompt-tool stdio), always refused: with the right command if it was the CLI
     denyMessage: (r) => r?.tool_name === "Bash" ? cliRefusal(r.input?.command, CLI_CMD) : null,
-    args: () => ["--append-system-prompt", systemPrompt + slidesInstructions() + deckInstructions(),
+    args: () => ["--append-system-prompt", systemPrompt + slidesInstructions() + quartoInstructions() + deckInstructions(),
       "--setting-sources", "", "--strict-mcp-config", "--safe-mode", "--disable-slash-commands",   // no settings files, no MCP servers or connectors
       "--permission-mode", "default", "--permission-prompt-tool", "stdio", "--tools", "Read,Glob,Grep,Edit,Write,Bash",
       "--allowedTools", ...readRules(), "Edit(./**)", "Write(./**)",
-      ...["layout", "shot", "slides", "pdf", "pdf-figure"].map(command => `Bash(${CLI_CMD} ${command}:*)`),
+      ...["layout", "shot", "slides", "element", "pdf", "pdf-figure", "resolve", "reply"].map(command => `Bash(${CLI_CMD} ${command}:*)`),
       "--disallowedTools", ...lockedPaths().flatMap((f) => [`Edit(./${f})`, `Write(./${f})`]),
       ...(choice.model ? ["--model", choice.model] : []), ...(choice.effort ? ["--effort", choice.effort] : [])],
   });
@@ -848,7 +905,7 @@ function toolSummary(name, input = {}) {
       // must show as the script, or a refused script looks like a refused layout check
       const cmd = String(input.command || "").trim();
       const m = cmd.startsWith(CLI_CMD + " ") && cmd.slice(CLI_CMD.length).match(/^\s+([\w-]+)\s*([^\n;&|<>`$]*)$/);
-      const names = { shot: "Screenshot", layout: "Check layout", "pdf-figure": "PDF figure" };
+      const names = { shot: "Screenshot", layout: "Check layout", element: "Read element", "pdf-figure": "PDF figure", resolve: "Resolve comment", reply: "Reply to comment" };
       return m ? { name: names[m[1]] || m[1], detail: m[1] === "pdf-figure" ? m[2].trim().replace(/^\S*\//, "") : m[2].trim() }
                : { name: "Run", detail: cmd.split("\n")[0].slice(0, 80) };
     }
@@ -1034,8 +1091,10 @@ function buildPrompt({ text: userText, pins = [], selection, layouts = [], curre
     ctx.push(...notes.map((n) => "Note: " + n));
     state.notes = [];
   }
-  if (selection) ctx.push(`Selected element (what "this" or "it" most likely refers to): ${selection.eid} (${selection.tag}), ` +
-    `box x=${selection.box.x} y=${selection.box.y} w=${selection.box.w} h=${selection.box.h} on slide ${selection.slide.index + 1}.`);
+  const selBox = (s) => `${s.eid} (${s.tag}), box x=${s.box.x} y=${s.box.y} w=${s.box.w} h=${s.box.h}`;
+  if (selection?.also?.length) ctx.push(`Selected elements (what "these", "them" or "this" most likely refer to), on slide ${selection.slide.index + 1}:\n` +
+    [selection, ...selection.also].map((s) => "- " + selBox(s)).join("\n"));
+  else if (selection) ctx.push(`Selected element (what "this" or "it" most likely refers to): ${selBox(selection)} on slide ${selection.slide.index + 1}.`);
   if (pins.length) ctx.push("Pins (numbered clicks; the user refers to them by number):\n" + pins.map(formatPin).join("\n"));
   for (const L of layouts) ctx.push("Layout:\n" + formatLayout(L));
   if (screenshot) ctx.push(`Screenshot of slide ${screenshot.slide}${screenshot.pins ? " with the pin markers" : ""}: ${screenshot.path} (Read it).`);
@@ -1082,6 +1141,98 @@ async function pdfFigure({ file = "", page = "1", box = "", out = "", width = ""
   return { text: `${out} (${size})` };
 }
 
+/* ---- Review comments (lib/review.mjs) ---------------------------------------------------------------
+   Kept in <deck folder>/.pindeck/: never a deck file, never in an undo, locked for the assistant. The packet
+   next to them is written once there are comments, and again whenever they or the deck change. An agent outside
+   PinDeck may set a comment's status in the file; the editor follows. A file that cannot be read is left as it
+   is: comments are then off, with the reason. */
+const REVIEW = reviewFiles(DECK_DIR, DECK_FILE);
+let review = null, reviewProblem = null, reviewSaved = null;
+function readReview() {
+  try { review = loadReview(REVIEW.json); reviewProblem = null; }
+  catch (e) { review = null; reviewProblem = `The comments file ${REVIEW.json} cannot be read (${e.message}): fix or remove it.`; }
+  try { reviewSaved = fs.readFileSync(REVIEW.json, "utf8"); } catch { reviewSaved = null; }
+}
+readReview();
+const deckIndex = () => indexDeck(readDeck(DECK_FILE) || "");
+// the Quarto source's text, for the source lines of comments (null for an HTML deck)
+const sourceText = () => { try { return SOURCE ? fs.readFileSync(path.join(DECK_DIR, SOURCE), "utf8") : null; } catch { return null; } };
+function commentsView(deck = deckIndex()) {
+  if (!review) return { comments: [], problem: reviewProblem };
+  return { file: path.relative(DECK_DIR, REVIEW.json), packet: path.relative(DECK_DIR, REVIEW.packet), problem: null,
+    comments: review.comments.map((c, i) => {
+      const loc = locate(deck, c);
+      return { ...c, n: i + 1, loc: { status: loc.status, index: loc.slide?.index ?? null, slideEid: loc.slide?.eid ?? null, eid: loc.eid, now: loc.now } };
+    }) };
+}
+function writePacket(deck = deckIndex()) {
+  if (!review || (!review.comments.length && !fs.existsSync(REVIEW.packet))) return;
+  fs.mkdirSync(path.dirname(REVIEW.packet), { recursive: true });
+  writeAtomic(REVIEW.packet, packet(review, deck, { deckFile: DECK_FILE, source: SOURCE, srcText: sourceText(), commentsFile: path.relative(DECK_DIR, REVIEW.json) }));
+}
+function commentsChanged({ save = true } = {}) {
+  const deck = deckIndex();
+  if (save) { saveReview(REVIEW.json, review); reviewSaved = fs.readFileSync(REVIEW.json, "utf8"); }
+  try { writePacket(deck); } catch (e) { console.error(e.message); }
+  const view = commentsView(deck);
+  broadcast("comments", view);
+  return view;
+}
+// edits of the file by another program (an agent marks a comment resolved): polled, which survives replaced files
+function syncReview() {
+  let now = null;
+  try { now = fs.readFileSync(REVIEW.json, "utf8"); } catch {}
+  if (now === reviewSaved) return false;
+  readReview();
+  return true;
+}
+fs.watchFile(REVIEW.json, { interval: 1000 }, () => { if (syncReview()) commentsChanged({ save: false }); });
+
+/* Rendering while PinDeck runs (see Quarto above): started by a change to a source file */
+let rendering = null, renderAgain = false, renderError = startRenderError, renderTimer = null, renderStarted = Date.now();
+if (renderError) {
+  addEntry({ kind: "notice", text: renderError + `\nThe deck shown is the last render that worked.` });
+  state.notes.push(renderError + "\nFix the source; PinDeck renders again after every change.");
+}
+function render() {
+  clearTimeout(renderTimer);
+  renderTimer = null;
+  if (rendering) { renderAgain = true; return rendering; }
+  renderStarted = Date.now();
+  rendering = new Promise((done) => {
+    execFile(QUARTO.path, ["render", SOURCE], { cwd: DECK_DIR, timeout: RENDER_TIMEOUT, maxBuffer: 1 << 24 }, (err, _out, stderr) => {
+      const was = renderError;
+      renderError = err ? quartoError(stderr || err.message) : null;
+      if (renderError && renderError !== was) {
+        addEntry({ kind: "notice", text: renderError });
+        state.notes.push(renderError + "\nFix the source; PinDeck renders again after every change.");
+      } else if (!renderError && was) addEntry({ kind: "notice", text: `${SOURCE} renders again.` });
+      if (!err) runEidPass();   // the fresh output gets its element ids (and the editor reloads it)
+      done();
+    });
+  }).finally(() => {
+    rendering = null;
+    if (renderAgain) { renderAgain = false; render(); }
+    pushStatus();
+  });
+  pushStatus();
+  return rendering;
+}
+function sourceChanged() {
+  clearTimeout(renderTimer);
+  renderTimer = setTimeout(render, 150);   // an editor's save is often several events
+}
+/* Before the assistant looks at the deck: a pending or running render ends first, and a source saved since the
+   last render began (its file event may not have come yet) is rendered now */
+async function rendered() {
+  if (!SOURCE) return null;
+  let saved = 0;
+  try { saved = fs.statSync(path.join(DECK_DIR, SOURCE)).mtimeMs; } catch {}
+  if (renderTimer || saved > renderStarted) render();
+  while (rendering) await rendering;
+  return renderError;
+}
+
 /* ---- 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,
@@ -1092,6 +1243,10 @@ 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;
+  if (SOURCE) {
+    if (isOutput(file)) { if (rendering || file !== DECK_FILE) return; }   // a render's own writes: its id pass reloads
+    else if (SOURCE_FILE.test(file)) sourceChanged();
+  }
   changed.add(file);
   scheduleFlush();
 }
@@ -1128,6 +1283,7 @@ function scheduleFlush() {
       };
       eidTimer = setTimeout(pass, 800);
     }
+    if (files.includes(DECK_FILE) && review?.comments.length) commentsChanged({ save: false });   // found again, or flagged
     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) {
@@ -1211,14 +1367,17 @@ function recordHandEdit(before, html, label, note, { manual = true, deletedFiles
 /* What deleting an element would remove, and which of its files nothing else uses. Files outside the
    deck folder, in vendor/, or still referenced elsewhere (the rest of the deck, theme.css, brand.css, or
    another deck in the folder or one folder down, which may share figures/) are never offered. */
-function deletePlan(eid) {
+/* What deleting one or more elements removes: the elements (a picture with its caption; an element inside another
+   one that goes too is left out) and the files they refer to */
+function deletePlan(eids) {
   const html = readDeck(DECK_FILE);
-  const target = deleteTarget(html, eid);
-  if (!target) return null;
-  const rest = removeElement(html, target.eid);
+  let targets = [].concat(eids).map((eid) => deleteTarget(html, eid));
+  if (!targets.length || targets.some((t) => !t)) return null;
+  targets = targets.filter((t, i) => !targets.some((o, j) => o.eid === t.eid ? j < i : o.outer.includes(`data-eid="${t.eid}"`)));
+  const rest = targets.reduce((h, t) => removeElement(h, t.eid), html);
   const css = (readDeck("theme.css") || "") + (readDeck("brand.css") || "");
   const others = otherDeckRefs();
-  const files = fileRefs(target.outer).flatMap((ref) => {
+  const files = [...new Set(targets.flatMap((t) => fileRefs(t.outer)))].flatMap((ref) => {
     const abs = path.resolve(DECK_DIR, ref);
     const rel = path.relative(DECK_DIR, abs).split(path.sep).join("/");
     if (rel.startsWith("..") || rel.startsWith("vendor/") || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) return [];
@@ -1227,7 +1386,7 @@ function deletePlan(eid) {
     const usedElsewhere = fileRefs(rest).some((r) => path.resolve(DECK_DIR, r) === abs) || css.includes(ref) || css.includes(rel) || usedBy.length > 0;
     return [{ rel, bytes: fs.statSync(abs).size, usedElsewhere, usedBy }];
   });
-  return { ...target, html: rest, files };
+  return { ...targets[0], targets: targets.map(({ eid, tag }) => ({ eid, tag })), html: rest, files };
 }
 /* The other decks of this folder and one folder down, each with a test of whether it refers to a file: in its
    HTML (relative to its own folder), or in the stylesheets beside it */
@@ -1302,7 +1461,7 @@ function undo(res) {
 /* ---- PowerPoint import -----------------------------------------------------------------------------
    Upload: the file is read at once (slide list for the dialog); in the background PowerPoint or Keynote
    makes a PDF of it, from which come the thumbnails and, on import, the pictures of diagrams.
-   Only the latest upload is kept, in ~/.pindeck-v3/decks/<deck>/imports/. */
+   Only the latest upload is kept, in ~/.pindeck-v4/decks/<deck>/imports/. */
 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 }
@@ -1468,6 +1627,7 @@ function serveFile(res, file, transform, req, extra = {}) {
 let ready = false;
 const NEEDS_DECK = /^\/api\/(message|slides|layout|shot|pdf|pdf-figure|edit|text|split|remove|notes|delete|delete-info|source|slide-hidden|move-slide|add-slide|import-apply|export)$/;
 const CLI_ROUTES = /^\/api\/(slides|layout|shot|pdf|pdf-figure)$/;   // answered as text, for cli.mjs
+const HAND_EDITS = /^\/api\/(edit|text|split|remove|notes|delete|slide-hidden|move-slide|add-slide|import|import-apply)$/;   // refused for a Quarto deck
 /* Scriptable files (HTML, SVG) from the deck get the sandbox, wherever they are asked for. Under /v/ they are
    read by documents of that sandboxed origin, so fonts and module scripts need CORS; the path is the secret.
    On localhost (Present) there is no sandbox: no login works there (see presentHost). */
@@ -1494,7 +1654,7 @@ const server = http.createServer(async (req, res) => {
     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);
+      return serveFile(res, path.join(EDITOR_DIR, "public/index.html"), (s) => s.replace("{{VERSION}}", VERSION), req);
     }
     if (req.method === "GET" && p.startsWith("/editor/")) {
       const f = safeJoin(path.join(EDITOR_DIR, "public"), p.slice(8));
@@ -1571,6 +1731,14 @@ const server = http.createServer(async (req, res) => {
       return;
     }
     // the deck file gone (moved, renamed, deleted) while PinDeck runs: say so, instead of failing on it
+    // a Quarto deck is rendered from its source: no hand edits of the output (the next render would undo them)
+    if (SOURCE && req.method === "POST" && HAND_EDITS.test(p))
+      return json(res, 409, { code: "quarto", error: `${DECK_FILE} is rendered by Quarto from ${SOURCE}: ask the assistant, or edit ${SOURCE} yourself.` });
+    // what the assistant checks is the deck rendered from its last edit
+    if (SOURCE && CLI_ROUTES.test(p)) {
+      const failed = await rendered();
+      if (failed) return text(res, 409, failed + `\nFix ${SOURCE}; PinDeck renders again after every change.`);
+    }
     if (NEEDS_DECK.test(p) && readDeck(DECK_FILE) == null) {
       const why = `${path.join(DECK_DIR, DECK_FILE)} is not there any more (moved, renamed or deleted). Put it back, ` +
         `or start PinDeck for the deck where it is now.`;
@@ -1599,6 +1767,7 @@ const server = http.createServer(async (req, res) => {
       const placed = (x) => x && typeof x.eid === "string" && x.slide && Number.isInteger(x.slide.index) && x.box;
       b.pins = (Array.isArray(b.pins) ? b.pins : []).filter((p) => placed(p) && p.point && p.at);
       if (!placed(b.selection)) b.selection = null;
+      else b.selection.also = (Array.isArray(b.selection.also) ? b.selection.also : []).filter((x) => x && typeof x.eid === "string" && x.box);
       if (!Array.isArray(b.layouts)) b.layouts = [];
       if (b.current && !Number.isInteger(b.current.index)) b.current = null;
       const preparation = { cancelled: false, controller: new AbortController() };
@@ -1625,13 +1794,72 @@ const server = http.createServer(async (req, res) => {
         const entry = addEntry({ kind: "user", text: b.text,
           screenshot: screenshot && { file: path.basename(screenshot.path), slide: screenshot.slide },
           attachments: b.attachments.map((a) => ({ path: a.path, kind: a.kind, name: a.name })),
-          selection: b.selection ? { eid: b.selection.eid, label: b.selection.eid.replace(/^[^/]+\//, ""), slide: b.selection.slide.index + 1 } : null,
+          selection: b.selection ? { eid: b.selection.eid, label: b.selection.eid.replace(/^[^/]+\//, "") + (b.selection.also.length ? ` +${b.selection.also.length}` : ""), slide: b.selection.slide.index + 1 } : null,
           pins: (b.pins || []).map((p) => ({ n: p.n, eid: p.eid, label: label(p), slide: p.slide.index + 1 })) });
         if (shotFailed) addEntry({ kind: "notice", text: `Screenshot of slide ${shotFailed.slide} failed: ${shotFailed.error}` });
         startTurn(buildPrompt({ ...b, screenshot, shotFailed }), entry);
         return json(res, 200, { id: entry.id });
       } finally { state.preparing = null; if (!state.turn) { state.busy = false; pushStatus(); } }
     }
+    if (p === "/api/comments" && req.method === "GET") return json(res, 200, commentsView());
+    // `cli.mjs resolve <id or C3> [what was done]`: the assistant (or a terminal) marks a comment resolved;
+    // `cli.mjs reply <id or C3> <text>`: it answers one it leaves open (why not, a question), in the comment's thread
+    if (p === "/api/resolve" || p === "/api/reply") {
+      syncReview();   // the poll may not have seen another program's edit yet: saving now would undo it
+      if (!review) return text(res, 409, reviewProblem);
+      const want = String(url.searchParams.get("id") || "").trim();
+      const n = /^C(\d+)$/i.exec(want)?.[1];
+      const c = n ? review.comments[+n - 1] : review.comments.find((x) => x.id === want);
+      if (!c) return text(res, 404, `No comment "${want}". Comment ids look like c-1a2b3c4d (or C3, its number in the editor).`);
+      const note = String(url.searchParams.get("note") || "").trim().slice(0, 2000);
+      const by = state.busy ? "assistant" : "command line";
+      const name = `C${review.comments.indexOf(c) + 1} (${c.id})`;
+      if (p === "/api/reply") {
+        if (!note) return text(res, 400, "Write the reply after the comment id.");
+        (c.replies ||= []).push({ by, text: note, at: new Date().toISOString() });
+      } else {
+        c.status = "resolved";
+        c.resolvedBy = by;
+        c.resolution = note.slice(0, 500) || null;
+      }
+      c.updated = new Date().toISOString();
+      commentsChanged();
+      return text(res, 200, p === "/api/reply" ? `Replied to ${name}; it stays open.` : `Resolved ${name}.`);
+    }
+    if (p === "/api/comments-request" && req.method === "GET") {
+      if (!review) return json(res, 409, { error: reviewProblem });
+      return json(res, 200, { text: commentsRequest(review, deckIndex(), { source: SOURCE, srcText: sourceText() }) });
+    }
+    if (/^\/api\/comment(-update|-delete)?$/.test(p) && req.method === "POST") {
+      syncReview();
+      if (!review) return json(res, 409, { error: reviewProblem });
+      const b = await body(req);
+      if (p === "/api/comment") {
+        if (typeof b.text !== "string" || !b.text.trim()) return json(res, 400, { error: "Write the comment first." });
+        let c;
+        try { c = commentFromPin(deckIndex(), { pin: b.pin || null, slide: b.slide }, b.text); }
+        catch (e) { return json(res, 409, { error: e.message }); }
+        review.comments.push(c);
+        return json(res, 200, { id: c.id, ...commentsChanged() });
+      }
+      const c = review.comments.find((x) => x.id === b.id);
+      if (!c) return json(res, 404, { error: "No such comment (removed meanwhile?)." });
+      if (p === "/api/comment-delete") review.comments = review.comments.filter((x) => x !== c);
+      else {
+        if (typeof b.text === "string") { if (!b.text.trim()) return json(res, 400, { error: "A comment cannot be empty." }); c.text = b.text.trim(); }
+        if (typeof b.reply === "string") {
+          if (!b.reply.trim()) return json(res, 400, { error: "Write the reply first." });
+          (c.replies ||= []).push({ by: "you", text: b.reply.trim(), at: new Date().toISOString() });
+        }
+        if (b.status === "open" || b.status === "resolved") {
+          c.status = b.status;
+          c.resolvedBy = b.status === "resolved" ? "you" : undefined;
+          if (b.status === "open") c.resolution = undefined;
+        }
+        c.updated = new Date().toISOString();
+      }
+      return json(res, 200, commentsChanged());
+    }
     if (p === "/api/upload" && req.method === "POST") {
       const original = decodeURIComponent(String(req.headers["x-filename"] || "file"));
       const kind = attachKind(original);
@@ -1817,27 +2045,27 @@ const server = http.createServer(async (req, res) => {
 
     // Delete an element (and, if the user agrees, the files only it uses)
     if (p === "/api/delete-info") {
-      const plan = deletePlan(url.searchParams.get("eid"));
+      const plan = deletePlan(url.searchParams.getAll("eid"));
       if (!plan) return json(res, 404, { error: "Element not found in the file." });
-      return json(res, 200, { eid: plan.eid, tag: plan.tag, files: plan.files });
+      return json(res, 200, { eid: plan.eid, tag: plan.tag, targets: plan.targets, files: plan.files });
     }
     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);
+      const plan = deletePlan(Array.isArray(b.eids) ? b.eids : b.eid);
       if (!plan) return json(res, 404, { error: "Element not found in the file." });
       const before = snapshot(EDITABLE);
       const wanted = new Set(b.files || []);
       const deletedFiles = plan.files.filter((f) => wanted.has(f.rel) && !f.usedElsewhere)
         .map((f) => ({ rel: f.rel, data: fs.readFileSync(path.join(DECK_DIR, f.rel)) }));
-      const short = plan.eid.replace(/^[^/]+\//, "/");
+      const short = plan.targets.map((t) => t.eid.replace(/^[^/]+\//, "/")).join(", ");
       const label = `Deleted ${short}` + (deletedFiles.length ? ` and ${deletedFiles.map((f) => f.rel).join(", ")}` : "");
       const turnId = recordHandEdit(before, plan.html, label,
-        `The user deleted ${plan.eid} (${plan.tag}) by hand` + (deletedFiles.length ? `, together with the file(s) ${deletedFiles.map((f) => f.rel).join(", ")}` : "") + ".",
+        `The user deleted ${plan.targets.map((t) => `${t.eid} (${t.tag})`).join(", ")} by hand` + (deletedFiles.length ? `, together with the file(s) ${deletedFiles.map((f) => f.rel).join(", ")}` : "") + ".",
         { manual: false, deletedFiles });
       for (const f of deletedFiles) removeDeckFile(f.rel);
-      return json(res, 200, { turnId, deleted: plan.eid, files: deletedFiles.map((f) => f.rel) });
+      return json(res, 200, { turnId, deleted: plan.targets.map((t) => t.eid), files: deletedFiles.map((f) => f.rel) });
     }
 
     // Hand edits from the editor: drag/resize (inline styles) and text
@@ -1948,6 +2176,11 @@ const server = http.createServer(async (req, res) => {
       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/element") {
+      const eid = url.searchParams.get("eid") || "";
+      const outer = getOuter(readDeck(DECK_FILE) || "", eid);
+      return outer === null ? text(res, 404, `No element "${eid}" in ${DECK_FILE}. Give a data-eid.`) : text(res, 200, outer);
+    }
     if (p === "/api/layout" || p === "/api/shot") {
       const slide = resolveSlide(url.searchParams.get("slide"));
       if (!slide) return text(res, 404, deckProblemNow() || `No slide "${url.searchParams.get("slide")}". Use \`${CLI_CMD} slides\`.`);
@@ -1991,6 +2224,7 @@ server.listen(PORT, "127.0.0.1", () => {
     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();
+    try { writePacket(); } catch (e) { console.error(e.message); }
   } catch (e) {
     console.error(e.plain ? e.message : `PinDeck could not open the deck: ${e.message}`);
     removeServerInfo();
@@ -2019,6 +2253,7 @@ async function quit() {
   if (quitting) process.exit(1);
   quitting = true;
   try { watcher?.close(); } catch {}
+  fs.unwatchFile(REVIEW.json);
   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")); }