@panphora/clayjs 1.15.2 → 1.16.0

package/src/core/page-data-write.js

@@ -0,0 +1,305 @@
+const DATA_WRITE = "data-write";
+const WRITE_HOLD_REASON = "Waiting for the page data write to finish";
+const SYNC_WAIT_MS = 12000;
+const HTTP_WAIT_MS = 30000;
+
+function refusal(code, message, details) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+async function responseBody(response) {
+  if (typeof response.json === "function") return response.json();
+  const text = await response.text();
+  return text ? JSON.parse(text) : null;
+}
+
+async function responseError(response) {
+  let body = {};
+  try {
+    body = (await responseBody(response)) || {};
+  } catch {}
+
+  const message = body.message || body.error || response.statusText || `Request failed (${response.status})`;
+  const error = new Error(message);
+  error.status = response.status;
+  error.error = body.error;
+  error.details = body.details;
+  return error;
+}
+
+function responseEtag(response) {
+  const value = response.headers?.get?.("ETag");
+  return typeof value === "string" && value ? value : null;
+}
+
+function dataUrl(rules, location) {
+  const base = `${location.origin}${location.pathname}`;
+  if (rules !== undefined) return `${base}?data=${encodeURIComponent(JSON.stringify(rules))}`;
+  return `${location.origin}/_/api${location.pathname}`;
+}
+
+function connected(sync) {
+  return !!sync && !sync.isDestroyed && sync.sse?.readyState === 1;
+}
+
+function syncWaiter(eventTarget, timeoutMs) {
+  const seen = [];
+  let expected = null;
+  let resolvePending = null;
+  let timer = null;
+
+  const matchesExact = (detail) =>
+    detail?.source === "disk" && (expected === null || detail.etag === expected);
+
+  const matchesPending = (detail) =>
+    detail?.source === "disk" && (detail.etag == null || expected === null || detail.etag === expected);
+
+  const cleanup = () => {
+    clearTimeout(timer);
+    eventTarget.removeEventListener("clay:sync-applied", onApplied);
+  };
+
+  const onApplied = (event) => {
+    seen.push(event.detail);
+    if (!resolvePending || !matchesPending(event.detail)) return;
+    const resolve = resolvePending;
+    resolvePending = null;
+    cleanup();
+    resolve(true);
+  };
+
+  eventTarget.addEventListener("clay:sync-applied", onApplied);
+
+  return {
+    waitFor(etag) {
+      expected = etag;
+      if (seen.some(matchesExact)) {
+        cleanup();
+        return Promise.resolve(true);
+      }
+      return new Promise((resolve) => {
+        resolvePending = resolve;
+        timer = setTimeout(() => {
+          resolvePending = null;
+          cleanup();
+          resolve(false);
+        }, timeoutMs);
+      });
+    },
+    cancel: cleanup,
+  };
+}
+
+function httpDeadline(timeoutMs) {
+  const controller = new AbortController();
+  let rejectDeadline;
+  const expired = new Promise((_, reject) => {
+    rejectDeadline = reject;
+  });
+  const timer = setTimeout(() => {
+    const error = new Error("The page data write timed out.");
+    error.name = "TimeoutError";
+    controller.abort(error);
+    rejectDeadline(error);
+  }, timeoutMs);
+
+  return {
+    signal: controller.signal,
+    waitFor(promise) {
+      return Promise.race([promise, expired]);
+    },
+    cancel() {
+      clearTimeout(timer);
+    },
+  };
+}
+
+async function defaultWriteModules() {
+  const [save, saveCore, etag, warning, editMode] = await Promise.all([
+    import("./save.js"),
+    import("./save-core.js"),
+    import("./etag.js"),
+    import("./unsaved-warning.js"),
+    import("./is-edit-mode.js"),
+  ]);
+  return { ...save, ...saveCore, ...etag, ...warning, ...editMode };
+}
+
+async function draftRefusal() {
+  const { isDraftMode } = await import("./is-edit-mode.js");
+  if (!isDraftMode) return null;
+  return refusal("DataUnavailableInDraft", "Page data is kept in this browser for this visitor.");
+}
+
+export function createPageDataWrite({
+  supports,
+  token,
+  fetchImpl,
+  getLocation,
+  eventTarget,
+  getLiveSync,
+  loadWriteModules = defaultWriteModules,
+  syncTimeoutMs = SYNC_WAIT_MS,
+  httpTimeoutMs = HTTP_WAIT_MS,
+}) {
+  let writeRunning = false;
+  let writeOutcomeUnknown = false;
+
+  function assertWriteState(modules, { checkHold = true } = {}) {
+    // A save session with admission closed is a page between modes. Its own exit is the
+    // only write that may go out until it commits or resumes, and page data is not it.
+    if (modules.savesAdmitted && !modules.savesAdmitted()) {
+      throw refusal("ModeTransition", "The page is switching modes. Write page data again when it has settled.");
+    }
+    if (writeOutcomeUnknown) {
+      throw refusal("DataWriteOutcomeUnknown", "A previous page data write has an unknown outcome. Reload before writing again.");
+    }
+    if (writeRunning) {
+      throw refusal("DataWriteInProgress", "Another page data write is already running.");
+    }
+    if (modules.isSaveInProgress()) {
+      throw refusal("SaveInProgress", "The page is already being saved.");
+    }
+    if (modules.saveFateIsUnknown()) {
+      throw refusal("SaveOutcomeUnknown", "The page's last save has an unknown outcome.");
+    }
+    if (checkHold && (modules.savesHeld() || modules.isSaveConflicted())) {
+      throw refusal("SavesHeld", "The page cannot write data while another save hold is active.");
+    }
+    if (modules.hasUnsavedChanges()) {
+      throw refusal("UnsavedChanges", "Save or discard the page's unsaved changes before writing data.");
+    }
+    if (!connected(getLiveSync())) {
+      throw refusal("SyncRequired", "Page data writes require the sync plugin to be connected.");
+    }
+  }
+
+  async function waitForBaseline(modules) {
+    if (modules.baselineSettled()) return;
+    await new Promise((resolve) => eventTarget.addEventListener("clay:baseline-settled", resolve, { once: true }));
+  }
+
+  async function writeData(values, { rules, ifMatch } = {}) {
+    const draft = await draftRefusal();
+    if (draft) throw draft;
+
+    if (!(await supports(DATA_WRITE))) {
+      throw refusal("DataWriteUnsupported", "This host does not support writing page data.");
+    }
+
+    const modules = await loadWriteModules();
+    if (!modules.isEditMode) {
+      throw refusal("DataWriteUnavailable", "Page data writes require an editable page.");
+    }
+
+    await waitForBaseline(modules);
+    assertWriteState(modules);
+
+    let match = ifMatch;
+    if (match == null) match = modules.lastSeenEtag() || await modules.seedEtag();
+    if (typeof match !== "string" || match === "") {
+      throw refusal("DataWriteVersionRequired", "Page data writes require a trustworthy document ETag.");
+    }
+
+    assertWriteState(modules);
+    writeRunning = true;
+    modules.holdAllSaves(WRITE_HOLD_REASON);
+
+    let waiter = null;
+    try {
+      if (modules.isSaveInProgress()) {
+        throw refusal("SaveInProgress", "The page is already being saved.");
+      }
+      if (modules.saveFateIsUnknown()) {
+        throw refusal("SaveOutcomeUnknown", "The page's last save has an unknown outcome.");
+      }
+      if (modules.isSaveConflicted()) {
+        throw refusal("SavesHeld", "The page cannot write data while another save hold is active.");
+      }
+      if (modules.hasUnsavedChanges()) {
+        throw refusal("UnsavedChanges", "Save or discard the page's unsaved changes before writing data.");
+      }
+      // Rechecked immediately before the POST: a mode switch can close admission while
+      // this write was waiting for the sync and the stamp.
+      if (modules.savesAdmitted && !modules.savesAdmitted()) {
+        throw refusal("ModeTransition", "The page is switching modes. Write page data again when it has settled.");
+      }
+      if (!connected(getLiveSync())) {
+        throw refusal("SyncRequired", "Page data writes require the sync plugin to be connected.");
+      }
+
+      const headers = {
+        "Content-Type": "application/json",
+        "If-Match": match,
+      };
+      const currentToken = token();
+      if (currentToken) headers["Save-Token"] = currentToken;
+
+      const body = JSON.stringify(values);
+      waiter = syncWaiter(eventTarget, syncTimeoutMs);
+      const deadline = httpDeadline(httpTimeoutMs);
+
+      let response;
+      try {
+        response = await deadline.waitFor(fetchImpl(dataUrl(rules, getLocation()), {
+          method: "POST",
+          credentials: "same-origin",
+          redirect: "error",
+          headers,
+          body,
+          signal: deadline.signal,
+        }));
+      } catch (cause) {
+        deadline.cancel();
+        writeOutcomeUnknown = true;
+        throw Object.assign(
+          refusal("DataWriteOutcomeUnknown", "The page data write has an unknown outcome. Do not retry automatically."),
+          { cause, unknownOutcome: true }
+        );
+      }
+
+      let data;
+      try {
+        if (!response.ok) throw await deadline.waitFor(responseError(response));
+        data = await deadline.waitFor(responseBody(response));
+      } catch (cause) {
+        if (cause?.status) throw cause;
+        writeOutcomeUnknown = true;
+        throw Object.assign(
+          refusal("DataWriteOutcomeUnknown", "The page data was written, but its response could not be read."),
+          { cause, unknownOutcome: true }
+        );
+      } finally {
+        deadline.cancel();
+      }
+
+      const etag = responseEtag(response);
+      if (etag && etag === modules.lastSeenEtag()) {
+        waiter.cancel();
+        waiter = null;
+        return { data, etag };
+      }
+
+      const applied = await waiter.waitFor(etag);
+      waiter = null;
+      if (!applied) {
+        return {
+          data,
+          etag,
+          pageUpdatePending: true,
+          message: "Written, page update pending.",
+        };
+      }
+      return { data, etag };
+    } finally {
+      waiter?.cancel();
+      writeRunning = false;
+      modules.releaseAllSaves({ reason: WRITE_HOLD_REASON });
+    }
+  }
+
+  return { writeData };
+}

