hyperclayjs 1.14.0 → 1.14.1

package/README.md

@@ -60,10 +60,10 @@ import 'hyperclayjs/presets/standard.js';
 | 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.3KB | Dynamic show/hide based on ancestor state with option:attribute="value" |
+| option-visibility | 5.5KB | 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 | CMD+S, [trigger-save] button, savestatus attribute |
+| save-system | 9.6KB | CMD+S, [trigger-save] button, savestatus attribute |
 | 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 |
 | tailwind-inject | 0.4KB | Injects tailwind CSS link with cache-bust on save |
@@ -106,7 +106,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 | 2.4KB | Dynamic stylesheet injection |
+| style-injection | 4KB | Dynamic stylesheet injection |
 
 ### String Utilities (String manipulation helpers)
 
@@ -132,17 +132,17 @@ import 'hyperclayjs/presets/standard.js';
 
 ## Presets
 
-### Minimal (~38.1KB)
+### Minimal (~40.6KB)
 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 (~57.4KB)
+### Standard (~60.1KB)
 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 (~178KB)
+### Everything (~182.3KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

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

package/src/core/optionVisibility.js

@@ -118,7 +118,11 @@ const optionVisibility = {
     try {
       const attributes = this.findOptionAttributes();
       const css = this.generateCSS(attributes);
-      insertStyles(STYLE_NAME, css);
+      // mutations-ignore: This style tag is regenerated on load. Without this,
+      // the mutation observer would detect it as a change, delaying the settled signal.
+      insertStyles(STYLE_NAME, css, (style) => {
+        style.setAttribute('mutations-ignore', '');
+      });
       this.log(`Generated ${attributes.length} rules`);
     } catch (error) {
       console.error('[OptionVisibility:Layer] Error generating rules:', error);

package/src/core/savePage.js

@@ -11,6 +11,7 @@
  */
 
 import throttle from "../utilities/throttle.js";
+import Mutation from "../utilities/mutation.js";
 import { isEditMode, isOwner } from "./isAdminOfCurrentResource.js";
 import {
   savePage as savePageCore,
@@ -19,6 +20,11 @@ import {
   beforeSave
 } from "./savePageCore.js";
 
+// Reset savestatus to 'saved' in snapshots (each module cleans up its own attrs)
+beforeSave(clone => {
+  clone.setAttribute('savestatus', 'saved');
+});
+
 // ============================================
 // SAVE STATE MANAGEMENT
 // ============================================
@@ -94,17 +100,6 @@ export function setUnsavedChanges(val) { unsavedChanges = val; }
 export function getLastSavedContents() { return lastSavedContents; }
 export function setLastSavedContents(val) { lastSavedContents = val; }
 
-// Initialize lastSavedContents on page load to match what's on disk
-// This prevents unnecessary save attempts when content hasn't changed
-document.addEventListener('DOMContentLoaded', () => {
-  if (isEditMode) {
-    // Capture initial state immediately for comparison
-    lastSavedContents = getPageContents();
-    // Set initial save status to 'saved'
-    document.documentElement.setAttribute('savestatus', 'saved');
-  }
-});
-
 /**
  * Save the current page with change detection and state management
  *
@@ -185,14 +180,87 @@ const throttledSave = throttle(savePage, 1200);
 // Baseline for autosave comparison
 let baselineContents = '';
 
-// Capture baseline after setup mutations settle
-document.addEventListener('DOMContentLoaded', () => {
-  if (isEditMode) {
-    setTimeout(() => {
-      baselineContents = getPageContents();
-    }, 1500);
-  }
-});
+// ============================================
+// BASELINE CAPTURE (Settled Signal)
+// ============================================
+//
+// WHY SETTLED SIGNAL:
+// Modules run on load and mutate the DOM (add styles, modify attributes).
+// A fixed delay (e.g., 1500ms) is arbitrary and either too short (misses slow
+// mutations) or too long (delays baseline). Instead, we wait for mutations to
+// stop, meaning all modules have finished their setup work.
+//
+// WHY IMMEDIATE + CONDITIONAL UPDATE:
+// We set baseline immediately as a safety net. If the user edits or saves
+// before settle completes, we don't overwrite their work. The settled snapshot
+// only replaces baseline if nothing changed (lastSavedContents === immediateContents).
+
+const SETTLE_MS = 500;        // Wait for no mutations for this long
+const MAX_SETTLE_MS = 3000;   // Max time to wait before forcing capture
+
+function initBaselineCapture() {
+  if (!isEditMode) return;
+
+  let userEdited = false;
+  let settled = false;
+  let unsubscribeMutation = null;
+
+  // Take immediate snapshot and set as baseline right away
+  // This ensures saves during settle window work correctly
+  const immediateContents = getPageContents();
+  lastSavedContents = immediateContents;
+  baselineContents = immediateContents;
+
+  // Track user edits to avoid overwriting real changes
+  const userEditEvents = ['input', 'change', 'paste'];
+  const markUserEdited = (e) => {
+    const target = e.target;
+    const isEditable = target.isContentEditable ||
+                       target.tagName === 'INPUT' ||
+                       target.tagName === 'TEXTAREA' ||
+                       target.tagName === 'SELECT';
+    if (isEditable) userEdited = true;
+  };
+  userEditEvents.forEach(evt => document.addEventListener(evt, markUserEdited, true));
+
+  // Called when mutations settle OR max timeout reached
+  const captureBaseline = () => {
+    if (settled) return;
+    settled = true;
+
+    // Cleanup listeners
+    if (unsubscribeMutation) unsubscribeMutation();
+    userEditEvents.forEach(evt => document.removeEventListener(evt, markUserEdited, true));
+
+    // Only update if no user edits AND no saves occurred during settle
+    // (if a save happened, lastSavedContents would differ from immediateContents)
+    if (!userEdited && lastSavedContents === immediateContents) {
+      const contents = getPageContents();
+      lastSavedContents = contents;
+      baselineContents = contents;
+    }
+
+    document.documentElement.setAttribute('savestatus', 'saved');
+  };
+
+  // Start settle observer - fires when no mutations for SETTLE_MS
+  unsubscribeMutation = Mutation.onAnyChange(
+    { debounce: SETTLE_MS, omitChangeDetails: true },
+    captureBaseline
+  );
+
+  // Max timeout fallback
+  setTimeout(() => {
+    if (!settled) captureBaseline();
+  }, MAX_SETTLE_MS);
+}
+
+// Run when DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initBaselineCapture);
+} else {
+  initBaselineCapture();
+}
 
 /**
  * Save the page with throttling, for use with auto-save

package/src/dom-utilities/insertStyleTag.js

@@ -2,10 +2,20 @@
  * Insert styles into the document (inline CSS or external stylesheet).
  *
  * With a persistent DOM (i.e. hyperclay), we need a way to update styles.
- * This function always inserts the new styles first, then removes any
- * duplicates. This ensures:
- *   - No flickering: new styles are applied before old ones are removed
- *   - Always upgrades: we default to the new styles/approach
+ * This function reuses existing elements when possible:
+ *   - Inline styles: matches by data-name, reuses if content matches
+ *   - External stylesheets: matches by normalized full URL path
+ *
+ * This ensures:
+ *   - No DOM churn: existing elements are reused when content/path matches
+ *   - No duplicates: removes any duplicate style/link elements
+ *   - Callback always runs: attributes can be updated on existing elements
+ *
+ * WHY REUSE IN-PLACE:
+ * In a persistent DOM (hyperclay), removing and re-adding elements changes their
+ * position and surrounding whitespace. This causes snapshot diffs even when content
+ * is identical, triggering false "unsaved changes" warnings. Reusing existing
+ * elements preserves DOM structure for stable snapshots.
  *
  * Usage:
  *   insertStyles('/path/to/file.css')                    // External stylesheet
@@ -18,15 +28,33 @@ function insertStyles(nameOrHref, cssOrCallback, callback) {
     // Inline style: insertStyles('my-styles', '.foo { ... }', optionalCallback)
     const name = nameOrHref;
     const css = cssOrCallback;
-    const oldStyles = document.querySelectorAll(`style[data-name="${name}"]`);
+    const existingStyles = [...document.querySelectorAll(`style[data-name="${name}"]`)];
+
+    // If exact match exists, just update attributes via callback and return it
+    const exactMatch = existingStyles.find(el => el.textContent === css);
+    if (exactMatch) {
+      if (callback) callback(exactMatch);
+      // Remove any duplicates
+      existingStyles.filter(el => el !== exactMatch).forEach(el => el.remove());
+      return exactMatch;
+    }
 
-    const style = document.createElement('style');
-    style.dataset.name = name;
-    style.textContent = css;
-    if (callback) callback(style);
-    document.head.appendChild(style);
+    // Update first existing style in-place, or create new one
+    let style;
+    if (existingStyles.length > 0) {
+      style = existingStyles[0];
+      style.textContent = css;
+      if (callback) callback(style);
+      // Remove duplicates
+      existingStyles.slice(1).forEach(el => el.remove());
+    } else {
+      style = document.createElement('style');
+      style.dataset.name = name;
+      style.textContent = css;
+      if (callback) callback(style);
+      document.head.appendChild(style);
+    }
 
-    oldStyles.forEach(el => el.remove());
     return style;
   }
 
@@ -34,25 +62,35 @@ function insertStyles(nameOrHref, cssOrCallback, callback) {
   const href = nameOrHref;
   const cb = typeof cssOrCallback === 'function' ? cssOrCallback : undefined;
 
-  let identifier;
-  try {
-    const url = new URL(href, window.location.href);
-    identifier = url.pathname.split('/').pop();
-  } catch (e) {
-    identifier = href;
-  }
+  // Normalize href to full URL for comparison
+  const normalizedHref = new URL(href, window.location.href).href;
+
+  // Find all links with matching normalized path
+  const existingLinks = [...document.querySelectorAll('link[rel="stylesheet"]')]
+    .filter(el => {
+      try {
+        return new URL(el.getAttribute('href'), window.location.href).href === normalizedHref;
+      } catch {
+        return false;
+      }
+    });
 
-  const oldLinks = document.querySelectorAll(
-    `link[href="${href}"], link[href*="${identifier}"]`
-  );
+  // If match exists, just update attributes via callback and return it
+  if (existingLinks.length > 0) {
+    const link = existingLinks[0];
+    if (cb) cb(link);
+    // Remove any duplicates
+    existingLinks.slice(1).forEach(el => el.remove());
+    return link;
+  }
 
+  // Create new link element
   const link = document.createElement('link');
   link.rel = 'stylesheet';
   link.href = href;
   if (cb) cb(link);
   document.head.appendChild(link);
 
-  oldLinks.forEach(el => el.remove());
   return link;
 }
 

package/src/hyperclay.js

@@ -1,5 +1,5 @@
 /**
- * HyperclayJS v1.14.0 - Minimal Browser-Native Loader
+ * HyperclayJS v1.14.1 - Minimal Browser-Native Loader
  *
  * Modules auto-init when imported (no separate init call needed).
  * Include `export-to-window` feature to export to window.hyperclay.