@panphora/clayjs 1.23.0 → 1.24.1

package/src/page/ai-area.js

@@ -0,0 +1,182 @@
+// The area engine: chosen blocks out as a request, a reply back as one undoable
+// transaction. No UI, no transport: a panel sends capture.html and proposes what
+// comes back, then keeps the proposal through keepAreaTransaction.
+import { planAdoption, adoptionTransaction, readBack, recordsOf } from "./adopt.js";
+import { canon, fragmentCleaner, parseArticle, renderModel, resolveIds } from "./projection.js";
+import { blockMap } from "./model.js";
+import { asStep } from "./blocksel.js";
+
+export const AREA_GUIDE = "This element holds blocks from a document editor. Reply with the same outer div. Inside it use p, h1, h2, h3, ul, ol, li, blockquote, pre with code, details with summary, hr, table with thead, tbody, tr, th, td, and the inline tags strong, em, s, u, code, a. You may also keep any tag already in the element. Keep each data-id on the block it belongs to, and give a new block no data-id. An hr with data-clay-keep stands for something you cannot see: keep it where it belongs unless the request says to remove it. Keep each checkbox on a list item unless the request says to remove it. No classes, no style attributes, no scripts.";
+
+const HELD_TYPES = new Set(["image", "file", "chart", "board", "toc", "tool", "preserved"]);
+const REWRITE_TYPES = new Set(["paragraph", "heading", "list_item", "quote", "callout", "code_block", "toggle", "divider", "table"]);
+
+const refused = (code, message) => ({ status: "refused", code, message });
+const body = ({ id, parent, ...rest }) => ({ ...rest, parent: parent ?? null });
+const same = (a, b) => canon(body(a)) === canon(body(b));
+const freshSeed = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+const CARRY_FIELDS = ["owner", "due", "pageIcon", "pageCoverSrc", "pageCoverAlt", "pageCoverX", "pageCoverY"];
+const carryFields = (was, item) => {
+  const out = { ...item };
+  for (const key of CARRY_FIELDS) {
+    if (out[key] === undefined || out[key] === null) {
+      if (was[key] !== undefined) out[key] = was[key];
+    }
+  }
+  return out;
+};
+
+const reconcileColumns = (item, was) => {
+  const used = new Set(item.cols.map((col) => col.id).filter(Boolean));
+  const cols = item.cols.map((col, i) => {
+    if (col.id) return col;
+    const source = was.cols[i];
+    if (!source?.id || used.has(source.id)) return col;
+    used.add(source.id);
+    return { ...col, id: source.id };
+  }).map((col) => {
+    const source = col.id ? was.cols.find((base) => base.id === col.id) : null;
+    if (!source) return col;
+    const out = { ...col };
+    if (out.kind === undefined && source.kind !== undefined) out.kind = source.kind;
+    if (out.width === undefined && source.width !== undefined) out.width = source.width;
+    return out;
+  });
+  return { ...item, cols };
+};
+
+export function captureArea(doc, ids, { dom = document } = {}) {
+  const blocks = blockMap(doc);
+  if (ids.some((id) => blocks[id]?.t === "opaque_block")) return refused("opaque", "This area holds a block this editor cannot rewrite.");
+  const baseItems = readBack(recordsOf(blocks), dom);
+  const wanted = new Set(ids);
+  const span = baseItems.filter((item) => wanted.has(item.id));
+  if (span.length !== ids.length) return refused("not-found", "Some of these blocks are no longer in the document.");
+  const held = new Map();
+  const typeOf = new Map();
+  const model = span.map((item) => {
+    const t = blocks[item.id]?.t ?? item.t;
+    if (!HELD_TYPES.has(t)) return item;
+    held.set(item.id, item);
+    typeOf.set(item.id, t);
+    return { id: item.id, t: "divider", parent: item.parent };
+  });
+  if (span.every((item) => held.has(item.id))) return refused("no-text", "This area holds nothing that can be rewritten.");
+  const template = dom.createElement("template");
+  template.innerHTML = renderModel(model, { clean: fragmentCleaner(dom) });
+  for (const el of template.content.querySelectorAll("hr[data-id]")) {
+    const id = el.getAttribute("data-id");
+    if (!held.has(id)) continue;
+    el.setAttribute("data-clay-keep", typeOf.get(id));
+  }
+  const lo = baseItems.indexOf(span[0]);
+  const hi = baseItems.indexOf(span[span.length - 1]);
+  if (hi - lo + 1 !== span.length) return refused("not-found", "These blocks are not next to each other.");
+  return {
+    status: "ok",
+    capture: {
+      ids: span.map((item) => item.id),
+      blocks,
+      baseItems,
+      before: baseItems.slice(0, lo),
+      span,
+      after: baseItems.slice(hi + 1),
+      parent: span[0].parent ?? null,
+      held,
+      html: `<div data-clay-area>${template.innerHTML}</div>`,
+    },
+  };
+}
+
+export function staleIds(doc, capture, dom = document) {
+  const items = readBack(recordsOf(blockMap(doc)), dom);
+  const now = new Map(items.map((item) => [item.id, item]));
+  const changed = capture.span
+    .filter((item) => !now.has(item.id) || !same(item, now.get(item.id)))
+    .map((item) => item.id);
+  if (changed.length) return changed;
+  const lo = items.findIndex((item) => item.id === capture.ids[0]);
+  const unbroken = capture.ids.every((id, n) => items[lo + n]?.id === id);
+  return unbroken ? [] : [...capture.ids];
+}
+
+export function proposeArea(state, capture, replyHtml, { seed = "", dom = document } = {}) {
+  const stale = staleIds(state.doc, capture, dom);
+  if (stale.length) return refused("stale", "These blocks changed while AI was working, so nothing was changed.");
+
+  const template = dom.createElement("template");
+  template.innerHTML = replyHtml ?? "";
+  const elements = [...template.content.children];
+  const only = elements.length === 1 ? elements[0] : null;
+  const wrapper = only && only.tagName === "DIV" && (only.hasAttribute("data-clay-area") || !only.hasAttribute("data-id")) ? only : null;
+  const article = dom.createElement("article");
+  article.append(...(wrapper ? wrapper.childNodes : template.content.childNodes));
+  let items = parseArticle(article);
+  if (!items.length) return refused("empty", "AI did not write any blocks. Try again.");
+
+  const inside = new Set(capture.ids);
+  items = items.map((item) => (item.id && !inside.has(item.id) ? { ...item, id: null } : item));
+  if (items.some((item) => !(item.id && capture.held.has(item.id)) && !REWRITE_TYPES.has(item.t))) {
+    return refused("active", "AI used formatting this editor cannot put in a document. Try again.");
+  }
+
+  const base = new Map(capture.span.map((item) => [item.id, item]));
+  const used = new Set(items.map((item) => item.id).filter(Boolean));
+  let cursor = 0;
+  const repaired = items.map((item) => {
+    if (item.id) {
+      const at = capture.ids.indexOf(item.id);
+      if (at >= 0) cursor = at + 1;
+      return item;
+    }
+    const id = capture.ids[cursor];
+    const was = id ? base.get(id) : null;
+    if (!id || used.has(id) || !was || was.t !== item.t) return item;
+    used.add(id);
+    cursor++;
+    return { ...item, id };
+  });
+
+  const settled = repaired.map((item) => {
+    const was = item.id ? base.get(item.id) : null;
+    return was?.t === "table" && item.t === "table" && Array.isArray(item.cols) && Array.isArray(was.cols)
+      ? reconcileColumns(item, was)
+      : item;
+  });
+
+  const taken = new Set(capture.baseItems.filter((item) => !base.has(item.id)).map((item) => item.id));
+  let reply = resolveIds(settled, { seed, known: base, taken });
+  for (let attempt = 0; attempt < 4 && reply.some((item) => taken.has(item.id)); attempt++) {
+    reply = resolveIds(settled, { seed: freshSeed(), known: base, taken });
+  }
+  if (reply.some((item) => taken.has(item.id))) return refused("active", "The new blocks from AI could not be added to the document. Try again.");
+  reply = reply.map((item) => (item.id && capture.held.has(item.id) ? { ...capture.held.get(item.id) } : item));
+  reply = reply.map((item) => {
+    const was = item.id ? base.get(item.id) : null;
+    return was && was.t === item.t ? carryFields(was, item) : item;
+  });
+  if (capture.parent !== null) reply = reply.map((item) => (item.parent ? item : { ...item, parent: capture.parent }));
+
+  const plan = planAdoption(capture.blocks, [...capture.before, ...reply, ...capture.after], capture.baseItems);
+  if (!plan) return refused("no-change", "AI did not change anything.");
+  const tr = adoptionTransaction(state, plan);
+  if (!tr) return refused("no-change", "AI did not change anything.");
+  const nodes = new Map();
+  tr.doc.forEach((node) => nodes.set(node.attrs.id, node));
+  return { status: "ready", plan, reply, nodes: reply.map((item) => nodes.get(item.id)).filter(Boolean) };
+}
+
+export function keepAreaTransaction(state, capture, proposal, dom = document) {
+  const stale = staleIds(state.doc, capture, dom);
+  if (stale.length) return { status: "stale", ids: stale };
+  const blocks = recordsOf(blockMap(state.doc));
+  const items = readBack(blocks, dom);
+  const lo = items.findIndex((item) => item.id === capture.ids[0]);
+  if (lo < 0) return { status: "stale", ids: [...capture.ids] };
+  const hi = lo + capture.ids.length - 1;
+  const plan = planAdoption(blocks, [...items.slice(0, lo), ...proposal.reply, ...items.slice(hi + 1)], items);
+  if (!plan) return { status: "stale", ids: [] };
+  const tr = adoptionTransaction(state, plan);
+  if (!tr) return { status: "stale", ids: [] };
+  return { status: "ok", tr: asStep(tr) };
+}

