@panphora/clayjs 1.6.1 → 1.8.0

package/src/core/page-data.js

@@ -0,0 +1,321 @@
+import { hostSupports } from "./host-meta.js";
+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);
+  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 };
+}
+
+export function createPageDataApi({
+  supports = hostSupports,
+  token = saveToken,
+  fetchImpl = (...args) => fetch(...args),
+  getLocation = () => window.location,
+  eventTarget = document,
+  loadWriteModules = defaultWriteModules,
+  syncTimeoutMs = SYNC_WAIT_MS,
+  httpTimeoutMs = HTTP_WAIT_MS,
+} = {}) {
+  let liveSync = null;
+  let writeRunning = false;
+  let writeOutcomeUnknown = false;
+
+  function setLiveSync(sync) {
+    liveSync = sync;
+  }
+
+  async function readData(rules) {
+    if (!(await supports(DATA_READ))) {
+      throw refusal("DataReadUnsupported", "This host does not support reading page data.");
+    }
+
+    let response;
+    try {
+      response = await fetchImpl(dataUrl(rules, getLocation()), {
+        method: "GET",
+        credentials: "same-origin",
+        cache: "no-store",
+        redirect: "error",
+      });
+    } catch (cause) {
+      throw Object.assign(refusal("DataReadFailed", cause?.message || "Could not read page data."), { cause });
+    }
+
+    if (!response.ok) throw await responseError(response);
+    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 }));
+  }
+
+  async function writeData(values, { rules, ifMatch } = {}) {
+    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.");
+      }
+      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 });
+    }
+  }
+
+  return { readData, writeData, setLiveSync };
+}
+
+const pageData = createPageDataApi();
+
+export const readData = pageData.readData;
+export const writeData = pageData.writeData;
+export const setPageDataLiveSync = pageData.setLiveSync;

package/src/core/save.js

@@ -26,7 +26,7 @@ import { seedEtag, lastSeenEtag } from "./etag.js";
 import { gateCaptureToken, gateClearIfUnchanged, pageMaybeDirty } from "../lib/dirty-gate.js";
 import { hasUnsavedState } from "../lib/unsaved-state.js";
 import { autosaveActive } from "../lib/autosave-state.js";
-import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
+import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS, HOST_RESPONSE_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 import { initUserGesture, markExplicitSave, clearExplicitSave } from "../lib/user-gesture.js";
 // A deliberate import cycle: unsaved-warning reads this module's saved baseline, and
@@ -51,16 +51,24 @@ addDocumentTransform(clone => {
   for (const name of ROOT_LIBRARY_ATTRS) clone.removeAttribute(name);
 });
 
-// Keep the host's save token out of the saved bytes, both spellings.
+// Keep the host's save token out of the saved bytes, both spellings, and the response
+// metadata with it.
 //
-// It is a credential for this response, never file content: htmlclay strips it from
-// every save body on arrival, so it never reached disk anyway. Sending it made the
+// A save token is a credential for this response, never file content: htmlclay strips it
+// from every save body on arrival, so it never reached disk anyway. Sending it made the
 // source map, which models the bytes a save sent, describe a root tag one attribute
 // longer than the file, and every offset after it was off by that much. The save
 // itself is authorized by the URL, which reads the token from the live page. The
 // document id is NOT stripped: htmlclay keeps it on disk on purpose.
+//
+// `documentetag` is the same kind of thing for a different reason. It names the version
+// of the response this tab loaded, and it is replaced on every serve, so writing it to
+// disk would freeze one response's stamp into the file and give the next reader a
+// provenance claim about bytes nobody built a response from. Root only, like the rest of
+// this transform: the same name on a child is the author's, and stripping those would
+// delete page content.
 addDocumentTransform(clone => {
-  for (const name of [...SAVE_TOKEN_ATTRS, ...LEGACY_SAVE_TOKEN_ATTRS]) clone.removeAttribute(name);
+  for (const name of [...SAVE_TOKEN_ATTRS, ...LEGACY_SAVE_TOKEN_ATTRS, ...HOST_RESPONSE_ATTRS]) clone.removeAttribute(name);
 });
 
 // ============================================
@@ -214,23 +222,26 @@ export function resumeAutosave() {
 }
 
 // ============================================
-// THE PREVIEW HOLD
+// THE ALL-SAVE HOLD
 // ============================================
 //
-// While an AI edit's rewrite is on screen and not yet kept, the DOM holds words the
-// person has not accepted. Every save would write them, the explicit ones included,
-// so for that window no save goes out at all. A save asked for meanwhile is
-// remembered and runs on release; Keep releases without the replay because it saves
-// right after.
+// While an operation owns the page's persisted state, no save goes out at all. A
+// save asked for meanwhile is remembered and runs on release.
 let previewHold = 0;
 let previewMissed = false;
+const PREVIEW_HOLD_REASON = 'Waiting for the AI edit to be kept or reverted';
+const holdReasons = new Map();
 
