@createiq/htmldiff 1.1.0 → 1.2.0-beta.1

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(diff -u test/input1.html test/input2.html)",
+      "Bash(npm test -- test/Bug.spec.tsx)",
+      "Bash(timeout 30s npm run test:ci -- test/Bug.spec.tsx)",
+      "Bash(npm run build)",
+      "Bash(timeout 10s npm run test:ci -- test/Bug.spec.tsx)",
+      "Bash(npm run lint)",
+      "Bash(npm run test:ci)",
+      "Bash(npm run bench:ci)"
+    ],
+    "deny": []
+  }
+}

package/README.md

@@ -127,6 +127,73 @@ This property defines relative size of the match to be considered as orphan, fro
 
 Returns the diff from an HtmlDiff instance.
 
+### HtmlDiff.executeThreeWay(genesis, cpLatest, meCurrent, options?)
+
+Three-way HTML diff for back-and-forth negotiation scenarios. Given:
+
+- `genesis` — the shared common ancestor (the version both parties started from)
+- `cpLatest` — the counterparty's current published position
+- `meCurrent` — your current draft
+
+`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' ...>`
+- 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 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(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. 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 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 `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
 
 The library uses [Biome](https://biomejs.dev/) for linting and formatting, and [Vitest](https://vitest.dev/) for unit