@panphora/clayjs 1.15.2 → 1.16.0

package/src/page/format-gate.js

@@ -0,0 +1,179 @@
+// The format gate: the one place a new-format command asks whether the document
+// may use that format yet.
+//
+// R understands floor 1 and sends that capability on every page write, but has
+// no floor-1 command of its own. F's first new-format command calls this gate
+// before it touches content:
+//
+//   const gate = createFormatGate({ host, installed, revision, lane });
+//   const result = await gate.run({ apply: (selection) => command(selection) });
+//
+// Activation adds the canonical marker to an otherwise equivalent capture and
+// nothing else. It is idempotent, it is refused while an admitted page editor
+// could not read floor 1, and a refusal leaves ordinary writing and every
+// unsaved store exactly as they were. The command that asked only applies if the
+// same editor installation and document revision still exist afterwards;
+// otherwise the answer is retryable and the content is untouched.
+//
+// The host seam is deliberately one object, because the floor is read, checked
+// and persisted under one per-document lock:
+//
+//   read()        -> Promise<{ floor, revision }>   the canonical floor as it stands
+//   capabilities()-> Promise<number[]>              admitted page editors' declared capabilities
+//   activate({ floor, capability, revision })
+//                 -> Promise<{ accepted: true, revision, receipt }
+//                          | { accepted: false, code }>
+//
+// `activate` holds the document's admission/write lock while it checks the
+// admitted editors again and persists the marker, so a legacy registration that
+// lands between `capabilities()` and `activate()` is refused rather than missed.
+
+import { PAGE_FORMAT, PAGE_FORMAT_EXTENSION, PAGE_FORMAT_UPGRADE, formatCapability, notePageFormatFloor, pageFormatDecision, pageFormatFloor } from "./format-level.js";
+
+const UPGRADE_MESSAGE = "This document uses a newer page format; update the editor in the other tabs to keep writing";
+
+const upgrade = (required) => ({ status: "upgrade-required", code: PAGE_FORMAT_UPGRADE, required, minimum: required, message: UPGRADE_MESSAGE });
+
+export function createFormatGate({
+  host,
+  capability = PAGE_FORMAT,
+  supported = () => true,
+  installed = () => null,
+  revision = () => null,
+  lane = null,
+} = {}) {
+  if (!host || typeof host.activate !== "function") throw new TypeError("format-gate: a host adapter is required");
+  let floor = 0;
+  let pending = null;
+  let lanePending = false;
+  let disposed = false;
+
+  // The floor this gate knows the document at. A save or a room answer can tell
+  // it, so a gate opened on an already-floor-1 document never asks to activate
+  // again.
+  function note(level) {
+    floor = Math.max(floor, formatCapability(level));
+    notePageFormatFloor(floor);
+    return floor;
+  }
+
+  async function read() {
+    try {
+      const answer = await host.read();
+      note(answer?.floor ?? pageFormatFloor(answer?.html));
+    } catch {}
+    return floor;
+  }
+
+  async function admittance() {
+    try {
+      const admitted = await host.capabilities();
+      return Array.isArray(admitted) ? admitted : [];
+    } catch {
+      return [];
+    }
+  }
+
+  // Whether a floor rise may happen at all: the host must have announced the
+  // format contract, and this runtime must declare the capability it writes with.
+  async function supportedHere() {
+    try {
+      return (await supported()) !== false;
+    } catch {
+      return false;
+    }
+  }
+
+  async function activateNow() {
+    if (disposed) return { status: "disposed", retry: false };
+    if (!(await supportedHere())) return { status: "unsupported-host", code: "page-format-unsupported", extension: PAGE_FORMAT_EXTENSION };
+    await read();
+    if (floor >= PAGE_FORMAT) return { status: "active", floor };
+    const admitted = await admittance();
+    const early = pageFormatDecision({ floor, required: PAGE_FORMAT, capability, admitted });
+    if (!early.ok) return upgrade(early.minimum);
+    const stamp = { revision: revision(), installed: installed() };
+    let answer;
+    try {
+      answer = await host.activate({ floor: PAGE_FORMAT, capability, revision: stamp.revision, installed: stamp.installed });
+    } catch (error) {
+      return { status: "failed", code: "page-format-activation-failed", error, retry: true };
+    }
+    if (!answer || answer.accepted !== true) {
+      if (answer?.code === PAGE_FORMAT_UPGRADE) return upgrade(PAGE_FORMAT);
+      return { status: "failed", code: answer?.code ?? "page-format-activation-failed", retry: true };
+    }
+    if (disposed) {
+      // The save was accepted, so the document is at floor 1 either way; this
+      // tab is gone and must not act on it.
+      note(PAGE_FORMAT);
+      return { status: "disposed", retry: false };
+    }
+    note(PAGE_FORMAT);
+    lanePending = true;
+    await joinLane(answer.receipt ?? null);
+    return { status: "active", floor, receipt: answer.receipt ?? null };
+  }
+
+  // Joining the new lane scope happens after the receipt is accepted, and only
+  // then: an interrupted switch leaves this tab on floor 0's scope with every
+  // store intact and the switch still pending, never a lane it cannot cover.
+  async function joinLane(receipt) {
+    if (!lane || !lanePending) return false;
+    try {
+      const result = await lane.switchTo({ floor: PAGE_FORMAT, receipt });
+      if (result && result.status === "switched") {
+        lanePending = false;
+        return true;
+      }
+    } catch {}
+    return false;
+  }
+
+  function activate() {
+    if (disposed) return Promise.resolve({ status: "disposed", retry: false });
+    if (floor >= PAGE_FORMAT) return joinLane(null).then(() => ({ status: "active", floor }));
+    if (!pending) pending = activateNow().finally(() => { pending = null; });
+    return pending;
+  }
+
+  return {
+    get floor() {
+      return floor;
+    },
+    get disposed() {
+      return disposed;
+    },
+    note,
+    read,
+    // Activation, once: a second caller while one is in flight waits on the
+    // same attempt, and a retry after a failure starts a new one.
+    activate,
+    // A new-format command: capture what it applies to, ask the gate, and apply
+    // only when activation succeeded and nothing moved underneath it.
+    async run(command) {
+      const stamp = { revision: revision(), installed: installed() };
+      const result = await activate();
+      if (result.status !== "active") return result;
+      if (disposed) return { status: "disposed", retry: false };
+      if (revision() !== stamp.revision || installed() !== stamp.installed) {
+        return { status: "retry", code: "format-gate-stale", retry: true };
+      }
+      return { status: "applied", floor, result: await command?.apply?.(stamp) };
+    },
+    // Retry what is still pending: a lane switch whose receipt is in hand, or an
+    // activation that failed on the wire. Unsaved work is never part of this.
+    async retry() {
+      if (disposed) return { status: "disposed", retry: false };
+      if (await joinLane(null)) return { status: "active", floor };
+      return activate();
+    },
+    // Disposal while awaiting the save: the answer is not applied, the lane is
+    // not switched, and the deferred command does not run.
+    dispose() {
+      disposed = true;
+      lanePending = false;
+      return { status: "disposed" };
+    },
+  };
+}

