perf(core): resolve block changes from changed range only

getBlocksChangedByTransaction snapshotted the entire document (a nodeToBlock
conversion of every block, twice) on every transaction. Since apps read
getChanges() on each keystroke, typing lagged in large documents. It now diffs
only the range the transaction touched.

Extract a shared getChangedRange() helper that, unlike ProseMirror's
changedRange(), also covers attribute-only steps (AttrStep) and mark steps, at
the same O(steps) cost. PreviousBlockType now uses it too, fixing a latent bug
where attribute-only changes (e.g. a heading's level) were silently missed by
its ranged diff.

Author: nperez0111

packages/core/src/api/getBlocksChangedByTransaction.ts

@@ -11,6 +11,7 @@ import {
 import type { BlockSchema } from "../schema/index.js";
 import type { InlineContentSchema } from "../schema/inlineContent/types.js";
 import type { StyleSchema } from "../schema/styles/types.js";
+import { getChangedRange } from "./getChangedRange.js";
 import { getNodeId } from "./getBlockInfoFromPos.js";
 import { nodeToBlock } from "./nodeConversions/nodeToBlock.js";
 import { isNodeBlock } from "./nodeUtil.js";
@@ -20,14 +21,29 @@ import { isNodeBlock } from "./nodeUtil.js";
  *
  * High-level algorithm used by getBlocksChangedByTransaction:
  * 1) Merge appended transactions into one document change.
- * 2) Collect a snapshot of blocks before and after (flat map by id, and per-parent child order).
- * 3) Emit inserts and deletes by diffing ids between snapshots.
- * 4) For ids present in both snapshots:
+ * 2) Compute the single range of the document that the transaction touched
+ *    (in both the new and old document), so we only inspect blocks that could
+ *    have changed rather than walking the whole document. This matters because
+ *    getChanges() runs per transaction: a full-document snapshot made typing in
+ *    large documents slow, since every keystroke re-converted every block.
+ * 3) Collect a snapshot of blocks before and after *within that range* (flat map
+ *    by id, and per-parent child order).
+ * 4) Emit inserts and deletes by diffing ids between snapshots.
+ * 5) For ids present in both snapshots:
  *    - If parentId changed, emit a move
  *    - Else if block changed (ignoring children), emit an update
- * 5) Finally, detect same-parent sibling reorders by comparing child order per parent.
+ * 6) Finally, detect same-parent sibling reorders by comparing child order per parent.
  *    We use an inlined O(n log n) LIS inside detectReorderedChildren to keep a
  *    longest already-ordered subsequence and mark only the remaining items as moved.
+ *
+ * Why a range is sufficient: `changedRange()` returns the single contiguous span
+ * from the first to the last changed position in the document. Any block that was
+ * inserted, deleted, moved, updated, or whose sibling order changed has all of its
+ * relevant positions (old and new) inside that span. Blocks entirely outside the
+ * span are byte-for-byte identical and keep their relative order, so they cannot
+ * produce a change. A moved block's parent always *contains* that block, so the
+ * parent overlaps the range and is included too (and nodeToBlock converts its full
+ * subtree regardless of the range).
  */
 /**
  * Gets the parent block of a node, if it has one.
@@ -144,14 +160,22 @@ type BlockSnapshot<
 };
 
 /**
- * Collects a snapshot of blocks and per-parent child order in a single traversal.
- * Uses "__root__" to represent the root level where parentId is undefined.
+ * Collects a snapshot of blocks and per-parent child order in a single traversal,
+ * limited to the block nodes that overlap the given range. Uses "__root__" to
+ * represent the root level where parentId is undefined.
+ *
+ * Traversing only the changed range (instead of the whole document) is what keeps
+ * this cheap per keystroke: nodeToBlock is only called for blocks that could have
+ * changed, not for every block in the document.
  */
 function collectSnapshot<
   BSchema extends BlockSchema,
   ISchema extends InlineContentSchema,
   SSchema extends StyleSchema,
