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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createiq/htmldiff",
-  "version": "1.2.0-beta.1",
+  "version": "1.2.0-beta.10",
   "description": "TypeScript port of htmldiff.net",
   "type": "module",
   "author": "Mathew Mannion <mathew.mannion@linklaters.com>",

package/src/HtmlDiff.ts

@@ -71,6 +71,40 @@ export interface AnalyzeResult {
  */
 export type ThreeWayOptions = AnalyzeOptions
 
+/**
+ * Opinionated options that align htmldiff's output with Microsoft Word's
+ * track-changes rendering for legal-document rewrites.
+ *
+ * The library's bare default (`orphanMatchThreshold = 0`) keeps every
+ * LCS match, however small — which fragments long sentence rewrites
+ * into many tiny ins/del pairs around stray word matches ("of", "the",
+ * "shall"). Word collapses those into a single coarse del+ins, which is
+ * dramatically more readable for legal text.
+ *
+ * 0.25 was tuned empirically against a customer Word reference (US
+ * Commercial One CP, May 2026):
+ *   - short edits (typo / one-word insert): output identical to
+ *     threshold=0 — inter-match distances are tiny so every match
+ *     trivially clears the bar;
+ *   - long rewrites (the "Specified Indebtedness" rewrite in the
+ *     reference): previously produced 6 dels + 5 ins fragmented around
+ *     stray matches; at 0.25 it condenses to 3 dels + 2 ins — close to
+ *     Word's 1+1 and a major readability win;
+ *   - higher values (0.3+) collapsed short edits containing inline
+ *     formatting changes into a single block — too aggressive.
+ *
+ * Consumers rendering legal documents should spread this into their
+ * options:
+ *   `HtmlDiff.execute(old, new, { ...WORD_ALIGNED_OPTIONS })`
+ *   `HtmlDiff.executeThreeWay(g, c, m, { ...WORD_ALIGNED_OPTIONS })`
+ *
+ * Other consumers (machine-readable diff, exact-token alignment) can
+ * keep the bare default.
+ */
+export const WORD_ALIGNED_OPTIONS: AnalyzeOptions = {
+  orphanMatchThreshold: 0.25,
+}
+
 export default class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -162,7 +196,22 @@ export default class HtmlDiff {
   // constructor overload that would re-leak the parameter we just hid.
   private tablePreprocessDepth = 0
 
-  private specialTagDiffStack: string[] = []
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
+  private specialTagDiffStack: Array<{
+    tag: string
+    styledTagNames: string
+    cssClass: string
+    metadata: WrapMetadata | undefined
+  }> = []
   private newWords: string[] = []
   private oldWords: string[] = []
   /**
@@ -234,8 +283,31 @@ export default class HtmlDiff {
     this.newText = newText
   }
 
-  static execute(oldText: string, newText: string): string {
-    return new HtmlDiff(oldText, newText).build()
+  /**
+   * Two-way diff entry point. Accepts the same `AnalyzeOptions` bag as
+   * `executeThreeWay`, with two intentional exceptions documented
+   * inline below. Consumers wanting Word-aligned output should spread
+   * `WORD_ALIGNED_OPTIONS` into the third argument.
+   *
+   * Note: unlike `analyze`, `execute` runs `build()` which performs
+   * full table preprocessing — `tablePreprocessDepth` stays at 0 so
+   * the recursive cell diff can happen. Callers can't override that.
+   */
+  static execute(oldText: string, newText: string, options: AnalyzeOptions = {}): string {
+    const inner = new HtmlDiff(oldText, newText)
+    if (options.blockExpressions) {
+      for (const expr of options.blockExpressions) inner.addBlockExpression(expr)
+    }
+    if (options.repeatingWordsAccuracy !== undefined) inner.repeatingWordsAccuracy = options.repeatingWordsAccuracy
+    if (options.orphanMatchThreshold !== undefined) inner.orphanMatchThreshold = options.orphanMatchThreshold
+    if (options.ignoreWhitespaceDifferences !== undefined) {
+      inner.ignoreWhitespaceDifferences = options.ignoreWhitespaceDifferences
+    }
+    // `useProjections` is intentionally NOT plumbed here — the 2-way
+    // path's build() runs its own heuristic. `analyze` honours it; if
+    // you need to force it for a 2-way result, route through `analyze`
+    // and consume the operations directly.
+    return inner.build()
   }
 
   /**
@@ -320,22 +392,6 @@ export default class HtmlDiff {
     return HtmlDiff.shouldUseContentProjections(oldWords, newWords, oldProj, newProj)
   }
 
-  /**
-   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
-   * version CP sent back), and V3 (Me's current draft), produces a
-   * single attributed HTML output where CP's and Me's changes are
-   * distinguished by `data-author` ('cp' or 'me') and matching
-   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
-   * CP's proposal" case (Me deleted text CP had inserted) gets a
-   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
-   *
-   * Coordinates the symmetric-projection decision (D1) across both
-   * internal `analyze` calls so V2 tokenises identically on each side
-   * of the spine. When `useProjections` is left undefined, the decision
-   * is the conjunction of both pair-wise heuristics — project iff both
-   * pairs would project on their own. Pass an explicit boolean to
-   * override.
-   */
   /**
    * Three-way HTML diff against a shared genesis. Produces attributed
    * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
@@ -424,6 +480,25 @@ export default class HtmlDiff {
    * buffer. Reusing the instance keeps the formatting-tag stack
    * (`specialTagDiffStack`) coherent across segments — a `<strong>`
    * opened in one segment and closed in another stays balanced.
+   *
+   * Edge case: an ins/del segment can open a formatting wrap whose
+   * matching closer ends up in an equal segment (`<strong>` deleted
+   * by CP but `</strong>` kept by both — buildSegments emits the open
+   * as del-cp and the close as equal). Equal segments bypass
+   * `insertTag` and push raw, so the stack entry for the open is
+   * never popped. Rather than throw — which forces the caller's UI
+   * into an error boundary — close every leftover wrap with `</ins>`
+   * at the end of emission.
+   *
+   * Caveat: the `</ins>` close is honest for the mod-wrap that the
+   * opener pushed (every formatting opener emits an inner `<ins…>`
+   * postInject regardless of whether the outer segment is ins or
+   * del). For del-segment formatting openers the outer `<del>` may
+   * itself be left open by the same emission imbalance; this fixup
+   * doesn't address that. Downstream browsers/DOMParser normalise
+   * mildly-malformed HTML by closing dangling tags, so the rendered
+   * output is usually acceptable — but the warning IS the signal
+   * that the input had a real imbalance worth investigating.
    */
   private static emitSegments(segments: Segment[]): string {
     const emitter = new HtmlDiff('', '')
@@ -436,18 +511,21 @@ export default class HtmlDiff {
       // insertTag mutates its `words` array; pass a copy.
       emitter.insertTag(tag, baseClass, [...seg.words], metadata)
     }
-    // Stack-balance invariant: every special-case opening tag pushed onto
-    // `specialTagDiffStack` during emission must have been matched by a
-    // closing tag. An unbalanced stack means the input had unbalanced
-    // formatting tags AND a Replace at an inconvenient position — the
-    // output would be silently malformed (half-closed `<ins>`). Fail
-    // loudly so the caller can investigate rather than ship broken HTML.
     if (emitter.specialTagDiffStack.length > 0) {
-      throw new Error(
+      // Log once so we can spot bad inputs in dev tools, but don't
+      // throw — the caller's only fallback was to crash the React
+      // tree, which is worse than emitting slightly-imperfect HTML.
+      // eslint-disable-next-line no-console
+      console.warn(
         `HtmlDiff.executeThreeWay: emission left ${emitter.specialTagDiffStack.length} ` +
-          'unclosed formatting tag(s) on the stack — input may have unbalanced ' +
-          '<strong>/<em>/etc. or there is a bug in segment emission.'
+          'unclosed formatting wrap(s) on the stack. Closing defensively. ' +
+          'This usually means a formatting tag opens in a del/ins segment ' +
+          'and its matching closer is in an equal segment.'
       )
+      while (emitter.specialTagDiffStack.length > 0) {
+        emitter.content.push('</ins>')
+        emitter.specialTagDiffStack.pop()
+      }
     }
     return emitter.content.join('')
   }
@@ -827,8 +905,13 @@ export default class HtmlDiff {
       // if there are nonTags, the index of the last tag is the index before the first nonTag.
       const indexLastTagInFirstTagBlock = indexOfFirstNonTag === -1 ? words.length - 1 : indexOfFirstNonTag - 1
 
-      let specialCaseTagInjection = ''
-      let specialCaseTagInjectionIsBefore = false
+      // Pre-injection sits BEFORE the extracted tag-block content (used
+      // by closing tags so `</ins></strong>` reads left-to-right).
+      // Post-injection sits AFTER (used by opening tags so the rendered
+      // order is `<strong><ins ...>` and by the overlap-split case so
+      // the re-opened `<ins>`s sit AFTER the actual closing tag).
+      let preInject = ''
+      let postInject = ''
 
       // handle opening tag
       if (HtmlDiff.SpecialCaseOpeningTagRegex.test(words[0])) {
@@ -840,10 +923,11 @@ export default class HtmlDiff {
         }
         const styledTagNames = Array.from(tagNames).join(' ')
 
-        this.specialTagDiffStack.push(words[0])
         // Carry the caller's metadata into the formatting-tag wrapper so
         // a 3-way author tag survives a `<strong>`/`<em>` content edit.
-        specialCaseTagInjection = `<ins${Utils.composeTagAttributes(`mod ${styledTagNames}`, metadata ?? {})}>`
+        const styledCssClass = `mod ${styledTagNames}`
+        this.specialTagDiffStack.push({ tag: words[0], styledTagNames, cssClass: styledCssClass, metadata })
+        postInject = `<ins${Utils.composeTagAttributes(styledCssClass, metadata ?? {})}>`
         if (tag === HtmlDiff.DelTag) {
           words.shift()
 
@@ -855,7 +939,6 @@ export default class HtmlDiff {
       }
       // handle closing tag
       else if (HtmlDiff.SpecialCaseClosingTagsSet.has(words[0].toLowerCase())) {
-        const openingTag = this.specialTagDiffStack.length === 0 ? null : this.specialTagDiffStack.pop()
         // For delete operations: when the tag block contains a mix of formatting and
         // non-formatting closing tags (e.g. </strong></div>), compare against the first
         // closing tag (the formatting one) rather than the last tag in the block.
@@ -870,19 +953,39 @@ export default class HtmlDiff {
             tagIndexToCompare = 0
           }
         }
-        const openingAndClosingTagsMatch =
-          !!openingTag && Utils.getTagName(openingTag) === Utils.getTagName(words[tagIndexToCompare])
 
-        if (openingTag && openingAndClosingTagsMatch) {
-          specialCaseTagInjection = '</ins>'
-          specialCaseTagInjectionIsBefore = true
+        // Search the stack for a matching opener (LIFO). When the match
+        // is the top entry, this is the normal balanced case and we
+        // emit a single `</ins>` before the closing tag. When the match
+        // is below an unmatched opener — i.e. another formatting wrap
+        // opened after it but hasn't been closed yet — the wraps
+        // overlap in source order, which has no valid LIFO HTML
+        // expression. Resolve by SPLITTING the wraps: close everything
+        // above the match (their `<ins>`s and the match's `<ins>`), then
+        // re-open the above wraps with fresh `<ins>` tags AFTER the
+        // closing tag emits. The above wraps continue to apply until
+        // their own closing tag arrives.
+        const closingTagName = Utils.getTagName(words[tagIndexToCompare])
+        let matchIdx = -1
+        for (let i = this.specialTagDiffStack.length - 1; i >= 0; i--) {
+          if (Utils.getTagName(this.specialTagDiffStack[i].tag) === closingTagName) {
+            matchIdx = i
+            break
+          }
         }
 
-        // if the tag has a corresponding opening tag, but they don't match,
-        // we need to push the opening tag back onto the stack
-        else if (openingTag) {
-          this.specialTagDiffStack.push(openingTag)
+        if (matchIdx >= 0) {
+          const aboveEntries = this.specialTagDiffStack.splice(matchIdx + 1)
+          this.specialTagDiffStack.pop() // pop the matched entry
+          // One `</ins>` per above entry, then one for the match itself.
+          preInject = '</ins>'.repeat(aboveEntries.length + 1)
+          for (const entry of aboveEntries) {
+            postInject += `<ins${Utils.composeTagAttributes(entry.cssClass, entry.metadata ?? {})}>`
+            this.specialTagDiffStack.push(entry) // their wrap continues via the new <ins>
+          }
         }
+        // No match in stack — orphan closing tag, drop the `<ins>` work
+        // and just let the tag itself flow through extractConsecutiveWords.
 
         if (tag === HtmlDiff.DelTag) {
           words.shift()
@@ -893,7 +996,7 @@ export default class HtmlDiff {
         }
       }
 
-      if (words.length === 0 && specialCaseTagInjection.length === 0) {
+      if (words.length === 0 && preInject.length === 0 && postInject.length === 0) {
         break
       }
 
@@ -909,11 +1012,7 @@ export default class HtmlDiff {
               !HtmlDiff.SpecialCaseClosingTagsSet.has(x.toLowerCase())
           : Utils.isTag
 
-      if (specialCaseTagInjectionIsBefore) {
-        this.content.push(specialCaseTagInjection + this.extractConsecutiveWords(words, isTagForExtraction).join(''))
-      } else {
-        this.content.push(this.extractConsecutiveWords(words, isTagForExtraction).join('') + specialCaseTagInjection)
-      }
+      this.content.push(preInject + this.extractConsecutiveWords(words, isTagForExtraction).join('') + postInject)
 
       if (words.length === 0) continue
 
@@ -1020,6 +1119,31 @@ export default class HtmlDiff {
         continue
       }
 
+      // Never orphan-reject a match whose tokens are ALL HTML tags.
+      // Tag tokens are structural; rejecting `</strong>` / `</em>` as
+      // an orphan match between two content deletions merges the tag
+      // into the deletion, leaving the matching opener unclosed —
+      // browsers then auto-close the opener at the END of the
+      // deletion, producing visually-wrong output (e.g. the body of
+      // a section deletion rendered as bold-italic because the
+      // closing `</strong></em>` ended up after the body deletion
+      // rather than after the heading). The orphan threshold is
+      // designed for stray word matches between heavily-edited spans,
+      // not for formatting boundaries.
+      let allTags = true
+      for (let i = curr.startInNew; i < curr.endInNew; i++) {
+        if (!Utils.isTag(wordsForDiffNew[i])) {
+          allTags = false
+          break
+        }
+      }
+      if (allTags) {
+        yield curr
+        prev = curr
+        curr = next
+        continue
+      }
+
       let oldDistanceInChars = 0
       for (let i = prev.endInOld; i < next.startInOld; i++) {
         oldDistanceInChars += wordsForDiffOld[i].length

package/src/ThreeWayDiff.ts

@@ -1,4 +1,5 @@
 import Action from './Action'
+import { lcsAlign } from './Alignment'
 import type { AnalyzeResult } from './HtmlDiff'
 import type Operation from './Operation'
 import type { WrapMetadata } from './Utils'
@@ -183,13 +184,33 @@ function collectInsertionsKeyedByEnd(d: AnalyzeResult): Map<number, string[]> {
 }
 
 /**
- * Emit any insertions at boundary `b`. When both authors inserted at
- * the same boundary AND the inserted token sequences are textually
- * identical, the insertion is treated as agreed and emitted unmarked.
- * Otherwise each side's insertion is emitted with author attribution.
+ * Emit any insertions at boundary `b`.
  *
- * The CP-then-Me ordering for disagreement is arbitrary but consistent;
- * callers don't depend on it.
+ * Reading model: a legal reviewer wants to see CP's INTENT relative
+ * to Me's current content. Me's content is the base; CP's deltas are
+ * what they need to act on. Under that framing:
+ *   - tokens both authors inserted at the same boundary → settled
+ *   - tokens CP inserted that Me doesn't have → ins-cp (CP wants
+ *     this added)
+ *   - tokens Me inserted that CP doesn't have → del-cp (CP wants
+ *     this removed from Me's content)
+ *
+ * The third case is the load-bearing attribution flip. The
+ * genesis-spine view technically labels me-only-at-boundary tokens
+ * as "ins-me" (Me added them; CP didn't), but that's confusing to
+ * a reviewer: they see "Me added X" alongside "CP added Y" and have
+ * to mentally derive "CP wants X gone, replaced with Y". Surfacing
+ * me-only tokens as `del-cp` shows CP's intent directly:
+ *   - "CP accepted Me's text minus `things`": settled bulk + del-cp
+ *     `things` (no parallel redundant insertions)
+ *   - "CP wants `cruel` where Me wrote `brave`": ins-cp `cruel` +
+ *     del-cp `brave` (the substitution intent reads directly)
+ *   - "CP added extra words": cp-extras stay as ins-cp (same as
+ *     before; the cp-only direction was always intent-correct)
+ *
+ * Pure single-side insertions (Me added text CP doesn't engage
+ * with at all, or vice versa) keep their genesis-spine attribution
+ * — these aren't refinement cases, just Me's own content additions.
  */
 function emitBoundary(
   b: number,
@@ -205,14 +226,40 @@ function emitBoundary(
   const hasMe = !!meIns && meIns.length > 0
   if (!hasCp && !hasMe) return
 
-  if (hasCp && hasMe && tokenArraysEqual(cpIns, meIns)) {
-    // Both authors inserted the same content — settled. Emit unmarked.
-    appendSegment(segments, { kind: 'equal' }, cpIns)
+  // Only-one-side: emit verbatim with that side's attribution.
+  // Genuine single-author additions stay author-attributed.
+  if (!hasCp) {
+    appendSegment(segments, { kind: 'ins', author: 'me' }, meIns!)
+    return
+  }
+  if (!hasMe) {
+    appendSegment(segments, { kind: 'ins', author: 'cp' }, cpIns!)
     return
   }
 
-  if (hasCp) appendSegment(segments, { kind: 'ins', author: 'cp' }, cpIns)
-  if (hasMe) appendSegment(segments, { kind: 'ins', author: 'me' }, meIns)
+  // Both sides inserted. Identical → settled. Otherwise LCS-align
+  // and apply the asymmetric intent reading.
+  if (tokenArraysEqual(cpIns!, meIns!)) {
+    appendSegment(segments, { kind: 'equal' }, cpIns!)
+    return
+  }
+
+  const alignment = lcsAlign(cpIns! as string[], meIns! as string[])
+  for (const a of alignment) {
+    if (a.oldIdx !== null && a.newIdx !== null) {
+      // Token appears in both insertions → settled.
+      appendSegment(segments, { kind: 'equal' }, [cpIns![a.oldIdx]])
+    } else if (a.oldIdx !== null) {
+      // Token in cp's insertion only → CP wants this added.
+      appendSegment(segments, { kind: 'ins', author: 'cp' }, [cpIns![a.oldIdx]])
+    } else if (a.newIdx !== null) {
+      // Token in me's insertion only → CP wants this removed from
+      // Me's content. (Genesis-spine would label this ins-me, but
+      // that reading is misleading for a reviewer at this kind of
+      // shared boundary — see the function-level comment.)
+      appendSegment(segments, { kind: 'del', author: 'cp' }, [meIns![a.newIdx]])
+    }
+  }
 }
 
 function tokenArraysEqual(a: readonly string[], b: readonly string[]): boolean {

package/src/ThreeWayTable.ts

@@ -1,4 +1,4 @@
-import { lcsAlign, textSimilarity } from './Alignment'
+import { type Alignment, lcsAlign, pairSimilarUnmatched, textSimilarity } from './Alignment'
 import { injectClass, parseOpeningTagAt } from './HtmlScanner'
 import {
   type CellRange,
@@ -8,6 +8,7 @@ import {
   PLACEHOLDER_SUFFIX,
   type RowRange,
   rowKey,
+  rowText,
   sameDimensions,
   spliceString,
   type TableRange,
@@ -143,8 +144,14 @@ function preprocessByContent(
   const cKeys = cTables.map(t => tableKey(cpLatest, t))
   const mKeys = mTables.map(t => tableKey(meCurrent, t))
 
-  const alignCp = lcsAlign(gKeys, cKeys)
-  const alignMe = lcsAlign(gKeys, mKeys)
+  // Exact tableKey LCS, then fuzzy-pair unmatched runs by content
+  // similarity. Without this, a table whose cells were edited (but
+  // not its overall shape) fails the exact tableKey match and the
+  // table-level aligner pulls it apart into a whole-table del + a
+  // whole-table ins. Same fuzzy pass `TableDiff` uses for the 2-way
+  // path — `pairSimilarTablesThreeWay` is defined below.
+  const alignCp = pairSimilarTablesThreeWay(lcsAlign(gKeys, cKeys), genesis, cpLatest, gTables, cTables)
+  const alignMe = pairSimilarTablesThreeWay(lcsAlign(gKeys, mKeys), genesis, meCurrent, gTables, mTables)
 
   // Maps: genesisIdx → matching cpIdx (-1 if none); cpIdx → matching genesisIdx; etc.
   const gToCp = new Array<number>(gTables.length).fill(-1)
@@ -303,7 +310,21 @@ function preprocessByContent(
   return { modifiedGenesis, modifiedCp, modifiedMe, placeholderToDiff }
 }
 
-const POSITIONAL_PAIR_SIMILARITY_THRESHOLD = 0.5
+// Positional pairing is the strict-default for three-way table merge:
+// when all three inputs have the same number of tables in the same
+// order, we pair them by index and let `diffTableThreeWay` handle
+// per-table cell/row level differences. The similarity guard below
+// only kicks in to *reject* positional alignment when a pair is
+// SO dissimilar that it's near-certainly a table reorder/rename
+// where content-LCS pairing would be materially better. The
+// threshold is intentionally low — the 2-way path has no such guard
+// and pairs purely by index (its `diffTable` falls back through
+// same-dimension → equal-row-count → row-LCS → whole-table on its
+// own), so the three-way path was stricter than its sibling and
+// silently dropped to whole-table del+ins for legitimate edits
+// like "rename one column and tweak its values". Aligning the
+// threshold here keeps the two-way and three-way paths in step.
+const POSITIONAL_PAIR_SIMILARITY_THRESHOLD = 0.15
 
 function positionallyAligned(
   genesis: string,
@@ -328,6 +349,79 @@ function tableKey(html: string, table: TableRange): string {
   return html.slice(table.tableStart, table.tableEnd).replace(/\s+/g, ' ').trim()
 }
 
+/**
+ * Character-level similarity above which the three-way aligner treats
+ * two rows / tables as "the same logical entry, edited" rather than
+ * an unrelated delete + insert. Matched to TableDiff's
+ * `ROW_FUZZY_THRESHOLD` / `CELL_FUZZY_THRESHOLD` so 2-way and 3-way
+ * agree on which pairings are reachable; if a row's content overlap
+ * is enough to fool the 2-way diff into pairing, it should also be
+ * enough for 3-way.
+ */
+const THREE_WAY_FUZZY_THRESHOLD = 0.5
+
+/**
+ * Run the same fuzzy-pairing pass `TableDiff.pairSimilarUnmatchedRows`
+ * applies after its exact-LCS, but against one side of the genesis
+ * spine (either cp or me). The genesis tables/rows are always the
+ * "old" side; `newTable` is the cp or me table being aligned. Returns
+ * the enriched alignment with additional paired entries.
+ *
+ * Cell-count guard: only fuzzy-pair when both rows have the same cell
+ * count. Without this guard an asymmetric restructure — e.g. CP and
+ * Me both added a different column — leads to ONE side fuzzy-pairing
+ * its row with genesis (content overlap above threshold) while the
+ * other side falls below threshold. That mismatch routes through
+ * `diffTableStructural`'s "Me dropped, CP kept" (or the mirror)
+ * branch, which emits CP's row as a Me-attributed deletion. In
+ * cp-only mode `stripMeAttributedMarkers` then removes the row
+ * entirely and CP's edit vanishes from the view — exactly the
+ * content-loss case we're meant to prevent. Restricting fuzzy
+ * pairing to same-shape rows preserves the common case (single cell
+ * edit, identical row shape) while pushing structural mismatches
+ * back to the boundary-insertion path that emits both sides
+ * explicitly.
+ */
+function pairSimilarRowsThreeWay(
+  alignment: Alignment[],
+  genesis: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange
+): Alignment[] {
+  const oldTexts = oldTable.rows.map(r => rowText(genesis, r))
+  const newTexts = newTable.rows.map(r => rowText(newHtml, r))
+  return pairSimilarUnmatched(alignment, THREE_WAY_FUZZY_THRESHOLD, (oldIdx, newIdx) => {
+    // Returning 0 sits below any positive threshold so
+    // `pairSimilarUnmatched` won't pair these rows; the guard remains
+    // defensive should the threshold ever be lowered to 0.
+    if (oldTable.rows[oldIdx].cells.length !== newTable.rows[newIdx].cells.length) return 0
+    return textSimilarity(oldTexts[oldIdx], newTexts[newIdx])
+  })
+}
+
+/**
+ * Table-level counterpart: after `lcsAlign(gKeys, otherKeys)` over
+ * full table HTML keys, fuzzy-pair unmatched table runs by their
+ * row-text-concatenated content. Without this, a table whose body
+ * was edited (but not its outer shape) fails the exact-key match
+ * and the preprocessing emits whole-table del + whole-table ins
+ * instead of recursing into per-cell three-way diffs.
+ */
+function pairSimilarTablesThreeWay(
+  alignment: Alignment[],
+  oldHtml: string,
+  newHtml: string,
+  oldTables: TableRange[],
+  newTables: TableRange[]
+): Alignment[] {
+  const oldTexts = oldTables.map(t => t.rows.map(r => rowText(oldHtml, r)).join(' '))
+  const newTexts = newTables.map(t => t.rows.map(r => rowText(newHtml, r)).join(' '))
+  return pairSimilarUnmatched(alignment, THREE_WAY_FUZZY_THRESHOLD, (oldIdx, newIdx) =>
+    textSimilarity(oldTexts[oldIdx], newTexts[newIdx])
+  )
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Per-table diff: positional cells or row-level structural change.
 
@@ -412,8 +506,17 @@ function diffTableStructural(
   const cKeys = tC.rows.map(r => rowKey(cpLatest, r))
   const mKeys = tM.rows.map(r => rowKey(meCurrent, r))
 
-  const alignCp = lcsAlign(gKeys, cKeys)
-  const alignMe = lcsAlign(gKeys, mKeys)
+  // Exact LCS first, then fuzzy-pair remaining unmatched runs. Without
+  // the fuzzy pass, a row where CP edited just a single cell's text
+  // produces no key match — the row aligner emits the genesis row as
+  // CP-deleted AND CP's reshaped row as inserted, when a cell-level
+  // diff against the paired row would render the edit far more
+  // legibly. The 2-way path (`TableDiff.pairSimilarUnmatchedRows`)
+  // has done this since inception; bringing the three-way path in
+  // step removes the asymmetry where the cp-only / all-changes view
+  // looks markedly worse than plain 2-way for ordinary cell edits.
+  const alignCp = pairSimilarRowsThreeWay(lcsAlign(gKeys, cKeys), genesis, cpLatest, tG, tC)
+  const alignMe = pairSimilarRowsThreeWay(lcsAlign(gKeys, mKeys), genesis, meCurrent, tG, tM)
 
   // genesisIdx → matching cpIdx (-1 if cp deleted this row)
   const gToCp = new Array<number>(tG.rows.length).fill(-1)
@@ -521,9 +624,40 @@ function emitPreservedRow(
     return out.join('')
   }
   // Cell-count mismatch within a preserved row — cell-level structural
-  // change deferred. Fall back to me-attributed Replace (genesis row
-  // removed, me row inserted). Lossy for CP within that row.
-  return emitFullRowAttributed(genesis, rG, 'del', 'me') + emitFullRowAttributed(meCurrent, rM, 'ins', 'me')
+  // alignment is non-trivial (which Me cell maps to which CP cell when
+  // the counts diverge?). The previous fallback emitted only
+  // genesis-as-del + me-as-ins, which silently destroyed CP's row
+  // content whenever CP changed the cell count — a content-loss bug
+  // (a row where CP added a column would disappear from the rendered
+  // diff entirely). Emit each side's row as a distinct attributed
+  // block so neither party's restructure can vanish:
+  //   - if both restructured (different shapes on both sides) the
+  //     genesis row is settled-deleted (silent) and we emit cp + me
+  //     rows side by side, each attributed to its author;
+  //   - if only one restructured, the genesis row is del-attributed to
+  //     the restructuring author so the reader sees what was there
+  //     before, then the new shape ins-attributed to the same author.
+  //
+  // Content edits inside a side that DID keep the genesis cell count
+  // are not surfaced here (no positional path is available across
+  // mismatched shapes); the underlying data is still present in the
+  // source document but the visual diff doesn't decompose it. That is
+  // a degradation of detail, not content loss — symmetric for cp/me.
+  const cpRestructured = rC.cells.length !== rG.cells.length
+  const meRestructured = rM.cells.length !== rG.cells.length
+  const blocks: string[] = []
+  if (cpRestructured && meRestructured) {
+    // Both sides restructured; genesis shape retained by neither.
+    blocks.push(emitFullRowAttributed(cpLatest, rC, 'ins', 'cp'))
+    blocks.push(emitFullRowAttributed(meCurrent, rM, 'ins', 'me'))
+  } else if (cpRestructured) {
+    blocks.push(emitFullRowAttributed(genesis, rG, 'del', 'cp'))
+    blocks.push(emitFullRowAttributed(cpLatest, rC, 'ins', 'cp'))
+  } else {
+    blocks.push(emitFullRowAttributed(genesis, rG, 'del', 'me'))
+    blocks.push(emitFullRowAttributed(meCurrent, rM, 'ins', 'me'))
+  }
+  return blocks.join('')
 }
 
 /**

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>',