package/src/page/format-level.js

@@ -0,0 +1,157 @@
+// The document format floor: how much of the page format a runtime must know
+// before it may write.
+//
+// The canonical marker is document metadata, outside the unchanged `{v,g,y}`
+// page value:
+//   <meta name="clay-page-format" content="1">
+// Absence means floor 0. A document's floor only ever rises, and every path that
+// writes a page declares the capability it writes with in
+// `X-Clay-Page-Format`. The value is protocol capability, not authorization: the
+// host still applies every permission check.
+//
+// `requiredPageFormat` answers the other direction: what floor does THIS content
+// need? Its registry is frozen at R (floor 1), so it does not shrink back as a
+// later release adds native schema support.
+
+export {
+  PAGE_FORMAT, PAGE_FORMAT_HEADER, PAGE_FORMAT_META, PAGE_FORMAT_EXTENSION, PAGE_FORMAT_UPGRADE,
+  formatCapability, pageFormatFloor, withPageFormatFloor, knownPageFormatFloor, notePageFormatFloor,
+} from "../core/page-format.js";
+import { PAGE_FORMAT, PAGE_FORMAT_UPGRADE, formatCapability } from "../core/page-format.js";
+
+const level = (value) => (Number.isSafeInteger(value) && value > 0 ? value : 0);
+
+// The floor-0 registry, frozen: every block type, mark code and block field R
+// understood when the floor was introduced. Built on first ask, so a client that
+// never checks content for its floor never carries the list.
+const REGISTRY = {
+  types: [
+    "paragraph", "heading", "list_item", "callout", "code_block", "toggle",
+    "divider", "image", "file", "table", "chart", "board", "tool", "preserved",
+  ],
+  marks: ["a", "b", "c", "i", "s"],
+  fields: [
+    "id", "t", "parent", "c", "m", "level", "kind", "indent", "checked", "owner",
+    "due", "lang", "open", "src", "alt", "caption", "width", "align", "name",
+    "size", "mime", "cols", "rows", "sort", "source", "series", "title",
+    "highlight", "columns", "cards", "artifact", "rev", "state", "html", "pos",
+  ],
+};
+let frozen = null;
+
+export function floorZero() {
+  if (!frozen) {
+    frozen = Object.freeze({
+      types: Object.freeze([...REGISTRY.types]),
+      marks: Object.freeze([...REGISTRY.marks]),
+      fields: Object.freeze([...REGISTRY.fields]),
+    });
+  }
+  return frozen;
+}
+
+const CODE = /^[A-Za-z]$/;
+
+// A mark key holds one code per mark, each followed by its attrs as a JSON array
+// when it carries them. Anything this registry has no code for is a newer
+// runtime's: an unfamiliar compact token, or `x` with a named extension.
+function newerMark(key) {
+  if (typeof key !== "string") throw new TypeError("page: a mark key is not a string");
+  if (!key || key[0] === "@") return false;
+  for (let i = 0; i < key.length;) {
+    const code = key[i];
+    if (!CODE.test(code)) throw new SyntaxError(`page: malformed mark key ${key}`);
+    if (!floorZero().marks.includes(code)) return true;
+    i += 1;
+    if (key[i] !== "[") continue;
+    let depth = 0, quoted = false;
+    const start = i;
+    for (; i < key.length; i++) {
+      const ch = key[i];
+      if (quoted) {
+        if (ch === "\\") i++;
+        else if (ch === '"') quoted = false;
+      } else if (ch === '"') quoted = true;
+      else if (ch === "[") depth++;
+      else if (ch === "]" && --depth === 0) { i++; break; }
+    }
+    if (i >= key.length && key[key.length - 1] !== "]") throw new SyntaxError(`page: unterminated attrs in mark key ${key.slice(start)}`);
+  }
+  return false;
+}
+
+const newerRuns = (m) => {
+  if (!Array.isArray(m)) return false;
+  for (const run of m) {
+    if (Array.isArray(run)) {
+      if (run.length === 2 && Number.isInteger(run[0]) && newerMark(run[1])) return true;
+    } else if (newerMark(run)) return true;
+  }
+  return false;
+};
+
+/**
+ * The floor a prospective semantic model needs: 1 when it holds a named
+ * extension mark, an unfamiliar compact token, an unfamiliar block or a block
+ * field the floor-0 registry does not know, 0 otherwise.
+ *
+ * @param {Array<Object>} model - items as projection.js projects them
+ * @returns {number}
+ */
+export function requiredPageFormat(model) {
+  if (!Array.isArray(model)) throw new TypeError("page: requiredPageFormat expects a model");
+  for (const item of model) {
+    if (!item || typeof item !== "object") continue;
+    if (!floorZero().types.includes(item.t)) return PAGE_FORMAT;
+    for (const key of Object.keys(item)) {
+      if (!floorZero().fields.includes(key)) return PAGE_FORMAT;
+    }
+    if (newerRuns(item.m)) return PAGE_FORMAT;
+    if (!Array.isArray(item.rows)) continue;
+    for (const row of item.rows) {
+      for (const cell of Object.values(row?.cells ?? {})) {
+        if (cell && typeof cell === "object" && newerRuns(cell.m)) return PAGE_FORMAT;
+      }
+    }
+  }
+  return 0;
+}
+
+/**
+ * One floor decision for every writer: the client's activation gate and the
+ * room's admission helper ask the same question and get the same answer.
+ *
+ * `floor` is the document's active floor, `required` what the prospective model
+ * needs, `capability` what this writer declares, and `admitted` the capabilities
+ * of the page editors already in the room. A write is refused before any
+ * mutation when this writer is below what the content needs, and a floor rise is
+ * refused while an admitted editor could not read the result.
+ *
+ * @param {Object} input
+ * @param {number} [input.floor]
+ * @param {number} [input.required]
+ * @param {number} [input.capability]
+ * @param {number[]} [input.admitted]
+ * @returns {{ok: boolean, activate: boolean, floor: number, required: number}}
+ */
+export function pageFormatDecision({ floor = 0, required = 0, capability = 0, admitted = [] } = {}) {
+  const active = level(floor);
+  const needs = Math.max(level(required), active);
+  const refuse = (minimum) => ({ ok: false, activate: false, floor: active, required: needs, minimum });
+  if (formatCapability(capability) < needs) return refuse(needs);
+  const activate = needs > active;
+  if (activate && admitted.some((value) => formatCapability(value) < needs)) return refuse(needs);
+  return { ok: true, activate, floor: needs, required: needs };
+}
+
+// What a refused writer is told: which floor the document needs and that its own
+// unsaved work is still its own. Nothing here is a reload.
+export function pageFormatRefusal(required, message = null) {
+  const minimum = level(required) || PAGE_FORMAT;
+  const error = new Error(message ?? `This document uses a newer page format (floor ${minimum}); update the editor to keep writing`);
+  error.name = "PageFormatUpgradeRequired";
+  error.code = PAGE_FORMAT_UPGRADE;
+  error.statusCode = 409;
+  error.minimum = minimum;
+  return error;
+}

