pindeck 3.4.0 → 4.0.0-beta.1

package/server.mjs

@@ -10,18 +10,18 @@
    - 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 { unifiedDiff } from "./lib/diff.mjs";
@@ -44,6 +44,7 @@ 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
@@ -70,9 +71,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 +105,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 +345,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 +586,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 +606,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 +633,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 +644,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 +698,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, 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 +726,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", "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 +904,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", "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) };
     }
@@ -1082,6 +1138,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 +1240,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 +1280,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) {
@@ -1302,7 +1455,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 +1621,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). */
@@ -1571,6 +1725,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.`;
@@ -1632,6 +1794,65 @@ const server = http.createServer(async (req, res) => {
         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);
@@ -1991,6 +2212,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 +2241,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")); }