@stll/folio-core 0.4.0 → 0.5.0

package/dist/utils/clipboard.js

@@ -86,7 +86,7 @@ async function copyRuns(runs, options = {}) {
 	try {
 		return await writeToClipboard(runsToClipboardContent(runs, includeFormatting));
 	} catch (error) {
-		onError?.(error);
+		onError?.(error instanceof Error ? error : new Error(String(error)));
 		return false;
 	}
 }
@@ -98,7 +98,7 @@ async function copyParagraphs(paragraphs, options = {}) {
 	try {
 		return await writeToClipboard(paragraphsToClipboardContent(paragraphs, includeFormatting));
 	} catch (error) {
-		onError?.(error);
+		onError?.(error instanceof Error ? error : new Error(String(error)));
 		return false;
 	}
 }
@@ -170,7 +170,7 @@ async function readFromClipboard(options = {}) {
 	try {
 		return await parseClipboardItems(await navigator.clipboard.read(), cleanWordFormatting);
 	} catch (error) {
-		onError?.(error);
+		onError?.(error instanceof Error ? error : new Error(String(error)));
 		return null;
 	}
 }

package/dist/utils/fontLoader.js

@@ -17,6 +17,8 @@ let isLoadingAny = false;
 * this map is used for font availability checks and preloading.
 */
 const FONT_MAPPING = {
+	Aptos: "Source Sans 3",
+	"Aptos Display": "Source Sans 3",
 	Calibri: "Carlito",
 	Cambria: "Caladea",
 	Arial: "Arimo",
@@ -38,6 +40,7 @@ const BUNDLED_FONTS = /* @__PURE__ */ new Set([
 	"Arimo",
 	"Tinos",
 	"Cousine",
+	"Source Sans 3",
 	"Calibri",
 	"Cambria",
 	"Arial",

package/dist/utils/fontResolver.js

@@ -44,6 +44,11 @@ const JP_MEASURED_LINE_HEIGHT = {
 	ratio: 1.303,
 	note: "Measured against real Word: 10.5pt Japanese body, non-grid section, renders at 13.68pt line pitch."
 };
+const APTOS_MEASURED_LINE_HEIGHT = {
+	source: "measured",
+	ratio: 1.2207,
+	note: "Measured against real Word: 11pt Aptos body, non-grid section, renders at 13.43pt line pitch."
+};
 /**
 * Mapping of common DOCX fonts to Google Fonts equivalents
 *
@@ -59,6 +64,30 @@ const JP_MEASURED_LINE_HEIGHT = {
 * ratios carried over unchanged, pending measurement.
 */
 const FONT_MAPPINGS = {
+	aptos: {
+		googleFont: "Source Sans 3",
+		category: "sans-serif",
+		fallbackStack: [
+			"Aptos",
+			"Source Sans 3",
+			"Arial",
+			"Helvetica",
+			"sans-serif"
+		],
+		singleLineRatio: singleLineRatioOf(APTOS_MEASURED_LINE_HEIGHT)
+	},
+	"aptos display": {
+		googleFont: "Source Sans 3",
+		category: "sans-serif",
+		fallbackStack: [
+			"Aptos Display",
+			"Source Sans 3",
+			"Arial",
+			"Helvetica",
+			"sans-serif"
+		],
+		singleLineRatio: singleLineRatioOf(APTOS_MEASURED_LINE_HEIGHT)
+	},
 	calibri: {
 		googleFont: "Carlito",
 		category: "sans-serif",
@@ -213,6 +242,23 @@ const FONT_MAPPINGS = {
 			unitsPerEm: 2048
 		})
 	},
+	montserrat: {
+		googleFont: "Montserrat",
+		category: "sans-serif",
+		fallbackStack: [
+			"Montserrat",
+			"Arial",
+			"Helvetica",
+			"sans-serif"
+		],
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 968,
+			hheaDescent: -251,
+			hheaLineGap: 0,
+			unitsPerEm: 1e3
+		})
+	},
 	"trebuchet ms": {
 		googleFont: "Fira Sans",
 		category: "sans-serif",
@@ -759,7 +805,8 @@ function resolveFontFamily(docxFontName) {
 			singleLineRatio: mapping.singleLineRatio
 		};
 	}
-	const defaultFallback = DEFAULT_FALLBACKS[detectFontCategory(docxFontName)];
+	const category = detectFontCategory(docxFontName);
+	const defaultFallback = DEFAULT_FALLBACKS[category];
 	return {
 		googleFont: null,
 		cssFallback: withArabicFallback(`${quoteFontName(docxFontName)}, ${defaultFallback}`),

package/dist/utils/zoom.d.ts

@@ -0,0 +1,21 @@
+//#region src/utils/zoom.d.ts
+/**
+ * Canonical zoom limits shared by every folio adapter (React, Vue, ...).
+ *
+ * Adapters must source their zoom range from here rather than hard-coding their
+ * own, so the reachable zoom span stays identical across framework hosts.
+ * Historically React clamped 0.25-4x while Vue clamped 0.5-2x; this module is
+ * the single source of truth that keeps them from drifting again.
+ *
+ * Note: the discrete zoom-level menu each adapter shows in its toolbar dropdown
+ * is a separate, deliberately curated subset (50-200%); it is not derived from
+ * these limits.
+ */
+/** Minimum reachable zoom level (25%). */
+declare const ZOOM_MIN = 0.25;
+/** Maximum reachable zoom level (400%). */
+declare const ZOOM_MAX = 4;
+/** Step applied per zoom-in / zoom-out action and per keyboard shortcut. */
+declare const ZOOM_STEP = 0.1;
+//#endregion
+export { ZOOM_MAX, ZOOM_MIN, ZOOM_STEP };

package/dist/utils/zoom.js

@@ -0,0 +1,21 @@
+//#region src/utils/zoom.ts
+/**
+* Canonical zoom limits shared by every folio adapter (React, Vue, ...).
+*
+* Adapters must source their zoom range from here rather than hard-coding their
+* own, so the reachable zoom span stays identical across framework hosts.
+* Historically React clamped 0.25-4x while Vue clamped 0.5-2x; this module is
+* the single source of truth that keeps them from drifting again.
+*
+* Note: the discrete zoom-level menu each adapter shows in its toolbar dropdown
+* is a separate, deliberately curated subset (50-200%); it is not derived from
+* these limits.
+*/
+/** Minimum reachable zoom level (25%). */
+const ZOOM_MIN = .25;
+/** Maximum reachable zoom level (400%). */
+const ZOOM_MAX = 4;
+/** Step applied per zoom-in / zoom-out action and per keyboard shortcut. */
+const ZOOM_STEP = .1;
+//#endregion
+export { ZOOM_MAX, ZOOM_MIN, ZOOM_STEP };

package/dist/version-comparison.d.ts

@@ -0,0 +1,92 @@
+import { FolioAIBlock } from "./ai-edits/types.js";
+import { WordDiffSegment } from "./ai-edits/word-diff.js";
+
+//#region src/version-comparison.d.ts
+/** One word-level diff segment within a `modified` block. Mirrors {@link WordDiffSegment}. */
+type FolioVersionDiffSegment = WordDiffSegment;
+/** Run-level formatting properties compared for `formatChanged` detection. */
+declare const FORMAT_PROPERTIES: readonly ["bold", "italic", "underline", "strike", "fontFamily", "fontSizePt", "color"];
+/** A run-level formatting property that can differ in a `formatChanged` block. */
+type FolioFormatProperty = (typeof FORMAT_PROPERTIES)[number];
+/** One block-level change between two document versions, in revised-side document order. */
+type FolioBlockDiff = {
+  type: "added";
+  blockId: string;
+  kind: string;
+  text: string;
+} | {
+  type: "deleted";
+  blockId: string;
+  kind: string;
+  text: string;
+} | {
+  type: "modified";
+  blockId: string;
+  kind: string;
+  segments: FolioVersionDiffSegment[];
+} | {
+  type: "formatChanged";
+  blockId: string;
+  kind: string;
+  text: string;
+  changedProperties: FolioFormatProperty[];
+} | {
+  type: "movedFrom";
+  blockId: string;
+  kind: string;
+  text: string;
+  moveGroupId: number;
+} | {
+  type: "movedTo";
+  blockId: string;
+  kind: string;
+  text: string;
+  moveGroupId: number;
+};
+/** Result of {@link compareDocxVersions}. */
+type FolioVersionDiff = {
+  /** Every changed block, in revised-side document order (deletions and move sources slotted where they sat). */changes: FolioBlockDiff[]; /** Counts across every paired/unpaired block, including the unchanged blocks `changes` omits. `moved` counts pairs, not entries. */
+  summaryCounts: {
+    added: number;
+    deleted: number;
+    modified: number;
+    formatChanged: number;
+    moved: number;
+    unchanged: number;
+  };
+};
+/** True when an `unpairedBaseCount * unpairedRevisedCount` LCS table would exceed {@link MAX_LCS_CELLS}. */
+declare const exceedsLcsBudget: (unpairedBaseCount: number, unpairedRevisedCount: number) => boolean;
+/**
+ * One step of a completed alignment, in revised-side document order with
+ * base-only blocks slotted where they sat. `pair` events cover pass 1/2
+ * anchors and pass 3's positional zip alike; whether the pair is unchanged,
+ * modified, or format-changed is the consumer's call.
+ */
+type FolioAlignedBlockEvent = {
+  type: "pair";
+  baseBlock: FolioAIBlock;
+  revisedBlock: FolioAIBlock;
+} | {
+  type: "baseOnly";
+  block: FolioAIBlock;
+} | {
+  type: "revisedOnly";
+  block: FolioAIBlock;
+};
+/**
+ * Run the three-pass alignment (see the module doc comment) over two block
+ * snapshots and flatten it into an ordered event stream. Shared by
+ * {@link compareDocxVersions} and the redline generator so both interpret
+ * one document walk instead of re-deriving it.
+ */
+declare const alignFolioBlocks: (baseBlocks: readonly FolioAIBlock[], revisedBlocks: readonly FolioAIBlock[]) => FolioAlignedBlockEvent[];
+/**
+ * Compare two `.docx` buffers and return a structured, block-level diff.
+ * See the module doc comment for the as-accepted comparison semantics, the
+ * three-pass alignment algorithm, move detection, and format-only change
+ * detection.
+ */
+declare const compareDocxVersions: (base: ArrayBuffer, revised: ArrayBuffer) => Promise<FolioVersionDiff>;
+//#endregion
+export { FolioAlignedBlockEvent, FolioBlockDiff, FolioFormatProperty, FolioVersionDiff, FolioVersionDiffSegment, alignFolioBlocks, compareDocxVersions, exceedsLcsBudget };

package/dist/version-comparison.js

@@ -0,0 +1,436 @@
+import { getFolioParaIdFromBlockId } from "./types/block-id.js";
+import { diffWordSegments } from "./ai-edits/word-diff.js";
+import { FolioDocxReviewer } from "./ai-edits/headless.js";
+//#region src/version-comparison.ts
+/**
+* Document version-diff engine: compare two `.docx` buffers block by block
+* and produce a structured, LLM-summarizable diff.
+*
+* Both buffers are parsed through {@link FolioDocxReviewer} — the same
+* headless parsing + clean-text path `read_document` / `read_changes` use —
+* so the comparison runs over each document's AS-ACCEPTED view: any pending
+* tracked changes already present in EITHER buffer count as applied before
+* the two are compared. Two documents that agree once their own pending
+* redlines are accepted report as unchanged, even if the underlying
+* tracked-change history differs.
+*
+* ## Alignment
+*
+* Blocks are paired across the two snapshots in three passes, each only
+* considering blocks the previous pass left unpaired:
+*
+* 1. **Stable-id pairing.** Blocks whose ids are equal AND not a `seq-NNNN`
+*    positional fallback ({@link getFolioParaIdFromBlockId} returns non-null)
+*    are paired directly. This covers both id shapes a snapshot can carry:
+*    - A real Word `w14:paraId`: stable identity, independent of text — an
+*      equal-id pair with different text is a genuine edit (`modified`).
+*    - `FolioDocxReviewer`'s deterministic fallback id (assigned when the
+*      source paragraph has no `w14:paraId`), which hashes the paragraph's
+*      TEXT plus its document ordinal. It is structurally indistinguishable
+*      from a real paraId ({@link getFolioParaIdFromBlockId} can't tell them
+*      apart), but pairing on equality is still safe: two equal deterministic
+*      ids necessarily came from identical text at an identical ordinal, so
+*      the pair is always text-equal (`unchanged`) — never a false
+*      `modified`. What it can't do is FIND a paragraph whose ordinal shifted
+*      (an insertion/deletion earlier in the document) even though its text
+*      is unchanged: that pair has two different fallback ids and falls
+*      through to pass 2.
+* 2. **Exact-text pairing.** An order-preserving LCS over remaining blocks,
+*    matched by exact text equality. This is what recovers same-text blocks
+*    that pass 1 missed because a fallback id shifted with the ordinal. Its
+*    O(m·n) table is skipped ({@link exceedsLcsBudget}) once the unpaired
+*    counts on both sides would exceed a fixed cell budget, so a document
+*    with few/no stable ids can't force a quadratic-sized allocation; those
+*    blocks fall through to pass 3 instead.
+* 3. **Positional fallback.** Whatever a monotonicity filter leaves
+*    unpaired is split into the gaps between anchored pairs (pass 1 + 2,
+*    time-ordered); within each gap the shorter side is zipped positionally
+*    against the longer one (`modified`), and any excess on either side is
+*    reported as `added` / `deleted`.
+*
+* The combined anchor set from passes 1 and 2 is re-filtered to the longest
+* increasing subsequence by revised-side index before pass 3 runs, so a
+* pathological crossing match (content reordered across versions) can't
+* produce an out-of-order gap — the alignment always walks both documents
+* forward.
+*
+* ## Move detection
+*
+* Relocated content would otherwise report as an unrelated `deleted` +
+* `added` pair (both order-preserving passes drop crossing matches by
+* design). A post-pass re-classifies such pairs: an `added` and a `deleted`
+* block with identical text and at least {@link MOVE_MINIMUM_WORD_COUNT}
+* words become `movedFrom` / `movedTo` entries sharing a `moveGroupId`. The
+* word-count floor keeps boilerplate one-liners ("Confidential", empty
+* headings) from pairing as spurious moves. Blocks a positional zip already
+* mis-paired as `modified` are out of this pass's reach — a known limitation
+* of the gap fallback, not of the move pass.
+*
+* ## Format-only changes
+*
+* A paired block whose text is byte-equal but whose run-level formatting
+* (bold, italic, underline, strike, font family, font size, color) differs
+* reports as `formatChanged` with the set of properties that differ, instead
+* of silently counting as `unchanged`. Detection walks the two blocks'
+* preview runs character-aligned; when a block carries non-text inline
+* content that makes the preview texts disagree, detection backs off to
+* `unchanged` rather than misattribute properties.
+*/
+/** Run-level formatting properties compared for `formatChanged` detection. */
+const FORMAT_PROPERTIES = [
+	"bold",
+	"italic",
+	"underline",
+	"strike",
+	"fontFamily",
+	"fontSizePt",
+	"color"
+];
+const isStableBlockId = (id) => getFolioParaIdFromBlockId(id) !== null;
+/**
+* Longest increasing subsequence by `revisedIndex`, assuming `pairs` is
+* already sorted by `baseIndex` ascending. Drops any pair that would make
+* the alignment walk backward in the revised document — the guard against
+* both id collisions (pass 1) and any crossing match (pass 1 + 2 combined).
+*/
+const longestIncreasingByRevisedIndex = (pairs) => {
+	if (pairs.length === 0) return [];
+	const lengths = new Int32Array(pairs.length).fill(1);
+	const predecessors = new Int32Array(pairs.length).fill(-1);
+	let bestEnd = 0;
+	for (let i = 0; i < pairs.length; i++) {
+		for (let j = 0; j < i; j++) {
+			const current = pairs[j];
+			const candidate = pairs[i];
+			if (!current || !candidate) continue;
+			if (current.revisedIndex < candidate.revisedIndex && (lengths[j] ?? 0) + 1 > (lengths[i] ?? 0)) {
+				lengths[i] = (lengths[j] ?? 0) + 1;
+				predecessors[i] = j;
+			}
+		}
+		if ((lengths[i] ?? 0) > (lengths[bestEnd] ?? 0)) bestEnd = i;
+	}
+	const ordered = [];
+	for (let cursor = bestEnd; cursor !== -1; cursor = predecessors[cursor] ?? -1) {
+		const pair = pairs[cursor];
+		if (pair) ordered.push(pair);
+	}
+	return ordered.toReversed();
+};
+/** Pass 1: pair blocks with equal, non-`seq-NNNN` ids. See the module doc comment. */
+const pairByStableId = (base, revised) => {
+	const revisedIndexById = /* @__PURE__ */ new Map();
+	revised.forEach((block, revisedIndex) => {
+		if (isStableBlockId(block.id)) revisedIndexById.set(block.id, revisedIndex);
+	});
+	const candidates = [];
+	base.forEach((block, baseIndex) => {
+		if (!isStableBlockId(block.id)) return;
+		const revisedIndex = revisedIndexById.get(block.id);
+		if (revisedIndex !== void 0) candidates.push({
+			baseIndex,
+			revisedIndex
+		});
+	});
+	return longestIncreasingByRevisedIndex(candidates);
+};
+/**
+* Cell budget for pass 2's O(m·n) exact-text LCS table (`dp` below allocates
+* `(m + 1) * (n + 1)` numbers). A document with no `w14:paraId`s — or an
+* adversarial one crafted to defeat pass 1 — can leave thousands of blocks
+* unpaired on both sides; without a cap, `pairByExactText` would allocate a
+* quadratic-sized table for it. Past this budget, {@link exceedsLcsBudget}
+* makes pass 2 back off entirely so alignment falls through to pass 3's
+* linear positional zip instead — pairing is less precise for these
+* degenerate inputs, but memory use stays bounded.
+*/
+const MAX_LCS_CELLS = 4e6;
+/** True when an `unpairedBaseCount * unpairedRevisedCount` LCS table would exceed {@link MAX_LCS_CELLS}. */
+const exceedsLcsBudget = (unpairedBaseCount, unpairedRevisedCount) => unpairedBaseCount * unpairedRevisedCount > MAX_LCS_CELLS;
+/** Pass 2: order-preserving LCS by exact text equality over the blocks pass 1 left unpaired. */
+const pairByExactText = (base, revised) => {
+	const m = base.length;
+	const n = revised.length;
+	if (m === 0 || n === 0) return [];
+	if (exceedsLcsBudget(m, n)) return [];
+	const baseTexts = base.map(({ block }) => block.text);
+	const revisedTexts = revised.map(({ block }) => block.text);
+	const stride = n + 1;
+	const dp = new Int32Array((m + 1) * stride);
+	for (let i = m - 1; i >= 0; i--) {
+		const rowOffset = i * stride;
+		const nextRowOffset = (i + 1) * stride;
+		const baseText = baseTexts[i];
+		for (let j = n - 1; j >= 0; j--) {
+			const revisedText = revisedTexts[j];
+			dp[rowOffset + j] = baseText === revisedText ? (dp[nextRowOffset + j + 1] ?? 0) + 1 : Math.max(dp[nextRowOffset + j] ?? 0, dp[rowOffset + j + 1] ?? 0);
+		}
+	}
+	const pairs = [];
+	let i = 0;
+	let j = 0;
+	while (i < m && j < n) {
+		const baseEntry = base[i];
+		const revisedEntry = revised[j];
+		if (!baseEntry || !revisedEntry) break;
+		if (baseTexts[i] === revisedTexts[j]) {
+			pairs.push({
+				baseIndex: baseEntry.index,
+				revisedIndex: revisedEntry.index
+			});
+			i++;
+			j++;
+			continue;
+		}
+		if ((dp[(i + 1) * stride + j] ?? 0) >= (dp[i * stride + j + 1] ?? 0)) i++;
+		else j++;
+	}
+	return pairs;
+};
+/**
+* Run the three-pass alignment (see the module doc comment) over two block
+* snapshots and flatten it into an ordered event stream. Shared by
+* {@link compareDocxVersions} and the redline generator so both interpret
+* one document walk instead of re-deriving it.
+*/
+const alignFolioBlocks = (baseBlocks, revisedBlocks) => {
+	const stableIdAnchors = pairByStableId(baseBlocks, revisedBlocks);
+	const usedBaseIndexes = new Set(stableIdAnchors.map((anchor) => anchor.baseIndex));
+	const usedRevisedIndexes = new Set(stableIdAnchors.map((anchor) => anchor.revisedIndex));
+	const baseRemaining = [];
+	baseBlocks.forEach((block, blockIndex) => {
+		if (!usedBaseIndexes.has(blockIndex)) baseRemaining.push({
+			block,
+			index: blockIndex
+		});
+	});
+	const revisedRemaining = [];
+	revisedBlocks.forEach((block, blockIndex) => {
+		if (!usedRevisedIndexes.has(blockIndex)) revisedRemaining.push({
+			block,
+			index: blockIndex
+		});
+	});
+	const exactTextAnchors = pairByExactText(baseRemaining, revisedRemaining);
+	const anchors = longestIncreasingByRevisedIndex([...stableIdAnchors, ...exactTextAnchors].toSorted((a, b) => a.baseIndex - b.baseIndex));
+	const events = [];
+	/** Pass 3: positionally zip the leftover blocks in one gap between anchors. */
+	const emitGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
+		const pairedCount = Math.min(baseTo - baseFrom, revisedTo - revisedFrom);
+		for (let k = 0; k < pairedCount; k++) {
+			const baseBlock = baseBlocks[baseFrom + k];
+			const revisedBlock = revisedBlocks[revisedFrom + k];
+			if (baseBlock && revisedBlock) events.push({
+				type: "pair",
+				baseBlock,
+				revisedBlock
+			});
+		}
+		for (let k = baseFrom + pairedCount; k < baseTo; k++) {
+			const block = baseBlocks[k];
+			if (block) events.push({
+				type: "baseOnly",
+				block
+			});
+		}
+		for (let k = revisedFrom + pairedCount; k < revisedTo; k++) {
+			const block = revisedBlocks[k];
+			if (block) events.push({
+				type: "revisedOnly",
+				block
+			});
+		}
+	};
+	let baseCursor = 0;
+	let revisedCursor = 0;
+	for (const anchor of anchors) {
+		emitGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
+		const baseBlock = baseBlocks[anchor.baseIndex];
+		const revisedBlock = revisedBlocks[anchor.revisedIndex];
+		if (baseBlock && revisedBlock) events.push({
+			type: "pair",
+			baseBlock,
+			revisedBlock
+		});
+		baseCursor = anchor.baseIndex + 1;
+		revisedCursor = anchor.revisedIndex + 1;
+	}
+	emitGap(baseCursor, baseBlocks.length, revisedCursor, revisedBlocks.length);
+	return events;
+};
+const previewRunsText = (runs) => runs.map((run) => run.text).join("");
+/**
+* Character-aligned formatting diff of two text-equal blocks. Walks both
+* blocks' preview runs in parallel and collects every property whose value
+* differs anywhere in the overlap. A side with `previewRuns === undefined`
+* (the snapshot omits them when every run is unstyled) counts as one
+* unstyled run spanning the whole text. When both sides carry runs but
+* their concatenated texts disagree (non-text inline content can make the
+* preview text drift from the block text), positions can't be aligned, so
+* detection backs off and reports no change.
+*/
+const diffPreviewRunFormatting = (base, revised) => {
+	if (base.previewRuns === void 0 && revised.previewRuns === void 0) return [];
+	const baseText = base.previewRuns === void 0 ? null : previewRunsText(base.previewRuns);
+	const revisedText = revised.previewRuns === void 0 ? null : previewRunsText(revised.previewRuns);
+	if (baseText !== null && revisedText !== null && baseText !== revisedText) return [];
+	const text = baseText ?? revisedText;
+	if (text === null || text.length === 0) return [];
+	const baseRuns = base.previewRuns ?? [{ text }];
+	const revisedRuns = revised.previewRuns ?? [{ text }];
+	const changed = /* @__PURE__ */ new Set();
+	let baseRunIndex = 0;
+	let revisedRunIndex = 0;
+	let baseOffset = 0;
+	let revisedOffset = 0;
+	while (baseRunIndex < baseRuns.length && revisedRunIndex < revisedRuns.length) {
+		const baseRun = baseRuns[baseRunIndex];
+		const revisedRun = revisedRuns[revisedRunIndex];
+		if (!baseRun || !revisedRun) break;
+		const step = Math.min(baseRun.text.length - baseOffset, revisedRun.text.length - revisedOffset);
+		if (step > 0) {
+			for (const property of FORMAT_PROPERTIES) if (baseRun[property] !== revisedRun[property]) changed.add(property);
+		}
+		baseOffset += step;
+		revisedOffset += step;
+		if (baseOffset >= baseRun.text.length) {
+			baseRunIndex++;
+			baseOffset = 0;
+		}
+		if (revisedOffset >= revisedRun.text.length) {
+			revisedRunIndex++;
+			revisedOffset = 0;
+		}
+	}
+	return FORMAT_PROPERTIES.filter((property) => changed.has(property));
+};
+/**
+* Floor for move detection: an added/deleted text must hold at least this
+* many whitespace-separated words before an identical pair re-classifies as
+* a move. Short boilerplate ("Confidential", a bare heading word) recurs
+* throughout real documents and would otherwise pair as spurious moves.
+*/
+const MOVE_MINIMUM_WORD_COUNT = 3;
+const meetsMoveWordCount = (text) => {
+	const words = text.matchAll(/\S+/gu);
+	let count = 0;
+	while (!words.next().done) if (++count >= MOVE_MINIMUM_WORD_COUNT) return true;
+	return false;
+};
+/**
+* Re-classify `deleted` + `added` pairs with identical text as
+* `movedFrom` / `movedTo` entries sharing a `moveGroupId`, in place, so each
+* side keeps its slot in the revised-side document order. Matching is FIFO
+* per text, so duplicated boilerplate above the word floor pairs
+* first-to-first rather than fanning out.
+*/
+const detectMoves = (changes, counts) => {
+	const deletedIndexesByText = /* @__PURE__ */ new Map();
+	changes.forEach((change, index) => {
+		if (change.type === "deleted" && meetsMoveWordCount(change.text)) {
+			const queue = deletedIndexesByText.get(change.text) ?? [];
+			queue.push(index);
+			deletedIndexesByText.set(change.text, queue);
+		}
+	});
+	if (deletedIndexesByText.size === 0) return;
+	let moveGroupId = 0;
+	changes.forEach((change, index) => {
+		if (change.type !== "added") return;
+		const deletedIndex = deletedIndexesByText.get(change.text)?.shift();
+		if (deletedIndex === void 0) return;
+		const deleted = changes[deletedIndex];
+		if (!deleted || deleted.type !== "deleted") return;
+		moveGroupId++;
+		changes[deletedIndex] = {
+			type: "movedFrom",
+			blockId: deleted.blockId,
+			kind: deleted.kind,
+			text: deleted.text,
+			moveGroupId
+		};
+		changes[index] = {
+			type: "movedTo",
+			blockId: change.blockId,
+			kind: change.kind,
+			text: change.text,
+			moveGroupId
+		};
+		counts.deleted--;
+		counts.added--;
+		counts.moved++;
+	});
+};
+/**
+* Compare two `.docx` buffers and return a structured, block-level diff.
+* See the module doc comment for the as-accepted comparison semantics, the
+* three-pass alignment algorithm, move detection, and format-only change
+* detection.
+*/
+const compareDocxVersions = async (base, revised) => {
+	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
+	const baseBlocks = baseReviewer.snapshot().blocks;
+	const revisedBlocks = revisedReviewer.snapshot().blocks;
+	const changes = [];
+	const counts = {
+		added: 0,
+		deleted: 0,
+		modified: 0,
+		formatChanged: 0,
+		moved: 0,
+		unchanged: 0
+	};
+	for (const event of alignFolioBlocks(baseBlocks, revisedBlocks)) {
+		if (event.type === "pair") {
+			const { baseBlock, revisedBlock } = event;
+			if (baseBlock.text !== revisedBlock.text) {
+				counts.modified++;
+				changes.push({
+					type: "modified",
+					blockId: revisedBlock.id,
+					kind: revisedBlock.kind,
+					segments: diffWordSegments(baseBlock.text, revisedBlock.text)
+				});
+				continue;
+			}
+			const changedProperties = diffPreviewRunFormatting(baseBlock, revisedBlock);
+			if (changedProperties.length > 0) {
+				counts.formatChanged++;
+				changes.push({
+					type: "formatChanged",
+					blockId: revisedBlock.id,
+					kind: revisedBlock.kind,
+					text: revisedBlock.text,
+					changedProperties
+				});
+				continue;
+			}
+			counts.unchanged++;
+			continue;
+		}
+		if (event.type === "baseOnly") {
+			counts.deleted++;
+			changes.push({
+				type: "deleted",
+				blockId: event.block.id,
+				kind: event.block.kind,
+				text: event.block.text
+			});
+			continue;
+		}
+		counts.added++;
+		changes.push({
+			type: "added",
+			blockId: event.block.id,
+			kind: event.block.kind,
+			text: event.block.text
+		});
+	}
+	detectMoves(changes, counts);
+	return {
+		changes,
+		summaryCounts: counts
+	};
+};
+//#endregion
+export { alignFolioBlocks, compareDocxVersions, exceedsLcsBudget };