@panphora/clayjs 1.1.0 → 1.3.0

package/src/sync/presence.js

@@ -0,0 +1,303 @@
+/**
+ * presence.js — who else is on this document.
+ *
+ * A fixed-corner stack of circles, one per participant the host chose to name,
+ * plus a count of everyone it did not. The host decides who is named, per
+ * recipient, from that recipient's own access; nothing here asks for a name and
+ * nothing here can widen what arrived.
+ *
+ * THE RULE THIS FILE EXISTS TO GET RIGHT.
+ *
+ * captureForSaveAndComparison() clones the document, hands that clone to peers
+ * on `clay:snapshot-ready`, and only THEN strips the save-only regions. So
+ * `no-save` alone is not enough: it keeps names out of the file while
+ * broadcasting them to every peer on the document, including a visitor the host
+ * deliberately answered with a count and no names. `no-snapshot` is the token
+ * that runs BEFORE the clone is emitted (captureSnapshot), so every runtime root
+ * here carries all three, tooltip included:
+ *
+ *   no-save      not written to the saved file
+ *   no-watch     invisible to the mutation system, so a roster change is not an edit
+ *   no-snapshot  absent from every snapshot, including the one peers receive
+ *
+ * The roster lives in this module's memory. It is never written to a DOM data
+ * store, an attribute or anything else a serializer walks — the names on screen
+ * are text nodes inside a subtree that no snapshot contains, and the hover label
+ * is held in a closure rather than in `title`. Styling is inline and hostile-css
+ * !important throughout, so there is no injected <style> tag to mark either.
+ *
+ * Gated on the host, not on the first frame: a host that does not announce
+ * `presence` draws nothing at all rather than an empty stack. That is what
+ * hyperclay-local, HTML Clay and makerclay do today and it stays that way until
+ * they adopt it.
+ *
+ * `people[].id` is an opaque keyed pseudonym. It picks the colour and nothing
+ * else: it is not a database id, it names no account, and it is never logged.
+ */
+
+import { hostSupports } from '../core/host-meta.js';
+import { make, set } from '../lib/hostile-css.js';
+
+// Runtime-only chrome, in one string so no root can carry two of the three.
+const RUNTIME_ONLY = 'no-save no-watch no-snapshot';
+
+// Two initials at 12px need about 15px of the circle, so the overlap has to
+// leave that much clear or the neighbouring circle eats the second letter.
+const SIZE = 30;
+const OVERLAP = 6;
+const FONT = "12px/1 system-ui,-apple-system,'Segoe UI',sans-serif";
+const LABEL_FONT = "12px/1.4 system-ui,-apple-system,'Segoe UI',sans-serif";
+
+// The chrome around the circles is themeable like every other clayjs surface.
+// The circles themselves are not: their colour is computed per participant, so
+// there is no one value a page could override.
+const INK = 'var(--clay-presence-ink,#1f2023)';
+const CHIP_BG = 'var(--clay-presence-bg,#fff)';
+const CHIP_EDGE = 'var(--clay-presence-edge,rgba(0,0,0,.14))';
+const TIP_BG = 'var(--clay-presence-tip-bg,#222)';
+const TIP_INK = 'var(--clay-presence-tip-ink,#fff)';
+const FACE = '#ffffff';
+
+// A fixed set rather than a computed hue: every one of these was looked at
+// against white initials, and a hue wheel puts neighbouring pseudonyms on two
+// blues nobody can tell apart.
+const COLORS = [
+  '#b91c1c', '#c2410c', '#a16207', '#15803d', '#0f766e',
+  '#0369a1', '#1d4ed8', '#6d28d9', '#a21caf', '#9f1239',
+];
+
+/** Every element this module creates, marked the same way. */
+function runtimeRoot(el) {
+  el.setAttribute('clay', RUNTIME_ONLY);
+  return el;
+}
+
+function hashOf(id) {
+  let h = 5381;
+  for (let i = 0; i < id.length; i++) {
+    h = (((h << 5) + h) ^ id.charCodeAt(i)) >>> 0;
+  }
+  return h;
+}
+
+// The pseudonym picks the colour and nothing else.
+function colorFor(id) {
+  return COLORS[hashOf(id) % COLORS.length];
+}
+
+// Array.from, not [0]: a name starting outside the BMP would otherwise show half
+// a character.
+function initialsOf(name) {
+  const words = String(name).trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return '?';
+  const first = (word) => Array.from(word)[0].toUpperCase();
+  return words.length === 1 ? first(words[0]) : first(words[0]) + first(words[1]);
+}
+
+/**
+ * Read the roster frame defensively. Everything here arrived over a wire, and a
+ * frame this function cannot understand must draw nothing rather than draw a
+ * guess: `[object Object]` in a circle is worse than an empty corner.
+ */
+function normalize(data) {
+  const list = data && Array.isArray(data.people) ? data.people : [];
+  const people = [];
+  for (const person of list) {
+    if (!person || typeof person.id !== 'string' || !person.id) continue;
+    const name = typeof person.name === 'string' && person.name.trim() ? person.name.trim() : 'Someone';
+    people.push({
+      id: person.id,
+      name,
+      canEdit: person.canEdit === true,
+      you: person.you === true,
+    });
+  }
+  const count = data && data.anonymous;
+  const anonymous = typeof count === 'number' && Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+  return { people, anonymous };
+}
+
+class Presence {
+  constructor() {
+    this.roster = { people: [], anonymous: 0 };
+    this.root = null;
+    this.stack = null;
+    this.count = null;
+    this.tip = null;
+    this._gate = null;
+  }
+
+  /**
+   * Does this host run presence at all? Asked once, of /_/meta, and never
+   * inferred from a frame arriving: the answer decides whether the chrome is
+   * built, so a host that says nothing draws nothing forever.
+   */
+  supported() {
+    if (!this._gate) this._gate = hostSupports('presence').then((ok) => ok === true, () => false);
+    return this._gate;
+  }
+
+  /**
+   * Take a roster frame. Held in memory first so a frame that arrives before
+   * discovery answers is not lost, and drawn only if the host announced the
+   * capability.
+   *
+   * @param {{people: Array, anonymous: number}} data
+   * @returns {Promise<void>}
+   */
+  async update(data) {
+    this.roster = normalize(data);
+    if (!(await this.supported())) return;
+    this.render();
+  }
+
+  /** The stream went away, so the roster is no longer true about anything. */
+  clear() {
+    this.roster = { people: [], anonymous: 0 };
+    if (!this.root) return;
+    this.root.remove();
+    this.root = null;
+    this.stack = null;
+    this.count = null;
+    this.tip = null;
+  }
+
+  render() {
+    const { people, anonymous } = this.roster;
+
+    // A person alone on a document is told nothing at all. The count is the
+    // total either way: a recipient the host would not name gets people: [] and
+    // everyone in `anonymous`, so this sum is the same participant count in both
+    // directions.
+    if (people.length + anonymous <= 1) {
+      this.hide();
+      return;
+    }
+    if (!this.build()) return;
+
+    this.hideTip();
+    this.stack.textContent = '';
+    for (const person of people) {
+      this.stack.appendChild(this.avatar(person));
+    }
+    // The overlap belongs between circles, so the leftmost one does not pull
+    // itself into the count beside it.
+    if (this.stack.firstElementChild) set(this.stack.firstElementChild, 'margin-left', '0');
+
+    if (anonymous > 0) {
+      this.count.textContent = `+${anonymous} viewing`;
+      set(this.count, 'display', 'inline-block');
+    } else {
+      this.count.textContent = '';
+      set(this.count, 'display', 'none');
+    }
+    set(this.root, 'display', 'flex');
+  }
+
+  hide() {
+    if (!this.root) return;
+    this.hideTip();
+    this.stack.textContent = '';
+    this.count.textContent = '';
+    set(this.root, 'display', 'none');
+  }
+
+  build() {
+    if (this.root) return true;
+    if (typeof document === 'undefined' || !document.body) return false;
+
+    this.root = runtimeRoot(make('div', [
+      'position:fixed',
+      'top:calc(12px + env(safe-area-inset-top,0px))',
+      'right:calc(12px + env(safe-area-inset-right,0px))',
+      'z-index:2147483000',
+      'display:flex', 'align-items:center', 'gap:8px',
+      'max-width:calc(100vw - 24px)',
+      `font:${LABEL_FONT}`, `color:${INK}`,
+      // Only the circles take a pointer. A fixed corner that swallowed clicks
+      // would take a bite out of whatever the page put underneath it.
+      'pointer-events:none',
+    ]));
+    this.root.setAttribute('data-clay-presence', '');
+
+    this.count = runtimeRoot(make('span', [
+      'box-sizing:border-box', 'flex:none', 'white-space:nowrap',
+      'padding:4px 8px', 'border-radius:999px',
+      `background-color:${CHIP_BG}`, 'background-image:none', `color:${INK}`,
+      'border-width:1px', 'border-style:solid', `border-color:${CHIP_EDGE}`,
+      `font:${LABEL_FONT}`,
+      'box-shadow:0 1px 3px rgba(0,0,0,.2)',
+      'display:none',
+    ]));
+    this.count.setAttribute('data-clay-presence-count', '');
+
+    this.stack = runtimeRoot(make('div', [
+      'display:flex', 'align-items:center', 'flex:none',
+    ]));
+
+    // Inside the root rather than appended to <body>, so the one element that
+    // holds a name at rest cannot outlive the subtree that keeps it out of a
+    // snapshot. It carries the marking of its own too.
+    this.tip = runtimeRoot(make('span', [
+      'position:absolute', 'top:100%', 'right:0', 'margin-top:6px',
+      'box-sizing:border-box', 'white-space:nowrap', 'pointer-events:none',
+      'padding:4px 8px', 'border-radius:6px',
+      `background-color:${TIP_BG}`, 'background-image:none',
+      `color:${TIP_INK}`, `font:${LABEL_FONT}`,
+      'box-shadow:0 4px 14px rgba(0,0,0,.28)',
+      'display:none',
+    ]));
+    this.tip.setAttribute('data-clay-presence-tip', '');
+
+    this.root.append(this.stack, this.count, this.tip);
+    document.body.appendChild(this.root);
+    return true;
+  }
+
+  avatar(person) {
+    const color = colorFor(person.id);
+    // Solid says this person can change the document; hollow says they are
+    // reading it. The two are the same three colours inverted, so a stack of
+    // both reads as one set rather than as two kinds of thing.
+    const skin = person.canEdit
+      ? [`background-color:${color}`, `color:${FACE}`, `border-color:${FACE}`]
+      : [`background-color:${FACE}`, `color:${color}`, `border-color:${color}`];
+
+    const el = runtimeRoot(make('div', [
+      'box-sizing:border-box', 'flex:none',
+      `width:${SIZE}px`, `height:${SIZE}px`, 'border-radius:50%',
+      'display:flex', 'align-items:center', 'justify-content:center',
+      `font:${FONT}`, 'font-weight:600',
+      `margin-left:-${OVERLAP}px`,
+      'border-width:2px', 'border-style:solid', 'background-image:none',
+      'box-shadow:0 1px 3px rgba(0,0,0,.28)',
+      'user-select:none', 'cursor:default', 'pointer-events:auto',
+      ...skin,
+    ], initialsOf(person.name)));
+    el.setAttribute('data-clay-presence-avatar', '');
+
+    // The name lives in this closure, never in an attribute on the element, and
+    // it reaches the DOM only while a pointer is actually on the circle.
+    const label = person.you ? `${person.name} (you)` : person.name;
+    el.addEventListener('mouseenter', () => this.showTip(label));
+    el.addEventListener('mouseleave', () => this.hideTip());
+    return el;
+  }
+
+  showTip(text) {
+    if (!this.tip) return;
+    this.tip.textContent = text;
+    set(this.tip, 'display', 'block');
+  }
+
+  hideTip() {
+    if (!this.tip) return;
+    this.tip.textContent = '';
+    set(this.tip, 'display', 'none');
+  }
+}
+
+const presence = new Presence();
+
+export { presence, Presence };
+export default presence;

