@panphora/clayjs 1.17.0 → 1.18.0

package/src/core/save-core.js

@@ -7,6 +7,8 @@
  * For full save system with state management, use save.js instead.
  */
 
+import { notifySaveAccepted } from "./save-accepted.js";
+export { onSaveAccepted } from "./save-accepted.js";
 import { isEditMode, isDraftMode } from "./is-edit-mode.js";
 import { draftTransport } from "./draft-mode.js";
 import { consumeUserDriven, consumeExplicitSave, markUserDriven } from "../lib/user-gesture.js";
@@ -15,6 +17,10 @@ import { lastSeenEtag, conditionalSaves, recordEtag } from "./etag.js";
 import { hostMeta } from "./host-meta.js";
 import { saveSize, storedFile, knownSaveLimit, saveLimit, announceSaveSize } from "./save-size.js";
 import { PAGE_FORMAT, PAGE_FORMAT_HEADER, knownPageFormatFloor, withPageFormatFloor } from "./page-format.js";
+
+// Re-exported for the save lane: it reads the floor and writes the marker these bytes
+// carry, without a second import of the format module.
+export { PAGE_FORMAT_META, knownPageFormatFloor } from "./page-format.js";
 import "./runtime-url.js";
 import {
   getPageContents,
@@ -30,11 +36,27 @@ import {
 // =============================================================================
 
 let saveInProgress = false;
+// Who holds the lane while a save prepares. A capture that will send later takes the lane
+// before its first await, so no second save can start work on the page it is reading; the
+// token is what lets that same save enter `runSave` while its own claim still stands.
+let laneHolder = null;
 const SAVE_PATH = '/_/save';
 const SAVE_TIMEOUT_MS = 12000;
 // The browser caps a keepalive body (Chromium refuses one over 64 KB), and it counts
 // BYTES: the hint is only attached to a save whose UTF-8 encoding fits well inside that.
 const KEEPALIVE_MAX_BODY = 60000;
+// Above this, a save body travels as a Blob instead of a string, so the document is
+// encoded once here rather than again inside fetch, and a retry of the same attempt
+// reuses that Blob. Counted in UTF-16 units, which are never more than the UTF-8 bytes
+// they encode to, so a body under the threshold by this measure is under it in bytes.
+const SAVE_BLOB_MIN_BYTES = 1024 * 1024;
+// The media type the string body has always arrived with, written out explicitly
+// because a Blob's own type never reaches the wire as a request header. text/plain is
+// CORS-safelisted, so this is still the same un-preflighted request.
+const SAVE_BODY_TYPE = 'text/plain;charset=UTF-8';
+// The one body a Blob was last built for, kept so the retry of a large save sends the
+// bytes it already encoded instead of encoding the document a second time.
+let lastBodyBlob = null;
 // Set by `withKeepalive`, read once by the next `sendOnce`: the hint belongs to one
 // request, not to the save pipeline.
 let nextSaveKeepalive = false;
@@ -48,7 +70,6 @@ let nextSaveKeepalive = false;
 //
 // Not a DOM event, deliberately. The whole document rides in the argument, and a
 // CustomEvent would put it on a bus any script on the page can listen to.
-const saveAcceptedHooks = [];
 
 // Headers another module asks every save to carry, by name.
 const extraSaveHeaders = new Map();
@@ -93,32 +114,37 @@ export function isSaveInProgress() {
 }
 
 /**
- * Run a callback with the bytes the host just accepted.
+ * Take the save lane for a capture that will prepare before it can send.
  *
- * Called once per accepted save, after the response, with the exact body that was
- * sent. Never called for a refused, failed or skipped save, and never in test mode,
- * where nothing reached a host.
+ * Runs in the caller's own task, before its first await, so a second save asked for while
+ * the first is preparing records intent instead of capturing the page again. The token
+ * comes back opaque: only the holder can enter `runSave` with it, and only the holder
+ * (or `runSave` settling that request) gives the lane back.
  *
- * @param {Function} callback - Receives the accepted HTML string
+ * @returns {?Object} the owner token, or null when a save already holds the lane
  */
-export function onSaveAccepted(callback) {
-  saveAcceptedHooks.push(callback);
+export function reserveSaveLane() {
+  if (saveInProgress) return null;
+  saveInProgress = true;
+  laneHolder = { reserved: true };
+  return laneHolder;
 }
 
-function notifySaveAccepted(html, captureId, artifact = null) {
-  for (const hook of saveAcceptedHooks) {
-    try {
-      // The artifact is the capture's own private model of these bytes, and it is
-      // offered only when it exists: a raw save and a capture without one keep the
-      // shape they had.
-      const accepted = artifact
-        ? { captureId: captureId ?? null, artifact }
-        : { captureId: captureId ?? null };
-      hook(html, accepted);
-    } catch (err) {
-      console.error('clayjs: onSaveAccepted hook failed:', err);
-    }
-  }
+/**
+ * Give the lane back after a preparation that took it. Idempotent, and harmless once the
+ * save it was reserved for has settled the lane itself.
+ *
+ * @param {Object} owner - the token `reserveSaveLane` returned
+ */
+export function releaseSaveLane(owner) {
+  if (!owner || laneHolder !== owner) return;
+  laneHolder = null;
+  saveInProgress = false;
+}
+
+/** Whether the next save rides a keepalive hint, which an unload flush cannot wait on. */
+export function keepaliveHeld() {
+  return nextSaveKeepalive;
 }
 
 // Listeners for "this exact body is about to leave". One call per real fetch, with
@@ -482,6 +508,10 @@ function formatConversionHeader(conversion) {
  * carrying the document alongside an unstripped snapshot; the snapshot's home is
  * the §10 relay, which the live-sync plugin already posts it to.
  *
+ * Above `SAVE_BLOB_MIN_BYTES` the body is a Blob wrapping that same one string, with the
+ * same media type written out explicitly: a different container for identical bytes,
+ * which is what keeps the encoding off the main thread's critical path.
+ *
  * @param {string} content - HTML to save
  * @param {boolean} userDriven - Whether a human gesture is behind this save
  * @param {AbortSignal} signal
@@ -517,11 +547,15 @@ export function buildSaveRequest(content, userDriven, signal, saveId, etag, keep
       // authorization, and refuses a lower one before mutation.
       [PAGE_FORMAT_HEADER]: String(PAGE_FORMAT)
     },
-    body: content
+    body: bodyForSave(content)
   };
 
   for (const [name, value] of extraSaveHeaders) options.headers[name] = value;
 
+  // Set after the process-global headers so the type describing THESE bytes is the one
+  // that goes out, the same rule the conversion header below follows.
+  if (typeof options.body !== 'string') options.headers['Content-Type'] = SAVE_BODY_TYPE;
+
   // The conversion request belongs to ONE logical save, and goes on every attempt
   // of it. Set after the process-global headers so the capture-bound value is the
   // one that describes these bytes.
@@ -529,11 +563,34 @@ export function buildSaveRequest(content, userDriven, signal, saveId, etag, keep
 
   if (etag) options.headers['If-Match'] = etag;
 
-  if (keepalive && new Blob([content]).size < KEEPALIVE_MAX_BODY) options.keepalive = true;
+  // The length test comes first because it is a floor on the byte count: a body too
+  // long by this measure is too big in bytes too, and never has to be encoded to find
+  // out. A keepalive body is always under 64 KB, so it never reaches the Blob path.
+  if (keepalive && content.length < KEEPALIVE_MAX_BODY && new Blob([content]).size < KEEPALIVE_MAX_BODY) options.keepalive = true;
 
   return { url: resolveSaveUrl(path), options };
 }
 
+/**
+ * The body of one save: the string itself, or, above `SAVE_BLOB_MIN_BYTES`, a Blob
+ * wrapping that one string with no further joining.
+ *
+ * The point is where the encoding happens. A string body is encoded to UTF-8 inside
+ * `fetch`, synchronously and on the main thread; at 11 MB that is the visible stall.
+ * A Blob carries the same bytes with the same media type, and building it once here
+ * means the retry of the same attempt sends the very Blob it already built.
+ *
+ * @param {string} content - HTML to save
+ * @returns {string|Blob}
+ */
+function bodyForSave(content) {
+  if (content.length < SAVE_BLOB_MIN_BYTES) return content;
+  if (lastBodyBlob && lastBodyBlob.content === content) return lastBodyBlob.blob;
+  const blob = new Blob([content], { type: SAVE_BODY_TYPE });
+  lastBodyBlob = { content, blob };
+  return blob;
+}
+
 /**
  * The stamp to send as If-Match, or null for a save that goes out unconditional.
  *
@@ -885,7 +942,7 @@ async function sendSave(content, { captureId = null, conversionHeader = null, at
 // `pageFormatFloor` is internal: one save may carry a floor this tab has not
 // noted yet, which is how the format gate's activation writes the marker. It
 // raises these bytes only, never what the tab knows the document at.
-function runSave(html, captureId, callback, conversion, capture = null, pageFormatFloor = 0) {
+function runSave(html, captureId, callback, conversion, capture = null, pageFormatFloor = 0, lane = null) {
   // A capture taken before the floor rose cannot drop the marker by omitting it:
   // the bytes that go out carry the floor this tab last saw. At floor 0 this is
   // the string itself, unchanged.
@@ -897,6 +954,10 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
     // recovered through the host's receipt reaches `accepted` like any other success,
     // so it adopts the artifact of the request that landed.
     const artifact = captureArtifact(capture);
+    // A prepared save already holds the lane: `saveInProgress` is this call's own claim,
+    // and its preparation gives it back once this save's bookkeeping is done.
+    const holdsLane = () => lane !== null && laneHolder === lane;
+    const releaseOwnLane = () => { if (!holdsLane()) saveInProgress = false; };
     const finished = (result, accepted = false) => {
       if (accepted) notifySaveAccepted(html, captureId ?? null, artifact);
       releaseCaptureArtifact(capture);
@@ -913,7 +974,7 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
     if (!isEditMode && !window.clay?.testMode) {
       return finished(skippedResult('Not in edit mode'));
     }
-    if (saveInProgress) {
+    if (saveInProgress && !holdsLane()) {
       return finished(skippedResult('Save already in progress'));
     }
 
@@ -929,7 +990,7 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
     // Test mode: skip network request, return mock success
     if (window.clay?.testMode) {
       setTimeout(() => {
-        saveInProgress = false;
+        releaseOwnLane();
         finished(successResult({ msg: 'Test mode: save skipped' }));
       }, 0);
       return;
@@ -945,7 +1006,7 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
     const size = saveSize(storedFile(html), knownSaveLimit());
     announceSaveSize(size);
     if (size.state === 'over') {
-      saveInProgress = false;
+      releaseOwnLane();
       return finished(tooLargeResult(size));
     }
 
@@ -955,7 +1016,7 @@ function runSave(html, captureId, callback, conversion, capture = null, pageForm
       // follow-up save can start it immediately rather than being told the lane
       // is busy by the save that just finished.
       .then(result => {
-        saveInProgress = false;
+        releaseOwnLane();
         // A host's 413 is the same refusal the guard above makes, so it carries the
         // same measurement. Its own answer about the size wins over nothing: the bytes
         // are this attempt's, and the limit is still only what discovery advertised.
@@ -998,8 +1059,8 @@ export function saveHtml(html, callback = () => {}) {
  * @param {Object} [options.conversion] - {source:'file', base} or {source:'room', base, epoch}
  * @returns {Promise<Object>}
  */
-export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion, capture = null, pageFormatFloor } = {}) {
-  return runSave(html, captureId, callback, conversion, capture, pageFormatFloor);
+export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion, capture = null, pageFormatFloor, lane = null } = {}) {
+  return runSave(html, captureId, callback, conversion, capture, pageFormatFloor, lane);
 }
 
 /**
@@ -1063,3 +1124,17 @@ export function replacePageWith(url, callback = () => {}) {
       });
   });
 }
+
+// The exit's own page checkpoint, published by save.js and read by the live plugin's
+// exit flush. It lives here because save.js is mocked by name in most page suites,
+// while this module is not: the slot lets an exit save a page without either module
+// importing the other's internals.
+let exitSaveFn = null;
+
+export function setExitSave(fn) {
+  exitSaveFn = fn;
+}
+
+export function exitSave() {
+  return exitSaveFn;
+}

package/src/core/save-job.js

@@ -0,0 +1,108 @@
+/**
+ * save-job.js — a save capture's remaining work as a resumable job.
+ *
+ * `beginSaveCapture` takes the one atomic look at the live page (`prepareSaveCapture`,
+ * which stays on the eager side because every save needs it) and hands back a job whose
+ * rest — the three serializations, the format marker and the renderer's verification — is
+ * a generator. Nothing else here decides anything: what the job must not do while it is
+ * half verified, and whether its bytes may go out, are the caller's (`core/save.js`).
+ *
+ * This module is reached only through the dynamic import that a save first takes the
+ * sliced path with, so a page whose documents are small never loads it and the Document
+ * editor's ready path never pays for it.
+ */
+
+import {
+  completeSaveCapture,
+  prepareSaveCapture,
+  readCapturePageState,
+  releaseSaveCapture,
+  runSaveRenderer
+} from './snapshot.js';
+import { serializeCloneSteps, serializeForCompareSteps } from './serialize-steps.js';
+
+/**
+ * Begin one save capture: everything that must see the live page in this call, then a job
+ * whose remaining work is `job.steps()`. The job holds every value that work reads, so a
+ * page edited between two steps cannot change the answer; `job.drop()` releases what it
+ * captured.
+ *
+ * @param {Object} options
+ * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
+ * @param {boolean} options.forRequest - These bytes go to a host, so the renderer may
+ *   attach the verified model they came from, for the accepted save to adopt
+ * @param {?{name: string, content: string}} options.pageFormatMarker - The document format
+ *   these bytes must declare, as the attributes of the marker element. It goes into the
+ *   save clone after the comparison domains are read and before the renderer verifies, so
+ *   the bytes verified are the bytes sent; the comparison baselines stay marker-free,
+ *   exactly as they do on the one-task path
+ * @returns {{ captureId: number, steps: function(): Generator, drop: function(): void }}
+ */
+export function beginSaveCapture(options = {}) {
+  const pin = prepareSaveCapture({ ...options, sliced: true });
+  return Object.freeze({
+    captureId: pin.captureId,
+    steps: () => saveSteps(pin),
+    drop: () => releaseSaveCapture(pin),
+  });
+}
+
+/**
+ * Declare the document format these bytes carry, in the save clone only.
+ *
+ * The same marker `withPageFormatFloor` puts in the final string, applied to the tree the
+ * renderer verifies so a prepared save cannot verify one document and send another. A
+ * clone already at that floor is left exactly as it is, because the string transform
+ * leaves such a document unchanged too.
+ */
+function setFormatMarker(clone, marker) {
+  const head = clone.querySelector('head');
+  if (!head) return;
+  const existing = clone.querySelector(`meta[name="${marker.name}"]`);
+  if (existing) {
+    if (existing.getAttribute('content') !== marker.content) existing.setAttribute('content', marker.content);
+    return;
+  }
+  const meta = clone.ownerDocument.createElement('meta');
+  meta.setAttribute('name', marker.name);
+  meta.setAttribute('content', marker.content);
+  head.appendChild(meta);
+}
+
+/**
+ * The renderer as a generator, resumed with the capture it belongs to active and put back
+ * before every yield: this capture is never the active one while this task is not running
+ * it.
+ */
+function* rendererSteps(clone, today, pin) {
+  if (!pin.renderer) return today;
+  let gen = null;
+  for (;;) {
+    let step;
+    try {
+      step = runSaveRenderer(pin.context, () => {
+        gen ||= pin.rendererSteps ? pin.rendererSteps(clone, today) : false;
+        return gen ? gen.next() : { done: true, value: pin.renderer(clone, today) };
+      });
+    } catch (err) {
+      console.error('clayjs: save renderer failed, sending the full serialization', err);
+      return today;
+    }
+    if (step.done) return step.value;
+    yield;
+  }
+}
+
+/** The resumable half of a save capture: three serializations that each yield too, then the renderer. */
+function* saveSteps(pin) {
+  readCapturePageState(pin);
+  const today = yield* serializeCloneSteps(pin.clone);
+  yield;
+  const forComparison = pin.compareClone ? (yield* serializeForCompareSteps(pin.compareClone)) : null;
+  yield;
+  const forDirty = pin.dirtyClone ? (yield* serializeForCompareSteps(pin.dirtyClone)) : forComparison;
+  yield;
+  if (pin.pageFormatMarker) setFormatMarker(pin.clone, pin.pageFormatMarker);
+  const forSave = yield* rendererSteps(pin.clone, today, pin);
+  return completeSaveCapture(pin, { forSave, forComparison, forDirty });
+}

package/src/core/save-prepare.js

@@ -0,0 +1,53 @@
+/**
+ * save-prepare.js — a save capture's remaining work, run across tasks.
+ *
+ * A large document's verification is seconds of uninterrupted work, so a save that has
+ * to do it prepares across tasks instead: `beginSaveCapture` takes the one atomic
+ * snapshot in its caller's task, and this module resumes the job's steps, handing the
+ * event loop back whenever a slice has spent its budget. Typing during that wait saves
+ * the checkpoint that was captured and leaves later edits dirty.
+ *
+ * Nothing here decides whether a save may go out: the caller owns the lane, the epochs
+ * and the request. This is the driver alone, so it stays off the editor's ready path —
+ * a page whose documents are small never loads it.
+ */
+
+import { defaultYieldTask, runSliced } from "../lib/slice.js";
+
+// The job itself is in the same lazily loaded graph: a save that prepares across tasks
+// takes its capture here, so the generator it resumes is never on the ready path.
+export { beginSaveCapture } from "./save-job.js";
+
+const monotonic = () => (globalThis.performance ? globalThis.performance.now() : Date.now());
+
+/**
+ * Resume a capture's steps, measuring the main-thread time they spend.
+ *
+ * `activeMs` is the sum of the slices' own execution time, never the wait between them:
+ * it is what the autosave scheduler is told about, so a slow host or a busy tab does not
+ * lengthen the cooldown.
+ *
+ * @param {Generator} steps - `job.steps()` from `beginSaveCapture`
+ * @param {Object} [options]
+ * @param {number} [options.budgetMs] - main-thread time one slice may spend before yielding
+ * @param {{aborted: boolean}} [options.signal] - read before every step; a job whose page
+ *   changed underneath it stops here and hands back nothing
+ * @returns {Promise<{result: ?Object, aborted: boolean, activeMs: number}>}
+ */
+export async function runPreparedSteps(steps, { budgetMs = 4, signal = null } = {}) {
+  let activeMs = 0;
+  let mark = monotonic();
+  const yieldTask = async () => {
+    activeMs += monotonic() - mark;
+    await defaultYieldTask();
+    mark = monotonic();
+  };
+  let outcome;
+  try {
+    outcome = await runSliced(steps, { budgetMs, signal, yieldTask });
+  } finally {
+    activeMs += monotonic() - mark;
+  }
+  const aborted = outcome !== null && typeof outcome === "object" && outcome.aborted === true;
+  return { result: aborted ? null : outcome, aborted, activeMs };
+}

package/src/core/save-size-notice.js

@@ -1,6 +1,7 @@
 import { isEditMode } from "./is-edit-mode.js";
 import { downloadStored } from "./conflict-download.js";
-import { bevelSurface, bevelText, bevelButton, pageScheme, setShown } from "../ui/bevel-controls.js";
+import { bevelSurface, bevelText, bevelButton, pageScheme, paintLook, setShown } from "../ui/bevel-controls.js";
+import { TOKENS } from "../ui/bevel.js";
 import { set } from "../lib/hostile-css.js";
 
 // The one quiet word about how large this document is.
@@ -90,6 +91,7 @@ function render(size) {
   // already recommends downloading one.
   setShown(copy, size.state === "over", "inline-flex");
   place();
+  paintLook(root, { background: TOKENS.surface });
 }
 
 function clear() {

package/src/core/save-slices.js

@@ -0,0 +1,15 @@
+/**
+ * save-slices.js — how big a document has to be before its work hands the page back.
+ *
+ * Two walks ask the same question and must answer it the same way: a save preparing its
+ * bytes (core/save.js) and the source map installing or repairing its model
+ * (source/session.js). The number lives here, on its own, because core/save.js
+ * initializes the save system when it is imported: a source module that read the
+ * threshold from it would start the editor's discovery requests behind the source
+ * plugin's back, which is a fetch that plugin never asked for.
+ */
+
+// A document whose last save was at least this big prepares its next one across tasks.
+// Verifying a file that size is seconds of uninterrupted work, and every keystroke behind
+// it waits; below the threshold the one-task capture is cheaper than the scheduling.
+export const SLICED_SAVE_MIN_BYTES = 300 * 1024;