@createiq/htmldiff 1.2.0-beta.5 → 1.2.0-beta.7

package/dist/HtmlDiff.cjs

@@ -1,3 +1,7 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
 //#region src/Match.ts
 var Match = class {
 	_startInOld;
@@ -2035,6 +2039,37 @@ var BlockFinder = class {
 };
 //#endregion
 //#region src/HtmlDiff.ts
+/**
+* Opinionated options that align htmldiff's output with Microsoft Word's
+* track-changes rendering for legal-document rewrites.
+*
+* The library's bare default (`orphanMatchThreshold = 0`) keeps every
+* LCS match, however small — which fragments long sentence rewrites
+* into many tiny ins/del pairs around stray word matches ("of", "the",
+* "shall"). Word collapses those into a single coarse del+ins, which is
+* dramatically more readable for legal text.
+*
+* 0.25 was tuned empirically against a customer Word reference (US
+* Commercial One CP, May 2026):
+*   - short edits (typo / one-word insert): output identical to
+*     threshold=0 — inter-match distances are tiny so every match
+*     trivially clears the bar;
+*   - long rewrites (the "Specified Indebtedness" rewrite in the
+*     reference): previously produced 6 dels + 5 ins fragmented around
+*     stray matches; at 0.25 it condenses to 3 dels + 2 ins — close to
+*     Word's 1+1 and a major readability win;
+*   - higher values (0.3+) collapsed short edits containing inline
+*     formatting changes into a single block — too aggressive.
+*
+* Consumers rendering legal documents should spread this into their
+* options:
+*   `HtmlDiff.execute(old, new, { ...WORD_ALIGNED_OPTIONS })`
+*   `HtmlDiff.executeThreeWay(g, c, m, { ...WORD_ALIGNED_OPTIONS })`
+*
+* Other consumers (machine-readable diff, exact-token alignment) can
+* keep the bare default.
+*/
+const WORD_ALIGNED_OPTIONS = { orphanMatchThreshold: .25 };
 var HtmlDiff = class HtmlDiff {
 	/**
 	* This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -2187,8 +2222,23 @@ var HtmlDiff = class HtmlDiff {
 		this.oldText = oldText;
 		this.newText = newText;
 	}
-	static execute(oldText, newText) {
-		return new HtmlDiff(oldText, newText).build();
+	/**
+	* Two-way diff entry point. Accepts the same `AnalyzeOptions` bag as
+	* `executeThreeWay`, with two intentional exceptions documented
+	* inline below. Consumers wanting Word-aligned output should spread
+	* `WORD_ALIGNED_OPTIONS` into the third argument.
+	*
+	* Note: unlike `analyze`, `execute` runs `build()` which performs
+	* full table preprocessing — `tablePreprocessDepth` stays at 0 so
+	* the recursive cell diff can happen. Callers can't override that.
+	*/
+	static execute(oldText, newText, options = {}) {
+		const inner = new HtmlDiff(oldText, newText);
+		if (options.blockExpressions) for (const expr of options.blockExpressions) inner.addBlockExpression(expr);
+		if (options.repeatingWordsAccuracy !== void 0) inner.repeatingWordsAccuracy = options.repeatingWordsAccuracy;
+		if (options.orphanMatchThreshold !== void 0) inner.orphanMatchThreshold = options.orphanMatchThreshold;
+		if (options.ignoreWhitespaceDifferences !== void 0) inner.ignoreWhitespaceDifferences = options.ignoreWhitespaceDifferences;
+		return inner.build();
 	}
 	/**
 	* Analyse a two-way diff and return its raw building blocks: the word
@@ -2311,9 +2361,17 @@ var HtmlDiff = class HtmlDiff {
 	* `insertTag` and push raw, so the stack entry for the open is
 	* never popped. Rather than throw — which forces the caller's UI
 	* into an error boundary — close every leftover wrap with `</ins>`
-	* at the end of emission. The resulting HTML has an extra
-	* `</ins>` next to the formatting closer; DOMParser-normalisation
-	* downstream produces sensible nesting.
+	* at the end of emission.
+	*
+	* Caveat: the `</ins>` close is honest for the mod-wrap that the
+	* opener pushed (every formatting opener emits an inner `<ins…>`
+	* postInject regardless of whether the outer segment is ins or
+	* del). For del-segment formatting openers the outer `<del>` may
+	* itself be left open by the same emission imbalance; this fixup
+	* doesn't address that. Downstream browsers/DOMParser normalise
+	* mildly-malformed HTML by closing dangling tags, so the rendered
+	* output is usually acceptable — but the warning IS the signal
+	* that the input had a real imbalance worth investigating.
 	*/
 	static emitSegments(segments) {
 		const emitter = new HtmlDiff("", "");
@@ -2739,6 +2797,7 @@ var HtmlDiff = class HtmlDiff {
 	}
 };
 //#endregion
-module.exports = HtmlDiff;
+exports.WORD_ALIGNED_OPTIONS = WORD_ALIGNED_OPTIONS;
+exports.default = HtmlDiff;
 
 //# sourceMappingURL=HtmlDiff.cjs.map