@panphora/clayjs 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
   "description": "clayjs: malleable documents. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",

package/src/attrs/add-from.js

@@ -0,0 +1,72 @@
+/**
+ * [add-from] Custom Attribute
+ *
+ * Adds a new item from a <template> on click. Edit mode only: this module is in
+ * the edit-only wave, so a visitor's page never loads it.
+ *
+ * Usage:
+ *   <button add-from="#task-tpl" add-to="#tasks">Add task</button>
+ *
+ * The template's first element is cloned, given a fresh data-id unless it already
+ * has one (templates carry none), and appended to the add-to element. Its first
+ * editable field is focused with its text selected, so typing replaces the
+ * placeholder. Ids are built without crypto.randomUUID, which is missing outside
+ * a secure context.
+ */
+
+const FIELD = '[contenteditable]:not([contenteditable="false"]), input, textarea';
+
+export function newId() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+}
+
+function find(selector) {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
+function focusField(item) {
+  const field = item.matches(FIELD) ? item : item.querySelector(FIELD);
+  if (!field) return;
+  field.focus();
+  if (typeof field.select === "function") return field.select();
+  const range = document.createRange();
+  range.selectNodeContents(field);
+  const selection = window.getSelection();
+  selection.removeAllRanges();
+  selection.addRange(range);
+}
+
+export function addFrom(trigger) {
+  const template = find(trigger.getAttribute("add-from"));
+  const list = find(trigger.getAttribute("add-to"));
+  const blueprint = template?.content?.firstElementChild;
+  if (!blueprint || !list) {
+    console.warn("[add-from] add-from must name a <template> and add-to the element to add into", trigger);
+    return null;
+  }
+  const item = blueprint.cloneNode(true);
+  if (!item.getAttribute("data-id")) item.setAttribute("data-id", newId());
+  list.append(item);
+  focusField(item);
+  return item;
+}
+
+function onClick(event) {
+  const trigger = event.target.closest?.("[add-from]");
+  if (!trigger) return;
+  event.preventDefault();
+  addFrom(trigger);
+}
+
+function init() {
+  document.addEventListener("click", onClick);
+}
+
+init();
+
+export default init;

package/src/core/conflict-notice.js

@@ -37,6 +37,7 @@ const MINIMIZE_SVG = '<svg viewBox="0 0 12 12" width="12" height="12" aria-hidde
 const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 
 const BLOCKED_ROW = "This spot changed again. Review the latest edit or download your copy.";
+const DATA_BLOCKED_ROW = "A data value can't be put back from here. Download your copy to keep yours.";
 
 let view = "hidden";
 let listOpen = false;
@@ -173,10 +174,6 @@ function render() {
     root.append(drawPanel(m));
   }
   set(root, "display", toastText || view !== "hidden" ? "flex" : "none");
-  if (view !== "hidden") {
-    const section = document.querySelector("[data-clay-section-notice]");
-    if (section) set(section, "display", "none");
-  }
   if (wellEl) wellEl.scrollTop = scroll;
 
   const want = pendingFocus || focusKey;
@@ -514,7 +511,7 @@ async function onRevert() {
     document.removeEventListener("focus", track, true);
   }
   busy = null;
-  for (const id of result.blockedIds) blockedRows.set(id, BLOCKED_ROW);
+  for (const id of result.blockedIds) blockedRows.set(id, ledger()?.get(id)?.kind === "json" ? DATA_BLOCKED_ROW : BLOCKED_ROW);
   view = mode() ? "bar" : "hidden";
   pendingFocus = stayed ? "review" : null;
   const saving = result.saveResult && (result.saveResult.ok || result.saveResult.msg === "Save already in progress");

package/src/core/conflict-presentation.js

@@ -262,6 +262,41 @@ function recoveryRow(record, rv) {
   };
 }
 
