@panphora/clayjs 1.2.0 → 1.4.0

package/src/sync/live-sync.js

@@ -40,12 +40,17 @@ import Mutation from "../lib/mutation.js";
 import { isSnapshotRemoved } from "../lib/region-policy.js";
 import { isEditMode } from "../core/is-edit-mode.js";
 import { mergeTagRecognizers } from "./merge-tags.js";
-import { serializeForSync, captureForComparisonAndDirty, captureSnapshot } from '../core/snapshot.js';
+import { serializeForSync, captureForComparisonAndDirty, captureSnapshot, originalSnapshotNode } from '../core/snapshot.js';
 import { isTabLocalRootAttr } from '../lib/root-attrs.js';
 import { protectPeerDoc, protectDiskDoc, activateIncomingDoc } from './splice-merge.js';
+import { presence } from './presence.js';
+// Side-effect import: the section-changed notice wires itself to
+// `clay:sync-applied`, which this file is the only dispatcher of.
+import './section-notice.js';
 import { hostMeta } from '../core/host-meta.js';
 import { recordEtag, seedEtag, lastSeenEtag } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate } from '../lib/dirty-gate.js';
+import { SyncStream } from './stream.js';
 
 // The page just took a frame verified clean against its baseline, so it now IS
 // the file on disk. Both saved baselines move together from one capture: leaving
@@ -75,6 +80,12 @@ import { savePageThrottled, setLastSavedBaselines, setUnsavedChanges } from '../
  * One profile is chosen once and used for BOTH directions for the life of the page.
  * Letting send and receive decide independently is exactly the bug this replaces: a
  * client that posted to the spec address while streaming from the legacy one.
+ *
+ * Both stream addresses carry `client-id`, in the same kebab spelling as the rest of
+ * the query. It is the tab's own sender id — the one every outbound frame already
+ * carries — so a host that reads it at admission knows this connection by the value
+ * its frames arrive under, and can tell two tabs of one cookie-less guest apart. A
+ * host that does not read it ignores an unknown parameter.
  */
 const WIRE_PROFILES = {
   spec: {
@@ -82,8 +93,8 @@ const WIRE_PROFILES = {
     relayPath: '/_/sync',
     documentHeader: 'Document-URL',
     snapshotKey: 'snapshot',
-    streamPath: (href, lane, resumeId) =>
-      `/_/sync?document-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}`,
+    streamPath: (href, lane, resumeId, clientId) =>
+      `/_/sync?document-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
   },
   // What every published clayjs speaks, and what hyperclayjs and the inline script in
   // every Collection dashboard hardcode. Hosts keep these addresses permanently.
@@ -92,8 +103,8 @@ const WIRE_PROFILES = {
     relayPath: '/_/live-sync/save',
     documentHeader: 'Page-URL',
     snapshotKey: 'html',
-    streamPath: (href, lane, resumeId) =>
-      `/_/live-sync/stream?page-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}`,
+    streamPath: (href, lane, resumeId, clientId) =>
+      `/_/live-sync/stream?page-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
   },
 };
 
