feat(versioning): experimental version diff fixes

[YousefED]

Stacked on #3173. This PR now also contains #3172, which is closed.

Summary

Two experimental fixes for how a version diff shows changes. Both are behind one option. The option changes only what a version diff shows. It does not change the stored document. Without the option, the diff is as before.

1. Implicit delete attribution: content that nobody deleted is not credited to a user. Example: Alice deletes a block while Bob types in it. Before, the diff showed Bob's text as "Deleted by: Alice".
2. Re-created blocks: a block that a type change or a move re-created shows once. Before, the diff showed the block twice (deleted and inserted), and credited all its content to the user who made the change.

Option

type VersionDiffFixes =
  | "implicitDeleteAttribution"
  | "implicitDeleteAttributionAndRecreatedBlocks";
collaboration: { experimental?: { versionDiffFixes?: VersionDiffFixes } }

Each value includes the fixes of the values before it. Thus, only combinations that work can be set. versionDiffFixesIncluded gives the fixes of each value.

Problem 1: implicit deletes

Alice deletes a block. At the same time, Bob adds text or blocks inside that block. Yjs then deletes Bob's content together with the block. Nobody deleted this content: it is an implicit delete. A move or a type change also deletes the original block, so the same problem occurs for these edits.

YHub already attributes deletions correctly: it attributes a deletion only to the content that the update itself deleted. The incorrect attribution came from our preview. We decoded snapshots with garbage collection on, so the preview read the children of the deleted block again from the baseline document, and rendered them under the "deleted by" mark of the block.

Changes

• snapshotCodec.ts: decode snapshots with gc: false. Nested deleted content keeps its own attribution: if Alice deleted it, it shows her name; if Yjs deleted it with its parent, it shows no name.
• snapshotPreview.ts, SnapshotDiffRenderer:
  • It hides content that was inserted and deleted between the two compared versions. The stock DiffRenderer hides this content only after garbage collection. Without this, gc: false shows "ghost" deletions.
  • Content that was deleted together with its block, with the same attribution, shows inside the deletion of the block. It does not get a second mark with the same tooltip. The comparison ignores times (deleteAt), because no mark shows them.
• snapshotPreview.ts, withoutLostMovers: a move (indent, drag, type change) deletes the block and inserts a copy with the same block id. When no copy is left, the diff shows only the deletion of the original block, which names the mover. But the mover did not delete the block: the copy was deleted with a concurrently deleted parent, or a different user deleted it later. Thus, the movers are removed from the deletion of the original block. Other users that deleted it keep the credit. When no user is left, the block shows without an author.

Problem 2: re-created blocks

In Yjs, the type of a node cannot change. Thus, a type change or a move re-creates the block: it stores a copy of the block (with the same block id) and deletes the original. The diff showed the original as deleted and the copy as inserted, and credited all the copied content to the user who made the change.

• A user changes a paragraph to a heading. The diff showed a deleted paragraph and an inserted heading, both credited to that user.
• A user indents a block. The diff showed the block twice: deleted at the old position and inserted at the new position.

Changes

When the diff is rendered, we pair each copy with its original (by block id). Then we show the pair once:

• Type change between two blocks with inline content: shown as a formatting change ("Formatting change" in the tooltip).
• Indent or outdent: shown as moved, at the new position only. An indent or outdent does not change the order of the blocks from top to bottom.
• Other moves: shown as moved at the new position, and struck through at the old position. Both show "Moved by: X".
• Copy in the same position (for example, because its children changed): shown as unchanged.

Copied content keeps its original authors, character by character. This also applies when you compare with the first version.

A block can be re-created more than once between two versions: for example, retyped and then indented, or moved twice. The copies then form a chain. Each copy is deleted by the update that inserts the next copy. We follow the chain back by the users and times of these updates. Thus:

• Text that a user typed into an intermediate copy keeps that user as its author.
• Content that was added to the original after the earlier version is credited to the user who added it.
• The final copy is paired with the block of the earlier version, not with an intermediate copy. When the earlier version has no such block and there are several candidates, we do not pair them.

We do not pair a copy with its original when the copy lost content (for example, a concurrent edit deleted text from the original). Then the diff shows a delete and an insert, as before. A type change between a text block and a block without inline content (for example, paragraph to image) is not paired.

Display:

