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

package/README.md

@@ -127,45 +127,72 @@ 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?)
+### HtmlDiff.executeThreeWay(genesis, cpLatest, meCurrent, 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
+- `genesis` — the shared common ancestor (the version both parties started from)
+- `cpLatest` — the counterparty's current published position
+- `meCurrent` — 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:
+`executeThreeWay` compares both `cpLatest` and `meCurrent` against `genesis` and attributes each side's accumulated
+changes independently:
 
 - 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'>`
+- When both authors made the same change, the result is treated as **settled** and emitted plain (no markup).
+- When both authors deleted the same content, the deletion is settled and silenced.
 
 ```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 genesis = '<p>The quick brown fox jumps over the lazy dog</p>'
+const cpLatest = '<p>The fast brown fox leaps</p>'
+const meCurrent = '<p>The quick brown antelope leaps over the lazy pig</p>'
 
-const merged = HtmlDiff.executeThreeWay(v1, v2, v3)
-// Counterparty added "interest" — kept by you.
-// Counterparty changed "five" → "five and a half" — you rejected.
+const merged = HtmlDiff.executeThreeWay(genesis, cpLatest, meCurrent)
+// CP changed quick→fast and removed "over the lazy dog" — attributed to cp.
+// You changed fox→antelope and added "pig" — attributed to me.
+// "jumps→leaps" was made by CP and kept by you — settled, emitted plain.
 ```
 
 Tables (including multi-table documents) and row/column structural changes are supported with the same author
-attribution at row, cell, and content granularity.
+attribution at row, cell, and content granularity. Settled changes (both sides agree) propagate through every
+granularity — a table both sides added unchanged emits plain; a row only one side added carries that author's
+attribution.
+
+#### Picking a genesis
+
+The right `genesis` depends on the negotiation:
+
+- **Single shared starting point** (e.g. `prefillReceiverAnswers=true`): use the V1.0 version that both parties
+  started from.
+- **Per-user starting points** (e.g. `prefillReceiverAnswers=false`): each party has their own genesis (their
+  `initialAnswers` — preset state or schema defaults). The diff from each user's perspective uses their own genesis,
+  and the two views may differ.
+
+The library doesn't pick the genesis itself — it consumes whatever the caller supplies. CreateiQ's frontend does the
+per-user selection.
 
 #### Options
 
-`executeThreeWay` accepts the same per-instance options as `HtmlDiff` (`repeatingWordsAccuracy`,
-`ignoreWhitespaceDifferences`, `orphanMatchThreshold`, `blockExpressions`). They flow into both internal pair-wise
-analyses identically.
+`executeThreeWay` accepts the same 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.
+both pair-wise heuristics — projection only activates when both `genesis↔cpLatest` and `genesis↔meCurrent` would
+benefit from it. Pass an explicit boolean to override.
+
+#### Known limitations
+
+- **Partial-adoption visibility.** When one author deletes a phrase but the other keeps part of it (e.g. CP deletes
+  "over the lazy dog" but Me keeps "over the lazy" and only changes "dog"→"pig"), the algorithm reports the deletion
+  at the token level — each kept token appears as a pending `<del cp>` while the one changed token appears separately.
+  The reader sees an honest token-level picture rather than a misleading phrase-level summary.
+- **Boundary-based settled-insertion detection.** Two authors inserting the same content but at slightly different
+  boundaries (because their respective diffs decomposed the surrounding change differently) may be reported as two
+  separate one-sided insertions rather than one settled insertion. Identical content at identical boundaries does
+  detect as settled.
 
 ## Contributing