@panphora/clayjs 1.15.2 → 1.17.0

package/src/plugins/undo.js

@@ -4,25 +4,75 @@
 // flag.
 
 import { undo } from '../vendor/hyper-undo.vendor.js'
-import { isEditMode } from '../core/is-edit-mode.js'
+import { isEditMode, startsAtImport } from '../core/is-edit-mode.js'
 import { isTabLocalAttr } from '../lib/root-attrs.js'
 import { isDerivedAttr } from '../lib/derived.js'
 import { PERSIST } from '../lib/attr-aliases.js'
+import { isGestureItem, isRuntimeAttribute } from '../lib/undo/capture-move.js'
+import { gateMarkDirty } from '../lib/dirty-gate.js'
 
 // Tab-local attributes (ephemeral state, route-active, root library state) are
-// never undone. The shared mutation hub already drops them for the main
-// instance; a scope made with create() runs its own observer, so it is told too.
+// 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
+// writes them is not an edit. The shared mutation hub already drops tab-local
+// attributes for the main instance; a scope made with create() runs its own
+// observer, so it is told too.
+// 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()
 const withTabLocal = (opts = {}) => {
   const own = opts.ignoreAttribute
   return {
     ...opts,
-    ignoreAttribute: (name, target) => isTabLocalAttr(name, target) || isDerivedAttr(target, name) || (own ? own(name, target) : false),
+    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,
   }
 }
 
+// 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.
+function keepsOwnHistory(node) {
+  const policy = window.clay?.region?.resolveRegionPolicy
+  if (!policy || node.nodeType !== 1) return false
+  const own = policy(node)
+  if (own.undoable !== false || own.persist === 'none') return false
+  const parent = node.parentElement
+  return !parent || policy(parent).undoable !== false
+}
+
 const createScope = undo.create.bind(undo)
 undo.create = (opts) => createScope(withTabLocal(opts))
 
+// The recording mode is the page's choice, and a session starts a new scope over the
+// page as it stands: remember it here, so an exit and a re-entry come back in the mode
+// the page picked instead of the default one.
+let recording = null
+const setRecording = undo.setRecording.bind(undo)
+undo.setRecording = (mode) => {
+  recording = mode ?? null
+  return setRecording(mode)
+}
+
+// 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.
+// So every commit, command, undo and redo that changed the document marks the
+// page dirty at the gate's own entry point, whose count is what the capture token
+// is compared against — an explicit mark advances it even while the gate is paused.
+const lastEntryId = () => undo.history.at(-1)?.id ?? null
+
+const command = undo.command.bind(undo)
+undo.command = (label, fn) => {
+  const receipt = command(label, fn)
+  if (receipt) gateMarkDirty()
+  return receipt
+}
+
+// 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.
+
 // 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)
@@ -32,7 +82,10 @@ undo.commit = (label, fn) => {
     warnedEffectCommit = true
     console.warn(`clay.effect: undo.commit("${label}") was called inside an effect. Run commands from event handlers, not from an effect.`)
   }
-  return commit(label, fn)
+  const before = lastEntryId()
+  const receipt = commit(label, fn)
+  if (receipt || lastEntryId() !== before) gateMarkDirty()
+  return receipt
 }
 
 // Undo and redo restore attributes. A control the user has touched shows its
@@ -74,23 +127,240 @@ function restoreControls() {
   })
 }
 
