@stll/folio-core 0.33.1 → 0.33.2

package/dist/ai-edits/table-geometry.js

@@ -0,0 +1,217 @@
+import { tableCellRejectAttrPatch, tableRejectAttrPatch, tableRowRejectAttrPatch } from "../prosemirror/commands/propertyChangeScope.js";
+import { tableAttrsToFormatting, tableCellAttrsToFormatting, tableRowAttrsToFormatting } from "../prosemirror/conversion/fromProseDoc.js";
+import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
+import { canonicalJson } from "../utils/canonicalJson.js";
+//#region src/ai-edits/table-geometry.ts
+const ORIGINAL_FORMATTING = "_originalFormatting";
+/**
+* The formatting a parser stored verbatim for the save path. It is deliberately
+* outside every projection below: a document saved by an editor materializes
+* style-resolved properties into its own `w:tcPr`, so two packages that render
+* the same table can store different formatting for it, and comparing what was
+* stored would report a difference no redline can or should represent. What is
+* compared is the effective set the properties resolve to.
+*/
+const withoutOriginalFormatting = (keys) => keys.filter((key) => key !== ORIGINAL_FORMATTING);
+/**
+* Attrs a `w:tblPrChange` reject restores, and therefore the attrs a match
+* writes and the projection reads. `columnWidths` is deliberately outside
+* them: the grid is `w:tblGrid`, not `w:tblPr`, and the editable model has no
+* `w:tblGridChange` to record a change of it against.
+*/
+const TABLE_SCOPED_ATTRS = withoutOriginalFormatting(Object.keys(tableRejectAttrPatch(void 0)));
+const ROW_SCOPED_ATTRS = withoutOriginalFormatting(Object.keys(tableRowRejectAttrPatch(void 0)));
+const CELL_SCOPED_ATTRS = withoutOriginalFormatting(Object.keys(tableCellRejectAttrPatch(void 0, void 0)));
+/**
+* `false` and absent are the same thing for every property in scope here: they
+* are all presence flags (`w:tblHeader`, `w:hidden`, `w:noWrap`), and a parser
+* that materializes an absent one as `false` must not read as a difference
+* from one that leaves it unset.
+*/
+const scopedAttrs = (attrs, keys) => {
+	const scoped = {};
+	for (const key of keys) {
+		const value = attrs[key];
+		scoped[key] = value === false ? null : value ?? null;
+	}
+	return scoped;
+};
+const cellProjection = (cell) => canonicalJson({
+	colspan: cell.attrs["colspan"],
+	rowspan: cell.attrs["rowspan"],
+	...scopedAttrs(cell.attrs, CELL_SCOPED_ATTRS)
+});
+const rowProjection = (row) => {
+	const cells = [];
+	row.forEach((cell) => {
+		cells.push(cellProjection(cell));
+	});
+	return `${canonicalJson(scopedAttrs(row.attrs, ROW_SCOPED_ATTRS))}|${cells.join("|")}`;
+};
+/**
+* One line per table, in the document order tables are numbered in: the
+* table's own properties, then each row's and each cell's. Nested tables get
+* their own lines rather than being folded into their parent's, so a
+* difference names the table it is in.
+*/
+const projectTableGeometry = (tables) => tables.map(({ node }) => {
+	const rows = [];
+	node.forEach((row) => {
+		rows.push(rowProjection(row));
+	});
+	return `${canonicalJson(scopedAttrs(node.attrs, TABLE_SCOPED_ATTRS))}#${rows.join("#")}`;
+});
+const childPositions = (node, start) => {
+	const positions = [];
+	let offset = start + 1;
+	node.forEach((child) => {
+		positions.push(offset);
+		offset += child.nodeSize;
+	});
+	return positions;
+};
+/**
+* `Node["attrs"]` is an open record, and the converters below want the node
+* type's own shape. The two span counts are the only members the schema always
+* carries a value for, so naming them is what turns the record into one.
+*/
+const cellAttrsOf = (node) => ({
+	...effectiveAttrs(node),
+	colspan: typeof node.attrs["colspan"] === "number" ? node.attrs["colspan"] : 1,
+	rowspan: typeof node.attrs["rowspan"] === "number" ? node.attrs["rowspan"] : 1
+});
+/**
+* The node's attrs with the style cascade's own values cleared, so the
+* converter treats every effective value as one the node states.
+*
+* A change element stores the COMPLETE previous property set and a reject
+* rebuilds the live properties from it alone, so the record has to hold what
+* the node renders with — including a border its table style supplied. The
+* save path wants the opposite (write only what the node states, or the
+* inherited value becomes an override), which is what the resolved companions
+* are for; a record is the one place they get in the way.
+*/
+const effectiveAttrs = (node) => ({
+	...node.attrs,
+	_resolvedBorders: null,
+	_resolvedMargins: null,
+	_resolvedCellMargins: null
+});
+const TABLE_SCOPE = {
+	keys: TABLE_SCOPED_ATTRS,
+	formattingOf: (node) => tableAttrsToFormatting(effectiveAttrs(node)),
+	rejectPatch: (previousFormatting) => tableRejectAttrPatch(previousFormatting),
+	changeAttr: "tblPrChange",
+	changeType: "tablePropertyChange"
+};
+const ROW_SCOPE = {
+	keys: ROW_SCOPED_ATTRS,
+	formattingOf: (node) => tableRowAttrsToFormatting(node.attrs),
+	rejectPatch: (previousFormatting) => tableRowRejectAttrPatch(previousFormatting),
+	changeAttr: "trPrChange",
+	changeType: "tableRowPropertyChange"
+};
+const CELL_SCOPE = {
+	keys: CELL_SCOPED_ATTRS,
+	formattingOf: (node) => tableCellAttrsToFormatting(cellAttrsOf(node)),
+	rejectPatch: (previousFormatting, liveFormatting) => tableCellRejectAttrPatch(previousFormatting, liveFormatting),
+	changeAttr: "tcPrChange",
+	changeType: "tableCellPropertyChange"
+};
+const scopedValues = (attrs, keys) => canonicalJson(scopedAttrs(attrs, keys));
+/**
+* One node's properties, matched to the node it was paired with, or `null`
+* when the difference cannot be recorded.
+*
+* A change element stores the COMPLETE previous property set, and rejecting it
+* rebuilds the live properties from that record alone. So the record is built
+* from what the node would SERIALIZE, not from what its parser stored: a cell
+* inherits borders and margins from the table and from a table style, and a
+* record that omitted them would reject to a third document.
+*
+* The check is direct, and it is what keeps the round trip exact: rebuild the
+* live values from the record and see whether they come back. Where they do
+* not, the difference is left alone rather than written as a revision that
+* cannot be undone.
+*/
+const propertyChangeFor = (base, target, position, scope) => {
+	const live = scopedValues(base.attrs, scope.keys);
+	if (live === scopedValues(target.attrs, scope.keys)) return null;
+	const previousFormatting = scope.formattingOf(base);
+	if (scopedValues(scope.rejectPatch(previousFormatting, previousFormatting), scope.keys) !== live) return null;
+	return {
+		position,
+		attrs: {
+			...scopedAttrs(target.attrs, scope.keys),
+			[ORIGINAL_FORMATTING]: scope.formattingOf(target) ?? null
+		},
+		changeAttr: scope.changeAttr,
+		changeType: scope.changeType,
+		previousFormatting
+	};
+};
+/**
+* Copy a paired table's, row's and cell's properties from the document it was
+* compared against, recording the previous set so a reject restores it.
+*
+* Pairings name cells, because that is what the block alignment resolves; the
+* row and the table each cell sits in are matched with it. A property set that
+* already agrees is left alone, so an unchanged table produces no revision.
+*
+* `colspan` / `rowspan` never move: they shape the table map, and changing one
+* without restructuring the rows around it leaves the map inconsistent with
+* its own grid. That is the rule a reject of a `w:tcPrChange` follows too.
+*/
+const matchTableGeometry = ({ tr, baseTables, targetTables, pairings, revision }) => {
+	const baseByIndex = new Map(baseTables.map((table) => [table.index, table]));
+	const targets = [];
+	const claimed = /* @__PURE__ */ new Set();
+	const consider = (base, target, position, scope) => {
+		if (claimed.has(position)) return;
+		claimed.add(position);
+		const change = propertyChangeFor(base, target, position, scope);
+		if (change) targets.push(change);
+	};
+	for (const { base, target } of pairings) {
+		const baseTable = baseByIndex.get(base.tableIndex);
+		const targetTable = targetTables.get(target.tableIndex);
+		if (!baseTable || !targetTable) continue;
+		const baseRow = baseTable.node.maybeChild(base.rowIndex);
+		const targetRow = targetTable.maybeChild(target.rowIndex);
+		const rowPosition = childPositions(baseTable.node, baseTable.start)[base.rowIndex];
+		if (!baseRow || !targetRow || rowPosition === void 0) continue;
+		const baseCell = baseRow.maybeChild(base.cellIndex);
+		const targetCell = targetRow.maybeChild(target.cellIndex);
+		const cellPosition = childPositions(baseRow, rowPosition)[base.cellIndex];
+		if (!baseCell || !targetCell || cellPosition === void 0) continue;
+		consider(baseTable.node, targetTable, baseTable.start, TABLE_SCOPE);
+		consider(baseRow, targetRow, rowPosition, ROW_SCOPE);
+		consider(baseCell, targetCell, cellPosition, CELL_SCOPE);
+	}
+	let revisionId = revision.idSeed;
+	for (const target of targets) {
+		const node = tr.doc.nodeAt(target.position);
+		if (!node) continue;
+		tr.setNodeMarkup(target.position, void 0, {
+			...node.attrs,
+			...target.attrs,
+			[target.changeAttr]: [{
+				type: target.changeType,
+				info: {
+					id: revisionId,
+					author: revision.author,
+					date: revision.date
+				},
+				...target.previousFormatting != null && { previousFormatting: target.previousFormatting }
+			}]
+		});
+		revisionId += 1;
+	}
+	if (revisionId > revision.idSeed) markStructuralChange(tr);
+	return {
+		nextRevisionId: revisionId,
+		matched: targets.length
+	};
+};
+//#endregion
+export { matchTableGeometry, projectTableGeometry };

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

