Post Revisions: Upgrade diff from v4 to v8

[manzoorwanijk]

What?

Closes #77976

Upgrades the diff library from ^4.0.2 to ^8.0.3 in packages/editor and packages/block-editor, and updates the post-revisions consumer code so the four-major bump is invisible to users — the in-editor revisions UI keeps the same block pairing and inline word-level diff output it produced under v4.

Why?

The diff library was declared at ^4.0.2 in editor / block-editor and ^8.0.3 in sync, blocking the cross-workspace Syncpack alignment work (#77950, #77954). Bumping editor to ^8.0.3 is a four-major jump that, on its own, breaks four unit tests in block-diff.js and surfaces real UX regressions in the post-revisions feature. The failures fall into two unrelated upstream behaviour changes:

1. LCS tie-breaker change (v6+). v6 added a "prefer deletions before insertions" tie-breaker, which selects a different LCS for inputs where multiple equal-length matches exist. The relevant case here is prev=[paragraph, whitespace, paragraph] versus curr=[paragraph_modified, whitespace, paragraph]: v8 picks the whitespace pseudo-block as the LCS anchor, so pairSimilarBlocks then sees two removed and two added paragraphs and similarity-matches dissimilar pairs — producing two confusing inline diffs instead of a clean modified+unchanged pair.
2. diffWords semantics change (v6+). v6 stopped treating whitespace as a token, so adjacent word changes coalesce into one removed/added pair. Inline rich-text diffs lose precision: Visit <a><del>our</del><ins>the</ins> <del>site</del><ins>website</ins></a> today (per-word) becomes Visit <a><del>our site</del><ins>the website</ins></a> today (one coarser diff).

Both are real user-visible regressions, not snapshot drift.

How?

1. Bump the dependency

• packages/editor/package.json and packages/block-editor/package.json: diff → ^8.0.3. (packages/sync was already on v8.)

2. Filter whitespace pseudo-blocks before LCS

packages/editor/src/components/post-revisions-preview/block-diff.js — diffRawBlocks now strips freeform/whitespace pseudo-blocks (the \n\n between block markers) from both arrays before passing them to diffArrays. With those out of the picture, v8's tie-breaker selects the same content-block LCS anchor v4 did for every previously-failing case. Whitespace pseudo-blocks aren't rendered (parseRawBlock returns undefined for them), so dropping them before the diff has no user-visible effect.

pairSimilarBlocks's placement heuristic was extended to match: it previously decided where to anchor a paired modification by checking whether any added block sat between the removed and added positions. Now that whitespace pseudo-blocks are no longer in the result list, an unchanged content block between the two positions is the only "the modified block crosses current-revision content" signal — so the heuristic also fires on unchanged blocks (but still ignores removed blocks, which don't exist in the current revision and so don't count as crossing).

3. Switch rich-text and field diffs to diffWordsWithSpace

• block-diff.js: applyRichTextDiff and applyDiffToBlock (sidebar changedAttributes) now call diffWordsWithSpace from the top-level diff import. v8's diffWordsWithSpace keeps whitespace as its own token, matching v4's diffWords semantics.
• revision-fields-diff/index.js: meta field diffs likewise use diffWordsWithSpace.

4. Migrate remaining diff imports to top-level

preserve-client-ids.js and block-compare/index.js used deep paths like 'diff/lib/diff/array'. v8's package.json exports map only wildcards ./lib/*.js (with extension); the bare-folder ./lib/ mapping requires a trailing slash. The deep paths only resolve here because the bundler/Jest resolver fills in .js — a future tooling change could break them. v8 also declares sideEffects: false in its per-output sub-manifests (libcjs/package.json and libesm/package.json), which webpack 4+ honours, so the historical tree-shaking reason for the deep imports no longer applies. The "diff doesn't tree-shake correctly" comment in block-compare/index.js was true for v4 but is now stale and gets removed.

5. Relax one test assertion

The 'handles two blocks that swapped positions' test was asserting which block stayed unmarked vs. which became removed/added. For a pure swap, both LCS choices are equally valid — both v4 and v8 produce semantically-correct output, they just disagree on which block reads as "unchanged." The test now asserts the user-facing invariant (one unmarked + one removed/added pair with same content) instead of the implementation choice.

6. CHANGELOG entries

Added ### Internal entries to packages/editor/CHANGELOG.md and packages/block-editor/CHANGELOG.md recording the major dependency bump.

Testing Instructions

Automated:

npm run test:unit -- -- packages/editor/src/components/post-revisions-preview/ \
                       packages/editor/src/components/revision-fields-diff/ \
                       packages/editor/src/components/revision-diff-panel/ \
                       packages/block-editor/src/components/block-compare/

Expected: 42/42 pass. Full npm run test:unit is also green (32538/32545, 7 unrelated skips).

Manual (golden path for the revisions UI):

1. Start wp-env (npm run wp-env start) and create a post with several paragraphs.
2. Edit and save the post a few times to build up a revision history. Mix the kinds of changes:
   • Add a couple of new paragraphs above an existing one and slightly tweak its wording.
   • Swap two paragraphs.
   • Inside a paragraph, change one word inside a link (e.g. our site → the website).
   • Add <strong> / <em> formatting to part of a paragraph.
3. Open the post's revisions preview (Document → Revisions → click a prior revision).
4. Verify the following render the same as on trunk before the bump:
   • The slightly-tweaked paragraph shows as a single modified block with a clean inline <del>…</del><ins>…</ins> diff, not two confusing pair-ups.
   • For a pure swap, exactly one block stays unmarked and the other shows as a removed+added pair with the same content (which side gets matched is implementation-defined — see below).
   • Inside-link word changes show per-word (our → the and site → website as two separate diffs), not coalesced into one.
   • Format-only changes (added bold, changed link URL) render as revision-diff-format-* spans on just the affected range.
5. Open the Meta panel in the document sidebar during revision mode (if any meta keys differ) and confirm word-level diffs there are also per-word.

Testing Instructions for Keyboard

No UI changes; existing keyboard navigation through the revisions panel is unaffected.

Screenshots or screencast

Before (v8 with no consumer fix)	After (this PR)
<del>First</del><ins>Second</ins> block content <ins>modified</ins> + a second confusing inline diff for the unchanged sibling	Single modified block with Second block content<ins> modified</ins>; the unchanged sibling stays unmarked
Visit <a><del>our site</del><ins>the website</ins></a> today (one coarse diff)	Visit <a><del>our</del><ins>the</ins> <del>site</del><ins>website</ins></a> today (per-word)

Use of AI Tools

This PR was authored with the assistance of Claude Code (Opus 4.7). All edits, the test results, and the manual testing steps were reviewed and verified by me.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: ellatrix <ellatrix@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: +1.35 kB (+0.02%)

Total Size: 8.44 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	380 kB	+106 B (+0.03%)
build/scripts/editor/index.min.js	466 kB	+1.24 kB (+0.27%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in b87a45c.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27007177068
📝 Reported issues:

• [Flaky Test] inserts a block should show a blue line indicator #41477 in /test/e2e/specs/editor/various/inserting-blocks.spec.js

[ciampo]

This feels like something that @ellatrix should take a look at — I don't personally have much context to understand the full implications of changing / keeping the previous diff behavior.

In the meantime, I'm sharing some notes from an initial round of AI-assisted review

PR Review: #77992 — Post Revisions: Upgrade diff from v4 to v8

Summary

Bumps diff from ^4.0.2 to ^8.0.3 in packages/editor and packages/block-editor to align with packages/sync. Two unrelated upstream behaviour changes (LCS tie-breaker in v6, diffWords whitespace tokenization in v6) would regress the post-revisions UI; the PR addresses both: switches the per-word diffs to diffWordsWithSpace, and inlines a v4-compatible port of diffArrays (~150 LoC) to keep the LCS pivot stable for block-level matching.

The motivation (Syncpack alignment), the diagnosis (the two v6 changes), and the choice of diffWordsWithSpace as the v4-compatible word-diff replacement all check out against the upstream release notes. The main concern is the cost of vendoring the LCS algorithm vs. cheaper alternatives (subclassing v8's Diff class, or making the consumer logic LCS-pivot-insensitive). A few sibling consumers also weren't updated for consistency.

Findings Overview

1. [major] Vendored ~150 LoC of upstream algorithm — consider subclassing v8's Diff class instead (packages/editor/src/components/post-revisions-preview/block-diff.js:48-193)
2. [major] preserve-client-ids.js still uses a deep import that's risky under v8 (packages/editor/src/components/post-revisions-preview/preserve-client-ids.js:4)
3. [major] Missing CHANGELOG entries for editor and block-editor (packages/editor/CHANGELOG.md:3, packages/block-editor/CHANGELOG.md:3)
4. [minor] Stale tree-shaking comment in block-compare not migrated (packages/block-editor/src/components/block-compare/index.js:5-7)
5. [minor] Local diffArrays shadows the upstream name — rename for clarity (packages/editor/src/components/post-revisions-preview/block-diff.js:48)
6. [minor] JSDoc on local diffArrays overstates what the algorithm does (packages/editor/src/components/post-revisions-preview/block-diff.js:30-43)
7. [minor] "Pure swap" test asserts an arbitrary LCS pivot rather than user-facing invariant (packages/editor/src/components/post-revisions-preview/test/block-diff.js:327-369)
8. [minor] Helper diffArrays doubles the file's size; consider extracting to a sibling module (packages/editor/src/components/post-revisions-preview/block-diff.js:48-193)
9. [nit] extractCommon( basePath, diagonalPath ) — diagonalPath is a number, not a path object (packages/editor/src/components/post-revisions-preview/block-diff.js:66)
10. [nit] Inconsistent placement of the diffWordsWithSpace rationale comment (packages/editor/src/components/post-revisions-preview/block-diff.js:669-677 vs packages/editor/src/components/revision-fields-diff/index.js:4-9)

---

1. [major] Consider subclassing v8's Diff class instead of vendoring the algorithm

packages/editor/src/components/post-revisions-preview/block-diff.js:48-193

Inlining ~150 LoC of upstream LCS code is a real maintenance cost: it is now WordPress's responsibility forever, even though the only behaviour we actually want from it is the v4 tie-breaker. v8 explicitly documents class CustomDiff extends Diff as the supported customization API:

The Diff object is now a class. Custom extensions of Diff, as described in the "Defining custom diffing behaviors" section of the README, can therefore now be done by writing a class CustomDiff extends Diff and overriding methods.

A subclass that re-uses v8's algorithm and only overrides the tie-breaker (and keeps v4's (added, removed) → (removed, added) post-swap, if still desired) should be ~20–30 LoC instead of ~150, and it inherits all future fixes and performance improvements upstream automatically.

It's also worth questioning whether we need v4-pivot fidelity at all. For both motivating cases:

• Whitespace pivot ('pairs paragraphs in order when section is condensed'): the failure is real (confusing dual inline diffs). But pairSimilarBlocks is the thing that gets confused — it could likely be made LCS-pivot-insensitive (e.g. by allowing a removed/added pair in either order to feed back into the similarity matcher). That structural fix would survive any future diff change.
• Pure swap (prev=[First, Second] / curr=[Second, First]): which block reads as "unchanged" vs "moved" is purely cosmetic — both v4 and v8 give equally-valid output here. This alone wouldn't justify vendoring an algorithm.

I'd suggest one of:

• Subclass Diff and only override the tie-breaker (keep this PR's scope, much smaller surface), or
• Make pairSimilarBlocks insensitive to LCS pivot choice (longer-term, no inlined algorithm needed).

Either feels preferable to maintaining a v4 reimplementation indefinitely. Happy to be convinced otherwise if you've already considered them — the PR description hints at the structural-fix option but doesn't say why it was ruled out.

---

2. [major] preserve-client-ids.js deep import is risky under diff v8

packages/editor/src/components/post-revisions-preview/preserve-client-ids.js:4

import { diffArrays } from 'diff/lib/diff/array';

Two concerns:

1. No .js extension. v8's package.json exports only wildcards ./lib/*.js (with extension); the bare-folder ./lib/ mapping requires a trailing slash on the consumer side. A path like 'diff/lib/diff/array' (no extension) only resolves because the bundler/Jest resolver fills in .js. This worked under v4 because v4 had no exports field. v8's stricter exports map makes this fragile — a future tooling change (or stricter ESM resolver) could break it.
2. sideEffects: false in v8. The historical reason for the deep import was tree-shaking; v8 marks the package sideEffects: false, so a top-level import { diffArrays } from 'diff' is now equivalent.

Suggest migrating to:

import { diffArrays } from 'diff';

The PR description says "its tests pass under v8 unmodified" — but the tests probably don't exercise the v6 LCS tie-breaker change (block-name signatures rarely produce equally-valid LCSes), so passing tests don't prove behaviour parity. Worth either (a) adding a test that does, or (b) explicitly noting in the file why this consumer is OK with v6 tie-breaker semantics.

---

3. [major] No CHANGELOG entries

packages/editor/CHANGELOG.md:3, packages/block-editor/CHANGELOG.md:3

Both packages get a major dependency bump but neither has an ## Unreleased > Internal entry. Even though the user-visible behaviour is unchanged by design, a major dep bump (and the inlining of a third-party algorithm port) is exactly the kind of thing that should be discoverable in the CHANGELOG when investigating future regressions.

Suggested entries:

Suggested CHANGELOG entries

### Internal

-   Updated `diff` dependency from `^4.0.2` to `^8.0.3`. ([#77992](https://github.com/WordPress/gutenberg/pull/77992))

(Same entry in packages/block-editor/CHANGELOG.md.)

---

4. [minor] Stale tree-shaking comment in block-compare; consider migrating its import too

packages/block-editor/src/components/block-compare/index.js:5-7

// diff doesn't tree-shake correctly, so we import from the individual
// module here, to avoid including too much of the library
import { diffChars } from 'diff/lib/diff/character';

This comment was true for v4 (no sideEffects declaration). It's no longer true for v8 (sideEffects: false, see release notes 8.0.2). Now that block-editor is also on v8, this is a good moment to:

• Migrate the import to top-level (import { diffChars } from 'diff'), and
• Remove the stale comment.

Same reasoning as #2. Keeping it within scope here makes the diff tooling consistent across the three consumers in the package.

---

5. [minor] Local diffArrays shadows the upstream name

packages/editor/src/components/post-revisions-preview/block-diff.js:48

function diffArrays( oldArr, newArr ) {

If a future contributor re-adds import { diffArrays } from 'diff' (e.g. for an unrelated diff in the same file), the import will silently shadow / collide with the local helper. Renaming the local one makes the v4-compatibility intent explicit and avoids the collision risk:

Suggested rename

function diffArraysV4Compatible( oldArr, newArr ) {
  // ...
}

---

6. [minor] JSDoc on diffArrays overstates what the algorithm does

packages/editor/src/components/post-revisions-preview/block-diff.js:30-43

/**
 * Compute an LCS-based array diff with the same tie-breaker semantics as
 * `diff` v4's `diffArrays`. The post-revisions UI relies on a specific LCS
 * choice when multiple equally-valid matches exist (e.g. preferring the
 * earlier occurrence in the previous revision over later ones, and
 * preferring content blocks over freeform/whitespace blocks). `diff` v6
 * changed the tie-breaker to "deletions before insertions", which produces
 * a different but equally-valid pairing — visible as confusing inline diffs
 * in the post-revisions feature. We reproduce v4's selection locally so
 * block-level matching stays stable across upgrades of the `diff` library.
 ...
 */

"Preferring content blocks over freeform/whitespace blocks" isn't something this function does — it's a downstream consequence of the LCS tie-breaker interacting with how pairSimilarBlocks then groups results. Stating it as a property of diffArrays is misleading; the function only tie-breaks on newPos. Suggest reworking to focus on the algorithmic invariant ("when multiple equal-length LCSes exist, prefer the one that advances newPos further") and leaving the downstream consequences in the comment on the consumer (pairSimilarBlocks).

---

7. [minor] "Pure swap" test asserts an arbitrary LCS pivot

packages/editor/src/components/post-revisions-preview/test/block-diff.js:327-369

The 'handles two blocks that swapped positions' test asserts the exact order [Second:added, First:unchanged, Second:removed] — meaning "First" stays put, "Second" moves. The opposite outcome ([Second:unchanged, ...]) would be equally valid LCS output. Asserting one over the other ties the test to the implementation choice rather than to user-facing value.

A more robust assertion would test the invariant — e.g. exactly one block is unmarked, the other is shown as removed+added with consistent content — without prescribing which one. That way the test would also pass on diff v8 directly (without the local diffArrays), letting the suite tell us which behaviour changes are user-visible vs. just LCS pivot drift.

Less critical than the items above, but worth considering since this test is one of the listed motivations for vendoring diffArrays.

---

8. [minor] Helper doubles the file's size; consider extracting

packages/editor/src/components/post-revisions-preview/block-diff.js:48-193

The local diffArrays adds ~150 LoC at the top of block-diff.js, which now mixes two unrelated concerns: (a) the LCS algorithm port and (b) the post-revisions diff orchestration. Extracting diffArrays to a sibling module (e.g. diff-arrays-v4.js) would:

• Keep block-diff.js focused on revision-specific logic.
• Make the algorithm port easier to delete in one shot if/when the consumer logic becomes pivot-insensitive (per TinyMCE formatting improvements #1).

Lower priority if you take #1 — subclassing would shrink it enough that extraction is unnecessary.

---

9. [nit] extractCommon( basePath, diagonalPath ) — parameter is a number

packages/editor/src/components/post-revisions-preview/block-diff.js:66

const extractCommon = ( basePath, diagonalPath ) => {

diagonalPath is the diagonal index (a number), not a path object — and the outer loop calls it diag. Renaming the parameter to diag for consistency would avoid the suggestion that it's another basePath-shaped value.

---

10. [nit] Inconsistent placement of the diffWordsWithSpace rationale comment

In block-diff.js, the rationale lives at the call site (inside applyRichTextDiff):

	/*
	 * Diff the plain text (words for cleaner output).
	 *
	 * `diffWordsWithSpace` keeps whitespace as its own token, the same
	 * behaviour `diffWords` had in `diff` v4. v6+ stopped treating
	 * whitespace as a token, which would otherwise coalesce adjacent word
	 * changes into one removed/added pair instead of reporting them
	 * separately — making the inline rich-text diff less precise.
	 */

But in revision-fields-diff/index.js, the same rationale lives at the import site:

/*
 * `diffWordsWithSpace` preserves the v4-style per-word output. v6+
 * stopped treating whitespace as a token in `diffWords`, which coalesces
 * adjacent word changes into a single removed/added pair.
 */

Minor inconsistency — pick one and apply uniformly. Since block-diff.js uses diffWordsWithSpace in two distinct call sites (applyRichTextDiff and applyDiffToBlock), the import-site comment is probably the cleaner pattern for both files.

[Copilot]

Pull request overview

This PR upgrades the diff dependency used by the editor’s revisions/compare features from v4 to v8, and updates the revisions diffing logic to preserve the same user-facing pairing and word-level inline diff behavior despite upstream behavioral changes in diff.

Changes:

• Upgrade diff to ^8.0.3 in @wordpress/editor and @wordpress/block-editor, and migrate remaining imports to the top-level diff entrypoint.
• Stabilize block pairing under diffArrays by filtering whitespace-only freeform pseudo-blocks before LCS matching, and adjust the placement heuristic in pairSimilarBlocks.
• Restore per-word inline diffs by switching from diffWords to diffWordsWithSpace for rich-text, sidebar changed-attribute diffs, and meta-field diffs; relax one swap test assertion to assert the UX invariant rather than a specific LCS tie-break.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/editor/src/components/revision-fields-diff/index.js	Switch meta diffs to diffWordsWithSpace via top-level diff import to preserve per-word output.
packages/editor/src/components/post-revisions-preview/test/block-diff.js	Update swap test to assert invariant output instead of a specific unchanged-anchor choice.
packages/editor/src/components/post-revisions-preview/preserve-client-ids.js	Migrate diffArrays import to top-level diff.
packages/editor/src/components/post-revisions-preview/block-diff.js	Filter whitespace pseudo-blocks pre-LCS; adjust pairing placement heuristic; use diffWordsWithSpace for inline and attribute diffs.
packages/editor/package.json	Bump diff dependency to ^8.0.3.
packages/editor/CHANGELOG.md	Record the diff major-version bump under Internal changes.
packages/block-editor/src/components/block-compare/index.js	Migrate diffChars import to top-level diff and remove now-stale tree-shaking comment.
packages/block-editor/package.json	Bump diff dependency to ^8.0.3.
packages/block-editor/CHANGELOG.md	Record the diff major-version bump under Internal changes.
package-lock.json	Lockfile updates reflecting diff v8 installs for the updated workspaces.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ciampo]

@manzoorwanijk FWIW, sharing another round of AI-assisted review.

Click to expand

PR Review: #77992 — Post Revisions: Upgrade diff from v4 to v8 (round 2)

Summary

This round reviews the PR after the previous round of feedback was applied. The author replaced the ~150 LoC vendored LCS port with a much smaller, sturdier fix: filter whitespace pseudo-blocks out of the input arrays before LCS, and update pairSimilarBlocks's placement heuristic so the unchanged-content case is detected without relying on a specific diffArrays tie-breaker. All four "major" items from the prior round are addressed: deep-path imports are migrated to top-level (block-compare, preserve-client-ids, block-diff), CHANGELOG entries are present in both packages, and the stale tree-shaking comment is gone.

The new approach is sound and substantially less risky than vendoring. Remaining feedback is small and mostly clarifying.

Findings Overview

1. [Possible issue] Asymmetric pairSimilarBlocks lookahead: 'modified' status is not treated as crossing current-revision content (packages/editor/src/components/post-revisions-preview/block-diff.js:271-282)
2. [minor] No focused unit test for the whitespace-pseudo-block filter (packages/editor/src/components/post-revisions-preview/test/block-diff.js)
3. [minor] isWhitespaceRawBlock only runs at the top of each diffRawBlocks invocation — consider asserting the invariant in the recursive call (packages/editor/src/components/post-revisions-preview/block-diff.js:322-330)
4. [minor] Tree-shaking comment removed but tree-shaking guarantee is more nuanced than the PR description suggests (packages/block-editor/src/components/block-compare/index.js:5)
5. [nit] Rationale comment placement is now inconsistent again (packages/editor/src/components/post-revisions-preview/block-diff.js:4-10 vs packages/editor/src/components/revision-fields-diff/index.js:4-9)
6. [nit] crossesCurrentContent comment is slightly out of sync with the code (packages/editor/src/components/post-revisions-preview/block-diff.js:260-268)

---

1. [Possible issue] Asymmetric lookahead in pairSimilarBlocks ignores already-paired modifications

packages/editor/src/components/post-revisions-preview/block-diff.js:271-282

The new heuristic treats unchanged blocks (status === undefined) and unpaired added blocks as "crossing current-revision content," but ignores 'modified' blocks. In the loop, modifications produced by earlier iterations of the outer for ( const rem of removed ) are stored only in the modifications Map — blocks[ i ].__revisionDiffStatus.status for those indices still reads as 'added' or 'removed', so this works out for the current iteration. But once crossesCurrentContent is decided based on 'added' && ! pairedAdded.has( i ), an added block that has already been "absorbed" into a pairing at the removed position (i.e. is in pairedAdded) is treated as not crossing — which is what we want. However, the symmetric case (a removed block at the added position, i.e. in pairedRemoved) isn't checked at all, because the loop never breaks on 'removed'.

In practice the existing tests all pass, so this may be intentional (removed blocks don't exist in the current revision and so don't actually "cross" current-revision content). But the asymmetry is worth a one-line confirmation in the comment, e.g.:

// 'removed' blocks (and pairedRemoved blocks placed at an added
// position) are not in the current revision and so don't count as
// crossing it. 'added' blocks that have already been absorbed into a
// modification at a removed position (pairedAdded) similarly don't.

If you're confident the current behaviour is correct, ignore — just flagging because the semantic distinction "current-revision content" vs. "anything in the result list" is what the heuristic now hinges on, and the code reads as if it might be inadvertently asymmetric.

---

2. [minor] Add a focused test for whitespace-pseudo-block filtering

packages/editor/src/components/post-revisions-preview/test/block-diff.js

The whitespace-filter behaviour is the primary mechanism for keeping LCS output stable across diff major versions, but it's only exercised transitively via the 'pairs paragraphs in order when section is condensed' test (which doesn't fail on a regression of the filter; it would fail downstream in pairSimilarBlocks). A direct test would lock the contract:

Suggested test

it( 'ignores whitespace-only freeform pseudo-blocks between block markers', () => {
  // Two paragraphs separated by raw whitespace at the document level
  // (the grammar parser emits these as { blockName: null, innerHTML: '\n\n' }).
  // Swapping their order shouldn't latch onto the whitespace pseudo-block
  // as the LCS anchor.
  const previous =
    '<!-- wp:paragraph --><p>First</p><!-- /wp:paragraph -->\n\n' +
    '<!-- wp:paragraph --><p>Second</p><!-- /wp:paragraph -->';
  const current =
    '<!-- wp:paragraph --><p>Second</p><!-- /wp:paragraph -->\n\n' +
    '<!-- wp:paragraph --><p>First</p><!-- /wp:paragraph -->';
  const blocks = diffRevisionContent( current, previous );
  // … assert one unchanged + one removed/added pair (the swap invariant)
} );

That way, if a future diff upgrade or refactor breaks the filter (e.g. blockName === null semantics change), this test is the canary, instead of an unrelated paragraph-condensing test failing in a confusing way.

---

3. [minor] Defensive: assert the filter holds inside recursion

packages/editor/src/components/post-revisions-preview/block-diff.js:322-330

function diffRawBlocks( currentRaw, previousRaw ) {
  // Strip whitespace-only freeform pseudo-blocks before LCS — see
  // `isWhitespaceRawBlock` for why.
  const currentBlocks = currentRaw.filter(
    ( b ) => ! isWhitespaceRawBlock( b )
  );
  const previousBlocks = previousRaw.filter(
    ( b ) => ! isWhitespaceRawBlock( b )
  );

The filter now runs at the top of every recursive call, which is correct but does redundant work for inner recursive calls (their innerBlocks were already filtered when the parent was diffed and stored). Harmless, just worth either:

• Documenting in the JSDoc that the filter is intentionally re-applied at every level (so the function is safe to call directly with raw grammar output, which is its public contract), or
• Pulling the filter out so it only runs at the top-level entry (diffRevisionContent) and asserting the invariant inside diffRawBlocks.

The first option is probably the right one — it keeps the function self-contained and the duplicate work is negligible.

---

4. [minor] block-compare tree-shaking comment removal — verify the assumption

packages/block-editor/src/components/block-compare/index.js:5

The PR description says "v8 also marks the package sideEffects: false", which made the deep diff/lib/diff/character import unnecessary. That's almost accurate — v8's top-level package.json doesn't have sideEffects: false; the flag lives in the per-output sub-manifests at libcjs/package.json and libesm/package.json that kpdecker/jsdiff writes during its build. Webpack 4+ honors nested sideEffects declarations, so tree-shaking should still work, but it's not exactly the property the PR description implies.

The size-change report on this PR (+866 B total, +784 B in editor, +82 B in block-editor) is consistent with tree-shaking working correctly — the editor bump is the new pairSimilarBlocks heuristic plus the LCS work, not unused diff code. So this is mostly cosmetic / for the description, not the code.

---

5. [nit] Rationale comment placement inconsistent across files

packages/editor/src/components/post-revisions-preview/block-diff.js:4-10 vs. packages/editor/src/components/revision-fields-diff/index.js:4-9

The two files now use slightly different framings:

/*
 * `diffWordsWithSpace` keeps whitespace as its own token, matching the
 * behaviour `diffWords` had in `diff` v4. v6+ stopped treating whitespace
 * as a token, which would otherwise coalesce adjacent word changes into a
 * single removed/added pair instead of reporting them per-word.
 */
import { diffArrays, diffWordsWithSpace } from 'diff';

/*
 * `diffWordsWithSpace` preserves the v4-style per-word output. v6+
 * stopped treating whitespace as a token in `diffWords`, which coalesces
 * adjacent word changes into a single removed/added pair.
 */
import { diffWordsWithSpace } from 'diff';

These are saying the same thing in two different ways; using identical wording (or extracting to a shared comment block) makes future grep-ability easier. Take or leave.

---

6. [nit] crossesCurrentContent comment slightly out of sync with code

packages/editor/src/components/post-revisions-preview/block-diff.js:260-268

// Decide where to place the modified block by checking
// what's between the removed and added positions.
// If anything between them is part of the current revision
// (an unpaired added block, or an unchanged block),
// placing at the removed position would put the modified
// block before content that comes before it in the
// current revision — so use the added position.
// Otherwise, use the removed position to keep the
// previous revision's order intact.

The comment says "if anything between them is part of the current revision," but the code only checks two specific cases (unchanged via status === undefined, and unpaired added). Modifications previously produced by this same loop iteration aren't checked — which is fine in practice (see #1) but the comment overstates the generality. Suggest narrowing the wording, e.g.:

// If any block between the two positions is in the current
// revision (an unchanged block, or an unpaired added block),
// placing the modification at the removed position would put it
// before content that already comes before it in the current
// revision — so use the added position instead.

…and possibly add an inline note that "removed and pairedRemoved blocks aren't checked because they're not in the current revision."

Still, I think this PR should be reviewed by someone familiar with the WordPress/Gutenberg diffiing, too.

[manzoorwanijk]

@manzoorwanijk FWIW, sharing another round of AI-assisted review.

Thank you. I have addressed the feedback.

I think this PR should be reviewed by someone familiar with the WordPress/Gutenberg diffiing, too.

Yes, I agree. Let us see if @ellatrix finds some time to have a look at this.

[ciampo]

cc'ing @aduth on this PR too, since he was partially involved in some npm / package.json / syncpack conversations

[manzoorwanijk]

Just a gentle reminder that this PR has been a blocker for other dependency improvements via #77950.

[ciampo]

@manzoorwanijk I suggest you look for who would be better suited to review this PR and ping them directly

[manzoorwanijk]

@manzoorwanijk I suggest you look for who would be better suited to review this PR and ping them directly

From the history of this area of the code or its reviews, I can see @ellatrix, @Mamaduka, @ntsekouras, @t-hamano, @aduth

[aduth]

I'm happy to give my thumbs-up on the upgrade itself, but I don't personally feel confident enough to weigh in on the semantics of how diffs are reflected in post revisions, which feels like the more impactful change here.

[ellatrix]

Would love to also use matchObject for the other test that was added, makes sense otherwise.

[manzoorwanijk]

Would love to also use matchObject for the other test that was added

Done in 5d8bdec. Thanks