@portone/docx-editor 0.2.1 → 0.3.0

package/dist/schema/attrRoles.js

@@ -2,105 +2,140 @@
 import { NodeType } from "prosemirror-model";
 var NODE_ATTR_ROLES = {
   paragraph: {
-    srcId: "session",
-    pAttrs: "source",
-    pPr: "source",
-    format: "display",
-    styleRun: "display"
+    srcId: { role: "session", class: "identity" },
+    pAttrs: { role: "source", class: "preserved" },
+    pPr: { role: "source", class: "preserved" },
+    format: { role: "display", class: "derived" },
+    styleRun: { role: "display", class: "derived" }
   },
   table: {
-    srcId: "session",
-    tblAttrs: "source",
-    tblPr: "source",
-    tblW: "source",
-    gridCols: "source",
-    format: "display",
-    styleInside: "display",
-    styleCellMargins: "display"
+    srcId: { role: "session", class: "identity" },
+    tblAttrs: { role: "source", class: "preserved" },
+    tblPr: { role: "source", class: "preserved" },
+    tblW: { role: "source", class: "model" },
+    gridCols: { role: "source", class: "model" },
+    // The grid the table had before it was last revised, carried as it arrived
+    gridChange: { role: "source", class: "preserved" },
+    format: { role: "display", class: "derived" },
+    styleInside: { role: "display", class: "derived" },
+    styleCellMargins: { role: "display", class: "derived" }
   },
   tableRow: {
-    trAttrs: "source",
-    tblPrEx: "source",
-    trPr: "source",
-    format: "display"
+    trAttrs: { role: "source", class: "preserved" },
+    tblPrEx: { role: "source", class: "preserved" },
+    trPr: { role: "source", class: "preserved" },
+    format: { role: "display", class: "derived" }
   },
   tableCell: {
-    colspan: "source",
-    rowspan: "source",
+    colspan: { role: "source", class: "model" },
+    rowspan: { role: "source", class: "model" },
     // prosemirror-tables' own attr. Import writes null, the writer never reads it, and the table
     // commands only carry it from one cell to another; a real column resize moves `gridCols`
-    colwidth: "display",
-    tcAttrs: "source",
-    tcPr: "source",
-    tcW: "source",
-    format: "display",
+    colwidth: { role: "display", class: "derived" },
+    tcAttrs: { role: "source", class: "preserved" },
+    tcPr: { role: "source", class: "preserved" },
+    tcW: { role: "source", class: "model" },
+    format: { role: "display", class: "derived" },
     // Read from `sdtPrefix` rather than from the file, but a lock is not a display value: leaving
     // it out of the comparison would let a step that unlocks a cell pass as a re-derivation
-    sdtPrefix: "source",
-    sdtContentsLocked: "source",
-    sdtDeletionLocked: "source"
+    sdtPrefix: { role: "source", class: "preserved" },
+    sdtContentsLocked: { role: "source", class: "derived" },
+    sdtDeletionLocked: { role: "source", class: "derived" }
+  },
+  rawBlock: {
+    xml: { role: "source", class: "preserved" },
+    name: { role: "source", class: "identity" }
+  },
+  docxRaw: {
+    srcId: { role: "session", class: "identity" },
+    name: { role: "session", class: "identity" }
+  },
+  bookmarkBlock: {
+    srcId: { role: "session", class: "identity" },
+    name: { role: "session", class: "identity" }
+  },
+  hardBreak: { brAttrs: { role: "source", class: "preserved" } },
+  image: {
+    // The bytes themselves, as a data URL the editor makes when an image is inserted
+    src: { role: "source", class: "model" },
+    extent: { role: "source", class: "model" },
+    alt: { role: "source", class: "model" },
+    xml: { role: "source", class: "preserved" }
+  },
+  commentStart: {
+    id: { role: "source", class: "identity" },
+    xml: { role: "source", class: "preserved" }
+  },
+  commentEnd: {
+    id: { role: "source", class: "identity" },
+    xml: { role: "source", class: "preserved" }
   },
-  rawBlock: { xml: "source", name: "source" },
-  docxRaw: { srcId: "session", name: "session" },
-  bookmarkBlock: { srcId: "session", name: "session" },
-  hardBreak: { brAttrs: "source" },
-  image: { src: "source", extent: "source", alt: "source", xml: "source" },
-  commentStart: { id: "source", xml: "source" },
-  commentEnd: { id: "source", xml: "source" },
   commentReference: {
-    id: "source",
-    referenceXml: "source",
-    author: "source",
-    authorId: "source",
-    initials: "source",
-    date: "source",
-    text: "source",
-    commentXml: "source",
-    paraId: "source",
-    resolved: "source",
-    extensionXml: "source",
-    replies: "source",
+    id: { role: "source", class: "identity" },
+    referenceXml: { role: "source", class: "preserved" },
+    author: { role: "source", class: "model" },
+    authorId: { role: "source", class: "model" },
+    initials: { role: "source", class: "model" },
+    date: { role: "source", class: "model" },
+    text: { role: "source", class: "model" },
+    commentXml: { role: "source", class: "preserved" },
+    paraId: { role: "source", class: "identity" },
+    resolved: { role: "source", class: "model" },
+    extensionXml: { role: "source", class: "preserved" },
+    replies: { role: "source", class: "model" },
     // Read to decide whether the comment parts are rewritten at all; neither is written
-    imported: "session",
-    threadImported: "session"
+    imported: { role: "session", class: "derived" },
+    threadImported: { role: "session", class: "derived" }
   },
   noteReference: {
-    kind: "source",
-    id: "source",
-    customMarkFollows: "source",
-    referenceXml: "source",
+    kind: { role: "source", class: "model" },
+    id: { role: "source", class: "identity" },
+    customMarkFollows: { role: "source", class: "model" },
+    referenceXml: { role: "source", class: "preserved" },
     // Both come from the notes part as the document was opened, and the writer puts back the
     // reference alone: a note renumbered around an edit is the same reference it was
-    label: "display",
-    text: "display"
+    label: { role: "display", class: "derived" },
+    text: { role: "display", class: "derived" }
   },
-  rawInline: { xml: "source" }
+  rawInline: { xml: { role: "source", class: "preserved" } }
 };
 var MARK_ATTR_ROLES = {
-  run: { rPr: "source", rAttrs: "source", format: "display" },
+  run: {
+    rPr: { role: "source", class: "preserved" },
+    rAttrs: { role: "source", class: "preserved" },
+    format: { role: "display", class: "derived" }
+  },
   sdt: {
-    sdtPrefix: "source",
+    sdtPrefix: { role: "source", class: "preserved" },
     // Counted through the document as it was opened, to tell one control from the next
-    sdtKey: "session",
-    contentsLocked: "source",
-    deletionLocked: "source"
+    sdtKey: { role: "session", class: "identity" },
+    contentsLocked: { role: "source", class: "derived" },
+    deletionLocked: { role: "source", class: "derived" }
   },
-  link: { linkPrefix: "source", href: "source", linkKey: "session" },
-  tab: { tabAttrs: "source" }
+  link: {
+    linkPrefix: { role: "source", class: "preserved" },
+    href: { role: "source", class: "model" },
+    linkKey: { role: "session", class: "identity" }
+  },
+  tab: { tabAttrs: { role: "source", class: "preserved" } }
 };
