@panphora/clayjs 1.13.1 → 1.15.0

package/src/live/store.js

@@ -4,7 +4,7 @@
 // Local ops change state at once. When authoritative moves, state is rebuilt in
 // place, so an object or list page code holds a reference to stays live.
 
-import { validateOp, checkOp, applyOp, applyOps, cloneJson, assignDeep, coalesce, serializeLive } from "./ops.js";
+import { validateOp, checkOp, applyOp, applyOps, applyTracked, undoTracked, cloneJson, assignDeep, coalesce, overlaps, serializeLive } from "./ops.js";
 
 const MUTATORS = new Set(["push", "pop", "shift", "unshift", "splice", "sort", "reverse", "fill", "copyWithin"]);
 const INDEX = /^(0|[1-9]\d*)$/;
@@ -21,6 +21,79 @@ function readPath(root, path) {
   return node;
 }
 
+const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+const sameOp = (a, b) => serializeLive(a) === serializeLive(b);
+
+// Applies ops in place, all or none: the records of what changed, or null
+// (and root as it was) when one does not apply.
+function track(root, ops) {
+  const done = [];
+  try {
+    for (const op of ops) {
+      const rec = applyTracked(root, op);
+      if (rec) {
+        done.push(rec);
+        root = rec.root;
+      }
+    }
+    return done;
+  } catch {
+    untrack(done);
+    return null;
+  }
+}
+
+function untrack(done) {
+  let root;
+  for (let i = done.length - 1; i >= 0; i--) root = undoTracked(done[i]);
+  return root;
+}
+
+// What a frame's ops did, slot by slot, when page state can follow them one
+// slot at a time instead of a rebuild: each object slot the frame changed once
+// or more (path, whether it held a value before and its value then), none
+// inside another, no list changed at its own level, no whole value replaced,
+// and no key taken out and put back (that moves the key to the end). Pending
+// ops this tab has not seen confirmed must not touch those slots, nor add or
+// remove keys beside a key the frame adds. With each slot, the object in state
+// that mirrors it (into). null: rebuild.
+function slotsOf(done, pending, state) {
+  const slots = [];
+  for (const rec of done) {
+    if (rec.at === null || Array.isArray(rec.at)) return null;
+    const slot = slots.find((x) => x.path.length === rec.path.length && overlaps(x.path, rec.path));
+    if (slot) {
+      // Taken out and put back in one frame: the key moves to the end.
+      if (slot.removed && rec.kind !== "remove") return null;
+      if (rec.kind === "remove") slot.removed = true;
+      continue;
+    }
+    if (slots.some((x) => overlaps(x.path, rec.path))) return null;
+    slots.push({ path: rec.path, at: rec.at, key: rec.key, had: rec.kind !== "add", old: rec.old, removed: rec.kind === "remove" });
+  }
+  for (const slot of slots) {
+    slot.has = has(slot.at, slot.key);
+    if (slot.had && slot.has && slot.removed) return null;
+    slot.into = readPath(state, slot.path.slice(0, -1));
+    if (!isContainer(slot.into) || Array.isArray(slot.into) || has(slot.into, slot.key) !== slot.had) return null;
+    const parent = slot.path.slice(0, -1);
+    for (const entry of pending) {
+      const path = entry.op.path;
+      if (overlaps(slot.path, path)) return null;
+      // A pending delete in a list above the slot shifts the indices the
+      // frame's path counts in.
+      if (entry.op.op === "del" && path.length <= slot.path.length && overlaps(path.slice(0, -1), slot.path) && Array.isArray(readPath(state, path.slice(0, -1)))) return null;
+      // A key the frame adds goes last; a pending op that adds or takes out a
+      // key of the same object would order them differently in a rebuild.
+      if (!slot.had && slot.has && path.length > parent.length && overlaps(parent, path)) {
+        const child = path[parent.length];
+        if (path.length === parent.length + 1 ? entry.op.op === "del" || !has(slot.at, String(child)) : !has(slot.at, String(child))) return null;
+      }
+    }
+  }
+  return slots;
+}
+
 // applyOp, except that a set replacing a container with one of the same kind
 // rewrites it in place, so a proxy over the old container still points at the
 // value page code sees.
