@panphora/clayjs 1.15.2 → 1.17.0

package/src/core/snapshot.js

@@ -74,6 +74,98 @@ export function originalSnapshotNode(cloneNode) {
   return snapshotProvenance.get(cloneNode) || null;
 }
 
+// The private artifact a save renderer may hand back for one capture: the model of
+// the exact bytes it returned, paired with the tree it was given, so an accepted save
+// can adopt it instead of parsing and pairing the accepted bytes again. It is keyed by
+// the capture result object the caller gets, so it lives exactly as long as the save
+// that produced it and there is no registry to grow.
+const captureArtifacts = new WeakMap();
+// The capture being serialized right now. Only a save capture has one; an inspection
+// capture and a direct `captureForSave` have no request behind them to adopt anything.
+let activeCapture = null;
+
+/**
+ * The capture the save renderer is producing bytes for, or null.
+ *
+ * Read by the renderer to find out whose bytes these are, and to attach the artifact
+ * with attachCaptureArtifact. Per call, not global state: it is set for exactly the
+ * synchronous serialization of one save clone.
+ */
+export function currentCaptureContext() {
+  return activeCapture;
+}
+
+/**
+ * Attach the artifact to the capture being serialized.
+ *
+ * Ignored outside a save capture, because an artifact nobody can accept is a parse and
+ * a pairing paid for nothing.
+ */
+export function attachCaptureArtifact(artifact) {
+  if (activeCapture && artifact) activeCapture.artifact = artifact;
+}
+
+// The page state of one save capture: the exact value its page tag carried when its
+// bytes were serialized, copied so the edits that follow the capture can never reach it.
+// Keyed by the capture id every accepted event carries, and dropped when the capture
+// settles, so an accepted save reads the state it was captured from rather than the
+// store's value at the moment the host answered.
+let capturePageStateReader = null;
+const capturePageStates = new Map();
+
+/**
+ * Register the reader that finds a page state in a final save clone.
+ *
+ * A page's own code registers it (page/save-projection.js), so a document without a
+ * page pays one null check per capture and nothing else. Read from the clone rather
+ * than from a store because that tag is what the file receives, after every transform
+ * and every authored save handler has run.
+ */
+export function setCapturePageState(reader) {
+  capturePageStateReader = reader;
+}
+
+/**
+ * The page state pinned to one capture, or null.
+ *
+ * @param {?number} captureId
+ * @returns {?Object}
+ */
+export function capturePageState(captureId) {
+  if (captureId === null || captureId === undefined) return null;
+  return capturePageStates.get(captureId) ?? null;
+}
+
+/** The artifact this capture's renderer attached, or null. */
+export function captureArtifact(result) {
+  return result ? captureArtifacts.get(result) || null : null;
+}
+
+/** Forget a capture's artifact: it was skipped, refused, or has now settled. */
+export function releaseCaptureArtifact(result) {
+  if (!result) return;
+  captureArtifacts.delete(result);
+  capturePageStates.delete(result.captureId);
+}
+
+/**
+ * Does this clone hold an authored save handler, template contents included?
+ *
+ * Those handlers are page JavaScript that can change the clone after the capture, so
+ * the accepted bytes may no longer describe the live page node for node; a pairing
+ * rebuilt by walking the two together would be describing the handler's tree. The
+ * inspection path stays for those pages.
+ */
+function hasAuthoredSaveHandlers(root) {
+  const visit = (el) => {
+    if (el.hasAttribute('onbeforesave') || el.hasAttribute('onbeforesnapshot')) return true;
+    const kids = el.localName === 'template' && el.content ? el.content : el;
+    for (const child of kids.children) if (visit(child)) return true;
+    return false;
+  };
+  return root.nodeType === 1 ? visit(root) : false;
+}
+
 function stripSnapshotRegions(clone) {
   for (const el of clone.querySelectorAll(SNAPSHOT_REMOVE_SELECTOR)) el.remove();
 }
@@ -103,6 +195,19 @@ function runAuthoredHandlers(clone, attr) {
   }
 }
 