+// A JSON conflict path ('players[id="alice"].x', 'grid[0][1]', '["a b"]') as the words
+// a person reads: players → alice → x. A keyed segment shows its key's value.
+export function jsonPathWords(path) {
+  const words = [];
+  let i = 0;
+  while (i < path.length) {
+    if (path[i] === ".") { i++; continue; }
+    if (path[i] === "[") {
+      let j = i + 1;
+      let inString = false;
+      for (; j < path.length; j++) {
+        const ch = path[j];
+        if (inString) {
+          if (ch === "\\") j++;
+          else if (ch === '"') inString = false;
+        } else if (ch === '"') inString = true;
+        else if (ch === "]") break;
+      }
+      let inner = path.slice(i + 1, j);
+      const keyed = /^[A-Za-z_$][\w$]*=/.exec(inner);
+      if (keyed) inner = inner.slice(keyed[0].length);
+      try { words.push(String(JSON.parse(inner))); } catch { words.push(inner); }
+      i = j + 1;
+      continue;
+    }
+    let j = i;
+    while (j < path.length && path[j] !== "." && path[j] !== "[") j++;
+    words.push(path.slice(i, j));
+    i = j;
+  }
+  return words.join(" → ");
+}
+
+const jsonValue = (v) => (v === undefined ? "(deleted)" : JSON.stringify(v));
+
 export function rowOf(record) {
   const id = record.id;
   if (record.recovery?.version === 1) return recoveryRow(record, record.recovery);
@@ -283,6 +318,13 @@ export function rowOf(record) {
       yours: both ? side(plain(record.local)) : null, now: both ? side(plain(record.remote)) : null, sentence,
     };
   }
+  if (record.kind === "json") {
+    const where = jsonPathWords(record.path || "");
+    return {
+      id, kind: "json", name: where ? `${record.name} → ${where}` : record.name, target: null,
+      yours: side(jsonValue(record.local)), now: side(jsonValue(record.resolved)), sentence: null,
+    };
+  }
   const host = hostOf(record.node);
   const el = elementOf(record.node);
   const name = el && HIDDEN.has(el.localName) ? kindName(el)

package/src/core/save-core.js

@@ -43,6 +43,20 @@ let nextSaveKeepalive = false;
 // CustomEvent would put it on a bus any script on the page can listen to.
 const saveAcceptedHooks = [];
 
