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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createiq/htmldiff",
-  "version": "1.2.0-beta.0",
+  "version": "1.2.0-beta.10",
   "description": "TypeScript port of htmldiff.net",
   "type": "module",
   "author": "Mathew Mannion <mathew.mannion@linklaters.com>",

package/src/HtmlDiff.ts

@@ -71,6 +71,40 @@ export interface AnalyzeResult {
  */
 export 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.
+ */
+export const WORD_ALIGNED_OPTIONS: AnalyzeOptions = {
+  orphanMatchThreshold: 0.25,
+}
+
 export default class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -162,7 +196,22 @@ export default class HtmlDiff {
   // constructor overload that would re-leak the parameter we just hid.
   private tablePreprocessDepth = 0
 
-  private specialTagDiffStack: string[] = []
+  /**
+   * 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: Array<{
+    tag: string
+    styledTagNames: string
+    cssClass: string
+    metadata: WrapMetadata | undefined
+  }> = []
   private newWords: string[] = []
   private oldWords: string[] = []
   /**
@@ -234,8 +283,31 @@ export default class HtmlDiff {
     this.newText = newText
   }
 
-  static execute(oldText: string, newText: string): string {
-    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: string, newText: string, options: AnalyzeOptions = {}): string {
+    const inner = new HtmlDiff(oldText, newText)
+    if (options.blockExpressions) {
+      for (const expr of options.blockExpressions) inner.addBlockExpression(expr)
+    }
+    if (options.repeatingWordsAccuracy !== undefined) inner.repeatingWordsAccuracy = options.repeatingWordsAccuracy
+    if (options.orphanMatchThreshold !== undefined) inner.orphanMatchThreshold = options.orphanMatchThreshold
+    if (options.ignoreWhitespaceDifferences !== undefined) {
+      inner.ignoreWhitespaceDifferences = options.ignoreWhitespaceDifferences
+    }
+    // `useProjections` is intentionally NOT plumbed here — the 2-way
+    // path's build() runs its own heuristic. `analyze` honours it; if
+    // you need to force it for a 2-way result, route through `analyze`
+    // and consume the operations directly.
+    return inner.build()
   }
 
   /**
@@ -321,56 +393,60 @@ export default class HtmlDiff {
   }
 
   /**
-   * 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'`.
+   * Three-way HTML diff against a shared genesis. Produces attributed
+   * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
+   * from Me's accumulated changes (genesis → meCurrent). Use this for
+   * blackline UX where the negotiation has gone through multiple turns
+   * and the reader wants to see "who proposed what" across the whole
+   * history, not just the most recent round.
+   *
+   * When both parties happen to have made the same change (e.g. CP
+   * proposed a wording change in turn N, Me adopted it in turn N+1),
+   * the change reads as "settled" and is emitted unmarked — only
+   * disagreements and pending proposals carry author attribution.
    *
-   * 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.
+   * @param genesis    the shared common ancestor (per-user — the FE
+   *                   picks between V1.0 and /preview/initialAnswers
+   *                   based on `prefillReceiverAnswers`)
+   * @param cpLatest   the counterparty's current published version
+   * @param meCurrent  Me's current draft (the document on screen)
    */
-  static executeThreeWay(v1: string, v2: string, v3: string, options: ThreeWayOptions = {}): string {
-    return HtmlDiff.executeThreeWayWithDepth(v1, v2, v3, options, 0)
+  static executeThreeWay(genesis: string, cpLatest: string, meCurrent: string, options: ThreeWayOptions = {}): string {
+    return HtmlDiff.executeThreeWayWithDepth(genesis, cpLatest, meCurrent, options, 0)
   }
 
   private static executeThreeWayWithDepth(
-    v1: string,
-    v2: string,
-    v3: string,
+    genesis: string,
+    cpLatest: string,
+    meCurrent: string,
     options: ThreeWayOptions,
     depth: number
   ): string {
-    // Table preprocessing first — replaces each V1/V2/V3 table with a
+    // Table preprocessing first — replaces each genesis/cp/me table with a
     // shared-nonce placeholder, then the word-level merge runs over the
     // table-free inputs. Cells are diffed recursively via executeThreeWay
-    // so the cell content is itself three-way attributed. Restoration
-    // happens at the end.
+    // so the cell content is itself three-way attributed.
     //
-    // Depth-cap the recursion. Each level recurses cellDiff → executeThreeWay,
-    // which would otherwise run unbounded on adversarially-nested input.
-    // Beyond the cap, skip table preprocessing entirely and let the
-    // word-level merge handle the raw HTML — same bail-out semantics as
-    // the 2-way `MaxTablePreprocessDepth` cap.
+    // Depth-cap the recursion so adversarially-nested input can't blow
+    // stack/memory.
     const tablePreprocess =
       depth < HtmlDiff.MaxThreeWayDepth
-        ? preprocessTablesThreeWay(v1, v2, v3, (c1, c2, c3) =>
-            HtmlDiff.executeThreeWayWithDepth(c1, c2, c3, options, depth + 1)
+        ? preprocessTablesThreeWay(genesis, cpLatest, meCurrent, (g, c, m) =>
+            HtmlDiff.executeThreeWayWithDepth(g, c, m, options, depth + 1)
           )
         : null
-    const inV1 = tablePreprocess?.modifiedV1 ?? v1
-    const inV2 = tablePreprocess?.modifiedV2 ?? v2
-    const inV3 = tablePreprocess?.modifiedV3 ?? v3
-
+    const inGenesis = tablePreprocess?.modifiedGenesis ?? genesis
+    const inCp = tablePreprocess?.modifiedCp ?? cpLatest
+    const inMe = tablePreprocess?.modifiedMe ?? meCurrent
+
+    // Symmetric projection across both analyses. The genesis-spine
+    // algorithm requires `genesis` to tokenise identically on each
+    // pair-wise analysis (both have genesis as the OLD side), so the
+    // useProjections decision must agree across both calls.
     const useProjections =
       options.useProjections ??
-      (HtmlDiff.evaluateProjectionApplicability(inV1, inV2) && HtmlDiff.evaluateProjectionApplicability(inV2, inV3))
+      (HtmlDiff.evaluateProjectionApplicability(inGenesis, inCp) &&
+        HtmlDiff.evaluateProjectionApplicability(inGenesis, inMe))
 
     const analyzeOpts: AnalyzeOptions = {
       useProjections,
@@ -379,21 +455,21 @@ export default class HtmlDiff {
       orphanMatchThreshold: options.orphanMatchThreshold,
       ignoreWhitespaceDifferences: options.ignoreWhitespaceDifferences,
     }
-    const d1 = HtmlDiff.analyze(inV1, inV2, analyzeOpts)
-    const d2 = HtmlDiff.analyze(inV2, inV3, analyzeOpts)
+    const dCp = HtmlDiff.analyze(inGenesis, inCp, analyzeOpts)
+    const dMe = HtmlDiff.analyze(inGenesis, inMe, analyzeOpts)
 
-    // Spine sanity check. Symmetric `useProjections` should guarantee
-    // alignment, but if a bug ever lets these diverge we want to fail
-    // loudly rather than silently produce a misattributed output.
-    if (d1.newDiffWords.length !== d2.oldDiffWords.length) {
+    // Spine sanity check — both analyses must share an identical genesis
+    // tokenisation. Symmetric useProjections guarantees this; if it ever
+    // diverges, fail loudly rather than silently misattribute.
+    if (dCp.oldDiffWords.length !== dMe.oldDiffWords.length) {
       throw new Error(
-        'HtmlDiff.executeThreeWay: V2 tokenisation diverged across pair-wise analyses ' +
-          `(${d1.newDiffWords.length} vs ${d2.oldDiffWords.length}). ` +
+        'HtmlDiff.executeThreeWay: genesis tokenisation diverged across pair-wise analyses ' +
+          `(${dCp.oldDiffWords.length} vs ${dMe.oldDiffWords.length}). ` +
           'This indicates the symmetric-projection coordination has a bug.'
       )
     }
 
-    const segments = buildSegments(d1, d2)
+    const segments = buildSegments(dCp, dMe)
     const merged = HtmlDiff.emitSegments(segments)
     return tablePreprocess ? restoreTablePlaceholders(merged, tablePreprocess.placeholderToDiff) : merged
   }
@@ -404,6 +480,25 @@ export default 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(segments: Segment[]): string {
     const emitter = new HtmlDiff('', '')
@@ -416,18 +511,21 @@ export default class HtmlDiff {
       // insertTag mutates its `words` array; pass a copy.
       emitter.insertTag(tag, baseClass, [...seg.words], metadata)
     }
-    // Stack-balance invariant: every special-case opening tag pushed onto
-    // `specialTagDiffStack` during emission must have been matched by a
-    // closing tag. An unbalanced stack means the input had unbalanced
-    // formatting tags AND a Replace at an inconvenient position — the
-    // output would be silently malformed (half-closed `<ins>`). Fail
-    // loudly so the caller can investigate rather than ship broken HTML.
     if (emitter.specialTagDiffStack.length > 0) {
-      throw new Error(
+      // Log once so we can spot bad inputs in dev tools, but don't
+      // throw — the caller's only fallback was to crash the React
+      // tree, which is worse than emitting slightly-imperfect HTML.
+      // eslint-disable-next-line no-console
+      console.warn(
         `HtmlDiff.executeThreeWay: emission left ${emitter.specialTagDiffStack.length} ` +
-          'unclosed formatting tag(s) on the stack — input may have unbalanced ' +
-          '<strong>/<em>/etc. or there is a bug in segment emission.'
+          'unclosed formatting wrap(s) on the stack. Closing defensively. ' +
+          'This usually means a formatting tag opens in a del/ins segment ' +
+          'and its matching closer is in an equal segment.'
       )
+      while (emitter.specialTagDiffStack.length > 0) {
+        emitter.content.push('</ins>')
+        emitter.specialTagDiffStack.pop()
+      }
     }
     return emitter.content.join('')
   }
@@ -807,8 +905,13 @@ export default class HtmlDiff {
       // if there are nonTags, the index of the last tag is the index before the first nonTag.
       const indexLastTagInFirstTagBlock = indexOfFirstNonTag === -1 ? words.length - 1 : indexOfFirstNonTag - 1
 
-      let specialCaseTagInjection = ''
-      let specialCaseTagInjectionIsBefore = false
+      // Pre-injection sits BEFORE the extracted tag-block content (used
+      // by closing tags so `</ins></strong>` reads left-to-right).
+      // Post-injection sits AFTER (used by opening tags so the rendered
+      // order is `<strong><ins ...>` and by the overlap-split case so
+      // the re-opened `<ins>`s sit AFTER the actual closing tag).
+      let preInject = ''
+      let postInject = ''
 
       // handle opening tag
       if (HtmlDiff.SpecialCaseOpeningTagRegex.test(words[0])) {
@@ -820,10 +923,11 @@ export default class HtmlDiff {
         }
         const styledTagNames = Array.from(tagNames).join(' ')
 
-        this.specialTagDiffStack.push(words[0])
         // Carry the caller's metadata into the formatting-tag wrapper so
         // a 3-way author tag survives a `<strong>`/`<em>` content edit.
-        specialCaseTagInjection = `<ins${Utils.composeTagAttributes(`mod ${styledTagNames}`, metadata ?? {})}>`
+        const styledCssClass = `mod ${styledTagNames}`
+        this.specialTagDiffStack.push({ tag: words[0], styledTagNames, cssClass: styledCssClass, metadata })
+        postInject = `<ins${Utils.composeTagAttributes(styledCssClass, metadata ?? {})}>`
         if (tag === HtmlDiff.DelTag) {
           words.shift()
 
@@ -835,7 +939,6 @@ export default class HtmlDiff {
       }
       // handle closing tag
       else if (HtmlDiff.SpecialCaseClosingTagsSet.has(words[0].toLowerCase())) {
-        const openingTag = this.specialTagDiffStack.length === 0 ? null : this.specialTagDiffStack.pop()
         // For delete operations: when the tag block contains a mix of formatting and
         // non-formatting closing tags (e.g. </strong></div>), compare against the first
         // closing tag (the formatting one) rather than the last tag in the block.
@@ -850,19 +953,39 @@ export default class HtmlDiff {
             tagIndexToCompare = 0
           }
         }
-        const openingAndClosingTagsMatch =
-          !!openingTag && Utils.getTagName(openingTag) === Utils.getTagName(words[tagIndexToCompare])
 
-        if (openingTag && openingAndClosingTagsMatch) {
-          specialCaseTagInjection = '</ins>'
-          specialCaseTagInjectionIsBefore = true
+        // Search the stack for a matching opener (LIFO). When the match
+        // is the top entry, this is the normal balanced case and we
+        // emit a single `</ins>` before the closing tag. When the match
+        // is below an unmatched opener — i.e. another formatting wrap
+        // opened after it but hasn't been closed yet — the wraps
+        // overlap in source order, which has no valid LIFO HTML
+        // expression. Resolve by SPLITTING the wraps: close everything
+        // above the match (their `<ins>`s and the match's `<ins>`), then
+        // re-open the above wraps with fresh `<ins>` tags AFTER the
+        // closing tag emits. The above wraps continue to apply until
+        // their own closing tag arrives.
+        const closingTagName = Utils.getTagName(words[tagIndexToCompare])
+        let matchIdx = -1
+        for (let i = this.specialTagDiffStack.length - 1; i >= 0; i--) {
+          if (Utils.getTagName(this.specialTagDiffStack[i].tag) === closingTagName) {
+            matchIdx = i
+            break
+          }
         }
 
-        // if the tag has a corresponding opening tag, but they don't match,
-        // we need to push the opening tag back onto the stack
-        else if (openingTag) {
-          this.specialTagDiffStack.push(openingTag)
+        if (matchIdx >= 0) {
+          const aboveEntries = this.specialTagDiffStack.splice(matchIdx + 1)
+          this.specialTagDiffStack.pop() // pop the matched entry
+          // One `</ins>` per above entry, then one for the match itself.
+          preInject = '</ins>'.repeat(aboveEntries.length + 1)
+          for (const entry of aboveEntries) {
+            postInject += `<ins${Utils.composeTagAttributes(entry.cssClass, entry.metadata ?? {})}>`
+            this.specialTagDiffStack.push(entry) // their wrap continues via the new <ins>
+          }
         }
+        // No match in stack — orphan closing tag, drop the `<ins>` work
+        // and just let the tag itself flow through extractConsecutiveWords.
 
         if (tag === HtmlDiff.DelTag) {
           words.shift()
@@ -873,7 +996,7 @@ export default class HtmlDiff {
         }
       }
 
-      if (words.length === 0 && specialCaseTagInjection.length === 0) {
+      if (words.length === 0 && preInject.length === 0 && postInject.length === 0) {
         break
       }
 
@@ -889,11 +1012,7 @@ export default class HtmlDiff {
               !HtmlDiff.SpecialCaseClosingTagsSet.has(x.toLowerCase())
           : Utils.isTag
 
-      if (specialCaseTagInjectionIsBefore) {
-        this.content.push(specialCaseTagInjection + this.extractConsecutiveWords(words, isTagForExtraction).join(''))
-      } else {
-        this.content.push(this.extractConsecutiveWords(words, isTagForExtraction).join('') + specialCaseTagInjection)
-      }
+      this.content.push(preInject + this.extractConsecutiveWords(words, isTagForExtraction).join('') + postInject)
 
       if (words.length === 0) continue
 
@@ -1000,6 +1119,31 @@ export default class HtmlDiff {
         continue
       }
 
+      // Never orphan-reject a match whose tokens are ALL HTML tags.
+      // Tag tokens are structural; rejecting `</strong>` / `</em>` as
+      // an orphan match between two content deletions merges the tag
+      // into the deletion, leaving the matching opener unclosed —
+      // browsers then auto-close the opener at the END of the
+      // deletion, producing visually-wrong output (e.g. the body of
+      // a section deletion rendered as bold-italic because the
+      // closing `</strong></em>` ended up after the body deletion
+      // rather than after the heading). The orphan threshold is
+      // designed for stray word matches between heavily-edited spans,
+      // not for formatting boundaries.
+      let allTags = true
+      for (let i = curr.startInNew; i < curr.endInNew; i++) {
+        if (!Utils.isTag(wordsForDiffNew[i])) {
+          allTags = false
+          break
+        }
+      }
+      if (allTags) {
+        yield curr
+        prev = curr
+        curr = next
+        continue
+      }
+
       let oldDistanceInChars = 0
       for (let i = prev.endInOld; i < next.startInOld; i++) {
         oldDistanceInChars += wordsForDiffOld[i].length