@stll/folio-core 0.1.3 → 0.3.0

package/dist/prosemirror/plugins/templateDirectives.js

@@ -21,6 +21,45 @@ const directiveExpr = (meta) => {
 		default: return assertNever(meta);
 	}
 };
+/** Block-directive openers ({{#if}}, {{#each}}) that start a gutter-rail band. */
+const BLOCK_OPENER_KINDS = /* @__PURE__ */ new Set(["if", "each"]);
+/** Block-directive closers ({{/if}}, {{/each}}) that end a gutter-rail band. */
+const BLOCK_CLOSER_KINDS = /* @__PURE__ */ new Set(["endif", "endeach"]);
+/**
+* Nesting depth (0-based) of every block-directive opener, derived purely from
+* the scanned ranges by containment: walk the block openers/closers in document
+* order with a kind-aware stack, and record each opener's depth as the stack size
+* before it is pushed. Only `block:true` if/each pairs participate (inline markers
+* resolve within a paragraph and get no rail).
+*
+* Matching is kind-aware so a mid-edit / unbalanced template stays sane: a closer
+* pops the nearest opener of the *same family* ({{/if}} ⇒ {{#if}}, {{/each}} ⇒
+* {{#each}}), dropping any still-open openers nested above it; a closer with no
+* matching opener is ignored (never decrements a foreign block's depth). A blind
+* open/close counter would mis-count here: e.g. a stray {{/each}} between {{#if}}
+* and a nested {{#each}} would wrongly pull the inner {{#each}} back to depth 0.
+*
+* Keyed by the opener's `from` PM position, which is unique per marker, so the
+* overlay can look a band's depth up from its opener range. This is a pure
+* function of the ranges (no layout), hence unit-testable in isolation; the
+* overlay caps the *visual* indentation separately.
+*/
+const computeBlockDepths = (ranges) => {
+	const depths = /* @__PURE__ */ new Map();
+	const stack = [];
+	const ordered = ranges.filter((r) => r.block && (BLOCK_OPENER_KINDS.has(r.kind) || BLOCK_CLOSER_KINDS.has(r.kind))).slice().sort((a, b) => a.from - b.from);
+	for (const range of ordered) {
+		if (BLOCK_OPENER_KINDS.has(range.kind)) {
+			depths.set(range.from, stack.length);
+			stack.push(range.kind);
+			continue;
+		}
+		const wantOpener = range.kind === "endif" ? "if" : "each";
+		const matchIdx = stack.lastIndexOf(wantOpener);
+		if (matchIdx !== -1) stack.length = matchIdx;
+	}
+	return depths;
+};
 const scanDirectives = (doc) => {
 	const ranges = [];
 	for (const chunks of collectBlockChunks(doc)) {
@@ -64,4 +103,4 @@ const createTemplateDirectivesPlugin = ({ onRangesChange } = {}) => createDocSca
 });
 const getTemplateDirectives = (state) => getDocScanRanges(templateDirectivesKey, state);
 //#endregion
-export { createTemplateDirectivesPlugin, getTemplateDirectives, scanDirectives, templateDirectivesKey };
+export { computeBlockDepths, createTemplateDirectivesPlugin, getTemplateDirectives, scanDirectives, templateDirectivesKey };

package/dist/prosemirror/queries.d.ts

