@panphora/clayjs 1.5.3 → 1.6.0

package/src/core/conflict-presentation.js

@@ -0,0 +1,301 @@
+// What a replaced edit is called in the notice, and what it said. Pure: reads the
+// page, never writes it. Names come from what the person can see (the element's
+// kind and the nearest heading above it), never from authored ids.
+
+const KIND = {
+  p: "Paragraph", a: "Link", li: "List item", ul: "List", ol: "List", img: "Image",
+  section: "Section", article: "Article", div: "Block", span: "Text", td: "Table cell",
+  th: "Table cell", tr: "Table row", table: "Table", button: "Button", blockquote: "Quote",
+  pre: "Code block", code: "Code", script: "Data block", style: "Style", figure: "Figure",
+  video: "Video", input: "Field", textarea: "Field", select: "Field", label: "Label",
+  template: "Template",
+};
+
+const ATTR = {
+  href: "Link address", alt: "Image description", title: "Tooltip", class: "Style",
+  style: "Style", value: "Field value", placeholder: "Placeholder",
+};
+
+const CONTAINERS = new Set(["section", "article", "div", "li", "aside", "main", "header", "footer", "nav"]);
+const HIDDEN = new Set(["script", "style", "template", "noscript"]);
+const HEADINGS = "h1,h2,h3,h4,h5,h6";
+const OWN_HEADING = ":scope > :is(h1,h2,h3,h4,h5,h6)";
+const CONTEXT = 40;
+
+export function cut(text, max = CONTEXT) {
+  const t = text.replace(/\s+/g, " ").trim();
+  return t.length > max ? t.slice(0, max).trimEnd() + "…" : t;
+}
+
+// The engine's slices can carry inline markup. Parsed inert, text only: nothing
+// from another tab's edit is ever put into the notice as HTML.
+export function plain(html) {
+  if (html == null) return "";
+  const t = document.createElement("template");
+  t.innerHTML = String(html);
+  return t.content.textContent;
+}
+
+function elementOf(node) {
+  if (!node) return null;
+  return node.nodeType === 1 ? node : node.parentElement;
+}
+
+// A node inside a live <template>'s content is not on the page; its host is.
+function hostOf(node) {
+  let n = node;
+  while (n) {
+    if (n.isConnected) return elementOf(n);
+    const root = n.getRootNode?.();
+    if (root && root.nodeType === 11 && root.host) { n = root.host; continue; }
+    const tpl = root && root.nodeType === 11 ? findTemplateOwning(root) : null;
+    if (tpl) { n = tpl; continue; }
+    return null;
+  }
+  return null;
+}
+
+function findTemplateOwning(fragment) {
+  for (const t of document.querySelectorAll("template")) if (t.content === fragment) return t;
+  return null;
+}
+
+function kindName(el) {
+  if (!el) return "Edit";
+  const tag = el.localName;
+  if (/^h[1-6]$/.test(tag)) return "Heading";
+  return KIND[tag] || tag.charAt(0).toUpperCase() + tag.slice(1);
+}
+
+export function headingAbove(node) {
+  let found = null;
+  for (const h of document.body.querySelectorAll(HEADINGS)) {
+    if (h === node || h.contains(node)) continue;
+    if (h.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING) found = h;
+  }
+  return found ? cut(found.textContent) : null;
+}
+
+function nameOfElement(el, attrName) {
+  if (!el) return attrName ? `"${attrName}" attribute` : "Edit";
+  if (attrName) {
+    const label = attrName === "src"
+      ? (el.localName === "img" || el.localName === "video" ? "Image address" : "Address")
+      : ATTR[attrName] || `"${attrName}" attribute`;
+    const under = el.isConnected ? headingAbove(el) : null;
+    return under ? `${label} under ${under}` : label;
+  }
+  if (HIDDEN.has(el.localName)) return kindName(el);
+  if (/^h[1-6]$/.test(el.localName)) {
+    const under = headingAbove(el);
+    return under ? `Heading under ${under}` : "Page heading";
+  }
+  if (CONTAINERS.has(el.localName)) {
+    const own = el.querySelector(OWN_HEADING);
+    if (own && own.textContent.trim()) return `${cut(own.textContent)} section`;
+  }
+  const kind = kindName(el);
+  const under = el.isConnected ? headingAbove(el) : null;
+  return under ? `${kind} under ${under}` : kind;
+}
+
+// Up to 40 characters either side of the clash, cut back to a word boundary, with
+// the ellipsis only where something was left out.
+export function textContext(full, start, end) {
+  let before = full.slice(Math.max(0, start - CONTEXT), start);
+  let after = full.slice(end, end + CONTEXT);
+  let cutBefore = start - CONTEXT > 0;
+  let cutAfter = end + CONTEXT < full.length;
+  if (cutBefore) {
+    const i = before.indexOf(" ");
+    before = i >= 0 ? before.slice(i + 1) : before;
+  }
+  if (cutAfter) {
+    const i = after.lastIndexOf(" ");
+    after = i >= 0 ? after.slice(0, i) : after;
+  }
+  return { before, after, cutBefore, cutAfter };
+}
+
+function side(hit, ctx) {
+  return { before: ctx?.before || "", hit, after: ctx?.after || "", cutBefore: !!ctx?.cutBefore, cutAfter: !!ctx?.cutAfter };
+}
+
+const SENTENCE = {
+  "edit-beats-delete": (k) => `You deleted this ${k}. The other edit changed it at the same time, so it is still here.`,
+  "move-beats-delete": (k) => `You deleted this ${k}. The other edit moved it at the same time, so it is still here.`,
+  "both-moved": (k) => `You moved this ${k}. The other edit moved it somewhere else. Their place is showing.`,
+  "both-reordered": (k) => `You reordered the items in this ${k}. The other edit reordered them too. Their order is showing.`,
+  "insert-collision": () => "You added something here. The other edit added something else in the same place. Theirs is showing.",
+};
+
+export function structuralSentence(record, kind) {
+  const reason = record.detail || record.reason;
+  const make = SENTENCE[reason];
+  return make ? make(kind.toLowerCase()) : "Your change here was replaced by the other edit.";
+}
+
+function visibleContainer(el) {
+  let n = el.parentElement;
+  while (n && HIDDEN.has(n.localName)) n = n.parentElement;
+  return n && n !== document.documentElement ? n : null;
+}
+
+const ATOM = "\uFFFC";
+const BREAK = "\u001E";
+
+// The engine's flattened text marks an inline element (an image, a field) with
+// U+FFFC and a block break with U+001E. Neither is shown as a control character.
+function shown(text) {
+  return text.replaceAll(ATOM, "[item]").replaceAll(BREAK, "\n");
+}
+
+function textSide(t) {
+  if (!t || typeof t.text !== "string") return null;
+  const ctx = textContext(t.text, t.start, t.end);
+  return {
+    before: shown(ctx.before), hit: shown(t.text.slice(t.start, t.end)), after: shown(ctx.after),
+    cutBefore: ctx.cutBefore, cutAfter: ctx.cutAfter,
+  };
+}
+
+// A live node the engine named, still on the page or in a live template.
+function liveOf(ref) {
+  for (const n of ref?.live || []) if (hostOf(n)) return n;
+  return null;
+}
+
+// Recovery paths index childNodes from the root the merge read as "mine" (the
+// clone the ledger keeps); "content" enters a template's fragment.
+function nodeAtPath(root, path) {
+  let n = root;
+  for (const step of path) {
+    if (!n) return null;
+    n = step === "content" ? n.content : n.childNodes[step];
+  }
+  return n || null;
+}
+
+function localNode(record, ref) {
+  const root = window.clay?.conflicts?.recoveryOf?.(record.id)?.root;
+  const path = ref?.local?.[0];
+  return root && path ? nodeAtPath(root, path) : null;
+}
+
+function visibleHost(node) {
+  const h = hostOf(node);
+  return h && HIDDEN.has(h.localName) ? visibleContainer(h) : h;
+}
+
+// Where a moved block went, in words: "into the FAQ section", "under Pricing".
+function placeName(node) {
+  const el = elementOf(node);
+  if (!el) return null;
+  if (CONTAINERS.has(el.localName)) {
+    const own = el.querySelector(OWN_HEADING);
+    if (own && own.textContent.trim()) return `into the ${cut(own.textContent)} section`;
+  }
+  const under = el.isConnected ? headingAbove(el) : null;
+  return under ? `under ${under}` : null;
+}
+
+function recoverySentence(record, rv, kind) {
+  const s = rv.structure;
+  const k = kind.toLowerCase();
+  switch (`${s.localAction}/${s.remoteAction}`) {
+    case "deleted/edited":
+      return `You deleted this ${k}. The other edit changed it at the same time, so it is still here.`;
+    case "deleted/moved":
+      return `You deleted this ${k}. The other edit moved it, so it is still here.`;
+    case "reordered/reordered":
+      return `You changed the order of the items in this ${k}. The other edit changed their order too. Their order is showing.`;
+    case "inserted/inserted":
+      return "You and the other edit added different content in the same place. Their content is showing.";
+    case "moved/moved": {
+      const mine = placeName(liveOf(s.localPlacement?.parent) || localNode(record, s.localPlacement?.parent));
+      const theirs = placeName(liveOf(s.mergedPlacement?.parent));
+      if (mine && theirs && mine !== theirs) {
+        return `You moved this ${k} ${mine}. The other edit moved it ${theirs}. Their position is showing.`;
+      }
+      return `You moved this ${k}. The other edit moved it somewhere else. Their position is showing.`;
+    }
+    default:
+      return "Your change here was replaced by the other edit.";
+  }
+}
+
+const CHANGED_AGAIN = "The other edit replaced this, and the page changed again before it could be shown here. Download my copy keeps your version.";
+
+const NON_ELEMENT = { 3: "Text", 8: "Comment" };
+
+function recoveryRow(record, rv) {
+  const id = record.id;
+  // Output the engine could not map to the page: nothing here to point at, and
+  // what the page shows is not the other edit's text either.
+  const shown = rv.applied !== false;
+  const live = shown ? liveOf(rv.subject) : null;
+  const target = live ? visibleHost(live) : null;
+  const shape = elementOf(live) || elementOf(localNode(record, rv.subject));
+  const plainKind = NON_ELEMENT[rv.subject?.nodeType];
+  if (rv.attribute) {
+    return {
+      id, kind: "attr", name: nameOfElement(shape, rv.attribute.qualifiedName), target,
+      yours: side(String(record.local ?? "")), now: shown ? side(String(record.remote ?? "")) : null,
+      sentence: shown ? null : CHANGED_AGAIN,
+    };
+  }
+  if (rv.structure) {
+    const kind = plainKind || (shape ? kindName(shape) : "Block");
+    const name = plainKind || (live ? nameOfElement(elementOf(live)) : kind);
+    return {
+      id, kind: "struct", name, target, yours: null, now: null,
+      sentence: shown ? recoverySentence(record, rv, kind) : CHANGED_AGAIN,
+    };
+  }
+  const name = plainKind === "Comment" ? "Comment"
+    : shape && HIDDEN.has(shape.localName) ? kindName(shape)
+    : nameOfElement(shape);
+  return {
+    id, kind: "text", name, target,
+    yours: textSide(rv.text?.local), now: shown ? textSide(rv.text?.merged) : null,
+    sentence: shown ? null : CHANGED_AGAIN,
+  };
+}
+
+export function rowOf(record) {
+  const id = record.id;
+  if (record.recovery?.version === 1) return recoveryRow(record, record.recovery);
+  if (record.kind === "attr") {
+    const el = record.el || null;
+    return {
+      id, kind: "attr", name: nameOfElement(el, record.name), target: hostOf(el),
+      yours: side(String(record.local ?? "")), now: side(String(record.remote ?? "")), sentence: null,
+    };
+  }
+  if (record.kind === "structure") {
+    const live = record.el && record.el.isConnected ? record.el : null;
+    const shape = live || record.base || record.el || null;
+    const kind = kindName(elementOf(shape));
+    const sentence = structuralSentence(record, kind);
+    const both = typeof record.local === "string" && typeof record.remote === "string";
+    return {
+      id, kind: "struct", name: live ? nameOfElement(live) : kind, target: live ? hostOf(live) : null,
+      yours: both ? side(plain(record.local)) : null, now: both ? side(plain(record.remote)) : null, sentence,
+    };
+  }
+  const host = hostOf(record.node);
+  const el = elementOf(record.node);
+  const name = el && HIDDEN.has(el.localName) ? kindName(el)
+    : record.node?.nodeType === 8 ? "Comment"
+    : nameOfElement(el);
+  // Inline-merge slices (they carry lss) are HTML; whole-text and word-level
+  // conflicts are the raw text itself, and parsing that as HTML would eat a literal <.
+  const html = typeof record.lss === "number";
+  const text = (v) => (v == null ? "" : Array.isArray(v) ? v.join("") : String(v));
+  const yours = html ? plain(record.local) : text(record.local);
+  const now = html ? plain(record.remote) : text(record.remote);
+  return {
+    id, kind: "text", name, target: host && !HIDDEN.has(host.localName) ? host : (host ? visibleContainer(host) : null),
+    yours: side(yours), now: side(now), sentence: null,
+  };
+}

