@panphora/clayjs 1.17.0 → 1.18.0

package/src/source/session.js

@@ -28,7 +28,9 @@
  *
  * NOTHING HERE BLOCKS BOOT. The install is async and the loader does not wait for
  * it. Only the save that asked for it waits, and a save after a failed install is the
- * ordinary full serialization rather than an error.
+ * ordinary full serialization rather than an error. For a large document that wait is
+ * itself sliced: the model is parsed across tasks, and so is a queued repair, on the same
+ * driver and the same threshold the save's own preparation uses.
  *
  * ON DEMAND
  *
@@ -50,15 +52,18 @@
 
 import {
   model,
+  modelSteps,
   checkSource,
   locate,
   nodeAt,
   pair,
-  pairCaptured,
+  pairCapturedSteps,
+  pairSteps,
   render,
-  verify,
-  verifyForSave
+  verifyForSaveSteps,
+  verifyRenderedSteps
 } from '../core/source-map.js';
+import { drain, runSliced } from '../lib/slice.js';
 import {
   attachCaptureArtifact,
   captureSaveClone,
@@ -66,7 +71,8 @@ import {
   originalSnapshotNode,
   setSaveRenderer
 } from '../core/snapshot.js';
-import { onSaveAccepted } from '../core/save-core.js';
+import { keepaliveHeld, onSaveAccepted } from '../core/save-core.js';
+import { SLICED_SAVE_MIN_BYTES } from '../core/save-slices.js';
 import { lastSeenEtag } from '../core/etag.js';
 
 const state = {
@@ -110,6 +116,28 @@ const SUPERSEDED_RETRIES = 2;
 
 const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
 
+// The main-thread time one slice of an install or a repair may spend before handing the
+// page back. The same budget the save's own preparation takes.
+const SLICED_STEP_BUDGET_MS = 4;
+
+// What an install's steps answer when a save or a disk frame replaced the file while they
+// ran: no answer at all, and the caller asks again.
+const SUPERSEDED = Object.freeze({ superseded: true });
+
+/**
+ * Whether a walk over bytes this big runs across tasks instead of in one.
+ *
+ * The threshold and both exceptions are the save's (core/save-slices.js): below
+ * `SLICED_SAVE_MIN_BYTES` the one-task walk is cheaper than the scheduling, a hidden tab
+ * has no typing to protect and its timers are throttled, and a keepalive save belongs to
+ * a page that is going away and cannot wait for a task boundary.
+ */
+function slicesWalk(bytes) {
+  if (document.hidden) return false;
+  if (keepaliveHeld()) return false;
+  return bytes >= SLICED_SAVE_MIN_BYTES;
+}
+
 const PROJECTED_MAP_PREFIX = '<script type="application/json" id="clay-runtime-map"';
 
 /**
@@ -171,6 +199,11 @@ function pairAgainstPage(m) {
   return pair(clone, m, originalSnapshotNode);
 }
 
+function* pairAgainstPageSteps(m) {
+  const clone = captureSaveClone({ flushUndo: false, authored: false });
+  return yield* pairSteps(clone, m, originalSnapshotNode);
+}
+
 /**
  * The version a set of bytes names for itself, or null when nothing stamped it.
  *
@@ -212,7 +245,7 @@ function staleVersion(m, context) {
   return `source refused: the fetch answered version ${stamp} while this page holds ${held}`;
 }
 
-function install(sourceUrl, context = null, attempt = 0, render = true, latest = null) {
+async function install(sourceUrl, context = null, attempt = 0, render = true, latest = null) {
   const session = state.session;
   const t0 = now();
   const generation = state.adoptions;
@@ -225,40 +258,75 @@ function install(sourceUrl, context = null, attempt = 0, render = true, latest =
   const receiptBytes = receipt && typeof receipt.bytes === 'string' && !isProjected(receipt.bytes)
     ? receipt.bytes
     : null;
-  return (receiptBytes !== null ? Promise.resolve(receiptBytes) : fetchSource(sourceUrl)).then((src) => {
+  try {
+    const src = receiptBytes !== null ? receiptBytes : await fetchSource(sourceUrl);
     if (session !== state.session) return null;
     const t1 = now();
-    const m = model(src);
-    const refused = checkSource(m, document);
-    if (refused) throw new Error(`source refused: ${refused}`);
-    const stale = staleVersion(m, context);
-    if (stale) throw new Error(stale);
+    const answer = await runInstallSteps({ src, context, render, session, generation, t0, t1 });
+    if (answer !== SUPERSEDED) return answer;
     // A save was accepted, or a disk frame carried newer bytes, while this answer was on
     // its way. Those bytes are the file now, so ask again rather than adopt an older
     // answer; a page that will not hold still is refused instead of retried forever.
-    if (state.adoptions !== generation) {
-      if (attempt < SUPERSEDED_RETRIES) return install(sourceUrl, context, attempt + 1, render, latest);
-      throw new Error('source refused: a save replaced the file while the fetch was in flight');
-    }
-    const t2 = now();
-    const { map, stats } = pairAgainstPage(m);
-    const t3 = now();
-
-    state.model = m;
-    state.map = map;
-    state.stats = stats;
-    state.timing = { fetch: t1 - t0, model: t2 - t1, pair: t3 - t2, refresh: null };
-    state.installed = true;
-    if (render) setSaveRenderer(renderSave);
-    return summary();
-  }).catch((err) => {
+    if (attempt < SUPERSEDED_RETRIES) return install(sourceUrl, context, attempt + 1, render, latest);
+    throw new Error('source refused: a save replaced the file while the fetch was in flight');
+  } catch (err) {
     // Not an error the page can do anything about, and not a failure of the save:
     // saves go out exactly as they would without this plugin. Said once.
     if (session !== state.session) return null;
     state.refused = String(err && err.message ? err.message : err);
     console.info(`clayjs: source map off (${state.refused}); saves use the full serialization`);
     return null;
-  });
+  }
+}
+
+/**
+ * Model and pair the bytes an install fetched, as steps.
+ *
+ * `drain` is the install this module always had and `runSliced` is the same walk across
+ * tasks, so a large document's first use hands the page back while its model is parsed
+ * and again while the page is paired against it: the pairing has a step form too, and
+ * yields every `YIELD_EVERY` nodes hashed or bound.
+ *
+ * Nothing is written to the session until the last yield is behind it, and an install
+ * whose page moved underneath it answers `SUPERSEDED` or null rather than installing a
+ * model of bytes the file no longer holds.
+ */
+function* installSteps(job) {
+  const m = yield* modelSteps(job.src);
+  const refused = checkSource(m, document);
+  if (refused) throw new Error(`source refused: ${refused}`);
+  const stale = staleVersion(m, job.context);
+  if (stale) throw new Error(stale);
+  if (state.adoptions !== job.generation) return SUPERSEDED;
+  const t2 = now();
+  yield;
+  if (state.session !== job.session) return null;
+  if (state.adoptions !== job.generation) return SUPERSEDED;
+  const { map, stats } = yield* pairAgainstPageSteps(m);
+  if (state.session !== job.session) return null;
+  if (state.adoptions !== job.generation) return SUPERSEDED;
+  const t3 = now();
+
+  state.model = m;
+  state.map = map;
+  state.stats = stats;
+  state.timing = { fetch: job.t1 - job.t0, model: t2 - job.t1, pair: t3 - t2, refresh: null };
+  state.installed = true;
+  if (job.render) setSaveRenderer(renderSave, { steps: renderSaveSteps });
+  return summary();
+}
+
+/**
+ * Run one install's steps in this task or across tasks, by the document's size.
+ *
+ * A session that ends while the walk yields aborts it, so a late answer installs nothing,
+ * which is the rule the fetch half already followed.
+ */
+async function runInstallSteps(job) {
+  if (!slicesWalk(job.src.length)) return drain(installSteps(job));
+  const signal = { get aborted() { return state.session !== job.session; } };
+  const answer = await runSliced(installSteps(job), { budgetMs: SLICED_STEP_BUDGET_MS, signal });
+  return answer && answer.aborted === true ? null : answer;
 }
 
 /**
@@ -292,12 +360,28 @@ function install(sourceUrl, context = null, attempt = 0, render = true, latest =
  * describes the live page there.
  */
 export function renderSave(clone, today, opts = {}) {
+  return drain(renderSaveSteps(clone, today, opts));
+}
+
+/**
+ * The same render, sliced: exactly one generator, so a save can run its verification
+ * across tasks without a second copy of this logic. Every assignment to the session
+ * happens after the last yield of its phase, so a slice that is aborted leaves the
+ * session as it was found and the next save renders from the same state.
+ *
+ * The generation the render started from is recorded, because a morph or an accepted
+ * save can re-pair the map while the verifier is yielding. A render whose bytes were
+ * laid out against a map that has since been rebuilt describes a page that is no longer
+ * here, so it is refused like any other render that cannot be trusted: today's bytes.
+ */
+export function* renderSaveSteps(clone, today, opts = {}) {
   if (!state.installed) return today;
   // A refresh still waiting for idle time runs now, so this save never renders from a
   // map a morph made stale. It pairs against the page, not this clone: onbeforesave may
   // have changed the clone, and the map must describe the live page.
-  refreshNow();
-  state.lastOutcome = null;
+  yield* refreshNowSteps();
+  const session = state.session;
+  const generation = state.repairs;
   const capture = currentCaptureContext();
   const adoptable = !!capture && !capture.authoredHandlers;
   const print = new Set();
@@ -312,15 +396,21 @@ export function renderSave(clone, today, opts = {}) {
     // The verifier's retained parse is a cost, so it is only asked for when there is a
     // capture that could adopt it.
     const v = adoptable
-      ? verifyForSave(out.text, today, document, clone, state.model.parseErrors)
-      : verify(out.text, today, document, clone, state.model.parseErrors);
+      ? yield* verifyForSaveSteps(out.text, today, document, clone, state.model.parseErrors)
+      : yield* verifyRenderedSteps(out.text, today, document, clone, state.model.parseErrors, false);
     if (v.ok) {
-      state.lastRenderMs = out.ms;
-      state.lastBytes = out.text.length;
-      state.lastOutcome = print.size
+      const stale = renderSuperseded(session, generation);
+      if (stale) return fallback(stale, today);
+      const outcome = print.size
         ? { text: out.text, scope: 'partial', reason: firstDiff, printed: print.size }
         : { text: out.text, scope: null };
-      if (v.model) offerCandidate(v.model, out.text, clone, capture);
+      const paired = v.model ? yield* pairCapturedSteps(clone, v.model, originalSnapshotNode) : null;
+      const late = renderSuperseded(session, generation);
+      if (late) return fallback(late, today);
+      state.lastRenderMs = out.ms;
+      state.lastBytes = out.text.length;
+      state.lastOutcome = outcome;
+      if (v.model) offerCandidate(v.model, out.text, capture, paired);
       return out.text;
     }
     if (firstDiff === null) firstDiff = v.diff;
@@ -329,6 +419,17 @@ export function renderSave(clone, today, opts = {}) {
   return fallback(firstDiff, today);
 }
 
+/**
+ * Why a render this generator laid out can no longer be trusted, or null. Only a yield
+ * can make this answer yes: a drained render never leaves this task.
+ */
+function renderSuperseded(session, generation) {
+  if (state.session !== session) return 'render refused: the session ended while this render ran';
+  if (!state.installed) return 'render refused: the source map was uninstalled while this render ran';
+  if (state.repairs !== generation) return 'render refused: the map was re-paired while this render ran';
+  return null;
+}
+
 /**
  * Hand this capture the model of the bytes it just verified, or nothing.
  *
@@ -337,8 +438,7 @@ export function renderSave(clone, today, opts = {}) {
  * does not correspond, node for node, leaves the capture without an artifact, and the
  * accepted save takes the inspection path it takes today.
  */
-function offerCandidate(m, html, clone, capture) {
-  const paired = pairCaptured(clone, m, originalSnapshotNode);
+function offerCandidate(m, html, capture, paired) {
   if (!paired) return;
   attachCaptureArtifact({
     captureId: capture.captureId,
@@ -506,25 +606,76 @@ function queueRepair(event) {
 function scheduleRefresh() {
   if (state.refreshQueued) return;
   state.refreshQueued = true;
-  if (typeof requestIdleCallback === 'function') requestIdleCallback(refreshNow, { timeout: 2000 });
-  else setTimeout(refreshNow, 0);
+  if (typeof requestIdleCallback === 'function') requestIdleCallback(refreshSoon, { timeout: 2000 });
+  else setTimeout(refreshSoon, 0);
 }
 
 /**
- * Run a queued refresh now. A no-op when none is queued, which is also what makes the
- * idle callback of a refresh that `text()` or `locate()` already ran harmless.
+ * The queued refresh, run the way this document's size allows: in the caller's task for a
+ * small one, across tasks for a large one, so a repair nobody is waiting for does not hold
+ * the page for its whole duration.
+ */
+function refreshSoon() {
+  if (!slicesWalk(refreshBytes())) { refreshNow(); return; }
+  runSlicedRefresh();
+}
+
+/**
+ * How big the bytes a queued refresh is about to model are: the accepted save's or a disk
+ * frame's when there are any, else the model this session already holds.
+ */
+function refreshBytes() {
+  if (typeof state.pendingBytes === 'string') return state.pendingBytes.length;
+  return state.model ? state.model.src.length : 0;
+}
+
+/**
+ * A refresh across tasks, and the one thing a sliced walk needs that a drained one does
+ * not: a walk that stopped because something newer arrived left the queue in place, and
+ * that newer answer's `scheduleRefresh` had nothing to do because the flag was still set.
+ * So the same work is asked for again here. A session that ended drops it instead.
+ */
+async function runSlicedRefresh() {
+  const session = state.session;
+  const signal = { get aborted() { return state.session !== session; } };
+  try {
+    await runSliced(refreshNowSteps(), { budgetMs: SLICED_STEP_BUDGET_MS, signal });
+  } catch (err) {
+    console.warn('clayjs: source map could not run the queued repair:', err);
+  }
+  if (!state.refreshQueued || !state.installed || state.session !== session) return;
+  state.refreshQueued = false;
+  scheduleRefresh();
+}
+
+/**
+ * Run a queued refresh now, in this task. A no-op when none is queued, which is also what
+ * makes the idle callback of a refresh that `text()` or `locate()` already ran harmless.
+ * Everything that reads the session synchronously comes through here: it must answer in
+ * the caller's task, so it drains the same steps the idle refresh may resume across tasks.
  */
 function refreshNow() {
+  drain(refreshNowSteps());
+}
+
+/**
+ * The same refresh, sliced: modelling yields, and nothing the session holds is written
+ * until the last yield is behind it.
+ *
+ * An aborted slice must leave the queued refresh queued, with its bytes, so the work is
+ * simply done again — nothing is half-adopted, and no counter is charged twice. That is
+ * why the queue is read into locals and committed at the end, and why a newer model,
+ * adoption or session arriving during a yield abandons this attempt rather than
+ * overwriting it: the newer one left its own refresh queued.
+ */
+export function* refreshNowSteps() {
   if (!state.refreshQueued) return;
-  state.refreshQueued = false;
-  if (!state.installed) return;
+  if (!state.installed) { state.refreshQueued = false; return; }
+  const session = state.session;
+  const repairs = state.repairs;
+  const adoptions = state.adoptions;
   const bytes = state.pendingBytes;
-  state.pendingBytes = null;
   const refetch = state.refetch && bytes === null;
-  if (refetch) state.refetch = false;
-  // Counted even when the re-pair below fails: either way this page is not the page a
-  // candidate captured before it was built against.
-  state.repairs++;
   const t = now();
   // The two halves fail independently, so they are tried independently. A refused
   // re-model used to skip the re-pair with it, and the re-pair is the half that
@@ -535,7 +686,7 @@ function refreshNow() {
   let m = state.model;
   if (bytes !== null) {
     try {
-      const next = model(bytes);
+      const next = yield* modelSteps(bytes);
       const refused = checkSource(next, document);
       if (refused) throw new Error(refused);
       m = next;
@@ -543,22 +694,39 @@ function refreshNow() {
       console.warn('clayjs: source map kept the previous model, the accepted bytes did not model:', err);
     }
   }
+  yield;
+  if (!superseded(session, repairs, adoptions)) return;
+  let paired = null;
   try {
-    const { map, stats } = pairAgainstPage(m);
-    state.model = m;
-    state.map = map;
-    state.stats = stats;
-    state.refreshes++;
-    state.timing.refresh = now() - t;
+    paired = pairAgainstPage(m);
   } catch (err) {
     // The map is now stale rather than wrong: it still describes the pairing as of
     // the last successful refresh. Renders off a stale map verify or fall back like
     // any other, so this costs formatting fidelity and nothing else.
     console.warn('clayjs: source map could not re-pair, continuing on the previous map:', err);
   }
+  state.refreshQueued = false;
+  state.pendingBytes = null;
+  if (refetch) state.refetch = false;
+  // Counted even when the re-pair above failed: either way this page is not the page a
+  // candidate captured before it was built against.
+  state.repairs++;
+  if (paired) {
+    state.model = m;
+    state.map = paired.map;
+    state.stats = paired.stats;
+    state.refreshes++;
+    state.timing.refresh = now() - t;
+  }
   if (refetch) refetchModel();
 }
 
+/** Whether something newer than the refresh this generator started arrived while it yielded. */
+function superseded(session, repairs, adoptions) {
+  return state.session === session && state.installed
+    && state.repairs === repairs && state.adoptions === adoptions;
+}
+
 /**
  * Take the model from the file itself, after a disk frame arrived with bytes this host
  * projected rather than bytes on disk.
@@ -664,6 +832,14 @@ export function stats() {
 
 export const installed = () => state.installed;
 
+/**
+ * How many times the map has been rebuilt since this session installed.
+ *
+ * A render is refused when this changes while it runs, so a save that prepares across
+ * tasks falls back to today's bytes rather than a pairing that no longer describes the page.
+ */
+export const repairGeneration = () => state.repairs;
+
 /** The facade's dispose: take the install back, and invalidate whatever was still loading. */
 export function release() {
   uninstall();

package/src/sync/editing-sender.js

@@ -36,6 +36,18 @@ export class EditingSender {
     for (const type of EVENTS) document.addEventListener(type, this._onEvent);
   }
 
+  /**
+   * Speak again after a quiesce that was refused: the listeners come back and the
+   * target this tab holds goes again, because the clear that came with the quiesce
+   * took the sender's last word off the host.
+   */
+  resume() {
+    if (!this.stopped) return;
+    this.start();
+    this.sent = null;
+    this.schedule();
+  }
+
   stop() {
     this.stopped = true;
     for (const type of EVENTS) document.removeEventListener(type, this._onEvent);

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

@@ -26,12 +26,29 @@ export function syncParticipant(sync) {
   // 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.
+  // The sender is stopped rather than only cleared, so the gate stays shut until the
+  // exit commits or is refused: a reconnect, a roster change or a focus move during
+  // the barrier would otherwise publish a target the session never takes back. The
+  // page's own awareness hears the same barrier and resumes with it, so its caret
+  // goes quiet with the sender and comes back on a refused exit.
   const quiesce = () => {
+    sync._presenceQuiesced = true;
+    sync._editing?.stop();
     presence.setGeneric(null);
     presence.releaseTarget();
+    if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:presence-quiesce"));
     return sync.lane === "live" && sync._morphInFlight ? { ok: false, code: "pending-input" } : { ok: true };
   };
-  const dispose = () => sync.stop();
+  const resume = () => {
+    sync._presenceQuiesced = false;
+    sync._editing?.resume();
+    if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:presence-resume"));
+  };
+  const dispose = () => {
+    sync._presenceQuiesced = false;
+    sync.stop();
+    if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:presence-resume"));
+  };
   return {
     id: "clay:sync",
     order: 50,
@@ -39,10 +56,11 @@ export function syncParticipant(sync) {
       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 };
+      if (context?.initial) return { quiesce, resume, dispose };
       let started = false;
       return {
         quiesce,
+        resume,
         // The commit: the lane a reader was following stops, and the same stream
         // slot opens on the live lane.
         enable() {
@@ -55,7 +73,9 @@ export function syncParticipant(sync) {
         // lane was the reader's: stopping it would take the saved lane the switch gives
         // back with it.
         dispose: () => {
+          sync._presenceQuiesced = false;
           if (started) sync.stop();
+          if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:presence-resume"));
         },
       };
     },