@panphora/clayjs 0.6.1 → 0.7.0

package/LICENSE

@@ -1,21 +1,16 @@
-MIT License
+MIT No Attribution
 
 Copyright (c) 2026 David Miranda
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# clayjs
+# clayjs™
 
 **Site, tutorial, and docs: [clayjs.com](https://clayjs.com)** · hosted platform: [hyperclay.com](https://hyperclay.com)
 
@@ -19,7 +19,7 @@ query params on the script URL:
 <script src="/clay.js?plugins=sync,cms&exclude=indicator"></script>
 ```
 
-- `?plugins=` — add optional plugins: `sync`, `cms`, `undo`, `sortable`, `indicator`, `quickcrop`, `wire`.
+- `?plugins=` — add optional plugins: `sync`, `cms`, `undo`, `sortable`, `indicator`, `quickcrop`, `upload`, `wire`, `demo`.
   Only `richclay` loads by default, and only in edit mode. `cms` brings `quickcrop` with it, because
   the CMS uses it for `data-hcms-crop` image fields.
 - `?exclude=` — drop a plugin that would otherwise load (a default, or one another plugin pulled in).
@@ -35,10 +35,6 @@ never reach the file on disk.
   `/_/save/{token}` and sends no cookies, because the token is the credential.
   A token also implies edit mode, which is the only such signal a sandboxed
   document can see. `htmlclaytoken` is the older spelling of the same thing.
-- `clay-save-transport="desktop-json-v1"` — send the save as
-  `{content, snapshotHtml, userDriven}` JSON instead of plain text. Only declare
-  it on a host whose save lane reads that envelope.
-
 Edit mode is decided in this order: the `?editmode` param, then
 `window.clayEditMode`, then a save token, then the platform's owner cookie.
 
@@ -111,8 +107,9 @@ lifecycle.
   satellite with no core loaded.
 - `region.addRegionToken(el, token)`, `region.resolveRegionPolicy(node)`, `region.isInert(node)`,
   `region.isSnapshotRemoved(el)`, `region.PERSIST`, `region.REGION_ATTRS`, and
-  `region.selectors.stripFromSave` / `.stripFromComparison` / `.snapshotRemove` / `.freeze` — write your
-  own attribute without hardcoding our selectors.
+  `region.selectors.stripFromSave` / `.stripFromComparison` / `.stripFromDirtyCheck` /
+  `.noTriggerAutosave` / `.noDirty` / `.snapshotRemove` / `.freeze` — write your own attribute
+  without hardcoding our selectors.
 - `save.saveHtml(html, cb, opts)`, `save.replacePageWith(url, cb)`, `save.isSaveInProgress()` — the save
   lane under `clay.save`. **`saveHtml` writes the bytes you hand it straight to the file**, bypassing the
   snapshot pipeline entirely; check `isSaveInProgress()` first.
@@ -126,8 +123,15 @@ attribute:
 <div clay="no-save no-snapshot freeze">…</div>
 ```
 
-Tokens: `no-save`, `no-snapshot`, `no-trigger-autosave`, `no-watch`, `no-undo`, `freeze`.
-Add `autosave` to `<html>` to save automatically on change.
+Tokens: `no-save`, `no-snapshot`, `no-trigger-autosave`, `no-dirty`, `no-watch`, `no-undo`,
+`freeze`. Add `autosave` to `<html>` to save automatically on change.
+
+`no-trigger-autosave` and `no-dirty` are the pair worth getting right. Both are saved in full and
+neither starts an autosave. The difference is whether their content is *work*: a
+`no-trigger-autosave` region holds real edits waiting for a manual save, so it warns you on close
+and live sync will not overwrite it, while a `no-dirty` region renders itself from something else,
+so it never warns and an incoming sync frame may replace it. Use `no-dirty` for filter bars,
+projections and drag previews; use `no-trigger-autosave` for a heavy editor you save by hand.
 
 ## Develop
 
@@ -151,7 +155,7 @@ Never edit `public/` by hand, and never copy a file into it. Its contents are
 **derived**:
 
 ```
-public/  =  package.json "files"  (minus NOTICE, which nothing requests)
+public/  =  package.json "files"  (minus THIRD-PARTY-NOTICES.md, which nothing requests)
          +  website/*             (flattened to the root, so /docs.html works)
 ```
 
@@ -161,3 +165,9 @@ reach npm and miss the site. Before this script existed the mirror was hand-copi
 and it drifted exactly that way: `src/core/host-attrs.js` never made it across, and
 since `loader.js` imports `is-edit-mode.js`, which imports it, the deployed
 `clay.js` could not boot at all.
+
+## License
+
+Our code is MIT-0 (MIT No Attribution): use it, remix it, ship it, no attribution
+needed. Vendored third-party files keep their original permissive licenses; see
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,40 @@
+# Third-party notices
+
+Our own code in this repository is licensed under MIT-0 (see LICENSE): use it,
+remix it, ship it, no attribution needed. The components below are third-party,
+or carry third-party code, and keep their original licenses.
+
+## SortableJS 1.15.6 (MIT)
+
+- File: src/vendor/Sortable.vendor.js
+- Copyright (c) SortableJS contributors
+- https://github.com/SortableJS/Sortable
+
+## Squire 2.4.8 (MIT)
+
+- Carried inside src/vendor/richclay.vendor.js and website/vendor/richclay.min.js
+  (richclay bundles Squire)
+- Copyright (c) 2011-2023 by Neil Jenkins
+- https://github.com/fastmail/Squire
+
+## DOMPurify 3.4.11 (Apache-2.0 OR MPL-2.0)
+
+- Carried inside src/vendor/richclay.vendor.js and website/vendor/richclay.min.js
+  (richclay bundles DOMPurify)
+- (c) Cure53 and other contributors
+- https://github.com/cure53/DOMPurify
+
+## MicroModal (MIT)
+
+- The modal component in src/ui/modal.js derives its structure and class naming
+  from MicroModal.
+- Copyright (c) 2017 Indrashish Ghosh
+- https://github.com/ghosh/Micromodal
+
+## First-party vendored modules
+
+The remaining files in src/vendor/ (hypercms, hyper-morph, hyper-undo, quickcrop,
+control-serialize) and the generated sap.js and clay-data.js are our own sibling
+libraries. clayjs also derives from our own hyperclayjs library (MIT); as the
+copyright holder of those portions we license them here under MIT-0 with the rest
+of our code.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@panphora/clayjs",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
-  "license": "MIT",
+  "license": "MIT-0",
   "homepage": "https://clayjs.com",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "sap.js",
     "clay-data.js",
     "_headers",
-    "NOTICE",
+    "THIRD-PARTY-NOTICES.md",
     "src/"
   ],
   "publishConfig": {

package/src/attrs/onaftersave.js

@@ -5,16 +5,30 @@
  * Only fires on 'clay:save-saved' events (not on error/offline).
  *
  * Usage:
- *   <span clay="no-trigger-autosave" onaftersave="this.innerText = event.detail.msg"></span>
- *   <link href="styles.css" onaftersave="cacheBust(this)">
+ *   <span clay="no-save" onaftersave="this.innerText = event.detail.msg"></span>
+ *   <link href="styles.css" onaftersave="clay.cacheBust(this)">
  *
- * MARK WHAT YOU MUTATE `no-trigger-autosave`.
- * These handlers run after the save baseline has been taken, so anything they write
- * to the live DOM reads as a change the user made and leaves the page permanently
- * dirty: autosave loops, and the close-tab warning never clears. The token strips
- * the element from every comparison capture, which is what stops that.
- * `cacheBust()` marks its own target, so the second example needs nothing. A handler
- * that mutates some OTHER element has to mark that element itself.
+ * MARK WHAT YOU MUTATE `no-save` (or `freeze`).
+ * These handlers run after the save baseline has been taken, so anything they
+ * write to the live DOM reads as a change the person made, and the page stays
+ * dirty: the close-tab warning never clears, and on an autosave page it loops.
+ * `no-save` keeps the element out of the file entirely, which is what you want
+ * for a status chip or any other runtime-only chrome. `freeze` is the choice
+ * when the element must exist in the saved file, but as authored rather than as
+ * the handler left it.
+ *
+ * CHANGED IN 0.7: `no-trigger-autosave` is no longer enough on its own.
+ * It stops the handler's write from STARTING a save, and it still does that. It
+ * no longer hides the write from an explicit save or from the close warning,
+ * because those two now deliberately see batching regions — an edit you make
+ * inside one is real work that nothing else is going to write. A handler whose
+ * output is marked only `no-trigger-autosave` will leave the page reporting
+ * unsaved changes after every save. Change those markers to `no-save`, or to
+ * `freeze` if the element belongs in the file.
+ *
+ * `clay.cacheBust()` and `[refetch-on-save]` need no marker at all: they
+ * remember the authored URL and restore it on every snapshot (authored-url.js).
+ * A handler that mutates some OTHER element has to mark that element itself.
  *
  * (The alternative — re-reading the whole live DOM after handlers run — is what
  * clayjs used to do, and it silently discarded anything typed during a save.)

package/src/attrs/refetch-on-save.js

@@ -1,28 +1,48 @@
-import { addRegionToken } from '../lib/region-policy.js';
+import Mutation from '../lib/mutation.js';
+import { urlAttrFor, writeRuntimeUrl, markSuperseded, isSuperseded } from '../lib/authored-url.js';
+
+/** Remove an element without letting the removal read as a user edit. */
+function removeQuietly(el) {
+  if (!el.parentNode) return;
+  Mutation.pause();
+  try {
+    el.remove();
+  } finally {
+    Mutation.resume();
+  }
+}
 
 function swapElement(el) {
-  const attr = el.hasAttribute('href') ? 'href' : el.hasAttribute('src') ? 'src' : null;
+  const attr = urlAttrFor(el);
   if (!attr) return;
 
-  const oldValue = el.getAttribute(attr);
-  const url = new URL(oldValue, location.href);
+  // A second save landing inside the two-second overlap would otherwise swap the
+  // element that is already on its way out, and clone the clone.
+  if (isSuperseded(el)) return;
+
+  const url = new URL(el.getAttribute(attr), location.href);
   url.searchParams.set('v', Date.now());
   const isSameOrigin = url.origin === location.origin;
-
-  const newEl = document.createElement(el.tagName);
-  for (const { name, value } of el.attributes) {
-    newEl.setAttribute(name, value);
+  const runtimeValue = isSameOrigin ? url.pathname + url.search : url.href;
+
+  Mutation.pause();
+  try {
+    const newEl = document.createElement(el.tagName);
+    for (const { name, value } of el.attributes) {
+      newEl.setAttribute(name, value);
+    }
+    // Record-if-absent carries over any authored URL the copied attributes
+    // already held, so cacheBust and refetch on one element keep the original.
+    writeRuntimeUrl(newEl, attr, runtimeValue);
+
+    markSuperseded(el);
+    el.insertAdjacentElement('afterend', newEl);
+
+    newEl.onload = () => removeQuietly(el);
+    setTimeout(() => removeQuietly(el), 2000);
+  } finally {
+    Mutation.resume();
   }
-  newEl.setAttribute(attr, isSameOrigin ? url.pathname + url.search : url.href);
-  addRegionToken(newEl, "no-trigger-autosave");
-  addRegionToken(newEl, "no-undo");
-
-  el.insertAdjacentElement('afterend', newEl);
-
-  newEl.onload = () => el.remove();
-  setTimeout(() => {
-    if (el.parentNode) el.remove();
-  }, 2000);
 }
 
 function init() {

package/src/core/autosave.js

@@ -13,7 +13,8 @@
 import Mutation from "../lib/mutation.js";
 import { isEditMode } from "./is-edit-mode.js";
 import { savePageThrottled } from "./save.js";
-import { initUserGesture, markUserDriven } from "../lib/user-gesture.js";
+import { markUserDriven } from "../lib/user-gesture.js";
+import { resolveRegionPolicy, skipForPolicy } from "../lib/region-policy.js";
 
 /**
  * Initialize auto-save on DOM changes
@@ -48,8 +49,13 @@ function initSaveOnPersistInput() {
   document.addEventListener('input', (e) => {
     if (!e.target.closest('[persist]')) return;
     // A trusted input on a [persist] field is itself a user-driven change the
-    // Mutation hub can't see (form values aren't DOM mutations). Attribute it.
-    if (e.isTrusted) markUserDriven();
+    // Mutation hub can't see (form values aren't DOM mutations). Attribute it,
+    // but only when the field is inside the dirty domain: a [persist] control in
+    // a no-save or freeze region contributes nothing to the saved bytes, so
+    // typing in one must not arm provenance for a later background write.
+    if (e.isTrusted && !skipForPolicy(resolveRegionPolicy(e.target), 'dirty')) {
+      markUserDriven();
+    }
     clearTimeout(inputSaveTimer);
     inputSaveTimer = setTimeout(savePageThrottled, 1500);
   }, true);
@@ -58,7 +64,8 @@ function initSaveOnPersistInput() {
 function init() {
   if (!document.documentElement.hasAttribute("autosave")) return;
   if (!isEditMode) return;
-  initUserGesture();
+  // initUserGesture moved to save.js's init: gesture provenance belongs to every
+  // editable page, not only the ones with <html autosave>.
   initSavePageOnChange();
   initSaveOnPersistInput();
 }

package/src/core/host-attrs.js

@@ -7,13 +7,7 @@
  * cannot drift between the edit-mode ladder and the save lane.
  */
 
-import { HOST_TOKEN_ATTRS, SAVE_TRANSPORT_ATTR } from "../lib/root-attrs.js";
-
-// A host that wants the desktop JSON envelope on its save lane declares it on
-// the root. This replaced a `location.hostname === 'localhost'` sniff, which sent
-// the envelope to every host that happened to be local, including ones whose
-// save lane takes text and answers 415.
-export const DESKTOP_JSON = "desktop-json-v1";
+import { HOST_TOKEN_ATTRS } from "../lib/root-attrs.js";
 
 /**
  * The per-document save token this response carries, or null.
@@ -35,12 +29,3 @@ export function saveToken() {
 export function hasSaveToken() {
   return saveToken() !== null;
 }
-
-/**
- * The save transport the served document declares, or null.
- * @returns {?string}
- */
-export function saveTransport() {
-  if (typeof document === "undefined") return null;
-  return document.documentElement.getAttribute(SAVE_TRANSPORT_ATTR);
-}

package/src/core/save-core.js

@@ -8,8 +8,8 @@
  */
 
 import { isEditMode } from "./is-edit-mode.js";
-import { consumeUserDriven, markUserDriven } from "../lib/user-gesture.js";
-import { saveToken, saveTransport, DESKTOP_JSON } from "./host-attrs.js";
+import { consumeUserDriven, consumeExplicitSave, markUserDriven } from "../lib/user-gesture.js";
+import { saveToken } from "./host-attrs.js";
 import {
   getPageContents,
   onSnapshot,
@@ -103,13 +103,19 @@ function skippedResult(msg) {
  * the save — and the per-document token in its path — to an origin the document
  * itself chose.
  *
+ * The body is the document, as text, always. Spec §3: this route has exactly one
+ * body shape. Everything else about the save travels in a header, which is how
+ * §6's `conditional` capability added `If-Match` without touching the body, and
+ * how anything later will be added too. There used to be a JSON envelope here
+ * carrying the document alongside an unstripped snapshot; the snapshot's home is
+ * the §10 relay, which the live-sync plugin already posts it to.
+ *
  * @param {string} content - HTML to save
- * @param {?string} snapshotHtml - unstripped snapshot, for the desktop envelope
  * @param {boolean} userDriven - Whether a human gesture is behind this save
  * @param {AbortSignal} signal
  * @returns {{url: string, options: Object}}
  */
-function buildSaveRequest(content, snapshotHtml, userDriven, signal) {
+function buildSaveRequest(content, userDriven, signal) {
   const token = saveToken();
   const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
   const options = {
@@ -120,23 +126,14 @@ function buildSaveRequest(content, snapshotHtml, userDriven, signal) {
       'Document-URL': window.location.href,
       // The older spelling of the same header, which htmlclay reads today.
       'Page-URL': window.location.href,
-      'X-Hyperclay-User-Driven': userDriven ? '1' : '0'
-    }
+      // Spec §9's name for the provenance bit. `X-Hyperclay-User-Driven` was the
+      // pre-spec spelling; every host reads Save-Trigger first and falls back to
+      // it, so stored documents running an older client keep working.
+      'Save-Trigger': userDriven ? 'user' : 'auto'
+    },
+    body: content
   };
 
-  // The desktop JSON envelope carries the unstripped snapshot alongside the
-  // document, so a sync engine can replay what the browser actually had. It goes
-  // out only when the served document DECLARES that transport, and it is passed in
-  // from the capture that produced `content` — it used to be left on a window
-  // global that was cleared only on success, so two captures without an intervening
-  // successful save would pair a stale snapshot with fresh content.
-  if (saveTransport() === DESKTOP_JSON && snapshotHtml) {
-    options.headers['Content-Type'] = 'application/json';
-    options.body = JSON.stringify({ content, snapshotHtml, userDriven });
-  } else {
-    options.body = content;
-  }
-
   return { url: new URL(path, window.location.origin).href, options };
 }
 
@@ -153,18 +150,22 @@ function buildSaveRequest(content, snapshotHtml, userDriven, signal) {
  * instead of the status.
  *
  * @param {string} content - HTML to save
- * @param {?string} snapshotHtml
  * @returns {Promise<Object>} The server's response body
  */
-function sendSave(content, snapshotHtml) {
+function sendSave(content) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), SAVE_TIMEOUT_MS);
 
   // Read-and-reset the data-guard provenance bit at the ACTUAL send (past the
   // early returns in the callers), so it's never consumed on a save that never
   // ships.
-  const userDriven = consumeUserDriven();
-  const { url, options } = buildSaveRequest(content, snapshotHtml, userDriven, controller.signal);
+  // Two independent ways a save is human: an edit made in a trusted turn, or a
+  // person pressing Save. Both are consumed here, at the one point past every
+  // early return, so neither can survive into an unrelated later save.
+  const gestureDriven = consumeUserDriven();
+  const explicitlyAsked = consumeExplicitSave();
+  const userDriven = gestureDriven || explicitlyAsked;
+  const { url, options } = buildSaveRequest(content, userDriven, controller.signal);
 
   return fetch(url, options)
     .then(res => res.text().then(text => {
@@ -208,15 +209,13 @@ function sendSave(content, snapshotHtml) {
  *
  * @param {string} html - HTML string to save
  * @param {Function} callback - Called with the result on completion
- * @param {Object} [options]
- * @param {?string} [options.snapshotHtml] - unstripped snapshot from the same capture
  * @returns {Promise<{msg: string, msgType: string, code: ?string, etag: ?string}>}
  *
  * @example
  * const {msg, msgType} = await saveHtml(myHtml);
  * if (msgType === 'error') console.error('Save failed:', msg);
  */
-export function saveHtml(html, callback = () => {}, { snapshotHtml = null } = {}) {
+export function saveHtml(html, callback = () => {}) {
   return new Promise((resolve) => {
     const done = (result) => {
       if (typeof callback === 'function') callback(result);
@@ -241,7 +240,7 @@ export function saveHtml(html, callback = () => {}, { snapshotHtml = null } = {}
       return;
     }
 
-    sendSave(html, snapshotHtml)
+    sendSave(html)
       .then(successResult, errorResult)
       // Clear the flag BEFORE handing the result back, so a caller that queues a
       // follow-up save can start it immediately rather than being told the lane