@panphora/clayjs 1.15.2 → 1.16.0

package/src/core/mode-receipt.js

@@ -0,0 +1,30 @@
+// One-shot proof of the mode this tab was in, written just before a reload and read
+// once, at the top of is-edit-mode.js. It is a hint, like the cookie: the host still
+// authorizes every save.
+import { docKey } from "../lib/doc-storage.js";
+
+const key = () => docKey("mode-receipt");
+const MAX_AGE_MS = 30000;
+
+function navigationType() {
+  try { return performance.getEntriesByType("navigation")[0]?.type ?? null; } catch { return null; }
+}
+
+export function takeReceipt() {
+  let raw = null;
+  try { raw = sessionStorage.getItem(key()); sessionStorage.removeItem(key()); } catch { return null; }
+  if (!raw) return null;
+  let receipt;
+  try { receipt = JSON.parse(raw); } catch { return null; }
+  if (receipt?.v !== 1 || receipt.path !== location.pathname) return null;
+  if (receipt.mode !== "edit" && receipt.mode !== "view") return null;
+  if (Date.now() - receipt.at > MAX_AGE_MS) return null;
+  if (!receipt.internal && navigationType() !== "reload") return null;
+  return receipt;
+}
+
+export function writeReceipt({ mode, canEdit, internal }) {
+  try {
+    sessionStorage.setItem(key(), JSON.stringify({ v: 1, path: location.pathname, mode, canEdit, at: Date.now(), internal }));
+  } catch {}
+}

package/src/core/mode-refusal.js

@@ -0,0 +1,13 @@
+// What a refused mode change tells the person who asked. A request that was joined,
+// superseded or dropped because the page moved on says nothing.
+const TEXT = {
+  "permission-denied": "You don't have permission to edit this document.",
+  "save-failed": "Couldn't save, so this page stays in edit mode.",
+  "host-timeout": "The workspace didn't answer, so this page stays as it was.",
+};
+const QUIET = new Set(["busy", "cancelled"]);
+
+export function modeRefusalText(result) {
+  if (!result || result.ok !== false || QUIET.has(result.code)) return null;
+  return TEXT[result.code] || result.message || "Couldn't switch modes.";
+}

package/src/core/mode-resources.js

@@ -0,0 +1,52 @@
+// Which authored resource a live switch can start and take back, decided before
+// preparation rather than discovered halfway through it. Which edit module is supported
+// is a separate table (mode-support.js). This module is a dynamic target: a reader never
+// fetches it.
+//
+// A style or a stylesheet link is one attribute, and the existing type flip restores it.
+// A script that has run cannot be un-run, so a document whose served bytes carry an
+// `editmode:resource` script has no reversible entry: its script would have to execute
+// again, and re-executing it on every entry is exactly what the reload path exists to
+// avoid. Such a document keeps the guarded reload.
+import { enableAdminResources, disableAdminResources } from "./admin-resources.js";
+
+export const RESOURCE_SELECTOR = '[editmode\\:resource]:is(style, link, script)';
+export const SCRIPT_SELECTOR = 'script[editmode\\:resource]';
+
+export function resourceSupport(root = document) {
+  const scripts = [...root.querySelectorAll(SCRIPT_SELECTOR)];
+  return { reversible: scripts.length === 0, scripts };
+}
+
+// The adapter's lease over the authored resources: a reversible flip for the styles and
+// stylesheets. A document whose script could not be taken back never reaches it, because
+// the caller refuses that document before preparation.
+export function resourcesLease(root = document) {
+  return {
+    enable() {
+      enableAdminResources(root);
+    },
+    quiesce() {},
+    resume() {},
+    dispose() {
+      disableAdminResources();
+    },
+  };
+}
+
+export function resourcesParticipant(root = document) {
+  return {
+    id: "clay:resources",
+    order: 100,
+    prepare() {
+      const { reversible } = resourceSupport(root);
+      if (!reversible) {
+        throw Object.assign(
+          new Error("clay.modeLifecycle: an editmode:resource script cannot be re-run"),
+          { code: "unsupported-plugin" }
+        );
+      }
+      return resourcesLease(root);
+    },
+  };
+}

package/src/core/mode-support.js