@@ -0,0 +1,46 @@
+import { Node } from "prosemirror-model";
+import { EditorView } from "prosemirror-view";
+
+//#region src/prosemirror/queries.d.ts
+/** A resolved PM position range — half-open `[from, to)` in PM coordinates. */
+type PmRange = {
+  from: number;
+  to: number;
+};
+/**
+ * Clamp a caller-supplied `[from, to]` range to a valid in-document span, or
+ * return `null` when it cannot be made valid: non-integer, negative, reversed
+ * (`to < from`), or a `from` past the document end. `to` is clamped to the
+ * document size so an out-of-range end never makes `doc.resolve()` throw a
+ * `RangeError`. Both adapters' `highlightRange` route raw caller positions
+ * through this so the no-op contract holds identically.
+ */
+declare function clampRangeToDoc(doc: Node, from: number, to: number): PmRange | null;
+/**
+ * Resolve a `commentId` to the PM position range its `comment` mark
+ * spans. Walks every inline node carrying a `comment` mark with the
+ * matching id and returns the union range (earliest start → latest end),
+ * so a comment whose range is interrupted by un-marked inline atoms still
+ * resolves to a single span. Returns `null` when the id is no longer
+ * present (the comment was deleted, or the marked text was removed) — the
+ * caller distinguishes "scrolled" from "stale" on that signal.
+ *
+ * Pure read over `view.state`; no dispatch.
+ */
+declare function findCommentRange(view: EditorView | null, commentId: number): PmRange | null;
+/**
+ * Resolve a tracked-change `revisionId` to the PM position range of its
+ * first site. Delegates to {@link extractTrackedChanges} so a coalesced
+ * revision (sites scattered across paragraphs, replace pairs, Enter
+ * chains) resolves to the same entry the sidebar shows. Matches on the
+ * entry's primary `revisionId`, its `insertionRevisionId`, or any
+ * `coalescedRevisionIds` member. Returns `null` when no entry carries the
+ * id (the change was accepted/rejected/deleted) — the caller uses this to
+ * show a "location no longer exists" affordance instead of a silent
+ * no-op.
+ *
+ * Pure read over `view.state`; no dispatch.
+ */
+declare function findChangeRange(view: EditorView | null, revisionId: number): PmRange | null;
+//#endregion
+export { PmRange, clampRangeToDoc, findChangeRange, findCommentRange };

package/dist/prosemirror/queries.js

@@ -0,0 +1,74 @@
+import { extractTrackedChanges } from "./utils/extractTrackedChanges.js";
+//#region src/prosemirror/queries.ts
+/**
+* Clamp a caller-supplied `[from, to]` range to a valid in-document span, or
+* return `null` when it cannot be made valid: non-integer, negative, reversed
+* (`to < from`), or a `from` past the document end. `to` is clamped to the
+* document size so an out-of-range end never makes `doc.resolve()` throw a
+* `RangeError`. Both adapters' `highlightRange` route raw caller positions
+* through this so the no-op contract holds identically.
+*/
+function clampRangeToDoc(doc, from, to) {
+	if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from) return null;
+	const max = doc.content.size;
+	if (from > max) return null;
+	return {
+		from,
+		to: Math.min(to, max)
+	};
+}
+/**
+* Resolve a `commentId` to the PM position range its `comment` mark
+* spans. Walks every inline node carrying a `comment` mark with the
+* matching id and returns the union range (earliest start → latest end),
+* so a comment whose range is interrupted by un-marked inline atoms still
+* resolves to a single span. Returns `null` when the id is no longer
+* present (the comment was deleted, or the marked text was removed) — the
+* caller distinguishes "scrolled" from "stale" on that signal.
+*
+* Pure read over `view.state`; no dispatch.
+*/
+function findCommentRange(view, commentId) {
+	if (!view) return null;
+	const commentType = view.state.schema.marks["comment"];
+	if (!commentType) return null;
+	let from = Infinity;
+	let to = -Infinity;
+	view.state.doc.descendants((node, pos) => {
+		if (!node.isInline) return;
+		for (const mark of node.marks) if (mark.type === commentType && mark.attrs["commentId"] === commentId) {
+			from = Math.min(from, pos);
+			to = Math.max(to, pos + node.nodeSize);
+		}
+	});
+	if (to < 0) return null;
+	return {
+		from,
+		to
+	};
+}
+/**
+* Resolve a tracked-change `revisionId` to the PM position range of its
+* first site. Delegates to {@link extractTrackedChanges} so a coalesced
+* revision (sites scattered across paragraphs, replace pairs, Enter
+* chains) resolves to the same entry the sidebar shows. Matches on the
+* entry's primary `revisionId`, its `insertionRevisionId`, or any
+* `coalescedRevisionIds` member. Returns `null` when no entry carries the
+* id (the change was accepted/rejected/deleted) — the caller uses this to
+* show a "location no longer exists" affordance instead of a silent
+* no-op.
+*
+* Pure read over `view.state`; no dispatch.
+*/
+function findChangeRange(view, revisionId) {
+	if (!view) return null;
+	const { entries } = extractTrackedChanges(view.state);
+	const entry = entries.find((e) => e.revisionId === revisionId || e.insertionRevisionId === revisionId || e.coalescedRevisionIds?.includes(revisionId));
+	if (!entry) return null;
+	return {
+		from: entry.from,
+		to: entry.to
+	};
+}
+//#endregion
+export { clampRangeToDoc, findChangeRange, findCommentRange };

