@panphora/clayjs 1.2.0 → 1.4.0

package/src/core/save.js

@@ -23,7 +23,7 @@ import {
 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 { 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";
 
@@ -43,6 +43,18 @@ addDocumentTransform(clone => {
   for (const name of ROOT_LIBRARY_ATTRS) clone.removeAttribute(name);
 });
 
+// Keep the host's save token out of the saved bytes, both spellings.
+//
+// It is a credential for this response, never file content: htmlclay strips it from
+// every save body on arrival, so it never reached disk anyway. Sending it made the
+// source map, which models the bytes a save sent, describe a root tag one attribute
+// longer than the file, and every offset after it was off by that much. The save
+// itself is authorized by the URL, which reads the token from the live page. The
+// document id is NOT stripped: htmlclay keeps it on disk on purpose.
+addDocumentTransform(clone => {
+  for (const name of [...SAVE_TOKEN_ATTRS, ...LEGACY_SAVE_TOKEN_ATTRS]) clone.removeAttribute(name);
+});
+
 // ============================================
 // SAVE STATE MANAGEMENT
 // ============================================

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,94 @@ 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;
+}
+
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+
+/**
+ * `clone.outerHTML`, except that a <noscript> holding only text is written raw.
+ *
+ * The page parsed with scripting on, so a <noscript> holds the author's markup as one
+ * text node, and the page's own serializer writes it back raw. The clone lives in a
+ * document with no window (createContentView), where scripting is off, and Chrome's
+ * serializer escapes that text there: `<p>` went to disk as `&lt;p&gt;`, which a reload
+ * reads as literal text, and every later save escaped it again. The text is swapped for
+ * a marker only while serializing, so the clone holds the same nodes when this returns.
+ */
+function serializeClone(clone) {
+  const blocks = [];
+  const collect = (node) => {
+    for (const child of node.childNodes) {
+      if (child.nodeType !== 1) continue;
+      if (child.localName === 'noscript' && child.namespaceURI === XHTML_NS) {
+        const kids = Array.from(child.childNodes);
+        if (kids.length && kids.every((n) => n.nodeType === 3)) blocks.push([child, kids]);
+        continue;
+      }
+      collect(child.localName === 'template' && child.content ? child.content : child);
+    }
+  };
+  collect(clone);
+  if (!blocks.length) return "<!DOCTYPE html>" + clone.outerHTML;
+  const nonce = Math.random().toString(36).slice(2);
+  const raw = blocks.map(([el, kids], i) => {
+    const marker = `\uE000clay-noscript-${nonce}-${i}\uE000`;
+    el.replaceChildren(el.ownerDocument.createTextNode(marker));
+    return [marker, kids.map((n) => n.data).join('')];
+  });
+  let html;
+  try {
+    html = "<!DOCTYPE html>" + clone.outerHTML;
+  } finally {
+    for (const [el, kids] of blocks) el.replaceChildren(...kids);
+  }
+  for (const [marker, text] of raw) html = html.split(marker).join(text);
+  return html;
+}
+
+/**
+ * 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 = serializeClone(clone);
+  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 +223,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 +236,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 +264,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 +285,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 +307,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 +354,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 +387,12 @@ export function captureForDirtyCheck({ flushUndo = true } = {}) {
   }
 
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(clone);
     hook(clone);
   }
 
+  stripSnapshotRegions(clone);
+
   return "<!DOCTYPE html>" + clone.outerHTML;
 }
 
@@ -262,8 +420,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 +432,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 +486,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 +513,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 +568,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 +580,10 @@ export function captureForMerge() {
     el.remove();
   }
   for (const hook of documentTransforms) {
+    stripSnapshotRegions(compareClone);
     hook(compareClone);
   }
+  stripSnapshotRegions(compareClone);
 
   return { saveClone: clone, compareClone, pairMap };
 }
@@ -437,7 +609,7 @@ export function captureForSave({ emitForSync = true } = {}) {
     }));
   }
 
-  return prepareCloneForSave(clone);
+  return serializeSaveClone(prepareCloneForSave(clone));
 }
 
 /**