@panphora/clayjs 1.1.0 → 1.2.0

package/src/core/save.js

@@ -17,7 +17,8 @@ import {
   getPageContents,
   replacePageWith as replacePageWithCore,
   addDocumentTransform,
-  isSaveInProgress
+  isSaveInProgress,
+  saveFateIsUnknown
 } from "./save-core.js";
 import { captureForComparison, captureForComparisonAndDirty, captureForSaveAndComparison } from "./snapshot.js";
 import { seedEtag } from "./etag.js";
@@ -54,8 +55,9 @@ let savingTimeout = null;
  * @param {string} state - One of: 'saving', 'saved', 'offline', 'error', 'conflict'
  * @param {string} msg - Optional message (e.g., error details)
  * @param {string} msgType - Optional severity from the server (e.g., 'warning')
+ * @param {Object} [extra] - Extra detail fields for the event (e.g. `changedBy`)
  */
-function setSaveState(state, msg = '', msgType = '') {
+function setSaveState(state, msg = '', msgType = '', extra = null) {
   if (savingTimeout) {
     clearTimeout(savingTimeout);
     savingTimeout = null;
@@ -64,7 +66,7 @@ function setSaveState(state, msg = '', msgType = '') {
   document.documentElement.setAttribute('savestatus', state);
 
   const event = new CustomEvent(`clay:save-${state}`, {
-    detail: { msg, msgType, timestamp: Date.now() }
+    detail: { msg, msgType, timestamp: Date.now(), ...(extra || {}) }
   });
   document.dispatchEvent(event);
 }
@@ -261,7 +263,10 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
     releaseConflictHold();
   } else if (result.msgType === 'conflict') {
     holdForConflict();
-    setSaveState('conflict', result.msg, result.msgType);
+    setSaveState('conflict', result.msg, result.msgType, {
+      changedBy: result.changedBy ?? null,
+      afterTimeout: result.afterTimeout === true,
+    });
   } else if (result.msgType !== 'skipped') {
     if (!navigator.onLine) {
       setSaveState('offline', result.msg);
@@ -274,8 +279,18 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken) {
 // Run the save that arrived while this one was in flight. savePage does its own
 // dirty check, so if nothing actually changed it resolves 'skipped' and stops:
 // this cannot spin.
+//
+// Not while the last save's fate is still unknown, which happens only when the
+// save timed out AND the host could not be asked what became of it. Sending then
+// is sending into a question: the host is unreachable, so the save is most likely
+// to time out too, and if it does reach a host that took the first write it is
+// refused, which puts a conflict bar on screen seconds after a person typed,
+// unprompted, over what is really a network problem. The queued state is KEPT, not
+// dropped, so the newer bytes still go out on the next save; the page is still
+// dirty, so an edit or a close warning will produce one.
 function drainPendingSave() {
   if (!pendingSave) return;
+  if (saveFateIsUnknown()) return;
   pendingSave = false;
   savePage();
 }

package/src/core/snapshot.js

@@ -477,7 +477,11 @@ export function serializeForSync(clone) {
   // truncate the broadcast.
   const shell = bareRoot.outerHTML;
   const endTag = `</${bareRoot.localName}>`;
-  return shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
+  // The doctype, so this artifact is a complete document like every other one this
+  // module produces. Spec section 2 asks for that, and it costs nothing on the wire:
+  // a receiver parses the string and morphs documentElement against documentElement,
+  // so the prologue is consumed by the parser and never reaches the morph.
+  return "<!DOCTYPE html>" + shell.slice(0, shell.length - endTag.length) + clone.innerHTML + endTag;
 }
 
 /**

package/src/core/stale-host-notice.js

@@ -0,0 +1,95 @@
+import { servedStaleToken } from "./host-attrs.js";
+import { isEditMode } from "./is-edit-mode.js";
+import onDomReady from "../lib/dom-ready.js";
+import { set, make } from "../lib/hostile-css.js";
+
+// The page's only visible word on a host too old to save to.
+//
+// This library reads one save-token name. A host older than that rename sends the
+// other one, so there is no token here, and it also sets the owner cookie, so without
+// help the page would open fully editable and 404 every save against a route that no
+// longer matches. is-edit-mode.js takes editing away for that reason. This says why.
+//
+// It loads in the ALWAYS wave, not the edit-only one, which is the whole point: the
+// case it exists for is precisely the case where edit mode is off, so a module gated on
+// edit mode could never run in it. host-attrs.js also logs a line, and that line is for
+// a developer. Somebody editing a document in a desktop app has no console open, and
+// "why can I not edit this any more" is the question they are actually holding.
+//
+// One line, no choice to make: nothing on this page can fix it, so offering a button
+// would be a lie. Dismissable, because after you have read it, it is only in the way.
+
+const BG = "var(--clay-notice-bg,#222)";
+const INK = "var(--clay-notice-ink,#fff)";
+const EDGE = "var(--clay-notice-edge,rgba(255,255,255,.28))";
+const FONT = "14px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif";
+
+const MESSAGE =
+  "This page can't be edited: the app serving it is out of date. " +
+  "Update HTML Clay to 1.9.0 or newer.";
+
+let root = null;
+
+// A phone keyboard shrinks the visual viewport but leaves fixed elements pinned to the
+// layout viewport, so a bottom-anchored bar parks itself behind the keyboard. Same fix
+// as the conflict notice.
+function place() {
+  if (!root) return;
+  const vv = window.visualViewport;
+  const lift = vv ? Math.max(0, window.innerHeight - vv.height - vv.offsetTop) : 0;
+  set(root, "bottom", `calc(${16 + lift}px + env(safe-area-inset-bottom,0px))`);
+}
+
+function dismiss() {
+  if (!root) return;
+  set(root, "display", "none");
+  window.visualViewport?.removeEventListener("resize", place);
+  window.visualViewport?.removeEventListener("scroll", place);
+}
+
+function build() {
+  root = make("div", [
+    "position:fixed", "left:50%", "transform:translateX(-50%)",
+    "z-index:2147483001", "display:flex", "align-items:center", "gap:10px",
+    "max-width:calc(100vw - 24px)", "flex-wrap:wrap", "justify-content:center",
+    "padding:9px 12px", "border-radius:10px",
+    `background:${BG}`, `color:${INK}`, `border:1px solid ${EDGE}`,
+    "box-shadow:0 6px 24px rgba(0,0,0,.32),0 1px 2px rgba(0,0,0,.24)",
+    `font:${FONT}`, "text-align:left",
+  ]);
+  // Three markers, and each is load-bearing on a page that CAN save: this element is
+  // injected, so it is in no document on disk and must never reach one, never wake the
+  // watcher, and never ride out in a snapshot to somebody else's browser.
+  root.setAttribute("clay", "no-save no-watch no-snapshot");
+  root.setAttribute("data-clay-stale-host", "");
+  root.setAttribute("role", "alert");
+
+  root.append(make("span", ["margin-right:2px"], MESSAGE));
+
+  const close = make("button", [
+    "all:initial", "box-sizing:border-box", "cursor:pointer", `font:${FONT}`,
+    "color:" + INK, "opacity:.72", "padding:2px 6px", "border-radius:6px", "flex:none",
+  ], "Dismiss");
+  close.type = "button";
+  close.setAttribute("aria-label", "Dismiss this message");
+  close.addEventListener("click", dismiss);
+  root.append(close);
+
+  document.body.appendChild(root);
+  place();
+  window.visualViewport?.addEventListener("resize", place);
+  window.visualViewport?.addEventListener("scroll", place);
+}
+
+function init() {
+  if (!servedStaleToken()) return;
+  // ?editmode=true outranks the stale-host check by design: that is a person at the
+  // keyboard asking for editing on this load, and is-edit-mode.js gives it to them.
+  // This notice never consulted that, so it appeared on a page that IS editable and
+  // told its reader the opposite. The message is only true while editing is actually
+  // off, so it is shown only then.
+  if (isEditMode) return;
+  build();
+}
+
+onDomReady(init);

package/src/lib/hostile-css.js

@@ -0,0 +1,49 @@
+// Styling that survives somebody else's stylesheet.
+//
+// Every declaration goes on as !important, and that is the whole reason anything this
+// library draws on a stranger's page looks the way it was written. A plain inline style
+// loses to an author rule carrying !important, and `button { ... !important }` is a
+// thing real pages do: the first browser run of the conflict notice had both of its
+// controls repainted in the host page's colours and font. Only an inline !important
+// outranks an author !important.
+
+/**
+ * Apply `prop:value` rules to an element, each one !important.
+ * @param {Element} el
+ * @param {string[]} rules
+ */
+export function style(el, rules) {
+  for (const rule of rules) {
+    const at = rule.indexOf(":");
+    el.style.setProperty(rule.slice(0, at).trim(), rule.slice(at + 1).trim(), "important");
+  }
+}
+
+/**
+ * Set one property, !important.
+ *
+ * Same reason as above, from the other direction: a later assignment has to be able to
+ * beat the !important already sitting on the element, and a plain `el.style.foo = x`
+ * silently cannot.
+ *
+ * @param {Element} el
+ * @param {string} prop
+ * @param {string} value
+ */
+export function set(el, prop, value) {
+  el.style.setProperty(prop, value, "important");
+}
+
+/**
+ * Build an element with those rules already on it.
+ * @param {string} tag
+ * @param {string[]} rules
+ * @param {string} [text]
+ * @returns {HTMLElement}
+ */
+export function make(tag, rules, text) {
+  const el = document.createElement(tag);
+  style(el, rules);
+  if (text) el.textContent = text;
+  return el;
+}

package/src/lib/root-attrs.js

@@ -8,31 +8,70 @@
  * peer's copy of them must never be applied.
  */
 
-// The two spellings of the save token. Spec §9 bounds one to per-file and per-tab
-// and makes the host strip it before writing, so it never reaches disk. But §9
-// bounds only the save path, and §10 fans a snapshot out to other editors'
+// The save token, in the order a reader tries the two spellings. Spec §9 bounds it to
+// per-file and per-tab and makes the host strip it before writing, so it never reaches
+// disk. But §9 bounds only the save path, and §10 fans a snapshot out to other editors'
 // browsers, which is the hole this module closes.
 //
 // Save tokens ONLY. host-attrs.js returns the first name it finds here and puts it
 // straight into the save URL, so anything added to this list becomes a credential
-// in a path. Durable identities go in the list below, never in this one.
-export const SAVE_TOKEN_ATTRS = ["savetoken", "htmlclaytoken"];
+// in a path. Durable identities go in HOST_IDENTITY_ATTRS, never in this one.
+//
+// One name, deliberately. §9 names exactly one save-token attribute.
+//
+// This is a knowing break, not an oversight. htmlclay is the only host that mints a save
+// token at all (hyperclay and Hyperclay Local authorize by cookie and inject nothing),
+// it serves both spellings only from 1.9.0, and a document loads this library from a
+// rolling URL. So a document served by an htmlclay at or below 1.8.0 keeps edit mode,
+// because that host also sets the isAdminOfCurrentResource cookie, and every save 404s,
+// because that host registers only `POST /_/save/{token}`.
+//
+// Taken on purpose, and taken now because the cost only grows: htmlclay 1.8.0 is days
+// old, the product is pre-launch, and the alternative is carrying a second credential
+// name in the save path permanently, since "wait until the old hosts are gone" is a
+// condition nobody ever measures. host-attrs.js says so plainly in the console when it
+// finds the old name, so the failure names its own cause and its own fix.
+//
+// ⚠️ RELEASE ORDER: htmlclay 1.9.0, which injects both names, must publish BEFORE this.
+export const SAVE_TOKEN_ATTRS = ["savetoken"];
+
+// The pre-rename spelling. Never read as a credential, which is the point of it being
+// here rather than above, and never removed from HOST_TOKEN_ATTRS below, which is a
+// different job: a name a host may inject has to go on being stripped before a save and
+// kept out of a peer's morph, or a live token gets written into a document or handed to
+// another tab. htmlclay injects it forever, because documents frozen against an older
+// client read it, so this name never leaves this file.
+export const LEGACY_SAVE_TOKEN_ATTRS = ["htmlclaytoken"];
 
-// Host-injected, but NOT credentials. htmlclayid is htmlclay's durable file
-// identity, stamped on every serve and absent from disk bytes, so it rides in the
-// morph protection below for the same reason a token does: a morph of raw disk
-// content would otherwise strip this tab's copy, and a peer's copy must never be
-// applied.
+// Host-injected, but NOT credentials. This is htmlclay's durable file identity,
+// stamped on every serve and absent from disk bytes, so it rides in the morph
+// protection below for the same reason a token does: a morph of raw disk content
+// would otherwise strip this tab's copy, and a peer's copy must never be applied.
+//
+// Two spellings, permanently, mirroring the token list above. htmlclay serves
+// `documentid` and reads either, but a document saved before that rename holds
+// `htmlclayid` on disk forever, and this list is what a morph consults. Knowing
+// only the current name would leave every pre-rename file's identity unprotected,
+// which is the failure this list exists to prevent.
 //
 // It was previously in the token list, where saveToken() returned it whenever a
 // host minted no token of its own. That is reachable: htmlclay stamps the id on
 // every serve but injects a token only for top-level document loads, and its save
 // route strips only the token, so the id reaches disk. Any such file hosted
 // somewhere tokenless made this library POST to /_/save/{id} with no cookie and
-// hand edit mode to every visitor.
-export const HOST_IDENTITY_ATTRS = ["htmlclayid"];
+// hand edit mode to every visitor. Splitting this list off from the token list is
+// what fixed that, and the split holds whatever token spellings are read above.
+export const HOST_IDENTITY_ATTRS = ["documentid", "htmlclayid"];
 
-export const HOST_TOKEN_ATTRS = [...SAVE_TOKEN_ATTRS, ...HOST_IDENTITY_ATTRS];
+// 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
+// or not this library will accept it as a credential.
+export const HOST_TOKEN_ATTRS = [
+  ...SAVE_TOKEN_ATTRS,
+  ...LEGACY_SAVE_TOKEN_ATTRS,
+  ...HOST_IDENTITY_ATTRS,
+];
 
 // This library's own root state, and this tab's UI truth.
 export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];

package/src/loader-logic.js

@@ -4,6 +4,10 @@ export const CORE_WAVES = {
     "core/edit-mode.js",   // both modes — matches today: 'edit-mode' is NOT in EDIT_MODE_ONLY
                            // (hyperclay.js:251-273 lists 'edit-mode-helpers', not 'edit-mode');
                            // toggleEditMode must exist in view mode, it's the way IN
+    // always, deliberately: it speaks only when the host is too old to save to, which
+    // 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",
   ],
   editOnly: [
     "core/snapshot.js", "core/save-core.js", "core/save.js",
@@ -45,6 +49,7 @@ export const MODULES = {
   "lib/region-policy.js":       () => import("./lib/region-policy.js"),
   "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/snapshot.js":           () => import("./core/snapshot.js"),
   "core/save-core.js":          () => import("./core/save-core.js"),
   "core/save.js":               () => import("./core/save.js"),