package/src/page/ai-preview.js

@@ -0,0 +1,80 @@
+// The preview of proposed blocks: the chosen blocks hidden, the proposal drawn in their
+// place. Nothing is dispatched into the document, so Discard leaves no trace and Keep is
+// still one transaction away. While a preview is up the editor answers read-only.
+import { state, view as pmView } from "../vendor/prosemirror.vendor.js";
+
+const { Plugin, PluginKey } = state;
+const PREVIEW = "blockeditor-ai-preview";
+
+export const aiPreviewKey = new PluginKey("blockeditor-ai-preview");
+
+// One node decoration per hidden block, and the proposal as a widget at the first of
+// them. Side -1 puts it above the block it stands for, and it takes no part in
+// selection or key handling.
+function decorationsFor(doc, ids, dom) {
+  const wanted = new Set(ids);
+  const decos = [];
+  let first = -1;
+  doc.forEach((node, at) => {
+    if (!wanted.has(node.attrs?.id)) return;
+    if (first < 0) first = at;
+    decos.push(pmView.Decoration.node(at, at + node.nodeSize, { class: "blockeditor-ai-hidden" }));
+  });
+  if (first < 0) return null;
+  decos.push(pmView.Decoration.widget(first, dom, { side: -1, ignoreSelection: true, stopEvent: () => true }));
+  return pmView.DecorationSet.create(doc, decos);
+}
+
+// A proposal that stands for no block of its own: a new tool appears at the bookmark
+// where it will be inserted, and the page around it stays as it is.
+function widgetFor(doc, at, dom) {
+  if (typeof at !== "number" || at < 0 || at > doc.content.size) return null;
+  return pmView.DecorationSet.create(doc, [
+    pmView.Decoration.widget(at, dom, { side: 1, ignoreSelection: true, stopEvent: () => true }),
+  ]);
+}
+
+export function aiPreviewPlugin() {
+  return new Plugin({
+    key: aiPreviewKey,
+    state: {
+      init: () => null,
+      // The set is built from the dispatch that shows it and mapped through every other
+      // transaction, so a peer's edit moves the hidden blocks and the proposal with it.
+      apply(tr, value, prev, next) {
+        const meta = tr.getMeta(PREVIEW);
+        if (meta === undefined) {
+          if (!value) return null;
+          const decorations = value.decorations.map(tr.mapping, tr.doc);
+          return decorations ? { decorations } : null;
+        }
+        if (!meta) return null;
+        const decorations = meta.ids ? decorationsFor(next.doc, meta.ids, meta.dom) : widgetFor(next.doc, meta.at, meta.dom);
+        return decorations ? { decorations } : null;
+      },
+    },
+    props: {
+      decorations: (st) => aiPreviewKey.getState(st)?.decorations ?? null,
+      // Any props.editable answering false makes ProseMirror read-only, which is how
+      // this composes with the boot's own setEditorActive rather than replacing it.
+      editable: (st) => (aiPreviewKey.getState(st) ? false : undefined),
+    },
+  });
+}
+
+export function showPreview(view, { ids, dom }) {
+  if (!view || view.isDestroyed || !ids?.length || !dom) return;
+  view.dispatch(view.state.tr.setMeta(PREVIEW, { ids: [...ids], dom }));
+}
+
+export function showWidget(view, { at, dom }) {
+  if (!view || view.isDestroyed || typeof at !== "number" || !dom) return;
+  view.dispatch(view.state.tr.setMeta(PREVIEW, { at, dom }));
+}
+
+export function clearPreview(view) {
+  if (!view || view.isDestroyed || !previewShown(view.state)) return;
+  view.dispatch(view.state.tr.setMeta(PREVIEW, null));
+}
+
+export const previewShown = (state) => !!aiPreviewKey.getState(state);