@@ -1,4 +1,4 @@
-import { TrackedChangeProvenance } from "../prosemirror/schema/marks.js";
+import { TableStructureRevision } from "./table-template.js";
 import { TableRowTarget } from "./table-targets.js";
 import { Transaction } from "prosemirror-state";
 import { Node } from "prosemirror-model";
@@ -27,19 +27,6 @@ type TableColumnInsertion = {
   columnIndex: number;
 };
 type TableColumnDeletion = TableColumnInsertion;
-type TableStructureRevision = {
-  revisionId: number;
-  author: string;
-  date: string;
-  /** Optional author initials (w:initials), carried for round-trip. */
-  initials?: string;
-  /**
-   * `"suggested"` marks the produced `trIns`/`trDel`/`cellMarker` as an AI
-   * proposal that is stripped from serialized DOCX until accepted.
-   */
-  provenance?: TrackedChangeProvenance;
-  suggestionId?: string;
-};
 type TableRowColumnMutationResult = {
   type: "applied";
   transaction: Transaction;
@@ -63,8 +50,39 @@ type ApplyTableRowInsertionOptions = {
   insertion: TableRowInsertion;
   cellTexts: readonly string[] | undefined;
   revision: TableStructureRevision | null;
+  /**
+   * The row to place, when the caller has one — a comparison adding a row the
+   * target document already holds. Its `w:trPr` and per-cell `w:tcPr` travel
+   * with it; `cellTexts` builds the row from the neighbouring one when it is
+   * absent or does not fit this table's grid.
+   */
+  template?: Node;
+};
+declare const applyTableRowInsertion: ({ tr, insertion, cellTexts, revision, template }: ApplyTableRowInsertionOptions) => TableRowColumnMutationResult;
+type MarkTableRowContentOptions = {
+  tr: Transaction;
+  rowPosition: number;
+  kind: "insertion" | "deletion";
+  revision: TableStructureRevision;
 };
-declare const applyTableRowInsertion: ({ tr, insertion, cellTexts, revision }: ApplyTableRowInsertionOptions) => TableRowColumnMutationResult;
+/**
+ * Mark the runs inside a row whose structural revision was just written.
+ *
+ * Word records a tracked row insertion or deletion twice: on the row
+ * (`w:trPr/w:ins` | `w:trPr/w:del`) AND around every run in its cells
+ * (`w:ins` | `w:del`, the latter with `w:delText`). A consumer that reads only
+ * run-level revisions — which is most of them — keeps a deleted row's text on
+ * 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.
+ */
+declare const markTableRowContent: ({ tr, rowPosition, kind, revision }: MarkTableRowContentOptions) => void;
 type ApplyTableColumnInsertionOptions = {
   tr: Transaction;
   insertion: TableColumnInsertion;
@@ -98,4 +116,4 @@ declare const applyTableRowDeletion: ({ tr, deletion, revision }: ApplyTableRowD
  */
 declare const splitCellParagraphTexts: (text: string) => string[];
 //#endregion
-export { TableColumnDeletion, TableColumnInsertion, TableRowDeletion, TableRowInsertion, TableStructureRevision, applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, splitCellParagraphTexts };
+export { MarkTableRowContentOptions, TableColumnDeletion, TableColumnInsertion, TableRowDeletion, TableRowInsertion, applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };

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

@@ -1,6 +1,7 @@
 import { markStructuralChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.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";
 //#region src/ai-edits/table-row-column-mutations.ts
 const getTableColumnCoordinateKey = ({ tablePosition, columnIndex }) => `${tablePosition}:${columnIndex}`;
@@ -25,7 +26,7 @@ const findTableRowInsertion = ({ doc, blockFrom, position }) => {
 		rowIndex
 	});
 };
-const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision }) => {
+const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision, template }) => {
 	if (revision && insertion.rowspanUpdates.length > 0) return { type: "unsupported" };
 	const liveRowspanUpdates = [];
 	for (const updatePosition of insertion.rowspanUpdates) {
@@ -44,8 +45,15 @@ const applyTableRowInsertion = ({ tr, insertion, cellTexts, revision }) => {
 		rowspan: update.rowspan + 1
 	});
 	const rowAttrs = revision ? { trIns: revision } : null;
-	const row = insertion.rowType.create(rowAttrs, insertion.cells);
-	tr.insert(insertion.rowPosition, populateTableRow(row, cellTexts));
+	const templated = template === void 0 ? null : tableRowFromTemplate({
+		template,
+		columnCount: insertion.columnCount
+	});
+	const row = templated ? templated.type.create({
+		...templated.attrs,
+		...rowAttrs
+	}, templated.content) : populateTableRow(insertion.rowType.create(rowAttrs, insertion.cells), cellTexts);
+	tr.insert(insertion.rowPosition, row);
 	if (revision) markTableRowContent({
 		tr,
 		rowPosition: insertion.rowPosition,
@@ -389,4 +397,4 @@ const getTableColumnDeletionCellPositions = ({ map, table, columnIndex }) => {
 	return [...positions];
 };
 //#endregion
-export { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, splitCellParagraphTexts };
+export { applyTableColumnDeletion, applyTableColumnInsertion, applyTableRowDeletion, applyTableRowInsertion, findTableColumnInsertion, findTableRowInsertion, getTableColumnCoordinateKey, markTableRowContent, splitCellParagraphTexts };

package/dist/ai-edits/table-template.d.ts

@@ -0,0 +1,60 @@
+import { TrackedChangeProvenance } from "../prosemirror/schema/marks.js";
+import { Node, Schema } from "prosemirror-model";
+//#region src/ai-edits/table-template.d.ts
+/** The node an operation should place, by the id of the operation placing it. */
+type FolioTableTemplates = ReadonlyMap<string, Node>;
+/**
+ * A structural tracked change on a table row.
+ *
+ * A whole-table insertion has no element of its own in the format: every row
+ * carries `w:trPr/w:ins`, and every run inside it carries `w:ins` as well. A
+ * consumer that reads only run-level revisions keeps the text of a rejected
+ * insertion when the row marker stands alone, so the two are always written
+ * together.
+ */
+type TableStructureRevision = {
+  revisionId: number;
+  author: string;
+  date: string;
+  /** Optional author initials (w:initials), carried for round-trip. */
+  initials?: string;
+  /**
+   * `"suggested"` marks the produced `trIns`/`trDel`/`cellMarker` as an AI
+   * proposal that is stripped from serialized DOCX until accepted.
+   */
+  provenance?: TrackedChangeProvenance;
+  suggestionId?: string;
+};
+type TableFromTemplateOptions = {
+  schema: Schema;
+  template: Node;
+  /** Present in tracked mode: the whole table is stamped as one insertion. */
+  revision?: TableStructureRevision;
+};
+/**
+ * The template table, ready to insert: its properties, grid, rows and cells
+ * carried verbatim, nested tables included, and every row plus every run
+ * stamped as an insertion when the caller is tracking changes.
+ *
+ * `null` when the template is not a table or holds no rows, so the caller can
+ * fall back to the operation's own cell texts rather than place something that
+ * is not one.
+ */
+declare const tableFromTemplate: ({ schema, template, revision }: TableFromTemplateOptions) => Node | null;
+type TableRowFromTemplateOptions = {
+  template: Node;
+  /** Grid columns the row has to occupy, from the table receiving it. */
+  columnCount: number;
+};
+/**
+ * The template row, ready to insert into an existing table.
+ *
+ * Refused — `null`, so the caller falls back to the operation's cell texts —
+ * when the row's cells do not span exactly the receiving table's grid: a row
+ * of a different width would leave the table's map inconsistent with its own
+ * grid. A cell that merged vertically in the document it came from is placed
+ * unmerged, because the rows it reached into are not this table's.
+ */
+declare const tableRowFromTemplate: ({ template, columnCount }: TableRowFromTemplateOptions) => Node | null;
+//#endregion
+export { FolioTableTemplates, TableStructureRevision, tableFromTemplate, tableRowFromTemplate };

package/dist/ai-edits/table-template.js

@@ -0,0 +1,176 @@
+import { stripBlockIdentityAttrs } from "./block-identity.js";
+import { Fragment } from "prosemirror-model";
+//#region src/ai-edits/table-template.ts
+/**
+* Building a table from another document's table rather than from a grid of
+* strings.
+*
+* `insertTable` and `insertTableRow` describe their content as cell texts,
+* which is the right shape for a caller that writes a table from nothing. A
+* comparison is not that caller: the table it adds already exists in the
+* document it is comparing against, complete with its `w:tblPr`, its
+* `w:tblGrid` widths, per-row `w:trPr`, per-cell `w:tcPr` — spans, vertical
+* merges, shading, borders, margins, alignment — and cell paragraphs carrying
+* their own properties. Rebuilding that from text loses every one of them, and
+* a consumer accepting the redline then gets a table that is not the one it
+* was compared to.
+*
+* So the operation may be handed the node it should place. The copy is
+* structural and keeps everything by default; what it cannot bring is what
+* only the package it came from can resolve — a relationship id (a drawing, a
+* hyperlink), a note or comment id, a bookmark, a paragraph identity, or a
+* tracked change belonging to the other document's history. Everything that
+* describes the table itself travels.
+*/
+/**
+* Nodes that name something the other package owns: a drawing's relationship,
+* an anchored frame's, a bookmark's id. They resolve to nothing once the table
+* has crossed, so they are dropped rather than copied into a dangling
+* reference.
+*/
+const PACKAGE_BOUND_NODE_NAMES = /* @__PURE__ */ new Set([
+	"image",
+	"textBox",
+	"textBoxAnchor",
+	"shape",
+	"bookmarkBoundary"
+]);
+/**
+* Marks that name something the other package owns. Run properties are the
+* point of copying the runs at all, so the denial is narrow: a relationship, a
+* note, a comment, and the other document's revisions.
+*/
+const PACKAGE_BOUND_MARK_NAMES = /* @__PURE__ */ new Set([
+	"hyperlink",
+	"footnoteRef",
+	"comment",
+	"insertion",
+	"deletion",
+	"runPropertyChange"
+]);
+/**
+* Paragraph attrs cleared on a copied paragraph: its identity, the bookmarks
+* and empty hyperlinks that name package-scoped ids, the section it ended, and
+* the tracked-change history of the document it came from. Its formatting —
+* style, alignment, spacing, indentation, borders, shading, tabs — is what the
+* copy exists to carry, and stays.
+*/
+const CLEARED_PARAGRAPH_ATTRS = [
+	"bookmarks",
+	"_emptyHyperlinks",
+	"_propertyChanges",
+	"pPrMark",
+	"_suggestedInsert",
+	"_sectionProperties",
+	"sectionBreakType",
+	"renderedPageBreakBefore"
+];
+/** Table, row and cell attrs that record the other document's revisions. */
+const CLEARED_TABLE_ATTRS = ["tblPrChange", "_suggestedInsert"];
+const CLEARED_ROW_ATTRS = [
+	"trIns",
+	"trDel",
+	"trPrChange"
+];
+const CLEARED_CELL_ATTRS = ["cellMarker", "tcPrChange"];
+const withoutAttrs = (attrs, cleared) => {
+	const next = { ...attrs };
+	for (const key of cleared) next[key] = null;
+	return next;
+};
+const insertionMarkOf = (schema, revision) => {
+	const markType = schema.marks["insertion"];
+	if (!revision || !markType) return null;
+	const { revisionId, author, date, initials, provenance, suggestionId } = revision;
+	return markType.create({
+		revisionId,
+		author,
+		date,
+		...initials !== void 0 && { initials },
+		...provenance !== void 0 && { provenance },
+		...suggestionId !== void 0 && { suggestionId }
+	});
+};
+const copiedAttrs = (node, context) => {
+	switch (node.type.spec["tableRole"]) {
+		case "table": return withoutAttrs(node.attrs, CLEARED_TABLE_ATTRS);
+		case "row": {
+			const attrs = withoutAttrs(node.attrs, CLEARED_ROW_ATTRS);
+			return context.revision ? {
+				...attrs,
+				trIns: context.revision
+			} : attrs;
+		}
+		case "cell":
+		case "header_cell": {
+			const attrs = withoutAttrs(node.attrs, CLEARED_CELL_ATTRS);
+			return context.clampRowSpan ? {
+				...attrs,
+				rowspan: 1
+			} : attrs;
+		}
+		default: return node.isTextblock ? withoutAttrs(stripBlockIdentityAttrs(node.attrs), CLEARED_PARAGRAPH_ATTRS) : node.attrs;
+	}
+};
+/**
+* One node of the template, or `null` when it names something the package it
+* came from owns. Inline content carries the insertion mark; a nested table is
+* copied by the same rules as the one holding it.
+*/
+const copyNode = (node, context) => {
+	if (PACKAGE_BOUND_NODE_NAMES.has(node.type.name)) return null;
+	const marks = node.marks.filter(({ type }) => !PACKAGE_BOUND_MARK_NAMES.has(type.name));
+	if (node.isLeaf) return node.mark(node.isInline && context.insertion ? [...marks, context.insertion] : marks);
+	const inner = node.type.spec["tableRole"] === "table" ? {
+		...context,
+		clampRowSpan: false
+	} : context;
+	const content = [];
+	node.forEach((child) => {
+		const copied = copyNode(child, inner);
+		if (copied) content.push(copied);
+	});
+	return node.type.create(copiedAttrs(node, context), Fragment.fromArray(content), marks);
+};
+/**
+* The template table, ready to insert: its properties, grid, rows and cells
+* carried verbatim, nested tables included, and every row plus every run
+* stamped as an insertion when the caller is tracking changes.
+*
+* `null` when the template is not a table or holds no rows, so the caller can
+* fall back to the operation's own cell texts rather than place something that
+* is not one.
+*/
+const tableFromTemplate = ({ schema, template, revision }) => {
+	if (template.type.spec["tableRole"] !== "table" || template.childCount === 0) return null;
+	return copyNode(template, {
+		revision: revision ?? null,
+		insertion: insertionMarkOf(schema, revision ?? null),
+		clampRowSpan: false
+	});
+};
+/**
+* The template row, ready to insert into an existing table.
+*
+* Refused — `null`, so the caller falls back to the operation's cell texts —
+* when the row's cells do not span exactly the receiving table's grid: a row
+* of a different width would leave the table's map inconsistent with its own
+* grid. A cell that merged vertically in the document it came from is placed
+* unmerged, because the rows it reached into are not this table's.
+*/
+const tableRowFromTemplate = ({ template, columnCount }) => {
+	if (template.type.spec["tableRole"] !== "row" || template.childCount === 0) return null;
+	let spanned = 0;
+	template.forEach((cell) => {
+		const colspan = cell.attrs["colspan"];
+		spanned += typeof colspan === "number" ? colspan : 1;
+	});
+	if (spanned !== columnCount) return null;
+	return copyNode(template, {
+		revision: null,
+		insertion: null,
+		clampRowSpan: true
+	});
+};
+//#endregion
+export { tableFromTemplate, tableRowFromTemplate };

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

@@ -276,6 +276,13 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
  * Delete the whole block. A block with words loses them and its paragraph
  * mark; a BLANK block has only a paragraph mark to lose, and loses it, so
  * the empty line goes away rather than the operation doing nothing.
+ *
+ * The block that ENDS its container is the exception, in both modes: a
+ * body, a cell, a header or footer, a note and a text box each end with a
+ * paragraph, and a deleted mark there would say "join with the paragraph
+ * after this one" where there is none. It loses its words and keeps its
+ * place. To remove it, delete the mark of the block BEFORE it, which
+ * merges forward into it.
  */
 {
   id: string;

package/dist/compare/__fixtures__/body-sequence.d.ts

@@ -13,6 +13,61 @@
  * gets written.
  */
 type CellContent = string | readonly BodyItem[];
+/** `w:tcPr` children a fixture can author, each named after the element. */
+type CellProperties = {
+  /** `w:gridSpan`: grid columns this cell occupies. */
+  gridSpan?: number;
+  /** `w:vMerge`: the cell starts a vertical merge, or continues one. */
+  verticalMerge?: "restart" | "continue";
+  /** `w:tcW` in twips. */
+  width?: number;
+  /** `w:shd` fill colour, as six hex digits. */
+  shadingFill?: string;
+  /** `w:vAlign`. */
+  verticalAlign?: "top" | "center" | "bottom";
+  /** `w:tcBorders`, single style on all four sides, in eighths of a point. */
+  borderSize?: number;
+  /** `w:tcMar`, the same margin on all four sides, in twips. */
+  margin?: number;
+};
+/** A cell: its content alone, or its content and its own `w:tcPr`. */
+type Cell = CellContent | ({
+  content: CellContent;
+} & CellProperties);
+/** A row: its cells alone, or its cells and its own `w:trPr`. */
+type TableRow = readonly Cell[] | {
+  cells: readonly Cell[];
+  /** `w:trHeight` in twips. */
+  height?: number;
+  /** `w:tblHeader`: the row repeats at the top of every page. */
+  header?: boolean;
+  /** `w:jc` on the row. */
+  justification?: "left" | "center" | "right";
+};
+/** `w:tblPr` children a fixture can author, each named after the element. */
+type TableProperties = {
+  /** `w:tblStyle`. */
+  styleId?: string;
+  /** `w:tblW`. */
+  width?: {
+    value: number;
+    type: "auto" | "dxa" | "pct";
+  };
+  /** `w:jc` on the table. */
+  justification?: "left" | "center" | "right";
+  /** `w:tblInd` in twips. */
+  indent?: number;
+  /** `w:tblBorders`, single style on every side, in eighths of a point. */
+  borderSize?: number;
+  /** `w:shd` fill colour on the table, as six hex digits. */
+  shadingFill?: string;
+  /** `w:tblLayout`. */
+  layout?: "fixed" | "autofit";
+  /** `w:tblCellMar`, the same margin on all four sides, in twips. */
+  cellMargin?: number;
+  /** `w:tblLook` value, as four hex digits. */
+  look?: string;
+};
 /**
  * One inline of a paragraph: plain text, or text carrying an external
  * hyperlink. A link is the case where a revision wrapper and the linked runs
@@ -35,7 +90,11 @@ type BodyItem = {
   paraId?: string;
 } | {
   kind: "table";
-  rows: readonly (readonly CellContent[])[];
+  rows: readonly TableRow[];
+  /** `w:tblPr` children, written in the order the schema requires. */
+  properties?: TableProperties;
+  /** `w:tblGrid` column widths, in twips. One per grid column. */
+  columnWidths?: readonly number[];
   /**
    * Rows a package hides with `w:hidden`. The snapshot skips their whole
    * subtree, so a document that has one is the case where the snapshot
@@ -53,4 +112,4 @@ type BodySequenceOptions = {
 };
 declare const buildBodySequenceDocx: (items: readonly BodyItem[], { header }?: BodySequenceOptions) => Promise<ArrayBuffer>;
 //#endregion
-export { BodyItem, BodySequenceOptions, CellContent, ParagraphInline, buildBodySequenceDocx };
+export { BodyItem, BodySequenceOptions, Cell, CellContent, CellProperties, ParagraphInline, TableProperties, TableRow, buildBodySequenceDocx };