@panphora/clayjs 1.17.0 → 1.18.0

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

@@ -20,6 +20,7 @@ import { sameAuthority, hostIdentityOf, pathIdentityOf } from "../../recovery/id
 import { sameLineage, sharesAncestry, lineageOf } from "./lineage.js";
 import { canonicalPageBytes, containsUpdate, digestHex, validatePageCheckpoint } from "./recovery-proof.js";
 import { RECOVERY_ORIGIN } from "./provider.js";
+import { registerUnsavedState } from "../../lib/unsaved-state.js";
 
 /** The channel this adapter journals and replays: one name, one version, everywhere. */
 export const PAGE_CHANNEL = "page.yjs";
@@ -193,11 +194,22 @@ export function applyCapsule(doc, parts) {
  *
  * 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.
+ * merge. A capsule with no owned work has nothing to restore and is skipped silently, and
+ * so is one from the generation before a save that already holds all its work: that save
+ * reached the file after its tab stopped listening for the answer.
  *
  * @param {{records?: Array<Object>, current: {context: Object, state: Object}, into: Object}} options
  * @returns {{replayed: Array<Object>, review: Array<Object>}}
  */
+function alreadyHeld(entry, current) {
+  try {
+    const { owned } = accumulateCapsule({ capsule: entry.capsule, batches: entry.batches });
+    return owned.length > 0 && containsUpdate(canonicalPageBytes(current.state), owned);
+  } catch {
+    return false;
+  }
+}
+
 export function replayJournals({ records = [], current, into } = {}) {
   const replayed = [];
   const review = [];
@@ -206,8 +218,8 @@ export function replayJournals({ records = [], current, into } = {}) {
     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" });
+      if (error?.code === "nothing-owned" || (error?.code === "foreign-generation" && alreadyHeld(entry, current))) continue;
+      review.push({ capsule: entry.capsule, batches: entry.batches, code: error?.code ?? "invalid-capsule", message: error?.message ?? "This journal cannot be replayed" });
       continue;
     }
     applyCapsule(into, parts);
@@ -244,25 +256,49 @@ export async function pageJournalContext({ authority, generation = null, base =
  * host with no people support gives its document to whoever holds it, so the document's
  * own host identity is the principal there.
  *
+ * `scope` records how the document was named. A host that gives the document an identity
+ * of its own is `"host"`; a host that gives it none, a local file among them, is `"path"`,
+ * and then the exact pathname is the whole of what this page's identity is.
+ *
  * @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}}
+ * @returns {?{host: string, documentId: string, principalId: string, scope: "host"|"path"}}
  */
 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;
+  const hostIdentity = hostIdentityOf(root);
+  const scope = hostIdentity ? "host" : "path";
+  const documentId = hostIdentity?.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 };
+  return { host, documentId, principalId, scope };
 }
 
 const journalKey = (id) => (typeof id === "string" ? id : JSON.stringify(id));
 
