hyperclayjs 1.8.0 → 1.9.0

package/README.md

@@ -57,24 +57,26 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
-| autosave | 1.1KB | Auto-save on DOM changes, unsaved changes warning |
+| autosave | 0.9KB | Auto-save on DOM changes |
 | edit-mode | 1.8KB | Toggle edit mode on hyperclay on/off |
 | edit-mode-helpers | 7.5KB | Admin-only functionality: [edit-mode-input], [edit-mode-resource], [edit-mode-onclick] |
-| option-visibility | 5.9KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
-| persist | 2.5KB | Persist input/select/textarea values to the DOM with [persist] attribute |
-| save-core | 6.5KB | Basic save function only - hyperclay.savePage() |
+| option-visibility | 5.3KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
+| persist | 2.4KB | Persist input/select/textarea values to the DOM with [persist] attribute |
+| save-core | 6.8KB | Basic save function only - hyperclay.savePage() |
 | save-system | 7.1KB | Manual save: keyboard shortcut (CMD+S), save button, change tracking |
 | save-toast | 0.9KB | Toast notifications for save events |
+| snapshot | 7.5KB | Source of truth for page state - captures DOM snapshots for save and sync |
+| unsaved-warning | 0.8KB | Warn before leaving page with unsaved changes |
 
 ### Custom Attributes (HTML enhancements)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| ajax-elements | 2.8KB | [ajax-form], [ajax-button] for async form submissions |
+| ajax-elements | 2.6KB | [ajax-form], [ajax-button] for async form submissions |
 | dom-helpers | 6.2KB | el.nearest, el.val, el.text, el.exec, el.cycle |
 | event-attrs | 4.1KB | [onclickaway], [onclone], [onpagemutation], [onrender] |
 | input-helpers | 1.2KB | [prevent-enter], [autosize] for textareas |
-| onaftersave | 1.2KB | [onaftersave] attribute - run JS when save status changes |
+| onaftersave | 1KB | [onaftersave] attribute - run JS when save status changes |
 | sortable | 3.4KB | Drag-drop sorting with [sortable], lazy-loads ~118KB Sortable.js in edit mode |
 
 ### UI Components (User interface elements)
@@ -89,6 +91,7 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
+| cache-bust | 0.6KB | Cache-bust href/src attributes |
 | cookie | 1.4KB | Cookie management (often auto-included) |
 | debounce | 0.4KB | Function debouncing |
 | mutation | 13KB | DOM mutation observation (often auto-included) |
@@ -102,7 +105,7 @@ import 'hyperclayjs/presets/standard.js';
 | all-js | 14.4KB | Full DOM manipulation library |
 | dom-ready | 0.4KB | DOM ready callback |
 | form-data | 2KB | Extract form data as an object |
-| style-injection | 1.1KB | Dynamic stylesheet injection |
+| style-injection | 1.9KB | Dynamic stylesheet injection |
 
 ### String Utilities (String manipulation helpers)
 
@@ -117,27 +120,28 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | file-upload | 10.7KB | File upload with progress |
-| send-message | 1.4KB | Message sending utility |
+| live-sync | 12KB | Real-time DOM sync across browsers and with file system |
+| send-message | 1.3KB | Message sending utility |
 
 ### Vendor Libraries (Third-party libraries)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| idiomorph | 8.2KB | Efficient DOM morphing library |
+| idiomorph | 8.3KB | Efficient DOM morphing library |
 
 ## Presets
 
-### Minimal (~30.1KB)
+### Minimal (~30.4KB)
 Essential features for basic editing
 
 **Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Standard (~48.8KB)
+### Standard (~48.4KB)
 Standard feature set for most use cases
 
 **Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Everything (~155.8KB)
+### Everything (~176.5KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

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

package/src/communication/live-sync.js