->(doc: Node): BlockSnapshot<BSchema, ISchema, SSchema> {
+>(
+  doc: Node,
+  range: { from: number; to: number },
+): BlockSnapshot<BSchema, ISchema, SSchema> {
   const ROOT_KEY = "__root__";
   const byId: Record<
     string,
@@ -161,7 +185,13 @@ function collectSnapshot<
     }
   > = {};
   const childrenByParent: Record<string, string[]> = {};
-  doc.descendants((node, pos) => {
+  // Clamp to valid document positions; mapped ranges should already be valid, but
+  // nodesBetween throws on out-of-range positions.
+  const from = Math.max(0, Math.min(range.from, doc.content.size));
+  const to = Math.max(from, Math.min(range.to, doc.content.size));
+  // nodesBetween visits every node overlapping [from, to] in document order,
+  // including ancestor blocks that contain the range.
+  doc.nodesBetween(from, to, (node, pos) => {
     if (!isNodeBlock(node)) {
       return true;
     }
@@ -282,11 +312,28 @@ export function getBlocksChangedByTransaction<
     ...appendedTransactions,
   ]);
 
+  // The range of the new document that the transaction changed. Null means the
+  // document did not change, so there is nothing to diff.
+  const newRange = getChangedRange(combinedTransaction);
+  if (!newRange) {
+    return [];
+  }
+  // Map that range back to old-document coordinates. The -1/+1 biases expand the
+  // range outwards so that, for pure inserts/deletes (where the new range is a
+  // collapsed point), the old range still covers the affected span.
+  const invertedMapping = combinedTransaction.mapping.invert();
+  const oldRange = {
+    from: invertedMapping.map(newRange.from, -1),
+    to: invertedMapping.map(newRange.to, 1),
+  };
+
   const prevSnap = collectSnapshot<BSchema, ISchema, SSchema>(
     combinedTransaction.before,
+    oldRange,
   );
   const nextSnap = collectSnapshot<BSchema, ISchema, SSchema>(
     combinedTransaction.doc,
+    newRange,
   );
 
   const changes: BlocksChanged<BSchema, ISchema, SSchema> = [];

packages/core/src/api/getChangedRange.ts

@@ -0,0 +1,69 @@
+import type { Transform } from "prosemirror-transform";
+
+/**
+ * Computes the single new-document range spanning everything a transform changed,
+ * or null when nothing changed.
+ *
+ * This is a drop-in replacement for ProseMirror's `Transform.changedRange()` that
+ * additionally accounts for position-preserving steps whose `StepMap` is empty:
+ * - `AttrStep` — a single node's attributes changed (emitted by updateBlock for
+ *   prop-only edits, e.g. a heading's `level` or a numbered list item's `index`).
+ * - `AddMarkStep` / `RemoveMarkStep` — marks changed over a range.
+ *
+ * `changedRange()` and tiptap's `getChangedRanges` both miss `AttrStep`: its map
+ * contributes no ranges, and it exposes `pos` rather than `from`/`to`. Any consumer
+ * that scopes work to the changed range (rather than walking the whole document)
+ * would therefore silently ignore prop-only updates. This helper recovers those
+ * positions directly from the step.
+ *
+ * Complexity matches `changedRange()`: O(number of steps). It advances a single
+ * accumulated range forward through each step map once, injecting empty-map steps'
+ * positions as it goes, rather than remapping every step's range independently.
+ */
+export function getChangedRange(
+  transform: Transform,
+): { from: number; to: number } | null {
+  const { mapping, steps } = transform;
+  let from = Number.POSITIVE_INFINITY;
+  let to = Number.NEGATIVE_INFINITY;
+
+  for (let i = 0; i < mapping.maps.length; i++) {
+    const map = mapping.maps[i];
+    // Advance the accumulated range into this step's coordinate space (identity
+    // for the first step). Biases keep it from spilling into content inserted at
+    // its edges, matching ProseMirror's own changedRange().
+    if (i) {
+      from = map.map(from, 1);
+      to = map.map(to, -1);
+    }
+
+    let hadRange = false;
+    map.forEach((_oldFrom, _oldTo, newFrom, newTo) => {
+      hadRange = true;
+      from = Math.min(from, newFrom);
+      to = Math.max(to, newTo);
+    });
+
+    if (!hadRange) {
+      // Empty step map: a position-preserving step, so its positions live in the
+      // current coordinate space and later maps advance them along with the rest.
+      const step = steps[i] as { pos?: number; from?: number; to?: number };
+      if (typeof step.pos === "number") {
+        // AttrStep
+        from = Math.min(from, step.pos);
+        to = Math.max(to, step.pos + 1);
+      } else if (typeof step.from === "number" && typeof step.to === "number") {
+        // AddMarkStep / RemoveMarkStep
+        from = Math.min(from, step.from);
+        to = Math.max(to, step.to);
+      }
+      // DocAttrStep (no pos/from/to) changes document-level attributes only and
+      // affects no nodes, so it is intentionally ignored.
+    }
+  }
+
+  if (from === Number.POSITIVE_INFINITY) {
+    return null;
+  }
+  return { from, to };
+}

packages/core/src/editor/performance.test.ts

@@ -144,4 +144,55 @@ describe("Performance: transaction processing scales sub-linearly (#2595)", () =
     // Absolute time (~40ms) is comparable to begin (~32ms).
     expect(ratio).toBeLessThan(250);
   });
+
+  // getChanges() is lazy: it only runs the (previously full-document) diff when
+  // an onChange/onBeforeChange subscriber actually calls it. The other tests
+  // never subscribe, so they don't cover getBlocksChangedByTransaction — the
+  // path an app hits when it registers editor.onChange(...) and inspects the
+  // changes on every keystroke. This test locks in that getChanges() only
+  // inspects the changed range, not the whole document.
+  it(
+    "getChanges() in onChange scales sub-linearly",
+    { timeout: 30_000 },
+    () => {
+      function measureWithGetChanges(
+        editor: BlockNoteEditor<any, any, any>,
+        pos: number,
+      ) {
+        // Force the full diff to run for every transaction, like an app that
+        // reads the changed blocks on each keystroke.
+        // eslint-disable-next-line @typescript-eslint/unbound-method -- getChanges is destructured from callback parameter, not a class
+        const unsubscribe = editor.onChange((_editor, { getChanges }) => {
+          getChanges();
+        });
+        const avg = measureAvgInsertTime(editor, pos);
+        unsubscribe();
+        return avg;
+      }
+
+      const smallEditor = createEditorWithBlocks(SMALL, "paragraph");
+      const largeEditor = createEditorWithBlocks(LARGE, "paragraph");
+
+      const smallAvg = measureWithGetChanges(
+        smallEditor,
+        smallEditor._tiptapEditor.view.state.doc.content.size - 2,
+      );
+      const largeAvg = measureWithGetChanges(
+        largeEditor,
+        largeEditor._tiptapEditor.view.state.doc.content.size - 2,
+      );
+      const ratio = largeAvg / smallAvg;
+
+      // eslint-disable-next-line no-console
+      console.log(
+        `getChanges (end): ${SMALL}=${smallAvg.toFixed(3)}ms, ${LARGE}=${largeAvg.toFixed(3)}ms, ratio=${ratio.toFixed(2)}x`,
+      );
+
+      // With the full-document snapshot, getChanges alone was O(blocks) per
+      // keystroke (two nodeToBlock conversions of the entire document), pushing
+      // this ratio toward the block-count ratio (~50x). Diffing only the changed
+      // range keeps it well below the other O(n) ProseMirror DOM costs.
+      expect(ratio).toBeLessThan(50);
+    },
+  );
 });