package/src/page/highlight-slot.js

@@ -0,0 +1,23 @@
+// The decoration slot code colours go into: code blocks highlight themselves
+// from a separate part, so the editor carries this empty plugin from boot and
+// the highlighter fills it once it loads.
+import { state, view as pmView } from "../vendor/prosemirror.vendor.js";
+
+const { Plugin, PluginKey } = state;
+const { DecorationSet } = pmView;
+
+export const highlightKey = new PluginKey("page-highlight");
+
+export function highlightSlot() {
+  return new Plugin({
+    key: highlightKey,
+    state: {
+      init: () => DecorationSet.empty,
+      apply(tr, set) {
+        const decos = tr.getMeta(highlightKey);
+        return decos ? DecorationSet.create(tr.doc, decos) : set.map(tr.mapping, tr.doc);
+      },
+    },
+    props: { decorations: (st) => highlightKey.getState(st) },
+  });
+}

package/src/page/highlight.js

@@ -5,9 +5,12 @@
 import { state, view as pmView } from "../vendor/prosemirror.vendor.js";
 import { schema } from "./schema.js";
 import { asStep } from "./blocksel.js";
+import { highlightKey, highlightSlot } from "./highlight-slot.js";
 
-const { Plugin, PluginKey } = state;
-const { Decoration, DecorationSet } = pmView;
+const { Plugin } = state;
+const { Decoration } = pmView;
+
+export { highlightKey };
 
 export const LANGS = [
   ["", "Plain text"],
@@ -106,9 +109,6 @@ const styleOf = (t) => {
   return s.join("; ");
 };
 
-export const highlightKey = new PluginKey("page-highlight");
-
-
 const CACHE_SIZE = 200;
 
 // Each pass rebuilds every code block's colours from a cache of token runs keyed
@@ -206,18 +206,32 @@ class Highlighter {
   }
 }
 
