@panphora/clayjs 1.12.1 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "type": "module",
   "description": "clayjs: malleable documents. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",
@@ -29,6 +29,7 @@
   "exports": {
     "./package.json": "./package.json",
     "./THIRD-PARTY-NOTICES.md": "./THIRD-PARTY-NOTICES.md",
+    "./guide.md": "./docs/guide.md",
     "./src/*": "./src/*",
     "./entries/*": "./entries/*",
     "./clay.standalone.js": "./dist/clay.standalone.js",
@@ -41,6 +42,7 @@
     "entries/",
     "dist/",
     "THIRD-PARTY-NOTICES.md",
+    "docs/guide.md",
     "src/"
   ],
   "publishConfig": {
@@ -60,6 +62,7 @@
     "check:foundation": "node scripts/propagate-foundation.mjs --check",
     "deploy": "node build.js && wrangler deploy && git rev-parse HEAD > .deploy",
     "build:parse5": "node scripts/build-parse5-vendor.mjs",
+    "build:prosemirror": "node scripts/build-prosemirror-vendor.mjs",
     "build:bevel": "node scripts/build-bevel-subset.mjs",
     "check:bevel": "node scripts/build-bevel-subset.mjs --check",
     "build:skins": "node scripts/build-vendor-skins.mjs",
@@ -79,6 +82,16 @@
     "parse5": "^7.3.0",
     "playwright": "1.62.1",
     "postcss": "^8.5.28",
+    "prosemirror-commands": "1.7.2",
+    "prosemirror-dropcursor": "1.8.4",
+    "prosemirror-gapcursor": "1.4.1",
+    "prosemirror-history": "1.5.1",
+    "prosemirror-inputrules": "1.5.1",
+    "prosemirror-keymap": "1.2.3",
+    "prosemirror-model": "1.25.12",
+    "prosemirror-state": "1.4.4",
+    "prosemirror-transform": "1.12.2",
+    "prosemirror-view": "1.42.6",
     "turndown": "^7.2.4",
     "turndown-plugin-gfm": "^1.0.2"
   },

package/packed-contract.json

@@ -13,6 +13,6 @@
     "@panphora/clayjs/entries/sap.js",
     "@panphora/clayjs/clay.standalone.js"
   ],
-  "members": ["THIRD-PARTY-NOTICES.md"],
+  "members": ["THIRD-PARTY-NOTICES.md", "docs/guide.md"],
   "families": ["./entries/*", "./dist/*", "./src/*"]
 }

package/src/lib/unsaved-state.js

@@ -11,9 +11,9 @@
 const sources = new Map();
 let nextKey = 0;
 
