@stll/folio-core 0.52.0 → 0.53.0

package/dist/ai-edits/table-row-column-mutations.d.ts

@@ -1,7 +1,7 @@
 import { TableStructureRevision } from "./table-template.js";
 import { TableRowTarget } from "./table-targets.js";
-import { Transaction } from "prosemirror-state";
 import { Node } from "prosemirror-model";
+import { Transaction } from "prosemirror-state";
 //#region src/ai-edits/table-row-column-mutations.d.ts
 type TableRowInsertion = {
   tableStart: number;
@@ -10,14 +10,13 @@ type TableRowInsertion = {
   cells: readonly Node[];
   rowspanUpdates: readonly number[];
   /**
-   * The table's column count, which is not `cells.length`. One cell can occupy
-   * several columns (a `colspan`), and one column can have no cell in this row
-   * at all (a `rowspan` from a row above reaches down into it).
+   * The table's column count, which is not `cells.length`: a column can have
+   * no cell in this row at all, when a `rowspan` from a row above reaches down
+   * through it. A template row has to span all of it.
    *
-   * It is what `cellTexts` is SIZED against — the most cells any row of this
-   * table could have — while the texts themselves fill the new row's cells in
-   * order. Sizing against `cells.length` refused a row the table can hold
-   * whenever a span made this row narrower than the table.
+   * `cellTexts` is sized against `cells.length` instead, because the nth text
+   * fills the nth cell the row has: a text past the last one has nowhere to
+   * go, and is refused rather than dropped.
    */
   columnCount: number;
 };
@@ -34,6 +33,27 @@ type TableRowColumnMutationResult = {
 } | {
   type: "unsupported";
 };
+type TableColumnInsertionResult = TableRowColumnMutationResult | {
+  type: "payloadDoesNotFit";
+  message: string;
+};
+type DescribeUnplacedCellTextsOptions = {
+  cellTexts: readonly string[] | undefined;
+  /** Cells the new row or column actually has. */
+  capacity: number;
+  target: "row" | "column";
+};
+/**
+ * Name the `cellTexts` a new row or column has no cell for, or `null` when
+ * every one of them has a place.
+ *
+ * A row is narrower than the table where a vertical merge from above reaches
+ * through it, and a column is shorter than the table where a horizontal merge
+ * spans across it; the merged cell takes that slot, so the texts are counted
+ * against the cells that are really built. Anything past the last one would
+ * be dropped by an operation reported as applied.
+ */
+declare const describeUnplacedCellTexts: ({ cellTexts, capacity, target }: DescribeUnplacedCellTextsOptions) => string | null;
 declare const getTableColumnCoordinateKey: ({ tablePosition, columnIndex }: TableColumnInsertion) => string;
 type FindTableColumnInsertionOptions = {
   doc: Node;
@@ -75,12 +95,14 @@ type MarkTableRowContentOptions = {
  * accept and an inserted row's text on reject when the row marker stands
  * alone, so the two must always be written together.
  *
- * Two kinds of run stay unmarked. A run that already carries a revision keeps
- * it, because OOXML nests `w:ins`/`w:del` but the editable model holds one
- * wrapper per run and overwriting would drop the earlier revision. A cell that
- * spans into the row below survives the deletion — `removeRow` moves it down
- * and shortens its span — so marking its text would delete content the
- * accepted document must still hold.
+ * Two kinds of run stay unmarked. A run that already carries a revision of the
+ * same kind keeps it, because overwriting would drop the earlier revision; a
+ * pending insertion inside a deleted row is marked deleted as well (`w:ins >
+ * w:del`), as `deleteBlock` marks one inside a deleted paragraph, so every
+ * reader leaves it out with the rest of the row. A cell that spans into the
+ * row below survives the deletion — `removeTableRow` moves it down and
+ * shortens its span — so marking its text would delete content the accepted
+ * document must still hold.
  */
 declare const markTableRowContent: ({ tr, rowPosition, kind, revision }: MarkTableRowContentOptions) => void;
 type ApplyTableColumnInsertionOptions = {
@@ -89,7 +111,7 @@ type ApplyTableColumnInsertionOptions = {
   cellTexts: readonly string[] | undefined;
   revision: TableStructureRevision | null;
 };
-declare const applyTableColumnInsertion: ({ tr, insertion, cellTexts, revision }: ApplyTableColumnInsertionOptions) => TableRowColumnMutationResult;
+declare const applyTableColumnInsertion: ({ tr, insertion, cellTexts, revision }: ApplyTableColumnInsertionOptions) => TableColumnInsertionResult;
 type ApplyTableColumnDeletionOptions = {
   tr: Transaction;
   deletion: TableColumnDeletion;
@@ -116,4 +138,4 @@ declare const applyTableRowDeletion: ({ tr, deletion, revision }: ApplyTableRowD
  */
 declare const splitCellParagraphTexts: (text: string) => string[];
 //#endregion
-export { MarkTableRowContentOptions, TableColumnDeletion, TableColumnInsertion, TableRowDeletion, TableRowInsertion, applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };
+export { MarkTableRowContentOptions, TableColumnDeletion, TableColumnInsertion, TableRowDeletion, TableRowInsertion, applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, describeUnplacedCellTexts, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };

package/dist/ai-edits/table-row-column-mutations.js

@@ -1,10 +1,27 @@
 import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
-import { reconcileTableGridAfterColumnRemoval } from "../prosemirror/tableGridMutation.js";
+import { reconcileTableGridAfterColumnInsertion, reconcileTableGridAfterColumnRemoval, removeRowsWithoutCells, removeTableRow } from "../prosemirror/tableGridMutation.js";
 import { stripBlockIdentityAttrs } from "./block-identity.js";
 import { findEnclosingTableCell, findEnclosingTableRow } from "./table-targets.js";
 import { tableRowFromTemplate } from "./table-template.js";
-import { TableMap, columnIsHeader, removeColumn, removeRow, rowIsHeader, tableNodeTypes } from "prosemirror-tables";
+import { TableMap, columnIsHeader, removeColumn, rowIsHeader, tableNodeTypes } from "prosemirror-tables";
 //#region src/ai-edits/table-row-column-mutations.ts
+const UNPLACED_TEXT_PREVIEW_LENGTH = 40;
+const previewCellText = (text) => JSON.stringify(text.length > UNPLACED_TEXT_PREVIEW_LENGTH ? `${text.slice(0, UNPLACED_TEXT_PREVIEW_LENGTH)}…` : text);
+/**
+* Name the `cellTexts` a new row or column has no cell for, or `null` when
+* every one of them has a place.
+*
+* A row is narrower than the table where a vertical merge from above reaches
+* through it, and a column is shorter than the table where a horizontal merge
+* spans across it; the merged cell takes that slot, so the texts are counted
+* against the cells that are really built. Anything past the last one would
+* be dropped by an operation reported as applied.
+*/
+const describeUnplacedCellTexts = ({ cellTexts, capacity, target }) => {
+	if (cellTexts === void 0 || cellTexts.length <= capacity) return null;
+	const unplaced = cellTexts.slice(capacity).map((text, offset) => `cellTexts[${capacity + offset}] ${previewCellText(text)}`);
+	return `the new ${target} has ${capacity} cell${capacity === 1 ? "" : "s"} (${target === "row" ? "a merged cell from the row above reaches through the rest" : "a merged cell spans across the rest"}), so ${unplaced.join(", ")} would not be placed`;
+};
 const getTableColumnCoordinateKey = ({ tablePosition, columnIndex }) => `${tablePosition}:${columnIndex}`;
 const findTableColumnInsertion = ({ doc, blockFrom, position }) => {
 	const target = findEnclosingTableCell(doc, blockFrom);
@@ -28,7 +45,6 @@ const findTableRowInsertion = ({ doc, blockFrom, position }) => {
 	});
 };
 const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision, template }) => {
-	if (revision && insertion.rowspanUpdates.length > 0) return { type: "unsupported" };
 	const liveRowspanUpdates = [];
 	for (const updatePosition of insertion.rowspanUpdates) {
 		const cellPosition = insertion.tableStart + updatePosition;
@@ -46,7 +62,7 @@ const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision, template }
 		rowspan: update.rowspan + 1
 	});
 	const rowAttrs = revision ? { trIns: revision } : null;
-	const templated = template === void 0 ? null : tableRowFromTemplate({
+	const templated = template === void 0 || insertion.rowspanUpdates.length > 0 ? null : tableRowFromTemplate({
 		template,
 		columnCount: insertion.columnCount
 	});
@@ -73,12 +89,14 @@ const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision, template }
 * accept and an inserted row's text on reject when the row marker stands
 * alone, so the two must always be written together.
 *
-* Two kinds of run stay unmarked. A run that already carries a revision keeps
-* it, because OOXML nests `w:ins`/`w:del` but the editable model holds one
-* wrapper per run and overwriting would drop the earlier revision. A cell that
-* spans into the row below survives the deletion — `removeRow` moves it down
-* and shortens its span — so marking its text would delete content the
-* accepted document must still hold.
+* Two kinds of run stay unmarked. A run that already carries a revision of the
+* same kind keeps it, because overwriting would drop the earlier revision; a
+* pending insertion inside a deleted row is marked deleted as well (`w:ins >
+* w:del`), as `deleteBlock` marks one inside a deleted paragraph, so every
+* reader leaves it out with the rest of the row. A cell that spans into the
+* row below survives the deletion — `removeTableRow` moves it down and
+* shortens its span — so marking its text would delete content the accepted
+* document must still hold.
 */
 const markTableRowContent = ({ tr, rowPosition, kind, revision }) => {
 	const row = tr.doc.nodeAt(rowPosition);
@@ -103,7 +121,7 @@ const markTableRowContent = ({ tr, rowPosition, kind, revision }) => {
 		if (!node.isInline) return true;
 		if (node.marks.some(isTrackedChangeMark)) {
 			wholeRowMarkable = false;
-			return false;
+			if (kind === "insertion" || node.marks.some(({ type }) => type.name === "deletion")) return false;
 		}
 		const from = contentFrom + offset;
 		markable.push({
@@ -127,8 +145,20 @@ const applyTableColumnInsertion = ({ tr, insertion, cellTexts, revision }) => {
 	const tablePosition = tr.mapping.map(insertion.tablePosition, 1);
 	const table = tr.doc.nodeAt(tablePosition);
 	if (!table || table.type.spec["tableRole"] !== "table") return { type: "unsupported" };
+	const map = TableMap.get(table);
+	if (insertion.columnIndex >= 0 && insertion.columnIndex <= map.width) {
+		const overflow = describeUnplacedCellTexts({
+			cellTexts,
+			capacity: getInsertedPhysicalColumnRows(map, insertion.columnIndex).length,
+			target: "column"
+		});
+		if (overflow !== null) return {
+			type: "payloadDoesNotFit",
+			message: overflow
+		};
+	}
 	const actions = buildTableColumnInsertionActions({
-		map: TableMap.get(table),
+		map,
 		table,
 		columnIndex: insertion.columnIndex,
 		cellTexts
@@ -150,6 +180,12 @@ const applyTableColumnInsertion = ({ tr, insertion, cellTexts, revision }) => {
 		}, action.cell.content) : action.cell;
 		tr.insert(position, cell);
 	}
+	reconcileTableGridAfterColumnInsertion({
+		tr,
+		tablePosition,
+		previousTable: table,
+		insertedColumn: insertion.columnIndex
+	});
 	return applied(tr, revision);
 };
 const applyTableColumnDeletion = ({ tr, deletion, insertedColumnCount, revision }) => {
@@ -196,6 +232,7 @@ const applyTableColumnDeletion = ({ tr, deletion, insertedColumnCount, revision
 		previousTable: table,
 		removedColumn: columnIndex
 	});
+	removeRowsWithoutCells(tr, tablePosition);
 	return applied(tr, null);
 };
 const applyTableRowDeletion = ({ tr, deletion, revision }) => {
@@ -213,26 +250,23 @@ const applyTableRowDeletion = ({ tr, deletion, revision }) => {
 		markStructuralChange(tr);
 		return applied(tr, revision);
 	}
-	const table = tr.doc.nodeAt(deletion.tablePosition);
-	if (!table || table.type.spec["tableRole"] !== "table" || deletion.rowIndex >= table.childCount) return { type: "unsupported" };
+	const at = tr.doc.resolve(tr.mapping.map(deletion.rowPosition));
+	const table = at.parent;
+	if (table.type.spec["tableRole"] !== "table" || at.nodeAfter?.type.spec["tableRole"] !== "row") return { type: "unsupported" };
+	const tablePosition = at.before();
 	if (table.childCount === 1) {
 		const transaction = deleteTableNode({
 			tr,
-			tablePosition: deletion.tablePosition,
+			tablePosition,
 			table
 		});
 		return transaction ? applied(transaction, null) : { type: "unsupported" };
 	}
-	const map = TableMap.get(table);
-	removeRow(tr, {
-		map,
+	removeTableRow(tr, {
+		map: TableMap.get(table),
 		table,
-		tableStart: deletion.tableStart,
-		left: 0,
-		top: deletion.rowIndex,
-		right: map.width,
-		bottom: deletion.rowIndex + 1
-	}, deletion.rowIndex);
+		tableStart: at.start()
+	}, at.index());
 	return applied(tr, null);
 };
 const applied = (transaction, revision) => ({
@@ -302,7 +336,8 @@ const splitCellParagraphTexts = (text) => text.split(CELL_LINE_BREAK_PATTERN);
 * Fill the new row's cells from `cellTexts`, in order: the nth text goes in
 * the nth cell the row actually has, which is how a caller reading the row
 * through the block snapshot counts them (`table.cellIndex`). Cells the caller
-* did not name stay empty.
+* did not name stay empty. The resolver has already refused more texts than
+* cells ({@link describeUnplacedCellTexts}).
 */
 const populateTableRow = (row, cellTexts) => {
 	if (cellTexts === void 0) return row;
@@ -404,4 +439,4 @@ const getTableColumnDeletionCellPositions = ({ map, table, columnIndex }) => {
 	return [...positions];
 };
 //#endregion
-export { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };
+export { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, describeUnplacedCellTexts, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };

package/dist/ai-edits/types.d.ts

@@ -1,7 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
+import { ListKind } from "../docx/listNumberingInstances.js";
 //#region src/ai-edits/types.d.ts
-type FolioAIBlockKind = FolioContentParagraphKind;
+type FolioAIBlockKind = FolioContentParagraphKind | "diagnostic";
 /** Boolean run properties supported by snapshots and range-formatting mutations. */
 type FolioAIInlineBooleanProperty = FolioContentInlineBooleanProperty;
 type FolioAIInlineFormatting = FolioContentInlineFormatting;
@@ -12,15 +13,28 @@ type FolioAIInlineFormatting = FolioContentInlineFormatting;
 type FolioAIInlineFormattingPatch = FolioContentInlineFormattingPatch;
 type FolioAIBlockPreviewRun = FolioContentRun;
 /**
- * A zero-width inline structure at one clean-text boundary. `pageBreak`
- * always represents an authored `<w:br w:type="page"/>`; an omitted `clear`
- * remains distinct from any explicit value even though it does not affect
- * layout for this break type.
+ * Inline structure inside a block's clean text.
+ *
+ * `pageBreak` is zero-width at one clean-text boundary and always represents
+ * an authored `<w:br w:type="page"/>`; an omitted `clear` remains distinct from
+ * any explicit value even though it does not affect layout for this break type.
+ *
+ * `noteReference` is a footnote or endnote reference, which the text shows as
+ * its marker (`[^1]` for the first footnote, `[^e1]` for the first endnote —
+ * the numbering the Markdown export uses) over `length` characters from
+ * `offset`. The marker is structure, not text: a range may not cut into it,
+ * and a text edit that would rewrite or remove it is refused
+ * (`protectedReference`).
  */
 type FolioAIBlockStructuralBoundary = {
   type: "pageBreak";
   offset: number;
   clear?: document_d_exports.BreakContent["clear"];
+} | {
+  type: "noteReference";
+  noteType: "footnote" | "endnote";
+  offset: number;
+  length: number;
 };
 /**
  * Where a block sits inside its innermost enclosing table. Every index is
@@ -33,6 +47,11 @@ type FolioAIBlockStructuralBoundary = {
 type FolioAIBlockTableLocation = FolioContentTableLocation;
 type FolioAIBlock = FolioContentBlock<FolioAIBlockKind> & {
   structuralBoundaries?: readonly FolioAIBlockStructuralBoundary[];
+  /** Present on a read-only block that reports preserved content Folio cannot interpret. */
+  diagnostic?: {
+    type: "opaqueCarrier";
+    carrier: string;
+  };
 };
 /**
  * The complete modeled attribute set of one direct `w:pPr/w:spacing` child.
@@ -43,6 +62,22 @@ type FolioAIParagraphSpacing = FolioContentParagraphSpacing;
 /** The complete modeled attribute set of one direct `w:pPr/w:ind` child. */
 type FolioAIParagraphIndentation = FolioContentParagraphIndentation;
 type FolioAIListReference = FolioContentListReference;
+/** The kinds of list an operation can start. */
+type FolioAIListKind = ListKind;
+/**
+ * Start a new list: a numbering instance of `kind`, defined for the
+ * operation, with its paragraphs at `level` (zero-based, default 0). Every
+ * paragraph one operation numbers this way joins the same new list; separate
+ * operations start separate lists. A package without a numbering part gets
+ * one.
+ */
+type FolioAINewListReference = {
+  start: "new";
+  kind: FolioAIListKind;
+  level?: number;
+};
+/** An existing numbering instance and level, or a new list. */
+type FolioAIListNumbering = FolioAIListReference | FolioAINewListReference;
 /** Which paragraphs split from one insertion's `text` receive its paragraph formatting. */
 type FolioAIInsertFormattingScope = "firstParagraph" | "allParagraphs";
 /**
@@ -53,13 +88,15 @@ type FolioAIInsertFormattingScope = "firstParagraph" | "allParagraphs";
 type FolioAIBlockParagraphProperties = {
   /** `w:pStyle`. `null` clears the style back to the default. */
   styleId?: string | null;
+  /** Direct `w:outlineLvl`. `null` restores style inheritance. */
+  outlineLevel?: document_d_exports.OutlineLevel | null;
   /**
    * `w:numPr/w:ilvl`, zero-based. `null` removes numbering unless `numbering`
    * supplies a concrete instance; together they retain that instance without
    * an authored level.
    */
   listLevel?: number | null;
-  numbering?: FolioAIListReference | null;
+  numbering?: FolioAIListNumbering | null;
   /** Direct `w:jc`. `null` clears the override and restores style inheritance. */
   alignment?: document_d_exports.ParagraphAlignment | null;
   /** Direct `w:spacing` attributes. `null` removes the whole direct child. */
@@ -234,8 +271,8 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   /**
    * Which paragraphs split from `text` receive the operation's
    * paragraph formatting: the inherited anchor formatting plus
-   * `styleId`, `listLevel`, `numbering`, `alignment`, `spacing` and
-   * `indentation`. `"firstParagraph"` (the default) formats the first
+   * `styleId`, `outlineLevel`, `listLevel`, `numbering`, `alignment`,
+   * `spacing` and `indentation`. `"firstParagraph"` (the default) formats the first
    * and leaves the rest as body paragraphs, for a heading followed by
    * its body. `"allParagraphs"` formats every paragraph alike, for
    * several list items in one operation. `pageBreakBefore` and
@@ -270,6 +307,13 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * inheritance alone cannot say.
    */
   styleId?: string | null;
+  /**
+   * Direct `w:outlineLvl` for the inserted block. Without it the
+   * inserted paragraph keeps the level the anchor states itself, so a
+   * body paragraph inserted beside a heading that states its level
+   * becomes a heading. `null` clears it and lets the style decide.
+   */
+  outlineLevel?: document_d_exports.OutlineLevel | null;
   /**
    * Override `w:numPr/w:ilvl` on the inserted block, keeping the
    * anchor's `w:numId`. Without it the inserted paragraph takes the
@@ -279,7 +323,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * they retain that instance without an authored level.
    */
   listLevel?: number | null;
-  numbering?: FolioAIListReference | null;
+  numbering?: FolioAIListNumbering | null;
   /**
    * Direct `w:jc` for the inserted block. `null` clears alignment copied
    * from the anchor and lets the inserted paragraph's style decide.
@@ -456,10 +500,12 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * Initial text for each cell of the new row, in order — the same order
    * a block's `table.cellIndex` counts. Cells left unnamed stay empty.
    *
-   * Sized against the table's COLUMN count, which is the most cells any
-   * row of it could have: more texts than that is refused rather than
-   * silently truncated, and fewer is not, so a row the table can hold is
-   * no longer refused because a span makes it narrower than the table.
+   * Sized against the cells the new row really has, which is fewer than
+   * the table's columns where a vertical merge from the row above
+   * reaches through the insertion point (the merge grows through the
+   * new row and keeps its column). More texts than cells is refused as
+   * `payloadDoesNotFit`, naming the texts with no cell, before anything
+   * is written; fewer leaves the remaining cells empty.
    *
    * A line break in a cell's text starts a new paragraph in that cell,
    * as in `insertTable`.
@@ -476,7 +522,11 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   /** Stable paragraph anchor inside the cell that receives the new sibling column. */
   blockId: string;
   position?: "after" | "before";
-  /** Initial text for newly created physical cells in row order. */
+  /**
+   * Initial text for newly created physical cells in row order. A
+   * horizontal merge the new column crosses widens instead of taking a
+   * cell, so more texts than new cells is refused as `payloadDoesNotFit`.
+   */
   cellTexts?: string[];
 } | {
   id: string;
@@ -539,7 +589,74 @@ type FolioAIEditSkipReason = "missingBlock" | "changedBlock" | "ambiguousFind" |
  * no entity to attach suggestions to); the operation was neither applied
  * nor queued.
  */
-"documentNotEditable";
+"documentNotEditable" |
+/**
+ * The operation supplies more values than its target can hold, so applying
+ * it would drop some of them: an `insertTableRow` whose `cellTexts` outnumber
+ * the cells the new row has (a vertical merge crossing the insertion point
+ * extends through the new row and takes a column away from it), or an
+ * `insertTableColumn` whose `cellTexts` outnumber the cells the new column
+ * has. Nothing was applied; `message` names the values that do not fit.
+ * Supply fewer values, or anchor the operation where the table has room.
+ */
+"payloadDoesNotFit" |
+/**
+ * An earlier operation of the same batch already claims this operation's
+ * target: it deletes, rewrites, splits or merges the block this one edits,
+ * or edits an overlapping stretch of its text. Operations of one batch all
+ * address the document as it was read, so this one would have landed on
+ * positions the other had moved. Nothing of it was applied; re-read the
+ * document after the batch and send it again, on its own.
+ */
+"overlappingOperation" |
+/**
+ * An offset of the operation falls inside one character: between the two
+ * UTF-16 halves of a surrogate pair (an emoji, a character outside the
+ * Basic Multilingual Plane), or — for an operation that changes text or
+ * breaks a paragraph — inside a grapheme cluster (a letter and its combining
+ * marks, an emoji sequence joined with zero-width joiners, a flag). Text cut
+ * there cannot be written back whole. Nothing was applied; move the offset
+ * to the boundary before or after the character.
+ */
+"splitsCharacter" |
+/**
+ * The text change would rewrite or remove a footnote or endnote reference
+ * (the `[^1]` / `[^e1]` markers the text shows), or write a marker-shaped
+ * string of its own. A reference is structure, not text: keep each marker
+ * the match covers in the replacement, in order, or match only the prose
+ * beside it.
+ */
+"protectedReference" |
+/**
+ * The operation names a paragraph style (`styleId`) the document does not
+ * define, or one defined as a table, character or numbering style. Nothing
+ * was applied: such a `w:pStyle` confers no formatting, so the paragraph
+ * would keep its body look. Use a paragraph style the document defines, or
+ * `null` to clear the style.
+ */
+"missingStyle" |
+/**
+ * The operation names a numbering instance (`numbering.numId`) the document
+ * does not define. Nothing was applied: a paragraph referencing a missing
+ * `w:num` cannot be saved. Re-read the document and use an instance it
+ * defines, or clear the numbering.
+ */
+"missingNumbering" |
+/**
+ * Applying the operation would have left a document that cannot be saved:
+ * the save-time model validator rejected the result. Nothing from the
+ * operation was applied; `message` carries the validator's path and reason.
+ */
+"invalidResult" |
+/**
+ * The block is pending deletion: a tracked change deletes its text and its
+ * paragraph mark, or the table row or cell holding it, so a reader lists it
+ * as a blank block and accepting removes it. Nothing was applied: text
+ * written there would join the next paragraph, or go with the row, once the
+ * deletion is accepted. Reject that deletion first, or insert a new block
+ * next to it.
+ */
+"pendingDeletion";
 type FolioAIEditAppliedOperation = {
   id: string;
   commentId?: number;
@@ -572,6 +689,15 @@ type FolioAIEditAppliedOperation = {
 type FolioAIEditSkippedOperation = {
   id: string;
   reason: FolioAIEditSkipReason;
+  /**
+   * What exactly was wrong when the reason alone does not say: the values a
+   * `payloadDoesNotFit` skip could not place, the earlier operation an
+   * `overlappingOperation` skip conflicts with, the offset and character of a
+   * `splitsCharacter` skip, the undefined style of a `missingStyle` skip, the
+   * undefined instance of a `missingNumbering` skip, or the validator's path
+   * and message of an `invalidResult` one.
+   */
+  message?: string;
 };
 /**
  * One automatic adjustment `apply.ts` made to an operation's input to keep the
@@ -600,6 +726,19 @@ type FolioAIEditNormalization =
   id: string;
   code: "unpairedMove";
   moveId: string;
+} |
+/**
+ * A text replacement rewrote a stretch whose characters did not all carry
+ * the same formatting, link or comment. The new text takes the formatting
+ * of the first character it replaces, and every link and comment over the
+ * stretch; text the replacement keeps keeps its own. A change spanning
+ * several words keeps only whole words, so no word is left partly in the
+ * old formatting. Direct and tracked modes allocate alike: accepting the
+ * tracked replacement leaves what the direct one writes.
+ */
+{
+  id: string;
+  code: "uniformReplacementFormatting";
 };
 type FolioAIEditNormalizationCode = FolioAIEditNormalization["code"];
 type FolioAIEditApplyResult = {
@@ -609,4 +748,4 @@ type FolioAIEditApplyResult = {
   normalizations?: FolioAIEditNormalization[];
 };
 //#endregion
-export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIInsertFormattingScope, FolioAIListReference, FolioAIParagraphIndentation, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIInsertFormattingScope, FolioAIListKind, FolioAIListNumbering, FolioAIListReference, FolioAINewListReference, FolioAIParagraphIndentation, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

package/dist/compare/compare.d.ts

@@ -100,7 +100,7 @@ type AppliedComparison = {
  * what you could not represent" and "give me nothing unless you can prove it"
  * are both legitimate asks and only the caller knows which one it is making.
  */
-declare const applyComparison: ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError | CompareDocxOperationLimitError>;
+declare const applyComparison: ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs, unsupported }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError | CompareDocxOperationLimitError>;
 /**
  * Stage 4: the result package, with every ZIP entry date pinned.
  *