@panphora/clayjs 1.25.0 → 1.26.0

package/src/plugins/undo.js

@@ -11,6 +11,56 @@ import { PERSIST } from '../lib/attr-aliases.js'
 import { isGestureItem, isRuntimeAttribute } from '../lib/undo/capture-move.js'
 import { gateMarkDirty } from '../lib/dirty-gate.js'
 
+// Where the caret goes after an undo or redo: at the text that changed.
+//
+// The engine's receipt carries a hint for it: `{ node, offset }` for a text run, and
+// `{ root, textOffset }` for a field whose saved content is its text. The person goes on
+// typing from there, so the field takes focus when they were already typing in a field.
+// When they were not (a button, the dock's Undo on a phone), the field is only scrolled
+// into view: focusing it would open the keyboard. A structural step carries no hint, so
+// an item coming back moves neither the caret nor the focus.
+
+const EDITABLE = '[contenteditable]:not([contenteditable="false"])'
+
+// The text node an offset into the field's text lands on: count the field's text nodes
+// until the offset is inside one. Past the end is the end of the last text node, and an
+// empty field is the field itself.
+function resolve(root, textOffset) {
+  let left = Number(textOffset) || 0
+  if (left < 0) left = 0
+  const doc = root.ownerDocument || document
+  const walker = doc.createTreeWalker(root, 4)
+  let last = null
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (left <= node.data.length) return { node, offset: left }
+    left -= node.data.length
+    last = node
+  }
+  return last ? { node: last, offset: last.data.length } : { node: root, offset: root.childNodes.length }
+}
+
+// The field the hint is inside. A field in a hidden section is neither scrolled to nor
+// focused, and a node that is no longer in the page has nowhere to put a caret.
+function hostOf(node) {
+  const element = node.nodeType === 1 ? node : node.parentElement
+  const host = element?.closest?.(EDITABLE)
+  if (!host || !host.isConnected) return null
+  if (typeof host.checkVisibility === 'function' && host.checkVisibility() === false) return null
+  return host
+}
+
+function placeCaret(hint) {
+  if (!hint) return
+  const at = hint.root ? resolve(hint.root, hint.textOffset) : hint
+  if (!at?.node) return
+  const host = hostOf(at.node)
+  if (!host) return
+  if (typeof host.scrollIntoView === 'function') host.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+  if (!document.activeElement?.closest?.(EDITABLE)) return
+  if (document.activeElement !== host) host.focus({ preventScroll: true })
+  document.getSelection()?.collapse(at.node, at.offset)
+}
+
 // Tab-local attributes (ephemeral state, route-active, root library state) are
 // never undone, and neither is what a drag's vendor writes on the item it holds:
 // `draggable` and `style` are the gesture's own bookkeeping, and a click that
@@ -20,6 +70,17 @@ import { gateMarkDirty } from '../lib/dirty-gate.js'
 // The page's own maintenance attributes, kept outside history by name (a card number a
 // repair rewrites, for example): saved like any attribute, never an edit to undo.
 const pageIgnored = new Set()
