pindeck 3.4.0 → 4.1.0-beta.1

package/lib/review.mjs

@@ -0,0 +1,200 @@
+/* Review comments (after Sebastian J. Schlecht's review mode for PinDeck).
+
+   A comment is a note on a slide or one of its elements, kept for later instead of sent to the assistant now.
+   Comments live in <deck folder>/.pindeck/<deck>.review.json: a dot folder, so they are never deck files, never
+   part of an undo and never edited by the assistant. Each comment keeps what it needs to be found again after
+   the deck changes: the slide's id attribute (Quarto's heading anchor), title and position, and the element's
+   id, tag and text. A comment whose slide or element cannot be found again is flagged, never silently moved.
+   Next to the comments, <deck>.review.md is the review packet: the open comments, for an agent outside PinDeck. */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { assignEids, parse, findSlides, walk, textOf } from "./eids.mjs";
+import { writeAtomic } from "./deck-files.mjs";
+
+const norm = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+const classes = (n) => (n.attrs?.class?.value || "").split(/\s+/).filter(Boolean);
+const tagOf = (n) => [n.name, ...classes(n)].join(".");
+
+/* The deck as comments see it: per slide, its id attribute, title, position in the stacks and its elements by
+   id. Ids are assigned in memory (a deck PinDeck has opened has them already; a rendered Quarto deck gets them
+   again after each render). */
+export function indexDeck(html) {
+  const withIds = assignEids(html).html;
+  const tree = parse(withIds);
+  const slides = findSlides(tree).map((sec, index) => {
+    const stacked = sec.parent?.name === "section";
+    const top = stacked ? sec.parent : sec;
+    const siblings = (n) => (n.parent?.children || []).filter((c) => c.name === sec.name);
+    let head = null;
+    walk(sec, (c) => { if (head) return false; if (/^h[1-3]$/.test(c.name)) { head = c; return false; } });
+    const elements = new Map();
+    walk(sec, (c) => {
+      if (c.name === "section" || (c.name === "aside" && classes(c).includes("notes"))) return false;
+      const eid = c.attrs?.["data-eid"]?.value;
+      if (!eid) return;
+      let fragment = false;
+      for (let p = c; p && p !== sec; p = p.parent) if (classes(p).includes("fragment")) fragment = true;
+      const src = c.name === "img" ? (c.attrs["data-src"] || c.attrs.src)?.value : null;
+      elements.set(eid, { eid, tag: tagOf(c), text: norm(src || textOf(withIds, c)), fragment });
+    });
+    return {
+      index, eid: sec.attrs["data-eid"]?.value, id: sec.attrs.id?.value || null,
+      title: head ? norm(textOf(withIds, head)) : "",
+      h: siblings(top).indexOf(top), v: stacked ? siblings(sec).indexOf(sec) : 0, elements,
+    };
+  });
+  return { html: withIds, slides };
+}
+
+/* A new comment from a pin placed in the editor (bridge.js onClick), or from the slide as a whole (pin null,
+   slide { index, eid }). */
+export function commentFromPin(deck, { pin, slide: whole }, text) {
+  const ref = pin ? pin.slide : whole;
+  const slide = deck.slides[ref?.index];
+  if (!slide || slide.eid !== ref.eid) throw new Error("The slide has changed since the pin was placed. Pin it again.");
+  const onSlide = !pin || pin.eid === slide.eid;
+  const el = onSlide ? null : slide.elements.get(pin.eid);
+  if (!onSlide && !el) throw new Error("Element not found in the deck. Pin it again.");
+  const r = (v) => Math.round(v * 1e4) / 1e4;
+  const now = new Date().toISOString();
+  return {
+    id: "c-" + crypto.randomBytes(4).toString("hex"), created: now, updated: now, status: "open", text: String(text).trim(),
+    slide: { id: slide.id, eid: slide.eid, title: slide.title, h: slide.h, v: slide.v },
+    target: el ? { eid: el.eid, tag: el.tag, text: el.text, fragment: el.fragment, word: pin.word || null, cell: pin.cell || null }
+      : { eid: null, tag: "section", text: "", fragment: false, word: null, cell: null },
+    // where the marker sits: on the slide (px), and inside its element (0..1 of its box)
+    point: pin?.point ? { x: r(pin.point.x), y: r(pin.point.y) } : null,
+    at: pin?.at ? { fx: r(pin.at.fx), fy: r(pin.at.fy) } : null,
+  };
+}
+
+/* Where a stored comment is in the deck as it is now.
+   status: ok        same slide, same element, same text
+           moved     the element's text was found elsewhere on the slide (ids can be positional)
+           changed   the element is there but its text differs: possibly already addressed
+           missing   the slide is there, the element is not
+           no-slide  neither the slide's id nor its title exists any more
+   Only "ok" and "moved" place the marker on the element; the others at the stored point on the slide (if any). */
+export function locate(deck, c) {
+  // shortcut: repeated titles resolve to the first; add an h/v tiebreak if decks repeat titles without ids
+  const slide = (c.slide.id && deck.slides.find((s) => s.id === c.slide.id)) ||
+    (c.slide.eid && deck.slides.find((s) => s.eid === c.slide.eid && (!c.slide.title || s.title === c.slide.title))) ||
+    (c.slide.title && deck.slides.find((s) => s.title === c.slide.title));
+  if (!slide) return { status: "no-slide", slide: null, eid: null };
+  const t = c.target;
+  if (!t.eid) return { status: "ok", slide, eid: null };
+  const els = [...slide.elements.values()];
+  const same = slide.elements.get(t.eid);
+  if (same && same.tag === t.tag && same.text === t.text) return { status: "ok", slide, eid: same.eid };
+  const moved = t.text && (els.find((e) => e.tag === t.tag && e.text === t.text) || els.find((e) => e.text === t.text));
+  if (moved) return { status: "moved", slide, eid: moved.eid };
+  if (same && same.tag === t.tag) return { status: "changed", slide, eid: null, now: same.text };
+  return { status: "missing", slide, eid: null };
+}
+export const matched = (status) => status === "ok" || status === "moved";
+
+/* ---- The comments file ------------------------------------------------------------------------ */
+export function reviewFiles(deckDir, deckFile) {
+  const base = path.join(deckDir, ".pindeck", deckFile.replace(/\.html?$/i, ""));
+  return { json: base + ".review.json", packet: base + ".review.md" };
+}
+export function loadReview(file) {
+  try {
+    const r = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!r || !Array.isArray(r.comments)) throw new Error(`${file} is not a PinDeck comments file.`);
+    // edited by hand or by another agent: a comment without what locate() needs would crash the server later
+    const bad = r.comments.findIndex((c) => typeof c?.id !== "string" || typeof c.text !== "string" || !c.slide || typeof c.slide !== "object" || !c.target || typeof c.target !== "object");
+    if (bad >= 0) throw new Error(`comment ${bad + 1} lacks its id, text, slide or target`);
+    const badReplies = r.comments.findIndex((c) => c.replies != null && !(Array.isArray(c.replies) && c.replies.every((x) => typeof x?.text === "string")));
+    if (badReplies >= 0) throw new Error(`comment ${badReplies + 1} has replies that are not a list of { by, text }`);
+    return r;
+  } catch (e) { if (e.code === "ENOENT") return { pindeckReview: 1, deck: {}, comments: [] }; throw e; }
+}
+export function saveReview(file, review) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  writeAtomic(file, JSON.stringify(review, null, 2) + "\n");   // a crash never leaves half a file
+}
+
+/* ---- The review packet ------------------------------------------------------------------------------ */
+const pandocId = (s) => norm(s.replace(/\{[^}]*\}\s*$/, "")).toLowerCase()
+  .replace(/[^\p{L}\p{N}\s_.-]/gu, "").replace(/^[^\p{L}]+/u, "").replace(/\s+/g, "-");
+
+/* 1-based line of the slide's heading in a Quarto/Markdown source, or null. */
+export function sourceLine(srcLines, slide) {
+  if (!srcLines || !slide) return null;
+  const i = srcLines.findIndex((l) => {
+    const m = /^#{1,3}\s+(.*)$/.exec(l);
+    if (!m) return false;
+    const explicit = /\{[^}]*#([\w:.-]+)/.exec(m[1]);
+    return explicit ? explicit[1] === slide.id : pandocId(m[1]) === slide.id || norm(m[1]) === slide.title;
+  });
+  return i < 0 ? null : i + 1;
+}
+
+const STATUS = {
+  ok: "ok", moved: "ok (element found again by its text)",
+  changed: "UNMATCHED: the element's text has changed since the comment (maybe already addressed)",
+  missing: "UNMATCHED: the element is no longer on this slide",
+  "no-slide": "UNMATCHED: the slide is no longer in the deck",
+};
+const clip = (s, n = 240) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+const slideName = (s) => `slide ${s.h + 1}${s.v ? "." + s.v : ""} “${s.title || "(untitled)"}”`;
+
+/* The open comments in deck order, each with where it is now and its number in the editor's list (C1, C2, …) */
+export function openComments(review, deck) {
+  const n = new Map(review.comments.map((c, i) => [c.id, i + 1]));
+  const key = (x) => (x.loc.slide ? x.loc.slide.index : 1e6) * 1e5 + (x.c.point?.y ?? 0);
+  return review.comments.filter((c) => c.status !== "resolved").map((c) => ({ c, n: n.get(c.id), loc: locate(deck, c) }))
+    .sort((a, b) => key(a) - key(b));
+}
+const who = (by) => (by === "you" ? "Reviewer" : by === "assistant" ? "Assistant" : by ? `${by[0].toUpperCase()}${by.slice(1)}` : "Agent");
+function items(list, lines) {
+  return list.flatMap(({ c, n, loc }) => {
+    const s = loc.slide, t = c.target;
+    const line = sourceLine(lines, s || { id: c.slide.id, title: c.slide.title });
+    return [`## C${n}. ${s ? slideName(s) : "was " + slideName(c.slide)}`, "",
+      `> ${c.text.replace(/\n/g, "\n> ")}`, "",
+      `- Slide: ${c.slide.id ? `\`#${c.slide.id}\`` : `\`${s?.eid || c.slide.eid}\``}${line ? `, source line ${line}` : ""} — ${STATUS[loc.status]}`,
+      t.eid ? `- Element: \`${t.tag}\`${matched(loc.status) ? ` (data-eid \`${loc.eid}\`)` : ""}${t.fragment ? ", a build step" : ""}: “${clip(t.text)}”`
+        : "- Element: the slide as a whole",
+      ...(t.word ? [`- Clicked word: “${t.word}”`] : []),
+      ...(t.cell ? [`- Table cell: row ${t.cell.row + 1}, column ${t.cell.col + 1}: “${clip(t.cell.text || "", 80)}”`] : []),
+      ...(loc.status === "changed" ? [`- Text now: “${clip(loc.now)}”`] : []),
+      ...(c.replies?.length ? ["- Thread, oldest first:", ...c.replies.map((r) => `  - ${who(r.by)}: ${r.text.replace(/\n/g, " ")}`)] : []),
+      `- Comment id: \`${c.id}\``, ""];
+  });
+}
+
+/* For an agent outside PinDeck (Claude Code in an editor, say): written next to the comments file */
+export function packet(review, deck, { deckFile = "the deck", source = null, srcText = null, commentsFile = "?" } = {}) {
+  const open = openComments(review, deck);
+  const stale = open.filter((x) => !matched(x.loc.status));
+  const resolved = review.comments.length - open.length;
+  return [
+    `# Slide review: ${deckFile}`, "",
+    `- Deck: \`${deckFile}\`${source ? `, source \`${source}\`` : ""}`,
+    `- Comments: \`${commentsFile}\``,
+    `- ${open.length} open comment(s), ${stale.length} unmatched; ${resolved} resolved (not listed).`, "",
+    "These are reviewer comments on the slides. They are not speaker notes: do not copy them into the deck.",
+    source ? `Make each change in the source (\`${source}\`, its stylesheets or figure scripts), never in the rendered HTML, ` +
+      "which the next render overwrites. Render, then" : "Make each change, then",
+    "set the comment's `status` to `\"resolved\"` in the comments file. If you cannot do one, or it is unclear, leave it open",
+    "and add `{ \"by\": \"agent\", \"text\": \"<why>\" }` to its `replies` list, where the reviewer can answer. Read a comment's",
+    "thread before acting on it. UNMATCHED comments point at slides or text that changed after the comment was made:",
+    "check whether they still apply before acting on them.", "",
+    ...items(open, srcText?.split("\n")),
+  ].join("\n");
+}
+
+/* For PinDeck's own assistant: the open comments as one request, put in the message box for the user to send */
+export function request(review, deck, { source = null, srcText = null } = {}) {
+  const open = openComments(review, deck);
+  if (!open.length) return "";
+  return [`Please address these ${open.length} review comment(s), one by one. They are notes for you, not slide text or speaker notes.`,
+    "Mark each one you have addressed as resolved with PinDeck's resolve command and its comment id. If one is unclear or no",
+    "longer applies, leave it open and say why with PinDeck's reply command instead of guessing. Where a comment has a",
+    "thread, the reviewer's latest answer is what to act on.", "",
+    ...items(open, source ? srcText?.split("\n") : null)].join("\n").trim();
+}

