@panphora/clayjs 1.10.0 → 1.11.1

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;
+    },
+  };
+}