@panphora/clayjs 1.5.3 → 1.6.1

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.
 //
@@ -206,6 +213,45 @@ export function resumeAutosave() {
   savePageThrottled();
 }
 
+// ============================================
+// THE PREVIEW HOLD
+// ============================================
+//
+// While an AI edit's rewrite is on screen and not yet kept, the DOM holds words the
+// person has not accepted. Every save would write them, the explicit ones included,
+// so for that window no save goes out at all. A save asked for meanwhile is
+// remembered and runs on release; Keep releases without the replay because it saves
+// right after.
+let previewHold = 0;
+let previewMissed = false;
+
+export function holdAllSaves() {
+  previewHold++;
+}
+
+export function releaseAllSaves({ replay = true } = {}) {
+  if (previewHold === 0) return;
+  previewHold--;
+  if (previewHold > 0) return;
+  const missed = previewMissed;
+  previewMissed = false;
+  if (missed && replay) savePage();
+}
+
+export function savesHeld() {
+  return previewHold > 0;
+}
+
+function heldForPreview(callback, resolve) {
+  if (previewHold === 0) return false;
+  previewMissed = true;
+  clearExplicitSave();
+  const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+  callback(skipped);
+  resolve(skipped);
+  return true;
+}
+
 // ============================================
 // THE CONFLICT HOLD
 // ============================================
@@ -257,7 +303,8 @@ export function isSaveConflicted() {
  * missed save. On a manual-save page with unsaved work the root stays in
  * 'conflict' and the notice stays up until the person saves, since nothing has
  * been written yet. Not clay:save-saved: no save happened, and that event runs
- * every [onaftersave] handler.
+ * every [onaftersave] handler. Either way clay:save-conflict-released fires, so a
+ * notice can drop the refusal it was showing.
  */
 export function conflictResolvedBySync(etag) {
   if (!conflictHold) return;
@@ -273,6 +320,7 @@ export function conflictResolvedBySync(etag) {
       detail: { timestamp: Date.now() }
     }));
   }
+  document.dispatchEvent(new CustomEvent('clay:save-conflict-released', { detail: { etag: etag ?? null } }));
   resumeAutosave();
 }
 
@@ -391,6 +439,8 @@ export function savePage(callback = () => {}) {
       return resolve(skipped);
     }
 
+    if (heldForPreview(callback, resolve)) return;
+
     // A save is already on the wire. Remember that a newer state is waiting rather
     // than dropping it: the in-flight request carries the older bytes, and if no
     // further mutation happens to retrigger autosave, the newer ones would never
@@ -476,6 +526,8 @@ export function savePageForce(callback = () => {}) {
       return resolve(skipped);
     }
 