-function rolesOf(type) {
-  const roles = type instanceof NodeType ? NODE_ATTR_ROLES[type.name] : MARK_ATTR_ROLES[type.name];
-  return roles ?? {};
+function factsOf(type) {
+  const facts = type instanceof NodeType ? NODE_ATTR_ROLES[type.name] : MARK_ATTR_ROLES[type.name];
+  return facts ?? {};
 }
 function attrRole(type, name) {
-  return rolesOf(type)[name] ?? "source";
+  return factsOf(type)[name]?.role ?? "source";
 }
 function displayAttrsOf(type) {
-  return Object.entries(rolesOf(type)).filter(([, role]) => role === "display").map(([name]) => name);
+  return Object.entries(factsOf(type)).filter(([, facts]) => facts.role === "display").map(([name]) => name);
+}
+function attrsOfClass(type, cls) {
+  return Object.entries(factsOf(type)).filter(([, facts]) => facts.class === cls).map(([name]) => name);
 }
 export {
   MARK_ATTR_ROLES,
   NODE_ATTR_ROLES,
   attrRole,
+  attrsOfClass,
   displayAttrsOf
 };

package/dist/schema/displayDerivation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * How a display value gets onto a node: who says what it should be, and why the transaction that
+ * writes it is no edit.
+ *
+ * What a node draws with is worked out from its source and the formatting around it
+ * (`./attrRoles`), and has to be worked out again whenever either moves: the lines of a table's
+ * cells once a row is added, the style values of a paragraph once its own properties change, and
+ * every value at once when the formatting the document is resolved against is replaced. A deriver
+ * says, for the node types it answers for, what the display attrs of one such node should be, and
+ * `deriveDisplay` walks the blocks of a document, asks each owner in turn, and writes one step per
+ * node whose attrs would change. Only the display attrs of what a deriver hands back are read, so
+ * a deriver cannot write a source attr, and the walk is by construction the kind of transaction
+ * `changesOnlyDisplayAttrs` describes.
+ *
+ * The interface stands here, below `docx` and `editor`, so that a module of either can write a
+ * deriver against it. What a deriver resolves against is the caller's own `Context`, which this
+ * module never reads; `editor/plugins/displayDerivation` registers the derivers and runs the walk
+ * after every edit.
+ *
+ * A transaction carrying the `displayOnly` pass goes through the guard list whole (`./guards`),
+ * provided every step of it is judged, off the role table alone, to change display attrs and
+ * nothing else. The pass is a claim rather than a key: a step that rewrites a source attr, a lock
+ * flag among them, or that puts content anywhere, fails the claim, and the transaction is then
+ * judged as any other edit.
+ */
+import { type Attrs, type MarkType, type Node as PMNode, type Schema } from "prosemirror-model";
+import { PluginKey } from "prosemirror-state";
+import { type Step, type Transform } from "prosemirror-transform";
+import type { docxSchema } from "./docxSchema";
+/** The name of a node type of the document schema, which is what a deriver answers for by */
+export type NodeName = typeof docxSchema extends Schema<infer Nodes, string> ? Nodes : never;
+/** The display attrs one node should carry, by the position the node stands at in the document handed to the deriver */
+export interface DisplayAttrs {
+    readonly pos: number;
+    readonly attrs: Attrs;
+    /** Omitted for node attrs. Otherwise updates an existing mark on this inline node. */
+    readonly mark?: {
+        readonly type: MarkType;
+        readonly to: number;
+    };
+}
+/**
+ * What says, for the node types it answers for, what one node's display attrs should be.
+ *
+ * `derive` is asked once per such node, in document order, with the node as the derivers before it
+ * left it. It hands back the display attrs of that node and of any node inside it, each by
+ * position - a table's deriver answers for the cells - or nothing where nothing changes; a source
+ * or session attr among what it hands back is not written. `previous` is the node this one maps
+ * back to in the document before the change, or null when there is none, or when every value is
+ * being worked out again from nothing.
+ */
+export interface DisplayDeriver<Context> {
+    readonly name: string;
+    /**
+     * The block node types this deriver answers for. The walk runs over the blocks and never into
+     * the inline content of a textblock, since it runs after every keystroke, so an inline type
+     * cannot be answered for.
+     */
+    readonly nodeTypes: readonly NodeName[];
+    derive(node: PMNode, pos: number, doc: PMNode, context: Context, previous: PMNode | null): readonly DisplayAttrs[];
+}
+/**
+ * Writes the display attrs the derivers hand back, one `setNodeMarkup` per node whose attrs would
+ * change, onto the transform. It holds no state of its own: what a node maps back to comes from
+ * the caller, who knows what changed.
+ *
+ * Every step keeps the document the same size, so the positions gathered before the first write
+ * still hold, and a deriver asked after another reads the node as that one left it.
+ */
+export declare function deriveDisplay<Context>(transform: Transform, context: Context, derivers: readonly DisplayDeriver<Context>[], previousOf: (node: PMNode, pos: number) => PMNode | null): void;
+/**
+ * The pass a re-derivation carries. A plugin key is used as the name so that it cannot collide
+ * with a consumer's own metadata.
+ */
+export declare const displayOnly: PluginKey<boolean>;
+/**
+ * Whether the step changes display attrs and nothing else, judged off the role table alone.
+ *
+ * Node attrs and existing mark attrs may change only their display fields. Adding a mark where
+ * that type was absent, changing source attrs, and all other step shapes remain edits.
+ */
+export declare function changesOnlyDisplayAttrs(step: Step, doc: PMNode): boolean;

package/dist/schema/displayDerivation.js

@@ -0,0 +1,130 @@
+// src/schema/displayDerivation.ts
+import {
+  Mark
+} from "prosemirror-model";
+import { PluginKey } from "prosemirror-state";
+import {
+  AddMarkStep,
+  AttrStep,
+  ReplaceAroundStep
+} from "prosemirror-transform";
+import { attrRole } from "./attrRoles.js";
+function ownersByType(schema, derivers) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const deriver of derivers) {
+    for (const name of deriver.nodeTypes) {
+      const type = schema.nodes[name];
+      if (type === void 0 || type.isInline) {
+        throw new Error(
+          `${deriver.name} answers for ${name}, which the walk over the blocks never reaches`
+        );
+      }
+      const owning = owners.get(name) ?? [];
+      owning.push(deriver);
+      owners.set(name, owning);
+    }
+  }
+  return owners;
+}
+function displayLaidOver(standing, derived) {
+  const attrs = { ...standing.attrs };
+  for (const [name, value] of Object.entries(derived)) {
+    if (attrRole(standing.type, name) === "display") attrs[name] = value;
+  }
+  return attrs;
+}
+function nodeStanding(doc, pos) {
+  const node = doc.nodeAt(pos);
+  if (node === null) throw new Error(`no node stands at ${pos}`);
+  return node;
+}
+function deriveDisplay(transform, context, derivers, previousOf) {
+  const owners = ownersByType(transform.doc.type.schema, derivers);
+  const spots = [];
+  transform.doc.descendants((node, pos) => {
+    const owning = owners.get(node.type.name);
+    if (owning !== void 0) spots.push({ pos, owners: owning });
+    return !node.isTextblock;
+  });
+  for (const spot of spots) {
+    for (const deriver of spot.owners) {
+      const node = nodeStanding(transform.doc, spot.pos);
+      const derived = deriver.derive(
+        node,
+        spot.pos,
+        transform.doc,
+        context,
+        previousOf(node, spot.pos)
+      );
+      for (const { pos, attrs, mark: target } of derived) {
+        const standing = nodeStanding(transform.doc, pos);
+        if (target !== void 0) {
+          const mark = target.type.isInSet(standing.marks);
+          if (!standing.isInline || mark === void 0) continue;
+          const end = pos + standing.nodeSize - transform.doc.resolve(pos).textOffset;
+          if (target.to <= pos || target.to > end) {
+            throw new Error(
+              "a display mark update must stay within its inline node"
+            );
+          }
+          const next2 = target.type.create(displayLaidOver(mark, attrs));
+          if (!mark.eq(next2)) {
+            transform.step(new AddMarkStep(pos, target.to, next2));
+          }
+          continue;
+        }
+        const next = displayLaidOver(standing, attrs);
+        if (!standing.hasMarkup(standing.type, next, standing.marks)) {
+          transform.setNodeMarkup(pos, null, next);
+        }
+      }
+    }
+  }
+}
+var displayOnly = new PluginKey("docxEditorDisplayOnly");
+function sameOutsideDisplay(type, was, now) {
+  const names = /* @__PURE__ */ new Set([...Object.keys(was), ...Object.keys(now)]);
+  for (const name of names) {
+    if (attrRole(type, name) === "display") continue;
+    if (was[name] !== now[name]) return false;
+  }
+  return true;
+}
+function rewrittenNode(step, doc) {
+  const was = doc.nodeAt(step.from);
+  const now = step.slice.content.firstChild;
+  if (was === null || now === null || step.slice.content.childCount !== 1 || step.slice.openStart !== 0 || step.slice.openEnd !== 0 || now.content.size !== 0 || step.insert !== 1 || step.gapFrom !== step.from + 1 || step.to !== step.from + was.nodeSize || step.gapTo !== step.to - 1) {
+    return null;
+  }
+  return { was, now };
+}
+function changesOnlyDisplayAttrs(step, doc) {
+  if (step instanceof AddMarkStep) {
+    let touched = false;
+    let allowed = true;
+    doc.nodesBetween(step.from, step.to, (node, _pos, parent) => {
+      if (!node.isInline) return true;
+      if (!parent?.type.allowsMarkType(step.mark.type)) return false;
+      touched = true;
+      const previous = step.mark.type.isInSet(node.marks);
+      if (!previous || !sameOutsideDisplay(step.mark.type, previous.attrs, step.mark.attrs))
+        allowed = false;
+      return false;
+    });
+    return touched && allowed;
+  }
+  if (step instanceof AttrStep) {
+    const node = doc.nodeAt(step.pos);
+    return node !== null && attrRole(node.type, step.attr) === "display";
+  }
+  if (!(step instanceof ReplaceAroundStep)) return false;
+  const rewritten = rewrittenNode(step, doc);
+  if (rewritten === null) return false;
+  const { was, now } = rewritten;
+  return was.type === now.type && Mark.sameSet(was.marks, now.marks) && sameOutsideDisplay(was.type, was.attrs, now.attrs);
+}
+export {
+  changesOnlyDisplayAttrs,
+  deriveDisplay,
+  displayOnly
+};