@@ -0,0 +1,396 @@
+/**
+ * live-sync.js — Real-time sync between admin users
+ *
+ * HOW IT WORKS:
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  1. LISTEN            snapshot-ready event from save    │
+ *   │                       (body with form values, no strip) │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  2. SEND               POST body to /live-sync/save     │
+ *   │                        (debounced, skip if unchanged)   │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  3. RECEIVE            SSE stream from server           │
+ *   │                        (other clients' changes)         │
+ *   └─────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  4. MORPH              Idiomorph to update DOM          │
+ *   │                        (preserves focus, input values)  │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * DEPENDS ON: Idiomorph (for intelligent DOM morphing)
+ * INTEGRATES WITH: snapshot.js (receives snapshot-ready events)
+ */
+
+class LiveSync {
+  constructor() {
+    this.sse = null;
+    this.currentFile = null;
+    this.lastHeadHash = null;
+    this.lastBodyHtml = null;
+    this.clientId = this.generateClientId();
+    this.debounceMs = 150;
+    this.debounceTimer = null;
+    this.isPaused = false;
+    this.isDestroyed = false;
+
+    // Store handler reference for cleanup
+    this._snapshotHandler = null;
+
+    // Callbacks
+    this.onConnect = null;
+    this.onDisconnect = null;
+    this.onUpdate = null;
+    this.onError = null;
+  }
+
+  /**
+   * Generate or retrieve a persistent client ID
+   */
+  generateClientId() {
+    let id = null;
+
+    try {
+      id = localStorage.getItem('livesync-client-id');
+    } catch (e) {
+      // localStorage might not be available
+    }
+
+    if (!id) {
+      id = Math.random().toString(36).slice(2, 11) + Date.now().toString(36);
+      try {
+        localStorage.setItem('livesync-client-id', id);
+      } catch (e) {
+        // That's okay
+      }
+    }
+
+    return id;
+  }
+
+  /**
+   * Start the LiveSync system
+   * Can be called after stop() to restart with a new file
+   */
+  start(file = null) {
+    // Reset destroyed flag to allow restart after stop()
+    this.isDestroyed = false;
+
+    // Prevent double-connect: clean up existing connection first
+    if (this.sse || this._snapshotHandler) {
+      this.cleanup();
+    }
+
+    this.currentFile = file || this.detectCurrentFile();
+
+    if (!this.currentFile) {
+      console.warn('[LiveSync] No file detected');
+      return;
+    }
+
+    // Reset state for new connection
+    this.lastHeadHash = null;
+    this.lastBodyHtml = null;
+
+    console.log('[LiveSync] Starting for:', this.currentFile);
+    this.connect();
+    this.listenForSnapshots();
+  }
+
+  /**
+   * Clean up resources without marking as destroyed
+   * Used internally by start() to prevent double-connect
+   */
+  cleanup() {
+    if (this.sse) {
+      this.sse.close();
+      this.sse = null;
+    }
+
+    if (this._snapshotHandler) {
+      document.removeEventListener('hyperclay:snapshot-ready', this._snapshotHandler);
+      this._snapshotHandler = null;
+    }
+
+    clearTimeout(this.debounceTimer);
+  }
+
+  /**
+   * Auto-detect the current site identifier from the URL
+   * Returns site ID without .html extension
+   *
+   * Handles:
+   * - /                  -> index
+   * - /about             -> about
+   * - /about.html        -> about
+   * - /about/            -> about/index
+   * - /pages/contact     -> pages/contact
+   * - /pages/contact/    -> pages/contact/index
+   */
+  detectCurrentFile() {
+    let pathname = window.location.pathname;
+
+    // Root path
+    if (pathname === '/') {
+      return 'index';
+    }
+
+    // Remove leading slash
+    pathname = pathname.replace(/^\//, '');
+
+    // Handle trailing slash -> directory index
+    if (pathname.endsWith('/')) {
+      return pathname + 'index';
+    }
+
+    // Remove .html extension if present
+    if (pathname.endsWith('.html')) {
+      return pathname.slice(0, -5);
+    }
+
+    // Already a site identifier
+    return pathname;
+  }
+
+  /**
+   * Connect to the SSE endpoint
+   * Uses native EventSource reconnection behavior
+   */
+  connect() {
+    if (this.isDestroyed) return;
+
+    const url = `/live-sync/stream?file=${encodeURIComponent(this.currentFile)}`;
+    this.sse = new EventSource(url);
+
+    this.sse.onopen = () => {
+      console.log('[LiveSync] Connected');
+      if (this.onConnect) this.onConnect();
+    };
+
+    this.sse.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+
+      // Handle error events from server
+      if (data.error) {
+        console.error('[LiveSync] Server error:', data.error);
+        if (this.onError) this.onError(new Error(data.error));
+        return;
+      }
+
+      const { body, headHash, sender } = data;
+
+      // Ignore own changes
+      if (sender === this.clientId) return;
+
+      // Guard against invalid body - never apply non-string
+      if (typeof body !== 'string') {
+        console.error('[LiveSync] Received invalid body (not a string), ignoring');
+        return;
+      }
+
+      // Check for head changes -> full reload
+      // Only compare when BOTH hashes exist (server must send headHash)
+      // Only set lastHeadHash when incoming hash is valid
+      if (headHash) {
+        if (this.lastHeadHash && headHash !== this.lastHeadHash) {
+          console.log('[LiveSync] Head changed, reloading');
+          location.reload();
+          return;
+        }
+        this.lastHeadHash = headHash;
+      }
+
+      console.log('[LiveSync] Received update from:', sender);
+      this.applyUpdate(body);
+      if (this.onUpdate) this.onUpdate({ body, sender });
+    };
+
+    // Native EventSource auto-reconnects on transient errors
+    // We just surface the status via callbacks
+    this.sse.onerror = () => {
+      if (this.sse.readyState === EventSource.CONNECTING) {
+        console.log('[LiveSync] Reconnecting...');
+      } else if (this.sse.readyState === EventSource.CLOSED) {
+        console.log('[LiveSync] Connection closed');
+        if (this.onError) this.onError(new Error('Connection closed'));
+      }
+      if (this.onDisconnect) this.onDisconnect();
+    };
+  }
+
+  /**
+   * Listen for snapshot-ready events from the save system.
+   * This replaces DOM observation — we sync when save happens.
+   */
+  listenForSnapshots() {
+    this._snapshotHandler = (event) => {
+      if (this.isPaused) return;
+
+      const { body } = event.detail;
+      if (!body) return;
+
+      this.sendBody(body);
+    };
+
+    document.addEventListener('hyperclay:snapshot-ready', this._snapshotHandler);
+  }
+
+  /**
+   * Send body HTML to the server (debounced)
+   * Only updates lastBodyHtml after successful save
+   */
+  sendBody(body) {
+    clearTimeout(this.debounceTimer);
+
+    this.debounceTimer = setTimeout(() => {
+      // Skip if unchanged
+      if (body === this.lastBodyHtml) return;
+
+      console.log('[LiveSync] Sending update');
+
+      // Compute head hash to send to server (for hosted mode)
+      const headHash = this.computeHeadHash();
+      this.lastHeadHash = headHash; // Track local head changes
+
+      fetch('/live-sync/save', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          file: this.currentFile,
+          body: body,
+          sender: this.clientId,
+          headHash: headHash
+        })
+      }).then(response => {
+        if (response.ok) {
+          // Only update lastBodyHtml after successful save
+          this.lastBodyHtml = body;
+        } else {
+          // Log non-OK responses but don't suppress future sends
+          console.warn('[LiveSync] Save returned status:', response.status);
+        }
+      }).catch(err => {
+        // Network error - don't update lastBodyHtml so next mutation will retry
+        console.error('[LiveSync] Save failed:', err);
+        if (this.onError) this.onError(err);
+      });
+    }, this.debounceMs);
+  }
+
+  /**
+   * Compute MD5-like hash of head content (first 8 hex chars)
+   * Uses a simple string hash since we don't have crypto in browser
+   */
+  computeHeadHash() {
+    const head = document.head?.innerHTML;
+    if (!head) return null;
+
+    // Simple hash function (djb2)
+    let hash = 5381;
+    for (let i = 0; i < head.length; i++) {
+      hash = ((hash << 5) + hash) + head.charCodeAt(i);
+      hash = hash & hash; // Convert to 32bit integer
+    }
+    // Convert to hex and take first 8 chars
+    return Math.abs(hash).toString(16).padStart(8, '0').slice(0, 8);
+  }
+
+  /**
+   * Apply an update received from the server
+   * Guards against non-string values
+   */
+  applyUpdate(bodyHtml) {
+    // Guard against non-string values
+    if (typeof bodyHtml !== 'string') {
+      console.error('[LiveSync] applyUpdate called with non-string value, ignoring');
+      return;
+    }
+
+    this.isPaused = true;
+    this.lastBodyHtml = bodyHtml;
+
+    try {
+      const temp = document.createElement('div');
+      temp.innerHTML = bodyHtml;
+
+      // Use Idiomorph if available
+      const morphFn = window.Idiomorph?.morph;
+
+      if (morphFn) {
+        morphFn(document.body, temp, {
+          morphStyle: 'innerHTML',
+          ignoreActiveValue: true
+        });
+      } else {
+        // Fallback to innerHTML
+        console.warn('[LiveSync] Idiomorph not available, using innerHTML fallback');
+        document.body.innerHTML = bodyHtml;
+      }
+
+      this.rehydrateFormState(document.body);
+    } finally {
+      this.isPaused = false;
+    }
+  }
+
+  /**
+   * Sync form control attributes to properties after DOM morph
+   */
+  rehydrateFormState(container) {
+    const focused = document.activeElement;
+
+    // Text inputs and textareas
+    container.querySelectorAll('input[value], textarea[value]').forEach(el => {
+      if (el === focused) return;
+      el.value = el.getAttribute('value') || '';
+    });
+
+    // Checkboxes and radios
+    container.querySelectorAll('input[type="checkbox"], input[type="radio"]').forEach(el => {
+      if (el === focused) return;
+      el.checked = el.hasAttribute('checked');
+    });
+
+    // Select dropdowns
+    container.querySelectorAll('select').forEach(select => {
+      if (select === focused) return;
+      select.querySelectorAll('option').forEach(opt => {
+        opt.selected = opt.hasAttribute('selected');
+      });
+    });
+  }
+
+  /**
+   * Stop LiveSync and clean up resources
+   * Can call start() again to restart
+   */
+  stop() {
+    this.cleanup();
+    this.isDestroyed = true;
+    console.log('[LiveSync] Stopped');
+  }
+}
+
+// Singleton instance
+const liveSync = new LiveSync();
+
+// Auto-initialize when DOM is ready
+if (typeof window !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => liveSync.start());
+  } else {
+    liveSync.start();
+  }
+}
+
+// Export for hyperclayjs module system
+export { liveSync };
+export default liveSync;

