@panphora/clayjs 1.6.0 → 1.6.1

package/dist/clay.standalone.js

@@ -1,4 +1,4 @@
-/* clayjs 1.6.0 standalone build: every clayjs module in one file. https://clayjs.com/offline
+/* clayjs 1.6.1 standalone build: every clayjs module in one file. https://clayjs.com/offline
    Third-party code inside keeps its own license (Sortable MIT, Squire MIT, DOMPurify Apache-2.0 OR MPL-2.0, MicroModal MIT, parse5 MIT): https://clayjs.com/THIRD-PARTY-NOTICES.md */
 (() => {
   var __create = Object.create;
@@ -2537,8 +2537,17 @@
     replacePageWith: () => replacePageWith,
     resetSaveAttempts: () => resetSaveAttempts,
     saveFateIsUnknown: () => saveFateIsUnknown,
-    saveHtml: () => saveHtml
+    saveHtml: () => saveHtml,
+    withKeepalive: () => withKeepalive
   });
+  async function withKeepalive(keepalive, run) {
+    nextSaveKeepalive = Boolean(keepalive);
+    try {
+      return await run();
+    } finally {
+      nextSaveKeepalive = false;
+    }
+  }
   function isSaveInProgress() {
     return saveInProgress;
   }
@@ -2612,7 +2621,7 @@
   function skippedResult(msg) {
     return { ok: false, msg, msgType: "skipped", code: null, etag: null };
   }
-  function buildSaveRequest(content, userDriven, signal, saveId, etag) {
+  function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false) {
     const token = saveToken();
     const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
     const options = {
@@ -2637,6 +2646,7 @@
       body: content
     };
     if (etag) options.headers["If-Match"] = etag;
+    if (keepalive && new Blob([content]).size < KEEPALIVE_MAX_BODY) options.keepalive = true;
     return { url: resolveSaveUrl(path), options };
   }
   function stampToSend() {
@@ -2654,7 +2664,9 @@
     const gestureDriven = consumeUserDriven();
     const explicitlyAsked = consumeExplicitSave();
     const userDriven = gestureDriven || explicitlyAsked;
-    const { url, options } = buildSaveRequest(content, userDriven, controller.signal, saveId, etag);
+    const keepalive = nextSaveKeepalive;
+    nextSaveKeepalive = false;
+    const { url, options } = buildSaveRequest(content, userDriven, controller.signal, saveId, etag, keepalive);
     rememberSentId(saveId);
     return fetch(url, options).then((res) => res.text().then((text) => {
       let data = {};
@@ -2779,7 +2791,7 @@
       });
     });
   }