packages/core/src/extensions/PreviousBlockType/PreviousBlockType.test.ts

@@ -96,4 +96,25 @@ describe("PreviousBlockType: scoped traversal", () => {
     ).length;
     expect(trackedBlockCount).toBeLessThan(10);
   });
+
+  it("detects attribute-only changes (heading level) that emit an AttrStep", () => {
+    const editor = createEditorWithBlocks(100, "heading");
+
+    // Changing only a heading's level (type stays "heading") emits an AttrStep,
+    // whose StepMap is empty — so ProseMirror's changedRange() returns null and
+    // the change would be missed unless the scoped range also covers AttrSteps.
+    const firstBlock = editor.document[0];
+    editor.updateBlock(firstBlock, { props: { level: 2 } } as any);
+
+    const state = getPreviousBlockTypePluginState(editor);
+
+    expect(state.updatedBlocks.size).toBe(1);
+    expect(state.updatedBlocks.has(firstBlock.id)).toBe(true);
+
+    // Still scoped to the changed range, not all 100 blocks.
+    const trackedBlockCount = Object.keys(
+      state.currentTransactionOldBlockAttrs,
+    ).length;
+    expect(trackedBlockCount).toBeLessThan(10);
+  });
 });

packages/core/src/extensions/PreviousBlockType/PreviousBlockType.ts

@@ -2,6 +2,7 @@ import { findChildrenInRange } from "@tiptap/core";
 import { Plugin, PluginKey } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 import { getNodeId } from "../../api/getBlockInfoFromPos.js";
+import { getChangedRange } from "../../api/getChangedRange.js";
 import { createExtension } from "../../editor/BlockNoteExtension.js";
 
 const PLUGIN_KEY = new PluginKey(`previous-blocks`);
@@ -73,8 +74,11 @@ export const PreviousBlockTypeExtension = createExtension(() => {
             }
 
             // Only check nodes affected by the transaction, not the entire document.
-            // changedRange() is O(steps) unlike tiptap's getChangedRanges which is O(steps²).
-            const newRange = transaction.changedRange();
+            // getChangedRange() is O(steps), unlike tiptap's getChangedRanges which
+            // is O(steps²). Unlike ProseMirror's changedRange() it also covers
+            // attribute-only steps (AttrStep), so a block whose `level`/`index`
+            // changes without any content edit is still picked up here.
+            const newRange = getChangedRange(transaction);
             if (!newRange) {
               return prev;
             }