@panphora/clayjs 1.0.0 → 1.1.0

package/src/core/save.js

@@ -20,6 +20,7 @@ import {
   isSaveInProgress
 } from "./save-core.js";
 import { captureForComparison, captureForComparisonAndDirty, captureForSaveAndComparison } from "./snapshot.js";
+import { seedEtag } from "./etag.js";
 import { gateCaptureToken, gateClearIfUnchanged } from "../lib/dirty-gate.js";
 import { ROOT_LIBRARY_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
@@ -50,7 +51,7 @@ let savingTimeout = null;
 /**
  * Sets the save status on <html> and dispatches an event.
  *
- * @param {string} state - One of: 'saving', 'saved', 'offline', 'error'
+ * @param {string} state - One of: 'saving', 'saved', 'offline', 'error', 'conflict'
  * @param {string} msg - Optional message (e.g., error details)
  * @param {string} msgType - Optional severity from the server (e.g., 'warning')
  */
@@ -190,6 +191,46 @@ export function resumeAutosave() {
   savePageThrottled();
 }
 
+// ============================================
+// THE CONFLICT HOLD
+// ============================================
+//
+// A 412 refuses this tab's bytes because the document changed since this tab last
+// saw it (spec §6). Two things have to follow, and the second is the one that is
+// easy to leave out.
+//
+// Nothing may be thrown away. The baselines do not advance on a refused save, so
+// the edits stay dirty, the close warning still fires, and the person keeps what
+// they typed. That falls out of applySaveResult and needs no special case.
+//
+// And autosave has to stop. Every autosave from here sends the same stamp and is
+// refused for the same reason, so leaving it running means a save attempt every
+// throttle window, forever, each one toasting a failure the person can do nothing
+// about. The suspension clay.wire already owns is exactly the right lever: it
+// stops AUTOsave only, so an explicit Cmd+S still goes out, and it replays one
+// missed save on release so nothing typed during the hold is stranded.
+//
+// The hold is released when a save lands, whatever produced it: clay.save.overwrite,
+// a live-sync frame that brought the page back in step, or the other tab going away.
+let conflictHold = false;
+
+function holdForConflict() {
+  if (conflictHold) return;
+  conflictHold = true;
+  suspendAutosave();
+}
+
+function releaseConflictHold() {
+  if (!conflictHold) return;
+  conflictHold = false;
+  resumeAutosave();
+}
+
+/** True while this tab is refusing to autosave over a version it has not seen. */
+export function isSaveConflicted() {
+  return conflictHold;
+}
+
 function skipped_(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
@@ -217,6 +258,10 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
     // warning, and the UI module is what decides how to render that.
     setSaveState('saved', result.msg || 'Saved', result.msgType);
     logBaseline(label, `${lastSavedContents.length} chars`);
+    releaseConflictHold();
+  } else if (result.msgType === 'conflict') {
+    holdForConflict();
+    setSaveState('conflict', result.msg, result.msgType);
   } else if (result.msgType !== 'skipped') {
     if (!navigator.onLine) {
       setSaveState('offline', result.msg);
@@ -405,6 +450,30 @@ export function savePageForce(callback = () => {}) {
   });
 }
 
+/**
+ * Keep this tab's version, over the one the host is holding.
+ *
+ * The only exit from a conflict that keeps what is on screen. It asks the host for
+ * the document's current stamp and force-saves with it, so the save that follows
+ * carries a value the host will accept. If the host answers with no stamp at all,
+ * the save goes out unconditional, which is last write wins, which is what the
+ * person just asked for by name.
+ *
+ * Deliberately not automatic, and deliberately not what a second Cmd+S does. A
+ * person pressing Save again has not been shown the other version, and reading
+ * that as consent to replace it destroys exactly the copy this capability exists
+ * to protect. The other two answers to a conflict need nothing from this library:
+ * `location.reload()` takes the host's version, and a page that wants to merge
+ * merges into its own DOM and then calls this.
+ *
+ * @param {Function} callback - Optional callback for custom handling
+ * @returns {Promise<{ok: boolean, msg: string, msgType: string}>}
+ */
+export async function saveOverwritingConflict(callback = () => {}) {
+  await seedEtag({ fresh: true });
+  return savePageForce(callback);
+}
+
 /**
  * Fetch HTML from a URL and save it, then reload
  * Emits error event if save fails
@@ -646,6 +715,16 @@ export function initHyperclaySaveButton() {
 export function init() {
   if (!isEditMode) return;
 
+  // §6's stamp for a page that has never saved. Fired here and never awaited: the
+  // request a person feels is the save, and a host with no /_/meta would make every
+  // first save wait out a discovery timeout for an answer that was never coming.
+  // Until the seed lands the first save goes out unconditional, which is last write
+  // wins, which is what every save did before this existed. This is also the only
+  // moment the seed can be useful at all: ask for it lazily at the first save and
+  // it can never arrive in time for that save, and from the second save onward the
+  // first save's own response has already supplied one.
+  seedEtag();
+
   // Every editable page, not just autosave pages. A manual-save page makes
   // exactly the saves a person asked for, and used to report all of them as
   // background writes because this was installed behind the autosave gate.

package/src/core/snapshot.js

@@ -109,10 +109,10 @@ export function addDocumentTransform(callback) {
  *
  * @returns {HTMLElement} Cloned document element with snapshot hooks applied
  */
-function clonePreventingOnclone(node) {
+function clonePreventingOnclone(node, deep = true) {
   const prev = window.__preventOnclone;
   window.__preventOnclone = true;
-  try { return node.cloneNode(true); }
+  try { return node.cloneNode(deep); }
   finally { window.__preventOnclone = prev; }
 }
 
@@ -293,7 +293,13 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
 export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   const clone = captureSnapshot();
 
-  // Emit for live-sync before any stripping
+  // Emit for live-sync before any stripping.
+  //
+  // A listener gets the very clone this function goes on to serialize into
+  // forSave, forComparison and forDirty — that sharing is the point, it saves a
+  // second full DOM clone per save. So a listener may READ it and must not write
+  // to it: anything it changes lands in the saved bytes and in both baselines,
+  // and a baseline the dirty check cannot reproduce warns on close forever.
   if (emitForSync) {
     document.dispatchEvent(new CustomEvent('clay:snapshot-ready', {
       detail: { documentElement: clone }
@@ -445,22 +451,33 @@ export function captureForSave({ emitForSync = true } = {}) {
  * (Not to be confused with captureBodyForSync below, which is the older
  * body-innerHTML helper and unrelated to the live-sync lane.)
  *
- * The clone is detached and unobserved, so removing the attributes in place and
- * putting them back is exact, and far cheaper than cloning the tree again. The
- * finally is load-bearing: the save path reads this same clone afterwards.
+ * It must not write to the clone. The caller derives forSave and both comparison
+ * baselines from this same object once every listener has returned, so anything
+ * left behind lands in the saved bytes and in both baselines.
+ *
+ * This used to strip the tab-local attributes in place and set them again in a
+ * finally, which looked exact and was not: an attribute list is ordered by
+ * insertion, so putting a name back appended it. On htmlclay, whose injectAttr
+ * splices the token and file id in right after `<html`, every save then installed
+ * a baseline whose root tag was ordered differently from the one any later dirty
+ * check builds off the live DOM — same names, same values, same length, never
+ * equal again. Closing an already-saved document warned every time, and
+ * savePageThrottled's "no changes to save" short-circuit never fired.
+ *
+ * The open tag is serialized from a childless copy instead, so the shared clone is
+ * never touched and there is no restore to get wrong. The copy is one element, not
+ * the tree.
  */
 export function serializeForSync(clone) {
-  const removed = [];
-  for (const name of TAB_LOCAL_ROOT_ATTRS) {
-    if (!clone.hasAttribute(name)) continue;
-    removed.push([name, clone.getAttribute(name)]);
-    clone.removeAttribute(name);
-  }
-  try {
-    return clone.outerHTML;
-  } finally {
-    for (const [name, value] of removed) clone.setAttribute(name, value);
-  }
+  const bareRoot = clonePreventingOnclone(clone, false);
+  for (const name of TAB_LOCAL_ROOT_ATTRS) bareRoot.removeAttribute(name);
+
+  // Split the end tag off by LENGTH rather than searching for one: an authored
+  // attribute value holding "</html>" would fool any indexOf-based split and
+  // truncate the broadcast.
+  const shell = bareRoot.outerHTML;
+  const endTag = `</${bareRoot.localName}>`;
+  return shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
 }
 
 /**

package/src/lib/root-attrs.js

@@ -8,15 +8,31 @@
  * peer's copy of them must never be applied.
  */
 
-// Injected by the host at serve time. Spec §9 bounds a save token to per-file and
-// per-tab and makes the host strip it before writing, so it never reaches disk.
-// But §9 bounds only the save path, and §10 fans a snapshot out to other editors'
+// The two spellings of the save token. Spec §9 bounds one to per-file and per-tab
+// and makes the host strip it before writing, so it never reaches disk. But §9
+// bounds only the save path, and §10 fans a snapshot out to other editors'
 // browsers, which is the hole this module closes.
 //
-// htmlclayid is host-injected too (htmlclay's durable file identity, stamped on
-// every serve, absent from disk bytes). It rides here so a morph of raw disk
-// content cannot strip this tab's copy, and a peer's copy is never applied.
-export const HOST_TOKEN_ATTRS = ["savetoken", "htmlclaytoken", "htmlclayid"];
+// Save tokens ONLY. host-attrs.js returns the first name it finds here and puts it
+// straight into the save URL, so anything added to this list becomes a credential
+// in a path. Durable identities go in the list below, never in this one.
+export const SAVE_TOKEN_ATTRS = ["savetoken", "htmlclaytoken"];
+
+// Host-injected, but NOT credentials. htmlclayid is htmlclay's durable file
+// identity, stamped on every serve and absent from disk bytes, so it rides in the
+// morph protection below for the same reason a token does: a morph of raw disk
+// content would otherwise strip this tab's copy, and a peer's copy must never be
+// applied.
+//
+// It was previously in the token list, where saveToken() returned it whenever a
+// host minted no token of its own. That is reachable: htmlclay stamps the id on
+// every serve but injects a token only for top-level document loads, and its save
+// route strips only the token, so the id reaches disk. Any such file hosted
+// somewhere tokenless made this library POST to /_/save/{id} with no cookie and
+// hand edit mode to every visitor.
+export const HOST_IDENTITY_ATTRS = ["htmlclayid"];
+
+export const HOST_TOKEN_ATTRS = [...SAVE_TOKEN_ATTRS, ...HOST_IDENTITY_ATTRS];
 
 // This library's own root state, and this tab's UI truth.
 export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];

package/src/loader-logic.js

@@ -7,6 +7,7 @@ export const CORE_WAVES = {
   ],
   editOnly: [
     "core/snapshot.js", "core/save-core.js", "core/save.js",
+    "core/save-conflict-notice.js",
     "core/unsaved-warning.js", "core/persist.js",
     "core/admin-attrs.js", "core/autosave.js",
     "attrs/save-freeze.js", "attrs/onaftersave.js", "attrs/refetch-on-save.js",
@@ -30,6 +31,44 @@ export const PLUGIN_PATHS = {
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
+// One literal import per module the loader can ask for, so a bundler can see the
+// whole graph. The loader used to build each specifier at runtime
+// (`import(base + "/src/" + path)`), which no bundler can follow, and that alone
+// stood between clayjs and the single-file build. A relative specifier resolves
+// against this file, so on clayjs.com the URLs fetched are exactly the ones the
+// computed form produced. The thunks keep every import lazy: nothing evaluates
+// until the loader asks, in the loader's order, which is load-bearing.
+// tests/unit/loader-modules.test.js proves every path in CORE_WAVES and
+// PLUGIN_PATHS has an entry here and that each entry imports the file it names.
+export const MODULES = {
+  "core/is-edit-mode.js":       () => import("./core/is-edit-mode.js"),
+  "lib/region-policy.js":       () => import("./lib/region-policy.js"),
+  "lib/mutation.js":            () => import("./lib/mutation.js"),
+  "core/edit-mode.js":          () => import("./core/edit-mode.js"),
+  "core/snapshot.js":           () => import("./core/snapshot.js"),
+  "core/save-core.js":          () => import("./core/save-core.js"),
+  "core/save.js":               () => import("./core/save.js"),
+  "core/save-conflict-notice.js": () => import("./core/save-conflict-notice.js"),
+  "core/unsaved-warning.js":    () => import("./core/unsaved-warning.js"),
+  "core/persist.js":            () => import("./core/persist.js"),
+  "core/admin-attrs.js":        () => import("./core/admin-attrs.js"),
+  "core/autosave.js":           () => import("./core/autosave.js"),
+  "attrs/save-freeze.js":       () => import("./attrs/save-freeze.js"),
+  "attrs/onaftersave.js":       () => import("./attrs/onaftersave.js"),
+  "attrs/refetch-on-save.js":   () => import("./attrs/refetch-on-save.js"),
+  "lib/cache-bust.js":          () => import("./lib/cache-bust.js"),
+  "vendor/richclay.vendor.js":  () => import("./vendor/richclay.vendor.js"),
+  "plugins/indicator.js":       () => import("./plugins/indicator.js"),
+  "sync/live-sync.js":          () => import("./sync/live-sync.js"),
+  "plugins/sortable.js":        () => import("./plugins/sortable.js"),
+  "plugins/undo.js":            () => import("./plugins/undo.js"),
+  "vendor/hypercms.vendor.js":  () => import("./vendor/hypercms.vendor.js"),
+  "vendor/quickcrop.vendor.js": () => import("./vendor/quickcrop.vendor.js"),
+  "plugins/upload.js":          () => import("./plugins/upload.js"),
+  "plugins/wire.js":            () => import("./plugins/wire.js"),
+  "plugins/demo.js":            () => import("./plugins/demo.js"),
+};
+
 const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "demo"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through

package/src/loader.js

@@ -1,16 +1,21 @@
-import { resolveModules } from "./loader-logic.js";
+import { resolveModules, MODULES } from "./loader-logic.js";
 import onDomReady from "./lib/dom-ready.js";
 
 function domReady() {
   return new Promise((resolve) => onDomReady(resolve));
 }
 
+// `base` has been unused since 1.1.0 (the loader imports through MODULES) and
+// stays anyway: /v1/clay.js and /v1/src/loader.js are cached independently, so
+// for a while after a deploy a browser can pair either file with the other's
+// previous release. A call shape that differs between them leaves the page with
+// no clayjs at all.
 export async function boot(base, params, readyResolve) {
   await domReady();                                    // Mutation observes document.body
                                                        // unconditionally, and a <head> placement
                                                        // would otherwise observe null
 
-  const editMode = await import(base + "/src/core/is-edit-mode.js");
+  const editMode = await MODULES["core/is-edit-mode.js"]();
   const { isEditMode, isOwner } = editMode;
 
   // richclay's vendor build detects edit mode via this legacy global; set it
@@ -19,13 +24,13 @@ export async function boot(base, params, readyResolve) {
   // and a conflicting leftover would make richclay disable itself.
   window.__hyperclayEditMode = isEditMode;
 
-  const regionPolicy = await import(base + "/src/lib/region-policy.js");
+  const regionPolicy = await MODULES["lib/region-policy.js"]();
 
   const plan = resolveModules(params, isEditMode);
   const loaded = {};
 
   for (const path of plan.core) {
-    loaded[path] = await import(base + "/src/" + path); // sequential: order is load-bearing
+    loaded[path] = await MODULES[path](); // sequential: order is load-bearing
   }
 
   assembleCore(loaded, { isEditMode, isOwner }, regionPolicy); // window.clay MUST be assembled
@@ -39,7 +44,7 @@ export async function boot(base, params, readyResolve) {
     // `ready` exports, never their evaluation.)
     let mod;
     try {
-      mod = await import(base + "/src/" + path);
+      mod = await MODULES[path]();
     } catch (err) {
       console.error(`clayjs: plugin "${path}" failed to load, continuing without it:`, err);
       continue;
@@ -81,6 +86,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   if (save) {
     const saveFn = save.savePage || save.default;
     saveFn.force = save.savePageForce;
+    saveFn.overwrite = save.saveOverwritingConflict;
     clay.save = saveFn;
   }
   if (snapshot) {

package/src/plugins/indicator.js

@@ -1,6 +1,12 @@
 import { isEditMode } from "../core/is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 
+// No 'conflict' here on purpose. core/save-conflict-notice.js owns that state now,
+// and it ships in every document rather than only the ones that turned this chip on.
+// Both listen to clay:save-conflict, so keeping a label here put a chip in the corner
+// saying the same thing as the bar at the same moment. Dropping it from this side
+// leaves core unaware that this plugin exists, which is the direction that
+// dependency has to point.
 const LABELS = {
   saving: "Saving…",
   saved: "Saved",
@@ -8,6 +14,11 @@ const LABELS = {
   offline: "Offline, not saved",
 };
 
+// States that stay on screen instead of fading, because 'saving' is still in flight.
+const STICKY = new Set(["saving"]);
+
+const ALARMING = new Set(["error", "offline"]);
+
 let el = null;
 let hideTimer = null;
 
@@ -34,11 +45,11 @@ function show(state) {
   const node = ensure();
   node.textContent = LABELS[state];
   node.dataset.state = state;
-  node.style.background = state === "error" || state === "offline"
+  node.style.background = ALARMING.has(state)
     ? "var(--clay-indicator-error-bg,#7a3b28)" : "var(--clay-indicator-bg,#2e2b27)";
   node.style.opacity = "1";
   clearTimeout(hideTimer);
-  if (state !== "saving") hideTimer = setTimeout(() => { node.style.opacity = "0"; }, 2200);
+  if (!STICKY.has(state)) hideTimer = setTimeout(() => { node.style.opacity = "0"; }, 2200);
 }
 
 function init() {

package/src/plugins/sortable.js

@@ -16,7 +16,6 @@
 */
 import { isEditMode } from "../core/is-edit-mode.js";
 import Mutation from "../lib/mutation.js";
-import { getVendorUrl } from "../lib/load-vendor-script.js";
 
 function makeSortable(sortableElem, Sortable) {
   let options = {};
@@ -89,10 +88,11 @@ function makeSortable(sortableElem, Sortable) {
 async function init() {
   if (!isEditMode) return;
 
-  // Load the vendor script
-  const vendorUrl = getVendorUrl(import.meta.url, '../vendor/Sortable.vendor.js');
-  await import(vendorUrl);
-  const Sortable = window.Sortable;
+  // Sortable's UMD header picks its target at run time: window.Sortable when no
+  // module system is present (a module load, and the single-file build), a
+  // default export when a bundler hands it one. Cover both.
+  const mod = await import('../vendor/Sortable.vendor.js');
+  const Sortable = window.Sortable || mod.default;
 
   // Set up sortable on page load
   document.querySelectorAll('[sortable]').forEach(el => makeSortable(el, Sortable));

package/src/standalone.js

@@ -0,0 +1,98 @@
+/* clayjs standalone: the entry of the single-file build. https://clayjs.com/offline
+
+   Twin of entries/clay.js. That bootstrap derives a base URL from its own script
+   tag and imports the loader at runtime; this one is bundled together with the
+   loader and every module it can ask for (see MODULES in loader-logic.js), so
+   `plugins=` decides what runs, never what downloads. The bootstrap logic below
+   (window.clay, `ready`, `__booted`, the retry path) is the same code as clay.js
+   and must stay in step with it; tests/unit/bootstrap-twins.test.js compares the
+   shared pieces. */
+import { boot } from "./loader.js";
+import onDomReady from "./lib/dom-ready.js";
+
+(function () {
+  // Suppress every vendored bundle's window auto-export; the loader assembles
+  // window.clay explicitly.
+  window.__hyperclayNoAutoExport = true;
+
+  // Merge into any window.clay a satellite already created; never replace it.
+  var clay = window.clay = window.clay || {};
+  // A second tag is a no-op: the original boot's `ready` promise survives.
+  // A FAILED boot resets the sentinel so a corrected tag can retry; the retry
+  // resolves the ORIGINAL `ready` promise via the stashed resolver.
+  if (clay.__booted) return;
+
+  function mintReady() {
+    clay.ready = new Promise(function (res, rej) {
+      clay.__readyResolve = res;
+      clay.__readyReject = rej;
+    });
+    // Nobody may be awaiting a failed boot's promise, and an unhandled rejection
+    // in the console is noise on top of the error we already logged.
+    clay.ready.catch(function () {});
+  }
+
+  if (!clay.ready) mintReady();
+
+  // clay.js needs its own URL to find the loader; this file needs it only for the
+  // query string, so pasted inline into the page it boots with the defaults.
+  var script = document.currentScript;
+  var params = script && script.src ? new URL(script.src, location.href).searchParams : new URLSearchParams();
+  clay.__booted = true;
+
+  function domReady() {
+    return new Promise(function (r) { onDomReady(r); });
+  }
+
+  // The module satellites, on the terms of their own entry scripts: each is a
+  // promise on clay.loaded, the ones that touch document.body wait for DOM
+  // ready, and events waits for dom because [onrender] handlers reach for its
+  // element helpers the moment events lands.
+  function satellite(name, promise) {
+    var p = promise.catch(function (err) {
+      console.error("clayjs: " + name + " failed to load:", err);
+      throw err;
+    });
+    // Mark handled: a failed satellite must not emit an unhandled rejection.
+    // Consumers who await clay.loaded[name] still get the error.
+    p.catch(function () {});
+    clay.loaded[name] = p;
+  }
+
+  clay.loaded = clay.loaded || {};
+  // The two generated satellites are classic scripts that assemble themselves
+  // onto window.clay when they run, and they carry no guard of their own, so
+  // they run here, behind the sentinel, and not as hoisted static imports: a
+  // duplicate tag would otherwise mount a second Sap runtime on the page. For
+  // the same reason a tag that already registered one (a leftover
+  // <script src="sap.js"> above this one) wins, and the copy in here stays idle.
+  if (!clay.loaded.data) satellite("data", import("../entries/clay-data.js"));
+  if (!clay.loaded.sap) satellite("sap", import("../entries/sap.js"));
+  satellite("dom", import("./dom/dom-helpers.js"));
+  satellite("utils", import("./utils/index.js"));
+  satellite("internals", import("./internals/index.js"));
+  satellite("all", import("./dom/all.js").then(function (m) {
+    window.All = m.default;   // interop carve-out, as in entries/all.js
+    clay.All = m.default;
+    return m.default;
+  }));
+  satellite("ui", domReady().then(function () { return import("./ui/index.js"); }));
+  satellite("options", domReady().then(function () { return import("./options/options.js"); }));
+  satellite("events", domReady()
+    .then(function () { return clay.loaded.dom && clay.loaded.dom.catch(function () {}); })
+    .then(function () { return import("./events/index.js"); }));
+
+  // The first argument is the loader's unused `base`; see boot() in loader.js.
+  boot(null, params, clay.__readyResolve).catch(function (err) {
+    clay.__booted = false;
+    console.error("clayjs failed to load:", err);
+    // Settle the promise so `await clay.ready` fails loudly instead of hanging,
+    // then mint a fresh one for a corrected retry tag. See entries/clay.js. A
+    // retry re-evaluates this whole file, satellites included; the path is
+    // reachable only when a bundled module throws on evaluation, which is a
+    // clayjs bug, not a page condition.
+    var reject = clay.__readyReject;
+    mintReady();
+    if (reject) reject(err);
+  });
+})();

package/src/sync/live-sync.js

@@ -44,6 +44,7 @@ import { serializeForSync, captureForComparisonAndDirty, captureSnapshot } from
 import { isTabLocalRootAttr } from '../lib/root-attrs.js';
 import { protectPeerDoc, protectDiskDoc, activateIncomingDoc } from './splice-merge.js';
 import { hostMeta } from '../core/host-meta.js';
+import { recordEtag, seedEtag } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate } from '../lib/dirty-gate.js';
 
 // The page just took a frame verified clean against its baseline, so it now IS
@@ -517,11 +518,50 @@ class LiveSync {
     const key = lane === 'live' ? '_heldLive' : '_heldExt';
     if (this[key] === isHeld) return;
     this[key] = isHeld;
+    // A hold that clears leaves this tab back in step, but every stamp frame that
+    // arrived while it was held was refused and nothing re-sends them: stamps are
+    // broadcast on a save, not on a merge. So the tab would go on holding a stamp
+    // from before the hold and have its next save refused over a conflict that has
+    // already resolved itself, which is this notice crying wolf. Ask the host for
+    // the current one instead. Only once BOTH lanes are clear, because one lane
+    // resuming while the other still holds means the tab is still behind.
+    if (!isHeld && !this._heldLive && !this._heldExt) {
+      seedEtag({ fresh: true, clearIfMissing: false });
+    }
     document.dispatchEvent(new CustomEvent(isHeld ? 'clay:sync-held' : 'clay:sync-resumed', {
       detail: { lane, el: el || null },
     }));
   }
 
+  /**
+   * Take a stamp that arrived with no document (spec §6).
+   *
+   * The host sends one whenever the file on disk changes, because an editing tab
+   * never receives the saved document itself: that lane is for viewers, and
+   * pushing a saved document onto an editor would replace work in progress.
+   *
+   * Taking it is what makes live sync and the conflict check agree. An editor
+   * whose peer frames are merging is already looking at the other tab's content,
+   * so refusing its next save would be a conflict about nothing.
+   *
+   * But only while this tab is in step. A held lane means live sync saw an
+   * incoming change, could not merge it into an unsaved local edit, and kept this
+   * tab's version instead, so the DOM here is knowingly missing what disk holds.
+   * Taking the new stamp there would let this tab's next save replace that change
+   * with nobody seeing it. That is the one loss live sync cannot prevent on its
+   * own: a held tab "converges through its own next save", and that convergence
+   * IS the overwrite. Refusing the stamp turns it into a conflict somebody is
+   * told about.
+   *
+   * @param {Object} data - The decoded frame
+   * @returns {boolean} True when this was a stamp frame and nothing should morph
+   */
+  _applyEtagFrame(data) {
+    if (typeof data.etag !== 'string' || typeof data.html === 'string') return false;
+    if (!this._heldLive && !this._heldExt) recordEtag(data.etag);
+    return true;
+  }
+
   /**
    * Connect to the SSE endpoint
    * Uses native EventSource reconnection behavior
@@ -609,6 +649,8 @@ class LiveSync {
         return;
       }
 
+      if (this._applyEtagFrame(data)) return;
+
       const { html, sender, identityMap } = data;
 
       // Ignore own changes — already reflected in the DOM, nothing to morph

package/src/ui/index.js

@@ -23,6 +23,13 @@ if (typeof window.toastPersistent === "undefined") window.toastPersistent = toas
 document.addEventListener("clay:save-saved", (e) =>
   toast(e.detail?.msg || "Saved", e.detail?.msgType === "warning" ? "warning" : "success"));
 document.addEventListener("clay:save-error", () => toastPersistent("Couldn't save", "error"));
+// Spec §6. Persistent, and carrying the host's own words, because this is the one
+// save outcome the person has to act on: their edits are safe and unsaved, and
+// autosave has stopped until they choose. Deliberately a toast and not a dialog:
+// most conflicts surface on an autosave nobody asked for, and a modal thrown over
+// the page a person is typing into is worse than the problem it reports.
+document.addEventListener("clay:save-conflict", (e) =>
+  toastPersistent(e.detail?.msg || "This document changed since you opened it", "warning"));
 document.addEventListener("clay:save-offline", () => toastPersistent("Offline, not saved", "warning"));
 
 export { toast, toastPersistent, ask, consent, tell, snippet, themodal };