package/src/core/save-conflict-notice.js

@@ -1,192 +1,2 @@
-import { isEditMode } from "./is-edit-mode.js";
-import onDomReady from "../lib/dom-ready.js";
-import { style, set, make } from "../lib/hostile-css.js";
-
-// The page's only word on a refused save. Without it a document whose host said no
-// looks exactly like one that is saving fine, while autosave sits suspended: the
-// status chip that would have said so is a plugin, off by default, so most
-// documents show nothing at all.
-//
-// It sits at the bottom because that is where a hand already is on a phone, and
-// one line because the decision is small: keep this version, or take the other.
-// Discarding arms before it fires, since it is the only control here that destroys
-// work with no undo, and the page's own CSS is treated as hostile throughout.
-
-const BG = "var(--clay-conflict-bg,#222)";
-const INK = "var(--clay-conflict-ink,#fff)";
-const EDGE = "var(--clay-conflict-edge,rgba(255,255,255,.28))";
-const WARN = "var(--clay-conflict-warn,#e3a33f)";
-const FONT = "14px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif";
-
-// The host names what moved the file when it knows. It often cannot: a plain
-// filesystem write has no author. Anything unrecognised falls back to the phrase
-// that is true in every case.
-const SOURCES = {
-  "another-tab": "in another tab",
-  "another-person": "by someone else",
-  "an-agent": "by an agent",
-};
-
-const ARM_MS = 5000;
-
-let root = null, line = null, keep = null, drop = null;
-let armTimer = null, armed = false, busy = false;
-
-const still = () => !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
-
-// all:initial first, because a page restyling every button is the normal case, not
-// the adversarial one. Everything the control needs is restated after it.
-function button(label, rules) {
-  const b = make("button", [
-    "all:initial", "box-sizing:border-box", "cursor:pointer", `font:${FONT}`,
-    "font-weight:500", "border-radius:6px", "padding:6px 12px", "white-space:nowrap",
-    "flex:none", ...rules,
-  ], label);
-  b.type = "button";
-  b.addEventListener("focus", () => {
-    set(b, "outline", `2px solid ${WARN}`);
-    set(b, "outline-offset", "2px");
-  });
-  b.addEventListener("blur", () => set(b, "outline", "none"));
-  return b;
-}
-
-// A phone keyboard shrinks the visual viewport but leaves fixed elements pinned to
-// the layout viewport, which parks a bottom-anchored bar behind the keyboard at the
-// exact moment somebody is typing. Lift it by the difference instead.
-function place() {
-  if (!root) return;
-  const vv = window.visualViewport;
-  const lift = vv ? Math.max(0, window.innerHeight - vv.height - vv.offsetTop) : 0;
-  set(root, "bottom", `calc(${16 + lift}px + env(safe-area-inset-bottom,0px))`);
-}
-
-function build() {
-  root = make("div", [
-    "position:fixed", "left:50%", "transform:translateX(-50%)",
-    "z-index:2147483001", "display:flex", "align-items:center", "gap:10px",
-    "max-width:calc(100vw - 24px)", "flex-wrap:wrap", "justify-content:center",
-    "padding:9px 12px", "border-radius:10px",
-    `background:${BG}`, `color:${INK}`, `border:1px solid ${EDGE}`,
-    "box-shadow:0 6px 24px rgba(0,0,0,.32),0 1px 2px rgba(0,0,0,.24)",
-    `font:${FONT}`, "text-align:left",
-  ]);
-  root.setAttribute("clay", "no-save no-watch no-snapshot");
-  root.setAttribute("data-clay-conflict", "");
-  root.setAttribute("role", "alert");
-
-  line = make("span", ["margin-right:2px"]);
-  drop = button("Load theirs", [`color:${INK}`, "opacity:.72", "padding:6px 8px"]);
-  keep = button("Keep mine", [`background:${INK}`, `color:${BG}`, "font-weight:600"]);
-
-  drop.addEventListener("click", onDrop);
-  keep.addEventListener("click", onKeep);
-  root.append(line, drop, keep);
-
-  if (!still()) {
-    set(root, "transition", "opacity .18s");
-    set(root, "opacity", "0");
-  }
-  document.body.appendChild(root);
-  place();
-  window.visualViewport?.addEventListener("resize", place);
-  window.visualViewport?.addEventListener("scroll", place);
-  requestAnimationFrame(() => set(root, "opacity", "1"));
-}
-
-// One arming click before the reload. A first click is a choice, not a confirmation
-// of anything, and this is the only control here that throws away work nothing can
-// bring back. It disarms itself so a bar left open does not stay one stray tap from
-// discarding an afternoon.
-function onDrop() {
-  if (armed) { window.location.reload(); return; }
-  armed = true;
-  drop.textContent = "Yes, drop my edits";
-  set(drop, "opacity", "1");
-  set(drop, "color", WARN);
-  set(drop, "box-shadow", `inset 0 0 0 1px ${WARN}`);
-  clearTimeout(armTimer);
-  armTimer = setTimeout(disarm, ARM_MS);
-}
-
-function disarm() {
-  clearTimeout(armTimer);
-  if (!armed) return;
-  armed = false;
-  drop.textContent = "Load theirs";
-  set(drop, "opacity", ".72");
-  set(drop, "color", INK);
-  set(drop, "box-shadow", "none");
-}
-
-async function onKeep() {
-  if (busy) return;
-  busy = true;
-  disarm();
-  keep.textContent = "Saving…";
-  set(keep, "opacity", ".65");
-  try {
-    const result = await window.clay?.save?.overwrite?.();
-    if (result && result.ok === false) throw new Error(result.msg || "");
-  } catch {
-    // Left showing: the save still has not happened, and clearing the bar here
-    // would put the page back to looking like one that is saving normally.
-    line.textContent = "That did not save either. Your edits are still here.";
-    keep.textContent = "Try again";
-    set(keep, "opacity", "1");
-    busy = false;
-    return;
-  }
-  busy = false;
-}
-
-function onKeydown(e) {
-  if (e.key === "Escape" && armed) { e.preventDefault(); drop.focus(); disarm(); }
-}
-
-function show(e) {
-  if (!root) build();
-  set(root, "display", "flex");
-  const named = SOURCES[e?.detail?.changedBy];
-  // Reassurance first, then the fact. What a person needs to know at this moment
-  // is that nothing of theirs is gone and nothing is about to be overwritten; the
-  // detail of what happened is the second half of the sentence, not the first.
-  // "Saving is paused" led here once and read as a failure, which it is not: the
-  // page is holding a version, and the two buttons below are the whole decision.
-  //
-  // An earlier save of this tab's timed out and the host could not say what became
-  // of it, so this refusal may be answering that write rather than anybody else's.
-  // Saying so is the whole reason the stamp is kept across a timeout instead of
-  // quietly reconciled. A host that NAMED the writer, or that answered the question
-  // with a receipt, knows better than this guess, so the name wins.
-  if (!named && e?.detail?.afterTimeout) {
-    line.textContent =
-      "This page changed elsewhere, possibly by your own save that timed out. " +
-      "Your edits here are safe, and nothing will be overwritten until you choose.";
-  } else {
-    line.textContent =
-      `This page changed ${named || "elsewhere"}. ` +
-      "Your edits here are safe, and nothing will be overwritten until you choose.";
-  }
-  keep.textContent = "Keep mine";
-  set(keep, "opacity", "1");
-  busy = false;
-  disarm();
-  place();
-}
-
-function hide() {
-  if (!root) return;
-  disarm();
-  set(root, "display", "none");
-}
-
-function init() {
-  if (!isEditMode) return;
-  document.addEventListener("clay:save-conflict", show);
-  document.addEventListener("clay:save-saved", hide);
-  document.addEventListener("clay:save-conflict-resolved", hide);
-  document.addEventListener("keydown", onKeydown);
-}
-
-onDomReady(init);
+// Kept so older imports of this path still load the notice. Removed in ClayJS 1.6.
+import "./conflict-notice.js";