-export function highlightPlugin({ tokenize: run = tokenize, delay = 300 } = {}) {
+// The highlighter is no longer a plugin view, so nothing calls its update: it
+// watches the editor's own dispatches and stops watching when it is destroyed.
+export function startHighlighter(view, { tokenize: run = tokenize, delay = 300 } = {}) {
+  const highlighter = new Highlighter(view, run, delay);
+  const dispatch = view.dispatch.bind(view);
+  let doc = view.state.doc;
+  const wrapped = (tr) => {
+    dispatch(tr);
+    if (view.state.doc === doc) return;
+    const prev = { doc };
+    doc = view.state.doc;
+    highlighter.update(view, prev);
+  };
+  view.dispatch = wrapped;
+  const stop = highlighter.destroy.bind(highlighter);
+  highlighter.destroy = () => {
+    if (view.dispatch === wrapped) view.dispatch = dispatch;
+    stop();
+  };
+  return highlighter;
+}
+
+export function highlightPlugin(options) {
   return new Plugin({
-    key: highlightKey,
-    state: {
-      init: () => DecorationSet.empty,
-      apply(tr, set) {
-        const decos = tr.getMeta(highlightKey);
-        return decos ? DecorationSet.create(tr.doc, decos) : set.map(tr.mapping, tr.doc);
-      },
-    },
-    props: { decorations: (st) => highlightKey.getState(st) },
-    view: (view) => new Highlighter(view, run, delay),
+    ...highlightSlot().spec,
+    view: (view) => startHighlighter(view, options),
   });
 }
 

package/src/page/history-intent.js

@@ -0,0 +1,78 @@
+// Typing joins one undo item the way it does in other editors: Mod-z removes the last
+// word typed, not the last letter. Only the editor's own input path marks a
+// transaction; a command or a programmatic dispatch stays one undo item by itself.
+import { state } from "../vendor/prosemirror.vendor.js";
+import { STEP } from "./blocks.js";
+
+export const HISTORY_INTENT = "page-history-intent";
+export const GROUP_MS = 500;
+
+const blockIdAt = (doc, pos) => {
+  const $pos = doc.resolve(pos);
+  return $pos.depth ? $pos.node(1).attrs.id : null;
+};
+
+const markKey = (st) => (st.storedMarks ?? st.selection.$from.marks()).map((m) => `${m.type.name}:${JSON.stringify(m.attrs)}`).sort().join(",");
+
+export function typingIntent(st, from, to, text) {
+  return { kind: "insert", blockId: blockIdAt(st.doc, from), from, end: from + text.length, replaced: from !== to, text, marks: markKey(st), at: Date.now() };
+}
+
+export function continuesGroup(prev, next) {
+  if (!prev || !next || prev.kind !== next.kind) return false;
+  if (next.kind === "compose") return prev.id === next.id;
+  if (prev.blockId !== next.blockId || next.at - prev.at > GROUP_MS) return false;
+  if (next.kind === "insert") return !next.replaced && next.from === prev.end && next.marks === prev.marks && !(/\s$/.test(prev.text) && /^\S/.test(next.text));
+  return next.direction === prev.direction && (next.direction < 0 ? next.to === prev.from : next.from === prev.from);
+}
+
+const DELETES = { deleteContentBackward: -1, deleteContentForward: 1 };
+const pendingDeletes = new WeakMap();
+const PENDING_MS = 1000;
+export const DERIVED = "page-derived";
+
+// A native deletion arrives as a DOM change with no handler, sometimes after a delayed flush
+// (Android waits 20 ms), so the beforeinput that announced it is held with the document it saw
+// and claimed by the next document change, whatever that change turns out to be.
+export function takePendingDelete(view) {
+  const mark = pendingDeletes.get(view) ?? null;
+  pendingDeletes.delete(view);
+  return mark;
+}
+
+export function deletionIntent(tr, mark) {
+  if (!mark || tr.before !== mark.doc || Date.now() - mark.at > PENDING_MS || tr.getMeta(STEP) || tr.steps.length !== 1) return null;
+  const step = tr.steps[0];
+  if (step.slice?.size !== 0 || step.from === step.to) return null;
+  const $from = tr.before.resolve(step.from), $to = tr.before.resolve(step.to);
+  if (!$from.parent.isTextblock || !$from.sameParent($to)) return null;
+  return { kind: "delete", blockId: $from.depth ? $from.node(1).attrs.id : null, direction: mark.direction, from: step.from, to: step.to, at: mark.at };
+}
+
+export function intentOf(transactions, view = null) {
+  const pending = view ? takePendingDelete(view) : null;
+  const primary = transactions.filter((t) => !t.getMeta(DERIVED));
+  if (primary.length !== 1) return null;
+  const tr = primary[0];
+  const composition = tr.getMeta("composition");
+  if (composition != null) return { kind: "compose", id: composition, at: Date.now() };
+  return tr.getMeta(HISTORY_INTENT) ?? deletionIntent(tr, pending);
+}
+
+export function historyIntentPlugin() {
+  return new state.Plugin({
+    props: {
+      handleTextInput(view, from, to, text, deflt) {
+        view.dispatch(deflt().setMeta(HISTORY_INTENT, typingIntent(view.state, from, to, text)));
+        return true;
+      },
+      handleDOMEvents: {
+        beforeinput(view, event) {
+          const direction = DELETES[event.inputType];
+          if (direction) pendingDeletes.set(view, { direction, at: Date.now(), doc: view.state.doc });
+          return false;
+        },
+      },
+    },
+  });
+}

package/src/page/inline.js

@@ -12,7 +12,11 @@
 // "@" and the node's JSON. No mark key starts with "@", so a U+FFFC typed as
 // text stays text. Private-use characters typed as text need nothing here:
 // encodeForMerge (replay.js) gives each one a code of its own.
+// A mark this schema has no type for keeps its token or named descriptor
+// instead of throwing (format-codec.js): the unit's key is written back exactly
+// as it was read.
 import { model } from "../vendor/prosemirror.vendor.js";
+import { descriptors, entriesOf, isOpaque, keyOf, opaqueMark } from "./format-codec.js";
 
 export const ATOM = "";
 export const CODES = { strong: "b", em: "i", strike: "s", code: "c", link: "a" };
@@ -21,6 +25,10 @@ const NAMES = Object.fromEntries(Object.entries(CODES).map(([name, code]) => [co
 export function markKey(marks) {
   let key = "";
   for (const mark of marks) {
+    if (isOpaque(mark)) {
+      key += keyOf(mark.attrs.entries);
+      continue;
+    }
     const code = CODES[mark.type.name];
     if (!code) throw new TypeError(`page: the mark ${mark.type.name} has no key code`);
     key += code;
@@ -30,21 +38,6 @@ export function markKey(marks) {
   return key;
 }
 
-// The end of the JSON array that starts at s[i].
-function arrayEnd(s, i) {
-  let depth = 0, str = false;
-  for (; i < s.length; i++) {
-    const ch = s[i];
-    if (str) {
-      if (ch === "\\") i++;
-      else if (ch === '"') str = false;
-    } else if (ch === '"') str = true;
-    else if (ch === "[") depth++;
-    else if (ch === "]" && --depth === 0) return i + 1;
-  }
-  throw new SyntaxError(`page: unterminated attrs in mark key ${s}`);
-}
-
 const parsed = new WeakMap();
 
 export function marksOf(schema, key) {
@@ -54,19 +47,19 @@ export function marksOf(schema, key) {
   let marks = cache.get(key);
   if (marks) return marks;
   marks = [];
-  for (let i = 0; i < key.length;) {
-    const type = schema.marks[NAMES[key[i]]];
-    if (!type) throw new TypeError(`page: unknown mark code ${key[i]} in ${key}`);
-    i++;
-    let attrs = null;
-    if (key[i] === "[") {
-      const end = arrayEnd(key, i);
-      const values = JSON.parse(key.slice(i, end));
-      attrs = Object.fromEntries(Object.keys(type.attrs).map((name, j) => [name, values[j]]));
-      i = end;
+  const opaque = [];
+  for (const desc of descriptors(key)) {
+    const name = desc.code === undefined ? null : NAMES[desc.code];
+    if (!name) {
+      opaque.push(desc);
+      continue;
     }
+    const type = schema.marks[name];
+    if (!type) throw new TypeError(`page: unknown mark code ${desc.code} in ${key}`);
+    const attrs = desc.attrs ? Object.fromEntries(Object.keys(type.attrs).map((field, j) => [field, desc.attrs[j]])) : null;
     marks = type.create(attrs).addToSet(marks);
   }
+  if (opaque.length) marks = opaqueMark(entriesOf(opaque)).addToSet(marks);
   cache.set(key, marks);
   return marks;
 }