+// What a structural undo step compares for a node whose live markup is not its saved
+// markup. An editor that owns a field registers one function (`clay.undo.addDurableForm`):
+// it answers a string for a node it owns and undefined for every other node.
+const durableForms = new Set()
+const durableFormOf = (node, host = null) => {
+  for (const form of durableForms) {
+    const own = form(node, host)
+    if (typeof own === 'string') return own
+  }
+  return undefined
+}
 const withTabLocal = (opts = {}) => {
   const own = opts.ignoreAttribute
   return {
@@ -27,15 +88,18 @@ const withTabLocal = (opts = {}) => {
     ignoreAttribute: (name, target, host) => pageIgnored.has(name) || isTabLocalAttr(name, target) || isDerivedAttr(target, name, host) || isRuntimeAttribute(name, target) || (own ? own(name, target, host) : false),
     isProtected: opts.isProtected || keepsOwnHistory,
     ignoreNode: opts.ignoreNode || isGestureItem,
+    durableForm: opts.durableForm || durableFormOf,
   }
 }
 
-// Saved content that undo does not record (a richclay region, a no-undo block) has a
-// history undo cannot restore, so a parent's undo or redo must not erase it. Chrome
-// that is never saved (editor-ui) loses nothing and is not protected.
+// Saved content that undo does not record (an authored no-undo block) has a history
+// undo cannot restore, so a parent's undo or redo must not erase it. A node with a
+// durable form (a mounted rich field) is certified by that form instead, and chrome
+// that is never saved (editor-ui) loses nothing; neither is protected.
 function keepsOwnHistory(node) {
   const policy = window.clay?.region?.resolveRegionPolicy
   if (!policy || node.nodeType !== 1) return false
+  if (durableFormOf(node) !== undefined) return false
   const own = policy(node)
   if (own.undoable !== false || own.persist === 'none') return false
   const parent = node.parentElement
@@ -52,9 +116,12 @@ let recording = null
 const setRecording = undo.setRecording.bind(undo)
 undo.setRecording = (mode) => {
   recording = mode ?? null
+  document.dispatchEvent(new CustomEvent('clay:undo-recording', { detail: { mode: recording } }))
   return setRecording(mode)
 }
 
+Object.defineProperty(undo, 'recordingMode', { get: () => recording, configurable: true })
+
 // An authored history action is a user edit, and it writes the DOM while a sync
 // frame's apply may hold both the mutation hub and the gate paused: neither feed
 // records it then, and the apply would take the write into its saved baseline.
@@ -73,6 +140,17 @@ undo.command = (label, fn) => {
 // Undo and redo mark it in afterReplay, which the engine calls on every path that
 // replays a step: the facade and the keyboard shortcut bound to the engine itself.
 
+// One entry holding one step that another editor stands behind (the block editor's own
+// Yjs stack item). It goes through the engine's own command, whose flush closes whatever
+// the page was typing, so the order of the two histories is the order of the edits. The
+// editor's step is not a document write of its own, so recording it never marks the page
+// dirty; the editor's own dirty feed is the one that does.
+undo.recordStep = (label, primitive) => command(label, () => undo.record(primitive))
+
+// A step that stands for an editor's own undo item holds tokens, not text: its prop names
+// it, and what a person wrote lives in the editor, not in a recovery copy.
+const isBlockStep = (entry) => !!entry?.steps?.length && entry.steps.every((step) => step.kind === 'value' && /^blockeditor-step(?::|$)/.test(step.prop))
+
 // A commit inside clay.effect drains the paused hub's records, so the effect's
 // own writes reach autosave and re-trigger it. Warn once; the commit still runs.
 const commit = undo.commit.bind(undo)
@@ -131,8 +209,9 @@ function restoreControls() {
 // undo or redo never reaches the control restore.
 const afterReplay = (receipt) => {
   if (!receipt?.ok) return
-  gateMarkDirty()
+  if (!isBlockStep(undo.describe(receipt.entryId))) gateMarkDirty()
   restoreControls()
+  if (receipt.caret && undo.pageHistory) placeCaret(receipt.caret)
 }
 
 // A refusal is announced for whoever presents it: the engine's receipt, once.
@@ -143,6 +222,17 @@ const refuse = ({ entryId, label, direction, code }) => {
   keepRefused({ ok: false, code, entryId, label, direction })
 }
 
+// A step the engine can no longer replay is skipped instead of blocking the press: the
+// person asked once and gets the next older step. Its recovery copy is made from the
+// description the engine hands over, because the entry is already out of the history.
+const skip = ({ entryId, label, direction, code, description }) => {
+  document.dispatchEvent(new CustomEvent('clay:undo-skipped', {
+    detail: { entryId, label, direction, code },
+  }))
+  if (isBlockStep(description)) return
+  keepRefused({ ok: false, code, entryId, label, direction, description })
+}
+
 // A refused step is kept as recovery before a reload can take it away: the refusal is
 // announced synchronously above and the copy is made behind it, so a store that will
 // not answer can never hold up the receipt. The module is fetched on the first refusal
@@ -185,6 +275,11 @@ const withRecovery = (call, fallback) => (...args) =>
 // An app's kept copy is announced like a refused step's, so the review notice shows it
 // in this session instead of only after a reload.
 const keepApp = withRecovery('keep', { ok: false, code: 'unavailable' })
+undo.addDurableForm = (form) => {
+  durableForms.add(form)
+  return () => { durableForms.delete(form) }
+}
+
 undo.ignoreAttribute = (name) => {
   const key = String(name || '')
   if (!key) return () => {}
@@ -235,9 +330,48 @@ undo.reviewActionsFor = (record) => {
 // after every entry, replay, refusal, dismissal and clear, and when a session starts or
 // ends. `undo` and `redo` are the entries the next press would replay, with `refused`
 // set on the one that was just refused.
-const HISTORY_EVENTS = ['commit', 'undo', 'redo', 'refused', 'discard', 'clear']
+const HISTORY_EVENTS = ['commit', 'undo', 'redo', 'refused', 'skipped', 'discard', 'clear']
+
+// Whatever else owns the moment (a proposal preview, a dialog) holds the page history: while
+// any hold is live the engine refuses a replay, so nothing behind the hold can be undone by a
+// stray Cmd+Z, and the event reports neither direction as available.
+const holds = new Set()
+
+// The engine's own answer for each direction: a getter on the engine object itself, so it is
+// read once here and called through, whatever else happens to the property.
+const engineDirection = (name) => {
+  for (let owner = undo; owner; owner = Object.getPrototypeOf(owner)) {
+    const desc = Object.getOwnPropertyDescriptor(owner, name)
+    if (!desc) continue
+    if (typeof desc.get === 'function') return () => desc.get.call(undo)
+    return () => Boolean(desc.value.call(undo))
+  }
+  return () => false
+}
+
+const engineCanUndo = engineDirection('canUndo')
+const engineCanRedo = engineDirection('canRedo')
+
+// While a hold is live neither direction is available, so a dock button, the editor's own
+// history and the event all answer the same thing.
+Object.defineProperty(undo, 'canUndo', { get: () => holds.size === 0 && engineCanUndo(), configurable: true })
+Object.defineProperty(undo, 'canRedo', { get: () => holds.size === 0 && engineCanRedo(), configurable: true })
+
+undo.hold = () => {
+  const token = Symbol('hold')
+  holds.add(token)
+  announceChange()
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    holds.delete(token)
+    announceChange()
+  }
+}
+
 const announceChange = () => {
-  const live = !!session?.started
+  const live = !!session?.started && holds.size === 0
   document.dispatchEvent(new CustomEvent('clay:undo-change', {
     detail: {
       canUndo: live && undo.canUndo,
@@ -254,6 +388,22 @@ const announceChange = () => {
 // recovery service and outlive every session; nothing here reads, clears or rewrites them.
 let session = null
 
+// There is one history in Edit and it is the page's: a live session is what puts a rich
+// field's typing on it and gives Cmd+Z in any editable field to it. No attribute decides
+// this, and a page that never loads this plugin never starts a session, so nothing about
+// it changes.
+Object.defineProperty(undo, 'pageHistory', {
+  get: () => !!session?.started,
+  configurable: true,
+})
+
+const announceSession = () => {
+  if (typeof document === 'undefined') return
+  document.dispatchEvent(new CustomEvent('clay:undo-session', {
+    detail: { started: !!session?.started, pageHistory: undo.pageHistory },
+  }))
+}
+
 function ownership() {
   return { started: false, admitted: false, subscriptions: [] }
 }
@@ -283,18 +433,29 @@ function undoLease(record) {
       if (record.started) return
       record.started = true
       record.admitted = true
-      undo.start(withTabLocal({ bindKeys: true, ...(recording ? { recording } : {}) }))
+      undo.start(withTabLocal({
+        bindKeys: true,
+        editableKeys: 'page',
+        ownKeysIn: ['.blockeditor-editor'],
+        typingBreak: 'sentence',
+        refused: 'skip',
+        holdReplay: () => holds.size > 0,
+        ...(recording ? { recording } : {}),
+      }))
       for (const type of ['undo', 'redo']) {
         undo.on(type, afterReplay)
         record.subscriptions.push({ type, handler: afterReplay })
       }
       undo.on('refused', refuse)
       record.subscriptions.push({ type: 'refused', handler: refuse })
+      undo.on('skipped', skip)
+      record.subscriptions.push({ type: 'skipped', handler: skip })
       for (const type of HISTORY_EVENTS) {
         undo.on(type, announceChange)
         record.subscriptions.push({ type, handler: announceChange })
       }
       announceChange()
+      announceSession()
     },
     quiesce() {
       if (!record.admitted) return
@@ -314,6 +475,7 @@ function undoLease(record) {
       for (const { type, handler } of record.subscriptions.splice(0)) undo.off(type, handler)
       undo.stop()
       announceChange()
+      announceSession()
     },
   }
 }

package/src/recovery/undo.js

@@ -148,7 +148,9 @@ let keeping = Promise.resolve();
  * keeps it — and answers with the failure.
  *
  * @param {Object} engine - the started undo scope (`clay.undo`)
- * @param {{entryId: string, direction: string, code?: string}} receipt
+ * @param {{entryId: string, direction: string, code?: string, description?: ?Object}} receipt
+ *   `description` is the engine's own `describe(entryId)` answer where the caller already has
+ *   it, as a skipped step does: that entry is out of the history by the time it is kept.
  * @returns {Promise<{ok: boolean, code?: string}>}
  */
 export function keepRefusal(engine, receipt) {
@@ -160,11 +162,13 @@ export function keepRefusal(engine, receipt) {
 async function keepRefusalNow(engine, receipt) {
   const ch = channel();
   if (!ch) return { ok: false, code: 'unavailable' };
-  let described = null;
-  try {
-    described = engine?.describe?.(receipt?.entryId) ?? null;
-  } catch (_) {
-    described = null;
+  let described = receipt?.description ?? null;
+  if (!described) {
+    try {
+      described = engine?.describe?.(receipt?.entryId) ?? null;
+    } catch (_) {
+      described = null;
+    }
   }
   if (!described) return { ok: false, code: 'unknown-entry' };
   const refused = described.refused && typeof described.refused === 'object' ? described.refused : {};
@@ -186,7 +190,10 @@ async function keepRefusalNow(engine, receipt) {
   try {
     staged = ch.stage({ key, kind: UNDO_KIND, baseEtag: representedEtag() ?? null, base: null, payload });
   } catch (err) {
-    console.error('clayjs: the refused step could not be kept for a later reload; it is still in this tab\'s history', err);
+    const message = receipt?.description
+      ? 'clayjs: the skipped step could not be kept for a later reload; its text is lost when this tab does'
+      : 'clayjs: the refused step could not be kept for a later reload; it is still in this tab\'s history'
+    console.error(message, err)
     return { ok: false, code: 'error' };
   }
   const written = await ch.flush();

package/src/server/markdown/index.js

@@ -0,0 +1,23 @@
+import { Marked } from "../../vendor/marked.vendor.js";
+import { importMarkdownTokens, MarkdownImportError, MAX_BYTES } from "../../page/import-markdown.js";
+import { fragmentCleaner, project, renderModel, revOf } from "../../page/projection.js";
+import { documentTitle } from "../../page/document-title.js";
+
+export { MarkdownImportError, MAX_BYTES };
+
+/**
+ * Markdown text as a Block editor article: the inner HTML of `<article data-blockeditor>`,
+ * the `data-rev` that article carries, and the title a save would write. The same codec
+ * and projection the editor uses, so the editor opens the result as its own page.
+ * `document` is any DOM document (jsdom on a server); raw HTML blocks are cleaned with it.
+ * `resolveImage(src)` may return a replacement address for an image, or null; `resolveLink(href)`
+ * does the same for a link (a link to another local file is otherwise kept as text).
+ */
+export function markdownArticle(text, { document, resolveImage = null, resolveLink = null } = {}) {
+  if (!document) throw new TypeError("markdownArticle needs a DOM document");
+  const tokens = new Marked().lexer(String(text ?? ""));
+  const { blocks, unsupported, refused } = importMarkdownTokens(tokens, { document, resolveImage, resolveLink });
+  const model = project(blocks);
+  const html = renderModel(model, { fallbackOf: () => "", clean: fragmentCleaner(document) });
+  return { html, rev: revOf(model), title: documentTitle(model), unsupported, refused };
+}

package/src/sync/conflicts.js

@@ -62,8 +62,10 @@ function changed(detail) {
 // A report is a loss unless the engine says this tab's operation survived, or a
 // hook kept the incoming change off the page. One the engine could not map to the
 // live page ("missing-output") still replaced this tab's work: it shows, without
-// a place to point at.
+// a place to point at. A region whose incoming version always wins (no-dirty,
+// no-watch) held nothing to keep, so replacing it is never a loss.
 function isLoss(c) {
+  if (c.kind === 'structure' && c.detail === 'remote-wins') return false;
   const r = c.recovery;
   if (!r) return true;
   if (r.applied === false && r.unavailable === 'hook-veto') return false;

package/src/sync/data-guard-notice.js

@@ -1,12 +1,24 @@
 import { saveToken } from "../core/host-attrs.js";
 import { storage } from "../lib/doc-storage.js";
+import { isSaveInProgress } from "../core/save-core.js";
 
-const TITLE = "Saved data was overwritten";
+const TITLE = "Some saved data was removed";
+const TITLES = {
+  recent: "A change from outside this page removed something you typed",
+  "all-typed": "A change from outside this page removed everything you typed",
+  emptied: "A change from outside this page emptied this page's data",
+  unreadable: "A change from outside this page left its data unreadable",
+};
+const TYPED_SHOWN = 3;
+const HOUR_MS = 3600000;
 const DONE_KEY = "data-guard-done";
 const READ_TIMEOUT_MS = 6000;
 const AFTER_SAVE_MS = 1500;
 const MIN_READ_GAP_MS = 5000;
 const VISIBLE_GAP_MS = 30000;
+const EXTERNAL_WINDOW_MS = 10000;
+const SETTLE_CAP_MS = 6000;
+const SAVE_UNSETTLED_EVENTS = ["clay:save-error", "clay:save-offline", "clay:save-conflict"];
 const UNREACHED = "Could not reach the server. Try again.";
 const REFUSED = "That did not go through. Try again.";
 const SAVE_FIRST = "Save your changes first, then try again.";
@@ -20,7 +32,15 @@ const isPending = (event) => Boolean(event) && typeof event.id === "string" && e
 const allowed = (current, event, choice, flag) => flag === true && !current.refused.has(`${event.id}:${choice}`);
 const canRestore = (current, event) => allowed(current, event, "restore", event.restorable);
 const canRevert = (current, event) => allowed(current, event, "revert", event.canRevert);
+const canPutBack = (current, event) => allowed(current, event, "put-back", event.canPutBack);
+const typed = (event) => (Array.isArray(event.typed) ? event.typed : []);
+const reasoned = (event) => Boolean(event.reason);
+const titleFor = (event) => TITLES[event.reason] ?? TITLE;
+const typedLoss = (event) => event.reason === "recent" || event.reason === "all-typed";
+const toneFor = (event) => (typedLoss(event) ? "info" : "warning");
 const credentials = () => (saveToken() ? "omit" : "same-origin");
+const settling = (current) =>
+  isSaveInProgress() || (current.lastExternal > 0 && Date.now() - current.lastExternal < EXTERNAL_WINDOW_MS);
 const headers = (extra = {}) => ({ "Document-URL": location.href, ...extra });
 
 function removeServerBar() {
@@ -34,7 +54,7 @@ function say(message, type) {
   }, () => {});
 }
 
-function describe(current, event) {
+function sourceOf(event) {
   const summary = event.lossSummary || {};
   const source = summary.provenance === "external" ? "A change from outside this page" : "A save from this page";
   const loss = summary.removedItems > 0
@@ -43,12 +63,54 @@ function describe(current, event) {
   const row = Array.isArray(event.preview) ? event.preview[0] : null;
   const parts = [`${source} ${loss}.`];
   if (row) parts.push(`${row.key}: ${row.yours} before, ${row.now} now.`);
-  if (canRestore(current, event)) {
-    if (event.droppedAdditions > 0) parts.push(`Restoring removes ${plural(event.droppedAdditions, "item")} added or changed since.`);
-  } else if (canRevert(current, event)) {
-    parts.push("This data no longer fits the page, but the whole change can be undone.");
+  return parts;
+}
+
+function labelFor(path) {
+  const parts = String(path ?? "").split(".").filter((part) => part && !/^\[[^\]]*\]$/.test(part));
+  const last = (parts[parts.length - 1] ?? "").replace(/\[[^\]]*\]/g, "").trim();
+  return last.replace(/[_-]+/g, " ") || "value";
+}
+
+function typedLine(event) {
+  const rows = typed(event);
+  if (!rows.length) return "";
+  const shown = rows.slice(0, TYPED_SHOWN).map((row) => `${labelFor(row.path)}: "${row.yours}"`);
+  const more = rows.length - shown.length;
+  return `${shown.join("; ")}${more > 0 ? ` and ${more} more.` : "."}`;
+}
+
+function typedWhen(event) {
+  if (event.reason === "all-typed") return "";
+  const row = typed(event)[0];
+  const at = typeof row?.at === "number" ? row.at : Date.parse(row?.at);
+  if (!Number.isFinite(at)) return "";
+  const ago = Date.now() - at;
+  if (ago < 0 || ago >= HOUR_MS) return "";
+  const minutes = Math.max(1, Math.floor(ago / 60000));
+  return `You typed ${typed(event).length === 1 ? "it" : "them"} ${plural(minutes, "minute")} ago.`;
+}
+
+function detailFor(current, event) {
+  if (!reasoned(event)) {
+    const parts = sourceOf(event);
+    if (canRestore(current, event)) {
+      if (event.droppedAdditions > 0) parts.push(`Restoring removes ${plural(event.droppedAdditions, "item")} added or changed since.`);
+    } else if (canRevert(current, event)) {
+      parts.push("This data no longer fits the page, but the whole change can be undone.");
+    } else {
+      parts.push("It cannot be restored from here.");
+    }
+    if (canRevert(current, event)) parts.push("Undo the change also removes edits made since.");
+    return parts.join(" ");
+  }
+  const parts = [];
+  if (typedLoss(event)) {
+    parts.push(typedLine(event) || sourceOf(event).join(" "));
+    const when = typedWhen(event);
+    if (when) parts.push(when);
   } else {
-    parts.push("It cannot be restored from here.");
+    parts.push(sourceOf(event).join(" "));
   }
   if (canRevert(current, event)) parts.push("Undo the change also removes edits made since.");
   return parts.join(" ");
@@ -56,14 +118,26 @@ function describe(current, event) {
 
 function actionsFor(current, event) {
   const actions = [];
-  if (canRestore(current, event)) actions.push({ label: "Restore", onClick: () => choose(current, event, "restore") });
+  if (!reasoned(event)) {
+    if (canRestore(current, event)) actions.push({ label: "Restore", onClick: () => choose(current, event, "restore") });
+    if (canRevert(current, event)) actions.push({ label: "Undo the change", onClick: () => choose(current, event, "revert") });
+    actions.push({ label: "Keep as is", onClick: () => choose(current, event, "dismiss") });
+    return actions;
+  }
+  if (canPutBack(current, event)) actions.push({ label: "Put it back", onClick: () => choose(current, event, "put-back") });
   if (canRevert(current, event)) actions.push({ label: "Undo the change", onClick: () => choose(current, event, "revert") });
-  actions.push({ label: "Keep as is", onClick: () => choose(current, event, "dismiss") });
+  actions.push({ label: "Keep the change", onClick: () => choose(current, event, "dismiss") });
   return actions;
 }
 
 async function draw(current, event) {
-  const key = [event.id, canRestore(current, event), canRevert(current, event), event.lastWriteAt, describe(current, event)].join("|");
+  const title = titleFor(event);
+  const detail = detailFor(current, event);
+  const key = [
+    event.id, title, event.reason ?? "", JSON.stringify(typed(event)),
+    canRestore(current, event), canPutBack(current, event), canRevert(current, event),
+    event.lastWriteAt, detail,
+  ].join("|");
   if (current.drawn === key) return true;
   current.drawn = key;
   current.eventId = event.id;
@@ -77,15 +151,20 @@ async function draw(current, event) {
     return false;
   }
   if (session !== current || current.drawn !== key) return false;
-  ui.dismissPersistent(TITLE, { now: true });
-  ui.toastPersistent(TITLE, "warning", { detail: describe(current, event), actions: actionsFor(current, event) });
+  const previous = current.title;
+  current.title = title;
+  if (previous && previous !== title) ui.dismissPersistent(previous, { now: true });
+  ui.dismissPersistent(title, { now: true });
+  ui.toastPersistent(title, toneFor(event), { detail, actions: actionsFor(current, event) });
   return true;
 }
 
 function clearNotice(current) {
+  const title = current.title;
   current.drawn = null;
   current.eventId = null;
-  ui?.dismissPersistent(TITLE, { now: true });
+  current.title = null;
+  if (title) ui?.dismissPersistent(title, { now: true });
 }
 
 async function read(current) {
@@ -113,7 +192,11 @@ async function read(current) {
   if (session !== current || turn !== current.turn) return;
   if (!body || typeof body !== "object" || !("event" in body)) return;
   if (isPending(body.event)) {
-    if (current.resolved.has(body.event.id)) return;
+    if (current.resolved.has(body.event.id) || current.waiting === body.event.id) return;
+    if (!current.waited.has(body.event.id) && settling(current)) {
+      waitForSettle(current, body.event.id);
+      return;
+    }
     if (await draw(current, body.event)) removeServerBar();
     return;
   }
@@ -150,7 +233,7 @@ function settle(current, event, choice, status, body) {
   } else if (status === 422) {
     current.refused.add(`${event.id}:${choice}`);
     if (current.eventId === event.id && !current.resolved.has(event.id)) draw(current, event);
-    say(choice === "restore" ? "That data no longer fits this page, so it could not be restored." : "That earlier version is no longer available.", "warning");
+    say(choice === "restore" || choice === "put-back" ? "That data no longer fits this page, so it could not be restored." : "That earlier version is no longer available.", "warning");
   } else if (status === 401 || status === 403) {
     say(RELOAD_FIRST, "error");
   } else {
@@ -202,17 +285,44 @@ function onNotification(current, e) {
     if (typeof data?.id !== "string") return;
     current.turn++;
     current.resolved.add(data.id);
+    if (current.waiting === data.id) stopWaiting(current);
     if (current.eventId === data.id) clearNotice(current);
     return;
   }
   if (action === "raised" && isPending(data) && !current.resolved.has(data.id)) {
     current.turn++;
+    if (current.waiting === data.id) return;
+    if (!current.waited.has(data.id) && settling(current)) {
+      waitForSettle(current, data.id);
+      return;
+    }
     draw(current, data).then((drawn) => { if (drawn) removeServerBar(); }, () => {});
   }
 }
 
 const readAt = (current) => Math.max(current.lastSave + AFTER_SAVE_MS, current.lastRead + MIN_READ_GAP_MS);
 
+function stopWaiting(current) {
+  if (!current.waiting) return false;
+  current.waiting = null;
+  clearTimeout(current.waitTimer);
+  current.waitTimer = null;
+  return true;
+}
+
+function endWait(current, { now = false } = {}) {
+  if (!stopWaiting(current) || session !== current) return;
+  if (now) read(current);
+  else armRead(current);
+}
+
+function waitForSettle(current, id) {
+  current.waited.add(id);
+  current.waiting = id;
+  clearTimeout(current.waitTimer);
+  current.waitTimer = setTimeout(() => endWait(current, { now: true }), SETTLE_CAP_MS);
+}
+
 function armRead(current) {
   if (current.timer) return;
   current.timer = setTimeout(() => {
@@ -235,22 +345,30 @@ export function start({ href, reload = () => window.location.reload() }) {
   const listeners = new AbortController();
   const current = {
     url: url.href, reload, listeners, turn: 0, lastRead: 0, lastSave: 0, timer: null,
-    busy: false, drawn: null, eventId: null, resolved: new Set(), refused: new Set(),
+    lastExternal: 0, waiting: null, waitTimer: null, waited: new Set(),
+    busy: false, drawn: null, eventId: null, title: null, resolved: new Set(), refused: new Set(),
   };
   session = current;
   const { signal } = listeners;
   document.addEventListener("clay:notification", (e) => onNotification(current, e), { signal });
+  document.addEventListener("clay:sync-applied", (e) => {
+    if (e.detail?.source === "disk") current.lastExternal = Date.now();
+  }, { signal });
   document.addEventListener("clay:save-saved", () => {
     current.lastSave = Date.now();
-    armRead(current);
+    if (current.waiting) endWait(current);
+    else armRead(current);
   }, { signal });
+  for (const name of SAVE_UNSETTLED_EVENTS) {
+    document.addEventListener(name, () => endWait(current, { now: true }), { signal });
+  }
   document.addEventListener("visibilitychange", () => {
     if (document.visibilityState === "visible" && Date.now() - current.lastRead >= VISIBLE_GAP_MS) read(current);
   }, { signal });
   const done = storage.session.get(DONE_KEY);
   if (done) {
     storage.session.remove(DONE_KEY);
-    say(done === "restore" ? "Your saved data is back." : "The earlier version is back.", "success");
+    say(done === "restore" || done === "put-back" ? "Your saved data is back." : "The earlier version is back.", "success");
   }
   read(current);
 }
@@ -261,5 +379,6 @@ export function stop() {
   session = null;
   current.listeners.abort();
   clearTimeout(current.timer);
+  clearTimeout(current.waitTimer);
   clearNotice(current);
 }