@panphora/clayjs 0.2.0 → 0.4.0

package/src/attrs/save-freeze.js

@@ -16,7 +16,7 @@
  * Changes inside freeze elements do not trigger autosave dirty checks.
  */
 
-import { onSnapshot, onPrepareForSave } from "../core/snapshot.js";
+import { onSnapshot, addDocumentTransform } from "../core/snapshot.js";
 import { isEditMode } from "../core/is-edit-mode.js";
 import { FREEZE_SELECTOR } from "../lib/region-policy.js";
 import Mutation from "../lib/mutation.js";
@@ -44,22 +44,51 @@ function captureAll() {
   }
 }
 
-function freezeClone(clone) {
+// 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
+// would work too, right up until clay:snapshot-ready — which fires BETWEEN the two
+// phases — hands the still-marked clone to live-sync and demo mode, both of which
+// serialize it on the spot.
+let pending = new WeakMap();
+
+// Phase 2. The clone is a verbatim cloneNode of the live root and nothing has been
+// stripped from it yet, so pairing by position is sound HERE and nowhere else.
+function freezeSnapshot(clone) {
+  pending = new WeakMap();
+
   const liveElements = document.querySelectorAll(FREEZE_SELECTOR);
   const cloneElements = clone.querySelectorAll(FREEZE_SELECTOR);
 
   log('freezing clone — live:', liveElements.length, 'clone:', cloneElements.length);
 
+  // Counts can only differ if an earlier onSnapshot hook added or removed
+  // elements, which means alignment is already gone. Restoring nothing beats
+  // restoring one element's authored content into a different element.
+  if (liveElements.length !== cloneElements.length) {
+    console.warn('[save-freeze] live/clone freeze counts differ, skipping freeze restore');
+    return;
+  }
+
   for (let i = 0; i < cloneElements.length; i++) {
-    const liveEl = liveElements[i];
-    const hasOriginal = liveEl && originals.has(liveEl);
-    if (hasOriginal) {
-      const original = originals.get(liveEl);
-      const current = cloneElements[i].innerHTML;
-      if (original !== current) {
-        log('element', i, '— restoring original');
-        cloneElements[i].innerHTML = original;
-      }
+    if (!originals.has(liveElements[i])) continue;
+    const original = originals.get(liveElements[i]);
+    pending.set(cloneElements[i], original);
+    if (cloneElements[i].innerHTML !== original) {
+      log('element', i, '— restoring original');
+      cloneElements[i].innerHTML = original;
+    }
+  }
+}
+
+// Phase 3a. Re-freeze anything an [onbeforesave] handler changed between the two
+// phases. Nothing to clean up: the pairing never entered the document.
+function freezePrepare(clone) {
+  for (const el of clone.querySelectorAll(FREEZE_SELECTOR)) {
+    const original = pending.get(el);
+    if (original !== undefined && el.innerHTML !== original) {
+      log('re-restoring original after prepare-phase change');
+      el.innerHTML = original;
     }
   }
 }
@@ -75,10 +104,8 @@ function init() {
   // 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. NOTE: the old observer watched
-  // document.documentElement; Mutation watches document.body, so a [freeze] added
-  // directly to <head> at runtime is no longer captured (authored <head> freeze
-  // regions are still handled by captureAll() on load) — an accepted edge.
+  // 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',
@@ -90,11 +117,12 @@ function init() {
 
   // Phase 2: Freeze in snapshot — before snapshot-ready fires.
   // This prevents live-sync from writing unfrozen content to disk.
-  onSnapshot(freezeClone);
+  onSnapshot(freezeSnapshot);
 
-  // Phase 3a: Freeze again in prepare — belt-and-suspenders.
-  // Catches any modifications made between phase 2 and 3a (e.g., onbeforesave handlers).
-  onPrepareForSave(freezeClone);
+  // Phase 3a: Freeze again in prepare, for anything changed between the phases
+  // (e.g. onbeforesave handlers). Pairs by the WeakMap phase 2 filled, because by
+  // now the clone has lost its [no-snapshot] subtrees and position means nothing.
+  addDocumentTransform(freezePrepare);
 }
 
 init();

package/src/core/admin-contenteditable.js

@@ -1,11 +1,11 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
-import { beforeSave } from "./snapshot.js";
+import { addDocumentTransform } from "./snapshot.js";
 
 export const SELECTOR = '[editmode\\:contenteditable]';
 
 export function disableContentEditableBeforeSave () {
-  beforeSave(docElem => {
+  addDocumentTransform(docElem => {
     docElem.querySelectorAll(SELECTOR).forEach(resource => {
       const originalValue = resource.getAttribute("contenteditable");
       resource.setAttribute("inert-contenteditable", originalValue);

package/src/core/admin-inputs.js

@@ -1,12 +1,12 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
-import { beforeSave } from "./snapshot.js";
+import { addDocumentTransform } from "./snapshot.js";
 
 export const SELECTOR_DISABLED = '[viewmode\\:disabled]';
 export const SELECTOR_READONLY = '[viewmode\\:readonly]';
 
 export function disableAdminInputsBeforeSave() {
-  beforeSave(docElem => {
+  addDocumentTransform(docElem => {
     docElem.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
       input.setAttribute('disabled', '');
     });

package/src/core/admin-onclick.js

@@ -1,11 +1,11 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
-import { beforeSave } from "./snapshot.js";
+import { addDocumentTransform } from "./snapshot.js";
 
 export const SELECTOR = '[editmode\\:onclick]';
 
 export function disableOnClickBeforeSave () {
-  beforeSave(docElem => {
+  addDocumentTransform(docElem => {
     docElem.querySelectorAll(SELECTOR).forEach(resource => {
       const originalValue = resource.getAttribute("onclick");
       resource.setAttribute("inert-onclick", originalValue);

package/src/core/admin-resources.js

@@ -1,18 +1,31 @@
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
-import { beforeSave } from "./snapshot.js";
+import { addDocumentTransform } from "./snapshot.js";
 
 export const SELECTOR = '[editmode\\:resource]:is(style, link, script)';
 export const SELECTOR_INERT = '[editmode\\:resource]:is(style, link, script)[type^="inert/"]';
 
+const INERT_PREFIX = 'inert/';
+
+// An absent type is recorded as an empty remainder, so enabling restores absence
+// rather than inventing text/javascript. A <style> or a stylesheet <link> handed a
+// JavaScript MIME on the way back never applies again.
+function makeInert(resource) {
+  const current = resource.getAttribute('type');
+  if (current && current.startsWith(INERT_PREFIX)) return false;
+  resource.setAttribute('type', INERT_PREFIX + (current || ''));
+  return true;
+}
+
+function makeActive(resource) {
+  const original = resource.getAttribute('type').slice(INERT_PREFIX.length);
+  if (original) resource.setAttribute('type', original);
+  else resource.removeAttribute('type');
+}
+
 export function disableAdminResourcesBeforeSave () {
-  beforeSave(docElem => {
-    docElem.querySelectorAll(SELECTOR).forEach(resource => {
-      const currentType = resource.getAttribute('type') || 'text/javascript';
-      if (!currentType.startsWith('inert/')) {
-        resource.setAttribute('type', `inert/${currentType}`);
-      }
-    });
+  addDocumentTransform(docElem => {
+    docElem.querySelectorAll(SELECTOR).forEach(makeInert);
   });
 }
 
@@ -27,18 +40,14 @@ export function enableAdminResourcesOnPageLoad () {
 // Runtime toggle functions
 export function enableAdminResources() {
   document.querySelectorAll(SELECTOR_INERT).forEach(resource => {
-    resource.type = resource.type.replace(/inert\//g, '');
+    makeActive(resource);
     resource.replaceWith(resource.cloneNode(true));
   });
 }
 
 export function disableAdminResources() {
   document.querySelectorAll(SELECTOR).forEach(resource => {
-    const currentType = resource.getAttribute('type') || 'text/javascript';
-    if (!currentType.startsWith('inert/')) {
-      resource.setAttribute('type', `inert/${currentType}`);
-      resource.replaceWith(resource.cloneNode(true));
-    }
+    if (makeInert(resource)) resource.replaceWith(resource.cloneNode(true));
   });
 }
 

package/src/core/autosave.js

@@ -19,9 +19,19 @@ import { initUserGesture, markUserDriven } from "../lib/user-gesture.js";
  * Initialize auto-save on DOM changes
  * Uses debounced mutation observer
  */
+// 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: 1500,
+    debounce: AUTOSAVE_DEBOUNCE_MS,
+    maxWait: AUTOSAVE_MAX_WAIT_MS,
     omitChangeDetails: true,
     require: 'autosave'
   }, () => {

package/src/core/edit-mode.js

@@ -3,7 +3,7 @@
 // (it's the way IN), and setPageTypeOnPageLoad marks <html> in either mode.
 import { isEditMode, isOwner } from "./is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
-import { beforeSave } from "./snapshot.js";
+import { addDocumentTransform } from "./snapshot.js";
 
 export function toggleEditMode() {
   const url = new URL(window.location.href);
@@ -13,7 +13,7 @@ export function toggleEditMode() {
 }
 
 export function setViewerPageTypeBeforeSave () {
-  beforeSave(docElem => {
+  addDocumentTransform(docElem => {
     docElem.setAttribute("editmode", "false");
     docElem.setAttribute("pageowner", "false");
   });

package/src/core/host-attrs.js

@@ -0,0 +1,46 @@
+/**
+ * host-attrs.js — the attributes a host puts on <html>, and what they mean.
+ *
+ * These are ephemeral: the host injects them into the response and strips them
+ * back out of whatever the client saves, so they never reach disk. clayjs only
+ * ever reads them, and reads them here so the two spellings of the save token
+ * cannot drift between the edit-mode ladder and the save lane.
+ */
+
+import { HOST_TOKEN_ATTRS, SAVE_TRANSPORT_ATTR } from "../lib/root-attrs.js";
+
+// A host that wants the desktop JSON envelope on its save lane declares it on
+// the root. This replaced a `location.hostname === 'localhost'` sniff, which sent
+// the envelope to every host that happened to be local, including ones whose
+// save lane takes text and answers 415.
+export const DESKTOP_JSON = "desktop-json-v1";
+
+/**
+ * The per-document save token this response carries, or null.
+ * @returns {?string}
+ */
+export function saveToken() {
+  if (typeof document === "undefined") return null;
+  for (const attr of HOST_TOKEN_ATTRS) {
+    const value = document.documentElement.getAttribute(attr);
+    if (value) return value;
+  }
+  return null;
+}
+
+/**
+ * True when the host handed this response a save token of either spelling.
+ * @returns {boolean}
+ */
+export function hasSaveToken() {
+  return saveToken() !== null;
+}
+
+/**
+ * The save transport the served document declares, or null.
+ * @returns {?string}
+ */
+export function saveTransport() {
+  if (typeof document === "undefined") return null;
+  return document.documentElement.getAttribute(SAVE_TRANSPORT_ATTR);
+}

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

@@ -1,12 +1,20 @@
 import cookie from "../lib/cookie.js";
 import query from "../lib/query.js";
+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 the platform's
-// 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.
+// 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
+// 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.
+//
+// The token sits above the cookie because it is the stronger claim and often the
+// only one visible: the host minted it for this response and nothing else, while
+// the cookie is ambient. A sandboxed document cannot read the cookie at all, so
+// without this rung a host that sandboxes its own documents can hand one a save
+// token and still watch it render read-only.
 let forcedEditMode = null;
 if (typeof window !== "undefined") {
   if (window.clayEditMode != null) {
@@ -17,10 +25,10 @@ if (typeof window !== "undefined") {
 }
 
 const isEditMode = query.editmode
-  ? query.editmode === "true" // takes precedence over the global and cookie
+  ? query.editmode === "true" // takes precedence over the global, token and cookie
   : forcedEditMode != null
     ? forcedEditMode
-    : Boolean(cookie.get("isAdminOfCurrentResource"));
+    : hasSaveToken() || Boolean(cookie.get("isAdminOfCurrentResource"));
 
 const isOwner = Boolean(cookie.get("isAdminOfCurrentResource"));
 

package/src/core/persist.js

@@ -86,7 +86,14 @@ export default function enablePersistentFormInputValues(filterBySelector = "[per
     const finalize = (selector) => {
       const live = document.querySelectorAll(selector);
       const cloned = doc.querySelectorAll(selector);
-      cloned.forEach((c, i) => { if (live[i]) finalizeControlForSave(c, live[i]); });
+      // Index pairing only holds while the two lists describe the same tree. If a
+      // hook ever diverges them, writing one control's value into another's is
+      // worse than writing none, so fail loudly instead of silently.
+      if (live.length !== cloned.length) {
+        console.warn('[persist] live/clone counts differ for', selector, '— skipping');
+        return;
+      }
+      cloned.forEach((c, i) => finalizeControlForSave(c, live[i]));
     };
     finalize(inputSelector);
     finalize(textareaSelector);