package/dist/prosemirror/styles/styleResolver.d.ts

@@ -8,6 +8,22 @@ type ResolvedParagraphStyle = {
   /** Paragraph formatting (alignment, spacing, indentation, etc.) */paragraphFormatting?: document_d_exports.ParagraphFormatting; /** Default run formatting from the style */
   runFormatting?: document_d_exports.TextFormatting;
 };
+/**
+ * Paragraph-spacing fields sourced from the table style enclosing a cell
+ * paragraph: the table style's own `w:pPr`, then the applicable
+ * `w:tblStylePr` conditional region's `w:pPr` layered on top (already merged
+ * by the caller — see `resolveTableBaseStyle`/`resolveTableStyleConditional`
+ * in toProseDoc.ts).
+ *
+ * Deliberately narrower than the full {@link ParagraphFormatting}: this is
+ * the layer-2 overlay described on {@link StyleResolver.resolveParagraphStyleInTable}
+ * and is scoped to the spacing fields responsible for folio's table-row
+ * height bug (table styles like Word's `TableGrid` zero these out relative
+ * to `docDefaults`). Alignment, indentation, borders, etc. are out of scope
+ * here — applying the whole `pPr` would risk regressing unrelated cell
+ * layout that isn't part of this fix.
+ */
+type TableCellParagraphSpacingOverlay = Pick<document_d_exports.ParagraphFormatting, "spaceBefore" | "spaceAfter" | "lineSpacing" | "lineSpacingRule" | "contextualSpacing">;
 /**
  * StyleResolver provides efficient access to resolved style properties
  */
