@panphora/clayjs 1.15.1 → 1.16.0

package/src/loader.js

@@ -1,22 +1,67 @@
-import { resolveModules, MODULES } from "./loader-logic.js";
+import { resolveModules, MODULES, PLUGIN_PATHS } from "./loader-logic.js";
 import onDomReady from "./lib/dom-ready.js";
-import { initTheme } from "./ui/theme.js";
+import { initTheme } from "./ui/theme-config.js";
 import { ephemeral } from "./lib/ephemeral.js";
+import { storage } from "./lib/doc-storage.js";
+import { trash } from "./lib/trash.js";
 import { effect } from "./lib/effect.js";
 import { style } from "./lib/style.js";
 import { derived } from "./lib/derived.js";
+import { assets } from "./lib/assets.js";
 import { bootPhase } from "./core/boot-phase.js";
+import { mergeEngine } from "./sync/merge-engine.js";
+import { mergeManifests, preloadEntries } from "./lib/preload.js";
+
+// The plugin name a late path announces: the loader's own name-to-path table,
+// read the other way.
+const PLUGIN_NAMES = Object.fromEntries(
+  Object.entries(PLUGIN_PATHS).flatMap(([name, spec]) =>
+    spec.ownerPath ? [[spec.path, name], [spec.ownerPath, name]] : [[spec.path, name]]
+  )
+);
+
+// Every namespace this page imported, boot's plan and a live entry's alike: one record,
+// so an entry skips what boot has and the edit members find their modules.
+const loaded = {};
+
+// clay:plugin-ready fires at most once per plugin per page: boot's late tail and a live
+// entry can both reach the same module.
+const announced = new Set();
+
+function announce(path) {
+  if (announced.has(path)) return;
+  announced.add(path);
+  document.dispatchEvent(new CustomEvent("clay:plugin-ready", { detail: { plugin: PLUGIN_NAMES[path] } }));
+}
+
+// A live entry's hint fetch: the bootstrap's cached one, preloading the plan the entry will
+// import. It lives here, beside the helper, because one more static edge into the reader's
+// graph is one more chunk of every reader's closure.
+const editHints = (loadEditHints, manifest, plan, hasSapJs) => () =>
+  loadEditHints().then((hints) => {
+    preloadEntries(mergeManifests(manifest, hints), [...plan.core, ...plan.plugins, ...plan.late], { isEditMode: true, hasSapJs });
+    return hints;
+  });
 
 function domReady() {
   return new Promise((resolve) => onDomReady(resolve));
 }
 
+// Where this document came from, when it is a copy of a starter template.
+function templateSource() {
+  const meta = document.querySelector('meta[name="hyper-source"]');
+  return meta ? meta.getAttribute("content") : null;
+}
+
 // `base` has been unused since 1.1.0 (the loader imports through MODULES) and
 // stays anyway: /v1/clay.js and /v1/src/loader.js are cached independently, so
 // for a while after a deploy a browser can pair either file with the other's
 // previous release. A call shape that differs between them leaves the page with
