@panphora/clayjs 1.15.2 → 1.16.0

package/src/attrs/save-freeze.js

@@ -17,13 +17,8 @@
  */
 
 import { onSnapshot, addDocumentTransform } from "../core/snapshot.js";
-import { isEditMode } from "../core/is-edit-mode.js";
 import { FREEZE_SELECTOR } from "../lib/region-policy.js";
-import { ROUTE_ACTIVE_ATTR } from "../lib/root-attrs.js";
-import { stripEphemeral } from "../lib/ephemeral.js";
-import Mutation from "../lib/mutation.js";
-
-const originals = new WeakMap();
+import { captureAll, frozenOriginal } from "../core/preserve-authored.js";
 
 const saveFreeze = { debug: false };
 
@@ -31,32 +26,6 @@ function log(...args) {
   if (saveFreeze.debug) console.log('[save-freeze]', ...args);
 }
 
-// The captured original is what the file keeps, so it must hold no router stamp
-// and no ephemeral state: either can be set on a child before this capture runs.
-function authoredInnerHTML(el) {
-  const html = el.innerHTML;
-  if (!el.querySelector(`[${ROUTE_ACTIVE_ATTR}]`) && !html.includes("ephemeral") && !html.includes("<dialog")) return html;
-  const copy = el.cloneNode(true);
-  for (const s of copy.querySelectorAll(`[${ROUTE_ACTIVE_ATTR}]`)) s.removeAttribute(ROUTE_ACTIVE_ATTR);
-  for (const child of copy.children) stripEphemeral(child);
-  return copy.innerHTML;
-}
-
-function capture(el) {
-  if (!originals.has(el)) {
-    originals.set(el, authoredInnerHTML(el));
-    log('captured original', originals.get(el).substring(0, 80) + '...');
-  }
-}
-
-function captureAll() {
-  const els = document.querySelectorAll(FREEZE_SELECTOR);
-  log('captureAll found', els.length, 'elements');
-  for (const el of els) {
-    capture(el);
-  }
-}
-
 // Which cloned element holds which authored innerHTML, for the current snapshot.
 // Keyed by the cloned element itself: the prepare phase runs on the same clone
 // object the snapshot phase saw, so identity is the pairing. An attribute marker