• The text of a moved block has no insert mark, because it keeps its authors. Thus, Block.css gives the text element the highlight of inserted text. In a code block, the highlight uses the dark variant of inserted code. A moved block without inline content (image, file, table, divider) gets the card of a formatting change.
• The insert and delete marks have a moved attribute. The tooltip shows "Moved" for both.

Gallery

One choice for the option ("Default", "Implicit delete attribution", "+ re-created blocks"), kept in the URL. A note can apply only with or without a fix. The sidebar shows the severity without fixes, and in parentheses the severity with all fixes (green: no problem left).

Moved to #3090

Two changes that this PR had are now in #3090, because they are on by default and do not depend on the option:

• A change without a known author shows "Deleted" or "Inserted" in the tooltip.
• A change to only the id attribute of a block is not shown.

Not covered

• The deleter of a lost move: when a different user deletes a moved block later, the diff does not name that user. The diff cannot tell this case from a copy that was lost with its parent.
• The time of a removed mover: the deletion of a lost move keeps the time (deleteAt) of the mover. No mark or tooltip shows the time.
• Moves of text (cut and paste): text has no id, so we cannot pair the cut with the paste.
• The lost content: the diff shows a lost move as a deletion without an author, at the original position. To keep the content, we need move support.
• Silent loss: when the destructive edit gets to the server first, the content of the other user is never visible in a version.
• "Had" is not "saw": content can get to the client of the deleter immediately before the delete. This content counts as content that the deleter had.
• History that was already garbage-collected: a stored version can lack deleted content. Then nested content uses the mark of the parent.
• Two concurrent copies of the same block (for example, "Cascading indents" in the gallery) still show as two inserted copies.
• "Delete a nested block": the parent loses its child group, and the copy loses content. Thus, it still shows as deleted and inserted.
• Tables and live suggestion mode: not changed.

Tests

The tests are in #3090. On #3090, 16 tests have the comment "To be fixed by #3166" and are marked it.fails. This PR changes them to normal tests:

• versionDiffAttribution.test.ts:
  • concurrent content inside a deleted block shows without an author, and the deletions of the deleter keep the name of the deleter;
  • a hover on content that was deleted with its parent shows no author;
  • a block that moves into a concurrently deleted block, and a moved block that a different user deletes later, show no author;
  • type changes, a block moved among its siblings (at both places), comparisons with the first version, later edits, a rewritten text;
  • "strikes a moved block's children through with it at its old place";
  • "shows a block indented, then outdented by the same user / a different user, as unchanged";
  • "credits two type changes to the last one";
  • "credits every word to its writer, between any two versions": a document that 4 users change in 7 versions. For each of the 21 pairs of versions, the diff must credit each word to the user who wrote it.
• nestingChanges.test.ts: an indent and an unindent show as one moved block.

This PR removes the test "attributes a move to the mover": with the re-created blocks fix, an indent shows as moved and not as deleted.

Other tests:

• versionDiffFlags.test.ts: each value of the option, for 4 scenarios. Each value stores the same updates, and showing a diff never writes to the document (no update, and the same bytes before and after).
• Versioning snapshot (tests/src/end-to-end/y-prosemirror/__snapshots__/versioning.test.tsx.snap): each scenario shows once without the option and once with it ("(experimental)"). Without the option, all scenarios are the same as on feat!: rebuild version history and customize snapshot actions #3090. With "Implicit delete attribution", 2 scenarios change. With "+ re-created blocks", 15 scenarios change. Each changed scenario has a note for the option in the gallery.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blocknote	Ready	Preview	Oct 9, 2026 11:57am UTC
blocknote-website	Ready	Preview	Oct 9, 2026 11:57am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@3166

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@3166

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@3166

@blocknote/diagram-block

npm i https://pkg.pr.new/@blocknote/diagram-block@3166

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@3166

@blocknote/math-block

npm i https://pkg.pr.new/@blocknote/math-block@3166

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@3166

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@3166

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@3166

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@3166

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@3166

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@3166

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@3166

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@3166

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@3166

@blocknote/xl-typst-exporter

npm i https://pkg.pr.new/@blocknote/xl-typst-exporter@3166

commit: ef5e48a

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://TypeCellOS.github.io/BlockNote/pr-preview/pr-3166/
Built to branch gh-pages at 2026-10-09 12:06 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[YousefED]

shouldn't we change cloneWithId instead?