@panphora/clayjs 0.1.0

package/src/lib/query.js

@@ -0,0 +1,3 @@
+const query = Object.fromEntries(new URLSearchParams(window.location.search));
+
+export default query;

package/src/lib/region-policy.js

@@ -0,0 +1,220 @@
+/**
+ * region-policy.js — the region capability model.
+ *
+ * A region declares how it participates in the framework via a small set of
+ * orthogonal tokens. The canonical spelling is the space-separated `clay`
+ * attribute (`clay="no-save no-undo"`); bare naked attributes are still
+ * resolved for back-compat. They apply to an element and its descendants:
+ *
+ *   no-save               — not written to the saved file (stripped). Live at runtime.
+ *   no-trigger-autosave   — saved, but editing it doesn't trigger an autosave / mark dirty.
+ *   no-undo               — edits here are not recorded in the undo stack.
+ *   no-watch              — invisible to the whole mutation system (high-churn regions). Still saved.
+ *   freeze                — saved as authored (runtime changes not persisted). Live at runtime.
+ *
+ * Four legacy markers map onto bundles of the above for back-compat. They all
+ * additionally gain "watched" (behaviors now run inside them):
+ *
+ *   mutations-ignore  ->  no-watch
+ *   save-remove       ->  no-save  no-undo
+ *   save-ignore       ->  no-trigger-autosave  no-undo
+ *   save-freeze       ->  freeze  no-undo
+ *
+ * Separately, a snapshot-layer marker controls whether an element appears in any
+ * snapshot at all (save file, live-sync broadcast, and dirty-comparison):
+ *
+ *   snapshot-remove / no-snapshot  — removed from every snapshot. Runtime-only
+ *     local chrome. hyper-morph also treats it as sync-ignored, so a live-sync
+ *     receiver preserves its own copy instead of deleting it. Handled in
+ *     snapshot.js, not by the policy axes below; no-snapshot is the consistent
+ *     alias for the original snapshot-remove.
+ *
+ * resolveRegionPolicy() walks an element's self-or-ancestor chain once and
+ * returns the four independent axes the rest of the framework keys off:
+ *   { watched, autosaveTriggered, undoable, persist, extension }
+ */
+
+import { EXTENSION_NODE_SELECTOR } from './extension-noise.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-undo', 'no-watch', 'freeze'];
+
+// Canonical tokens spellable inside the space-separated `clay` attribute.
+const CLAY_TOKENS = ["no-save", "no-snapshot", "no-trigger-autosave", "no-watch", "no-undo", "freeze"];
+
+// 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
+}
+
+// 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 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 /
+// mutations-ignore footgun (their content stays in the saved file, but is no
+// longer counted as a change).
+export const STRIP_FROM_COMPARISON =
+  '[clay~="no-save"], [clay~="no-trigger-autosave"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-trigger-autosave], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
+
+// Snapshot-layer marker: removed from EVERY snapshot (save, live-sync broadcast,
+// 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 function isSnapshotRemoved(el) {
+  return hasRegionToken(el, 'snapshot-remove') || hasRegionToken(el, 'no-snapshot');
+}
+
+const PERSIST_RANK = { full: 0, frozen: 1, none: 2 };
+const RANK_PERSIST = ['full', 'frozen', 'none'];
+
+function startElement(node) {
+  return node && node.nodeType !== 1 ? node.parentElement : node;
+}
+
+/**
+ * Walk an element's self-or-ancestor chain once and resolve its region axes.
+ *
+ * @param {Node} node
+ * @returns {{watched:boolean, autosaveTriggered:boolean, undoable:boolean, persist:string, extension:boolean}}
+ */
+export function resolveRegionPolicy(node) {
+  let element = startElement(node);
+
+  // Browser-extension injected content is never page content, for any consumer.
+  if (element && element.closest && element.closest(EXTENSION_NODE_SELECTOR)) {
+    return { watched: false, autosaveTriggered: false, undoable: false, persist: PERSIST.FULL, extension: true };
+  }
+
+  let watched = true;
+  let undoable = true;
+  let autosaveOff = false;
+  let persistRank = 0;
+
+  while (element && element.nodeType === 1) {
+    if (element.hasAttribute) {
+      // new naked attributes
+      if (hasRegionToken(element, 'no-watch')) watched = false;
+      if (hasRegionToken(element, 'no-trigger-autosave')) autosaveOff = true;
+      if (hasRegionToken(element, 'no-undo')) undoable = false;
+      if (hasRegionToken(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;
+      if (hasRegionToken(element, 'save-remove')) { persistRank = Math.max(persistRank, PERSIST_RANK.none); undoable = false; }
+      if (hasRegionToken(element, 'save-ignore')) { autosaveOff = true; undoable = false; }
+      if (hasRegionToken(element, 'save-freeze')) { persistRank = Math.max(persistRank, PERSIST_RANK.frozen); undoable = false; }
+    }
+    element = element.parentElement;
+  }
+
+  // Implication rules (no-save wins over freeze automatically via Math.max above):
+  //   no-watch  ⟹ no autosave + no undo (can't track what isn't watched)
+  //   no-save / freeze ⟹ no autosave (nothing live to persist)
+  if (!watched) { autosaveOff = true; undoable = false; }
+  if (persistRank > 0) autosaveOff = true;
+
+  return {
+    watched,
+    autosaveTriggered: !autosaveOff,
+    undoable,
+    persist: RANK_PERSIST[persistRank],
+    extension: false,
+  };
+}
+
+/**
+ * Cheap intake-level check: is a node invisible to EVERY consumer?
+ *
+ * Only no-watch / mutations-ignore (and extension noise) qualify — they're the
+ * one universal drop, so the observer can skip walking those subtrees entirely.
+ * All other region attributes are resolved per-consumer in Mutation._notify.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export function isInert(node) {
+  let element = startElement(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'))) {
+      return true;
+    }
+    element = element.parentElement;
+  }
+  return false;
+}
+
+/**
+ * Combine two resolved policies into the stricter of each axis. Used to merge a
+ * removed (detached) element's own markers with its still-attached parent's.
+ */
+export function strictestPolicy(a, b) {
+  return {
+    watched: a.watched && b.watched,
+    autosaveTriggered: a.autosaveTriggered && b.autosaveTriggered,
+    undoable: a.undoable && b.undoable,
+    persist: PERSIST_RANK[a.persist] >= PERSIST_RANK[b.persist] ? a.persist : b.persist,
+    extension: a.extension || b.extension,
+  };
+}
+
+// Literal `skip:[...]` escape-hatch tokens -> axis predicate.
+const SKIP_TOKEN_PREDICATES = {
+  'no-watch': p => !p.watched,
+  'mutations-ignore': p => !p.watched,
+  'no-save': p => p.persist === PERSIST.NONE,
+  'save-remove': p => p.persist === PERSIST.NONE,
+  'freeze': p => p.persist === PERSIST.FROZEN,
+  'save-freeze': p => p.persist === PERSIST.FROZEN,
+  'no-trigger-autosave': p => !p.autosaveTriggered,
+  'save-ignore': p => !p.autosaveTriggered,
+  'no-undo': p => !p.undoable,
+};
+
+/**
+ * Should a consumer skip a change in this region?
+ *
+ * @param {object} policy   resolved region policy
+ * @param {string} [require] axis the consumer needs: 'observed' | 'autosave' | 'undo'
+ * @param {string[]} [skip]  literal attribute escape-hatch (any match -> skip)
+ * @returns {boolean}
+ */
+export function skipForPolicy(policy, require, skip) {
+  if (policy.extension) return true;
+  if (skip && skip.length) {
+    return skip.some(tok => SKIP_TOKEN_PREDICATES[tok]?.(policy) || false);
+  }
+  switch (require) {
+    case 'observed': return !policy.watched;
+    case 'autosave': return !policy.autosaveTriggered;
+    case 'undo': return !policy.undoable;
+    default:
+      // No require declared: preserve the legacy four-marker skip so unmodified
+      // consumers behave exactly as before. (Undo-only opt-outs still pass.)
+      return !policy.watched || !policy.autosaveTriggered || policy.persist !== PERSIST.FULL;
+  }
+}
+
+// The canonical region API the vendored hyper-undo (a separate bundle that can't
+// import this module) delegates "is this undoable?" to via window.hyperclay.region,
+// so the two can no longer drift. The loader assembles this onto the compat shim.
+export const windowRegionShape = {
+  resolveRegionPolicy,
+  isInert,
+  skipForPolicy,
+  strictestPolicy,
+  PERSIST,
+  REGION_ATTRS,
+  STRIP_FROM_SAVE,
+  FREEZE_SELECTOR,
+  STRIP_FROM_COMPARISON,
+};

package/src/lib/throttle.js

@@ -0,0 +1,41 @@
+function throttle(callback, delay, executeFirst = true) {
+  let lastCall = executeFirst ? 0 : Date.now();
+  let timeoutId = null;
+  let pendingResolvers = [];
+
+  return function (...args) {
+    const ctx = this;
+    const now = Date.now();
+    const remaining = delay - (now - lastCall);
+
+    return new Promise((resolve) => {
+      if (remaining <= 0) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+        lastCall = now;
+
+        const resolvers = pendingResolvers.concat(resolve);
+        pendingResolvers = [];
+
+        Promise.resolve(callback.apply(ctx, args))
+          .then(value => { for (const r of resolvers) r(value); });
+      } else {
+        pendingResolvers.push(resolve);
+
+        if (!timeoutId) {
+          timeoutId = setTimeout(() => {
+            lastCall = Date.now();
+            timeoutId = null;
+            const resolvers = pendingResolvers;
+            pendingResolvers = [];
+
+            Promise.resolve(callback.apply(ctx, args))
+              .then(value => { for (const r of resolvers) r(value); });
+          }, remaining);
+        }
+      }
+    });
+  };
+}
+
+export default throttle;

package/src/lib/user-gesture.js

@@ -0,0 +1,126 @@
+/**
+ * user-gesture — the "was a human driving this write?" signal for the
+ * data-clobber guard. Small and dedicated (NOT behaviorCollector, which is the
+ * analytics collector).
+ *
+ * How it works: capture-phase listeners for trusted user-intent events stamp
+ * `lastTrustedGestureTs` (and set a same-turn `gestureTaskActive` flag, cleared
+ * on the next macrotask). The Mutation hub calls `isUserDrivenNow()`
+ * synchronously when it processes a DOM change. A change reads as user-driven if
+ * it lands in the same turn as a gesture OR within `RECENT_GESTURE_MS` of the
+ * last trusted gesture. The recency window is what attributes CROSS-TURN
+ * first-party edits: a button's `click` handler runs a turn after its
+ * `pointerdown`, and a confirm-modal delete runs a macrotask after the Confirm
+ * gesture (theModal defers its resolve via setTimeout) — both mutate a few ms
+ * after the gesture, inside the window. A background setTimeout / fetch().then()
+ * mutation with no recent gesture reads background. Synthetic dispatchEvent /
+ * el.click() are isTrusted=false, so a script can't fake a gesture.
+ *
+ * Why a bounded recency window and not `navigator.userActivation`: its transient
+ * window is ~5s and consumable — too loose for a recovery tool, since a
+ * background clobber within 5s of any click would read user-driven and suppress
+ * the chip (silent data loss). `RECENT_GESTURE_MS` is an owned, tight window
+ * stamped only by trusted gestures, so it's unspoofable and an order of
+ * magnitude less exposed.
+ *
+ * The accumulated bit rides every save the page makes; the server splits a
+ * UI-gestured save from a background-script save with it.
+ */
+
+// `change` and `submit` are included intentionally. Both are reachable with
+// isTrusted=true from script (checkbox.click(), form.requestSubmit(), a
+// submit-button .click()), so a nefarious script could fake a gesture and suppress
+// the chip. That is out of scope by design: this panel catches ACCIDENTAL
+// deletion, not malicious intent, and we assume scripts are helpful. Listening for
+// them attributes legitimate script- or control-driven form edits as driven, which
+// avoids false-positive chips. (A synthetic dispatchEvent stays isTrusted=false.)
+const GESTURE_EVENTS = ['pointerdown', 'pointerup', 'click', 'keydown', 'beforeinput', 'change', 'submit', 'paste', 'drop', 'cut'];
+
+// A cross-turn first-party edit (click handler, confirm-modal delete) mutates
+// within a few ms of its trusted gesture; 500ms is ample margin while keeping
+// the false-negative window (a background clobber near a gesture) an order of
+// magnitude tighter than navigator.userActivation's ~5s.
+const RECENT_GESTURE_MS = 500;
+
+let gestureTaskActive = false;
+let lastTrustedGestureTs = -Infinity;
+let userDrivenSinceLastSave = false;
+let installed = false;
+
+// Monotonic clock for the recency window — never moves backward, so a system
+// clock change can't widen or break the window (Date.now() can jump).
+function now() {
+  return (typeof performance !== 'undefined' && performance.now) ? performance.now() : Date.now();
+}
+
+function markGestureTurn() {
+  gestureTaskActive = true;
+  lastTrustedGestureTs = now();
+  // Clear the same-turn flag on the next macrotask. The MutationObserver
+  // microtask for a change made synchronously in this turn drains BEFORE this
+  // fires; cross-turn changes fall back to the recency window above.
+  setTimeout(() => { gestureTaskActive = false; }, 0);
+}
+
+function onGesture(e) {
+  if (!e || !e.isTrusted) return;
+  markGestureTurn();
+}
+
+/**
+ * Install the capture-phase gesture listeners (idempotent). Call once in edit
+ * mode (autosave.js and data-loss-panel both do this).
+ */
+export function initUserGesture() {
+  if (installed || typeof document === 'undefined') return;
+  installed = true;
+  for (const type of GESTURE_EVENTS) {
+    document.addEventListener(type, onGesture, true);
+  }
+}
+
+/**
+ * True iff a trusted gesture drove this exact turn, OR one happened within
+ * RECENT_GESTURE_MS. The Mutation hub calls this synchronously per change batch.
+ */
+export function isUserDrivenNow() {
+  if (gestureTaskActive) return true;
+  return (now() - lastTrustedGestureTs) < RECENT_GESTURE_MS;
+}
+
+/**
+ * Record that an autosave-relevant change happened in a user-driven turn. Called
+ * by the Mutation hub (per autosave-filtered batch) and by the [persist] input
+ * path (a trusted input is itself the gesture+change).
+ */
+export function markUserDriven() {
+  userDrivenSinceLastSave = true;
+}
+
+/**
+ * Read-and-reset the accumulated bit. Called at the ACTUAL save send (not on a
+ * save that never ships), so it survives the autosave debounce and coalescing.
+ * @returns {boolean}
+ */
+export function consumeUserDriven() {
+  const v = userDrivenSinceLastSave;
+  userDrivenSinceLastSave = false;
+  return v;
+}
+
+/** Test seam: force-reset state. */
+export function _resetUserGesture() {
+  gestureTaskActive = false;
+  lastTrustedGestureTs = -Infinity;
+  userDrivenSinceLastSave = false;
+}
+
+/**
+ * Test seam: open a gesture turn as a trusted event would, without a real
+ * trusted event (jsdom can't forge isTrusted). Same semantics as onGesture: the
+ * turn is active synchronously and cleared on the next macrotask, and the
+ * recency timestamp is stamped.
+ */
+export function _simulateGestureTurn() {
+  markGestureTurn();
+}

package/src/loader-logic.js

@@ -0,0 +1,62 @@
+export const CORE_WAVES = {
+  always: [
+    "lib/mutation.js",     // first: everything hangs off the hub; cms/sync need it in view mode too
+    "core/edit-mode.js",   // both modes — matches today: 'edit-mode' is NOT in EDIT_MODE_ONLY
+                           // (hyperclay.js:251-273 lists 'edit-mode-helpers', not 'edit-mode');
+                           // toggleEditMode must exist in view mode, it's the way IN
+  ],
+  editOnly: [
+    "core/snapshot.js", "core/save-core.js", "core/save.js",
+    "core/unsaved-warning.js", "core/persist.js",
+    "core/admin-attrs.js", "core/autosave.js",
+    "attrs/save-freeze.js", "attrs/onaftersave.js", "attrs/refetch-on-save.js",
+    "lib/cache-bust.js",
+  ],
+};
+
+export const PLUGIN_PATHS = {
+  richclay:  { path: "vendor/richclay.vendor.js",  editOnly: true,  default: true },
+  indicator: { path: "plugins/indicator.js",       editOnly: true,  default: false },
+  sync:      { path: "sync/live-sync.js",          editOnly: false, default: false },
+  sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
+  undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
+  cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+};
+
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync"];
+
+function parseCsv(params, key, enabled, apply) {
+  const raw = params.get(key);
+  if (!raw) return;
+  for (const token of raw.split(",")) {
+    const name = token.trim();
+    if (!name) continue;
+    if (!PLUGIN_PATHS[name]) {
+      console.warn(`clayjs: unknown plugin "${name}"`);
+      continue;
+    }
+    apply(enabled, name);
+  }
+}
+
+export function resolveModules(params, isEditMode) {
+  const core = [...CORE_WAVES.always];
+  if (isEditMode) core.push(...CORE_WAVES.editOnly);
+
+  const enabled = new Set();
+  for (const [name, spec] of Object.entries(PLUGIN_PATHS)) {
+    if (spec.default) enabled.add(name);
+  }
+  parseCsv(params, "plugins", enabled, (set, name) => set.add(name));
+  parseCsv(params, "exclude", enabled, (set, name) => set.delete(name));
+
+  const plugins = [];
+  for (const name of PLUGIN_ORDER) {
+    if (!enabled.has(name)) continue;
+    const spec = PLUGIN_PATHS[name];
+    if (spec.editOnly && !isEditMode) continue;
+    plugins.push(spec.path);
+  }
+
+  return { core, plugins };
+}

package/src/loader.js

@@ -0,0 +1,123 @@
+import { resolveModules } from "./loader-logic.js";
+import onDomReady from "./lib/dom-ready.js";
+
+function domReady() {
+  return new Promise((resolve) => onDomReady(resolve));
+}
+
+export async function boot(base, params, readyResolve) {
+  await domReady();                                    // Mutation observes document.body
+                                                       // unconditionally, and a <head> placement
+                                                       // would otherwise observe null
+
+  const editMode = await import(base + "/src/core/is-edit-mode.js");
+  const { isEditMode, isOwner } = editMode;
+
+  // richclay's vendor build detects edit mode via this legacy global; set it
+  // before any plugin import so its autoInit sees the right value. Overwrite
+  // even a pre-set value: resolution already consumed it (lowest precedence),
+  // and a conflicting leftover would make richclay disable itself.
+  window.__hyperclayEditMode = isEditMode;
+
+  const regionPolicy = await import(base + "/src/lib/region-policy.js");
+
+  const plan = resolveModules(params, isEditMode);
+  const loaded = {};
+
+  for (const path of plan.core) {
+    loaded[path] = await import(base + "/src/" + path); // sequential: order is load-bearing
+  }
+
+  assembleCore(loaded, { isEditMode, isOwner }, regionPolicy); // window.clay + shim MUST exist
+                                                               // before any plugin import
+
+  for (const path of plan.plugins) {
+    const mod = await import(base + "/src/" + path);
+    loaded[path] = mod;
+    attachPluginMember(path, mod);   // immediately, not after the loop: hypercms's ?cms=true
+                                     // auto-open runs as a microtask queued during ITS evaluation
+                                     // (before boot resumes) and reads window.hyperclay.RichClay
+                                     // and .undo, which earlier plugins must have mirrored by then
+  }
+
+  // Plugins with async setup (sortable's vendor fetch) export `ready`; hold
+  // clay.ready until they finish. allSettled: a failed plugin degrades, never blocks boot.
+  await Promise.allSettled(plan.plugins.map((path) => loaded[path]?.ready).filter(Boolean));
+
+  installViewModeNotice(isEditMode);
+  readyResolve(window.clay);
+  document.dispatchEvent(new CustomEvent("clay:ready", { detail: { clay: window.clay } }));
+}
+
+function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
+  const clay = window.clay;
+
+  const mutation = loaded["lib/mutation.js"];
+  const editModeMod = loaded["core/edit-mode.js"];
+
+  Object.assign(clay, {
+    toggleEditMode: editModeMod.toggleEditMode,
+    isEditMode,
+    isOwner,
+    Mutation: mutation.default,
+  });
+
+  const snapshot = loaded["core/snapshot.js"];
+  const save = loaded["core/save.js"];
+  const cacheBustMod = loaded["lib/cache-bust.js"];
+
+  if (save) {
+    const saveFn = save.savePage || save.default;
+    saveFn.force = save.savePageForce;
+    clay.save = saveFn;
+  }
+  if (snapshot) {
+    clay.getHTML = snapshot.getPageContents;
+    clay.beforeSave = snapshot.beforeSave;
+    clay.onSnapshot = snapshot.onSnapshot;
+  }
+  if (cacheBustMod) {
+    clay.cacheBust = cacheBustMod.default;
+  }
+
+  // vendor-compat shim: richclay, hypercms, and hyper-undo read window.hyperclay;
+  // remove when the vendors migrate to window.clay.
+  window.hyperclay = window.hyperclay || {};
+  Object.assign(window.hyperclay, {
+    Mutation: clay.Mutation,
+    isEditMode: clay.isEditMode,
+    region: regionPolicy.windowRegionShape,
+  });
+  if (clay.beforeSave) {
+    window.hyperclay.beforeSave = clay.beforeSave;        // richclay's save-cleanup hook
+    window.hyperclay.onPrepareForSave = clay.beforeSave;  // hypercms uses this name
+  }
+  if (clay.save) {
+    window.hyperclay.savePage = clay.save;
+  }
+}
+
+function attachPluginMember(path, mod) {
+  const clay = window.clay;
+
+  if (path === "plugins/undo.js") {
+    clay.undo = mod.undo || mod.default;
+    window.hyperclay.undo = clay.undo;
+  } else if (path === "sync/live-sync.js") {
+    clay.morph = mod.morph;
+  } else if (path === "vendor/hypercms.vendor.js") {
+    clay.cms = mod.cms || mod.default;
+    window.hyperclay.hypercms = clay.cms;
+  } else if (path === "vendor/richclay.vendor.js") {
+    window.hyperclay.RichClay = mod.RichClay || mod.default;
+  }
+}
+
+function installViewModeNotice(isEditMode) {
+  if (isEditMode) return;
+  document.addEventListener("click", (event) => {
+    if (!event.target.closest?.("[trigger-save]")) return;
+    console.info("clayjs: you're not the owner of this page; changes stay local");
+    document.dispatchEvent(new CustomEvent("clay:view-save-attempt"));
+  });
+}