package/lib/servers.mjs

@@ -2,7 +2,7 @@
    `pindeck login` and cli.mjs.
 
    Each PinDeck process (a front, a deck server on its own, or one behind a front) keeps a file of its own in
-   ~/.pindeck-v3/servers/<pid>.json (0600, in a 0700 folder) with its address and token. Several fronts and
+   ~/.pindeck-v4/servers/<pid>.json (0600, in a 0700 folder) with its address and token. Several fronts and
    servers can run side by side (another --port, another PINDECK_HOME user, a server started on its own) and
    none overwrites another's file; a file whose process is gone is removed when it is read. */
 

package/lib/system-prompt.md

@@ -69,7 +69,8 @@ this path to cli.mjs even if another one appears earlier in the conversation, ea
 convert or ls. Such commands are refused (or need an approval nobody can give) and are not run. A
 refused command did nothing: do not retry it as it is, do it another way.
 - To change files, use Edit, even for large changes: several Edit calls in a row are fine.
-- To look at files, use Read, Grep and Glob.
+- To look at files, use Read, Grep and Glob. A slide can be one very long line: to see one element of
+  it, run `{{CLI}} element <data-eid>...`, which prints that element's HTML exactly as written.
 - To check several slides, name them all: `{{CLI}} layout 9 10 11 --issues`.
 
 ## Checking your work