@@ -0,0 +1,82 @@
+// Which resolved module a live switch can start and take back, keyed by the path the
+// loader resolves. This module is data only — it imports nothing and evaluates nothing —
+// and it is a dynamic target: a reader never fetches it.
+//
+// A path that is not a row here is unsupported, never assumed supported, so a plugin that
+// arrives through an implication, a default, a `[sap]` root or template metadata is
+// checked exactly like one the URL named. The caller takes the reload path before
+// anything is prepared.
+//
+//   "neutral"  page-lifetime machinery that acts only under the committed mode or write
+//              admission, so a live entry can import it and leave it alone
+//   "export"   the module's namespace exports `modeParticipant`, prepared as a lease
+//   "reader"   the view plan's reader, owned by the transition rather than a lease
+//   function   a reader-loaded module whose participant lives in its edit chunk:
+//              `(mod) => Promise<participant>`, so the reader never loads it
+export const MODULE_SUPPORT = {
+  // The always wave: state mirrors, a key handler and the facades both modes read.
+  "lib/mutation.js": "neutral",
+  "core/preserve-authored.js": "neutral",
+  "core/edit-mode.js": "neutral",
+  "core/mode-key.js": "neutral",
+  "core/stale-host-notice.js": "neutral",
+  "core/page-data.js": "neutral",
+  // Snapshot, save core and the facades over them: functions and transforms read at
+  // capture and save time, never at evaluation.
+  "core/snapshot.js": "neutral",
+  "core/save-core.js": "neutral",
+  "core/recovery.js": "neutral",
+  "core/unsaved-warning.js": "neutral",
+  // These run on a save capture or after a saved event, which only a committed edit
+  // produces, and each handler rechecks the mode or admission at event time, so an old
+  // edit event is never replayed after an exit.
+  "attrs/onaftersave.js": "neutral",
+  "attrs/refetch-on-save.js": "neutral",
+  "lib/cache-bust.js": "neutral",
+  "attrs/save-freeze.js": "neutral",
+  "core/persist.js": "neutral",
+  "attrs/add-from.js": "neutral",
+  "core/etag.js": "neutral",
+  // The modules that keep a session and hand the controller a lease.
+  "core/save.js": "export",
+  "core/conflict-notice.js": "export",
+  "core/autosave.js": "export",
+  "core/admin-attrs.js": "export",
+  "plugins/indicator.js": "export",
+  "plugins/richclay.js": "export",
+  "plugins/sortable.js": "export",
+  "plugins/undo.js": "export",
+  "plugins/unsent.js": "export",
+  "plugins/upload.js": "export",
+  "plugins/people.js": "export",
+  "plugins/live.js": "export",
+  "plugins/page.js": "export",
+  "plugins/visitor-drafts-owner.js": "export",
+  // A view boot already loaded these three, and each reads the mode at event time.
+  "plugins/menu.js": "neutral",
+  "plugins/upgrade.js": "neutral",
+  "plugins/derive.js": "neutral",
+  // A binding has no import-time work, and its disposal belongs to the application's own
+  // participant.
+  "plugins/bind-text.js": "neutral",
+  // The view plan's reader, owned by the transition rather than a lease: the controller
+  // prepares no lease for a `"reader"` row.
+  "plugins/page-view.js": "reader",
+  // The source map fetches, pairs and installs a save renderer, so it is a session: the
+  // lease installs on a live entry and clears the renderer when the page goes back to view.
+  "plugins/source.js": "export",
+  // Generic sync: the module a reader and an editor both load, and the one whose
+  // session starts regardless of mode. Its participant is in the edit chunk.
+  "sync/live-sync.js": (mod) => mod.liveSync.editParticipant(),
+  // The channel to a local process: its lease holds admission for the edit requests it
+  // sends, so a live entry opens it at the commit and an exit closes it again.
+  "plugins/wire.js": "export",
+  // The AI composer: the lease builds the chrome on a live entry and takes it down again.
+  "plugins/ai-edit.js": "export",
+  // The CMS: the source owns the session, so the lease that opens it is the one that
+  // closes it.
+  "plugins/cms.js": "export",
+};
+
+export const supportFor = (path) =>
+  Object.prototype.hasOwnProperty.call(MODULE_SUPPORT, path) ? MODULE_SUPPORT[path] : null;

