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

package/test/HtmlDiff.spec.ts

@@ -48,6 +48,21 @@ describe('HtmlDiff', () => {
       'Some formatted text',
       "Some <ins class='mod strong i'>formatted</ins> text",
     ],
+    // Overlapping formatting wraps — old wraps a word in <strong>, new wraps the same
+    // word in <u>. The wraps cross (mod-strong opens before mod-u, but the </strong>
+    // closing arrives before </u>), so emission must split the inner wrap to keep
+    // HTML well-formed. Regression: previously left mod-strong unclosed and the
+    // 3-way path threw on the unbalanced stack.
+    [
+      '<strong>three</strong>',
+      '<u>three</u>',
+      "<ins class='mod strong'><u><ins class='mod u'>three</ins></ins><ins class='mod u'></ins></u>",
+    ],
+    [
+      'a <strong>three</strong> b',
+      'a <u>three</u> b',
+      "a <ins class='mod strong'><u><ins class='mod u'>three</ins></ins><ins class='mod u'></ins></u> b",
+    ],
     [
       '<table><tr><td>col1</td><td>col2</td></tr><tr><td>Data 1</td><td>Data 2</td></tr></table>',
       '<table><tr><td>col1</td><td>col2</td></tr></table>',

package/test/HtmlDiff.threeWay.spec.ts

@@ -1,89 +1,191 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
-import HtmlDiff from '../src/HtmlDiff'
+import HtmlDiff, { WORD_ALIGNED_OPTIONS } from '../src/HtmlDiff'
 
-describe('HtmlDiff.executeThreeWay', () => {
+/**
+ * Three-way diff tests under the genesis-spine model.
+ *
+ * `executeThreeWay(genesis, cpLatest, meCurrent)` compares both cp and
+ * me against the shared common ancestor (genesis). Each side's
+ * accumulated changes are attributed independently:
+ *
+ *   - Both authors made the same change → emit plain (settled)
+ *   - One author changed, the other kept the genesis content → emit
+ *     that author's change with attribution; the kept content shows
+ *     "pending" via the del/ins wrapping
+ *   - Both made different changes at the same place → each shown with
+ *     its author's attribution
+ */
+describe('HtmlDiff.executeThreeWay (genesis-spine)', () => {
   describe('attribution matrix', () => {
-    it('CP-only changes — Me made no edits (V3 == V2)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world.')).toBe(
-        "Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world."
+    it('settled — both authors made the same change', () => {
+      // Genesis: "Hello world". Both cp and me changed it to "Hello cruel world".
+      // The change is settled — emit plain.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello cruel world')).toBe(
+        'Hello cruel world'
       )
     })
 
-    it('Me-only changes — CP made no edits (V2 == V1)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello world.', 'Hello world today.')).toBe(
-        "Hello world<ins class='diffins me' data-author='me'>&nbsp;today</ins>."
+    it('CP changes a word, Me kept the genesis word', () => {
+      // Genesis: "Hello world". CP changed to "Hello cruel world". Me kept "Hello world".
+      // From Me's view: CP's insertion is pending. Render with cp attribution; Me's
+      // text ("world") is preserved verbatim.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')).toBe(
+        "Hello <ins class='diffins cp' data-author='cp'>cruel </ins>world"
       )
     })
 
-    it('Me keeps CP insertion (both authors visible)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world today.')).toBe(
-        "Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world<ins class='diffins me' data-author='me'>&nbsp;today</ins>."
+    it('Me changes a word, CP kept genesis', () => {
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello cruel world')).toBe(
+        "Hello <ins class='diffins me' data-author='me'>cruel </ins>world"
       )
     })
 
-    it('Me rejects CP insertion (data-rejects markup)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello world.')).toBe(
-        "Hello<del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>&nbsp;cruel</del> world."
+    it('CP and Me each change the same word differently', () => {
+      // Genesis: "Hello world". CP made "Hello cruel world", Me made "Hello brave world".
+      // Both inserted at the same boundary. Under the intent-reading
+      // model, the reviewer sees CP's proposal relative to Me's
+      // current content: "CP wants `cruel` where Me has `brave`" —
+      // ins-cp `cruel` + del-cp `brave`. Reads as a substitution
+      // intent, which is what a legal reviewer needs to act on.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello brave world')).toBe(
+        "Hello <ins class='diffins cp' data-author='cp'>cruel</ins><del class='diffdel cp' data-author='cp'>brave</del> world"
       )
     })
 
-    it('CP-deletion of V1 text surfaces as a CP-attributed <del>', () => {
+    it('CP deletes a word, Me kept it', () => {
+      // Genesis: "Some really fine print". CP removed "really". Me kept it.
+      // Render genesis token "really" with del-cp markup — Me's text still has it.
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some fine print', 'Some really fine print')).toBe(
+        "Some<del class='diffdel cp' data-author='cp'>&nbsp;really</del> fine print"
+      )
+    })
+
+    it('Me deletes a word, CP kept it', () => {
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some really fine print', 'Some fine print')).toBe(
+        "Some<del class='diffdel me' data-author='me'>&nbsp;really</del> fine print"
+      )
+    })
+
+    it('Both authors delete the same content → settled, silenced', () => {
+      // Genesis: "Some really fine print". Both removed "really".
+      // Settled — neither the deletion nor any del markup appears.
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some fine print', 'Some fine print')).toBe(
+        'Some fine print'
+      )
+    })
+
+    it("CP accepted Me's addition with a word removed — del-cp on the removed word", () => {
+      // Real flow on the live preview:
+      //   - Me appends "And I add more things here"
+      //   - CP "accepts" Me's addition but deletes the word "things"
+      // Intent reading: CP wants "things" gone. del-cp on the me-only
+      // word; the rest of the shared addition is settled.
       expect(
-        HtmlDiff.executeThreeWay('Some really fine print here.', 'Some fine print here.', 'Some fine print here.')
-      ).toBe("Some<del class='diffdel cp' data-author='cp'>&nbsp;really</del> fine print here.")
+        HtmlDiff.executeThreeWay('baseline.', 'baseline. And I add more here', 'baseline. And I add more things here')
+      ).toBe("baseline. And I add more<del class='diffdel cp' data-author='cp'>&nbsp;things</del> here")
     })
 
-    it('Me-deletion of original V1 text (CP did nothing, Me deleted)', () => {
+    it("CP rewrote one of Me's added words — del-cp on the replaced word + ins-cp on the replacement", () => {
+      // Non-subset variant: CP didn't just delete, they substituted.
+      //   Me: "And I add more things here"
+      //   CP: "And I add more anything here"
+      // The single word differs — the intent reading is "CP wants
+      // things replaced with anything".
       expect(
         HtmlDiff.executeThreeWay(
-          'Some really fine print here.',
-          'Some really fine print here.',
-          'Some fine print here.'
+          'baseline.',
+          'baseline. And I add more anything here',
+          'baseline. And I add more things here'
         )
-      ).toBe("Some<del class='diffdel me' data-author='me'>&nbsp;really</del> fine print here.")
+      ).toBe(
+        "baseline. And I add more <ins class='diffins cp' data-author='cp'>anything</ins><del class='diffdel cp' data-author='cp'>things</del> here"
+      )
     })
 
-    it('CP and Me Replace ops in different places (del-then-ins for both)', () => {
-      // CP did will→shall; Me did thirty→sixty business. Both Replaces
-      // must emit del-then-ins in source order, matching the 2-way
-      // convention so the diff reads naturally.
+    it("CP extended Me's addition with extra words — ins-cp on the additions, no del", () => {
+      // CP added beyond me — cp-extras stay as ins-cp, no del-cp
+      // since CP didn't remove anything.
+      //   Me: "And I add more things here"
+      //   CP: "And I add more things and other stuff here"
       expect(
         HtmlDiff.executeThreeWay(
-          'The party will pay the fee within thirty days.',
-          'The party shall pay the fee within thirty days.',
-          'The party shall pay the fee within sixty business days.'
+          'baseline.',
+          'baseline. And I add more things and other stuff here',
+          'baseline. And I add more things here'
         )
-      ).toBe(
-        "The party <del class='diffdel cp' data-author='cp'>will</del><ins class='diffins cp' data-author='cp'>shall</ins> pay the fee within <del class='diffdel me' data-author='me'>thirty</del><ins class='diffins me' data-author='me'>sixty business</ins> days."
-      )
+      ).toBe("baseline. And I add more things<ins class='diffins cp' data-author='cp'>&nbsp;and other stuff</ins> here")
     })
-  })
 
-  describe('Replace-collision and tail-end edge cases', () => {
-    it('Replace collision — CP and Me each replace the same V2 token', () => {
-      // V1: "foo" → V2: "bar" (CP Replace). V2: "bar" → V3: "baz" (Me Replace).
-      // V2's "bar" is replaced-into-by-cp AND replaced-out-by-me → reject.
-      // Off-spine: V1's "foo" (cpDel) emitted before; V3's "baz" (meIns)
-      // emitted after the reject (mirrors the del-then-ins ordering).
-      expect(HtmlDiff.executeThreeWay('foo', 'bar', 'baz')).toBe(
-        "<del class='diffdel cp' data-author='cp'>foo</del><del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>bar</del><ins class='diffins me' data-author='me'>baz</ins>"
+    it("Me added text that CP didn't engage with — stays as ins-me, NOT del-cp", () => {
+      // The critical inverse: Me appends a new paragraph that CP
+      // doesn't have anything for at that boundary. This is a
+      // genuine Me-side insertion — NOT a "CP removed" event. The
+      // emitBoundary's single-side branch (!hasCp) preserves
+      // ins-me attribution. Without this carve-out, every Me
+      // insertion would be mis-attributed as "CP wants this gone",
+      // even when CP never engaged with the content.
+      expect(HtmlDiff.executeThreeWay('baseline.', 'baseline.', 'baseline. New paragraph Me added.')).toBe(
+        "baseline.<ins class='diffins me' data-author='me'>&nbsp;New paragraph Me added.</ins>"
       )
     })
 
-    it('tail-end interleavings — CP deletion + Me insertion both at the end of V2', () => {
-      // V1 = "Hello world" (CP deletes " world" → V2 = "Hello").
-      // V2 = "Hello" (Me adds " cruel" → V3 = "Hello cruel").
-      // Both off-spine ops land at the tail boundary; output order is
-      // cpDel then meIns (no V2 token to anchor around).
-      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello', 'Hello cruel')).toBe(
-        "Hello<del class='diffdel cp' data-author='cp'>&nbsp;world</del><ins class='diffins me' data-author='me'>&nbsp;cruel</ins>"
+    it('CP and Me each added different content at different boundaries — each side keeps their own attribution', () => {
+      // Me added at the end of one sentence; CP added at the end of
+      // another. Different genesis boundaries — each goes through
+      // the !hasCp / !hasMe single-side branch. Neither side's
+      // addition surfaces as the other's deletion.
+      expect(
+        HtmlDiff.executeThreeWay(
+          'First sentence. Second sentence.',
+          'First sentence with cp-addition. Second sentence.',
+          'First sentence. Second sentence with me-addition.'
+        )
+      ).toBe(
+        "First sentence<ins class='diffins cp' data-author='cp'>&nbsp;with cp-addition</ins>. Second sentence<ins class='diffins me' data-author='me'>&nbsp;with me-addition</ins>."
       )
     })
+
+    it('Stable across no-change rounds — V5 produces same output as V3 when V5==V3', () => {
+      // The user's V3/V5 invariant: when neither party changes their position
+      // in a subsequent turn, the diff should look identical to the previous
+      // turn's diff. With the genesis spine, this falls out automatically.
+      const genesis = 'The quick brown fox jumps over the lazy dog'
+      const cp = 'The fast brown fox leaps'
+      const me = 'The quick brown antelope leaps over the lazy pig'
+      const v3Output = HtmlDiff.executeThreeWay(genesis, cp, me)
+      const v5Output = HtmlDiff.executeThreeWay(genesis, cp, me)
+      expect(v5Output).toBe(v3Output)
+      // Sanity check the V3 output contains all four author-attributed changes
+      // from the user's expected output (quick→fast cp, fox→antelope me, etc.)
+      expect(v3Output).toMatch(/<del class='diffdel cp' data-author='cp'>quick<\/del>/)
+      expect(v3Output).toMatch(/<ins class='diffins cp' data-author='cp'>fast<\/ins>/)
+      expect(v3Output).toMatch(/<del class='diffdel me' data-author='me'>fox<\/del>/)
+      expect(v3Output).toMatch(/<ins class='diffins me' data-author='me'>antelope<\/ins>/)
+    })
+
+    it('Inverted view — switching cp and me args produces inverted attribution', () => {
+      // From the user's V4 example: same genesis, but from Party B's view
+      // cp and me swap. The output should have all attributions inverted.
+      const genesis = 'The quick brown fox jumps over the lazy dog'
+      const partyACurrent = 'The quick brown antelope leaps over the lazy pig'
+      const partyBCurrent = 'The fast brown fox leaps'
+
+      const aView = HtmlDiff.executeThreeWay(genesis, partyBCurrent, partyACurrent) // A is me, B is cp
+      const bView = HtmlDiff.executeThreeWay(genesis, partyACurrent, partyBCurrent) // B is me, A is cp
+
+      // A's view: B made fast/leaps changes (CP-attributed), A made antelope/pig (Me).
+      expect(aView).toMatch(/<ins class='diffins cp' data-author='cp'>fast<\/ins>/)
+      expect(aView).toMatch(/<ins class='diffins me' data-author='me'>antelope<\/ins>/)
+
+      // B's view: A made antelope/pig (now CP), B made fast/leaps (now Me).
+      expect(bView).toMatch(/<ins class='diffins me' data-author='me'>fast<\/ins>/)
+      expect(bView).toMatch(/<ins class='diffins cp' data-author='cp'>antelope<\/ins>/)
+    })
   })
 
   describe('identity inputs', () => {
-    it('V1 == V2 == V3 returns the input verbatim', () => {
+    it('all three identical → input verbatim', () => {
       const text = '<p>Nothing changed at all.</p>'
       expect(HtmlDiff.executeThreeWay(text, text, text)).toBe(text)
     })
@@ -92,77 +194,199 @@ describe('HtmlDiff.executeThreeWay', () => {
       expect(HtmlDiff.executeThreeWay('', '', '')).toBe('')
     })
 
-    it('V1 == V2 collapses to a single-author diff (CP did nothing)', () => {
-      const out = HtmlDiff.executeThreeWay('Hello world.', 'Hello world.', 'Hello brave world.')
+    it('cp matches genesis (only Me changed)', () => {
+      // Negative assertion is load-bearing: without `not.toContain`
+      // a cp↔me swap inside the genesis-spine merge would still
+      // emit `data-author='cp'` somewhere in the output and the
+      // positive assertion would silently pass.
+      const out = HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello brave world')
       expect(out).toContain("data-author='me'")
       expect(out).not.toContain("data-author='cp'")
     })
 
-    it('V2 == V3 collapses to a single-author diff (Me did nothing)', () => {
-      const out = HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world.')
+    it('me matches genesis (only CP changed)', () => {
+      const out = HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')
       expect(out).toContain("data-author='cp'")
       expect(out).not.toContain("data-author='me'")
     })
   })
 
   describe('HTML structure handling', () => {
-    it('preserves wrapping <p> tags around an attributed run', () => {
-      expect(
-        HtmlDiff.executeThreeWay('<p>Hello world.</p>', '<p>Hello cruel world.</p>', '<p>Hello cruel world.</p>')
-      ).toBe("<p>Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world.</p>")
+    it('preserves wrapping <p> tags', () => {
+      expect(HtmlDiff.executeThreeWay('<p>Hello world.</p>', '<p>Hello cruel world.</p>', '<p>Hello world.</p>')).toBe(
+        "<p>Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world.</p>"
+      )
     })
 
-    it('attributes formatting-tag edits via the special-case path', () => {
-      // V1 plain; CP wraps "fee" in <strong>; Me leaves it. The
-      // formatting-tag special case inside insertTag now carries the
-      // author class through to the `mod` ins wrapper.
-      const out = HtmlDiff.executeThreeWay(
-        '<p>The fee is due.</p>',
-        '<p>The <strong>fee</strong> is due.</p>',
-        '<p>The <strong>fee</strong> is due.</p>'
-      )
-      expect(out).toContain("data-author='cp'")
-      expect(out).toMatch(/<ins class='mod[^']*cp'/)
+    it('multi-paragraph with edits in different paragraphs by each author', () => {
+      const genesis = '<p>First paragraph.</p><p>Second paragraph.</p>'
+      const cp = '<p>First paragraph edited by CP.</p><p>Second paragraph.</p>'
+      const me = '<p>First paragraph.</p><p>Second paragraph edited by Me.</p>'
+      const out = HtmlDiff.executeThreeWay(genesis, cp, me)
+      // CP's edit appears in the first paragraph, Me's in the second.
+      expect(out).toMatch(/<p>First paragraph.*data-author='cp'.*<\/p>/)
+      expect(out).toMatch(/<p>Second paragraph.*data-author='me'.*<\/p>/)
     })
 
-    it('multi-paragraph: each author scoped to their own paragraph', () => {
-      expect(
-        HtmlDiff.executeThreeWay(
-          '<p>First paragraph.</p><p>Second paragraph.</p>',
-          '<p>First paragraph edited by CP.</p><p>Second paragraph.</p>',
-          '<p>First paragraph edited by CP.</p><p>Second paragraph also edited by Me.</p>'
-        )
-      ).toBe(
-        "<p>First paragraph<ins class='diffins cp' data-author='cp'>&nbsp;edited by CP</ins>.</p><p>Second paragraph<ins class='diffins me' data-author='me'>&nbsp;also edited by Me</ins>.</p>"
+    it('overlapping formatting wraps from each author do not unbalance the emission stack', () => {
+      // Genesis: plain "three". CP wrapped it in <strong>, Me in <u>. The
+      // mod-strong (cp) and mod-u (me) wraps cross: <strong> opens before
+      // <u>, but </strong> arrives before </u>. The emitter must split
+      // the inner wrap so the output stays well-formed instead of
+      // throwing an unbalanced-stack error.
+      //
+      // Under the intent-reading model, Me's `<u>` wrap is a
+      // formatting choice CP didn't make — surfaces as a CP-attributed
+      // mod wrap (since CP's view doesn't include the underline). The
+      // load-bearing assertion here is that the emission stays
+      // balanced — the exact mod-author labelling reflects the
+      // asymmetric reading and matches the rest of the suite.
+      expect(HtmlDiff.executeThreeWay('three', '<strong>three</strong>', '<u>three</u>')).toBe(
+        "<strong><ins class='mod strong cp' data-author='cp'><ins class='mod u cp' data-author='cp'>three</ins></ins></strong><ins class='mod u cp' data-author='cp'></ins>"
       )
     })
   })
 
   describe('options pass-through', () => {
     it('honours ignoreWhitespaceDifferences', () => {
+      // Genesis: "a  b" (double space). CP keeps it, Me uses "a b" (single space).
       const without = HtmlDiff.executeThreeWay('a  b', 'a  b', 'a b')
       const withFlag = HtmlDiff.executeThreeWay('a  b', 'a  b', 'a b', { ignoreWhitespaceDifferences: true })
-      // Without the flag, the whitespace difference triggers a Me-attributed Replace.
       expect(without).toContain("data-author='me'")
-      // With the flag, no diff at all.
+      // CP matches genesis — any cp attribution would be a mis-merge.
+      expect(without).not.toContain("data-author='cp'")
       expect(withFlag).not.toContain('data-author=')
     })
+  })
+
+  describe('stack-balance defence', () => {
+    // The emission walks segments built by `buildSegments`: ins/del
+    // segments go through `insertTag` (which manages the formatting-
+    // tag stack), but equal segments push raw words straight to the
+    // content buffer. When a formatting opener is in a del segment
+    // and its matching closer falls in an equal segment, the stack
+    // entry never gets popped — the emitter used to throw "emission
+    // left 1 unclosed formatting tag(s) on the stack" and crash the
+    // caller. Now it closes the leftover wraps defensively with
+    // `</ins>` so the output stays renderable.
+
+    it('CP inserted a <strong> opener whose closer is matched as equal — does not throw', () => {
+      // Genesis has an orphan closer (`X</strong>`); CP wrapped X in
+      // a fresh `<strong>`. The opener is ins-cp (no genesis match)
+      // but the closer is shared by all three and emits as equal.
+      // The mod-`<ins>` opened on the strong push needs to be closed
+      // somehow; the defensive path emits a trailing `</ins>`.
+      expect(() => HtmlDiff.executeThreeWay('X</strong>', '<strong>X</strong>', 'X</strong>')).not.toThrow()
+    })
 
-    it('useProjections=true forces structural normalisation even when heuristic would skip', () => {
-      // V1==V2 has no structural diff (heuristic would skip projection),
-      // V2↔V3 has no structural diff either, so the symmetric default is
-      // also skip. Forcing useProjections=true here is a no-op functionally
-      // but exercises the forced-on code path.
-      const out = HtmlDiff.executeThreeWay('<p>a b c</p>', '<p>a b c</p>', '<p>a x c</p>', { useProjections: true })
-      expect(out).toContain("data-author='me'")
+    it('CP deleted only the <strong> opener — does not throw', () => {
+      // Symmetric: genesis had `<strong>X</strong>`, CP dropped the
+      // opener but kept the closer. The opener-delete pushes onto
+      // the stack and the closer arrives via an equal segment.
+      expect(() => HtmlDiff.executeThreeWay('<strong>X</strong>', 'X</strong>', '<strong>X</strong>')).not.toThrow()
+    })
+
+    it('emits the defensive </ins> close and logs a warning when the stack is unbalanced', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        const out = HtmlDiff.executeThreeWay('X</strong>', '<strong>X</strong>', 'X</strong>')
+        // The content survives.
+        expect(out).toContain('X')
+        // The defensive close path actually ran — output contains
+        // at least one `</ins>` that wasn't paired by `insertTag`
+        // (the only way the defensive branch can add one).
+        expect(out).toMatch(/<\/ins>/)
+        // And the warn was emitted. Without this assertion the path
+        // could silently stop firing in a future refactor and the
+        // test would still pass on the (incidentally-present) content.
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('unclosed formatting wrap'))
+      } finally {
+        warn.mockRestore()
+      }
+    })
+  })
+
+  describe('WORD_ALIGNED_OPTIONS — opinionated consumer defaults', () => {
+    // The library default (`orphanMatchThreshold = 0`) keeps every LCS
+    // match, however small — which fragments long sentence rewrites
+    // into many tiny ins/del pairs around stray word matches. Word's
+    // track-changes collapses those into a single coarse del+ins,
+    // which is markedly more readable for legal text. The exported
+    // `WORD_ALIGNED_OPTIONS` lets consumers opt into that without
+    // re-tuning the magic number themselves.
+    const longGenesis =
+      '"Specified Indebtedness" will have the meaning specified in Section 14 and shall include, with respect to Party B, any obligation (whether present or future, contingent or otherwise) for the payment or repayment of money.'
+    const longCp =
+      '"Specified Indebtedness" will have the meaning specified in Section 14 of the Agreement except that such term shall not include obligations.'
+
+    it('exports a 0.25 orphan threshold tuned for Word-aligned output', () => {
+      expect(WORD_ALIGNED_OPTIONS).toEqual({ orphanMatchThreshold: 0.25 })
+    })
+
+    it('plumbs through HtmlDiff.execute and reduces fragmentation versus the bare default', () => {
+      const bare = HtmlDiff.execute(longGenesis, longCp)
+      const aligned = HtmlDiff.execute(longGenesis, longCp, WORD_ALIGNED_OPTIONS)
+      const count = (s: string, re: RegExp) => (s.match(re) ?? []).length
+      // The bare default keeps every tiny match — Word-aligned produces
+      // strictly fewer ins/del wrappers for the same input.
+      expect(count(aligned, /<ins/g)).toBeLessThan(count(bare, /<ins/g))
+      expect(count(aligned, /<del/g)).toBeLessThan(count(bare, /<del/g))
+    })
+
+    it('plumbs through HtmlDiff.executeThreeWay too', () => {
+      const bare = HtmlDiff.executeThreeWay(longGenesis, longCp, longGenesis)
+      const aligned = HtmlDiff.executeThreeWay(longGenesis, longCp, longGenesis, WORD_ALIGNED_OPTIONS)
+      const count = (s: string, re: RegExp) => (s.match(re) ?? []).length
+      expect(count(aligned, /<ins/g)).toBeLessThan(count(bare, /<ins/g))
+      expect(count(aligned, /<del/g)).toBeLessThan(count(bare, /<del/g))
+    })
+  })
+
+  describe('orphan-match guard for structural tags', () => {
+    // Real regression from the live preview (Additional Condition
+    // Precedent in the 2002 ISDA Schedule): when CP deletes a section
+    // whose answer renders as an empty formatting shell —
+    //   <p data-html="x"><em><strong></strong></em></p>
+    // — the `</strong>` and `</em>` matches sit between two content
+    // deletions ("Heading. " before, body after). At
+    // WORD_ALIGNED_OPTIONS.orphanMatchThreshold=0.25 those structural
+    // matches were rejected as orphans, swallowed into the deletion
+    // span, and the browser auto-closed the openers AT THE END of
+    // the deletion — visually rendering the entire deletion as
+    // bold-italic. The orphan filter now exempts tag-only matches
+    // so structural boundaries always survive.
+
+    it('CP deletes section with em+strong heading + plain body — closers stay between heading and body', () => {
+      const genesis =
+        '<p data-html="x"><em><strong>Additional Condition Precedent. </strong></em>For the purposes of Section 2(a)(iii).</p>'
+      const cp = '<p data-html="x"><em><strong></strong></em></p>'
+      const me = genesis
+
+      const out = HtmlDiff.executeThreeWay(genesis, cp, me, WORD_ALIGNED_OPTIONS)
+
+      // </strong> appears BEFORE the body deletion — meaning the
+      // body sits outside the bold-italic wrap, not inside it.
+      const closeStrongIdx = out.indexOf('</strong>')
+      const bodyDelIdx = out.indexOf('For the purposes')
+      expect(closeStrongIdx).toBeGreaterThan(0)
+      expect(bodyDelIdx).toBeGreaterThan(closeStrongIdx)
+      // No `<strong>…<del>body` substring exists — confirm by exact
+      // shape too. Heading wraps in strong+em, body is a plain del.
+      expect(out).toBe(
+        '<p data-html="x"><em><strong>' +
+          "<del class='diffdel cp' data-author='cp'>Additional Condition Precedent. </del>" +
+          '</strong></em>' +
+          "<del class='diffdel cp' data-author='cp'>For the purposes of Section 2(a)(iii).</del>" +
+          '</p>'
+      )
     })
   })
 
-  describe('first-turn fallback (real-world scenario)', () => {
-    it('falls back cleanly when only Party A has edited (V2 == V1)', () => {
-      // The case the user described: when Party B is drafting V2 against
-      // V1, the 3-way view from Party A's perspective shows only Me's
-      // changes — no spurious CP authorship.
+  describe('first-turn fallback', () => {
+    it('cp == genesis means CP made no changes — Me-only attribution', () => {
+      // Common case: this is the first turn where the counterparty hasn't
+      // responded yet, so the cp version equals the genesis. Only Me's
+      // changes appear.
       const out = HtmlDiff.executeThreeWay(
         '<p>Draft contract.</p>',
         '<p>Draft contract.</p>',