@erdemtuna/doc-review 0.7.0 → 0.8.1

package/src/serialize.js

@@ -9,20 +9,6 @@
 export const UI_ATTR = "data-eh-ui";
 export const MARK_ATTR = "data-eh-mark";
 
-/** Keep a hydrated app editable even if its framework removes the attribute. */
-export function keepBodyEditable(body) {
-  const enforce = () => {
-    if (body.getAttribute("contenteditable") !== "true") {
-      body.setAttribute("contenteditable", "true");
-    }
-  };
-  enforce();
-  const Observer = body.ownerDocument.defaultView.MutationObserver;
-  const observer = new Observer(enforce);
-  observer.observe(body, { attributes: true, attributeFilter: ["contenteditable"] });
-  return observer;
-}
-
 /** Serialize a document to the HTML that should live on disk. */
 export function serializeDocument(doc) {
   const clone = doc.documentElement.cloneNode(true);

package/src/server.js

@@ -4,11 +4,13 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { atomicWrite, Store, resolveAsset } from "./state.js";
+import { normalizeCommentAnchor } from "./comment-anchor.js";
 import { injectSdk, stripSdk } from "./html-transform.js";
 import { isMarkdown, renderMarkdownPage } from "./markdown.js";
 import { canonicalTarget, ensureStateDir, localUrl, SERVER_PROTOCOL, serverPath, stateDir, targetKey } from "./paths.js";
 import { acquireServerLock, releaseServerLock, removeOwnedServerRecord } from "./server-lock.js";
 import { invocation, shellQuote } from "./setup.js";
+import { limitEditFields } from "./edit-limits.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -223,8 +225,13 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
       const current = hash(html);
       // Our own autosave must never bounce back as a reload.
       if (lastWritten.get(key) === current) return;
+      try {
+        store.setPristine(key, html, { keepEdits: isMarkdown(page.file) });
+      } catch (err) {
+        console.error(`Could not refresh review baseline for ${page.file}: ${err.message}`);
+        return;
+      }
       lastWritten.set(key, current);
-      store.setPristine(key, html);
       for (const session of sessionsForKey(key)) {
         invalidateSessionRender(session);
         emit(session, "reload", { key });
@@ -274,7 +281,7 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
           id: c.id,
           kind: c.kind,
           quote: c.quote,
-          anchor: c.anchor,
+          anchor: c.anchor == null ? c.anchor : normalizeCommentAnchor(c.kind, c.anchor),
           feedback: c.feedback,
           ...(c.correction ? { correction: true, correction_of: c.correctionOf } : {}),
         })),
@@ -283,6 +290,7 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
           kind: e.kind,
           before: e.before,
           after: e.after,
+          ...(e.truncated ? { truncated: true, truncated_fields: e.truncated_fields } : {}),
           ...(e.before_html !== undefined && e.before_html !== e.before ? { before_html: e.before_html } : {}),
           ...(e.after_html !== undefined && e.after_html !== e.after ? { after_html: e.after_html } : {}),
           ...(Array.isArray(e.staged_assets) && e.staged_assets.length ? { staged_assets: e.staged_assets } : {}),
@@ -313,6 +321,7 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
     const hasMarkdown = pages.some((p) => p.kind === "file" && isMarkdown(p.file));
     const hasUrl = pages.some((p) => p.kind === "url");
     const hasCorrections = pages.some((p) => p.comments.some((c) => c.correction));
+    const hasTruncation = pages.some((p) => p.edits.some((e) => e.truncated));
     const id = `b_${crypto.randomBytes(12).toString("hex")}`;
     const entry = store.page(session.entryKey);
     const pollTarget = entry?.kind === "url" ? entry.url : entry?.file;
@@ -325,9 +334,14 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
       sent_at: new Date().toISOString(),
       next_step:
         "Apply this feedback. Each entry in `pages` names the reviewed file or localhost URL. Items under `edits` are " +