-export function registerUnsavedState({ id = '', isPending }) {
+export function registerUnsavedState({ id = '', isPending, flush = null }) {
   const key = ++nextKey;
-  sources.set(key, { id, isPending });
+  sources.set(key, { id, isPending, flush });
   let disposed = false;
   return {
     changed() {
@@ -49,6 +49,15 @@ export function hasUnsavedState() {
   return false;
 }
 
+// Ask every pending source that can finish on its own (a checkpoint, a queued
+// upload) to do so, and wait. Sources without a flush (an open composition)
+// stay pending; they are listed in the answer, never waited on.
+export async function flushUnsaved() {
+  const flushes = [...sources.values()].filter((s) => typeof s.flush === 'function' && isPending(s));
+  const results = await Promise.all(flushes.map((s) => Promise.resolve().then(s.flush).catch(() => ({ ok: false }))));
+  return { ok: results.every((r) => r?.ok !== false), pending: pendingIds() };
+}
+
 if (typeof window !== 'undefined') {
   window.clay = window.clay || {};
   window.clay.registerUnsavedState = registerUnsavedState;

package/src/live/checkpoint.js

@@ -95,6 +95,13 @@ export function createCheckpoints({ needsSave, blocked, save, saveNow, now = ()
       const at = Math.max(now(), retryAt);
       if (deadline === null || at < deadline) arm(at);
     },
+    // Save no later than ms from now (the page editor's pause save). Never
+    // later than a deadline already set, never before a failed save's retry time.
+    within(ms) {
+      if (running) return;
+      const at = Math.max(now() + ms, retryAt);
+      if (deadline === null || at < deadline) arm(at);
+    },
     // True while the hide/close save is being made.
     get flushing() {
       return flushing;

package/src/live/fast-lane.js

@@ -91,6 +91,8 @@ export function createFastLane({
   // newest op id ever put in a frame.
   const lanes = new Map();
 
+  const tell = (name, event) => entries.get(name)?.store.deliver?.({ code: null, n: null, seq: null, through: null, retryAfter: null, ...event });
+
   function laneOf(name) {
     let lane = lanes.get(name);
     if (!lane) lanes.set(name, (lane = { n: 0, unsent: [], awaiting: [], framed: 0 }));
@@ -115,7 +117,7 @@ export function createFastLane({
     const store = entries.get(name)?.store;
     let through = 0;
     for (const frame of lane.awaiting) if (!unapplied(frame)) through = frame.through;
-    if (store && through) store.rebase(store.authoritative, { source: "state", through });
+    if (store && through) store.rebase(store.authoritative, { source: "state", through, cause: "leave" });
     onLeave(name, { epoch, seq });
     lane.unsent = [];
     lane.awaiting = [];
@@ -156,7 +158,8 @@ export function createFastLane({
         const [entry] = lane.unsent.splice(0, 1);
         console.warn(`clay.live("${name}"): one update was larger than ${FRAME_BYTES} bytes, so it was undone`);
         const store = entries.get(name)?.store;
-        store?.rebase(store.authoritative, { source: "state", through: entry.id });
+        store?.rebase(store.authoritative, { source: "state", through: entry.id, cause: "undone" });
+        tell(name, { phase: "undone", code: "op-too-large", through: entry.id });
         continue;
       }
       const take = lane.unsent.splice(0, count);
@@ -178,6 +181,7 @@ export function createFastLane({
     const sentEpoch = epoch;
     frame.sentOn = connection;
     frame.sent = true;
+    tell(name, { phase: "sent", n: frame.n, through: frame.through });
     // Refusal is evidence about earlier attempts only: this one may apply.
     frame.refused = false;
     inFlight = true;
@@ -212,7 +216,7 @@ export function createFastLane({
     }
     lane.awaiting.splice(lane.awaiting.indexOf(frame), 1);
     const store = entries.get(name)?.store;
-    store?.rebase(store.authoritative, { source: "state", through: frame.through });
+    store?.rebase(store.authoritative, { source: "state", through: frame.through, cause: "decided" });
   }
 
   // Every frame the room ordered at or before the applied seq is in the
@@ -225,7 +229,7 @@ export function createFastLane({
       }
       if (through === undefined) continue;
       const store = entries.get(name)?.store;
-      store?.rebase(store.authoritative, { source: "state", through });
+      store?.rebase(store.authoritative, { source: "state", through, cause: "settled" });
     }
   }
 
@@ -246,12 +250,14 @@ export function createFastLane({
         return;
       }
       frame.seq = Number.isInteger(body?.seq) ? body.seq : null;
+      tell(name, { phase: "landed", n: frame.n, seq: frame.seq, through: frame.through });
       // Its event already went by, or came inside a state this tab took: the ops are in.
       settleAwaiting();
       return;
     }
     if (transient(status)) {
       frame.sent = false;
+      tell(name, { phase: "retry", code: body?.code ?? (status === 0 ? "offline" : status === 429 ? "rate-limited" : "server"), n: frame.n, through: frame.through, retryAfter: retryAfter ?? null });
       if (unhandled(status)) frame.refused = true;
       else {
         frame.uncertain = true;
@@ -268,6 +274,7 @@ export function createFastLane({
       // The room holds a receipt for every connected sender and has no room for
       // this one: this store goes at save speed until the room takes it back.
       if (status === 503 && body?.code === "busy") {
+        tell(name, { phase: "left", code: "busy", n: frame.n, through: frame.through });
         console.warn(`clay.live("${name}"): the room is full, so it stays at save speed for now`);
         roomNames.delete(name);
         leaveRoom(name, lane);
@@ -285,12 +292,14 @@ export function createFastLane({
       return;
     }
     if (REVOKED.has(status)) {
+      tell(name, { phase: "refused", code: "revoked", n: frame.n, through: frame.through });
       if (!frame.uncertain) frame.refused = true;
       stop();
       return;
     }
     const reason = body?.error || body?.code || `status ${status}`;
     if (status === 404) {
+      tell(name, { phase: "left", code: "no-store", n: frame.n, through: frame.through });
       console.warn(`clay.live("${name}"): the room has no such store, so it stays at save speed (${reason})`);
       frame.refused = true;
       roomNames.delete(name);
@@ -299,8 +308,9 @@ export function createFastLane({
     }
     lane.awaiting.splice(lane.awaiting.indexOf(frame), 1);
     const store = entries.get(name)?.store;
+    tell(name, { phase: "refused", code: body?.code ?? "refused", n: frame.n, through: frame.through });
     console.warn(`clay.live("${name}"): the host refused an update, so it was undone (${reason})`);
-    store?.rebase(store.authoritative, { source: "state", through: frame.through });
+    store?.rebase(store.authoritative, { source: "state", through: frame.through, cause: "refused" });
   }
 
   function apply(frame) {
@@ -321,10 +331,11 @@ export function createFastLane({
       const i = lane.awaiting.findIndex((sent) => sent.n === frame.n);
       if (i >= 0) {
         through = lane.awaiting[i].through;
+        tell(frame.name, { phase: "echoed", n: frame.n, seq: frame.seq, through });
         lane.awaiting.splice(0, i + 1);
       }
     }
-    store.rebase(next, { source: own ? "state" : "remote", through });
+    store.rebase(next, { source: own ? "state" : "remote", through, frame: { seq: frame.seq, from: frame.from, n: frame.n, ops: frame.ops } });
     entries.get(frame.name).last = frame.seq;
     onApplied();
     if (frame.checkpoint === true) onCheckpoint();
@@ -411,7 +422,7 @@ export function createFastLane({
           frame.seq = null;
         }
         lane.awaiting = resend;
-        entry.store.rebase(room.value, { source: "state", through: through || undefined });
+        entry.store.rebase(room.value, { source: "state", through: through || undefined, room: { seq, fresh: true, moves: state.moves?.[name] ?? null, floor: Number.isInteger(room.floor) ? room.floor : null } });
         lane.unsent = unframed(name, lane);
       } else {
         const seen = room.seen ? room.seen[clientId] : undefined;
@@ -439,7 +450,7 @@ export function createFastLane({
           }
         }
         lane.awaiting = next;
-        entry.store.rebase(room.value, { source: "state", through });
+        entry.store.rebase(room.value, { source: "state", through, room: { seq, fresh: false, moves: state.moves?.[name] ?? null, floor: Number.isInteger(room.floor) ? room.floor : null } });
         // Back in the room after a spell at save speed: frame what was made meanwhile.
         if (rejoined) {
           lane.unsent = unframed(name, lane);
@@ -476,7 +487,7 @@ export function createFastLane({
     const asked = { connection, stateCount };
     let state = null;
     try {
-      state = await transport.fetchState(clientId);
+      state = await transport.fetchState(clientId, epoch !== null && seq > 0 ? { epoch, seq } : null);
     } catch {}
     fetching = false;
     if (stopped) return;
@@ -544,7 +555,10 @@ export function createFastLane({
         stateCount++;
         for (const [name, landed] of Object.entries(data.landed)) {
           const entry = entries.get(name);
-          if (entry && Number.isInteger(landed)) entry.landed = landed;
+          if (entry && Number.isInteger(landed)) {
+            entry.landed = landed;
+            tell(name, { phase: "checkpointed", seq: landed });
+          }
         }
         onLanded();
       }

package/src/live/local-lane.js

@@ -20,6 +20,7 @@
 
 import { applyOps, applyOp, checkOp, cloneJson, validateOp, serializeLive, textHash, diffOps } from "./ops.js";
 import { HyperMorph } from "../vendor/hyper-morph.vendor.js";
+import { movesSince } from "./moves.js";
 
 const VERSION = 4;
 export const REQUEST_MS = 2000;
@@ -118,14 +119,20 @@ export function localTransport({ seed, key = "clay-live:" + window.location.path
 
   const landedIn = (m) => (m.behind || m.landed === null ? -1 : m.landed);
 
-  function roomState() {
+  function roomState(since = null) {
     const stores = {};
     const meta = {};
     for (const [name, m] of mirror.stores) {
       stores[name] = { value: cloneJson(m.value), ephemeral: m.ephemeral, seen: receiptsFor(name), last: m.last, landed: landedIn(m) };
       meta[name] = { log: m.log, last: m.last, landed: m.landed, floor: m.floor, behind: m.behind, file: m.file, inFile: m.inFile };
     }
-    return { epoch: room.epoch, seq: room.seq, writer: clientId, stores, mirror: { seen: [...mirror.seen], stores: meta } };
+    const state = { epoch: room.epoch, seq: room.seq, writer: clientId, stores, mirror: { seen: [...mirror.seen], stores: meta } };
+    if (since && since.epoch === mirror.epoch) {
+      const moves = {};
+      for (const [name, m] of mirror.stores) moves[name] = movesSince(m, since);
+      state.moves = moves;
+    }
+    return state;
   }
 
   function alreadyMerged(m, frame) {
@@ -507,7 +514,7 @@ export function localTransport({ seed, key = "clay-live:" + window.location.path
     } else if (room && m.type === "post") {
       if (m.epoch === room.epoch) post({ type: "answer", to: m.from, rid: m.rid, result: roomApply(m.from, m.frame) });
     } else if (room && m.type === "state-request") {
-      post({ type: "answer", to: m.from, rid: m.rid, result: roomState() });
+      post({ type: "answer", to: m.from, rid: m.rid, result: roomState(m.since) });
     }
   }
 
@@ -554,11 +561,11 @@ export function localTransport({ seed, key = "clay-live:" + window.location.path
     // The sequencer's state, installed into the mirror first. An answer to a
     // request made before the mirror changed (another state, or this tab
     // starting a room) is dropped: the lane asks again or already has it.
-    async fetchState() {
-      if (room) return roomState();
+    async fetchState(_clientId, since = null) {
+      if (room) return roomState(since);
       const asked = gen;
-      const state = await request({ type: "state-request" });
-      if (room) return roomState();
+      const state = await request({ type: "state-request", since });
+      if (room) return roomState(since);
       if (asked !== gen || !install(state)) return null;
       return state;
     },

package/src/live/moves.js

@@ -0,0 +1,11 @@
+// The moves a store's log holds after `since` ({ epoch, seq }), for a tab that
+// already applied everything through since.seq. [] when nothing is newer; null
+// when the log no longer reaches back that far (its floor is past since.seq),
+// so the tab cannot replay and takes the value as it is. A log may start above
+// since.seq + 1 with nothing missing: the seqs between went to other stores.
+export function movesSince(store, since) {
+  if (!since || !Number.isInteger(since.seq)) return null;
+  if (since.seq >= (store.last ?? 0)) return [];
+  if (since.seq < (store.floor ?? 0)) return null;
+  return store.log.filter((entry) => entry.seq > since.seq).map((entry) => ({ seq: entry.seq, ops: entry.ops }));
+}

package/src/live/server-lane.js

@@ -39,9 +39,10 @@ export async function relayData(clientId, frame) {
  * The room's { epoch, seq, writer, stores }; { status } when the host refused;
  * null when the request never got an answer. clientId marks this tab as taking part.
  */
-export async function fetchLiveState(clientId) {
+export async function fetchLiveState(clientId, since = null) {
   const url = dataUrl();
   if (clientId) url.searchParams.set("client-id", clientId);
+  if (since && typeof since.epoch === "string" && Number.isInteger(since.seq)) url.searchParams.set("since", `${since.epoch}:${since.seq}`);
   try {
     const response = await fetch(url.href, {
       credentials: "same-origin",

package/src/live/store.js

@@ -47,6 +47,8 @@ export function createStore({ name, value, ephemeral = false }) {
   let mode = "file";
   const listeners = new Set();
   const sinks = new Set();
+  const rebases = new Set();
+  const deliveries = new Set();
   const views = new WeakMap();
 
   function emit(source, ops) {
@@ -275,17 +277,46 @@ export function createStore({ name, value, ephemeral = false }) {
     // `confirmed` pending ops, or every op up to the mark `through`. The rest
     // replay over it; a pending op that no longer applies is dropped too.
     // Listeners hear about it only when the value page code sees changed.
-    rebase(next, { source = "remote", confirmed = 0, through } = {}) {
+    rebase(next, { source = "remote", confirmed = 0, through, frame = null, room = null, cause = null } = {}) {
       if (!isContainer(next) || kind(next) !== kind(state)) {
         console.warn(`clay.live("${name}"): ignored an incoming value that is not ${kind(state)}`);
         return false;
       }
       const before = serializeLive(state);
+      const prev = authoritative;
       authoritative = cloneJson(next);
       pending = through === undefined ? pending.slice(confirmed) : pending.filter((entry) => entry.id > through);
       rebuild();
+      for (const fn of [...rebases]) {
+        try {
+          fn({ source, frame, room, cause, prev, next: authoritative });
+        } catch (err) {
+          console.error(`clay.live("${name}"): a rebase listener threw`, err);
+        }
+      }
       if (serializeLive(state) !== before) emit(source, null);
       return true;
     },
+    // Every rebase, whether or not the value page code sees changed, with what
+    // caused it: the frame the room applied, the state read, or the lane's own
+    // settling. For the page editor; never on the handle.
+    onRebase(fn) {
+      rebases.add(fn);
+      return () => rebases.delete(fn);
+    },
+    // What became of this tab's frames: { phase, code, n, seq, through, retryAfter }.
+    onDelivery(fn) {
+      deliveries.add(fn);
+      return () => deliveries.delete(fn);
+    },
+    deliver(event) {
+      for (const fn of [...deliveries]) {
+        try {
+          fn(event);
+        } catch (err) {
+          console.error(`clay.live("${name}"): a delivery listener threw`, err);
+        }
+      }
+    },
   };
 }

package/src/loader-logic.js

@@ -42,6 +42,9 @@ export const PLUGIN_PATHS = {
   // Who is editing and who wrote what. Not editOnly: a reader still sees names.
   people:    { path: "plugins/people.js",          editOnly: false, default: false },
   wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
+  // A visitor's contact form to the document's owner. Not editOnly: visitors are
+  // who send messages.
+  message:   { path: "plugins/message.js",         editOnly: false, default: false },
   // Edit mode only: the AI comment box is an editing gesture. Opt in with
   // `plugins=ai-edit`; it stays dormant on any host that does not list a ready
   // `ai-edit` helper.
@@ -100,6 +103,7 @@ export const MODULES = {
   "plugins/upload.js":          () => import("./plugins/upload.js"),
   "plugins/people.js":          () => import("./plugins/people.js"),
   "plugins/wire.js":            () => import("./plugins/wire.js"),
+  "plugins/message.js":         () => import("./plugins/message.js"),
   "plugins/ai-edit.js":         () => import("./plugins/ai-edit.js"),
   "plugins/demo.js":            () => import("./plugins/demo.js"),
   "plugins/visitor-drafts.js": () => import("./plugins/visitor-drafts.js"),
@@ -108,7 +112,7 @@ export const MODULES = {
 
 // `source` is last on purpose: its install captures a save clone, so it wants every
 // plugin that registers a document transform to have registered it first.
-const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "people", "cms", "sync", "live", "wire", "ai-edit", "demo", "source"];
+const PLUGIN_ORDER = ["visitor-drafts", "richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "people", "cms", "sync", "live", "message", "wire", "ai-edit", "demo", "source"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through
 // a capability lookup (`clay.quickcrop`) and silently uploads the raw file when it

package/src/loader.js

@@ -141,6 +141,8 @@ function attachPluginMember(path, mod, loaded) {
     clay.people = mod.people;
     clay.author = mod.author;
     Object.defineProperty(clay, "me", { get: mod.currentMe, configurable: true, enumerable: true });
+  } else if (path === "plugins/message.js") {
+    clay.message = mod.message;
   } else if (path === "plugins/wire.js") {
     clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/ai-edit.js") {