package/src/sync/section-notice.js

@@ -0,0 +1,230 @@
+/**
+ * section-notice.js — "<name> changed this section".
+ *
+ * One dismissible line, shown when a live-sync frame from somebody else
+ * actually changed the editable region this reader was working in.
+ *
+ * HOW "THIS SECTION CHANGED" IS DECIDED, AND WHY BOTH OBVIOUS READINGS ARE WRONG.
+ *
+ * Not "an ancestor was morphed". Every frame morphs `document.documentElement`,
+ * so `body` is an ancestor of every region there is and that test reports every
+ * unrelated edit anybody makes anywhere on the page.
+ *
+ * Not "an ancestor was replaced". hyper-morph matches and mutates IN PLACE
+ * (morphNode / morphAttributes), so nothing is replaced when a peer retypes a
+ * sentence — which is the common case this notice exists for.
+ *
+ * So the region's own content is compared across the morph. The baseline is
+ * recorded when the reader focuses the region and refreshed while they type, so
+ * their own keystrokes are never read as somebody else's edit, and the
+ * comparison runs on `clay:sync-applied`, which fires after the awaited morph.
+ * It is re-recorded on EVERY applied frame, named or not: a change nobody is
+ * named for would otherwise leave the baseline behind the screen, and the next
+ * named frame — which may have touched nothing here — would inherit it and put
+ * the wrong person's name on somebody else's edit.
+ *
+ * The one thing that gets past it: a page script that rewrites the region
+ * without an `input` event. That drift is charged to whichever named frame lands
+ * next. Typing, pasting and every other user edit of a control or a
+ * contenteditable subtree do fire one, which is the case this is for.
+ *
+ * The region is kept AFTER focus leaves, deliberately. hyper-morph's
+ * `ignoreActiveValue` skips both the value sync and the child morph for
+ * `document.activeElement`, so nothing can change under the caret while it is
+ * still there; the frame worth reporting is the one that lands on the paragraph
+ * the reader just left.
+ *
+ * DISMISS ONLY. An undo here would mean recovering displaced local work, which
+ * nothing in this library builds. Unsaved local work is protected before the
+ * morph by protectPeerDoc, and a refused save is still the conflict bar's job.
+ *
+ * Silent with no `by` on the frame, which is the whole gate: the server stamps
+ * an author on live-lane frames alone, so a saved-lane reader — who must never
+ * be told who wrote the public page they are reading — is silent by
+ * construction rather than by a second rule that could disagree.
+ *
+ * Every root carries all three runtime tokens, for the reason presence.js's
+ * header sets out: captureForSaveAndComparison() hands its clone to peers on
+ * `clay:snapshot-ready` and strips the save-only regions only AFTER that, so
+ * `no-save` alone keeps an author's name out of the file while broadcasting it
+ * to every peer on the document.
+ *
+ *   no-save      not written to the saved file
+ *   no-watch     invisible to the mutation system, so a notice is not an edit
+ *   no-snapshot  absent from every snapshot, including the one peers receive
+ *
+ * The name reaches the DOM in one text node inside that subtree and is held
+ * nowhere else — no attribute, no data store, nothing a serializer walks.
+ */
+
+import { make, set } from '../lib/hostile-css.js';
+
+// Runtime-only chrome, in one string so no root can carry two of the three.
+const RUNTIME_ONLY = 'no-save no-watch no-snapshot';
+
+const BG = 'var(--clay-section-bg,#222)';
+const INK = 'var(--clay-section-ink,#fff)';
+const EDGE = 'var(--clay-section-edge,rgba(255,255,255,.28))';
+const FONT = "14px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif";
+
+// A control's work is its live value, which its markup does not carry. An
+// editable subtree's is its markup, and `outerHTML` covers the region's own
+// attributes too, so an in-place attribute change on it counts as a change.
+const CONTROLS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+// The nearest element that DECLARES the attribute, which is the host of the
+// editable subtree. `isContentEditable` is inherited, so it answers true for
+// every descendant text node's parent and names no region at all.
+const EDITABLE = '[contenteditable]:not([contenteditable="false"])';
+
+/** Every element this module creates, marked the same way. */
+function runtimeRoot(el) {
+  el.setAttribute('clay', RUNTIME_ONLY);
+  return el;
+}
+
+function regionOf(target) {
+  if (!target || target.nodeType !== 1 || typeof target.closest !== 'function') return null;
+  if (CONTROLS.has(target.tagName)) return target;
+  return target.closest(EDITABLE);
+}
+
+// Null for a region the frame removed outright, which differs from every string
+// a live region can produce and so reads as the change it is.
+function contentOf(el) {
+  if (!el || !el.isConnected) return null;
+  return CONTROLS.has(el.tagName) ? String(el.value) : el.outerHTML;
+}
+
+// The stamp arrived over a wire. The server promises a name on every live-lane
+// frame, and this still checks, because a frame that cannot be understood must
+// draw nothing rather than draw "undefined changed this section".
+function nameOf(by) {
+  if (!by || typeof by !== 'object') return null;
+  const name = typeof by.name === 'string' ? by.name.trim() : '';
+  return name || null;
+}
+
+class SectionNotice {
+  constructor() {
+    this.region = null;
+    this.content = null;
+    this.root = null;
+    this.line = null;
+    this._wired = false;
+    this._onFocusIn = (event) => this.remember(event.target);
+    this._onEdit = (event) => this.refresh(event.target);
+    this._onApplied = (event) => this.applied(event && event.detail);
+  }
+
+  /** Idempotent, so importing this module twice cannot double-report a frame. */
+  init() {
+    if (this._wired || typeof document === 'undefined') return;
+    this._wired = true;
+    document.addEventListener('focusin', this._onFocusIn);
+    // `input` alone: a <select> fires it before its `change`, and every other
+    // user edit of a control or an editable subtree fires it too.
+    document.addEventListener('input', this._onEdit);
+    document.addEventListener('clay:sync-applied', this._onApplied);
+  }
+
+  destroy() {
+    if (!this._wired) return;
+    this._wired = false;
+    document.removeEventListener('focusin', this._onFocusIn);
+    document.removeEventListener('input', this._onEdit);
+    document.removeEventListener('clay:sync-applied', this._onApplied);
+    this.region = null;
+    this.content = null;
+    if (this.root) this.root.remove();
+    this.root = null;
+    this.line = null;
+  }
+
+  /** The section the reader is working in. Focus on anything else leaves it alone. */
+  remember(target) {
+    const region = regionOf(target);
+    if (!region) return;
+    this.region = region;
+    this.content = contentOf(region);
+  }
+
+  /** Their own typing is not somebody else's edit. */
+  refresh(target) {
+    const region = regionOf(target);
+    if (!region || region !== this.region) return;
+    this.content = contentOf(region);
+  }
+
+  applied(detail) {
+    if (!this.region) return;
+    const now = contentOf(this.region);
+    const changed = now !== this.content;
+    this.content = now;
+    if (!changed) return;
+    const name = nameOf(detail && detail.by);
+    if (!name) return;
+    this.show(name);
+  }
+
+  show(name) {
+    if (!this.build()) return;
+    this.line.textContent = `${name} changed this section`;
+    set(this.root, 'display', 'flex');
+  }
+
+  hide() {
+    if (!this.root) return;
+    this.line.textContent = '';
+    set(this.root, 'display', 'none');
+  }
+
+  build() {
+    if (this.root && this.root.isConnected) return true;
+    if (typeof document === 'undefined' || !document.body) return false;
+
+    this.root = runtimeRoot(make('div', [
+      'position:fixed',
+      'left:calc(12px + env(safe-area-inset-left,0px))',
+      // Clear of the conflict bar, which is bottom-anchored and can span almost
+      // the whole width of a phone. That bar is the more urgent of the two, so
+      // this one moves rather than covering it.
+      'bottom:calc(72px + env(safe-area-inset-bottom,0px))',
+      'z-index:2147483000',
+      'display:none', 'align-items:center', 'gap:10px',
+      'box-sizing:border-box', 'max-width:calc(100vw - 24px)',
+      'padding:9px 12px', 'border-radius:10px',
+      `background-color:${BG}`, 'background-image:none', `color:${INK}`,
+      'border-width:1px', 'border-style:solid', `border-color:${EDGE}`,
+      'box-shadow:0 6px 24px rgba(0,0,0,.32),0 1px 2px rgba(0,0,0,.24)',
+      `font:${FONT}`, 'text-align:left',
+    ]));
+    this.root.setAttribute('data-clay-section-notice', '');
+    this.root.setAttribute('role', 'status');
+
+    this.line = runtimeRoot(make('span', ['flex:1 1 auto']));
+    this.line.setAttribute('data-clay-section-notice-line', '');
+
+    // all:initial first, because a page restyling every button is the normal
+    // case rather than the adversarial one; everything it needs is restated.
+    const dismiss = runtimeRoot(make('button', [
+      'all:initial', 'box-sizing:border-box', 'cursor:pointer', `font:${FONT}`,
+      'font-weight:500', 'border-radius:6px', 'padding:4px 8px',
+      'white-space:nowrap', 'flex:none', `color:${INK}`, 'opacity:.72',
+    ], 'Dismiss'));
+    dismiss.type = 'button';
+    dismiss.setAttribute('data-clay-section-notice-dismiss', '');
+    dismiss.addEventListener('click', () => this.hide());
+
+    this.root.append(this.line, dismiss);
+    document.body.appendChild(this.root);
+    return true;
+  }
+}
+
+const sectionNotice = new SectionNotice();
+
+if (typeof document !== 'undefined') sectionNotice.init();
+
+export { sectionNotice, SectionNotice };
+export default sectionNotice;