-  var saveInProgress, SAVE_PATH, SAVE_TIMEOUT_MS, saveAcceptedHooks, sentIds, SENT_ID_MEMORY, unknownAttempt;
+  var saveInProgress, SAVE_PATH, SAVE_TIMEOUT_MS, KEEPALIVE_MAX_BODY, nextSaveKeepalive, saveAcceptedHooks, sentIds, SENT_ID_MEMORY, unknownAttempt;
   var init_save_core = __esm({
     "src/core/save-core.js"() {
       init_is_edit_mode();
@@ -2791,6 +2803,8 @@
       saveInProgress = false;
       SAVE_PATH = "/_/save";
       SAVE_TIMEOUT_MS = 12e3;
+      KEEPALIVE_MAX_BODY = 6e4;
+      nextSaveKeepalive = false;
       saveAcceptedHooks = [];
       sentIds = [];
       SENT_ID_MEMORY = 8;
@@ -2864,6 +2878,18 @@
   });
 
   // src/lib/dirty-gate.js
+  function scheduleAnnounce() {
+    if (!isEditMode || queued) return;
+    queued = true;
+    queueMicrotask(() => {
+      queued = false;
+      if (typeof document === "undefined") return;
+      const dirty = pageMaybeDirty();
+      if (dirty === announcedDirty) return;
+      announcedDirty = dirty;
+      document.dispatchEvent(new CustomEvent(dirty ? "clay:dirty" : "clay:clean"));
+    });
+  }
   function gatedPersistControls() {
     const out = [];
     for (const el5 of document.querySelectorAll(PERSIST_CONTROLS)) {
@@ -2878,6 +2904,7 @@
     if (!(el5.matches("input, textarea, select") || el5.isContentEditable)) return;
     if (el5.closest(GATE_IGNORE)) return;
     changes++;
+    scheduleAnnounce();
   }
   function startDirtyGate() {
     if (started) return;
@@ -2885,7 +2912,10 @@
     mutation_default.onAnyChange(
       { omitChangeDetails: true, require: "dirty" },
       () => {
-        if (!paused) changes++;
+        if (!paused) {
+          changes++;
+          scheduleAnnounce();
+        }
       }
     );
     document.addEventListener("input", onUserInput, true);
@@ -2948,6 +2978,7 @@
   }
   function gateMarkDirty() {
     changes++;
+    scheduleAnnounce();
   }
   function gateClearIfUnchanged(token) {
     if (!token) return;
@@ -2957,8 +2988,9 @@
     for (const [el5, sig] of token.probe) {
       if (controlSignature(el5) === sig) probeCache.set(el5, sig);
     }
+    scheduleAnnounce();
   }
-  var changes, clearedAt, paused, started, PERSIST_CONTROLS, GATE_IGNORE, probeCache;
+  var changes, clearedAt, paused, started, announcedDirty, queued, PERSIST_CONTROLS, GATE_IGNORE, probeCache;
   var init_dirty_gate = __esm({
     "src/lib/dirty-gate.js"() {
       init_mutation();
@@ -2969,6 +3001,8 @@
       clearedAt = 0;
       paused = false;
       started = false;
+      announcedDirty = false;
+      queued = false;
       PERSIST_CONTROLS = `input${PERSIST2}, textarea${PERSIST2}, select${PERSIST2}`;
       GATE_IGNORE = `${STRIP_FROM_DIRTY_CHECK}, ${SNAPSHOT_REMOVE_SELECTOR}`;
       probeCache = /* @__PURE__ */ new WeakMap();
@@ -2982,6 +3016,52 @@
     }
   });
 
+  // src/lib/unsaved-state.js
+  function registerUnsavedState({ id = "", isPending: isPending2 }) {
+    const key2 = ++nextKey;
+    sources.set(key2, { id, isPending: isPending2 });
+    let disposed = false;
+    return {
+      changed() {
+        if (disposed) return;
+        document.dispatchEvent(new CustomEvent("clay:unsaved-state-changed", {
+          detail: { pending: pendingIds() }
+        }));
+      },
+      dispose() {
+        if (disposed) return;
+        disposed = true;
+        sources.delete(key2);
+      }
+    };
+  }
+  function isPending(source2) {
+    try {
+      return !!source2.isPending();
+    } catch (err) {
+      console.error(`[clay] unsaved-state check "${source2.id}" threw`, err);
+      return true;
+    }
+  }
+  function pendingIds() {
+    return [...sources.values()].filter(isPending).map((s2) => s2.id);
+  }
+  function hasUnsavedState() {
+    for (const source2 of sources.values()) if (isPending(source2)) return true;
+    return false;
+  }
+  var sources, nextKey;
+  var init_unsaved_state = __esm({
+    "src/lib/unsaved-state.js"() {
+      sources = /* @__PURE__ */ new Map();
+      nextKey = 0;
+      if (typeof window !== "undefined") {
+        window.clay = window.clay || {};
+        window.clay.registerUnsavedState = registerUnsavedState;
+      }
+    }
+  });
+
   // src/lib/autosave-state.js
   function setAutosaveActive(value) {
     active = !!value;
@@ -3094,6 +3174,67 @@
     }
   });
 
+  // src/core/unsaved-warning.js
+  var unsaved_warning_exports = {};
+  __export(unsaved_warning_exports, {
+    bytesUnsaved: () => bytesUnsaved,
+    hasUnsavedChanges: () => hasUnsavedChanges,
+    reloadAfterDiscard: () => reloadAfterDiscard
+  });
+  function reloadAfterDiscard({ isCurrent, reload }) {
+    if (!isCurrent()) return false;
+    discardPermit = true;
+    setTimeout(() => {
+      discardPermit = false;
+    }, 1e3);
+    reload();
+    return true;
+  }
+  function hasUnsavedChanges() {
+    if (!isEditMode) return false;
+    if (hasUnsavedState()) return true;
+    if (window.clay?.demo) return false;
+    return bytesUnsaved();
+  }
+  function bytesUnsaved() {
+    if (!isEditMode) return false;
+    try {
+      return captureForDirtyCheck() !== getLastSavedDirty();
+    } catch {
+      return true;
+    }
+  }
+  var discardPermit;
+  var init_unsaved_warning = __esm({
+    "src/core/unsaved-warning.js"() {
+      init_is_edit_mode();
+      init_snapshot();
+      init_save();
+      init_autosave_debug();
+      init_unsaved_state();
+      discardPermit = false;
+      preloadIfEnabled();
+      window.addEventListener("beforeunload", (event) => {
+        if (!isEditMode) return;
+        if (discardPermit) {
+          discardPermit = false;
+          return;
+        }
+        if (!hasUnsavedChanges()) return;
+        event.preventDefault();
+        event.returnValue = "";
+        if (!window.clay?.demo && !hasUnsavedState()) {
+          try {
+            const currentForCompare = captureForDirtyCheck();
+            const lastSaved = getLastSavedDirty();
+            if (currentForCompare !== lastSaved) logUnloadDiffSync(currentForCompare, lastSaved);
+          } catch {
+          }
+        }
+      });
+    }
+  });
+
   // src/core/save.js
   var save_exports = {};
   __export(save_exports, {
@@ -3101,6 +3242,7 @@
     baselineSettled: () => baselineSettled,
     conflictResolvedBySync: () => conflictResolvedBySync,
     default: () => save_default,
+    flushSave: () => flushSave,
     getLastSavedBytes: () => getLastSavedBytes,
     getLastSavedContents: () => getLastSavedContents,
     getLastSavedDirty: () => getLastSavedDirty,
@@ -3366,6 +3508,85 @@
       });
     });
   }
