hyperclayjs 1.26.0 → 1.26.2

package/README.md

@@ -62,10 +62,10 @@ import 'hyperclayjs/presets/standard.js';
 | edit-mode-helpers | 6.8KB | Admin-only functionality: [viewmode:disabled], [editmode:resource], [editmode:onclick] |
 | option-visibility | 7.1KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
 | persist | 6.4KB | Persist input/select/textarea values to the DOM with [persist] attribute |
-| save-core | 8.9KB | Basic save function only - hyperclay.savePage() |
-| save-system | 13.4KB | CMD+S, [trigger-save] button, savestatus attribute |
+| save-core | 11.5KB | Basic save function only - hyperclay.savePage() |
+| save-system | 15.4KB | CMD+S, [trigger-save] button, savestatus attribute |
 | save-toast | 0.9KB | Toast notifications for save events |
-| snapshot | 10.8KB | Source of truth for page state - captures DOM snapshots for save and sync |
+| snapshot | 11KB | Source of truth for page state - captures DOM snapshots for save and sync |
 | unsaved-warning | 1.3KB | Warn before leaving page with unsaved changes |
 
 ### Custom Attributes (HTML enhancements)
@@ -96,10 +96,10 @@ import 'hyperclayjs/presets/standard.js';
 |--------|------|-------------|
 | cache-bust | 0.6KB | Cache-bust href/src attributes |
 | cookie | 1.4KB | Cookie management (often auto-included) |
-| debounce | 0.4KB | Function debouncing |
+| debounce | 0.7KB | Function debouncing |
 | mutation | 13.8KB | DOM mutation observation (often auto-included) |
 | nearest | 3.4KB | Find nearest elements (often auto-included) |
-| throttle | 0.8KB | Function throttling |
+| throttle | 1.3KB | Function throttling |
 
 ### DOM Utilities (DOM manipulation helpers)
 
@@ -134,17 +134,17 @@ import 'hyperclayjs/presets/standard.js';
 
 ## Presets
 
-### Minimal (~57KB)
+### Minimal (~61.8KB)
 Essential features for basic editing
 
 **Modules:** `save-core`, `snapshot`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Standard (~83.9KB)
+### Standard (~88.7KB)
 Standard feature set for most use cases
 
 **Modules:** `save-core`, `snapshot`, `save-system`, `unsaved-warning`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Everything (~225.8KB)
+### Everything (~231.4KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperclayjs",
-  "version": "1.26.0",
+  "version": "1.26.2",
   "description": "Modular JavaScript library for building interactive malleable HTML files with Hyperclay",
   "type": "module",
   "main": "src/hyperclay.js",

package/src/core/savePage.js

