@panphora/clayjs 1.2.0 → 1.4.0

package/src/core/unsaved-warning.js

@@ -31,6 +31,9 @@ preloadIfEnabled();
 // the person editing it deserves the warning.
 window.addEventListener('beforeunload', (event) => {
   if (!isEditMode) return;
+  // The demo plugin saves into this browser's own storage, so leaving the page
+  // loses nothing a prompt could protect.
+  if (window.clay?.demo) return;
 
   // The DIRTY domain, not the autosave domain. An edit inside a
   // no-trigger-autosave region never starts a save by itself, which is exactly

package/src/dom/dom-helpers.js

@@ -1,8 +1,12 @@
 import nearest from "./nearest.js";
 import pipe from "./pipe.js";
+import { createContentView, cleanContentClone } from '../lib/content-dom.js';
 
 function init () {
 
+  window.clay = window.clay || {};
+  window.clay.dom = Object.assign(window.clay.dom || {}, { createContentView, cleanContentClone });
+
   // Bail if already initialized
   if (HTMLElement.prototype.hasOwnProperty('nearest')) {
     return;
@@ -214,5 +218,5 @@ function init () {
 // Auto-init when module is imported
 init();
 
-export { init };
+export { init, createContentView, cleanContentClone };
 export default init;

package/src/lib/content-dom.js

@@ -0,0 +1,108 @@
+import { capabilitySelector, hasCapability } from './region-capabilities.js'
+
+const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visited|defined)\b/i
+
+function copyControlState(source, copy) {
+  if (!/^(INPUT|TEXTAREA|SELECT|OPTION)$/.test(source.tagName || '')) return
+  const type = (source.getAttribute?.('type') || '').toLowerCase()
+  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio') copy.value = source.value
+  if ('checked' in source && 'checked' in copy) copy.checked = source.checked
+  if ('selected' in source && 'selected' in copy) copy.selected = source.selected
+  if (source.tagName === 'SELECT') {
+    for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
+  }
+  if ('indeterminate' in source && 'indeterminate' in copy) copy.indeterminate = source.indeterminate
+}
+
+function matchesWithin(node, selector, boundary, inherit) {
+  if (inherit) return !!node.closest?.(selector)
+  let current = node
+  while (current?.nodeType === 1) {
+    if (current.matches(selector)) return true
+    if (current === boundary) break
+    current = current.parentElement
+  }
+  return false
+}
+
+function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
+  if (source.nodeType === 1 && (
+    (inherit ? hasCapability(source, capability) : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    (exclude && matchesWithin(source, exclude, boundary, inherit))
+  )) return null
+  const copy = targetDocument.importNode(source, false)
+  maps.cloneToLive.set(copy, source)
+  maps.liveToClone.set(source, copy)
+  const sourceChildren = source.nodeType === 1 && source.tagName === 'TEMPLATE' ? source.content : source
+  const copyChildren = copy.nodeType === 1 && copy.tagName === 'TEMPLATE' ? copy.content : copy
+  if (sourceChildren !== source) {
+    maps.cloneToLive.set(copyChildren, sourceChildren)
+    maps.liveToClone.set(sourceChildren, copyChildren)
+  }
+  for (const child of sourceChildren.childNodes || []) {
+    const childCopy = importTree(child, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps)
+    if (childCopy) {
+      copyChildren.appendChild(childCopy)
+      if (child.nodeType === 1) copyControlState(child, childCopy)
+    }
+  }
+  if (source.nodeType === 1) copyControlState(source, copy)
+  return copy
+}
+
+export function createContentView(context, { capability = 'data', exclude = null, inherit = true } = {}) {
+  if (!context) throw new TypeError('createContentView requires a DOM context')
+  const sourceDocument = context.nodeType === 9 ? context : context.ownerDocument
+  if (!sourceDocument?.implementation?.createHTMLDocument) {
+    throw new TypeError('createContentView requires an HTML DOM implementation')
+  }
+  const inertDocument = sourceDocument.implementation.createHTMLDocument('')
+  const cloneToLive = new WeakMap()
+  const liveToClone = new WeakMap()
+  const sourceRoot = context.nodeType === 9 ? context.documentElement : context
+  if (exclude) inertDocument.documentElement.matches(exclude)
+  const capabilityMatch = capabilitySelector(capability)
+  const root = importTree(sourceRoot, inertDocument, capability, capabilityMatch, exclude, sourceRoot, inherit, { cloneToLive, liveToClone })
+  if (context.nodeType === 9 && root) {
+    inertDocument.replaceChild(root, inertDocument.documentElement)
+    liveToClone.set(context, inertDocument)
+    cloneToLive.set(inertDocument, context)
+  }
+
+  const assertSelector = selector => {
+    if (UNSUPPORTED_SELECTOR.test(selector)) {
+      throw new Error(`Filtered content queries do not support stateful selector: ${selector}`)
+    }
+  }
+
+  return {
+    root,
+    document: inertDocument,
+    capability,
+    selector: capabilitySelector(capability),
+    cloneToLive,
+    liveToClone,
+    original(node) { return cloneToLive.get(node) || null },
+    cloneOf(node) { return liveToClone.get(node) || null },
+    query(selector, queryRoot = root) {
+      assertSelector(selector)
+      return Array.from(queryRoot.querySelectorAll(selector), node => cloneToLive.get(node) || node)
+    },
+    text(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.textContent || ''
+    },
+    html(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.innerHTML ?? ''
+    },
+    clone(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected ? inertDocument.importNode(projected, true) : null
+    },
+  }
+}
+
+export function cleanContentClone(node, options) {
+  return createContentView(node, options).root
+}

package/src/lib/mutation.js

@@ -68,6 +68,7 @@
 
 import { EXTENSION_ATTR_PATTERN } from './extension-noise.js';
 import { resolveRegionPolicy, isInert, strictestPolicy, skipForPolicy } from './region-policy.js';
+import { isPolicyAttribute } from './region-capabilities.js';
 import { ROOT_LIBRARY_ATTRS } from './root-attrs.js';
 
 import { isUserDrivenNow, markUserDriven } from './user-gesture.js';
@@ -186,7 +187,12 @@ const localMutation = {
       // doesn't participate in (no-save / no-trigger-autosave / no-undo / freeze
       // and their legacy equivalents), resolved against the callback's `require`.
       let filteredChanges = changes.filter(
-        change => !skipForPolicy(this._policyForChange(change), require, skip)
+        change => {
+          const currentSkipped = skipForPolicy(this._policyForChange(change), require, skip);
+          if (!change.policyTransition) return !currentSkipped;
+          const previousSkipped = skipForPolicy(change.previousPolicy, require, skip);
+          return !(currentSkipped && previousSkipped);
+        }
       );
       if (!filteredChanges.length) {
         this._log('No changes passed the region policy, skipping callback');
@@ -478,7 +484,8 @@ const localMutation = {
       // Intake drop: a no-watch / mutations-ignore subtree (or extension noise)
       // is invisible to every consumer, so skip it without walking. All other
       // region attributes are resolved per-consumer in _notify.
-      if (isInert(mutation.target)) {
+      const policyTransition = mutation.type === 'attributes' && isPolicyAttribute(mutation.attributeName);
+      if (!policyTransition && isInert(mutation.target)) {
         continue;
       }
 
@@ -586,7 +593,9 @@ const localMutation = {
           element: mutation.target,
           attribute: mutation.attributeName,
           oldValue: mutation.oldValue,
-          newValue: mutation.target.getAttribute(mutation.attributeName)
+          newValue: mutation.target.getAttribute(mutation.attributeName),
+          policyTransition,
+          previousPolicy: policyTransition ? policyBeforeMutation(mutation) : null,
         };
         changes.push(change);
         changesByType.attribute.push(change);
@@ -783,3 +792,17 @@ if (typeof window !== 'undefined' && !existingHub) {
 }
 
 export default Mutation;
+function policyBeforeMutation(record) {
+  let source = record.target;
+  let clone = source.cloneNode(false);
+  const leaf = clone;
+  while (source.parentElement) {
+    source = source.parentElement;
+    const parent = source.cloneNode(false);
+    parent.appendChild(clone);
+    clone = parent;
+  }
+  if (record.oldValue == null) leaf.removeAttribute(record.attributeName);
+  else leaf.setAttribute(record.attributeName, record.oldValue);
+  return resolveRegionPolicy(leaf);
+}

package/src/lib/region-capabilities.js

@@ -0,0 +1,69 @@
+export const CAPABILITIES = Object.freeze({
+  data: Object.freeze({ tokens: ['no-data'], bundles: ['editor-ui'] }),
+  save: Object.freeze({ tokens: ['no-save'], bundles: ['editor-ui'] }),
+  snapshot: Object.freeze({ tokens: ['no-snapshot'], bundles: ['editor-ui'] }),
+  watch: Object.freeze({ tokens: ['no-watch'], bundles: ['editor-ui'] }),
+  undo: Object.freeze({ tokens: ['no-undo'], bundles: ['editor-ui'] }),
+  history: Object.freeze({ tokens: [], bundles: ['editor-ui'] }),
+})
+
+export const BUNDLES = Object.freeze({
+  'editor-ui': Object.freeze(['no-data', 'no-save', 'no-snapshot', 'no-watch', 'no-undo']),
+})
+
+export const POLICY_TOKENS = Object.freeze([
+  'no-save',
+  'no-snapshot',
+  'no-trigger-autosave',
+  'no-dirty',
+  'no-watch',
+  'no-undo',
+  'no-data',
+  'freeze',
+  'editor-ui',
+])
+
+export function hasPolicyToken(element, token) {
+  if (!element || element.nodeType !== 1) return false
+  const clay = element.getAttribute?.('clay')
+  return !!(
+    (clay && clay.split(/\s+/).includes(token)) ||
+    element.hasAttribute?.(token)
+  )
+}
+
+export function expandsTo(element, token) {
+  if (hasPolicyToken(element, token)) return true
+  for (const [bundle, members] of Object.entries(BUNDLES)) {
+    if (members.includes(token) && hasPolicyToken(element, bundle)) return true
+  }
+  return false
+}
+
+export function capabilitySelector(capability) {
+  const definition = CAPABILITIES[capability]
+  if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+  return [...definition.tokens, ...definition.bundles]
+    .flatMap(token => [`[clay~="${token}"]`, `[${token}]`])
+    .join(', ')
+}
+
+export function closestWithCapability(node, capability) {
+  let element = node && node.nodeType === 1 ? node : node?.parentElement
+  while (element && element.nodeType === 1) {
+    const definition = CAPABILITIES[capability]
+    if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+    if (definition.tokens.some(token => expandsTo(element, token)) ||
+        definition.bundles.some(bundle => hasPolicyToken(element, bundle))) return element
+    element = element.parentElement
+  }
+  return null
+}
+
+export function hasCapability(node, capability) {
+  return !!closestWithCapability(node, capability)
+}
+
+export function isPolicyAttribute(name) {
+  return name === 'clay' || POLICY_TOKENS.includes(name)
+}

package/src/lib/region-policy.js

@@ -44,24 +44,21 @@
  */
 
 import { EXTENSION_NODE_SELECTOR } from './extension-noise.js';
+import { capabilitySelector, expandsTo, hasCapability, hasPolicyToken, POLICY_TOKENS } from './region-capabilities.js';
 
 export const PERSIST = { FULL: 'full', FROZEN: 'frozen', NONE: 'none' };
 
 // The canonical region tokens (spelled in the `clay` attribute or as bare attrs).
-export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'freeze'];
+export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'no-data', 'freeze', 'editor-ui'];
 
 // Every canonical token spellable inside the space-separated `clay` attribute.
 // Exported: this list used to exist as a private CLAY_TOKENS that nothing read,
 // while callers hardcoded their own copies.
-export const TOKENS = ["no-save", "no-snapshot", "no-trigger-autosave", "no-dirty", "no-watch", "no-undo", "freeze"];
+export const TOKENS = [...POLICY_TOKENS];
 
 // True when a region marker is present, whether spelled as a `clay` token
 // (whitespace-token semantics, matching [clay~=token]) or a legacy bare attribute.
-function hasRegionToken(el, token) {
-  const clay = el.getAttribute?.("clay");
-  if (clay && clay.split(/\s+/).includes(token)) return true;   // whitespace-token semantics, matches [clay~=…]
-  return !!el.hasAttribute?.(token);                            // legacy bare attribute
-}
+const hasRegionToken = hasPolicyToken;
 
 /**
  * Add a canonical region token to an element's `clay` attribute, preserving any
@@ -79,7 +76,7 @@ export function addRegionToken(el, token) {
 }
 
 // Serializer selectors (recognize the clay-token spelling FIRST, then new + legacy bare).
-export const STRIP_FROM_SAVE = '[clay~="no-save"], [no-save], [save-remove]';
+export const STRIP_FROM_SAVE = `${capabilitySelector('save')}, [save-remove]`;
 export const FREEZE_SELECTOR = '[clay~="freeze"], [freeze], [save-freeze]';
 // forComparison additionally strips every region whose autosave-trigger is off,
 // so their churn never marks the page dirty — including the no-watch /
@@ -117,7 +114,8 @@ export const STRIP_FROM_DIRTY_CHECK =
 // dirty-comparison) in snapshot.js. `no-snapshot` is the consistent alias for the
 // original `snapshot-remove`; hyper-morph treats both as sync-ignored so a
 // live-sync receiver keeps its own local copy instead of deleting it.
-export const SNAPSHOT_REMOVE_SELECTOR = '[clay~="no-snapshot"], [snapshot-remove], [no-snapshot]';
+export const SNAPSHOT_REMOVE_SELECTOR = `${capabilitySelector('snapshot')}, [snapshot-remove]`;
+export const NO_DATA_SELECTOR = capabilitySelector('data');
 
 // Ancestor-aware, because the strip removes a marked element together with its
 // whole subtree: a child of a no-snapshot region is just as absent from every
@@ -128,6 +126,10 @@ export function isSnapshotRemoved(node) {
   return !!(element && element.closest && element.closest(SNAPSHOT_REMOVE_SELECTOR));
 }
 
+export function isDataExcluded(node) {
+  return hasCapability(node, 'data');
+}
+
 const PERSIST_RANK = { full: 0, frozen: 1, none: 2 };
 const RANK_PERSIST = ['full', 'frozen', 'none'];
 
@@ -158,11 +160,11 @@ export function resolveRegionPolicy(node) {
   while (element && element.nodeType === 1) {
     if (element.hasAttribute) {
       // new naked attributes
-      if (hasRegionToken(element, 'no-watch')) watched = false;
+      if (expandsTo(element, 'no-watch')) watched = false;
       if (hasRegionToken(element, 'no-trigger-autosave')) autosaveOff = true;
       if (hasRegionToken(element, 'no-dirty')) { autosaveOff = true; dirtyOff = true; }
-      if (hasRegionToken(element, 'no-undo')) undoable = false;
-      if (hasRegionToken(element, 'no-save')) persistRank = Math.max(persistRank, PERSIST_RANK.none);
+      if (expandsTo(element, 'no-undo')) undoable = false;
+      if (expandsTo(element, 'no-save')) persistRank = Math.max(persistRank, PERSIST_RANK.none);
       if (hasRegionToken(element, 'freeze')) persistRank = Math.max(persistRank, PERSIST_RANK.frozen);
       // legacy markers -> bundles
       if (hasRegionToken(element, 'mutations-ignore')) watched = false;
@@ -209,7 +211,7 @@ export function isInert(node) {
   if (element && element.closest && element.closest(EXTENSION_NODE_SELECTOR)) return true;
   while (element && element.nodeType === 1) {
     if (element.hasAttribute &&
-        (hasRegionToken(element, 'no-watch') || hasRegionToken(element, 'mutations-ignore'))) {
+        (expandsTo(element, 'no-watch') || hasRegionToken(element, 'mutations-ignore'))) {
       return true;
     }
     element = element.parentElement;
@@ -283,6 +285,7 @@ export const regionShape = {
   resolveRegionPolicy,
   isInert,
   isSnapshotRemoved,
+  isDataExcluded,
   skipForPolicy,
   strictestPolicy,
   addRegionToken,
@@ -297,6 +300,7 @@ export const regionShape = {
   NO_TRIGGER_AUTOSAVE_SELECTOR,
   NO_DIRTY_SELECTOR,
   SNAPSHOT_REMOVE_SELECTOR,
+  NO_DATA_SELECTOR,
   FREEZE_SELECTOR,
 
   // Nested camelCase: what clay.internals.region has always published.
@@ -307,6 +311,7 @@ export const regionShape = {
     noTriggerAutosave: NO_TRIGGER_AUTOSAVE_SELECTOR,
     noDirty: NO_DIRTY_SELECTOR,
     snapshotRemove: SNAPSHOT_REMOVE_SELECTOR,
+    noData: NO_DATA_SELECTOR,
     freeze: FREEZE_SELECTOR,
   },
 };

package/src/loader-logic.js

@@ -10,10 +10,14 @@ export const CORE_WAVES = {
     "core/stale-host-notice.js",
   ],
   editOnly: [
-    "core/snapshot.js", "core/save-core.js", "core/save.js",
+    "vendor/hyper-morph.vendor.js",
+    "core/snapshot.js",
+    // Before save.js: it takes the boot baseline as it evaluates, and a snapshot
+    // transform registered after that made an untouched page read as unsaved.
+    "core/persist.js", "core/admin-attrs.js",
+    "core/save-core.js", "core/save.js",
     "core/save-conflict-notice.js",
-    "core/unsaved-warning.js", "core/persist.js",
-    "core/admin-attrs.js", "core/autosave.js",
+    "core/unsaved-warning.js", "core/autosave.js",
     "attrs/save-freeze.js", "attrs/onaftersave.js", "attrs/refetch-on-save.js",
     "lib/cache-bust.js",
   ],
@@ -32,7 +36,18 @@ export const PLUGIN_PATHS = {
   // superset of the cms's, so the plugin is present exactly when it can be used.
   upload:    { path: "plugins/upload.js",          editOnly: true,  default: false },
   wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
+  // Edit mode only: the AI comment box is an editing gesture, and the plugin is
+  // dormant anyway on any host that does not list a ready `ai-edit` helper.
+  "ai-edit": { path: "plugins/ai-edit.js",         editOnly: true,  default: false },
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
+  // Saves the file's own bytes back instead of a fresh serialization of the DOM.
+  // editOnly because a page that cannot save has nothing to preserve. On by default
+  // because the fallback rate it is judged on can only be collected from real pages,
+  // and a plugin nobody enables produces no number to judge. It costs a 48 KB parser
+  // and one extra request at boot, both in edit mode only, and every save it cannot
+  // verify is sent as the ordinary full serialization, so the floor is the behaviour
+  // it replaces. `exclude=source` turns it off.
+  source:    { path: "plugins/source.js",          editOnly: true,  default: true },
 };
 
 // One literal import per module the loader can ask for, so a bundler can see the
@@ -62,6 +77,7 @@ export const MODULES = {
   "attrs/onaftersave.js":       () => import("./attrs/onaftersave.js"),
   "attrs/refetch-on-save.js":   () => import("./attrs/refetch-on-save.js"),
   "lib/cache-bust.js":          () => import("./lib/cache-bust.js"),
+  "vendor/hyper-morph.vendor.js": () => import("./vendor/hyper-morph.vendor.js"),
   "vendor/richclay.vendor.js":  () => import("./vendor/richclay.vendor.js"),
   "plugins/indicator.js":       () => import("./plugins/indicator.js"),
   "sync/live-sync.js":          () => import("./sync/live-sync.js"),
@@ -71,10 +87,14 @@ export const MODULES = {
   "vendor/quickcrop.vendor.js": () => import("./vendor/quickcrop.vendor.js"),
   "plugins/upload.js":          () => import("./plugins/upload.js"),
   "plugins/wire.js":            () => import("./plugins/wire.js"),
+  "plugins/ai-edit.js":         () => import("./plugins/ai-edit.js"),
   "plugins/demo.js":            () => import("./plugins/demo.js"),
+  "plugins/source.js":          () => import("./plugins/source.js"),
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "demo"];
+// `source` is last on purpose: its install captures a save clone, so it wants every
+// plugin that registers a document transform to have registered it first.
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "ai-edit", "demo", "source"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through
 // a capability lookup (`clay.quickcrop`) and silently uploads the raw file when it
@@ -92,7 +112,9 @@ const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop",
 // This is the only line in the capability that changes how an already-published
 // page behaves, which is why it shipped alone, one release after the plugin it
 // enables. Reverting it is reverting this line.
-const IMPLIES = { cms: ["quickcrop", "upload"] };
+// ai-edit reads `clay.wire.helpers()` and sends through `clay.wire.send`, so a page
+// that asks for it has to have the wire. The wire loads first in the order above.
+const IMPLIES = { cms: ["quickcrop", "upload"], "ai-edit": ["wire"] };
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);

package/src/loader.js

@@ -82,6 +82,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   const snapshot = loaded["core/snapshot.js"];
   const save = loaded["core/save.js"];
   const cacheBustMod = loaded["lib/cache-bust.js"];
+  const hyperMorph = loaded["vendor/hyper-morph.vendor.js"];
 
   if (save) {
     const saveFn = save.savePage || save.default;
@@ -97,6 +98,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   if (cacheBustMod) {
     clay.cacheBust = cacheBustMod.default;
   }
+  if (hyperMorph) clay.morph = hyperMorph.morph;
 }
 
 function attachPluginMember(path, mod) {
@@ -112,12 +114,16 @@ function attachPluginMember(path, mod) {
     clay.upload = mod.upload || mod.default;
   } else if (path === "plugins/wire.js") {
     clay.wire = mod.wire || mod.default;
+  } else if (path === "plugins/ai-edit.js") {
+    clay.aiEdit = mod.aiEdit || mod.default;
   } else if (path === "plugins/demo.js") {
     clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {
     clay.RichClay = mod.RichClay || mod.default;
   } else if (path === "vendor/quickcrop.vendor.js") {
     clay.quickcrop = mod.quickcrop || mod.default;
+  } else if (path === "plugins/source.js") {
+    clay.source = mod.source || mod.default;
   }
 }