@panphora/clayjs 1.1.0 → 1.3.0

package/src/core/snapshot.js

@@ -30,7 +30,9 @@
  *   ┌─────────────────────────┐
  *   │  4. SERIALIZE           │
  *   │  "<!DOCTYPE html>"      │
- *   │  + outerHTML            │
+ *   │  + outerHTML, unless a  │
+ *   │  save renderer is set   │
+ *   │  (setSaveRenderer)      │
  *   │                         │
  *   │  → sent to server       │
  *   └─────────────────────────┘
@@ -40,6 +42,7 @@ import { stripExtensionNoise } from '../lib/extension-noise.js';
 import { restoreAuthoredUrls } from '../lib/authored-url.js';
 import { STRIP_FROM_SAVE, STRIP_FROM_COMPARISON, STRIP_FROM_DIRTY_CHECK, NO_TRIGGER_AUTOSAVE_SELECTOR, SNAPSHOT_REMOVE_SELECTOR } from '../lib/region-policy.js';
 import { TAB_LOCAL_ROOT_ATTRS } from '../lib/root-attrs.js';
+import { createContentView } from '../lib/content-dom.js';
 
 // =============================================================================
 // HOOK REGISTRIES
@@ -47,6 +50,20 @@ import { TAB_LOCAL_ROOT_ATTRS } from '../lib/root-attrs.js';
 
 const snapshotHooks = [];       // Phase 2: Always run (form sync)
 const documentTransforms = [];  // Phase 3a: Save and change check (strip admin)
