@panphora/clayjs 1.15.1 → 1.16.0

package/src/core/edit-mode.js

@@ -1,28 +1,161 @@
 // Edit mode system - combines the editmode toggle with page type setting.
-// Loads in BOTH view and edit mode: toggleEditMode must exist in view mode
+// Loads in BOTH view and edit mode: setMode must exist in view mode
 // (it's the way IN), and setPageTypeOnPageLoad marks <html> in either mode.
-import { isDraftMode, isEditMode, isOwner } from "./is-edit-mode.js";
+import { canEdit, isDraftMode, isEditMode, isOwner, mode, modeState, registerModeParticipant } from "./is-edit-mode.js";
+import { writeReceipt } from "./mode-receipt.js";
 import onDomReady from "../lib/dom-ready.js";
-import { addDocumentTransform } from "./snapshot.js";
 
-export function toggleEditMode() {
+let leaving = false;
+
+// The public registration. The built-ins own the `clay:` prefix (`clay:resources` and
+// every module participant), so an application may not take an id from that space.
+const register = (participant) => {
+  if (typeof participant?.id === "string" && participant.id.startsWith("clay:")) {
+    throw new TypeError(`clay.modeLifecycle: the id "${participant.id}" is reserved`);
+  }
+  return registerModeParticipant(participant);
+};
+
+export const modeLifecycle = {
+  register,
+  canWrite: () => modeState().phase === "idle" && isEditMode,
+  get state() {
+    return Object.freeze(modeState());
+  },
+};
+
+// The lazy dispatcher. The controller is a dynamic target, fetched by an explicit
+// initial edit or the first live switch — never because a live declaration, a menu or
+// a participant exists — and a rejected fetch is retried on the next ask.
+let controller = null;
+
+const fetchController = () => (controller ||= import("./mode-lifecycle.js").catch(() => (controller = null)));
+
+// A live switch is a contract the document signs, not a hint. The loader records both
+// resolved plans here only when `<html clay-mode-switch="live">` asked for one; the
+// decision behind it and the controller that runs the transaction are a dynamic target,
+// fetched by the first switch and never by the declaration itself.
+let liveSwitch = null;
+
+export const noteLiveSwitch = (boot) => {
+  liveSwitch = boot;
+};
+
+export async function activateInitialMode() {
+  if (!isEditMode) return;
+  try {
+    await (await fetchController()).activateInitial();
+  } catch (err) {
+    console.error("clayjs: the mode lifecycle failed to start:", err);
+  }
+}
+
+// One mode request at a time, whoever ends up handling it (the workspace shell, the live
+// controller or a reload): asking for the same mode joins it, and asking for the other one
+// is busy until it settles.
+let pending = null;
+
+export async function setMode(next) {
+  if (next !== "edit" && next !== "view") throw new TypeError(`clay.setMode: unknown mode "${next}"`);
+  if (pending) return pending.target === next ? pending.promise : { ok: false, mode, code: "busy" };
+  if (next === mode && !controller) return { ok: true, mode, changed: false };
+  if (isDraftMode) return { ok: false, mode, code: "not-allowed" };
+  const promise = request(next);
+  pending = { target: next, promise };
+  try {
+    return await promise;
+  } finally {
+    if (pending?.promise === promise) pending = null;
+  }
+}
+
+async function request(next) {
+  // In a workspace frame the shell owns the frame and decides permission, so a mode change
+  // is its reload, not ours: hand it over before anything local starts. Only a shell that
+  // does not take part ("host-unsupported") leaves the switch to this document.
+  const host = typeof window !== "undefined" ? window.clay?._requestHostMode : undefined;
+  if (typeof host === "function" && next !== mode) {
+    let answer;
+    try {
+      answer = await host(next);
+    } catch {
+      return { ok: false, mode, code: "host-failed" };
+    }
+    if (answer?.reason !== "host-unsupported") {
+      if (!answer?.ok) return { ok: false, mode, code: answer?.reason || "host-refused" };
+      leaving = true;
+      return { ok: true, mode: next, changed: true, reloading: true };
+    }
+  }
+  if (next === "edit" && mode !== "edit") return enterEdit();
+  if (!canEdit && !(next === "view" && mode === "edit")) return { ok: false, mode, code: "not-allowed" };
+  return switchTo(next);
+}
+
+async function enterEdit() {
+  const asked = location.pathname;
+  const { checkHostPermission } = await import("./host-permission.js");
+  const writable = await checkHostPermission({ fresh: true });
+  // The page moved to another document while the host answered: this request was for the old one.
+  if (location.pathname !== asked) return { ok: false, mode, code: "cancelled" };
+  if (writable === false) return { ok: false, mode, code: "permission-denied" };
+  if (!canEdit) return { ok: false, mode, code: "not-allowed" };
+  return switchTo("edit");
+}
+
+async function switchTo(next) {
+  if (liveSwitch) {
+    // A fetch that fails keeps the old way in: the guarded reload below.
+    const loaded = await fetchController();
+    const live = loaded && (await loaded.switchMode(next, liveSwitch));
+    if (live) return live;
+  }
+  if (next === mode) return { ok: true, mode, changed: false };
+  if (mode === "edit") {
+    let result;
+    try {
+      result = await window.clay?.save?.flush?.();
+    } catch (err) {
+      return { ok: false, mode, code: "save-failed", state: err?.state };
+    }
+    if (result && result.state && result.state !== "saved" && result.state !== "clean") {
+      return { ok: false, mode, code: "save-failed", state: result.state };
+    }
+  }
+  leaving = true;
+  writeReceipt({ mode: next, canEdit, internal: true });
+  location.reload();
+  return { ok: true, mode: next, changed: true, reloading: true };
+}
+
+function openEditParam() {
   const url = new URL(window.location.href);
-  const newMode = isEditMode && !isDraftMode ? "false" : "true";
-  url.searchParams.set('editmode', newMode);
+  url.searchParams.set('editmode', 'true');
   window.location.href = url.toString();
 }
 
-export function setViewerPageTypeBeforeSave () {
-  addDocumentTransform(docElem => {
-    docElem.setAttribute("editmode", "false");
-    docElem.setAttribute("pageowner", "false");
-  });
+export const toggleEditMode = () =>
+  isDraftMode ? openEditParam() : setMode(mode === "edit" ? "view" : "edit");
+
+function keepModeOnReload() {
+  if (!canEdit || isDraftMode) return;
+  window.addEventListener("pagehide", () => { if (!leaving) writeReceipt({ mode, canEdit, internal: false }); });
+}
+
+function markCanEdit() {
+  if (canEdit) {
+    document.documentElement.setAttribute("canedit", "true");
+  } else {
+    document.documentElement.removeAttribute("canedit");
+  }
 }
 
 export function setPageTypeOnPageLoad () {
   onDomReady(() => {
     document.documentElement.setAttribute("editmode", isEditMode ? "true" : "false");
     document.documentElement.setAttribute("pageowner", isOwner ? "true" : "false");
+    markCanEdit();
+    document.addEventListener("clay:capabilitychange", markCanEdit);
     if (isDraftMode) {
       document.documentElement.setAttribute("draftmode", "true");
     } else {
@@ -32,12 +165,12 @@ export function setPageTypeOnPageLoad () {
 }
 
 function init() {
-  setViewerPageTypeBeforeSave();
   setPageTypeOnPageLoad();
+  keepModeOnReload();
 }
 
 // Auto-init when module is imported
 init();
 
-export { init, isEditMode, isOwner };
-export default { init, toggleEditMode, isEditMode, isOwner };
+export { init, isEditMode, isOwner, canEdit, mode };
+export default { init, setMode, toggleEditMode, isEditMode, isOwner, canEdit, mode };

package/src/core/etag.js

@@ -103,6 +103,25 @@ export function forgetEtag() {
   recordEtag(null);
 }
 
+// Only a real answer (spec is a number) says what the host supports: a refresh
+// that failed comes back as a bare host with no extensions, and must not switch
+// conditional saves off for the rest of the page's life.
+function adoptHostExtensions(meta) {
+  if (typeof meta.spec === "number") conditional = meta.extensions.includes("conditional");
+}
+
+/**
+ * Learn from discovery whether this host offers conditional saves. The stamp is
+ * left alone: a session that only wants the capability must not move the version
+ * it is about to save against.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function learnConditionalSaves() {
+  adoptHostExtensions(await hostMeta());
+  return conditional;
+}
+
 /**
  * Learn from discovery whether this host offers conditional saves, and what the
  * document's current stamp is.
@@ -124,10 +143,7 @@ export function forgetEtag() {
 export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
   const at = generation;
   const meta = await hostMeta({ fresh });
-  // Only a real answer (spec is a number) says what the host supports: a refresh
-  // that failed comes back as a bare host with no extensions, and must not switch
-  // conditional saves off for the rest of the page's life.
-  if (typeof meta.spec === "number") conditional = meta.extensions.includes("conditional");
+  adoptHostExtensions(meta);
 
   if (generation !== at) return lastSeen;
 
@@ -184,11 +200,13 @@ document.addEventListener("clay:sync-applied", (event) => {
 // Edit mode goes further: the stamp it SAVES with has to move too, and the host is the
 // only source for the value, so it forgets the one it holds and asks again with the
 // overwrite flags. A view-mode tab never saves, so its save stamp can stay where it is.
-if (isEditMode) {
-  document.addEventListener("clay:sync-applied", (event) => {
-    if (event.detail?.source !== "disk") return;
-    if (typeof event.detail.etag === "string" && event.detail.etag) return;
-    forgetEtag();
-    seedEtag({ fresh: true });
-  });
-}
+// The mode is read when the frame arrives rather than when the listener is installed: a
+// live entry imports this module in view, and this listener has to move the stamp once
+// the edit session it belongs to has committed.
+document.addEventListener("clay:sync-applied", (event) => {
+  if (!isEditMode) return;
+  if (event.detail?.source !== "disk") return;
+  if (typeof event.detail.etag === "string" && event.detail.etag) return;
+  forgetEtag();
+  seedEtag({ fresh: true });
+});

package/src/core/host-meta.js

@@ -27,8 +27,20 @@ const META_TIMEOUT_MS = 6000;
 // a host that failed to say who you are has not said you are nobody.
 const outcomes = new WeakMap();
 
-function settle(outcome, meta = bareHost()) {
+// The path each answer was fetched for, captured when that fetch started. A document block
+// describes one document, and a reply that lands after a route change answers for the one
+// that asked.
+const paths = new WeakMap();
+
+// Which fetch produced each answer, counted from 1 in the order the fetches started. An
+// answer that lands late is still older than one that started later.
+const orders = new WeakMap();
+let fetches = 0;
+
+function settle(outcome, meta = bareHost(), asked = null, order = null) {
   outcomes.set(meta, outcome);
+  if (asked !== null) paths.set(meta, asked);
+  if (order !== null) orders.set(meta, order);
   return meta;
 }
 
@@ -42,6 +54,26 @@ export function hostMetaOutcome(meta) {
   return outcomes.get(meta) ?? "none";
 }
 
+/**
+ * The path the fetch behind `meta` started on, or undefined when there is none.
+ *
+ * @param {Object} meta - an answer from hostMeta()
+ * @returns {string|undefined}
+ */
+export function hostMetaPath(meta) {
+  return paths.get(meta);
+}
+
+/**
+ * Which fetch produced `meta`, counting from 1 in the order the fetches started, or 0 when none did.
+ *
+ * @param {Object} meta - an answer from hostMeta()
+ * @returns {number}
+ */
+export function hostMetaOrder(meta) {
+  return orders.get(meta) ?? 0;
+}
+
 // The bare-core-host answer, which is also every failure's answer.
 function bareHost() {
   return { spec: null, extensions: [], document: null };
@@ -101,6 +133,36 @@ export async function hostSupports(name) {
   return meta.extensions.includes(name);
 }
 
+/**
+ * The page format this host enforces: 1 when it announced `page-format-v1`,
+ * otherwise 0.
+ *
+ * A host announces that extension only once its floor enforcement and tolerant
+ * checkpoint renderer are installed, so a host that cannot hold the floor keeps
+ * the newer writers off. The answer comes from the memoized discovery: one
+ * answer serves every asker under a loaded document.
+ *
+ * @returns {Promise<number>}
+ */
+export async function hostPageFormat() {
+  const meta = await hostMeta();
+  return meta.extensions.includes("page-format-v1") ? 1 : 0;
+}
+
+/**
+ * Whether this host keeps a version history a person can go back to.
+ *
+ * The `document` block names it: absent means no history, which is the answer every
+ * host gave before the field existed. Read through discovery like every other
+ * capability, never inferred from the hostname or a probed route.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function hostVersions() {
+  const meta = await hostMeta();
+  return meta.document?.versions === true;
+}
+
 /** Drop the memoized answer. Tests only. */
 export function resetHostMeta() {
   inFlight = null;
@@ -183,8 +245,10 @@ export async function querySaveOutcome({ saveId, requestHash, signal } = {}) {
 }
 
 async function fetchMeta() {
+  const asked = location.pathname;
+  const order = ++fetches;
   // A file opened from disk has no host to ask, and fetch would only throw.
-  if (!/^https?:$/.test(window.location.protocol)) return settle("none");
+  if (!/^https?:$/.test(window.location.protocol)) return settle("none", bareHost(), asked, order);
 
   const token = saveToken();
   // A host that mints tokens answers discovery per token, because on a sandboxed
@@ -211,25 +275,25 @@ async function fetchMeta() {
       redirect: "manual",
       signal: controller.signal
     });
-    if (!res.ok) return settle(res.status >= 500 ? "failed" : "none");
+    if (!res.ok) return settle(res.status >= 500 ? "failed" : "none", bareHost(), asked, order);
     const text = await res.text();
-    if (!text) return settle("none");
+    if (!text) return settle("none", bareHost(), asked, order);
 
     let body;
     try {
       body = JSON.parse(text);
     } catch (_) {
-      return settle("none");
+      return settle("none", bareHost(), asked, order);
     }
-    if (!body || typeof body !== "object" || typeof body.spec !== "number") return settle("none");
+    if (!body || typeof body !== "object" || typeof body.spec !== "number") return settle("none", bareHost(), asked, order);
 
     return settle("ok", {
       spec: body.spec,
       extensions: Array.isArray(body.extensions) ? body.extensions : [],
       document: body.document && typeof body.document === "object" ? body.document : null
-    });
+    }, asked, order);
   } catch (_) {
-    return settle("failed");
+    return settle("failed", bareHost(), asked, order);
   } finally {
     clearTimeout(timeoutId);
   }

package/src/core/host-permission.js

@@ -0,0 +1,29 @@
+import { hostMeta, hostMetaOrder, hostMetaOutcome, hostMetaPath } from "./host-meta.js";
+import { noteHostWritable } from "./is-edit-mode.js";
+
+let accepted = null;
+let committed = 0;
+
+// A permission answer counts only for the document it was fetched for and only when discovery
+// answered: a failed refresh, or an answer with no document block, is not evidence either way,
+// and leaves the last accepted answer standing. A host that offers no discovery at all ("none")
+// is no answer, so the hints apply again. An older answer never overwrites a newer one.
+export async function checkHostPermission({ fresh = false } = {}) {
+  const asked = location.pathname;
+  let meta = await hostMeta({ fresh });
+  if (location.pathname !== asked) return accepted;
+  if (hostMetaPath(meta) !== asked) {
+    meta = await hostMeta({ fresh: true });
+    if (location.pathname !== asked || hostMetaPath(meta) !== asked) return accepted;
+  }
+  const outcome = hostMetaOutcome(meta);
+  if (outcome === "failed" || (outcome === "ok" && !meta.document)) return accepted;
+  const writable = outcome === "ok" ? meta.document.writable : undefined;
+  // An answer from a fetch older than the one already committed is out of date.
+  const order = hostMetaOrder(meta);
+  if (order < committed) return accepted;
+  committed = order;
+  accepted = typeof writable === "boolean" ? writable : null;
+  noteHostWritable(accepted);
+  return accepted;
+}

package/src/core/is-edit-mode.js

@@ -2,10 +2,14 @@ import cookie from "../lib/cookie.js";
 import query from "../lib/query.js";
 import { hasSaveToken, servedStaleToken, servedSiteVisibility } from "./host-attrs.js";
 import { draftEligible } from "./draft-mode.js";
+import { takeReceipt } from "./mode-receipt.js";
 
-// Edit-mode precedence: an explicit ?editmode=true|false URL param wins, then an
-// authored `viewonly` attribute on <html> (a tool page that must never save its
-// runtime state, even on a host that hands it a save token), then an
+// Two answers come out of here, both decided once, at module evaluation: may this
+// person edit the document (`canEdit`), and does this tab start in edit (`mode`).
+//
+// canEdit is the edit-mode ladder, read as permission. An explicit ?editmode=true|false
+// URL param wins, then an authored `viewonly` attribute on <html> (a tool page that must
+// never save its runtime state, even on a host that hands it a save token), then an
 // opt-in window.clayEditMode global (with the legacy window.__hyperclayEditMode
 // still honored as a fallback for older standalone embedders — htmlclay itself
 // uses its injected save token plus the admin cookie, not this global), then
@@ -16,6 +20,13 @@ import { draftEligible } from "./draft-mode.js";
 // comes before ?editmode=true unless the owner cookie is present, and before the
 // owner cookie otherwise.
 //
+// mode is the narrower question: permission alone no longer opens a document for
+// editing, so an owner reads every document the way a visitor does. A tab starts
+// editing only when something explicit asks for it: a receipt this tab left for its
+// own reload (the person's choice in this tab, newer than the URL it was served with),
+// an ?editmode=true param, window.clayEditMode = true, or an authored
+// <html opens-in="edit"> for a tool page. clay.setMode('edit') is the way in.
+//
 // The token sits above the cookie because it is the stronger claim and often the
 // only one visible: the host minted it for this response and nothing else, while
 // the cookie is ambient. A sandboxed document cannot read the cookie at all, so
@@ -52,23 +63,145 @@ const isDraftMode =
   forcedEditMode == null &&
   !hasSaveToken();
 
-const isEditMode = isDraftMode
-  ? true
+const receipt = typeof window !== "undefined" ? takeReceipt() : null;
+const opensInEdit =
+  typeof document !== "undefined" && document.documentElement.getAttribute("opens-in") === "edit";
+
+// May this person edit here? The old rule, read as permission.
+const hostCanEdit = query.editmode
+  ? query.editmode === "true" || (!isViewOnlyDocument && !servedStaleToken() && (forcedEditMode ?? (hasSaveToken() || ownerCookie)))
+  : isViewOnlyDocument || servedStaleToken()
+    ? false
+    : forcedEditMode != null
+      ? forcedEditMode
+      : hasSaveToken() || ownerCookie;
+const keptCanEdit =
+  receipt?.canEdit === true && forcedEditMode !== false && !servedStaleToken() &&
+  !(isViewOnlyDocument && query.editmode !== "true");
+const hintCanEdit = hostCanEdit || keptCanEdit;
+// What the document or the URL itself rules out; a host's yes never overrides these.
+const authoredRestriction = isDraftMode || servedStaleToken() || forcedEditMode === false ||
+  query.editmode === "false" || (isViewOnlyDocument && query.editmode !== "true");
+let canEdit = hintCanEdit;
+
+// The host's own answer to "may this caller save here": false takes edit away, true grants
+// it unless the document rules it out, and no answer leaves the hints in charge.
+export function noteHostWritable(writable) {
+  const next = writable === false ? false : writable === true ? hintCanEdit || !authoredRestriction : hintCanEdit;
+  if (next === canEdit) return;
+  canEdit = next;
+  if (typeof document !== "undefined") document.dispatchEvent(new Event("clay:capabilitychange"));
+}
+
+// Does this tab start editing? Only when something explicit asks for it.
+const startsEditing = receipt
+  ? receipt.mode === "edit"
   : query.editmode
-    ? query.editmode === "true" // takes precedence over viewonly, the global, token and cookie
-    : isViewOnlyDocument || servedStaleToken()
-      ? false
-      : forcedEditMode != null
-        ? forcedEditMode
-        : hasSaveToken() || ownerCookie;
+    ? query.editmode === "true"
+    : forcedEditMode === true || opensInEdit;
 
+// Live bindings, not constants: the lifecycle controller commits a transition by
+// rewriting them here, and every facade reads them through a getter, so a boolean
+// copied onto `clay` at boot can never go stale.
+let isEditMode = isDraftMode ? true : canEdit && startsEditing;
+let mode = isDraftMode ? "draft" : isEditMode ? "edit" : "view";
 const isOwner = ownerCookie;
 
+// The rest of `clay.modeLifecycle.state`: where edits land, which transition is
+// running, and why the last one refused. The controller is the only writer.
+const lifecycle = {
+  phase: "idle",
+  destination: isDraftMode ? "draft" : "host",
+  generation: 0,
+  reason: null,
+};
+
+export function commitModeFacts(next) {
+  if (next.mode !== undefined) mode = next.mode;
+  if (next.isEditMode !== undefined) {
+    isEditMode = next.isEditMode;
+    if (typeof window !== "undefined") window.__hyperclayEditMode = isEditMode;
+  }
+  if (next.canEdit !== undefined) canEdit = next.canEdit;
+  for (const key in lifecycle) if (next[key] !== undefined) lifecycle[key] = next[key];
+}
+
+export const modeState = () => ({ mode, ...lifecycle });
+
+// A module that starts a session when it evaluates belongs to the session that was idle when
+// it landed: during any transition the committed mode is still the one being left, so a late
+// import would start an editor no exit holds a lease over.
+export function startsAtImport() {
+  return isEditMode && modeState().phase === "idle";
+}
+
+// The one registration queue, on `window.clay`: the API, a preboot push and a later raw
+// push all land in the array the controller drains. Non-enumerable, because it is a
+// handoff and not a member of the facade a page boots with.
+const queue = (() => {
+  if (typeof window === "undefined" || !window.clay) return [];
+  if (window.clay.modeParticipants) return window.clay.modeParticipants;
+  Object.defineProperty(window.clay, "modeParticipants", { value: [], writable: true, configurable: true });
+  return window.clay.modeParticipants;
+})();
+const registered = new Set();
+
+// The readiness check reads the queue without draining it. A registration taken back also
+// leaves the controller's roster, but only when the controller is already loaded.
+let forgetFromRoster = () => {};
+export const noteParticipantForget = (fn) => (forgetFromRoster = fn);
+export const peekModeParticipants = () => queue.slice();
+
+const refuse = (message) => {
+  throw new TypeError(`clay.modeLifecycle: ${message}`);
+};
+
+const refuseUnlessIdleInView = () => {
+  if (lifecycle.phase !== "idle" || isEditMode) refuse("the page is not idle in view");
+};
+
+// A blocked page is a view with a reason: the transition that refused is over and the page
+// is not idle only so the refusal can be read. A participant that arrives then is recorded
+// for the next entry, which is the answer the block already gave, so it is not a second
+// refusal on top of it.
+const refuseUnlessAnEntryCanTakeIt = () => {
+  if (lifecycle.phase === "blocked" && !isEditMode) return;
+  refuseUnlessIdleInView();
+};
+
+export function takeModeParticipants() {
+  registered.clear();
+  return queue.splice(0);
+}
+
+export function registerModeParticipant(participant) {
+  const id = participant && participant.id;
+  if (typeof id !== "string" || !id || typeof participant.prepare !== "function") refuse("a participant needs an id and a prepare()");
+  if (registered.has(id)) refuse(`duplicate participant id "${id}"`);
+  refuseUnlessAnEntryCanTakeIt();
+  registered.add(id);
+  queue.push(participant);
+  // `live`, not `registered`: a drain clears that set while the roster keeps the
+  // participant, so an unregister after the first drain still has to reach the roster.
+  let live = true;
+  return () => {
+    if (!live) return;
+    refuseUnlessAnEntryCanTakeIt();
+    live = false;
+    registered.delete(id);
+    const index = queue.indexOf(participant);
+    if (index !== -1) queue.splice(index, 1);
+    forgetFromRoster(id);
+  };
+}
+
 const siteVisibility = servedSiteVisibility;
 
 export {
   isDraftMode,
   isEditMode,
   isOwner,
-  siteVisibility
+  siteVisibility,
+  canEdit,
+  mode
 }