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

package/src/Utils.ts

@@ -32,8 +32,39 @@ export function stripTagAttributes(word: string): string {
   return word
 }
 
-export function wrapText(text: string, tagName: string, cssClass: string): string {
-  return `<${tagName} class='${cssClass}'>${text}</${tagName}>`
+/**
+ * Optional metadata attached to a wrapped tag. Used by `executeThreeWay`
+ * to colour diff segments with their author (CP vs Me) via extra classes
+ * and `data-*` attributes; the two-way path passes nothing and gets the
+ * unchanged historical output.
+ */
+export interface WrapMetadata {
+  /** Space-separated classes appended after `cssClass`. */
+  extraClasses?: string
+  /** `data-*` attribute map, keyed by the attribute name *without* the `data-` prefix. */
+  dataAttrs?: Readonly<Record<string, string>>
+}
+
+export function wrapText(text: string, tagName: string, cssClass: string, metadata?: WrapMetadata): string {
+  if (!metadata) return `<${tagName} class='${cssClass}'>${text}</${tagName}>`
+  return `<${tagName}${composeTagAttributes(cssClass, metadata)}>${text}</${tagName}>`
+}
+
+/**
+ * Build the attribute portion of an opening tag from a base class plus
+ * optional metadata. Exposed so emission paths that build opening-tag
+ * fragments by hand (e.g. the formatting-tag special-case in
+ * `HtmlDiff.insertTag`) can stay consistent with `wrapText`.
+ */
+export function composeTagAttributes(cssClass: string, metadata: WrapMetadata): string {
+  const classes = metadata.extraClasses ? `${cssClass} ${metadata.extraClasses}` : cssClass
+  let out = ` class='${classes}'`
+  if (metadata.dataAttrs) {
+    for (const key of Object.keys(metadata.dataAttrs)) {
+      out += ` data-${key}='${metadata.dataAttrs[key]}'`
+    }
+  }
+  return out
 }
 
 export function isStartOfTag(val: string): boolean {
@@ -85,6 +116,7 @@ export default {
   isTag,
   stripTagAttributes,
   wrapText,
+  composeTagAttributes,
   isStartOfTag,
   isEndOfTag,
   isStartOfEntity,

package/test/HtmlDiff.analyze.spec.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+
+import Action from '../src/Action'
+import HtmlDiff from '../src/HtmlDiff'
+
+describe('HtmlDiff.analyze', () => {
+  describe('return shape', () => {
+    it('returns operations indexed into oldDiffWords / newDiffWords', () => {
+      const result = HtmlDiff.analyze('a b c', 'a x c')
+      expect(result.oldDiffWords).toBeInstanceOf(Array)
+      expect(result.newDiffWords).toBeInstanceOf(Array)
+      expect(result.operations).toBeInstanceOf(Array)
+      // Every op's endInOld must be ≤ oldDiffWords.length, etc.
+      for (const op of result.operations) {
+        expect(op.endInOld).toBeLessThanOrEqual(result.oldDiffWords.length)
+        expect(op.endInNew).toBeLessThanOrEqual(result.newDiffWords.length)
+      }
+    })
+
+    it('returns original word arrays alongside the diff arrays', () => {
+      const result = HtmlDiff.analyze('hello world', 'hello there world')
+      expect(result.oldOriginalWords).toBeInstanceOf(Array)
+      expect(result.newOriginalWords).toBeInstanceOf(Array)
+    })
+
+    it('returns null contentToOriginal maps when projections are inactive', () => {
+      // Plain text with no structural tags → projection inactive.
+      const result = HtmlDiff.analyze('a b c', 'a x c')
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+    })
+
+    it('returns non-null contentToOriginal maps when projections are active', () => {
+      // Different wrapper tags → projection kicks in.
+      const result = HtmlDiff.analyze('<p>hello world</p>', '<div>hello world</div>')
+      expect(result.oldContentToOriginal).not.toBeNull()
+      expect(result.newContentToOriginal).not.toBeNull()
+    })
+  })
+
+  describe('useProjections option', () => {
+    it('honours useProjections=false even when the heuristic would project', () => {
+      const result = HtmlDiff.analyze('<p>hello world</p>', '<div>hello world</div>', { useProjections: false })
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+      // Structural tags appear as diff tokens — observable consequence.
+      expect(result.oldDiffWords).toContain('<p>')
+      expect(result.newDiffWords).toContain('<div>')
+    })
+
+    it('honours useProjections=true even when the heuristic would skip', () => {
+      // Same structural tags on both sides → heuristic skips projection.
+      // Forcing it should still project (strip the <p> tags from diff space).
+      const result = HtmlDiff.analyze('<p>a b c</p>', '<p>a x c</p>', { useProjections: true })
+      expect(result.oldContentToOriginal).not.toBeNull()
+      expect(result.newContentToOriginal).not.toBeNull()
+      // Structural tags removed from diff arrays.
+      expect(result.oldDiffWords).not.toContain('<p>')
+    })
+
+    it('keeps projections off when useProjections=true but one side has no content', () => {
+      const result = HtmlDiff.analyze('<p></p>', '<p>added</p>', { useProjections: true })
+      // Empty-content side disables the forced projection.
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+    })
+  })
+
+  describe('symmetric V2 tokenisation', () => {
+    it('produces an identical V2 diff array across two calls when useProjections matches', () => {
+      const v1 = '<p>Hello world.</p>'
+      const v2 = '<p>Hello cruel world.</p>'
+      const v3 = '<p>Hello cruel world today.</p>'
+      const useProjections = false // Force off — both calls agree.
+      const d1 = HtmlDiff.analyze(v1, v2, { useProjections })
+      const d2 = HtmlDiff.analyze(v2, v3, { useProjections })
+      expect(d1.newDiffWords).toEqual(d2.oldDiffWords)
+    })
+
+    it('the V2 arrays diverge when one call projects and the other does not (motivates D1)', () => {
+      // Asymmetric structural patterns: V1 has <p>, V3 has <div>; V2 has <p>.
+      // V1↔V2 heuristic: no structural diff → no projection.
+      // V2↔V3 heuristic: structural diff → project.
+      // Result: d1.newDiffWords (raw V2) ≠ d2.oldDiffWords (projected V2).
+      const v1 = '<p>Hello world.</p>'
+      const v2 = '<p>Hello cruel world.</p>'
+      const v3 = '<div>Hello cruel world today.</div>'
+      const d1 = HtmlDiff.analyze(v1, v2)
+      const d2 = HtmlDiff.analyze(v2, v3)
+      // This is the bug that D1's symmetric-decision design exists to prevent.
+      expect(d1.newDiffWords).not.toEqual(d2.oldDiffWords)
+    })
+  })
+
+  describe('options pass-through', () => {
+    it('respects ignoreWhitespaceDifferences', () => {
+      // With the flag on, the matcher should consider two-space and
+      // single-space as equivalent; without it, they replace.
+      const withoutFlag = HtmlDiff.analyze('a  b', 'a b')
+      const withFlag = HtmlDiff.analyze('a  b', 'a b', { ignoreWhitespaceDifferences: true })
+      const replaceCount = (r: typeof withFlag) => r.operations.filter(op => op.action === Action.Replace).length
+      // Flag off: whitespace difference shows up as a Replace.
+      expect(replaceCount(withoutFlag)).toBeGreaterThan(0)
+      // Flag on: no Replace, only Equals.
+      expect(replaceCount(withFlag)).toBe(0)
+    })
+
+    it('respects blockExpressions', () => {
+      // Without the block expression, "01/01/2026" is split into multiple
+      // tokens; with it, the whole date is one token (per WordSplitter's
+      // BlockFinder contract — uses the `g` flag).
+      const dateExpr = /\d{2}\/\d{2}\/\d{4}/g
+      const without = HtmlDiff.analyze('on 01/01/2026 here', 'on 02/02/2027 here')
+      const withExpr = HtmlDiff.analyze('on 01/01/2026 here', 'on 02/02/2027 here', { blockExpressions: [dateExpr] })
+      expect(withExpr.oldDiffWords.length).toBeLessThan(without.oldDiffWords.length)
+    })
+  })
+})
+
+describe('HtmlDiff.evaluateProjectionApplicability', () => {
+  it('returns false when structures match', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p>a</p>', '<p>b</p>')).toBe(false)
+  })
+
+  it('returns true when structures differ (wrapper rename)', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p>a b c</p>', '<div>a b c</div>')).toBe(true)
+  })
+
+  it('returns false when one side has no structural tags at all', () => {
+    // Plain text vs wrapped HTML: shouldUseContentProjections bails.
+    expect(HtmlDiff.evaluateProjectionApplicability('plain text', '<p>plain text</p>')).toBe(false)
+  })
+
+  it('returns false when projection would empty one side', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p></p>', '<div>content</div>')).toBe(false)
+  })
+
+  it('lets a composer compute a symmetric decision across three inputs', () => {
+    const v1 = '<p>Hello world.</p>'
+    const v2 = '<p>Hello cruel world.</p>'
+    const v3 = '<div>Hello cruel world today.</div>'
+    const proj12 = HtmlDiff.evaluateProjectionApplicability(v1, v2)
+    const proj23 = HtmlDiff.evaluateProjectionApplicability(v2, v3)
+    // The symmetric decision is the conjunction — project iff both pairs would.
+    const symmetric = proj12 && proj23
+    expect(symmetric).toBe(false) // V1↔V2 has no structural diff.
+    // Both calls then use useProjections=false and V2 tokenises identically.
+    const d1 = HtmlDiff.analyze(v1, v2, { useProjections: symmetric })
+    const d2 = HtmlDiff.analyze(v2, v3, { useProjections: symmetric })
+    expect(d1.newDiffWords).toEqual(d2.oldDiffWords)
+  })
+})