@@ -121,129 +121,160 @@ export function getLastSavedContents() { return lastSavedContents; }
 export function setLastSavedContents(val) { lastSavedContents = val; }
 
 /**
- * Save the current page with change detection and state management
+ * Save the current page with change detection and state management.
+ *
+ * Returns a Promise that resolves with {msg, msgType} — the same object
+ * passed to the callback. Promise never rejects; errors resolve with
+ * msgType: 'error', skipped early-returns resolve with msgType: 'skipped'.
  *
  * @param {Function} callback - Optional callback for custom handling
+ * @returns {Promise<{msg: string, msgType: string}>}
  */
 export function savePage(callback = () => {}) {
-  if (!isEditMode && !window.hyperclay?.testMode) {
-    return;
-  }
+  return new Promise((resolve) => {
+    if (!isEditMode && !window.hyperclay?.testMode) {
+      const skipped = { msg: 'Not in edit mode', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
 
-  // Don't start a new save if one is already in progress
-  if (isSaveInProgress()) {
-    return;
-  }
+    // Don't start a new save if one is already in progress
+    if (isSaveInProgress()) {
+      const skipped = { msg: 'Save already in progress', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
 
-  // Check if offline - set DOM state immediately for UI feedback
-  // but still try the fetch (navigator.onLine can be wrong)
-  const wasOffline = !navigator.onLine;
-  if (wasOffline) {
-    setOfflineStateQuiet();
-  }
+    // Check if offline - set DOM state immediately for UI feedback
+    // but still try the fetch (navigator.onLine can be wrong)
+    const wasOffline = !navigator.onLine;
+    if (wasOffline) {
+      setOfflineStateQuiet();
+    }
 
-  // Single capture: clone once, get both versions
-  // forComparison has [save-remove] and [save-ignore] stripped
-  // forSave has only [save-remove] stripped
-  let forSave, forComparison;
-  try {
-    ({ forSave, forComparison } = captureForSaveAndComparison());
-  } catch (err) {
-    console.error('savePage: captureForSaveAndComparison failed', err);
-    setSaveState('error', err.message);
-    if (typeof callback === 'function') {
-      callback({ msg: err.message, msgType: 'error' });
+    // Single capture: clone once, get both versions
+    // forComparison has [save-remove] and [save-ignore] stripped
+    // forSave has only [save-remove] stripped
+    let forSave, forComparison;
+    try {
+      ({ forSave, forComparison } = captureForSaveAndComparison());
+    } catch (err) {
+      console.error('savePage: captureForSaveAndComparison failed', err);
+      setSaveState('error', err.message);
+      const result = { msg: err.message, msgType: 'error' };
+      if (typeof callback === 'function') {
+        callback(result);
+      }
+      return resolve(result);
     }
-    return;
-  }
 
-  // Compare directly - lastSavedContents is already stripped
-  unsavedChanges = (forComparison !== lastSavedContents);
-  logSaveCheck('savePage dirty check', !unsavedChanges);
+    // Compare directly - lastSavedContents is already stripped
+    unsavedChanges = (forComparison !== lastSavedContents);
+    logSaveCheck('savePage dirty check', !unsavedChanges);
 
-  // Skip if content hasn't changed
-  if (!unsavedChanges) {
-    return;
-  }
+    // Skip if content hasn't changed
+    if (!unsavedChanges) {
+      const skipped = { msg: 'No changes to save', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
 
-  // Start debounced 'saving' state (only shows if save takes >500ms)
-  setSavingState();
-
-  // Use saveHtml directly with our pre-captured content (avoids double capture)
-  saveHtml(forSave, (err, data) => {
-    if (!err) {
-      // SUCCESS - store stripped version for future comparisons
-      lastSavedContents = forComparison;
-      unsavedChanges = false;
-      setSaveState('saved', data?.msg || 'Saved');
-      logBaseline('updated after save', `${lastSavedContents.length} chars`);
-    } else {
-      // FAILED - determine if it's offline or server error
-      if (!navigator.onLine) {
-        setSaveState('offline', err.message);
+    // Start debounced 'saving' state (only shows if save takes >500ms)
+    setSavingState();
+
+    // Use saveHtml directly with our pre-captured content (avoids double capture)
+    saveHtml(forSave, (err, data) => {
+      if (!err) {
+        // SUCCESS - store stripped version for future comparisons
+        lastSavedContents = forComparison;
+        unsavedChanges = false;
+        setSaveState('saved', data?.msg || 'Saved');
+        logBaseline('updated after save', `${lastSavedContents.length} chars`);
       } else {
-        setSaveState('error', err.message);
+        // FAILED - determine if it's offline or server error
+        if (!navigator.onLine) {
+          setSaveState('offline', err.message);
+        } else {
+          setSaveState('error', err.message);
+        }
       }
-    }
 
-    // Call user callback if provided (preserve server's msgType)
-    if (typeof callback === 'function') {
-      callback({
+      // Call user callback if provided (preserve server's msgType)
+      const result = {
         msg: err?.message || data?.msg,
         msgType: err ? 'error' : (data?.msgType || 'success')
-      });
-    }
+      };
+      if (typeof callback === 'function') {
+        callback(result);
+      }
+      resolve(result);
+    });
   });
 }
 
+/**
+ * Force-save the current page (skips dirty check).
+ *
+ * @param {Function} callback - Optional callback for custom handling
+ * @returns {Promise<{msg: string, msgType: string}>}
+ */
 export function savePageForce(callback = () => {}) {
-  if (!isEditMode && !window.hyperclay?.testMode) {
-    return;
-  }
+  return new Promise((resolve) => {
+    if (!isEditMode && !window.hyperclay?.testMode) {
+      const skipped = { msg: 'Not in edit mode', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
 
-  if (isSaveInProgress()) {
-    return;
-  }
+    if (isSaveInProgress()) {
+      const skipped = { msg: 'Save already in progress', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
 
-  const wasOffline = !navigator.onLine;
-  if (wasOffline) {
-    setOfflineStateQuiet();
-  }
+    const wasOffline = !navigator.onLine;
+    if (wasOffline) {
+      setOfflineStateQuiet();
+    }
 
-  let forSave, forComparison;
-  try {
-    ({ forSave, forComparison } = captureForSaveAndComparison());
-  } catch (err) {
-    console.error('savePageForce: captureForSaveAndComparison failed', err);
-    setSaveState('error', err.message);
-    if (typeof callback === 'function') {
-      callback({ msg: err.message, msgType: 'error' });
+    let forSave, forComparison;
+    try {
+      ({ forSave, forComparison } = captureForSaveAndComparison());
+    } catch (err) {
+      console.error('savePageForce: captureForSaveAndComparison failed', err);
+      setSaveState('error', err.message);
+      const result = { msg: err.message, msgType: 'error' };
+      if (typeof callback === 'function') {
+        callback(result);
+      }
+      return resolve(result);
     }
-    return;
-  }
 
-  setSavingState();
+    setSavingState();
 
-  saveHtml(forSave, (err, data) => {
-    if (!err) {
-      lastSavedContents = forComparison;
-      unsavedChanges = false;
-      setSaveState('saved', data?.msg || 'Saved');
-      logBaseline('updated after force save', `${lastSavedContents.length} chars`);
-    } else {
-      if (!navigator.onLine) {
-        setSaveState('offline', err.message);
+    saveHtml(forSave, (err, data) => {
+      if (!err) {
+        lastSavedContents = forComparison;
+        unsavedChanges = false;
+        setSaveState('saved', data?.msg || 'Saved');
+        logBaseline('updated after force save', `${lastSavedContents.length} chars`);
       } else {
-        setSaveState('error', err.message);
+        if (!navigator.onLine) {
+          setSaveState('offline', err.message);
+        } else {
+          setSaveState('error', err.message);
+        }
       }
-    }
 
-    if (typeof callback === 'function') {
-      callback({
+      const result = {
         msg: err?.message || data?.msg,
         msgType: err ? 'error' : (data?.msgType || 'success')
-      });
-    }
+      };
+      if (typeof callback === 'function') {
+        callback(result);
+      }
+      resolve(result);
+    });
   });
 }
 
@@ -364,13 +395,21 @@ if (document.readyState === 'loading') {
 }
 
 /**
- * Save the page with throttling, for use with auto-save
- * Checks both baseline and last saved content to prevent saves from initial setup
+ * Save the page with throttling, for use with auto-save.
+ * Checks both baseline and last saved content to prevent saves from initial setup.
+ *
+ * Returns a Promise resolving with {msg, msgType}. Within-throttle-window calls
+ * piggyback on the trailing-edge save and resolve with its result.
  *
  * @param {Function} callback - Optional callback
+ * @returns {Promise<{msg: string, msgType: string}>}
  */
 export function savePageThrottled(callback = () => {}) {
-  if (!isEditMode) return;
+  if (!isEditMode) {
+    const skipped = { msg: 'Not in edit mode', msgType: 'skipped' };
+    callback(skipped);
+    return Promise.resolve(skipped);
+  }
 
   // For autosave: check both that content changed from baseline AND from last save
   // This prevents saves from initial setup mutations
@@ -382,10 +421,14 @@ export function savePageThrottled(callback = () => {}) {
   logSaveCheck('throttled vs baseline', !differsFromBaseline);
   logSaveCheck('throttled vs lastSave', !differsFromLastSave);
 
-  if (differsFromBaseline && differsFromLastSave) {
-    unsavedChanges = true;
-    throttledSave(callback);
+  if (!(differsFromBaseline && differsFromLastSave)) {
+    const skipped = { msg: 'No changes to save', msgType: 'skipped' };
+    callback(skipped);
+    return Promise.resolve(skipped);
   }
+
+  unsavedChanges = true;
+  return throttledSave(callback);
 }
 
 /**

package/src/core/savePageCore.js

@@ -66,240 +66,294 @@ function getContentsForSave() {
 /**
  * Save the current page contents to the server.
  *
+ * Returns a Promise that resolves with {msg, msgType} — the same object
+ * passed to the callback. Promise never rejects; errors resolve with
+ * msgType: 'error', skipped early-returns resolve with msgType: 'skipped'.
+ *
  * @param {Function} callback - Called with {msg, msgType} on completion
- *   msgType will be 'success' or 'error'
+ *   msgType will be 'success', 'error', or 'skipped'
+ * @returns {Promise<{msg: string, msgType: string}>}
  *
  * @example
+ * // Callback form (unchanged)
  * savePage(({msg, msgType}) => {
- *   if (msgType === 'error') {
- *     console.error('Save failed:', msg);
- *   } else {
- *     console.log('Saved:', msg);
- *   }
+ *   if (msgType === 'error') console.error('Save failed:', msg);
  * });
+ *
+ * @example
+ * // Promise form
+ * const {msg, msgType} = await savePage();
+ * if (msgType === 'error') console.error('Save failed:', msg);
  */
 export function savePage(callback = () => {}) {
-  if (saveInProgress) {
-    return;
-  }
-  if (!isEditMode && !window.hyperclay?.testMode) {
-    return;
-  }
-
-  let currentContents;
-  try {
-    currentContents = getContentsForSave();
-  } catch (err) {
-    console.error('savePage: getContentsForSave failed', err);
-    callback({ msg: err.message, msgType: "error" });
-    return;
-  }
-  saveInProgress = true;
-
-  // Test mode: skip network request, return mock success
-  if (window.hyperclay?.testMode) {
-    setTimeout(() => {
-      saveInProgress = false;
-      if (typeof callback === 'function') {
-        callback({ msg: "Test mode: save skipped", msgType: "success" });
-      }
-    }, 0);
-    return;
-  }
+  return new Promise((resolve) => {
+    if (saveInProgress) {
+      const skipped = { msg: 'Save already in progress', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
+    if (!isEditMode && !window.hyperclay?.testMode) {
+      const skipped = { msg: 'Not in edit mode', msgType: 'skipped' };
+      callback(skipped);
+      return resolve(skipped);
+    }
+
+    let currentContents;
+    try {
+      currentContents = getContentsForSave();
+    } catch (err) {
+      console.error('savePage: getContentsForSave failed', err);
+      const result = { msg: err.message, msgType: "error" };
+      callback(result);
+      return resolve(result);
+    }
+    saveInProgress = true;
+
+    // Test mode: skip network request, return mock success
+    if (window.hyperclay?.testMode) {
+      setTimeout(() => {
+        saveInProgress = false;
+        const result = { msg: "Test mode: save skipped", msgType: "success" };
+        if (typeof callback === 'function') {
+          callback(result);
+        }
+        resolve(result);
+      }, 0);
+      return;
+    }
+
+    // Add timeout - abort if server doesn't respond within 12 seconds
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 12000);
+
+    // Check if running on Hyperclay Local - send JSON with both versions for platform sync
+    const isHyperclayLocal = window.location.hostname === 'localhost' ||
+                             window.location.hostname === '127.0.0.1';
+
+    const fetchOptions = {
+      method: 'POST',
+      credentials: 'include',
+      signal: controller.signal,
+      headers: { 'Page-URL': window.location.href }
+    };
+
+    if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
+      // Send JSON with both stripped content and full snapshot for platform live sync
+      fetchOptions.headers['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify({
+        content: currentContents,
+        snapshotHtml: window.__hyperclaySnapshotHtml
+      });
+      // Clear after use to avoid stale data
+      window.__hyperclaySnapshotHtml = null;
+    } else {
+      // Platform: send plain text as before
+      fetchOptions.body = currentContents;
+    }
+
+    fetch(saveEndpoint, fetchOptions)
+      .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 => {
+        const result = { msg: data.msg, msgType: data.msgType || 'success' };
+        if (typeof callback === 'function') {
+          callback(result);
+        }
+        resolve(result);
+      })
+      .catch(err => {
+        clearTimeout(timeoutId);
+        console.error('Failed to save page:', err);
 
-  // Add timeout - abort if server doesn't respond within 12 seconds
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 12000);
-
-  // Check if running on Hyperclay Local - send JSON with both versions for platform sync
-  const isHyperclayLocal = window.location.hostname === 'localhost' ||
-                           window.location.hostname === '127.0.0.1';
-
-  const fetchOptions = {
-    method: 'POST',
-    credentials: 'include',
-    signal: controller.signal,
-    headers: { 'Page-URL': window.location.href }
-  };
-
-  if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
-    // Send JSON with both stripped content and full snapshot for platform live sync
-    fetchOptions.headers['Content-Type'] = 'application/json';
-    fetchOptions.body = JSON.stringify({
-      content: currentContents,
-      snapshotHtml: window.__hyperclaySnapshotHtml
-    });
-    // Clear after use to avoid stale data
-    window.__hyperclaySnapshotHtml = null;
-  } else {
-    // Platform: send plain text as before
-    fetchOptions.body = currentContents;
-  }
+        const msg = err.name === 'AbortError'
+          ? 'Server not responding'
+          : 'Save failed';
 
-  fetch(saveEndpoint, fetchOptions)
-    .then(res => {
-      clearTimeout(timeoutId);
-      return res.json().then(data => {
-        if (!res.ok) {
-          throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+        const result = { msg, msgType: "error" };
+        if (typeof callback === 'function') {
+          callback(result);
         }
-        return data;
+        resolve(result);
+      })
+      .finally(() => {
+        clearTimeout(timeoutId);
+        saveInProgress = false;
       });
-    })
-    .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);
-
-      const msg = err.name === 'AbortError'
-        ? 'Server not responding'
-        : 'Save failed';
-
-      if (typeof callback === 'function') {
-        callback({ msg, msgType: "error" });
-      }
-    })
-    .finally(() => {
-      clearTimeout(timeoutId);
-      saveInProgress = false;
-    });
+  });
 }
 
 /**
  * Save specific HTML content to the server.
  *
+ * Returns a Promise that resolves with {err, data} — same arguments
+ * passed to the callback. Promise never rejects; errors resolve with
+ * truthy err. Skipped early-returns resolve with data.msgType: 'skipped'.
+ *
  * @param {string} html - HTML string to save
  * @param {Function} callback - Called with (err, data) on completion
+ * @returns {Promise<{err: ?Error, data: ?{msg: string, msgType: string}}>}
  *
  * @example
+ * // Callback form (unchanged)
  * saveHtml(myHtml, (err, data) => {
- *   if (err) {
- *     console.error('Save failed:', err);
- *   } else {
- *     console.log('Saved:', data);
- *   }
+ *   if (err) console.error('Save failed:', err);
  * });
+ *
+ * @example
+ * // Promise form
+ * const {err, data} = await saveHtml(myHtml);
+ * if (err) console.error('Save failed:', err);
  */
 export function saveHtml(html, callback = () => {}) {
-  if (!isEditMode || saveInProgress) {
-    return;
-  }
-
-  saveInProgress = true;
-
-  // Test mode: skip network request, return mock success
-  if (window.hyperclay?.testMode) {
-    setTimeout(() => {
-      saveInProgress = false;
-      if (typeof callback === 'function') {
-        callback(null, { msg: "Test mode: save skipped", msgType: "success" });
-      }
-    }, 0);
-    return;
-  }
+  return new Promise((resolve) => {
+    if (!isEditMode || saveInProgress) {
+      const data = {
+        msg: saveInProgress ? 'Save already in progress' : 'Not in edit mode',
+        msgType: 'skipped'
+      };
+      callback(null, data);
+      return resolve({ err: null, data });
+    }
+
+    saveInProgress = true;
+
+    // Test mode: skip network request, return mock success
+    if (window.hyperclay?.testMode) {
+      setTimeout(() => {
+        saveInProgress = false;
+        const data = { msg: "Test mode: save skipped", msgType: "success" };
+        if (typeof callback === 'function') {
+          callback(null, data);
+        }
+        resolve({ err: null, data });
+      }, 0);
+      return;
+    }
+
+    // Add timeout - abort if server doesn't respond within 12 seconds
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 12000);
+
+    // Check if running on Hyperclay Local - send JSON with both versions for platform sync
+    const isHyperclayLocal = window.location.hostname === 'localhost' ||
+                             window.location.hostname === '127.0.0.1';
+
+    const fetchOptions = {
+      method: 'POST',
+      credentials: 'include',
+      signal: controller.signal,
+      headers: { 'Page-URL': window.location.href }
+    };
+
+    if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
+      // Send JSON with both stripped content and full snapshot for platform live sync
+      fetchOptions.headers['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify({
+        content: html,
+        snapshotHtml: window.__hyperclaySnapshotHtml
+      });
+      // Clear after use to avoid stale data
+      window.__hyperclaySnapshotHtml = null;
+    } else {
+      // Platform: send plain text as before
+      fetchOptions.body = html;
+    }
+
+    fetch(saveEndpoint, fetchOptions)
+      .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(null, data);
+        }
+        resolve({ err: null, data });
+      })
+      .catch(err => {
+        clearTimeout(timeoutId);
+        console.error('Failed to save page:', err);
 
-  // Add timeout - abort if server doesn't respond within 12 seconds
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 12000);
-
-  // Check if running on Hyperclay Local - send JSON with both versions for platform sync
-  const isHyperclayLocal = window.location.hostname === 'localhost' ||
-                           window.location.hostname === '127.0.0.1';
-
-  const fetchOptions = {
-    method: 'POST',
-    credentials: 'include',
-    signal: controller.signal,
-    headers: { 'Page-URL': window.location.href }
-  };
-
-  if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
-    // Send JSON with both stripped content and full snapshot for platform live sync
-    fetchOptions.headers['Content-Type'] = 'application/json';
-    fetchOptions.body = JSON.stringify({
-      content: html,
-      snapshotHtml: window.__hyperclaySnapshotHtml
-    });
-    // Clear after use to avoid stale data
-    window.__hyperclaySnapshotHtml = null;
-  } else {
-    // Platform: send plain text as before
-    fetchOptions.body = html;
-  }
+        // Normalize timeout errors
+        const error = err.name === 'AbortError'
+          ? new Error('Server not responding')
+          : err;
 
-  fetch(saveEndpoint, fetchOptions)
-    .then(res => {
-      clearTimeout(timeoutId);
-      return res.json().then(data => {
-        if (!res.ok) {
-          throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+        if (typeof callback === 'function') {
+          callback(error);
         }
-        return data;
+        resolve({ err: error, data: null });
+      })
+      .finally(() => {
+        clearTimeout(timeoutId);
+        saveInProgress = false;
       });
-    })
-    .then(data => {
-      if (typeof callback === 'function') {
-        callback(null, data);
-      }
-    })
-    .catch(err => {
-      clearTimeout(timeoutId);
-      console.error('Failed to save page:', err);
-
-      // Normalize timeout errors
-      const error = err.name === 'AbortError'
-        ? new Error('Server not responding')
-        : err;
-
-      if (typeof callback === 'function') {
-        callback(error);
-      }
-    })
-    .finally(() => {
-      clearTimeout(timeoutId);
-      saveInProgress = false;
-    });
+  });
 }
 
 /**
  * Fetch HTML from a URL and save it to replace the current page.
  *
+ * Returns a Promise that resolves with {err, data} — same arguments
+ * passed to the callback. Promise never rejects.
+ *
  * @param {string} url - URL to fetch HTML from
  * @param {Function} callback - Called with (err, data) on completion
+ * @returns {Promise<{err: ?Error, data: ?{msg: string, msgType: string}}>}
  *
  * @example
+ * // Callback form (unchanged)
  * replacePageWith('/templates/blog.html', (err, data) => {
- *   if (err) {
- *     console.error('Failed:', err);
- *   } else {
- *     window.location.reload();
- *   }
+ *   if (err) console.error('Failed:', err);
+ *   else window.location.reload();
  * });
+ *
+ * @example
+ * // Promise form
+ * const {err, data} = await replacePageWith('/templates/blog.html');
+ * if (!err) window.location.reload();
  */
 export function replacePageWith(url, callback = () => {}) {
-  if (!isEditMode || saveInProgress) {
-    return;
-  }
-
-  fetch(url)
-    .then(res => res.text())
-    .then(html => {
-      saveHtml(html, (err, data) => {
+  return new Promise((resolve) => {
+    if (!isEditMode || saveInProgress) {
+      const data = {
+        msg: saveInProgress ? 'Save already in progress' : 'Not in edit mode',
+        msgType: 'skipped'
+      };
+      callback(null, data);
+      return resolve({ err: null, data });
+    }
+
+    fetch(url)
+      .then(res => res.text())
+      .then(html => {
+        saveHtml(html, (err, data) => {
+          if (typeof callback === 'function') {
+            callback(err, data);
+          }
+          resolve({ err: err || null, data: data || null });
+        });
+      })
+      .catch(err => {
+        console.error('Failed to fetch template:', err);
         if (typeof callback === 'function') {
-          callback(err, data);
+          callback(err);
         }
+        resolve({ err, data: null });
       });
-    })
-    .catch(err => {
-      console.error('Failed to fetch template:', err);
-      if (typeof callback === 'function') {
-        callback(err);
-      }
-    });
+  });
 }
 
 // =============================================================================

package/src/core/snapshot.js

@@ -78,8 +78,15 @@ export const beforeSave = onPrepareForSave;
  *
  * @returns {HTMLElement} Cloned document element with snapshot hooks applied
  */
+function clonePreventingOnclone(node) {
+  const prev = window.__preventOnclone;
+  window.__preventOnclone = true;
+  try { return node.cloneNode(true); }
+  finally { window.__preventOnclone = prev; }
+}
+
 export function captureSnapshot() {
-  const clone = document.documentElement.cloneNode(true);
+  const clone = clonePreventingOnclone(document.documentElement);
 
   for (const hook of snapshotHooks) {
     hook(clone);
@@ -196,7 +203,7 @@ export function captureForSaveAndComparison({ emitForSync = true } = {}) {
   }
 
   // Clone for comparison before stripping (cheaper than cloning live DOM)
-  const compareClone = clone.cloneNode(true);
+  const compareClone = clonePreventingOnclone(clone);
 
   // Save clone: strip [save-remove], then run hooks
   for (const el of clone.querySelectorAll('[save-remove]')) {

package/src/custom-attributes/onclone.js

@@ -13,8 +13,10 @@ function init() {
     const clonedNode = originalCloneNode.call(this, deep);
 
     if (clonedNode.nodeType === Node.ELEMENT_NODE) {
-      processOnclone(clonedNode);
-      clonedNode.querySelectorAll('[onclone]').forEach(processOnclone);
+      if (!window.__preventOnclone) {
+        processOnclone(clonedNode);
+        clonedNode.querySelectorAll('[onclone]').forEach(processOnclone);
+      }
 
       // Patch textareas: the persist module writes live values to data-value
       // on every keystroke (because writing textContent on a focused textarea

package/src/hyperclay.js

@@ -1,7 +1,7 @@
 /**
  * DO NOT EDIT THIS FILE DIRECTLY — it is generated from build/hyperclay.template.js
  *
- * HyperclayJS v1.26.0 - Minimal Browser-Native Loader
+ * HyperclayJS v1.26.2 - Minimal Browser-Native Loader
  *
  * Modules auto-init when imported (no separate init call needed).
  * Include `export-to-window` feature to export to window.hyperclay.

package/src/utilities/debounce.js

@@ -1,13 +1,22 @@
 // debounce.js
 function debounce(callback, delay) {
   let timeoutId;
+  let pendingResolvers = [];
 
   return function (...args) {
+    const ctx = this;
     clearTimeout(timeoutId);
 
-    timeoutId = setTimeout(() => {
-      callback.apply(this, args);
-    }, delay);
+    return new Promise((resolve) => {
+      pendingResolvers.push(resolve);
+
+      timeoutId = setTimeout(() => {
+        const resolvers = pendingResolvers;
+        pendingResolvers = [];
+        Promise.resolve(callback.apply(ctx, args))
+          .then(value => { for (const r of resolvers) r(value); });
+      }, delay);
+    });
   };
 }
 

package/src/utilities/throttle.js

@@ -1,22 +1,40 @@
 function throttle(callback, delay, executeFirst = true) {
   let lastCall = executeFirst ? 0 : Date.now();
   let timeoutId = null;
+  let pendingResolvers = [];
 
   return function (...args) {
+    const ctx = this;
     const now = Date.now();
     const remaining = delay - (now - lastCall);
 
-    if (remaining <= 0) {
-      clearTimeout(timeoutId);
-      lastCall = now;
-      return callback.apply(this, args);
-    } else if (!timeoutId) {
-      timeoutId = setTimeout(() => {
-        lastCall = Date.now();
+    return new Promise((resolve) => {
+      if (remaining <= 0) {
+        clearTimeout(timeoutId);
         timeoutId = null;
-        callback.apply(this, args);
-      }, remaining);
-    }
+        lastCall = now;
+
+        const resolvers = pendingResolvers.concat(resolve);
+        pendingResolvers = [];
+
+        Promise.resolve(callback.apply(ctx, args))
+          .then(value => { for (const r of resolvers) r(value); });
+      } else {
+        pendingResolvers.push(resolve);
+
+        if (!timeoutId) {
+          timeoutId = setTimeout(() => {
+            lastCall = Date.now();
+            timeoutId = null;
+            const resolvers = pendingResolvers;
+            pendingResolvers = [];
+
+            Promise.resolve(callback.apply(ctx, args))
+              .then(value => { for (const r of resolvers) r(value); });
+          }, remaining);
+        }
+      }
+    });
   };
 }