-export function holdAllSaves() {
+export function holdAllSaves(reason = PREVIEW_HOLD_REASON) {
   previewHold++;
+  holdReasons.set(reason, (holdReasons.get(reason) || 0) + 1);
 }
 
-export function releaseAllSaves({ replay = true } = {}) {
-  if (previewHold === 0) return;
+export function releaseAllSaves({ replay = true, reason = PREVIEW_HOLD_REASON } = {}) {
+  const count = holdReasons.get(reason) || 0;
+  if (count === 0) return;
+  if (count === 1) holdReasons.delete(reason);
+  else holdReasons.set(reason, count - 1);
   previewHold--;
   if (previewHold > 0) return;
   const missed = previewMissed;
@@ -242,11 +253,16 @@ export function savesHeld() {
   return previewHold > 0;
 }
 
+export function saveHoldReason() {
+  if (previewHold === 0) return null;
+  return holdReasons.keys().next().value || PREVIEW_HOLD_REASON;
+}
+
 function heldForPreview(callback, resolve) {
   if (previewHold === 0) return false;
   previewMissed = true;
   clearExplicitSave();
-  const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+  const skipped = skipped_(saveHoldReason());
   callback(skipped);
   resolve(skipped);
   return true;
@@ -854,7 +870,7 @@ export function savePageThrottled(callback = () => {}) {
 
   if (previewHold > 0) {
     previewMissed = true;
-    const skipped = skipped_('Waiting for the AI edit to be kept or reverted');
+    const skipped = skipped_(saveHoldReason());
     callback(skipped);
     return Promise.resolve(skipped);
   }

package/src/lib/content-dom.js

@@ -5,9 +5,9 @@ const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visite
 function copyControlState(source, copy) {
   if (!/^(INPUT|TEXTAREA|SELECT|OPTION)$/.test(source.tagName || '')) return
   const type = (source.getAttribute?.('type') || '').toLowerCase()
-  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio') copy.value = source.value
-  if ('checked' in source && 'checked' in copy) copy.checked = source.checked
-  if ('selected' in source && 'selected' in copy) copy.selected = source.selected
+  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio' && type !== 'file') copy.value = source.value
+  if (source.tagName === 'INPUT' && (type === 'checkbox' || type === 'radio')) copy.checked = source.checked
+  if (source.tagName === 'OPTION') copy.selected = source.selected
   if (source.tagName === 'SELECT') {
     for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
   }

package/src/lib/root-attrs.js

@@ -63,6 +63,19 @@ export const LEGACY_SAVE_TOKEN_ATTRS = ["htmlclaytoken"];
 // what fixed that, and the split holds whatever token spellings are read above.
 export const HOST_IDENTITY_ATTRS = ["documentid", "htmlclayid"];
 
+// Response metadata, and neither of the other two. `documentetag` names the version
+// of the bytes the host built THIS response from, which is the one thing neither the
+// token nor the identity can say: a token grants a capability and an identity names a
+// file, while the stamp names a revision. It rides on the response only, so an
+// incoming morph must never apply a peer's copy and an outgoing sync must never carry
+// this tab's. Read once, at module evaluation, by host-attrs.js — never re-read from
+// the live root, which a morph may since have rewritten.
+//
+// Kept out of SAVE_TOKEN_ATTRS on purpose: host-attrs.js returns the first name it
+// finds in that list straight into the save URL, and a version stamp is not a
+// credential.
+export const HOST_RESPONSE_ATTRS = ["documentetag"];
+
 // What a host may have injected, and therefore what has to be stripped before a save
 // and kept out of an incoming morph. Wider than what is READ, on purpose: the old token
 // spelling is still injected by every htmlclay, so it still has to be stripped, whether
@@ -87,6 +100,7 @@ export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];
 // can no longer save at all.
 export const TAB_LOCAL_ROOT_ATTRS = new Set([
   ...HOST_TOKEN_ATTRS,
+  ...HOST_RESPONSE_ATTRS,
   ...ROOT_LIBRARY_ATTRS,
 ]);
 

package/src/loader-logic.js

@@ -8,6 +8,7 @@ export const CORE_WAVES = {
     // is exactly the case where edit mode is off, so the editOnly wave would never
     // reach it. It draws nothing on any other page.
     "core/stale-host-notice.js",
+    "core/page-data.js",
   ],
   editOnly: [
     "vendor/hyper-morph.vendor.js",
@@ -66,6 +67,7 @@ export const MODULES = {
   "lib/mutation.js":            () => import("./lib/mutation.js"),
   "core/edit-mode.js":          () => import("./core/edit-mode.js"),
   "core/stale-host-notice.js":  () => import("./core/stale-host-notice.js"),
+  "core/page-data.js":          () => import("./core/page-data.js"),
   "core/snapshot.js":           () => import("./core/snapshot.js"),
   "core/save-core.js":          () => import("./core/save-core.js"),
   "core/save.js":               () => import("./core/save.js"),

package/src/loader.js

@@ -50,7 +50,7 @@ export async function boot(base, params, readyResolve) {
       continue;
     }
     loaded[path] = mod;
-    attachPluginMember(path, mod);   // immediately, not after the loop: hypercms's ?cms=true
+    attachPluginMember(path, mod, loaded); // immediately, not after the loop: hypercms's ?cms=true
                                      // auto-open runs as a microtask queued during ITS evaluation
                                      // (before boot resumes) and reads clay.RichClay and clay.undo,
                                      // which earlier plugins must have attached by then
@@ -83,6 +83,10 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   const save = loaded["core/save.js"];
   const cacheBustMod = loaded["lib/cache-bust.js"];
   const hyperMorph = loaded["vendor/hyper-morph.vendor.js"];
+  const pageData = loaded["core/page-data.js"];
+
+  clay.readData = pageData.readData;
+  clay.writeData = pageData.writeData;
 
   if (save) {
     const saveFn = save.savePage || save.default;
@@ -107,7 +111,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   if (hyperMorph) clay.morph = hyperMorph.morph;
 }
 
-function attachPluginMember(path, mod) {
+function attachPluginMember(path, mod, loaded) {
   const clay = window.clay;
 
   if (path === "plugins/undo.js") {
@@ -115,6 +119,7 @@ function attachPluginMember(path, mod) {
   } else if (path === "sync/live-sync.js") {
     clay.morph = mod.morph;
     clay.conflicts = mod.conflicts;
+    loaded["core/page-data.js"].setPageDataLiveSync(mod.liveSync);
   } else if (path === "plugins/cms.js") {
     clay.cms = mod.cms || mod.default;
   } else if (path === "plugins/upload.js") {