package/test/HtmlDiff.tables.matrix.spec.ts

@@ -108,9 +108,14 @@ describe('HtmlDiff — table operations matrix', () => {
       // still drifts.
       const rowCount = countMatches(result, /<tr[\s>]/g)
       expect(rowCount).toBe(4) // header + Party A + empty + Party B
-      expect(result).toContain(
-        "<tr class='diffins'><td class='diffins'></td><td class='diffins'></td><td class='diffins'></td><td class='diffins'></td></tr>"
-      )
+      // The inserted empty row must be emitted with diffins on the <tr>
+      // and 4 empty diffins-marked cells. Asserted via regex (quote-
+      // agnostic, whitespace-tolerant) so an incidental change in
+      // attribute-quote style isn't flagged as a regression.
+      const emptyInsertedRow = result.match(/<tr class=['"]diffins['"]>(.*?)<\/tr>/)
+      expect(emptyInsertedRow).not.toBeNull()
+      const emptyCellCount = countMatches(emptyInsertedRow?.[1] ?? '', /<td class=['"]diffins['"]><\/td>/g)
+      expect(emptyCellCount).toBe(4)
     })
   })
 })

package/test/HtmlDiff.tables.spec.ts

@@ -859,7 +859,15 @@ describe('HtmlDiff — tables', () => {
         '<table><tr><td>A</td><td>X</td></tr><tr data-behaviour="data"><td>B</td><td>EXTRA</td><td>C</td></tr></table>'
 
       const result = HtmlDiff.execute(oldHtml, newHtml)
-      expect(result).toContain('<tr data-behaviour="data">')
+      // The <tr> attribute must survive AND the row's cells must be
+      // intact: B preserved, EXTRA inserted, C preserved. A bare
+      // `toContain('<tr data-behaviour="data">')` would pass even if
+      // the cells were dropped or duplicated downstream.
+      expect(result).toContain(
+        '<tr data-behaviour="data"><td>B</td>' +
+          "<td class='diffins'><ins class='diffins'>EXTRA</ins></td>" +
+          '<td>C</td></tr>'
+      )
     })
 
     it('preserves data-* attribute on a <tr> when the row passes through fuzzy-matching with content edit', () => {
@@ -879,7 +887,12 @@ describe('HtmlDiff — tables', () => {
         '</table>'
 
       const result = HtmlDiff.execute(oldHtml, newHtml)
-      expect(result).toContain('<tr data-behaviour="data">')
+      // Same intent as above: attribute must survive AND the row's
+      // content-edit must be present on the same <tr>.
+      expect(result).toContain(
+        '<tr data-behaviour="data"><td>The quick brown fox jumps over' +
+          "<ins class='diffins'>&nbsp;the lazy dog</ins>.</td></tr>"
+      )
     })
 
     it('preserves <table> attributes verbatim from new (no diff marker on attribute changes)', () => {
@@ -1573,12 +1586,13 @@ describe('HtmlDiff — tables', () => {
     })
   })
 
-  // Coverage gaps surfaced by the v8 report: the cell-LCS fallback path
-  // (diffStructurallyAlignedRow + cellKey + pairSimilarUnmatchedCells) is
-  // only entered when the per-row column delta exceeds MAX_COLUMN_DELTA
-  // (6) or the row's logical width exceeds MAX_COLUMN_SEARCH_WIDTH (40).
-  // None of the existing tests trigger that. These tests exercise the
-  // fallback and pin its behaviour.
+  // The cell-LCS fallback path (diffStructurallyAlignedRow + cellKey +
+  // pairSimilarUnmatchedCells) is now entered only when the per-row
+  // column delta exceeds MAX_COLUMN_DELTA (6) — the semantic "this is a
+  // row rewrite, not a column add" guard. The row-width guard
+  // (MAX_COLUMN_SEARCH_WIDTH) is now defensive only since the DP is
+  // O(M × N). These tests pin the fallback's behaviour for the
+  // delta > 6 path.
   describe('cell-LCS fallback for very-wide column changes', () => {
     it('handles 8 columns inserted alongside existing cells (delta > MAX_COLUMN_DELTA)', () => {
       // Old: 3 cells. New: 11 cells (8 columns added). Exact-LCS finds
@@ -1689,22 +1703,25 @@ describe('HtmlDiff — tables', () => {
       const newHtml =
         '<table><tr>' + '<td>FirstB</td>' + '<td colspan="2">Merged AB</td>' + '<td>LastB</td>' + '</tr></table>'
 
-      const result = HtmlDiff.execute(oldHtml, newHtml)
       // First and last cells should diff content cell-by-cell (matching
       // colspans = 1 on both sides); middle two old cells merge into
-      // one colspan=2 cell tagged 'mod colspan'.
-      expect(result).toContain("<del class='diffmod'>FirstA</del>")
-      expect(result).toContain("<ins class='diffmod'>FirstB</ins>")
-      expect(result).toContain('colspan="2" class=\'mod colspan\'')
-      expect(result).toContain("<del class='diffmod'>LastA</del>")
-      expect(result).toContain("<ins class='diffmod'>LastB</ins>")
+      // one colspan=2 cell tagged 'mod colspan'. Asserted as an exact
+      // string so that a positional swap of first/last is caught — a
+      // swap-blind set of `toContain` assertions would not flag it.
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table><tr>' +
+          "<td><del class='diffmod'>FirstA</del><ins class='diffmod'>FirstB</ins></td>" +
+          `<td colspan="2" class='mod colspan'>Merged AB</td>` +
+          "<td><del class='diffmod'>LastA</del><ins class='diffmod'>LastB</ins></td>" +
+          '</tr></table>'
+      )
     })
 
-    it('handles row wider than MAX_COLUMN_SEARCH_WIDTH (40 cells) — fallback to cell-LCS', () => {
+    it('handles a 50-cell row with a single column inserted at start', () => {
       // 50-cell row in old, 51-cell row in new (1 column added at
-      // start). MAX_COLUMN_SEARCH_WIDTH guard prevents the
-      // combinatorial search; fallback to cell-LCS which finds 50
-      // exact matches and the 1 new cell as an insertion.
+      // start). Now stays on the DP path (MAX_COLUMN_SEARCH_WIDTH=200);
+      // produces the same output as the prior cell-LCS fallback would
+      // have: 1 inserted cell, 50 preserved.
       const oldCells = Array.from({ length: 50 }, (_, i) => `<td>c${i}</td>`).join('')
       const newCells = `<td>NEW</td>${oldCells}`
       const oldHtml = `<table><tr>${oldCells}</tr></table>`
@@ -1741,4 +1758,336 @@ describe('HtmlDiff — tables', () => {
       )
     })
   })
+
+  // The column-position search can encounter score ties when inserted
+  // cells have content that is similar both to each other and to
+  // existing cells (e.g. boilerplate "N/A" in a legal schedule). The
+  // algorithm's tie-breaking resolves to skipping LATER positions in
+  // the longer side — the lex-first-combo behaviour of the original
+  // combinatorial path, now matched by "prefer pair on ties" in the DP
+  // backtrack. These tests pin both the structural shape AND the exact
+  // positions the diffins markers land on, so a silent shift of the
+  // tie-breaking rule would fail loudly.
+  describe('column-position search — score-tied inputs', () => {
+    it('handles delta=2 with content-similar inserts (N/A boilerplate)', () => {
+      const oldHtml = '<table><tr><td>N/A</td><td>Term</td><td>Amount</td><td>N/A</td></tr></table>'
+      const newHtml =
+        '<table><tr><td>N/A</td><td>N/A</td><td>Term</td><td>N/A</td><td>Amount</td><td>N/A</td></tr></table>'
+
+      // Exact match locks in tie-breaking: the diffins markers MUST land
+      // on the earliest positions that produce the optimal score (here:
+      // positions 0 and 3).
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table><tr>' +
+          "<td class='diffins'><ins class='diffins'>N/A</ins></td>" +
+          '<td>N/A</td>' +
+          '<td>Term</td>' +
+          "<td class='diffins'><ins class='diffins'>N/A</ins></td>" +
+          '<td>Amount</td>' +
+          '<td>N/A</td>' +
+          '</tr></table>'
+      )
+    })
+
+    it('still passes the loose structural checks for the same inputs', () => {
+      // Kept alongside the exact-match assertion above as a structural
+      // safety net: if the exact form ever shifts (e.g. quote style),
+      // these structural invariants still apply.
+      const oldHtml = '<table><tr><td>N/A</td><td>Term</td><td>Amount</td><td>N/A</td></tr></table>'
+      const newHtml =
+        '<table><tr><td>N/A</td><td>N/A</td><td>Term</td><td>N/A</td><td>Amount</td><td>N/A</td></tr></table>'
+
+      const result = HtmlDiff.execute(oldHtml, newHtml)
+      // Both inserted N/A cells must be marked diffins.
+      const insMarkers = (result.match(/<td class='diffins'>/g) || []).length
+      expect(insMarkers).toBe(2)
+      // Total td count must be 6 (no phantoms).
+      const tdCount = (result.match(/<td[\s>]/g) || []).length
+      expect(tdCount).toBe(6)
+      // Term and Amount must appear as unmarked preserved cells exactly
+      // once each — they're not similar to N/A, so the algorithm has no
+      // ambiguity around them.
+      expect(result).toContain('<td>Term</td>')
+      expect(result).toContain('<td>Amount</td>')
+    })
+
+    it('handles delta=6 (the MAX_COLUMN_DELTA cap) without misalignment', () => {
+      const oldHtml = '<table><tr><td>A</td><td>B</td><td>C</td><td>D</td></tr></table>'
+      const newHtml =
+        '<table><tr>' +
+        '<td>A</td><td>X1</td><td>X2</td><td>B</td><td>X3</td>' +
+        '<td>X4</td><td>C</td><td>X5</td><td>X6</td><td>D</td>' +
+        '</tr></table>'
+
+      const result = HtmlDiff.execute(oldHtml, newHtml)
+      // Exactly 6 cells inserted, 4 preserved.
+      const insMarkers = (result.match(/<td class='diffins'>/g) || []).length
+      expect(insMarkers).toBe(6)
+      const tdCount = (result.match(/<td[\s>]/g) || []).length
+      expect(tdCount).toBe(10)
+      // All four original cells survive in order without diff markers.
+      expect(result).toContain('<td>A</td>')
+      expect(result).toContain('<td>B</td>')
+      expect(result).toContain('<td>C</td>')
+      expect(result).toContain('<td>D</td>')
+    })
+  })
+
+  // orderAlignmentForEmission's `preserved` list is empty when no rows
+  // survive across the diff. The "delete every row" and "insert every
+  // row" cases are corner cases where the float-positioning logic must
+  // degenerate cleanly: every del's primary becomes `-0.5` (predecessor
+  // index -1), every ins's primary is its own newIdx. Both should emit
+  // in oldIdx / newIdx order respectively, with no preserved rows
+  // sandwiched between them.
+  describe('orderAlignmentForEmission — empty preserved list', () => {
+    it('emits every row as diffdel when new is empty (no preserved rows)', () => {
+      const oldHtml =
+        '<table>' +
+        '<tr><td>r1</td></tr>' +
+        '<tr><td>r2</td></tr>' +
+        '<tr><td>r3</td></tr>' +
+        '<tr><td>r4</td></tr>' +
+        '<tr><td>r5</td></tr>' +
+        '</table>'
+      const newHtml = '<table></table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>r1</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>r2</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>r3</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>r4</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>r5</del></td></tr>" +
+          '</table>'
+      )
+    })
+
+    it('emits every row as diffins when old is empty (no preserved rows)', () => {
+      const oldHtml = '<table></table>'
+      const newHtml = '<table>' + '<tr><td>r1</td></tr>' + '<tr><td>r2</td></tr>' + '<tr><td>r3</td></tr>' + '</table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>r1</ins></td></tr>" +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>r2</ins></td></tr>" +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>r3</ins></td></tr>" +
+          '</table>'
+      )
+    })
+
+    it('emits all-deletes in order when only the header is preserved', () => {
+      // The header is the only preserved row, so 'preserved' has 1 entry
+      // and every del's newIdxOfPreservedBefore returns -1 — exercising
+      // the boundary between empty-preserved and a single anchoring row.
+      const oldHtml =
+        '<table>' +
+        '<tr><td>Header</td></tr>' +
+        '<tr><td>row a</td></tr>' +
+        '<tr><td>row b</td></tr>' +
+        '<tr><td>row c</td></tr>' +
+        '</table>'
+      const newHtml = '<table><tr><td>Header</td></tr></table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          '<tr><td>Header</td></tr>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row a</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row b</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row c</del></td></tr>" +
+          '</table>'
+      )
+    })
+  })
+
+  // Fuzzy row-pairing threshold (0.5) calibrations on ISDA-flavoured
+  // content. The interesting cases are at the edges: rows that share a
+  // little (an enumeration prefix only) — must NOT pair (otherwise an
+  // unrelated rewrite shows up as a single-row content edit); rows that
+  // share a lot of boilerplate text but differ in the meaningful body —
+  // must pair (otherwise the user sees del+ins instead of an edit).
+  describe('fuzzy row pairing — enumerated clauses and shared boilerplate', () => {
+    it('does NOT pair rows that share only an enumeration prefix (different bodies)', () => {
+      // Old has 2 rows, new has 3 rows. The "1." and "2." prefixes are
+      // the only commonality — bodies are completely unrelated.
+      // textSimilarity falls below 0.5 (prefix is 3 chars in 60+; jaccard
+      // is also tiny), so fuzzy pairing must NOT fire — each pair should
+      // emit as a clean del + ins, not a noisy intra-row diff.
+      const oldHtml =
+        '<table>' +
+        '<tr><td>1. Party A shall pay the gross amount on each Payment Date.</td></tr>' +
+        '<tr><td>2. Party B shall deliver collateral on each Calculation Date.</td></tr>' +
+        '</table>'
+      const newHtml =
+        '<table>' +
+        '<tr><td>1. Section intentionally left blank.</td></tr>' +
+        '<tr><td>2. Different boilerplate entirely.</td></tr>' +
+        '<tr><td>3. Brand new clause added here.</td></tr>' +
+        '</table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>1. Party A shall pay the gross amount on each Payment Date.</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>2. Party B shall deliver collateral on each Calculation Date.</del></td></tr>" +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>1. Section intentionally left blank.</ins></td></tr>" +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>2. Different boilerplate entirely.</ins></td></tr>" +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>3. Brand new clause added here.</ins></td></tr>" +
+          '</table>'
+      )
+    })
+
+    it('DOES pair rows that share a long boilerplate footer (Jaccard kicks in)', () => {
+      // The 9-char body differs, but the 50-char trailing footer is
+      // identical. Prefix-suffix similarity is low, but token Jaccard is
+      // very high because shared footer tokens dominate the token set.
+      // textSimilarity = Math.max(prefix_suffix, jaccard) → must pair.
+      const footer = ' subject to the terms of the Master Agreement.'
+      const oldHtml = `<table><tr><td>Anchor row</td></tr><tr><td>Alpha now${footer}</td></tr></table>`
+      const newHtml =
+        `<table><tr><td>Anchor row</td></tr><tr><td>Bravo new${footer}</td></tr>` +
+        '<tr><td>Extra row appended</td></tr></table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          '<tr><td>Anchor row</td></tr>' +
+          "<tr><td><del class='diffmod'>Alpha</del><ins class='diffmod'>Bravo</ins> " +
+          "<del class='diffmod'>now</del><ins class='diffmod'>new</ins>" +
+          ' subject to the terms of the Master Agreement.</td></tr>' +
+          "<tr class='diffins'><td class='diffins'><ins class='diffins'>Extra row appended</ins></td></tr>" +
+          '</table>'
+      )
+    })
+  })
+
+  // orderAlignmentForEmission must keep unpaired dels in their correct
+  // positions even when the run contains a mix of preserved rows, fuzzy-
+  // paired rows, and unpaired dels. A regression here would make trailing
+  // dels appear before the row they came after — the same family of bug
+  // as the "deleted rows out of order" report that motivated the
+  // function in the first place.
+  describe('orderAlignmentForEmission — mixed paired and unpaired rows', () => {
+    it('emits trailing unpaired dels after a fuzzy-paired content edit', () => {
+      // Old: [Aaaaa, Bbbbb, Cccc, Dddd]. New: [Aaaaa, Bbbbb+NEW].
+      // After LCS: A is preserved. After pairSimilarUnmatchedRows: B↔B'
+      // via fuzzy. C and D are unpaired dels. The output order must be:
+      // preserved(A) → paired(B,B') → del(C) → del(D).
+      const oldHtml =
+        '<table>' +
+        '<tr><td>Aaaaa shared content here</td></tr>' +
+        '<tr><td>Bbbbb shared content here</td></tr>' +
+        '<tr><td>Cccc deleted row</td></tr>' +
+        '<tr><td>Dddd deleted row</td></tr>' +
+        '</table>'
+      const newHtml =
+        '<table>' +
+        '<tr><td>Aaaaa shared content here</td></tr>' +
+        '<tr><td>Bbbbb shared content here NEW</td></tr>' +
+        '</table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          '<tr><td>Aaaaa shared content here</td></tr>' +
+          "<tr><td>Bbbbb shared content here<ins class='diffins'>&nbsp;NEW</ins></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>Cccc deleted row</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>Dddd deleted row</del></td></tr>" +
+          '</table>'
+      )
+    })
+
+    it('emits dels at the end of the table in old-document order', () => {
+      // Specifically protects against the regression that motivated
+      // orderAlignmentForEmission: deleting the last two rows
+      // simultaneously must emit them in the order they appeared in old
+      // (second-last, then last), not reversed or jumbled.
+      const oldHtml =
+        '<table>' +
+        '<tr><td>kept1</td></tr>' +
+        '<tr><td>kept2</td></tr>' +
+        '<tr><td>second-last</td></tr>' +
+        '<tr><td>last</td></tr>' +
+        '</table>'
+      const newHtml = '<table><tr><td>kept1</td></tr><tr><td>kept2</td></tr></table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          '<tr><td>kept1</td></tr>' +
+          '<tr><td>kept2</td></tr>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>second-last</del></td></tr>" +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>last</del></td></tr>" +
+          '</table>'
+      )
+    })
+  })
+
+  // pairSimilarUnmatched is intentionally greedy (not Hungarian-optimal).
+  // When two unmatched-old entries are both above-threshold matches for
+  // the same unmatched-new entry, the first del wins the pairing only
+  // when iterating in document order means "first" matches the better
+  // candidate. The output must still be structurally valid — no phantom
+  // cells, no dropped content — regardless of which del wins.
+  describe('pairSimilarUnmatchedCells — competing dels for the same ins', () => {
+    it('keeps both candidate cells intact when two old cells could pair with one new cell', () => {
+      // Two old cells with identical content compete for one similar
+      // new cell. The greedy assignment picks one to pair as a content
+      // edit; the other emits as a full diffdel. Both must appear; no
+      // cell may silently vanish.
+      const oldHtml =
+        '<table><tr>' +
+        '<td>Preserved</td>' +
+        '<td>Old content alpha to be edited</td>' +
+        '<td>Old content alpha to be edited</td>' +
+        '</tr></table>'
+      const newHtml = '<table><tr>' + '<td>Preserved</td>' + '<td>Old content alpha CHANGED</td>' + '</tr></table>'
+
+      const result = HtmlDiff.execute(oldHtml, newHtml)
+      // The losing del must emit as a full diffdel cell.
+      expect(result).toContain("<td class='diffdel'><del class='diffdel'>Old content alpha to be edited</del></td>")
+      // The winning pair must emit as a partial content edit.
+      expect(result).toContain("<del class='diffmod'>to be edited</del>")
+      expect(result).toContain("<ins class='diffmod'>CHANGED</ins>")
+      // Structural: 3 tds total in the output (1 preserved, 1 full-del,
+      // 1 paired-edit). No phantoms.
+      const tdCount = (result.match(/<td[\s>]/g) || []).length
+      expect(tdCount).toBe(3)
+    })
+  })
+
+  // Row-LCS on a non-trivial 7-row table where only every other row
+  // matches. Existing named tests max out around 4 rows; the matrix
+  // never produces a row-count drop this large with this much
+  // interleaving. This exercises the LCS DP itself, not just the
+  // diff emission.
+  describe('row-LCS on larger tables', () => {
+    it('finds 4 preserved rows interleaved with 3 dropped rows in a 7-row old table', () => {
+      const oldHtml =
+        '<table>' +
+        '<tr><td>row1 preserved</td></tr>' +
+        '<tr><td>row2 old body</td></tr>' +
+        '<tr><td>row3 preserved</td></tr>' +
+        '<tr><td>row4 old body</td></tr>' +
+        '<tr><td>row5 preserved</td></tr>' +
+        '<tr><td>row6 old body</td></tr>' +
+        '<tr><td>row7 preserved</td></tr>' +
+        '</table>'
+      const newHtml =
+        '<table>' +
+        '<tr><td>row1 preserved</td></tr>' +
+        '<tr><td>row3 preserved</td></tr>' +
+        '<tr><td>row5 preserved</td></tr>' +
+        '<tr><td>row7 preserved</td></tr>' +
+        '</table>'
+
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table>' +
+          '<tr><td>row1 preserved</td></tr>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row2 old body</del></td></tr>" +
+          '<tr><td>row3 preserved</td></tr>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row4 old body</del></td></tr>" +
+          '<tr><td>row5 preserved</td></tr>' +
+          "<tr class='diffdel'><td class='diffdel'><del class='diffdel'>row6 old body</del></td></tr>" +
+          '<tr><td>row7 preserved</td></tr>' +
+          '</table>'
+      )
+    })
+  })
 })