hyperclayjs 1.29.1 → 1.31.0

package/README.md

@@ -44,11 +44,16 @@ npm install hyperclayjs
 
 ```javascript
 // Import specific modules
-import { savePage } from 'hyperclayjs/core/savePage.js';
-import toast from 'hyperclayjs/ui/toast.js';
+import { savePage } from 'hyperclayjs/core/savePage';
+import toast from 'hyperclayjs/ui/toast';
+```
+
+To load a full preset, use the CDN loader with `?preset=standard`:
 
-// Or use presets
-import 'hyperclayjs/presets/standard.js';
+```html
+<script type="module">
+  await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?preset=standard');
+</script>
 ```
 
 ## Available Modules
@@ -65,7 +70,7 @@ import 'hyperclayjs/presets/standard.js';
 | 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 | 11.5KB | Source of truth for page state - captures DOM snapshots for save and sync |
+| snapshot | 11.9KB | 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)
@@ -87,6 +92,7 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | dialogs | 8.5KB | ask(), consent(), tell(), snippet() dialog functions |
+| quickcrop | 16.8KB | Image-crop modal for upload flows - quickcrop(file) returns a cropped Blob; uses themodal when available |
 | the-modal | 23KB | Full modal window creation system - window.theModal |
 | toast | 15.8KB | Success/error message notifications, toast(msg, msgType) |
 
@@ -97,7 +103,7 @@ import 'hyperclayjs/presets/standard.js';
 | cache-bust | 0.6KB | Cache-bust href/src attributes |
 | cookie | 1.4KB | Cookie management (often auto-included) |
 | debounce | 0.7KB | Function debouncing |
-| mutation | 15.6KB | DOM mutation observation (often auto-included) |
+| mutation | 16.4KB | DOM mutation observation (often auto-included) |
 | nearest | 3.4KB | Find nearest elements (often auto-included) |
 | throttle | 1.3KB | Function throttling |
 
@@ -123,29 +129,46 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | file-upload | 11.3KB | File upload with progress |
-| live-sync | 25.3KB | Real-time DOM sync across browsers |
+| live-sync | 25.9KB | Real-time DOM sync across browsers |
 | send-message | 1.3KB | Message sending utility |
 
+### Data & Undo (Page data and undo history)
+
+| Module | Size | Description |
+|--------|------|-------------|
+| data | 0.5KB | Read/write structured data from the DOM via named rules tags — window.hyperclay.extractData() / applyData(). Backs the /_/api endpoint shape. |
+| undo | 0.8KB | DOM-state undo/redo via MutationObserver inverse-op replay. Cmd+Z works out of the box; integrates with hypercms via window.hyperclay.undo. |
+
 ### Vendor Libraries (Third-party libraries)
 
 | Module | Size | Description |
 |--------|------|-------------|
 | hyper-morph | 18.8KB | DOM morphing with content-based element matching |
-| hypercms | 72.4KB | Live edit-in-place CMS sidebar driven by a hyper-html-api rules tag. Pairs with [sortable] and [hyper-morph]. |
+| hypercms | 127KB | Live edit-in-place CMS sidebar driven by a hyper-html-api rules tag. Pairs with [sortable] and [hyper-morph]. |
 
 ## Presets
 
-### Minimal (~62.3KB)
+### Minimal (~62.7KB)
 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 (~89.2KB)
+### Standard (~90.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`
+**Modules:** `save-core`, `snapshot`, `save-system`, `unsaved-warning`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `data`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
+
+### CMS (~204.7KB)
+Visual CMS editing for rules-tag pages: hypercms sidebar, undo, drag-reorder, save
+
+**Modules:** `save-core`, `snapshot`, `save-system`, `unsaved-warning`, `toast`, `save-toast`, `mutation`, `hypercms`, `sortable`, `undo`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Everything (~323.5KB)
+### Smooth Sailing (~350.5KB)
+Everything, without gotchas
+
+**Modules:** `save-core`, `save-system`, `unsaved-warning`, `save-toast`, `edit-mode-helpers`, `persist`, `snapshot`, `option-visibility`, `edit-mode`, `event-attrs`, `ajax-elements`, `sortable`, `movable`, `dom-helpers`, `input-helpers`, `onaftersave`, `save-freeze`, `dialogs`, `quickcrop`, `toast`, `the-modal`, `mutation`, `nearest`, `cookie`, `throttle`, `debounce`, `dom-ready`, `window-load`, `all-js`, `style-injection`, `form-data`, `hypercms`, `undo`, `data`, `slugify`, `copy-to-clipboard`, `query-params`, `behavior-collector`, `send-message`, `file-upload`, `refetch-on-save`, `export-to-window`, `view-mode-excludes-edit-modules`
+
+### Everything (~397.2KB)
 All available features
 
 Includes all available modules across all categories.
