@createiq/htmldiff 1.2.0-beta.1 → 1.2.0-beta.10

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.
@@ -99,6 +130,16 @@ declare class HtmlDiff {
   private newText;
   private oldText;
   private tablePreprocessDepth;
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -163,7 +204,17 @@ declare class HtmlDiff {
    * @param newText The new text.
    */
   constructor(oldText: string, newText: string);
-  static execute(oldText: string, newText: string): 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
    * arrays the diff ran against, the operations produced, the original
@@ -192,22 +243,6 @@ declare class HtmlDiff {
    * why symmetry matters.
    */
   static evaluateProjectionApplicability(oldText: string, newText: string): boolean;
-  /**
-   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
-   * version CP sent back), and V3 (Me's current draft), produces a
-   * single attributed HTML output where CP's and Me's changes are
-   * distinguished by `data-author` ('cp' or 'me') and matching
-   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
-   * CP's proposal" case (Me deleted text CP had inserted) gets a
-   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
-   *
-   * Coordinates the symmetric-projection decision (D1) across both
-   * internal `analyze` calls so V2 tokenises identically on each side
-   * of the spine. When `useProjections` is left undefined, the decision
-   * is the conjunction of both pair-wise heuristics — project iff both
-   * pairs would project on their own. Pass an explicit boolean to
-   * override.
-   */
   /**
    * Three-way HTML diff against a shared genesis. Produces attributed
    * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
@@ -235,6 +270,25 @@ declare class HtmlDiff {
    * buffer. Reusing the instance keeps the formatting-tag stack
    * (`specialTagDiffStack`) coherent across segments — a `<strong>`
    * opened in one segment and closed in another stays balanced.
+   *
+   * Edge case: an ins/del segment can open a formatting wrap whose
+   * matching closer ends up in an equal segment (`<strong>` deleted
+   * by CP but `</strong>` kept by both — buildSegments emits the open
+   * as del-cp and the close as equal). Equal segments bypass
+   * `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.
+   *
+   * 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;
   /**
@@ -338,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.
@@ -99,6 +130,16 @@ declare class HtmlDiff {
   private newText;
   private oldText;
   private tablePreprocessDepth;
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -163,7 +204,17 @@ declare class HtmlDiff {
    * @param newText The new text.
    */
   constructor(oldText: string, newText: string);
-  static execute(oldText: string, newText: string): 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
    * arrays the diff ran against, the operations produced, the original
@@ -192,22 +243,6 @@ declare class HtmlDiff {
    * why symmetry matters.
    */
   static evaluateProjectionApplicability(oldText: string, newText: string): boolean;
-  /**
-   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
-   * version CP sent back), and V3 (Me's current draft), produces a
-   * single attributed HTML output where CP's and Me's changes are
-   * distinguished by `data-author` ('cp' or 'me') and matching
-   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
-   * CP's proposal" case (Me deleted text CP had inserted) gets a
-   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
-   *
-   * Coordinates the symmetric-projection decision (D1) across both
-   * internal `analyze` calls so V2 tokenises identically on each side
-   * of the spine. When `useProjections` is left undefined, the decision
-   * is the conjunction of both pair-wise heuristics — project iff both
-   * pairs would project on their own. Pass an explicit boolean to
-   * override.
-   */
   /**
    * Three-way HTML diff against a shared genesis. Produces attributed
    * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
@@ -235,6 +270,25 @@ declare class HtmlDiff {
    * buffer. Reusing the instance keeps the formatting-tag stack
    * (`specialTagDiffStack`) coherent across segments — a `<strong>`
    * opened in one segment and closed in another stays balanced.
+   *
+   * Edge case: an ins/del segment can open a formatting wrap whose
+   * matching closer ends up in an equal segment (`<strong>` deleted
+   * by CP but `</strong>` kept by both — buildSegments emits the open
+   * as del-cp and the close as equal). Equal segments bypass
+   * `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.
+   *
+   * 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;
   /**
@@ -338,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