@panphora/clayjs 1.15.1 → 1.16.0

package/src/plugins/ai-edit.js

@@ -41,10 +41,9 @@
  * invisible to the mutation system (its status text changes constantly), absent from
  * every snapshot and from what peers receive.
  */
-import { HyperMorph } from "../vendor/hyper-morph.vendor.js";
-import { mergeTagRecognizers } from "../sync/merge-tags.js";
+import { loadedEngine, mergeEngine } from "../sync/merge-engine.js";
 import Mutation from "../lib/mutation.js";
-import { isEditMode } from "../core/is-edit-mode.js";
+import { startsAtImport } from "../core/is-edit-mode.js";
 import { holdAllSaves, releaseAllSaves } from "../core/save.js";
 import { STRIP_FROM_SAVE, SNAPSHOT_REMOVE_SELECTOR } from "../lib/region-policy.js";
 import { enableContentEditable } from "../core/admin-contenteditable.js";
@@ -81,7 +80,10 @@ let barMode = null;  // "working", "ready", "saving" or "error"
 let barLifecycle = null;
 let barCloseTimer = null;
 let panelPointerDown = false; // the last pointerdown began in the panel: its click is not a page click
-const drafts = new WeakMap();  // compose text a target keeps while the panel is shut
+let drafts = new WeakMap();  // compose text a target keeps while the panel is shut
+// A WeakMap cannot be read back, and an exit has to know whether anything typed here is
+// still unsent, so the targets that hold a draft are counted beside it.
+const drafted = new Set();
 let anchorEl = null;    // element the panel is currently anchored to
 let chipTarget = null;  // unit the hover chip currently points at
 let chipHideTimer = null;
@@ -92,6 +94,24 @@ let selectionTimer = null;
 let anchorRange = null;  // the selection the open panel was raised for
 let returnFocus = null;  // where focus goes back to when the panel closes
 let helperState = null;  // "ready" or "unavailable"
+let listeners = null;    // the AbortController every handler one session added listens on
+let observers = [];      // the page observers that session opened
+let styleEl = null;      // the one stylesheet the chrome needed
+let chromeToken = 0;     // the latest init(); a teardown retires the one before it
+
+function dropDraft(el) {
+  drafts.delete(el);
+  drafted.delete(el);
+}
+
+function keepDraft(el, text) {
+  if (!text) {
+    dropDraft(el);
+    return;
+  }
+  drafts.set(el, text);
+  drafted.add(el);
+}
 
 const HIGHLIGHT = 'clay-ai-edit';
 const OFF_MESSAGE = 'AI editing is turned off. Turn it on from the app’s menu.';