+    if (heldForPreview(callback, resolve)) return;
+
     if (isSaveInProgress()) {
       pendingSave = true;
       const skipped = skipped_('Save already in progress');
@@ -515,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.
  *
@@ -705,6 +852,13 @@ export function savePageThrottled(callback = () => {}) {
     return Promise.resolve(skipped);
   }
 
+  if (previewHold > 0) {
+    previewMissed = true;
+    const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+    callback(skipped);
+    return Promise.resolve(skipped);
+  }
+
   // Every autosave path lands here — the mutation-driven one, the [persist] input
   // timer, and live-sync's convergence save after a protected apply — which is
   // why the suspension lives at this one entry rather than at each caller.

package/src/core/snapshot.js

@@ -679,3 +679,24 @@ export function captureBodyForSync() {
 export function getPageContents() {
   return captureForSave({ emitForSync: false });
 }
+
+/**
+ * The page as this tab had it before a merge replaced some of it, as the bytes a
+ * save would have written. The ledger's clone is shared and must come back
+ * untouched, so this works on a copy. A snapshot-domain clone still needs the save
+ * preparation (transforms, the [no-save] strip) but not the authored onbeforesave
+ * handlers: this is a download, not a save. A save-domain clone is already prepared.
+ */
+export function serializeRecoveryClone(clone, { prepared = false } = {}) {
+  const copy = clonePreventingOnclone(clone);
+  return serializeClone(prepared ? copy : prepareCloneForSave(copy, { authored: false }));
+}
+
+/**
+ * The live page as a save would write it, for a download: the save transforms and
+ * the [no-save] strip, but no authored handler runs and the undo batch stays open.
+ * Nothing is sent and no event fires.
+ */
+export function captureRecoveryPage() {
+  return serializeSaveClone(captureSaveClone({ flushUndo: false, authored: false }));
+}

package/src/core/stale-host-notice.js

@@ -19,17 +19,16 @@ import { set, make } from "../lib/hostile-css.js";
 // One line, no choice to make: nothing on this page can fix it, so offering a button
 // would be a lie. Dismissable, because after you have read it, it is only in the way.
 
-const BG = "var(--clay-notice-bg,#222)";
-const INK = "var(--clay-notice-ink,#fff)";
-const EDGE = "var(--clay-notice-edge,rgba(255,255,255,.28))";
-const FONT = "14px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif";
-
 const MESSAGE =
   "This page can't be edited: the app serving it is out of date. " +
   "Update HTML Clay to 1.9.0 or newer.";
 
 let root = null;
 
+// Bevel is fetched only when the warning is actually shown. This module loads on every
+// page, view mode included, and almost none of them ever show it.
+let ui = null;
+
 // A phone keyboard shrinks the visual viewport but leaves fixed elements pinned to the
 // layout viewport, so a bottom-anchored bar parks itself behind the keyboard. Same fix
 // as the conflict notice.
@@ -48,32 +47,24 @@ function dismiss() {
 }
 
 function build() {
-  root = make("div", [
+  root = ui.bevelSurface("div", [
     "position:fixed", "left:50%", "transform:translateX(-50%)",
-    "z-index:2147483001", "display:flex", "align-items:center", "gap:10px",
-    "max-width:calc(100vw - 24px)", "flex-wrap:wrap", "justify-content:center",
-    "padding:9px 12px", "border-radius:10px",
-    `background:${BG}`, `color:${INK}`, `border:1px solid ${EDGE}`,
-    "box-shadow:0 6px 24px rgba(0,0,0,.32),0 1px 2px rgba(0,0,0,.24)",
-    `font:${FONT}`, "text-align:left",
+    "z-index:2147483001", "display:flex", "align-items:center", "gap:10px 12px",
+    "width:max-content", "max-width:calc(100vw - 24px)", "flex-wrap:wrap",
+    "padding:8px 8px 8px 14px", "text-align:left", `color-scheme:${ui.pageScheme()}`,
   ]);
   // Three markers, and each is load-bearing on a page that CAN save: this element is
   // injected, so it is in no document on disk and must never reach one, never wake the
   // watcher, and never ride out in a snapshot to somebody else's browser.
-  root.setAttribute("clay", "no-save no-watch no-snapshot");
+  root.setAttribute("clay", ui.RUNTIME_ONLY);
   root.setAttribute("data-clay-stale-host", "");
   root.setAttribute("role", "alert");
 
-  root.append(make("span", ["margin-right:2px"], MESSAGE));
-
-  const close = make("button", [
-    "all:initial", "box-sizing:border-box", "cursor:pointer", `font:${FONT}`,
-    "color:" + INK, "opacity:.72", "padding:2px 6px", "border-radius:6px", "flex:none",
-  ], "Dismiss");
-  close.type = "button";
+  const dot = make("span", ["all:initial", "color-scheme:inherit", "display:inline-block", "flex:none", "width:8px", "height:8px", "border-radius:50%", `background:${ui.TOKENS.ox}`]);
+  dot.setAttribute("clay", ui.RUNTIME_ONLY);
+  const close = ui.bevelButton("Dismiss", { small: true, variant: "quiet", onClick: dismiss });
   close.setAttribute("aria-label", "Dismiss this message");
-  close.addEventListener("click", dismiss);
-  root.append(close);
+  root.append(dot, ui.bevelText("span", [], MESSAGE), close);
 
   document.body.appendChild(root);
   place();
@@ -81,7 +72,7 @@ function build() {
   window.visualViewport?.addEventListener("scroll", place);
 }
 
-function init() {
+async function init() {
   if (!servedStaleToken()) return;
   // ?editmode=true outranks the stale-host check by design: that is a person at the
   // keyboard asking for editing on this load, and is-edit-mode.js gives it to them.
@@ -89,7 +80,13 @@ function init() {
   // told its reader the opposite. The message is only true while editing is actually
   // off, so it is shown only then.
   if (isEditMode) return;
+  const [controls, bevel] = await Promise.all([import("../ui/bevel-controls.js"), import("../ui/bevel.js")]);
+  ui = { ...controls, TOKENS: bevel.TOKENS };
   build();
 }
 
-onDomReady(init);
+let shown = Promise.resolve();
+onDomReady(() => { shown = init(); });
+
+// Settles once the warning is on the page, or straight away when there is none to show.
+export const whenShown = () => shown;

package/src/core/unsaved-warning.js

@@ -19,6 +19,20 @@ import { isEditMode } from "./is-edit-mode.js";
 import { captureForDirtyCheck } from "./snapshot.js";
 import { getLastSavedDirty } from "./save.js";
 import { logUnloadDiffSync, preloadIfEnabled } from "../lib/autosave-debug.js";
+import { hasUnsavedState } from "../lib/unsaved-state.js";
+
+// One beforeunload let through, for the reload a person confirmed with two presses
+// in the conflict notice. Nothing else is switched off: the next close still warns.
+let discardPermit = false;
+export function reloadAfterDiscard({ isCurrent, reload }) {
+  if (!isCurrent()) return false;
+  discardPermit = true;
+  // Browsers fire beforeunload for a reload on their own schedule; a permit still
+  // unused a second later means the navigation did not happen.
+  setTimeout(() => { discardPermit = false; }, 1000);
+  reload();
+  return true;
+}
 
 // Pre-load diff library if debug mode is on (so it's ready for unload)
 preloadIfEnabled();
@@ -29,23 +43,57 @@ 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;
-  // The demo plugin saves into this browser's own storage, so leaving the page
-  // loses nothing a prompt could protect.
-  if (window.clay?.demo) return;
-
-  // 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();
-
-  if (currentForCompare !== lastSaved) {
-    // Debug: log what's different before showing the warning
-    logUnloadDiffSync(currentForCompare, lastSaved);
-
-    event.preventDefault();
-    event.returnValue = '';
+
+  if (discardPermit) {
+    discardPermit = false;
+    return;
+  }
+
+  if (!hasUnsavedChanges()) return;
+
+  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/content-dom.js

@@ -27,8 +27,10 @@ function matchesWithin(node, selector, boundary, inherit) {
 
 function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
   if (source.nodeType === 1 && (
-    (inherit ? hasCapability(source, capability) : matchesWithin(source, capabilityMatch, boundary, false)) ||
-    (exclude && matchesWithin(source, exclude, boundary, inherit))
+    (inherit
+      ? hasCapability(source, capability)
+      : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    (exclude && (inherit && source !== boundary ? source.matches(exclude) : matchesWithin(source, exclude, boundary, inherit)))
   )) return null
   const copy = targetDocument.importNode(source, false)
   maps.cloneToLive.set(copy, source)

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,8 +212,18 @@ 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) {
   startDirtyGate();
 }
+
+// Public for editors whose own surface is editor-ui (so neither gate feed sees it):
+// a person's edit made while a live-sync frame waits on a resource would otherwise be
+// recorded as saved. Set here, not in the loader, because the sync plugin is what
+// loads this module.
+if (typeof window !== 'undefined') {
+  window.clay = window.clay || {};
+  window.clay.markDirty = gateMarkDirty;
+}

package/src/lib/unsaved-state.js

@@ -0,0 +1,55 @@
+/**
+ * unsaved-state.js: "this tab holds work its saved bytes cannot show".
+ *
+ * The close warning compares the page's bytes with the last save. Some work is
+ * not in those bytes: text a live-sync merge replaced, kept in memory until the
+ * person reviews it, or an editor's model ahead of the DOM it writes into. Its
+ * owner registers a synchronous check here, and the close warning fires while
+ * any check says pending. Checks run fresh each time, so a forgotten state can
+ * never outlive what it describes, and a save never clears one.
+ */
+const sources = new Map();
+let nextKey = 0;
+
+export function registerUnsavedState({ id = '', isPending }) {
+  const key = ++nextKey;
+  sources.set(key, { id, isPending });
+  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(key);
+    },
+  };
+}
+
+// A check that throws counts as pending: unknown is not clean.
+function isPending(source) {
+  try {
+    return !!source.isPending();
+  } catch (err) {
+    console.error(`[clay] unsaved-state check "${source.id}" threw`, err);
+    return true;
+  }
+}
+
+export function pendingIds() {
+  return [...sources.values()].filter(isPending).map((s) => s.id);
+}
+
+export function hasUnsavedState() {
+  for (const source of sources.values()) if (isPending(source)) return true;
+  return false;
+}
+
+if (typeof window !== 'undefined') {
+  window.clay = window.clay || {};
+  window.clay.registerUnsavedState = registerUnsavedState;
+}