@panphora/clayjs 1.16.0 → 1.18.0

package/src/core/host-meta.js

@@ -149,6 +149,24 @@ export async function hostPageFormat() {
   return meta.extensions.includes("page-format-v1") ? 1 : 0;
 }
 
+/**
+ * Where this host serves the page state of one accepted version, or null.
+ *
+ * Two things have to be true: the host announced `page-recovery-v1` by name, and its
+ * document block named the resource as `pageState.href`. A host that has the resource
+ * but has not announced the extension is still launching it, and a client that inferred
+ * either one from the other would retire journaled work against a pair nobody promised.
+ * Absent, empty or not a string is null, which means no conditional read and no proof
+ * from one: the records stay.
+ *
+ * @returns {Promise<?string>}
+ */
+export async function hostPageStateHref() {
+  const meta = await hostMeta();
+  if (!meta.extensions.includes("page-recovery-v1")) return null;
+  return meta.document?.pageState?.href || null;
+}
+
 /**
  * Whether this host keeps a version history a person can go back to.
  *
@@ -163,6 +181,44 @@ export async function hostVersions() {
   return meta.document?.versions === true;
 }
 
+const HOST_ACTIONS = ["codeEditor", "versions", "duplicate", "reveal", "export"];
+
+function httpUrl(value) {
+  if (typeof value !== "string" || !value) return null;
+  try {
+    const url = new URL(value, location.href);
+    return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What the host offers this caller for the document, from the `document.actions` block:
+ * `{ codeEditor, versions, duplicate, reveal, export }`, each present only when the host
+ * named it. An action is a page to open (`{ href }`, any http(s) URL) or something the
+ * host does itself when the page asks (`{ post }`, a same-origin URL). A host without
+ * the block offers none of them.
+ *
+ * @returns {Promise<Record<string, {href: string} | {post: string}>>}
+ */
+export async function hostActions() {
+  const meta = await hostMeta();
+  const block = meta.document?.actions;
+  const actions = {};
+  if (!block || typeof block !== "object") return actions;
+  for (const name of HOST_ACTIONS) {
+    const href = httpUrl(block[name]?.href);
+    if (href) {
+      actions[name] = { href: href.href };
+      continue;
+    }
+    const post = httpUrl(block[name]?.post);
+    if (post && post.origin === location.origin) actions[name] = { post: post.href };
+  }
+  return actions;
+}
+
 /** Drop the memoized answer. Tests only. */
 export function resetHostMeta() {
   inFlight = null;

package/src/core/is-edit-mode.js

@@ -83,19 +83,35 @@ const hintCanEdit = hostCanEdit || keptCanEdit;
 const authoredRestriction = isDraftMode || servedStaleToken() || forcedEditMode === false ||
   query.editmode === "false" || (isViewOnlyDocument && query.editmode !== "true");
 let canEdit = hintCanEdit;
+// The host's own answer as it stands, true or false, and null while it has said nothing
+// either way. Kept beside canEdit because it is the same answer read for a different
+// question: canEdit is what the page may do, and this is what the host has already said it
+// will refuse.
+let hostWritable = null;
 
 // The host's own answer to "may this caller save here": false takes edit away, true grants
 // it unless the document rules it out, and no answer leaves the hints in charge.
 export function noteHostWritable(writable) {
+  hostWritable = typeof writable === "boolean" ? writable : null;
   const next = writable === false ? false : writable === true ? hintCanEdit || !authoredRestriction : hintCanEdit;
   if (next === canEdit) return;
   canEdit = next;
   if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:capabilitychange"));
 }
 
+// What the host last answered about this page being writable, or null while it has said
+// nothing. A denial is the client's own knowledge that a save will be refused, so the save
+// lane reads it before building a request it already knows the host will not take.
+export function learnedHostWritable() {
+  return hostWritable;
+}
+
 // Does this tab start editing? Only when something explicit asks for it.
+// A receipt the page left on its own hide records where the tab happened to be, not a
+// choice, so a tool page that now declares opens-in="edit" still opens editing. A switch
+// the person made leaves an internal receipt, and that one is kept.
 const startsEditing = receipt
-  ? receipt.mode === "edit"
+  ? receipt.mode === "edit" || (opensInEdit && !receipt.internal)
   : query.editmode
     ? query.editmode === "true"
     : forcedEditMode === true || opensInEdit;

package/src/core/mode-key.js

@@ -1,6 +1,7 @@
 import { canEdit, isDraftMode, mode } from "./is-edit-mode.js";
 import { setMode } from "./edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
+import { PERSIST, resolveRegionPolicy } from "../lib/region-policy.js";
 
 const mac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
 const chord = mac ? "⌘⇧E" : "Ctrl+Shift+E";
@@ -53,7 +54,16 @@ const NOTE_CSS = `.clay-mode-note {
   opacity: .65;
 }
 .clay-mode-note button:hover { opacity: 1; background: rgba(23, 28, 36, .08); }
+.clay-mode-note .clay-view-notice__edit {
+  width: auto;
+  padding: 0 10px;
+  border: 1px solid rgba(23, 28, 36, .2);
+  font-size: 13px;
+  font-weight: 600;
+  opacity: 1;
+}
 @media (prefers-color-scheme: dark) {
+  .clay-mode-note .clay-view-notice__edit { border-color: rgba(233, 233, 236, .22); }
   .clay-mode-note {
     border-color: rgba(233, 233, 236, .16);
     color: var(--clay-ui-fg, #E9E9EC);
@@ -74,48 +84,144 @@ const NOTE_CSS = `.clay-mode-note {
   }
 }`;
 
-function styles() {
-  if (document.getElementById("clay-mode-note-style")) return;
-  const style = document.createElement("style");
-  style.id = "clay-mode-note-style";
-  style.setAttribute("clay", "editor-ui");
-  style.textContent = NOTE_CSS;
-  document.head.append(style);
+// A note mounts in its own shadow root, so the page's CSS cannot restyle it. The helper is
+// imported only when a note shows: this module loads on every page, a note rarely.
+const closedNotes = new WeakSet();
+
+function mountNote(content) {
+  import("../ui/editor-ui.js").then(({ mountEditorUI }) => {
+    if (!closedNotes.has(content)) mountEditorUI({ name: "mode-note", content, css: [NOTE_CSS] });
+  });
 }
 
-function onKey(e) {
-  if (!(canEdit || mode === "edit")) return;
-  if (!(mac ? e.metaKey : e.ctrlKey) || !e.shiftKey || e.altKey || e.code !== "KeyE" || e.isComposing) return;
-  e.preventDefault();
-  setMode(mode === "edit" ? "view" : "edit").then((r) => {
+function closeNote(content) {
+  closedNotes.add(content);
+  content.getRootNode().host?.remove();
+}
+
+function switchTo(next) {
+  return setMode(next).then((r) => {
     if (r.ok) return;
     import("./mode-refusal.js").then(({ modeRefusalText }) => {
       const text = modeRefusalText(r);
-      if (text) window.clay?.toast?.(text, "error");
+      if (!text) return;
+      // Templates that load no UI satellite still say why the switch did nothing.
+      if (typeof window.clay?.toast === "function") window.clay.toast(text, "error");
+      else if (typeof window.clay?.menu?.note === "function") window.clay.menu.note(text);
+      else showNote(text);
     });
   });
 }
 
-function showNote() {
-  styles();
+function onKey(e) {
+  if (!(canEdit || mode === "edit")) return;
+  if (!(mac ? e.metaKey : e.ctrlKey) || !e.shiftKey || e.altKey || e.code !== "KeyE" || e.isComposing) return;
+  e.preventDefault();
+  switchTo(mode === "edit" ? "view" : "edit");
+}
+
+// A tab in view keeps nothing typed into it, and a page whose own script opens an
+// editor at load (an OverType journal) accepts that typing all day. So for a person
+// who can edit, the first edit to a field that saves in edit mode raises a notice
+// that stays until the tab edits. Fields edit mode would unlock (inert
+// contenteditable, viewmode:readonly, viewmode:disabled) raise it on the attempt.
+const VIEW_NOTICE = "In view mode, so edits won't be saved.";
+const SAVING_FIELD = ":is(input, textarea, select):is([persist], [clay-persist])";
+const INERT_FIELD = "[editmode\\:contenteditable], [viewmode\\:readonly], [viewmode\\:disabled]";
+
+let viewNotice = null;
+
+function savedContent(el) {
+  if (!el.isConnected) return false;
+  const policy = resolveRegionPolicy(el);
+  return policy.persist === PERSIST.FULL && !policy.extension;
+}
+
+function savingField(node) {
+  const el = node?.nodeType === 1 ? node : node?.parentElement;
+  if (!el) return null;
+  const field = el.closest(SAVING_FIELD) || el.closest(INERT_FIELD) || (el.isContentEditable ? el : null);
+  return field && savedContent(field) ? field : null;
+}
+
+const liveField = (el) =>
+  el.isContentEditable || (el.matches("input, textarea, select") && !el.readOnly && !el.disabled);
+
+const watching = () => canEdit && mode === "view";
+
+function onViewInput(e) {
+  if (watching() && savingField(e.target)) showViewNotice();
+}
+
+// Bubbles on window, after the page's own handlers, so a single-key shortcut the
+// page handled (and prevented) never reads as an attempt to type.
+function onViewKey(e) {
+  if (!watching() || e.defaultPrevented || e.isComposing || e.ctrlKey || e.metaKey || e.altKey) return;
+  if (!(e.key.length === 1 && e.key !== " ") && e.key !== "Backspace" && e.key !== "Delete") return;
+  const target = e.target;
+  if (target?.nodeType !== 1 || liveField(target)) return;
+  if (target !== document.body && !target.closest(INERT_FIELD)) return;
+  const field = savingField(target === document.body ? document.getSelection()?.anchorNode : target);
+  if (field?.matches(INERT_FIELD)) showViewNotice();
+}
+
+function onViewPointer(e) {
+  if (!watching()) return;
+  const field = e.target?.closest?.("[viewmode\\:disabled]");
+  if (field && savedContent(field)) showViewNotice();
+}
+
+function showViewNotice() {
+  if (viewNotice) return;
+  console.warn('clayjs: this tab is in view mode, so edits made here are not saved. clay.setMode("edit") switches; a page that must edit as soon as it opens declares <html opens-in="edit">.');
+  document.querySelector('clay-editor-ui[data-clay-ui="mode-note"]')?.remove();
+  viewNotice = document.createElement("div");
+  viewNotice.setAttribute("clay", "editor-ui");
+  viewNotice.setAttribute("role", "alert");
+  viewNotice.className = "clay-mode-note clay-view-notice";
+  viewNotice.innerHTML = '<span></span><button type="button" class="clay-view-notice__edit">Switch to edit</button>';
+  viewNotice.querySelector("span").textContent = VIEW_NOTICE;
+  viewNotice.querySelector("button").addEventListener("click", () => switchTo("edit"));
+  mountNote(viewNotice);
+}
+
+function onModeChange() {
+  if (mode === "view" || !viewNotice) return;
+  closeNote(viewNotice);
+  viewNotice = null;
+}
+
+function showNote(message) {
   const note = document.createElement("div");
   note.setAttribute("clay", "editor-ui");
   note.setAttribute("role", "status");
   note.className = "clay-mode-note";
   note.innerHTML = `<span>This page opens in view mode. Press <kbd>${chord}</kbd> to edit.</span><button type="button" aria-label="Dismiss">×</button>`;
-  const close = () => note.remove();
+  if (message) note.querySelector("span").textContent = message;
+  const close = () => closeNote(note);
   note.querySelector("button").addEventListener("click", close);
   addEventListener("keydown", (e) => { if (e.key === "Escape") close(); }, { once: true });
   setTimeout(close, 12000);
-  document.body.append(note);
+  mountNote(note);
 }
 
 if (!isDraftMode) {
   document.addEventListener("keydown", onKey);
+  document.addEventListener("input", onViewInput, true);
+  document.addEventListener("pointerdown", onViewPointer, true);
+  window.addEventListener("keydown", onViewKey);
+  document.addEventListener("clay:modechange", onModeChange);
   onDomReady(() => {
     if (!canEdit || mode !== "view" || document.querySelector("[clay-mode-toggle]")) return;
-    queueMicrotask(() => {
-      if (window.clay?.menu) return;
+    // The note needs clay.storage, which the loader attaches after the core wave.
+    const whenReady = (run) => {
+      const ready = window.clay?.ready;
+      if (window.clay?.storage || typeof ready?.then !== "function") queueMicrotask(run);
+      else ready.then(run, () => {});
+    };
+    whenReady(() => {
+      // A menu loads after ready and carries its own way in.
+      if (window.clay?.menu || window.clay?.plugins?.includes?.("menu")) return;
       const store = window.clay?.storage?.local;
       if (!store || store.get("mode-note")) return;
       store.set("mode-note", true);

package/src/core/mode-support.js

@@ -78,5 +78,10 @@ export const MODULE_SUPPORT = {
   "plugins/cms.js": "export",
 };
 
+export const PAGE_FEATURE_SUPPORT = {
+  "page/ybind/recovery.js": { owner: "plugins/page.js", lifecycle: "child" },
+  "page/recovery-ui.js": { owner: "plugins/page.js", lifecycle: "child" },
+};
+
 export const supportFor = (path) =>
   Object.prototype.hasOwnProperty.call(MODULE_SUPPORT, path) ? MODULE_SUPPORT[path] : null;

package/src/core/mode-transition.js

@@ -65,17 +65,30 @@ export async function runSaveBarrier({ generation = saveGeneration(), keepalive
   if (!operation && !claimed) return refusal("busy");
   const deadline = Date.now() + timeoutMs;
   const permit = openSavePermit(generation);
+  const abort = new AbortController();
   try {
     for (let pass = 0; ; pass++) {
       if (generation !== saveGeneration()) return refusal("stale-document");
       if (Date.now() >= deadline) return refusal("timeout");
 
-      // Work that finishes on its own — a checkpoint, a queued upload — is asked to. A
-      // composer waiting on its person has no flush and stays pending: that is a refusal,
-      // never a blur or a submit on their behalf.
-      const sources = await bounded(flushUnsaved(), deadline);
-      if (sources === EXPIRED) return refusal("timeout");
-      if (!sources.ok) return refusal("pending-input", { pending: sources.pending });
+      // Work that finishes on its own — a checkpoint, a queued upload — is asked to, under
+      // this exit's own permit and inside its own deadline: the save such a source needs is
+      // the one write a closed session still admits. A composer waiting on its person has no
+      // flush and stays pending: that is a refusal, never a blur or a submit on their behalf.
+      const context = {
+        permit,
+        deadline,
+        keepalive,
+        signal: abort.signal,
+        timeoutMs: Math.max(0, deadline - Date.now()),
+      };
+      const sources = await bounded(flushUnsaved(context), deadline);
+      if (sources === EXPIRED) return refusal("timeout", { pending: pendingIds() });
+      if (!sources.ok) {
+        if (isSaveConflicted()) return refusal("conflict", { pending: sources.pending });
+        if (saveFateIsUnknown()) return refusal("save-unknown", { pending: sources.pending });
+        return refusal("pending-input", { pending: sources.pending });
+      }
       if (sources.pending.length) return refusal("pending-input", { pending: sources.pending });
 
       // Neither a conflict nor an unresolved fate is a failure a retry fixes.
@@ -106,6 +119,7 @@ export async function runSaveBarrier({ generation = saveGeneration(), keepalive
       return { ok: true, state: result.state, etag: result.etag ?? null };
     }
   } finally {
+    abort.abort();
     closeSavePermit(permit);
     if (claimed) releaseDocumentOperation(claimed);
   }

package/src/core/preserve-authored.js

@@ -37,10 +37,10 @@ export function authoredAttr(el, name) {
 // An attribute that was removed and written again lands at the end of the list, and
 // attribute order is what a saved file compares: an untouched page would come back
 // with `disabled` moved. Rebuilding the list in the recorded order is the only way to
-// hand the file back exactly what it served. Runs only when something actually moved,
-// and only on the way out of edit.
-export function restoreAuthoredOrder(el) {
-  const seen = authored.get(el);
+// hand the file back exactly what it served. Runs only when something actually moved, on
+// the way out of edit and on the save clone, whose record belongs to its live original.
+export function restoreAuthoredOrder(el, from = el) {
+  const seen = authored.get(from);
   if (!seen) return;
   const current = el.getAttributeNames();
   const desired = [

package/src/core/recovery.js

@@ -42,6 +42,28 @@ function pageWriterId() {
   return `wr-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 
