@panphora/clayjs 0.4.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT",

package/src/core/admin-contenteditable.js

@@ -22,9 +22,10 @@ export function enableContentEditableForAdminOnPageLoad () {
   });
 }
 
-// Runtime toggle functions
-export function enableContentEditable() {
-  document.querySelectorAll(SELECTOR).forEach(el => {
+// Runtime toggle functions. `root` lets scoped live sync activate a parsed
+// incoming document the same way boot activates the live one.
+export function enableContentEditable(root = document) {
+  root.querySelectorAll(SELECTOR).forEach(el => {
     let val = el.getAttribute("inert-contenteditable");
     if (!["false", "plaintext-only"].includes(val)) val = "true";
     el.setAttribute("contenteditable", val);

package/src/core/admin-inputs.js

@@ -24,11 +24,13 @@ export function enableAdminInputsOnPageLoad() {
   });
 }
 
-export function enableAdminInputs() {
-  document.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
+// `root` lets scoped live sync activate a parsed incoming document the same
+// way boot activates the live one.
+export function enableAdminInputs(root = document) {
+  root.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
     input.removeAttribute('disabled');
   });
-  document.querySelectorAll(SELECTOR_READONLY).forEach(input => {
+  root.querySelectorAll(SELECTOR_READONLY).forEach(input => {
     input.removeAttribute('readonly');
   });
 }

package/src/core/admin-onclick.js

@@ -22,9 +22,10 @@ export function enableOnClickForAdminOnPageLoad () {
   });
 }
 
-// Runtime toggle functions
-export function enableOnClick() {
-  document.querySelectorAll(SELECTOR).forEach(el => {
+// Runtime toggle functions. `root` lets scoped live sync activate a parsed
+// incoming document the same way boot activates the live one.
+export function enableOnClick(root = document) {
+  root.querySelectorAll(SELECTOR).forEach(el => {
     const val = el.getAttribute("inert-onclick");
     if (val) {
       el.setAttribute("onclick", val);

package/src/core/admin-resources.js

@@ -37,11 +37,15 @@ export function enableAdminResourcesOnPageLoad () {
   });
 }
 
-// Runtime toggle functions
-export function enableAdminResources() {
-  document.querySelectorAll(SELECTOR_INERT).forEach(resource => {
+// Runtime toggle functions. `root` lets scoped live sync activate a parsed
+// incoming document; the clone-swap re-execution trick only applies to the
+// live document — in a detached parse nothing executes, and the morph's own
+// script handling decides execution when the content lands.
+export function enableAdminResources(root = document) {
+  const live = (root.ownerDocument || root) === document;
+  root.querySelectorAll(SELECTOR_INERT).forEach(resource => {
     makeActive(resource);
-    resource.replaceWith(resource.cloneNode(true));
+    if (live) resource.replaceWith(resource.cloneNode(true));
   });
 }
 

package/src/core/is-edit-mode.js

@@ -4,8 +4,9 @@ import { hasSaveToken } from "./host-attrs.js";
 
 // Edit-mode precedence: an explicit ?editmode=true|false URL param wins, then an
 // opt-in window.clayEditMode global (with the legacy window.__hyperclayEditMode
-// still honored as a fallback — htmlclay injects it today), then a save token the
-// host put on the root, then the platform's isAdminOfCurrentResource cookie. The
+// still honored as a fallback for older standalone embedders — htmlclay itself
+// uses the injected htmlclaytoken plus the admin cookie, not this global), then
+// a save token the host put on the root, then the isAdminOfCurrentResource cookie. The
 // global is for standalone uses (demos, htmlclay, any self-saving file) that are
 // always editable and have no owner cookie; setting it before clayjs loads turns
 // on the edit-only modules.

package/src/core/save.js

@@ -20,6 +20,7 @@ import {
   isSaveInProgress
 } from "./save-core.js";
 import { captureForComparison, captureForSaveAndComparison } from "./snapshot.js";
+import { gateCaptureToken, gateClearIfUnchanged } from "../lib/dirty-gate.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 
 // Reset savestatus to 'saved' in snapshots (each module cleans up its own attrs)
@@ -116,6 +117,37 @@ let lastSavedContents = '';
 // A save was requested while one was on the wire; run one more when it settles.
 let pendingSave = false;
 
+// ============================================
+// AUTOSAVE SUSPENSION
+// ============================================
+//
+// clay.wire holds this for the length of an agent request. The save is
+// last-writer-wins with a backup, so an autosave landing while a local process is
+// writing the same file posts the pre-agent document: the server backs the agent's
+// bytes up and writes the browser's, the watcher's revalidation then fails, and
+// the agent's work exists only in Backups while the page reports success.
+//
+// It suspends AUTOsave only. An explicit savePage — Cmd+S, a [trigger-save]
+// button, or the wire's own pre-send flush — is a deliberate act and still runs.
+//
+// Reference counted, because two overlapping requests each hold it. A save
+// skipped while suspended is replayed on release, or the user's edits would sit
+// unsaved until something else happened to mutate the page.
+let autosaveSuspended = 0;
+let autosaveMissed = false;
+
+export function suspendAutosave() {
+  autosaveSuspended++;
+}
+
+export function resumeAutosave() {
+  if (autosaveSuspended === 0) return;
+  autosaveSuspended--;
+  if (autosaveSuspended > 0 || !autosaveMissed) return;
+  autosaveMissed = false;
+  savePageThrottled();
+}
+
 function skipped_(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
@@ -129,10 +161,13 @@ function skipped_(msg) {
  * where the write may or may not have landed, so it is not treated as success
  * either.
  */
-function applySaveResult(result, forComparison, label) {
+function applySaveResult(result, forComparison, label, gateToken) {
   if (result.ok) {
     lastSavedContents = forComparison;
     unsavedChanges = false;
+    // Generation-checked: clears the scoped-sync dirty gate only if nothing
+    // changed while this save was on the wire.
+    gateClearIfUnchanged(gateToken);
     // The server's severity rides through untouched: a save can land AND carry a
     // warning, and the UI module is what decides how to render that.
     setSaveState('saved', result.msg || 'Saved', result.msgType);
@@ -201,6 +236,7 @@ export function savePage(callback = () => {}) {
     // forSave strips non-persisted regions ([no-save]/[save-remove])
     // forComparison additionally strips every autosave-off region
     let forSave, forComparison, snapshotHtml;
+    const gateToken = gateCaptureToken();
     try {
       ({ forSave, forComparison, snapshotHtml } = captureForSaveAndComparison());
     } catch (err) {
@@ -219,6 +255,7 @@ export function savePage(callback = () => {}) {
 
     // Skip if content hasn't changed
     if (!unsavedChanges) {
+      gateClearIfUnchanged(gateToken);
       const skipped = skipped_('No changes to save');
       callback(skipped);
       return resolve(skipped);
@@ -229,7 +266,7 @@ export function savePage(callback = () => {}) {
 
     // Use saveHtml directly with our pre-captured content (avoids double capture)
     saveHtml(forSave, (result) => {
-      applySaveResult(result, forComparison, 'updated after save');
+      applySaveResult(result, forComparison, 'updated after save', gateToken);
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -266,6 +303,7 @@ export function savePageForce(callback = () => {}) {
     }
 
     let forSave, forComparison, snapshotHtml;
+    const gateToken = gateCaptureToken();
     try {
       ({ forSave, forComparison, snapshotHtml } = captureForSaveAndComparison());
     } catch (err) {
@@ -281,7 +319,7 @@ export function savePageForce(callback = () => {}) {
     setSavingState();
 
     saveHtml(forSave, (result) => {
-      applySaveResult(result, forComparison, 'updated after force save');
+      applySaveResult(result, forComparison, 'updated after force save', gateToken);
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -383,9 +421,13 @@ function initBaselineCapture() {
     // (if a save happened, lastSavedContents would differ from immediateContents)
     if (!userEdited && lastSavedContents === immediateContents) {
       // Store stripped version so comparisons are direct (no parsing needed)
+      const gateToken = gateCaptureToken();
       const contents = captureForComparison();
       lastSavedContents = contents;
       baselineContents = contents;
+      // Boot churn (modules rewriting attributes at DOM-ready) counted toward
+      // the scoped-sync gate; the settled baseline is the proof it wasn't edits.
+      gateClearIfUnchanged(gateToken);
       logBaseline('settled capture', `${contents.length} chars`);
     } else {
       logBaseline('settled skipped', userEdited ? 'user edited' : 'save occurred during settle');
@@ -440,12 +482,23 @@ export function savePageThrottled(callback = () => {}) {
     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.
+  if (autosaveSuspended > 0) {
+    autosaveMissed = true;
+    const skipped = skipped_('Autosave suspended');
+    callback(skipped);
+    return Promise.resolve(skipped);
+  }
+
   // For autosave: while the page is still settling, content must differ from BOTH
   // the load-time baseline and the last save, so module setup churn cannot trigger
   // a save. Once settled, the baseline veto is disarmed and only the last save
   // matters — otherwise undoing back to the page's original state can never be
   // persisted, because it matches the baseline forever.
   // Compare directly - stored versions are already stripped
+  const gateToken = gateCaptureToken();
   const currentForCompare = captureForComparison();
   const differsFromBaseline = !baselineActive || currentForCompare !== baselineContents;
   const differsFromLastSave = currentForCompare !== lastSavedContents;
@@ -454,6 +507,7 @@ export function savePageThrottled(callback = () => {}) {
   logSaveCheck('throttled vs lastSave', !differsFromLastSave);
 
   if (!(differsFromBaseline && differsFromLastSave)) {
+    if (!differsFromLastSave) gateClearIfUnchanged(gateToken);
     const skipped = skipped_('No changes to save');
     callback(skipped);
     return Promise.resolve(skipped);

package/src/core/snapshot.js

@@ -116,13 +116,16 @@ function clonePreventingOnclone(node) {
   finally { window.__preventOnclone = prev; }
 }
 
-export function captureSnapshot() {
+export function captureSnapshot({ flushUndo = 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
   // Cmd+Z after save would restore to a state earlier than the last save.
   // No-op when undo isn't loaded or no batch is pending.
-  if (typeof window !== 'undefined' && window.clay?.undo?.flush) {
+  // flushUndo: false is for captures that are not save boundaries (the scoped
+  // live-sync dirty oracle runs per incoming frame, and flushing there would
+  // shatter the user's undo batches mid-typing).
+  if (flushUndo && typeof window !== 'undefined' && window.clay?.undo?.flush) {
     window.clay.undo.flush();
   }
 
@@ -181,8 +184,8 @@ function prepareCloneForSave(clone) {
  *
  * @returns {string} HTML string with all autosave-off regions stripped
  */
-export function captureForComparison() {
-  const clone = captureSnapshot();
+export function captureForComparison({ flushUndo = true } = {}) {
+  const clone = captureSnapshot({ flushUndo });
 
   // Run inline [onbeforesave] handlers
   runAuthoredHandlers(clone, 'onbeforesave');
@@ -260,6 +263,58 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   return { forSave, forComparison, snapshotHtml };
 }
 
+/**
+ * Capture for a protected live-sync merge: the save-domain and comparison-
+ * domain clones of ONE snapshot, plus a WeakMap pairing every comparison
+ * element to its save-clone twin.
+ *
+ * The pairing is recorded immediately after the comparison clone is created,
+ * while the two trees are still isomorphic; each side's strips then remove
+ * nodes independently without disturbing it. The scoped-sync dirty diff runs
+ * on the comparison clone (the same domain as lastSavedContents), and dirty
+ * roots map through pairMap to save-domain subtrees (the same domain as the
+ * file on disk), which still carry the no-trigger-autosave / freeze / no-watch
+ * children the comparison strips.
+ *
+ * Never emits snapshot-ready (this capture must not feed the send pipeline)
+ * and never flushes the undo batch (it runs per incoming frame, not per save).
+ *
+ * @returns {{ saveClone: HTMLElement, compareClone: HTMLElement, pairMap: WeakMap }}
+ */
+export function captureForMerge() {
+  const clone = captureSnapshot({ flushUndo: false });
+
+  runAuthoredHandlers(clone, 'onbeforesave');
+
+  const compareClone = clonePreventingOnclone(clone);
+
+  const pairMap = new WeakMap();
+  (function pair(compareEl, saveEl) {
+    pairMap.set(compareEl, saveEl);
+    const compareKids = compareEl.children;
+    const saveKids = saveEl.children;
+    for (let i = 0; i < compareKids.length; i++) {
+      pair(compareKids[i], saveKids[i]);
+    }
+  })(compareClone, clone);
+
+  for (const hook of documentTransforms) {
+    hook(clone);
+  }
+  for (const el of clone.querySelectorAll(STRIP_FROM_SAVE)) {
+    el.remove();
+  }
+
+  for (const el of compareClone.querySelectorAll(STRIP_FROM_COMPARISON)) {
+    el.remove();
+  }
+  for (const hook of documentTransforms) {
+    hook(compareClone);
+  }
+
+  return { saveClone: clone, compareClone, pairMap };
+}
+
 /**
  * PHASE 1-4: Full pipeline for saving to server.
  *

package/src/lib/dirty-gate.js

@@ -0,0 +1,169 @@
+/**
+ * dirty-gate.js — "might this page hold unsaved edits?" as a cheap counter.
+ *
+ * Scoped live sync must decide, on every incoming frame, whether to pay for a
+ * full capture-and-diff (the oracle) or apply the frame directly. This gate is
+ * the cheap side of that decision. It may over-report (a false "dirty" just
+ * runs the oracle, which then finds nothing), but it must never under-report:
+ * a false "clean" full-morphs over a real unsaved edit.
+ *
+ * Two feeds, because neither alone sees everything:
+ *   - the mutation hub (require: 'autosave'), which sees DOM changes but not
+ *     value-property writes on form controls (typing fires no MutationRecord
+ *     for .value), and
+ *   - capture-phase input/change listeners on ALL form controls, not just
+ *     [persist] ones, plus contenteditable hosts.
+ *
+ * The one hole left is a PROGRAMMATIC value write on a [persist] control: no
+ * event, no MutationRecord. persistProbeDirty() closes it by comparing each
+ * [persist] control's live state against its serialized default state, with a
+ * per-element cache so a value the oracle or a save has already verified stops
+ * costing a probe miss on every frame.
+ *
+ * Clearing is generation-checked: a save records the counter at capture time
+ * and clears only if nothing changed while the request was on the wire, so
+ * keystrokes during an in-flight save keep the gate dirty.
+ */
+
+import Mutation from './mutation.js';
+import { isEditMode } from '../core/is-edit-mode.js';
+import { STRIP_FROM_COMPARISON, SNAPSHOT_REMOVE_SELECTOR } from './region-policy.js';
+
+let changes = 0;
+let clearedAt = 0;
+let paused = false;
+let started = false;
+
+const PERSIST_CONTROLS = 'input[persist], textarea[persist], select[persist]';
+
+// Regions the comparison never sees. The hub feed already skips them, through
+// `require: 'autosave'`, and the input feed has to skip them for the same
+// reason: their content is stripped from the comparison clone, so an edit inside
+// one can never produce a dirty root, and counting it marks the page dirty with
+// nothing for the oracle to find — permanently, since only a save clears the
+// counter and churn in these regions triggers none.
+//
+// This is not a relaxation of "never under-report". A control here is absent
+// from the clone by definition, so there is nothing about it to under-report.
+// It matters because a mounted tool (redpen's answer field, any panel that
+// marks itself no-save) is a real <textarea> in the document: one keystroke in
+// it used to freeze the live-sync save baseline for the rest of the session,
+// after which every incoming disk change was diffed against a stale base, and
+// the previous change was spliced back over the newer one and written to disk.
+const GATE_IGNORE = `${STRIP_FROM_COMPARISON}, ${SNAPSHOT_REMOVE_SELECTOR}`;
+const probeCache = new WeakMap();
+
+function onUserInput(event) {
+  // Deliberately NOT gated on `paused`: a morph never dispatches input or
+  // change events, so anything arriving here is the user — including typing
+  // during a morph's async resource wait, which must keep the page dirty.
+  const el = event.target;
+  if (!el || el.nodeType !== 1) return;
+  if (!(el.matches('input, textarea, select') || el.isContentEditable)) return;
+  if (el.closest(GATE_IGNORE)) return;
+  changes++;
+}
+
+export function startDirtyGate() {
+  if (started) return;
+  started = true;
+  Mutation.onAnyChange(
+    { omitChangeDetails: true, require: 'autosave' },
+    () => {
+      if (!paused) changes++;
+    }
+  );
+  document.addEventListener('input', onUserInput, true);
+  document.addEventListener('change', onUserInput, true);
+}
+
+/** The morph-apply window: nothing that happens inside it is a user edit. */
+export function pauseGate() { paused = true; }
+export function resumeGate() { paused = false; }
+
+function controlSignature(el) {
+  if (el instanceof HTMLSelectElement) {
+    return Array.from(el.selectedOptions, (o) => o.value).join('\u0000');
+  }
+  if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) {
+    return el.checked ? '1' : '0';
+  }
+  return el.value;
+}
+
+// True when the control's live state matches its serialized (attribute-level)
+// state — i.e. a snapshot taken right now would carry nothing new for it.
+// persist's own listeners keep attributes current for USER input; only
+// programmatic writes diverge here.
+function serializedStateMatches(el) {
+  if (el instanceof HTMLSelectElement) {
+    return Array.from(el.options).every((o) => o.selected === o.defaultSelected);
+  }
+  if (el instanceof HTMLInputElement) {
+    if (el.type === 'checkbox' || el.type === 'radio') {
+      return el.checked === el.defaultChecked;
+    }
+    return el.value === el.defaultValue;
+  }
+  if (el instanceof HTMLTextAreaElement) {
+    if (el.hasAttribute('data-value')) {
+      return el.value === el.getAttribute('data-value');
+    }
+    return el.value === el.defaultValue;
+  }
+  return true;
+}
+
+export function persistProbeDirty() {
+  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+    const sig = controlSignature(el);
+    if (probeCache.get(el) === sig) continue;
+    if (serializedStateMatches(el)) {
+      probeCache.set(el, sig);
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Call after the oracle verified the whole page clean against its baseline. */
+export function probeMarkClean() {
+  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+    probeCache.set(el, controlSignature(el));
+  }
+}
+
+export function pageMaybeDirty() {
+  return changes > clearedAt || persistProbeDirty();
+}
+
+/**
+ * Record the gate state at capture time. The save flow takes a token when it
+ * clones the DOM and hands it back on success (or on a verified "no changes"),
+ * so a clear can never swallow edits made while the save was in flight.
+ */
+export function gateCaptureToken() {
+  const probe = [];
+  for (const el of document.querySelectorAll(PERSIST_CONTROLS)) {
+    probe.push([el, controlSignature(el)]);
+  }
+  return { gen: changes, probe };
+}
+
+export function gateClearIfUnchanged(token) {
+  if (!token) return;
+  if (changes === token.gen) {
+    clearedAt = token.gen;
+  }
+  // Probe entries clear per element, and only if the element still holds the
+  // exact value the capture carried — a programmatic write between capture
+  // and completion stays dirty.
+  for (const [el, sig] of token.probe) {
+    if (controlSignature(el) === sig) probeCache.set(el, sig);
+  }
+}
+
+if (typeof document !== 'undefined' && isEditMode) {
+  startDirtyGate();
+}

package/src/lib/root-attrs.js

@@ -12,7 +12,11 @@
 // 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.
-export const HOST_TOKEN_ATTRS = ["savetoken", "htmlclaytoken"];
+//
+// 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"];
 
 // Which save envelope this host's lane takes: a fact about the response, not
 // about the document.

package/src/loader-logic.js

@@ -21,10 +21,11 @@ export const PLUGIN_PATHS = {
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+  wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "demo"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "wire", "demo"];
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);

package/src/loader.js

@@ -102,6 +102,8 @@ function attachPluginMember(path, mod) {
     clay.morph = mod.morph;
   } else if (path === "vendor/hypercms.vendor.js") {
     clay.cms = mod.cms || mod.default;
+  } else if (path === "plugins/wire.js") {
+    clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/demo.js") {
     clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {