@atlaskit/editor-plugin-show-diff 10.1.23 → 10.3.0

package/dist/es2019/pm-plugins/calculateDiff/smart/classifySmartChanges.js

@@ -0,0 +1,689 @@
+import { makePromotedChange, mergeOverlappingByNewDocRange, rangesOverlap } from './helpers';
+import { buildCharsByOffset, countWords, segmentSentences, segmentWordSpans } from './segmentText';
+import { resolveThresholds } from './thresholds';
+/**
+ * Block-first `smart` classifier.
+ *
+ * Groups changes by the top-level block they touch — like the `block` diff type — then
+ * classifies WITHIN each block group:
+ *
+ *   1. structural / node-type change (blockA.type !== blockB.type)  → whole block
+ *   2. text-bearing block (paragraph/heading)                       → sentence / paragraph / inline
+ *   3. container block (list/table/layout/panel/...)                → recurse into children,
+ *      promoting the whole container when changed-child density ≥ node.ratio (with the
+ *      rigid-child escalation: cell → row → table, column → section, item → list).
+ *
+ * Grouping on real top-level block boundaries prevents the "empty structural shell" family
+ * of bugs (e.g. bulletList → table rendering empty bullets).
+ */
+export const classifySmartChanges = ({
+  changes,
+  originalDoc,
+  newDoc,
+  locale,
+  thresholds: overrides
+}) => {
+  if (changes.length === 0) {
+    return changes;
+  }
+  const thresholds = resolveThresholds(overrides);
+  const groups = groupByTopLevelBlock(changes, originalDoc, newDoc);
+  const result = [];
+  for (const group of groups) {
+    result.push(...classifyBlockGroup(group, originalDoc, newDoc, locale, thresholds));
+  }
+
+  // Clamp to valid bounds (defensive) and coalesce overlaps.
+  const maxA = originalDoc.content.size;
+  const maxB = newDoc.content.size;
+  const clamped = result.map(change => clampChange(change, maxA, maxB)).filter(change => change !== null);
+  return mergeOverlappingByNewDocRange(clamped);
+};
+
+/**
+ * A group of raw changes that all fall within the same top-level block, plus the resolved
+ * block node on each side. `blockA`/`blockB` are null for pure insertions/deletions where
+ * one side has no corresponding block.
+ */
+
+/** A resolved block: the node plus its OUTER bounds (before open token / after close token). */
+
+/**
+ * Group changes by the top-level block (direct child of doc) they touch, aligning the A-side
+ * and B-side blocks a change covers. A single change can span MULTIPLE top-level blocks (e.g.
+ * a ReplaceStep whose slice contains several nodes); we enumerate every block it overlaps on
+ * both sides (`topLevelBlocksInRange`) and create one group per aligned block, so added/removed
+ * blocks in a multi-node replacement are never dropped. Unlike `groupChangesByBlock`, we KEEP
+ * each group's constituent raw changes so intra-block density can be measured.
+ */
+const groupByTopLevelBlock = (changes, docA, docB) => {
+  const groups = new Map();
+  const ensureGroup = (blockA, blockB, anchors) => {
+    if (!blockA && !blockB) {
+      return null;
+    }
+    // Key by both sides so an added block (blockA=null) on the B side and a deleted block
+    // (blockB=null) on the A side each get their own group.
+    const key = `${blockB ? blockB.from : 'x'}:${blockA ? blockA.from : 'x'}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = {
+        blockA,
+        blockB,
+        changes: [],
+        ...anchors
+      };
+      groups.set(key, group);
+    }
+    return group;
+  };
+  for (const change of changes) {
+    // A single change (e.g. a ReplaceStep whose slice spans several nodes) can cover MULTIPLE
+    // top-level blocks on either side. Resolving only the block at `fromB` would silently drop
+    // the extra blocks (e.g. an added table after a replaced paragraph). So we enumerate every
+    // top-level block the change overlaps on BOTH sides and create a group per aligned block.
+    const blocksB = topLevelBlocksInRange(docB, change.fromB, change.toB);
+    const blocksA = topLevelBlocksInRange(docA, change.fromA, change.toA);
+
+    // Simple, common case: exactly one block on each side (or one side empty).
+    if (blocksB.length <= 1 && blocksA.length <= 1) {
+      var _blocksA$, _blocksB$;
+      const group = ensureGroup((_blocksA$ = blocksA[0]) !== null && _blocksA$ !== void 0 ? _blocksA$ : null, (_blocksB$ = blocksB[0]) !== null && _blocksB$ !== void 0 ? _blocksB$ : null);
+      group === null || group === void 0 ? void 0 : group.changes.push(change);
+      continue;
+    }
+
+    // Multi-block span: align blocks positionally by index. The first `min(len)` blocks are
+    // REPLACEMENTS (paired A↔B). Extra B-blocks are PURE INSERTIONS and extra A-blocks are
+    // PURE DELETIONS — and, crucially, these must NOT reuse the raw change's full A/B range
+    // (that range covers the paired blocks too, so an added block would claim the original
+    // content already owned by a paired replacement, rendering it deleted twice). Instead we
+    // anchor a pure insertion's A side (and a pure deletion's B side) as ZERO-WIDTH at the
+    // end of the last paired block on the opposite side.
+    const paired = Math.min(blocksA.length, blocksB.length);
+    for (let i = 0; i < paired; i++) {
+      const group = ensureGroup(blocksA[i], blocksB[i]);
+      group === null || group === void 0 ? void 0 : group.changes.push(change);
+    }
+    // Anchor for extras = end of the last paired block on the opposite side (or the start of
+    // the span if there were no paired blocks).
+    const anchorA = paired > 0 ? blocksA[paired - 1].to : change.fromA;
+    const anchorB = paired > 0 ? blocksB[paired - 1].to : change.fromB;
+    for (let i = paired; i < blocksB.length; i++) {
+      const group = ensureGroup(null, blocksB[i], {
+        anchorA
+      });
+      group === null || group === void 0 ? void 0 : group.changes.push(change);
+    }
+    for (let i = paired; i < blocksA.length; i++) {
+      const group = ensureGroup(blocksA[i], null, {
+        anchorB
+      });
+      group === null || group === void 0 ? void 0 : group.changes.push(change);
+    }
+  }
+  return Array.from(groups.values()).sort((a, b) => {
+    var _ref, _a$blockB$from, _a$blockB, _a$blockA, _ref2, _b$blockB$from, _b$blockB, _b$blockA;
+    return ((_ref = (_a$blockB$from = (_a$blockB = a.blockB) === null || _a$blockB === void 0 ? void 0 : _a$blockB.from) !== null && _a$blockB$from !== void 0 ? _a$blockB$from : (_a$blockA = a.blockA) === null || _a$blockA === void 0 ? void 0 : _a$blockA.from) !== null && _ref !== void 0 ? _ref : 0) - ((_ref2 = (_b$blockB$from = (_b$blockB = b.blockB) === null || _b$blockB === void 0 ? void 0 : _b$blockB.from) !== null && _b$blockB$from !== void 0 ? _b$blockB$from : (_b$blockA = b.blockA) === null || _b$blockA === void 0 ? void 0 : _b$blockA.from) !== null && _ref2 !== void 0 ? _ref2 : 0);
+  });
+};
+
+/**
+ * Enumerate the top-level blocks (direct children of doc) whose outer range overlaps
+ * `[from, to)`. Returns each as a BlockRef. Used to split a change that spans several blocks.
+ */
+const topLevelBlocksInRange = (doc, from, to) => {
+  const lo = Math.min(Math.max(from, 0), doc.content.size);
+  const hi = Math.min(Math.max(to, lo), doc.content.size);
+  const refs = [];
+  let offset = 0;
+  for (let i = 0; i < doc.childCount; i++) {
+    const node = doc.child(i);
+    const blockFrom = offset;
+    const blockTo = offset + node.nodeSize;
+    // Overlap test; include a zero-width touch at the block start (pure insertion point).
+    if (blockFrom < hi && blockTo > lo) {
+      refs.push({
+        node,
+        from: blockFrom,
+        to: blockTo
+      });
+    } else if (blockFrom === lo && blockFrom === hi) {
+      refs.push({
+        node,
+        from: blockFrom,
+        to: blockTo
+      });
+    }
+    offset = blockTo;
+  }
+  return refs;
+};
+const clampChange = (change, maxA, maxB) => {
+  const fromA = Math.max(0, Math.min(change.fromA, maxA));
+  const toA = Math.max(fromA, Math.min(change.toA, maxA));
+  const fromB = Math.max(0, Math.min(change.fromB, maxB));
+  const toB = Math.max(fromB, Math.min(change.toB, maxB));
+  if (toA === fromA && toB === fromB) {
+    return null;
+  }
+  return {
+    ...change,
+    fromA,
+    toA,
+    fromB,
+    toB
+  };
+};
+const TEXT_BLOCK_TYPES = new Set(['paragraph', 'heading']);
+
+/**
+ * Rigid children cannot be individually deleted+re-inserted without breaking their parent's
+ * structure — promoting one escalates to its structural unit (see classifyContainer):
+ *   layoutColumn → layoutSection, tableCell/tableHeader → tableRow → table.
+ */
+const RIGID_CHILD_TYPES = new Set(['layoutColumn', 'tableCell', 'tableHeader']);
+const TABLE_TYPE = 'table';
+
+/**
+ * Emit a single whole-block (node-level) change covering both sides of a group. Used for
+ * structural / node-type replacements and for containers dense enough to replace wholesale.
+ */
+const wholeBlockChange = (blockA, blockB, changes, anchors) => {
+  var _anchors$anchorA, _anchors$anchorA2, _anchors$anchorB, _anchors$anchorB2;
+  // Pure insertion (blockA === null): the A side must be a ZERO-WIDTH anchor, never the raw
+  // change's A range (which spans sibling blocks that were separately replaced). Same for a
+  // pure deletion's B side. Falling back to the change coords is the last-resort path when no
+  // anchor was supplied (single-block insert/delete, where the coords are already zero-width).
+  const fromA = blockA ? blockA.from : (_anchors$anchorA = anchors === null || anchors === void 0 ? void 0 : anchors.anchorA) !== null && _anchors$anchorA !== void 0 ? _anchors$anchorA : changes[0].fromA;
+  const toA = blockA ? blockA.to : (_anchors$anchorA2 = anchors === null || anchors === void 0 ? void 0 : anchors.anchorA) !== null && _anchors$anchorA2 !== void 0 ? _anchors$anchorA2 : changes[changes.length - 1].toA;
+  const fromB = blockB ? blockB.from : (_anchors$anchorB = anchors === null || anchors === void 0 ? void 0 : anchors.anchorB) !== null && _anchors$anchorB !== void 0 ? _anchors$anchorB : changes[0].fromB;
+  const toB = blockB ? blockB.to : (_anchors$anchorB2 = anchors === null || anchors === void 0 ? void 0 : anchors.anchorB) !== null && _anchors$anchorB2 !== void 0 ? _anchors$anchorB2 : changes[changes.length - 1].toB;
+  return makePromotedChange(fromA, toA, fromB, toB, 'node');
+};
+
+/**
+ * Classify one block group. This is the single recursive decision point:
+ *  - one side missing (pure insert/delete)   → whole block
+ *  - node type changed (para→panel, list→table, heading→para, …) → whole block
+ *  - text-bearing block                       → sentence / paragraph / inline
+ *  - container                                → recurse into children (with rigid escalation)
+ */
+const classifyBlockGroup = (group, originalDoc, newDoc, locale, thresholds) => {
+  const {
+    blockA,
+    blockB,
+    changes,
+    anchorA,
+    anchorB
+  } = group;
+
+  // Pure insertion or deletion of a whole block.
+  if (!blockA || !blockB) {
+    return [wholeBlockChange(blockA, blockB, changes, {
+      anchorA,
+      anchorB
+    })];
+  }
+
+  // Node-type / structural change: the whole block was replaced. No further analysis — this
+  // is what makes list→table, paragraph→panel, heading→paragraph "just work".
+  if (blockA.node.type.name !== blockB.node.type.name) {
+    return [wholeBlockChange(blockA, blockB, changes)];
+  }
+
+  // Text-bearing block → sentence / paragraph / inline.
+  if (TEXT_BLOCK_TYPES.has(blockB.node.type.name)) {
+    return classifyTextblock(blockA, blockB, changes, locale, thresholds);
+  }
+
+  // Container block → measure changed-child density, promote whole container or recurse.
+  return classifyContainer(blockA, blockB, changes, originalDoc, newDoc, locale, thresholds);
+};
+
+/**
+ * Sentence- and paragraph-level classification for a single text-bearing block.
+ */
+const classifyTextblock = (blockA, blockB, changes, locale, thresholds) => {
+  const charsB = buildCharsByOffset(blockB.node);
+  const sentencesB = segmentSentences(charsB, locale);
+  const charsA = buildCharsByOffset(blockA.node);
+  const sentencesA = segmentSentences(charsA, locale);
+
+  // Block content starts one position after the block's outer start (open token).
+  const contentStartB = blockB.from + 1;
+
+  // Map each change to the sentence indices (new-doc offset space) it overlaps.
+  const changedSentenceIdx = new Set();
+  const perSentenceChanges = new Map();
+  for (const change of changes) {
+    const fromOff = change.fromB - contentStartB;
+    const toOff = change.toB - contentStartB;
+    for (let s = 0; s < sentencesB.length; s++) {
+      const sentence = sentencesB[s];
+      if (rangesOverlap(fromOff, Math.max(toOff, fromOff + 1), sentence.from, sentence.to)) {
+        changedSentenceIdx.add(s);
+        let list = perSentenceChanges.get(s);
+        if (!list) {
+          list = [];
+          perSentenceChanges.set(s, list);
+        }
+        list.push(change);
+      }
+    }
+  }
+
+  // Level 2: paragraph promotion.
+  const sentenceDenom = Math.max(sentencesA.length, sentencesB.length, 1);
+  const sentencesChanged = changedSentenceIdx.size;
+  if (sentencesChanged >= thresholds.paragraph.minChanged && sentencesChanged / sentenceDenom >= thresholds.paragraph.ratio) {
+    return [makePromotedChange(blockA.from, blockA.to, blockB.from, blockB.to, 'paragraph')];
+  }
+
+  // Level 1: per-sentence promotion (else keep inline changes).
+  const contentStartA = blockA.from + 1;
+  const out = [];
+  for (const [sIdx, sentenceChanges] of perSentenceChanges.entries()) {
+    const sentence = sentencesB[sIdx];
+    const wordsNew = countWords(charsB, sentence, locale);
+    const sentA = sentencesA[sIdx];
+    const wordsOld = sentA ? countWords(charsA, sentA, locale) : 0;
+    const wordSpans = segmentWordSpans(charsB, sentence, locale);
+    let wordsChanged = 0;
+    for (const w of wordSpans) {
+      const overlaps = sentenceChanges.some(c => rangesOverlap(c.fromB - contentStartB, Math.max(c.toB - contentStartB, c.fromB - contentStartB + 1), w.from, w.to));
+      if (overlaps) {
+        wordsChanged++;
+      }
+    }
+    const wordDenom = Math.max(wordsOld, wordsNew, 1);
+    if (wordsChanged >= thresholds.sentence.minChanged && wordsChanged / wordDenom >= thresholds.sentence.ratio) {
+      const fromB = contentStartB + sentence.from;
+      const toB = contentStartB + sentence.to;
+      const fromA = sentA ? contentStartA + sentA.from : sentenceChanges[0].fromA;
+      const toA = sentA ? contentStartA + sentA.to : sentenceChanges[0].toA;
+      out.push(makePromotedChange(fromA, toA, fromB, toB, 'sentence'));
+    } else {
+      out.push(...sentenceChanges);
+    }
+  }
+  return out;
+};
+
+/** A resolved direct child of a container, with its outer bounds and index. */
+
+/** Resolve the direct children of a container node (whose OUTER start is `blockFrom`). */
+const childRefs = block => {
+  const refs = [];
+  let offset = block.from + 1; // content starts after the container's open token
+  block.node.forEach((child, _, index) => {
+    refs.push({
+      node: child,
+      from: offset,
+      to: offset + child.nodeSize,
+      index
+    });
+    offset += child.nodeSize;
+  });
+  return refs;
+};
+
+/** Which direct-child indices of `block` are touched by any of `changes` (new-doc coords). */
+const changedChildIndices = (block, children, changes) => {
+  const changed = new Set();
+  for (const child of children) {
+    const touched = changes.some(c => rangesOverlap(c.fromB, Math.max(c.toB, c.fromB + 1), child.from, child.to));
+    if (touched) {
+      changed.add(child.index);
+    }
+  }
+  return changed;
+};
+
+/**
+ * A single entry in an aligned child list: a matched A/B pair, a pure insertion (a=null), or a
+ * pure deletion (b=null).
+ */
+
+/**
+ * Align a container's A-side and B-side direct children via an LCS over their serialized
+ * content. This is essential because index alignment (`childrenA[childB.index]`) breaks the
+ * moment a child is inserted or removed: every child after the insertion/deletion point would
+ * be mis-paired, causing added items to be classified against the wrong (or a B-side) original
+ * child — which corrupts the A-side coordinates and makes one list's deletions surface under a
+ * different block. The LCS pairs identical children as "matched" (unchanged, skipped later),
+ * leaving genuinely added children as B-only and removed children as A-only.
+ */
+const alignChildren = (childrenA, childrenB) => {
+  const keyA = childrenA.map(c => JSON.stringify(c.node.toJSON()));
+  const keyB = childrenB.map(c => JSON.stringify(c.node.toJSON()));
+  const n = childrenA.length;
+  const m = childrenB.length;
+  // LCS length table.
+  const lcs = Array.from({
+    length: n + 1
+  }, () => Array.from({
+    length: m + 1
+  }, () => 0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = keyA[i] === keyB[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  // Backtrack. Identical children become matched anchors. Runs of non-identical children
+  // between anchors are "zipped" positionally into modified pairs (a & b), with any leftover
+  // B children as pure insertions and leftover A children as pure deletions. Zipping avoids
+  // treating a MODIFIED child (whose content merely differs) as a delete+insert — that pairing
+  // lets the recursion diff inside the child (inline/sentence) instead of replacing it whole.
+  const out = [];
+  let i = 0;
+  let j = 0;
+  // Pending runs of unmatched children on each side, flushed (zipped) at each anchor / at end.
+  let runA = [];
+  let runB = [];
+  const flushRuns = () => {
+    const shared = Math.min(runA.length, runB.length);
+    for (let k = 0; k < shared; k++) {
+      out.push({
+        a: runA[k],
+        b: runB[k]
+      });
+    }
+    for (let k = shared; k < runA.length; k++) {
+      out.push({
+        a: runA[k],
+        b: null
+      });
+    }
+    for (let k = shared; k < runB.length; k++) {
+      out.push({
+        a: null,
+        b: runB[k]
+      });
+    }
+    runA = [];
+    runB = [];
+  };
+  while (i < n && j < m) {
+    if (keyA[i] === keyB[j]) {
+      flushRuns();
+      out.push({
+        a: childrenA[i],
+        b: childrenB[j]
+      });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      runA.push(childrenA[i]);
+      i++;
+    } else {
+      runB.push(childrenB[j]);
+      j++;
+    }
+  }
+  while (i < n) {
+    runA.push(childrenA[i]);
+    i++;
+  }
+  while (j < m) {
+    runB.push(childrenB[j]);
+    j++;
+  }
+  flushRuns();
+  return out;
+};
+
+/**
+ * Container classification with the rigid-child escalation rules:
+ *  - list:         replace whole list if changed items / items ≥ node.ratio, else recurse
+ *                  into each changed listItem's content.
+ *  - table:        replace whole table if changed cells / cells ≥ node.ratio; else, for each
+ *                  changed ROW, replace the row if changed cells / row-cells ≥ node.ratio,
+ *                  else recurse into each changed cell's content.
+ *  - layout:       replace whole section if changed columns / columns ≥ node.ratio, else
+ *                  recurse into each changed column's content.
+ *  - generic (panel/expand/quote/...): replace whole block if changed children / children ≥
+ *                  node.ratio, else recurse into each changed child.
+ */
+const classifyContainer = (blockA, blockB, changes, originalDoc, newDoc, locale, thresholds) => {
+  const typeName = blockB.node.type.name;
+
+  // Tables need cell-level counting across rows; handle them specially.
+  if (typeName === TABLE_TYPE) {
+    return classifyTable(blockA, blockB, changes, originalDoc, newDoc, locale, thresholds);
+  }
+  const childrenB = childRefs(blockB);
+  const childrenA = childRefs(blockA);
+  const changed = changedChildIndices(blockB, childrenB, changes);
+  const denom = Math.max(childrenA.length, childrenB.length, 1);
+  if (changed.size / denom >= thresholds.node.ratio) {
+    return [wholeBlockChange(blockA, blockB, changes)];
+  }
+
+  // Below threshold → recurse per child, using an LCS alignment so inserted/removed children
+  // do not mis-pair (which previously corrupted A-side coordinates and leaked one block's
+  // deletions into another). Each alignment entry is one of:
+  //   - matched (a & b): recurse to classify any intra-child changes (skipped if identical);
+  //   - added (b only):  a pure insertion, with a zero-width A anchor near its position;
+  //   - removed (a only): a pure deletion, with a zero-width B anchor near its position.
+  const alignment = alignChildren(childrenA, childrenB);
+  const out = [];
+  // Running A/B anchors from the last matched pair, so pure insert/delete get sensible
+  // zero-width coordinates on the opposite side.
+  let lastMatchedAEnd = blockA.from + 1;
+  let lastMatchedBEnd = blockB.from + 1;
+  for (const {
+    a,
+    b
+  } of alignment) {
+    if (a && b) {
+      lastMatchedAEnd = a.to;
+      lastMatchedBEnd = b.to;
+      // Identical content is left as-is by the LCS; if a change still overlaps this pair
+      // (e.g. marks), recurse to classify it.
+      const childChanges = changes.filter(c => rangesOverlap(c.fromB, Math.max(c.toB, c.fromB + 1), b.from, b.to));
+      if (childChanges.length === 0) {
+        continue;
+      }
+      out.push(...classifyChild(a, b, childChanges, originalDoc, newDoc, locale, thresholds));
+      continue;
+    }
+    if (b && !a) {
+      // Added child: pure insertion. Anchor the (empty) A side at the last matched A end.
+      out.push(makePromotedChange(lastMatchedAEnd, lastMatchedAEnd, b.from, b.to, 'node'));
+      lastMatchedBEnd = b.to;
+      continue;
+    }
+    if (a && !b) {
+      // Removed child: pure deletion. Anchor the (empty) B side at the last matched B end.
+      out.push(makePromotedChange(a.from, a.to, lastMatchedBEnd, lastMatchedBEnd, 'node'));
+      lastMatchedAEnd = a.to;
+    }
+  }
+  return out;
+};
+
+/**
+ * Classify a table: replace the whole table when changed-cells/total-cells ≥ node.ratio;
+ * otherwise for each changed row, replace the row when its own changed-cells/row-cells ≥
+ * node.ratio, else recurse into each changed cell.
+ */
+const classifyTable = (blockA, blockB, changes, originalDoc, newDoc, locale, thresholds) => {
+  const rowsB = childRefs(blockB);
+  const rowsA = childRefs(blockA);
+
+  // Total cell counts across the whole table.
+  let totalCellsB = 0;
+  let changedCellsB = 0;
+  const perRowChangedCells = new Map();
+  for (const row of rowsB) {
+    const cells = childRefs(row);
+    totalCellsB += cells.length;
+    const changedCells = changedChildIndices(row, cells, changes);
+    if (changedCells.size > 0) {
+      perRowChangedCells.set(row.index, changedCells);
+      changedCellsB += changedCells.size;
+    }
+  }
+  let totalCellsA = 0;
+  for (const row of rowsA) {
+    totalCellsA += row.node.childCount;
+  }
+  const cellDenom = Math.max(totalCellsA, totalCellsB, 1);
+
+  // Whole-table replacement.
+  if (changedCellsB / cellDenom >= thresholds.node.ratio) {
+    return [wholeBlockChange(blockA, blockB, changes)];
+  }
+  const out = [];
+  // LCS-align rows (mirrors classifyContainer) so an inserted/deleted row does not mis-pair
+  // every subsequent row by index (which would corrupt the row-level A coordinates).
+  const rowAlignment = alignChildren(rowsA, rowsB);
+  let lastMatchedRowAEnd = blockA.from + 1;
+  let lastMatchedRowBEnd = blockB.from + 1;
+  for (const {
+    a: rowA,
+    b: rowB
+  } of rowAlignment) {
+    // Added row: pure insertion (only if it actually carries changes).
+    if (rowB && !rowA) {
+      var _perRowChangedCells$g, _perRowChangedCells$g2;
+      if (((_perRowChangedCells$g = (_perRowChangedCells$g2 = perRowChangedCells.get(rowB.index)) === null || _perRowChangedCells$g2 === void 0 ? void 0 : _perRowChangedCells$g2.size) !== null && _perRowChangedCells$g !== void 0 ? _perRowChangedCells$g : 0) > 0) {
+        out.push(makePromotedChange(lastMatchedRowAEnd, lastMatchedRowAEnd, rowB.from, rowB.to, 'node'));
+      }
+      lastMatchedRowBEnd = rowB.to;
+      continue;
+    }
+    // Removed row: pure deletion.
+    if (rowA && !rowB) {
+      out.push(makePromotedChange(rowA.from, rowA.to, lastMatchedRowBEnd, lastMatchedRowBEnd, 'node'));
+      lastMatchedRowAEnd = rowA.to;
+      continue;
+    }
+    if (!rowA || !rowB) {
+      continue;
+    }
+    lastMatchedRowAEnd = rowA.to;
+    lastMatchedRowBEnd = rowB.to;
+    const changedCells = perRowChangedCells.get(rowB.index);
+    if (!changedCells || changedCells.size === 0) {
+      continue;
+    }
+    const cellsB = childRefs(rowB);
+    // Row-level replacement.
+    if (changedCells.size / Math.max(rowA.node.childCount, cellsB.length, 1) >= thresholds.node.ratio) {
+      out.push(makePromotedChange(rowA.from, rowA.to, rowB.from, rowB.to, 'node'));
+      continue;
+    }
+    // Else recurse into each changed cell's content (cell is never replaced alone). Cells are
+    // positionally aligned within a matched row (table columns are fixed, so a cell at index i
+    // on the B side corresponds to index i on the A side).
+    const cellsA = childRefs(rowA);
+    for (const cellB of cellsB) {
+      var _cellsA$cellB$index;
+      if (!changedCells.has(cellB.index)) {
+        continue;
+      }
+      const cellA = (_cellsA$cellB$index = cellsA[cellB.index]) !== null && _cellsA$cellB$index !== void 0 ? _cellsA$cellB$index : null;
+      const cellChanges = changes.filter(c => rangesOverlap(c.fromB, Math.max(c.toB, c.fromB + 1), cellB.from, cellB.to));
+      out.push(...classifyChild(cellA, cellB, cellChanges, originalDoc, newDoc, locale, thresholds));
+    }
+  }
+  return out;
+};
+
+/**
+ * Recurse into a rigid/structural child (listItem, layoutColumn, tableCell/tableHeader) or a
+ * plain child block. Rigid children are containers of blocks: we recurse into THEIR children
+ * (paragraphs, nested lists, …) so we never delete+replace the rigid child itself. A plain
+ * text-bearing or container child is classified directly.
+ */
+const classifyChild = (childA, childB, changes, originalDoc, newDoc, locale, thresholds) => {
+  if (changes.length === 0) {
+    return [];
+  }
+  const typeName = childB.node.type.name;
+  const asBlock = ref => ref ? {
+    node: ref.node,
+    from: ref.from,
+    to: ref.to
+  } : null;
+
+  // Structurally-rigid wrapper (layoutColumn / tableCell / tableHeader): the wrapper itself is
+  // NEVER a whole-block result — deleting+re-inserting a single column or cell would break the
+  // parent layout/table structure. We only reach here because the parent already decided NOT
+  // to promote wholesale, so we bypass `classifyContainer` (which could promote the whole
+  // wrapper when it is internally dense) and classify EACH of the wrapper's direct children on
+  // its own. This keeps the diff strictly inside the wrapper (inline / sentence / paragraph,
+  // or a nested container such as a list inside a table cell).
+  if (RIGID_CHILD_TYPES.has(typeName)) {
+    const blockB = asBlock(childB);
+    if (!blockB) {
+      return [];
+    }
+    const wrapperA = asBlock(childA);
+    const childrenB = childRefs(blockB);
+    const childrenA = wrapperA ? childRefs(wrapperA) : [];
+    const out = [];
+    // LCS-align inner children (mirrors classifyContainer) so a paragraph inserted/deleted
+    // inside the cell/column does not mis-pair every subsequent inner child by index. We never
+    // promote the wrapper itself here — we only classify each inner child.
+    const alignment = alignChildren(childrenA, childrenB);
+    let lastMatchedAEnd = wrapperA ? wrapperA.from + 1 : blockB.from + 1;
+    let lastMatchedBEnd = blockB.from + 1;
+    for (const {
+      a,
+      b
+    } of alignment) {
+      if (a && b) {
+        lastMatchedAEnd = a.to;
+        lastMatchedBEnd = b.to;
+        const innerChanges = changes.filter(c => rangesOverlap(c.fromB, Math.max(c.toB, c.fromB + 1), b.from, b.to));
+        if (innerChanges.length === 0) {
+          continue;
+        }
+        out.push(...classifyChild(a, b, innerChanges, originalDoc, newDoc, locale, thresholds));
+        continue;
+      }
+      if (b && !a) {
+        // Added inner child: pure insertion, zero-width A anchor at the last matched A end.
+        out.push(makePromotedChange(lastMatchedAEnd, lastMatchedAEnd, b.from, b.to, 'node'));
+        lastMatchedBEnd = b.to;
+        continue;
+      }
+      if (a && !b) {
+        // Removed inner child: pure deletion, zero-width B anchor at the last matched B end.
+        out.push(makePromotedChange(a.from, a.to, lastMatchedBEnd, lastMatchedBEnd, 'node'));
+        lastMatchedAEnd = a.to;
+      }
+    }
+    return out;
+  }
+
+  // A `listItem` CAN be replaced wholesale (delete + re-insert at the same position does not
+  // break the list's structure), so per the spec it uses the normal container rule: promote
+  // the whole item when its own content is dense enough, else recurse into its children.
+  if (typeName === 'listItem') {
+    const blockB = asBlock(childB);
+    const blockAItem = asBlock(childA);
+    // Pure deletion of the item: emit the whole A-side item as deleted (zero-width B anchor at
+    // the item's own B-less position — anchored at the A start for lack of parent context).
+    if (!blockB) {
+      return blockAItem ? [makePromotedChange(blockAItem.from, blockAItem.to, blockAItem.from, blockAItem.from, 'node')] : [];
+    }
+    // Pure insertion of the item: emit the whole B-side item as inserted with a ZERO-WIDTH A
+    // anchor. (Using `blockB` as the A side would make the LCS compare the item against itself
+    // and drop the insertion.)
+    if (!blockAItem) {
+      return [makePromotedChange(blockB.from, blockB.from, blockB.from, blockB.to, 'node')];
+    }
+    return classifyContainer(blockAItem, blockB, changes, originalDoc, newDoc, locale, thresholds);
+  }
+
+  // Plain child block: classify as its own group (text or nested container).
+  return classifyBlockGroup({
+    blockA: asBlock(childA),
+    blockB: asBlock(childB),
+    changes
+  }, originalDoc, newDoc, locale, thresholds);
+};