-function init() {
-  if (!isEditMode) return
-  // Defer until the body exists so the default scope (document.body) is valid.
-  if (typeof document === 'undefined') return
-  const start = () => {
-    undo.start(withTabLocal({ bindKeys: true }))
-    undo.on('undo', restoreControls)
-    undo.on('redo', restoreControls)
+// The engine emits its receipt only after a whole replay applied, so a refused
+// undo or redo never reaches the control restore.
+const afterReplay = (receipt) => {
+  if (!receipt?.ok) return
+  gateMarkDirty()
+  restoreControls()
+}
+
+// A refusal is announced for whoever presents it: the engine's receipt, once.
+const refuse = ({ entryId, label, direction, code }) => {
+  document.dispatchEvent(new CustomEvent('clay:undo-refused', {
+    detail: { ok: false, code, entryId, label, direction },
+  }))
+  keepRefused({ ok: false, code, entryId, label, direction })
+}
+
+// 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
+// or the first app keep; no reader and no boot pays for it, and nothing it writes is a
+// save.
+let recoveryLoad = null
+
+function loadRecovery() {
+  recoveryLoad ??= import('../recovery/undo.js').catch((error) => {
+    recoveryLoad = null
+    console.error('clayjs: the undo recovery module could not be downloaded; a refused step stays in this tab only', error)
+    return null
+  })
+  return recoveryLoad
+}
+
+async function keepRefused(receipt) {
+  let written = { ok: false, code: 'unavailable' }
+  try {
+    const module = await loadRecovery()
+    if (module) written = await module.keepRefusal(undo, receipt)
+  } catch (_) {
+    written = { ok: false, code: 'error' }
   }
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', start)
-  } else {
-    start()
+  const detail = written?.ok === true
+    ? { ok: true, entryId: receipt.entryId, direction: receipt.direction }
+    : { ok: false, code: written?.code || 'error', entryId: receipt.entryId, direction: receipt.direction }
+  document.dispatchEvent(new CustomEvent('clay:undo-kept', { detail }))
+}
+
+// The page's own records on the same channel and in the same store: `keep` stages one,
+// `kept` is what a later session can review, and `dismissKept` is the explicit,
+// revision-checked way one leaves. All three fetch the recovery module on demand.
+const withRecovery = (call, fallback) => (...args) =>
+  loadRecovery().then(
+    (module) => (module ? module[call](...args) : fallback),
+    () => fallback
+  )
+
+// 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.ignoreAttribute = (name) => {
+  const key = String(name || '')
+  if (!key) return () => {}
+  pageIgnored.add(key)
+  return () => { pageIgnored.delete(key) }
+}
+
+undo.keep = async (spec) => {
+  const written = await keepApp(spec)
+  if (written?.ok === true) {
+    document.dispatchEvent(new CustomEvent('clay:undo-kept', { detail: { ok: true, key: spec?.key == null ? null : `app:${spec.key}` } }))
   }
+  return written
+}
+undo.kept = withRecovery('kept', { ok: false, code: 'unavailable', records: [] })
+undo.dismissKept = withRecovery('dismissKept', { ok: false, code: 'unavailable' })
+
+// The page's own actions on a kept copy. A provider is asked about every record the
+// review panel draws, and each action it returns becomes a button on that row, so a
+// template offers Keep as new without the panel knowing what a card is. A provider
+// that throws costs its own buttons only, never the row or the copy.
+const reviewProviders = new Set()
+
+undo.reviewActions = (fn) => {
+  if (typeof fn !== 'function') return () => {}
+  reviewProviders.add(fn)
+  return () => { reviewProviders.delete(fn) }
+}
+
+undo.reviewActionsFor = (record) => {
+  const actions = []
+  for (const fn of reviewProviders) {
+    let offered
+    try {
+      offered = fn(record)
+    } catch (error) {
+      console.error('clayjs: a review action could not describe itself; the copy stays reviewable', error)
+      continue
+    }
+    for (const item of Array.isArray(offered) ? offered : []) {
+      if (item && typeof item.run === 'function' && item.label) actions.push(item)
+    }
+  }
+  return actions
+}
+
+// One event for whatever presents the history (Undo and Redo buttons, a refusal banner):
+// 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 announceChange = () => {
+  const live = !!session?.started
+  document.dispatchEvent(new CustomEvent('clay:undo-change', {
+    detail: {
+      canUndo: live && undo.canUndo,
+      canRedo: live && undo.canRedo,
+      undo: (live && undo.history.at(-1)) || null,
+      redo: (live && undo.future?.[0]) || null,
+    },
+  }))
+}
+
+// One edit session owns the page's DOM history. A session starts its own over the page as
+// it stands, so nothing an earlier session recorded, and nothing a reader painted while the
+// page was in view, is this session's to undo. The durable recovery records belong to the
+// recovery service and outlive every session; nothing here reads, clears or rewrites them.
+let session = null
+
+function ownership() {
+  return { started: false, admitted: false, subscriptions: [] }
+}
+
+const isStale = (context) => {
+  if (!context) return false
+  if (context.signal?.aborted) return true
+  return typeof context.isCurrent === 'function' && !context.isCurrent()
+}
+
+// The default scope is document.body, so a boot that is still parsing waits for the body
+// to exist before the session starts.
+function bodyReady() {
+  if (typeof document === 'undefined') return Promise.resolve()
+  if (document.readyState !== 'loading') return Promise.resolve()
+  return new Promise((resolve) => document.addEventListener('DOMContentLoaded', resolve, { once: true }))
+}
+
+// One edit session over the live page. `enable` starts a fresh history and the control
+// restore that follows it; `quiesce` closes recording so the exit barrier's writes are not
+// entries, keeping the history itself; `resume` is the refused exit; `dispose` detaches
+// exactly the subscriptions this session added and takes the history and its keydown
+// binding back, so a later entry starts from nothing.
+function undoLease(record) {
+  return {
+    enable() {
+      if (record.started) return
+      record.started = true
+      record.admitted = true
+      undo.start(withTabLocal({ bindKeys: true, ...(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 })
+      for (const type of HISTORY_EVENTS) {
+        undo.on(type, announceChange)
+        record.subscriptions.push({ type, handler: announceChange })
+      }
+      announceChange()
+    },
+    quiesce() {
+      if (!record.admitted) return
+      record.admitted = false
+      undo.pause()
+    },
+    resume() {
+      if (record.admitted) return
+      record.admitted = true
+      undo.resume()
+    },
+    dispose() {
+      record.admitted = false
+      if (session === record) session = null
+      if (!record.started) return
+      record.started = false
+      for (const { type, handler } of record.subscriptions.splice(0)) undo.off(type, handler)
+      undo.stop()
+      announceChange()
+    },
+  }
+}
+
+/**
+ * Undo as a mode participant: the history the commit that enters edit starts, and the one
+ * the exit takes back.
+ *
+ * `prepare` waits for the body the default scope needs, and answers with the session's
+ * lease; that wait can outlive the session that asked for it, so the generation is asked
+ * again once the body exists. `enable` starts the history. `quiesce` stops recording
+ * without losing what the session already holds. `dispose` hands back the subscriptions,
+ * the history and the keydown binding.
+ */
+export function undoParticipant() {
+  return {
+    id: 'clay:undo',
+    order: 350,
+    async prepare(context = {}) {
+      if (context.initial === true) return adopt()
+      await bodyReady()
+      if (isStale(context)) {
+        throw Object.assign(new Error('clay:undo prepared for a stale generation'), { code: 'stale-document' })
+      }
+      return undoLease(session || (session = ownership()))
+    },
+  }
+}
+
+// The boot this tab already made, adopted instead of prepared: it is the history `init`
+// below started, or, on a boot that started none, nothing to hand back.
+async function adopt() {
+  const lease = await ready
+  return { enable() {}, quiesce: () => lease?.quiesce(), resume: () => lease?.resume(), dispose: () => lease?.dispose() }
+}
+
+// Auto-init when the module is imported; the loader awaits `ready` before resolving clay.ready
+async function init() {
+  if (!startsAtImport()) return null
+  if (typeof document === 'undefined') return null
+  const lease = await undoParticipant().prepare()
+  lease.enable()
+  return lease
 }
 
-init()
+const ready = init()
 
-export { undo, restoreControls }
+export { undo, restoreControls, init, ready }
+export { undoParticipant as modeParticipant }
 export default undo

package/src/plugins/unsent.js

@@ -0,0 +1,132 @@
+// Text typed into chrome and not yet sent (a comment box, a description being edited),
+// kept per record and name, outside the file. A redraw or a reload brings it back.
+//
+// The record a field belongs to is named by an `unsent-key` attribute on its nearest
+// such ancestor, and by the nearest `[data-id]` ancestor when there is none: a view
+// with two draft fields under one record names each scope it wants kept apart. The
+// name is the field's own `unsent` attribute. A draft is pending while the field's
+// value differs from the base it started at, an emptied field included.
+import { registerUnsavedState } from "../lib/unsaved-state.js";
+import { storage } from "../lib/doc-storage.js";
+
+const KEY = "unsent";
+const drafts = new Map(Object.entries(storage.session.get(KEY) || {}));
+const bases = new WeakMap();
+const pending = registerUnsavedState({ id: "unsent", isPending: () => drafts.size > 0 });
+
+const keyOf = (el) => {
+  const scope = el.closest("[unsent-key]");
+  const record = (scope && scope.getAttribute("unsent-key")) || el.closest("[data-id]")?.dataset.id;
+  const name = el.getAttribute("unsent");
+  return record && name ? `${record}|${name}` : null;
+};
+const split = (key) => { const at = key.indexOf("|"); return [key.slice(0, at), key.slice(at + 1)]; };
+
+function persist() {
+  storage.session.set(KEY, Object.fromEntries(drafts));
+  pending.changed();
+  document.dispatchEvent(new CustomEvent("clay:unsent-changed", { detail: { count: drafts.size } }));
+}
+
+function onBeforeInput(e) {
+  const el = e.target.closest?.("[unsent]");
+  if (el && !bases.has(el)) bases.set(el, el.value);
+}
+
+function onInput(e) {
+  const el = e.target.closest?.("[unsent]");
+  const key = el && keyOf(el);
+  if (!key) return;
+  const base = bases.get(el) ?? drafts.get(key)?.base ?? "";
+  if (el.value === base) {
+    drafts.delete(key);
+    bases.delete(el);
+  } else {
+    drafts.set(key, { base, text: el.value });
+  }
+  persist();
+}
+
+function restore(el) {
+  const key = keyOf(el);
+  const draft = key && drafts.get(key);
+  if (!draft) return;
+  const current = el.value;
+  bases.set(el, draft.base);
+  el.value = draft.text;
+  el.dispatchEvent(new CustomEvent("clay:unsent-restored", {
+    bubbles: true,
+    detail: { base: draft.base, current, stale: current !== draft.base },
+  }));
+}
+
+const observer = new MutationObserver((records) => {
+  for (const record of records) for (const node of record.addedNodes) {
+    if (node.nodeType !== 1) continue;
+    if (node.matches("[unsent]")) restore(node);
+    for (const el of node.querySelectorAll("[unsent]")) restore(el);
+  }
+});
+
+function restoreAll() {
+  for (const el of document.querySelectorAll("[unsent]")) restore(el);
+}
+
+// The listeners and the observer belong to the page, not to an edit session: a reader
+// repaint while the page is in view has to bring the drafts back too. Installing twice
+// adds nothing, which is what keeps a second entry from recording one keystroke twice.
+let installed = false;
+
+function install() {
+  if (installed) return;
+  installed = true;
+  document.addEventListener("beforeinput", onBeforeInput, true);
+  document.addEventListener("input", onInput, true);
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+
+install();
+restoreAll();
+
+/**
+ * Unsent drafts as a mode participant.
+ *
+ * Nothing here is the session's to lose: a draft is a revision of one control (its base
+ * and its text, per record and name) that the page's bytes cannot show, and the restore
+ * that brings it back runs in view as well. So `enable` installs and restores, and
+ * `quiesce`, `resume` and `dispose` leave every draft, its base and the pending check
+ * exactly where they are — an exit that teardown could acknowledge would report a view
+ * while a person's half-written text still waits outside the file.
+ */
+export function unsentParticipant() {
+  return {
+    id: "clay:unsent",
+    order: 320,
+    prepare(context = {}) {
+      // Adoption asks for a lease over the boot's session, and this module has none to
+      // hand back: it installs once at import and keeps every draft.
+      if (context.initial === true) {
+        return { enable() {}, quiesce() {}, resume() {}, dispose() {} };
+      }
+      install();
+      return {
+        enable() {
+          install();
+          restoreAll();
+        },
+        quiesce() {},
+        resume() {},
+        dispose() {},
+      };
+    },
+  };
+}
+
+export { unsentParticipant as modeParticipant };
+
+export const unsent = {
+  get size() { return drafts.size; },
+  list: () => [...drafts].map(([key, d]) => { const [record, name] = split(key); return { record, name, ...d }; }),
+  clear(el) { const key = keyOf(el); if (key && drafts.delete(key)) persist(); bases.delete(el); },
+  drop(record, name) { if (drafts.delete(`${record}|${name}`)) persist(); },
+};

package/src/plugins/upgrade-run.js

@@ -0,0 +1 @@
+export { start, apply, prepare } from "../core/upgrade-run.js";

package/src/plugins/upgrade.js

@@ -0,0 +1,210 @@
+// A copy made from a starter template says where it came from: its `hyper-source`
+// and `hyper-version` metas. Once per load, the person who can edit such a copy is
+// asked whether a newer version was published, and gets one offer when it was: an
+// item with a dot in the menu, or a notice with Upgrade and Not now when the page
+// has no menu. Nothing here writes the document; the click lands on
+// `clay:upgrade-requested`, which is where the upgrade itself picks it up.
+//
+// Silent on every other page: no metas (a copy made before templates carried them),
+// a visitor, a draft, no network, a failed fetch, a bad digest or an equal version.
+// The 24-hour cache is hyper-html-api's own; the dotted-version comparison is
+// core/version.js, so the rules engine that upgrades a document stays the click's.
+import { isNewerVersion } from "../core/version.js";
+
+const CACHE_PREFIX = "hha:upgrade-check:";
+const TTL_MS = 24 * 60 * 60 * 1000;
+const DISMISSED_KEY = "upgrade-dismissed";
+const NOTICE = "A new version of this template is available.";
+
+function readMeta(doc, name) {
+  const el = doc.querySelector(`meta[name="${name}"]`);
+  const content = el ? el.getAttribute("content") : null;
+  return content && content.trim() ? content.trim() : null;
+}
+
+function readCache(key) {
+  try {
+    const raw = globalThis.localStorage.getItem(key);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(key, value) {
+  try {
+    globalThis.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    // No storage (a private window): the next load asks again.
+  }
+}
+
+async function digestOf(bytes) {
+  const subtle = globalThis.crypto && globalThis.crypto.subtle;
+  if (!subtle) return null;
+  const digest = await subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function fetchOrNull(fetchFn, url) {
+  try {
+    const res = await fetchFn(url, { credentials: "omit" });
+    if (!res.ok) return null;
+    return res;
+  } catch {
+    return null;
+  }
+}
+
+// `hyper-source` names the published HTML; its manifest is the same URL as JSON.
+async function latestManifest(sourceHref, currentVersion, { fetchFn, now }) {
+  const latestUrl = new URL(sourceHref);
+  latestUrl.pathname = latestUrl.pathname.replace(/\.html$/, ".json");
+  const cacheKey = `${CACHE_PREFIX}${latestUrl.href}:${currentVersion}`;
+  const cached = readCache(cacheKey);
+  if (cached && typeof cached.checkedAt === "number" && now - cached.checkedAt < TTL_MS) {
+    return { latest: cached.latest, latestUrl };
+  }
+  const res = await fetchOrNull(fetchFn, latestUrl.href);
+  if (!res) return { latest: null, latestUrl };
+  let latest = null;
+  try {
+    latest = await res.json();
+  } catch {
+    return { latest: null, latestUrl };
+  }
+  writeCache(cacheKey, { checkedAt: now, latest });
+  return { latest, latestUrl };
+}
+
+export async function findUpdate({
+  doc = document,
+  loc = location,
+  fetchFn = (url, init) => fetch(url, init),
+  now = Date.now(),
+} = {}) {
+  const clay = (typeof window !== "undefined" && window.clay) || {};
+  // A visitor cannot act on the offer, and a draft is not the document the source
+  // would replace. Neither fetches.
+  if (!clay.canEdit || clay.isDraftMode) return null;
+
+  const sourceUrl = readMeta(doc, "hyper-source");
+  const currentVersion = readMeta(doc, "hyper-version");
+  if (!sourceUrl || !currentVersion) return null;
+
+  let source;
+  try {
+    source = new URL(sourceUrl, loc ? loc.href : undefined);
+  } catch {
+    return null;
+  }
+  if (!source.pathname.endsWith(".html")) return null;
+  // A pristine published copy points at itself: it is the source, not a copy of one.
+  if (loc && source.origin === loc.origin && source.pathname === loc.pathname) return null;
+  const latestUrl = new URL(source.href);
+  latestUrl.pathname = latestUrl.pathname.replace(/\.html$/, ".json");
+
+  const { latest } = await latestManifest(source.href, currentVersion, { fetchFn, now });
+  if (!latest || typeof latest !== "object") return null;
+  if (typeof latest.version !== "string" || !isNewerVersion(latest.version, currentVersion)) return null;
+
+  const storage = clay.storage && clay.storage.local;
+  if (storage && storage.get(DISMISSED_KEY) === latest.version) return null;
+
+  if (typeof latest.html !== "string" || !latest.html) return null;
+  const htmlUrl = new URL(latest.html, latestUrl).href;
+  const res = await fetchOrNull(fetchFn, htmlUrl);
+  if (!res) return null;
+  let bytes;
+  try {
+    bytes = await res.arrayBuffer();
+  } catch {
+    return null;
+  }
+  const digest = await digestOf(bytes);
+  // A manifest whose digest does not match its HTML is a host that served the wrong
+  // bytes. Nothing is offered, because nothing can be trusted to be that version.
+  if (!digest || digest !== String(latest.sha256 || "").toLowerCase()) return null;
+
+  return { version: latest.version, html: htmlUrl, sha256: digest, latestUrl: latestUrl.href };
+}
+
+function dismiss(version) {
+  const clay = window.clay;
+  const storage = clay && clay.storage && clay.storage.local;
+  if (storage) storage.set(DISMISSED_KEY, version);
+}
+
+function menuPlanned(clay) {
+  return Boolean(clay && Array.isArray(clay.plugins) && clay.plugins.includes("menu"));
+}
+
+function menuReady(clay) {
+  return Boolean(clay && clay.menu && typeof clay.menu.addItem === "function");
+}
+
+function whenMenuReady(clay) {
+  if (menuReady(clay) || !menuPlanned(clay)) return Promise.resolve();
+  return new Promise((resolve) => {
+    const onSettled = (event) => {
+      if (!event.detail || event.detail.plugin !== "menu") return;
+      document.removeEventListener("clay:plugin-ready", onSettled);
+      document.removeEventListener("clay:plugin-failed", onSettled);
+      resolve();
+    };
+    document.addEventListener("clay:plugin-ready", onSettled);
+    document.addEventListener("clay:plugin-failed", onSettled);
+  });
+}
+
+export async function announce(update, clay = typeof window !== "undefined" ? window.clay : null) {
+  const run = () => document.dispatchEvent(new CustomEvent("clay:upgrade-requested", { detail: update }));
+  await whenMenuReady(clay);
+  if (menuReady(clay)) {
+    clay.menu.addItem({ id: "upgrade", label: `Upgrade to version ${update.version}`, badge: true, run });
+    return "menu";
+  }
+  if (clay && typeof clay.toastPersistent === "function") {
+    clay.toastPersistent(NOTICE, "info", {
+      actions: [
+        { label: "Upgrade", onClick: run },
+        { label: "Not now", onClick: () => dismiss(update.version) },
+      ],
+    });
+    return "notice";
+  }
+  return null;
+}
+
+let started = false;
+
+export async function start(options = {}) {
+  if (started) return null;
+  started = true;
+  const clay = window.clay;
+  // Toasts and the menu are drawn by satellites that may land after boot settles.
+  await Promise.resolve(clay && clay.loaded && clay.loaded.ui).catch(() => {});
+  const update = await findUpdate(options).catch(() => null);
+  if (!update) return null;
+  await announce(update);
+  return update;
+}
+
+export async function replace(html, options) {
+  const mod = await import("../core/save-replace.js");
+  return mod.replace(html, options);
+}
+
+function onUpgradeRequested(event) {
+  import("./upgrade-run.js")
+    .then((mod) => mod.start(event.detail))
+    .catch((err) => console.error("clayjs: the upgrade could not start:", err));
+}
+
+const bootClay = typeof window !== "undefined" ? window.clay : null;
+if (bootClay && bootClay.canEdit && !bootClay.isDraftMode) {
+  document.addEventListener("clay:upgrade-requested", onUpgradeRequested);
+  const ready = bootClay.ready;
+  if (ready && typeof ready.then === "function") ready.then(() => start(), () => {});
+  else start();
+}