package/src/core/mode-switch.js

@@ -0,0 +1,259 @@
+// The live switch's decision, and the one lease every session starts with.
+//
+// A document that signs `<html clay-mode-switch="live">` is saying its code can enter and
+// leave edit repeatedly. That claim is checked here, before anything is prepared: every
+// module either of its plans resolves must have a support row and nothing it authored may
+// have to run again, or the document keeps the guarded reload. The same goes for a queued
+// participant that is not one: a lease nobody can call is not a lease.
+//
+// The controller reaches this module, and only the controller: a reader pays for the
+// declaration and nothing else.
+import { peekModeParticipants, registerModeParticipant } from "./is-edit-mode.js";
+import { resourceSupport, resourcesParticipant } from "./mode-resources.js";
+import { supportFor } from "./mode-support.js";
+
+let resourcesQueued = false;
+
+// A participant queued before boot may be a promise; the controller awaits that one
+// itself. Anything else has to have the shape a lease is prepared from, and its id has to
+// be unique across the queue. Validating never drains: a malformed queue is left as it is.
+const participantsReady = () => {
+  const ids = new Set();
+  for (const entry of peekModeParticipants()) {
+    if (typeof entry?.then === "function") continue;
+    const id = entry?.id;
+    if (typeof id !== "string" || typeof entry?.prepare !== "function") return false;
+    if (ids.has(id)) return false;
+    ids.add(id);
+  }
+  return true;
+};
+
+// Every module either road resolves: the edit plan with its own core wave, the plugins an
+// implication, a default, a `[sap]` root or template metadata pulled in, and the plan this
+// tab booted. Passing that whole set is the point — a plugin nobody named is checked
+// exactly like one the URL did.
+const resolvedPaths = (handle) => [
+  ...(handle?.edit?.core ?? []),
+  ...(handle?.edit?.plugins ?? []),
+  ...(handle?.edit?.late ?? []),
+  ...(handle?.view?.plugins ?? []),
+  ...(handle?.view?.late ?? []),
+];
+
+/**
+ * Which of the modules this document resolves this release cannot start and take back.
+ *
+ * @param {{edit?: object, view?: object}} handle - both resolved plans
+ * @returns {string[]}
+ */
+export function unsupportedPaths(handle) {
+  return [...new Set(resolvedPaths(handle))].filter((path) => supportFor(path) === null);
+}
+
+/**
+ * May this document switch live, through the plans it resolved?
+ *
+ * @param {{edit?: object, view?: object}} handle - both resolved plans
+ * @returns {boolean}
+ */
+export function liveAllowed(handle) {
+  return participantsReady() && unsupportedPaths(handle).length === 0 && resourceSupport().reversible;
+}
+
+// The authored styles and stylesheets are the first lease of an entry: `liveAllowed` proved
+// them reversible, so the entry flips them and the exit flips them back. Registered once,
+// through the queue the dispatcher already holds, while the page is idle in view.
+export function openResources() {
+  if (resourcesQueued) return;
+  resourcesQueued = true;
+  registerModeParticipant(resourcesParticipant());
+}
+
+// The abort an entry reports when its own deadline or a newer generation cancelled it:
+// named as the platform names a cancelled import, so a caller can tell it apart from a
+// module that failed.
+const cancelled = () =>
+  Object.assign(new Error("clay.modeLifecycle: the import was cancelled"), { name: "AbortError", code: "aborted" });
+
+// One deadline covers the whole transition, so the reader's half of it is bounded by the
+// same number the controller uses for everything else.
+const DEADLINE_MS = 15000;
+
+const fault = (message, code) => Object.assign(new Error(`clayjs: ${message}`), { code });
+
+// The promise, or the entry's cancellation, whichever settles first: an acquisition that
+// never answers is a reload, not a session built on nothing.
+const within = (promise, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(cancelled());
+    const abort = () => reject(cancelled());
+    signal?.addEventListener?.("abort", abort);
+    Promise.resolve(promise).then(
+      (value) => {
+        signal?.removeEventListener?.("abort", abort);
+        resolve(value);
+      },
+      (err) => {
+        signal?.removeEventListener?.("abort", abort);
+        reject(err);
+      }
+    );
+  });
+
+// A handoff answers with the file it was built from, never with a promise of one: a
+// reader that represents no bytes has nothing a session can be built on.
+const noFile = (handoff) => !handoff?.represented || handoff.represented.bytes === null;
+
+// The instance inside a `sync/live-sync.js` namespace: the module exports the singleton
+// under its own name and as the default, and both name the same object.
+const syncLane = (mod) => (mod && (mod.liveSync ?? mod.default ?? mod)) || null;
+
+/**
+ * Ask the reader a declared document already runs for its half of the switch: the file
+ * it represents, the queue it is holding, and the calls that apply, give back and retire
+ * them.
+ *
+ * The page-view reader answers first, because a Document's reader owns the article; a
+ * generic-sync document's saved lane answers next. A document with neither has no reader
+ * and needs no handoff. A reader that represents no file throws `not-acquired`, which is
+ * the reload: nothing has been prepared yet, so the page can still be replaced.
+ *
+ * @param {object} handle - the loader's handle: `{loaded, modules, attach, ...}`
+ * @param {{signal?: AbortSignal}} [context] - the entry's context
+ * @returns {Promise<?object>}
+ */
+export async function prepareReader(handle, context = {}) {
+  const signal = context.signal;
+  const options = { signal, deadline: DEADLINE_MS };
+  const pageView = handle?.loaded?.["plugins/page-view.js"];
+  if (pageView?.ready) {
+    await within(pageView.acquired, signal);
+    const handoff = await pageView.prepareHandoff(options);
+    if (noFile(handoff)) throw fault("the reader has no file to hand over", "not-acquired");
+    return handoff;
+  }
+  const lane = syncLane(handle?.loaded?.["sync/live-sync.js"]);
+  if (lane && !lane.isDestroyed && lane.lane === "saved") {
+    const handoff = await lane.prepareHandoff(options);
+    if (noFile(handoff)) throw fault("the reader has no file to hand over", "not-acquired");
+    return handoff;
+  }
+  return null;
+}
+
+/**
+ * Start the reader a view holds, from the file the session left: the page-view reader
+ * paints that receipt at once and asks the host for nothing, and the saved lane starts
+ * with it, so a second entry has a file without waiting for a frame. Every reader the page
+ * ran before the entry starts again, so a page-view reader that follows generic sync's
+ * saved lane gets that lane back too. `accepted` null starts the reader as a view boot does.
+ *
+ * @param {object} handle - the loader's handle
+ * @param {?{bytes: string, etag: ?string, seq: ?number}} accepted - the receipt to start from
+ */
+export function startReader(handle, accepted = null) {
+  const pageView = handle?.loaded?.["plugins/page-view.js"];
+  // The plan this page booted, not what an entry imported: a Document's edit plan
+  // carries generic sync as well, and the reader is restarted as the one it was.
+  const sync = Array.isArray(handle?.view?.plugins)
+    ? handle.view.plugins.includes("sync/live-sync.js")
+    : Boolean(handle?.loaded?.["sync/live-sync.js"]);
+  if (pageView) {
+    const start = pageView.restart ?? pageView.start;
+    start({ sync, represented: accepted });
+    // Every reader the page ran before the entry comes back, not the first one found:
+    // with `plugins=page,sync` the page-view reader follows generic sync's saved lane,
+    // so that lane is restarted too and the article keeps following other tabs.
+    if (!sync) return undefined;
+  }
+  const lane = syncLane(handle?.loaded?.["sync/live-sync.js"]);
+  if (lane) return lane.start(lane.currentFile, { lane: "saved", represented: accepted });
+  return undefined;
+}
+
+/**
+ * Import an edit plan's missing modules through the loader's own record and import cache.
+ *
+ * One path at a time, core then plugins then the late tail, in plan order: the same order
+ * boot imports them in, for the same reasons. A path boot already loaded is skipped, so
+ * nothing evaluates twice; a path in flight is awaited, so boot's late tail and an entry
+ * that overlap share one import; and a rejected thunk is dropped from the cache so the
+ * next attempt calls it again. It attaches the edit members once the core has landed and
+ * each plugin's member as that plugin lands, exactly as boot does, and it announces
+ * nothing: the plugin-ready events belong to a committed entry, not to an import.
+ *
+ * @param {object} handle - the loader's handle: `{loaded, modules, attach, attachEditCore, loadEditHints, late}`
+ * @param {{core?: string[], plugins?: string[], late?: string[]}} plan
+ * @param {{signal?: AbortSignal}} [options]
+ * @returns {Promise<string[]>} the plugin paths this call newly loaded
+ */
+export async function importPlan(handle, plan, { signal } = {}) {
+  const inflight = (handle.inflight ||= new Map());
+  const newlyLoaded = [];
+
+  const stop = () => { if (signal?.aborted) throw cancelled(); };
+
+  // The loader's own hint fetch, which preloads what it returns against this plan. A failed
+  // fetch defers hints, never an import already mapped.
+  const hints = handle.loadEditHints?.();
+  if (hints) {
+    try {
+      await hints;
+    } catch {}
+  }
+
+  const importPath = (path) => {
+    if (!inflight.has(path)) {
+      const promise = Promise.resolve()
+        .then(() => handle.modules[path]())
+        .catch((err) => {
+          inflight.delete(path);
+          throw err;
+        });
+      inflight.set(path, promise);
+    }
+    return inflight.get(path);
+  };
+
+  for (const path of plan.core ?? []) {
+    if (handle.loaded[path]) continue;
+    stop();
+    const mod = await importPath(path);
+    handle.loaded[path] = mod;
+    mod.install?.();
+  }
+  // Once, after the core wave: the members those modules offer, added to the facade
+  // boot assembled rather than replacing it.
+  handle.attachEditCore(handle.loaded);
+
+  for (const path of plan.plugins ?? []) {
+    if (handle.loaded[path]) continue;
+    stop();
+    const mod = await importPath(path);
+    handle.loaded[path] = mod;
+    handle.attach(path, mod);
+    newlyLoaded.push(path);
+  }
+
+  const late = (plan.late ?? []).filter((path) => !handle.loaded[path]);
+  if (late.length) {
+    // Boot's tail may be importing these same paths right now, and it records them in the
+    // same table a moment after each import resolves. Waiting for it costs nothing an
+    // entry was not already waiting for, and it is what keeps one import per path.
+    stop();
+    try {
+      await handle.late;
+    } catch {}
+    for (const path of late) {
+      if (handle.loaded[path]) continue;
+      stop();
+      const mod = await importPath(path);
+      handle.loaded[path] = mod;
+      handle.attach(path, mod);
+      newlyLoaded.push(path);
+    }
+  }
+
+  return newlyLoaded;
+}

