@panphora/clayjs 1.16.0 → 1.17.0

package/src/page/view-hooks.js

@@ -0,0 +1,32 @@
+import { state } from "../vendor/prosemirror.vendor.js";
+
+// The update hooks a loaded view part registers for its editor view. The plugin
+// below calls them on every document change, so a part keeps its blocks fresh
+// without the editor importing it: the part adds its hook when it installs and
+// removes it on dispose.
+export const viewHooks = new WeakMap();
+
+// The feature loader of each mounted editor, so an insert path can ask for a
+// block's part before it draws the block.
+export const viewFeatures = new WeakMap();
+
+export function addViewHook(view, hook) {
+  const hooks = viewHooks.get(view) ?? new Set();
+  viewHooks.set(view, hooks);
+  hooks.add(hook);
+  return () => hooks.delete(hook);
+}
+
+export function viewHookPlugin() {
+  return new state.Plugin({
+    view: (view) => ({
+      update: (next) => { for (const hook of viewHooks.get(next) ?? []) hook.update?.(next); },
+      destroy: () => {
+        const hooks = viewHooks.get(view);
+        if (!hooks) return;
+        for (const hook of hooks) hook.destroy?.(view);
+        hooks.clear();
+      },
+    }),
+  });
+}

package/src/page/ybind/binding.js

@@ -3,16 +3,32 @@ import { NET, createPageDoc, walk, docOf } from "./core.js";
 import { createBridge, keepViewPos } from "./bridge.js";
 import { createYProvider, entriesOf, dec } from "./provider.js";
 