package/src/sync/splice-merge.js

@@ -32,7 +32,7 @@
  */
 
 import { findChangedRoots, spliceProtected } from '../vendor/hyper-morph.vendor.js';
-import { captureSnapshot, captureForMerge } from '../core/snapshot.js';
+import { captureSnapshot, captureForMerge, originalSnapshotNode } from '../core/snapshot.js';
 // save.js is edit-only in the loader waves but safe to reach from here: its
 // module body guards every init on isEditMode, and the disk lane that needs
 // this state only ever runs in edit-mode tabs.
@@ -109,17 +109,14 @@ function walkPairs(a, b, cb) {
  * whose child counts diverge (extension noise beside the clone's strip) is
  * skipped — those elements fall back to data-id / id matching.
  */
-function fillCloneIds(liveEl, cloneEl, liveWeakMap, idOf) {
-  const id = liveWeakMap.get(liveEl);
+function fillCloneIds(liveEl, cloneEl, liveWeakMap, idOf, root = true) {
+  const live = originalSnapshotNode(cloneEl) || (root ? liveEl : null);
+  const id = liveWeakMap.get(live);
   if (id) idOf.set(cloneEl, id);
-  const liveKids = [];
-  for (const c of liveEl.children) {
-    if (!isSnapshotRemoved(c)) liveKids.push(c);
-  }
   const cloneKids = cloneEl.children;
-  if (liveKids.length !== cloneKids.length) return;
-  for (let i = 0; i < liveKids.length; i++) {
-    fillCloneIds(liveKids[i], cloneKids[i], liveWeakMap, idOf);
+  for (let i = 0; i < cloneKids.length; i++) {
+    const childLive = originalSnapshotNode(cloneKids[i]);
+    fillCloneIds(childLive, cloneKids[i], liveWeakMap, idOf, false);
   }
 }