@@ -168,6 +179,11 @@ class LiveSync {
     // cleanly. It rides in the slot beside the bytes it describes so the two can
     // never be separated, which is the whole rule (§6, and §22 of the plan).
     this._pendingEtag = null;
+    // Who the server says sent the pending frame, `{ id, name }`. Rides in the
+    // slot for the same reason the stamp does: it describes these bytes and
+    // nothing else, so a newer frame replacing them takes its author with it.
+    // Reported on `clay:sync-applied` once the frame has actually applied.
+    this._pendingBy = null;
     this._morphInFlight = false;
     this._rafHandle = null;
 
@@ -327,6 +343,10 @@ class LiveSync {
       this.sse = null;
     }
 
+    // Nothing feeds the roster once the stream is gone, so leaving the stack up
+    // would show a list of people who may all have left.
+    presence.clear();
+
     if (this._snapshotHandler) {
       document.removeEventListener('clay:snapshot-ready', this._snapshotHandler);
       this._snapshotHandler = null;
@@ -350,6 +370,7 @@ class LiveSync {
     this._pendingHtml = null;
     this._pendingSeq = null;
     this._pendingIdentityMap = null;
+    this._pendingBy = null;
     this._pendingExternal = null;
     clearTimeout(this._holdRetryPeer);
     clearTimeout(this._holdRetryExt);
@@ -382,33 +403,25 @@ class LiveSync {
     const map = {};
     if (!liveRoot || !cloneRoot) return map;
 
-    const visit = (live, clone, path) => {
-      let id = this.liveWeakMap.get(live);
-      if (!id) {
-        id = this._mintId();
-        this.liveWeakMap.set(live, id);
+    const visit = (clone, path) => {
+      const live = originalSnapshotNode(clone);
+      if (live) {
+        let id = this.liveWeakMap.get(live);
+        if (!id) {
+          id = this._mintId();
+          this.liveWeakMap.set(live, id);
+        }
+        map[path] = id;
       }
-      map[path] = id;
 
-      const liveKids = [];
-      for (const c of live.children) {
-        if (!isSnapshotRemoved(c)) liveKids.push(c);
-      }
       const cloneKids = clone.children;
 
-      if (liveKids.length !== cloneKids.length) {
-        this._log(
-          `identity map: subtree skipped at "${path}" (live=${liveKids.length}, clone=${cloneKids.length})`
-        );
-        return;
-      }
-
-      for (let i = 0; i < liveKids.length; i++) {
-        visit(liveKids[i], cloneKids[i], path === '' ? String(i) : `${path}.${i}`);
+      for (let i = 0; i < cloneKids.length; i++) {
+        visit(cloneKids[i], path === '' ? String(i) : `${path}.${i}`);
       }
     };
 
-    visit(liveRoot, cloneRoot, '');
+    visit(cloneRoot, '');
     return map;
   }
 
@@ -511,7 +524,11 @@ class LiveSync {
   _resolveProfile() {
     if (!this._profilePromise) {
       this._profilePromise = hostMeta()
-        .then((meta) => (meta?.extensions?.includes('sync') ? WIRE_PROFILES.spec : WIRE_PROFILES.legacy))
+        .then((meta) => {
+          const extensions = meta?.extensions || [];
+          this._sharedSync = extensions.includes('sync') && extensions.includes('sync-worker') && !extensions.includes('presence');
+          return extensions.includes('sync') ? WIRE_PROFILES.spec : WIRE_PROFILES.legacy;
+        })
         .catch(() => WIRE_PROFILES.legacy)
         .then((profile) => {
           this._profile = profile;
@@ -590,10 +607,14 @@ class LiveSync {
     // Whichever wire discovery selected. start() does not call connect() until the
     // profile is known, so this is never null on the normal path.
     const profile = this._profile || WIRE_PROFILES.legacy;
-    const path = profile.streamPath(window.location.href, this.lane, this.resumeId);
+    const path = profile.streamPath(window.location.href, this.lane, this.resumeId, this.clientId);
     // Resolved against the real origin: a <base href> in the authored document
     // would otherwise point the sync stream at an origin the document chose.
-    this.sse = new EventSource(new URL(path, window.location.origin).href);
+    this.sse = new SyncStream(new URL(path, window.location.origin).href, {
+      shared: this._sharedSync,
+      documentURL: window.location.href,
+      lane: this.lane,
+    });
 
     this.sse.onopen = () => {
       console.log('[LiveSync] Connected');
@@ -628,6 +649,21 @@ class LiveSync {
       });
     });
 
+    // The roster is a NAMED event for the same reason the cursor frame is: a tab
+    // with no listener for it never sees a bare data line, so every published
+    // client is counted in the roster without being sent one. The frame is
+    // handed on untouched — who is named is the host's decision, taken per
+    // recipient from that recipient's own access, and nothing here can widen it.
+    this.sse.addEventListener('presence', (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      presence.update(data);
+    });
+
     this.sse.onmessage = (event) => {
       const data = JSON.parse(event.data);
 
@@ -696,7 +732,7 @@ class LiveSync {
       }
 
       this._log(`Received update from: ${sender} (my clientId: ${this.clientId}, seq=${seq})`);
-      this.applyUpdate(html, seq, identityMap, etag);
+      this.applyUpdate(html, seq, identityMap, etag, data.by);
       if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap, etag });
     };
 
@@ -924,7 +960,7 @@ class LiveSync {
     const info = data.data;
     if (info && info.kind === 'external-change') {
       if (typeof info.html === 'string') {
-        this._enqueueExternal(info.html, data.seq, info.etag);
+        this._enqueueExternal(info.html, data.seq, info.etag, info.by);
       } else {
         this._fetchExternalChange(data.seq);
       }
@@ -937,7 +973,7 @@ class LiveSync {
     return false;
   }
 
-  _enqueueExternal(html, seq, etag) {
+  _enqueueExternal(html, seq, etag, by) {
     if (typeof seq === 'number') {
       if (seq <= this._lastExternalSeq) {
         this._log(`Dropping replayed external change: seq=${seq}`);
@@ -950,6 +986,11 @@ class LiveSync {
       seq,
       saveEpoch: this._saveEpoch,
       etag: typeof etag === 'string' && etag ? etag : null,
+      // Carried for the same reason the stamp is, and null on every disk frame
+      // today: hyperclay stamps an author on the two live relays and nowhere
+      // else, so a change that arrived from the filesystem has no author to
+      // name. The slot carries it so a host that does stamp one is believed.
+      by: by ?? null,
     };
     this._scheduleNextFrame();
   }
@@ -977,6 +1018,7 @@ class LiveSync {
    */
   _fetchServedDocument(seq, { attempt = 0, repair = false } = {}) {
     const epoch = this._saveEpoch;
+    if (repair && typeof seq !== 'number') seq = this._lastExternalSeq;
     fetch(new URL(window.location.href), { cache: 'no-store' })
       .then((response) => (response.ok ? response.text() : null))
       .then((html) => {
@@ -987,7 +1029,7 @@ class LiveSync {
           // said replay cannot fix this page, so if the newer fetch fails there is
           // nothing else coming. Refetch rather than drop the only repair.
           if (repair && attempt < 3) {
-            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
+            this._fetchServedDocument(this._lastExternalSeq, { attempt: attempt + 1, repair });
           }
           return;
         }
@@ -1003,8 +1045,9 @@ class LiveSync {
         }
         // No stamp: this body came from a GET of the served page, which nobody
         // stamped, so the apply leaves the held stamp alone and etag.js asks the
-        // host for a replacement.
-        this._pendingExternal = { html, seq, saveEpoch: epoch, etag: null };
+        // host for a replacement. No author either, for the same reason — a GET
+        // answers what disk holds, not who put it there.
+        this._pendingExternal = { html, seq, saveEpoch: epoch, etag: null, by: null };
         this._scheduleNextFrame();
       })
       .catch((err) => {
@@ -1031,8 +1074,10 @@ class LiveSync {
    * @param {string} html - Full document HTML
    * @param {number} [seq] - Optional monotonic seq from the server
    * @param {Object} [identityMap] - Optional element-identity map from sender
+   * @param {string} [etag] - Optional version stamp for these bytes
+   * @param {Object} [by] - Optional `{ id, name }` author stamp for these bytes
    */
-  applyUpdate(html, seq, identityMap, etag) {
+  applyUpdate(html, seq, identityMap, etag, by) {
     if (this.isDestroyed) return;
     this._pendingHtml = html;
     this._pendingSeq = seq;
@@ -1041,6 +1086,7 @@ class LiveSync {
     // correct: the stamp belongs to bytes that are no longer what will apply.
     // Losing it costs one honest 412 later, which is the safe direction.
     this._pendingEtag = etag ?? null;
+    this._pendingBy = by ?? null;
     this._scheduleNextFrame();
   }
 
@@ -1098,7 +1144,7 @@ class LiveSync {
       } else {
         this._morphInFlight = true;
         try {
-          await this._doApplyExternal(ext.html, ext.seq, ext.etag);
+          await this._doApplyExternal(ext.html, ext.seq, ext.etag, ext.by);
         } catch (err) {
           console.error('[LiveSync] applyExternal failed:', err);
         } finally {
@@ -1110,15 +1156,17 @@ class LiveSync {
       const seq = this._pendingSeq;
       const identityMap = this._pendingIdentityMap;
       const etag = this._pendingEtag;
+      const by = this._pendingBy;
       this._pendingHtml = null;
       this._pendingSeq = null;
       this._pendingIdentityMap = null;
       this._pendingEtag = null;
+      this._pendingBy = null;
       if (html == null) return;
 
       this._morphInFlight = true;
       try {
-        await this._doApplyUpdate(html, seq, identityMap, etag);
+        await this._doApplyUpdate(html, seq, identityMap, etag, by);
       } catch (err) {
         console.error('[LiveSync] applyUpdate failed:', err);
       } finally {
@@ -1157,9 +1205,11 @@ class LiveSync {
    * @param {string} html
    * @param {number} [seq]
    * @param {Object} [identityMap]
+   * @param {string} [etag]
+   * @param {Object} [by]
    * @returns {Promise<void>}
    */
-  async _doApplyUpdate(html, seq, identityMap, etag) {
+  async _doApplyUpdate(html, seq, identityMap, etag, by = null) {
     this._log('applyUpdate - pausing mutations and morphing');
     this.isPaused = true;
 
@@ -1247,6 +1297,7 @@ class LiveSync {
             this._pendingHtml = html;
             this._pendingSeq = seq;
             this._pendingIdentityMap = identityMap;
+            this._pendingBy = by;
             this._scheduleNextFrame();
           }, 3000);
           return;
@@ -1354,8 +1405,13 @@ class LiveSync {
       // `source` is what lets a listener tell the two apply paths apart. clay.wire
       // waits for a DISK frame to call an agent's write landed, and another tab's
       // edit arriving first would otherwise report the wrong bytes as delivered.
+      //
+      // `by` is the server's answer about who sent these bytes, and it is on the
+      // event rather than on the frame's arrival for one reason: a frame that held
+      // returns above without reaching here, so nothing can name an author for a
+      // change this tab never took. Null on every frame the host did not stamp.
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'peer' }
+        detail: { seq, source: 'peer', by: by || null }
       }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
@@ -1392,7 +1448,7 @@ class LiveSync {
    * holds or a later dirty peer apply misclassifies this frame's content as
    * local edits.
    */
-  async _doApplyExternal(html, seq, etag = null) {
+  async _doApplyExternal(html, seq, etag = null, by = null) {
     this._log(`applyExternal - external disk change (seq=${seq})`);
     this.isPaused = true;
 
@@ -1432,7 +1488,7 @@ class LiveSync {
           this._holdRetryExt = setTimeout(() => {
             this._holdRetryExt = null;
             if (this.isDestroyed || this._pendingExternal != null) return;
-            this._pendingExternal = { html, seq, saveEpoch: epochAtHold, etag };
+            this._pendingExternal = { html, seq, saveEpoch: epochAtHold, etag, by };
             this._scheduleNextFrame();
           }, 3000);
           return;
@@ -1501,7 +1557,15 @@ class LiveSync {
       }
 
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'disk', etag: typeof etag === 'string' && etag ? etag : null }
+        detail: {
+          seq,
+          source: 'disk',
+          etag: typeof etag === 'string' && etag ? etag : null,
+          by: by || null,
+          // The bytes now on disk, exactly as they arrived. The source map models them
+          // so this tab's next save copies from the file somebody else just wrote.
+          html,
+        }
       }));
     } finally {
       this._log('applyExternal - morph complete, resuming mutations');

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;