package/src/core/save-feedback.js

@@ -0,0 +1,6 @@
+// Which save feedback is on the page, so the indicator chip and the automatic toasts
+// never report the same save twice: the chip owns saving and saved, the toasts own a
+// save that failed or went offline. Each side sets its own flag when it loads; both
+// read them only when an event arrives, so load order does not matter. savedToast is
+// the page's `clay.saveToast` switch: Saved goes to a toast instead of the chip.
+export const saveFeedback = { chip: false, toasts: false, savedToast: false };

package/src/core/save.js

@@ -206,6 +206,45 @@ export function resumeAutosave() {
   savePageThrottled();
 }
 
+// ============================================
+// THE PREVIEW HOLD
+// ============================================
+//
+// While an AI edit's rewrite is on screen and not yet kept, the DOM holds words the
+// person has not accepted. Every save would write them, the explicit ones included,
+// so for that window no save goes out at all. A save asked for meanwhile is
+// remembered and runs on release; Keep releases without the replay because it saves
+// right after.
+let previewHold = 0;
+let previewMissed = false;
+
+export function holdAllSaves() {
+  previewHold++;
+}
+
+export function releaseAllSaves({ replay = true } = {}) {
+  if (previewHold === 0) return;
+  previewHold--;
+  if (previewHold > 0) return;
+  const missed = previewMissed;
+  previewMissed = false;
+  if (missed && replay) savePage();
+}
+
+export function savesHeld() {
+  return previewHold > 0;
+}
+
+function heldForPreview(callback, resolve) {
+  if (previewHold === 0) return false;
+  previewMissed = true;
+  clearExplicitSave();
+  const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+  callback(skipped);
+  resolve(skipped);
+  return true;
+}
+
 // ============================================
 // THE CONFLICT HOLD
 // ============================================
