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

package/dist/HtmlDiff.d.cts

@@ -63,6 +63,37 @@ interface AnalyzeResult {
  * `evaluateProjectionApplicability` results.
  */
 type ThreeWayOptions = AnalyzeOptions;
+/**
+ * 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.
+ */
+declare const WORD_ALIGNED_OPTIONS: AnalyzeOptions;
 declare class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -173,6 +204,16 @@ declare class HtmlDiff {
    * @param newText The new text.
    */
   constructor(oldText: string, newText: string);
+  /**
+   * 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: string, newText: string, options?: AnalyzeOptions): string;
   /**
    * Analyse a two-way diff and return its raw building blocks: the word
@@ -237,9 +278,17 @@ declare 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.
    */
   private static emitSegments;
   /**
@@ -343,5 +392,5 @@ declare class HtmlDiff {
   private findMatch;
 }
 //#endregion
-export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, HtmlDiff as default };
+export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, WORD_ALIGNED_OPTIONS, HtmlDiff as default };
 //# sourceMappingURL=HtmlDiff.d.cts.map

package/dist/HtmlDiff.d.mts

@@ -63,6 +63,37 @@ interface AnalyzeResult {
  * `evaluateProjectionApplicability` results.
  */
 type ThreeWayOptions = AnalyzeOptions;
+/**
+ * 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.
+ */
+declare const WORD_ALIGNED_OPTIONS: AnalyzeOptions;
 declare class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -173,6 +204,16 @@ declare class HtmlDiff {
    * @param newText The new text.
    */
   constructor(oldText: string, newText: string);
+  /**
+   * 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: string, newText: string, options?: AnalyzeOptions): string;
   /**
    * Analyse a two-way diff and return its raw building blocks: the word
@@ -237,9 +278,17 @@ declare 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.
    */
   private static emitSegments;
   /**
@@ -343,5 +392,5 @@ declare class HtmlDiff {
   private findMatch;
 }
 //#endregion
-export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, HtmlDiff as default };
+export { AnalyzeOptions, AnalyzeResult, ThreeWayOptions, WORD_ALIGNED_OPTIONS, HtmlDiff as default };
 //# sourceMappingURL=HtmlDiff.d.mts.map

package/dist/HtmlDiff.mjs

@@ -2035,6 +2035,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,6 +2218,16 @@ var HtmlDiff = class HtmlDiff {
 		this.oldText = oldText;
 		this.newText = newText;
 	}
+	/**
+	* 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);
@@ -2316,9 +2357,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("", "");
@@ -2744,6 +2793,6 @@ var HtmlDiff = class HtmlDiff {
 	}
 };
 //#endregion
-export { HtmlDiff as default };
+export { WORD_ALIGNED_OPTIONS, HtmlDiff as default };
 
 //# sourceMappingURL=HtmlDiff.mjs.map