@@ -40,6 +113,9 @@ export function createStore({ name, value, ephemeral = false }) {
 
   let authoritative = cloneJson(value);
   const state = cloneJson(value);
+  // state is authoritative with pending replayed over it. Only a confirm whose
+  // ops no longer apply breaks that, until the next rebuild.
+  let coherent = true;
   // This tab's unconfirmed ops, oldest first, each with a local id that only grows.
   let pending = [];
   let nextId = 1;
@@ -48,6 +124,7 @@ export function createStore({ name, value, ephemeral = false }) {
   const listeners = new Set();
   const sinks = new Set();
   const rebases = new Set();
+  const confirmations = new Set();
   const deliveries = new Set();
   const views = new WeakMap();
 
@@ -74,6 +151,47 @@ export function createStore({ name, value, ephemeral = false }) {
     }
     pending = kept;
     assignDeep(state, next);
+    coherent = true;
+  }
+
+  function tell(event) {
+    for (const fn of [...rebases]) {
+      try {
+        fn(event);
+      } catch (err) {
+        console.error(`clay.live("${name}"): a rebase listener threw`, err);
+      }
+    }
+  }
+
+  // drop: [first, last], the pending ops with ids in that range are taken out
+  // (an op the host refused); the others stay.
+  function rebase(next, { source = "remote", confirmed = 0, through, drop, dropIds, frame = null, room = null, cause = null } = {}) {
+    if (!isContainer(next) || kind(next) !== kind(state)) {
+      console.warn(`clay.live("${name}"): ignored an incoming value that is not ${kind(state)}`);
+      return false;
+    }
+    const before = serializeLive(state);
+    const prev = authoritative;
+    authoritative = cloneJson(next);
+    if (drop) pending = pending.filter((entry) => entry.id < drop[0] || entry.id > drop[1]);
+    else if (dropIds) { const ids = new Set(dropIds); pending = pending.filter((entry) => !ids.has(entry.id)); }
+    else pending = through === undefined ? pending.slice(confirmed) : pending.filter((entry) => entry.id > through);
+    rebuild();
+    tell({ source, frame, room, cause, prev, before: (path) => readPath(prev, path), next: authoritative });
+    if (serializeLive(state) !== before) emit(source, null);
+    return true;
+  }
+
+  // The value before the frame whose records are done: authoritative copied,
+  // with the records taken back in the copy, path by path.
+  function priorOf(done) {
+    const copy = cloneJson(authoritative);
+    for (let i = done.length - 1; i >= 0; i--) {
+      const rec = done[i];
+      undoTracked({ ...rec, at: readPath(copy, rec.path.slice(0, -1)) });
+    }
+    return copy;
   }
 
   function publish(ops) {
@@ -238,6 +356,8 @@ export function createStore({ name, value, ephemeral = false }) {
     get value() {
       return state;
     },
+    // The room's value. A frame changes it in place (rebaseOps), so a caller
+    // that keeps any part of it past the call copies it. Never mutate it.
     get authoritative() {
       return authoritative;
     },
@@ -270,31 +390,89 @@ export function createStore({ name, value, ephemeral = false }) {
         authoritative = applyOps(cloneJson(authoritative), taken.map((entry) => entry.op));
       } catch {
         authoritative = cloneJson(state);
+        coherent = false;
       }
       pending = pending.filter((entry) => entry.id > through);
+      for (const fn of [...confirmations]) {
+        try {
+          fn({ through });
+        } catch (err) {
+          console.error(`clay.live("${name}"): a confirmation listener threw`, err);
+        }
+      }
+    },
+    onConfirm(fn) {
+      confirmations.add(fn);
+      return () => confirmations.delete(fn);
     },
     // A new value from outside. Ops already in it are dropped: the first
     // `confirmed` pending ops, or every op up to the mark `through`. The rest
     // replay over it; a pending op that no longer applies is dropped too.
     // Listeners hear about it only when the value page code sees changed.
-    rebase(next, { source = "remote", confirmed = 0, through, frame = null, room = null, cause = null } = {}) {
-      if (!isContainer(next) || kind(next) !== kind(state)) {
-        console.warn(`clay.live("${name}"): ignored an incoming value that is not ${kind(state)}`);
-        return false;
+    rebase,
+    // The ops of a frame the room ordered, checked: the same ops validated, or
+    // null when they do not apply to authoritative as a whole.
+    checkOps(ops) {
+      let checked;
+      try {
+        checked = ops.map(validateOp);
+      } catch {
+        return null;
       }
-      const before = serializeLive(state);
-      const prev = authoritative;
-      authoritative = cloneJson(next);
-      pending = through === undefined ? pending.slice(confirmed) : pending.filter((entry) => entry.id > through);
-      rebuild();
-      for (const fn of [...rebases]) {
-        try {
-          fn({ source, frame, room, cause, prev, next: authoritative });
-        } catch (err) {
-          console.error(`clay.live("${name}"): a rebase listener threw`, err);
+      const done = track(authoritative, checked);
+      if (!done) return null;
+      untrack(done);
+      return checked;
+    },
+    // rebase(authoritative with checked ops applied, options), without copying
+    // the whole value: the ops change authoritative in place, and page state
+    // follows slot by slot when slotsOf allows, or does not move when the ops
+    // are this tab's own pending ops coming back. Anything else rebuilds, as
+    // rebase does. Listeners get prev only when they read it, and before(path)
+    // for what one path held. next is authoritative itself, changed in place by
+    // later frames: a listener copies what it keeps; prev is its own copy.
+    rebaseOps(ops, { source = "remote", confirmed = 0, through, frame = null, room = null, cause = null } = {}) {
+      const done = track(authoritative, ops);
+      if (!done) return false;
+      const kept = through === undefined ? pending.slice(confirmed) : pending.filter((entry) => entry.id > through);
+      const dropped = pending.length - kept.length;
+      const whole = done.some((rec) => rec.at === null);
+      const own = coherent && !whole && dropped === ops.length && ops.every((op, i) => sameOp(op, pending[i].op));
+      const slots = coherent && !own && dropped === 0 ? slotsOf(done, kept, state) : null;
+      if (!own && !slots) {
+        untrack(done);
+        return rebase(applyOps(cloneJson(authoritative), ops), { source, confirmed, through, frame, room, cause });
+      }
+      pending = kept;
+      let changed = false;
+      for (const slot of slots ?? []) {
+        const at = slot.into;
+        if (slot.has) {
+          const value = slot.at[slot.key];
+          if (!slot.had || serializeLive(slot.old) !== serializeLive(value)) changed = true;
+          const cur = slot.had ? at[slot.key] : undefined;
+          const next = cloneJson(value);
+          const same = isContainer(cur) && isContainer(next) && Array.isArray(cur) === Array.isArray(next);
+          Object.defineProperty(at, slot.key, { value: same ? assignDeep(cur, next) : next, enumerable: true, writable: true, configurable: true });
+        } else if (slot.had) {
+          changed = true;
+          delete at[slot.key];
         }
       }
-      if (serializeLive(state) !== before) emit(source, null);
+      let prior = null;
+      const prev = () => (prior ??= priorOf(done));
+      const shifted = done.some((rec) => Array.isArray(rec.at) && rec.kind !== "put");
+      const before = (path) => {
+        if (shifted) return readPath(prev(), path);
+        for (const rec of done) {
+          if (!overlaps(rec.path, path)) continue;
+          if (rec.path.length > path.length) return readPath(prev(), path);
+          return readPath(rec.old, path.slice(rec.path.length));
+        }
+        return readPath(authoritative, path);
+      };
+      tell({ source, frame, room, cause, get prev() { return prev(); }, before, next: authoritative });
+      if (changed) emit(source, null);
       return true;
     },
     // Every rebase, whether or not the value page code sees changed, with what

package/src/loader-logic.js

@@ -31,6 +31,7 @@ export const PLUGIN_PATHS = {
   // A live JSON tag as an in-memory object (clay.live). Not editOnly: a reader's
   // tab still shows the game, and its writes stay in that tab.
   live:      { path: "plugins/live.js",           editOnly: false, default: false },
+  page:      { path: "plugins/page.js",           editOnly: true,  default: false },
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "plugins/cms.js",             editOnly: false, default: false },
@@ -59,6 +60,9 @@ export const PLUGIN_PATHS = {
   // it replaces. `exclude=source` turns it off.
   source:    { path: "plugins/source.js",          editOnly: true,  default: true },
   "visitor-drafts": { path: "plugins/visitor-drafts.js", editOnly: false, default: false },
+  // The sapjs core. Loaded for any page with a [sap] root at boot (resolveModules'
+  // hasSap), in view mode too: a reader's tab paints the same totals.
+  derive:    { path: "plugins/derive.js",          editOnly: false, default: false },
 };
 
 // One literal import per module the loader can ask for, so a bundler can see the
@@ -96,6 +100,7 @@ export const MODULES = {
   "plugins/indicator.js":       () => import("./plugins/indicator.js"),
   "sync/live-sync.js":          () => import("./sync/live-sync.js"),
   "plugins/live.js":            () => import("./plugins/live.js"),
+  "plugins/page.js":            () => import("./plugins/page.js"),
   "plugins/sortable.js":        () => import("./plugins/sortable.js"),
   "plugins/undo.js":            () => import("./plugins/undo.js"),
   "plugins/cms.js":             () => import("./plugins/cms.js"),
@@ -108,11 +113,12 @@ export const MODULES = {
   "plugins/demo.js":            () => import("./plugins/demo.js"),
   "plugins/visitor-drafts.js": () => import("./plugins/visitor-drafts.js"),
   "plugins/source.js":          () => import("./plugins/source.js"),
+  "plugins/derive.js":          () => import("./plugins/derive.js"),
 };
 
 // `source` is last on purpose: its install captures a save clone, so it wants every
 // plugin that registers a document transform to have registered it first.
-const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "people", "cms", "sync", "live", "message", "wire", "ai-edit", "demo", "source"];
+const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "people", "cms", "sync", "live", "page", "message", "wire", "ai-edit", "demo", "derive", "source"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through
 // a capability lookup (`clay.quickcrop`) and silently uploads the raw file when it
@@ -134,7 +140,12 @@ const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "un
 // that asks for it has to have the wire. The wire loads first in the order above.
 // It does not bring undo: hyper-undo takes Cmd+Z for the whole window, text fields
 // included, which a page that never asked for it should not get by default.
-const IMPLIES = { cms: ["quickcrop", "upload"], "ai-edit": ["wire"] };
+// A page's peers reach it through live sync's stream (live/stream-bridge.js), so
+// a Document without sync saves whole files and never sees another tab type. Its
+// image and file blocks send through `clay.upload`: without the plugin every drop
+// ends in "File uploads are not available", while with it a host that stores no
+// files answers `unsupported` and the editor offers to embed the file instead.
+const IMPLIES = { cms: ["quickcrop", "upload"], "ai-edit": ["wire"], page: ["live", "sync", "upload"] };
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);
@@ -152,13 +163,13 @@ function parseCsv(params, key, enabled, apply) {
 
 // Each of these talks to the host or writes outside the visitor's own record, so a
 // page that keeps its edits in this browser cannot carry them.
-const DRAFT_DROPS = ["sync", "live", "upload", "quickcrop", "cms", "people", "wire", "ai-edit", "demo", "source"];
+const DRAFT_DROPS = ["sync", "live", "page", "upload", "quickcrop", "cms", "people", "wire", "ai-edit", "demo", "source"];
 
 // [refetch-on-save] swaps its element for a fresh GET of the same URL after every
 // save, which on a visitor's own draft is a request to the host.
 const DRAFT_DROPS_CORE = ["attrs/refetch-on-save.js"];
 
-export function resolveModules(params, isEditMode, { isDraftMode = false } = {}) {
+export function resolveModules(params, isEditMode, { isDraftMode = false, hasSap = false } = {}) {
   const core = [...CORE_WAVES.always];
   if (isEditMode) core.push(...CORE_WAVES.editOnly);
 
@@ -171,6 +182,7 @@ export function resolveModules(params, isEditMode, { isDraftMode = false } = {})
   for (const [name, spec] of Object.entries(PLUGIN_PATHS)) {
     if (spec.default) enabled.add(name);
   }
+  if (hasSap) enabled.add("derive");
   // ai-edit cannot run without the wire, so excluding the wire excludes it too.
   if (excluded.has("wire")) enabled.delete("ai-edit");
   // A default-on plugin that this mode drops brings nothing with it. An explicitly

package/src/loader.js

@@ -2,6 +2,10 @@ import { resolveModules, MODULES } from "./loader-logic.js";
 import onDomReady from "./lib/dom-ready.js";
 import { initTheme } from "./ui/theme.js";
 import { ephemeral } from "./lib/ephemeral.js";
+import { effect } from "./lib/effect.js";
+import { style } from "./lib/style.js";
+import { derived } from "./lib/derived.js";
+import { bootPhase } from "./core/boot-phase.js";
 
 function domReady() {
   return new Promise((resolve) => onDomReady(resolve));
@@ -34,7 +38,9 @@ export async function boot(base, params, readyResolve) {
 
   const { isDraftMode } = editMode;
 
-  const plan = resolveModules(params, isEditMode, { isDraftMode });
+  const hasSap = Boolean(document.querySelector("[sap]"));
+  bootPhase.holdSettle = hasSap && isEditMode;
+  const plan = resolveModules(params, isEditMode, { isDraftMode, hasSap });
   const loaded = {};
 
   for (const path of plan.core) {
@@ -68,11 +74,36 @@ export async function boot(base, params, readyResolve) {
   // clay.ready until they finish. allSettled: a failed plugin degrades, never blocks boot.
   await Promise.allSettled(plan.plugins.map((path) => loaded[path]?.ready).filter(Boolean));
 
+  if (hasSap) mountDerivedEngine(loaded);
+
   installViewModeNotice(isEditMode);
   readyResolve(window.clay);
   document.dispatchEvent(new CustomEvent("clay:ready", { detail: { clay: window.clay } }));
 }
 
+// The explicit mount phase for a derive engine (sapjs or its core). It runs after
+// frozen regions recorded their authored markup (save-freeze, core wave) and
+// visitor drafts were restored (plugins), so the first pass paints the page those
+// produced, and the held boot baseline settles on that painted page. Sap.mount()
+// skips roots already mounted, so sapjs's own later mount at clay.ready is a no-op.
+export function mountDerivedEngine(loaded) {
+  const save = loaded["core/save.js"];
+  let fileSignature = null;
+  try {
+    fileSignature = save ? save.currentPaintSignature() : null;
+  } catch (err) {
+    console.error("clayjs: could not read the page's painted values:", err);
+  }
+  try {
+    if (window.Sap && typeof window.Sap.mount === "function") window.Sap.mount();
+  } catch (err) {
+    console.error("clayjs: the derive engine failed to mount:", err);
+  } finally {
+    save?.releaseBootSettle();
+  }
+  if (save && fileSignature != null) save.schedulePaintHeal(fileSignature);
+}
+
 function assembleCore(loaded, { isDraftMode, isEditMode, isOwner, siteVisibility }, regionPolicy) {
   const clay = window.clay;
 
@@ -98,6 +129,9 @@ function assembleCore(loaded, { isDraftMode, isEditMode, isOwner, siteVisibility
   clay.readData = pageData.readData;
   clay.writeData = pageData.writeData;
   clay.ephemeral = ephemeral;
+  clay.derived = derived;
+  clay.effect = effect;
+  clay.style = style;
 
   if (save) {
     const saveFn = save.savePage || save.default;
@@ -133,6 +167,8 @@ function attachPluginMember(path, mod, loaded) {
     loaded["core/page-data.js"].setPageDataLiveSync(mod.liveSync);
   } else if (path === "plugins/live.js") {
     clay.live = mod.live;
+  } else if (path === "plugins/page.js") {
+    clay.page = mod.page;
   } else if (path === "plugins/cms.js") {
     clay.cms = mod.cms || mod.default;
   } else if (path === "plugins/upload.js") {

package/src/page/address.js

@@ -0,0 +1,20 @@
+const SAFE_SCHEME = /^(https?:|mailto:|tel:)/i;
+
+export function safeHref(raw) {
+  const s = String(raw ?? "").trim().replace(/[\u0000-\u001f\u007f]/g, "");
+  if (!s) return null;
+  if (s.startsWith("#") || (s.startsWith("/") && !s.startsWith("//"))) return s;
+  if (SAFE_SCHEME.test(s)) return s;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(s)) return null;
+  if (/^(\/\/)?[\w-]+(\.[\w-]+)+(:\d+)?([/?#]\S*)?$/.test(s)) return `https://${s.replace(/^\/\//, "")}`;
+  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)) return `mailto:${s}`;
+  return null;
+}
+
+export const safeSrc = (s) => (s && /^data:image\/(png|jpeg|gif|webp);/i.test(s) && s.length <= 2_100_000 ? s : safeHref(s));
+
+export function safeFileHref(raw) {
+  if (typeof raw !== "string") return null;
+  const href = safeHref(raw);
+  return href && /^(https?:|\/(?!\/))/i.test(href) ? href : null;
+}

package/src/page/adopt-boot.js

@@ -0,0 +1,189 @@
+// When a hand-edited article is adopted: the file read at boot, before the
+// editor mounts into the article, and every newer file that arrives. Only the
+// checkpoint writer adopts (two adopters would both land the same splice). While
+// an adoption waits for the binding or an IME composition, autosave is held, so
+// a checkpoint cannot save the old article over the edit first.
+import { suspendAutosave, resumeAutosave } from "../core/save.js";
+import { history } from "../vendor/prosemirror.vendor.js";
+import { ADOPT, classifyFile, planAdoption, adoptionTransaction, readBack } from "./adopt.js";
+import { mergePageModels } from "./merge.js";
+import { blockMap } from "./model.js";
+import { parseModel } from "./projection.js";
+import { ARTICLE, pageTags } from "./save-projection.js";
+import { HyperMorph } from "../vendor/hyper-morph.vendor.js";
+
+const parseTag = (text) => { try { return HyperMorph.parseJsonRelaxed(text); } catch { return null; } };
+
+export function readFile(root) {
+  const article = root.querySelector(ARTICLE);
+  return article ? { article: article.cloneNode(true), tags: pageTags(root).map((el) => parseTag(el.textContent)) } : null;
+}
+
+export function compositionIdle(view) {
+  return new Promise((resolve) => {
+    if (!view.composing) return resolve();
+    view.dom.addEventListener("compositionend", () => setTimeout(() => resolve(compositionIdle(view)), 0), { once: true });
+  });
+}
+
+export function installAdoption({
+  view,
+  source = null,
+  ready = Promise.resolve(),
+  isAdopter = () => true,
+  idle = () => compositionIdle(view),
+  requestCheckpoint = () => {},
+  notice = () => {},
+  snapshot = () => null,
+  mergeTagless = false,
+  writerReady = () => Promise.resolve(),
+  adopted = () => {},
+  hold = suspendAutosave,
+  release = resumeAutosave,
+  holdMs = 10_000,
+  doc = document,
+}) {
+  let last = source ? source.article.innerHTML : null;
+  // A host that keeps no page data (HTML Clay) sends files with no page tag. What
+  // this tab saw on disk per data-rev, in the order it saw it: the boot article,
+  // every frame, and every article this tab's own save sent. The base for a frame
+  // is the last of those with its rev, else the last article on disk: an untouched
+  // older copy then merges to nothing, and a hand edit that kept the rev merges in.
+  let disk = source ? source.article : null;
+  const seen = new Map();
+  const record = (article) => {
+    const rev = article.getAttribute("data-rev");
+    if (!rev) return;
+    const list = seen.get(rev) ?? [];
+    seen.delete(rev);
+    seen.set(rev, list);
+    list.push(article);
+    if (list.length > 10) list.shift();
+    if (seen.size > 20) seen.delete(seen.keys().next().value);
+  };
+  if (disk) record(disk);
+  let queue = Promise.resolve();
+  let disposed = false;
+  let cancel;
+  const cancelled = new Promise((resolve) => (cancel = resolve));
+
+  // The hold never outlives the controller, and never lasts past holdMs: an
+  // editor that never settles must not stop every later save.
+  async function waitForEditor() {
+    let timer;
+    const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), holdMs); });
+    try {
+      return await Promise.race([Promise.resolve(ready).then(() => idle()).then(() => "ready"), cancelled.then(() => "disposed"), timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // The editor merged three-way with what the file changed since base.
+  function land(blocks, current, baseItems, incoming) {
+    const merged = mergePageModels(baseItems, current, incoming, { doc, merge3: HyperMorph.merge3, mergeJson: HyperMorph.mergeJson });
+    const lost = merged.conflicts.filter((k) => k.kind === "text" || k.kind === "field");
+    const copy = lost.length ? snapshot() : null;
+    const plan = planAdoption(blocks, merged.items, current);
+    const tr = plan && adoptionTransaction(view.state, plan);
+    if (!tr) return null;
+    view.dispatch(tr);
+    view.dispatch(history.closeHistory(view.state.tr));
+    const counts = { edited: plan.edited.size, created: plan.created.size, deleted: plan.deleted.length, moved: plan.reordered };
+    const { displaced } = tr.getMeta(ADOPT);
+    if (Object.keys(displaced).length) counts.displaced = displaced;
+    if (lost.length) counts.conflicts = lost;
+    if (copy) counts.copy = copy;
+    return counts;
+  }
+
+  async function adopt(file) {
+    if (mergeTagless && !file.tags.length) return adoptTagless(file);
+    const found = classifyFile(file.article, file.tags);
+    if (found.kind === "unbased") console.warn("page: the article and its data changed together; kept the data");
+    if (found.kind !== "adopt" || !isAdopter()) return null;
+    hold();
+    try {
+      const waited = await waitForEditor();
+      if (waited === "timeout") console.warn("page: gave up waiting for the editor; the hand edit was not adopted");
+      if (waited !== "ready" || disposed || !isAdopter()) return null;
+      const blocks = blockMap(view.state.doc);
+      const counts = land(blocks, readBack(blocks, doc), found.baseItems, found.parsed);
+      if (counts) adopted(found.A);
+      return counts;
+    } finally {
+      release();
+    }
+  }
+
+  async function adoptTagless(file) {
+    const rev = file.article.getAttribute("data-rev");
+    const list = (rev && seen.get(rev)) || [];
+    const base = list.at(-1) ?? disk;
+    // An untouched older copy leaves the page as it is.
+    if (list.slice(0, -1).some((article) => article.innerHTML === file.article.innerHTML)) return null;
+    record(file.article);
+    disk = file.article;
+    if (!base) return null;
+    // Only the room's elected writer merges a frame, so it lands once however
+    // many tabs see it; and it lands even when the editor never settles, since
+    // the next save would otherwise write over the edit.
+    hold();
+    try {
+      await writerReady();
+      if (disposed || !isAdopter()) return null;
+      const waited = await waitForEditor();
+      if (waited === "disposed" || disposed || !isAdopter()) return null;
+      const blocks = blockMap(view.state.doc);
+      const current = readBack(blocks, doc);
+      const known = new Map(current.map((item) => [item.id, item]));
+      const parse = (article) => parseModel(article, { seed: article.getAttribute("data-rev") ?? "", known });
+      return land(blocks, current, parse(base), parse(file.article));
+    } finally {
+      release();
+    }
+  }
+
+  function run(file) {
+    queue = queue
+      .then(() => adopt(file))
+      .then((counts) => {
+        if (!counts) return;
+        requestCheckpoint();
+        notice(counts);
+        doc.dispatchEvent(new CustomEvent("clay:page-adopted", { detail: counts }));
+      })
+      .catch((error) => console.error("page: adoption failed", error));
+    return queue;
+  }
+
+  function onFrame(event) {
+    const html = event.detail?.html;
+    if (disposed || typeof html !== "string") return;
+    const file = readFile(new DOMParser().parseFromString(html, "text/html"));
+    if (!file || file.article.innerHTML === last) return;
+    last = file.article.innerHTML;
+    run(file);
+  }
+
+  doc.addEventListener("clay:sync-applied", onFrame);
+  if (source) run(source);
+
+  return {
+    idle: () => queue,
+    // A save of this tab landed: the file holds what it sent, so that article is
+    // the one an outside edit made on the saved file merges against.
+    saved(html) {
+      if (!mergeTagless || typeof html !== "string") return;
+      const article = new DOMParser().parseFromString(html, "text/html").querySelector(ARTICLE);
+      if (!article) return;
+      record(article);
+      disk = article;
+    },
+    dispose() {
+      disposed = true;
+      cancel();
+      doc.removeEventListener("clay:sync-applied", onFrame);
+    },
+  };
+}