@panphora/clayjs 0.2.0 → 0.4.0

package/src/core/save-core.js

@@ -9,12 +9,11 @@
 
 import { isEditMode } from "./is-edit-mode.js";
 import { consumeUserDriven, markUserDriven } from "../lib/user-gesture.js";
+import { saveToken, saveTransport, DESKTOP_JSON } from "./host-attrs.js";
 import {
-  captureForSave,
-  beforeSave,
   getPageContents,
   onSnapshot,
-  onPrepareForSave
+  addDocumentTransform
 } from "./snapshot.js";
 
 // =============================================================================
@@ -22,7 +21,8 @@ import {
 // =============================================================================
 
 let saveInProgress = false;
-const saveEndpoint = '/_/save';
+const SAVE_PATH = '/_/save';
+const SAVE_TIMEOUT_MS = 12000;
 
 /**
  * Check if a save is currently in progress.
@@ -32,214 +32,202 @@ export function isSaveInProgress() {
   return saveInProgress;
 }
 
-/**
- * Resolve the save endpoint for the current host.
- *
- * htmlclay (the local Go app for .htmlclay files) authenticates each save with
- * a per-file token injected as the `htmlclaytoken` attribute on <html>, and
- * carries it in the URL path so the same token works for fetch and EventSource.
- * When that attribute is present, save to `/_/save/{token}`; otherwise use the
- * bare `/_/save` (platform and Hyperclay Local, which authenticate by cookie).
- *
- * @returns {string} The endpoint URL for the current save.
- */
-function getSaveEndpoint() {
-  const htmlclayToken = document.documentElement.getAttribute('htmlclaytoken');
-  return htmlclayToken ? `${saveEndpoint}/${htmlclayToken}` : saveEndpoint;
-}
-
 // =============================================================================
 // RE-EXPORTS FROM SNAPSHOT (for backwards compat)
 // =============================================================================
 
-export { beforeSave, getPageContents, onSnapshot, onPrepareForSave };
+export { getPageContents, onSnapshot, addDocumentTransform };
 
 // =============================================================================
-// INTERNAL: GET PAGE CONTENTS
+// THE RESULT
 // =============================================================================
+// One shape from every entry point: {ok, msg, msgType, code, etag}. There used to
+// be three shapes — two callback conventions and a hand-built third — which is how
+// a skipped save came to be read as a successful one.
+//
+// `ok` is the OUTCOME: did these bytes reach the server and get accepted. `msgType`
+// is the SEVERITY, and it belongs to the server, which can answer a perfectly good
+// save with 'warning' (htmlclay does, when an outside process touched the file).
+// Reading the severity as the outcome means treating that warning as a failure.
+
+function successResult(data) {
+  return {
+    ok: true,
+    msg: data.msg ?? 'Saved',
+    msgType: data.msgType || 'success',
+    code: data.code ?? null,
+    etag: data.etag ?? null
+  };
+}
 
-/**
- * Get the current page contents as HTML string for saving.
- * Emits snapshot-ready event for live-sync.
- *
- * @returns {string} HTML string of current page
- */
-function getContentsForSave() {
-  // Emit for live-sync when actually saving
-  return captureForSave({ emitForSync: true });
+function errorResult(err) {
+  const timedOut = err.name === 'AbortError';
+  return {
+    ok: false,
+    msg: timedOut ? 'Server not responding' : (err.message || 'Save failed'),
+    // A timeout is not evidence the write failed. The request may well have landed,
+    // so this reports "we do not know" rather than asserting something false.
+    msgType: timedOut ? 'unknown' : 'error',
+    code: timedOut ? 'timeout' : (err.code ?? null),
+    etag: null
+  };
+}
+
+function skippedResult(msg) {
+  return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
 
 // =============================================================================
-// SAVE FUNCTIONS
+// THE WIRE
 // =============================================================================
+// One request builder and one response decoder. Keeping two copies of the request
+// is what let four separate wire bugs hide at once, each of which had to be found
+// twice.
 
 /**
- * Save the current page contents to the server.
+ * Build the save request for this host.
  *
- * Returns a Promise that resolves with {msg, msgType} — the same object
- * passed to the callback. Promise never rejects; errors resolve with
- * msgType: 'error', skipped early-returns resolve with msgType: 'skipped'.
+ * htmlclay (the local Go app for .htmlclay files) authenticates each save with a
+ * per-file token on the root and carries it in the URL path, so the same token
+ * works for fetch and EventSource. The platform and Hyperclay Local authenticate
+ * by cookie and use the bare endpoint.
  *
- * @param {Function} callback - Called with {msg, msgType} on completion
- *   msgType will be 'success', 'error', or 'skipped'
- * @returns {Promise<{msg: string, msgType: string}>}
+ * A token save asks for no cookies at all. The token IS the credential, and a
+ * credentialed cross-origin request needs Access-Control-Allow-Credentials back;
+ * a host that mints per-document tokens must never send that header, because
+ * `Origin: null` is forgeable and must not buy ambient authority. Asking anyway
+ * gets every sandboxed save blocked before it leaves the browser.
  *
- * @example
- * // Callback form (unchanged)
- * savePage(({msg, msgType}) => {
- *   if (msgType === 'error') console.error('Save failed:', msg);
- * });
+ * The endpoint is resolved against the real origin rather than left relative,
+ * because a <base href> anywhere in the authored document would otherwise redirect
+ * the save — and the per-document token in its path — to an origin the document
+ * itself chose.
  *
- * @example
- * // Promise form
- * const {msg, msgType} = await savePage();
- * if (msgType === 'error') console.error('Save failed:', msg);
+ * @param {string} content - HTML to save
+ * @param {?string} snapshotHtml - unstripped snapshot, for the desktop envelope
+ * @param {boolean} userDriven - Whether a human gesture is behind this save
+ * @param {AbortSignal} signal
+ * @returns {{url: string, options: Object}}
  */
-export function savePage(callback = () => {}) {
-  return new Promise((resolve) => {
-    if (saveInProgress) {
-      const skipped = { msg: 'Save already in progress', msgType: 'skipped' };
-      callback(skipped);
-      return resolve(skipped);
-    }
-    if (!isEditMode && !window.clay?.testMode) {
-      const skipped = { msg: 'Not in edit mode', msgType: 'skipped' };
-      callback(skipped);
-      return resolve(skipped);
-    }
-
-    let currentContents;
-    try {
-      currentContents = getContentsForSave();
-    } catch (err) {
-      console.error('savePage: getContentsForSave failed', err);
-      const result = { msg: err.message, msgType: "error" };
-      callback(result);
-      return resolve(result);
-    }
-    saveInProgress = true;
-
-    // Test mode: skip network request, return mock success
-    if (window.clay?.testMode) {
-      setTimeout(() => {
-        saveInProgress = false;
-        const result = { msg: "Test mode: save skipped", msgType: "success" };
-        if (typeof callback === 'function') {
-          callback(result);
-        }
-        resolve(result);
-      }, 0);
-      return;
+function buildSaveRequest(content, snapshotHtml, userDriven, signal) {
+  const token = saveToken();
+  const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
+  const options = {
+    method: 'POST',
+    credentials: token ? 'omit' : 'same-origin',
+    signal,
+    headers: {
+      'Document-URL': window.location.href,
+      // The older spelling of the same header, which htmlclay reads today.
+      'Page-URL': window.location.href,
+      'X-Hyperclay-User-Driven': userDriven ? '1' : '0'
     }
+  };
+
+  // The desktop JSON envelope carries the unstripped snapshot alongside the
+  // document, so a sync engine can replay what the browser actually had. It goes
+  // out only when the served document DECLARES that transport, and it is passed in
+  // from the capture that produced `content` — it used to be left on a window
+  // global that was cleared only on success, so two captures without an intervening
+  // successful save would pair a stale snapshot with fresh content.
+  if (saveTransport() === DESKTOP_JSON && snapshotHtml) {
+    options.headers['Content-Type'] = 'application/json';
+    options.body = JSON.stringify({ content, snapshotHtml, userDriven });
+  } else {
+    options.body = content;
+  }
+
+  return { url: new URL(path, window.location.origin).href, options };
+}
 
-    // Add timeout - abort if server doesn't respond within 12 seconds
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 12000);
-
-    // Check if running on Hyperclay Local - send JSON with both versions for platform sync
-    const isHyperclayLocal = window.location.hostname === 'localhost' ||
-                             window.location.hostname === '127.0.0.1';
-
-    // Read-and-reset the data-guard provenance bit at the ACTUAL send (past the
-    // early returns above), so it's never consumed on a save that never ships.
-    const userDriven = consumeUserDriven();
-
-    const fetchOptions = {
-      method: 'POST',
-      credentials: 'include',
-      signal: controller.signal,
-      headers: { 'Page-URL': window.location.href, 'X-Hyperclay-User-Driven': userDriven ? '1' : '0' }
-    };
-
-    if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
-      // Send JSON with both stripped content and full snapshot for platform live sync
-      fetchOptions.headers['Content-Type'] = 'application/json';
-      fetchOptions.body = JSON.stringify({
-        content: currentContents,
-        snapshotHtml: window.__hyperclaySnapshotHtml,
-        userDriven
-      });
-    } else {
-      // Platform: send plain text as before
-      fetchOptions.body = currentContents;
-    }
-
-    fetch(getSaveEndpoint(), fetchOptions)
-      .then(res => {
-        clearTimeout(timeoutId);
-        return res.json().then(data => {
-          if (!res.ok) {
-            throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
-          }
-          return data;
-        });
-      })
-      .then(data => {
-        // Clear the snapshot only once the save actually landed (a failed save
-        // keeps it so a retry still carries the provenance snapshot).
-        window.__hyperclaySnapshotHtml = null;
-        const result = { msg: data.msg, msgType: data.msgType || 'success' };
-        if (typeof callback === 'function') {
-          callback(result);
-        }
-        resolve(result);
-      })
-      .catch(err => {
-        clearTimeout(timeoutId);
-        console.error('Failed to save page:', err);
-
-        // The save never landed: re-arm the user-driven bit so the next (retry)
-        // save still reports the human gesture instead of reading as background.
-        if (userDriven) markUserDriven();
-
-        const msg = err.name === 'AbortError'
-          ? 'Server not responding'
-          : 'Save failed';
-
-        const result = { msg, msgType: "error" };
-        if (typeof callback === 'function') {
-          callback(result);
+/**
+ * Send one save and decode one response.
+ *
+ * Resolves with the server's JSON body: `msg` and `msgType` everywhere, plus
+ * `code` and `etag` from a host that follows the spec. Rejects with the raw error,
+ * carrying the server's message and `code` when it answered at all.
+ *
+ * The body is read as text and parsed defensively BEFORE the status is consulted.
+ * Calling res.json() first meant a 200 with an empty body reported failure over a
+ * save that had landed, and a 502 HTML error page surfaced as "Unexpected token '<'"
+ * instead of the status.
+ *
+ * @param {string} content - HTML to save
+ * @param {?string} snapshotHtml
+ * @returns {Promise<Object>} The server's response body
+ */
+function sendSave(content, snapshotHtml) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), SAVE_TIMEOUT_MS);
+
+  // Read-and-reset the data-guard provenance bit at the ACTUAL send (past the
+  // early returns in the callers), so it's never consumed on a save that never
+  // ships.
+  const userDriven = consumeUserDriven();
+  const { url, options } = buildSaveRequest(content, snapshotHtml, userDriven, controller.signal);
+
+  return fetch(url, options)
+    .then(res => res.text().then(text => {
+      let data = {};
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch (err) {
+          if (res.ok) throw new Error('Server sent a response that was not JSON');
         }
-        resolve(result);
-      })
-      .finally(() => {
-        clearTimeout(timeoutId);
-        saveInProgress = false;
-      });
-  });
+      }
+      if (!res.ok) {
+        const error = new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
+        error.code = data.code ?? null;
+        error.status = res.status;
+        throw error;
+      }
+      return data;
+    }))
+    .catch(err => {
+      console.error('Failed to save page:', err);
+      // The save never landed: re-arm the user-driven bit so the next (retry)
+      // save still reports the human gesture instead of reading as background.
+      if (userDriven) markUserDriven();
+      throw err;
+    })
+    .finally(() => {
+      clearTimeout(timeoutId);
+    });
 }
 
