hyperclayjs 1.7.0 → 1.9.0

package/README.md

@@ -21,7 +21,7 @@ Destructure directly from the import:
 
 ```html
 <script type="module">
-  const { toast, savePage } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?preset=standard');
+  const { toast, savePage } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?preset=standard');
   toast('Hello!');
 </script>
 ```
@@ -30,7 +30,7 @@ Or with custom features:
 
 ```html
 <script type="module">
-  const { toast, ask } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/hyperclay.js?features=toast,dialogs');
+  const { toast, ask } = await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?features=toast,dialogs');
 </script>
 ```
 
@@ -57,38 +57,41 @@ 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 | 5.4KB | 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.3KB | Basic save function only - hyperclay.savePage() |
+| edit-mode-helpers | 7.5KB | Admin-only functionality: [edit-mode-input], [edit-mode-resource], [edit-mode-onclick] |
+| 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 |
-| dom-helpers | 5.7KB | el.nearest, el.val, el.text, el.exec, el.cycle |
-| event-attrs | 3.6KB | [onclickaway], [onclone], [onpagemutation], [onrender] |
+| 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 |
-| sortable | 2.8KB | Drag-drop sorting with [sortable], lazy-loads ~118KB Sortable.js in edit mode |
+| 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)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| dialogs | 8.4KB | ask(), consent(), tell(), snippet() dialog functions |
-| the-modal | 19.8KB | Full modal window creation system - window.theModal |
+| dialogs | 7.7KB | ask(), consent(), tell(), snippet() dialog functions |
+| the-modal | 21.8KB | Full modal window creation system - window.theModal |
 | toast | 7.7KB | Success/error message notifications, toast(msg, msgType) |
 
 ### Utilities (Core utilities (often auto-included))
 
 | 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) |
@@ -99,10 +102,10 @@ import 'hyperclayjs/presets/standard.js';
 
 | Module | Size | Description |
 |--------|------|-------------|
-| all-js | 14KB | Full DOM manipulation library |
+| 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 (~27.8KB)
+### Minimal (~30.4KB)
 Essential features for basic editing
 
 **Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
 
-### Standard (~45.5KB)
+### 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 (~150.2KB)
+### Everything (~176.5KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,39 +1,31 @@
 {
   "name": "hyperclayjs",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Modular JavaScript library for building interactive HTML applications with Hyperclay",
   "type": "module",
-  "main": "hyperclay.js",
-  "module": "hyperclay.js",
+  "main": "src/hyperclay.js",
+  "module": "src/hyperclay.js",
   "exports": {
     ".": {
-      "import": "./hyperclay.js",
-      "default": "./hyperclay.js"
+      "import": "./src/hyperclay.js",
+      "default": "./src/hyperclay.js"
     },
-    "./core/*": "./core/*.js",
-    "./custom-attributes/*": "./custom-attributes/*.js",
-    "./ui/*": "./ui/*.js",
-    "./utilities/*": "./utilities/*.js",
-    "./dom-utilities/*": "./dom-utilities/*.js",
-    "./string-utilities/*": "./string-utilities/*.js",
-    "./communication/*": "./communication/*.js",
-    "./vendor/*": "./vendor/*.js"
+    "./core/*": "./src/core/*.js",
+    "./custom-attributes/*": "./src/custom-attributes/*.js",
+    "./ui/*": "./src/ui/*.js",
+    "./utilities/*": "./src/utilities/*.js",
+    "./dom-utilities/*": "./src/dom-utilities/*.js",
+    "./string-utilities/*": "./src/string-utilities/*.js",
+    "./communication/*": "./src/communication/*.js",
+    "./vendor/*": "./src/vendor/*.js"
   },
   "files": [
-    "core",
-    "custom-attributes",
-    "ui",
-    "utilities",
-    "dom-utilities",
-    "string-utilities",
-    "communication",
-    "vendor",
-    "hyperclay.js",
-    "module-dependency-graph.json"
+    "src"
   ],
   "scripts": {
-    "dev": "npm run build && http-server -p 3535 -c-1 -o /index.html",
+    "dev": "npm run build && npm run build:website && http-server website -p 3535 -c-1 -o /index.html",
     "build": "npm run generate:deps && npm run build:loader && npm run build:readme && npm run build:load-jsdelivr && npm run build:index-url",
+    "build:website": "node scripts/build-website.js",
     "generate:deps": "node build/generate-dependency-graph.js",
     "build:loader": "node build/build-loader.js",
     "build:readme": "node build/generate-readme.js",
@@ -44,7 +36,7 @@
     "format": "prettier --write .",
     "release": "./scripts/release.sh",
     "prepublishOnly": "npm run build && npm test",
-    "postpublish": "test -n \"$SKIP_POSTPUBLISH\" || open http://127.0.0.1:3535/build/load-jsdelivr.html"
+    "postpublish": "test -n \"$SKIP_POSTPUBLISH\" || open http://127.0.0.1:3535/load-jsdelivr.html"
   },
   "repository": {
     "type": "git",

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/{communication → 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/adminContenteditable.js

@@ -0,0 +1,51 @@
+import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
+import onDomReady from "../dom-utilities/onDomReady.js";
+import {beforeSave} from "./savePage.js";
+
+export function disableContentEditableBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll('[edit-mode-contenteditable]').forEach(resource => {
+      const originalValue = resource.getAttribute("contenteditable");
+      resource.setAttribute("inert-contenteditable", originalValue);
+      resource.removeAttribute("contenteditable");
+    });
+  });
+}
+
+export function enableContentEditableForAdminOnPageLoad () {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableContentEditable();
+  });
+}
+
+// Runtime toggle functions
+export function enableContentEditable() {
+  document.querySelectorAll('[edit-mode-contenteditable]').forEach(el => {
+    let val = el.getAttribute("inert-contenteditable");
+    if (!["false", "plaintext-only"].includes(val)) val = "true";
+    el.setAttribute("contenteditable", val);
+    el.removeAttribute("inert-contenteditable");
+  });
+}
+
+export function disableContentEditable() {
+  document.querySelectorAll('[edit-mode-contenteditable]').forEach(el => {
+    const val = el.getAttribute("contenteditable") || "true";
+    el.setAttribute("inert-contenteditable", val);
+    el.removeAttribute("contenteditable");
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableContentEditableBeforeSave();
+  enableContentEditableForAdminOnPageLoad();
+}
+
+// Export to window
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.enableContentEditable = enableContentEditable;
+window.hyperclay.disableContentEditable = disableContentEditable;
+window.h = window.hyperclay;