@@ -33,6 +49,32 @@ declare class StyleResolver {
    * @returns Resolved paragraph and run formatting
    */
   resolveParagraphStyle(styleId: string | undefined | null): ResolvedParagraphStyle;
+  /**
+   * Resolve paragraph style properties for a paragraph inside a table cell,
+   * layering the enclosing table style's paragraph-spacing fields into the
+   * cascade between docDefaults and the paragraph's own style chain.
+   *
+   * Per ECMA-376 §17.7.2, a cell paragraph's properties resolve in this
+   * order (later wins):
+   *   1. docDefaults (`w:pPrDefault`)
+   *   2. the enclosing table style's `w:pPr` (`tableParagraphOverlay`, here)
+   *   3. the paragraph's own style chain (`w:pStyle` + `basedOn` ancestors)
+   *   4. direct formatting on the paragraph (`w:pPr`)
+   *
+   * Layer 4 is applied by the caller (`paragraphFormattingToAttrs`), which
+   * already prefers the paragraph's direct formatting over this method's
+   * result. Layer 3 is applied below, after the overlay, so an explicit
+   * paragraph style still wins over the table for any field it sets.
+   *
+   * @param styleId - The paragraph's style ID (e.g., 'Heading1', 'Normal')
+   * @param tableParagraphOverlay - Paragraph-spacing fields from the
+   *   enclosing table style (base `pPr` merged with the applicable
+   *   conditional region), or `undefined` when the paragraph isn't in a
+   *   table cell, the table has no style, or the style sets no spacing.
+   * @returns Resolved paragraph and run formatting
+   */
+  resolveParagraphStyleInTable(styleId: string | undefined | null, tableParagraphOverlay: TableCellParagraphSpacingOverlay | undefined): ResolvedParagraphStyle;
+  private resolveParagraphStyleCascade;
   /**
    * Resolve the style applied to the paragraph that follows one styled with
    * `styleId` when the user presses Enter (OOXML `w:next`, §17.7.4.10).
@@ -91,4 +133,4 @@ declare class StyleResolver {
  */
 declare function createStyleResolver(styleDefinitions: document_d_exports.StyleDefinitions | undefined): StyleResolver;
 //#endregion
-export { ResolvedParagraphStyle, StyleResolver, createStyleResolver };
+export { ResolvedParagraphStyle, StyleResolver, TableCellParagraphSpacingOverlay, createStyleResolver };

package/dist/prosemirror/styles/styleResolver.js

@@ -70,9 +70,43 @@ var StyleResolver = class {
 	* @returns Resolved paragraph and run formatting
 	*/
 	resolveParagraphStyle(styleId) {
+		return this.resolveParagraphStyleCascade(styleId, void 0);
+	}
+	/**
+	* Resolve paragraph style properties for a paragraph inside a table cell,
+	* layering the enclosing table style's paragraph-spacing fields into the
+	* cascade between docDefaults and the paragraph's own style chain.
+	*
+	* Per ECMA-376 §17.7.2, a cell paragraph's properties resolve in this
+	* order (later wins):
+	*   1. docDefaults (`w:pPrDefault`)
+	*   2. the enclosing table style's `w:pPr` (`tableParagraphOverlay`, here)
+	*   3. the paragraph's own style chain (`w:pStyle` + `basedOn` ancestors)
+	*   4. direct formatting on the paragraph (`w:pPr`)
+	*
+	* Layer 4 is applied by the caller (`paragraphFormattingToAttrs`), which
+	* already prefers the paragraph's direct formatting over this method's
+	* result. Layer 3 is applied below, after the overlay, so an explicit
+	* paragraph style still wins over the table for any field it sets.
+	*
+	* @param styleId - The paragraph's style ID (e.g., 'Heading1', 'Normal')
+	* @param tableParagraphOverlay - Paragraph-spacing fields from the
+	*   enclosing table style (base `pPr` merged with the applicable
+	*   conditional region), or `undefined` when the paragraph isn't in a
+	*   table cell, the table has no style, or the style sets no spacing.
+	* @returns Resolved paragraph and run formatting
+	*/
+	resolveParagraphStyleInTable(styleId, tableParagraphOverlay) {
+		return this.resolveParagraphStyleCascade(styleId, tableParagraphOverlay);
+	}
+	resolveParagraphStyleCascade(styleId, tableParagraphOverlay) {
 		const result = {};
 		if (this.docDefaults?.pPr) result.paragraphFormatting = { ...this.docDefaults.pPr };
 		if (this.docDefaults?.rPr) result.runFormatting = { ...this.docDefaults.rPr };
+		if (tableParagraphOverlay) {
+			const merged = mergeParagraphFormatting(result.paragraphFormatting, tableParagraphOverlay);
+			if (merged !== void 0) result.paragraphFormatting = merged;
+		}
 		if (!styleId) {
 			if (this.defaultParagraphStyle) this.mergeStyleIntoResult(result, this.defaultParagraphStyle);
 			return result;

package/dist/prosemirror/tableResize.d.ts

@@ -0,0 +1,49 @@
+import { EditorView } from "prosemirror-view";
+
+//#region src/prosemirror/tableResize.d.ts
+/** 1px ≈ 15 twips at 96dpi (20 twips/pt × 72pt/in ÷ 96px/in). */
+declare const TWIPS_PER_PIXEL = 15;
+/** Minimum column width (~0.2"). */
+declare const MIN_CELL_WIDTH_TWIPS = 300;
+/** Minimum row height (~0.14"). */
+declare const MIN_ROW_HEIGHT_TWIPS = 200;
+/** Read the [left, right] column widths at `colIndex` in the table starting at `pmStart`. */
+declare function readColumnWidths(view: EditorView, pmStart: number, colIndex: number): {
+  left: number;
+  right: number;
+} | null;
+/**
+ * Read the row height (in twips) for `rowIndex` in the table starting at
+ * `pmStart`. Returns null if the row has no explicit height — the caller
+ * can fall back to measuring the rendered DOM cell.
+ */
+declare function readRowHeight(view: EditorView, pmStart: number, rowIndex: number): number | null;
+/** Read the last-column width (the one being resized from the table's right edge). */
+declare function readColumnWidthAt(view: EditorView, pmStart: number, colIndex: number): number | null;
+/**
+ * Bake a column-resize into the PM doc: update the table's `columnWidths`
+ * attr and every cell at `colIdx` / `colIdx + 1` in every row.
+ */
+declare function commitColumnResize(view: EditorView, opts: {
+  pmStart: number;
+  colIdx: number;
+  newLeft: number;
+  newRight: number;
+}): void;
+/** Bake a row-resize into the PM doc: update the target row's `height` + `heightRule`. */
+declare function commitRowResize(view: EditorView, opts: {
+  pmStart: number;
+  rowIdx: number;
+  newHeight: number;
+}): void;
+/**
+ * Bake a right-edge resize into the PM doc: grow only the last column.
+ * Updates `columnWidths[colIdx]` and the cell at `colIdx` in every row.
+ */
+declare function commitRightEdgeResize(view: EditorView, opts: {
+  pmStart: number;
+  colIdx: number;
+  newWidth: number;
+}): void;
+//#endregion
+export { MIN_CELL_WIDTH_TWIPS, MIN_ROW_HEIGHT_TWIPS, TWIPS_PER_PIXEL, commitColumnResize, commitRightEdgeResize, commitRowResize, readColumnWidthAt, readColumnWidths, readRowHeight };

package/dist/prosemirror/tableResize.js

@@ -0,0 +1,162 @@
+//#region src/prosemirror/tableResize.ts
+/** 1px ≈ 15 twips at 96dpi (20 twips/pt × 72pt/in ÷ 96px/in). */
+const TWIPS_PER_PIXEL = 15;
+/** Minimum column width (~0.2"). */
+const MIN_CELL_WIDTH_TWIPS = 300;
+/** Minimum row height (~0.14"). */
+const MIN_ROW_HEIGHT_TWIPS = 200;
+/** Walk up from `pmStart + 1` to find the enclosing table node. */
+function findTableAt(view, pmStart) {
+	try {
+		const $pos = view.state.doc.resolve(pmStart + 1);
+		for (let d = $pos.depth; d >= 0; d--) {
+			const node = $pos.node(d);
+			if (node.type.name === "table") return {
+				node,
+				tablePos: $pos.before(d)
+			};
+		}
+	} catch {}
+	return null;
+}
+/** Read the [left, right] column widths at `colIndex` in the table starting at `pmStart`. */
+function readColumnWidths(view, pmStart, colIndex) {
+	const found = findTableAt(view, pmStart);
+	if (!found) return null;
+	const widths = found.node.attrs["columnWidths"];
+	if (!widths) return null;
+	const left = widths[colIndex];
+	const right = widths[colIndex + 1];
+	if (left === void 0 || right === void 0) return null;
+	return {
+		left,
+		right
+	};
+}
+/**
+* Read the row height (in twips) for `rowIndex` in the table starting at
+* `pmStart`. Returns null if the row has no explicit height — the caller
+* can fall back to measuring the rendered DOM cell.
+*/
+function readRowHeight(view, pmStart, rowIndex) {
+	const found = findTableAt(view, pmStart);
+	if (!found) return null;
+	let rowHeight = null;
+	let idx = 0;
+	found.node.forEach((child) => {
+		if (idx === rowIndex) {
+			const h = child.attrs["height"];
+			if (h) rowHeight = h;
+		}
+		idx++;
+	});
+	return rowHeight;
+}
+/** Read the last-column width (the one being resized from the table's right edge). */
+function readColumnWidthAt(view, pmStart, colIndex) {
+	const found = findTableAt(view, pmStart);
+	if (!found) return null;
+	const widths = found.node.attrs["columnWidths"];
+	if (!widths) return null;
+	const width = widths[colIndex];
+	if (width === void 0) return null;
+	return width;
+}
+/**
+* Bake a column-resize into the PM doc: update the table's `columnWidths`
+* attr and every cell at `colIdx` / `colIdx + 1` in every row.
+*/
+function commitColumnResize(view, opts) {
+	const { pmStart, colIdx, newLeft, newRight } = opts;
+	const found = findTableAt(view, pmStart);
+	if (!found) return;
+	const { node, tablePos } = found;
+	const tr = view.state.tr;
+	const widths = [...node.attrs["columnWidths"] ?? []];
+	widths[colIdx] = newLeft;
+	widths[colIdx + 1] = newRight;
+	tr.setNodeMarkup(tablePos, void 0, {
+		...node.attrs,
+		columnWidths: widths,
+		tableLayout: "fixed"
+	});
+	let rowOffset = tablePos + 1;
+	node.forEach((row) => {
+		let cellOffset = rowOffset + 1;
+		let cellColIdx = 0;
+		row.forEach((cell) => {
+			const colspan = cell.attrs["colspan"] || 1;
+			if (cellColIdx === colIdx || cellColIdx === colIdx + 1) {
+				const newWidth = cellColIdx === colIdx ? newLeft : newRight;
+				tr.setNodeMarkup(tr.mapping.map(cellOffset), void 0, {
+					...cell.attrs,
+					width: newWidth,
+					widthType: "dxa",
+					colwidth: null
+				});
+			}
+			cellOffset += cell.nodeSize;
+			cellColIdx += colspan;
+		});
+		rowOffset += row.nodeSize;
+	});
+	view.dispatch(tr);
+}
+/** Bake a row-resize into the PM doc: update the target row's `height` + `heightRule`. */
+function commitRowResize(view, opts) {
+	const { pmStart, rowIdx, newHeight } = opts;
+	const found = findTableAt(view, pmStart);
+	if (!found) return;
+	const { node, tablePos } = found;
+	const tr = view.state.tr;
+	let rowOffset = tablePos + 1;
+	let idx = 0;
+	node.forEach((row) => {
+		if (idx === rowIdx) tr.setNodeMarkup(tr.mapping.map(rowOffset), void 0, {
+			...row.attrs,
+			height: newHeight,
+			heightRule: "atLeast"
+		});
+		rowOffset += row.nodeSize;
+		idx++;
+	});
+	view.dispatch(tr);
+}
+/**
+* Bake a right-edge resize into the PM doc: grow only the last column.
+* Updates `columnWidths[colIdx]` and the cell at `colIdx` in every row.
+*/
+function commitRightEdgeResize(view, opts) {
+	const { pmStart, colIdx, newWidth } = opts;
+	const found = findTableAt(view, pmStart);
+	if (!found) return;
+	const { node, tablePos } = found;
+	const tr = view.state.tr;
+	const widths = [...node.attrs["columnWidths"] ?? []];
+	widths[colIdx] = newWidth;
+	tr.setNodeMarkup(tablePos, void 0, {
+		...node.attrs,
+		columnWidths: widths,
+		tableLayout: "fixed"
+	});
+	let rowOffset = tablePos + 1;
+	node.forEach((row) => {
+		let cellOffset = rowOffset + 1;
+		let cellColIdx = 0;
+		row.forEach((cell) => {
+			const colspan = cell.attrs["colspan"] || 1;
+			if (cellColIdx === colIdx) tr.setNodeMarkup(tr.mapping.map(cellOffset), void 0, {
+				...cell.attrs,
+				width: newWidth,
+				widthType: "dxa",
+				colwidth: null
+			});
+			cellOffset += cell.nodeSize;
+			cellColIdx += colspan;
+		});
+		rowOffset += row.nodeSize;
+	});
+	view.dispatch(tr);
+}
+//#endregion
+export { MIN_CELL_WIDTH_TWIPS, MIN_ROW_HEIGHT_TWIPS, TWIPS_PER_PIXEL, commitColumnResize, commitRightEdgeResize, commitRowResize, readColumnWidthAt, readColumnWidths, readRowHeight };

package/dist/prosemirror/utils/extractTrackedChanges.d.ts

@@ -0,0 +1,106 @@
+import { EditorState } from "prosemirror-state";
+
+//#region src/prosemirror/utils/extractTrackedChanges.d.ts
+/**
+ * One tracked change surfaced by {@link extractTrackedChanges}. Each entry
+ * groups all sites of one revision into a single row that the sidebar
+ * renders as one card.
+ *
+ * @public
+ */
+type TrackedChangeEntry = {
+  /**
+   * Revision shape. Inline shapes (`insertion`, `deletion`, `replacement`)
+   * wrap text runs; the rest are structural revisions on node attrs.
+   *
+   * - `insertion` — text was added (`<w:ins>`).
+   * - `deletion` — text was struck through but not removed (`<w:del>`).
+   * - `replacement` — a deletion + insertion by the same author at the
+   *   same position+time; sidebar shows one combined card. `deletedText`
+   *   and `insertionRevisionId` are set on this variant.
+   * - `paragraphMarkInsertion` / `paragraphMarkDeletion` — Enter /
+   *   Backspace produced a tracked paragraph break (`<w:pPr><w:rPr><w:ins/>` /
+   *   `<w:del/>`).
+   * - `paragraphPropertiesChanged` — formatting (alignment, spacing,
+   *   etc.) on the paragraph was changed (`<w:pPrChange>`).
+   * - `rowInserted` / `rowDeleted` / `rowPropertiesChanged` — table
+   *   row authored / removed / formatted (`<w:trPr><w:ins/>` / `<w:del/>`
+   *   / `<w:trPrChange>`).
+   * - `cellInserted` / `cellDeleted` / `cellMerged` /
+   *   `cellPropertiesChanged` — per-cell revisions
+   *   (`<w:cellIns>` / `<w:cellDel>` / `<w:cellMerge>` / `<w:tcPrChange>`).
+   * - `tablePropertiesChanged` — table-level formatting
+   *   (`<w:tblPrChange>`).
+   */
+  type: "insertion" | "deletion" | "replacement" | "paragraphMarkInsertion" | "paragraphMarkDeletion" | "paragraphPropertiesChanged" | "rowInserted" | "rowDeleted" | "rowPropertiesChanged" | "cellInserted" | "cellDeleted" | "cellMerged" | "cellPropertiesChanged" | "tableInserted" | "tableDeleted" | "tablePropertiesChanged";
+  /**
+   * Affected text. For inline types this is the run's text; for
+   * structural types it's the surrounding paragraph / cell content
+   * (truncated by the sidebar before display).
+   */
+  text: string;
+  /**
+   * Only set when `type === 'replacement'` — the text the user removed.
+   * The inserted text lives in {@link TrackedChangeEntry.text}.
+   */
+  deletedText?: string | undefined; /** Author that minted the revision (`w:author`). */
+  author: string; /** ISO timestamp the revision was minted (`w:date`). May be undefined for legacy imports. */
+  date?: string | undefined;
+  /**
+   * Document position where the revision starts. For inline types this
+   * is the start of the marked text run; for structural types it's the
+   * containing paragraph / row / cell / table node's start position.
+   */
+  from: number;
+  /**
+   * Document position where the revision ends. For inline coalesced
+   * runs that span multiple paragraphs, this is the END position of the
+   * LAST run in the group; the intervening structural positions are not
+   * preserved.
+   */
+  to: number; /** The `w:id` of the revision. */
+  revisionId: number;
+  /**
+   * Only set when `type === 'replacement'` — the insertion half carries
+   * a DIFFERENT `w:id` from the deletion (sharing would trip the OOXML
+   * move-pair serializer).
+   */
+  insertionRevisionId?: number | undefined;
+  /**
+   * Extra `w:id`s that map to the same logical revision as this card.
+   * Populated when the extractor coalesces a burst of distinct ids by
+   * (author, date) — e.g. a foreign document where the source editor
+   * minted a fresh id per atomic edit.
+   */
+  coalescedRevisionIds?: number[] | undefined;
+};
+/**
+ * Output of {@link extractTrackedChanges}.
+ *
+ * @public
+ */
+type TrackedChangesResult = {
+  /** Tracked-change entries, sorted by document position, with adjacent same-revision entries merged. */entries: TrackedChangeEntry[];
+  /**
+   * Map of `commentId -> revisionId` for comments whose range overlaps a tracked-change mark.
+   * Consumers (DocxEditor's threading effect) use this to thread comments under their tracked change.
+   */
+  commentToRevision: Map<number, number>;
+};
+/**
+ * Walk the PM doc and extract every tracked change as a flat list of
+ * `TrackedChangeEntry` plus a comment→revision overlap map. Adjacent
+ * inline marks coalesce by `(type, revisionId, author, date)`; a
+ * deletion immediately followed by an insertion (same author + same
+ * date) collapses into a single `replacement` entry; paragraph-mark
+ * cards (`paragraphMarkInsertion` / `paragraphMarkDeletion`) are
+ * hidden when an inline entry already covers their revision triple
+ * (one Accept clears every site of one conceptual change).
+ *
+ * Pure and deterministic. Returns `EMPTY_RESULT` on null state.
+ *
+ * @public
+ */
+declare function extractTrackedChanges(state: EditorState | null): TrackedChangesResult;
+//#endregion
+export { TrackedChangeEntry, TrackedChangesResult, extractTrackedChanges };