@portone/docx-editor 0.2.1 → 0.4.0

package/dist/page/pageDecorations.js

@@ -1,96 +1,31 @@
 // src/page/pageDecorations.ts
-import { Plugin, PluginKey } from "prosemirror-state";
+import {
+  Plugin,
+  PluginKey
+} from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
-import { docxSchema, isPageBreak } from "../schema/index.js";
 import { editorAttributes } from "../styles/classNames.js";
+import { blockKindFor } from "./blockKinds.js";
+import { DEFAULT_BLOCK_KINDS } from "./kinds/index.js";
 var marksKey = new PluginKey("docxPageDecorations");
 function pushStyle(marginTop) {
   return `margin-block-start:${marginTop}px`;
 }
-function spaceStyle(height) {
-  return `display:block;height:${height}px`;
-}
-function isPageBreakNode(node) {
-  return node?.type === docxSchema.nodes.hardBreak && isPageBreak(node.attrs.brAttrs);
-}
-function pageBreaksIn(block, blockPos) {
-  const found = [];
-  if (block.type !== docxSchema.nodes.paragraph) return found;
-  block.forEach((child, offset) => {
-    if (isPageBreakNode(child)) {
-      found.push({ at: blockPos + 1 + offset, size: child.nodeSize });
-    }
-  });
-  return found;
-}
-function breakSpaces(block, blockPos, heights, into) {
-  for (const { at, size } of pageBreaksIn(block, blockPos)) {
-    const height = heights.get(at) ?? 0;
-    into.push(
-      Decoration.inline(at, at + size, {
-        nodeName: "span",
-        style: spaceStyle(height),
-        [editorAttributes.pageBreakSpace]: `${height}`
-      })
-    );
+function cutsByBlock(doc, cuts) {
+  const byBlock = /* @__PURE__ */ new Map();
+  for (const cut of cuts) {
+    const $at = doc.resolve(cut.at);
+    if ($at.depth === 0) continue;
+    const blockPos = $at.before(1);
+    const found = byBlock.get(blockPos);
+    if (found) found.push(cut);
+    else byBlock.set(blockPos, [cut]);
   }
+  return byBlock;
 }
-function spaceMarks(doc, spaces) {
-  return spaces.flatMap((space) => {
-    const block = doc.nodeAt(space.pos);
-    const found = block ? pageBreaksIn(block, space.pos)[space.index] : null;
-    return found ? [{ at: found.at, height: space.height }] : [];
-  });
-}
-function tableSpace(continuation) {
-  const row = document.createElement("tr");
-  row.setAttribute(editorAttributes.tablePageSpace, `${continuation.height}`);
-  row.setAttribute("aria-hidden", "true");
-  row.setAttribute("contenteditable", "false");
-  row.style.height = `${continuation.height}px`;
-  const cell = document.createElement("td");
-  cell.colSpan = continuation.columns;
-  cell.style.height = `${continuation.height}px`;
-  row.append(cell);
-  return row;
-}
-function repeatedHeader(view, rowPos) {
-  const source = view.nodeDOM(rowPos);
-  const row = source instanceof HTMLElement && source.tagName === "TR" ? source.cloneNode(true) : document.createElement("tr");
-  row.setAttribute(editorAttributes.tableRepeatedHeader, "");
-  row.setAttribute("aria-hidden", "true");
-  row.setAttribute("contenteditable", "false");
-  row.removeAttribute("id");
-  row.querySelectorAll("[id]").forEach((element) => {
-    element.removeAttribute("id");
-  });
-  return row;
-}
-function tableContinuationDecorations(continuations, into) {
-  continuations.forEach((continuation) => {
-    into.push(
-      Decoration.widget(continuation.pos, () => tableSpace(continuation), {
-        key: `table-page-space-${continuation.pos}-${continuation.height}-${continuation.columns}`,
-        side: -100
-      })
-    );
-    continuation.headerRows.forEach((rowPos, headerIndex) => {
-      into.push(
-        Decoration.widget(
-          continuation.pos,
-          (view) => repeatedHeader(view, rowPos),
-          {
-            key: `table-repeated-header-${continuation.pos}-${headerIndex}-` + continuation.headerSignature,
-            side: -90 + headerIndex
-          }
-        )
-      );
-    });
-  });
-}
-function decorationsFor(doc, pushes, spaces, tableContinuations) {
+function decorationsFor(doc, kinds, pushes, cuts) {
   const byPos = new Map(pushes.map((push) => [push.pos, push]));
-  const heights = new Map(spaces.map((space) => [space.at, space.height]));
+  const byBlock = cutsByBlock(doc, cuts);
   const decorations = [];
   doc.forEach((node, offset) => {
     const push = byPos.get(offset);
@@ -102,65 +37,63 @@ function decorationsFor(doc, pushes, spaces, tableContinuations) {
         })
       );
     }
-    breakSpaces(node, offset, heights, decorations);
+    blockKindFor(kinds, node).decorate(
+      offset,
+      node,
+      byBlock.get(offset) ?? [],
+      decorations
+    );
   });
-  tableContinuationDecorations(tableContinuations, decorations);
   return DecorationSet.create(doc, decorations);
 }