@@ -257,7 +296,8 @@ export function isSaveConflicted() {
  * missed save. On a manual-save page with unsaved work the root stays in
  * 'conflict' and the notice stays up until the person saves, since nothing has
  * been written yet. Not clay:save-saved: no save happened, and that event runs
- * every [onaftersave] handler.
+ * every [onaftersave] handler. Either way clay:save-conflict-released fires, so a
+ * notice can drop the refusal it was showing.
  */
 export function conflictResolvedBySync(etag) {
   if (!conflictHold) return;
@@ -273,6 +313,7 @@ export function conflictResolvedBySync(etag) {
       detail: { timestamp: Date.now() }
     }));
   }
+  document.dispatchEvent(new CustomEvent('clay:save-conflict-released', { detail: { etag: etag ?? null } }));
   resumeAutosave();
 }
 
@@ -391,6 +432,8 @@ export function savePage(callback = () => {}) {
       return resolve(skipped);
     }
 
+    if (heldForPreview(callback, resolve)) return;
+
     // A save is already on the wire. Remember that a newer state is waiting rather
     // than dropping it: the in-flight request carries the older bytes, and if no
     // further mutation happens to retrigger autosave, the newer ones would never
@@ -476,6 +519,8 @@ export function savePageForce(callback = () => {}) {
       return resolve(skipped);
     }
 
