@panphora/clayjs 1.15.2 → 1.16.0

package/src/sync/conflict-revert.js

@@ -399,6 +399,7 @@ function planText(rec, apply) {
   const subject = rec.recovery.subject;
   const live = liveOf(subject, apply, subject.nodeType);
   if (!live) return null;
+  const box = live.nodeType === 3 && live.parentNode?.localName === "textarea" ? live.parentNode : live;
   const local = t.local.text.slice(t.local.start, t.local.end);
   if (STRUCTURAL.test(t.merged.text.slice(t.merged.start, t.merged.end)) || local.includes(BREAK)) return null;
   const op = { kind: "text", id: rec.id, ticket: apply.ticket, key: subject.key, fragment: t.local.fragment, encoding: t.encoding, local, ids: new Set(), range: document.createRange() };
@@ -411,12 +412,12 @@ function planText(rec, apply) {
   }
   // A textarea shows its value, which typing moves away from its child text: the
   // spot is found in the value and both are written.
-  if (live.localName === "textarea") {
+  if (box.localName === "textarea") {
     if (op.encoding !== "plain") return null;
-    const span = rebase(t.merged.text, live.value, t.merged.start, t.merged.end);
+    const span = rebase(t.merged.text, box.value, t.merged.start, t.merged.end);
     if (!span) return null;
-    op.range.selectNodeContents(live);
-    return { ...op, root: live, field: live, scope: live, f: { text: live.value }, s: span.s, e: span.e, before: live.value, bs: span.s, be: span.e };
+    op.range.selectNodeContents(box);
+    return { ...op, root: box, field: box, scope: box, f: { text: box.value }, s: span.s, e: span.e, before: box.value, bs: span.s, be: span.e };
   }
   const f = project(live);
   const from = scopeStart(t, live, f);

package/src/sync/conflicts-edit.js

@@ -0,0 +1,119 @@
+/**
+ * The edit-only half of the conflict ledger.
+ *
+ * `conflicts.js` is the one conflict module a reader and an editor both load, and a
+ * reader never records a conflict: it has nothing unsaved for an incoming frame to
+ * win over. So the copy a reload has to keep, and the store it goes to, live here.
+ * `conflicts.js` starts this fetch as it evaluates in edit mode, and hands it the
+ * material it cannot rebuild; a conflict that arrives before it lands is queued
+ * there and drains the moment it does.
+ */
+
+import { TAB_LOCAL_ROOT_ATTRS } from '../lib/root-attrs.js';
+import { serializeRecoveryClone } from '../core/snapshot.js';
+import { rowOf } from '../core/conflict-presentation.js';
+
+// The recovery half of this module is fetched, not imported: no recovery code is in
+// the boot graph, and a page that never loses anything never downloads it. The copy
+// itself is made synchronously below and queued here, so what has to be preserved is
+// preserved before anything is released; the queue drains the moment the module
+// arrives. Until it does, the live record is the only copy, which is where this
+// started.
+const DURABLE_QUEUE_MAX = 20;
+let durable = null;
+let loadingDurable = false;
+const durableQueue = [];
+
+function loadDurable() {
+  if (durable || loadingDurable) return;
+  loadingDurable = true;
+  import('../recovery/conflicts.js').then(
+    (module) => {
+      durable = module;
+      loadingDurable = false;
+      drainDurable();
+    },
+    (error) => {
+      loadingDurable = false;
+      console.error('clayjs: the conflict recovery module could not be downloaded; conflicts stay in this tab only', error);
+    }
+  );
+}
+
+function drainDurable() {
+  if (!durable) {
+    loadDurable();
+    return;
+  }
+  while (durableQueue.length) {
+    const spec = durableQueue.shift();
+    try {
+      durable.recordConflicts(spec);
+    } catch (err) {
+      console.error('clayjs: the conflict could not be stored for a later reload; it is still here', err);
+    }
+  }
+}
+
+// The losing text a reload has to keep, as the notice already words it. Everything
+// here is plain text: the row's own name, the sentence that explains it, and the two
+// sides, with the rest of the copy in the stored root.
+function conflictEntry(rec, context) {
+  let row = null;
+  try {
+    row = rowOf(rec);
+  } catch (_) {}
+  const full = (side) => (!side ? '' : (side.cutBefore ? '\u2026' : '') + side.before + side.hit + side.after + (side.cutAfter ? '\u2026' : ''));
+  return {
+    id: String(rec.id),
+    kind: String(rec.kind ?? ''),
+    key: rec.recovery?.key == null ? '' : String(rec.recovery.key),
+    name: row?.name ? String(row.name) : '',
+    sentence: row?.sentence ? String(row.sentence) : '',
+    yours: full(row?.yours),
+    now: full(row?.now),
+    context,
+  };
+}
+
+// The pre-apply root as the bytes a save would have written, with the root
+// attributes this response and this tab own removed first: a recovery copy never
+// carries a save token, a file id or this library's own UI state.
+function recoveryHtml(apply) {
+  try {
+    const source = apply.recoveryRoot ?? apply.root;
+    const clone = source?.cloneNode?.(true);
+    if (!clone) return null;
+    for (const name of TAB_LOCAL_ROOT_ATTRS) clone.removeAttribute(name);
+    return serializeRecoveryClone(clone, { prepared: apply.domain === 'save' });
+  } catch (err) {
+    console.error('clayjs: the conflict recovery page could not be serialized; the conflict text is still stored', err);
+    return null;
+  }
+}
+
+// Copy the material before anything is released, and never let the store's failure
+// reach the ledger: a quota or a blocked database leaves the live record exactly
+// where it was. Losing the copy to this queue is bounded, never silent.
+export function keep({ apply, records }) {
+  try {
+    durableQueue.push({
+      apply: { id: apply.id, source: apply.source, domain: apply.domain, seq: apply.seq, etag: apply.etag, ticket: apply.ticket },
+      root: recoveryHtml(apply),
+      conflicts: records.map(({ rec, context }) => conflictEntry(rec, context)),
+    });
+    if (durableQueue.length > DURABLE_QUEUE_MAX) durableQueue.shift();
+    drainDurable();
+  } catch (err) {
+    console.error('clayjs: the conflict could not be stored for a later reload; it is still here', err);
+  }
+}
+
+// An acknowledged conflict leaves the store with the ledger record it came from:
+// nothing here reads it back, and a store that cannot be reached just keeps it.
+export function dismiss(ids) {
+  import('../recovery/conflicts.js').then(
+    (module) => module.dismissConflicts(ids),
+    () => {}
+  ).catch(() => {});
+}

package/src/sync/conflicts-facade.js

@@ -0,0 +1,49 @@
+// clay.conflicts before the conflict ledger has loaded. No merge has happened, so
+// there are no conflicts: reads answer empty, writes have nothing to act on, and a
+// context resolver registered now is handed to the ledger when it loads. Once loaded,
+// every member delegates, so the object a page holds never changes.
+let ledger = null;
+let loading = null;
+const resolvers = new Map();
+
+export function loadConflicts() {
+  loading ??= Promise.all([import('./conflicts.js'), import('./conflict-footprints.js')]).then(([c, f]) => {
+    ledger = { ...c, beginLineageCapture: f.beginLineageCapture };
+    // The unregister the real registry handed back, so a resolver the page drops
+    // before or after the download leaves the ledger's registry alike.
+    for (const resolver of [...resolvers.keys()]) resolvers.set(resolver, c.registerContext(resolver));
+    return ledger;
+  });
+  return loading;
+}
+
+export const conflictLedger = () => ledger;
+
+export const conflicts = {
+  get size() { return ledger ? ledger.conflicts.size : 0; },
+  list() { return ledger ? ledger.conflicts.list() : []; },
+  get(id) { return ledger ? ledger.conflicts.get(id) : null; },
+  acknowledge(ids, options = {}) {
+    if (ledger) return ledger.conflicts.acknowledge(ids, options);
+    if (!Array.isArray(ids)) throw new TypeError('clay.conflicts.acknowledge needs an array of ids');
+    return { removedIds: [], remainingIds: [] };
+  },
+  claim(ids, options = {}) {
+    if (ledger) return ledger.conflicts.claim(ids, options);
+    if (!options.owner) throw new TypeError('clay.conflicts.claim needs an owner');
+    return { release() {} };
+  },
+  registerContext(resolver) {
+    if (ledger) return ledger.conflicts.registerContext(resolver);
+    if (typeof resolver !== 'function') throw new TypeError('clay.conflicts.registerContext needs a resolver function');
+    resolvers.set(resolver, null);
+    return () => {
+      const registered = resolvers.get(resolver);
+      resolvers.delete(resolver);
+      if (registered) registered();
+    };
+  },
+  contextFor(rec, apply) { return ledger ? ledger.conflicts.contextFor(rec, apply) : null; },
+  recoveryOf(id) { return ledger ? ledger.conflicts.recoveryOf(id) : null; },
+  hasPendingApply() { return ledger ? ledger.conflicts.hasPendingApply() : false; },
+};

package/src/sync/conflicts.js

@@ -1,5 +1,6 @@
 import { registerUnsavedState } from '../lib/unsaved-state.js';
 import { releaseProtection } from './conflict-footprints.js';
+import { isEditMode } from '../core/is-edit-mode.js';
 
 // What incoming frames won over this tab's unsaved edits, kept for the life of
 // the document until the person decides. Nothing here is read by a save, a
@@ -13,8 +14,32 @@ let counter = 0;
 const records = new Map();
 const applies = new Map();
 const pending = new Set();
+const resolvers = new Set();
 let registration = null;
 
+// The recording half is edit-only, like live sync's: a reader has nothing unsaved to
+// lose. Edit mode starts the fetch as this file evaluates; a loss that arrives first
+// waits in the queue below.
+const EDIT_QUEUE_MAX = 20;
+let edit = null;
+let editLoad = null;
+const editQueue = [];
+
+export function loadEdit() {
+  editLoad ??= import('./conflicts-edit.js').then(
+    (module) => {
+      edit = module;
+      while (editQueue.length) edit.keep(editQueue.shift());
+    },
+    (error) => {
+      editLoad = null;
+      console.error('clayjs: the conflict recovery module could not be downloaded; conflicts stay in this tab only', error);
+    }
+  );
+}
+
+if (isEditMode) loadEdit();
+
 function nextId(prefix = '') {
   return `${nonce}:${prefix}${++counter}`;
 }
@@ -45,12 +70,61 @@ function isLoss(c) {
   return r.localLost !== false;
 }
 
+// The page names a conflict when it can: a record id, a label and a field, from the
+// app's own registered resolver. What comes back is a name and an action for the
+// notice, never a claim, and never a replacement for the generic ones.
+const CONTEXT_FIELDS = ['kind', 'id', 'label', 'field'];
+
+// What can be stored: the identity, the label and the field. An `open` action is a
+// function bound to this page's tree and stays on the live record.
+function contextFields(value) {
+  if (!value || typeof value !== 'object') return null;
+  const context = {};
+  for (const field of CONTEXT_FIELDS) {
+    const found = value[field];
+    if (typeof found === 'string' && found) context[field] = found;
+    else if (typeof found === 'number' && Number.isFinite(found)) context[field] = String(found);
+  }
+  return Object.keys(context).length ? context : null;
+}
+
+function contextOf(value) {
+  const context = contextFields(value);
+  if (!context) return null;
+  if (typeof value.open === 'function') context.open = value.open;
+  return context;
+}
+
+// The newest registration answers first: an app that changes its own resolver gets
+// the new one without having to unregister the old.
+function contextFor(rec, apply) {
+  for (const resolver of [...resolvers].reverse()) {
+    let answer;
+    try {
+      answer = resolver(rec, apply);
+    } catch (err) {
+      console.error('clayjs: a conflict context resolver threw; the conflict stays generic', err);
+      continue;
+    }
+    const context = contextOf(answer);
+    if (context) return context;
+  }
+  return null;
+}
+
+export function registerContext(resolver) {
+  if (typeof resolver !== 'function') throw new TypeError('clay.conflicts.registerContext needs a resolver function');
+  resolvers.add(resolver);
+  return () => resolvers.delete(resolver);
+}
+
 function install(apply, raw) {
   const id = nextId();
   const rec = Object.assign(raw[0], {
     id, applyId: apply.id, source: apply.source, ticket: apply.ticket,
     rawReports: raw, claimedBy: null,
   });
+  rec.context = contextFor(rec, apply);
   records.set(id, rec);
   apply.ids.add(id);
   return id;
@@ -91,6 +165,19 @@ function foldInsertions(groups) {
   return [...folded.values()];
 }
 
+// What the store may keep of a record's context, read now, while the record still
+// knows it: the identity, the label and the field, never the resolver's action, which
+// is a function bound to this page's tree and stays on the live record.
+function keepConflicts(apply, ids) {
+  const kept = ids.map((id) => records.get(id)).filter(Boolean);
+  if (!kept.length) return;
+  const spec = { apply, records: kept.map((rec) => ({ rec, context: contextFields(rec.context) })) };
+  if (edit) return edit.keep(spec);
+  editQueue.push(spec);
+  if (editQueue.length > EDIT_QUEUE_MAX) editQueue.shift();
+  loadEdit();
+}
+
 export function completeApply(applyId, conflicts, { ticket }) {
   const apply = applies.get(applyId);
   if (!apply) return [];
@@ -103,6 +190,7 @@ export function completeApply(applyId, conflicts, { ticket }) {
     groups.get(key).push(c);
   }
   const ids = foldInsertions([...groups.values()]).map((raw) => install(apply, raw));
+  if (ids.length) keepConflicts(apply, ids);
   pending.delete(applyId);
   if (!ids.length) applies.delete(applyId);
   if (ids.length) changed({ added: ids.map((id) => records.get(id)) });
@@ -117,6 +205,7 @@ export function failApply(applyId, error, { ticket = 0 } = {}) {
   pending.delete(applyId);
   const id = install(apply, [{ kind: 'apply-incomplete', detail: null, error: String(error) }]);
   records.get(id).rawReports = [];
+  keepConflicts(apply, [id]);
   changed({ added: [records.get(id)] });
   return [id];
 }
@@ -147,7 +236,13 @@ export const conflicts = {
         if (!apply.ids.size) applies.delete(rec.applyId);
       }
     }
-    if (removedIds.length) changed({ removedIds, reason });
+    if (removedIds.length) {
+      changed({ removedIds, reason });
+      import('./conflicts-edit.js').then(
+        (module) => module.dismiss(removedIds),
+        () => {}
+      );
+    }
     return { removedIds, remainingIds: [...records.keys()] };
   },
   claim(ids, { owner }) {
@@ -178,6 +273,9 @@ export const conflicts = {
       },
     };
   },
+  registerContext,
+  contextFor,
+
   recoveryOf(id) {
     const rec = records.get(id);
     return rec ? applies.get(rec.applyId) || null : null;

package/src/sync/editing-marker.js

@@ -14,18 +14,37 @@
 import { hostSupports } from '../core/host-meta.js';
 import { make, set } from '../lib/hostile-css.js';
 import { personColor } from '../lib/person-face.js';
-import { RUNTIME_ONLY } from '../ui/bevel-controls.js';
-import { FONT_MONO } from '../ui/bevel.js';
 import { EDITING_PATH, elementAt } from './editing-path.js';
 
 const FACE = '#FFFCF6';
 const RESET = ['all:initial', 'color-scheme:inherit', 'direction:ltr', 'unicode-bidi:isolate'];
 const CHIP_HEIGHT = 18;
 const GAP = 3;
-const CHIP_FONT = `600 11px/16px ${FONT_MONO}`;
+
+// The marking token and the chip face are the Bevel subset, a first-use download: a
+// reader with nobody else on the page never draws a marker, so it never fetches them.
+let ui = null;
+let uiLoad = null;
+
+function loadUI() {
+  uiLoad ??= Promise.all([import('../ui/bevel-controls.js'), import('../ui/bevel.js')])
+    .then(([controls, bevel]) => (ui = {
+      RUNTIME_ONLY: controls.RUNTIME_ONLY,
+      CHIP_FONT: `600 11px/16px ${bevel.FONT_MONO}`,
+    }))
+    .catch((error) => {
+      uiLoad = null;
+      throw error;
+    });
+  return uiLoad;
+}
+
+// A frame never rejects its way back to the stream: a chunk that failed to arrive
+// leaves the block unmarked and the next frame asks again.
+const uiReady = () => loadUI().then(() => true, () => false);
 
 function runtimeRoot(el) {
-  el.setAttribute('clay', RUNTIME_ONLY);
+  el.setAttribute('clay', ui.RUNTIME_ONLY);
   return el;
 }
 
@@ -59,7 +78,7 @@ class EditingMarker {
   async update(frame) {
     this.editors = editorsOf(frame);
     if (!(await this.supported())) return;
-    this.render();
+    await this.render();
   }
 
   clear() {
@@ -79,7 +98,19 @@ class EditingMarker {
     });
   }
 
+  // A synchronous draw while the chunk is here, as it always was, and one draw
+  // queued for when it arrives on the first frame that needs it.
   render() {
+    if (ui) {
+      this.paint();
+      return Promise.resolve();
+    }
+    return uiReady().then((ok) => {
+      if (ok) this.paint();
+    });
+  }
+
+  paint() {
     const groups = new Map();
     for (const editor of this.editors) {
       const element = elementAt(editor.path);
@@ -130,7 +161,7 @@ class EditingMarker {
       const chip = runtimeRoot(make('span', [
         ...RESET,
         'box-sizing:border-box', `height:${CHIP_HEIGHT}px`, 'padding:1px 6px',
-        `font:${CHIP_FONT}`, 'letter-spacing:.02em', 'white-space:nowrap',
+        `font:${ui.CHIP_FONT}`, 'letter-spacing:.02em', 'white-space:nowrap',
         'max-width:180px', 'overflow:hidden', 'text-overflow:ellipsis',
         `background-color:${personColor(editor.id)}`, `color:${FACE}`,
         `box-shadow:0 0 0 1px ${FACE}`,

package/src/sync/editing-sender.js

@@ -1,11 +1,18 @@
 import { blockOf, pathOf } from './editing-path.js';
+import { presence } from './presence-store.js';
 
 const INTERVAL_MS = 250;
 const RETRY_MS = 2000;
 const EVENTS = ['focusin', 'focusout', 'selectionchange', 'clay:sync-applied', 'clay:workspace-background', 'clay:workspace-foreground'];
 
+// The default is the facade's generic half: a page that publishes a target does
+// not post it itself, and an owner that attached a transport is the only thing that
+// does. The marker stands aside while an explicit page target owns the session, so
+// one document never has two senders talking at once.
+const publish = (target) => presence.setGeneric(target);
+
 export class EditingSender {
-  constructor({ send, now = () => Date.now() }) {
+  constructor({ send = publish, now = () => Date.now() }) {
     this.send = send;
     this.now = now;
     this.others = false;

package/src/sync/live-sync-edit.js

@@ -0,0 +1,63 @@
+/**
+ * The edit-only half of live sync.
+ *
+ * `live-sync.js` is the one sync module a reader and an editor both load. The
+ * names below are the ones it reaches only in edit mode (or whose view-mode
+ * answer is a constant), so they live in this separate chunk: live-sync loads it
+ * with `await import()` on its edit path, and a view-mode tab never fetches the
+ * save, admin or editing-sender graph behind it.
+ */
+import { loadEdit as loadConflictsEdit } from "./conflicts.js";
+import { presence } from "./presence-store.js";
+
+export { savePageThrottled, setLastSavedBaselines, setUnsavedChanges, getLastSavedBytes, conflictResolvedBySync, isSaveConflicted, baselineSettled, schedulePaintHeal } from "../core/save.js";
+export { enableContentEditable } from "../core/admin-contenteditable.js";
+export { enableOnClick } from "../core/admin-onclick.js";
+export { enableAdminInputs } from "../core/admin-inputs.js";
+export { enableAdminResources } from "../core/admin-resources.js";
+export { EditingSender } from "./editing-sender.js";
+
+// The lifecycle participant a live switch prepares for generic sync. `sync` is the
+// one LiveSync instance the page owns: the saved lane it follows as a reader is what
+// an entry stops, and the live lane it starts is what an exit disposes. The exit's
+// saved lane is the controller's to restart, not this lease's.
+export function syncParticipant(sync) {
+  // The outgoing target goes before the editor is taken down, so a caret this tab
+  // published cannot outlive the session that published it. A page target is
+  // released with the ownership it came with; the generic marker is cleared
+  // outright. Neither falls back to a positional marker: the exit publishes nobody.
+  const quiesce = () => {
+    presence.setGeneric(null);
+    presence.releaseTarget();
+    return sync.lane === "live" && sync._morphInFlight ? { ok: false, code: "pending-input" } : { ok: true };
+  };
+  const dispose = () => sync.stop();
+  return {
+    id: "clay:sync",
+    order: 50,
+    async prepare(context) {
+      await loadConflictsEdit();
+      // Adoption: the explicit initial edit started this lane as the module
+      // evaluated, so the lease covers it and starts nothing new.
+      if (context?.initial) return { quiesce, dispose };
+      let started = false;
+      return {
+        quiesce,
+        // The commit: the lane a reader was following stops, and the same stream
+        // slot opens on the live lane.
+        enable() {
+          const file = sync.currentFile;
+          sync.stop();
+          sync.start(file, { lane: "live" });
+          started = true;
+        },
+        // A refused entry disposes what it prepared as well, and until the commit this
+        // lane was the reader's: stopping it would take the saved lane the switch gives
+        // back with it.
+        dispose: () => {
+          if (started) sync.stop();
+        },
+      };
+    },
+  };
+}