+// Headers another module asks every save to carry, by name.
+const extraSaveHeaders = new Map();
+
+/**
+ * Add a header to every save from now on, or remove it with a null value.
+ *
+ * @param {string} name
+ * @param {string|null} value
+ */
+export function setSaveHeader(name, value) {
+  if (value == null) extraSaveHeaders.delete(name);
+  else extraSaveHeaders.set(name, String(value));
+}
+
 /**
  * Send the next save with `keepalive`, so a request whose page is going away (a tab
  * closing, a navigation) is still finished by the transport.
@@ -238,6 +252,11 @@ function errorResult(err) {
     // Live sync compares it with the frames it merges to know when the refusal
     // is answered.
     conflictEtag: conflicted ? (err.etag ?? null) : null,
+    // The host's answer, null when none came (a lost connection or a timeout).
+    status: Number.isInteger(err.status) ? err.status : null,
+    // An attempt of this save timed out, so it may have landed whatever the
+    // final answer says.
+    hadTimeout: timedOut || err.hadTimeout === true,
     etag: null
   };
 }
@@ -312,6 +331,8 @@ function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive =
     body: content
   };
 
+  for (const [name, value] of extraSaveHeaders) options.headers[name] = value;
+
   if (etag) options.headers['If-Match'] = etag;
 
   if (keepalive && new Blob([content]).size < KEEPALIVE_MAX_BODY) options.keepalive = true;
@@ -559,6 +580,7 @@ async function sendSave(content) {
     try {
       return await sendOnce(content, saveId, etag);
     } catch (err) {
+      if (reSent) err.hadTimeout = true;
       if (err.name === 'AbortError') {
         if (reSent) throw err;
         const { landed, resend, etag: original } = await recoverUnknownSave();

package/src/core/save.js

@@ -221,6 +221,13 @@ export function resumeAutosave() {
   savePageThrottled();
 }
 
+// Whether an agent's request currently holds autosave off. A caller that forces a
+// save on its own schedule (live data checkpoints) asks this first, because a
+// forced save would write the browser's bytes over the agent's.
+export function autosaveIsSuspended() {
+  return autosaveSuspended > 0;
+}
+
 // ============================================
 // THE ALL-SAVE HOLD
 // ============================================
@@ -372,15 +379,17 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken, forS
   } else if (result.msgType === 'conflict') {
     holdForConflict(result.conflictEtag);
     setSaveState('conflict', result.msg, result.msgType, {
+      hadTimeout: result.hadTimeout === true,
       changedBy: result.changedBy ?? null,
       afterTimeout: result.afterTimeout === true,
       etag: result.conflictEtag ?? null,
     });
   } else if (result.msgType !== 'skipped') {
+    const extra = { status: result.status ?? null, hadTimeout: result.hadTimeout === true };
     if (!navigator.onLine) {
-      setSaveState('offline', result.msg);
+      setSaveState('offline', result.msg, '', extra);
     } else {
-      setSaveState('error', result.msg);
+      setSaveState('error', result.msg, '', extra);
     }
   }
 }

package/src/lib/region-capabilities.js

@@ -21,6 +21,7 @@ export const POLICY_TOKENS = Object.freeze([
   'no-data',
   'freeze',
   'editor-ui',
+  'live',
 ])
 
 export function hasPolicyToken(element, token) {

package/src/lib/region-policy.js

@@ -49,7 +49,7 @@ import { capabilitySelector, expandsTo, hasCapability, hasPolicyToken, POLICY_TO
 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', 'no-data', 'freeze', 'editor-ui'];
+export const REGION_ATTRS = ['no-save', 'no-trigger-autosave', 'no-dirty', 'no-undo', 'no-watch', 'no-data', 'freeze', 'editor-ui', 'live'];
 
 // Every canonical token spellable inside the space-separated `clay` attribute.
 // Exported: this list used to exist as a private CLAY_TOKENS that nothing read,
@@ -83,7 +83,7 @@ export const FREEZE_SELECTOR = '[clay~="freeze"], [freeze], [save-freeze]';
 // 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~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-trigger-autosave], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
+  '[clay~="no-save"], [clay~="no-trigger-autosave"], [clay~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-trigger-autosave], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore], [clay~="live"]';
 
 // Every spelling of no-trigger-autosave: the ONE difference between the autosave
 // domain and the dirty domain. A document containing none of these has identical
@@ -94,6 +94,10 @@ export const STRIP_FROM_COMPARISON =
 export const NO_TRIGGER_AUTOSAVE_SELECTOR =
   '[clay~="no-trigger-autosave"], [no-trigger-autosave]';
 
+// Live JSON stores (clay="live" on a merge= JSON script). Saved, stripped from both
+// comparison domains, and ignored by the live-sync merge: the live plugin owns the value.
+export const LIVE_SELECTOR = '[clay~="live"]';
+
 // Disposable regions: saved, but their content is explicitly not work. Stripped
 // from BOTH comparison domains, skipped by the merge on both sides, and never
 // counted by the close warning. This is the declared signal that lets the merge
@@ -108,7 +112,7 @@ export const NO_DIRTY_SELECTOR =
 // dirty-tracked either, and counting it would re-freeze the live-sync baseline
 // the way the mounted-tool bug did (see dirty-gate.js).
 export const STRIP_FROM_DIRTY_CHECK =
-  '[clay~="no-save"], [clay~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore]';
+  '[clay~="no-save"], [clay~="no-dirty"], [clay~="freeze"], [clay~="no-watch"], [no-save], [save-remove], [no-dirty], [save-ignore], [freeze], [save-freeze], [no-watch], [mutations-ignore], [clay~="live"]';
 
 // Snapshot-layer marker: removed from EVERY snapshot (save, live-sync broadcast,
 // dirty-comparison) in snapshot.js. `no-snapshot` is the consistent alias for the
@@ -163,6 +167,9 @@ export function resolveRegionPolicy(node) {
       if (expandsTo(element, 'no-watch')) watched = false;
       if (hasRegionToken(element, 'no-trigger-autosave')) autosaveOff = true;
       if (hasRegionToken(element, 'no-dirty')) { autosaveOff = true; dirtyOff = true; }
+      // A live JSON store: saved, but its value lives in memory and the live plugin
+      // writes it into each save clone, so the tag itself is never work to track.
+      if (hasRegionToken(element, 'live')) { autosaveOff = true; dirtyOff = true; undoable = false; }
       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);

package/src/live/checkpoint.js

@@ -0,0 +1,106 @@
+// Checkpoints for clay.live stores. A live change never marks the page unsaved
+// (live tags are outside the comparison domains), so nothing else would ever save
+// it. This does: at a fixed deadline CHECKPOINT_MS after the first unsaved change,
+// so a steady stream of moves still saves on time, and once more, right away,
+// when the tab is hidden or closed.
+
+export const CHECKPOINT_MS = 8000;
+export const RETRY_MS = 1000;
+
+/**
+ * @param {object} deps
+ * @param {() => boolean} deps.needsSave - is there a live change no accepted save holds
+ * @param {() => boolean} deps.blocked - must a save wait (settling, conflict, agent editing)
+ * @param {() => Promise<object>} deps.save - the checkpoint save; resolves { ok, msgType }
+ * @param {() => unknown} deps.saveNow - the hide/close save, sent with keepalive
+ */
+export function createCheckpoints({ needsSave, blocked, save, saveNow, now = () => Date.now(), setTimer = setTimeout, clearTimer = clearTimeout }) {
+  let deadline = null;
+  let timer = null;
+  let running = false;
+  let flushing = false;
+  // After a save that did not land, no save before this time (soon included).
+  let retryAt = 0;
+
+  function after(result) {
+    const skipped = result && !result.ok && result.msgType === "skipped";
+    retryAt = result?.ok || skipped ? 0 : now() + CHECKPOINT_MS;
+    return skipped ? RETRY_MS : CHECKPOINT_MS;
+  }
+
+  function arm(at) {
+    deadline = at;
+    if (timer !== null) clearTimer(timer);
+    timer = setTimer(run, Math.max(0, at - now()));
+  }
+
+  function disarm() {
+    if (timer !== null) clearTimer(timer);
+    timer = null;
+    deadline = null;
+  }
+
+  async function run() {
+    timer = null;
+    deadline = null;
+    if (!needsSave()) return;
+    if (blocked()) {
+      arm(now() + RETRY_MS);
+      return;
+    }
+    running = true;
+    let result = null;
+    try {
+      result = await save();
+    } catch {
+      result = null;
+    } finally {
+      running = false;
+    }
+    const wait = after(result);
+    if (!needsSave()) return;
+    // A save skipped because another was on the wire is retried soon; anything
+    // else waits a full interval, so a failing host is not asked every second.
+    arm(now() + wait);
+  }
+
+  return {
+    // A live change happened. The first one after a save starts the clock; later
+    // ones do not move it.
+    changed() {
+      if (deadline === null && !running) arm(now() + CHECKPOINT_MS);
+    },
+    // The tab is going away or out of sight: save now if anything is unsaved.
+    // A save that did not land arms the clock again, as run() does.
+    flush() {
+      if (running || !needsSave() || blocked()) return;
+      disarm();
+      running = true;
+      flushing = true;
+      Promise.resolve()
+        .then(saveNow)
+        .catch(() => null)
+        .then((result) => {
+          running = false;
+          flushing = false;
+          const wait = after(result);
+          if (!needsSave()) return;
+          arm(now() + wait);
+        });
+    },
+    // Save as soon as possible: the room asks for it (its log is half full, or
+    // the file holds a version the room cannot rebuild from).
+    soon() {
+      if (running) return;
+      const at = Math.max(now(), retryAt);
+      if (deadline === null || at < deadline) arm(at);
+    },
+    // True while the hide/close save is being made.
+    get flushing() {
+      return flushing;
+    },
+    get deadline() {
+      return deadline;
+    },
+  };
+}