+  function settled(deadline) {
+    const events = ["clay:save-saved", "clay:save-error", "clay:save-offline", "clay:save-conflict"];
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      const cleanup = () => {
+        clearTimeout(timer);
+        for (const name of events) document.removeEventListener(name, onSettle);
+      };
+      const onSettle = () => {
+        cleanup();
+        resolve();
+      };
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        reject(Object.assign(new Error("Save timed out."), { state: "failed" }));
+        return;
+      }
+      timer = setTimeout(() => {
+        cleanup();
+        reject(Object.assign(new Error("Save timed out."), { state: "failed" }));
+      }, remaining);
+      for (const name of events) document.addEventListener(name, onSettle);
+    });
+  }
+  function flushError(message, state2) {
+    return Object.assign(new Error(message), { state: state2 });
+  }
+  function nextEvent(name, deadline) {
+    return new Promise((resolve, reject) => {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return reject(flushError("Save timed out.", "failed"));
+      const timer = setTimeout(() => {
+        document.removeEventListener(name, onEvent);
+        reject(flushError("Save timed out.", "failed"));
+      }, remaining);
+      const onEvent = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      document.addEventListener(name, onEvent, { once: true });
+    });
+  }
+  async function flushSave({ keepalive = false, timeoutMs = 15e3 } = {}) {
+    if (!isEditMode) return { state: "view", etag: null };
+    const deadline = Date.now() + timeoutMs;
+    let timer = null;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(flushError("Save timed out.", "failed")), Math.max(0, timeoutMs));
+    });
+    try {
+      return await Promise.race([flushBytes(keepalive, deadline), timeout]);
+    } catch (err) {
+      if (err && typeof err.state === "string") throw err;
+      throw flushError(err?.message || "Save failed", "failed");
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function flushBytes(keepalive, deadline) {
+    if (!baselineSettled()) await nextEvent("clay:baseline-settled", deadline);
+    let saved = false;
+    let etag = null;
+    for (let attempt = 0; attempt < 4; attempt++) {
+      if (isSaveInProgress()) await settled(deadline);
+      if (isSaveConflicted()) throw flushError("This document has a conflict to resolve.", "conflict");
+      const token = gateCaptureToken();
+      if (!bytesUnsaved()) {
+        gateClearIfUnchanged(token);
+        if (hasUnsavedState()) throw flushError("This document has unsaved work a save cannot write.", "blocked");
+        return { state: saved ? "saved" : "clean", etag: etag ?? lastSeenEtag() };
+      }
+      const result2 = await withKeepalive(keepalive, () => savePage());
+      if (result2.msgType === "skipped") continue;
+      if (!result2.ok) throw flushError(result2.msg || "Save failed", result2.msgType === "conflict" || isSaveConflicted() ? "conflict" : "failed");
+      saved = true;
+      etag = result2.etag ?? null;
+    }
+    throw flushError("The document kept changing while saving.", "failed");
+  }
   async function saveOverwritingConflict(callback = () => {
   }) {
     await seedEtag({ fresh: true });
@@ -3391,7 +3612,7 @@
   function initBaselineCapture() {
     if (!isEditMode) return;
     let userEdited = false;
-    let settled = false;
+    let settled2 = false;
     let unsubscribeMutation = null;
     const { forComparison: immediateContents, forDirty: immediateDirty } = captureForComparisonAndDirty();
     lastSavedContents = immediateContents;
@@ -3406,8 +3627,8 @@
     };
     userEditEvents.forEach((evt) => document.addEventListener(evt, markUserEdited, true));
     const captureBaseline = () => {
-      if (settled) return;
-      settled = true;
+      if (settled2) return;
+      settled2 = true;
       if (unsubscribeMutation) unsubscribeMutation();
       userEditEvents.forEach((evt) => document.removeEventListener(evt, markUserEdited, true));
       if (!userEdited && lastSavedContents === immediateContents && lastSavedDirty === immediateDirty) {
@@ -3431,7 +3652,7 @@
       captureBaseline
     );
     setTimeout(() => {
-      if (!settled) captureBaseline();
+      if (!settled2) captureBaseline();
     }, MAX_SETTLE_MS);
   }
   function savePageThrottled(callback = () => {
@@ -3508,10 +3729,12 @@
       init_snapshot();
       init_etag();
       init_dirty_gate();
+      init_unsaved_state();
       init_autosave_state();
       init_root_attrs();
       init_autosave_debug();
       init_user_gesture();
+      init_unsaved_warning();
       addDocumentTransform((clone) => {
         for (const name of ROOT_LIBRARY_ATTRS) clone.removeAttribute(name);
       });
@@ -3965,98 +4188,6 @@
     }
   });
 
-  // src/lib/unsaved-state.js
-  function registerUnsavedState({ id = "", isPending: isPending2 }) {
-    const key2 = ++nextKey;
-    sources.set(key2, { id, isPending: isPending2 });
-    let disposed = false;
-    return {
-      changed() {
-        if (disposed) return;
-        document.dispatchEvent(new CustomEvent("clay:unsaved-state-changed", {
-          detail: { pending: pendingIds() }
-        }));
-      },
-      dispose() {
-        if (disposed) return;
-        disposed = true;
-        sources.delete(key2);
-      }
-    };
-  }
-  function isPending(source2) {
-    try {
-      return !!source2.isPending();
-    } catch (err) {
-      console.error(`[clay] unsaved-state check "${source2.id}" threw`, err);
-      return true;
-    }
-  }
-  function pendingIds() {
-    return [...sources.values()].filter(isPending).map((s2) => s2.id);
-  }
-  function hasUnsavedState() {
-    for (const source2 of sources.values()) if (isPending(source2)) return true;
-    return false;
-  }
-  var sources, nextKey;
-  var init_unsaved_state = __esm({
-    "src/lib/unsaved-state.js"() {
-      sources = /* @__PURE__ */ new Map();
-      nextKey = 0;
-      if (typeof window !== "undefined") {
-        window.clay = window.clay || {};
-        window.clay.registerUnsavedState = registerUnsavedState;
-      }
-    }
-  });
-
-  // src/core/unsaved-warning.js
-  var unsaved_warning_exports = {};
-  __export(unsaved_warning_exports, {
-    reloadAfterDiscard: () => reloadAfterDiscard
-  });
-  function reloadAfterDiscard({ isCurrent, reload }) {
-    if (!isCurrent()) return false;
-    discardPermit = true;
-    setTimeout(() => {
-      discardPermit = false;
-    }, 1e3);
-    reload();
-    return true;
-  }
-  var discardPermit;
-  var init_unsaved_warning = __esm({
-    "src/core/unsaved-warning.js"() {
-      init_is_edit_mode();
-      init_snapshot();
-      init_save();
-      init_autosave_debug();
-      init_unsaved_state();
-      discardPermit = false;
-      preloadIfEnabled();
-      window.addEventListener("beforeunload", (event) => {
-        if (!isEditMode) return;
-        if (discardPermit) {
-          discardPermit = false;
-          return;
-        }
-        const held = hasUnsavedState();
-        let bytesDiffer = false;
-        if (!held && !window.clay?.demo) {
-          const currentForCompare = captureForDirtyCheck();
-          const lastSaved = getLastSavedDirty();
-          bytesDiffer = currentForCompare !== lastSaved;
-          if (bytesDiffer) logUnloadDiffSync(currentForCompare, lastSaved);
-        }
-        if (held || bytesDiffer) {
-          event.preventDefault();
-          event.returnValue = "";
-        }
-      });
-    }
-  });
-
   // src/vendor/hyper-morph.vendor.js
   var hyper_morph_vendor_exports = {};
   __export(hyper_morph_vendor_exports, {
@@ -10603,10 +10734,10 @@
         }
         _flushQueuedSend() {
           if (this.isDestroyed || this._sendInFlight) return;
-          const queued = this._queuedSend;
-          if (!queued) return;
+          const queued2 = this._queuedSend;
+          if (!queued2) return;
           this._queuedSend = null;
-          this._postUpdate(queued.html, queued.identityMap, queued.etag);
+          this._postUpdate(queued2.html, queued2.identityMap, queued2.etag);
         }
         /**
          * Tell the other editors what this tab's save stored, and under which stamp.
@@ -10660,10 +10791,10 @@
             retry = true;
           }).finally(() => {
             this._sendInFlight = false;
-            const queued = this._queuedSend;
+            const queued2 = this._queuedSend;
             this._queuedSend = null;
-            if (queued) {
-              this._postUpdate(queued.html, queued.identityMap, queued.etag);
+            if (queued2) {
+              this._postUpdate(queued2.html, queued2.identityMap, queued2.etag);
               return;
             }
             if (!retry || !etag || attempt >= 3 || this.isDestroyed) return;
@@ -25244,10 +25375,10 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
           );
           return canvas;
         }
-        let settled = false;
+        let settled2 = false;
         const finishOnce = () => {
-          if (settled) return false;
-          settled = true;
+          if (settled2) return false;
+          settled2 = true;
           host.close();
           URL.revokeObjectURL(url);
           active2 = false;
@@ -25257,7 +25388,7 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
           content: stage,
           confirmLabel,
           onConfirm() {
-            if (settled) return;
+            if (settled2) return;
             let canvas, dataURL;
             try {
               canvas = renderCrop();
@@ -25606,10 +25737,10 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
       const path = token ? `${UPLOAD_PATH}/${token}` : UPLOAD_PATH;
       const url = new URL(path, window.location.origin).href;
       const xhr = new XMLHttpRequest();
-      let settled = false;
+      let settled2 = false;
       const finish2 = (value) => {
-        if (settled) return;
-        settled = true;
+        if (settled2) return;
+        settled2 = true;
         clearTimeout(timeoutId);
         if (signal) signal.removeEventListener("abort", onAbort);
         resolve(value);
@@ -25779,10 +25910,10 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
     stream.onerror = () => {
     };
     streamReady = new Promise((resolve) => {
-      let settled = false;
+      let settled2 = false;
       const finish2 = () => {
-        if (settled) return;
-        settled = true;
+        if (settled2) return;
+        settled2 = true;
         resolve();
       };
       stream.onopen = finish2;
@@ -25957,7 +26088,7 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
       setTimeout(settle3, timeout);
     });
   }
-  async function flushSave() {
+  async function flushSave2() {
     if (!isEditMode) return;
     const clay4 = window.clay;
     if (!clay4 || typeof clay4.save !== "function") return;
@@ -26076,7 +26207,7 @@ tr.hcms-shell.hcms-inline-ghost { display: table-row; }
       if (rec.document === "edit") {
         await holdSaving(rec);
         if (rec.state !== "sent") return;
-        await flushSave();
+        await flushSave2();
         if (rec.state !== "sent") return;
       }
       await openStream();
@@ -36080,10 +36211,10 @@ ${t}` : `"use strict"; return (${t});`;
             onYes = [];
             onNo = [];
             onOpen = [];
-            let settled = false;
+            let settled2 = false;
             const dismiss3 = () => {
-              if (settled) return;
-              settled = true;
+              if (settled2) return;
+              settled2 = true;
               myOnNo.forEach((cb) => cb());
             };
             if (this.isShowing || document.querySelector("[data-clay-modal]")) {
@@ -36149,7 +36280,7 @@ ${t}` : `"use strict"; return (${t});`;
                   }
                 }
                 if (shouldClose) {
-                  settled = true;
+                  settled2 = true;
                   MicroModal.close();
                 }
               }
@@ -37110,8 +37241,10 @@ ${t}` : `"use strict"; return (${t});`;
       const saveFn = save.savePage || save.default;
       saveFn.force = save.savePageForce;
       saveFn.overwrite = save.saveOverwritingConflict;
+      saveFn.flush = save.flushSave;
       clay4.save = saveFn;
     }
+    clay4.hasUnsavedChanges = loaded["core/unsaved-warning.js"]?.hasUnsavedChanges ?? (() => false);
     if (snapshot) {
       clay4.getHTML = snapshot.getPageContents;
       clay4.addDocumentTransform = snapshot.addDocumentTransform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",

package/src/core/save-core.js

@@ -25,6 +25,12 @@ import {
 let saveInProgress = false;
 const SAVE_PATH = '/_/save';
 const SAVE_TIMEOUT_MS = 12000;
+// The browser caps a keepalive body (Chromium refuses one over 64 KB), and it counts
+// BYTES: the hint is only attached to a save whose UTF-8 encoding fits well inside that.
+const KEEPALIVE_MAX_BODY = 60000;
+// Set by `withKeepalive`, read once by the next `sendOnce`: the hint belongs to one
+// request, not to the save pipeline.
+let nextSaveKeepalive = false;
 
 // Listeners for "the host took these exact bytes". This is the only place in the
 // library that knows both the body that went out and that the host accepted it, and
@@ -37,6 +43,26 @@ const SAVE_TIMEOUT_MS = 12000;
 // CustomEvent would put it on a bus any script on the page can listen to.
 const saveAcceptedHooks = [];
 
+/**
+ * Send the next save with `keepalive`, so a request whose page is going away (a tab
+ * closing, a navigation) is still finished by the transport.
+ *
+ * A transport hint and nothing more: the save is the same save, and the body has to
+ * fit the browser's keepalive cap for the hint to go on the wire at all.
+ *
+ * @param {boolean} keepalive
+ * @param {Function} run - the save to run with the hint set
+ * @returns {Promise<Object>} whatever `run` resolves with
+ */
+export async function withKeepalive(keepalive, run) {
+  nextSaveKeepalive = Boolean(keepalive);
+  try {
+    return await run();
+  } finally {
+    nextSaveKeepalive = false;
+  }
+}
+
 /**
  * Check if a save is currently in progress.
  * @returns {boolean}
@@ -258,9 +284,10 @@ function skippedResult(msg) {
  * @param {AbortSignal} signal
  * @param {string} saveId - this attempt's §6 receipt id
  * @param {?string} etag - the stamp to send as If-Match, or null
+ * @param {boolean} keepalive - whether to ask the transport to see the request through
  * @returns {{url: string, options: Object}}
  */
-function buildSaveRequest(content, userDriven, signal, saveId, etag) {
+function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false) {
   const token = saveToken();
   const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
   const options = {
@@ -287,6 +314,8 @@ function buildSaveRequest(content, userDriven, signal, saveId, etag) {
 
   if (etag) options.headers['If-Match'] = etag;
 
+  if (keepalive && new Blob([content]).size < KEEPALIVE_MAX_BODY) options.keepalive = true;
+
   return { url: resolveSaveUrl(path), options };
 }
 
@@ -357,7 +386,11 @@ function sendOnce(content, saveId, etag) {
   const gestureDriven = consumeUserDriven();
   const explicitlyAsked = consumeExplicitSave();
   const userDriven = gestureDriven || explicitlyAsked;
-  const { url, options } = buildSaveRequest(content, userDriven, controller.signal, saveId, etag);
+  // Read-and-reset here too, at the one send that can still honour it: a save that
+  // returns early never reaches this point, so the hint cannot leak onto a later one.
+  const keepalive = nextSaveKeepalive;
+  nextSaveKeepalive = false;
+  const { url, options } = buildSaveRequest(content, userDriven, controller.signal, saveId, etag, keepalive);
   rememberSentId(saveId);
 
   return fetch(url, options)

package/src/core/save.js

@@ -18,15 +18,22 @@ import {
   replacePageWith as replacePageWithCore,
   addDocumentTransform,
   isSaveInProgress,
-  saveFateIsUnknown
+  saveFateIsUnknown,
+  withKeepalive
 } from "./save-core.js";
 import { captureForComparison, captureForComparisonAndDirty, captureForSaveAndComparison } from "./snapshot.js";
-import { seedEtag } from "./etag.js";
+import { seedEtag, lastSeenEtag } from "./etag.js";
 import { gateCaptureToken, gateClearIfUnchanged, pageMaybeDirty } from "../lib/dirty-gate.js";
+import { hasUnsavedState } from "../lib/unsaved-state.js";
 import { autosaveActive } from "../lib/autosave-state.js";
 import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 import { initUserGesture, markExplicitSave, clearExplicitSave } from "../lib/user-gesture.js";
+// A deliberate import cycle: unsaved-warning reads this module's saved baseline, and
+// flush asks the SAME bytes question the close warning asks, through `bytesUnsaved`.
+// Both read across it at call time, never while a module is evaluating, so neither
+// side sees a half-built module.
+import { bytesUnsaved } from "./unsaved-warning.js";
 
 // Keep this library's own root state out of the saved bytes.
 //
@@ -560,6 +567,101 @@ export function savePageForce(callback = () => {}) {
   });
 }
 
+// Resolve on the next save that settles, or reject once the deadline has passed.
+// Every settled state is one, not just success: a save that failed is an answer about
+// the page's bytes too, and the caller decides what to do with it.
+function settled(deadline) {
+  const events = ['clay:save-saved', 'clay:save-error', 'clay:save-offline', 'clay:save-conflict'];
+  return new Promise((resolve, reject) => {
+    let timer = null;
+    const cleanup = () => {
+      clearTimeout(timer);
+      for (const name of events) document.removeEventListener(name, onSettle);
+    };
+    const onSettle = () => {
+      cleanup();
+      resolve();
+    };
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      reject(Object.assign(new Error('Save timed out.'), { state: 'failed' }));
+      return;
+    }
+    timer = setTimeout(() => {
+      cleanup();
+      reject(Object.assign(new Error('Save timed out.'), { state: 'failed' }));
+    }, remaining);
+    for (const name of events) document.addEventListener(name, onSettle);
+  });
+}
+
+function flushError(message, state) {
+  return Object.assign(new Error(message), { state });
+}
+
+// Resolve when `name` fires on document, or reject at the deadline.
+function nextEvent(name, deadline) {
+  return new Promise((resolve, reject) => {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return reject(flushError('Save timed out.', 'failed'));
+    const timer = setTimeout(() => {
+      document.removeEventListener(name, onEvent);
+      reject(flushError('Save timed out.', 'failed'));
+    }, remaining);
+    const onEvent = () => { clearTimeout(timer); resolve(); };
+    document.addEventListener(name, onEvent, { once: true });
+  });
+}
+
+// Save now; answer only when the host has accepted the bytes the page holds now.
+// Resolves { state: 'view' | 'clean' | 'saved', etag }. Rejects with an Error carrying
+// state 'failed' (including a timeout), 'conflict', or 'blocked' (the bytes are on the
+// host but the page holds work a save cannot write, registered through
+// clay.registerUnsavedState; only a person can resolve that). Never overwrites.
+// `keepalive` is a transport hint honoured under 60 KB of UTF-8.
+export async function flushSave({ keepalive = false, timeoutMs = 15000 } = {}) {
+  if (!isEditMode) return { state: 'view', etag: null };
+  const deadline = Date.now() + timeoutMs;
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(flushError('Save timed out.', 'failed')), Math.max(0, timeoutMs));
+  });
+  try {
+    return await Promise.race([flushBytes(keepalive, deadline), timeout]);
+  } catch (err) {
+    if (err && typeof err.state === 'string') throw err;
+    throw flushError(err?.message || 'Save failed', 'failed');
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function flushBytes(keepalive, deadline) {
+  // Load-time module churn is not the person's work: autosave never saves it, and
+  // neither does a flush. Wait for the baseline to settle (at most MAX_SETTLE_MS).
+  if (!baselineSettled()) await nextEvent('clay:baseline-settled', deadline);
+
+  let saved = false;
+  let etag = null;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (isSaveInProgress()) await settled(deadline);
+    if (isSaveConflicted()) throw flushError('This document has a conflict to resolve.', 'conflict');
+    const token = gateCaptureToken();
+    if (!bytesUnsaved()) {
+      gateClearIfUnchanged(token);
+      if (hasUnsavedState()) throw flushError('This document has unsaved work a save cannot write.', 'blocked');
+      return { state: saved ? 'saved' : 'clean', etag: etag ?? lastSeenEtag() };
+    }
+    const result = await withKeepalive(keepalive, () => savePage());
+    // The lane was busy (a drained pending save is on the wire): wait it out next turn.
+    if (result.msgType === 'skipped') continue;
+    if (!result.ok) throw flushError(result.msg || 'Save failed', result.msgType === 'conflict' || isSaveConflicted() ? 'conflict' : 'failed');
+    saved = true;
+    etag = result.etag ?? null;
+  }
+  throw flushError('The document kept changing while saving.', 'failed');
+}
+
 /**
  * Keep this tab's version, over the one the host is holding.
  *

package/src/core/unsaved-warning.js

@@ -43,6 +43,39 @@ preloadIfEnabled();
 // sandboxed document, which cannot read cookies at all. Those are exactly the
 // documents where an unsaved edit is easiest to lose. If the page is editable,
 // the person editing it deserves the warning.
+//
+// The same predicate is exposed as `clay.hasUnsavedChanges`, which a host asks
+// synchronously before deciding whether a save is worth asking for.
+export function hasUnsavedChanges() {
+  if (!isEditMode) return false;
+
+  // Work outside the DOM first: it needs no capture, and a capture that throws
+  // must not hide it. The demo plugin does not save it either, so it warns there too.
+  if (hasUnsavedState()) return true;
+
+  // The demo plugin saves the page's bytes into this browser's own storage, so
+  // leaving loses none of them.
+  if (window.clay?.demo) return false;
+
+  return bytesUnsaved();
+}
+
+// The page's own bytes against the last bytes the host accepted. A capture that throws
+// counts as unsaved: something on the page is broken, and "nothing to lose" is the one
+// answer that can lose work.
+//
+// The DIRTY domain, not the autosave domain. An edit inside a no-trigger-autosave
+// region never starts a save by itself, which is exactly why closing the tab on one has
+// to warn: nothing else is going to write it.
+export function bytesUnsaved() {
+  if (!isEditMode) return false;
+  try {
+    return captureForDirtyCheck() !== getLastSavedDirty();
+  } catch {
+    return true;
+  }
+}
+
 window.addEventListener('beforeunload', (event) => {
   if (!isEditMode) return;
 
@@ -51,26 +84,16 @@ window.addEventListener('beforeunload', (event) => {
     return;
   }
 
-  // Work outside the DOM first: it needs no capture, and a capture that throws
-  // must not hide it. The demo plugin does not save it either, so it warns there too.
-  const held = hasUnsavedState();
-
-  // The demo plugin saves the page's bytes into this browser's own storage, so
-  // leaving loses none of them.
-  let bytesDiffer = false;
-  if (!held && !window.clay?.demo) {
-    // The DIRTY domain, not the autosave domain. An edit inside a
-    // no-trigger-autosave region never starts a save by itself, which is exactly
-    // why closing the tab on one has to warn: nothing else is going to write it.
-    const currentForCompare = captureForDirtyCheck();
-    const lastSaved = getLastSavedDirty();
-    bytesDiffer = currentForCompare !== lastSaved;
-    // Debug: log what's different before showing the warning
-    if (bytesDiffer) logUnloadDiffSync(currentForCompare, lastSaved);
-  }
+  if (!hasUnsavedChanges()) return;
 
-  if (held || bytesDiffer) {
-    event.preventDefault();
-    event.returnValue = '';
+  event.preventDefault();
+  event.returnValue = '';
+  // Debug only, after the decision: a capture that throws here must not cancel the warning.
+  if (!window.clay?.demo && !hasUnsavedState()) {
+    try {
+      const currentForCompare = captureForDirtyCheck();
+      const lastSaved = getLastSavedDirty();
+      if (currentForCompare !== lastSaved) logUnloadDiffSync(currentForCompare, lastSaved);
+    } catch {}
   }
 });

package/src/lib/dirty-gate.js

@@ -35,6 +35,26 @@ let clearedAt = 0;
 let paused = false;
 let started = false;
 
+// The state change, announced on the document: `clay:dirty` when work nothing has
+// written appears, `clay:clean` when a save (or the oracle) has accounted for it. A
+// burst of edits is ONE announcement, since what a listener wants is the state, not
+// the edit. Only a transition is dispatched.
+let announcedDirty = false;
+let queued = false;
+
+function scheduleAnnounce() {
+  if (!isEditMode || queued) return;
+  queued = true;
+  queueMicrotask(() => {
+    queued = false;
+    if (typeof document === 'undefined') return;
+    const dirty = pageMaybeDirty();
+    if (dirty === announcedDirty) return;
+    announcedDirty = dirty;
+    document.dispatchEvent(new CustomEvent(dirty ? 'clay:dirty' : 'clay:clean'));
+  });
+}
+
 const PERSIST_CONTROLS = `input${PERSIST}, textarea${PERSIST}, select${PERSIST}`;
 
 // Regions the loss oracle never sees. The hub feed already skips them, through
@@ -81,6 +101,7 @@ function onUserInput(event) {
   if (!(el.matches('input, textarea, select') || el.isContentEditable)) return;
   if (el.closest(GATE_IGNORE)) return;
   changes++;
+  scheduleAnnounce();
 }
 
 export function startDirtyGate() {
@@ -89,7 +110,10 @@ export function startDirtyGate() {
   Mutation.onAnyChange(
     { omitChangeDetails: true, require: 'dirty' },
     () => {
-      if (!paused) changes++;
+      if (!paused) {
+        changes++;
+        scheduleAnnounce();
+      }
     }
   );
   document.addEventListener('input', onUserInput, true);
@@ -151,6 +175,7 @@ export function probeMarkClean() {
   for (const el of gatedPersistControls()) {
     probeCache.set(el, controlSignature(el));
   }
+  scheduleAnnounce();
 }
 
 export function pageMaybeDirty() {
@@ -173,6 +198,7 @@ export function gateCaptureToken() {
 /** A change nothing in the DOM recorded: the page holds text a save has not written. */
 export function gateMarkDirty() {
   changes++;
+  scheduleAnnounce();
 }
 
 export function gateClearIfUnchanged(token) {
@@ -186,6 +212,7 @@ export function gateClearIfUnchanged(token) {
   for (const [el, sig] of token.probe) {
     if (controlSignature(el) === sig) probeCache.set(el, sig);
   }
+  scheduleAnnounce();
 }
 
 if (typeof document !== 'undefined' && isEditMode) {

package/src/loader.js

@@ -88,8 +88,14 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
     const saveFn = save.savePage || save.default;
     saveFn.force = save.savePageForce;
     saveFn.overwrite = save.saveOverwritingConflict;
+    saveFn.flush = save.flushSave;
     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);
   if (snapshot) {
     clay.getHTML = snapshot.getPageContents;
     clay.addDocumentTransform = snapshot.addDocumentTransform;