@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/editor/page/autosave.mjs

@@ -0,0 +1,977 @@
+import { TEXTS_KEPT, createCommits, nodeHTML, writtenHTML } from "./commit.mjs";
+import { randomRequestId } from "../../shared/ids.mjs";
+import { viewKey } from "../../shared/session.mjs";
+import { postJson } from "./post.mjs";
+import { unpack } from "./sync-state.mjs";
+
+// Autosave (docs/editor.md, "Autosave"): the page is always editing and commits what changed
+// (commit.mjs) by itself. A change waits for a pause in typing (IDLE), at most LONGEST while the
+// reader keeps typing; a discrete operation (a block deleted, moved, split or converted, a
+// formatting step, undo) and the end of an input method's composition commit at once, and Ctrl+S
+// commits whatever waits. One commit is on its way at a time; what changes meanwhile goes with the
+// next. A commit that does not get through is tried again, later and later, as it was: the file
+// may have taken it (only the answer was lost), and one built anew from the page would name what
+// it wrote as still to be written (the reader's later words lost, or a conflict with them).
+//
+// Nothing is lost when the page goes away before a commit is answered: what is not in the file is
+// kept in localStorage (the crash buffer): the commit whose answer never came, the commit that
+// would carry everything else (what is held for the reader too), and the text of blocks no commit
+// can carry yet; with a commit whose answer is not known, what the page knows and the page itself
+// (stateKey), so that the next page takes up exactly where this one was. A page opening on the report sends what a closed or crashed page left there
+// (recover), and lists what the file did not take (lostKey) until the reader has dealt with it.
+// Commits name everything by identity and the blocks made on the page by ids the page proposes,
+// so sending one again, from the buffer or after a lost answer, writes it once. Closing the page
+// tries a last commit (keepalive) when none is on its way, but that is only a try; the buffer is
+// what counts.
+//
+// The file changing by someone else (the Agent, another tab) is not a question for the reader:
+// commits merge with it on the server, and once nothing is left that the file does not have
+// (settled) and the reader pauses, the page reloads to show it, where the reader was
+// (reloadView). Only when that write put texts the reader committed back as they were (an Agent
+// writing the whole file from what it read earlier) does the page ask first: it keeps the texts it
+// committed (commits.committed(), and those of its earlier loads in sessionStorage), the blocks it
+// made and moved this load (commits.placedUnits()) and what its components wrote (commits.written(),
+// those of earlier loads too), and the server says which the file now has as before (POST
+// /__gallery/edit/reverted): a text as it was, a block it made gone, a block it moved back in the unit
+// it was in, a part as before a write of the page's.
+
+const IDLE = 1600;
+const LONGEST = 8000;
+const RETRY = [1000, 2000, 5000, 10000, 30000];
+const QUIET = 1500; // how long the reader has changed nothing before the page reloads by itself
+const STORE_EVERY = 1000; // the crash buffer while typing, at most this often
+const JOURNAL_FOR = 60 * 60 * 1000; // how long a committed text is checked for being put back
+const OWN_FOR = 5000; // how long the live-reload channel may still announce a version this page wrote
+
+// A committed text as the revert check names it, whichever load named it: the report's title, a block of
+// a unit by the unit's id (or what named the unit, with none) and its place in it, any other by what
+// names it but the words it had.
+const sameText = (block) => JSON.stringify(block?.title ? "title" : block?.unit ? [block.unit.id ?? block.unit.blockId ?? [block.unit.key, block.unit.open], block.self ? true : block.path ?? null] : { ...block, before: undefined });
+
+/**
+ * map: the page's map (slug, version, token); commits: createCommits(); blocked(): commits wait
+ * (an input method is composing); changedAt(): when the reader last changed anything; holding(asked):
+ * the reader is in the middle of something (a press, a drag), so the page does not reload by
+ * itself (`asked`: the page asked to be shown again itself, reloadSoon, where someone else's write
+ * alone came before); refresh(): the state changed; applied(result, receipt): a commit was taken in;
+ * failed(reason, message): a commit that cannot go through as it is (not a lost connection);
+ * warn("storage"): the crash buffer could not be written; storage: localStorage
+ * (get/set/remove/keys); tab(): this tab's id (a duplicated tab takes a new one); notice(): what the
+ * page says after it reloads by itself (a merge it just made), or null; session: sessionStorage
+ * (get/set/remove); reverted(entries): texts, blocks and components' writes of the reader's that
+ * someone else's write put back, for the reader to decide on (decide) before the page shows that
+ * write (a component's with `written`: the parts, by name, and the hashes the file holds of them);
+ * before(): called right
+ * before a commit goes, a promise it waits for (or null): what goes with the edit elsewhere is told
+ * first (where the words of the reader's 批注 went: annotate/ sync).
+ */
+export function createAutosave({ map, commits, blocked, changedAt, holding = () => false, refresh, applied, failed, warn = () => {}, storage, tab, notice = () => null, session = null, reverted = () => {}, before = () => null }) {
+  let known = map.version; // the file's version as the page last knew it
+  // Versions this page's commits wrote (and the one it opened on), in order, and when: the
+  // live-reload channel announces them too, a little later, in the order they were written. Only
+  // for a while, and only in that order: a version is a text, not a write, and someone else writing
+  // the file back to one of them (later, or after a newer one of the page's was announced) is a
+  // write of theirs.
+  const own = [{ version: map.version, at: Date.now() }];
+  let heardUpTo = 0; // the last of them announced so far (its place in own)
+  let flight = null; // the commit on its way: { request, pending }
+  let parked = null; // a commit sent whose outcome is not known (no answer, busy): { request, pending }, sent again as it is
+  let buffer = null; // the request the crash buffer holds now (leave() sends that very one)
+  let chain = Promise.resolve(); // the page's writes, one after another (send)
+  let again = false;
+  let timer = 0;
+  let first = 0; // when the oldest change still waiting was made
+  let failures = 0;
+  let retryAt = 0;
+  let offline = false;
+  let stopped = null; // why commits stopped (a refusal that trying again will not change)
+  let foreign = false; // someone else wrote the file since the page showed it
+  let asked = false; // the page asked to be shown again itself (reloadSoon)
+  let reloading = false;
+  let closed = false; // the page is done with (close)
+  let leaving = false; // the page goes away (leave), until it is shown again from the back/forward cache
+  let storedAt = 0;
+  let flightAt = 0; // when the commit on its way went
+  let buffered = false; // the crash buffer holds something
+  let unstored = false; // the crash buffer could not be written
+  let storedFrom = null; // what the page held (collect()'s result) when the buffer was last written with nothing on its way; null: write it anew
+  const events = []; // [version, when]: what the live-reload channel announced while a commit was on its way
+  // Texts committed by this page's earlier loads (journalKey), still checked for a while, each under a
+  // key of its own (`c<n>`: an earlier load's keys name its blocks, as this one's name others); what
+  // their components wrote is the commits' own again (carry), by instance.
+  const journalKey = `gallery-edit:${map.slug}:journal`;
+  let carried = [];
+  try {
+    const kept = (JSON.parse(session?.get(journalKey) ?? "[]") ?? []).filter((entry) => entry && Date.now() - entry.time < JOURNAL_FOR);
+    carried = kept.filter((entry) => entry.instance === undefined).map((entry, index) => ({ ...entry, key: `c${index}` }));
+    commits.carry(kept.filter((entry) => entry.instance !== undefined).map(({ instance, parts, time }) => ({ id: instance, parts, time })));
+  } catch {}
+  session?.remove(journalKey);
+  const reverts = new Map(); // key -> entry: put back by someone else, waiting for the reader
+  let checking = false;
+  const waiters = [];
+  const bufferKey = () => pendingKey(map.slug, tab());
+  const keptKey = () => stateKey(map.slug, tab());
+
+  // How many changes wait, and how many blocks no commit can carry yet, as last counted
+  // (collectEdits is not free): on each change, after each commit. `counted`: what they were
+  // counted from (collect()'s result), to know whether they still hold (commits.current).
+  let count = 0;
+  let drafts = 0;
+  let counted = null;
+  const recount = (collected = commits.collect()) => {
+    ({ waiting: count, drafts } = commits.counts(collected));
+    counted = collected;
+  };
+  const waiting = () => count;
+
+  // ---------- scheduling ----------
+  function arm(due) {
+    clearTimeout(timer);
+    timer = setTimeout(run, Math.max(0, due - Date.now(), retryAt - Date.now()));
+  }
+
+  /**
+   * A change was made (`collected`: collectEdits' result, when the caller has it): commit after a
+   * pause, or at once (`now`) for a discrete operation.
+   */
+  function changed(now = false, collected = undefined) {
+    if (closed) return;
+    recount(collected);
+    if (stopped || reloading) return;
+    if (count === 0 && !now) {
+      store({ collected: counted }); // nothing waits (typed and deleted again): nothing to keep but what is on its way
+      return;
+    }
+    const at = Date.now();
+    if (!first) first = at;
+    arm(now ? at : Math.min(at + IDLE, first + LONGEST));
+    if (!buffered || at - storedAt > STORE_EVERY) store({ collected: counted }); // the first change at once, then now and then
+  }
+
+  /** Commit whatever waits, now; resolves with "saved", "nothing", "offline" or "error". */
+  function flush() {
+    return new Promise((resolve) => {
+      waiters.push(resolve);
+      retryAt = 0;
+      if (flight) again = true;
+      else {
+        clearTimeout(timer);
+        run();
+      }
+    });
+  }
+
+  const settle = (outcome) => waiters.splice(0).forEach((resolve) => resolve(outcome));
+
+  // A commit that throws on the page (a bug) stops autosave and says so, rather than leaving
+  // everything waiting without a word.
+  async function run() {
+    try {
+      await commit();
+    } catch (error) {
+      flight = null;
+      stopped = "error";
+      failed("error", String(error?.message ?? error));
+      refresh();
+      settle("error");
+      throw error;
+    }
+  }
+
+  async function commit() {
+    timer = 0;
+    if (closed) return;
+    if (flight) {
+      again = true;
+      return;
+    }
+    if (stopped || reloading) return settle("error");
+    if (blocked()) return arm(Date.now() + 300); // the composition's end is a change: the commit goes after the pause
+    // A commit whose outcome is not known goes again as it went, before anything newer is built.
+    // Otherwise it is built from what the page holds now, which the count and the crash buffer read
+    // too (one collect for the three); nothing is built when nothing waited as last counted and
+    // nothing changed since (commits.current: a flush with nothing to save, as when the page is left).
+    const idle = !parked && count === 0 && commits.current(counted);
+    const collected = parked ? undefined : idle ? counted : commits.collect();
+    const built = parked ?? (idle ? null : commits.build({ collected }));
+    first = 0;
+    if (!built) {
+      recount(collected);
+      store({ collected });
+      refresh();
+      settle(offline ? "offline" : "nothing");
+      maybeReload();
+      return;
+    }
+    flight = parked ?? { request: { ...built.request, known, request: randomRequestId() }, pending: built.pending };
+    flightAt = Date.now();
+    parked = null;
+    store({ collected });
+    refresh();
+    let receipt;
+    try {
+      await before();
+    } catch {}
+    try {
+      receipt = await send(flight.request);
+    } catch {
+      receipt = { ok: false, reason: "offline" };
+    }
+    const sent = flight;
+    flight = null;
+    if (closed) return; // the page is gone: nothing to take in
+    let after; // with the answer taken in: what the page holds now (anew: the page changed meanwhile), counted and kept
+    if (receipt.ok) {
+      failures = 0;
+      retryAt = 0;
+      offline = false;
+      known = receipt.version;
+      if (receipt.wrote !== false) own.push({ version: receipt.version, at: Date.now() }); // one that changed nothing wrote no version
+      if (receipt.foreign) foreign = true;
+      applied(commits.apply(sent.pending, receipt, { alone: !foreign }), receipt);
+      after = commits.collect();
+      recount(after);
+      for (const [version, at] of events.splice(0)) heard(version, false, at);
+      // Someone else wrote the file before this commit: what that put back is asked now, as when
+      // the live-reload channel tells of a write (heard).
+      if (receipt.foreign) checkReverted().then((answered) => answered !== null && maybeReload());
+    } else if (receipt.reason === "offline" || receipt.reason === "busy" || receipt.reason === "server") {
+      parked = sent;
+      offline = receipt.reason === "offline";
+      failures += 1;
+      retryAt = Date.now() + RETRY[Math.min(failures, RETRY.length) - 1];
+    } else {
+      parked = sent; // kept in the crash buffer: a page opening on the report sends it
+      stopped = receipt.reason;
+      failed(receipt.reason, receipt.message);
+    }
+    store({ collected: after });
+    refresh();
+    if (stopped) return settle("error");
+    if (!receipt.ok) {
+      settle(offline ? "offline" : "busy");
+      arm(retryAt);
+      return;
+    }
+    if (again || waiters.length > 0) {
+      again = false;
+      if (waiting() > 0) return commit();
+    }
+    if (waiting() > 0) arm(first ? Math.min(first + LONGEST, Date.now() + IDLE) : Date.now() + IDLE);
+    else settle("saved");
+    maybeReload();
+  }
+
+  // Every write of the page goes through here, one at a time: commits, and the reader's decision
+  // on a text someone else put back.
+  function send(request) {
+    const run = chain.then(() => postCommit(map, request));
+    chain = run.catch(() => {});
+    return run;
+  }
+
+  // ---------- the crash buffer ----------
+  // What the file may not have: the commit on its way or whose answer never came (`sent`), the
+  // commit of everything that differs from what the last answer left (held conflicts and blocks the
+  // file refused too: sent again, what the file does not take is listed for the reader), and the
+  // texts no commit carries (`keep`: blocks no commit can carry yet, texts someone else's write put
+  // back). Nothing at all: no buffer. While a commit's answer is not known (sent again later, on its
+  // way for a while, or the page going away: `leaving`), what the page knows and the page itself go
+  // along too (stateKey). From leave() on the page is going away, and so is every store after it as
+  // it goes (visibilitychange's flush, sending again the commit whose answer never came). `collected`:
+  // collect()'s result, when the caller has it from the same task.
+  //
+  // With nothing on its way, the buffer is written from the page and what the commits know of it
+  // (and what someone else put back): when none of these changed since it was last written
+  // (commits.current), it holds this already and is left as it is. A page that is left stores three
+  // times in a row (prepare-close; pagehide; visibilitychange's flush), each a pass over every block.
+  function store({ collected = undefined } = {}) {
+    if (closed) return;
+    storedAt = Date.now();
+    const sent = flight?.request ?? parked?.request ?? null;
+    if (!sent && !unstored && storedFrom !== null && commits.current(storedFrom)) return;
+    const from = collected ?? commits.collect();
+    const { request: built, drafts: texts, typed = [] } = commits.buffer(from);
+    storedFrom = sent ? null : from;
+    // Kept with the buffer as it is now or not at all: taken up as it was earlier, it would miss
+    // what the page did since (the buffer's commit has it).
+    let kept = false;
+    if (sent && (parked || leaving || (flight && Date.now() - flightAt > STORE_EVERY))) {
+      try {
+        kept = storage.set(keptKey(), JSON.stringify({ sent: sent.request, foreign, ...commits.keep((flight ?? parked).pending) })) !== false;
+      } catch {}
+    }
+    if (!kept) storage.remove(keptKey()); // the next page goes on from the buffer (rebase)
+    const request = built && { ...built, known: null, request: randomRequestId() };
+    buffer = request;
+    // Words typed in a block a commit makes have no commit to go with: listed, unless one is on its
+    // way, when the page's texts below say what the next page does not show of them.
+    const keep = [...[...texts, ...(sent ? [] : typed)].map((text) => ({ why: "draft", text })), ...[...reverts.values()].map((entry) => ({ why: "reverted", html: entry.mine, ...writtenIn(entry.id, entry.data) }))];
+    buffered = Boolean(sent || request || keep.length > 0);
+    if (!buffered) {
+      storage.remove(bufferKey());
+      unstored = false;
+      return;
+    }
+    // With a commit whose answer is not known, what follows it is rebuilt on its answer by the next
+    // page (recover: rebase), as well as it can be: the texts of the page's blocks go along, and
+    // what the page then opened on the file does not show is listed (checkLeft).
+    const page = sent ? commits.texts() : undefined;
+    const stored = storage.set(bufferKey(), JSON.stringify({
+      v: 2, time: Date.now(), sent: sent && { ...sent, known: null }, request, keep, ...(page ? { page } : {}),
+    })) !== false;
+    if (!stored && !unstored) warn("storage");
+    unstored = !stored;
+  }
+
+  /**
+   * The page goes away: keep what is not in the file, and what it committed for the next load to ask
+   * of (keepJournal), and try to commit it (the answer is never read): the very request the buffer
+   * holds, so that the next page sending it again gets its answer (the commit is not applied twice).
+   */
+  function leave() {
+    // Closed: the page that shows the report now (a workbench's next one) has the buffer, its own.
+    if (closed) return;
+    leaving = true;
+    store();
+    keepJournal();
+    if (flight || parked || stopped || waiting() === 0 || !buffer) return; // what is on its way is in the buffer
+    postCommit(map, buffer, { keepalive: true }).catch(() => {});
+  }
+
+  // ---------- someone else's changes ----------
+  /**
+   * The live-reload channel says the file is now `version` (`anyway`: it changed, whatever the
+   * version, as when this page sent what a closed page left), `at` when it said so.
+   */
+  function heard(version, anyway = false, at = Date.now()) {
+    if (closed) return;
+    // It may be the commit on its way, or one whose answer was lost: known once that one is answered
+    // (as of when it was announced).
+    if ((flight || parked) && !anyway) return void events.push([version, at]);
+    if (!anyway) {
+      if (!version) return;
+      // The next of the page's own writes to be announced (one before the last announced was
+      // written back by someone else).
+      const index = own.findIndex((write, place) => place >= heardUpTo && write.version === version);
+      if (index >= 0 && (version === known || at - own[index].at < OWN_FOR)) {
+        heardUpTo = index;
+        return;
+      }
+    }
+    foreign = true;
+    refresh();
+    // What that write put back of the page's is asked at once, whatever else waits: the reader
+    // hears of it now, not once all else is settled.
+    checkReverted().then((answered) => answered !== null && maybeReload());
+    maybeReload();
+  }
+
+  // Whether everything the page shows is in the file: nothing waits, nothing is on its way or
+  // waits to be sent again, nothing is held for the reader, no block waits for the reader to finish
+  // it (a title still empty). Only then may the page reload by itself.
+  const settled = () => !flight && !parked && waiting() === 0 && drafts === 0 && commits.issues.size === 0 && reverts.size === 0;
+
+  // What someone else's write put back of what the page committed (POST /__gallery/edit/reverted):
+  // texts as they were before, blocks it made taken out, blocks it moved back where they were, parts
+  // components wrote as they were before. Each one is held for the reader (reverted) until decided.
+  // Resolves with whether the server answered; null while another check runs (that one asks again
+  // when it is done).
+  let recheck = false;
+  async function checkReverted() {
+    if (checking) {
+      recheck = true;
+      return null;
+    }
+    const texts = journal();
+    const units = commits.placedUnits();
+    const instances = commits.written();
+    if (texts.length === 0 && units.length === 0 && instances.length === 0) return true;
+    checking = true;
+    let answer = null;
+    try {
+      const response = await postJson("/__gallery/edit/reverted", map.token, { slug: map.slug, opening: map.version, texts: texts.map(({ key, block, original, earlier }) => ({ key, block, original, ...(earlier ? { earlier } : {}) })), units, instances: instances.map(({ key, id, parts }) => ({ key, id, parts })), pageIds: commits.pageIds() });
+      answer = await response.json();
+    } catch {}
+    checking = false;
+    if (closed) return false;
+    const back = answer?.ok ? [
+      ...answer.reverted.map(({ key, theirs }) => ({ ...texts.find((entry) => entry.key === key), theirs })).filter((entry) => entry.key),
+      // A block put back: by its unit, with what it holds (the reader's words, to copy).
+      ...(answer.units ?? []).filter(({ key }) => units.some((unit) => unit.key === key)).map(({ key, gone }) => ({ key: `p${key}`, unit: key, gone: Boolean(gone), mine: commits.unitText(key) })),
+      // Parts a component wrote put back: by its unit, with the hashes the file holds of them (`written`)
+      // and what the page holds of them (`data`, the reader's, kept with the crash buffer); none the page
+      // holds as the file does, however the file spells it (heldOtherwise).
+      ...(answer.parts ?? []).map(({ key, parts, markup }) => {
+        const entry = instances.find((instance) => instance.key === key);
+        return { entry, parts: entry && parts && typeof parts === "object" ? commits.heldOtherwise(entry.key, parts, markup) : {} };
+      }).filter(({ entry, parts }) => entry && Object.keys(parts).length > 0)
+        .map(({ entry, parts }) => {
+          const data = commits.dataOfUnit(entry.key, Object.keys(parts)) ?? {};
+          return { key: `s${entry.key}`, unit: entry.key, id: entry.id, written: parts, data, mine: Object.values(data).join("\n") };
+        }),
+    ].filter((entry) => !reverts.has(entry.key)) : [];
+    if (back.length > 0) {
+      for (const entry of back) reverts.set(entry.key, entry);
+      storedFrom = null; // the buffer keeps their words too
+      store();
+      refresh();
+      reverted(back);
+    }
+    if (recheck) {
+      recheck = false;
+      return checkReverted();
+    }
+    return Boolean(answer?.ok);
+  }
+
+  // Once everything is in the file and the reader pauses, show the file as it is, where the reader
+  // was; unless it put back texts or blocks the reader committed (checkReverted, asked once more
+  // right before). What is not in the file yet is settled by a commit or by the reader (each ends by
+  // asking again), so only a pause is waited for here.
+  let reloadTimer = 0;
+  async function maybeReload() {
+    clearTimeout(reloadTimer);
+    if (!foreign || reloading || checking || stopped || closed || !settled()) return;
+    const quiet = Date.now() - changedAt();
+    if (blocked() || holding(asked) || quiet < QUIET) {
+      reloadTimer = setTimeout(maybeReload, Math.max(300, QUIET - quiet));
+      return;
+    }
+    const answered = await checkReverted();
+    if (answered === null) return; // another check runs, and asks again when it is done
+    if (!answered) return void (reloadTimer = setTimeout(maybeReload, 2000));
+    // Anything may have happened meanwhile (a change, a commit and its conflicts, something put back): ask again.
+    if (!settled() || blocked() || holding(asked) || Date.now() - changedAt() < QUIET) return void (reloadTimer = setTimeout(maybeReload, 300));
+    reloading = true;
+    storage.remove(bufferKey());
+    storage.remove(keptKey());
+    storedFrom = null; // written anew if anything stores after all
+    keepJournal();
+    refresh();
+    reloadView(map.slug, null, notice());
+  }
+
+  // The texts committed, this load's and earlier ones', one of each block (sameText): what an earlier
+  // load committed of a block a later one committed too is where that text started, and what it was
+  // between (two of one block are no one question: the server's answer would name neither); back as it
+  // was first, it is asked of what it was between.
+  const journal = () => {
+    const now = commits.committed().map((entry) => ({ ...entry, time: Date.now() }));
+    const texts = new Map();
+    for (const entry of [...carried, ...now]) {
+      const name = sameText(entry.block);
+      const was = texts.get(name);
+      if (!was) {
+        texts.set(name, entry);
+        continue;
+      }
+      const earlier = [...new Set([...(was.earlier ?? []), was.mine, entry.original, ...(entry.earlier ?? [])])].filter((text) => text !== entry.mine && text !== was.original).slice(-TEXTS_KEPT);
+      const joined = { ...entry, original: was.original, earlier };
+      if (earlier.length === 0) delete joined.earlier;
+      if (entry.mine === was.original && earlier.length === 0) texts.delete(name);
+      else texts.set(name, joined);
+    }
+    return [...texts.values()];
+  };
+
+  // What the page committed (journal()) and what its components wrote (commits.written()), kept for the
+  // next load of the page in this tab, which asks of them as its own: when it is shown again, and when
+  // the page goes away (a reload of the reader's, another document opened in a workbench).
+  function keepJournal() {
+    const kept = [
+      ...journal().map((entry) => ({ ...entry, time: entry.time ?? Date.now() })),
+      ...commits.written().map(({ id, parts, time }) => ({ instance: id, parts, time })),
+    ];
+    if (kept.length > 0) session?.set(journalKey, JSON.stringify(kept));
+    else session?.remove(journalKey);
+  }
+
+  /**
+   * The reader decided on a text, block or component's write someone else put back: `mine` commits it
+   * again over theirs, otherwise theirs stays. Once every one is decided, the page shows the file.
+   */
+  async function decide(key, mine) {
+    const entry = reverts.get(key);
+    if (!entry) return;
+    if (entry.unit !== undefined) {
+      // A block put back: kept (made again, or moved again where the page has it), or the file's. Parts a
+      // component wrote: written again over the file's (its hashes of them), or the file's.
+      if (entry.written) commits.rewrite(entry.unit, entry.written, mine);
+      else commits.putBack(entry.unit, { gone: entry.gone, mine });
+      reverts.delete(key);
+      storedFrom = null;
+      if (mine) changed(true);
+      store();
+      refresh();
+      if (reverts.size === 0) maybeReload();
+      return true;
+    }
+    if (mine) {
+      const texts = [{ key, block: { ...entry.block, before: entry.theirs }, parts: [{ keep: true, html: entry.mine }] }];
+      const receipt = await send({ opening: map.version, known: null, texts, units: [], touch: [], request: randomRequestId() }).catch(() => null);
+      if (!receipt?.ok || receipt.texts?.[0]?.status === "conflict") return false;
+    }
+    reverts.delete(key);
+    storedFrom = null;
+    carried = carried.filter((other) => sameText(other.block) !== sameText(entry.block));
+    if (!mine) commits.unjournal(key);
+    store();
+    refresh();
+    if (reverts.size === 0) maybeReload();
+    return true;
+  }
+
+  /** Show the file as it is once nothing waits (the reader gave a change up for the file's, or what the page is made of changed). */
+  function reloadSoon() {
+    foreign = true;
+    asked = true;
+    maybeReload();
+  }
+
+  addEventListener("online", () => {
+    retryAt = 0;
+    if ((count > 0 || parked) && !flight) arm(Date.now());
+  });
+  addEventListener("pageshow", (event) => {
+    if (event.persisted) leaving = false;
+  });
+
+  /**
+   * The page is done with (it goes away for good, or a test lets it go): nothing more is committed,
+   * stored, tried again or reloaded, and an answer still on its way is not taken in.
+   */
+  function close() {
+    closed = true;
+    clearTimeout(timer);
+    clearTimeout(reloadTimer);
+  }
+
+  return {
+    changed,
+    flush,
+    leave,
+    heard,
+    store,
+    decide,
+    reloadSoon,
+    close,
+    get state() {
+      return { waiting: waiting(), syncing: Boolean(flight), offline, stopped, foreign, reloading, held: commits.issues.size + reverts.size, drafts, unstored };
+    },
+  };
+}
+
+// A commit sent: the server's answer, or { ok: false, reason: "server" } when it failed or answered
+// no JSON (a lost connection rejects: the caller reads that as offline).
+async function postCommit(map, request, { keepalive = false } = {}) {
+  const response = await postJson("/__gallery/edit/commit", map.token, { slug: map.slug, ...request }, { keepalive });
+  if (response.status >= 500) return { ok: false, reason: "server" };
+  return response.json().catch(() => ({ ok: false, reason: "server" }));
+}
+
+// ---------- reloading where the reader was ----------
+
+
+// What a tab keeps in storage, by kind: gallery-edit:<slug>:<kind>:<tab>.
+const tabKey = (kind, slug, tab) => `gallery-edit:${slug}:${kind}:${tab}`;
+
+/** Where a tab keeps what waits to be saved (the crash buffer). */
+export const pendingKey = (slug, tab) => tabKey("pending", slug, tab);
+
+/** Where it keeps, with a commit whose answer is not known, what the page knows and the page (createCommits' keep). */
+export const stateKey = (slug, tab) => tabKey("state", slug, tab);
+const PENDING_KEY = /^gallery-edit:([^:]+):pending:(.+)$/;
+/** The state key of the tab a crash buffer's key (a pendingKey) belongs to. */
+const stateKeyOf = (key) => {
+  const [, slug, tab] = PENDING_KEY.exec(key);
+  return stateKey(slug, tab);
+};
+
+/**
+ * Where a page keeps what it could not put back into the file (recover): the reader's words, listed
+ * until the reader says they are dealt with. [{ why, html | text, time }]
+ */
+export const lostKey = (slug) => `gallery-edit:${slug}:lost`;
+
+/**
+ * Where a page keeps the texts of the blocks a page it recovered showed (one with a commit whose
+ * answer it never learned): the page that opens next lists those it does not show (checkLeft).
+ */
+const checkKey = (slug) => `gallery-edit:${slug}:check`;
+
+function keepCheck(storage, slug, texts) {
+  let list = [];
+  try {
+    list = JSON.parse(storage.get(checkKey(slug)) ?? "[]") ?? [];
+  } catch {}
+  return storage.set(checkKey(slug), JSON.stringify([...list, ...texts].slice(-2000))) !== false;
+}
+
+/**
+ * Once recover() is done and the page shows the file: the texts a page it recovered showed that this
+ * one does not (`shown`: its blocks' texts) are listed under lostKey, whatever the rebuilt commits
+ * missed (a safety net: no word goes without a trace). Returns how many.
+ */
+export function checkLeft(storage, slug, shown) {
+  let texts = [];
+  try {
+    texts = JSON.parse(storage.get(checkKey(slug)) ?? "[]") ?? [];
+  } catch {}
+  if (texts.length === 0) return 0;
+  const words = (text) => String(text).replace(/\s+/g, " ").trim();
+  // What the page shows, and what is listed already (a block not finished, kept as a draft).
+  const listed = readLost(storage, slug).map((item) => item.text ?? String(item.html ?? "").replace(/<[^>]*>/g, ""));
+  const here = words([...shown, ...listed].join("\n"));
+  const missing = [...new Set(texts.map(words))].filter((text) => text && !here.includes(text));
+  if (missing.length > 0 && !keepLost(storage, slug, missing.map((text) => ({ why: "rebase", text })))) return 0;
+  storage.remove(checkKey(slug));
+  return missing.length;
+}
+
+/** What lostKey holds. */
+export function readLost(storage, slug) {
+  try {
+    const list = JSON.parse(storage.get(lostKey(slug)) ?? "[]");
+    return Array.isArray(list) ? list : [];
+  } catch {
+    return [];
+  }
+}
+
+// Add to what lostKey holds (the newest 100); false when it could not be written.
+function keepLost(storage, slug, items) {
+  const time = Date.now();
+  return storage.set(lostKey(slug), JSON.stringify([...readLost(storage, slug), ...items.map((item) => ({ ...item, time }))].slice(-100))) !== false;
+}
+
+/**
+ * Reload the page to show the file as it is now, keeping where the reader was (`view`, or now):
+ * the scroll position, the block the caret was in (by its data-block-id) with the caret's offset in
+ * its text and what the editor keeps besides (keepWith); `notice` is said once the page is back.
+ */
+export function reloadView(slug, view = null, notice = null) {
+  keep(slug, { ...(view ?? viewNow()), notice });
+}
+
+/** Where the reader is now, as reloadView keeps it: { x, y, unit, self, offset, and what keepWith gives }. */
+export function viewNow() {
+  const selection = getSelection();
+  const anchor = selection.rangeCount ? selection.anchorNode : null;
+  const host = (anchor?.nodeType === 1 ? anchor : anchor?.parentElement)?.closest?.("[contenteditable='true']") ?? null; // an empty block's caret stands in the block itself
+  const unit = host?.closest("[data-block-id]");
+  let offset = null;
+  if (host && unit) {
+    const head = document.createRange();
+    head.setStart(host, 0);
+    head.setEnd(selection.anchorNode, selection.anchorOffset);
+    offset = head.toString().length;
+  }
+  return { x: scrollX, y: scrollY, unit: unit?.getAttribute("data-block-id") ?? null, self: unit === host, offset, ...kept() };
+}
+
+let kept = () => ({});
+/** What a page shown again takes over besides where the reader was: `read()`, its fields (the detail cards open). */
+export function keepWith(read) {
+  kept = read;
+}
+
+let reloader = () => location.reload();
+/**
+ * How the page is shown again: by default it reloads; in a workbench, the workbench loads the
+ * report out of sight and puts it in this page's place once it is drawn (editor.mjs, session.mjs).
+ */
+export function setReloader(reload) {
+  reloader = reload;
+}
+
+function keep(slug, view) {
+  try {
+    sessionStorage.setItem(viewKey(slug), JSON.stringify(view));
+  } catch {}
+  reloader();
+}
+
+/** Where the reader was before reloadView: { x, y, unit, self, offset, notice, and what keepWith gave } once, or null. */
+export function takeView(slug) {
+  try {
+    const view = JSON.parse(sessionStorage.getItem(viewKey(slug)) ?? "null");
+    sessionStorage.removeItem(viewKey(slug));
+    return view && typeof view.y === "number" ? view : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------- recovering what a page left ----------
+
+const partsHTML = (text) => (text?.parts ?? []).map((part) => part.html).filter(Boolean).join("\n");
+// A commit sent again is answered once it is known to have gone in or not: not when the server
+// could not be reached, was busy or failed (tried again by the next page). A request it can never
+// take (`body`) is answered too: what it carried is listed for the reader.
+const answered = (receipt) => receipt.ok || receipt.reason === "body";
+// Whether the file gave up something of a commit for its package's manifest having changed: nothing
+// for the reader to decide, and nothing to list (a page goes by the manifest there is now).
+const outdatedIn = (receipt) => Boolean(receipt?.units?.some((answer) => answer.status === "conflict" && answer.reason === "definition"));
+// A node as compared between two commits (their keys differ).
+const shape = (node) => JSON.stringify(node, (name, value) => (name === "key" ? undefined : value));
+
+// What of `request` the file did not take (answered `receipt`): the reader's words, to list.
+function refusedOf(request, receipt) {
+  if (!receipt.ok) {
+    return [...(request.texts ?? []).map((text) => ({ why: "refused", html: partsHTML(text) })), ...(request.units ?? []).map((op) => ({ why: "refused", html: op.insert ? nodeHTML(op.insert) : writtenHTML(op) }))]
+      .filter((item) => item.html);
+  }
+  const texts = new Map((request.texts ?? []).map((text) => [text.key, text]));
+  const ops = new Map((request.units ?? []).map((op) => [op.key, op]));
+  const out = [];
+  for (const answer of receipt.texts ?? []) {
+    const html = answer.status === "conflict" ? partsHTML(texts.get(answer.key)) : "";
+    if (html) out.push({ why: answer.reason === "missing" ? "missing" : "changed", html });
+  }
+  for (const answer of receipt.units ?? []) {
+    // What a manifest that changed refused is given up (outdatedIn), nothing the reader keeps.
+    const op = answer.status === "conflict" && answer.reason !== "definition" ? ops.get(answer.key) : null;
+    // A block made on the page, one turned into another type (its text goes with the conversion), or what a component wrote.
+    const html = op?.insert ? nodeHTML(op.insert) : writtenHTML(op) ?? "";
+    if (html) out.push({ why: op.insert ? "insert" : answer.reason === "missing" ? "missing" : "changed", html, ...writtenIn(op?.unit?.id ?? op?.unit?.blockId, op?.source) });
+  }
+  return out;
+}
+
+// Of a component's write the file did not take, the block it was written in (its id) and the parts it
+// wrote (`parts`, by name), for the reader to copy as that block holding them (editor.mjs showLost).
+const writtenIn = (unit, parts) => (typeof unit === "string" && parts && typeof parts === "object" ? { unit, parts } : {});
+
+/**
+ * The commit a page left built from the same start as one whose answer it never learned (`sent`,
+ * sent again first and answered `answer`), made to go on from what that one wrote. A text both
+ * carry starts from what the file took of it. A block `sent` made (a split-off part, a block made
+ * on the page, the blocks in it) is not made again: it is in the file, by the id the answer gives,
+ * and what the page did to it since goes as done to that block: its text as an edit of what `sent`
+ * wrote, a move as a move. Blocks added into or taken out of one it made, or its blocks put in
+ * another order, have no start the file knows: what it holds is listed for the reader instead.
+ * Returns { request (null: nothing left), dropped }.
+ */
+function rebase(request, sent, answer) {
+  if (!request || !sent || !answer?.ok) return { request, dropped: [] };
+  const answers = new Map([...(answer.texts ?? []), ...(answer.units ?? [])].map((entry) => [entry.key, entry]));
+  const took = (key) => answers.get(key) && answers.get(key).status !== "conflict";
+  const fileId = (key, proposed) => answer.made?.[key] ?? proposed;
+  // Proposed id -> { id (the file's), node (as `sent` carried it), place (of an insert, as sent) }.
+  const made = new Map();
+  const note = (node) => {
+    if (node?.blockId) made.set(node.blockId, { id: fileId(node.key, node.blockId), node });
+    node?.children?.forEach(note);
+  };
+  for (const text of sent.texts ?? []) {
+    if (!took(text.key)) continue;
+    for (const part of text.parts ?? []) if (!part.keep && part.blockId) made.set(part.blockId, { id: fileId(part.key, part.blockId), node: { html: part.html } });
+  }
+  for (const op of sent.units ?? []) {
+    if (!op.insert || !took(op.key)) continue;
+    note(op.insert);
+    if (op.insert.blockId) made.get(op.insert.blockId).place = shape(op.place);
+  }
+  const dropped = [];
+  const extra = []; // edits of blocks `sent` made
+  let serial = 0;
+  const ref = (id) => ({ key: `r${serial++}`, id });
+  // The text of a block `sent` made, as an edit of what it wrote.
+  const edit = (entry, html) => {
+    if (html !== undefined && html !== entry.node.html) extra.push({ key: `r${serial++}`, block: { unit: ref(entry.id), self: true, before: entry.node.html ?? "" }, parts: [{ keep: true, html }] });
+  };
+  // A block made on the page as this commit carries it, against what `sent` made of it: its text and
+  // its blocks' texts as edits; false when its blocks differ (added, taken out, in another order).
+  const follow = (node, entry) => {
+    const now = (node.children ?? []).map((child) => child.blockId ?? null);
+    const then = (entry.node.children ?? []).map((child) => child.blockId ?? null);
+    if (now.join() !== then.join() || now.some((id) => id === null || !made.has(id))) return false;
+    if (node.title !== entry.node.title) return false;
+    edit(entry, node.html);
+    return (node.children ?? []).every((child) => follow(child, made.get(child.blockId)));
+  };
+
+  const before = new Map((sent.texts ?? []).filter((text) => took(text.key)).map((text) => [text.key, text]));
+  const texts = [];
+  for (const text of request.texts ?? []) {
+    const parts = (text.parts ?? []).filter((part) => {
+      if (part.keep || !made.has(part.blockId)) return true;
+      edit(made.get(part.blockId), part.html);
+      return false;
+    });
+    const earlier = before.get(text.key);
+    if (!earlier) {
+      texts.push({ ...text, parts });
+      continue;
+    }
+    const sentHTML = earlier.parts.find((part) => part.keep)?.html;
+    const mine = parts.find((part) => part.keep)?.html;
+    if (parts.length === 1 && mine !== undefined && mine === sentHTML) continue; // nothing since
+    const entry = answers.get(text.key);
+    const start = entry.status === "merged" ? entry.html : sentHTML;
+    texts.push({ ...text, parts, block: { ...text.block, before: start ?? text.block.before } });
+  }
+  const units = [];
+  for (const op of request.units ?? []) {
+    const entry = op.insert?.blockId ? made.get(op.insert.blockId) : null;
+    if (!entry) {
+      units.push(op);
+      continue;
+    }
+    if (!follow(op.insert, entry)) {
+      dropped.push({ why: "rebase", html: nodeHTML(op.insert) });
+      continue;
+    }
+    if (entry.place !== undefined && shape(op.place) !== entry.place) units.push({ key: op.key, unit: ref(entry.id), move: op.place });
+  }
+  texts.push(...extra);
+  // The units both name, as `sent` left them (as a page takes in an answer): the ids the file gave
+  // them and their hashes now, so what this one does to them is not taken for a change of someone
+  // else's (a unit's numbers in the page's map are its key in both).
+  const known = (ref) => {
+    if (!ref || typeof ref !== "object") return;
+    if (typeof ref.key === "number") {
+      const id = answer.ids?.[ref.key];
+      const hash = answer.hashes?.[ref.key];
+      if (id) ref.id = id;
+      if (hash) ref.hash = hash;
+    }
+    for (const value of Object.values(ref)) if (value && typeof value === "object") known(value);
+  };
+  const ops = structuredClone(units);
+  const edited = structuredClone(texts);
+  ops.forEach(known);
+  edited.forEach(known);
+  for (const op of ops) if (typeof op.hash === "string" && answer.hashes?.[op.unit?.key]) op.hash = answer.hashes[op.unit.key];
+  texts.splice(0, texts.length, ...edited);
+  units.splice(0, units.length, ...ops);
+  // Changed, it is another commit: an id of its own, the same each time it is made from this one.
+  const changed = JSON.stringify([texts, units]) !== JSON.stringify([request.texts ?? [], request.units ?? []]);
+  const next = texts.length + units.length > 0 ? { ...request, texts, units, ...(changed && request.request ? { request: `${request.request.slice(0, 38)}r` } : {}) } : null;
+  return { request: next, dropped };
+}
+
+/**
+ * A page that went away with a commit whose answer it never learned (`answer`, now known), taken
+ * up: what it knew and the page as it was (`bundle`, stateKey) in a document of their own
+ * (`parse`), with that answer taken in. { commits, alone }, or null when it cannot be (the bundle
+ * unreadable).
+ */
+function rehydrate(bundle, answer, parse) {
+  try {
+    const { document, value } = unpack(bundle, parse);
+    let layout = value.layout;
+    const commits = createCommits({ root: document, map: value.map, baselines: value.baselines, getLayout: () => layout, setLayout: (next) => (layout = next), restore: value });
+    const alone = !bundle.foreign && !answer.foreign;
+    commits.apply(value.pending, answer, { alone });
+    return { commits, alone };
+  } catch {
+    return null;
+  }
+}
+
+// What the file did not take of what a page taken up sent (its commits' issues): the reader's words, to list.
+const heldOf = (commits) => [...commits.issues.values()].filter((issue) => issue.mine)
+  .map((issue) => ({ why: issue.kind === "insert" ? "insert" : issue.reason === "missing" ? "missing" : "changed", html: issue.mine, ...writtenIn(issue.kind === "unit" ? commits.fileId(issue.unit) : null, issue.change?.source) }));
+
+/**
+ * Send what closed or crashed pages of this report left in the crash buffer under `keys`
+ * (pendingKey: this tab's own after a reload, those of tabs that are gone), oldest first: a commit
+ * whose answer never came first, as it was, then the rest of what waited. What the file does not
+ * take, and the texts no commit carried, go to lostKey before the buffer goes; a buffer whose
+ * commits are not answered (the server unreachable, busy) stays for the next page. Resolves with
+ * { sent: whether the file changed, lost: how many texts were listed, offline: the server could
+ * not be reached, left: a buffer stays for a later page (the server busy or failing, the list not
+ * written), outdated: what a component wrote was given up, its package's manifest having changed }.
+ */
+export async function recover({ map, storage, keys, parse = (html) => new DOMParser().parseFromString(html, "text/html") }) {
+  keys = keys.filter((key) => PENDING_KEY.test(key) && storage.get(key) !== null);
+  if (keys.length === 0) return { sent: false, lost: 0, offline: false };
+  const entries = keys.map((key) => {
+    const raw = storage.get(key) ?? "";
+    try {
+      const entry = JSON.parse(raw);
+      if (entry?.v === 2) return { key, time: entry.time, sent: entry.sent ?? null, request: entry.request ?? null, keep: Array.isArray(entry.keep) ? entry.keep : [], page: Array.isArray(entry.page) ? entry.page : [] };
+    } catch {}
+    return { key, time: 0, unreadable: raw };
+  }).sort((a, b) => a.time - b.time);
+  const send = (request) => postCommit(map, request);
+  let sent = false;
+  let lost = 0;
+  let outdated = false;
+  for (const entry of entries) {
+    const found = entry.unreadable ? [{ why: "unreadable", text: entry.unreadable.slice(0, 20000) }] : [];
+    if (!entry.unreadable) {
+      try {
+        let answer = null;
+        if (entry.sent) {
+          answer = await send(entry.sent);
+          if (!answered(answer)) return { sent, lost, offline: false, left: true }; // kept for the next page
+          if (answer.ok && answer.version !== map.version) sent = true;
+          outdated ||= outdatedIn(answer);
+        }
+        // What followed it: when the page went with what it knew, the page is taken up and goes on as
+        // it would have, commit after commit until nothing is left (one may wait for another: an
+        // item's conversion for its lists to go), each kept in the buffer, with what the page knows
+        // then, before it goes (a page that cannot send it sends that very one); what the file did
+        // not take in the end is listed. Otherwise the rest is rebuilt on the answer (rebase).
+        let bundle = null;
+        try {
+          bundle = answer?.ok ? JSON.parse(storage.get(stateKeyOf(entry.key)) ?? "null") : null;
+        } catch {}
+        const taken = bundle && entry.sent && bundle.sent === entry.sent.request ? rehydrate(bundle, answer, parse) : null;
+        if (!taken && entry.sent) found.push(...refusedOf(entry.sent, answer));
+        let request = null;
+        if (taken) {
+          for (let round = 0; round < 8; round++) {
+            let built = null;
+            try {
+              built = taken.commits.build({ held: round === 0 }); // what was held for the reader goes once more
+            } catch {}
+            if (!built) break;
+            const next = { ...built.request, known: null, request: randomRequestId() };
+            let state = null;
+            try {
+              state = JSON.stringify({ sent: next.request, foreign: !taken.alone, ...taken.commits.keep(built.pending) });
+            } catch {}
+            if (storage.set(entry.key, JSON.stringify({ v: 2, time: entry.time, sent: next, request: null, keep: entry.keep, page: entry.page })) === false) return { sent, lost, offline: false, left: true };
+            if (!state || storage.set(stateKeyOf(entry.key), state) === false) storage.remove(stateKeyOf(entry.key));
+            const reply = await send(next);
+            if (!answered(reply)) return { sent, lost, offline: false, left: true };
+            if (reply.ok && reply.version !== map.version) sent = true;
+            outdated ||= outdatedIn(reply);
+            if (!reply.ok) {
+              found.push(...refusedOf(next, reply));
+              break;
+            }
+            taken.commits.apply(built.pending, reply, { alone: taken.alone && !reply.foreign });
+          }
+          found.push(...heldOf(taken.commits));
+          storage.remove(stateKeyOf(entry.key));
+        } else {
+          const rebased = rebase(entry.request, entry.sent, answer);
+          request = rebased.request;
+          found.push(...rebased.dropped);
+        }
+        if (request) {
+          const second = await send(request);
+          if (!answered(second)) return { sent, lost, offline: false, left: true };
+          if (second.ok && second.version !== map.version) sent = true;
+          outdated ||= outdatedIn(second);
+          found.push(...refusedOf(request, second));
+        }
+      } catch {
+        return { sent, lost, offline: true }; // kept for the next page
+      }
+      found.push(...entry.keep.filter((item) => item?.html || item?.text));
+    }
+    if (found.length > 0 && !keepLost(storage, map.slug, found)) return { sent, lost, offline: false, left: true }; // the buffer stays
+    if (entry.page?.length > 0 && !keepCheck(storage, map.slug, entry.page)) return { sent, lost, offline: false, left: true };
+    lost += found.length;
+    storage.remove(entry.key);
+    storage.remove(stateKeyOf(entry.key));
+  }
+  return { sent, lost, offline: false, outdated };
+}