@panphora/clayjs 1.23.0 → 1.24.1

package/src/core/save-core.js

@@ -85,6 +85,20 @@ export function setSaveHeader(name, value) {
   else extraSaveHeaders.set(name, String(value));
 }
 
+// Headers that depend on the bytes of one save. Each source gets the exact string being
+// sent and returns `{ name: value }` or null. A source that throws is skipped: a save
+// must not fail because a header could not be computed.
+const saveHeaderSources = new Set();
+
+/**
+ * @param {(content: string) => (Object<string, string>|null)} source
+ * @returns {() => void} removes the source
+ */
+export function addSaveHeaderSource(source) {
+  saveHeaderSources.add(source);
+  return () => saveHeaderSources.delete(source);
+}
+
 /**
  * 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.
@@ -229,7 +243,10 @@ function successResult(data) {
     msg: data.msg ?? 'Saved',
     msgType: data.msgType || 'success',
     code: data.code ?? null,
-    etag: data.etag ?? null
+    etag: data.etag ?? null,
+    // A multi-page host's answer about shared values: which declared keys it stored,
+    // which it refused, and which values this tab is behind on. Absent on every other save.
+    ...(data.siteData ? { siteData: data.siteData } : {})
   };
 }
 
@@ -359,7 +376,7 @@ function errorResult(err) {
     // An attempt of this save timed out, so it may have landed whatever the
     // final answer says.
     hadTimeout: timedOut || err.hadTimeout === true,
-    // The typed refusal behind `code`, kept for the caller: `page-capacity` carries
+    // The typed refusal behind `code`, kept for the caller: `blockeditor-capacity` carries
     // which limit was hit, the conversion codes carry which condition failed.
     reason: err.reason ?? null,
     // Only meaningful while a save can still retry; a caller sees how long the
@@ -428,7 +445,7 @@ function invalidHeaderResult() {
 }
 
 // How many extra sends one logical save may make while the host is still
-// converting the page. `page-converting` is a pre-commit refusal, so the same
+// converting the page. `blockeditor-converting` is a pre-commit refusal, so the same
 // body is worth offering again; anything else is surfaced on the first answer.
 const PAGE_CONVERTING_MAX_RETRIES = 3;
 const HTTP_DATE = /^(?:(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT|(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), \d{2}-(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-\d{2} \d{2}:\d{2}:\d{2} GMT|(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?: \d|\d{2}) \d{2}:\d{2}:\d{2} \d{4})$/;
@@ -452,7 +469,7 @@ function parseRetryAfter(value) {
   return Math.max(0, Math.min(3600, Math.round((when - Date.now()) / 1000)));
 }
 
-// The host grammar for `Page-Conversion`, from `server-lib/page-conversion.js`:
+// The host grammar for `Blockeditor-Conversion`, from `server-lib/page-conversion.js`:
 // `file` takes a 64-lowercase-hex baseline and no epoch; `room` takes the same
 // baseline plus an epoch of [A-Za-z0-9-]{1,64}. Validating here means a caller
 // with bad metadata gets a typed answer instead of a wasted round trip.
@@ -518,10 +535,11 @@ function formatConversionHeader(conversion) {
  * @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
- * @param {?string} conversionHeader - the `Page-Conversion` value for this logical save, or null
+ * @param {?string} conversionHeader - the `Blockeditor-Conversion` value for this logical save, or null
+ * @param {boolean} perSaveHeaders - false for a lane that sends bytes this tab did not edit (replace), which declares nothing about them
  * @returns {{url: string, options: Object}}
  */