+// =============================================================================
+// SAVE FUNCTIONS
+// =============================================================================
+
 /**
  * Save specific HTML content to the server.
  *
- * Returns a Promise that resolves with {err, data} — same arguments
- * passed to the callback. Promise never rejects; errors resolve with
- * truthy err. Skipped early-returns resolve with data.msgType: 'skipped'.
+ * Returns a Promise resolving with {msg, msgType, code, etag} — the same object
+ * passed to the callback. Never rejects.
  *
  * @param {string} html - HTML string to save
- * @param {Function} callback - Called with (err, data) on completion
- * @returns {Promise<{err: ?Error, data: ?{msg: string, msgType: string}}>}
+ * @param {Function} callback - Called with the result on completion
+ * @param {Object} [options]
+ * @param {?string} [options.snapshotHtml] - unstripped snapshot from the same capture
+ * @returns {Promise<{msg: string, msgType: string, code: ?string, etag: ?string}>}
  *
  * @example
- * // Callback form (unchanged)
- * saveHtml(myHtml, (err, data) => {
- *   if (err) console.error('Save failed:', err);
- * });
- *
- * @example
- * // Promise form
- * const {err, data} = await saveHtml(myHtml);
- * if (err) console.error('Save failed:', err);
+ * const {msg, msgType} = await saveHtml(myHtml);
+ * if (msgType === 'error') console.error('Save failed:', msg);
  */