@@ -76,8 +45,9 @@ function freezeSnapshot(clone, provenance) {
 
   for (const cloneElement of cloneElements) {
     const liveElement = provenance.original(cloneElement);
-    if (!liveElement || !originals.has(liveElement)) continue;
-    const original = originals.get(liveElement);
+    if (!liveElement) continue;
+    const original = frozenOriginal(liveElement);
+    if (original === undefined) continue;
     pending.set(cloneElement, original);
     if (cloneElement.innerHTML !== original) {
       log('restoring original');
@@ -99,27 +69,12 @@ function freezePrepare(clone) {
 }
 
 function init() {
-  log('init, isEditMode:', isEditMode);
-  if (!isEditMode) return;
+  log('init');
 
+  // The always wave's preservation foundation already recorded every region, in view
+  // mode and before any paint; this only covers a boot that skipped that wave.
   captureAll();
 
-  // Capture the original innerHTML of dynamically added [freeze]/[save-freeze]
-  // regions. Folded onto the single Mutation observer (Phase 2 — was its own).
-  // debounce:0 so we snapshot the authored content before any runtime edit
-  // mutates it; the callback is a pure read into a WeakMap (no DOM writes).
-  // require:'observed' (skip only no-watch); pausable:false so a morphed-in
-  // freeze region is still captured. Mutation observes document.documentElement,
-  // so a [freeze] added directly to <head> at runtime is captured like any other.
-  Mutation.onAddElement({
-    selectorFilter: FREEZE_SELECTOR,
-    require: 'observed',
-    pausable: false,
-    debounce: 0
-  }, (changes) => {
-    changes.forEach(({ element }) => capture(element));
-  });
-
   // Phase 2: Freeze in snapshot — before snapshot-ready fires.
   // This prevents live-sync from writing unfrozen content to disk.
   onSnapshot(freezeSnapshot);

package/src/core/admin-attrs.js

@@ -1,22 +1,129 @@
 // Admin system - combines all admin features (edit-only).
-import { init as initContenteditable } from './admin-contenteditable.js';
-import { init as initInputs } from './admin-inputs.js';
-import { init as initOnClick } from './admin-onclick.js';
-import { init as initResources } from './admin-resources.js';
+import { init as initContenteditable, enableContentEditable, disableContentEditable, SELECTOR as CONTENTEDITABLE } from './admin-contenteditable.js';
+import { init as initInputs, enableAdminInputs, disableAdminInputs, SELECTOR_DISABLED, SELECTOR_READONLY } from './admin-inputs.js';
+import { init as initOnClick, enableOnClick, disableOnClick, SELECTOR as ONCLICK } from './admin-onclick.js';
+import { init as initResources, enableAdminResources, disableAdminResources, SELECTOR as RESOURCES } from './admin-resources.js';
+import Mutation from '../lib/mutation.js';
+import { isEditMode } from './is-edit-mode.js';
 
-let initialized = false;
+// Every control this family activates, in one selector: what a node added mid-session is
+// matched against, and what the lease enables.
+const SELECTOR = [CONTENTEDITABLE, SELECTOR_DISABLED, SELECTOR_READONLY, ONCLICK, RESOURCES].join(', ');
 
-function init() {
-  if (initialized) return;
-  initialized = true;
+const ENABLE = [enableContentEditable, enableAdminInputs, enableOnClick, enableAdminResources];
+
+let installation = null;
+// The one add-element subscription this page runs, and whether it admits new controls.
+// A live entry installs it at its enable and removes it at its dispose; a tab that booted
+// in edit has no lease to do either, so its installation starts it and the adopted
+// session's dispose is what takes it away.
+let watching = null;
+let admission = false;
+
+const activate = (node) => {
+  const scope = node.parentNode || node;
+  for (const enable of ENABLE) enable(scope);
+};
+
+// One shared function, one install, however many times a session asks for it: a control
+// that arrives after the sweep — add-from's clone, a node a live frame morphed in — is
+// activated as it lands, and nothing after the subscription is removed.
+function watch() {
+  admission = true;
+  if (watching) return;
+  watching = Mutation.onAddElement({
+    selectorFilter: SELECTOR,
+    require: 'observed',
+    pausable: false,
+    debounce: 0,
+  }, (changes) => {
+    if (!admission) return;
+    changes.forEach(({ element }) => activate(element));
+  });
+}
+
+function unwatch() {
+  admission = false;
+  if (!watching) return;
+  watching();
+  watching = null;
+}
+
+// Loader-managed initialization. The loader calls this after it imports the module, in
+// its own wave order; the import calls it too, so a page reaches the same installation by
+// either road. Calling it again is asking for the transforms the page already has, not
+// for a second set: the save-time restore of each authored form is installed once, which
+// is what makes a repeated entry cost nothing.
+export function install() {
+  if (installation) return installation;
   initContenteditable();
   initInputs();
   initOnClick();
   initResources();
+  installation = { selector: SELECTOR };
+  // A tab that boots in edit: the boot's own page-load helpers turned the served controls
+  // on and there is no lease yet to watch for the ones that arrive afterwards.
+  if (isEditMode) watch();
+  return installation;
 }
 
-// Auto-init when module is imported
-init();
+install();
+
+// One edit session over the live DOM. `enable` turns the served inert controls into
+// working ones and starts watching for controls that arrive afterwards — a clone from
+// add-from, a node a live frame morphed in; `quiesce` leaves them exactly as they are and
+// stops admitting new ones; `resume` is the refused exit; `dispose` hands every control
+// back the form the file served and removes this session's subscription, and nothing else.
+export function controlsLease(root = document) {
+  return {
+    enable() {
+      for (const enable of ENABLE) enable(root);
+      watch();
+    },
+    quiesce() {
+      admission = false;
+    },
+    resume() {
+      admission = true;
+    },
+    dispose() {
+      unwatch();
+      disableContentEditable();
+      disableAdminInputs();
+      disableOnClick();
+      disableAdminResources();
+    }
+  };
+}
+
+/**
+ * The controls as a mode participant.
+ *
+ * The installation above is page-lifetime and turns no control on: it puts the
+ * save-time restore in front of each authored form, and in a tab that booted in edit it
+ * starts the one watcher. A session is the lease below.
+ *
+ * `initial: true` adopts the edit this tab booted into, where the boot's own
+ * `enable...OnPageLoad` helpers already turned the served controls on: its enable asks
+ * for the same one watcher the installation already started, and its dispose is what
+ * hands the controls back.
+ */
+export function modeParticipant() {
+  return {
+    id: 'clay:controls',
+    order: 110,
+    prepare(context = {}) {
+      const lease = controlsLease();
+      if (context.initial !== true) return lease;
+      return {
+        enable: () => watch(),
+        quiesce: () => lease.quiesce(),
+        resume: () => lease.resume(),
+        dispose: () => lease.dispose(),
+      };
+    },
+  };
+}
 
-export { init };
-export default init;
+export { install as init };
+export default install;

package/src/core/admin-contenteditable.js

@@ -1,16 +1,13 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 import { addDocumentTransform } from "./snapshot.js";
+import { authoredAttr, canonicalContentEditable, captureAuthored, restoreAuthoredOrder } from "./preserve-authored.js";
 
 export const SELECTOR = '[editmode\\:contenteditable]';
 
 export function disableContentEditableBeforeSave () {
   addDocumentTransform(docElem => {
-    docElem.querySelectorAll(SELECTOR).forEach(resource => {
-      const originalValue = resource.getAttribute("contenteditable");
-      resource.setAttribute("inert-contenteditable", originalValue === null ? "true" : originalValue);
-      resource.removeAttribute("contenteditable");
-    });
+    docElem.querySelectorAll(SELECTOR).forEach(canonicalContentEditable);
   });
 }
 
@@ -26,10 +23,16 @@ export function enableContentEditableForAdminOnPageLoad () {
 // incoming document the same way boot activates the live one.
 export function enableContentEditable(root = document) {
   root.querySelectorAll(SELECTOR).forEach(el => {
-    const val = el.getAttribute("inert-contenteditable");
+    captureAuthored(el);
+    // Already active (a second activation of the same node) keeps the value it already
+    // holds, so re-running this never downgrades `plaintext-only` to `true`.
+    const val = el.getAttribute("inert-contenteditable")
+      ?? el.getAttribute("contenteditable")
+      ?? authoredAttr(el, "inert-contenteditable")
+      ?? "true";
     // Keywords match ASCII case-insensitively, so `FALSE` means false. The author's own
     // spelling is what gets written, so the save transform puts it back unchanged.
-    const keyword = val === null ? null : val.toLowerCase();
+    const keyword = val.toLowerCase();
     el.setAttribute("contenteditable", ["", "true", "false", "plaintext-only"].includes(keyword) ? val : "true");
     el.removeAttribute("inert-contenteditable");
   });
@@ -37,9 +40,8 @@ export function enableContentEditable(root = document) {
 
 export function disableContentEditable() {
   document.querySelectorAll(SELECTOR).forEach(el => {
-    const val = el.getAttribute("contenteditable");
-    el.setAttribute("inert-contenteditable", val === null ? "true" : val);
-    el.removeAttribute("contenteditable");
+    canonicalContentEditable(el);
+    restoreAuthoredOrder(el);
   });
 }
 

package/src/core/admin-inputs.js

@@ -1,25 +1,21 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 import { addDocumentTransform, originalSnapshotNode } from "./snapshot.js";
+import { authoredAttr, captureAuthored, restoreAuthoredOrder } from "./preserve-authored.js";
 
 export const SELECTOR_DISABLED = '[viewmode\\:disabled]';
 export const SELECTOR_READONLY = '[viewmode\\:readonly]';
 
 const BOOLEANS = [[SELECTOR_DISABLED, 'disabled'], [SELECTOR_READONLY, 'readonly']];
 
-// What the author wrote for `disabled` / `readonly` on each live element, from before
-// edit mode removed it. A boolean attribute means the same whatever its value, so this
-// is only about handing the file back its own spelling (`disabled="disabled"`).
-const authored = new WeakMap();
-
 export function disableAdminInputsBeforeSave() {
   addDocumentTransform(docElem => {
     for (const [selector, name] of BOOLEANS) {
       docElem.querySelectorAll(selector).forEach(input => {
         if (input.hasAttribute(name)) return;
         const live = originalSnapshotNode(input);
-        const spelled = live && authored.get(live);
-        input.setAttribute(name, spelled && spelled[name] !== undefined ? spelled[name] : '');
+        const spelled = live ? authoredAttr(live, name) : null;
+        input.setAttribute(name, spelled === null ? '' : spelled);
       });
     }
   });
@@ -38,20 +34,23 @@ export function enableAdminInputsOnPageLoad() {
 export function enableAdminInputs(root = document) {
   for (const [selector, name] of BOOLEANS) {
     root.querySelectorAll(selector).forEach(input => {
-      const value = input.getAttribute(name);
-      if (value !== null) authored.set(input, { ...(authored.get(input) || {}), [name]: value });
+      captureAuthored(input);
       input.removeAttribute(name);
     });
   }
 }
 
+// A boolean attribute means the same whatever its value, so the point of putting it
+// back is handing the file its own spelling (`disabled="disabled"`) instead of `""`.
 export function disableAdminInputs() {
-  document.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
-    input.setAttribute('disabled', '');
-  });
-  document.querySelectorAll(SELECTOR_READONLY).forEach(input => {
-    input.setAttribute('readonly', '');
-  });
+  for (const [selector, name] of BOOLEANS) {
+    document.querySelectorAll(selector).forEach(input => {
+      const spelled = authoredAttr(input, name);
+      if (spelled === null) input.removeAttribute(name);
+      else input.setAttribute(name, spelled);
+      restoreAuthoredOrder(input);
+    });
+  }
 }
 
 export function init() {

package/src/core/admin-onclick.js

@@ -1,6 +1,7 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 import { addDocumentTransform } from "./snapshot.js";
+import { restoreAuthoredOrder } from "./preserve-authored.js";
 
 export const SELECTOR = '[editmode\\:onclick]';
 
@@ -46,6 +47,7 @@ export function disableOnClick() {
       el.setAttribute("inert-onclick", val);
       el.removeAttribute("onclick");
     }
+    restoreAuthoredOrder(el);
   });
 }
 

package/src/core/autosave.js

@@ -12,7 +12,7 @@
 
 import Mutation from "../lib/mutation.js";
 import { isEditMode } from "./is-edit-mode.js";
-import { savePageThrottled } from "./save.js";
+import { autosaveScheduler, savesAdmitted } from "./save.js";
 import { markUserDriven } from "../lib/user-gesture.js";
 import { resolveRegionPolicy, skipForPolicy } from "../lib/region-policy.js";
 import { PERSIST, AUTOSAVE } from "../lib/attr-aliases.js";
@@ -20,25 +20,20 @@ import { setAutosaveActive } from "../lib/autosave-state.js";
 
 /**
  * Initialize auto-save on DOM changes
- * Uses debounced mutation observer
+ *
+ * The scheduler owns the quiet period and the maximum wait, so this subscriber
+ * only reports that content changed. No debounce here: the hub's would be a
+ * second timer measuring the same quiet window, and the page must not be copied
+ * to answer a question the scheduler has not yet admitted.
  */
-// A bare debounce resets on every change, so a page with anything that mutates
-// faster than the delay — a clock, a countdown, a polling counter — pushes autosave
-// into the future forever and it never fires, with nothing in the UI saying so.
-// maxWait bounds that: however long the churn lasts, a save happens within
-// AUTOSAVE_MAX_WAIT_MS of the first change it was waiting on. (The settled baseline
-// capture in save.js already solved this for itself with MAX_SETTLE_MS.)
-const AUTOSAVE_DEBOUNCE_MS = 1500;
-const AUTOSAVE_MAX_WAIT_MS = 10000;
-
 function initSavePageOnChange() {
   Mutation.onAnyChange({
-    debounce: AUTOSAVE_DEBOUNCE_MS,
-    maxWait: AUTOSAVE_MAX_WAIT_MS,
+    debounce: 0,
     omitChangeDetails: true,
     require: 'autosave'
   }, () => {
-    savePageThrottled();
+    if (!savesAdmitted()) return;
+    autosaveScheduler.noteActivity();
   });
 }
 
@@ -46,7 +41,6 @@ function initSavePageOnChange() {
  * Initialize auto-save on input events for [persist] elements
  * Form input values don't trigger DOM mutations, so we listen for input events
  */
-let inputSaveTimer = null;
 function initSaveOnPersistInput() {
   document.addEventListener('input', (e) => {
     if (!e.target.closest(PERSIST)) return;
@@ -58,24 +52,83 @@ function initSaveOnPersistInput() {
     if (e.isTrusted && !skipForPolicy(resolveRegionPolicy(e.target), 'dirty')) {
       markUserDriven();
     }
-    clearTimeout(inputSaveTimer);
-    inputSaveTimer = setTimeout(savePageThrottled, 1500);
+    if (!savesAdmitted()) return;
+    autosaveScheduler.noteActivity();
   }, true);
 }
 
-function init() {
+/**
+ * Record editable input and composition activity while an automatic save is
+ * pending.
+ *
+ * An active IME changes nothing in the canonical record yet, so a pause between
+ * composition updates would read as quiet and the capture would land mid-word.
+ * This records timing only: it makes no input dirty, so a frozen editor and a
+ * no-save field still save nothing.
+ */
+function initRecordEditActivity() {
+  const noteActivity = (e) => {
+    if (!autosaveScheduler.pending()) return;
+    const target = e.target;
+    if (!target || typeof target.closest !== 'function') return;
+    const field = target.closest('input, textarea, select, [contenteditable]');
+    if (!field) return;
+    if (skipForPolicy(resolveRegionPolicy(field), 'dirty')) return;
+    if (!savesAdmitted()) return;
+    autosaveScheduler.noteActivity();
+  };
+  document.addEventListener('input', noteActivity, true);
+  document.addEventListener('compositionupdate', noteActivity, true);
+}
+
+let installed = false;
+
+/**
+ * Loader-managed initialization, and the import's own: one subscription set per page.
+ *
+ * A live re-entry asks for the autosave this page already has, not a second one, so the
+ * listeners above are installed once and an activity report they make while a save
+ * session has admission closed is dropped rather than arming another timer.
+ */
+function install() {
+  if (installed) return;
   if (!document.documentElement.matches(AUTOSAVE)) return;
   if (!isEditMode) return;
+  installed = true;
   setAutosaveActive(true);
   // initUserGesture moved to save.js's init: gesture provenance belongs to every
   // editable page, not only the ones with <html autosave>.
   initSavePageOnChange();
   initSaveOnPersistInput();
+  initRecordEditActivity();
 }
 
-// No window exports - savePageThrottled is exported from save-system
+// No window exports - the scheduler lives in save-system and savePageThrottled is
+// exported from there
 
 // Auto-init when module is imported
-init();
+install();
+
+export { install as init };
+export default install;
 
-export default init;
+/**
+ * Auto-save as a mode participant.
+ *
+ * A live entry imports this module in view, where `install` above is inert, so the
+ * participant is how the entry asks for it once the mode has committed. Nothing here
+ * belongs to a session: the scheduler already parks an attempt a closed save session
+ * refuses (`savePageThrottled`) and replays it on `resume`, and every attempt checks the
+ * mode, so quiesce and dispose have nothing to undo. `initial: true` adopts the edit this
+ * tab booted into, where the import's own `install` already ran: the lease starts nothing.
+ */
+export function modeParticipant() {
+  return {
+    id: "clay:autosave",
+    order: 20,
+    prepare(context = {}) {
+      if (context.initial === true) return { enable() {}, quiesce() {}, resume() {}, dispose() {} };
+      return { enable: install, quiesce() {}, resume() {}, dispose() {} };
+    },
+  };
+}

package/src/core/conflict-download.js

@@ -89,6 +89,28 @@ export function downloadHtml({ html, name }) {
   }
 }
 
+// The review panel's own copy: the page a reload kept, when there is one, with every
+// stored row it drew listed beside it as JSON. The rows are already plain, so nothing
+// here reads the ledger the tab no longer has.
+export function downloadStored({ html = null, edits = [] } = {}) {
+  try {
+    const page = typeof html === "string" ? html : captureRecoveryPage();
+    const data = {
+      format: "clay-lost-edits",
+      version: 1,
+      savedAt: new Date().toISOString(),
+      page: location.href,
+      refused: false,
+      edits: Array.isArray(edits) ? edits : [],
+      earlierPages: [],
+    };
+    return downloadHtml({ html: embed(page, data), name: `${documentName()}-my-copy-${stamp()}.html` });
+  } catch (err) {
+    console.error("clayjs: could not build the download", err);
+    return false;
+  }
+}
+
 export function downloadRecovery(records, { refused = false } = {}) {
   try {
     const { html, name } = buildRecovery(records, { refused });