@panphora/clayjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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:
+
+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.

package/README.md

@@ -0,0 +1,57 @@
+# clayjs
+
+Self-saving, malleable HTML in one classic `<script>`. Load `clay.js` on a page and it
+becomes editable in place, snapshots its own DOM, and saves that DOM back to the file it
+came from. No build step, no framework.
+
+## Use
+
+```html
+<script src="https://clayjs.com/clay.js"></script>
+```
+
+The loader detects edit vs view mode and pulls only the modules it needs. Tune it with
+query params on the script URL:
+
+```html
+<script src="/clay.js?plugins=sync,cms&exclude=indicator"></script>
+```
+
+- `?plugins=` — add optional plugins: `sync`, `cms` (richclay, indicator, sortable, undo load by default in edit mode).
+- `?exclude=` — drop a default plugin.
+- `?editmode=false` — force view mode (URL param wins over cookies/globals).
+
+## Readiness
+
+The bootstrap creates `window.clay` synchronously with just a `ready` promise, then augments
+that same object once boot finishes. Wait for it before using any other member:
+
+```js
+await clay.ready;      // or: document.addEventListener("clay:ready", ...)
+clay.save();
+```
+
+Edit mode exposes `clay.save()` (+ `clay.save.force()`), `clay.getHTML()`, `clay.beforeSave(fn)`,
+`clay.onSnapshot(fn)`, `clay.toggleEditMode()`, `clay.isEditMode`, `clay.isOwner`, `clay.Mutation`,
+`clay.cacheBust(el)`, plus `clay.undo` / `clay.cms` / `clay.morph` when those plugins load. View
+mode keeps only the always-available members (`toggleEditMode`, `isEditMode`, `isOwner`,
+`Mutation`, `ready`); edit-only members are simply absent.
+
+## Regions
+
+Mark parts of the DOM the save/sync engine should treat specially with one space-separated
+attribute:
+
+```html
+<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.
+
+## Develop
+
+```bash
+npm test        # jest unit suite
+npm run dev     # stub save server on :4601 for the tests/fixtures pages
+```

package/clay.js

@@ -0,0 +1,21 @@
+/* clayjs bootstrap. https://clayjs.com */
+(function () {
+  // Suppress every vendored bundle's window auto-export; the loader assembles
+  // window.clay (and a scoped compat shim) explicitly.
+  window.__hyperclayNoAutoExport = true;
+
+  var readyResolve;
+  var clay = { ready: new Promise(function (r) { readyResolve = r; }) };
+  window.clay = clay;
+
+  var script = document.currentScript;
+  if (!script || !script.src) {
+    console.error("clayjs: could not determine my own URL (load me with a classic <script src=...>, not type=\"module\")");
+    return;
+  }
+  var url = new URL(script.src, location.href);
+  var base = url.href.slice(0, url.href.lastIndexOf("/"));
+  import(base + "/src/loader.js")
+    .then(function (m) { return m.boot(base, url.searchParams, readyResolve); })
+    .catch(function (err) { console.error("clayjs failed to load:", err); });
+})();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@panphora/clayjs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
+  "license": "MIT",
+  "homepage": "https://clayjs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panphora/clayjs.git"
+  },
+  "files": [
+    "clay.js",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "dev": "node tests/stub-server.mjs"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0"
+  }
+}

package/src/attrs/onaftersave.js

@@ -0,0 +1,38 @@
+/**
+ * [onaftersave] Custom Attribute
+ *
+ * Runs inline JavaScript after a successful save.
+ * Only fires on 'clay:save-saved' events (not on error/offline).
+ *
+ * Usage:
+ *   <span onaftersave="this.innerText = event.detail.msg"></span>
+ *   <link href="styles.css" onaftersave="cacheBust(this)">
+ *
+ * The event.detail object contains:
+ *   - status: 'saved'
+ *   - msg: string (e.g., 'Saved')
+ *   - timestamp: number (Date.now())
+ */
+
+function broadcast(e) {
+  const status = e.type.replace('clay:save-', '');
+  const detail = { ...e.detail, status };
+
+  document.querySelectorAll('[onaftersave]').forEach(el => {
+    try {
+      const event = new CustomEvent('aftersave', { detail });
+      const handler = new Function('event', el.getAttribute('onaftersave'));
+      handler.call(el, event);
+    } catch (err) {
+      console.error('[onaftersave] Error in handler:', err);
+    }
+  });
+}
+
+function init() {
+  document.addEventListener('clay:save-saved', broadcast);
+}
+
+init();
+
+export default init;

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

@@ -0,0 +1,36 @@
+function swapElement(el) {
+  const attr = el.hasAttribute('href') ? 'href' : el.hasAttribute('src') ? 'src' : null;
+  if (!attr) return;
+
+  const oldValue = el.getAttribute(attr);
+  const url = new URL(oldValue, 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);
+  }
+  newEl.setAttribute(attr, isSameOrigin ? url.pathname + url.search : url.href);
+  const tokens = new Set((newEl.getAttribute("clay") || "").trim().split(/\s+/).filter(Boolean));
+  tokens.add("no-trigger-autosave");
+  tokens.add("no-undo");
+  newEl.setAttribute("clay", Array.from(tokens).join(" "));
+
+  el.insertAdjacentElement('afterend', newEl);
+
+  newEl.onload = () => el.remove();
+  setTimeout(() => {
+    if (el.parentNode) el.remove();
+  }, 2000);
+}
+
+function init() {
+  document.addEventListener('clay:save-saved', () => {
+    document.querySelectorAll('[refetch-on-save]').forEach(swapElement);
+  });
+}
+
+init();
+
+export default init;

package/src/attrs/save-freeze.js

@@ -0,0 +1,102 @@
+/**
+ * [freeze] / [save-freeze] Custom Attribute
+ *
+ * Freezes an element's innerHTML for save purposes.
+ * The live DOM can change freely, but the saved HTML always
+ * contains the original content captured when the element first appeared.
+ *
+ * Usage:
+ *   <div clay="freeze">Content that JS will modify at runtime</div>
+ *
+ * The original innerHTML is captured:
+ *   - On page load, for all existing freeze elements
+ *   - On DOM insertion, for dynamically added freeze elements
+ *
+ * At save time, the clone's innerHTML is replaced with the stored original.
+ * Changes inside freeze elements do not trigger autosave dirty checks.
+ */
+
+import { onSnapshot, onPrepareForSave } from "../core/snapshot.js";
+import { isEditMode } from "../core/is-edit-mode.js";
+import { FREEZE_SELECTOR } from "../lib/region-policy.js";
+import Mutation from "../lib/mutation.js";
+
+const originals = new WeakMap();
+
+const saveFreeze = { debug: false };
+
+function log(...args) {
+  if (saveFreeze.debug) console.log('[save-freeze]', ...args);
+}
+
+function capture(el) {
+  if (!originals.has(el)) {
+    originals.set(el, el.innerHTML);
+    log('captured original', el.innerHTML.substring(0, 80) + '...');
+  }
+}
+
+function captureAll() {
+  const els = document.querySelectorAll(FREEZE_SELECTOR);
+  log('captureAll found', els.length, 'elements');
+  for (const el of els) {
+    capture(el);
+  }
+}
+
+function freezeClone(clone) {
+  const liveElements = document.querySelectorAll(FREEZE_SELECTOR);
+  const cloneElements = clone.querySelectorAll(FREEZE_SELECTOR);
+
+  log('freezing clone — live:', liveElements.length, 'clone:', cloneElements.length);
+
+  for (let i = 0; i < cloneElements.length; i++) {
+    const liveEl = liveElements[i];
+    const hasOriginal = liveEl && originals.has(liveEl);
+    if (hasOriginal) {
+      const original = originals.get(liveEl);
+      const current = cloneElements[i].innerHTML;
+      if (original !== current) {
+        log('element', i, '— restoring original');
+        cloneElements[i].innerHTML = original;
+      }
+    }
+  }
+}
+
+function init() {
+  log('init, isEditMode:', isEditMode);
+  if (!isEditMode) return;
+
+  captureAll();
+
+  // Capture the original innerHTML of dynamically added [freeze]/[save-freeze]
+  // regions. Folded onto the single Mutation observer (Phase 2 — was its own).
+  // debounce:0 so we snapshot the authored content before any runtime edit
+  // mutates it; the callback is a pure read into a WeakMap (no DOM writes).
+  // require:'observed' (skip only no-watch); pausable:false so a morphed-in
+  // freeze region is still captured. NOTE: the old observer watched
+  // document.documentElement; Mutation watches document.body, so a [freeze] added
+  // directly to <head> at runtime is no longer captured (authored <head> freeze
+  // regions are still handled by captureAll() on load) — an accepted edge.
+  Mutation.onAddElement({
+    selectorFilter: FREEZE_SELECTOR,
+    require: 'observed',
+    pausable: false,
+    debounce: 0
+  }, (changes) => {
+    changes.forEach(({ element }) => capture(element));
+  });
+
+  // Phase 2: Freeze in snapshot — before snapshot-ready fires.
+  // This prevents live-sync from writing unfrozen content to disk.
+  onSnapshot(freezeClone);
+
+  // Phase 3a: Freeze again in prepare — belt-and-suspenders.
+  // Catches any modifications made between phase 2 and 3a (e.g., onbeforesave handlers).
+  onPrepareForSave(freezeClone);
+}
+
+init();
+
+export default saveFreeze;

package/src/core/admin-attrs.js

@@ -0,0 +1,22 @@
+// Admin system - combines all admin features (edit-only).
+import { init as initContenteditable } from './admin-contenteditable.js';
+import { init as initInputs } from './admin-inputs.js';
+import { init as initOnClick } from './admin-onclick.js';
+import { init as initResources } from './admin-resources.js';
+
+let initialized = false;
+
+function init() {
+  if (initialized) return;
+  initialized = true;
+  initContenteditable();
+  initInputs();
+  initOnClick();
+  initResources();
+}
+
+// Auto-init when module is imported
+init();
+
+export { init };
+export default init;

package/src/core/admin-contenteditable.js

@@ -0,0 +1,47 @@
+import { isEditMode, isOwner } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { beforeSave } from "./snapshot.js";
+
+export const SELECTOR = '[editmode\\:contenteditable]';
+
+export function disableContentEditableBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll(SELECTOR).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(SELECTOR).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(SELECTOR).forEach(el => {
+    const val = el.getAttribute("contenteditable") || "true";
+    el.setAttribute("inert-contenteditable", val);
+    el.removeAttribute("contenteditable");
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableContentEditableBeforeSave();
+  enableContentEditableForAdminOnPageLoad();
+}

package/src/core/admin-inputs.js

@@ -0,0 +1,48 @@
+import { isEditMode, isOwner } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { beforeSave } from "./snapshot.js";
+
+export const SELECTOR_DISABLED = '[viewmode\\:disabled]';
+export const SELECTOR_READONLY = '[viewmode\\:readonly]';
+
+export function disableAdminInputsBeforeSave() {
+  beforeSave(docElem => {
+    docElem.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
+      input.setAttribute('disabled', '');
+    });
+    docElem.querySelectorAll(SELECTOR_READONLY).forEach(input => {
+      input.setAttribute('readonly', '');
+    });
+  });
+}
+
+export function enableAdminInputsOnPageLoad() {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableAdminInputs();
+  });
+}
+
+export function enableAdminInputs() {
+  document.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
+    input.removeAttribute('disabled');
+  });
+  document.querySelectorAll(SELECTOR_READONLY).forEach(input => {
+    input.removeAttribute('readonly');
+  });
+}
+
+export function disableAdminInputs() {
+  document.querySelectorAll(SELECTOR_DISABLED).forEach(input => {
+    input.setAttribute('disabled', '');
+  });
+  document.querySelectorAll(SELECTOR_READONLY).forEach(input => {
+    input.setAttribute('readonly', '');
+  });
+}
+
+export function init() {
+  disableAdminInputsBeforeSave();
+  enableAdminInputsOnPageLoad();
+}

package/src/core/admin-onclick.js

@@ -0,0 +1,50 @@
+import { isEditMode, isOwner } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { beforeSave } from "./snapshot.js";
+
+export const SELECTOR = '[editmode\\:onclick]';
+
+export function disableOnClickBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll(SELECTOR).forEach(resource => {
+      const originalValue = resource.getAttribute("onclick");
+      resource.setAttribute("inert-onclick", originalValue);
+      resource.removeAttribute("onclick");
+    });
+  });
+}
+
+export function enableOnClickForAdminOnPageLoad () {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableOnClick();
+  });
+}
+
+// Runtime toggle functions
+export function enableOnClick() {
+  document.querySelectorAll(SELECTOR).forEach(el => {
+    const val = el.getAttribute("inert-onclick");
+    if (val) {
+      el.setAttribute("onclick", val);
+      el.removeAttribute("inert-onclick");
+    }
+  });
+}
+
+export function disableOnClick() {
+  document.querySelectorAll(SELECTOR).forEach(el => {
+    const val = el.getAttribute("onclick");
+    if (val) {
+      el.setAttribute("inert-onclick", val);
+      el.removeAttribute("onclick");
+    }
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableOnClickBeforeSave();
+  enableOnClickForAdminOnPageLoad();
+}

package/src/core/admin-resources.js

@@ -0,0 +1,49 @@
+import { isEditMode, isOwner } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { beforeSave } from "./snapshot.js";
+
+export const SELECTOR = '[editmode\\:resource]:is(style, link, script)';
+export const SELECTOR_INERT = '[editmode\\:resource]:is(style, link, script)[type^="inert/"]';
+
+export function disableAdminResourcesBeforeSave () {
+  beforeSave(docElem => {
+    docElem.querySelectorAll(SELECTOR).forEach(resource => {
+      const currentType = resource.getAttribute('type') || 'text/javascript';
+      if (!currentType.startsWith('inert/')) {
+        resource.setAttribute('type', `inert/${currentType}`);
+      }
+    });
+  });
+}
+
+export function enableAdminResourcesOnPageLoad () {
+  if (!isEditMode) return;
+
+  onDomReady(() => {
+    enableAdminResources();
+  });
+}
+
+// Runtime toggle functions
+export function enableAdminResources() {
+  document.querySelectorAll(SELECTOR_INERT).forEach(resource => {
+    resource.type = resource.type.replace(/inert\//g, '');
+    resource.replaceWith(resource.cloneNode(true));
+  });
+}
+
+export function disableAdminResources() {
+  document.querySelectorAll(SELECTOR).forEach(resource => {
+    const currentType = resource.getAttribute('type') || 'text/javascript';
+    if (!currentType.startsWith('inert/')) {
+      resource.setAttribute('type', `inert/${currentType}`);
+      resource.replaceWith(resource.cloneNode(true));
+    }
+  });
+}
+
+// Auto-initialize
+export function init() {
+  disableAdminResourcesBeforeSave();
+  enableAdminResourcesOnPageLoad();
+}

package/src/core/autosave.js

@@ -0,0 +1,61 @@
+/**
+ * Auto-save system for clayjs
+ *
+ * Automatically saves page on DOM changes with throttling.
+ * Gated by the <html autosave> attribute.
+ *
+ * Requires the 'save-system' module to be loaded first.
+ *
+ * Recommended companion modules:
+ *   - 'unsaved-warning' - Warn before leaving with unsaved changes (required for beforeunload)
+ */
+
+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";
+
+/**
+ * Initialize auto-save on DOM changes
+ * Uses debounced mutation observer
+ */
+function initSavePageOnChange() {
+  Mutation.onAnyChange({
+    debounce: 1500,
+    omitChangeDetails: true,
+    require: 'autosave'
+  }, () => {
+    savePageThrottled();
+  });
+}
+
+/**
+ * Initialize auto-save on input events for [persist] elements
+ * Form input values don't trigger DOM mutations, so we listen for input events
+ */
+let inputSaveTimer = null;
+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();
+    clearTimeout(inputSaveTimer);
+    inputSaveTimer = setTimeout(savePageThrottled, 1500);
+  }, true);
+}
+
+function init() {
+  if (!document.documentElement.hasAttribute("autosave")) return;
+  if (!isEditMode) return;
+  initUserGesture();
+  initSavePageOnChange();
+  initSaveOnPersistInput();
+}
+
+// No window exports - savePageThrottled is exported from save-system
+
+// Auto-init when module is imported
+init();
+
+export default init;

package/src/core/edit-mode.js

@@ -0,0 +1,38 @@
+// Edit mode system - combines the editmode toggle with page type setting.
+// Loads in BOTH view and edit mode: toggleEditMode must exist in view mode
+// (it's the way IN), and setPageTypeOnPageLoad marks <html> in either mode.
+import { isEditMode, isOwner } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { beforeSave } from "./snapshot.js";
+
+export function toggleEditMode() {
+  const url = new URL(window.location.href);
+  const newMode = isEditMode ? "false" : "true";
+  url.searchParams.set('editmode', newMode);
+  window.location.href = url.toString();
+}
+
+export function setViewerPageTypeBeforeSave () {
+  beforeSave(docElem => {
+    docElem.setAttribute("editmode", "false");
+    docElem.setAttribute("pageowner", "false");
+  });
+}
+
+export function setPageTypeOnPageLoad () {
+  onDomReady(() => {
+    document.documentElement.setAttribute("editmode", isEditMode ? "true" : "false");
+    document.documentElement.setAttribute("pageowner", isOwner ? "true" : "false");
+  });
+}
+
+function init() {
+  setViewerPageTypeBeforeSave();
+  setPageTypeOnPageLoad();
+}
+
+// Auto-init when module is imported
+init();
+
+export { init, isEditMode, isOwner };
+export default { init, toggleEditMode, isEditMode, isOwner };

package/src/core/is-edit-mode.js

@@ -0,0 +1,30 @@
+import cookie from "../lib/cookie.js";
+import query from "../lib/query.js";
+
+// Edit-mode precedence: an explicit ?editmode=true|false URL param wins, then an
+// opt-in window.clayEditMode global (with the legacy window.__hyperclayEditMode
+// still honored as a fallback — htmlclay injects it today), then the platform's
+// isAdminOfCurrentResource cookie. The global is for standalone uses (demos,
+// htmlclay, any self-saving file) that are always editable and have no owner
+// cookie; setting it before clayjs loads turns on the edit-only modules.
+let forcedEditMode = null;
+if (typeof window !== "undefined") {
+  if (window.clayEditMode != null) {
+    forcedEditMode = Boolean(window.clayEditMode);
+  } else if (window.__hyperclayEditMode != null) {
+    forcedEditMode = Boolean(window.__hyperclayEditMode);
+  }
+}
+
+const isEditMode = query.editmode
+  ? query.editmode === "true" // takes precedence over the global and cookie
+  : forcedEditMode != null
+    ? forcedEditMode
+    : Boolean(cookie.get("isAdminOfCurrentResource"));
+
+const isOwner = Boolean(cookie.get("isAdminOfCurrentResource"));
+
+export {
+  isEditMode,
+  isOwner
+}