@panphora/clayjs 1.9.2 → 1.11.0

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/core/snapshot.js

@@ -41,7 +41,7 @@
 import { stripExtensionNoise } from '../lib/extension-noise.js';
 import { restoreAuthoredUrls } from '../lib/authored-url.js';
 import { STRIP_FROM_SAVE, STRIP_FROM_COMPARISON, STRIP_FROM_DIRTY_CHECK, NO_TRIGGER_AUTOSAVE_SELECTOR, SNAPSHOT_REMOVE_SELECTOR } from '../lib/region-policy.js';
-import { TAB_LOCAL_ROOT_ATTRS } from '../lib/root-attrs.js';
+import { TAB_LOCAL_ROOT_ATTRS, stripRouteAttrs } from '../lib/root-attrs.js';
 import { createContentView } from '../lib/content-dom.js';
 
 // =============================================================================
@@ -277,6 +277,9 @@ export function captureSnapshot({ flushUndo = true, authored = true } = {}) {
   // snapshot so it never reaches a save, a comparison, or a live-sync broadcast.
   stripExtensionNoise(clone);
 
+  // Router state says where this tab is, not what the document holds.
+  stripRouteAttrs(clone);
+
   return clone;
 }
 

package/src/core/source-map.js

@@ -1,7 +1,7 @@
 /**
  * source-map.js — save the file, not a serialization of it.
  *
- * Every program that edits a malleable HTML file rewrites the whole file, because
+ * Every program that edits a malleable document rewrites the whole file, because
  * each one parses to a tree and serializes the tree back out, and a serializer does
  * not reproduce its input. A no-edit save through `clone.outerHTML` rewrites about
  * 88% of an authored document's lines: attributes reorder, quoting normalises, `&`

package/src/lib/mutation.js

@@ -69,7 +69,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 { ROOT_LIBRARY_ATTRS, ROUTE_ROOT_PREFIX, ROUTE_ACTIVE_ATTR } from './root-attrs.js';
 
 import { isUserDrivenNow, markUserDriven } from './user-gesture.js';
 
@@ -83,12 +83,15 @@ const dummyElem = document.createElement("div");
 // instead of body. The raw lane is deliberately unfiltered ("raw means raw"), so
 // without this every save would push a savestatus flip into undo's record stream
 // and Cmd+Z after a save would undo that instead of the user's edit.
+// Router state (route-* on the root, route-active anywhere) is dropped here for the same reason.
 const ROOT_LIBRARY_ATTR_SET = new Set(ROOT_LIBRARY_ATTRS);
 
 function isLibraryRootAttr(record) {
-  return record.type === 'attributes'
-    && record.target === document.documentElement
-    && ROOT_LIBRARY_ATTR_SET.has(record.attributeName);
+  if (record.type !== 'attributes') return false;
+  const name = record.attributeName;
+  if (name === ROUTE_ACTIVE_ATTR) return true;
+  return record.target === document.documentElement
+    && (ROOT_LIBRARY_ATTR_SET.has(name) || name.startsWith(ROUTE_ROOT_PREFIX));
 }
 
 function withoutLibraryNoise(records) {
@@ -127,6 +130,7 @@ const localMutation = {
    * Always pair with resume() in a try/finally block.
    */
   pause() {
+    if (this._pauseDepth === 0) this._deliverBeforePause();
     // Reference-counted so nested pauses (e.g. a programmatic pause wrapping a
     // live-sync morph that also pauses) only resume on the outermost release.
     this._pauseDepth++;
@@ -139,6 +143,26 @@ const localMutation = {
     this._log('Paused', this._pauseDepth);
   },
 
+  // Records the browser queued before this pause describe changes made outside
+  // it. Left in the queue, resume() would drain them as paused-time records and
+  // only non-pausable callbacks would see them, so autosave missed a change made
+  // just before a pause. Deliver them on a microtask, as the observer would have.
+  _deliverBeforePause() {
+    if (!this._observer) return;
+    const records = this._observer.takeRecords();
+    if (records.length) queueMicrotask(() => this._onRecords(records));
+  },
+
+  /**
+   * Hand the records the browser has queued to raw subscribers' buffers and to
+   * non-pausable callbacks only, as if they had happened inside a pause. For a
+   * caller whose writes and their undoing cancel out, so the page's change feed
+   * has nothing to see.
+   */
+  dropQueued() {
+    if (this._observer) this._drainBrowserQueue(this);
+  },
+
   /**
    * Resume mutation observation after a pause.
    */

package/src/lib/person-face.js

@@ -0,0 +1,16 @@
+export const PERSON_COLORS = Object.freeze(['#6b4fa8', '#2f6a9e', '#9a6a1c', '#a8463d', '#2f7a69', '#4f6178', '#3f7d3a', '#a2457a']);
+
+export function colorIndexOf(id) {
+  let hash = 0;
+  for (const ch of String(id)) hash = (hash * 31 + ch.codePointAt(0)) >>> 0;
+  return hash % PERSON_COLORS.length;
+}
+
+export function personColor(id) {
+  return PERSON_COLORS[colorIndexOf(id)];
+}
+
+export function initialsOf(name) {
+  const letters = String(name).trim().split(/\s+/).filter(Boolean).slice(0, 2).map((word) => Array.from(word)[0]);
+  return letters.join("").toUpperCase() || "?";
+}

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/lib/root-attrs.js

@@ -116,3 +116,31 @@ export const TAB_LOCAL_ROOT_ATTRS = new Set([
 export function isTabLocalRootAttr(name, element) {
   return element === document.documentElement && TAB_LOCAL_ROOT_ATTRS.has(name);
 }
+
+// Router state. The router mirrors each URL-hash param onto the root as
+// route-<name>, and stamps route-active on the record a param selects. Both say
+// where this tab is in the document, not what the document holds, so they are
+// tab-local like the library's own root state: never saved, never dirty, never
+// undone, never sent to or taken from a peer. route-* is reserved on the root
+// only; route-active is reserved on every element.
+export const ROUTE_ROOT_PREFIX = "route-";
+export const ROUTE_ACTIVE_ATTR = "route-active";
+
+/**
+ * True when `name` on `el` belongs to this tab rather than to the document:
+ * every tab-local root attribute, route-* on a root, and route-active anywhere.
+ * Works on the live root and on a snapshot clone's or parsed frame's root.
+ */
+export function isTabLocalAttr(name, el) {
+  if (name === ROUTE_ACTIVE_ATTR) return true;
+  if (!el || el.localName !== "html" || el.parentElement) return false;
+  return TAB_LOCAL_ROOT_ATTRS.has(name) || name.startsWith(ROUTE_ROOT_PREFIX);
+}
+
+/** Remove router state from a snapshot clone: route-* on its root, route-active anywhere. */
+export function stripRouteAttrs(root) {
+  for (const attr of [...root.attributes]) {
+    if (attr.name.startsWith(ROUTE_ROOT_PREFIX)) root.removeAttribute(attr.name);
+  }
+  for (const el of root.querySelectorAll(`[${ROUTE_ACTIVE_ATTR}]`)) el.removeAttribute(ROUTE_ACTIVE_ATTR);
+}

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