@@ -190,6 +210,7 @@ function strippedBodyHTML() {
 // ---------------------------------------------------------------- morphing
 
 function morphTo(el, content, scripts) {
+  const { HyperMorph } = loadedEngine();
   return HyperMorph.morph(el, content, { morphStyle: 'outerHTML', restoreFocus: true, scripts });
 }
 
@@ -201,6 +222,7 @@ function morphTo(el, content, scripts) {
 // against the snapshot the model saw, so data the user changed mid-flight survives
 // the reply. Rewinds must restore the snapshot exactly, so they disable merging.
 function sessionMorph(s, content, { rewind = false } = {}) {
+  const { HyperMorph, mergeTagRecognizers } = loadedEngine();
   // handle:false: a reply's scripts never run, so the preview cannot execute code
   // before Keep, and neither can a rewind.
   const scripts = rewind
@@ -300,7 +322,7 @@ async function sendRequest(el, comment, quote) {
   }
   // The sent comment is this target's draft until the reply is ready: Error, Stop, a
   // refused reply, a morph failure and a host cancellation all leave it in place.
-  drafts.set(el, comment);
+  keepDraft(el, comment);
   closePanelForSend();
   session.paused = true;
   pauseObservers();
@@ -321,6 +343,9 @@ async function sendRequest(el, comment, quote) {
   session.handle = handle;
   const outcome = await handle.done;
   if (!session || session.handle !== handle) return;
+  // The engine is fetched here, where a reply is applied, not at boot.
+  await mergeEngine();
+  if (!session || session.handle !== handle) return;
   if (outcome.state === 'done') onDone(outcome.result || {});
   else if (outcome.state === 'cancelled') onError('HTML Clay stopped this edit.');
   else onError(outcome.error || 'the helper reported an error');
@@ -417,7 +442,7 @@ function onDone(payload) {
     return;
   }
   positionChrome();
-  drafts.delete(session.el); // delivered: the comment is no longer this target's draft
+  dropDraft(session.el); // delivered: the comment is no longer this target's draft
   showBar('ready');
   setBarStatus(readyText(warnings, payload.model), warnings.length ? 'warn' : '');
 }
@@ -444,7 +469,7 @@ function revertSession() {
   session = null;
   if (!s) return;
   try {
-    if (s.state === 'requesting' || s.state === 'deciding') {
+    if ((s.state === 'requesting' || s.state === 'deciding') && loadedEngine()) {
       sessionMorph(s, s.snapshot, { rewind: true });
     }
   } finally {
@@ -507,15 +532,16 @@ function marked(el, name, value) {
 }
 
 function buildChrome() {
-  const style = document.createElement('style');
-  style.setAttribute('clay', RUNTIME_ONLY);
-  style.textContent = `
+  const { signal } = listeners;
+  styleEl = document.createElement('style');
+  styleEl.setAttribute('clay', RUNTIME_ONLY);
+  styleEl.textContent = `
     [editmode\\:contenteditable][contenteditable]:focus {
       outline: 1px solid #4a4a6a; outline-offset: 4px; border-radius: 2px;
     }
     ::highlight(clay-ai-edit) { background-color: ${TOKENS['brass-soft']} !important; }
   `;
-  document.head.appendChild(style);
+  document.head.appendChild(styleEl);
 
   const scheme = `color-scheme:${pageScheme()}`;
 
@@ -641,24 +667,28 @@ function buildChrome() {
     openPanel(document.body, quoteFromSelection(document.body));
   });
 
-  window.addEventListener('scroll', () => { positionChrome(); hideChip(); }, { passive: true });
-  window.addEventListener('resize', () => { placeBubble(); if (panel && !panel.hidden) fitTextarea(); positionChrome(); }, { passive: true });
+  window.addEventListener('scroll', () => { positionChrome(); hideChip(); }, { passive: true, signal });
+  window.addEventListener('resize', () => { placeBubble(); if (panel && !panel.hidden) fitTextarea(); positionChrome(); }, { passive: true, signal });
   // The CMS toggle can arrive after this chrome, and a docked sidebar slides it left.
   const replace = () => { placeBubble(); positionChrome(); };
-  document.addEventListener('hcms:open', () => { replace(); setTimeout(replace, 350); });
-  document.addEventListener('hcms:close', () => { replace(); setTimeout(replace, 350); });
-  new MutationObserver((records) => {
+  document.addEventListener('hcms:open', () => { replace(); setTimeout(replace, 350); }, { signal });
+  document.addEventListener('hcms:close', () => { replace(); setTimeout(replace, 350); }, { signal });
+  const cmsToggle = new MutationObserver((records) => {
     syncBubble();
     const touched = (nodes) => [...nodes].some((n) => n.nodeType === 1 && n.hasAttribute('data-hcms-toggle-host'));
     if (records.some((r) => touched(r.addedNodes) || touched(r.removedNodes))) replace();
-  }).observe(document.body, { childList: true });
+  });
+  cmsToggle.observe(document.body, { childList: true });
+  observers.push(cmsToggle);
 
   // A target removed from the page ends its edit, so the save hold and the paused
   // observers never outlive it. A running bar is no exception: it is torn down with
   // the target it was describing.
-  new MutationObserver(() => {
+  const targetGone = new MutationObserver(() => {
     if (anchorEl && !anchorEl.isConnected) abandonTarget();
-  }).observe(document.body, { childList: true, subtree: true });
+  });
+  targetGone.observe(document.body, { childList: true, subtree: true });
+  observers.push(targetGone);
 }
 
 // The panel's height changes as the box grows and the status line fills, so it is
@@ -709,6 +739,7 @@ function applyHelperState() {
 // The host's toggle can change while the page is open, so each opening asks again.
 function refreshHelperState() {
   helperStateNow().then((state) => {
+    if (!panel) return; // the session this asked for has ended
     helperState = state || 'unavailable';
     if (!panel.hidden && !session) applyHelperState();
     else syncBubble();
@@ -939,8 +970,7 @@ function openPanel(el, quote) {
 // panel is opened on that target again.
 function storeDraft() {
   if (!anchorEl) return;
-  if (textarea.value) drafts.set(anchorEl, textarea.value);
-  else drafts.delete(anchorEl);
+  keepDraft(anchorEl, textarea.value);
 }
 
 function closePanel() {
@@ -1023,6 +1053,7 @@ function escapeIsMine(event) {
 }
 
 function wireInteractions() {
+  const { signal } = listeners;
   // Clicks: text units are contenteditable (caret) and figures keep their own
   // interactivity, so neither is intercepted, and nothing here prevents the click from
   // landing. Any click on the page away from ClayJS chrome closes the box, a click
@@ -1033,7 +1064,7 @@ function wireInteractions() {
   // box and ends on the page is still the box's, not a click away from it.
   document.addEventListener('pointerdown', (event) => {
     panelPointerDown = panel.contains(event.target);
-  }, { capture: true });
+  }, { capture: true, signal });
 
   document.addEventListener('click', (event) => {
     const startedInPanel = panelPointerDown;
@@ -1050,7 +1081,7 @@ function wireInteractions() {
     } else if (!panel.hidden) {
       closePanel();
     }
-  });
+  }, { signal });
 
   // Hover chip: follows the unit under the cursor while no panel is open.
   let lastMove = 0;
@@ -1064,7 +1095,7 @@ function wireInteractions() {
     const unit = unitFrom(event.target);
     if (unit) showChipFor(unit);
     else scheduleChipHide();
-  });
+  }, { signal });
 
   document.addEventListener('keydown', (event) => {
     if (isShortcut(event)) {
@@ -1094,26 +1125,35 @@ function wireInteractions() {
     if (barMode === 'error') { closeBar(); return; }
     if (barMode) return;
     if (!panel.hidden) closePanel();
-  });
+  }, { signal });
 
   document.addEventListener('selectionchange', () => {
     clearTimeout(selectionTimer);
     selectionTimer = setTimeout(showChipForSelection, 150);
-  });
+  }, { signal });
 }
 
 // ---------------------------------------------------------------- boot
 
-async function init() {
-  if (!isEditMode || panel) return;  // an owner/editor feature, built once
+async function loadHelper() {
+  const token = ++chromeToken;
   helperState = await helperStateNow();
-  // No ai-edit helper on this host: stay dormant. A concurrent open() that got here
-  // first may also have built the chrome already.
+  return token === chromeToken;
+}
+
+function build() {
   if (!helperState || panel) return;
+  listeners = new AbortController();
   buildChrome();
   wireInteractions();
 }
 
+async function init() {
+  if (!startsAtImport() || panel) return;  // an owner/editor feature, built once
+  if (!(await loadHelper())) return;
+  build();
+}
+
 // A target the composer can be opened on: a connected content element of this
 // document. ClayJS chrome, transient UI, everything the save strips and everything
 // that holds no text are not targets.
@@ -1141,11 +1181,106 @@ async function open(el, { prompt } = {}) {
     textarea.focus();
     return true;
   }
-  if (typeof prompt === 'string' && !drafts.has(el)) drafts.set(el, prompt);
+  if (typeof prompt === 'string' && !drafts.has(el)) keepDraft(el, prompt);
   openPanel(el, null);
   return true;
 }
 
-onDomReady(() => { init().catch(() => {}); });
+/**
+ * A committed exit: the chrome, every handler this session added and every page
+ * observer go. What the person typed is a draft, and an exit that could not represent it
+ * never gets here, so nothing unsent is thrown away by this.
+ */
+function teardown() {
+  chromeToken++;
+  const s = session;
+  session = null;
+  try {
+    s?.handle?.cancel();
+    if (s) {
+      if (s.paused) resumeObservers();
+      if (s.held) releaseAllSaves();
+    }
+  } catch {}
+  clearTimeout(selectionTimer);
+  selectionTimer = null;
+  clearTimeout(chipHideTimer);
+  chipHideTimer = null;
+  clearTimeout(barCloseTimer);
+  barCloseTimer = null;
+  clearHighlight();
+  listeners?.abort();
+  listeners = null;
+  for (const observer of observers) observer.disconnect();
+  observers = [];
+  for (const node of [styleEl, ring, panel, bar, chip, docBubble]) node?.remove();
+  styleEl = ring = panel = textarea = statusEl = pointer = bar = barStatus = null;
+  barStop = barKeep = barRevert = barClose = chip = docBubble = null;
+  buttons = {};
+  barMode = null;
+  barLifecycle = null;
+  anchorEl = null;
+  anchorRange = null;
+  returnFocus = null;
+  pendingSelection = undefined;
+  chipTarget = null;
+  chipSelection = undefined;
+  panelPointerDown = false;
+  helperState = null;
+  drafts = new WeakMap();
+  drafted.clear();
+}
+
+/**
+ * ai-edit as a mode lease.
+ *
+ * Preparing this lease asks the host whether it lists a ready helper, which is safe while
+ * the committed mode is still view; the commit that enters edit builds the chrome, inert
+ * until somebody opens it, exactly as `clay.aiEdit.init()` does. What a session adds is
+ * everything still unresolved — a request on the wire, a preview waiting for Keep or
+ * Revert, a comment typed and not sent — so `quiesce` refuses the exit and `resume`
+ * leaves that same preview, comment and selection timer exactly as they were.
+ * `dispose` (after the barrier) stops every editor-only handler and takes the chrome
+ * down, so a save or selection event in view draws nothing. `initial: true` adopts the
+ * chrome the boot's own import built, and asks the host nothing a second time.
+ */
+export function aiEditParticipant() {
+  return {
+    id: "clay:ai-edit",
+    order: 950, // after the wire (900): this request is sent through it
+    prepare(context = {}) {
+      const initial = context.initial === true;
+      return {
+        ready: initial ? boot : loadHelper(),
+        enable() {
+          if (!initial) build();
+        },
+        quiesce() {
+          const unsent = (panel && !panel.hidden && textarea.value.trim() !== '') ||
+            [...drafted].some((el) => el.isConnected);
+          const pending = [];
+          if (session) pending.push(session.id);
+          if (barMode === 'saving') pending.push('save');
+          if (unsent) pending.push('prompt');
+          if (!pending.length) return;
+          throw Object.assign(new Error('clay.aiEdit: an edit here is still unresolved'), {
+            code: 'pending-input',
+            pending,
+          });
+        },
+        resume() {},
+        dispose() {
+          teardown();
+        },
+      };
+    },
+  };
+}
+
+// The boot's own answer, which an explicit edit boot's exit adopts rather than re-asking.
+let boot = null;
+onDomReady(() => { boot = init().then(() => {}, () => {}); });
+
+export { aiEditParticipant as modeParticipant };
 
 export const aiEdit = { init, open };

package/src/plugins/bind-text.js

@@ -0,0 +1,218 @@
+/**
+ * clay.bindText — an editor textarea that lives outside the saved records.
+ *
+ * The textarea sits in a `clay="freeze"` region and edits one record's text
+ * element (for example `<pre><code class="entry-body">`). Every input is
+ * written into the record at once, so a save captures it as the record's text
+ * and a peer's merge of another paragraph keeps both edits. A change to the
+ * record from elsewhere (a peer's merge, a restored draft, a JSON API write) is
+ * shown in the textarea with the caret kept. During an IME composition nothing
+ * is written or shown, and when it ends both edits apply unless they touch the
+ * same stretch of text. Nothing here is Journal-specific: OverType, the
+ * timestamps and the note arrive as callbacks.
+ *
+ * The binding answers for its own lifecycle too: `flush()` reports whether the
+ * record now holds the text and refuses while a composition is running, `open()`
+ * and `close()` honor that refusal, and `dispose()` only detaches once the exit
+ * barrier has landed.
+ */
+
+// Applies two edits to one text when each is one stretch of it (an IME composition always is) and the
+// stretches do not overlap (two inserts at one point keep both); null when they do.
+export function spliceMerge(base, local, remote) {
+  const span = (text) => {
+    let pre = 0;
+    const max = Math.min(base.length, text.length);
+    while (pre < max && base[pre] === text[pre]) pre++;
+    let suf = 0;
+    while (suf < max - pre && base[base.length - 1 - suf] === text[text.length - 1 - suf]) suf++;
+    return { start: pre, end: base.length - suf, text: text.slice(pre, text.length - suf) };
+  };
+  const l = span(local);
+  const r = span(remote);
+  if (l.end <= r.start) return base.slice(0, l.start) + l.text + base.slice(l.end, r.start) + r.text + base.slice(r.end);
+  if (r.end <= l.start) return base.slice(0, r.start) + r.text + base.slice(r.end, l.start) + l.text + base.slice(l.end);
+  return null;
+}
+
+// Where an offset in `before` lands in `after`, when the two differ in one stretch.
+export function mapCaret(before, after, offset) {
+  let pre = 0;
+  const max = Math.min(before.length, after.length);
+  while (pre < max && before[pre] === after[pre]) pre++;
+  if (offset <= pre) return offset;
+  let suf = 0;
+  while (suf < max - pre && before[before.length - 1 - suf] === after[after.length - 1 - suf]) suf++;
+  return offset >= before.length - suf ? after.length - (before.length - offset) : after.length - suf;
+}
+
+export function bindText(textarea, { onWrite, onShow, onConflict, onGone } = {}) {
+  const OBSERVE = { characterData: true, childList: true, subtree: true };
+  let field = textarea;
+  const ta = () => field;
+  let s = null; // { key, code, seen, composing, resolve }
+  let disposed = false;
+  const observer = new MutationObserver(() => {
+    observer.takeRecords();
+    if (s && !s.composing && s.code.textContent !== s.seen) reconcile(s.code.textContent);
+  });
+
+  // New durable input is the lifecycle's to admit, not the binding's: while a transition
+  // runs, a keystroke is not new input and is refused. A standalone page has no lifecycle
+  // and always admits.
+  const admitted = () => window.clay?.modeLifecycle?.canWrite?.() !== false;
+
+  // The record holds what the textarea holds. That is the only proof a flush landed: a
+  // callback that staged a conflict or a gone record has not made the text represented.
+  const represented = () => !!(s && s.code.isConnected && s.code.textContent === ta().value);
+
+  function write(value) {
+    const t = s.code.firstChild;
+    if (t && t.nodeType === 3 && !t.nextSibling) t.data = value;
+    else s.code.textContent = value;
+    observer.takeRecords();
+    s.seen = value;
+    onWrite?.(s.code);
+  }
+  function show(value) {
+    const el = ta();
+    const before = el.value;
+    const [a, b] = [mapCaret(before, value, el.selectionStart), mapCaret(before, value, el.selectionEnd)];
+    el.value = value;
+    if (document.activeElement === el) el.setSelectionRange(a, b);
+    s.seen = value;
+    onShow?.();
+  }
+  // The record changed while the textarea held text the record had not taken yet.
+  // `base` is the text both sides were editing, read before show() moves `seen`: a
+  // caller staging the losing side needs what the clash was measured against, not
+  // what the textarea holds afterwards. The second argument is additive, so a
+  // caller that only wants the typed string ignores it.
+  function reconcile(now) {
+    const typed = ta().value;
+    const base = s.seen;
+    const merged = typed === base ? now : spliceMerge(base, typed, now);
+    if (merged == null) {
+      onConflict?.(typed, { key: s.key, base, remote: now });
+      show(now);
+      return { ok: false, code: "conflict" };
+    }
+    if (merged !== now) write(merged);
+    show(merged);
+    return { ok: true };
+  }
+  // A record that cannot be resolved hands its text to `onGone` and is released: there is
+  // nothing left here that a later write could land in, and holding the detached element
+  // would refuse every record switch after it.
+  function rebind() {
+    const code = s.resolve ? s.resolve() : null;
+    if (!code) {
+      onGone?.(ta().value, { key: s.key, base: s.seen });
+      observer.disconnect();
+      s = null;
+      return false;
+    }
+    s.code = code;
+    observer.disconnect();
+    observer.observe(s.code, OBSERVE);
+    return true;
+  }
+  // `captured` is the composition this binding already holds: it finishes through its own
+  // operation, so a closed admission does not throw away what the person was typing.
+  function input(captured = false) {
+    if (!s) return { ok: true };
+    if (s.composing) return { ok: false, code: "composition" };
+    if (!captured && !admitted()) return { ok: false, code: "busy" };
+    if (!s.code.isConnected && !rebind()) return { ok: false, code: "gone" };
+    const now = s.code.textContent;
+    if (now !== s.seen) return reconcile(now);
+    const value = ta().value;
+    if (value !== s.seen) write(value);
+    return { ok: true };
+  }
+  // A composition in progress is not something a flush may end on the person's behalf: it
+  // is refused, and `s.composing` stays exactly as it was. Everything else runs the input
+  // path above, and its answer says whether the record now holds the text.
+  function flush() {
+    if (!s) return { ok: true };
+    if (s.composing) return { ok: false, code: "composition" };
+    const result = input();
+    if (!result.ok) return result;
+    return represented() ? { ok: true } : { ok: false, code: "conflict" };
+  }
+  function open(textEl, options = {}) {
+    if (disposed) return { ok: false, code: "disposed" };
+    const key = options.key;
+    if (s && s.key === key) {
+      s.resolve = options.resolve;
+      if (s.code !== textEl || !s.code.isConnected) {
+        if (!rebind()) return { ok: false, code: "gone" };
+        return input();
+      }
+      return { ok: true };
+    }
+    // A refused flush keeps the open record and its observer: nothing was written, so
+    // switching records here would drop the text the refusal was protecting. A record that
+    // was gone has already handed its text over and released itself, so there is nothing
+    // left to protect and the switch goes ahead.
+    const flushed = flush();
+    if (!flushed.ok && s) return flushed;
+    observer.disconnect();
+    s = { key, code: textEl, seen: textEl.textContent, composing: false, resolve: options.resolve };
+    observer.observe(textEl, OBSERVE);
+    const el = ta();
+    el.value = s.seen;
+    el.setSelectionRange(0, 0);
+    onShow?.();
+    return { ok: true };
+  }
+  function close() {
+    const flushed = flush();
+    if (!flushed.ok && s) return flushed;
+    observer.disconnect();
+    s = null;
+    return { ok: true };
+  }
+  // Detaching only. The barrier has already succeeded when a lease disposes the binding, so
+  // this never flushes: a composition still in progress or text the record never took keeps
+  // the listeners where they are, and the caller is told why.
+  function dispose() {
+    if (disposed) return { ok: true };
+    if (s?.composing) return { ok: false, code: "composition" };
+    if (s && !represented()) return { ok: false, code: "pending-input" };
+    disposed = true;
+    observer.disconnect();
+    detach();
+    s = null;
+    return { ok: true };
+  }
+  function attach(next) {
+    if (disposed || !next || next === field) return;
+    detach();
+    field = next;
+    listen();
+  }
+
+  function onInput() { input(); }
+  function onCompositionStart() { if (s) s.composing = true; }
+  function onCompositionEnd() { if (s) { s.composing = false; input(true); } }
+  function listen() {
+    field.addEventListener("input", onInput);
+    field.addEventListener("compositionstart", onCompositionStart);
+    field.addEventListener("compositionend", onCompositionEnd);
+  }
+  function detach() {
+    field.removeEventListener("input", onInput);
+    field.removeEventListener("compositionstart", onCompositionStart);
+    field.removeEventListener("compositionend", onCompositionEnd);
+  }
+
+  listen();
+
+  return {
+    open, close, flush, dispose,
+    current: () => s && s.code,
+    attach,
+    composing: () => !!(s && s.composing),
+  };
+}

package/src/plugins/cms.js

@@ -4,9 +4,102 @@
 import { installSkin } from "../ui/vendor-skin.js";
 import { CSS } from "../ui/skins/cms.js";
 import { CSS as TOGGLE_CSS, ROOTS as TOGGLE_ROOTS } from "../ui/skins/cms-toggle.js";
+import { cms as hypercms } from "../vendor/hypercms.vendor.js";
 
 export { cms, default } from "../vendor/hypercms.vendor.js";
 
 installSkin("cms", CSS);
 // The toggle takes the page's scheme, so Bevel's face and ink resolve the way the page reads.
 installSkin("cms-toggle", TOGGLE_CSS, { roots: TOGGLE_ROOTS });
+
+const fault = (message, code) => Object.assign(new Error(`clay:cms: ${message}`), { code });
+
+const isStale = (context) => {
+  if (!context) return false;
+  if (context.signal?.aborted) return true;
+  return typeof context.isCurrent === "function" && !context.isCurrent();
+};
+
+// One edit session over the page the CMS edits, as a ClayJS lease. The source owns the
+// session itself, so every method here is the source's own lifecycle call: `enable`
+// opens and mounts, `resume` is the refused exit over the same session, and `dispose`
+// goes through the CMS's teardown after the barrier.
+//
+// `quiesce` is the one call the lease shapes. The source answers for the work it still
+// holds, an upload in flight or a painted preview, with `{ok:false}` rather than by
+// tearing that work down: an exit refused there keeps the session, its buffers and the
+// upload, and the controller resumes the same lease once the person finishes or
+// discards it. The lease contract carries a refusal as the `code` a controller reports,
+// so the non-ok answer is thrown as `pending-input`.
+function cmsLease(source) {
+  let disposed = false;
+  return {
+    ready: source.ready,
+    enable() {
+      if (disposed) return;
+      source.enable();
+    },
+    quiesce() {
+      if (disposed) return;
+      const result = source.quiesce();
+      if (result && result.ok === false) {
+        throw Object.assign(fault("the CMS still has work to finish", result.code || "pending-input"), {
+          pending: result.pending,
+        });
+      }
+      return result;
+    },
+    resume() {
+      if (disposed) return;
+      source.resume();
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      source.dispose();
+    },
+  };
+}
+
+// The boot this tab made, adopted instead of prepared. A page that opened the CMS itself
+// (`?cms=true`) holds a session the source hands no lease out for, so it cannot be
+// quiesced or torn down through the adapter and the caller keeps its reload instead;
+// a boot that opened nothing has nothing to hand back, and this lease starts nothing.
+function adopt() {
+  if (hypercms.isOpen) throw fault("the CMS this boot opened cannot be taken back", "unsupported-plugin");
+  const lease = cmsLease(hypercms.prepareModeLease({}));
+  return {
+    enable() {},
+    quiesce: () => lease.quiesce(),
+    resume: () => lease.resume(),
+    dispose: () => lease.dispose(),
+  };
+}
+
+/**
+ * The CMS as a mode participant: the session the commit that enters edit opens, and the
+ * one the exit destroys.
+ *
+ * `prepare` is inert by construction, because the source's lease mounts nothing until
+ * `enable`; a vendor build without that lifecycle is refused here rather than opened
+ * beside the controller, where an exit would have no session to quiesce and no teardown
+ * to run. `order` is the source's: the CMS edits the page's own attributes and content,
+ * so it enters after the modules that prepare that page for editing, and it leaves
+ * first, while its session can still refuse an exit over an upload or a preview.
+ */
+export function cmsParticipant(options = {}) {
+  return {
+    id: "clay:cms",
+    order: 1000,
+    async prepare(context = {}) {
+      if (typeof hypercms.prepareModeLease !== "function") {
+        throw fault("this vendor build has no quiescable session", "unsupported-plugin");
+      }
+      if (isStale(context)) throw fault("prepared for a stale generation", "stale-document");
+      if (context.initial === true) return adopt();
+      return cmsLease(hypercms.prepareModeLease(options));
+    },
+  };
+}
+
+export { cmsParticipant as modeParticipant };