+// Is `next` a later accepted state than `base`? A state vector only grows, so one that
+// is behind the base anywhere is an older save that finished late.
+function newer(next, base) {
+  if (!base.length) return true;
+  const ahead = Y.decodeStateVector(Y.encodeStateVectorFromUpdateV2(base));
+  const behind = Y.decodeStateVector(Y.encodeStateVectorFromUpdateV2(next));
+  for (const [client, clock] of ahead) if ((behind.get(client) ?? 0) < clock) return false;
+  return true;
+}
+
+// The part of a capsule the new base does not already hold: work a compaction merged in
+// before the save that covered it reads as nothing once that save is the base.
+function unsaved(base, part) {
+  const bytes = bytesOf(part);
+  if (!bytes || !bytes.length) return new Uint8Array(0);
+  return containsUpdate(base, bytes) ? new Uint8Array(0) : bytes;
+}
+
 /**
  * The accepted page state an episode starts from, as the bytes its capsule keeps.
  *
@@ -315,13 +351,17 @@ export function pageChannel(service) {
 export function createPageJournal({ channel, key, context, base = null, onChange = () => {} }) {
   const records = new Map();
   const waiting = [];
+  const awaiting = [];
   const inflight = new Set();
-  const bytesOfBase = bytesOf(base) ?? new Uint8Array(0);
+  let bytesOfBase = bytesOf(base) ?? new Uint8Array(0);
   let resolved = null;
   let failure = null;
   let batches = 0;
   let batchBytes = 0;
   let episode = false;
+  let carryBase = true;
+  let holding = false;
+  let rebasing = Promise.resolve(null);
   let compacting = null;
   let closed = false;
 
@@ -329,16 +369,38 @@ export function createPageJournal({ channel, key, context, base = null, onChange
     channel,
     key,
     onChange,
-    context: () => ready,
+    // The context of the base the journal holds now: an accepted save moves it.
+    context: () => ready.then(() => resolved),
     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),
+    // The next record this journal commits, or null when the store refuses one or the
+    // session closes: the destination a copy names is only real once it is on this device.
+    next: () => new Promise((resolve) => { awaiting.push(resolve); }),
+    // Does the work this journal holds carry exactly this block's text? The episode's own
+    // base is here, so the answer needs no store and no page.
+    covers: (blockId, text) => {
+      const owned = [...records.values()].map((record) => record.update).filter((update) => update && update.byteLength);
+      const capsule = {
+        kind: "binary",
+        version: 1,
+        id: "journal",
+        revision: 0,
+        payload: {
+          base: bytesOfBase,
+          dependencies: new Uint8Array(0),
+          owned: owned.length ? Y.mergeUpdatesV2(owned) : new Uint8Array(0),
+        },
+      };
+      return coversText([capsule], blockId, text);
+    },
+    pending: () => inflight.size + (holding ? waiting.length : 0) + (failure ? 1 : 0),
     get failure() { return failure; },
     retire,
+    rebase,
     compact,
     // An acknowledgement is metadata: it says a room holds the bytes and retires nothing.
     acknowledged: () => {
@@ -348,6 +410,7 @@ export function createPageJournal({ channel, key, context, base = null, onChange
     close: () => {
       closed = true;
       waiting.length = 0;
+      settle(null);
     },
   };
 
@@ -367,8 +430,61 @@ export function createPageJournal({ channel, key, context, base = null, onChange
       return resolved;
     });
 
+  function settle(value) {
+    for (const resolve of awaiting.splice(0)) resolve(value);
+  }
+
   function retire(list) {
-    for (const item of list || []) records.delete(journalKey(item?.id));
+    for (const item of list || []) {
+      const key = journalKey(item?.id);
+      const record = records.get(key);
+      if (!record) continue;
+      records.delete(key);
+      batches = Math.max(0, batches - 1);
+      batchBytes = Math.max(0, batchBytes - (record.update?.byteLength ?? 0));
+    }
+  }
+
+  // An accepted save is the base the next replay starts from: the page reopens on it,
+  // and the batches it retired are no longer there to build on. Rebases run one at a
+  // time, appends wait for them, and a save older than the base already held is ignored.
+  function rebase(state) {
+    rebasing = rebasing.then(() => moveBase(bytesOf(state))).catch(() => null);
+    return rebasing;
+  }
+
+  async function moveBase(next) {
+    if (closed || !resolved || !next || !next.length || !newer(next, bytesOfBase)) return null;
+    holding = true;
+    try {
+      while (inflight.size && !closed) await journal.next();
+      if (closed) return null;
+      const moved = typeof context === "function" ? await context(next) : context;
+      if (!moved || !moved.authority) return null;
+      if (episode) {
+        const answer = typeof channel.rebase === "function"
+          ? await channel.rebase({
+              key,
+              context: moved,
+              rebuild: (payload) => ({
+                base: next,
+                dependencies: unsaved(next, payload.dependencies),
+                owned: unsaved(next, payload.owned),
+              }),
+            })
+          : null;
+        // A writer whose capsule never reached the store starts its next one on this base.
+        if (answer?.code === "missing") carryBase = true;
+        else if (!answer?.ok) return null;
+      }
+      bytesOfBase = next;
+      resolved = moved;
+      for (const record of records.values()) record.context = moved;
+      return moved;
+    } finally {
+      holding = false;
+      if (resolved) for (const run of waiting.splice(0)) run(resolved);
+    }
   }
 
   function names() {
@@ -383,8 +499,6 @@ export function createPageJournal({ channel, key, context, base = null, onChange
       .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)
@@ -402,6 +516,7 @@ export function createPageJournal({ channel, key, context, base = null, onChange
       answer = channel.append({ key, context, update: bytes, origin, base: first ? bytesOfBase : null });
     } catch (_) {
       failure = "error";
+      settle(null);
       journal.onChange();
       return;
     }
@@ -412,6 +527,7 @@ export function createPageJournal({ channel, key, context, base = null, onChange
         inflight.delete(token);
         if (!receipt || receipt.ok !== true) {
           failure = receipt?.code ?? "error";
+          settle(null);
           journal.onChange();
           return;
         }
@@ -422,22 +538,29 @@ export function createPageJournal({ channel, key, context, base = null, onChange
           batchBytes += bytes.byteLength;
         }
         journal.onChange();
+        settle({ id: receipt.id, revision: receipt.revision });
         if (batches >= COMPACT_BATCHES || batchBytes >= COMPACT_BYTES) compact();
       },
       () => {
         inflight.delete(token);
         failure = "error";
+        settle(null);
         journal.onChange();
       },
     );
   }
 
+  function dispatch(context, bytes, origin) {
+    const first = carryBase;
+    carryBase = false;
+    write(context, bytes, origin, first);
+  }
+
   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));
+    if (resolved && !holding) dispatch(resolved, bytes, origin);
+    else waiting.push((context) => dispatch(context, bytes, origin));
   }
 
   return journal;
@@ -472,6 +595,90 @@ export function openPageJournal({ meta = null, service = null, base = null, onCh
   });
 }
 
+/**
+ * Where this tab's typing lives, and the wait that lets an exit leave edit.
+ *
+ * The answer is only ever as strong as the evidence behind it: a write whose transaction
+ * has not committed is Pending, committed records are Stored, a room's confirmation makes
+ * them Shared, and only a checkpoint that covers them makes the page Saved. The same
+ * handle is the exit's barrier for the journal: every append already handed over commits,
+ * and the store's own writes are down, before it answers. A journal that cannot write at
+ * all holds nothing and says so once, as Unavailable, so a person is never stranded in
+ * edit by a device that has stopped taking bytes.
+ *
+ * @param {Object} options
+ * @param {Object} options.journal - this session's page journal
+ * @param {?Object} [options.store] - the live page store, for its confirmations
+ * @param {Function} [options.reduce] - the precedence reducer, (facts) => state or null
+ * @param {Function} [options.onState] - (state) for every state the facts change to
+ * @param {Function} [options.onUnavailable] - (code) when the journal cannot write
+ * @returns {{checkpoint: Function, state: Function, dispose: Function}}
+ */
+export function watchJournal({ journal, store = null, reduce = () => null, onState = () => {}, onUnavailable = () => {} } = {}) {
+  if (!journal) return { checkpoint() {}, state: () => null, dispose() {} };
+  const seen = { acknowledged: false, checkpointed: false };
+  let last = null;
+  const state = () => {
+    const failure = journal.failure ?? null;
+    const records = journal.records().length;
+    return reduce({
+      unavailable: Boolean(failure),
+      pending: failure ? 0 : journal.pending(),
+      journaled: seen.acknowledged ? 0 : records,
+      acknowledged: seen.acknowledged ? records : 0,
+      checkpointed: seen.checkpointed && !records,
+    });
+  };
+  const publish = () => {
+    const next = state();
+    if (!next || next === last) return last;
+    last = next;
+    if (next === "unavailable") onUnavailable(journal.failure);
+    else onState(next);
+    return next;
+  };
+  // The binding owns this callback and hears every append and refusal through it.
+  const inner = journal.onChange;
+  journal.onChange = () => { inner?.(); publish(); };
+  // Work handed over now is work no room has seen and no checkpoint covers.
+  const offLocal = store?.onLocal?.(() => {
+    seen.acknowledged = false;
+    seen.checkpointed = false;
+    publish();
+  });
+  const offConfirm = store?.onConfirm?.(() => {
+    seen.acknowledged = true;
+    publish();
+  });
+  const blocked = () => Boolean(journal.failure);
+  const source = registerUnsavedState({
+    id: "page:journal",
+    isPending: () => !blocked() && journal.pending() > 0,
+    flush: async () => {
+      if (blocked()) return { ok: true };
+      while (!blocked() && journal.pending() > 0) {
+        if (!(await journal.next())) break;
+      }
+      await Promise.resolve(journal.channel?.flush?.()).catch(() => null);
+      return { ok: blocked() || journal.pending() === 0 };
+    },
+  });
+  publish();
+  return {
+    checkpoint() {
+      seen.checkpointed = true;
+      publish();
+    },
+    state,
+    dispose() {
+      journal.onChange = inner;
+      offLocal?.();
+      offConfirm?.();
+      source.dispose();
+    },
+  };
+}
+
 /**
  * Replay this page's journal once, after the authority snapshot is adopted.
  *
@@ -486,3 +693,339 @@ export async function replayInto({ journal, state, into } = {}) {
   if (!listed?.ok) return { replayed: [], review: [] };
   return replayJournals({ records: listed.records, current: { context, state }, into });
 }
+
+const posOf = (block) => (typeof block?.pos === "string" ? block.pos : "");
+const idsInOrder = (blocks) =>
+  Object.keys(blocks).sort((a, b) => {
+    const left = posOf(blocks[a]);
+    const right = posOf(blocks[b]);
+    if (left !== right) return left < right ? -1 : 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+
+// The text of one block, cells included: what a person reads in a review, and what an
+// insert-as-text offers back.
+function blockText(block) {
+  if (typeof block?.c === "string") return block.c;
+  if (!block?.rows) return "";
+  const parts = [];
+  for (const row of Object.values(block.rows)) {
+    for (const cell of Object.values(row?.cells ?? {})) {
+      const text = typeof cell === "string" ? cell : typeof cell?.c === "string" ? cell.c : "";
+      if (text) parts.push(text);
+    }
+  }
+  return parts.join(" ");
+}
+
+/**
+ * The page a set of records reconstructs, block by block.
+ *
+ * Records arrive in the store's shape — capsules with their batches — or as the updates
+ * a live journal holds, and both read back as one page: they share a lineage, and Yjs
+ * merges them by operation identity.
+ *
+ * @param {Array<Object>} [records]
+ * @returns {?Object} the block model, by block id, or null when it cannot be decoded
+ */
+function pageOf(records = []) {
+  const doc = new Y.Doc();
+  try {
+    for (const entry of capsulesOf(records)) {
+      let parts;
+      try {
+        parts = accumulateCapsule(entry);
+      } catch (_) {
+        continue;
+      }
+      for (const bytes of [parts.base, parts.dependencies, parts.owned]) if (bytes.length) Y.applyUpdateV2(doc, bytes, NET);
+    }
+    for (const record of records || []) {
+      const update = bytesOf(record?.update);
+      if (update && update.length) Y.applyUpdateV2(doc, update, NET);
+    }
+    return blocksFromYValue({ v: 1, g: 0, y: { seed: toBase64(Y.encodeStateAsUpdateV2(doc)) } });
+  } catch (_) {
+    return null;
+  } finally {
+    doc.destroy();
+  }
+}
+
+/**
+ * The readable page a capsule reconstructs: one line per block, in the page's own order.
+ *
+ * A capsule that cannot be decoded at all reads as no text rather than as an error: a
+ * review still says what it can, and nothing here decides whether it may be replayed.
+ *
+ * @param {{capsule: Object, batches?: Array<Object>}} options
+ * @returns {string}
+ */
+export function reconstructText({ capsule, batches = [] } = {}) {
+  let blocks;
+  try {
+    blocks = reconstructPage({ capsule, batches });
+  } catch (_) {
+    return "";
+  }
+  const lines = [];
+  for (const id of idsInOrder(blocks)) {
+    const text = blockText(blocks[id]);
+    if (text) lines.push(text);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The review rows a page draws for the journals it may not replay.
+ *
+ * Each row keeps the capsule it came from, so the person can read it, download it or
+ * copy its content, and nothing in a row is applied to the page.
+ *
+ * @param {Array<{capsule: Object, batches?: Array<Object>, code: string, message: string}>} [review]
+ * @returns {Array<Object>}
+ */
+export function describeReview(review = []) {
+  return (review || []).map((entry) => ({
+    id: entry?.capsule?.id,
+    revision: entry?.capsule?.revision ?? 0,
+    code: entry?.code ?? "invalid-capsule",
+    message: entry?.message ?? "This journal cannot be replayed",
+    text: reconstructText({ capsule: entry?.capsule, batches: entry?.batches ?? [] }),
+    capsule: entry?.capsule ?? null,
+    batches: entry?.batches ?? [],
+  }));
+}
+
+/**
+ * Whether a capsule's own blocks reconstruct to exactly this text.
+ *
+ * Composition end asks this before retiring a shadow: an update the journal holds is a
+ * transaction, and only a transaction carrying the same visible text means the typing
+ * reached the document.
+ *
+ * @param {Array<Object>} records - the journal's records
+ * @param {?string} blockId
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function coversText(records = [], blockId = null, text = "") {
+  const id = blockId == null ? "" : String(blockId);
+  const want = typeof text === "string" ? text : "";
+  if (!id || !want) return false;
+  const blocks = pageOf(records);
+  return Boolean(blocks && blocks[id] && blockText(blocks[id]) === want);
+}
+
+/** The channel that records where a reviewed capsule was copied to: one name, one version. */
+export const COPY_CHANNEL = "page.copy";
+export const COPY_VERSION = 1;
+
+// One channel per service, registered the first time something is actually copied.
+const copyChannels = new WeakMap();
+
+/**
+ * The copy-marker channel of one recovery service.
+ *
+ * @param {Object} service - `clay.recovery`
+ * @returns {?Object} the channel api
+ */
+export function pageCopyChannel(service) {
+  if (!service) return null;
+  const existing = copyChannels.get(service);
+  if (existing) return existing;
+  const channel = service.register({ channel: COPY_CHANNEL, version: COPY_VERSION });
+  copyChannels.set(service, channel);
+  return channel;
+}
+
+const copyKey = (source) => `copy:${source?.key ?? ""}:${identityKey(source?.id)}`;
+
+/**
+ * The transfer marker naming one capsule's copy, if this store has one.
+ *
+ * @param {{records?: Array<Object>, source: {key: string, id: *}}} options
+ * @returns {?{record: Object, source: Object, destination: Object}}
+ */
+export function markerFor({ records = [], source = null } = {}) {
+  if (!source || source.id === undefined) return null;
+  for (const record of records || []) {
+    const payload = record?.payload;
+    if (!payload?.source || !payload?.destination) continue;
+    if (payload.source.key !== source.key) continue;
+    if (identityKey(payload.source.id) !== identityKey(source.id)) continue;
+    return { record, source: payload.source, destination: payload.destination };
+  }
+  return null;
+}
+
+/**
+ * What one marker says about the copy it names.
+ *
+ * "copied" while the destination record is still in the journal: the copy is on this
+ * device and nothing has proved it saved. "covered" once the destination is gone from
+ * the journal, which only a checkpoint (or a dismissed destination) can do.
+ *
+ * @param {{marker: ?Object, records?: Array<Object>}} options
+ * @returns {string} "open", "copied" or "covered"
+ */
+export function copyState({ marker = null, records = [] } = {}) {
+  if (!marker?.destination) return "open";
+  const id = marker.destination.id;
+  const kept = (records || []).some((record) => record && identityKey(record.id) === identityKey(id));
+  return kept ? "copied" : "covered";
+}
+
+/**
+ * Insert a reviewed capsule's content as a copy, with fresh block ids.
+ *
+ * The content goes in through `insert`, which is the page's own document command and
+ * names the destination record it committed; nothing of the capsule's Yjs operations is
+ * merged into this page, so a changed lineage is never merged blindly. The source
+ * capsule is not retired here: it survives until a checkpoint covers the destination,
+ * and the marker written last says where that destination is. A copy already on this
+ * device is never made twice, and a refused or failed insert leaves the source exactly
+ * where it was.
+ *
+ * @param {Object} options
+ * @param {Object} options.channel - the `page.yjs` channel api
+ * @param {Object} options.copies - the copy-marker channel api
+ * @param {{key: string, id: *, revision: number}} options.source
+ * @param {Function} options.insert - () => Promise<{key: string, id: *, revision: number}>
+ * @returns {Promise<{ok: boolean, code?: string, destination?: Object, marker?: Object}>}
+ */
+export async function recoverAsCopy({ channel, copies, source, insert } = {}) {
+  if (!channel || !copies || !source || typeof insert !== "function") return { ok: false, code: "unavailable" };
+  let list;
+  let marks;
+  try {
+    [list, marks] = await Promise.all([channel.list(), copies.list()]);
+  } catch (_) {
+    return { ok: false, code: "unavailable" };
+  }
+  const marker = markerFor({ records: marks?.ok ? marks.records : [], source });
+  if (marker) {
+    const state = copyState({ marker, records: list?.ok ? list.records : [] });
+    if (state === "copied") return { ok: false, code: "already-copied", marker };
+    if (state === "covered") return { ok: false, code: "covered", marker };
+  }
+  let destination;
+  try {
+    destination = await insert();
+  } catch (_) {
+    return { ok: false, code: "insert-failed" };
+  }
+  if (!destination || destination.revision === undefined || destination.id === undefined) return { ok: false, code: "insert-failed" };
+  copies.stage({
+    key: copyKey(source),
+    kind: "text",
+    payload: {
+      source: { key: source.key ?? "", id: source.id, revision: source.revision ?? 0 },
+      destination: { key: destination.key ?? "", id: destination.id, revision: destination.revision },
+    },
+  });
+  const written = await copies.flush();
+  if (!written?.ok) return { ok: false, code: written?.code || "error", destination };
+  return { ok: true, destination };
+}
+
+/** The channel a composition's visible text is kept on while it is not a transaction. */
+export const IME_CHANNEL = "page.ime";
+export const IME_VERSION = 1;
+
+const IME_PREFIX = "composing:";
+
+const imeChannels = new WeakMap();
+
+/**
+ * The composition-shadow channel of one recovery service.
+ *
+ * @param {Object} service - `clay.recovery`
+ * @returns {?Object} the channel api
+ */
+export function pageImeChannel(service) {
+  if (!service) return null;
+  const existing = imeChannels.get(service);
+  if (existing) return existing;
+  const channel = service.register({ channel: IME_CHANNEL, version: IME_VERSION });
+  imeChannels.set(service, channel);
+  return channel;
+}
+
+/**
+ * The shadow one composing block's visible text is kept under.
+ *
+ * Composition is never forced into a transaction: while it is active the block's text is
+ * staged on a text channel, so a crash offers it as text. Composition end retires the
+ * shadow only when a journaled update carries the same text — `covered`, or answered
+ * from the records given — and anything else is kept and offered, because that typing
+ * never reached the document.
+ *
+ * @param {{channel: ?Object, key: string}} options
+ * @returns {?Object}
+ */
+export function openImeShadow({ channel = null, key = "" } = {}) {
+  if (!channel) return null;
+
+  async function drop(blockId) {
+    let listed;
+    try {
+      listed = await channel.list();
+    } catch (_) {
+      return 0;
+    }
+    if (!listed?.ok) return 0;
+    let retired = 0;
+    for (const record of listed.records) {
+      if (record?.payload?.blockId !== blockId) continue;
+      try {
+        const receipt = await channel.dismiss(record.id, { revision: record.revision });
+        if (receipt?.ok) retired += 1;
+      } catch (_) {}
+    }
+    return retired;
+  }
+
+  return {
+    key,
+    channel,
+    keep({ blockId = null, text = "" } = {}) {
+      const id = blockId == null ? "" : String(blockId);
+      const value = typeof text === "string" ? text : "";
+      if (!id || !value) return null;
+      return channel.stage({ key: `${IME_PREFIX}${id}`, kind: "text", payload: { blockId: id, text: value } });
+    },
+    async clear({ blockId = null, text = "", covered = null, records = [] } = {}) {
+      const id = blockId == null ? "" : String(blockId);
+      if (!id) return { ok: false, code: "invalid" };
+      const carried = typeof covered === "boolean" ? covered : coversText(records, id, text);
+      if (!carried) return { ok: false, code: "not-covered" };
+      const retired = await drop(id);
+      return retired ? { ok: true, retired } : { ok: false, code: "not-covered" };
+    },
+    async list() {
+      return channel.list();
+    },
+    dispose() {
+      return channel.flush();
+    },
+  };
+}
+
+/**
+ * The composition shadows a page's store holds as reviewable text.
+ *
+ * @param {Array<Object>} [records] - the composition channel's records
+ * @returns {Array<{id: *, revision: number, blockId: string, text: string}>}
+ */
+export function imeEntries(records = []) {
+  const out = [];
+  for (const record of records || []) {
+    if (!record || record.supported === false) continue;
+    const payload = record.payload;
+    if (!payload || typeof payload.text !== "string" || !payload.text) continue;
+    if (typeof payload.blockId !== "string" || !payload.blockId) continue;
+    out.push({ id: record.id, revision: record.revision, blockId: payload.blockId, text: payload.text });
+  }
+  return out;
+}