-        "changes the human already made: `after` is their exact new wording, so carry it across verbatim, and " +
+        "changes the human already made: unless marked `truncated`, `after` is their exact new wording, so carry it across verbatim, and " +
         "never revert it. When an edit carries `after_html`, the human changed formatting (bold, italic, links) — " +
         "use the HTML version, translated into the source's own syntax. " +
+        (hasTruncation
+          ? "Some edits are marked `truncated`; `truncated_fields` lists incomplete fields. Never apply incomplete text or HTML " +
+            "as a complete replacement or invent missing content. Recover the full edit only from an authoritative source, " +
+            "or ask the user for it. Do not acknowledge this batch until all feedback is handled. "
+          : "") +
         (hasMarkdown
           ? "Markdown pages were reviewed rendered, so quotes and `after` wording use the rendered text — apply " +
             "the change to the Markdown source, keeping its formatting syntax. "
@@ -562,6 +576,10 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
       if (route === "/chrome.css") return serveFile(res, path.join(here, "chrome.css"));
       if (route === "/chrome.js") return serveFile(res, path.join(here, "chrome-client.js"));
       if (route === "/chrome-session.js") return serveFile(res, path.join(here, "chrome-session.js"));
+      if (route === "/icons.js") return serveFile(res, path.join(here, "icons.js"), opaqueModuleCors(req));
+      if (route === "/positioning.js") return serveFile(res, path.join(here, "positioning.js"), opaqueModuleCors(req));
+      if (route === "/review-mode.js") return serveFile(res, path.join(here, "review-mode.js"), opaqueModuleCors(req));
+      if (route === "/comment-target.js") return serveFile(res, path.join(here, "comment-target.js"), opaqueModuleCors(req));
       if (route === "/sdk.js") return serveFile(res, path.join(here, "sdk.js"), opaqueModuleCors(req));
       if (route === "/editing.js") return serveFile(res, path.join(here, "editing.js"), opaqueModuleCors(req));
       if (route === "/anchor-text.js") return serveFile(res, path.join(here, "anchor-text.js"), opaqueModuleCors(req));
@@ -829,15 +847,21 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
 
         if (action === "comment" && req.method === "POST") {
           const body = await readBody(req);
+          const kind = body.kind === "element" ? "element" : "selection";
+          const feedback = String(body.feedback || "").trim();
           const comment = {
             id: uid("c"),
-            kind: body.kind === "element" ? "element" : "selection",
+            kind,
             quote: String(body.quote || ""),
-            anchor: body.anchor || null,
-            feedback: String(body.feedback || ""),
+            anchor: normalizeCommentAnchor(
+              kind,
+              body.anchor || (kind === "selection" ? { quote: String(body.quote || "") } : null)
+            ),
+            feedback,
             createdAt: Date.now(),
           };
           if (!comment.feedback) return json(res, 400, { error: "empty feedback" });
+          if (!comment.anchor) return json(res, 400, { error: "invalid comment anchor" });
           store.addComment(key, comment);
           return json(res, 200, { comment, page: pageState(key) });
         }
@@ -862,7 +886,11 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
           const body = await readBody(req);
           const label = String(body.label || "Document");
           const kind = body.kind === "deleted" ? "deleted" : body.kind === "moved" ? "moved" : "edited";
-          const cap = (s) => (typeof s === "string" ? s.slice(0, 4000) : undefined);
+          const limited = limitEditFields({
+            before: body.before, after: body.after, before_html: body.before_html, after_html: body.after_html,
+            ...(kind === "moved" ? { moved_after: body.moved_after, moved_before: body.moved_before } : {}),
+          });
+          const fields = limited.fields;
           const stagedRoot = path.join(stateDir(), "pasted", key);
           const stagedAssets = Array.isArray(body.staged_assets)
             ? body.staged_assets
@@ -882,10 +910,12 @@ export function createServer({ store: suppliedStore, storeOptions, owner = null,
                 .map(({ path: assetPath, preview_src }) => ({ path: assetPath, preview_src }))
             : [];
           const extra = {
-            ...(kind === "moved" ? { moved_after: cap(body.moved_after) || "", moved_before: cap(body.moved_before) || "" } : {}),
+            truncated: limited.truncated,
+            truncated_fields: limited.truncated_fields,
+            ...(kind === "moved" ? { moved_after: fields.moved_after || "", moved_before: fields.moved_before || "" } : {}),
             ...(stagedAssets.length ? { staged_assets: stagedAssets } : {}),
           };
-          store.addEdit(key, label, kind, cap(body.before), cap(body.after), cap(body.before_html), cap(body.after_html), extra);
+          store.addEdit(key, label, kind, fields.before, fields.after, fields.before_html, fields.after_html, extra);
           return json(res, 200, { page: pageState(key) });
         }
 

package/src/setup-guidance.js

@@ -0,0 +1,128 @@
+export const GUIDANCE_BEGIN = "<!-- BEGIN doc-review -->";
+export const GUIDANCE_END = "<!-- END doc-review -->";
+
+// Historical generated text is deliberately independent of the current guidance.
+const LEGACY_TAIL = `
+\`npx -y @erdemtuna/doc-review <file.html>\`. For a locally running web page, open the real
+route with \`npx -y @erdemtuna/doc-review http://localhost:3000/path\` instead of recreating
+it as a static file. Then block on
+\`npx -y @erdemtuna/doc-review poll <target> --timeout 600\` until they send feedback.
+If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
+poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
+arrives, apply it, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`.
+
+Keep the poll command in the foreground and do not end the turn while it waits.
+If the shell returns a process or session handle, keep waiting on that handle until
+the command exits. \`npx -y @erdemtuna/doc-review status <target>\` reports instantly
+whether feedback is already waiting, without blocking.
+
+The batch groups feedback by page under \`pages\`, so fix every page listed. Items
+under \`edits\` are changes the user already made: \`after\` is their exact wording,
+so carry it across verbatim and never revert it — and if the HTML was generated
+from MDX or Markdown, apply it to the source too. Markdown files open rendered
+and are never written by doc-review: apply their comments and edits to the
+Markdown source, keeping its syntax. There is no reply channel; the user sees
+your work when the page reloads. For a localhost page, direct edits and deletions
+arrive with \`kind: "url"\`; find and update the matching MDX, TSX, template, or
+component source. Never write the rendered HTTP response over project source.`;
+
+export const LEGACY_GUIDANCE = Object.freeze([
+  `## Reviewing files and localhost pages with doc-review
+
+After writing an HTML or Markdown file the user will read, open it for them with${LEGACY_TAIL}`,
+  `## Reviewing files and localhost pages with doc-review
+
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with${LEGACY_TAIL}`,
+]);
+
+const migrationMessage = "AGENTS.md contains custom or unrecognized doc-review guidance — left it unchanged. " +
+  "Manually reconcile that guidance, then wrap only the setup-owned section in " +
+  `${GUIDANCE_BEGIN} and ${GUIDANCE_END}, or remove it and re-run setup.`;
+
+function invalidMarkers() {
+  throw new Error("AGENTS.md has malformed, duplicate, or ambiguous doc-review ownership markers. " +
+    "Keep exactly one standalone BEGIN/END pair in order, then re-run setup. No setup files were changed.");
+}
+
+function render(body, newline) {
+  return `${GUIDANCE_BEGIN}\n${body.trim()}\n${GUIDANCE_END}`.replaceAll("\n", newline);
+}
+
+/** Plan the complete edit before setup writes any files. Never normalize user text. */
+export function updateGuidance(existing, body) {
+  const lines = [...existing.matchAll(/[^\n]*(?:\n|$)/g)]
+    .filter((match) => match[0])
+    .map((match) => ({
+      text: match[0].replace(/\r?\n$/, ""),
+      start: match.index,
+      end: match.index + match[0].replace(/\r?\n$/, "").length,
+    }));
+  const markers = lines.filter(({ text }) => /doc-review/i.test(text) &&
+    (/\b(?:BEGIN|END)\b/i.test(text) && /<!--|-->|^\s*(?:BEGIN|END)\b/i.test(text)));
+
+  if (markers.length) {
+    if (markers.length !== 2 || markers[0].text !== GUIDANCE_BEGIN || markers[1].text !== GUIDANCE_END) {
+      invalidMarkers();
+    }
+    const [begin, end] = markers;
+    const newline = existing.slice(begin.end).startsWith("\r\n") ? "\r\n" : "\n";
+    return {
+      contents: existing.slice(0, begin.start) + render(body, newline) + existing.slice(end.end),
+      message: "Updated setup-owned AGENTS.md guidance   (Codex)",
+    };
+  }
+
+  const candidates = [];
+  for (const legacy of LEGACY_GUIDANCE) {
+    for (const command of ["npx -y @erdemtuna/doc-review", "doc-review"]) {
+      for (const newline of ["\n", "\r\n"]) {
+        const text = legacy.replaceAll("npx -y @erdemtuna/doc-review", command).replaceAll("\n", newline);
+        let start = existing.indexOf(text);
+        while (start !== -1) {
+          const end = start + text.length;
+          const before = existing.slice(0, start);
+          const after = existing.slice(end);
+          // A complete generated section, not a substring of customized prose.
+          if ((start === 0 || before.endsWith("\n") || before === "\uFEFF") &&
+              /^(?:\r?\n|$)/.test(after) &&
+              /^(?:\s*$|(?:\r?\n)+(?=#{1,2} ))/.test(after)) {
+            candidates.push({ start, end, newline });
+          }
+          start = existing.indexOf(text, start + text.length);
+        }
+      }
+    }
+  }
+  if (candidates.length > 1) {
+    throw new Error("AGENTS.md contains multiple legacy doc-review sections; ownership is ambiguous. " +
+      "Reconcile them before re-running setup. No setup files were changed.");
+  }
+  if (candidates.length === 1) {
+    const { start, end, newline } = candidates[0];
+    const surrounding = existing.slice(0, start) + existing.slice(end);
+    if (!/doc-review/i.test(surrounding)) {
+      return {
+        contents: existing.slice(0, start) + render(body, newline) + existing.slice(end),
+        message: "Migrated legacy AGENTS.md guidance to setup-owned markers   (Codex)",
+      };
+    }
+  }
+  if (/doc-review/i.test(existing)) {
+    return { contents: existing, message: migrationMessage };
+  }
+
+  const newline = existing.includes("\r\n") ? "\r\n" : "\n";
+  const separator = !existing || existing.endsWith(newline + newline)
+    ? ""
+    : existing.endsWith("\n") ? newline : newline + newline;
+  return {
+    contents: existing + separator + render(body, newline) + newline,
+    message: `${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`,
+  };
+}

package/src/setup.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { updateGuidance } from "./setup-guidance.js";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_NAME = "@erdemtuna/doc-review";
@@ -50,15 +51,26 @@ export const skillFor = (cmd) => readSkill().replaceAll(NPX_COMMAND, cmd);
 const CODEX_BLOCK = `
 ## Reviewing files and localhost pages with doc-review
 
-After writing an HTML or Markdown file the user will read, open it for them with
+Start only when the user explicitly invokes /doc-review or requests an
+interactive browser review. Writing, updating, discussing, or generically reviewing
+content does not authorize opening a review or polling. Another skill's automatic
+review step is not user permission. Otherwise respond normally.
+
+After that explicit request, open the requested HTML or Markdown file with
 \`${NPX_COMMAND} <file.html>\`. For a locally running web page, open the real
 route with \`${NPX_COMMAND} http://localhost:3000/path\` instead of recreating
 it as a static file. Then block on
 \`${NPX_COMMAND} poll <target> --timeout 600\` until they send feedback.
 If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
 poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
-arrives, apply it, then run the exact acknowledgement command in its
-\`next_step\`, which uses \`--ack <batch_id>\`.
+arrives, handle every item, then run the exact acknowledgement command in its
+\`next_step\`, which uses \`--ack <batch_id>\`. Keep that exact batch ID on retries;
+never acknowledge an unhandled batch.
+
+Without \`--timeout\`, the CLI defaults to a 12-hour cutoff. An explicit
+\`--timeout\` is one end-to-end deadline, including server discovery and reconnect
+attempts. Keep using the bounded foreground \`--timeout 600\` loop above;
+those polls do not wait 12 hours.
 
 Keep the poll command in the foreground and do not end the turn while it waits.
 If the shell returns a process or session handle, keep waiting on that handle until
@@ -66,9 +78,19 @@ the command exits. \`${NPX_COMMAND} status <target>\` reports instantly
 whether feedback is already waiting, without blocking.
 
 The batch groups feedback by page under \`pages\`, so fix every page listed. Items
-under \`edits\` are changes the user already made: \`after\` is their exact wording,
-so carry it across verbatim and never revert it — and if the HTML was generated
-from MDX or Markdown, apply it to the source too. Markdown files open rendered
+under \`edits\` are changes the user already made. For non-truncated edits,
+\`after\` is their exact wording: carry it across verbatim and never revert it.
+If the HTML was generated from MDX or Markdown, apply complete edits to the
+source too.
+
+Edit fields are limited to 200,000 Unicode code points each. An edit with
+\`truncated: true\` identifies clipped fields in the \`truncated_fields\` array.
+Never apply incomplete text or HTML as a complete replacement or invent missing
+text. Recover the full edit only from an authoritative source; otherwise ask the
+user for the complete edit. Do not acknowledge the batch until every item,
+including truncated edits, has been handled.
+
+Markdown files open rendered
 and are never written by doc-review: apply their comments and edits to the
 Markdown source, keeping its syntax. There is no reply channel; the user sees
 your work when the page reloads. For a localhost page, direct edits and deletions
@@ -79,6 +101,17 @@ component source. Never write the rendered HTTP response over project source.
 export function installSkills(cwd, { global: isGlobal = false, home = os.homedir(), command } = {}) {
   const done = [];
   const cmd = command || invocation();
+  const agents = path.join(cwd, "AGENTS.md");
+  let guidance;
+  let existing;
+  if (!isGlobal) {
+    const bytes = fs.existsSync(agents) ? fs.readFileSync(agents) : Buffer.alloc(0);
+    existing = bytes.toString("utf8");
+    if (!Buffer.from(existing, "utf8").equals(bytes)) {
+      throw new Error("AGENTS.md is not valid UTF-8; convert it before re-running setup. No setup files were changed.");
+    }
+    guidance = updateGuidance(existing, CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd));
+  }
 
   const skillRoots = isGlobal
     ? [
@@ -96,15 +129,8 @@ export function installSkills(cwd, { global: isGlobal = false, home = os.homedir
   }
 
   if (!isGlobal) {
-    const agents = path.join(cwd, "AGENTS.md");
-    const existing = fs.existsSync(agents) ? fs.readFileSync(agents, "utf8") : "";
-    if (existing.includes("doc-review")) {
-      done.push("AGENTS.md already mentions doc-review — left it alone");
-    } else {
-      const block = CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd);
-      fs.writeFileSync(agents, existing ? `${existing.trimEnd()}\n${block}` : block.trimStart());
-      done.push(`${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`);
-    }
+    if (guidance.contents !== existing) fs.writeFileSync(agents, guidance.contents);
+    done.push(guidance.message);
   }
 
   done.push("", `Agents will be told to run: ${cmd}`);

package/src/state.js

@@ -1,7 +1,10 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { normalizeCommentAnchor } from "./comment-anchor.js";
 import { canonicalTarget, ensureStateDir, pageKey, realFile, statePath, targetKey } from "./paths.js";
+export { atomicWrite } from "./atomic-write.js";
+import { atomicWrite } from "./atomic-write.js";
 
 /** Anything untouched this long is review debris, not work in progress. */
 const PRUNE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
@@ -46,6 +49,17 @@ function normalizeState(parsed, makeBatchId) {
     receipts: parsed.receipts && typeof parsed.receipts === "object" ? parsed.receipts : {},
   };
   let changed = !parsed.batches || !parsed.receipts;
+  const normalizeAnchor = (comment) => {
+    if (!comment || comment.anchor == null) return;
+    const normalized = normalizeCommentAnchor(comment.kind === "element" ? "element" : "selection", comment.anchor);
+    if (JSON.stringify(normalized) !== JSON.stringify(comment.anchor)) {
+      comment.anchor = normalized;
+      changed = true;
+    }
+  };
+  for (const page of Object.values(data.pages)) {
+    for (const comment of page?.comments || []) normalizeAnchor(comment);
+  }
   for (const record of Object.values(data.batches)) {
     if (!record || typeof record !== "object" || !record.batch || !Array.isArray(record.cleanup)) {
       throw new Error("Invalid doc-review state: malformed feedback batch.");
@@ -73,28 +87,13 @@ function normalizeState(parsed, makeBatchId) {
     if (!DELIVERY_STATES.has(record.delivery_state)) {
       throw new Error(`Invalid doc-review state: unknown delivery state ${record.delivery_state}.`);
     }
+    for (const page of record.batch.pages || []) {
+      for (const comment of page.comments || []) normalizeAnchor(comment);
+    }
   }
   return { data, changed };
 }
 
-/**
- * Atomic write via a unique sibling tmp file. The name is unguessable and the
- * create is exclusive, so a pre-planted symlink can never redirect the write,
- * and a failed rename never leaves a predictable orphan behind.
- */
-export function atomicWrite(file, data) {
-  const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
-  fs.writeFileSync(tmp, data, { flag: "wx" });
-  try {
-    fs.renameSync(tmp, file);
-  } catch (err) {
-    try {
-      fs.unlinkSync(tmp);
-    } catch {}
-    throw err;
-  }
-}
-
 /**
  * All durable state lives in one JSON file. No database, no network.
  *
@@ -234,8 +233,12 @@ export class Store {
   }
 
   addComment(key, comment) {
+    const anchor = comment.anchor == null
+      ? comment.anchor
+      : normalizeCommentAnchor(comment.kind === "element" ? "element" : "selection", comment.anchor);
+    if (comment.anchor != null && !anchor) throw new Error("Invalid comment anchor.");
     return this.update(key, (page) => {
-      page.comments.push(comment);
+      page.comments.push({ ...comment, ...(comment.anchor !== undefined ? { anchor } : {}) });
     });
   }
 
@@ -324,6 +327,19 @@ export class Store {
         if (afterHtml !== undefined) row.after_html = afterHtml;
         // A re-move of the same block replaces its landing spot.
         if (extra) {
+          if (Array.isArray(extra.truncated_fields)) {
+            const replaced = new Set([
+              ...(after !== undefined ? ["after"] : []),
+              ...(afterHtml !== undefined ? ["after_html"] : []),
+              ...["moved_after", "moved_before"].filter((field) => extra[field] !== undefined),
+            ]);
+            // Original before text is retained across edits, including its truncation.
+            const truncatedFields = [...new Set([
+              ...(row.truncated_fields || []).filter((field) => !replaced.has(field)),
+              ...extra.truncated_fields.filter((field) => replaced.has(field)),
+            ])];
+            extra = { ...extra, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+          }
           if (extra.staged_assets) {
             const assets = [...(row.staged_assets || []), ...extra.staged_assets];
             extra = { ...extra, staged_assets: [...new Map(assets.map((asset) => [asset.path, asset])).values()] };
@@ -344,10 +360,10 @@ export class Store {
   }
 
   /** After the agent writes, its version becomes the new revert target. */
-  setPristine(key, html) {
+  setPristine(key, html, { keepEdits = false } = {}) {
     return this.update(key, (page) => {
       page.pristine = html;
-      page.edits = [];
+      if (!keepEdits) page.edits = [];
     });
   }