@panphora/clayjs 1.0.0 → 1.2.0

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,15 +8,70 @@
  * peer's copy of them must never be applied.
  */
 
-// Injected by the host at serve time. Spec §9 bounds a save token 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.
 //
-// htmlclayid is host-injected too (htmlclay's durable file identity, stamped on
-// every serve, absent from disk bytes). It rides here so a morph of raw disk
-// content cannot strip this tab's copy, and a peer's copy is never applied.
-export const HOST_TOKEN_ATTRS = ["savetoken", "htmlclaytoken", "htmlclayid"];
+// 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 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. 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. 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"];
+
+// 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,9 +4,14 @@ 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",
+    "core/save-conflict-notice.js",
     "core/unsaved-warning.js", "core/persist.js",
     "core/admin-attrs.js", "core/autosave.js",
     "attrs/save-freeze.js", "attrs/onaftersave.js", "attrs/refetch-on-save.js",
@@ -30,6 +35,45 @@ export const PLUGIN_PATHS = {
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
+// One literal import per module the loader can ask for, so a bundler can see the
+// whole graph. The loader used to build each specifier at runtime
+// (`import(base + "/src/" + path)`), which no bundler can follow, and that alone
+// stood between clayjs and the single-file build. A relative specifier resolves
+// against this file, so on clayjs.com the URLs fetched are exactly the ones the
+// computed form produced. The thunks keep every import lazy: nothing evaluates
+// until the loader asks, in the loader's order, which is load-bearing.
+// tests/unit/loader-modules.test.js proves every path in CORE_WAVES and
+// PLUGIN_PATHS has an entry here and that each entry imports the file it names.
+export const MODULES = {
+  "core/is-edit-mode.js":       () => import("./core/is-edit-mode.js"),
+  "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"),
+  "core/save-conflict-notice.js": () => import("./core/save-conflict-notice.js"),
+  "core/unsaved-warning.js":    () => import("./core/unsaved-warning.js"),
+  "core/persist.js":            () => import("./core/persist.js"),
+  "core/admin-attrs.js":        () => import("./core/admin-attrs.js"),
+  "core/autosave.js":           () => import("./core/autosave.js"),
+  "attrs/save-freeze.js":       () => import("./attrs/save-freeze.js"),
+  "attrs/onaftersave.js":       () => import("./attrs/onaftersave.js"),
+  "attrs/refetch-on-save.js":   () => import("./attrs/refetch-on-save.js"),
+  "lib/cache-bust.js":          () => import("./lib/cache-bust.js"),
+  "vendor/richclay.vendor.js":  () => import("./vendor/richclay.vendor.js"),
+  "plugins/indicator.js":       () => import("./plugins/indicator.js"),
+  "sync/live-sync.js":          () => import("./sync/live-sync.js"),
+  "plugins/sortable.js":        () => import("./plugins/sortable.js"),
+  "plugins/undo.js":            () => import("./plugins/undo.js"),
+  "vendor/hypercms.vendor.js":  () => import("./vendor/hypercms.vendor.js"),
+  "vendor/quickcrop.vendor.js": () => import("./vendor/quickcrop.vendor.js"),
+  "plugins/upload.js":          () => import("./plugins/upload.js"),
+  "plugins/wire.js":            () => import("./plugins/wire.js"),
+  "plugins/demo.js":            () => import("./plugins/demo.js"),
+};
+
 const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "demo"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through

package/src/loader.js

@@ -1,16 +1,21 @@
-import { resolveModules } from "./loader-logic.js";
+import { resolveModules, MODULES } from "./loader-logic.js";
 import onDomReady from "./lib/dom-ready.js";
 
 function domReady() {
   return new Promise((resolve) => onDomReady(resolve));
 }
 