package/dist/schema/docxSchema.d.ts

@@ -7,6 +7,9 @@
  * goes back out as the XML it arrived as. Which of the two a block is decides how it is written
  * (`docx/serializeBlock`) and how a submitted file is compared against the original
  * (`docx/storyProjection`), so a new block node has to name one of them.
+ *
+ * `./attrRoles` declares each attr's provenance and comparison role; `attrClasses.test.ts`
+ * checks coverage. The plugin guide defines the supported public surface.
  */
 import { Schema } from "prosemirror-model";
 export { imageNodeSpec, runMarkSpec } from "./rendering";

package/dist/schema/docxSchema.js

@@ -69,9 +69,7 @@ function isPageBreak(brAttrs) {
 }
 function srcIdOf(dom) {
   const raw = dom.getAttribute("data-src");
-  if (raw === null) return null;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isNaN(parsed) ? null : parsed;
+  return raw === null || raw === "" ? null : raw;
 }
 function repliesHoldTheirXml(value) {
   if (!Array.isArray(value)) return true;
@@ -126,13 +124,11 @@ var docxSchema = new Schema({
         pAttrs: { default: null },
         /** The whole `<w:pPr>...</w:pPr>` XML. null when there is none */
         pPr: { default: null },
-        /** The display values derived from reading pPr */
+        /** Derived paragraph formatting; see `./attrRoles`. */
         format: { default: null },
         /**
-         * The character formatting the style this paragraph wears lays down, drawn as the
-         * paragraph's own CSS so that text carrying no run of its own inherits it.
-         * It is derived from the style table the same way `format` is, and like `format` it never
-         * goes back into the document.
+         * Derived character formatting drawn on the paragraph so unmarked text inherits it.
+         * Its comparison role and provenance are declared in `./attrRoles`.
          */
         styleRun: { default: null }
       },
@@ -144,7 +140,7 @@ var docxSchema = new Schema({
           {
             class: editorClassNames.paragraph,
             style: paragraphStyle(format, styleRun),
-            "data-src": node.attrs.srcId === null ? void 0 : `${node.attrs.srcId}`,
+            "data-src": text(node.attrs.srcId),
             "data-pattrs": text(node.attrs.pAttrs),
             "data-ppr": text(node.attrs.pPr),
             "data-fmt": formatJson(format),
@@ -195,6 +191,13 @@ var docxSchema = new Schema({
         tblW: { default: null },
         /** The `w:gridCol` widths (dxa) in order */
         gridCols: { default: [] },
+        /**
+         * The whole `<w:tblGridChange>...</w:tblGridChange>` XML, the record of the grid this
+         * table had before it was last revised. Carried as it arrived because the grid around it
+         * is rebuilt from `gridCols`, and CT_TblGrid takes it after the columns however wide
+         * those turn out to be (ECMA-376 Part 1 17.4.48)
+         */
+        gridChange: { default: null },
         format: { default: null },
         /** The lines between cells the table style laid down, so an edit can derive them again */
         styleInside: { default: null },
@@ -208,11 +211,12 @@ var docxSchema = new Schema({
         const attrs = {
           class: editorClassNames.table,
           style: tableStyle(format, width),
-          "data-src": node.attrs.srcId === null ? void 0 : `${node.attrs.srcId}`,
+          "data-src": text(node.attrs.srcId),
           "data-tblattrs": text(node.attrs.tblAttrs),
           "data-tblpr": text(node.attrs.tblPr),
           "data-tblw": formatJson(width),
           "data-cols": numberListText(gridCols),
+          "data-gridchange": text(node.attrs.gridChange),
           "data-fmt": formatJson(format),
           "data-style-inside": formatJson(
             toInsideBorders(node.attrs.styleInside)
@@ -237,13 +241,21 @@ var docxSchema = new Schema({
           getAttrs: (dom) => {
             const tblAttrs = rawXml(dom, "data-tblattrs", ATTRIBUTES);
             const tblPr = rawXml(dom, "data-tblpr", ELEMENT("tblPr"));
-            if (tblAttrs === false || tblPr === false) return false;
+            const gridChange = rawXml(
+              dom,
+              "data-gridchange",
+              ELEMENT("tblGridChange")
+            );
+            if (tblAttrs === false || tblPr === false || gridChange === false) {
+              return false;
+            }
             return {
               srcId: srcIdOf(dom),
               tblAttrs,
               tblPr,
               tblW: toTableWidth(parseJson(dom.getAttribute("data-tblw"))),
               gridCols: parseNumberList(dom.getAttribute("data-cols")),
+              gridChange,
               format: toTableFormat(parseJson(dom.getAttribute("data-fmt"))),
               styleInside: toInsideBorders(
                 parseJson(dom.getAttribute("data-style-inside"))
@@ -439,7 +451,7 @@ var docxSchema = new Schema({
           "div",
           {
             class: className,
-            "data-src": node.attrs.srcId === null ? "" : `${node.attrs.srcId}`,
+            "data-src": text(node.attrs.srcId) ?? "",
             "data-name": text(node.attrs.name)
           },
           label
@@ -470,7 +482,7 @@ var docxSchema = new Schema({
           "div",
           {
             class: editorClassNames.bookmarkBlock,
-            "data-src": node.attrs.srcId === null ? "" : `${node.attrs.srcId}`,
+            "data-src": text(node.attrs.srcId) ?? "",
             "data-name": text(node.attrs.name),
             hidden: "hidden"
           }
@@ -923,7 +935,7 @@ var docxSchema = new Schema({
       attrs: {
         rPr: { default: null },
         rAttrs: { default: null },
-        /** The display values derived from reading rPr */
+        /** Derived run formatting; see `./attrRoles`. */
         format: { default: null }
       },
       toDOM(mark) {

package/dist/schema/editGuard.d.ts

@@ -46,7 +46,7 @@ export type EditIntent =
  * against the places it puts that guard to the test, and a place naming a guard that no longer
  * stands has to be a mistake the compiler catches rather than an annotation answering for nothing.
  */
-export type EditGuardName = "protection" | "lock" | "bookmark" | "note";
+export type EditGuardName = "protection" | "lock" | "bookmark" | "note" | "section";
 /** What every guard answers, whichever of the two judgements it is written as */
 interface GuardCommon {
     readonly name: EditGuardName;

package/dist/schema/guards.d.ts

@@ -12,14 +12,16 @@
  * `./editGuard` so that a module writing a guard need not read this one, and is handed on from
  * here so that a caller has one door to the whole seam.
  *
- * `editShut` is not yet what every command asks. Only `editor/commands/breakCommands`,
- * `editor/commands/tabCommands` and `editor/insertImage` ask it today; the rest still compose
- * `editsShut` with a lock predicate of their own (`./locks`), and each decides for itself whether
- * a stretch a guard shuts is trimmed out of the edit or refuses the whole of it. Until they move
- * over, a guard added to the list below reaches those commands through `transactionAllowed` alone,
- * which refuses the transaction they built rather than telling them not to build it.
+ * A command decides nothing of its own about any of this. It takes one of the two shapes an edit
+ * comes in - `guardedCommand`, which builds the whole edit and is refused whole, and
+ * `openStretches`, which leaves the shut stretches out and applies to the rest - and both ask the
+ * list below. A guard registered here therefore reaches every command by being registered, rather
+ * than by each command being taught about it.
+ *
+ * `editsShut` (`./protectionState`) stays what it was, the view-level question of whether the body
+ * is open at all, which is a question about the editor rather than about an edit.
  */
-import type { EditorState, Selection, Transaction } from "prosemirror-state";
+import type { Command, EditorState, Selection, Transaction } from "prosemirror-state";
 import { type EditGuard, type EditIntent } from "./editGuard";
 import { type ProtectionState } from "./protection";
 export type { EditGuard, EditGuardName, EditIntent } from "./editGuard";
@@ -47,9 +49,10 @@ export declare const EDIT_GUARDS: readonly EditGuard[];
  * decision stands apart from it and every caller building an edit asks this rather than handing
  * the transaction to a state.
  *
- * The whole-change judgements come first and take no pass, since a pass lifts one guard's reading
- * of a step rather than another guard's reading of the change. What is left is judged step by
- * step, each step over the document it was built against.
+ * A re-derivation of display values is no edit and is let through before any guard is asked. The
+ * whole-change judgements then come first and take no pass, since a pass lifts one guard's
+ * reading of a step rather than another guard's reading of the change. What is left is judged
+ * step by step, each step over the document it was built against.
  */
 export declare function transactionAllowed(tr: Transaction, state: EditorState): boolean;
 /**
@@ -59,10 +62,30 @@ export declare function transactionAllowed(tr: Transaction, state: EditorState):
  * being refused by the guard draws a live control that swallows the click.
  */
 export declare function editShut(state: EditorState, intent: EditIntent): boolean;
+/** What a command doing this to whatever is selected means to do, one intent per selected stretch */
+export declare function selectionIntents(selection: Selection, kind: "mark" | "replace"): EditIntent[];
 /**
- * What a command doing this to whatever is selected means to do, one intent per selected stretch.
+ * Build, guard, dispatch: the one shape of a command that is refused whole.
  *
- * A stretch of no length holds nothing to mark or to put away, so whatever the command would do to
- * a stretch it is an insertion there.
+ * A structural edit has no smaller piece to fall back on - half a row cannot be deleted, and half a
+ * block of cells cannot be merged into one - so the whole transaction is built, handed to the whole
+ * guard list, and dispatched only if it comes back allowed. A character or a paragraph edit does
+ * the opposite and leaves the shut stretches out (`openStretches`).
+ *
+ * The answer is the same whether or not `dispatch` was passed. The transaction is built before
+ * either way, so asking the guard costs nothing more, and a command reporting one thing to a button
+ * and doing another would be worse than the button being wrong.
  */
-export declare function selectionIntents(selection: Selection, kind: "mark" | "replace"): EditIntent[];
+export declare function guardedCommand(build: (state: EditorState) => Transaction | null): Command;
+/**
+ * The stretches the guards leave open, which is the one shape of a command that is trimmed.
+ *
+ * A shut stretch is left out rather than the whole edit refused: a guard turns down the whole
+ * transaction, so asking for the shut stretch as well would leave the rest of the selection
+ * unedited too. A selection the guards leave nothing of edits nothing, and the command reports that
+ * of its own accord, which is the disabled state of the control that runs it.
+ */
+export declare function openStretches<S extends {
+    from: number;
+    to: number;
+}>(state: EditorState, stretches: readonly S[], kind: "mark" | "replace"): S[];