-export function saveHtml(html, callback = () => {}) {
+export function saveHtml(html, callback = () => {}, { snapshotHtml = null } = {}) {
   return new Promise((resolve) => {
-    if (!isEditMode || saveInProgress) {
-      const data = {
-        msg: saveInProgress ? 'Save already in progress' : 'Not in edit mode',
-        msgType: 'skipped'
-      };
-      callback(null, data);
-      return resolve({ err: null, data });
+    const done = (result) => {
+      if (typeof callback === 'function') callback(result);
+      resolve(result);
+    };
+
+    if (!isEditMode && !window.clay?.testMode) {
+      return done(skippedResult('Not in edit mode'));
+    }
+    if (saveInProgress) {
+      return done(skippedResult('Save already in progress'));
     }
 
     saveInProgress = true;
@@ -248,85 +236,19 @@ export function saveHtml(html, callback = () => {}) {
     if (window.clay?.testMode) {
       setTimeout(() => {
         saveInProgress = false;
-        const data = { msg: "Test mode: save skipped", msgType: "success" };
-        if (typeof callback === 'function') {
-          callback(null, data);
-        }
-        resolve({ err: null, data });
+        done(successResult({ msg: 'Test mode: save skipped' }));
       }, 0);
       return;
     }
 
-    // Add timeout - abort if server doesn't respond within 12 seconds
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 12000);
-
-    // Check if running on Hyperclay Local - send JSON with both versions for platform sync
-    const isHyperclayLocal = window.location.hostname === 'localhost' ||
-                             window.location.hostname === '127.0.0.1';
-
-    const userDriven = consumeUserDriven();
-
-    const fetchOptions = {
-      method: 'POST',
-      credentials: 'include',
-      signal: controller.signal,
-      headers: { 'Page-URL': window.location.href, 'X-Hyperclay-User-Driven': userDriven ? '1' : '0' }
-    };
-
-    if (isHyperclayLocal && window.__hyperclaySnapshotHtml) {
-      // Send JSON with both stripped content and full snapshot for platform live sync
-      fetchOptions.headers['Content-Type'] = 'application/json';
-      fetchOptions.body = JSON.stringify({
-        content: html,
-        snapshotHtml: window.__hyperclaySnapshotHtml,
-        userDriven
-      });
-    } else {
-      // Platform: send plain text as before
-      fetchOptions.body = html;
-    }
-
-    fetch(getSaveEndpoint(), fetchOptions)
-      .then(res => {
-        clearTimeout(timeoutId);
-        return res.json().then(data => {
-          if (!res.ok) {
-            throw new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
-          }
-          return data;
-        });
-      })
-      .then(data => {
-        // Clear the snapshot only once the save actually landed (a failed save
-        // keeps it so a retry still carries the provenance snapshot).
-        window.__hyperclaySnapshotHtml = null;
-        if (typeof callback === 'function') {
-          callback(null, data);
-        }
-        resolve({ err: null, data });
-      })
-      .catch(err => {
-        clearTimeout(timeoutId);
-        console.error('Failed to save page:', err);
-
-        // The save never landed: re-arm the user-driven bit so the next (retry)
-        // save still reports the human gesture instead of reading as background.
-        if (userDriven) markUserDriven();
-
-        // Normalize timeout errors
-        const error = err.name === 'AbortError'
-          ? new Error('Server not responding')
-          : err;
-
-        if (typeof callback === 'function') {
-          callback(error);
-        }
-        resolve({ err: error, data: null });
-      })
-      .finally(() => {
-        clearTimeout(timeoutId);
+    sendSave(html, snapshotHtml)
+      .then(successResult, errorResult)
+      // Clear the flag BEFORE handing the result back, so a caller that queues a
+      // 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;
+        done(result);
       });
   });
 }
@@ -334,52 +256,39 @@ export function saveHtml(html, callback = () => {}) {
 /**
  * Fetch HTML from a URL and save it to replace the current page.
  *
- * Returns a Promise that resolves with {err, data} — same arguments
- * passed to the callback. Promise never rejects.
- *
- * @param {string} url - URL to fetch HTML from
- * @param {Function} callback - Called with (err, data) on completion
- * @returns {Promise<{err: ?Error, data: ?{msg: string, msgType: string}}>}
+ * Returns a Promise resolving with {msg, msgType, code, etag}. Never rejects.
  *
- * @example
- * // Callback form (unchanged)
- * replacePageWith('/templates/blog.html', (err, data) => {
- *   if (err) console.error('Failed:', err);
- *   else window.location.reload();
- * });
+ * The fetch status is checked before the body is used: without that, pointing this
+ * at a path that 404s saved the server's error page over the user's document.
  *
- * @example
- * // Promise form
- * const {err, data} = await replacePageWith('/templates/blog.html');
- * if (!err) window.location.reload();
+ * @param {string} url - URL to fetch HTML from
+ * @param {Function} callback - Called with the result on completion
+ * @returns {Promise<{msg: string, msgType: string, code: ?string, etag: ?string}>}
  */
 export function replacePageWith(url, callback = () => {}) {
   return new Promise((resolve) => {
-    if (!isEditMode || saveInProgress) {
-      const data = {
-        msg: saveInProgress ? 'Save already in progress' : 'Not in edit mode',
-        msgType: 'skipped'
-      };
-      callback(null, data);
-      return resolve({ err: null, data });
-    }
+    const done = (result) => {
+      if (typeof callback === 'function') callback(result);
+      resolve(result);
+    };
+
+    if (!isEditMode) return done(skippedResult('Not in edit mode'));
+    if (saveInProgress) return done(skippedResult('Save already in progress'));
 
-    fetch(url)
-      .then(res => res.text())
-      .then(html => {
-        saveHtml(html, (err, data) => {
-          if (typeof callback === 'function') {
-            callback(err, data);
-          }
-          resolve({ err: err || null, data: data || null });
-        });
+    // Resolved against the document's real location, not a <base href> the page
+    // may have set.
+    fetch(new URL(url, window.location.href).href)
+      .then(res => {
+        if (!res.ok) {
+          throw new Error(`Template fetch failed: HTTP ${res.status} ${res.statusText}`);
+        }
+        return res.text();
       })
+      .then(html => saveHtml(html))
+      .then(done)
       .catch(err => {
         console.error('Failed to fetch template:', err);
-        if (typeof callback === 'function') {
-          callback(err);
-        }
-        resolve({ err, data: null });
+        done(errorResult(err));
       });
   });
 }