@@ -81,6 +82,15 @@ overlapping elements, clipped text); add --issues to print only the issues. Fix
   {{CLI}} shot <slide-eid or number>...
 only when you need a visual judgement the numbers cannot give (balance, figure content, colour)
 or the user asks; it prints the path of a PNG, which you then Read.
+## Review comments
+The user can keep comments on slides (ids c-…, numbered C1, C2, … in the editor) and ask you to address them.
+They are notes for you, not slide text or speaker notes. When you have addressed one, mark it resolved:
+  {{CLI}} resolve <comment id> <one line on what you did>
+Leave a comment open when you could not do it, or it was unclear, and say why on the comment itself, where the
+user can answer you:
+  {{CLI}} reply <comment id> <why not, or what you need to know>
+A comment's thread (your replies and the user's) comes with it; read the user's latest answer before acting.
+
 If the user asks for a PDF, run `{{CLI}} pdf handout` (one page per slide, build steps complete) or
 `{{CLI}} pdf presentation` (one page per build step); it prints the path of the PDF.
 
@@ -91,7 +101,8 @@ inline styles on the element in {{DECK}}: `translate: Xpx Ypx` for moves, `width
 keep them unless asked. If the user asks to clean up, move them into proper CSS rules.
 The user can also edit text in place (double-click); you get a note with the new text. Keep their
 wording unless asked to change it.
-A selected element is listed in <editor-context>; "this" or "it" usually means that element.
+A selected element is listed in <editor-context>; "this" or "it" usually means that element. When
+several are selected, "these" or "them" means all of them.
 
 ## Replies
 Replies appear in a narrow sidebar. Keep them short: 1 to 4 sentences saying what you changed,

package/lib/usage.mjs

@@ -1,15 +1,16 @@
 /* pindeck --help, and the hint after a bad argument: the front (front.mjs) and a deck server (server.mjs)
    take the same arguments. */
-export const USAGE = `Usage: pindeck [deck-folder | deck-file.html] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <folder>]...
+export const USAGE = `Usage: pindeck [deck-folder | deck-file.html | quarto-deck.qmd] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <folder>]...
        pindeck login [deck-folder | deck-file.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 folder without one opens a list of its decks. 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">.
+<meta name="pindeck:size" content="1440x1080">. A Quarto deck (talk.qmd) is rendered by PinDeck, and the
+assistant edits its source.
 In the editor, the deck's name opens the other decks in the deck's folder and the asset roots (and one
 folder down), each with its own chat and undo, on the same port and login.
 login prints a new one-time login link for the running PinDeck (with a deck: one that opens that deck).
 --asset-root lets the deck use files outside its folder: a folder that contains the deck (paths such as
 ../shared/style.css then work), or one that symlinks in the deck may point to. Repeatable; also
-"assetRoots" in ~/.pindeck-v3/config.json.`;
+"assetRoots" in ~/.pindeck-v4/config.json.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pindeck",
-  "version": "3.4.0",
+  "version": "4.1.0-beta.1",
   "description": "PinDeck: an editor for HTML slide decks on macOS, and on Linux through an SSH tunnel. Pin elements, describe the change, and Claude Code or OpenAI Codex edits the slides.",
   "keywords": [
     "slides",
@@ -32,6 +32,9 @@
     "lib/",
     "public/",
     "README.md",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "!docs/v4-plan.md",
     "LICENSE"
   ],
   "scripts": {

package/public/bridge.js

@@ -42,6 +42,9 @@
       background:#ED8C01; color:#fff; font:700 calc(14px*var(--pindeck-u,1))/calc(26px*var(--pindeck-u,1)) system-ui, sans-serif; text-align:center;
       box-shadow:0 0 0 calc(2px*var(--pindeck-u,1)) #fff, 0 calc(2px*var(--pindeck-u,1)) calc(6px*var(--pindeck-u,1)) rgba(0,0,0,.45);
       cursor:pointer; pointer-events:auto; }
