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

package/src/TableDiff.ts

@@ -0,0 +1,1269 @@
+/**
+ * Table-aware preprocessing for HtmlDiff.
+ *
+ * The word-level diff alone matches longest-common-subsequences across cell
+ * boundaries and produces structurally wrong output for table edits — it
+ * shuffles content between cells, introduces phantom `<td>`s, and provides
+ * no signal that an entire row or column was added/deleted. We pre-process
+ * the inputs to give Word-style results:
+ *
+ *   • When dimensions match (same row count, same cell count per row), we
+ *     diff cell content positionally so cross-cell shifts produce one
+ *     independent del/ins per cell.
+ *   • When dimensions don't match (added/deleted row, added/deleted column),
+ *     we run a row-level LCS to identify structurally added/deleted rows,
+ *     then within preserved rows a cell-level LCS to identify added/deleted
+ *     columns. Structurally added rows/cells get `class='diffins'` on the
+ *     `<tr>`/`<td>`; deleted ones get `class='diffdel'`. Preserved cells
+ *     fall back to a content diff via the recursive HtmlDiff callback.
+ *
+ * Tables are spliced out into placeholders before the main diff runs and
+ * spliced back in after, so the surrounding (non-table) content is diffed
+ * by the normal word-level pipeline.
+ */
+
+interface CellRange {
+  /** Start index of the cell's opening tag in the original html. */
+  cellStart: number
+  /** Index just past the cell's closing tag. */
+  cellEnd: number
+  /** Cell content range — the slice we feed into the cell-level diff. */
+  contentStart: number
+  contentEnd: number
+}
+
+interface RowRange {
+  rowStart: number
+  rowEnd: number
+  cells: CellRange[]
+}
+
+interface TableRange {
+  tableStart: number
+  tableEnd: number
+  rows: RowRange[]
+}
+
+export interface PreprocessResult {
+  modifiedOld: string
+  modifiedNew: string
+  /** Maps placeholder marker → already-diffed table HTML to splice back in. */
+  placeholderToDiff: Map<string, string>
+}
+
+// HTML comments survive WordSplitter as a single atomic token and are
+// treated as equal on both sides, so they pass through the diff
+// untouched and are easy to substitute back later. The nonce is generated
+// per call so a previously-diffed document being re-diffed (or any input
+// that legitimately contains an `<!--HTMLDIFF_TABLE_*-->` comment) can't
+// collide with the placeholder we substitute. We additionally regenerate
+// the nonce if it appears in either input.
+const PLACEHOLDER_PREFIX_BASE = '<!--HTMLDIFF_TABLE_'
+const PLACEHOLDER_SUFFIX = '-->'
+
+/**
+ * Hard cap on table dimensions handled by the structural-aware path.
+ * The row-LCS is O(rows²), the per-row cell-LCS is O(cells²), and each
+ * comparison string-equals row content (potentially many KB). Without a
+ * cap, a several-thousand-row table can pin a CPU for seconds. Tables
+ * larger than this fall through to the word-level diff, which scales
+ * linearly. Tuned to comfortably cover real-world ISDA schedules
+ * (which routinely have 1000+ rows).
+ */
+const MAX_TABLE_ROWS = 1500
+const MAX_TABLE_CELLS_PER_ROW = 200
+
+function makePlaceholderPrefix(oldHtml: string, newHtml: string): string {
+  // 4 random bytes → 8 hex chars → 16^8 ≈ 4.3 billion combinations. We
+  // also retry if the generated nonce happens to occur in either input.
+  // Using `Math.random` here is fine: we're not defending against a
+  // malicious adversary, just avoiding accidental collisions.
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const nonce = Math.floor(Math.random() * 0xffffffff)
+      .toString(16)
+      .padStart(8, '0')
+    const prefix = `${PLACEHOLDER_PREFIX_BASE}${nonce}_`
+    if (!oldHtml.includes(prefix) && !newHtml.includes(prefix)) {
+      return prefix
+    }
+  }
+  // Astronomically unlikely. Falling back to a counter ensures progress
+  // rather than an infinite loop, and any remaining collision will simply
+  // surface as a malformed diff that the caller can detect.
+  return `${PLACEHOLDER_PREFIX_BASE}fallback_${Date.now()}_`
+}
+
+type DiffCellFn = (oldCellContent: string, newCellContent: string) => string
+
+/**
+ * Diffs every paired-by-position table in the inputs and replaces each
+ * source table with a placeholder, returning the modified inputs plus the
+ * placeholder→diff mapping. Returns null when there are no tables to
+ * preprocess or the table counts don't line up.
+ */
+export function preprocessTables(oldHtml: string, newHtml: string, diffCell: DiffCellFn): PreprocessResult | null {
+  const oldTables = findTopLevelTables(oldHtml)
+  const newTables = findTopLevelTables(newHtml)
+
+  if (oldTables.length === 0 && newTables.length === 0) return null
+  if (oldTables.length !== newTables.length) return null
+
+  // Bail out on pathologically large tables — see MAX_TABLE_ROWS comment.
+  for (let i = 0; i < oldTables.length; i++) {
+    if (exceedsSizeLimit(oldTables[i]) || exceedsSizeLimit(newTables[i])) return null
+  }
+
+  const pairs: Array<{ oldTable: TableRange; newTable: TableRange; diffed: string }> = []
+  for (let i = 0; i < oldTables.length; i++) {
+    pairs.push({
+      oldTable: oldTables[i],
+      newTable: newTables[i],
+      diffed: diffTable(oldHtml, newHtml, oldTables[i], newTables[i], diffCell),
+    })
+  }
+
+  // Splice from end → start so earlier offsets stay valid.
+  let modifiedOld = oldHtml
+  let modifiedNew = newHtml
+  const placeholderPrefix = makePlaceholderPrefix(oldHtml, newHtml)
+  const placeholderToDiff = new Map<string, string>()
+  for (let i = pairs.length - 1; i >= 0; i--) {
+    const placeholder = `${placeholderPrefix}${i}${PLACEHOLDER_SUFFIX}`
+    placeholderToDiff.set(placeholder, pairs[i].diffed)
+    modifiedOld = spliceString(modifiedOld, pairs[i].oldTable.tableStart, pairs[i].oldTable.tableEnd, placeholder)
+    modifiedNew = spliceString(modifiedNew, pairs[i].newTable.tableStart, pairs[i].newTable.tableEnd, placeholder)
+  }
+
+  return { modifiedOld, modifiedNew, placeholderToDiff }
+}
+
+export function restoreTablePlaceholders(diffOutput: string, placeholderToDiff: Map<string, string>): string {
+  let result = diffOutput
+  for (const [placeholder, html] of placeholderToDiff) {
+    result = result.split(placeholder).join(html)
+  }
+  return result
+}
+
+function spliceString(s: string, start: number, end: number, replacement: string): string {
+  return s.slice(0, start) + replacement + s.slice(end)
+}
+
+function exceedsSizeLimit(table: TableRange): boolean {
+  if (table.rows.length > MAX_TABLE_ROWS) return true
+  for (const row of table.rows) {
+    if (row.cells.length > MAX_TABLE_CELLS_PER_ROW) return true
+  }
+  return false
+}
+
+function diffTable(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  diffCell: DiffCellFn
+): string {
+  if (sameDimensions(oldTable, newTable)) {
+    return diffPositionalTable(oldHtml, newHtml, oldTable, newTable, diffCell)
+  }
+  if (oldTable.rows.length === newTable.rows.length) {
+    // Same row count, different cell counts: column add/delete only.
+    // Aligning rows positionally avoids the LCS row-key mismatch that
+    // happens when rows have different cell counts.
+    return diffSameRowCountTable(oldHtml, newHtml, oldTable, newTable, diffCell)
+  }
+  return diffStructurallyAlignedTable(oldHtml, newHtml, oldTable, newTable, diffCell)
+}
+
+function diffSameRowCountTable(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  diffCell: DiffCellFn
+): string {
+  // Walk the new table verbatim (preserving `<thead>`/`<tbody>` wrappers,
+  // whitespace, etc.) and substitute each row's content with the diffed
+  // form. The cursor-based emission keeps everything between rows intact.
+  const out: string[] = []
+  let cursor = newTable.tableStart
+  let r = 0
+  while (r < newTable.rows.length) {
+    const merge = detectVerticalMerge(oldHtml, newHtml, oldTable, newTable, r)
+    if (merge) {
+      out.push(newHtml.slice(cursor, newTable.rows[r].rowStart))
+      out.push(merge.diff)
+      cursor = newTable.rows[r + merge.span - 1].rowEnd
+      r += merge.span
+      continue
+    }
+    const split = detectVerticalSplit(oldHtml, newHtml, oldTable, newTable, r)
+    if (split) {
+      out.push(newHtml.slice(cursor, newTable.rows[r].rowStart))
+      out.push(split.diff)
+      cursor = newTable.rows[r + split.span - 1].rowEnd
+      r += split.span
+      continue
+    }
+    const newRow = newTable.rows[r]
+    out.push(newHtml.slice(cursor, newRow.rowStart))
+    out.push(diffPreservedRow(oldHtml, newHtml, oldTable.rows[r], newRow, diffCell))
+    cursor = newRow.rowEnd
+    r++
+  }
+  out.push(newHtml.slice(cursor, newTable.tableEnd))
+  return out.join('')
+}
+
+/**
+ * Detects a vertical merge starting at row `r`: new row R has a single
+ * cell with rowspan=K (and any colspan ≥ 1), with rows R+1..R+K-1 empty
+ * in new. Old rows R..R+K-1 must have a logical column width equal to
+ * the new cell's colspan and contain no rowspan'd cells of their own.
+ * This handles both single-column merges (old rows are 1-cell, new cell
+ * rowspan=K) and rectangular merges (e.g. 2×2 merge into a single
+ * colspan=2 rowspan=2 cell). Output: emit the merged cell with
+ * `class='mod rowspan'` and the empty trailing rows unchanged.
+ */
+function detectVerticalMerge(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  r: number
+): { diff: string; span: number } | null {
+  const newRow = newTable.rows[r]
+  if (newRow.cells.length !== 1) return null
+  const cell = newRow.cells[0]
+  const span = getRowspan(newHtml, cell)
+  if (span <= 1) return null
+  if (r + span > newTable.rows.length) return null
+
+  const colspan = getColspan(newHtml, cell)
+
+  for (let k = 1; k < span; k++) {
+    if (newTable.rows[r + k].cells.length !== 0) return null
+  }
+  for (let k = 0; k < span; k++) {
+    const oldRow = oldTable.rows[r + k]
+    if (!oldRow) return null
+    // The absorbed region's logical width must match the merged cell's
+    // colspan; otherwise this isn't a clean rectangular merge and we let
+    // the caller fall through.
+    if (sumColspans(oldHtml, oldRow.cells) !== colspan) return null
+    for (const c of oldRow.cells) {
+      if (getRowspan(oldHtml, c) !== 1) return null
+    }
+  }
+
+  const out: string[] = []
+  out.push(rowHeaderSlice(newHtml, newRow))
+  out.push(emitSpanChangedCell(newHtml, cell, 'rowspan'))
+  out.push('</tr>')
+  for (let k = 1; k < span; k++) {
+    out.push(emitEmptyRow(newHtml, newTable.rows[r + k]))
+  }
+  return { diff: out.join(''), span }
+}
+
+/**
+ * Detects a vertical split starting at row `r`: old row R has a single
+ * cell with rowspan=K, old rows R+1..R+K-1 are empty. New rows R..R+K-1
+ * each have a single cell. Output: emit each new row with the new cell
+ * tagged `class='mod rowspan'`.
+ */
+function detectVerticalSplit(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  r: number
+): { diff: string; span: number } | null {
+  const oldRow = oldTable.rows[r]
+  if (oldRow.cells.length !== 1) return null
+  const oldCell = oldRow.cells[0]
+  const span = getRowspan(oldHtml, oldCell)
+  if (span <= 1) return null
+  if (r + span > oldTable.rows.length) return null
+
+  const colspan = getColspan(oldHtml, oldCell)
+
+  for (let k = 1; k < span; k++) {
+    if (oldTable.rows[r + k].cells.length !== 0) return null
+  }
+  for (let k = 0; k < span; k++) {
+    const newRow = newTable.rows[r + k]
+    if (!newRow) return null
+    // New rows must collectively cover the same logical width as the old
+    // merged cell's colspan, with no rowspan'd cells of their own.
+    if (sumColspans(newHtml, newRow.cells) !== colspan) return null
+    for (const c of newRow.cells) {
+      if (getRowspan(newHtml, c) !== 1) return null
+    }
+  }
+
+  const out: string[] = []
+  for (let k = 0; k < span; k++) {
+    const newRow = newTable.rows[r + k]
+    out.push(rowHeaderSlice(newHtml, newRow))
+    for (const c of newRow.cells) {
+      out.push(emitSpanChangedCell(newHtml, c, 'rowspan'))
+    }
+    out.push('</tr>')
+  }
+  return { diff: out.join(''), span }
+}
+
+function emitEmptyRow(html: string, row: RowRange): string {
+  // Re-emit the source row's `<tr ...></tr>` verbatim.
+  return html.slice(row.rowStart, row.rowEnd)
+}
+
+function sameDimensions(a: TableRange, b: TableRange): boolean {
+  if (a.rows.length !== b.rows.length) return false
+  for (let i = 0; i < a.rows.length; i++) {
+    if (a.rows[i].cells.length !== b.rows[i].cells.length) return false
+  }
+  return true
+}
+
+/**
+ * Same-dimension path: walk the new table verbatim and substitute each
+ * cell content range with the cell-level diff. The surrounding
+ * `<thead>`/`<tbody>`/whitespace passes through untouched.
+ */
+function diffPositionalTable(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  diffCell: DiffCellFn
+): string {
+  const out: string[] = []
+  let cursor = newTable.tableStart
+  for (let r = 0; r < newTable.rows.length; r++) {
+    const oldRow = oldTable.rows[r]
+    const newRow = newTable.rows[r]
+    for (let c = 0; c < newRow.cells.length; c++) {
+      const oldCell = oldRow.cells[c]
+      const newCell = newRow.cells[c]
+      out.push(newHtml.slice(cursor, newCell.contentStart))
+      out.push(
+        diffCell(
+          oldHtml.slice(oldCell.contentStart, oldCell.contentEnd),
+          newHtml.slice(newCell.contentStart, newCell.contentEnd)
+        )
+      )
+      cursor = newCell.contentEnd
+    }
+  }
+  out.push(newHtml.slice(cursor, newTable.tableEnd))
+  return out.join('')
+}
+
+/**
+ * Mismatched-dimensions path: row-level LCS to identify added/deleted rows,
+ * then per preserved row a cell-level LCS to identify added/deleted cells.
+ * Reconstructs the table from scratch — there's no "single new structure"
+ * to walk verbatim, since we're stitching together kept rows from both
+ * sides.
+ */
+function diffStructurallyAlignedTable(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  diffCell: DiffCellFn
+): string {
+  const oldKeys = oldTable.rows.map(row => rowKey(oldHtml, row))
+  const newKeys = newTable.rows.map(row => rowKey(newHtml, row))
+  const exactAlignment = lcsAlign(oldKeys, newKeys)
+  const alignment = pairSimilarUnmatchedRows(exactAlignment, oldTable, newTable, oldHtml, newHtml)
+
+  // Walk new's tableStart→tableEnd, substituting rows with their diffed
+  // form so `<thead>`/`<tbody>` wrappers and inter-row whitespace are
+  // preserved verbatim. Deleted rows (no position in new) are injected
+  // inline at their alignment position. If new has no rows at all, fall
+  // back to a from-scratch reconstruction so we still emit deleted rows.
+  if (newTable.rows.length === 0) {
+    return rebuildStructurallyAlignedTable(oldHtml, newHtml, oldTable, newTable, alignment, diffCell)
+  }
+
+  // Emit the table header (`<table>` + any `<thead>`/`<tbody>` opening
+  // text up to the first row) up-front so a leading run of deleted-only
+  // alignments doesn't slip in before the table opens.
+  const out: string[] = []
+  out.push(newHtml.slice(newTable.tableStart, newTable.rows[0].rowStart))
+  let cursor = newTable.rows[0].rowStart
+  for (const align of alignment) {
+    if (align.newIdx !== null) {
+      const newRow = newTable.rows[align.newIdx]
+      out.push(newHtml.slice(cursor, newRow.rowStart))
+      if (align.oldIdx !== null) {
+        out.push(diffPreservedRow(oldHtml, newHtml, oldTable.rows[align.oldIdx], newRow, diffCell))
+      } else {
+        out.push(emitFullRow(newHtml, newRow, 'ins', diffCell))
+      }
+      cursor = newRow.rowEnd
+    } else if (align.oldIdx !== null) {
+      // Deleted row: inject inline at the current cursor (between the
+      // previously emitted row and the next one in new).
+      out.push(emitFullRow(oldHtml, oldTable.rows[align.oldIdx], 'del', diffCell))
+    }
+  }
+  out.push(newHtml.slice(cursor, newTable.tableEnd))
+  return out.join('')
+}
+
+function rebuildStructurallyAlignedTable(
+  oldHtml: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange,
+  alignment: Alignment[],
+  diffCell: DiffCellFn
+): string {
+  // Used when new has no rows but old does — we lose the per-row
+  // wrappers from new (there are none), so reconstruct from old's frame.
+  const out: string[] = []
+  out.push(headerSlice(newHtml, newTable, oldHtml, oldTable))
+  for (const align of alignment) {
+    if (align.oldIdx !== null) {
+      out.push(emitFullRow(oldHtml, oldTable.rows[align.oldIdx], 'del', diffCell))
+    } else if (align.newIdx !== null) {
+      out.push(emitFullRow(newHtml, newTable.rows[align.newIdx], 'ins', diffCell))
+    }
+  }
+  out.push('</table>')
+  return out.join('')
+}
+
+function headerSlice(newHtml: string, newTable: TableRange, oldHtml: string, oldTable: TableRange): string {
+  // Slice from <table> to the start of the first <tr>. Prefer new since
+  // attribute changes on <table> itself should follow new.
+  const newFirstRow = newTable.rows[0]?.rowStart ?? newTable.tableEnd - '</table>'.length
+  if (newFirstRow > newTable.tableStart) {
+    return newHtml.slice(newTable.tableStart, newFirstRow)
+  }
+  const oldFirstRow = oldTable.rows[0]?.rowStart ?? oldTable.tableEnd - '</table>'.length
+  return oldHtml.slice(oldTable.tableStart, oldFirstRow)
+}
+
+function rowKey(html: string, row: RowRange): string {
+  // Include cell tag text in the key so column-add doesn't accidentally
+  // match a row to one with different cell counts. Whitespace-normalize to
+  // tolerate formatting differences.
+  return html.slice(row.rowStart, row.rowEnd).replace(/\s+/g, ' ').trim()
+}
+
+function diffPreservedRow(
+  oldHtml: string,
+  newHtml: string,
+  oldRow: RowRange,
+  newRow: RowRange,
+  diffCell: DiffCellFn
+): string {
+  if (oldRow.cells.length === newRow.cells.length) {
+    return diffPositionalRow(oldHtml, newHtml, oldRow, newRow, diffCell)
+  }
+  // Cell counts differ. Try to interpret it as a horizontal merge/split via
+  // colspan first — preserving the new structure with `class='mod colspan'`
+  // on each affected cell. Falls back to the cell-LCS path if the cells
+  // don't align cleanly on logical column positions.
+  const colspanAligned = diffColspanChangedRow(oldHtml, newHtml, oldRow, newRow, diffCell)
+  if (colspanAligned !== null) return colspanAligned
+  return diffStructurallyAlignedRow(oldHtml, newHtml, oldRow, newRow, diffCell)
+}
+
+/**
+ * Try to align cells by logical column position (sum of colspans). When
+ * one side has a colspan'd cell that absorbs multiple cells on the other
+ * side, emit the new structure with `class='mod colspan'` on the
+ * merged/split cells. Returns null if the rows don't align cleanly —
+ * caller falls back to a generic cell-LCS.
+ */
+function diffColspanChangedRow(
+  oldHtml: string,
+  newHtml: string,
+  oldRow: RowRange,
+  newRow: RowRange,
+  diffCell: DiffCellFn
+): string | null {
+  const oldWidth = sumColspans(oldHtml, oldRow.cells)
+  const newWidth = sumColspans(newHtml, newRow.cells)
+  if (oldWidth !== newWidth) return null
+
+  const out: string[] = []
+  out.push(rowHeaderSlice(newHtml, newRow))
+
+  let oi = 0
+  let ni = 0
+  while (oi < oldRow.cells.length && ni < newRow.cells.length) {
+    const oCell = oldRow.cells[oi]
+    const nCell = newRow.cells[ni]
+    const oSpan = getColspan(oldHtml, oCell)
+    const nSpan = getColspan(newHtml, nCell)
+
+    if (oSpan === nSpan) {
+      out.push(emitDiffedCell(oldHtml, newHtml, oCell, nCell, diffCell))
+      oi++
+      ni++
+    } else if (nSpan > oSpan) {
+      // New cell absorbs multiple old cells — horizontal merge.
+      let totalOldSpan = 0
+      let oj = oi
+      while (oj < oldRow.cells.length && totalOldSpan < nSpan) {
+        totalOldSpan += getColspan(oldHtml, oldRow.cells[oj])
+        oj++
+      }
+      if (totalOldSpan !== nSpan) return null
+      out.push(emitSpanChangedCell(newHtml, nCell, 'colspan'))
+      oi = oj
+      ni++
+    } else {
+      // One old cell becomes multiple new cells — horizontal split.
+      let totalNewSpan = 0
+      let nj = ni
+      while (nj < newRow.cells.length && totalNewSpan < oSpan) {
+        totalNewSpan += getColspan(newHtml, newRow.cells[nj])
+        nj++
+      }
+      if (totalNewSpan !== oSpan) return null
+      for (let k = ni; k < nj; k++) {
+        out.push(emitSpanChangedCell(newHtml, newRow.cells[k], 'colspan'))
+      }
+      oi++
+      ni = nj
+    }
+  }
+
+  // If we couldn't consume both sides cleanly, bail out.
+  if (oi !== oldRow.cells.length || ni !== newRow.cells.length) return null
+
+  out.push('</tr>')
+  return out.join('')
+}
+
+function sumColspans(html: string, cells: CellRange[]): number {
+  let total = 0
+  for (const cell of cells) total += getColspan(html, cell)
+  return total
+}
+
+function getColspan(html: string, cell: CellRange): number {
+  return parseSpanAttribute(html.slice(cell.cellStart, cell.contentStart), 'colspan')
+}
+
+function getRowspan(html: string, cell: CellRange): number {
+  return parseSpanAttribute(html.slice(cell.cellStart, cell.contentStart), 'rowspan')
+}
+
+function parseSpanAttribute(openingTag: string, name: 'colspan' | 'rowspan'): number {
+  const re = name === 'colspan' ? /\bcolspan\s*=\s*["']?(\d+)["']?/i : /\browspan\s*=\s*["']?(\d+)["']?/i
+  const m = re.exec(openingTag)
+  if (!m) return 1
+  const value = Number.parseInt(m[1], 10)
+  return Number.isFinite(value) && value > 0 ? value : 1
+}
+
+/**
+ * Emits a cell that's the merged/split product of a structural change,
+ * tagged with `class='mod colspan'` or `class='mod rowspan'`. Content is
+ * carried through unmodified — Word doesn't track these changes, and
+ * inserting del/ins around content that didn't really change would be
+ * misleading.
+ */
+function emitSpanChangedCell(html: string, cell: CellRange, kind: 'colspan' | 'rowspan'): string {
+  const tdOpening = parseOpeningTagAt(html, cell.cellStart)
+  if (!tdOpening) return html.slice(cell.cellStart, cell.cellEnd)
+  const tdOpenTag = injectClass(html.slice(cell.cellStart, tdOpening.end), `mod ${kind}`)
+  return tdOpenTag + html.slice(cell.contentStart, cell.cellEnd)
+}
+
+function diffPositionalRow(
+  oldHtml: string,
+  newHtml: string,
+  oldRow: RowRange,
+  newRow: RowRange,
+  diffCell: DiffCellFn
+): string {
+  const out: string[] = []
+  // Use new's <tr> opening tag (preserves attributes from new).
+  const trHeader = rowHeaderSlice(newHtml, newRow)
+  out.push(trHeader)
+
+  let cursor = newRow.cells[0]?.cellStart ?? newRow.rowEnd
+  for (let c = 0; c < newRow.cells.length; c++) {
+    const oldCell = oldRow.cells[c]
+    const newCell = newRow.cells[c]
+    out.push(newHtml.slice(cursor, newCell.contentStart))
+    out.push(
+      diffCell(
+        oldHtml.slice(oldCell.contentStart, oldCell.contentEnd),
+        newHtml.slice(newCell.contentStart, newCell.contentEnd)
+      )
+    )
+    cursor = newCell.contentEnd
+  }
+  out.push(newHtml.slice(cursor, newRow.rowEnd))
+  return out.join('')
+}
+
+function diffStructurallyAlignedRow(
+  oldHtml: string,
+  newHtml: string,
+  oldRow: RowRange,
+  newRow: RowRange,
+  diffCell: DiffCellFn
+): string {
+  const oldKeys = oldRow.cells.map(cell => cellKey(oldHtml, cell))
+  const newKeys = newRow.cells.map(cell => cellKey(newHtml, cell))
+  const exactAlignment = lcsAlign(oldKeys, newKeys)
+  // After exact LCS, fuzzy-pair adjacent unmatched old/new cells whose
+  // content is similar enough — so a content-edit cell alongside a
+  // column-add in the same row produces a content diff for the edited
+  // cell rather than a phantom delete + insert + extra cell.
+  const alignment = pairSimilarUnmatchedCells(exactAlignment, oldRow, newRow, oldHtml, newHtml)
+
+  const out: string[] = []
+  // Use new's <tr> if it exists; otherwise old's.
+  out.push(rowHeaderSlice(newHtml, newRow))
+
+  for (const align of alignment) {
+    if (align.oldIdx !== null && align.newIdx !== null) {
+      const oldCell = oldRow.cells[align.oldIdx]
+      const newCell = newRow.cells[align.newIdx]
+      out.push(emitDiffedCell(oldHtml, newHtml, oldCell, newCell, diffCell))
+    } else if (align.newIdx !== null) {
+      out.push(emitFullCell(newHtml, newRow.cells[align.newIdx], 'ins', diffCell))
+    } else if (align.oldIdx !== null) {
+      out.push(emitFullCell(oldHtml, oldRow.cells[align.oldIdx], 'del', diffCell))
+    }
+  }
+
+  out.push('</tr>')
+  return out.join('')
+}
+
+function cellKey(html: string, cell: CellRange): string {
+  // Use cell content (not tag attributes) for matching, since column-add
+  // typically changes content but not tag attributes — and matching purely
+  // on attributes would mis-pair cells with the same content but different
+  // styling.
+  return html.slice(cell.contentStart, cell.contentEnd).replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Emits a row with all cells either inserted (kind='ins') or deleted
+ * (kind='del'). Adds `class='diffins'`/`'diffdel'` to the `<tr>` and to
+ * each `<td>`, with an `<ins>`/`<del>` wrapper around any cell content
+ * (empty cells get the class but no wrapper).
+ */
+function emitFullRow(html: string, row: RowRange, kind: 'ins' | 'del', diffCell: DiffCellFn): string {
+  const cls = kind === 'ins' ? 'diffins' : 'diffdel'
+  const trOpening = parseOpeningTagAt(html, row.rowStart)
+  if (!trOpening) return html.slice(row.rowStart, row.rowEnd)
+  const trOpenTag = injectClass(html.slice(row.rowStart, trOpening.end), cls)
+
+  const out: string[] = [trOpenTag]
+  let cursor = trOpening.end
+  for (const cell of row.cells) {
+    out.push(html.slice(cursor, cell.cellStart))
+    out.push(emitFullCell(html, cell, kind, diffCell))
+    cursor = cell.cellEnd
+  }
+  out.push(html.slice(cursor, row.rowEnd))
+  return out.join('')
+}
+
+/**
+ * Emits a fully-inserted or fully-deleted cell. Inner text runs are wrapped
+ * with `<ins>`/`<del>` while formatting tags pass through unchanged, so
+ * `<strong>B</strong>` renders as `<strong><ins>B</ins></strong>` —
+ * matching htmldiff's general convention without the doubled-`<ins>` that
+ * the full recursive diff would produce for newly-inserted formatting.
+ * Empty cells get the class on the `<td>` but no inner wrapping.
+ */
+function emitFullCell(html: string, cell: CellRange, kind: 'ins' | 'del', _diffCell: DiffCellFn): string {
+  const cls = kind === 'ins' ? 'diffins' : 'diffdel'
+  const tdOpening = parseOpeningTagAt(html, cell.cellStart)
+  if (!tdOpening) return html.slice(cell.cellStart, cell.cellEnd)
+  const tdOpenTag = injectClass(html.slice(cell.cellStart, tdOpening.end), cls)
+
+  const content = html.slice(cell.contentStart, cell.contentEnd)
+  const wrapped = content.trim().length === 0 ? content : wrapInlineTextRuns(content, kind)
+  const closing = html.slice(cell.contentEnd, cell.cellEnd)
+  return tdOpenTag + wrapped + closing
+}
+
+/**
+ * Wraps every non-whitespace text run in the given content with an
+ * `<ins>`/`<del>` tag, leaving HTML tags untouched. This produces output
+ * like `<strong><ins>X</ins></strong>` for fully-inserted formatted
+ * content — the same shape the rest of htmldiff emits for content
+ * insertions inside existing formatting.
+ */
+function wrapInlineTextRuns(content: string, kind: 'ins' | 'del'): string {
+  const tag = kind === 'ins' ? 'ins' : 'del'
+  const cls = kind === 'ins' ? 'diffins' : 'diffdel'
+
+  const out: string[] = []
+  let i = 0
+  while (i < content.length) {
+    if (content[i] === '<') {
+      const tagEnd = parseOpeningTagAt(content, i)
+      if (!tagEnd) {
+        // Malformed — pass the rest through verbatim.
+        out.push(content.slice(i))
+        break
+      }
+      out.push(content.slice(i, tagEnd.end))
+      i = tagEnd.end
+      continue
+    }
+    let j = i
+    while (j < content.length && content[j] !== '<') j++
+    const text = content.slice(i, j)
+    if (text.trim().length > 0) {
+      out.push(`<${tag} class='${cls}'>${text}</${tag}>`)
+    } else {
+      out.push(text)
+    }
+    i = j
+  }
+  return out.join('')
+}
+
+function emitDiffedCell(
+  oldHtml: string,
+  newHtml: string,
+  oldCell: CellRange,
+  newCell: CellRange,
+  diffCell: DiffCellFn
+): string {
+  const tdOpening = parseOpeningTagAt(newHtml, newCell.cellStart)
+  if (!tdOpening) return newHtml.slice(newCell.cellStart, newCell.cellEnd)
+  const tdOpenTag = newHtml.slice(newCell.cellStart, tdOpening.end)
+  const content = diffCell(
+    oldHtml.slice(oldCell.contentStart, oldCell.contentEnd),
+    newHtml.slice(newCell.contentStart, newCell.contentEnd)
+  )
+  const closing = newHtml.slice(newCell.contentEnd, newCell.cellEnd)
+  return tdOpenTag + content + closing
+}
+
+function rowHeaderSlice(html: string, row: RowRange): string {
+  // Slice from <tr> to just before the first <td> opening tag. Preserves
+  // the <tr ...> attributes plus any inter-tag whitespace. For a row with
+  // no cells, we only want the `<tr ...>` opening — the caller appends the
+  // closing `</tr>` explicitly, so taking the whole `<tr></tr>` here would
+  // double the close.
+  const opening = parseOpeningTagAt(html, row.rowStart)
+  if (!opening) return ''
+  if (row.cells.length === 0) return html.slice(row.rowStart, opening.end)
+  return html.slice(row.rowStart, row.cells[0].cellStart)
+}
+
+interface Alignment {
+  oldIdx: number | null
+  newIdx: number | null
+}
+
+/** Character-level similarity threshold above which we treat two rows as "the same row, edited". */
+const ROW_FUZZY_THRESHOLD = 0.5
+
+/**
+ * Threshold for "this cell is a content-edit of that cell." Tuned the same
+ * as ROW_FUZZY_THRESHOLD; cells in legal docs that share most of their
+ * content typically ARE the same logical cell with a body edit, so 0.5
+ * works for both granularities in practice.
+ */
+const CELL_FUZZY_THRESHOLD = 0.5
+
+/**
+ * After exact LCS, scan the alignment for runs of "old deleted, then new
+ * inserted" (or vice versa) and pair entries whose content is similar
+ * enough to be treated as an edit rather than a delete+insert. This keeps
+ * row-level edits (a typo fix, a single word change) from being shown as
+ * an entire row vanishing and a new one appearing — matching what users
+ * expect from a typical track-changes view.
+ */
+function pairSimilarUnmatchedRows(
+  alignment: Alignment[],
+  oldTable: TableRange,
+  newTable: TableRange,
+  oldHtml: string,
+  newHtml: string
+): Alignment[] {
+  return pairSimilarUnmatched(alignment, ROW_FUZZY_THRESHOLD, (oldIdx, newIdx) =>
+    rowSimilarity(oldTable.rows[oldIdx], newTable.rows[newIdx], oldHtml, newHtml)
+  )
+}
+
+function pairSimilarUnmatchedCells(
+  alignment: Alignment[],
+  oldRow: RowRange,
+  newRow: RowRange,
+  oldHtml: string,
+  newHtml: string
+): Alignment[] {
+  return pairSimilarUnmatched(alignment, CELL_FUZZY_THRESHOLD, (oldIdx, newIdx) =>
+    cellSimilarity(oldRow.cells[oldIdx], newRow.cells[newIdx], oldHtml, newHtml)
+  )
+}
+
+/**
+ * Identify pairings inside each unmatched-only run, then build the output
+ * alignment by walking the original and substituting paired entries at
+ * the *ins position* (not the del position). This keeps the result
+ * monotonic in newIdx — critical because the cursor-based emission
+ * downstream walks new's html in order. Emitting at the del position
+ * would be fine when del<ins in the alignment array (the typical case),
+ * but can violate monotonicity when there are mixed unpaired entries in
+ * between (column-add + row-add together, content-edit + column-add,
+ * etc.).
+ *
+ * Generic over what's being paired — works for both rows (by full row
+ * content similarity) and cells (by per-cell content similarity).
+ */
+function pairSimilarUnmatched(
+  alignment: Alignment[],
+  threshold: number,
+  similarity: (oldIdx: number, newIdx: number) => number
+): Alignment[] {
+  const pairs = new Map<number, number>() // del-alignment-idx → ins-alignment-idx
+  let i = 0
+  while (i < alignment.length) {
+    if (alignment[i].oldIdx !== null && alignment[i].newIdx !== null) {
+      i++
+      continue
+    }
+    const runStart = i
+    while (i < alignment.length && (alignment[i].oldIdx === null) !== (alignment[i].newIdx === null)) i++
+    const runEnd = i
+
+    const delIndices: number[] = []
+    const insIndices: number[] = []
+    for (let k = runStart; k < runEnd; k++) {
+      if (alignment[k].oldIdx !== null) delIndices.push(k)
+      else insIndices.push(k)
+    }
+
+    const usedIns = new Set<number>()
+    for (const di of delIndices) {
+      let bestIi = -1
+      let bestSim = threshold
+      for (const ii of insIndices) {
+        if (usedIns.has(ii)) continue
+        const sim = similarity(alignment[di].oldIdx as number, alignment[ii].newIdx as number)
+        if (sim > bestSim) {
+          bestSim = sim
+          bestIi = ii
+        }
+      }
+      if (bestIi >= 0) {
+        pairs.set(di, bestIi)
+        usedIns.add(bestIi)
+      }
+    }
+  }
+
+  const insToDel = new Map<number, number>() // ins-alignment-idx → del-alignment-idx
+  for (const [delAi, insAi] of pairs) insToDel.set(insAi, delAi)
+  const pairedDels = new Set<number>(pairs.keys())
+
+  const result: Alignment[] = []
+  for (let k = 0; k < alignment.length; k++) {
+    if (pairedDels.has(k)) continue // paired del — emitted when we reach its ins
+    if (insToDel.has(k)) {
+      const delAi = insToDel.get(k) as number
+      result.push({ oldIdx: alignment[delAi].oldIdx, newIdx: alignment[k].newIdx })
+    } else {
+      result.push(alignment[k])
+    }
+  }
+  return result
+}
+
+/**
+ * Character-level similarity using shared prefix + suffix as a fraction
+ * of the longer string. Catches "single edit somewhere in a long row"
+ * (which token-Jaccard misses on short rows) while still correctly
+ * rejecting rows with no positional overlap. HTML tags are stripped to
+ * keep the comparison content-focused.
+ */
+function rowSimilarity(oldRow: RowRange, newRow: RowRange, oldHtml: string, newHtml: string): number {
+  const a = rowText(oldHtml, oldRow)
+  const b = rowText(newHtml, newRow)
+  if (a === b) return 1
+  if (a.length === 0 || b.length === 0) return 0
+
+  let prefix = 0
+  const minLen = Math.min(a.length, b.length)
+  while (prefix < minLen && a[prefix] === b[prefix]) prefix++
+
+  let suffix = 0
+  while (
+    suffix < a.length - prefix &&
+    suffix < b.length - prefix &&
+    a[a.length - 1 - suffix] === b[b.length - 1 - suffix]
+  ) {
+    suffix++
+  }
+
+  return (prefix + suffix) / Math.max(a.length, b.length)
+}
+
+function rowText(html: string, row: RowRange): string {
+  const parts: string[] = []
+  for (const cell of row.cells) {
+    parts.push(html.slice(cell.contentStart, cell.contentEnd).replace(/<[^>]+>/g, ' '))
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+/**
+ * Character-level prefix+suffix similarity for a single cell's text
+ * content. Same metric as rowSimilarity, scoped to one cell so we can
+ * fuzzy-pair unmatched cells (e.g. a cell with a content edit alongside
+ * a column add in the same row).
+ */
+function cellSimilarity(oldCell: CellRange, newCell: CellRange, oldHtml: string, newHtml: string): number {
+  const a = cellText(oldHtml, oldCell)
+  const b = cellText(newHtml, newCell)
+  if (a === b) return 1
+  if (a.length === 0 || b.length === 0) return 0
+
+  let prefix = 0
+  const minLen = Math.min(a.length, b.length)
+  while (prefix < minLen && a[prefix] === b[prefix]) prefix++
+
+  let suffix = 0
+  while (
+    suffix < a.length - prefix &&
+    suffix < b.length - prefix &&
+    a[a.length - 1 - suffix] === b[b.length - 1 - suffix]
+  ) {
+    suffix++
+  }
+
+  return (prefix + suffix) / Math.max(a.length, b.length)
+}
+
+function cellText(html: string, cell: CellRange): string {
+  return html
+    .slice(cell.contentStart, cell.contentEnd)
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase()
+}
+
+/**
+ * Standard LCS alignment: walks both sequences and emits a list of pairs
+ * where `(oldIdx, newIdx)` are both set for matching positions, and one
+ * side is null for an unmatched entry on the other side. Equality uses
+ * strict ===.
+ */
+function lcsAlign(oldKeys: string[], newKeys: string[]): Alignment[] {
+  const m = oldKeys.length
+  const n = newKeys.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0))
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (oldKeys[i - 1] === newKeys[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1] + 1
+      } else {
+        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1])
+      }
+    }
+  }
+
+  const result: Alignment[] = []
+  let i = m
+  let j = n
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && oldKeys[i - 1] === newKeys[j - 1]) {
+      result.unshift({ oldIdx: i - 1, newIdx: j - 1 })
+      i--
+      j--
+    } else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+      result.unshift({ oldIdx: null, newIdx: j - 1 })
+      j--
+    } else {
+      result.unshift({ oldIdx: i - 1, newIdx: null })
+      i--
+    }
+  }
+  return result
+}
+
+/**
+ * Returns the opening tag string with the given class injected. Existing
+ * `class` attributes are preserved and the new class appended.
+ */
+/**
+ * Returns the opening tag with the given class injected. Locates the real
+ * `class` attribute via attribute-aware walking (NOT a flat regex — that
+ * would mis-match inside a foreign attribute value like
+ * `title="see class='x'"`). When the class already partially overlaps with
+ * `cls` — e.g. existing `class="mod"` and we're injecting `mod colspan` —
+ * only the missing tokens get appended, so we never end up with
+ * `class="mod mod colspan"`.
+ */
+function injectClass(openingTag: string, cls: string): string {
+  const clsTokens = cls.split(/\s+/).filter(Boolean)
+  if (clsTokens.length === 0) return openingTag
+
+  const classAttr = findClassAttribute(openingTag)
+  if (classAttr) {
+    const existingTokens = classAttr.value.split(/\s+/).filter(Boolean)
+    const missing = clsTokens.filter(t => !existingTokens.includes(t))
+    if (missing.length === 0) return openingTag
+    const updatedValue =
+      existingTokens.length === 0 ? missing.join(' ') : `${existingTokens.join(' ')} ${missing.join(' ')}`
+    return openingTag.slice(0, classAttr.valueStart) + updatedValue + openingTag.slice(classAttr.valueEnd)
+  }
+
+  const isSelfClosing = openingTag.endsWith('/>')
+  const insertAt = isSelfClosing ? openingTag.length - 2 : openingTag.length - 1
+  return `${openingTag.slice(0, insertAt).replace(/\s*$/, '')} class='${cls}'${openingTag.slice(insertAt)}`
+}
+
+/**
+ * Walks the opening tag's attributes (respecting quoted values) to find
+ * the actual `class` attribute. Returns the value range (start/end of the
+ * value content, *excluding* the surrounding quotes) and the value, or
+ * null if no `class` attribute is present.
+ */
+function findClassAttribute(openingTag: string): { valueStart: number; valueEnd: number; value: string } | null {
+  // Skip past the tag name. Tag starts with `<`; first run of [A-Za-z0-9-]
+  // is the tag name. Anything after is attribute territory.
+  let i = 1
+  while (i < openingTag.length && /[A-Za-z0-9_:-]/.test(openingTag[i])) i++
+
+  while (i < openingTag.length) {
+    // Skip whitespace
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+    if (i >= openingTag.length) break
+    if (openingTag[i] === '>' || openingTag[i] === '/') break
+
+    // Read attribute name
+    const nameStart = i
+    while (i < openingTag.length && !/[\s=>/]/.test(openingTag[i])) i++
+    const name = openingTag.slice(nameStart, i)
+
+    // Optional whitespace + '=' + optional whitespace + value
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+    if (openingTag[i] !== '=') {
+      // Bare attribute (no value) — not class
+      continue
+    }
+    i++ // past '='
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+
+    // Value: quoted or unquoted
+    let valueStart: number
+    let valueEnd: number
+    if (openingTag[i] === '"' || openingTag[i] === "'") {
+      const quote = openingTag[i]
+      i++
+      valueStart = i
+      while (i < openingTag.length && openingTag[i] !== quote) i++
+      valueEnd = i
+      if (i < openingTag.length) i++ // past closing quote
+    } else {
+      valueStart = i
+      while (i < openingTag.length && !/[\s>/]/.test(openingTag[i])) i++
+      valueEnd = i
+    }
+
+    if (name.toLowerCase() === 'class') {
+      return { valueStart, valueEnd, value: openingTag.slice(valueStart, valueEnd) }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Walks html and returns ranges for every top-level `<table>...</table>`
+ * block. Nested tables aren't extracted as separate top-level entries —
+ * they're captured inside the parent's content range and handled when the
+ * cell-level diff recurses through them.
+ */
+function findTopLevelTables(html: string): TableRange[] {
+  const tables: TableRange[] = []
+  let i = 0
+  while (i < html.length) {
+    if (matchesTagAt(html, i, 'table')) {
+      const opening = parseOpeningTagAt(html, i)
+      if (!opening) {
+        i++
+        continue
+      }
+      const tableContentStart = opening.end
+      const tableEnd = findMatchingClosingTag(html, tableContentStart, 'table')
+      if (tableEnd === -1) {
+        i = opening.end
+        continue
+      }
+      const closingTagStart = tableEnd - '</table>'.length
+      const rows = findTopLevelRows(html, tableContentStart, closingTagStart)
+      tables.push({ tableStart: i, tableEnd, rows })
+      i = tableEnd
+    } else {
+      i++
+    }
+  }
+  return tables
+}
+
+function findTopLevelRows(html: string, start: number, end: number): RowRange[] {
+  const rows: RowRange[] = []
+  let i = start
+  while (i < end) {
+    if (matchesTagAt(html, i, 'tr')) {
+      const opening = parseOpeningTagAt(html, i)
+      if (!opening) {
+        i++
+        continue
+      }
+      const rowContentStart = opening.end
+      const rowEnd = findMatchingClosingTag(html, rowContentStart, 'tr', end)
+      if (rowEnd === -1) {
+        i = opening.end
+        continue
+      }
+      const closingTagStart = rowEnd - '</tr>'.length
+      const cells = findTopLevelCells(html, rowContentStart, closingTagStart)
+      rows.push({ rowStart: i, rowEnd, cells })
+      i = rowEnd
+    } else if (matchesClosingTagAt(html, i, 'table')) {
+      // Defensive: bail out if we encounter a closing </table> while
+      // scanning rows (we should have stopped at `end` already).
+      break
+    } else {
+      i++
+    }
+  }
+  return rows
+}
+
+function findTopLevelCells(html: string, start: number, end: number): CellRange[] {
+  const cells: CellRange[] = []
+  let i = start
+  while (i < end) {
+    if (matchesTagAt(html, i, 'td') || matchesTagAt(html, i, 'th')) {
+      const tagName = matchesTagAt(html, i, 'td') ? 'td' : 'th'
+      const opening = parseOpeningTagAt(html, i)
+      if (!opening) {
+        i++
+        continue
+      }
+      const contentStart = opening.end
+      const cellEnd = findMatchingClosingTag(html, contentStart, tagName, end)
+      if (cellEnd === -1) {
+        i = opening.end
+        continue
+      }
+      const contentEnd = cellEnd - `</${tagName}>`.length
+      cells.push({ cellStart: i, cellEnd, contentStart, contentEnd })
+      i = cellEnd
+    } else if (matchesClosingTagAt(html, i, 'tr')) {
+      break
+    } else {
+      i++
+    }
+  }
+  return cells
+}
+
+function matchesTagAt(html: string, i: number, tagName: string): boolean {
+  if (html[i] !== '<') return false
+  const candidate = html.slice(i + 1, i + 1 + tagName.length).toLowerCase()
+  if (candidate !== tagName) return false
+  const after = html[i + 1 + tagName.length]
+  return after === '>' || after === ' ' || after === '\t' || after === '\n' || after === '\r' || after === '/'
+}
+
+function matchesClosingTagAt(html: string, i: number, tagName: string): boolean {
+  if (html[i] !== '<' || html[i + 1] !== '/') return false
+  const candidate = html.slice(i + 2, i + 2 + tagName.length).toLowerCase()
+  if (candidate !== tagName) return false
+  const after = html[i + 2 + tagName.length]
+  return after === '>' || after === ' ' || after === '\t' || after === '\n' || after === '\r'
+}
+
+interface OpeningTag {
+  /** Index just past the closing `>` of the opening tag. */
+  end: number
+}
+
+function parseOpeningTagAt(html: string, i: number): OpeningTag | null {
+  // HTML comments, CDATA, processing instructions, and DOCTYPE need their
+  // own terminators — a plain `>`-walker would cut a comment like
+  // `<!-- a > b -->` at the first inner `>`, treating the rest as text
+  // and corrupting downstream offsets. Word-exported HTML routinely
+  // emits comments inside tables (conditional comments, OLE markers) so
+  // these have to be handled, not just be theoretical.
+  if (html.startsWith('<!--', i)) {
+    const close = html.indexOf('-->', i + 4)
+    return close === -1 ? null : { end: close + 3 }
+  }
+  if (html.startsWith('<![CDATA[', i)) {
+    const close = html.indexOf(']]>', i + 9)
+    return close === -1 ? null : { end: close + 3 }
+  }
+  if (html.startsWith('<?', i)) {
+    const close = html.indexOf('?>', i + 2)
+    return close === -1 ? null : { end: close + 2 }
+  }
+  // Walk to the next unquoted '>'. Handles attributes whose values contain
+  // a literal '>' inside quotes, which a plain indexOf would mishandle.
+  let j = i + 1
+  let quote: string | null = null
+  while (j < html.length) {
+    const ch = html[j]
+    if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '>') {
+      return { end: j + 1 }
+    }
+    j++
+  }
+  return null
+}
+
+/**
+ * Returns the index just past the matching `</tagName>`, accounting for
+ * nested tags of the same name. Returns -1 if no match before `limit`.
+ */
+function findMatchingClosingTag(html: string, from: number, tagName: string, limit: number = html.length): number {
+  let depth = 1
+  let i = from
+  while (i < limit) {
+    if (matchesTagAt(html, i, tagName)) {
+      const opening = parseOpeningTagAt(html, i)
+      if (!opening) {
+        i++
+        continue
+      }
+      const tagText = html.slice(i, opening.end)
+      if (!tagText.endsWith('/>')) depth++
+      i = opening.end
+    } else if (matchesClosingTagAt(html, i, tagName)) {
+      depth--
+      const closing = parseOpeningTagAt(html, i)
+      const closingEnd = closing?.end ?? i + `</${tagName}>`.length
+      if (depth === 0) return closingEnd
+      i = closingEnd
+    } else {
+      i++
+    }
+  }
+  return -1
+}