hyperclayjs 1.8.0 → 1.10.0

package/src/core/optionVisibility.js

@@ -31,16 +31,15 @@
  */
 
 import Mutation from "../utilities/mutation.js";
+import insertStyles from "../dom-utilities/insertStyleTag.js";
+
+const STYLE_NAME = 'option-visibility';
 
 const optionVisibility = {
   debug: false,
   _started: false,
-  _styleElement: null,
   _unsubscribe: null,
 
-  LAYER_NAME: 'option-visibility',
-  STYLE_CLASS: 'option-visibility-layer-styles',
-
   log(...args) {
     if (this.debug) console.log('[OptionVisibility:Layer]', ...args);
   },
@@ -104,7 +103,7 @@ const optionVisibility = {
       return `[option\\:${safeName}="${safeValue}"]{display:none!important}[${safeName}="${safeValue}"] [option\\:${safeName}="${safeValue}"]{display:revert-layer!important}`;
     }).join('');
 
-    return `@layer ${this.LAYER_NAME}{${rules}}`;
+    return `@layer ${STYLE_NAME}{${rules}}`;
   },
 
   /**
@@ -119,33 +118,8 @@ const optionVisibility = {
     try {
       const attributes = this.findOptionAttributes();
       const css = this.generateCSS(attributes);
-
-      // Remove style element if no attributes
-      if (!css) {
-        if (this._styleElement) {
-          this._styleElement.remove();
-          this._styleElement = null;
-          this.log('Removed empty style element');
-        }
-        return;
-      }
-
-      // Skip if unchanged
-      if (this._styleElement?.textContent === css) {
-        this.log('Styles unchanged');
-        return;
-      }
-
-      // Create or update
-      if (!this._styleElement) {
-        this._styleElement = document.createElement('style');
-        this._styleElement.className = this.STYLE_CLASS;
-        document.head.appendChild(this._styleElement);
-      }
-
-      this._styleElement.textContent = css;
+      insertStyles(STYLE_NAME, css);
       this.log(`Generated ${attributes.length} rules`);
-
     } catch (error) {
       console.error('[OptionVisibility:Layer] Error generating rules:', error);
     }
@@ -190,10 +164,8 @@ const optionVisibility = {
       this._unsubscribe = null;
     }
 
-    if (this._styleElement) {
-      this._styleElement.remove();
-      this._styleElement = null;
-    }
+    const style = document.querySelector(`style[data-name="${STYLE_NAME}"]`);
+    if (style) style.remove();
 
     this.log('Stopped');
   }

package/src/core/savePageCore.js

@@ -1,64 +1,63 @@
 /**
- * Core save functionality for Hyperclay
+ * savePageCore.js — Network save functionality
  *
- * This is the minimal save system - just the basic save function you can call yourself.
- * No toast notifications, no auto-save, no keyboard shortcuts.
+ * This module handles sending page contents to the server.
+ * It uses snapshot.js for capturing the DOM state.
  *
- * Use this if you want full control over save behavior and notifications.
- * For the full save system with conveniences, use savePage.js instead.
+ * For full save system with state management, use savePage.js instead.
  */
 
 import cookie from "../utilities/cookie.js";
 import { isEditMode } from "./isAdminOfCurrentResource.js";
+import {
+  captureForSave,
+  isCodeMirrorPage,
+  getCodeMirrorContents,
+  beforeSave,
+  getPageContents,
+  onSnapshot,
+  onPrepareForSave
+} from "./snapshot.js";
+
+// =============================================================================
+// STATE
+// =============================================================================
 
-let beforeSaveCallbacks = [];
 let saveInProgress = false;
 const saveEndpoint = `/save/${cookie.get("currentResource")}`;
 
-/**
- * Register a callback to run before saving
- * Callbacks receive the cloned document element
- *
- * @param {Function} cb - Callback function(docElem)
- */
-export function beforeSave(cb) {
-  beforeSaveCallbacks.push(cb);
-}
+// =============================================================================
+// RE-EXPORTS FROM SNAPSHOT (for backwards compat)
+// =============================================================================
+
+export { beforeSave, getPageContents, onSnapshot, onPrepareForSave };
+
+// =============================================================================
+// INTERNAL: GET PAGE CONTENTS
+// =============================================================================
 
 /**
- * Get the current page contents as HTML
- * Handles CodeMirror pages, runs [onbeforesave] attributes, removes [save-ignore] elements
+ * Get the current page contents as HTML string for saving.
+ * Handles both normal pages and CodeMirror editor pages.
+ * Emits snapshot-ready event for live-sync (normal pages only).
  *
  * @returns {string} HTML string of current page
  */