package/src/communication/sendMessage.js

@@ -5,17 +5,11 @@ import toast from "../ui/toast.js";
 function sendMessage(eventOrObj, successMessage = "Successfully sent", callback) {
   let form;
   let data;
-  
+
   if (eventOrObj instanceof Event) {
     eventOrObj.preventDefault();
     form = eventOrObj.target.closest('form');
-
-    if (!form) {
-      toast('No form found for this element', 'error');
-      return Promise.reject('No form found');
-    }
-
-    data = getDataFromForm(form);
+    data = form ? getDataFromForm(form) : {};
   } else {
     data = eventOrObj;
     if (this?.closest) {

package/src/core/autosave.js

@@ -2,18 +2,17 @@
  * Auto-save system for Hyperclay
  *
  * Automatically saves page on DOM changes with throttling.
- * Warns before leaving page with unsaved changes.
  *
  * Requires the 'save-system' module to be loaded first.
- * For toast notifications, also load the 'save-toast' module.
+ *
+ * Recommended companion modules:
+ *   - 'unsaved-warning' - Warn before leaving with unsaved changes (required for beforeunload)
+ *   - 'save-toast' - Show toast notifications on save events
  */
 
 import Mutation from "../utilities/mutation.js";
-import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
-import {
-  savePageThrottled,
-  getUnsavedChanges
-} from "./savePage.js";
+import { isEditMode } from "./isAdminOfCurrentResource.js";
+import { savePageThrottled } from "./savePage.js";
 
 /**
  * Initialize auto-save on DOM changes
@@ -28,16 +27,6 @@ function initSavePageOnChange() {
   });
 }
 
-/**
- * Warn before leaving page with unsaved changes
- */
-window.addEventListener('beforeunload', (event) => {
-  if (getUnsavedChanges() && isOwner) {
-    event.preventDefault();
-    event.returnValue = '';
-  }
-});
-
 function init() {
   if (!isEditMode) return;
   initSavePageOnChange();

package/src/core/enablePersistentFormInputValues.js

@@ -1,57 +1,52 @@
-import { beforeSave } from './savePage.js';
+import { onSnapshot } from './snapshot.js';
 
 // <input type="checkbox" persist>
 export default function enablePersistentFormInputValues(filterBySelector = "[persist]") {
-  const selector = `input${filterBySelector}:not([type="password"]):not([type="hidden"]):not([type="file"]), textarea${filterBySelector}, select${filterBySelector}`;
-  
-  document.addEventListener('input', (event) => {
-    const elem = event.target;
-    if (elem.matches(selector) && !(elem.type === 'checkbox' || elem.type === 'radio')) {
-      if (elem.tagName.toLowerCase() === 'textarea') {
-        // Store in value attribute instead of textContent to preserve cursor position
-        elem.setAttribute('value', elem.value);
-      } else {
-        elem.setAttribute('value', elem.value);
-      }
-    }
-  });
+  const inputSelector = `input${filterBySelector}:not([type="password"]):not([type="hidden"]):not([type="file"])`;
+  const textareaSelector = `textarea${filterBySelector}`;
+  const selectSelector = `select${filterBySelector}`;
 
-  document.addEventListener('change', (event) => {
-    const elem = event.target;
-    if (elem.matches(selector)) {
-      // Handle checkboxes and radios
-      if (elem.type === 'checkbox' || elem.type === 'radio') {
-        if (elem.checked) {
-          elem.setAttribute('checked', '');
+  // Use onSnapshot so form values are synced for both save AND live-sync
+  onSnapshot((doc) => {
+    // Sync text inputs
+    const liveInputs = document.querySelectorAll(inputSelector);
+    const clonedInputs = doc.querySelectorAll(inputSelector);
+    clonedInputs.forEach((cloned, i) => {
+      const live = liveInputs[i];
+      if (live.type === 'checkbox' || live.type === 'radio') {
+        if (live.checked) {
+          cloned.setAttribute('checked', '');
         } else {
-          elem.removeAttribute('checked');
+          cloned.removeAttribute('checked');
         }
+      } else {
+        cloned.setAttribute('value', live.value);
       }
-      // Handle select elements
-      else if (elem.tagName.toLowerCase() === 'select') {
-        // Remove selected from all options
-        const options = elem.querySelectorAll('option');
-        options.forEach(option => option.removeAttribute('selected'));
+    });
 
-        // Add selected to currently selected option(s)
-        if (elem.multiple) {
-          const selectedOptions = elem.selectedOptions;
-          Array.from(selectedOptions).forEach(option => {
-            option.setAttribute('selected', '');
-          });
-        } else if (elem.selectedIndex >= 0) {
-          options[elem.selectedIndex].setAttribute('selected', '');
-        }
-      }
-    }
-  });
+    // Sync textareas
+    const liveTextareas = document.querySelectorAll(textareaSelector);
+    const clonedTextareas = doc.querySelectorAll(textareaSelector);
+    clonedTextareas.forEach((cloned, i) => {
+      cloned.textContent = liveTextareas[i].value;
+    });
 
-  // Before save, transfer value attribute to textContent for textareas
-  beforeSave((doc) => {
-    const textareas = doc.querySelectorAll('textarea[value]');
-    textareas.forEach(textarea => {
-      textarea.textContent = textarea.getAttribute('value');
-      textarea.removeAttribute('value');
+    // Sync selects
+    const liveSelects = document.querySelectorAll(selectSelector);
+    const clonedSelects = doc.querySelectorAll(selectSelector);
+    clonedSelects.forEach((cloned, i) => {
+      const live = liveSelects[i];
+      const clonedOptions = cloned.querySelectorAll('option');
+      clonedOptions.forEach(opt => opt.removeAttribute('selected'));
+
+      if (live.multiple) {
+        Array.from(live.selectedOptions).forEach(opt => {
+          const idx = Array.from(live.options).indexOf(opt);
+          if (clonedOptions[idx]) clonedOptions[idx].setAttribute('selected', '');
+        });
+      } else if (live.selectedIndex >= 0 && clonedOptions[live.selectedIndex]) {
+        clonedOptions[live.selectedIndex].setAttribute('selected', '');
+      }
     });
   });
 }