+const snapshotProvenance = new WeakMap();
+
+// Phase 4, and there is only ever one. Everything else in this file is a list
+// because many things want a turn; serializing the document is one decision, so a
+// second renderer would be two answers to "what bytes does this save send".
+let saveRenderer = null;
+
+export function originalSnapshotNode(cloneNode) {
+  return snapshotProvenance.get(cloneNode) || null;
+}
+
+function stripSnapshotRegions(clone) {
+  for (const el of clone.querySelectorAll(SNAPSHOT_REMOVE_SELECTOR)) el.remove();
+}
 
 /**
  * Run every authored handler of one kind over a clone, and never let one of them
@@ -63,6 +80,8 @@ const documentTransforms = [];  // Phase 3a: Save and change check (strip admin)
  */
 function runAuthoredHandlers(clone, attr) {
   for (const el of clone.querySelectorAll(`[${attr}]`)) {
+    stripSnapshotRegions(clone);
+    if (el !== clone && !clone.contains(el)) continue;
     try {
       new Function(el.getAttribute(attr)).call(el);
     } catch (err) {
@@ -81,6 +100,51 @@ export function onSnapshot(callback) {
   snapshotHooks.push(callback);
 }
 
+/**
+ * Replace the save-domain serializer.
+ *
+ * Given the prepared save clone and the bytes `clone.outerHTML` would have sent, it
+ * returns the bytes to send instead. The source map (plugins/source.js) is the only
+ * caller: it renders the file's own bytes back out with only the changed regions
+ * reprinted, so a save stops rewriting 88% of an authored document's lines.
+ *
+ * It runs on the save path with a person's document in its hands, so the contract is
+ * narrow. It must return a complete document. It must not touch the clone, which is
+ * also the source of both comparison baselines. And it must be able to answer with
+ * `today` unchanged, because that is what it has to do whenever it is not certain:
+ * the caller here treats a throw the same way, so the floor of any renderer is the
+ * serialization it replaced.
+ *
+ * Comparison and dirty-check captures deliberately do NOT go through it. Those
+ * strings are only ever compared against each other, so they gain nothing from
+ * source fidelity and would pay a full render on every keystroke's dirty check.
+ *
+ * @param {?Function} renderer - (clone, today) => string, or null to restore outerHTML
+ */
+export function setSaveRenderer(renderer) {
+  saveRenderer = renderer;
+}
+
+/**
+ * The bytes a save sends: the prepared clone, through the save renderer if one is
+ * installed.
+ *
+ * The try/catch is not defensive noise around a renderer that already catches its
+ * own errors. That one catches in order to COUNT, and to fire the event that says a
+ * document reprinted; this one is the guarantee that no bug in an optional plugin can
+ * cost somebody a save.
+ */
+function serializeSaveClone(clone) {
+  const today = "<!DOCTYPE html>" + clone.outerHTML;
+  if (!saveRenderer) return today;
+  try {
+    return saveRenderer(clone, today);
+  } catch (err) {
+    console.error('clayjs: save renderer failed, sending the full serialization', err);
+    return today;
+  }
+}
+
 /**
  * Register a transform that runs over a detached clone when preparing to save.
  * Use for: stripping admin elements, cleanup.
@@ -116,7 +180,7 @@ function clonePreventingOnclone(node, deep = true) {
   finally { window.__preventOnclone = prev; }
 }
 
-export function captureSnapshot({ flushUndo = true } = {}) {
+export function captureSnapshot({ flushUndo = true, authored = true } = {}) {
   // 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
@@ -129,10 +193,27 @@ export function captureSnapshot({ flushUndo = true } = {}) {
     window.clay.undo.flush();
   }
 
-  const clone = clonePreventingOnclone(document.documentElement);
+  const view = createContentView(document.documentElement, { capability: 'snapshot' });
+  const clone = view.root;
+  // A <template>'s children are not its childNodes, they are its content fragment's,
+  // so walking childNodes alone leaves everything inside a template with no provenance.
+  // Nothing noticed until the source map asked which live node a clone node came from
+  // and got null for every node in a template, which reprinted the whole template on
+  // every save. createContentView already maps the fragment itself, so descending into
+  // it is all that was missing.
+  const remember = (node) => {
+    const live = view.original(node);
+    if (live) snapshotProvenance.set(node, live);
+    const children = node.nodeType === 1 && node.tagName === 'TEMPLATE' && node.content
+      ? node.content.childNodes
+      : node.childNodes;
+    for (const child of children || []) remember(child);
+  };
+  remember(clone);
 
   for (const hook of snapshotHooks) {
-    hook(clone);
+    stripSnapshotRegions(clone);
+    hook(clone, { original: originalSnapshotNode });
   }
 
   // Put back any URL clay rewrote at runtime (cache-bust, refetch-on-save) so
@@ -140,11 +221,13 @@ export function captureSnapshot({ flushUndo = true } = {}) {
   // authored handler sees the same URLs the file will.
   restoreAuthoredUrls(clone);
 
-  runAuthoredHandlers(clone, 'onbeforesnapshot');
+  stripSnapshotRegions(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.
+  if (authored) runAuthoredHandlers(clone, 'onbeforesnapshot');
 
-  for (const el of clone.querySelectorAll(SNAPSHOT_REMOVE_SELECTOR)) {
-    el.remove();
-  }
+  stripSnapshotRegions(clone);
 
   // Browser-extension noise (password-manager menus, Grammarly overlays, and
   // marker attributes on real inputs) is not page content. Drop it from every
@@ -159,17 +242,21 @@ export function captureSnapshot({ flushUndo = true } = {}) {
  * Mutates the clone — only call once per snapshot.
  *
  * @param {HTMLElement} clone - A snapshot from captureSnapshot()
- * @returns {string} Full HTML string ready for server
+ * @returns {HTMLElement} The same clone, in the save domain
  */
-function prepareCloneForSave(clone) {
+function prepareCloneForSave(clone, { authored = true } = {}) {
+  stripSnapshotRegions(clone);
   // Run inline [onbeforesave] handlers
-  runAuthoredHandlers(clone, 'onbeforesave');
+  if (authored) runAuthoredHandlers(clone, 'onbeforesave');
 
   // Run registered prepare hooks ([freeze]/[save-freeze] innerHTML restore lives here)
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
 
+  stripSnapshotRegions(clone);
+
   // Strip [no-save] / legacy [save-remove] LAST (snapshot-algorithm step 7): a
   // prepare hook (freeze restore) can re-inject [no-save] content into the clone,
   // so the strip must run after the hooks or that content leaks to disk.
@@ -177,7 +264,29 @@ function prepareCloneForSave(clone) {
     el.remove();
   }
 
-  return "<!DOCTYPE html>" + clone.outerHTML;
+  return clone;
+}
+
+/**
+ * The save-domain clone, for a caller that needs the tree rather than the bytes.
+ *
+ * The source map pairs against this rather than against the live DOM, because this is
+ * the tree in the file's own domain: edit mode deactivated back to the inert
+ * attribute forms, [no-save] gone, every transform run. Every node in it that came
+ * from the page can be traced back with originalSnapshotNode.
+ *
+ * Emits no snapshot-ready event: this capture must never feed the send pipeline.
+ *
+ * A caller that is only INSPECTING the tree passes `{ flushUndo: false, authored:
+ * false }`. Both defaults are right for a save and wrong for anything else: flushing
+ * closes the undo batch, so a capture taken mid-typing splits the user's undo history
+ * at a point they did not make, and the authored handlers are page JavaScript that is
+ * meant to run once per save, not once per capture.
+ *
+ * @returns {HTMLElement}
+ */
+export function captureSaveClone({ flushUndo = true, authored = true } = {}) {
+  return prepareCloneForSave(captureSnapshot({ flushUndo, authored }), { authored });
 }
 
 /**
@@ -202,9 +311,12 @@ export function captureForComparison({ flushUndo = true } = {}) {
 
   // Run registered prepare hooks
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
 
+  stripSnapshotRegions(clone);
+
   return "<!DOCTYPE html>" + clone.outerHTML;
 }
 
@@ -232,9 +344,12 @@ export function captureForDirtyCheck({ flushUndo = true } = {}) {
   }
 
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
 
+  stripSnapshotRegions(clone);
+
   return "<!DOCTYPE html>" + clone.outerHTML;
 }
 
@@ -262,8 +377,10 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
     el.remove();
   }
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
+  stripSnapshotRegions(clone);
   const forComparison = "<!DOCTYPE html>" + clone.outerHTML;
 
   let forDirty = forComparison;
@@ -272,8 +389,10 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
       el.remove();
     }
     for (const hook of documentTransforms) {
+      stripSnapshotRegions(dirtyClone);
       hook(dirtyClone);
     }
+    stripSnapshotRegions(dirtyClone);
     forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
   }
 
@@ -324,20 +443,24 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   // Save clone: run hooks (freeze restore lives here), THEN strip [no-save]/[save-remove]
   // LAST (snapshot-algorithm step 7) so freeze-restored [no-save] content can't leak to disk.
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
+  stripSnapshotRegions(clone);
   for (const el of clone.querySelectorAll(STRIP_FROM_SAVE)) {
     el.remove();
   }
-  const forSave = "<!DOCTYPE html>" + clone.outerHTML;
+  const forSave = serializeSaveClone(clone);
 
   // Compare clone: strip every autosave-off region, then run hooks
   for (const el of compareClone.querySelectorAll(STRIP_FROM_COMPARISON)) {
     el.remove();
   }
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(compareClone);
     hook(compareClone);
   }
+  stripSnapshotRegions(compareClone);
   const forComparison = "<!DOCTYPE html>" + compareClone.outerHTML;
 
   // Dirty clone: same shape as the compare clone, one selector weaker.
@@ -347,8 +470,10 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
       el.remove();
     }
     for (const hook of documentTransforms) {
+      stripSnapshotRegions(dirtyClone);
       hook(dirtyClone);
     }
+    stripSnapshotRegions(dirtyClone);
     forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
   }
 
@@ -400,8 +525,10 @@ export function captureForMerge() {
   })(compareClone, clone);
 
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
+  stripSnapshotRegions(clone);
   for (const el of clone.querySelectorAll(STRIP_FROM_SAVE)) {
     el.remove();
   }
@@ -410,8 +537,10 @@ export function captureForMerge() {
     el.remove();
   }
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(compareClone);
     hook(compareClone);
   }
+  stripSnapshotRegions(compareClone);
 
   return { saveClone: clone, compareClone, pairMap };
 }
@@ -437,7 +566,7 @@ export function captureForSave({ emitForSync = true } = {}) {
     }));
   }
 
-  return prepareCloneForSave(clone);
+  return serializeSaveClone(prepareCloneForSave(clone));
 }
 
 /**
@@ -477,7 +606,11 @@ export function serializeForSync(clone) {
   // truncate the broadcast.
   const shell = bareRoot.outerHTML;
   const endTag = `</${bareRoot.localName}>`;
-  return shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
+  // The doctype, so this artifact is a complete document like every other one this
+  // module produces. Spec section 2 asks for that, and it costs nothing on the wire:
+  // a receiver parses the string and morphs documentElement against documentElement,
+  // so the prologue is consumed by the parser and never reaches the morph.
+  return "<!DOCTYPE html>" + shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
 }
 
 /**