@@ -194,17 +217,17 @@ The configurator shows:
 
 ```
 hyperclayjs/
-├── hyperclay.js              # Self-detecting module loader
-├── core/                     # Core hyperclay features
-├── custom-attributes/        # HTML attribute enhancements
-├── ui/                       # UI components (toast, modals, prompts)
-├── utilities/                # General utilities (mutation, cookie, etc.)
-├── dom-utilities/            # DOM manipulation helpers
-├── string-utilities/         # String manipulation tools
-├── communication/            # File upload and messaging
-├── vendor/                   # Third-party libraries (Sortable.js, etc.)
+├── src/hyperclay.js          # Self-detecting module loader
+├── src/core/                 # Core hyperclay features
+├── src/custom-attributes/    # HTML attribute enhancements
+├── src/ui/                   # UI components (toast, modals, prompts)
+├── src/utilities/            # General utilities (mutation, cookie, etc.)
+├── src/dom-utilities/        # DOM manipulation helpers
+├── src/string-utilities/     # String manipulation tools
+├── src/communication/        # File upload and messaging
+├── src/vendor/               # Third-party libraries (Sortable.js, etc.)
 ├── scripts/                  # Build and generation scripts
-└── starter-kit-configurator.html  # Interactive configurator
+└── website/config.html       # Interactive configurator
 ```
 
 ### Setup
@@ -244,10 +267,10 @@ The configurator dynamically loads this file to always show accurate information
 
 ## Browser Support
 
-- Chrome 89+
-- Firefox 89+
-- Safari 15.4+
-- Edge 89+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
 
 The loader uses ES modules with top-level await. Use `await import()` to ensure modules finish loading before your code runs.
 
@@ -266,6 +289,11 @@ hyperclay.initHyperclaySaveButton(); // Looks for [trigger-save]
 hyperclay.initSaveKeyboardShortcut(); // CMD/CTRL+S
 ```
 
+Any element with the `trigger-save` attribute saves the page on click. For
+viewers who can't save (not the owner / not in edit mode), the loader shows a
+toast instead — "You're not the owner, changes are local only" — even on pages
+that exclude the save modules via `view-mode-excludes-edit-modules`.
+
 ### Toast Notifications
 
 ```javascript
@@ -352,7 +380,7 @@ myFeature();
 <script src="/public/js/hyperclay.js?preset=standard" type="module"></script>
 
 <!-- Or specific features -->