package/src/page/ai-surface.js

@@ -0,0 +1,257 @@
+// clay.blockeditor.ai: the page half of "rewrite a chosen area". It builds a target for the
+// chosen blocks, sends their captured HTML as one request, previews the reply over them
+// and keeps it as one undoable transaction. The panel that drives it is ai-edit's.
+import { state, model } from "../vendor/prosemirror.vendor.js";
+import { schema } from "./schema.js";
+import { outline, siblingSpan, touchedBlocks } from "./blocks.js";
+import { currentSpan } from "./blocksel.js";
+import { showPreview, clearPreview } from "./ai-preview.js";
+import { MAX_PAYLOAD_BYTES, contextRefsOf, wantsPage } from "../lib/ai-comment.js";
+import { createToolTargets } from "./ai-tool.js";
+
+const { TextSelection } = state;
+const HELPER = "ai-edit";
+const EDIT_ID = "page area";
+const TOO_LARGE = "This section is too large for AI editing. Select a smaller part.";
+const STALE = "Someone changed this area while AI was working, so nothing was changed.";
+const GONE = "This page is not open for editing any more.";
+const NO_WIRE = "AI editing isn't available on this page right now.";
+
+let requestCounter = 0;
+
+// Every block is a top-level node, so one pass finds any of them.
+function nodeOf(doc, id) {
+  let found = null;
+  doc.forEach((node, at) => { if (node.attrs?.id === id) found = { node, at }; });
+  return found;
+}
+
+const isTool = (doc, id) => {
+  const found = nodeOf(doc, id);
+  return found?.node?.type === schema.nodes.tool;
+};
+
+const idsOf = (ents, lo, hi) => ents.slice(lo, hi + 1).map((e) => e.node.attrs.id).filter(Boolean);
+
+const freshSeed = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+const emptyRect = () => ({ x: 0, y: 0, left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 });
+
+function unionRect(rects) {
+  if (!rects.length) return emptyRect();
+  const left = Math.min(...rects.map((r) => r.left));
+  const top = Math.min(...rects.map((r) => r.top));
+  const right = Math.max(...rects.map((r) => r.right));
+  const bottom = Math.max(...rects.map((r) => r.bottom));
+  return { x: left, y: top, left, top, right, bottom, width: right - left, height: bottom - top };
+}
+
+// A non-empty text selection inside one block says which words the request is about.
+// Its offsets are counted from the start of that block, as the DOM path counts them
+// from the start of its element.
+function quoteIn(st, ents, span) {
+  const sel = st.selection;
+  if (!(sel instanceof TextSelection) || sel.empty) return null;
+  const [a, b] = touchedBlocks(st.doc, sel, ents);
+  if (a !== b || span.lo !== a || span.hi !== a) return null;
+  const block = ents[a];
+  if (sel.from < block.at || sel.to > block.end) return null;
+  const text = st.doc.textBetween(sel.from, sel.to, " ");
+  if (!text.trim()) return null;
+  const start = st.doc.textBetween(block.at + 1, sel.from, " ").length;
+  return { text, start, end: start + text.length };
+}
+
+export function createPageAi({ getView, store = () => null, acceptState } = {}) {
+  const viewNow = () => {
+    const view = getView();
+    return view && !view.isDestroyed ? view : null;
+  };
+
+  const targets = new Map();
+  const tools = createToolTargets({
+    getView: viewNow,
+    store,
+    acceptState,
+  });
+
+  const reviseTarget = (id) => tools.reviseTool(id);
+
+  function areaTarget(ids, { quote = null, label = null } = {}) {
+    for (const [key, cached] of targets) if (!cached.isConnected) targets.delete(key);
+    const cached = targets.get(ids.join(","));
+    if (cached) {
+      cached.quote = quote ?? undefined;
+      return cached;
+    }
+    let capture = null;
+    let proposal = null;
+    const target = {
+      aiTarget: true,
+      label: label ?? (ids.length === 1 ? "This block" : `${ids.length} blocks`),
+      ref: [...ids],
+      get isConnected() {
+        const view = viewNow();
+        return !!view && ids.some((id) => nodeOf(view.state.doc, id));
+      },
+      getBoundingClientRect() {
+        const view = viewNow();
+        if (!view) return emptyRect();
+        const preview = view.dom.querySelector(".blockeditor-ai-preview");
+        if (preview) return preview.getBoundingClientRect();
+        const ends = [target.ref[0], target.ref[target.ref.length - 1]];
+        const rects = ends
+          .map((id) => nodeOf(view.state.doc, id))
+          .map((found) => (found ? view.nodeDOM(found.at) : null))
+          .filter((node) => node && typeof node.getBoundingClientRect === "function")
+          .map((node) => node.getBoundingClientRect());
+        return unionRect(rects);
+      },
+      async start(comment, argument) {
+        const view = viewNow();
+        if (!view) return { status: "refused", code: "gone", message: GONE };
+        // Read here, not imported: a page with exclude=wire must not pull the wire in.
+        const wire = window.clay?.wire;
+        if (!wire) return { status: "refused", code: "no-wire", message: NO_WIRE };
+        // Fetched where a person asks, as the /ai tool client is, so a boot that never
+        // rewrites anything never downloads the area engine.
+        const { captureArea, AREA_GUIDE } = await import("./ai-area.js");
+        const found = captureArea(view.state.doc, target.ref);
+        capture = null;
+        proposal = null;
+        if (found.status !== "ok") return { status: "refused", code: found.code, message: found.message };
+        const quoted = argument ?? target.quote;
+        const payload = {
+          id: "req-" + Date.now().toString(36) + "-" + (++requestCounter),
+          editId: EDIT_ID,
+          tag: "div",
+          elementHTML: found.capture.html,
+          comment: comment + "\n\n" + AREA_GUIDE,
+          contextRefs: contextRefsOf(comment),
+        };
+        if (quoted) {
+          payload.quote = quoted.text;
+          if (Number.isInteger(quoted.start)) payload.selection = { start: quoted.start, end: quoted.end };
+        }
+        if (wantsPage(comment)) payload.page = true;
+        // Refused here, before anything is sent: the envelope would refuse it anyway,
+        // and a refusal the page cannot explain is worse than one it can.
+        if (new Blob([JSON.stringify(payload)]).size > MAX_PAYLOAD_BYTES) {
+          return { status: "refused", code: "too-large", message: TOO_LARGE };
+        }
+        capture = found.capture;
+        return {
+          status: "ok",
+          id: payload.id,
+          send: (hooks = {}) => {
+            let live = true;
+            let handle = null;
+            const done = (async () => {
+              // @page reads the file the host has on disk, so the page is saved first.
+              if (payload.page) await window.clay?.save?.();
+              if (!live) return { state: "cancelled" };
+              handle = wire.send(payload, { helper: HELPER, onStatus: hooks.onStatus });
+              return handle.done;
+            })();
+            return { done, cancel() { live = false; handle?.cancel(); } };
+          },
+        };
+      },
+      async propose(result) {
+        const view = viewNow();
+        if (!view || !capture) return { status: "refused", message: "This area is no longer open for AI editing." };
+        const { proposeArea } = await import("./ai-area.js");
+        const ready = proposeArea(view.state, capture, result?.html ?? "", { seed: freshSeed() });
+        if (ready.status !== "ready") return { status: "refused", message: ready.message };
+        proposal = ready;
+        const dom = view.dom.ownerDocument.createElement("div");
+        dom.className = "blockeditor-ai-preview";
+        const serializer = model.DOMSerializer.fromSchema(schema);
+        dom.appendChild(serializer.serializeFragment(model.Fragment.from(ready.nodes), { document: view.dom.ownerDocument }));
+        showPreview(view, { ids: capture.ids, dom });
+        return { status: "ready" };
+      },
+      async keep() {
+        const view = viewNow();
+        if (!view || !capture || !proposal) return { status: "failed", message: STALE };
+        const { keepAreaTransaction } = await import("./ai-area.js");
+        const result = keepAreaTransaction(view.state, capture, proposal);
+        clearPreview(view);
+        if (result.status !== "ok") return { status: "failed", message: STALE };
+        view.dispatch(result.tr);
+        if (view.dom.isConnected) view.focus();
+        try {
+          await window.clay?.save?.flush?.();
+        } catch {
+          return { status: "failed", message: "Your change is in the document, but saving failed. It will be saved with your next edit." };
+        }
+        return { status: "kept" };
+      },
+      discard() {
+        const view = viewNow();
+        if (!view) return;
+        clearPreview(view);
+        if (view.dom.isConnected) view.focus();
+      },
+    };
+    target.quote = quote ?? undefined;
+    targets.set(ids.join(","), target);
+    return target;
+  }
+
+  return {
+    active: () => !!viewNow(),
+    targetFromSelection() {
+      const view = viewNow();
+      if (!view) return null;
+      const ents = outline(view.state.doc);
+      if (!ents.length) return null;
+      const span = currentSpan(view.state, ents);
+      const ids = idsOf(ents, span.lo, span.hi);
+      if (!ids.length) return null;
+      // One tool block is revised, not rewritten: its menu's Revise and Cmd+J on it
+      // open the same panel on the same target.
+      if (ids.length === 1 && isTool(view.state.doc, ids[0])) return reviseTarget(ids[0]);
+      return areaTarget(ids, { quote: quoteIn(view.state, ents, span) });
+    },
+    targetAt(x, y) {
+      const view = viewNow();
+      if (!view) return null;
+      const hit = view.posAtCoords({ left: x, top: y });
+      if (!hit) return null;
+      const ents = outline(view.state.doc);
+      if (!ents.length) return null;
+      const at = hit.inside >= 0 ? hit.inside : hit.pos;
+      // A tool is one atomic node, so a point on it resolves to the boundary just after
+      // it: the block the person pointed at is the one that ends there.
+      const ends = ents.findIndex((e) => e.node.type === schema.nodes.tool && e.end === at);
+      const index = ends >= 0 ? ends : Math.min(Math.max(view.state.doc.resolve(at).index(0), 0), ents.length - 1);
+      const { lo, hi } = siblingSpan(ents, index, index);
+      const ids = idsOf(ents, lo, hi);
+      if (!ids.length) return null;
+      if (ids.length === 1 && isTool(view.state.doc, ids[0])) return reviseTarget(ids[0]);
+      return areaTarget(ids);
+    },
+    between(a, b) {
+      const view = viewNow();
+      if (!view) return null;
+      const ents = outline(view.state.doc);
+      const indexes = [...(a?.ref ?? []), ...(b?.ref ?? [])]
+        .map((id) => ents.findIndex((e) => e.node.attrs.id === id))
+        .filter((at) => at >= 0);
+      if (!indexes.length) return null;
+      const { lo, hi } = siblingSpan(ents, Math.min(...indexes), Math.max(...indexes));
+      const ids = idsOf(ents, lo, hi);
+      return ids.length ? areaTarget(ids) : null;
+    },
+    wholePage() {
+      const view = viewNow();
+      const ids = view ? outline(view.state.doc).map((e) => e.node.attrs.id).filter(Boolean) : [];
+      return areaTarget(ids, { label: "This page" });
+    },
+    // `/ai` and Revise are targets the same panel drives, with the tool's own request
+    // shape and the tool's own Keep.
+    newTool(remove) { return tools.newTool(remove ?? null); },
+    reviseTool(toolId) { return tools.reviseTool(toolId); },
+  };
+}