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

package/README.md

@@ -127,6 +127,46 @@ This property defines relative size of the match to be considered as orphan, fro
 
 Returns the diff from an HtmlDiff instance.
 
+### HtmlDiff.executeThreeWay(v1, v2, v3, options?)
+
+Three-way HTML diff for back-and-forth negotiation scenarios. Given:
+
+- `v1` — the version you last sent
+- `v2` — the version the counterparty sent back
+- `v3` — your current draft
+
+`executeThreeWay` produces a single attributed HTML output where the counterparty's changes (V1→V2) and your changes
+(V2→V3) are distinguished by `data-author` and class:
+
+- Counterparty insertions / deletions: `<ins class='diffins cp' data-author='cp'>` / `<del class='diffdel cp' ...>`
+- Your insertions / deletions: `<ins class='diffins me' data-author='me'>` / `<del class='diffdel me' ...>`
+- Your rejections of counterparty insertions (you deleted text they added): `<del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>`
+
+```ts
+import HtmlDiff from '@createiq/htmldiff'
+
+const v1 = '<p>The fee is five percent.</p>'
+const v2 = '<p>The interest fee is five and a half percent.</p>'
+const v3 = '<p>The interest fee is five percent.</p>'
+
+const merged = HtmlDiff.executeThreeWay(v1, v2, v3)
+// Counterparty added "interest" — kept by you.
+// Counterparty changed "five" → "five and a half" — you rejected.
+```
+
+Tables (including multi-table documents) and row/column structural changes are supported with the same author
+attribution at row, cell, and content granularity.
+
+#### Options
+
+`executeThreeWay` accepts the same per-instance options as `HtmlDiff` (`repeatingWordsAccuracy`,
+`ignoreWhitespaceDifferences`, `orphanMatchThreshold`, `blockExpressions`). They flow into both internal pair-wise
+analyses identically.
+
+`useProjections` controls structural-tag normalisation. When undefined (default), the decision is the conjunction of
+both pair-wise heuristics — projection only activates when both V1↔V2 and V2↔V3 would benefit from it. Pass an
+explicit boolean to override.
+
 ## Contributing
 
 The library uses [Biome](https://biomejs.dev/) for linting and formatting, and [Vitest](https://vitest.dev/) for unit