+// `base` has been unused since 1.1.0 (the loader imports through MODULES) and
+// stays anyway: /v1/clay.js and /v1/src/loader.js are cached independently, so
+// for a while after a deploy a browser can pair either file with the other's
+// previous release. A call shape that differs between them leaves the page with
+// no clayjs at all.
 export async function boot(base, params, readyResolve) {
   await domReady();                                    // Mutation observes document.body
                                                        // unconditionally, and a <head> placement
                                                        // would otherwise observe null
 
-  const editMode = await import(base + "/src/core/is-edit-mode.js");
+  const editMode = await MODULES["core/is-edit-mode.js"]();
   const { isEditMode, isOwner } = editMode;
 
   // richclay's vendor build detects edit mode via this legacy global; set it
@@ -19,13 +24,13 @@ export async function boot(base, params, readyResolve) {
   // and a conflicting leftover would make richclay disable itself.
   window.__hyperclayEditMode = isEditMode;
 
-  const regionPolicy = await import(base + "/src/lib/region-policy.js");
+  const regionPolicy = await MODULES["lib/region-policy.js"]();
 
   const plan = resolveModules(params, isEditMode);
   const loaded = {};
 
   for (const path of plan.core) {
-    loaded[path] = await import(base + "/src/" + path); // sequential: order is load-bearing
+    loaded[path] = await MODULES[path](); // sequential: order is load-bearing
   }
 
   assembleCore(loaded, { isEditMode, isOwner }, regionPolicy); // window.clay MUST be assembled
@@ -39,7 +44,7 @@ export async function boot(base, params, readyResolve) {
     // `ready` exports, never their evaluation.)
     let mod;
     try {
-      mod = await import(base + "/src/" + path);
+      mod = await MODULES[path]();
     } catch (err) {
       console.error(`clayjs: plugin "${path}" failed to load, continuing without it:`, err);
       continue;
@@ -81,6 +86,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
   if (save) {
     const saveFn = save.savePage || save.default;
     saveFn.force = save.savePageForce;
+    saveFn.overwrite = save.saveOverwritingConflict;
     clay.save = saveFn;
   }
   if (snapshot) {

package/src/plugins/indicator.js

@@ -1,6 +1,12 @@
 import { isEditMode } from "../core/is-edit-mode.js";
 import onDomReady from "../lib/dom-ready.js";
 
+// No 'conflict' here on purpose. core/save-conflict-notice.js owns that state now,
+// and it ships in every document rather than only the ones that turned this chip on.
+// Both listen to clay:save-conflict, so keeping a label here put a chip in the corner
+// saying the same thing as the bar at the same moment. Dropping it from this side
+// leaves core unaware that this plugin exists, which is the direction that
+// dependency has to point.
 const LABELS = {
   saving: "Saving…",
   saved: "Saved",
@@ -8,6 +14,11 @@ const LABELS = {
   offline: "Offline, not saved",
 };
 
+// States that stay on screen instead of fading, because 'saving' is still in flight.
+const STICKY = new Set(["saving"]);
+
+const ALARMING = new Set(["error", "offline"]);
+
 let el = null;
 let hideTimer = null;
 
@@ -34,11 +45,11 @@ function show(state) {
   const node = ensure();
   node.textContent = LABELS[state];
   node.dataset.state = state;
-  node.style.background = state === "error" || state === "offline"
+  node.style.background = ALARMING.has(state)
     ? "var(--clay-indicator-error-bg,#7a3b28)" : "var(--clay-indicator-bg,#2e2b27)";
   node.style.opacity = "1";
   clearTimeout(hideTimer);
-  if (state !== "saving") hideTimer = setTimeout(() => { node.style.opacity = "0"; }, 2200);
+  if (!STICKY.has(state)) hideTimer = setTimeout(() => { node.style.opacity = "0"; }, 2200);
 }
 
 function init() {

package/src/plugins/sortable.js

@@ -16,7 +16,6 @@
 */
 import { isEditMode } from "../core/is-edit-mode.js";
 import Mutation from "../lib/mutation.js";
-import { getVendorUrl } from "../lib/load-vendor-script.js";
 
 function makeSortable(sortableElem, Sortable) {
   let options = {};
@@ -89,10 +88,11 @@ function makeSortable(sortableElem, Sortable) {
 async function init() {
   if (!isEditMode) return;
 
-  // Load the vendor script
-  const vendorUrl = getVendorUrl(import.meta.url, '../vendor/Sortable.vendor.js');
-  await import(vendorUrl);
-  const Sortable = window.Sortable;
+  // Sortable's UMD header picks its target at run time: window.Sortable when no
+  // module system is present (a module load, and the single-file build), a
+  // default export when a bundler hands it one. Cover both.
+  const mod = await import('../vendor/Sortable.vendor.js');
+  const Sortable = window.Sortable || mod.default;
 
   // Set up sortable on page load
   document.querySelectorAll('[sortable]').forEach(el => makeSortable(el, Sortable));

package/src/standalone.js

@@ -0,0 +1,98 @@
+/* clayjs standalone: the entry of the single-file build. https://clayjs.com/offline
+
+   Twin of entries/clay.js. That bootstrap derives a base URL from its own script
+   tag and imports the loader at runtime; this one is bundled together with the
+   loader and every module it can ask for (see MODULES in loader-logic.js), so
+   `plugins=` decides what runs, never what downloads. The bootstrap logic below
+   (window.clay, `ready`, `__booted`, the retry path) is the same code as clay.js
+   and must stay in step with it; tests/unit/bootstrap-twins.test.js compares the
+   shared pieces. */
+import { boot } from "./loader.js";
+import onDomReady from "./lib/dom-ready.js";
+
+(function () {
+  // Suppress every vendored bundle's window auto-export; the loader assembles
+  // window.clay explicitly.
+  window.__hyperclayNoAutoExport = true;
+
+  // Merge into any window.clay a satellite already created; never replace it.
+  var clay = window.clay = window.clay || {};
+  // A second tag is a no-op: the original boot's `ready` promise survives.
+  // A FAILED boot resets the sentinel so a corrected tag can retry; the retry
+  // resolves the ORIGINAL `ready` promise via the stashed resolver.
+  if (clay.__booted) return;
+
+  function mintReady() {
+    clay.ready = new Promise(function (res, rej) {
+      clay.__readyResolve = res;
+      clay.__readyReject = rej;
+    });
+    // Nobody may be awaiting a failed boot's promise, and an unhandled rejection
+    // in the console is noise on top of the error we already logged.
+    clay.ready.catch(function () {});
+  }
+
+  if (!clay.ready) mintReady();
+
+  // clay.js needs its own URL to find the loader; this file needs it only for the
+  // query string, so pasted inline into the page it boots with the defaults.
+  var script = document.currentScript;
+  var params = script && script.src ? new URL(script.src, location.href).searchParams : new URLSearchParams();
+  clay.__booted = true;
+
+  function domReady() {
+    return new Promise(function (r) { onDomReady(r); });
+  }
+
+  // The module satellites, on the terms of their own entry scripts: each is a
+  // promise on clay.loaded, the ones that touch document.body wait for DOM
+  // ready, and events waits for dom because [onrender] handlers reach for its
+  // element helpers the moment events lands.
+  function satellite(name, promise) {
+    var p = promise.catch(function (err) {
+      console.error("clayjs: " + name + " failed to load:", err);
+      throw err;
+    });
+    // Mark handled: a failed satellite must not emit an unhandled rejection.
+    // Consumers who await clay.loaded[name] still get the error.
+    p.catch(function () {});
+    clay.loaded[name] = p;
+  }
+
+  clay.loaded = clay.loaded || {};
+  // The two generated satellites are classic scripts that assemble themselves
+  // onto window.clay when they run, and they carry no guard of their own, so
+  // they run here, behind the sentinel, and not as hoisted static imports: a
+  // duplicate tag would otherwise mount a second Sap runtime on the page. For
+  // the same reason a tag that already registered one (a leftover
+  // <script src="sap.js"> above this one) wins, and the copy in here stays idle.
+  if (!clay.loaded.data) satellite("data", import("../entries/clay-data.js"));
+  if (!clay.loaded.sap) satellite("sap", import("../entries/sap.js"));
+  satellite("dom", import("./dom/dom-helpers.js"));
+  satellite("utils", import("./utils/index.js"));
+  satellite("internals", import("./internals/index.js"));
+  satellite("all", import("./dom/all.js").then(function (m) {
+    window.All = m.default;   // interop carve-out, as in entries/all.js
+    clay.All = m.default;
+    return m.default;
+  }));
+  satellite("ui", domReady().then(function () { return import("./ui/index.js"); }));
+  satellite("options", domReady().then(function () { return import("./options/options.js"); }));
+  satellite("events", domReady()
+    .then(function () { return clay.loaded.dom && clay.loaded.dom.catch(function () {}); })
+    .then(function () { return import("./events/index.js"); }));
+
+  // The first argument is the loader's unused `base`; see boot() in loader.js.
+  boot(null, params, clay.__readyResolve).catch(function (err) {
+    clay.__booted = false;
+    console.error("clayjs failed to load:", err);
+    // Settle the promise so `await clay.ready` fails loudly instead of hanging,
+    // then mint a fresh one for a corrected retry tag. See entries/clay.js. A
+    // retry re-evaluates this whole file, satellites included; the path is
+    // reachable only when a bundled module throws on evaluation, which is a
+    // clayjs bug, not a page condition.
+    var reject = clay.__readyReject;
+    mintReady();
+    if (reject) reject(err);
+  });
+})();