+let cloneCanonicalizer = null;
+
+export function setCloneCanonicalizer(canonicalize) {
+  cloneCanonicalizer = canonicalize;
+}
+
+// A document parsed from received bytes gets the same canonical URLs a capture has, so a merge
+// compares like with like. A no-op until save-core registers the canonicalizer.
+export function canonicalizeReceived(doc) {
+  cloneCanonicalizer?.(doc);
+  return doc;
+}
+
 /**
  * Register a hook that runs on EVERY snapshot (save AND sync).
  * Use for: syncing form values to the clone.
@@ -190,14 +295,23 @@ function serializeClone(clone) {
  * document reprinted; this one is the guarantee that no bug in an optional plugin can
  * cost somebody a save.
  */
-function serializeSaveClone(clone) {
+function serializeSaveClone(clone, context = null) {
+  if (context && capturePageStateReader) {
+    let state = null;
+    try { state = capturePageStateReader(clone); } catch (_) {}
+    if (state) capturePageStates.set(context.captureId, state);
+  }
   const today = serializeClone(clone);
   if (!saveRenderer) return today;
+  const previous = activeCapture;
+  activeCapture = context;
   try {
     return saveRenderer(clone, today);
   } catch (err) {
     console.error('clayjs: save renderer failed, sending the full serialization', err);
     return today;
+  } finally {
+    activeCapture = previous;
   }
 }
 
@@ -236,7 +350,7 @@ function clonePreventingOnclone(node, deep = true) {
   finally { window.__preventOnclone = prev; }
 }
 
-export function captureSnapshot({ flushUndo = true, authored = true, forSave = false, requestRefresh = false } = {}) {
+export function captureSnapshot({ flushUndo = true, authored = true, forSave = false, requestRefresh = false, context = null } = {}) {
   // Force-close any pending undo idle batch BEFORE cloning the DOM, so the
   // snapshot reflects a clean undo boundary. Without this, a save that fires
   // mid-typing would leave the idle batch open across the save boundary, and
@@ -265,7 +379,14 @@ export function captureSnapshot({ flushUndo = true, authored = true, forSave = f
   // authored handler sees the same URLs the file will.
   restoreAuthoredUrls(clone);
 
+  cloneCanonicalizer?.(clone);
+
   stripSnapshotRegions(clone);
+  // Whether the page authors its own save handlers, read here because this is the
+  // snapshot BEFORE either of them runs: a handler can add the other one, and it is the
+  // page as captured that decides whether the save can be paired without an inspection.
+  if (context) context.authoredHandlers = hasAuthoredSaveHandlers(clone);
+
   // authored: false is for a capture that is not a save and not a frame the page will
   // see. The attributes hold page-author JavaScript, so running them is a side effect
   // the author asked for once per save, not once per capture.
@@ -479,12 +600,22 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
  *
  * @param {Object} options
  * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
+ * @param {boolean} options.forRequest - These bytes go to a host, so the renderer may
+ *   attach the verified model they came from, for the accepted save to adopt
  * @returns {{ forSave: string, forComparison: string, forDirty: string, captureId: number }}
  */
-export function captureForSaveAndComparison({ emitForSync = true, flushUndo = true, requestRefresh = false } = {}) {
+export function captureForSaveAndComparison({ emitForSync = true, flushUndo = true, requestRefresh = false, forRequest = false } = {}) {
   if (!Number.isSafeInteger(captureCounter + 1)) throw new Error('Save capture identity exhausted');
   const captureId = ++captureCounter;
-  const clone = captureSnapshot({ flushUndo, forSave: emitForSync, requestRefresh });
+  // The context this capture's renderer may attach a private artifact to, and the
+  // record of whether the page has its own save handlers. It never reaches the object
+  // this function returns: that keeps its four public fields.
+  //
+  // Only for a capture whose bytes go to a host. A capture taken for anything else (a
+  // live-sync disk base, a download, an inspection) has no request to adopt it, so it
+  // pays neither the retained parse nor the pairing.
+  const context = forRequest ? { captureId, authoredHandlers: false, artifact: null } : null;
+  const clone = captureSnapshot({ flushUndo, forSave: emitForSync, requestRefresh, context });
 
   // Emit for live-sync before any stripping.
   //
@@ -525,7 +656,7 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
     el.remove();
   }
   stripDiagnosticBeacons(clone);
-  const forSave = serializeSaveClone(clone);
+  const forSave = serializeSaveClone(clone, context);
 
   // Compare clone: strip every autosave-off region, then run hooks
   for (const el of compareClone.querySelectorAll(STRIP_FROM_COMPARISON)) {
@@ -552,7 +683,9 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
     forDirty = serializeForCompare(dirtyClone);
   }
 
-  return { forSave, forComparison, forDirty, captureId };
+  const result = { forSave, forComparison, forDirty, captureId };
+  if (context && context.artifact) captureArtifacts.set(result, context.artifact);
+  return result;
 }
 
 /**
@@ -704,13 +837,28 @@ export function captureBodyForSync() {
 }
 
 /**
- * Get page contents for change detection.
- * Does NOT emit snapshot-ready event (safe for comparison).
+ * The bytes a save would send, without saving anything.
  *
- * Returns full HTML via snapshot pipeline.
+ * Emits no snapshot-ready event (safe for comparison), and with no options it is
+ * exactly `captureForSave({ emitForSync: false })`.
+ *
+ * `transform(root)` edits the detached clone and nothing else, and runs before
+ * prepareCloneForSave so the authored hooks, the transforms and the [no-save] strip
+ * still have their say. It must be synchronous: a preview that finished later would
+ * describe a page that has moved on, so a thenable is refused rather than awaited.
+ * There is no global registration, so no other save ever sees these edits, and the
+ * renderer runs without a capture context, so nothing can adopt these bytes as a model.
  */
-export function getPageContents() {
-  return captureForSave({ emitForSync: false });
+export function getPageContents({ transform = null, flushUndo = true } = {}) {
+  if (!transform && flushUndo) return captureForSave({ emitForSync: false });
+  const clone = captureSnapshot({ flushUndo });
+  if (transform) {
+    const pending = transform(clone);
+    if (pending && typeof pending.then === 'function') {
+      throw new TypeError('getHTML: the transform must be synchronous');
+    }
+  }
+  return serializeSaveClone(prepareCloneForSave(clone));
 }
 
 /**

package/src/core/source-map.js

@@ -63,6 +63,22 @@ export function model(src) {
     sourceCodeLocationInfo: true,
     onParseError: (e) => parseErrors.set(e.code, (parseErrors.get(e.code) || 0) + 1),
   });
+  return modelFromParsed(src, doc, parseErrors);
+}
+
+/**
+ * The model for bytes that have already been parsed, by this module or by the verifier.
+ *
+ * The split exists so a verified render costs one parse instead of two: the verifier
+ * parses the bytes with locations to count the errors the render introduced, and that
+ * tree is the model of exactly the bytes it verified. Everything below the parse is
+ * here verbatim; nothing here assumes who called the parser.
+ *
+ * @param {string} src - the bytes the tree was parsed from, which the ranges index
+ * @param {Object} doc - parse5 document, parsed with sourceCodeLocationInfo
+ * @param {Map} parseErrors - that parse's error counts, by code
+ */
+function modelFromParsed(src, doc, parseErrors) {
   const html = doc.childNodes.find((n) => n.nodeName === 'html');
   const outside = doc.childNodes.filter((n) => n !== html).map((n) => n.nodeName === '#documentType'
     ? { kind: 'doctype', name: n.name || '', publicId: n.publicId || '', systemId: n.systemId || '' }
@@ -296,11 +312,20 @@ function outsideOf(doc) {
 
 const UNIT_SEP = '\u0000';
 
+// The two steps pairCaptured exists to skip. Its whole claim is that a structurally
+// identical capture needs neither a signature tree nor an alignment, and a test that
+// only checks the resulting map cannot see the difference: hashing and aligning the same
+// two identical trees produces the same map. Read by tests and by the save meter; the
+// save path itself never reads it.
+export const pairingCounts = { align: 0, hashKey: 0 };
+export function resetPairingCounts() { pairingCounts.align = 0; pairingCounts.hashKey = 0; }
+
 function mix(h, s) {
   for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); }
   return h >>> 0;
 }
 function hashKey(parts) {
+  pairingCounts.hashKey++;
   let a = 2166136261, b = 5381;
   for (const p of parts) { a = mix(a, p); b = (Math.imul(b, 33) ^ mix(a ^ 0x9e3779b9, p)) >>> 0; }
   return a.toString(36) + '.' + b.toString(36);
@@ -356,6 +381,7 @@ const DP_CELLS = 4096;
  * 4.7 ms, and 32,000 siblings in 15.5 ms.
  */
 export function align(LK, SK) {
+  pairingCounts.align++;
   const pairs = [];
   const LI = LK.map((_, i) => i), SI = SK.map((_, j) => j);
   stage(LI, SI, 0);
@@ -500,6 +526,84 @@ function bind(node, loc, map, keyMap, stats, path, resolve, gen) {
   for (let j = 0; j < S.length; j++) if (!usedS.has(j)) stats.unmatchedSource.push({ path, node: describeLoc(S[j]) });
 }
 
+/**
+ * Pair a capture against the model built from the bytes that capture verified as.
+ *
+ * The map has to exist either way: it is what says where the live page is in the file.
+ * What this skips is the SEARCH for it. `pair` computes four signature keys per node and
+ * aligns child lists by them, because it is handed a page and a file that may have
+ * diverged arbitrarily. A verified capture has not diverged: the verifier compared the
+ * captured tree against today's bytes, node for node, so the model of those bytes has the
+ * captured tree, in order, with the same children. Walking the two together is the whole
+ * pairing.
+ *
+ * Refusing matters more than succeeding. Anything that differs returns null and the caller
+ * takes `pair`; a walk that guessed instead would pair one tree's locations to another
+ * tree's nodes and print the wrong bytes into the file. There is no partial result here.
+ *
+ * @param {Node} root - the prepared save clone's document element
+ * @param {Object} m - the model of the bytes this clone was verified to render as
+ * @param {Function} [provenance] - clone node -> the identity to key the map by
+ * @returns {?{map: WeakMap, stats: Object}} null when the trees are not the same shape
+ */
+export function pairCaptured(root, m, provenance = (n) => n) {
+  if (!m.root) return null;
+  const found = [];
+  const unresolved = matchCaptured(root, m.root, provenance, found);
+  if (unresolved < 0) return null;
+  const map = new WeakMap();
+  // One token for this pass, set on the model and on every bound loc, exactly as `pair`
+  // does it: render slices a loc only when the two still agree.
+  const gen = {};
+  m.gen = gen;
+  let paired = 0;
+  // A clone node a transform created has no live original and stays unpaired, so it is
+  // printed: the same thing `pair` does with it.
+  for (const [key, loc] of found) if (key) { map.set(key, loc); loc.gen = gen; paired++; }
+  return {
+    map,
+    stats: { paired, unmatchedLive: [], unmatchedSource: [], attrDiffs: [], textDiffs: 0, unresolved },
+  };
+}
+
+/** @returns {number} unresolved nodes below this pair, or -1 when the two differ at all */
+function matchCaptured(node, loc, provenance, found) {
+  if (loc.kind === 'text') {
+    if (node.nodeType !== 3 || node.data !== loc.value) return -1;
+  } else if (loc.kind === 'comment') {
+    if (node.nodeType !== 8 || node.data !== loc.value) return -1;
+  } else {
+    if (node.nodeType !== 1 || node.localName !== loc.tag || node.namespaceURI !== loc.node.namespaceURI) return -1;
+    if (capturedAttrs(node) !== capturedLocAttrs(loc.node)) return -1;
+  }
+  const key = provenance(node);
+  found.push([key, loc]);
+  let unresolved = key ? 0 : 1;
+  if (loc.kind !== 'element') return unresolved;
+  const L = capturedKids(node), S = loc.children;
+  if (L.length !== S.length) return -1;
+  for (let i = 0; i < L.length; i++) {
+    const n = matchCaptured(L[i], S[i], provenance, found);
+    if (n < 0) return -1;
+    unresolved += n;
+  }
+  return unresolved;
+}
+
+const attrKey = (a) => JSON.stringify(a);
+/** Qualified name, namespace and value, sorted: two attribute sets are equal as sets. */
+const capturedAttrs = (el) => Array.from(el.attributes, (a) => attrKey([a.namespaceURI || '', a.name, a.value])).sort().join(UNIT_SEP);
+// parse5 adjusts a foreign attribute in the tree (`xlink:href` is `{ prefix: 'xlink', name: 'href' }`)
+// and keeps the location map keyed by the name as written, so the qualified name is rebuilt here.
+const capturedLocAttrs = (node) => node.attrs.map((a) => attrKey([a.namespace || '', a.prefix ? a.prefix + ':' + a.name : a.name, a.value])).sort().join(UNIT_SEP);
+
+function capturedKids(el) {
+  const list = el.nodeType === 1 && el.tagName === 'TEMPLATE' && el.content ? el.content.childNodes : el.childNodes;
+  const out = [];
+  for (const n of list) if (n.nodeType === 1 || n.nodeType === 3 || n.nodeType === 8) out.push(n);
+  return out;
+}
+
 // =============================================================================
 // RENDER
 // =============================================================================
@@ -923,6 +1027,27 @@ function lis(vals) {
 // the right one.
 
 export function verify(rendered, today, liveDocument, clone = null, sourceErrors = null) {
+  return verifyRendered(rendered, today, liveDocument, clone, sourceErrors, false);
+}
+
+/**
+ * verify, keeping the parse it already paid for.
+ *
+ * The parse-error check below is a parse5 parse of the rendered bytes, and it is thrown
+ * away today: an accepted save then parses the accepted bytes a second time to model them.
+ * This returns the same verdict with that tree as `model`, so the save that verified can
+ * be modelled from the tree that verified it. `model` is present only when the verdict is
+ * ok AND the candidate is still this document (checkSource), which is what a caller needs
+ * before the candidate may be adopted; a fallback keeps today's path.
+ *
+ * A renderer must not verify its own output, so this is not a second verifier: it is the
+ * same walk, told to retain what it parsed.
+ */
+export function verifyForSave(rendered, today, liveDocument, clone = null, sourceErrors = null) {
+  return verifyRendered(rendered, today, liveDocument, clone, sourceErrors, true);
+}
+
+function verifyRendered(rendered, today, liveDocument, clone, sourceErrors, retain) {
   const P = new DOMParser();
   const A = P.parseFromString(rendered, 'text/html');
   const outsideA = vOutside(A), outsideLive = vOutside(liveDocument);
@@ -937,14 +1062,20 @@ export function verify(rendered, today, liveDocument, clone = null, sourceErrors
     at = [];
     cloneDiff = vDiff(A.documentElement, clone, 'html', at);
     if (!cloneDiff) {
-      const w = vParseErrors(rendered, sourceErrors);
-      return w ? { ok: false, diff: w } : { ok: true, diff: null, oracle: 'clone' };
+      const w = vParseErrors(rendered, sourceErrors, retain);
+      if (w.diff) return { ok: false, diff: w.diff };
+      return retain ? withCandidate({ ok: true, diff: null, oracle: 'clone' }, w, rendered, liveDocument)
+        : { ok: true, diff: null, oracle: 'clone' };
     }
   }
   const B = P.parseFromString(today, 'text/html');
   const diff = vDiff(A.documentElement, B.documentElement, 'html');
-  const worse = diff ? null : vParseErrors(rendered, sourceErrors);
-  if (!diff) return worse ? { ok: false, diff: worse } : { ok: true, diff: null, oracle: 'today' };
+  const worse = diff ? null : vParseErrors(rendered, sourceErrors, retain);
+  if (!diff) {
+    if (worse.diff) return { ok: false, diff: worse.diff };
+    return retain ? withCandidate({ ok: true, diff: null, oracle: 'today' }, worse, rendered, liveDocument)
+      : { ok: true, diff: null, oracle: 'today' };
+  }
   // `at` is the index path, in the clone, of the node where the render first differs,
   // so a caller can print that element and try again instead of discarding the whole
   // render. It is valid in the clone because every earlier sibling at every level on
@@ -983,15 +1114,32 @@ export function nodeAt(root, at) {
  * represent, such as a duplicated element, change the tree, and the comparison above
  * is what catches those.
  */
-function vParseErrors(rendered, sourceErrors) {
-  if (!sourceErrors) return null;
+function vParseErrors(rendered, sourceErrors, retain) {
+  if (!sourceErrors) return { diff: null };
   const seen = new Map();
-  parse(rendered, { onParseError: (e) => seen.set(e.code, (seen.get(e.code) || 0) + 1) });
+  const doc = parse(rendered, retain
+    ? { sourceCodeLocationInfo: true, onParseError: (e) => seen.set(e.code, (seen.get(e.code) || 0) + 1) }
+    : { onParseError: (e) => seen.set(e.code, (seen.get(e.code) || 0) + 1) });
   for (const [code, n] of seen) {
     const was = sourceErrors.get(code) || 0;
-    if (n > was) return `the render introduced parse errors the source does not have: ${code} ${was} -> ${n}`;
+    if (n > was) return { diff: `the render introduced parse errors the source does not have: ${code} ${was} -> ${n}` };
   }
-  return null;
+  return retain ? { diff: null, doc, parseErrors: seen } : { diff: null };
+}
+
+/**
+ * Attach the model of the bytes just verified, or leave the verdict as it is.
+ *
+ * checkSource first: the tree comparison cannot see anything outside <html>, and a model
+ * that fails it is not this document no matter what the render verified as. A failed check
+ * is not a refusal of the save; the caller keeps the fallback path it has today.
+ */
+function withCandidate(verdict, errors, rendered, liveDocument) {
+  if (!errors.doc) return verdict;
+  const candidate = modelFromParsed(rendered, errors.doc, errors.parseErrors);
+  if (checkSource(candidate, liveDocument)) return verdict;
+  verdict.model = candidate;
+  return verdict;
 }
 function vOutside(doc) {
   const out = [];

package/src/core/unsaved-warning.js

@@ -18,8 +18,8 @@
 import { isEditMode, isDraftMode } from "./is-edit-mode.js";
 import { draftStoreFailed, flushDraft } from "./draft-mode.js";
 import { captureForDirtyCheck } from "./snapshot.js";
-import { getLastSavedDirty } from "./save.js";
-import { logUnloadDiffSync, preloadIfEnabled } from "../lib/autosave-debug.js";
+import { getLastSavedDirty, sessionParked, styleAdoptionPending } from "./save.js";
+import { logUnloadDiffSync, preloadIfEnabled } from "../lib/autosave-debug-gate.js";
 import { hasUnsavedState } from "../lib/unsaved-state.js";
 
 // One beforeunload let through, for the reload a person confirmed with two presses
@@ -48,6 +48,10 @@ preloadIfEnabled();
 // 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() {
+  // Bytes a save session parked before its exit were never written, and whatever mode the
+  // page reports by then, they are still only here. Asked first, because the mode is a
+  // claim about the page and this is a claim about the host.
+  if (sessionParked()) return true;
   if (!isEditMode) return false;
 
   // Work outside the DOM first: it needs no capture, and a capture that throws
@@ -72,14 +76,20 @@ export function hasUnsavedChanges() {
 export function bytesUnsaved() {
   if (!isEditMode) return false;
   try {
-    return captureForDirtyCheck() !== getLastSavedDirty();
+    const current = captureForDirtyCheck();
+    // A style adoption is not work: the page is only waiting for the stripper that
+    // takes its own owned tag out of the stored bytes. The capture above still runs,
+    // so a throw is still an unsaved page, and any edit since the adoption was
+    // queued turns this off.
+    if (styleAdoptionPending(current)) return false;
+    return current !== getLastSavedDirty();
   } catch {
     return true;
   }
 }
 
 window.addEventListener('beforeunload', (event) => {
-  if (!isEditMode) return;
+  if (!isEditMode && !sessionParked()) return;
 
   if (discardPermit) {
     discardPermit = false;