+// Each page holds a lock named for its writer for as long as it lives: a record whose
+// writer still holds one belongs to an open tab that will save it, not to lost work.
+const WRITER_LOCK = "clay-recovery-writer:";
+
+function holdWriterLock(writerId) {
+  const locks = globalThis.navigator?.locks;
+  if (typeof locks?.request !== "function") return;
+  locks.request(WRITER_LOCK + writerId, () => new Promise(() => {})).catch(() => {});
+}
+
+async function liveWriters(own) {
+  const locks = globalThis.navigator?.locks;
+  if (typeof locks?.query !== "function") return new Set();
+  try {
+    const { held = [] } = await locks.query();
+    return new Set(held.map((lock) => lock.name).filter((name) => typeof name === "string" && name.startsWith(WRITER_LOCK))
+      .map((name) => name.slice(WRITER_LOCK.length)).filter((id) => id !== own));
+  } catch {
+    return new Set();
+  }
+}
+
 function recordKey(id) {
   return Array.isArray(id) ? id.join("\u0000") : String(id);
 }
@@ -112,6 +134,34 @@ export function noteRecoveryCapture({ captureId, html } = {}) {
   for (const service of services) service.capture(captureId, html);
 }
 
+/**
+ * Freeze what every service holds at this capture's boundary.
+ *
+ * A save that prepares across tasks cannot read the services after it, so the copies that
+ * could be covered are pinned here, synchronously, in the task the snapshot was taken in.
+ * `finishRecoveryCapture` then judges exactly those against the bytes the save verifies:
+ * a copy written after this capture is neither covered by it nor acknowledged by it.
+ *
+ * @param {*} captureId
+ */
+export function beginRecoveryCapture(captureId) {
+  if (!services.size || captureId == null) return;
+  for (const service of services) service.pinCapture(captureId);
+}
+
+/**
+ * Record what this capture's final bytes cover, among the copies pinned at its boundary.
+ *
+ * Called with the verified bytes, before anything is sent. Nothing is acknowledged here.
+ *
+ * @param {*} captureId
+ * @param {string} html
+ */
+export function finishRecoveryCapture(captureId, html) {
+  if (!services.size || captureId == null) return;
+  for (const service of services) service.coverCapture(captureId, html);
+}
+
 /**
  * Report how a capture settled.
  *
@@ -153,10 +203,14 @@ export function createRecovery({
   const channels = new Map();
   const listeners = new Set();
   const captures = new Map();
+  // What each preparing capture found held at its boundary, before it could read the
+  // final bytes. Cleared however the capture settles.
+  const pinned = new Map();
   let prepared = null;
   let identity = null;
   let store = null;
   let status = { ok: true, code: null, durable: false };
+  holdWriterLock(writerId);
 
   function snapshot() {
     return {
@@ -248,6 +302,56 @@ export function createRecovery({
     return covered;
   }
 
+  // The copies a capture taken now could cover, without reading its bytes: they do not
+  // exist yet, and by the time they do a newer copy may have replaced one of these.
+  function pinCapture(captureId) {
+    const list = [];
+    for (const entry of channels.values()) {
+      if (typeof entry.readSaved !== 'function' || !entry.held.size) continue;
+      for (const record of entry.held.values()) {
+        if (record.kind !== TEXT) continue;
+        list.push({
+          channel: entry.channel,
+          key: record.key,
+          id: record.id,
+          revision: record.revision,
+          payload: record.payload,
+        });
+      }
+    }
+    if (list.length) pinned.set(captureId, list);
+  }
+
+  // The same coverage question `capture` asks, over the copies pinned at the capture and
+  // the bytes the save finally holds. The saved map is read once per channel, and only
+  // for a channel that had something it could cover.
+  function coverCapture(captureId, html) {
+    const list = pinned.get(captureId);
+    pinned.delete(captureId);
+    if (!list || typeof html !== 'string') return;
+    const saved = new Map();
+    const covered = new Map();
+    for (const candidate of list) {
+      if (!saved.has(candidate.channel)) {
+        const entry = channels.get(candidate.channel);
+        let read = null;
+        try {
+          read = typeof entry?.readSaved === 'function' ? entry.readSaved(html) : null;
+        } catch (_) {
+          read = null;
+        }
+        saved.set(candidate.channel, read && typeof read.get === 'function' ? read : null);
+      }
+      const read = saved.get(candidate.channel);
+      if (!read || !read.has(candidate.key)) continue;
+      if (!payloadsMatch(read.get(candidate.key), candidate.payload)) continue;
+      const coveredHere = covered.get(candidate.channel) ?? [];
+      coveredHere.push({ id: candidate.id, revision: candidate.revision });
+      covered.set(candidate.channel, coveredHere);
+    }
+    if (covered.size) captures.set(captureId, covered);
+  }
+
   function capture(captureId, html) {
     if (captureId == null || typeof html !== "string") return;
     const covered = new Map();
@@ -277,6 +381,7 @@ export function createRecovery({
   // acknowledgement is ordered against every put this service has already queued:
   // a copy that reaches the database late meets the watermark it was refused by.
   function settle(captureId, ok, etag) {
+    pinned.delete(captureId);
     const covered = captures.get(captureId);
     if (!covered) return Promise.resolve();
     captures.delete(captureId);
@@ -471,7 +576,6 @@ export function createRecovery({
     entry.batches += 1;
     entry.batchBytes += record.payload.byteLength;
     if (receipt.skipped) return { ok: true, id: record.id, revision, skipped: true };
-    planCompaction(entry);
     return { ok: true, id: record.id, revision };
   }
 
@@ -543,9 +647,9 @@ export function createRecovery({
    * A swap that lost the head re-reads everything and tries again, so a compaction
    * that raced an append or another compaction never deletes input it did not merge.
    */
