hyperclayjs 1.13.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 |
@@ -85,7 +85,7 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | dialogs | 7.7KB | ask(), consent(), tell(), snippet() dialog functions |
-| the-modal | 20.8KB | Full modal window creation system - window.theModal |
+| the-modal | 21KB | Full modal window creation system - window.theModal |
 | toast | 7.9KB | Success/error message notifications, toast(msg, msgType) |
 
 ### Utilities (Core utilities (often auto-included))
@@ -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 (~30.6KB)
+### Minimal (~40.6KB)
 Essential features for basic editing
 
-**Modules:** `save-core`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`
+**Modules:** `save-core`, `snapshot`, `save-system`, `edit-mode-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Standard (~49.1KB)
+### Standard (~60.1KB)
 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`
+**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 (~177.8KB)
+### Everything (~182.3KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperclayjs",
-  "version": "1.13.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/core/tailwindInject.js

@@ -5,9 +5,10 @@ function init() {
   const currentResource = cookie.get('currentResource');
   if (!currentResource) return;
 
-  const href = `/tailwindcss/${currentResource}`;
+  const href = `/tailwindcss/${currentResource}.css`;
   insertStyles(href, (link) => {
     link.setAttribute('onaftersave', 'cacheBust(this)');
+    link.setAttribute('mutations-ignore', '');
   });
 }
 

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.13.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.
@@ -73,11 +73,13 @@ const PRESETS = {
     "description": "Essential features for basic editing",
     "modules": [
       "save-core",
+      "snapshot",
       "save-system",
       "edit-mode-helpers",
       "toast",
       "save-toast",
-      "export-to-window"
+      "export-to-window",
+      "view-mode-excludes-edit-modules"
     ]
   },
   "standard": {
@@ -85,7 +87,9 @@ const PRESETS = {
     "description": "Standard feature set for most use cases",
     "modules": [
       "save-core",
+      "snapshot",
       "save-system",
+      "unsaved-warning",
       "edit-mode-helpers",
       "persist",
       "option-visibility",
@@ -93,7 +97,8 @@ const PRESETS = {
       "dom-helpers",
       "toast",
       "save-toast",
-      "export-to-window"
+      "export-to-window",
+      "view-mode-excludes-edit-modules"
     ]
   },
   "everything": {
@@ -140,7 +145,8 @@ const PRESETS = {
       "file-upload",
       "live-sync",
       "tailwind-inject",
-      "export-to-window"
+      "export-to-window",
+      "view-mode-excludes-edit-modules"
     ]
   }
 };

package/src/ui/theModal.js

@@ -166,8 +166,10 @@ const MicroModal = (() => {
     }
 
     removeEventListeners () {
-      this.modal.removeEventListener('touchstart', this.onClick)
-      this.modal.removeEventListener('click', this.onClick)
+      if (this.modal) {
+        this.modal.removeEventListener('touchstart', this.onClick)
+        this.modal.removeEventListener('click', this.onClick)
+      }
       document.removeEventListener('keydown', this.onKeydown)
     }
 
@@ -303,7 +305,9 @@ const MicroModal = (() => {
   }
 
   const close = targetModal => {
+    if (!activeModal) return
     targetModal ? activeModal.closeModalById(targetModal) : activeModal.closeModal()
+    activeModal = null
   }
 
   return { init, show, close }
@@ -364,6 +368,7 @@ const modalCss = `<style class="micromodal-css">
 
 .micromodal__container {
   position: relative;
+  max-width: 600px;
   box-sizing: border-box;
   overflow-y: auto;
   padding: 26px 40px 40px 40px;
@@ -465,7 +470,7 @@ const modalCss = `<style class="micromodal-css">
   background-color: #1D1F2F;
   color: #E5E7EB;
   font-family: inherit;
-  font-size: 16px;
+  font-size: inherit;
   font-weight: bold;
 }
 
@@ -495,7 +500,7 @@ const modalCss = `<style class="micromodal-css">
 
 .micromodal .snippet-code-block pre {
   color: white;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-family: var(--hyperclay-modal-code-font-family, var(--hyperclay-modal-font-family, monospace));
   font-size: 0.875rem;
   white-space: nowrap;
   margin: 0;
@@ -540,21 +545,21 @@ const modalCss = `<style class="micromodal-css">
 }
 
 .micromodal .micromodal__tell-title {
-  font-size: 20px;
+  font-size: var(--hyperclay-modal-title-font-size, 20px);
   font-weight: bold;
 }
 
 .micromodal .micromodal__tell-content {
-  font-size: 16px;
+  font-size: var(--hyperclay-modal-font-size, 16px);
   font-weight: normal;
 }
 
 @media (min-width: 640px) {
   .micromodal .micromodal__tell-title {
-    font-size: 22px;
+    font-size: var(--hyperclay-modal-title-font-size, 22px);
   }
   .micromodal .micromodal__tell-content {
-    font-size: 18px;
+    font-size: var(--hyperclay-modal-font-size, 18px);
   }
 }
 </style>`;

package/src/utilities/cacheBust.js

@@ -2,10 +2,11 @@
 // Cache-bust an element's href or src attribute by adding/updating a version query param
 
 function cacheBust(el) {
-  const attr = el.href !== undefined ? 'href' : 'src';
-  const url = new URL(el[attr], location.href);
+  const attr = el.hasAttribute('href') ? 'href' : 'src';
+  const currentValue = el.getAttribute(attr);
+  const url = new URL(currentValue, location.href);
   url.searchParams.set('v', Date.now());
-  el[attr] = url.href;
+  el.setAttribute(attr, url.href);
 }
 
 // Auto-export to window unless suppressed by loader