-function marksFor(doc, pushes, spaces, tableContinuations) {
+function marksFor(doc, kinds, pushes, cuts) {
   return {
+    kinds,
     pushes,
-    spaces,
-    tableContinuations,
-    decorations: decorationsFor(doc, pushes, spaces, tableContinuations)
+    cuts,
+    decorations: decorationsFor(doc, kinds, pushes, cuts)
   };
 }
-function samePushes(a, b) {
-  return a.length === b.length && a.every((push, index) => {
-    const other = b[index];
-    return other !== void 0 && other.pos === push.pos && other.marginTop === push.marginTop;
-  });
-}
-function sameSpaces(a, b) {
-  return a.length === b.length && a.every((space, index) => {
-    const other = b[index];
-    return other !== void 0 && other.at === space.at && other.height === space.height;
-  });
-}
-function sameTableContinuations(a, b) {
-  return a.length === b.length && a.every((continuation, index) => {
-    const other = b[index];
-    return other !== void 0 && other.pos === continuation.pos && other.height === continuation.height && other.columns === continuation.columns && other.headerSignature === continuation.headerSignature && other.headerRows.length === continuation.headerRows.length && other.headerRows.every(
-      (rowPos, rowIndex) => rowPos === continuation.headerRows[rowIndex]
-    );
+function stillCuts(kinds, doc, at) {
+  const $at = doc.resolve(at);
+  if ($at.depth === 0) return false;
+  const block = doc.nodeAt($at.before(1));
+  return block !== null && blockKindFor(kinds, block).holdsCut(doc, at);
+}
+function retainsContent(tr, at, mapped) {
+  const node = tr.before.nodeAt(at);
+  if (!node || node.isLeaf) return false;
+  const content = tr.mapping.mapResult(at + 1, -1);
+  return !content.deletedAcross && content.pos === mapped + 1;
+}
+function samePageMarks(a, b) {
+  return a.pushes.length === b.pushes.length && a.cuts.length === b.cuts.length && a.pushes.every((push, index) => {
+    const other = b.pushes[index];
+    return other !== void 0 && other.pos === push.pos && other.marginTop === push.marginTop && other.push === push.push;
+  }) && a.cuts.every((cut, index) => {
+    const other = b.cuts[index];
+    return other !== void 0 && other.at === cut.at && other.height === cut.height;
   });
 }
-function pageDecorations() {
+function pageDecorations(kinds = DEFAULT_BLOCK_KINDS) {
   return new Plugin({
     key: marksKey,
     state: {
-      init: (_config, state) => marksFor(state.doc, [], [], []),
+      init: (_config, state) => marksFor(state.doc, kinds, [], []),
       apply(tr, value) {
         const next = tr.getMeta(marksKey);
         if (next) return next;
         if (!tr.docChanged) return value;
         return marksFor(
           tr.doc,
+          value.kinds,
           value.pushes.map((push) => ({
             ...push,
             pos: tr.mapping.map(push.pos)
           })),
-          value.spaces.flatMap((space) => {
-            const at = tr.mapping.map(space.at);
-            return isPageBreakNode(tr.doc.nodeAt(at)) ? [{ ...space, at }] : [];
-          }),
-          value.tableContinuations.flatMap((continuation) => {
-            const pos = tr.mapping.map(continuation.pos);
-            if (tr.doc.nodeAt(pos)?.type.spec.tableRole !== "row") return [];
-            const headerRows = continuation.headerRows.map((rowPos) => tr.mapping.map(rowPos)).filter(
-              (rowPos) => tr.doc.nodeAt(rowPos)?.type.spec.tableRole === "row"
-            );
-            return [{ ...continuation, pos, headerRows }];
+          value.cuts.flatMap((cut) => {
+            const mapped = tr.mapping.mapResult(cut.at, 1);
+            return !stillCuts(value.kinds, tr.doc, mapped.pos) || mapped.deleted && !retainsContent(tr, cut.at, mapped.pos) ? [] : [{ ...cut, at: mapped.pos }];
           })
         );
       }
@@ -170,43 +103,28 @@ function pageDecorations() {
     }
   });
 }
+function blockKindsOf(state) {
+  return marksKey.getState(state)?.kinds ?? DEFAULT_BLOCK_KINDS;
+}
 function current(view) {
-  return marksKey.getState(view.state) ?? marksFor(view.state.doc, [], [], []);
+  return marksKey.getState(view.state) ?? { pushes: [], cuts: [] };
 }
-function dispatch(view, next) {
+function setPageMarks(view, next) {
+  if (samePageMarks(current(view), next)) return;
   view.dispatch(
-    view.state.tr.setMeta(marksKey, next).setMeta("addToHistory", false)
-  );
-}
-function setPagePushes(view, pushes) {
-  const marks = current(view);
-  if (samePushes(marks.pushes, pushes)) return;
-  dispatch(
-    view,
-    marksFor(view.state.doc, pushes, marks.spaces, marks.tableContinuations)
-  );
-}
-function setPageBreakSpaces(view, spaces) {
-  const marks = current(view);
-  const next = spaceMarks(view.state.doc, spaces);
-  if (sameSpaces(marks.spaces, next)) return;
-  dispatch(
-    view,
-    marksFor(view.state.doc, marks.pushes, next, marks.tableContinuations)
-  );
-}
-function setTableContinuations(view, continuations) {
-  const marks = current(view);
-  if (sameTableContinuations(marks.tableContinuations, continuations)) return;
-  dispatch(
-    view,
-    marksFor(view.state.doc, marks.pushes, marks.spaces, continuations)
+    view.state.tr.setMeta(
+      marksKey,
+      marksFor(
+        view.state.doc,
+        blockKindsOf(view.state),
+        next.pushes,
+        next.cuts
+      )
+    ).setMeta("addToHistory", false)
   );
 }
 export {
-  pageBreaksIn,
+  blockKindsOf,
   pageDecorations,
-  setPageBreakSpaces,
-  setPagePushes,
-  setTableContinuations
+  setPageMarks
 };

package/dist/page/pageLayout.d.ts

@@ -47,14 +47,6 @@ export declare const A4_PAGE_PIXELS: PagePixels;
  * moment before a document is opened.
  */
 export declare function pageGeometryStyle(page: PagePixels): string;
-/** The space opened up at one page break, so that what follows it starts the next page */
-export interface BreakSpace {
-    /** The position where the block holding the break starts */
-    pos: number;
-    /** Which break inside that block, counted in document order */
-    index: number;
-    height: number;
-}
 /** One block to be moved down to the next page */
 export interface BlockPush {
     pos: number;
@@ -63,17 +55,6 @@ export interface BlockPush {
     /** Of that, the extra amount pushed for the page's sake */
     push: number;
 }
-/** A display-only row inserted before the row that continues on the next page */
-export interface TableContinuation {
-    /** The position of the first original row on the next page */
-    pos: number;
-    /** Space from the previous page's row boundary to the next page body */
-    height: number;
-    /** Header rows to project immediately after the space */
-    headerRows: readonly number[];
-    headerSignature: string;
-    columns: number;
-}
 /** A place where one page parts from the next */
 export interface PageSplit {
     /** Where the previous page's body ends, measured from the top of the body */
@@ -82,11 +63,6 @@ export interface PageSplit {
     page: number;
     /** Whether the document records a break at this place */
     forced: boolean;
-    /**
-     * Whether every place before this one was recorded by the document, so the number can
-     * be trusted
-     */
-    exactPage: boolean;
     /**
      * Whether the block is taller than one page, so it cannot be pushed and the text
      * crosses this place
@@ -98,11 +74,6 @@ export interface PageStart {
     page: number;
     /** Where this page's body starts, measured from the top of the body */
     bodyStart: number;
-    /**
-     * Whether every place before this one was recorded by the document, so the number can
-     * be trusted
-     */
-    exactPage: boolean;
     /**
      * Whether text crosses over from the previous page, so this page continues with no top
      * margin
@@ -137,5 +108,7 @@ export interface PageLayoutInput {
  * written into the text - is filled out to the end of the page it falls on, which carries the rest
  * of that block to the top of the next page while the block itself stays whole. An optional one -
  * a row boundary in a table - is taken only where the piece after it would run off the page.
+ * A block kept with the next one is pushed together with what it is kept with: the blocks kept
+ * after it and the first piece of the block the keeps end at.
  */
 export declare function pageLayout({ blocks, pageBodyHeight, pageStep, }: PageLayoutInput): PageLayout;

package/dist/page/pageLayout.js

@@ -41,6 +41,34 @@ var TOLERANCE_PX = 0.5;
 function round(value) {
   return Math.round(value * 100) / 100;
 }
+function keepsWithNext(block, next) {
+  return block.keepWithNext && block.candidates.length === 0 && !block.breakAfter && !next.breakBefore;
+}
+function keptExtents(blocks, fitsPage) {
+  const extents = /* @__PURE__ */ new Map();
+  let run = [];
+  const settle = () => {
+    const head = run.at(-1);
+    if (head && fitsPage(head.extent)) {
+      for (const { index, extent } of run) {
+        extents.set(index, extent);
+      }
+    }
+    run = [];
+  };
+  for (let index = blocks.length - 2; index >= 0; index -= 1) {
+    const block = blocks[index];
+    const next = blocks[index + 1];
+    if (block && next && keepsWithNext(block, next)) {
+      const below = run.at(-1)?.extent ?? next.minFirstPiece;
+      run.push({ index, extent: block.height + next.gap + below });
+    } else {
+      settle();
+    }
+  }
+  settle();
+  return extents;
+}
 function pageLayout({
   blocks,
   pageBodyHeight,
@@ -49,39 +77,34 @@ function pageLayout({
   const pushes = [];
   const cuts = [];
   const splits = [];
-  const firstPage = {
-    page: 1,
-    bodyStart: 0,
-    exactPage: true,
-    crossed: false
-  };
+  const firstPage = { page: 1, bodyStart: 0, crossed: false };
   const pages = [firstPage];
   if (!(pageBodyHeight > 0)) {
     return { pushes, cuts, splits, pages, bodyHeight: 0 };
   }
   let pageStart = 0;
   let cursor = 0;
-  let exactPage = true;
   const split = (y, crossed, forced) => {
-    if (!forced) exactPage = false;
     const page = splits.length + 2;
-    splits.push({ y: round(y), page, forced, exactPage, crossed });
+    splits.push({ y: round(y), page, forced, crossed });
     pageStart = crossed ? y : y + pageStep;
-    pages.push({ page, bodyStart: round(pageStart), exactPage, crossed });
+    pages.push({ page, bodyStart: round(pageStart), crossed });
   };
   const crossTo = (y) => {
     while (y > pageStart + pageBodyHeight + TOLERANCE_PX) {
       split(pageStart + pageBodyHeight, true, false);
     }
   };
+  const fitsPage = (extent) => extent <= pageBodyHeight + TOLERANCE_PX;
+  const kept = keptExtents(blocks, fitsPage);
   let breakAfterPrevious = false;
-  for (const block of blocks) {
+  for (const [index, block] of blocks.entries()) {
     const pageEnd = pageStart + pageBodyHeight;
     const top = cursor + block.gap;
     const startsPage = (block.breakBefore || breakAfterPrevious) && top > pageStart + TOLERANCE_PX;
-    const first = block.minFirstPiece;
+    const first = kept.get(index) ?? block.minFirstPiece;
     const overflows = top + first > pageEnd + TOLERANCE_PX;
-    const fits = first <= pageBodyHeight + TOLERANCE_PX;
+    const fits = fitsPage(first);
     const push = startsPage || overflows && fits ? Math.max(0, pageEnd + pageStep - top) : 0;
     if (push > 0 || startsPage) split(pageEnd, false, startsPage);
     if (push > 0) {
@@ -94,9 +117,9 @@ function pageLayout({
     const contentTop = top + push;
     let added = 0;
     let pieceStart = 0;
-    for (let index = 0; index <= block.candidates.length; index += 1) {
-      const cut = index === 0 ? null : block.candidates[index - 1];
-      const pieceEnd = block.candidates[index]?.offset ?? block.height;
+    for (let index2 = 0; index2 <= block.candidates.length; index2 += 1) {
+      const cut = index2 === 0 ? null : block.candidates[index2 - 1];
+      const pieceEnd = block.candidates[index2]?.offset ?? block.height;
       const pieceTop = contentTop + pieceStart + added;
       let pieceBottom = contentTop + pieceEnd + added;
       if (cut) {

package/dist/page/usePageLayout.d.ts

@@ -3,18 +3,14 @@
  * page-boundary positions over to the view. It remeasures whenever the text changes or the
  * box is resized.
  *
- * A measurement hands new pushes and break spaces to the view (`./pageDecorations`), which is a
- * decoration transaction against the very paragraph an IME may be composing in, and a composition
+ * A measurement hands its marks to the view (`./pageDecorations`) in one decoration transaction
+ * against the very paragraph an IME may be composing in, and a composition
  * in Japanese or Chinese stays open across a whole clause while the text grows line by line. So no
  * measurement is taken while a composition is open: the frame is taken again until it is over.
  */
-import type { Node as PMNode } from "prosemirror-model";
 import type { EditorView } from "prosemirror-view";
 import { type RefObject } from "react";
 import type { PageGeometry } from "../docx/pageGeometry";
-import type { PageCut } from "./blockKinds";
-import { type TableHeaderProjection } from "./measureBlocks";
-import { type BreakSpace, type TableContinuation } from "./pageLayout";
 /** One place where a page parts from the next. The position is measured on the sheet */
 export interface PageMark {
     page: number;
@@ -23,12 +19,6 @@ export interface PageMark {
     height: number;
     crossed: boolean;
 }
-/** The number laid on the corner of a page */
-export interface PageBadge {
-    page: number;
-    top: number;
-    exactPage: boolean;
-}
 /** The paper area of one visual page, used to place its header and footer stories. */
 export interface PageFace {
     page: number;
@@ -45,7 +35,6 @@ export interface PageOverlay {
     /** The sheet height with the last page filled out in full */
     sheetHeight: number;
     marks: PageMark[];
-    badges: PageBadge[];
     pages: PageFace[];
 }
 interface PageLayoutOptions {
@@ -57,16 +46,5 @@ interface PageLayoutOptions {
     /** The paper the open document names. A4 where a document names none */
     geometry?: PageGeometry;
 }
-/**
- * The layout's cuts as the two kinds of mark the decorations still take.
- *
- * A cut names the position the continued piece starts at, and which of the two it is follows from
- * what stands there: a page `br` the block it sits in counted, or a table row. This stands in
- * until the decorations take the cuts themselves.
- */
-export declare function cutsToLegacyMarks(cuts: readonly PageCut[], tables: ReadonlyMap<number, TableHeaderProjection>, doc: PMNode): {
-    spaces: BreakSpace[];
-    tableContinuations: TableContinuation[];
-};
 export declare function usePageLayout({ view, layer, enabled, revision, geometry, }: PageLayoutOptions): PageOverlay | null;
 export {};

package/dist/page/usePageLayout.js

@@ -8,19 +8,13 @@ import {
 } from "react";
 import { editorCssVariables } from "../styles/classNames.js";
 import { measureSheet } from "./measureBlocks.js";
-import {
-  pageBreaksIn,
-  setPageBreakSpaces,
-  setPagePushes,
-  setTableContinuations
-} from "./pageDecorations.js";
+import { setPageMarks } from "./pageDecorations.js";
 import {
   A4_PAGE_PIXELS,
   PAGE_SPLIT_PX,
   pageLayout,
   pagePixels
 } from "./pageLayout.js";
-var BADGE_INSET_PX = 8;
 function useFrameThrottle(run, hold) {
   const latest = useRef({ run, hold });
   const frame = useRef(0);
@@ -51,28 +45,7 @@ function useFrameThrottle(run, hold) {
   }, []);
 }
 function sameOverlay(a, b) {
-  return a !== null && a.left === b.left && a.top === b.top && a.width === b.width && a.sheetHeight === b.sheetHeight && JSON.stringify(a.marks) === JSON.stringify(b.marks) && JSON.stringify(a.badges) === JSON.stringify(b.badges) && JSON.stringify(a.pages) === JSON.stringify(b.pages);
-}
-function cutsToLegacyMarks(cuts, tables, doc) {
-  const spaces = [];
-  const tableContinuations = [];
-  for (const cut of cuts) {
-    const pos = doc.resolve(cut.at).before(1);
-    const block = doc.nodeAt(pos);
-    if (!block) continue;
-    const index = pageBreaksIn(block, pos).findIndex(
-      (found) => found.at === cut.at
-    );
-    if (index >= 0) {
-      spaces.push({ pos, index, height: cut.height });
-      continue;
-    }
-    const headers = tables.get(pos);
-    if (headers) {
-      tableContinuations.push({ pos: cut.at, height: cut.height, ...headers });
-    }
-  }
-  return { spaces, tableContinuations };
+  return a !== null && a.left === b.left && a.top === b.top && a.width === b.width && a.sheetHeight === b.sheetHeight && JSON.stringify(a.marks) === JSON.stringify(b.marks) && JSON.stringify(a.pages) === JSON.stringify(b.pages);
 }
 function usePageLayout({
   view,
@@ -96,14 +69,7 @@ function usePageLayout({
         pageBodyHeight: page.bodyHeight,
         pageStep: page.pageStep
       });
-      const marks = cutsToLegacyMarks(
-        layout.cuts,
-        measured.tables,
-        view.state.doc
-      );
-      setPagePushes(view, layout.pushes);
-      setPageBreakSpaces(view, marks.spaces);
-      setTableContinuations(view, marks.tableContinuations);
+      setPageMarks(view, { pushes: layout.pushes, cuts: layout.cuts });
       const sheetHeight = measured.contentTop + layout.bodyHeight + measured.contentBottom;
       box.style.setProperty(editorCssVariables.sheetHeight, `${sheetHeight}px`);
       const next = {
@@ -117,13 +83,7 @@ function usePageLayout({
           height: split.crossed ? 0 : PAGE_SPLIT_PX,
           crossed: split.crossed
         })),
-        // The number is laid on the page's top corner. A page crossed into has no margin,
-        // so the place it was split at is its corner
-        badges: layout.pages.map((start) => ({
-          page: start.page,
-          top: measured.contentTop + start.bodyStart - (start.crossed ? 0 : page.marginTop) + BADGE_INSET_PX,
-          exactPage: start.exactPage
-        })),
+        // A page crossed into has no margin, so the place it was split at is its top corner
         pages: layout.pages.map((start) => {
           const paperTop = measured.contentTop + start.bodyStart - (start.crossed ? 0 : page.marginTop);
           return {
@@ -147,9 +107,7 @@ function usePageLayout({
     if (enabled) return;
     layer.current?.style.removeProperty(editorCssVariables.sheetHeight);
     if (!view) return;
-    setPagePushes(view, []);
-    setPageBreakSpaces(view, []);
-    setTableContinuations(view, []);
+    setPageMarks(view, { pushes: [], cuts: [] });
   }, [enabled, layer, view]);
   useEffect(() => {
     const box = layer.current;
@@ -164,6 +122,5 @@ function usePageLayout({
   return enabled ? overlay : null;
 }
 export {
-  cutsToLegacyMarks,
   usePageLayout
 };

package/dist/schema/attrRoles.d.ts

@@ -1,27 +1,32 @@
 /**
- * What each attr of the schema is for, so that a judgement about a node can say which of them it
- * is judging.
+ * Each attr has two independent classifications. Its role controls source comparison: `source`
+ * values are what the writer writes a block from; `display` values are worked out from the source
+ * and the formatting around it, and are never written into a block's XML (`docx/newLists` reads a
+ * list reference off one to decide what numbering.xml needs); `session` values are what export
+ * reads but neither writes nor derives again - which block, control or link this is, whether a
+ * comment came in with the file, the name of a preserved element. `sourceEquality` compares source
+ * and session values so a display refresh does not rebuild an untouched block.
  *
- * An attr is one of three things. A `source` attr is what the exporter writes from: the XML the
- * file arrived as, or a value the model owns that replaces part of it. A `display` attr is worked
- * out from the source and the formatting around it, is never written, and is free to change the
- * moment the surroundings do. A `session` attr says which block, control or link of the open
- * document this is, and is never written either.
+ * Its class records provenance: `preserved` holds XML, `derived` is calculated from other data,
+ * `identity` identifies content (imported or allocated here), and `model` holds editable values.
+ * Classification alone does not promise a public API; the plugin guide defines that boundary.
  *
- * The split exists because a display value changing is not the document changing. Opening a file
- * in the editor re-derives a table's cell borders (`table/gridBorders`), and a comparison that
- * counted that as an edit would rewrite a table nobody touched, losing the markup the writer does
- * not model. `./sourceEquality` leaves display attrs out for that reason, and keeps session attrs
- * in: two blocks that came from different places in the file are different blocks.
- *
- * `attrRoles.test.ts` holds this table against the schema in both directions, so an attr added
- * without a role fails there before it can reach a judgement that does not know what to do with it.
+ * Lock flags are derived from control XML but have the source role: ignoring them in a comparison
+ * would let an unlock pass as a display refresh. The imported flags are derived with the session
+ * role because export reads them to decide whether to rewrite comment parts.
+ * Both columns are checked against the schema by the adjacent tests.
  */
 import { type MarkType, NodeType } from "prosemirror-model";
 export type AttrRole = "source" | "display" | "session";
-type AttrRoles = Readonly<Record<string, Readonly<Record<string, AttrRole>>>>;
-export declare const NODE_ATTR_ROLES: AttrRoles;
-export declare const MARK_ATTR_ROLES: AttrRoles;
+export type AttrClass = "preserved" | "derived" | "identity" | "model";
+/** What is declared about one attr: what a comparison does with it, and where its value comes from */
+export type AttrFacts = {
+    readonly role: AttrRole;
+    readonly class: AttrClass;
+};
+type AttrTable = Readonly<Record<string, Readonly<Record<string, AttrFacts>>>>;
+export declare const NODE_ATTR_ROLES: AttrTable;
+export declare const MARK_ATTR_ROLES: AttrTable;
 /**
  * What this attr of this node or mark is for.
  *
@@ -32,4 +37,6 @@ export declare const MARK_ATTR_ROLES: AttrRoles;
 export declare function attrRole(type: NodeType | MarkType, name: string): AttrRole;
 /** The attrs of this node or mark that are worked out rather than written */
 export declare function displayAttrsOf(type: NodeType | MarkType): readonly string[];
+/** The attrs of this node or mark that the given class covers */
+export declare function attrsOfClass(type: NodeType | MarkType, cls: AttrClass): readonly string[];
 export {};