-// no clayjs at all.
-export async function boot(base, params, readyResolve) {
+// no clayjs at all. The optional arguments after the third come only from the chunked
+// bootstrap: the manifest a reader downloads, the edit supplement an explicit
+// ?editmode=true page fetched beside it, and the cached fetch of that supplement for
+// every other resolved edit or draft. Their absence means no preloading.
+export async function boot(base, params, readyResolve, manifest = null, supplement = null, loadEditHints = null) {
   initTheme();
   const draftMode = await MODULES["core/draft-mode.js"]();
   draftMode.noteBootParams(params);
@@ -26,7 +71,11 @@ export async function boot(base, params, readyResolve) {
                                                        // would otherwise observe null
 
   const editMode = await MODULES["core/is-edit-mode.js"]();
-  const { isEditMode, isOwner, siteVisibility } = editMode;
+  const { isEditMode, isDraftMode, isOwner, siteVisibility, canEdit } = editMode;
+
+  // A draft saved by its visitor never reaches the host, and hostMeta() answers
+  // bareHost() for it, so the request would fetch an answer nothing reads.
+  if (isEditMode && !isDraftMode) import("./core/host-permission.js").then((m) => m.checkHostPermission()).catch(() => {});
 
   // richclay's vendor build detects edit mode via this legacy global; set it
   // before any plugin import so its autoInit sees the right value. Overwrite
@@ -36,19 +85,67 @@ export async function boot(base, params, readyResolve) {
 
   const regionPolicy = await MODULES["lib/region-policy.js"]();
 
-  const { isDraftMode } = editMode;
-
   const hasSap = Boolean(document.querySelector("[sap]"));
+  // derive.js imports the sapjs core only when no sap.js script took the page over.
+  const hasSapJs = Boolean(document.querySelector('script[src*="sap.js"]'));
   bootPhase.holdSettle = hasSap && isEditMode;
-  const plan = resolveModules(params, isEditMode, { isDraftMode, hasSap });
-  const loaded = {};
+  const plan = resolveModules(params, isEditMode, { isDraftMode, hasSap, canEdit, templateSource: templateSource() });
+  // Where edits land, resolved once: a visitor draft saves into its draft slot, the
+  // demo plugin into localStorage, and everything else to the host. setMode takes no
+  // destination, and V4 has no draft-to-host transition.
+  if (plan.plugins.includes("plugins/demo.js")) editMode.commitModeFacts({ destination: "demo" });
+  preloadEntries(mergeManifests(manifest, supplement), [...plan.core, ...plan.plugins], { isEditMode, isDraftMode, hasSapJs });
+  // A resolved initial edit or draft fetches the release's hint index, whether or not
+  // the URL announced it. It lands beside preparation and only ever adds modulepreloads:
+  // a failed fetch defers hints, never an import already mapped.
+  if ((isEditMode || isDraftMode) && !supplement && loadEditHints) {
+    loadEditHints()
+      .then((hints) => preloadEntries(mergeManifests(manifest, hints), [...plan.core, ...plan.plugins], { isEditMode, isDraftMode, hasSapJs }))
+      .catch(() => {});
+  }
+  // Not awaited by boot: an entry that overlaps the tail waits on this rather than
+  // import the same paths a second time.
+  let settleLate;
+  const lateDone = new Promise((resolve) => { settleLate = resolve; });
+  // The reader's transport choice comes from the plan just resolved, never from the
+  // URL: when generic sync loaded, it owns the saved lane and the reader follows
+  // the frames it applies rather than opening a second stream.
+  const readerOptions = { sync: plan.plugins.includes("sync/live-sync.js") };
 
   for (const path of plan.core) {
     loaded[path] = await MODULES[path](); // sequential: order is load-bearing
+    // The loader starts what it imports: a target that exports `install` gets it called
+    // here, once, in this order. A module another road reaches (a live switch, a second
+    // entry) then reuses that same installation instead of adding a second one.
+    loaded[path].install?.();
   }
 
-  assembleCore(loaded, { isDraftMode, isEditMode, isOwner, siteVisibility }, regionPolicy); // window.clay MUST be assembled
-                                                               // before any plugin import
+  assembleCore(loaded, { isDraftMode, isOwner, siteVisibility }, regionPolicy);
+  attachEditCore(loaded); // window.clay MUST be assembled before any plugin import
+  // A document that signs the live-switch contract hands its boot to the mode dispatcher.
+  // Nothing is fetched for it here: the decision and the controller behind it wait for the
+  // first switch, so this costs a reader with a declaration no more than one attribute.
+  if (document.documentElement.getAttribute("clay-mode-switch") === "live") {
+    const editing = resolveModules(params, true, { isDraftMode, hasSap, canEdit, templateSource: templateSource() });
+    loaded["core/edit-mode.js"].noteLiveSwitch({
+      edit: editing,
+      // The plan a view boot would have resolved, not the edit plan this boot resolved: an
+      // exit imports it and starts its reader, and an edit-only module belongs to the
+      // session being left.
+      view: resolveModules(params, false, { isDraftMode, hasSap, canEdit, templateSource: templateSource() }),
+      loaded,
+      modules: MODULES,
+      attach: attachPluginMember,
+      attachEditCore,
+      announce,
+      loadEditHints: loadEditHints ? editHints(loadEditHints, manifest, editing, hasSapJs) : null,
+      late: lateDone,
+    });
+  }
+  // An explicit initial edit drains the preboot participant queue and enables its
+  // leases before a plugin can take input. A reader returns at the first line.
+  await loaded["core/edit-mode.js"].activateInitialMode();
+  window.clay.plugins = Object.freeze([...plan.plugins, ...plan.late].map((path) => PLUGIN_NAMES[path]));
 
   for (const path of plan.plugins) {
     // A plugin that throws on evaluation degrades to absent. Unguarded, its
@@ -64,6 +161,7 @@ export async function boot(base, params, readyResolve) {
       continue;
     }
     loaded[path] = mod;
+    if (path === "plugins/page-view.js") mod.start(readerOptions);
     attachPluginMember(path, mod, loaded); // immediately, not after the loop: hypercms's ?cms=true
                                      // auto-open runs as a microtask queued during ITS evaluation
                                      // (before boot resumes) and reads clay.RichClay and clay.undo,
@@ -76,9 +174,50 @@ export async function boot(base, params, readyResolve) {
 
   if (hasSap) mountDerivedEngine(loaded);
 
-  installViewModeNotice(isEditMode);
+  installViewModeNotice(editMode);
   readyResolve(window.clay);
   document.dispatchEvent(new CustomEvent("clay:ready", { detail: { clay: window.clay } }));
+  if (plan.late.length) loadLate(plan.late, editMode).then(settleLate, settleLate);
+  else settleLate();
+}
+
+// An edit-only plugin belongs to the edit session that resolved it. Once the page has
+// left edit, importing it would start an editor in a view, so the tail drops it instead:
+// the module is not fetched, not attached and not announced. Dropping is not a reload —
+// nothing is re-imported with a cache-busting URL, and a later entry asks the module
+// cache for the same single instance.
+//
+// A transition in flight counts as left: until it commits, `isEditMode` still reads the
+// mode being left, and a module that evaluated then would start an unadopted session. The
+// modules ask the same question themselves (`startsAtImport`), so an import already in
+// flight when the exit began starts nothing either.
+const stale = (path, editMode) =>
+  PLUGIN_PATHS[PLUGIN_NAMES[path]]?.editOnly && !editMode.startsAtImport();
+
+// Plugins no first paint or keystroke waits for. They load after the editor takes input
+// (right away on a page without one), one at a time and in plan order, and a failure
+// degrades to absent as at boot.
+async function loadLate(paths, editMode) {
+  try {
+    await window.clay.page?.ready;
+  } catch {}
+  for (const path of paths) {
+    if (stale(path, editMode)) continue;
+    try {
+      const mod = await MODULES[path]();
+      // The session can end while the fetch is in flight, so ask again before the module
+      // is given a page to wire itself into.
+      if (stale(path, editMode)) continue;
+      loaded[path] = mod;
+      attachPluginMember(path, mod, loaded);
+      await mod.ready;
+      if (stale(path, editMode)) continue;
+      announce(path);
+    } catch (err) {
+      console.error(`clayjs: plugin "${path}" failed to load, continuing without it:`, err);
+      document.dispatchEvent(new CustomEvent("clay:plugin-failed", { detail: { plugin: PLUGIN_NAMES[path] } }));
+    }
+  }
 }
 
 // The explicit mount phase for a derive engine (sapjs or its core). It runs after
@@ -104,7 +243,7 @@ export function mountDerivedEngine(loaded) {
   if (save && fileSignature != null) save.schedulePaintHeal(fileSignature);
 }
 
-function assembleCore(loaded, { isDraftMode, isEditMode, isOwner, siteVisibility }, regionPolicy) {
+function assembleCore(loaded, { isDraftMode, isOwner, siteVisibility }, regionPolicy) {
   const clay = window.clay;
 
   const mutation = loaded["lib/mutation.js"];
@@ -112,63 +251,106 @@ function assembleCore(loaded, { isDraftMode, isEditMode, isOwner, siteVisibility
 
   Object.assign(clay, {
     toggleEditMode: editModeMod.toggleEditMode,
+    setMode: editModeMod.setMode,
+    modeLifecycle: editModeMod.modeLifecycle,
     isDraftMode,
-    isEditMode,
     isOwner,
     siteVisibility,
     Mutation: mutation.default,
     region: regionPolicy.windowRegionShape,
   });
 
-  const snapshot = loaded["core/snapshot.js"];
-  const save = loaded["core/save.js"];
-  const cacheBustMod = loaded["lib/cache-bust.js"];
-  const hyperMorph = loaded["vendor/hyper-morph.vendor.js"];
+  // Getters over the live mode facts, never copies: the lifecycle commits a new mode
+  // and these read it back, so `clay.mode` stays a string that cannot go stale.
+  for (const key of ["mode", "isEditMode", "canEdit"]) {
+    Object.defineProperty(clay, key, { get: () => editModeMod[key], enumerable: true, configurable: true });
+  }
+
+  clay.assets = assets;
+
   const pageData = loaded["core/page-data.js"];
 
   clay.readData = pageData.readData;
   clay.writeData = pageData.writeData;
   clay.ephemeral = ephemeral;
+  clay.storage = storage;
+  // About the document rather than the page, and asked for on use: a reader never
+  // downloads the discovery client for it.
+  clay.host = {
+    get versions() {
+      return import("./core/host-meta.js").then((m) => m.hostVersions());
+    },
+  };
+  clay.trash = trash;
   clay.derived = derived;
   clay.effect = effect;
   clay.style = style;
+  clay.morph = (oldEl, newEl, options) => mergeEngine().then(({ morph }) => morph(oldEl, newEl, options));
+}
+
+// The edit half of the assembly: boot runs it right after the always half, and a live entry
+// runs it once its edit core has landed. It adds what those modules offer and replaces
+// nothing already there, so a member a reader attached first survives.
+function attachEditCore(loaded) {
+  const clay = window.clay;
 
+  const save = loaded["core/save.js"];
   if (save) {
     const saveFn = save.savePage || save.default;
     saveFn.force = save.savePageForce;
     saveFn.overwrite = save.saveOverwritingConflict;
     saveFn.flush = save.flushSave;
-    clay.save = saveFn;
+    saveFn.soon = save.savePageSoon;
+    // What the host says it will store, and a measurement of candidate bytes. Both
+    // are asked for on use: a reader has neither, and a page that never asks pays
+    // nothing.
+    saveFn.limits = save.saveLimits;
+    saveFn.inspect = save.inspectSaveSize;
+    // An upgrade-capable reader's temporary save object hands its `replace` to the function.
+    if (clay.save !== saveFn && typeof clay.save?.replace === "function") saveFn.replace = clay.save.replace;
+    if (clay.save !== saveFn) clay.save = saveFn;
   }
   // The close warning's own predicate, reachable without a capture. It falls back to
   // false rather than to absent: the module is edit-only, and a document that cannot
   // save has nothing unsaved. Older clayjs has no such member, and that is the answer
   // a host feature-detects.
-  clay.hasUnsavedChanges = loaded["core/unsaved-warning.js"]?.hasUnsavedChanges ?? (() => false);
+  clay.hasUnsavedChanges =
+    loaded["core/unsaved-warning.js"]?.hasUnsavedChanges ?? clay.hasUnsavedChanges ?? (() => false);
+  const snapshot = loaded["core/snapshot.js"];
   if (snapshot) {
-    clay.getHTML = snapshot.getPageContents;
-    clay.addDocumentTransform = snapshot.addDocumentTransform;
-    clay.onSnapshot = snapshot.onSnapshot;
+    if (!clay.getHTML) clay.getHTML = snapshot.getPageContents;
+    if (!clay.addDocumentTransform) clay.addDocumentTransform = snapshot.addDocumentTransform;
+    if (!clay.onSnapshot) clay.onSnapshot = snapshot.onSnapshot;
   }
-  if (cacheBustMod) {
+  const cacheBustMod = loaded["lib/cache-bust.js"];
+  if (cacheBustMod && !clay.cacheBust) {
     clay.cacheBust = cacheBustMod.default;
   }
-  if (hyperMorph) clay.morph = hyperMorph.morph;
+  // Edit mode only, and absent entirely in view mode: a reader has nothing to
+  // recover and must never open the database. The facade is here; the store behind
+  // it arrives when the page's first adapter registers a channel.
+  const recoveryMod = loaded["core/recovery.js"];
+  if (recoveryMod && !clay.recovery) clay.recovery = recoveryMod.recovery;
 }
 
-function attachPluginMember(path, mod, loaded) {
+function attachPluginMember(path, mod, namespaces = loaded) {
   const clay = window.clay;
 
   if (path === "plugins/undo.js") {
     clay.undo = mod.undo || mod.default;
+  } else if (path === "plugins/unsent.js") {
+    clay.unsent = mod.unsent;
   } else if (path === "sync/live-sync.js") {
     clay.morph = mod.morph;
     clay.conflicts = mod.conflicts;
-    loaded["core/page-data.js"].setPageDataLiveSync(mod.liveSync);
+    namespaces["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/upgrade.js") {
+    clay.save = clay.save || {};
+    clay.save.replace = mod.replace;
   } else if (path === "plugins/cms.js") {
     clay.cms = mod.cms || mod.default;
   } else if (path === "plugins/upload.js") {
@@ -189,17 +371,23 @@ function attachPluginMember(path, mod, loaded) {
     clay.RichClay = mod.RichClay || mod.default;
   } else if (path === "plugins/quickcrop.js") {
     clay.quickcrop = mod.quickcrop || mod.default;
+  } else if (path === "plugins/sortable.js") {
+    // With the module, not with its vendor: a move answers before a drag can start.
+    clay.sortable = mod.sortable;
   } else if (path === "plugins/source.js") {
     clay.source = mod.source || mod.default;
-  } else if (path === "plugins/visitor-drafts.js") {
+  } else if (path === "plugins/visitor-drafts.js" || path === "plugins/visitor-drafts-owner.js") {
     clay.visitorDrafts = mod.visitorDrafts;
+  } else if (path === "plugins/bind-text.js") {
+    clay.bindText = mod.bindText;
   }
 }
 
-function installViewModeNotice(isEditMode) {
-  if (isEditMode) return;
+function installViewModeNotice(editMode) {
+  if (editMode.isEditMode) return;
   document.addEventListener("click", (event) => {
     if (!event.target.closest?.("[trigger-save]")) return;
+    if (editMode.isEditMode) return;
     console.info("clayjs: you're not the owner of this page; changes stay local");
     document.dispatchEvent(new CustomEvent("clay:view-save-attempt"));
   });

package/src/page/adopt-boot.js

@@ -10,9 +10,27 @@ 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";
+import { parseJsonRelaxed } from "../vendor/hyper-morph-json.vendor.js";
+import { loadedEngine, mergeEngine } from "../sync/merge-engine.js";
 
-const parseTag = (text) => { try { return HyperMorph.parseJsonRelaxed(text); } catch { return null; } };
+const parseTag = (text) => { try { return parseJsonRelaxed(text); } catch { return null; } };
+
+// What one adoption attempt did, so a caller can tell a landed adoption from a
+// stopped, refused or failed one. `ok` is true only when the store holds the
+// accepted state afterwards, whether that meant splicing the file in or finding
+// nothing to splice.
+const UNCHANGED = { ok: true, outcome: "unchanged" };
+const STOPPED = { ok: false, outcome: "disposed", reason: "adoption-disposed" };
+const REFUSED = { ok: false, outcome: "refused", reason: "adoption-refused" };
+const TIMED_OUT = { ok: false, outcome: "refused", reason: "adoption-timeout" };
+const FAILED = { ok: false, outcome: "error", reason: "adoption-error" };
+// Another tab holds the room's writer seat: the adoption is that tab's to land,
+// and it reaches this one through the room. Not a refusal, and not a success yet.
+const AWAITED = { ok: true, outcome: "writer-adopts" };
+const landed = (counts) => ({ ok: true, outcome: "adopted", counts });
+
+// The bound on adoption, and on waiting for the elected writer's adoption.
+export const ADOPTION_TIMEOUT_MS = 10_000;
 
 export function readFile(root) {
   const article = root.querySelector(ARTICLE);
@@ -40,7 +58,7 @@ export function installAdoption({
   adopted = () => {},
   hold = suspendAutosave,
   release = resumeAutosave,
-  holdMs = 10_000,
+  holdMs = ADOPTION_TIMEOUT_MS,
   doc = document,
 }) {
   let last = source ? source.article.innerHTML : null;
@@ -81,6 +99,7 @@ export function installAdoption({
 
   // The editor merged three-way with what the file changed since base.
   function land(blocks, current, baseItems, incoming) {
+    const { HyperMorph } = loadedEngine();
     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;
@@ -101,16 +120,25 @@ export function installAdoption({
     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;
+    if (found.kind !== "adopt") return UNCHANGED;
+    // Only the room's writer adopts, so another tab's write is this tab's adoption
+    // too: it arrives through the room, and the caller waits for it there.
+    if (!isAdopter()) return AWAITED;
     hold();
     try {
+      await mergeEngine();
+      if (disposed) return STOPPED;
+      if (!isAdopter()) return REFUSED;
       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;
+      if (waited === "disposed" || disposed) return STOPPED;
+      if (waited !== "ready") return TIMED_OUT;
+      if (!isAdopter()) return REFUSED;
       const blocks = blockMap(view.state.doc);
       const counts = land(blocks, readBack(blocks, doc), found.baseItems, found.parsed);
-      if (counts) adopted(found.A);
-      return counts;
+      if (!counts) return UNCHANGED;
+      adopted(found.A);
+      return landed(counts);
     } finally {
       release();
     }
@@ -121,39 +149,60 @@ export function installAdoption({
     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;
+    if (list.slice(0, -1).some((article) => article.innerHTML === file.article.innerHTML)) return UNCHANGED;
     record(file.article);
     disk = file.article;
-    if (!base) return null;
+    if (!base) return UNCHANGED;
+    // The latest copy again, attributes and all: merging it into the page changes nothing.
+    if (base.outerHTML === file.article.outerHTML) return UNCHANGED;
     // 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 mergeEngine();
+      if (disposed) return STOPPED;
+      if (!isAdopter()) return REFUSED;
       await writerReady();
-      if (disposed || !isAdopter()) return null;
+      if (disposed) return STOPPED;
+      if (!isAdopter()) return REFUSED;
       const waited = await waitForEditor();
-      if (waited === "disposed" || disposed || !isAdopter()) return null;
+      if (waited === "disposed" || disposed) return STOPPED;
+      if (!isAdopter()) return REFUSED;
       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));
+      const counts = land(blocks, current, parse(base), parse(file.article));
+      return counts ? landed(counts) : UNCHANGED;
     } finally {
       release();
     }
   }
 
-  function run(file) {
+  // A failed attempt is an outcome, never a resolved success: the coordinator
+  // decides on `ok`, and the outside world keeps its events and quiet queue.
+  async function attempt(file) {
+    try {
+      return await adopt(file);
+    } catch (error) {
+      console.error("page: adoption failed", error);
+      return FAILED;
+    }
+  }
+
+  let bootOutcome = null;
+  function run(file, boot = false) {
     queue = queue
-      .then(() => adopt(file))
-      .then((counts) => {
-        if (!counts) return;
+      .then(() => attempt(file))
+      .then((outcome) => {
+        if (boot) bootOutcome = outcome;
+        if (!outcome.ok || outcome.outcome !== "adopted") return outcome;
         requestCheckpoint();
-        notice(counts);
-        doc.dispatchEvent(new CustomEvent("clay:page-adopted", { detail: counts }));
-      })
-      .catch((error) => console.error("page: adoption failed", error));
+        notice(outcome.counts);
+        doc.dispatchEvent(new CustomEvent("clay:page-adopted", { detail: outcome.counts }));
+        return outcome;
+      });
     return queue;
   }
 
@@ -167,10 +216,15 @@ export function installAdoption({
   }
 
   doc.addEventListener("clay:sync-applied", onFrame);
-  if (source) run(source);
+  if (source) run(source, true);
 
   return {
-    idle: () => queue,
+    // Resolves once everything queued so far has been attempted, with the boot
+    // file's own outcome: landed, unchanged, stopped, refused or failed.
+    idle: async () => {
+      await queue;
+      return bootOutcome;
+    },
     // 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) {

package/src/page/adopt.js

@@ -9,7 +9,8 @@
 // Cmd+Z takes the whole adoption back.
 import { model as pmModel, history } from "../vendor/prosemirror.vendor.js";
 import { blockMap, nodeFromBlock, repairSiblings } from "./model.js";
-import { project, canon, revOf, parseModel, renderModel, fragmentCleaner } from "./projection.js";
+import { DEFAULTS, project, canon, revOf, parseModel, renderModel, fragmentCleaner, unitsOf } from "./projection.js";
+import { unflatten } from "./inline.js";
 import { blocksFromPageValues } from "./ybind/decode.js";
 
 export const ADOPT = "page-adopt";
@@ -56,7 +57,7 @@ export function blockFromItem(item, cur) {
   const { id, t, ...fields } = item;
   const out = { t, pos: cur?.pos ?? null };
   Object.assign(out, fields);
-  if (t === "table" && !fields.rows.length) fields.rows = [{ id: `r-${id}`, cells: {} }];
+  if (t === "table" && !fields.rows.length && fields.cols.length) fields.rows = [{ id: `r-${id}`, cells: {} }];
   if (t === "table") {
     out.cols = keyed(fields.cols, cur?.cols, "c", ({ id: _i, ...c }) => c);
     out.rows = keyed(fields.rows, cur?.rows, "r", ({ id: _i, cells, pos }) => ({ pos, cells }));
@@ -74,6 +75,23 @@ export function blockFromItem(item, cur) {
 
 // ---- the transaction ---------------------------------------------------------
 
+// A block type this runtime has no schema for keeps its whole record in the
+// inert node, and its text for mapping.
+const opaqueNode = (schema, id, block) => {
+  const { t, pos, c, m, ...raw } = block;
+  const content = typeof c === "string" && c ? unflatten(schema, c, unitsOf(m, c.length), schema.nodes.opaque_block) : null;
+  return schema.nodes.opaque_block.create({ id, pos, raw: { t, ...raw } }, content);
+};
+
+// The editor’s blocks as the article and the record state them: an opaque node
+// stands for the record it carries, never for a block type of its own.
+const recordsOf = (blocks) => Object.fromEntries(Object.entries(blocks).map(([id, b]) => {
+  if (b.t !== "opaque_block") return [id, b];
+  const { t: _t, raw, ...rest } = b;
+  const { t, ...fields } = raw ?? {};
+  return [id, { t: t ?? "paragraph", pos: b.pos, ...fields, ...rest }];
+}));
+
 function find(doc, id) {
   let found = null;
   doc.forEach((node, pos) => { if (!found && node.attrs.id === id) found = { node, pos }; });
@@ -119,7 +137,7 @@ export function adoptionTransaction(state, plan) {
   if (!plan) return null;
   const schema = state.schema;
   const doc = state.doc;
-  const current = blockMap(doc);
+  const current = recordsOf(blockMap(doc));
   const tr = state.tr;
   const projected = new Map(project(current).map((item) => [item.id, item]));
   const displaced = {};
@@ -127,7 +145,10 @@ export function adoptionTransaction(state, plan) {
     const was = plan.base.get(id), now = projected.get(id);
     if (was && now && !same(body(was), body(now))) displaced[id] = current[id];
   }
-  const nodeOf = (id, item) => nodeFromBlock(schema, id, blockFromItem(item, current[id]));
+  const nodeOf = (id, item) => {
+    const block = blockFromItem(item, current[id]);
+    return Object.hasOwn(DEFAULTS, item.t) ? nodeFromBlock(schema, id, block) : opaqueNode(schema, id, block);
+  };
 
   // Adopting into a page that had no blocks: the editor's empty placeholder line
   // goes, after the article's blocks are in (an empty doc would get a new one).