-<script src="/public/js/hyperclay.js?features=save,edit-mode-helpers,toast" type="module"></script>
+<script src="/public/js/hyperclay.js?features=save-core,edit-mode-helpers,toast" type="module"></script>
 ```
 
 ## Contributing

package/package.json

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

package/src/communication/live-sync.js

@@ -10,7 +10,7 @@
  *                              │
  *                              ▼
  *   ┌─────────────────────────────────────────────────────────┐
- *   │  2. SEND               POST html to /live-sync/save     │
+ *   │  2. SEND               POST html to /_/live-sync/save   │
  *   │                        (debounced, skip if unchanged)   │
  *   └─────────────────────────────────────────────────────────┘
  *                              │
@@ -343,7 +343,7 @@ class LiveSync {
     if (this.isDestroyed) return;
 
     const pageUrl = encodeURIComponent(window.location.href);
-    const url = `/live-sync/stream?page-url=${pageUrl}`;
+    const url = `/_/live-sync/stream?page-url=${pageUrl}`;
     this.sse = new EventSource(url);
 
     this.sse.onopen = () => {
@@ -457,7 +457,7 @@ class LiveSync {
 
       this._log(`Sending update (HTML length: ${html.length}, lastHtml length: ${this.lastHtml?.length || 0})`);
 
-      fetch('/live-sync/save', {
+      fetch('/_/live-sync/save', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'Page-URL': window.location.href },
         body: JSON.stringify({
@@ -646,6 +646,17 @@ class LiveSync {
       // receive time (in onmessage) so the staleness check covers own-save
       // echoes even when they don't reach this point.
       this.lastHtml = html;
+
+      // Announce that a remote morph just landed, so document-level listeners
+      // that are deaf to Mutation.pause (e.g. the hypercms form panel) can
+      // re-sync. Fires only on a successful apply, and only for genuine remote
+      // morphs — own-sender and stale-seq echoes are filtered upstream in
+      // onmessage before applyUpdate is ever called. Covers every SSE morph
+      // source (peer edit, version restore, body-swap) since they all funnel
+      // through this single choke point.
+      document.dispatchEvent(new CustomEvent('hyperclay:livesync-applied', {
+        detail: { seq }
+      }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
       Mutation.resume();

package/src/communication/sendMessage.js

@@ -19,7 +19,7 @@ function sendMessage(eventOrObj, successMessage = "Successfully sent", callback)
 
   data.behaviorData = behaviorCollector.getData();
 
-  return fetch("/message", {
+  return fetch("/_/message", {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(data)

package/src/communication/uploadFile.js

@@ -208,7 +208,7 @@ function createFileFromData(fileName, fileBody, onComplete = () => {}) {
 
 function uploadFileData(fileName, fileBody, progressCallback, extraData = {}) {
   const xhr = new XMLHttpRequest();
-  xhr.open("POST", "/upload", true);
+  xhr.open("POST", "/_/upload", true);
   xhr.setRequestHeader("Content-Type", "application/json");
   xhr.setRequestHeader("Page-URL", window.location.href);
 

package/src/core/savePageCore.js

@@ -23,7 +23,7 @@ import {
 // =============================================================================
 
 let saveInProgress = false;
-const saveEndpoint = '/save';
+const saveEndpoint = '/_/save';
 
 /**
  * Check if a save is currently in progress.

package/src/core/snapshot.js

@@ -36,6 +36,8 @@
  *   └─────────────────────────┘
  */
 
+import { stripExtensionNoise } from '../utilities/extension-noise.js';
+
 // =============================================================================
 // HOOK REGISTRIES
 // =============================================================================
@@ -109,6 +111,11 @@ export function captureSnapshot() {
     el.remove();
   }
 
+  // Browser-extension noise (password-manager menus, Grammarly overlays, and
+  // marker attributes on real inputs) is not page content. Drop it from every
+  // snapshot so it never reaches a save, a comparison, or a live-sync broadcast.
+  stripExtensionNoise(clone);
+
   return clone;
 }
 

package/src/data.js

@@ -0,0 +1,10 @@
+// Re-exports the vendored hyper-html-api data sugar as window.hyperclay
+// .extractData / .applyData. The vendor file's wrapper attaches the public API
+// to window.hyperclay during evaluation (see
+// hyper-html-api/scripts/copy-to-hyperclayjs.js), so importing it is enough.
+// No import-map entry needed — relative vendor import, same as undo.js. This is
+// a core read/write primitive, so it is NOT edit-mode-only.
+
+import { extractData, applyData, engine } from './vendor/hyper-html-api.vendor.js'
+
+export { extractData, applyData, engine }

package/src/hyperclay.js

@@ -1,7 +1,7 @@
 /**
  * DO NOT EDIT THIS FILE DIRECTLY — it is generated from build/hyperclay.template.js
  *
- * HyperclayJS v1.29.1 - Minimal Browser-Native Loader
+ * HyperclayJS v1.31.0 - Minimal Browser-Native Loader
  *
  * Modules auto-init when imported (no separate init call needed).
  * Include `export-to-window` feature to export to window.hyperclay.
@@ -46,6 +46,7 @@ const MODULE_PATHS = {
   "onaftersave": "./custom-attributes/onaftersave.js",
   "save-freeze": "./custom-attributes/saveFreeze.js",
   "dialogs": "./ui/prompts.js",
+  "quickcrop": "./ui/quickcrop.js",
   "toast": "./ui/toast.js",
   "toast-hyperclay": "./ui/toast-hyperclay.js",
   "the-modal": "./ui/theModal.js",
@@ -63,6 +64,7 @@ const MODULE_PATHS = {
   "hyper-morph": "./vendor/hyper-morph.vendor.js",
   "hypercms": "./vendor/hypercms.vendor.js",
   "undo": "./undo.js",
+  "data": "./data.js",
   "slugify": "./string-utilities/slugify.js",
   "copy-to-clipboard": "./string-utilities/copy-to-clipboard.js",
   "query-params": "./string-utilities/query.js",
@@ -101,12 +103,31 @@ const PRESETS = {
       "option-visibility",
       "event-attrs",
       "dom-helpers",
+      "data",
       "toast",
       "save-toast",
       "export-to-window",
       "view-mode-excludes-edit-modules"
     ]
   },
+  "cms": {
+    "name": "CMS",
+    "description": "Visual CMS editing for rules-tag pages: hypercms sidebar, undo, drag-reorder, save",
+    "modules": [
+      "save-core",
+      "snapshot",
+      "save-system",
+      "unsaved-warning",
+      "toast",
+      "save-toast",
+      "mutation",
+      "hypercms",
+      "sortable",
+      "undo",
+      "export-to-window",
+      "view-mode-excludes-edit-modules"
+    ]
+  },
   "smooth-sailing": {
     "name": "Smooth Sailing",
     "description": "Everything, without gotchas",
@@ -129,6 +150,7 @@ const PRESETS = {
       "onaftersave",
       "save-freeze",
       "dialogs",
+      "quickcrop",
       "toast",
       "the-modal",
       "mutation",
@@ -143,6 +165,7 @@ const PRESETS = {
       "form-data",
       "hypercms",
       "undo",
+      "data",
       "slugify",
       "copy-to-clipboard",
       "query-params",
@@ -177,6 +200,7 @@ const PRESETS = {
       "onaftersave",
       "save-freeze",
       "dialogs",
+      "quickcrop",
       "toast",
       "the-modal",
       "mutation",
@@ -193,6 +217,7 @@ const PRESETS = {
       "hyper-morph",
       "hypercms",
       "undo",
+      "data",
       "slugify",
       "copy-to-clipboard",
       "query-params",
@@ -267,8 +292,14 @@ if (viewModeExcludesEdit) {
   }
 }
 
-// Modules that extend prototypes must load before modules that execute user code
-const LOAD_FIRST = new Set(['dom-helpers', 'all-js']);
+// Modules that extend prototypes must load before modules that execute user code.
+// 'mutation' is here so it evaluates (and installs window.hyperclay.Mutation) in
+// the first wave, before hypercms in the rest wave: hypercms reads
+// window.hyperclay.Mutation at evaluation/auto-open time, so loading mutation
+// first makes ?cms=true auto-open deterministic instead of racing. Safe because
+// export-to-window is awaited before the first wave, so mutation's window-install
+// is not suppressed when it runs.
+const LOAD_FIRST = new Set(['dom-helpers', 'all-js', 'mutation']);
 
 // export-to-window flips the flag, so it must load before other modules
 const LOAD_BEFORE_ALL = 'export-to-window';
@@ -308,6 +339,20 @@ try {
 
 if (debug) console.log('HyperclayJS: Ready');
 
+// View-mode save notice: in edit mode, save-system's own [trigger-save]
+// listener handles clicks. For everyone else that listener is either never
+// installed (its init is edit-mode gated) or not loaded at all
+// (view-mode-excludes-edit-modules), so a save click would silently do
+// nothing. Catch it here and say why. Imports happen at click time, so this
+// costs nothing on page load.
+document.addEventListener('click', async (event) => {
+  if (!event.target.closest?.('[trigger-save]')) return;
+  const { isEditMode } = await import(`${baseUrl}/core/isAdminOfCurrentResource.js`);
+  if (isEditMode) return;
+  const { default: toast } = await import(`${baseUrl}/ui/toast.js`);
+  toast("You're not the owner, changes are local only", "warning");
+});
+
 // ES module exports - allows destructuring from import()
 export const savePage = window.hyperclayModules['save-core']?.savePage ?? window.hyperclayModules['save-core']?.default;
 export const beforeSave = window.hyperclayModules['save-system']?.beforeSave ?? window.hyperclayModules['save-system']?.default;
@@ -327,6 +372,7 @@ export const ask = window.hyperclayModules['dialogs']?.ask ?? window.hyperclayMo
 export const consent = window.hyperclayModules['dialogs']?.consent ?? window.hyperclayModules['dialogs']?.default;
 export const tell = window.hyperclayModules['dialogs']?.tell ?? window.hyperclayModules['dialogs']?.default;
 export const snippet = window.hyperclayModules['dialogs']?.snippet ?? window.hyperclayModules['dialogs']?.default;
+export const quickcrop = window.hyperclayModules['quickcrop']?.quickcrop ?? window.hyperclayModules['quickcrop']?.default;
 export const toast = window.hyperclayModules['toast']?.toast ?? window.hyperclayModules['toast']?.default;
 export const toastHyperclay = window.hyperclayModules['toast-hyperclay']?.toastHyperclay ?? window.hyperclayModules['toast-hyperclay']?.default;
 export const themodal = window.hyperclayModules['the-modal']?.themodal ?? window.hyperclayModules['the-modal']?.default;
@@ -346,6 +392,8 @@ export const HyperMorph = window.hyperclayModules['hyper-morph']?.HyperMorph ??
 export const morph = window.hyperclayModules['hyper-morph']?.morph ?? window.hyperclayModules['hyper-morph']?.default;
 export const cms = window.hyperclayModules['hypercms']?.cms ?? window.hyperclayModules['hypercms']?.default;
 export const undo = window.hyperclayModules['undo']?.undo ?? window.hyperclayModules['undo']?.default;
+export const extractData = window.hyperclayModules['data']?.extractData ?? window.hyperclayModules['data']?.default;
+export const applyData = window.hyperclayModules['data']?.applyData ?? window.hyperclayModules['data']?.default;
 export const slugify = window.hyperclayModules['slugify']?.slugify ?? window.hyperclayModules['slugify']?.default;
 export const copyToClipboard = window.hyperclayModules['copy-to-clipboard']?.copyToClipboard ?? window.hyperclayModules['copy-to-clipboard']?.default;
 export const query = window.hyperclayModules['query-params']?.query ?? window.hyperclayModules['query-params']?.default;