-export function getPageContents() {
-  const isCodeMirrorPage = !!document.querySelector('.CodeMirror')?.CodeMirror;
-
-  if (!isCodeMirrorPage) {
-    let docElem = document.documentElement.cloneNode(true);
-
-    // Run onbeforesave callbacks
-    docElem.querySelectorAll('[onbeforesave]').forEach(el =>
-      new Function(el.getAttribute('onbeforesave')).call(el)
-    );
-
-    // Remove elements marked save-ignore
-    docElem.querySelectorAll('[save-ignore]').forEach(el =>
-      el.remove()
-    );
-
-    // Run registered beforeSave callbacks
-    beforeSaveCallbacks.forEach(cb => cb(docElem));
-
-    return "<!DOCTYPE html>" + docElem.outerHTML;
-  } else {
-    // For CodeMirror pages, get value from editor
-    return document.querySelector('.CodeMirror').CodeMirror.getValue();
+function getContentsForSave() {
+  if (isCodeMirrorPage()) {
+    // CodeMirror pages don't emit snapshot-ready - no live-sync for code editors
+    return getCodeMirrorContents();
   }
+  // Emit for live-sync when actually saving
+  return captureForSave({ emitForSync: true });
 }
 
+// =============================================================================
+// SAVE FUNCTIONS
+// =============================================================================
+
 /**
- * Save the current page contents to the server
+ * Save the current page contents to the server.
  *
  * @param {Function} callback - Called with {msg, msgType} on completion
  *   msgType will be 'success' or 'error'
@@ -82,10 +81,10 @@ export function savePage(callback = () => {}) {
 
   let currentContents;
   try {
-    currentContents = getPageContents();
+    currentContents = getContentsForSave();
   } catch (err) {
-    console.error('savePage: getPageContents failed', err);
-    callback({msg: err.message, msgType: "error"});
+    console.error('savePage: getContentsForSave failed', err);
+    callback({ msg: err.message, msgType: "error" });
     return;
   }
   saveInProgress = true;
@@ -95,15 +94,15 @@ export function savePage(callback = () => {}) {
     setTimeout(() => {
       saveInProgress = false;
       if (typeof callback === 'function') {
-        callback({msg: "Test mode: save skipped", msgType: "success"});
+        callback({ msg: "Test mode: save skipped", msgType: "success" });
       }
     }, 0);
     return;
   }
 
-  // Add timeout - abort if server doesn't respond within 5 seconds
+  // Add timeout - abort if server doesn't respond within 12 seconds
   const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 5000);
+  const timeoutId = setTimeout(() => controller.abort('Save timeout'), 12000);
 
   fetch(saveEndpoint, {
     method: 'POST',
@@ -111,44 +110,43 @@ export function savePage(callback = () => {}) {
     body: currentContents,
     signal: controller.signal
   })
-  .then(res => {
-    clearTimeout(timeoutId);
-    return res.json().then(data => {
-      if (!res.ok) {
-        throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+    .then(res => {
+      clearTimeout(timeoutId);
+      return res.json().then(data => {
+        if (!res.ok) {
+          throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+        }
+        return data;
+      });
+    })
+    .then(data => {
+      if (typeof callback === 'function') {
+        callback({ msg: data.msg, msgType: data.msgType || 'success' });
       }
-      return data;
-    });
-  })
-  .then(data => {
-    if (typeof callback === 'function') {
-      callback({msg: data.msg, msgType: data.msgType || 'success'});
-    }
-  })
-  .catch(err => {
-    clearTimeout(timeoutId);
-    console.error('Failed to save page:', err);
+    })
+    .catch(err => {
+      clearTimeout(timeoutId);
+      console.error('Failed to save page:', err);
 
-    const msg = err.name === 'AbortError'
-      ? 'Server not responding'
-      : 'Save failed';
+      const msg = err.name === 'AbortError'
+        ? 'Server not responding'
+        : 'Save failed';
 
-    if (typeof callback === 'function') {
-      callback({msg, msgType: "error"});
-    }
-  })
-  .finally(() => {
-    clearTimeout(timeoutId);
-    saveInProgress = false;
-  });
+      if (typeof callback === 'function') {
+        callback({ msg, msgType: "error" });
+      }
+    })
+    .finally(() => {
+      clearTimeout(timeoutId);
+      saveInProgress = false;
+    });
 }
 
 /**
- * Save specific HTML content to the server
+ * Save specific HTML content to the server.
  *
  * @param {string} html - HTML string to save
  * @param {Function} callback - Called with (err, data) on completion
- *   err will be null on success, Error object on failure
  *
  * @example
  * saveHtml(myHtml, (err, data) => {
@@ -171,7 +169,7 @@ export function saveHtml(html, callback = () => {}) {
     setTimeout(() => {
       saveInProgress = false;
       if (typeof callback === 'function') {
-        callback(null, {msg: "Test mode: save skipped", msgType: "success"});
+        callback(null, { msg: "Test mode: save skipped", msgType: "success" });
       }
     }, 0);
     return;
@@ -182,32 +180,32 @@ export function saveHtml(html, callback = () => {}) {
     credentials: 'include',
     body: html
   })
-  .then(res => {
-    return res.json().then(data => {
-      if (!res.ok) {
-        throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+    .then(res => {
+      return res.json().then(data => {
+        if (!res.ok) {
+          throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+        }
+        return data;
+      });
+    })
+    .then(data => {
+      if (typeof callback === 'function') {
+        callback(null, data);
       }
-      return data;
+    })
+    .catch(err => {
+      console.error('Failed to save page:', err);
+      if (typeof callback === 'function') {
+        callback(err);
+      }
+    })
+    .finally(() => {
+      saveInProgress = false;
     });
-  })
-  .then(data => {
-    if (typeof callback === 'function') {
-      callback(null, data); // Success: no error
-    }
-  })
-  .catch(err => {
-    console.error('Failed to save page:', err);
-    if (typeof callback === 'function') {
-      callback(err); // Pass error
-    }
-  })
-  .finally(() => {
-    saveInProgress = false;
-  });
 }
 
 /**
- * Fetch HTML from a URL and save it to replace the current page
+ * Fetch HTML from a URL and save it to replace the current page.
  *
  * @param {string} url - URL to fetch HTML from
  * @param {Function} callback - Called with (err, data) on completion
@@ -243,7 +241,10 @@ export function replacePageWith(url, callback = () => {}) {
     });
 }
 
-// Auto-export to window unless suppressed by loader
+// =============================================================================
+// WINDOW EXPORTS
+// =============================================================================
+
 if (!window.__hyperclayNoAutoExport) {
   window.hyperclay = window.hyperclay || {};
   window.hyperclay.savePage = savePage;

package/src/core/snapshot.js

@@ -0,0 +1,203 @@
+/**
+ * snapshot.js — The source of truth for page state
+ *
+ * THE SAVE/SYNC PIPELINE:
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  1. CLONE         document.documentElement.cloneNode()  │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  2. SNAPSHOT HOOKS       onSnapshot callbacks           │
+ *   │                          (form value sync)              │
+ *   │                                                         │
+ *   │     ✓ Used by: SAVE and LIVE-SYNC                       │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *              ┌───────────────┴───────────────┐
+ *              ▼                               ▼
+ *   ┌─────────────────────────┐     ┌─────────────────────────┐
+ *   │  3a. PREPARE HOOKS      │     │  3b. DONE               │
+ *   │  onPrepareForSave       │     │  (live-sync stops here) │
+ *   │  [onbeforesave]         │     │                         │
+ *   │  [save-ignore]          │     │  → emits snapshot-ready │
+ *   │                         │     └─────────────────────────┘
+ *   │  ✓ Used by: SAVE only   │
+ *   └─────────────────────────┘
+ *              │
+ *              ▼
+ *   ┌─────────────────────────┐
+ *   │  4. SERIALIZE           │
+ *   │  "<!DOCTYPE html>"      │
+ *   │  + outerHTML            │
+ *   │                         │
+ *   │  → sent to server       │
+ *   └─────────────────────────┘
+ */
+
+// =============================================================================
+// HOOK REGISTRIES
+// =============================================================================
+
+const snapshotHooks = [];       // Phase 2: Always run (form sync)
+const prepareForSaveHooks = []; // Phase 3a: Save only (strip admin)
+
+/**
+ * Register a hook that runs on EVERY snapshot (save AND sync).
+ * Use for: syncing form values to the clone.
+ *
+ * @param {Function} callback - Receives the cloned document element
+ */
+export function onSnapshot(callback) {
+  snapshotHooks.push(callback);
+}
+
+/**
+ * Register a hook that runs ONLY when preparing for save.
+ * Use for: stripping admin elements, cleanup.
+ *
+ * @param {Function} callback - Receives the cloned document element
+ */
+export function onPrepareForSave(callback) {
+  prepareForSaveHooks.push(callback);
+}
+
+// Backwards compat alias
+export const beforeSave = onPrepareForSave;
+
+// =============================================================================
+// CAPTURE FUNCTIONS
+// =============================================================================
+
+/**
+ * PHASE 1-2: Clone the DOM and run snapshot hooks.
+ *
+ * This is the "canonical" state — form values synced, nothing stripped.
+ * Used as the base for both saving and syncing.
+ *
+ * @returns {HTMLElement} Cloned document element with snapshot hooks applied
+ */
+export function captureSnapshot() {
+  const clone = document.documentElement.cloneNode(true);
+
+  for (const hook of snapshotHooks) {
+    hook(clone);
+  }
+
+  return clone;
+}
+
+/**
+ * Prepare an already-captured snapshot for saving.
+ * Mutates the clone — only call once per snapshot.
+ *
+ * @param {HTMLElement} clone - A snapshot from captureSnapshot()
+ * @returns {string} Full HTML string ready for server
+ */
+function prepareCloneForSave(clone) {
+  // Run inline [onbeforesave] handlers
+  for (const el of clone.querySelectorAll('[onbeforesave]')) {
+    new Function(el.getAttribute('onbeforesave')).call(el);
+  }
+
+  // Remove elements that shouldn't be saved
+  for (const el of clone.querySelectorAll('[save-ignore]')) {
+    el.remove();
+  }
+
+  // Run registered prepare hooks
+  for (const hook of prepareForSaveHooks) {
+    hook(clone);
+  }
+
+  return "<!DOCTYPE html>" + clone.outerHTML;
+}
+
+/**
+ * PHASE 1-4: Full pipeline for saving to server.
+ *
+ * Captures snapshot, emits for live-sync, then prepares for save.
+ * This is the main entry point for the save process.
+ *
+ * @param {Object} options
+ * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
+ * @returns {string} Full HTML string ready for server
+ */
+export function captureForSave({ emitForSync = true } = {}) {
+  const clone = captureSnapshot();
+
+  // Emit for live-sync before stripping admin elements
+  // Sends full cloned documentElement so live-sync can extract head and body
+  if (emitForSync) {
+    document.dispatchEvent(new CustomEvent('hyperclay:snapshot-ready', {
+      detail: { documentElement: clone }
+    }));
+  }
+
+  return prepareCloneForSave(clone);
+}
+
+/**
+ * PHASE 1-2 (body only): For live-sync between admin users.
+ *
+ * Includes admin elements — no stripping.
+ * Note: Prefer listening to 'hyperclay:snapshot-ready' event instead,
+ * which reuses the save's clone.
+ *
+ * @returns {string} Body innerHTML with form values synced
+ */
+export function captureBodyForSync() {
+  const clone = captureSnapshot();
+  return clone.querySelector('body').innerHTML;
+}
+
+/**
+ * Get page contents for change detection.
+ * Does NOT emit snapshot-ready event (safe for comparison).
+ *
+ * For CodeMirror pages, returns editor content directly.
+ * For normal pages, returns full HTML via snapshot pipeline.
+ */
+export function getPageContents() {
+  if (isCodeMirrorPage()) {
+    return getCodeMirrorContents();
+  }
+  return captureForSave({ emitForSync: false });
+}
+
+// =============================================================================
+// CODEMIRROR SUPPORT
+// =============================================================================
+
+/**
+ * Check if this is a CodeMirror editor page.
+ * CodeMirror pages bypass the normal snapshot pipeline.
+ */
+export function isCodeMirrorPage() {
+  return !!document.querySelector('.CodeMirror')?.CodeMirror;
+}
+
+/**
+ * Get CodeMirror editor contents.
+ * @returns {string} Editor contents
+ */
+export function getCodeMirrorContents() {
+  return document.querySelector('.CodeMirror').CodeMirror.getValue();
+}
+
+// =============================================================================
+// WINDOW EXPORTS
+// =============================================================================
+
+if (!window.__hyperclayNoAutoExport) {
+  window.hyperclay = window.hyperclay || {};
+  window.hyperclay.captureSnapshot = captureSnapshot;
+  window.hyperclay.captureForSave = captureForSave;
+  window.hyperclay.captureBodyForSync = captureBodyForSync;
+  window.hyperclay.onSnapshot = onSnapshot;
+  window.hyperclay.onPrepareForSave = onPrepareForSave;
+  window.hyperclay.beforeSave = beforeSave;
+  window.hyperclay.getPageContents = getPageContents;
+  window.h = window.hyperclay;
+}

package/src/core/unsavedWarning.js

@@ -0,0 +1,26 @@
+/**
+ * Unsaved Warning Module
+ *
+ * Warns users before leaving the page if there are unsaved changes.
+ * Self-contained: compares current page content to last saved content on beforeunload.
+ *
+ * Works independently of autosave - no mutation observer needed during editing,
+ * just a single comparison when the user tries to leave.
+ *
+ * Requires the 'save-system' module (automatically included as dependency).
+ */
+
+import { isOwner, isEditMode } from "./isAdminOfCurrentResource.js";
+import { getPageContents, getLastSavedContents } from "./savePage.js";
+
+window.addEventListener('beforeunload', (event) => {
+  if (!isOwner || !isEditMode) return;
+
+  const currentContents = getPageContents();
+  const lastSaved = getLastSavedContents();
+
+  if (currentContents !== lastSaved) {
+    event.preventDefault();
+    event.returnValue = '';
+  }
+});

package/src/custom-attributes/ajaxElements.js

@@ -38,16 +38,9 @@ function submitAjax(elem) {
     }
     method = (method || 'POST').toUpperCase();
 
-    // Get data - for buttons, only use form data if button is inside a form
-    let data = {};
-    if (isButton && parentForm) {
-      // Button inside form: use form data
-      data = getDataFromForm(parentForm);
-    } else if (!isButton) {
-      // It's a form element itself
-      data = getDataFromForm(elem);
-    }
-    // For standalone buttons with no form, data remains empty object
+    // Get data - from parent form if button is inside one, otherwise from element itself
+    const dataSource = (isButton && parentForm) ? parentForm : elem;
+    const data = getDataFromForm(dataSource);
 
     fetch(url, {
       method: method,

package/src/custom-attributes/onaftersave.js

@@ -1,16 +1,16 @@
 /**
  * [onaftersave] Custom Attribute
  *
- * Runs inline JavaScript when save status changes.
- * Pairs with the existing [onbeforesave] attribute.
+ * Runs inline JavaScript after a successful save.
+ * Only fires on 'hyperclay:save-saved' events (not on error/offline).
  *
  * Usage:
  *   <span onaftersave="this.innerText = event.detail.msg"></span>
- *   <div onaftersave="console.log('Status:', event.detail.status)"></div>
+ *   <link href="styles.css" onaftersave="cacheBust(this)">
  *
  * The event.detail object contains:
- *   - status: 'saving' | 'saved' | 'offline' | 'error'
- *   - msg: string (e.g., 'Saved' or error message)
+ *   - status: 'saved'
+ *   - msg: string (e.g., 'Saved')
  *   - timestamp: number (Date.now())
  */
 
@@ -30,10 +30,7 @@ function broadcast(e) {
 }
 
 function init() {
-  document.addEventListener('hyperclay:save-saving', broadcast);
   document.addEventListener('hyperclay:save-saved', broadcast);
-  document.addEventListener('hyperclay:save-offline', broadcast);
-  document.addEventListener('hyperclay:save-error', broadcast);
 }
 
 init();