-  async function swapBatches(entry, observed) {
+  async function swapBatches(entry, observed, rebase = null) {
     for (let tries = 0; tries < 3; tries++) {
-      let capsuleId = null;
+      let capsuleId = rebase?.capsuleId ?? null;
       const inputs = [];
       for (const { id, revision } of observed) {
         const read = await store.get(id);
@@ -556,7 +660,7 @@ export function createRecovery({
         if (!sameId(capsuleId, record.capsuleId)) continue;
         inputs.push(record);
       }
-      if (!capsuleId || !inputs.length) return { ok: true, retired: [] };
+      if (!capsuleId || !(inputs.length || rebase)) return { ok: true, retired: [] };
       const head = await store.get(capsuleId);
       if (!head.ok || !head.record) return { ok: false, code: "missing" };
       const capsule = head.record;
@@ -567,6 +671,8 @@ export function createRecovery({
       ].filter(Boolean);
       const mergedOwned = owned.length ? copyPayload(await entry.merge(owned)) : new Uint8Array(0);
       const mergedDependencies = dependencies.length ? copyPayload(await entry.merge(dependencies)) : new Uint8Array(0);
+      let payload = { base: capsule.payload?.base ?? new Uint8Array(0), dependencies: mergedDependencies, owned: mergedOwned };
+      if (rebase) payload = await rebase.rebuild(payload);
       const revision = Math.max(entry.revision, capsule.revision) + 1;
       entry.revision = revision;
       const swapped = await store.compactBinary({
@@ -574,20 +680,11 @@ export function createRecovery({
         version: entry.version,
         capsuleId,
         expectedRevision: capsule.revision,
-        replacement: {
-          revision,
-          updated: now?.() ?? Date.now(),
-          payload: {
-            base: capsule.payload?.base ?? new Uint8Array(0),
-            dependencies: mergedDependencies,
-            owned: mergedOwned,
-          },
-        },
+        replacement: { revision, updated: now?.() ?? Date.now(), context: rebase?.context, payload },
         inputs: inputs.map((record) => ({ id: record.id, revision: record.revision })),
       });
       if (swapped.ok) {
-        entry.batches = 0;
-        entry.batchBytes = 0;
+        if (inputs.length) entry.batches = entry.batchBytes = 0;
         return { ok: true, retired: swapped.retired, revision: swapped.revision };
       }
       if (swapped.code !== "stale") return { ok: false, code: swapped.code };
@@ -607,22 +704,11 @@ export function createRecovery({
     return receipt.ok ? { ok: true, retired: receipt.retired } : { ok: false, code: receipt.code, retired: [] };
   }
 
-  function planCompaction(entry) {
-    if (typeof entry.merge !== "function" || entry.compaction) return;
-    if (entry.batches < COMPACT_BATCHES && entry.batchBytes < COMPACT_BYTES) return;
-    entry.compaction = (async () => {
-      const listed = await store.list();
-      if (!listed.ok) return;
-      const mine = listed.records.filter(
-        (record) => record.channel === entry.channel && record.kind === "binary-batch" && record.writerId === writerId
-      );
-      if (!mine.length) return;
-      await compact(entry, { records: mine.map(({ id, revision }) => ({ id, revision })) });
-    })()
-      .catch(() => {})
-      .finally(() => {
-        entry.compaction = null;
-      });
+  async function rebase(entry, { key, context, rebuild } = {}) {
+    const opened = await ensurePrepared();
+    const receipt = opened.ok ? await swapBatches(entry, [], { capsuleId: binaryOf(entry, String(key)), context, rebuild }) : opened;
+    note(receipt);
+    return receipt;
   }
 
   function flush(entry) {
@@ -644,8 +730,9 @@ export function createRecovery({
     const result = await store.list();
     note(result);
     if (!result.ok) return { ok: false, code: result.code, records: [], status: snapshot() };
+    const live = await liveWriters(writerId);
     const records = result.records
-      .filter((record) => record.channel === entry.channel)
+      .filter((record) => record.channel === entry.channel && !live.has(record.writerId))
       .map((record) => ({ ...record, supported: record.version === entry.version }));
     return { ok: true, records, status: snapshot() };
   }
@@ -684,7 +771,7 @@ export function createRecovery({
     return flushed;
   }
 
-  const handle = { capture, settle };
+  const handle = { capture, settle, pinCapture, coverCapture };
 
   function channelApi(entry) {
     return {
@@ -698,6 +785,7 @@ export function createRecovery({
       markAcknowledged: (spec) => markAcknowledged(entry, spec),
       checkpoint: (spec) => checkpoint(entry, spec),
       compact: (spec) => compact(entry, spec),
+      rebase: (spec) => rebase(entry, spec),
       subscribe: (fn) => subscribe(entry, fn),
       dispose: () => dispose(entry),
     };

package/src/core/save-accepted.js

@@ -0,0 +1,33 @@
+// The hook every accepted save reports to, in a module of its own so a reader can
+// listen for accepted bytes without loading the save code.
+const saveAcceptedHooks = [];
+
+/**
+ * Run a callback with the bytes the host just accepted.
+ *
+ * Called once per accepted save, after the response, with the exact body that was
+ * sent. Never called for a refused, failed or skipped save, and never in test mode,
+ * where nothing reached a host.
+ *
+ * @param {Function} callback - Receives the accepted HTML string
+ */
+export function onSaveAccepted(callback) {
+  saveAcceptedHooks.push(callback);
+}
+
+export function notifySaveAccepted(html, captureId, artifact = null) {
+  for (const hook of saveAcceptedHooks) {
+    try {
+      // The artifact is the capture's own private model of these bytes, and it is
+      // offered only when it exists: a raw save and a capture without one keep the
+      // shape they had.
+      const accepted = artifact
+        ? { captureId: captureId ?? null, artifact }
+        : { captureId: captureId ?? null };
+      hook(html, accepted);
+    } catch (err) {
+      console.error('clayjs: onSaveAccepted hook failed:', err);
+    }
+  }
+}
+