-export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () => {}, ownedTokens = [], authorToken = null, setTimer = setTimeout, clearTimer = clearTimeout, compact, captureTimeout = 500, checkpointWithin = () => {}, requestCheckpoint = null, registerUnsavedState = null, onStopped = () => {} }) {
+export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () => {}, ownedTokens = [], authorToken = null, setTimer = setTimeout, clearTimer = clearTimeout, compact, captureTimeout = 500, checkpointWithin = () => {}, requestCheckpoint = null, registerUnsavedState = null, onStopped = () => {}, journal = null }) {
   for (const [, v] of entriesOf(store.value.y)) Y.applyUpdateV2(ydoc, dec(v), NET);
   const pd = createPageDoc(ydoc);
-  const provider = createYProvider({ store, ydoc, setTimer, clearTimer, compact, onStopped });
+  // The journal is installed before the provider, because the provider is what sees an
+  // update: nothing can reach the document without passing it first. Its own code lives
+  // with the recovery channel and is only loaded when a page has one to journal into.
+  const pageJournal = journal || null;
+  const provider = createYProvider({
+    store,
+    ydoc,
+    setTimer,
+    clearTimer,
+    compact,
+    onStopped,
+    journal: { local: (u) => pageJournal?.local(u), dependency: (u) => pageJournal?.dependency(u) },
+  });
   const stats = { groups: 0, mismatch: 0, renders: 0, first: null };
   const bridge = createBridge({ pd, onNotice, ownedTokens, authorToken, stats, captureTimeout });
   const waiters = new Set();
   let disposed = false;
   let checksQueued = false;
-  const unsaved = registerUnsavedState?.({ id: "page:live", isPending: () => store.pending.length > 0 || provider.reconcilePending, flush });
+  const unsaved = registerUnsavedState?.({
+    id: "page:live",
+    isPending: () => store.pending.length > 0 || provider.reconcilePending || Boolean(pageJournal && !pageJournal.failure && pageJournal.pending()),
+    flush,
+  });
   const changed = () => {
     unsaved?.changed();
     if (checksQueued) return;
@@ -24,7 +40,13 @@ export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () =>
   };
   const offLocal = store.onLocal(() => { checkpointWithin(1500); changed(); });
   const offRebase = store.onRebase(changed);
-  const offConfirm = store.onConfirm(changed);
+  const offConfirm = store.onConfirm(() => {
+    pageJournal?.acknowledged();
+    changed();
+  });
+  // Everything the journal reports while this session is the active one is unsaved state:
+  // a write in flight, a write the store refused, or a room that has not confirmed.
+  if (pageJournal) pageJournal.onChange = changed;
 
   function flush({ timeoutMs = 10_000 } = {}) {
     if (disposed) return Promise.resolve({ ok: false, code: "disposed" });
@@ -73,6 +95,7 @@ export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () =>
 
   return {
     ydoc, pd, provider, bridge, stats, flush, awareness,
+    get journal() { return pageJournal; },
     doc: () => keepViewPos(docOf(pd, walk(pd))),
     attach: (view) => bridge.attach(view),
     dispatch: (tr) => bridge.dispatch(tr),
@@ -92,6 +115,10 @@ export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () =>
       offRebase();
       offConfirm();
       unsaved?.dispose();
+      // Best effort, never the primary path: every append already resolved on its own
+      // commit, and what is left is only a write the store refused.
+      pageJournal?.close();
+      Promise.resolve(pageJournal?.channel?.flush?.()).catch(() => {});
       for (const waiter of [...waiters]) waiter.finish({ ok: false, code: "disposed" });
       bridge.dispose();
       provider.dispose();

package/src/page/ybind/marks.js

@@ -1,5 +1,6 @@
 import { schema } from "../schema.js";
 import { entriesOfYjs, isOpaque, opaqueMark, yjsFields } from "../format-codec.js";
+import { NATIVE_NAMES, nativeAttrs } from "../format-native.js";
 
 export const markName = (k) => k.split("!")[0].split("~")[0];
 export const isCancel = (k) => k.includes("!");
@@ -29,7 +30,7 @@ export function marksFromAttributes(a, blockType) {
   const marks = [];
   let unknown = null;
   for (const [n, v] of best) {
-    if (schema.marks[n]) marks.push(schema.marks[n].create(v === true ? null : v));
+    if (schema.marks[n] && (!NATIVE_NAMES.has(n) || nativeAttrs(n, v))) marks.push(schema.marks[n].create(v === true ? null : v));
     else (unknown ??= {})[n] = v;
   }
   // The walk asks this of every text run on every keystroke, and almost none carry a

package/src/page/ybind/provider.js

@@ -11,6 +11,10 @@ export const enc = (u) => toBase64(u);
 export const dec = (s) => fromBase64(s);
 
 export const PART = 12 * 1024;
+
+// The origin a replayed journal is applied through. It is offered to the room like any
+// other local work and is never journaled again: a recovery is not this tab's typing.
+export const RECOVERY_ORIGIN = "page-recovery";
 const baseOf = (k) => PART_KEY.exec(k)?.[1] ?? k;
 
 export function yValueOf(ydoc) {
@@ -80,7 +84,7 @@ const utf8Bytes = (text) => (encoder ? encoder.encode(text).length : text.length
 const sameDeletes = (a, b) => Y.equalDeleteSets(Y.createDeleteSetFromStructStore(a.store), Y.createDeleteSetFromStructStore(b.store));
 const svEqual = (a, b) => { if (a.size !== b.size) return false; for (const [c, n] of a) if (b.get(c) !== n) return false; return true; };
 
-export function createYProvider({ store, ydoc, compact: limits = {}, setTimer = setTimeout, clearTimer = clearTimeout, onStopped = () => {}, stats = { applied: 0, offered: 0, compactions: 0 } }) {
+export function createYProvider({ store, ydoc, compact: limits = {}, setTimer = setTimeout, clearTimer = clearTimeout, onStopped = () => {}, stats = { applied: 0, offered: 0, compactions: 0 }, journal = null }) {
   const initial = entriesOf(store.value.y);
   const known = new Set();
   // Set when this tab's page can no longer reach the room: "lineage" when the room holds
@@ -116,7 +120,10 @@ export function createYProvider({ store, ydoc, compact: limits = {}, setTimer =
 
   for (const [k] of initial) known.add(k);
 
+  // Ahead of the stop guards, and of the room's own delivery: work this tab can no longer
+  // offer, and work a refused offer took back, is still work a crash must not lose.
   const onUpdate = (u, origin) => {
+    if (origin !== NET && origin !== ORIGINS_ORIGIN && origin !== RECOVERY_ORIGIN) journal?.local(u);
     if (stopped || origin === NET || origin === ORIGINS_ORIGIN) return;
     put(nextKey("u"), u);
   };
@@ -127,7 +134,11 @@ export function createYProvider({ store, ydoc, compact: limits = {}, setTimer =
     canCompact = true;
     known.add(k);
     stats.applied++;
-    Y.applyUpdateV2(ydoc, dec(v), NET);
+    const update = dec(v);
+    Y.applyUpdateV2(ydoc, update, NET);
+    // A received update can be the prerequisite of a later local insert, so the journal
+    // keeps it beside the work it owns, and never counts it as this tab's own.
+    journal?.dependency(update);
   };
 
   let wantReconcile = false;

package/src/page/ybind/recovery-replay.js

@@ -16,9 +16,22 @@ import * as Y from "../../vendor/yjs.vendor.js";
 import { toBase64 } from "../../vendor/yjs.vendor.js";
 import { NET } from "./layout.js";
 import { blocksFromYValue } from "./decode.js";
-import { sameAuthority } from "../../recovery/identity.js";
-import { sameLineage, sharesAncestry } from "./lineage.js";
-import { canonicalPageBytes, containsUpdate } from "./recovery-proof.js";
+import { sameAuthority, hostIdentityOf, pathIdentityOf } from "../../recovery/identity.js";
+import { sameLineage, sharesAncestry, lineageOf } from "./lineage.js";
+import { canonicalPageBytes, containsUpdate, digestHex, validatePageCheckpoint } from "./recovery-proof.js";
+import { RECOVERY_ORIGIN } from "./provider.js";
+
+/** The channel this adapter journals and replays: one name, one version, everywhere. */
+export const PAGE_CHANNEL = "page.yjs";
+export const PAGE_CHANNEL_VERSION = 1;
+
+// When one writer's batches are merged into its capsule: past either threshold, and never
+// over a record the store has not confirmed.
+export const COMPACT_BATCHES = 64;
+export const COMPACT_BYTES = 1024 * 1024;
+
+/** The channel's own merge, for the binary store's compaction. */
+export const mergePageUpdates = (parts) => Y.mergeUpdatesV2(parts);
 
 export class PageReplayError extends Error {
   constructor(code, message) {
@@ -125,6 +138,351 @@ export function admitCapsule({ capsule, batches = [], current } = {}) {
   const stateBytes = canonicalPageBytes(current.state);
   if (parts.base.length && !containsUpdate(stateBytes, parts.base)) fail("missing-base", "The page no longer contains the journal's base");
   if (!parts.owned.length) fail("nothing-owned", "This capsule owns no local work");
-  if (!sharesAncestry(current.state, { v: 1, g: 0, y: { seed: toBase64(parts.owned) } })) fail("foreign-lineage", "This journal shares no ancestry with this page");
+  // The reconstructed page is what has to share this page's ancestry, base included:
+  // this tab's own inserts carry its client alone, and never the page's.
+  const rebuilt = merge([parts.base, parts.dependencies, parts.owned]);
+  if (!sharesAncestry(current.state, { v: 1, g: 0, y: { seed: toBase64(rebuilt) } })) fail("foreign-lineage", "This journal shares no ancestry with this page");
   return parts;
 }
+
+/**
+ * One writer's capsules, each with the batches that belong to it.
+ *
+ * A session that died before its batches were compacted leaves them behind, so a
+ * capsule is only ever read together with every batch naming it, whichever session
+ * wrote it.
+ *
+ * @param {Array<Object>} [records] - what the channel listed
+ * @returns {Array<{capsule: Object, batches: Array<Object>}>}
+ */
+export function capsulesOf(records = []) {
+  const capsules = new Map();
+  const batches = new Map();
+  for (const record of records || []) {
+    if (!record || record.supported === false) continue;
+    if (record.kind === "binary") {
+      capsules.set(identityKey(record.id), record);
+      continue;
+    }
+    if (record.kind !== "binary-batch" || record.capsuleId === undefined) continue;
+    const key = identityKey(record.capsuleId);
+    const list = batches.get(key) ?? [];
+    list.push(record);
+    batches.set(key, list);
+  }
+  return [...capsules.entries()].map(([key, capsule]) => ({ capsule, batches: batches.get(key) ?? [] }));
+}
+
+/**
+ * Apply an admitted capsule's three parts into a live document.
+ *
+ * The recovery origin is its own: the provider offers the result to the room, and the
+ * journal never takes it as this tab's own work, so a recovery is never journaled twice.
+ *
+ * @param {Object} doc - the Y.Doc the page is being edited in
+ * @param {Object} parts - an `accumulateCapsule` result
+ */
+export function applyCapsule(doc, parts) {
+  for (const bytes of [parts.base, parts.dependencies, parts.owned]) {
+    if (bytes && bytes.length) Y.applyUpdateV2(doc, bytes, RECOVERY_ORIGIN);
+  }
+}
+
+/**
+ * Replay every capsule this page may replay, and name the ones it may not.
+ *
+ * Nothing is applied for a capsule that fails admission: a changed authority, a changed
+ * generation, a base the page no longer contains or no shared ancestry is review, not a
+ * merge. A capsule with no owned work has nothing to restore and is skipped silently.
+ *
+ * @param {{records?: Array<Object>, current: {context: Object, state: Object}, into: Object}} options
+ * @returns {{replayed: Array<Object>, review: Array<Object>}}
+ */
+export function replayJournals({ records = [], current, into } = {}) {
+  const replayed = [];
+  const review = [];
+  for (const entry of capsulesOf(records)) {
+    let parts;
+    try {
+      parts = admitCapsule({ capsule: entry.capsule, batches: entry.batches, current });
+    } catch (error) {
+      if (error?.code === "nothing-owned") continue;
+      review.push({ capsule: entry.capsule, code: error?.code ?? "invalid-capsule", message: error?.message ?? "This journal cannot be replayed" });
+      continue;
+    }
+    applyCapsule(into, parts);
+    replayed.push({ id: entry.capsule.id, revision: parts.revision, owned: parts.owned.length });
+  }
+  return { replayed, review };
+}
+
+/**
+ * The context one episode's capsules are journaled under.
+ *
+ * A host that persists a page generation names it; without one, the generation is the
+ * digest of the accepted base, so a page rebuilt from other bytes is another generation
+ * and a page that has not changed keeps its own.
+ *
+ * @param {Object} options
+ * @param {{host: string, documentId: string, principalId: string}} options.authority
+ * @param {?string} options.generation
+ * @param {?Uint8Array} options.base - the accepted state captured at the episode's start
+ * @param {number} [options.formatFloor]
+ * @returns {Promise<Object>}
+ */
+export async function pageJournalContext({ authority, generation = null, base = null, formatFloor = 0 } = {}) {
+  const bytes = bytesOf(base) ?? new Uint8Array(0);
+  const token = typeof generation === "string" && generation ? generation : await digestHex(bytes);
+  return { authority, lineage: await lineageOf(token, bytes), formatFloor };
+}
+
+/**
+ * The authority this page journals under, or null when it cannot be pinned.
+ *
+ * A host that names people names the account too, and an answer without one is not a
+ * principal: replay waits for the next boot rather than filing work under a guess. A
+ * host with no people support gives its document to whoever holds it, so the document's
+ * own host identity is the principal there.
+ *
+ * @param {Object} [options]
+ * @param {?Object} [options.meta] - the host's discovery answer
+ * @param {?Location} [options.location]
+ * @param {?Element} [options.root]
+ * @returns {?{host: string, documentId: string, principalId: string}}
+ */
+export function pageAuthority({ meta = null, location: where = globalThis.location, root = globalThis.document?.documentElement } = {}) {
+  const host = where?.origin ?? "";
+  if (!host) return null;
+  const documentId = hostIdentityOf(root)?.identity ?? pathIdentityOf(where?.pathname ?? "/").identity;
+  if (!documentId) return null;
+  const people = meta?.document?.people;
+  const principalId = people && typeof people === "object" ? people.me?.id ?? null : documentId;
+  if (!principalId) return null;
+  return { host, documentId, principalId };
+}
+
+const journalKey = (id) => (typeof id === "string" ? id : JSON.stringify(id));
+
+/**
+ * The accepted page state an episode starts from, as the bytes its capsule keeps.
+ *
+ * @param {Object} state - a version 1 page value
+ * @returns {Uint8Array}
+ */
+export const journalBase = (state) => canonicalPageBytes(state);
+
+/**
+ * The page channel of one recovery service, registered once per page load.
+ *
+ * A channel is registered at its own version and nothing calls it until a page can
+ * actually journal: a reader and a page without a pinned identity register nothing.
+ *
+ * @param {Object} service - `clay.recovery`
+ * @returns {Object} the channel api
+ */
+const channels = new WeakMap();
+export function pageChannel(service) {
+  if (!service) return null;
+  const existing = channels.get(service);
+  if (existing) return existing;
+  const channel = service.register({
+    channel: PAGE_CHANNEL,
+    version: PAGE_CHANNEL_VERSION,
+    validateCheckpoint: validatePageCheckpoint,
+    merge: mergePageUpdates,
+  });
+  channels.set(service, channel);
+  return channel;
+}
+
+/**
+ * One session's journal in the shared recovery store.
+ *
+ * Every local update is handed over as it happens: the bytes and the id are fixed
+ * synchronously, so a buffer reused after the call cannot change what was written, and
+ * the append resolves only once its transaction committed. Nothing here waits for the
+ * room, the network or the editor. Compaction names only the records the store has
+ * confirmed, because an append still in flight or refused has no revision to swap and
+ * must keep exactly the bytes it was given.
+ *
+ * @param {Object} options
+ * @param {Object} options.channel - the `page.yjs` channel api
+ * @param {string} options.key - the document this episode belongs to
+ * @param {Function|Object} options.context - (base) => Promise<context>, or the context
+ * @param {?Uint8Array} [options.base] - the accepted state the episode started from
+ * @returns {Object}
+ */
+export function createPageJournal({ channel, key, context, base = null, onChange = () => {} }) {
+  const records = new Map();
+  const waiting = [];
+  const inflight = new Set();
+  const bytesOfBase = bytesOf(base) ?? new Uint8Array(0);
+  let resolved = null;
+  let failure = null;
+  let batches = 0;
+  let batchBytes = 0;
+  let episode = false;
+  let compacting = null;
+  let closed = false;
+
+  const journal = {
+    channel,
+    key,
+    onChange,
+    context: () => ready,
+    local: (bytes) => send(bytes, "local"),
+    // Only while an episode is open: a peer's updates on their own are not this tab's work
+    // to keep, and a page that has journaled nothing owns nothing.
+    dependency: (bytes) => { if (episode) send(bytes, "dependency"); },
+    records: () => [...records.values()],
+    names,
+    pending: () => inflight.size + (failure ? 1 : 0),
+    get failure() { return failure; },
+    retire,
+    compact,
+    // An acknowledgement is metadata: it says a room holds the bytes and retires nothing.
+    acknowledged: () => {
+      if (closed || !resolved || !records.size || typeof channel.markAcknowledged !== "function") return Promise.resolve(null);
+      return Promise.resolve(channel.markAcknowledged({ records: names(), authority: resolved.authority })).catch(() => null);
+    },
+    close: () => {
+      closed = true;
+      waiting.length = 0;
+    },
+  };
+
+  const ready = Promise.resolve()
+    .then(() => (typeof context === "function" ? context(bytesOfBase) : context))
+    .catch(() => null)
+    .then((value) => {
+      resolved = value && value.authority ? value : null;
+      if (!resolved) {
+        closed = true;
+        failure = "unavailable";
+        waiting.length = 0;
+        journal.onChange();
+        return null;
+      }
+      for (const run of waiting.splice(0)) run(resolved);
+      return resolved;
+    });
+
+  function retire(list) {
+    for (const item of list || []) records.delete(journalKey(item?.id));
+  }
+
+  function names() {
+    return [...records.values()].map(({ id, revision }) => ({ id, revision }));
+  }
+
+  function compact() {
+    if (compacting || closed || !records.size || typeof channel.compact !== "function") return compacting;
+    const named = names();
+    compacting = Promise.resolve()
+      .then(() => channel.compact({ records: named }))
+      .then((receipt) => {
+        if (!receipt?.ok) return receipt;
+        retire(receipt.retired);
+        batches = Math.max(0, batches - (receipt.retired?.length ?? 0));
+        if (!batches) batchBytes = 0;
+        return receipt;
+      })
+      .catch(() => null)
+      .then((receipt) => {
+        compacting = null;
+        journal.onChange();
+        return receipt;
+      });
+    return compacting;
+  }
+
+  function write(context, bytes, origin, first) {
+    let answer;
+    try {
+      answer = channel.append({ key, context, update: bytes, origin, base: first ? bytesOfBase : null });
+    } catch (_) {
+      failure = "error";
+      journal.onChange();
+      return;
+    }
+    const token = {};
+    inflight.add(token);
+    Promise.resolve(answer).then(
+      (receipt) => {
+        inflight.delete(token);
+        if (!receipt || receipt.ok !== true) {
+          failure = receipt?.code ?? "error";
+          journal.onChange();
+          return;
+        }
+        failure = null;
+        if (!receipt.skipped) {
+          records.set(journalKey(receipt.id), { id: receipt.id, revision: receipt.revision, update: bytes, context });
+          batches += 1;
+          batchBytes += bytes.byteLength;
+        }
+        journal.onChange();
+        if (batches >= COMPACT_BATCHES || batchBytes >= COMPACT_BYTES) compact();
+      },
+      () => {
+        inflight.delete(token);
+        failure = "error";
+        journal.onChange();
+      },
+    );
+  }
+
+  function send(bytes, origin) {
+    if (closed || !bytes || !bytes.byteLength || typeof channel.append !== "function") return;
+    const first = !episode;
+    episode = true;
+    if (resolved) write(resolved, bytes, origin, first);
+    else waiting.push((context) => write(context, bytes, origin, first));
+  }
+
+  return journal;
+}
+
+/**
+ * This session's journal, opened from the host's own answer, or null.
+ *
+ * A host that cannot name who is writing, or a tab with no recovery service, journals
+ * nothing: a page that cannot pin its identity never replays across sessions.
+ *
+ * @param {Object} options
+ * @param {?Object} options.meta - the host's discovery answer
+ * @param {Object} options.service - `clay.recovery`
+ * @param {?Uint8Array} options.base - the accepted state captured before input
+ * @param {Function} [options.onChange]
+ * @returns {?Object}
+ */
+export function openPageJournal({ meta = null, service = null, base = null, onChange = () => {}, location, root } = {}) {
+  const authority = pageAuthority({ meta, location, root });
+  if (!authority) return null;
+  const channel = pageChannel(service);
+  if (!channel) return null;
+  const generation = meta?.document?.pageState?.generation ?? null;
+  const formatFloor = Array.isArray(meta?.extensions) && meta.extensions.includes("page-format-v1") ? 1 : 0;
+  return createPageJournal({
+    channel,
+    key: [authority.host, authority.documentId].join(":"),
+    context: (accepted) => pageJournalContext({ authority, generation, base: accepted, formatFloor }),
+    base,
+    onChange,
+  });
+}
+
+/**
+ * Replay this page's journal once, after the authority snapshot is adopted.
+ *
+ * @param {{journal: Object, state: Object, into: Object}} options
+ * @returns {Promise<{replayed: Array<Object>, review: Array<Object>}>}
+ */
+export async function replayInto({ journal, state, into } = {}) {
+  if (!journal) return { replayed: [], review: [] };
+  const context = await journal.context();
+  if (!context) return { replayed: [], review: [] };
+  const listed = await journal.channel.list();
+  if (!listed?.ok) return { replayed: [], review: [] };
+  return replayJournals({ records: listed.records, current: { context, state }, into });
+}

package/src/plugins/live.js

@@ -8,7 +8,7 @@
 import { contains, parseBy, frameSet, descendants, unionRanges, formatBy } from "../live/provenance.js";
 import { createStore } from "../live/store.js";
 import { serializeLive, stampOf, parseStamp, textHash } from "../live/ops.js";
-import { onSnapshot } from "../core/snapshot.js";
+import { capturePageState, onSnapshot } from "../core/snapshot.js";
 import { onSaveAccepted, onSaveAttempt, onSaveOutcome, isSaveInProgress } from "../core/save-core.js";
 import { savePageForce, baselineSettled, isSaveConflicted, autosaveIsSuspended } from "../core/save.js";
 import { withKeepalive } from "../core/save-core.js";
@@ -1235,11 +1235,47 @@ onSaveOutcome(({ captureId, result, attempts, sent }) => {
   if (plan) startHistoryRecovery(plan, { result, attempts, startedAt: Date.now() });
 });
 
+// The recovery integration's turn at an accepted save, when one journals this page.
+// Registered by page code once it holds a `page.yjs` channel, so a page that journals
+// nothing loads neither the proof builder nor the conditional client, and pays one null
+// check per save.
+let pageCheckpoints = null;
+
+/**
+ * Hand every accepted save to a page checkpoint integration, or null to stop.
+ *
+ * The integration builds the proof from the capture's pinned page state and the bytes
+ * the host took; nothing here decides what is covered. Its answer is not awaited: a save
+ * that succeeded is saved whether or not a journal can be retired, and a failure there
+ * must never reach the save's own outcome.
+ *
+ * @param {?Function} install - ({capture, state, article, etag}) => unknown
+ */
+export function registerPageCheckpoints(install) {
+  pageCheckpoints = install;
+}
+
+function offerCheckpoint(captureId, html) {
+  if (!pageCheckpoints) return;
+  // Read synchronously, before this capture is released: the value is the one its page
+  // tag carried, and the edits that followed it are not in these bytes.
+  const state = capturePageState(captureId);
+  if (!state) return;
+  let article = null;
+  try { article = parseHtml(html).querySelector("article[data-page]")?.innerHTML ?? null; }
+  catch (_) { article = null; }
+  const etag = lastSeenEtag();
+  Promise.resolve()
+    .then(() => pageCheckpoints({ capture: String(captureId), state, article, etag }))
+    .catch(() => {});
+}
+
 // An accepted body confirms the ops of the capture that sent it, and only those.
 // A null context (a raw save) cannot consume a captured pin.
 function handleAccepted(html, context) {
   const captureId = context?.captureId;
   if (captureId === null || captureId === undefined) return;
+  offerCheckpoint(captureId, html);
   const pin = capturePins.get(captureId);
   if (!pin) return;
   dropCapture(captureId);