+    .__pin.__comment { background:#1a73e8; border-radius:calc(6px*var(--pindeck-u,1)); width:auto; min-width:calc(26px*var(--pindeck-u,1));
+      padding:0 calc(5px*var(--pindeck-u,1)); }
+    .__pin.__stale { background:#8a8f98; }
     .__hover { position:absolute; z-index:999; pointer-events:none; outline:calc(2px*var(--pindeck-u,1)) dashed #ED8C01;
       outline-offset:calc(2px*var(--pindeck-u,1)); background:rgba(237,140,1,.06); }
     .__hover span { position:absolute; left:calc(-2px*var(--pindeck-u,1)); background:#ED8C01; color:#fff; white-space:nowrap;
@@ -64,7 +67,8 @@
     .__sel i[data-h="ne"] { left:100%; top:0; cursor:nesw-resize; } .__sel i[data-h="e"] { left:100%; top:50%; cursor:ew-resize; }
     .__sel i[data-h="se"] { left:100%; top:100%; cursor:nwse-resize; } .__sel i[data-h="s"] { left:50%; top:100%; cursor:ns-resize; }
     .__sel i[data-h="sw"] { left:0; top:100%; cursor:nesw-resize; } .__sel i[data-h="w"] { left:0; top:50%; cursor:ew-resize; }
-    .__sel.readonly i { display:none; }
+    .__sel.readonly i, .__sel.multi i { display:none; }
+    html.__selmode ${SLIDE} .__selected.__member { outline:calc(1px*var(--pindeck-u,1)) dashed #1a73e8; outline-offset:0; }
     .__sel-label { position:absolute; left:calc(-1.5px*var(--pindeck-u,1)); white-space:nowrap; background:#1a73e8; color:#fff;
       font:600 calc(11px*var(--pindeck-u,1))/calc(17px*var(--pindeck-u,1)) system-ui, sans-serif; padding:0 calc(5px*var(--pindeck-u,1));
       border-radius:calc(3px*var(--pindeck-u,1)); font-variant-numeric:tabular-nums; }
@@ -102,19 +106,22 @@
   const byEid = (eid, root = document) => root.querySelector(`[data-eid="${CSS.escape(eid)}"]`);
 
   /* Visible text of an element, without KaTeX's hidden MathML copy. */
+  const MATH_TEX = 'script[type^="math/tex"]';   // MathJax 2 (Quarto) keeps the TeX here; its rendering is skipped
   function textOf(el, ownOnly) {
     if (el.tagName === "IMG") return el.getAttribute("alt") || (el.getAttribute("src") || "").split("/").pop();
     let out = "";
     const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, {
       acceptNode(n) {
         const p = n.parentElement;
-        if (!p || p.closest(".katex-mathml, .__pin, .__hover, .__flash, .__sel, .__guide, .__edit-hint, .__hidden-banner, aside.notes, script, style")) return NodeFilter.FILTER_REJECT;
+        if (p?.matches(MATH_TEX)) return NodeFilter.FILTER_ACCEPT;
+        if (!p || p.closest(".katex-mathml, .MathJax, .MathJax_Display, .MathJax_Preview, .MathJax_CHTML, .MathJax_SVG, mjx-container, .__pin, .__hover, .__flash, .__sel, .__guide, .__edit-hint, .__hidden-banner, aside.notes, script, style")) return NodeFilter.FILTER_REJECT;
         if (ownOnly) { const owner = p.closest("[data-eid]"); if (owner !== el) return NodeFilter.FILTER_REJECT; }
         return NodeFilter.FILTER_ACCEPT;
       },
     });
     while (walker.nextNode()) {
       const n = walker.currentNode;
+      if (n.parentElement.matches(MATH_TEX)) { out += `\\(${n.nodeValue.trim()}\\) `; continue; }
       out += n.nodeValue + (n.parentElement.closest(".katex") ? "" : " "); // KaTeX splits math into one span per glyph
     }
     return out.replace(/\u200b/g, "").replace(/\s+/g, " ").trim();
@@ -239,7 +246,8 @@
   const presentHash = (index) => deck.hash(index);   // the slide's address in the deck opened on its own
 
   /* ---- Pins and hover ---------------------------------------------------------------------- */
-  let mode = "select", pins = [], editable = true;   // mode: "select" (drag, resize) or "pin"
+  // mode: "select" (drag, resize) or "pin"; lockReason: why hand edits are off for good (a Quarto deck)
+  let mode = "select", pins = [], editable = true, lockReason = null;
   const tagOf = (el) => el.tagName.toLowerCase() + (el.classList.length ? "." + [...el.classList].filter((c) => !c.startsWith("__")).join(".") : "");
   function wordAt(x, y, el) {
     let node, offset;
@@ -250,7 +258,7 @@
       const r = document.caretRangeFromPoint(x, y);
       if (r) { node = r.startContainer; offset = r.startOffset; }
     }
-    if (!node || node.nodeType !== 3 || !el.contains(node) || node.parentElement.closest(".katex-mathml")) return null;
+    if (!node || node.nodeType !== 3 || !el.contains(node) || node.parentElement.closest(".katex-mathml, .MathJax, mjx-container")) return null;
     const s = node.nodeValue;
     const isW = (c) => /[\p{L}\p{N}_\-.,%×]/u.test(c);
     let a = offset, b = offset;
@@ -276,6 +284,8 @@
   function onClick(e) {
     if (MODE !== "main") return;
     e.preventDefault(); e.stopPropagation(); e.stopImmediatePropagation();
+    const comment = e.target.closest?.(".__comment");   // a review comment's marker opens it, in either mode
+    if (comment) { host()?.openComment(comment.dataset.comment); return; }
     if (mode !== "pin") return;
     const marker = e.target.closest?.(".__pin");
     if (marker) { host()?.removePin(+marker.dataset.n); return; }
@@ -329,10 +339,11 @@
         x = b.x + p.at.fx * b.w; y = b.y + p.at.fy * b.h;
       }
       const m = document.createElement("div");
-      m.className = "__pin";
+      m.className = "__pin" + (p.comment ? " __comment" : "") + (p.stale ? " __stale" : "");
       m.dataset.n = p.n;
+      if (p.comment) m.dataset.comment = p.comment;
       m.textContent = p.n;
-      m.title = "Click to remove pin " + p.n;
+      m.title = p.title || "Click to remove pin " + p.n;
       Object.assign(m.style, { left: x + "px", top: y + "px" });
       sec.appendChild(m);
     }
@@ -379,8 +390,22 @@
   const fmtTranslate = (x, y) => (r1(x) || r1(y) ? `${r1(x)}px ${r1(y)}px` : "");
   const nameOf = (el, sec) => { const e = el.dataset.eid || ""; return e.startsWith(sec.dataset.eid + "/") ? e.slice(sec.dataset.eid.length) : e; };
 
+  /* The selection: one element, or several on the same slide (⌘-click adds and removes). `el` is the one
+     clicked last: it is what Enter edits and what the assistant gets first. Several move together and have no
+     resize handles. */
+  const many = () => sel.els.length > 1;
+  const groupName = () => many() ? `${sel.els.length} elements (${sel.els.map((e) => nameOf(e, sel.sec)).join(", ")})` : nameOf(sel.el, sel.sec);
+  function unionBox(els, sec) {
+    const bs = els.map((e) => boxOf(e, sec));
+    const x = Math.min(...bs.map((b) => b.x)), y = Math.min(...bs.map((b) => b.y));
+    return { x, y, w: Math.max(...bs.map((b) => b.x + b.w)) - x, h: Math.max(...bs.map((b) => b.y + b.h)) - y };
+  }
   function drawSel() {
-    if (!sel || !sel.el.isConnected) return removeSel();
+    if (sel) {
+      sel.els = sel.els.filter((e) => e.isConnected);
+      if (!sel.el.isConnected) sel.el = sel.els.at(-1);
+    }
+    if (!sel?.el) return removeSel();
     if (editing) return;
     if (!selBox) {
       selBox = document.createElement("div");
@@ -388,34 +413,46 @@
       selBox.innerHTML = '<span class="__sel-label"></span>' + HANDLES.map((h) => `<i data-h="${h}"></i>`).join("");
     }
     if (selBox.parentElement !== sel.sec) sel.sec.appendChild(selBox);
-    const b = boxOf(sel.el, sel.sec);
+    const b = many() ? unionBox(sel.els, sel.sec) : boxOf(sel.el, sel.sec);
+    selBox.classList.toggle("multi", many());
+    for (const e of sel.els) e.classList.toggle("__member", many());
     Object.assign(selBox.style, { left: b.x + "px", top: b.y + "px", width: b.w + "px", height: b.h + "px" });
     selBox.classList.toggle("readonly", !editable);
     const lab = selBox.firstChild;
-    lab.textContent = `${nameOf(sel.el, sel.sec)}   ` + (drag?.kind === "move" ? `x ${b.x}  y ${b.y}` : `${b.w} × ${b.h}`);
+    lab.textContent = `${many() ? sel.els.length + " elements" : nameOf(sel.el, sel.sec)}   ` + (drag?.kind === "move" ? `x ${b.x}  y ${b.y}` : `${b.w} × ${b.h}`);
     lab.className = "__sel-label " + (b.y < 30 ? "below" : "above");
   }
-  function removeSel() { selBox?.remove(); document.querySelectorAll(".__selected").forEach((e) => e.classList.remove("__selected")); }
-  function select(el, sec, notify = true) {
+  function removeSel() { selBox?.remove(); document.querySelectorAll(".__selected").forEach((e) => e.classList.remove("__selected", "__member")); }
+  function select(el, sec, notify = true, els = el ? [el] : []) {
     removeSel();
-    sel = el ? { el, sec } : null;
-    if (sel) { sel.el.classList.add("__selected"); drawSel(); }
+    sel = el ? { el, sec, els } : null;
+    if (sel) { sel.els.forEach((e) => e.classList.add("__selected")); drawSel(); }
     if (notify) host()?.selectionChanged(sel ? selectionInfo() : null);
   }
+  // ⌘-click: add an element to the selection, or take it out. An element and one inside it cannot move
+  // together (the inner one would move twice), so adding one drops the other.
+  function toggleSel(t) {
+    if (!sel || sel.sec !== t.sec) return select(t.el, t.sec);
+    const els = sel.els.includes(t.el) ? sel.els.filter((e) => e !== t.el)
+      : [...sel.els.filter((e) => !e.contains(t.el) && !t.el.contains(e)), t.el];
+    if (!els.length) return select(null, null);
+    select(els.includes(t.el) ? t.el : els.at(-1), t.sec, true, els);
+  }
   function selectionInfo() {
     const { el, sec } = sel;
-    return { eid: el.dataset.eid, slide: slideInfo(sec), tag: tagOf(el), box: boxOf(el, sec), text: textOf(el).slice(0, 120) };
+    const info = (e) => ({ eid: e.dataset.eid, tag: tagOf(e), box: boxOf(e, sec) });
+    return { ...info(el), slide: slideInfo(sec), text: textOf(el).slice(0, 120),
+      ...(many() ? { also: sel.els.filter((e) => e !== el).map(info) } : {}) };
   }
-  function selectEid(eid) {
-    const el = eid && byEid(eid);
-    const sec = el?.closest(SLIDE_OF);
-    if (!el || sec !== deck.current()) return select(null, null);
-    select(el, sec);
+  function selectEid(eids) {
+    const els = [].concat(eids || []).map((eid) => byEid(eid)).filter((e) => e?.closest(SLIDE_OF) === deck.current());
+    if (!els.length) return select(null, null);
+    select(els[0], deck.current(), true, els);
   }
 
   function selectHover(e) {
     const t = selectableOf(e.target);
-    if (!t || (sel && t.el === sel.el)) return hideHover();
+    if (!t || sel?.els.includes(t.el)) return hideHover();
     if (!hoverBox) { hoverBox = document.createElement("div"); hoverBox.className = "__hover"; hoverBox.appendChild(document.createElement("span")); }
     const b = boxOf(t.el, t.sec);
     if (hoverBox.parentElement !== t.sec) t.sec.appendChild(hoverBox);
@@ -427,11 +464,11 @@
   }
 
   /* Snap targets: slide edges and centre, the footer rule, and the edges and centres of other elements */
-  function snapTargets(sec, el) {
+  function snapTargets(sec, skip) {
     const xs = [0, W / 2, W], ys = [0, H / 2, H];
     if (FOOTER_TOP != null && sec.querySelector(".slide-foot")) ys.push(FOOTER_TOP);
     for (const o of sec.querySelectorAll("[data-eid]")) {
-      if (o === el || el.contains(o) || o.contains(el)) continue;
+      if (skip.some((el) => o === el || el.contains(o) || o.contains(el))) continue;
       if (o.closest("svg") && o.tagName.toLowerCase() !== "svg") continue;
       if (!o.getClientRects().length) continue;
       const b = boxOf(o, sec);
@@ -472,30 +509,32 @@
     hideHover();
     // double click: edit the text under the pointer
     const now = performance.now();
-    const dbl = now - lastDown.t < 450 && Math.hypot(e.clientX - lastDown.x, e.clientY - lastDown.y) < 6 && lastDown.el === e.target;
+    const dbl = !(e.metaKey || e.ctrlKey) && now - lastDown.t < 450 && Math.hypot(e.clientX - lastDown.x, e.clientY - lastDown.y) < 6 && lastDown.el === e.target;
     lastDown = { t: dbl ? 0 : now, x: e.clientX, y: e.clientY, el: e.target };
     if (dbl && !e.target.closest?.(".__sel i")) return editAt(e.target, e.clientX, e.clientY);
     const handle = e.target.closest?.(".__sel i[data-h]");
     if (!handle) {
       if (e.target.closest?.(".__pin")) return;   // pin markers are removed in pin mode only
-      const t = selectableOf(e.target);
-      if (!t) return select(null, null);
+      const t = selectableOf(e.target), add = e.metaKey || e.ctrlKey;
+      if (!t) return add ? undefined : select(null, null);
       if (t.locked) {
-        select(null, null);
+        if (!add) select(null, null);   // a ⌘-click that misses keeps the group
         host()?.toast(`${t.el.classList.contains("slide-foot") ? "The footer is" : "This element is"} set by brand.css and locked.`);
         return;
       }
-      if (!sel || sel.el !== t.el) select(t.el, t.sec);
+      if (add) return toggleSel(t);
+      if (!sel?.els.includes(t.el)) select(t.el, t.sec);
     }
-    if (!editable) { if (handle) host()?.toast("Claude is working. Moving and resizing resume when it has finished."); return; }
+    if (!editable) { if (handle) host()?.toast(lockReason || "Claude is working. Moving and resizing resume when it has finished."); return; }
     const el = sel.el, cs = getComputedStyle(el);
     const { s } = frame(sel.sec);
     const [tx, ty] = translateOf(el);
+    const styles = (e) => ({ translate: e.style.translate, width: e.style.width, height: e.style.height, "max-width": e.style.maxWidth, "max-height": e.style.maxHeight });
     drag = {
       kind: handle ? "resize" : "move", handle: handle?.dataset.h, x0: e.clientX, y0: e.clientY, s, started: !!handle,
-      b: boxOf(el, sel.sec), tx, ty, cw: parseFloat(cs.width) || 0, ch: parseFloat(cs.height) || 0,
-      maxW: cs.maxWidth, maxH: cs.maxHeight, targets: snapTargets(sel.sec, el),
-      before: { translate: el.style.translate, width: el.style.width, height: el.style.height, "max-width": el.style.maxWidth, "max-height": el.style.maxHeight },
+      b: many() ? unionBox(sel.els, sel.sec) : boxOf(el, sel.sec), tx, ty, cw: parseFloat(cs.width) || 0, ch: parseFloat(cs.height) || 0,
+      maxW: cs.maxWidth, maxH: cs.maxHeight, targets: snapTargets(sel.sec, sel.els),
+      items: sel.els.map((e) => { const [x, y] = translateOf(e); return { el: e, tx: x, ty: y, before: styles(e) }; }),
     };
     document.documentElement.setPointerCapture?.(e.pointerId);
   }
@@ -520,8 +559,8 @@
         const sy = snapTo([b.y + dy, b.y + dy + b.h / 2, b.y + dy + b.h], targets.ys, tol);
         if (sy) { dy += sy.d; gy.push(sy.at); }
       }
-      el.style.translate = fmtTranslate(drag.tx + dx, drag.ty + dy);
-      drag.label = `Moved ${nameOf(el, sel.sec)} by ${r1(dx)}, ${r1(dy)} px`;
+      for (const it of drag.items) it.el.style.translate = fmtTranslate(it.tx + dx, it.ty + dy);
+      drag.label = `Moved ${groupName()} by ${r1(dx)}, ${r1(dy)} px`;
     } else {
       const h = drag.handle;
       let w = b.w, ht = b.h, ox = 0, oy = 0;   // ox/oy: how far the left/top edge moves
@@ -564,26 +603,30 @@
     clearGuides();
     if (!sel) return;
     drawSel();
-    if (d.started) commit(d.before, d.label);
+    if (d.started) commit(d.items, d.label);
   }
-  function commit(before, label) {
-    const el = sel.el, set = {};
-    const now = { translate: el.style.translate, width: el.style.width, height: el.style.height,
-      "max-width": el.style.maxWidth, "max-height": el.style.maxHeight };
-    for (const k of Object.keys(now)) if (now[k] !== before[k]) set[k] = now[k] || null;
-    if (Object.keys(set).length) host()?.commitEdit({ eid: el.dataset.eid, set }, label);
+  // one edit (one undo step) for all the elements that changed
+  function commit(items, label) {
+    const ops = items.flatMap(({ el, before }) => {
+      const set = {}, now = { translate: el.style.translate, width: el.style.width, height: el.style.height,
+        "max-width": el.style.maxWidth, "max-height": el.style.maxHeight };
+      for (const k of Object.keys(now)) if (now[k] !== before[k]) set[k] = now[k] || null;
+      return Object.keys(set).length ? [{ eid: el.dataset.eid, set }] : [];
+    });
+    if (ops.length) host()?.commitEdit(ops, label);
     host()?.selectionChanged(selectionInfo());
   }
   function nudge(dx, dy) {
     if (!sel) return;
-    if (!editable) return host()?.toast("Claude is working. Moving and resizing resume when it has finished.");
-    const el = sel.el;
-    const [tx, ty] = translateOf(el);
-    el.style.translate = fmtTranslate(tx + dx, ty + dy);
+    if (!editable) return host()?.toast(lockReason || "Claude is working. Moving and resizing resume when it has finished.");
+    const ops = sel.els.map((el) => {
+      const [tx, ty] = translateOf(el);
+      el.style.translate = fmtTranslate(tx + dx, ty + dy);
+      return { eid: el.dataset.eid, set: { translate: el.style.translate || null } };
+    });
     drawSel();
     renderPins(pins);
-    host()?.commitEdit({ eid: el.dataset.eid, set: { translate: el.style.translate || null } },
-      { nudge: true, name: nameOf(el, sel.sec), dx, dy });
+    host()?.commitEdit(ops, { nudge: true, name: groupName(), dx, dy });
     host()?.selectionChanged(selectionInfo());
   }
   function setMode(m) {
@@ -641,12 +684,12 @@
   }
 
   async function startEdit(t, x, y, opts = {}) {
-    if (!editable) return host()?.toast("Claude is working. Editing resumes when it has finished.");
+    if (!editable) return host()?.toast(lockReason || "Claude is working. Editing resumes when it has finished.");
     if (editing) await finishEdit(true);
     const src = opts.src ?? await host()?.textSource(t.eid, t.path);
     if (src == null || !t.el.isConnected) return;
     const el = t.el;
-    if (!sel || sel.el !== el) select(el.dataset.eid ? el : null, t.sec);
+    if (!sel || sel.el !== el || many()) select(el.dataset.eid ? el : null, t.sec);   // text editing is one element at a time
     removeSel();
     hideHover();
     editing = { ...t, rendered: el.innerHTML };
@@ -776,7 +819,7 @@
     // a new bullet left empty is removed again
     if (ed.isNew && isBlank(el)) {
       el.remove();
-      if (sel?.el === el) select(null, null);
+      if (sel?.els.includes(el)) select(null, null);
       host()?.commitRemove(eid);
       chainDirty = false;
       return;
@@ -1087,7 +1130,7 @@
       isEditing: () => !!editing,
       deselect() { select(null, null); },
       hasSelection: () => !!sel,
-      setEditable(on) { editable = !!on; if (!editable && editing) finishEdit(true); if (sel) drawSel(); },
+      setEditable(on, why = null) { editable = !!on; lockReason = why; if (!editable && editing) finishEdit(true); if (sel) drawSel(); },
       renderPins,
       async measure(index) {
         goto(index);
@@ -1136,7 +1179,7 @@
         const k = e.key, meta = e.metaKey || e.ctrlKey;
         if (sel && mode === "select" && !meta && (k === "Delete" || k === "Backspace")) {
           e.preventDefault(); e.stopImmediatePropagation();
-          host()?.requestDelete(sel.el.dataset.eid);
+          host()?.requestDelete(sel.els.map((e) => e.dataset.eid));
           return;
         }
         // arrows nudge the selection (Shift: 10 px) instead of changing slides