@panphora/clayjs 1.15.1 → 1.16.0

package/src/lib/dirty-gate.js

@@ -51,6 +51,9 @@ function scheduleAnnounce() {
     const dirty = pageMaybeDirty();
     if (dirty === announcedDirty) return;
     announcedDirty = dirty;
+    const root = document.documentElement;
+    if (dirty) root.setAttribute('unsaved', 'true');
+    else root.removeAttribute('unsaved');
     document.dispatchEvent(new CustomEvent(dirty ? 'clay:dirty' : 'clay:clean'));
   });
 }
@@ -182,6 +185,18 @@ export function pageMaybeDirty() {
   return changes > clearedAt || persistProbeDirty();
 }
 
+/**
+ * How many changes this page has recorded, ever.
+ *
+ * Monotonic and never rewound by a save or a clear, so a caller that closed input
+ * admission can record it and later prove that nothing new arrived while it was closed,
+ * instead of assuming quiet. Observation keeps running while admission is closed: what
+ * stops is writing, never the record of work.
+ */
+export function gateRevision() {
+  return changes;
+}
+
 /**
  * Record the gate state at capture time. The save flow takes a token when it
  * clones the DOM and hands it back on success (or on a verified "no changes"),

package/src/lib/doc-storage.js

@@ -0,0 +1,33 @@
+// Browser storage for one document. Two documents on one origin (every file on a
+// hyperclay.com subdomain) otherwise share every key an app writes.
+export const docKey = (key) => `clay:doc:${location.pathname}:${key}`;
+
+function area(name) {
+  const memory = new Map();
+  // Keys whose last write or removal could not reach the backend. Memory holds
+  // the authoritative value (or the removal) for them until one write lands.
+  const overrides = new Set();
+  const prefix = () => docKey("");
+  const backend = () => { try { return window[name] || null; } catch { return null; } };
+  return {
+    get(key) {
+      const k = prefix() + key;
+      if (!overrides.has(k)) {
+        try { const raw = backend()?.getItem(k); if (raw != null) return JSON.parse(raw); } catch {}
+      }
+      return memory.has(k) ? memory.get(k) : undefined;
+    },
+    set(key, value) {
+      const k = prefix() + key;
+      memory.set(k, value);
+      try { backend().setItem(k, JSON.stringify(value)); overrides.delete(k); return true; } catch { overrides.add(k); return false; }
+    },
+    remove(key) {
+      const k = prefix() + key;
+      memory.delete(k);
+      try { backend().removeItem(k); overrides.delete(k); } catch { overrides.add(k); }
+    },
+  };
+}
+
+export const storage = { local: area("localStorage"), session: area("sessionStorage") };

package/src/lib/effect.js

@@ -110,17 +110,22 @@ export function effect(fn) {
     queueMicrotask(run);
   };
 
+  const undoEvents = ["undo", "redo"];
+  const bindUndo = () => {
+    for (const type of undoEvents) clay.undo?.on?.(type, schedule);
+  };
+
   const offMutation = Mutation.onAnyChange({ debounce: 0, require: "observed" }, schedule);
   document.addEventListener("clay:sync-applied", schedule);
-  clay.undo?.on?.("undo", schedule);
-  clay.undo?.on?.("redo", schedule);
+  document.addEventListener("clay:modechange", bindUndo);
+  bindUndo();
 
   const stop = () => {
     stopped = true;
     offMutation();
     document.removeEventListener("clay:sync-applied", schedule);
-    clay.undo?.off?.("undo", schedule);
-    clay.undo?.off?.("redo", schedule);
+    document.removeEventListener("clay:modechange", bindUndo);
+    for (const type of undoEvents) clay.undo?.off?.(type, schedule);
   };
 
   schedule();

package/src/lib/mutation.js

@@ -150,11 +150,13 @@ const localMutation = {
   // Records the browser queued before this pause describe changes made outside
   // it. Left in the queue, resume() would drain them as paused-time records and
   // only non-pausable callbacks would see them, so autosave missed a change made
-  // just before a pause. Deliver them on a microtask, as the observer would have.
+  // just before a pause. Deliver them NOW, before the depth rises and before the
+  // pause is bridged to undo: a deferred delivery arrived while the raw lane was
+  // paused, and undo's paused sink drops what it sees then.
   _deliverBeforePause() {
     if (!this._observer) return;
     const records = this._observer.takeRecords();
-    if (records.length) queueMicrotask(() => this._onRecords(records));
+    if (records.length) this._onRecords(records);
   },
 
   /**

package/src/lib/offline-runtime.js

@@ -0,0 +1,226 @@
+export const LOCAL_PREFIX = "/_/clayjs/";
+
+const CONTROL = /[\u0000-\u001F\u007F]/;
+const ASCII_EDGE_SPACE = /^[\t\n\f\r ]|[\t\n\f\r ]$/;
+const ROLLING = /^https:\/\/clayjs\.com\/v(\d+)\/([\s\S]*)$/;
+const EXACT = /^https:\/\/clayjs\.com\/(\d+)\.(\d+)\.(\d+)\/([\s\S]*)$/;
+const LOCAL = /^\/_\/clayjs\/(\d+)\.(\d+)\.(\d+)\/([\s\S]*)$/;
+const SUSPECT = /%2e|%2f|%5c/i;
+
+function majorOf(version) {
+  if (typeof version !== "string") return null;
+  const match = /^(\d+)\.\d+\.\d+$/.exec(version);
+  return match ? match[1] : null;
+}
+
+function originOf(documentURL) {
+  if (typeof documentURL !== "string" || documentURL === "") return null;
+  try {
+    return new URL(documentURL).origin;
+  } catch {
+    return null;
+  }
+}
+
+function splitURL(raw) {
+  const hashAt = raw.indexOf("#");
+  const hash = hashAt < 0 ? "" : raw.slice(hashAt);
+  const withoutHash = hashAt < 0 ? raw : raw.slice(0, hashAt);
+  const searchAt = withoutHash.indexOf("?");
+  const search = searchAt < 0 ? "" : withoutHash.slice(searchAt);
+  const head = searchAt < 0 ? withoutHash : withoutHash.slice(0, searchAt);
+  return { head, search, hash };
+}
+
+function decodePath(rawPath) {
+  if (rawPath === "") return null;
+  if (rawPath.includes("\\")) return null;
+  if (SUSPECT.test(rawPath)) return null;
+  const segments = rawPath.split("/");
+  const decoded = [];
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") return null;
+    let value;
+    try {
+      value = decodeURIComponent(segment);
+    } catch {
+      return null;
+    }
+    if (value.includes("/") || value.includes("\\")) return null;
+    if (value === "." || value === "..") return null;
+    decoded.push(value);
+  }
+  return decoded.join("/");
+}
+
+export function parseRuntimeURL(raw, { documentURL } = {}) {
+  if (typeof raw !== "string") return null;
+  if (raw === "") return null;
+  if (ASCII_EDGE_SPACE.test(raw) || CONTROL.test(raw)) return null;
+  const { head, search, hash } = splitURL(raw);
+
+  let kind = null;
+  let version = null;
+  let major = null;
+  let rawPath = null;
+
+  let match = ROLLING.exec(head);
+  if (match) {
+    kind = "rolling";
+    major = match[1];
+    rawPath = match[2];
+  }
+  if (!kind) {
+    match = EXACT.exec(head);
+    if (match) {
+      kind = "exact";
+      version = `${match[1]}.${match[2]}.${match[3]}`;
+      major = match[1];
+      rawPath = match[4];
+    }
+  }
+  if (!kind) {
+    match = LOCAL.exec(head);
+    if (match) {
+      kind = "local";
+      version = `${match[1]}.${match[2]}.${match[3]}`;
+      major = match[1];
+      rawPath = match[4];
+    }
+  }
+  if (!kind) {
+    const origin = originOf(documentURL);
+    if (origin && head.startsWith(`${origin}/`)) {
+      match = LOCAL.exec(head.slice(origin.length));
+      if (match) {
+        kind = "local";
+        version = `${match[1]}.${match[2]}.${match[3]}`;
+        major = match[1];
+        rawPath = match[4];
+      }
+    }
+  }
+  if (!kind) return null;
+
+  const path = decodePath(rawPath);
+  if (path === null) return null;
+
+  return { kind, major, version, rawPath, path, search, hash };
+}
+
+function filesOf(releases, version) {
+  const release = releases && typeof releases === "object" ? releases[version] : null;
+  return release && typeof release.files === "object" && release.files ? release.files : null;
+}
+
+export function resolveRuntimeURL(raw, { releases, selectedVersion, documentURL } = {}) {
+  const selected = filesOf(releases, selectedVersion);
+  if (selected) {
+    const aliases = releases[selectedVersion].aliases;
+    if (aliases && typeof aliases === "object" && Object.hasOwn(aliases, raw)) {
+      const target = aliases[raw];
+      return {
+        kind: "alias",
+        version: selectedVersion,
+        path: target,
+        search: "",
+        hash: "",
+        available: true,
+        canonicalURL: raw,
+        localURL: `${LOCAL_PREFIX}${selectedVersion}/${target}`,
+      };
+    }
+  }
+
+  const parsed = parseRuntimeURL(raw, { documentURL });
+  if (!parsed) return null;
+  if (parsed.kind === "local") return null;
+
+  let version;
+  if (parsed.kind === "rolling") {
+    if (majorOf(selectedVersion) === null || majorOf(selectedVersion) !== parsed.major) return null;
+    version = selectedVersion;
+  } else {
+    version = parsed.version;
+    if (!filesOf(releases, version)) {
+      return {
+        kind: "exact",
+        version,
+        path: parsed.path,
+        search: parsed.search,
+        hash: parsed.hash,
+        available: false,
+        canonicalURL: raw,
+        localURL: null,
+      };
+    }
+  }
+
+  const files = filesOf(releases, version);
+  if (!files || !Object.hasOwn(files, parsed.path)) return null;
+
+  return {
+    kind: parsed.kind,
+    version,
+    path: parsed.path,
+    search: parsed.search,
+    hash: parsed.hash,
+    available: true,
+    canonicalURL: raw,
+    localURL: `${LOCAL_PREFIX}${version}/${parsed.rawPath}${parsed.search}${parsed.hash}`,
+  };
+}
+
+function entriesOf(descriptor) {
+  if (!descriptor || typeof descriptor !== "object") return [];
+  if (!Array.isArray(descriptor.entries)) return [];
+  return descriptor.entries.filter((entry) => entry && typeof entry === "object");
+}
+
+function originalMatchesRelease(original, version, releases) {
+  if (!releases) return true;
+  const files = filesOf(releases, version);
+  return Boolean(files && Object.hasOwn(files, original.path));
+}
+
+export function canonicalizeRuntimeURL(value, { descriptor, releases, documentURL, aliases } = {}) {
+  const local = parseRuntimeURL(value, { documentURL });
+  if (!local || local.kind !== "local") return value;
+
+  const entries = entriesOf(descriptor);
+  const localMajor = majorOf(local.version);
+
+  for (const entry of entries) {
+    if (entry.local !== value || typeof entry.original !== "string") continue;
+    const trusted = releases?.[local.version]?.aliases ?? aliases;
+    if (trusted && typeof trusted === "object" && !local.search && !local.hash &&
+        Object.hasOwn(trusted, entry.original) && trusted[entry.original] === local.path) {
+      return entry.original;
+    }
+    const original = parseRuntimeURL(entry.original);
+    if (!original) continue;
+    if (original.kind !== "rolling" && original.kind !== "exact") continue;
+    if (original.rawPath !== local.rawPath) continue;
+    if (original.search !== local.search) continue;
+    if (original.hash !== local.hash) continue;
+    if (original.kind === "rolling" ? original.major !== localMajor : original.version !== local.version) continue;
+    if (!originalMatchesRelease(local, local.version, releases)) continue;
+    if (original.kind === "exact") return entry.original;
+    return `https://clayjs.com/v${original.major}/${local.rawPath}${local.search}${local.hash}`;
+  }
+
+  for (const entry of entries) {
+    if (typeof entry.original !== "string") continue;
+    const original = parseRuntimeURL(entry.original);
+    if (!original) continue;
+    if (original.kind !== "rolling" && original.kind !== "exact") continue;
+    if (original.rawPath !== local.rawPath) continue;
+    if (original.kind === "rolling" ? original.major !== localMajor : original.version !== local.version) continue;
+    if (original.kind === "rolling") {
+      return `https://clayjs.com/v${original.major}/${local.rawPath}${local.search}${local.hash}`;
+    }
+    return `https://clayjs.com/${original.version}/${local.rawPath}${local.search}${local.hash}`;
+  }
+
+  return `https://clayjs.com/${local.version}/${local.rawPath}${local.search}${local.hash}`;
+}

package/src/lib/preload.js

@@ -0,0 +1,48 @@
+// A reader fetched only the manifest; an editable page also fetched the supplement.
+// Both are hint lists, so a boot holding one still runs and defers the other's hints.
+export function mergeManifests(manifest, supplement) {
+  if (!manifest || !supplement) return manifest;
+  const both = { ...supplement, ...manifest };
+  for (const key of ["entries", "imports", "bootImports"]) both[key] = { ...supplement[key], ...manifest[key] };
+  return both;
+}
+
+// The chunked build's files that a boot plan will import, fetched in parallel before
+// boot() imports them one at a time in its load-bearing order. clay="no-save" keeps
+// the links out of every save and out of live sync's merge.
+const PAGE_PLUGIN = "plugins/page.js";
+
+export function preloadEntries(manifest, paths, { isEditMode = false, isDraftMode = false, hasSapJs = false } = {}, doc = document) {
+  if (!manifest?.entries) return 0;
+  const seeds = [...paths];
+  for (const path of paths) {
+    for (const file of manifest.bootImports?.[path] ?? []) {
+      if (hasSapJs && file === "vendor/sap-core.vendor.js") continue;
+      seeds.push(file);
+    }
+  }
+  if (isEditMode && !isDraftMode) seeds.push(...(manifest.editBootImports ?? []));
+  // The editor is fetched beside the room join, so a plan that runs the page plugin
+  // preloads it and another template's edit boot does not.
+  if (isEditMode && !isDraftMode && paths.includes(PAGE_PLUGIN)) seeds.push(...(manifest.editorBootImports ?? []));
+  const want = new Set();
+  const add = (file) => {
+    if (!file || want.has(file)) return;
+    want.add(file);
+    for (const dep of manifest.imports?.[file] ?? []) add(dep);
+  };
+  for (const p of seeds) add(manifest.entries[p]);
+  const have = new Set([...doc.querySelectorAll('link[rel="modulepreload"]')].map((link) => link.href));
+  let added = 0;
+  for (const file of want) {
+    const href = new URL(file, manifest.base).href;
+    if (have.has(href)) continue;
+    const link = doc.createElement("link");
+    link.rel = "modulepreload";
+    link.href = href;
+    link.setAttribute("clay", "no-save");
+    doc.head.append(link);
+    added++;
+  }
+  return added;
+}

package/src/lib/root-attrs.js

@@ -94,7 +94,7 @@ export const HOST_TOKEN_ATTRS = [
 ];
 
 // This library's own root state, and this tab's UI truth.
-export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner", "draftmode"];
+export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner", "draftmode", "unsaved", "canedit"];
 
 // Never copied between tabs: not written onto this root by an incoming morph, not
 // sent out on a sync broadcast.

package/src/lib/trash.js

@@ -0,0 +1,18 @@
+// Soft delete. A record in the trash keeps its place, id and content and carries
+// data-deleted-at; restoring removes the attribute; purging removes the record.
+export const DELETED_ATTR = "data-deleted-at";
+const run = (label, fn) => (window.clay?.undo?.commit ? window.clay.undo.commit(label, fn) : fn());
+const tell = (el, type) => el.dispatchEvent(new CustomEvent(type, { bubbles: true }));
+
+export const trash = Object.assign(
+  (el, { at = new Date().toISOString() } = {}) => {
+    run("Move to Trash", () => el.setAttribute(DELETED_ATTR, at));
+    tell(el, "clay:trashed");
+    return { undo: () => trash.restore(el) };
+  },
+  {
+    is: (el) => !!el.getAttribute(DELETED_ATTR),
+    restore(el) { run("Restore", () => el.removeAttribute(DELETED_ATTR)); tell(el, "clay:restored"); },
+    purge(el) { run("Delete forever", () => el.remove()); },
+  },
+);

package/src/lib/undo/capture-move.js

@@ -0,0 +1,152 @@
+// One drag or one `clay.sortable.move` as one semantic undo entry.
+//
+// The engine records primitives, not gestures. A move is the item leaving its source
+// slot and arriving in the destination slot, so the entry is that remove and that add
+// recorded inside `undo.command`; the engine pairs them into its own `move` step,
+// checked against the item's identity and both sequences, so undo puts the card back
+// without replaying the drag and redo moves it again.
+//
+// A gesture also writes while it happens. Sortable marks the item it picks up
+// draggable and leaves style="" behind, and those writes are runtime, not authored
+// content: they are ignored while the gesture is open (isRuntimeAttribute), and the
+// writes the end of the gesture makes are held out of the automatic idle batch
+// (holdMove/releaseMove) so a drag cannot also become a generic `Edit` entry.
+
+const RUNTIME_ATTRS = new Set(['draggable', 'style'])
+
+// The presses whose gesture may still be writing. Bounded: a press joins on pointerdown
+// and leaves on its end, its cancel, or the session's dispose.
+const open = new Set()
+
+const engine = () => window.clay?.undo
+
+const sameNodes = (a, b) => a.length === b.length && a.every((node, i) => node === b[i])
+
+// The label a person reads in the history. A container names its own moves; a list
+// that does not is simply "Move".
+function moveLabel(result) {
+  const named = result.from?.getAttribute?.('sortable-label') || result.to?.getAttribute?.('sortable-label')
+  return named || 'Move'
+}
+
+// The press: what a drag started with, before the vendor touched anything.
+export function beginMove(item) {
+  const from = item?.parentElement
+  if (!item || !from) return null
+  const start = {
+    item,
+    from,
+    children: [...from.children],
+    next: item.nextSibling,
+    previous: item.previousSibling,
+    nodes: new Set([item, ...item.querySelectorAll('*')]),
+    held: false,
+  }
+  open.add(start)
+  return start
+}
+
+// A runtime attribute of the item a gesture holds: the vendor's own bookkeeping, which
+// a mere click would otherwise write into the file and into history.
+export function isRuntimeAttribute(name, target) {
+  if (!RUNTIME_ATTRS.has(name)) return false
+  for (const start of open) if (start.nodes.has(target)) return true
+  return false
+}
+
+// The item a gesture holds: the vendor moves it many times during dragover or
+// touchmove, and none of those moves is an edit; the one semantic move is recorded
+// at the end.
+export function isGestureItem(node) {
+  for (const start of open) if (start.item === node) return true
+  return false
+}
+
+// The engine's own exclusion bracket, opened before the gesture's final writes and
+// closed right after its one entry: those writes reach neither the idle batch nor a
+// command's capture. Reference-counted by the engine, so a release that arrives twice
+// is harmless.
+export function holdMove(start) {
+  const undo = engine()
+  if (!start || start.held || !undo?.pause) return false
+  undo.pause()
+  start.held = true
+  return true
+}
+
+export function releaseMove(start) {
+  if (!start) return
+  open.delete(start)
+  if (!start.held) return
+  start.held = false
+  engine()?.resume?.()
+}
+
+export function releaseAllMoves() {
+  for (const start of [...open]) releaseMove(start)
+}
+
+// Something outside this gesture changed the source list, or took the item away. The
+// start coordinates describe a list that is no longer there, so nothing is recorded:
+// the card stays where the merged document put it, undo does not claim it, and the
+// page is told why.
+function drifted(start, result) {
+  if (!start.item.isConnected || start.item.parentElement !== result.to) return true
+  const before = start.children.filter((node) => node !== start.item)
+  const after = [...start.from.children].filter((node) => node !== start.item)
+  return !sameNodes(before, after)
+}
+
+// The drop left the card in the slot it started in: not a move, not an event, not an
+// entry.
+function sameSlot(start, result) {
+  if (result.from !== result.to) return false
+  const now = [...result.to.children]
+  return sameNodes(now, start.children)
+}
+
+function removal(start) {
+  const member = (node) => node && node.parentNode === start.from
+  const next = member(start.next) ? start.next : null
+  return {
+    kind: 'remove',
+    parent: start.from,
+    nodes: [start.item],
+    before: next,
+    afterAuthored: next,
+    beforeAuthored: member(start.previous) ? start.previous : null,
+  }
+}
+
+function addition(result) {
+  return {
+    kind: 'add',
+    parent: result.to,
+    nodes: [result.item],
+    before: result.item.nextSibling,
+    afterAuthored: result.item.nextSibling,
+    beforeAuthored: result.item.previousSibling,
+  }
+}
+
+// Record one completed move from the start slot to the final slot. The runtime
+// attributes are already restored by the time this runs, so no vendor write can reach
+// the entry. Returns the engine's receipt, or null when this move earns no entry.
+export function recordMove(start, result) {
+  if (!start || !result || result.item !== start.item) return null
+  const label = moveLabel(result)
+  if (drifted(start, result)) {
+    document.dispatchEvent(new CustomEvent('clay:undo-unavailable', {
+      detail: { label, code: 'conflicted' },
+    }))
+    return null
+  }
+  if (sameSlot(start, result)) return null
+  const undo = engine()
+  if (!undo?.command || !undo?.record) return null
+  holdMove(start)
+  return undo.command(label, () => {
+    undo.record(removal(start))
+    undo.record(addition(result))
+  })
+}

package/src/live/local-channel.js

@@ -0,0 +1,61 @@
+// The one BroadcastChannel a document's same-browser tabs share: the durable lane
+// carries the room's frames over it, and the local presence service carries
+// `presence-v1` session frames beside them. This module owns opening the channel,
+// routing a message to the subscribers that asked for its kind, and closing it
+// when the last of them lets go, so neither service opens or closes the other's.
+//
+// The wire version stays the durable lane's 4, and `presence-v1` is an optional
+// message family beside the durable types: a client that does not know it already
+// ignores every type it does not handle.
+
+const VERSION = 4;
+export const PRESENCE_TYPE = "presence-v1";
+
+export function localChannelSupported() {
+  return typeof BroadcastChannel === "function";
+}
+
+/**
+ * A channel handle for one document's tabs. `post` adds the wire version;
+ * `subscribe` reports the messages of one kind ("durable" or "presence") and
+ * returns the release, which closes the channel once it is the last one out.
+ *
+ * @param {string} key
+ */
+export function localChannel(key) {
+  const channel = new BroadcastChannel(key);
+  const listeners = { durable: new Set(), presence: new Set() };
+  let refs = 0;
+
+  channel.onmessage = ({ data }) => {
+    if (!data || data.v !== VERSION || typeof data.type !== "string") return;
+    const set = data.type === PRESENCE_TYPE ? listeners.presence : listeners.durable;
+    for (const listener of [...set]) listener(data);
+  };
+
+  return {
+    key,
+    get open() {
+      return refs > 0;
+    },
+    post(message) {
+      if (!refs) return;
+      channel.postMessage({ v: VERSION, ...message });
+    },
+    subscribe(kind, listener) {
+      const set = kind === "presence" ? listeners.presence : listeners.durable;
+      set.add(listener);
+      refs += 1;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        set.delete(listener);
+        refs -= 1;
+        if (refs > 0) return;
+        channel.onmessage = null;
+        channel.close();
+      };
+    },
+  };
+}