-export function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false, conversionHeader = null) {
+export function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false, conversionHeader = null, perSaveHeaders = true) {
   const token = saveToken();
   const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
   const options = {
@@ -552,6 +570,18 @@ export function buildSaveRequest(content, userDriven, signal, saveId, etag, keep
 
   for (const [name, value] of extraSaveHeaders) options.headers[name] = value;
 
+  if (perSaveHeaders) {
+    for (const source of saveHeaderSources) {
+      let extra = null;
+      try {
+        extra = source(content);
+      } catch (err) {
+        console.error('clayjs: a save header source failed:', err);
+      }
+      if (extra) for (const [name, value] of Object.entries(extra)) options.headers[name] = String(value);
+    }
+  }
+
   // Set after the process-global headers so the type describing THESE bytes is the one
   // that goes out, the same rule the conversion header below follows.
   if (typeof options.body !== 'string') options.headers['Content-Type'] = SAVE_BODY_TYPE;
@@ -559,7 +589,7 @@ export function buildSaveRequest(content, userDriven, signal, saveId, etag, keep
   // The conversion request belongs to ONE logical save, and goes on every attempt
   // of it. Set after the process-global headers so the capture-bound value is the
   // one that describes these bytes.
-  if (conversionHeader) options.headers['Page-Conversion'] = conversionHeader;
+  if (conversionHeader) options.headers['Blockeditor-Conversion'] = conversionHeader;
 
   if (etag) options.headers['If-Match'] = etag;
 
@@ -638,14 +668,13 @@ function draftResponse(status, body) {
 function sendToDraftStore(content) {
   const send = draftTransport();
   if (!send) return Promise.resolve(draftResponse(503, { msg: "Saving in this browser is not ready yet", msgType: "error", code: "draft-not-ready" }));
-  return Promise.resolve().then(() => {
-    try {
-      send(content);
-      return draftResponse(200, { msg: "Saved in this browser", msgType: "success" });
-    } catch (error) {
-      return draftResponse(507, { msg: "Couldn't save in this browser. Storage is full or turned off.", msgType: "error", code: error.code || "draft-storage" });
-    }
-  });
+  // The transport's promise settles once the draft database holds the save.
+  return Promise.resolve()
+    .then(() => send(content))
+    .then(
+      () => draftResponse(200, { msg: "Saved in this browser", msgType: "success" }),
+      (error) => draftResponse(507, { msg: "Couldn't save in this browser. Storage is full or turned off.", msgType: "error", code: error?.code || "draft-storage" }),
+    );
 }
 
 /**
@@ -876,7 +905,7 @@ async function sendSave(content, { captureId = null, conversionHeader = null, at
   // is fast and conclusive, so it gets its own turn regardless.
   let reSent = false;
   let duplicateResolved = false;
-  // `page-converting` is the one refusal that is worth offering the same bytes
+  // `blockeditor-converting` is the one refusal that is worth offering the same bytes
   // again: the host has written nothing and is telling us when it expects to be
   // ready. The capture these bytes came from is pinned here, so a capture made
   // while we wait — newer edits, a disk frame — cancels the retry instead of
@@ -916,7 +945,7 @@ async function sendSave(content, { captureId = null, conversionHeader = null, at
         continue;
       }
 
-      if (err.code === 'page-converting' && convertingRetries < PAGE_CONVERTING_MAX_RETRIES) {
+      if (err.code === 'blockeditor-converting' && convertingRetries < PAGE_CONVERTING_MAX_RETRIES) {
         if (currentCaptureId() !== retryGuard) throw err;
         convertingRetries += 1;
         // Default a missing or unparseable header to one second, so a host that
@@ -939,14 +968,14 @@ async function sendSave(content, { captureId = null, conversionHeader = null, at
 // thing whether the bytes came from a bound capture or a raw caller. `captureId`
 // is null for a raw save: it belongs to no capture and can confirm none.
 //
-// `pageFormatFloor` is internal: one save may carry a floor this tab has not
+// `blockeditorFormatFloor` is internal: one save may carry a floor this tab has not
 // noted yet, which is how the format gate's activation writes the marker. It
 // raises these bytes only, never what the tab knows the document at.
-function runSave(html, captureId, callback, conversion, capture = null, pageFormatFloor = 0, lane = null) {
+function runSave(html, captureId, callback, conversion, capture = null, blockeditorFormatFloor = 0, lane = null) {
   // A capture taken before the floor rose cannot drop the marker by omitting it:
   // the bytes that go out carry the floor this tab last saw. At floor 0 this is
   // the string itself, unchanged.
-  html = withPageFormatFloor(html, Math.max(knownPageFormatFloor(), pageFormatFloor));
+  html = withPageFormatFloor(html, Math.max(knownPageFormatFloor(), blockeditorFormatFloor));
   return new Promise((resolve) => {
     const attempts = [];
     // Read once, before the first request: the artifact belongs to the capture that
@@ -1021,7 +1050,7 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
         // same measurement. Its own answer about the size wins over nothing: the bytes
         // are this attempt's, and the limit is still only what discovery advertised.
         if (result.code === 'save-too-large' && !result.size) result.size = size;
-        if (result.ok) notifySaveAccepted(html, captureId ?? null, artifact);
+        if (result.ok) notifySaveAccepted(html, captureId ?? null, artifact, result.siteData ?? null);
         finished(result);
       });
   });
@@ -1059,8 +1088,8 @@ export function saveHtml(html, callback = () => {}) {
  * @param {Object} [options.conversion] - {source:'file', base} or {source:'room', base, epoch}
  * @returns {Promise<Object>}
  */
-export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion, capture = null, pageFormatFloor, lane = null } = {}) {
-  return runSave(html, captureId, callback, conversion, capture, pageFormatFloor, lane);
+export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion, capture = null, blockeditorFormatFloor, lane = null } = {}) {
+  return runSave(html, captureId, callback, conversion, capture, blockeditorFormatFloor, lane);
 }
 
 /**

package/src/core/save-failure-notice.js

@@ -0,0 +1,37 @@
+import { saveFeedback } from "./save-feedback.js";
+import { toastPersistent, dismissPersistent, preload } from "../ui/toast-lazy.js";
+
+// A failed save is never silent. core/save.js fetches this file at the person's first
+// input and hands it every failed save no listener claimed. A page with the indicator chip, clay-ui or its own
+// notices (`clay.saveFeedback = "own"`) already reports failures, so nothing is added
+// there. Everywhere else the toast stack shows what clay-ui would have shown. Core keeps
+// calling in for every later save, so a failure the block editor claims stays its own,
+// and the next save that lands takes the toast down. The toast stack is the block
+// editor's too, so its dismissals reach these toasts.
+const TOASTS = {
+  error: ["Couldn't save", "error"],
+  offline: ["Offline, will retry", "warning"],
+};
+
+let shown = false;
+
+const unheard = () => !(saveFeedback.chip || saveFeedback.toasts || window.clay?.saveFeedback === "own");
+
+// core/save.js calls this at the person's first input, so the toast can still show offline.
+export function warm() {
+  if (unheard()) preload();
+}
+
+export function reportFailure(state) {
+  if (!TOASTS[state] || !unheard()) return;
+  shown = true;
+  // One failure notice at a time: a connection that comes and goes swaps them.
+  for (const [other, [message]] of Object.entries(TOASTS)) if (other !== state) dismissPersistent(message);
+  toastPersistent(...TOASTS[state]);
+}
+
+export function clearFailures() {
+  if (!shown) return;
+  shown = false;
+  for (const [message] of Object.values(TOASTS)) dismissPersistent(message);
+}

package/src/core/save-feedback.js

@@ -4,3 +4,9 @@
 // read them only when an event arrives, so load order does not matter. savedToast is
 // the page's `clay.saveToast` switch: Saved goes to a toast instead of the chip.
 export const saveFeedback = { chip: false, toasts: false, savedToast: false };
+
+// Set on a failed save's event detail by a listener that put its own notice up (the block
+// editor's retry and blocked notices), so the chip and the fallback toast stay out of it.
+// core/save.js writes the same key without importing this file, which the edit boot does
+// not otherwise fetch.
+export const FAILURE_CLAIMED = Symbol.for("clay.saveFailureClaimed");

package/src/core/save-replace.js

@@ -46,7 +46,7 @@ export async function replace(html, { etag } = {}) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const { url, options } = buildSaveRequest(html, true, controller.signal, mintSaveId(), stamp);
+    const { url, options } = buildSaveRequest(html, true, controller.signal, mintSaveId(), stamp, false, null, false);
     const res = await fetch(url, options);
     const text = await res.text();
     let data = {};

package/src/core/save-size.js

@@ -32,13 +32,13 @@ function adopt(meta) {
   return limit;
 }
 
-// A Document's live state rides in one <script merge="page"> tag that Hyperclay
+// A Document's live state rides in one <script merge="blockeditor"> tag that Hyperclay
 // stores apart from the file, and its limit (`maxBytesMeasures: 'file'`) is judged on
 // the body without that tag, the way the host's splitPage() cuts it: the whole line
 // when the tag stands alone on it, otherwise the tag itself. Where the host would not
 // split (no tag, two tags), the cut here can only make the count smaller, so the
 // host's own 413 stays the answer and nothing is refused that the host would store.
-const PAGE_TAG = /<script\b[^>]*\bmerge=(["'])page\1[^>]*>[\s\S]*?<\/script\s*>/i;
+const PAGE_TAG = /<script\b[^>]*\bmerge=(["'])blockeditor\1[^>]*>[\s\S]*?<\/script\s*>/i;
 
 export function storedFile(html, measure = measures) {
   if (measure !== 'file' || typeof html !== 'string') return html;

package/src/core/save.js

@@ -111,6 +111,43 @@ function setSaveState(state, msg = '', msgType = '', extra = null) {
     detail: { msg, msgType, timestamp: Date.now(), ...(extra || {}) }
   });
   document.dispatchEvent(event);
+  reportIfUnheard(state, event.detail);
+}
+
+// A failed save is never silent. Every listener has seen the event by now; a listener
+// that put its own notice up (the block editor's retry and blocked notices) claimed it.
+// The rest goes to save-failure-notice.js, which shows a toast when nothing else on the
+// page reports failures and takes it down when a later save lands. The claim key is
+// save-feedback.js's FAILURE_CLAIMED.
+const FAILURE_CLAIMED = Symbol.for('clay.saveFailureClaimed');
+export const claimFailure = (event) => { if (event?.detail) event.detail[FAILURE_CLAIMED] = true; };
+
+let failureNotice = null;
+const loadFailureNotice = () => {
+  failureNotice ??= import('./save-failure-notice.js').catch((error) => {
+    failureNotice = null;
+    throw error;
+  });
+  return failureNotice;
+};
+
+// A save fails offline most of all, when nothing more can be downloaded. So the notice and
+// the toast stack it needs arrive at the person's first input, as the indicator's chip
+// does, never at boot.
+const warmFailureNotice = () => { loadFailureNotice().then((m) => m.warm(), () => {}); };
+for (const type of ['beforeinput', 'keydown', 'pointerdown']) {
+  document.addEventListener(type, warmFailureNotice, { once: true, capture: true });
+}
+
+function reportIfUnheard(state, detail) {
+  if (state === 'saved') {
+    failureNotice?.then((m) => m.clearFailures(), () => {});
+    return;
+  }
+  if ((state !== 'error' && state !== 'offline') || detail?.[FAILURE_CLAIMED]) return;
+  loadFailureNotice().then((m) => m.reportFailure(state), (error) => {
+    console.error('clayjs: a save failed and the notice for it could not be downloaded', error);
+  });
 }
 
 /**
@@ -931,7 +968,7 @@ function prepareInvalidation(ctx, epoch, morph) {
   if (!savesAdmitted(ctx.permit)) return 'session';
   if (refusesSave()) return 'refused';
   if (baselineRevision !== epoch.baselines) return 'newer save';
-  if (Math.max(knownPageFormatFloor(), ctx.pageFormatFloor) > epoch.floor) return 'floor';
+  if (Math.max(knownPageFormatFloor(), ctx.blockeditorFormatFloor) > epoch.floor) return 'floor';
   return null;
 }
 
@@ -969,7 +1006,7 @@ async function settleCaptured({
   captureId,
   gateToken,
   costMs,
-  pageFormatFloor = 0,
+  blockeditorFormatFloor = 0,
   quietConflict = false,
   laneHeld = false,
   lane = null,
@@ -1069,7 +1106,7 @@ async function settleCaptured({
       // lane busy and waits that request out, which is what its 'clean' answer describes.
       // A prepared save holds the lane itself, so its caller does the draining instead.
       if (!laneHeld) drainPendingSave();
-    }, { capture, pageFormatFloor, lane });
+    }, { capture, blockeditorFormatFloor, lane });
   });
 }
 
@@ -1092,7 +1129,7 @@ async function runSlicedSave(ctx, lane) {
       const epoch = {
         generation: saveGenerationAt,
         baselines: baselineRevision,
-        floor: Math.max(knownPageFormatFloor(), ctx.pageFormatFloor),
+        floor: Math.max(knownPageFormatFloor(), ctx.blockeditorFormatFloor),
       };
       const job = prepDriver.beginSaveCapture({
         requestRefresh: true,
@@ -1135,7 +1172,7 @@ async function runSlicedSave(ctx, lane) {
           captureId: captured.captureId,
           gateToken,
           costMs: prepared.activeMs,
-          pageFormatFloor: ctx.pageFormatFloor,
+          blockeditorFormatFloor: ctx.blockeditorFormatFloor,
           quietConflict: ctx.quietConflict,
           laneHeld: true,
           lane,
@@ -1225,6 +1262,32 @@ function attemptSave(options, callback = () => {}) {
   return adoptionQueue.then(() => attemptSaveNow(options, callback));
 }
 
+// A save waiting on something it needs before its capture: the source map's install, or
+// the preparer loaded on demand. The chip moves only on save events, so without this it
+// kept its last word, usually "Saved", for the whole wait, which on a host whose every
+// connection was held open lasted until a tab closed. Past the usual 500 ms it says
+// 'saving'; if the attempt then sends nothing and the page has nothing left to save, it
+// goes back to 'saved' through `clay:save-status`, never `clay:save-saved`, which would
+// run every [onaftersave] handler as though a save had happened.
+function afterWait(wait, attempt) {
+  let shown = false;
+  const timer = setTimeout(() => {
+    shown = true;
+    setSaveState('saving');
+  }, 500);
+  return wait.then(() => {
+    clearTimeout(timer);
+    return attempt();
+  }).then((result) => {
+    if (shown && !isSaveInProgress() && !pageMaybeDirty()
+        && document.documentElement.getAttribute('savestatus') === 'saving') {
+      document.documentElement.setAttribute('savestatus', 'saved');
+      document.dispatchEvent(new CustomEvent('clay:save-status', { detail: { state: 'saved' } }));
+    }
+    return result;
+  });
+}
+
 function attemptSaveNow({ kind, permit = null }, callback = () => {}) {
   const explicit = kind === 'explicit';
 
@@ -1321,10 +1384,10 @@ function attemptSaveNow({ kind, permit = null }, callback = () => {}) {
 
     // The source map asks a save to wait here: after the gates, before the capture.
     const prepare = window.clay?.source?.ensureForSave?.();
-    if (prepare) return prepare.then(() => resolve(attemptSaveNow({ kind, permit }, callback)));
+    if (prepare) return resolve(afterWait(prepare, () => attemptSaveNow({ kind, permit }, callback)));
 
     if (preparesSliced() && !prepDriver) {
-      loadPreparer().then(() => resolve(attemptSaveNow({ kind, permit }, callback)));
+      resolve(afterWait(loadPreparer(), () => attemptSaveNow({ kind, permit }, callback)));
       return;
     }
 
@@ -1348,7 +1411,7 @@ function attemptSaveNow({ kind, permit = null }, callback = () => {}) {
         explicit,
         forced: false,
         permit,
-        pageFormatFloor: 0,
+        blockeditorFormatFloor: 0,
         quietConflict: false,
         settleSoonQueued,
         callback,
@@ -1433,8 +1496,8 @@ function savePagePermitted(permit, callback = () => {}) {
  * @param {Function} callback - Optional callback for custom handling
  * @returns {Promise<{msg: string, msgType: string}>}
  */
-export function savePageForce(callback = () => {}, { quietConflict = false, pageFormatFloor = 0, permit = null } = {}) {
-  if (capabilityPending) return capabilityKnown.then(() => savePageForce(callback, { quietConflict, pageFormatFloor, permit }));
+export function savePageForce(callback = () => {}, { quietConflict = false, blockeditorFormatFloor = 0, permit = null } = {}) {
+  if (capabilityPending) return capabilityKnown.then(() => savePageForce(callback, { quietConflict, blockeditorFormatFloor, permit }));
   return new Promise((resolve) => {
     if (!isEditMode && !window.clay?.testMode) {
       const skipped = skipped_('Not in edit mode');
@@ -1488,7 +1551,7 @@ export function savePageForce(callback = () => {}, { quietConflict = false, page
     }
 
     const prepare = window.clay?.source?.ensureForSave?.();
-    if (prepare) return prepare.then(() => resolve(savePageForce(callback, { quietConflict, pageFormatFloor, permit })));
+    if (prepare) return resolve(afterWait(prepare, () => savePageForce(callback, { quietConflict, blockeditorFormatFloor, permit })));
 
     const wasOffline = !navigator.onLine;
     if (wasOffline) {
@@ -1498,7 +1561,7 @@ export function savePageForce(callback = () => {}, { quietConflict = false, page
     // A forced save prepares like an ordinary one when the document is this big; it only
     // skips the dirty question, which `forced` says here.
     if (preparesSliced() && !prepDriver) {
-      loadPreparer().then(() => resolve(savePageForce(callback, { quietConflict, pageFormatFloor, permit })));
+      resolve(afterWait(loadPreparer(), () => savePageForce(callback, { quietConflict, blockeditorFormatFloor, permit })));
       return;
     }
 
@@ -1512,7 +1575,7 @@ export function savePageForce(callback = () => {}, { quietConflict = false, page
         explicit: true,
         forced: true,
         permit,
-        pageFormatFloor,
+        blockeditorFormatFloor,
         quietConflict,
         settleSoonQueued,
         callback,
@@ -1546,7 +1609,7 @@ export function savePageForce(callback = () => {}, { quietConflict = false, page
       captureId,
       gateToken,
       costMs: 0,
-      pageFormatFloor,
+      blockeditorFormatFloor,
       quietConflict,
       capture,
       noteRecovery: () => noteRecoveryCapture({ captureId, html: forSave }),
@@ -1627,7 +1690,7 @@ export async function flushSave({ keepalive = false, timeoutMs = 15000, permit =
   const run = { over: false };
   let timer = null;
   const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(flushError('Save timed out.', 'failed')), Math.max(0, timeoutMs));
+    timer = setTimeout(() => reject(Object.assign(flushError('Save timed out.', 'failed'), { timedOut: true })), Math.max(0, timeoutMs));
   });
   try {
     return await Promise.race([flushBytes(keepalive, deadline, held, run), timeout]);

package/src/core/site-edits.js

@@ -0,0 +1,166 @@
+/**
+ * Shared site values edited on this page.
+ *
+ * On a multi-page host a page's `site` rule names values every page of the site shows:
+ * a nav, a footer. The host overwrites them with the site store's on every save, which
+ * keeps a stale tab from putting old values back and would also undo an edit made right
+ * here. So each save says which top-level `site` keys the person changed in this tab
+ * (`Site-Data: keys=nav,brand`), and the host writes exactly those to the store before
+ * it overwrites the rest.
+ *
+ * Both sides of the comparison are read from captured bytes, never from the live DOM:
+ * the baseline from the save pipeline's own record of what the file held at boot (which
+ * leaves out anything typed while the editor was still loading), moved on by this tab's
+ * accepted saves and by any other change to that record (a clean live-sync frame), and
+ * each save from the string being sent. Whatever the save pipeline normalizes is then normalized on both sides,
+ * so a value nobody touched cannot read as edited. That matters most in a stale tab,
+ * where a wrongly declared key would write old content over newer.
+ */
+import { addSaveHeaderSource } from "./save-core.js";
+import { onSaveAccepted } from "./save-accepted.js";
+import { getLastSavedContents, savePageThrottled } from "./save.js";
+import Mutation from "../lib/mutation.js";
+
+export const SITE_DATA_HEADER = "Site-Data";
+
+const RULES_TAG = 'script[data-rules-name~="api"]';
+// A top-level key: it opens the object or follows a comma, so `.site:first-child` in a
+// selector string is not a declaration.
+const DECLARES_SITE = /(?:^|[{,])\s*["']?site["']?\s*:/;
+const EMPTY = { html: null, now: null, keys: [] };
+
+let engine = null;
+let baseline = null;
+let last = EMPTY;
+// The save pipeline's record the baseline was last taken from. Whenever it changes (this
+// tab's accepted save, a clean live-sync frame), every key the host did not refuse takes
+// the record's value: for this tab's own save that is the value it sent, so an edit typed
+// while the save was in flight still differs, and for a frame it is what the file now holds.
+let knownSaved = null;
+const refusedKeys = new Set();
+// Values the host refreshed, with the value this tab had sent. The accepted hook runs before
+// the save pipeline installs that save's record, so the record then still holds the sent
+// value: the refreshed one stands. A record holding anything else is newer, and wins.
+const refreshed = new Map();
+
+// False while there is no record yet: no baseline, so no header.
+function followSavedRecord() {
+  const record = getLastSavedContents();
+  if (typeof record !== "string" || !record) return false;
+  if (record === knownSaved) return true;
+  const values = valuesOf(parse(record));
+  if (!baseline) baseline = values;
+  else {
+    for (const [key, value] of Object.entries(values)) {
+      if (refusedKeys.has(key)) continue;
+      const host = refreshed.get(key);
+      baseline[key] = host && host.sent === value ? host.value : value;
+    }
+  }
+  refreshed.clear();
+  knownSaved = record;
+  last = EMPTY;
+  return true;
+}
+
+function siteRule(root) {
+  const rule = engine.engine.findRulesIn(root, "api")?.rules?.site;
+  return rule !== null && typeof rule === "object" && !Array.isArray(rule) ? rule : null;
+}
+
+function valuesOf(root) {
+  const rule = siteRule(root);
+  if (!rule) return {};
+  const site = engine.extractData(root, { site: rule }).site ?? {};
+  return Object.fromEntries(Object.entries(site).map(([key, value]) => [key, JSON.stringify(value)]));
+}
+
+const parse = (html) => new DOMParser().parseFromString(html, "text/html").documentElement;
+
+function read(html) {
+  if (last.html !== html) {
+    const now = valuesOf(parse(html));
+    last = { html, now, keys: Object.keys(now).filter((key) => now[key] !== baseline[key]) };
+  }
+  return last;
+}
+
+// No header until the baseline exists: without one this tab cannot tell an edit from a
+// stale value, and a host that sees no header treats every shared value as stale.
+function siteHeader(html) {
+  if (!engine || typeof html !== "string" || !followSavedRecord()) return null;
+  return { [SITE_DATA_HEADER]: `keys=${read(html).keys.map(encodeURIComponent).join(",")}` };
+}
+
+// Values the host stored that this tab was behind on. Taken only for a key the person has
+// not touched since the save was captured, and never for a key the host refused: that
+// one still shows the edit that was not stored, and the page says so.
+function takeCurrent(current, sent, refused) {
+  const root = document.documentElement;
+  const rule = siteRule(root);
+  const live = valuesOf(root);
+  const applied = [];
+  for (const [key, value] of Object.entries(current)) {
+    if (refused.has(key) || !rule || !Object.hasOwn(rule, key) || live[key] !== sent[key]) continue;
+    // Outside undo history and the edit observers, the way a sync frame lands: an undo
+    // must not bring back the value this tab was behind on, and then declare it.
+    const fields = new Map([...root.querySelectorAll("[editable]")].map((field) => [field, field.innerHTML]));
+    Mutation.pause();
+    try {
+      engine.applyData(root, { site: { [key]: value } }, { site: { [key]: rule[key] } });
+      baseline[key] = valuesOf(root)[key];
+      refreshed.set(key, { sent: sent[key], value: baseline[key] });
+      applied.push(key);
+    } catch (error) {
+      console.error(`clayjs: the shared value "${key}" could not be refreshed on this page`, error);
+    } finally {
+      Mutation.resume();
+    }
+    // An editor that keeps its own undo history (RichClay) is told its field was rewritten,
+    // so its undo starts from the new value rather than stepping back to the old one.
+    for (const [field, before] of fields) {
+      if (field.isConnected && field.innerHTML !== before) field.dispatchEvent(new CustomEvent("clay:external-write"));
+    }
+  }
+  // The writes above ran with the edit observers paused, so the save pipeline still
+  // records the older value: typing that value back would then look like no change and
+  // never be saved. Ask for the same automatic save live sync asks for after it applies a
+  // frame, which stores what the page now shows and moves the record to it.
+  if (applied.length) savePageThrottled();
+  return applied;
+}
+
+function accept(html, answer) {
+  if (!engine || !followSavedRecord()) return;
+  refreshed.clear();
+  const sent = read(html).now;
+  // A `stale` key was edited on a value older than the store's: the host keeps the newer one
+  // and sends it as `current`, which this tab takes instead of declaring its edit again.
+  const refused = new Set((answer?.refused ?? []).filter((entry) => entry.code !== "stale").map((entry) => entry.key));
+  for (const key of Object.keys(sent)) {
+    if (refused.has(key)) refusedKeys.add(key);
+    else {
+      baseline[key] = sent[key];
+      refusedKeys.delete(key);
+    }
+  }
+  last = EMPTY;
+  if (!answer) return;
+  const applied = answer.current ? takeCurrent(answer.current, sent, refused) : [];
+  document.dispatchEvent(new CustomEvent("clay:site-data", {
+    detail: { written: answer.written ?? [], refused: answer.refused ?? [], applied },
+  }));
+}
+
+// Resolves once the engine has loaded, or at once on a page that declares no `site` key. The
+// baseline itself is read from the save pipeline's record when it is first needed.
+export const ready = DECLARES_SITE.test(document.querySelector(RULES_TAG)?.textContent ?? "")
+  ? (() => {
+      const loading = import("../vendor/hyper-html-api-data.vendor.js");
+      addSaveHeaderSource(siteHeader);
+      onSaveAccepted((html, accepted) => accept(html, accepted.siteData ?? null));
+      return loading.then((loaded) => {
+        engine = loaded;
+      }).catch((error) => console.error("clayjs: shared site edits are not tracked on this page", error));
+    })()
+  : Promise.resolve();

package/src/core/unsaved-warning.js

@@ -16,7 +16,7 @@
  */
 
 import { isEditMode, isDraftMode } from "./is-edit-mode.js";
-import { draftStoreFailed, flushDraft } from "./draft-mode.js";
+import { draftStoreFailed, draftUnconfirmed, flushDraft } from "./draft-mode.js";
 import { captureForDirtyCheck } from "./snapshot.js";
 import { getLastSavedDirty, sessionParked, styleAdoptionPending } from "./save.js";
 import { logUnloadDiffSync, preloadIfEnabled } from "../lib/autosave-debug-gate.js";
@@ -57,7 +57,7 @@ export function hasUnsavedChanges() {
   // 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;
-  if (isDraftMode) return draftStoreFailed();
+  if (isDraftMode) return draftStoreFailed() || draftUnconfirmed();
 
   // The demo plugin saves the page's bytes into this browser's own storage, so
   // leaving loses none of them.