package/src/core/mode-transition.js

@@ -0,0 +1,112 @@
+// The save barrier: the one write an exit is allowed to make, and the pause around it.
+//
+// A switch has closed input admission before this runs, so an ordinary save cannot go
+// out. The barrier is not an ordinary save: it carries a permit minted for the mode
+// generation it is leaving, it fastens the work no save can write (registered models,
+// uploads, a composer waiting on its person), it writes the page's bytes, and it answers
+// only when the host has accepted bytes that include everything the page still holds.
+//
+// It also takes the document-operation slot, because a flush is only meaningful if
+// nothing else replaces the document while it runs. A caller that already owns that slot
+// (the mode controller's exit) hands its token in, so the barrier does not queue behind
+// its own claim: a standalone call still claims one and releases it.
+//
+// This module is a dynamic target reached from the mode controller: a reader never
+// fetches it.
+import { claimDocumentOperation, releaseDocumentOperation, operationKind, saveFateIsUnknown } from "./save-core.js";
+import { flushSave, isSaveConflicted, openSavePermit, closeSavePermit, saveGeneration } from "./save.js";
+import { flushUnsaved, pendingIds } from "../lib/unsaved-state.js";
+import { bytesUnsaved } from "./unsaved-warning.js";
+
+const DEADLINE_MS = 15000;
+const EXPIRED = Symbol("the barrier deadline passed");
+// Two passes at most: the first writes, and a second only covers input that arrived
+// while the first request was on the wire. Anything still unsaved after that refuses.
+const MAX_PASSES = 2;
+
+const refusal = (code, extra = {}) => ({ ok: false, code, ...extra });
+
+// One wait of the barrier, bounded by its own deadline: a source whose flush never
+// settles is the deadline's business, not an exit that never returns.
+async function bounded(pending, deadline) {
+  let timer = null;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(EXPIRED), Math.max(0, deadline - Date.now()));
+  });
+  try {
+    return await Promise.race([Promise.resolve(pending), expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export { claimDocumentOperation as claimOperation, releaseDocumentOperation as releaseOperation, operationKind };
+
+/**
+ * Fasten everything this page holds that a save cannot write, then write its bytes.
+ *
+ * Answers `{ ok: true, state, etag }` only when the host accepted bytes that include
+ * every edit and every registered value on the page, under `generation`'s permit. Every
+ * other answer is `{ ok: false, code }` from the transition vocabulary: `busy`,
+ * `stale-document`, `pending-input`, `conflict`, `save-unknown`, `save-failed`,
+ * `timeout`. Nothing about the page's state moves on a refusal, and nothing is aborted:
+ * a write already on the wire keeps its own outcome.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.generation] - the mode generation this exit is leaving
+ * @param {boolean} [options.keepalive]
+ * @param {number} [options.timeoutMs] - the whole barrier, the pending-source flush
+ *   included, so a source that never settles refuses as `timeout`
+ * @param {Object} [options.operation] - the slot its caller already holds; claimed here when absent
+ * @returns {Promise<{ok: boolean, code?: string, state?: string, etag?: ?string, pending?: string[]}>}
+ */
+export async function runSaveBarrier({ generation = saveGeneration(), keepalive = false, timeoutMs = DEADLINE_MS, operation = null } = {}) {
+  const claimed = operation ? null : claimDocumentOperation("mode");
+  if (!operation && !claimed) return refusal("busy");
+  const deadline = Date.now() + timeoutMs;
+  const permit = openSavePermit(generation);
+  try {
+    for (let pass = 0; ; pass++) {
+      if (generation !== saveGeneration()) return refusal("stale-document");
+      if (Date.now() >= deadline) return refusal("timeout");
+
+      // Work that finishes on its own — a checkpoint, a queued upload — is asked to. A
+      // composer waiting on its person has no flush and stays pending: that is a refusal,
+      // never a blur or a submit on their behalf.
+      const sources = await bounded(flushUnsaved(), deadline);
+      if (sources === EXPIRED) return refusal("timeout");
+      if (!sources.ok) return refusal("pending-input", { pending: sources.pending });
+      if (sources.pending.length) return refusal("pending-input", { pending: sources.pending });
+
+      // Neither a conflict nor an unresolved fate is a failure a retry fixes.
+      if (isSaveConflicted()) return refusal("conflict");
+      if (saveFateIsUnknown()) return refusal("save-unknown");
+
+      let result;
+      try {
+        result = await flushSave({ keepalive, timeoutMs: Math.max(0, deadline - Date.now()), permit });
+      } catch (err) {
+        if (err?.state === "conflict") return refusal("conflict");
+        if (err?.state === "blocked") return refusal("pending-input", { pending: pendingIds() });
+        if (saveFateIsUnknown()) return refusal("save-unknown");
+        if (Date.now() >= deadline) return refusal("timeout");
+        return refusal("save-failed");
+      }
+
+      if (result.state !== "clean" && result.state !== "saved") return refusal("save-failed");
+      // The host answered, but an answer is only an exit when nothing is left behind.
+      if (isSaveConflicted()) return refusal("conflict");
+      if (saveFateIsUnknown()) return refusal("save-unknown");
+      const pending = pendingIds();
+      if (pending.length) return refusal("pending-input", { pending });
+      if (bytesUnsaved()) {
+        if (pass + 1 < MAX_PASSES && Date.now() < deadline) continue;
+        return refusal("pending-input");
+      }
+      return { ok: true, state: result.state, etag: result.etag ?? null };
+    }
+  } finally {
+    closeSavePermit(permit);
+    if (claimed) releaseDocumentOperation(claimed);
+  }
+}