+    if (heldForPreview(callback, resolve)) return;
+
     if (isSaveInProgress()) {
       pendingSave = true;
       const skipped = skipped_('Save already in progress');
@@ -705,6 +750,13 @@ export function savePageThrottled(callback = () => {}) {
     return Promise.resolve(skipped);
   }
 
+  if (previewHold > 0) {
+    previewMissed = true;
+    const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+    callback(skipped);
+    return Promise.resolve(skipped);
+  }
+
   // Every autosave path lands here — the mutation-driven one, the [persist] input
   // timer, and live-sync's convergence save after a protected apply — which is
   // why the suspension lives at this one entry rather than at each caller.

package/src/core/snapshot.js

@@ -679,3 +679,24 @@ export function captureBodyForSync() {
 export function getPageContents() {
   return captureForSave({ emitForSync: false });
 }
+
+/**
+ * The page as this tab had it before a merge replaced some of it, as the bytes a
+ * save would have written. The ledger's clone is shared and must come back
+ * untouched, so this works on a copy. A snapshot-domain clone still needs the save
+ * preparation (transforms, the [no-save] strip) but not the authored onbeforesave
+ * handlers: this is a download, not a save. A save-domain clone is already prepared.
+ */
+export function serializeRecoveryClone(clone, { prepared = false } = {}) {
+  const copy = clonePreventingOnclone(clone);
+  return serializeClone(prepared ? copy : prepareCloneForSave(copy, { authored: false }));
+}
+
+/**
+ * The live page as a save would write it, for a download: the save transforms and
+ * the [no-save] strip, but no authored handler runs and the undo batch stays open.
+ * Nothing is sent and no event fires.
+ */
+export function captureRecoveryPage() {
+  return serializeSaveClone(captureSaveClone({ flushUndo: false, authored: false }));
+}