package/src/plugins/indicator.js

@@ -0,0 +1,51 @@
+import { isEditMode } from "../core/is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+
+const LABELS = {
+  saving: "Saving…",
+  saved: "Saved",
+  error: "Couldn't save",
+  offline: "Offline, not saved",
+};
+
+let el = null;
+let hideTimer = null;
+
+function ensure() {
+  if (el) return el;
+  el = document.createElement("div");
+  el.setAttribute("clay", "no-save no-watch no-snapshot");
+  el.setAttribute("data-clay-indicator", "");
+  el.setAttribute("role", "status");
+  el.style.cssText = [
+    "position:fixed", "right:16px", "bottom:16px", "z-index:2147483000",
+    "padding:4px 12px", "border-radius:999px",
+    "font:13px/1.6 system-ui,-apple-system,sans-serif",
+    "background:var(--clay-indicator-bg,#2e2b27)",
+    "color:var(--clay-indicator-ink,#f2f0eb)",
+    "opacity:0", "transition:opacity .25s", "pointer-events:none",
+  ].join(";");
+  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) el.style.transition = "none";
+  document.body.appendChild(el);
+  return el;
+}
+
+function show(state) {
+  const node = ensure();
+  node.textContent = LABELS[state];
+  node.dataset.state = state;
+  node.style.background = state === "error" || state === "offline"
+    ? "var(--clay-indicator-error-bg,#7a3b28)" : "var(--clay-indicator-bg,#2e2b27)";
+  node.style.opacity = "1";
+  clearTimeout(hideTimer);
+  if (state !== "saving") hideTimer = setTimeout(() => { node.style.opacity = "0"; }, 2200);
+}
+
+function init() {
+  if (!isEditMode) return;
+  for (const state of Object.keys(LABELS)) {
+    document.addEventListener("clay:save-" + state, () => show(state));
+  }
+}
+
+onDomReady(init);