package/src/core/page-data.js

@@ -3,9 +3,6 @@ import { saveToken } from "./host-attrs.js";
 
 const DATA_READ = "data-read";
 const DATA_WRITE = "data-write";
-const WRITE_HOLD_REASON = "Waiting for the page data write to finish";
-const SYNC_WAIT_MS = 12000;
-const HTTP_WAIT_MS = 30000;
 
 function refusal(code, message, details) {
   const error = new Error(message);
@@ -45,93 +42,6 @@ function dataUrl(rules, location) {
   return `${location.origin}/_/api${location.pathname}`;
 }
 
-function connected(sync) {
-  return !!sync && !sync.isDestroyed && sync.sse?.readyState === 1;
-}
-
-function syncWaiter(eventTarget, timeoutMs) {
-  const seen = [];
-  let expected = null;
-  let resolvePending = null;
-  let timer = null;
-
-  const matchesExact = (detail) =>
-    detail?.source === "disk" && (expected === null || detail.etag === expected);
-
-  const matchesPending = (detail) =>
-    detail?.source === "disk" && (detail.etag == null || expected === null || detail.etag === expected);
-
-  const cleanup = () => {
-    clearTimeout(timer);
-    eventTarget.removeEventListener("clay:sync-applied", onApplied);
-  };
-
-  const onApplied = (event) => {
-    seen.push(event.detail);
-    if (!resolvePending || !matchesPending(event.detail)) return;
-    const resolve = resolvePending;
-    resolvePending = null;
-    cleanup();
-    resolve(true);
-  };
-
-  eventTarget.addEventListener("clay:sync-applied", onApplied);
-
-  return {
-    waitFor(etag) {
-      expected = etag;
-      if (seen.some(matchesExact)) {
-        cleanup();
-        return Promise.resolve(true);
-      }
-      return new Promise((resolve) => {
-        resolvePending = resolve;
-        timer = setTimeout(() => {
-          resolvePending = null;
-          cleanup();
-          resolve(false);
-        }, timeoutMs);
-      });
-    },
-    cancel: cleanup,
-  };
-}
-
-function httpDeadline(timeoutMs) {
-  const controller = new AbortController();
-  let rejectDeadline;
-  const expired = new Promise((_, reject) => {
-    rejectDeadline = reject;
-  });
-  const timer = setTimeout(() => {
-    const error = new Error("The page data write timed out.");
-    error.name = "TimeoutError";
-    controller.abort(error);
-    rejectDeadline(error);
-  }, timeoutMs);
-
-  return {
-    signal: controller.signal,
-    waitFor(promise) {
-      return Promise.race([promise, expired]);
-    },
-    cancel() {
-      clearTimeout(timer);
-    },
-  };
-}
-
-async function defaultWriteModules() {
-  const [save, saveCore, etag, warning, editMode] = await Promise.all([
-    import("./save.js"),
-    import("./save-core.js"),
-    import("./etag.js"),
-    import("./unsaved-warning.js"),
-    import("./is-edit-mode.js"),
-  ]);
-  return { ...save, ...saveCore, ...etag, ...warning, ...editMode };
-}
-
 async function draftRefusal() {
   const { isDraftMode } = await import("./is-edit-mode.js");
   if (!isDraftMode) return null;
@@ -144,13 +54,12 @@ export function createPageDataApi({
   fetchImpl = (...args) => fetch(...args),
   getLocation = () => window.location,
   eventTarget = document,
-  loadWriteModules = defaultWriteModules,
-  syncTimeoutMs = SYNC_WAIT_MS,
-  httpTimeoutMs = HTTP_WAIT_MS,
+  loadWriteModules,
+  syncTimeoutMs,
+  httpTimeoutMs,
 } = {}) {
   let liveSync = null;
-  let writeRunning = false;
-  let writeOutcomeUnknown = false;
+  let writeEngine = null;
 
   function setLiveSync(sync) {
     liveSync = sync;
@@ -180,36 +89,28 @@ export function createPageDataApi({
     return { data: await responseBody(response), etag: responseEtag(response) };
   }
 
-  function assertWriteState(modules, { checkHold = true } = {}) {
-    if (writeOutcomeUnknown) {
-      throw refusal("DataWriteOutcomeUnknown", "A previous page data write has an unknown outcome. Reload before writing again.");
-    }
-    if (writeRunning) {
-      throw refusal("DataWriteInProgress", "Another page data write is already running.");
-    }
-    if (modules.isSaveInProgress()) {
-      throw refusal("SaveInProgress", "The page is already being saved.");
-    }
-    if (modules.saveFateIsUnknown()) {
-      throw refusal("SaveOutcomeUnknown", "The page's last save has an unknown outcome.");
-    }
-    if (checkHold && (modules.savesHeld() || modules.isSaveConflicted())) {
-      throw refusal("SavesHeld", "The page cannot write data while another save hold is active.");
-    }
-    if (modules.hasUnsavedChanges()) {
-      throw refusal("UnsavedChanges", "Save or discard the page's unsaved changes before writing data.");
-    }
-    if (!connected(liveSync)) {
-      throw refusal("SyncRequired", "Page data writes require the sync plugin to be connected.");
-    }
-  }
-
-  async function waitForBaseline(modules) {
-    if (modules.baselineSettled()) return;
-    await new Promise((resolve) => eventTarget.addEventListener("clay:baseline-settled", resolve, { once: true }));
+  function loadWriteEngine() {
+    if (writeEngine) return writeEngine;
+
+    writeEngine = import("./page-data-write.js").then(({ createPageDataWrite }) => createPageDataWrite({
+      supports,
+      token,
+      fetchImpl,
+      getLocation,
+      eventTarget,
+      getLiveSync: () => liveSync,
+      loadWriteModules,
+      syncTimeoutMs,
+      httpTimeoutMs,
+    })).catch((error) => {
+      writeEngine = null;
+      throw error;
+    });
+
+    return writeEngine;
   }
 
-  async function writeData(values, { rules, ifMatch } = {}) {
+  async function writeData(values, options) {
     const draft = await draftRefusal();
     if (draft) throw draft;
 
@@ -217,110 +118,8 @@ export function createPageDataApi({
       throw refusal("DataWriteUnsupported", "This host does not support writing page data.");
     }
 
-    const modules = await loadWriteModules();
-    if (!modules.isEditMode) {
-      throw refusal("DataWriteUnavailable", "Page data writes require an editable page.");
-    }
-
-    await waitForBaseline(modules);
-    assertWriteState(modules);
-
-    let match = ifMatch;
-    if (match == null) match = modules.lastSeenEtag() || await modules.seedEtag();
-    if (typeof match !== "string" || match === "") {
-      throw refusal("DataWriteVersionRequired", "Page data writes require a trustworthy document ETag.");
-    }
-
-    assertWriteState(modules);
-    writeRunning = true;
-    modules.holdAllSaves(WRITE_HOLD_REASON);
-
-    let waiter = null;
-    try {
-      if (modules.isSaveInProgress()) {
-        throw refusal("SaveInProgress", "The page is already being saved.");
-      }
-      if (modules.saveFateIsUnknown()) {
-        throw refusal("SaveOutcomeUnknown", "The page's last save has an unknown outcome.");
-      }
-      if (modules.isSaveConflicted()) {
-        throw refusal("SavesHeld", "The page cannot write data while another save hold is active.");
-      }
-      if (modules.hasUnsavedChanges()) {
-        throw refusal("UnsavedChanges", "Save or discard the page's unsaved changes before writing data.");
-      }
-      if (!connected(liveSync)) {
-        throw refusal("SyncRequired", "Page data writes require the sync plugin to be connected.");
-      }
-
-      const headers = {
-        "Content-Type": "application/json",
-        "If-Match": match,
-      };
-      const currentToken = token();
-      if (currentToken) headers["Save-Token"] = currentToken;
-
-      const body = JSON.stringify(values);
-      waiter = syncWaiter(eventTarget, syncTimeoutMs);
-      const deadline = httpDeadline(httpTimeoutMs);
-
-      let response;
-      try {
-        response = await deadline.waitFor(fetchImpl(dataUrl(rules, getLocation()), {
-          method: "POST",
-          credentials: "same-origin",
-          redirect: "error",
-          headers,
-          body,
-          signal: deadline.signal,
-        }));
-      } catch (cause) {
-        deadline.cancel();
-        writeOutcomeUnknown = true;
-        throw Object.assign(
-          refusal("DataWriteOutcomeUnknown", "The page data write has an unknown outcome. Do not retry automatically."),
-          { cause, unknownOutcome: true }
-        );
-      }
-
-      let data;
-      try {
-        if (!response.ok) throw await deadline.waitFor(responseError(response));
-        data = await deadline.waitFor(responseBody(response));
-      } catch (cause) {
-        if (cause?.status) throw cause;
-        writeOutcomeUnknown = true;
-        throw Object.assign(
-          refusal("DataWriteOutcomeUnknown", "The page data was written, but its response could not be read."),
-          { cause, unknownOutcome: true }
-        );
-      } finally {
-        deadline.cancel();
-      }
-
-      const etag = responseEtag(response);
-      if (etag && etag === modules.lastSeenEtag()) {
-        waiter.cancel();
-        waiter = null;
-        return { data, etag };
-      }
-
-      const applied = await waiter.waitFor(etag);
-      waiter = null;
-      if (!applied) {
-        return {
-          data,
-          etag,
-          pageUpdatePending: true,
-          message: "Written, page update pending.",
-        };
-      }
-      return { data, etag };
-    } finally {
-      waiter?.cancel();
-      writeRunning = false;
-      modules.releaseAllSaves({ reason: WRITE_HOLD_REASON });
-    }
+    const engine = await loadWriteEngine();
+    return engine.writeData(values, options);
   }
 
   return { readData, writeData, setLiveSync };

package/src/core/page-format-wire.js

@@ -0,0 +1,4 @@
+// The page format this runtime writes, and the header every page write declares it
+// in. No imports, so the server bundle and any reader can carry it.
+export const PAGE_FORMAT = 1;
+export const PAGE_FORMAT_HEADER = "X-Clay-Page-Format";

package/src/core/page-format.js

@@ -0,0 +1,58 @@
+// The document format floor as the save wire carries it: the canonical
+//   <meta name="clay-page-format" content="1">
+// marker (absence is floor 0, a floor only rises) and the `X-Clay-Page-Format`
+// capability header every page write declares. Core code because every save sends
+// the header; what content needs which floor lives in `page/format-level.js`.
+
+import { PAGE_FORMAT } from "./page-format-wire.js";
+export { PAGE_FORMAT, PAGE_FORMAT_HEADER } from "./page-format-wire.js";
+export const PAGE_FORMAT_META = "clay-page-format";
+export const PAGE_FORMAT_EXTENSION = "page-format-v1";
+export const PAGE_FORMAT_UPGRADE = "page-format-upgrade-required";
+
+// Every helper here is a plain function with no top-level work, so a client that
+// imports one of them carries only that one.
+const level = (value) => (Number.isSafeInteger(value) && value > 0 ? value : 0);
+
+const metaTag = (html) => /<meta\b[^>]*\bname\s*=\s*["']?clay-page-format["']?[^>]*>/i.exec(html);
+
+// A capability as a request declares it: a missing or unreadable header is no
+// capability at all, so it can never authorize a write.
+export function formatCapability(value) {
+  if (typeof value === "number") return level(value);
+  if (typeof value !== "string" || !/^\s*\d+\s*$/.test(value)) return 0;
+  return level(Number(value));
+}
+
+// The floor a document carries. Absent or unreadable metadata is floor 0.
+export function pageFormatFloor(html) {
+  if (typeof html !== "string") return 0;
+  const tag = metaTag(html);
+  if (!tag) return 0;
+  const content = /\bcontent\s*=\s*["']?(\d+)/i.exec(tag[0]);
+  return content ? level(Number(content[1])) : 0;
+}
+
+// The same document with its floor marker set to `floor`, or with every marker
+// gone at 0. Canonical by construction, so it is idempotent: a document already
+// at that floor comes back unchanged.
+export function withPageFormatFloor(html, floor) {
+  const want = level(floor);
+  if (typeof html !== "string" || !want) return html;
+  const tag = metaTag(html);
+  if (tag && pageFormatFloor(tag[0]) === want) return html;
+  const marker = `<meta name="${PAGE_FORMAT_META}" content="${want}">`;
+  if (tag) return html.slice(0, tag.index) + marker + html.slice(tag.index + tag[0].length);
+  const at = /<\/head\s*>/i.exec(html) || /<body\b/i.exec(html);
+  return at ? html.slice(0, at.index) + marker + html.slice(at.index) : marker + html;
+}
+
+// The floor this tab last saw the document at. A save goes out with its capture
+// repaired to this floor, so a capture taken before activation cannot drop the
+// marker by omitting it.
+let known = 0;
+export const knownPageFormatFloor = () => known;
+export function notePageFormatFloor(value) {
+  known = Math.max(known, level(value));
+  return known;
+}