refactor(track-changes): improve comment accuracy and deduplicate test helpers

- Update replaceAroundStep.js comment to note that the isNodeMarkupChange
  heuristic matches both setNodeMarkup and setBlockType (indistinguishable
  at the step level), with reference to SD-2191 follow-up
- Extract findFirstParagraphRange() into testUtils.js, replacing 4
  duplicated paragraph-finding loops in replaceAroundStep.test.js
- Extract getFirstParagraphStyleId() helper in behavior test, replacing 3
  duplicated page.evaluate blocks

Author: caio-pizzol

packages/super-editor/src/extensions/track-changes/trackChangesHelpers/replaceAroundStep.js

@@ -94,10 +94,14 @@ export const replaceAroundStep = ({
     return;
   }
 
-  // Detect setNodeMarkup steps: they preserve the node type and content,
-  // only changing attributes (e.g. paragraph styleId for heading changes).
-  // These are safe to apply — they don't alter document structure.
-  // We also check step.insert === 1 to exclude lift() operations (insert === 0).
+  // Detect node-markup-change steps (setNodeMarkup and setBlockType both
+  // produce this same ReplaceAroundStep shape — they can't be distinguished
+  // at the step level). Used here to let paragraph style changes through in
+  // suggesting mode (e.g. Normal → Heading1 via setNodeMarkup).
+  // step.insert === 1 excludes lift() operations (insert === 0).
+  // Note: setBlockType is not triggered via UI in suggesting mode, but if
+  // it were, it would also bypass tracking. SD-2191 will add proper tracked
+  // change marks for these operations.
   const isNodeMarkupChange =
     step.structure && step.insert === 1 && step.gapFrom === step.from + 1 && step.gapTo === step.to - 1;
 

packages/super-editor/src/extensions/track-changes/trackChangesHelpers/replaceAroundStep.test.js

@@ -7,7 +7,7 @@ import { replaceAroundStep } from './replaceAroundStep.js';
 import { TrackDeleteMarkName, TrackInsertMarkName } from '../constants.js';
 import { TrackChangesBasePluginKey } from '../plugins/trackChangesBasePlugin.js';
 import { initTestEditor } from '@tests/helpers/helpers.js';
-import { findTextPos } from './testUtils.js';
+import { findTextPos, findFirstParagraphRange } from './testUtils.js';
 
 describe('replaceAroundStep handler', () => {
   let editor;
@@ -53,16 +53,7 @@ describe('replaceAroundStep handler', () => {
     // We find the first paragraph and create a step that would "unwrap" it
     // by replacing the paragraph's opening and closing tokens while preserving
     // the content between them.
-    let paraStart = null;
-    let paraEnd = null;
-    doc.forEach((node, offset) => {
-      if (paraStart === null && node.type.name === 'paragraph') {
-        paraStart = offset;
-        paraEnd = offset + node.nodeSize;
-      }
-    });
-
-    if (paraStart === null) throw new Error('No paragraph found');
+    const { paraStart, paraEnd } = findFirstParagraphRange(doc);
 
     // Build a transaction with a ReplaceAroundStep.
     // The step unwraps the paragraph: replaces the paragraph node but keeps its inline content.
@@ -159,16 +150,7 @@ describe('replaceAroundStep handler', () => {
       );
       const state = createState(doc);
 
-      // Build a ReplaceAroundStep that matches setNodeMarkup: structure=true, insert=1,
-      // gapFrom=from+1, gapTo=to-1 (wraps the same content in a new node with different attrs)
-      let paraStart = null;
-      let paraEnd = null;
-      state.doc.forEach((node, offset) => {
-        if (paraStart === null && node.type.name === 'paragraph') {
-          paraStart = offset;
-          paraEnd = offset + node.nodeSize;
-        }
-      });
+      const { paraStart, paraEnd } = findFirstParagraphRange(state.doc);
 
       const newParagraph = schema.nodes.paragraph.create({ paragraphProperties: { styleId: 'Heading1' } });
       const step = new ReplaceAroundStep(
@@ -211,14 +193,7 @@ describe('replaceAroundStep handler', () => {
       );
       const state = createState(doc);
 
-      let paraStart = null;
-      let paraEnd = null;
-      state.doc.forEach((node, offset) => {
-        if (paraStart === null && node.type.name === 'paragraph') {
-          paraStart = offset;
-          paraEnd = offset + node.nodeSize;
-        }
-      });
+      const { paraStart, paraEnd } = findFirstParagraphRange(state.doc);
 
       // lift-style step: insert=0, structure=true, gap=±1
       const step = new ReplaceAroundStep(paraStart, paraEnd, paraStart + 1, paraEnd - 1, Slice.empty, 0, true);
@@ -255,14 +230,7 @@ describe('replaceAroundStep handler', () => {
       );
       const state = createState(doc);
 
-      let paraStart = null;
-      let paraEnd = null;
-      state.doc.forEach((node, offset) => {
-        if (paraStart === null && node.type.name === 'paragraph') {
-          paraStart = offset;
-          paraEnd = offset + node.nodeSize;
-        }
-      });
+      const { paraStart, paraEnd } = findFirstParagraphRange(state.doc);
 
       const newParagraph = schema.nodes.paragraph.create({ paragraphProperties: { styleId: 'Heading1' } });
       const step = new ReplaceAroundStep(

packages/super-editor/src/extensions/track-changes/trackChangesHelpers/testUtils.js

@@ -17,3 +17,21 @@ export function findTextPos(docNode, exactText) {
   });
   return found;
 }
+
+/**
+ * Find the start and end positions of the first paragraph node in a document.
+ * @param {import('prosemirror-model').Node} doc - Document node to search
+ * @returns {{ paraStart: number, paraEnd: number }}
+ */
+export function findFirstParagraphRange(doc) {
+  let paraStart = null;
+  let paraEnd = null;
+  doc.forEach((node, offset) => {
+    if (paraStart === null && node.type.name === 'paragraph') {
+      paraStart = offset;
+      paraEnd = offset + node.nodeSize;
+    }
+  });
+  if (paraStart === null) throw new Error('No paragraph found');
+  return { paraStart, paraEnd };
+}

tests/behavior/tests/formatting/heading-style-suggesting-mode.spec.ts

@@ -1,4 +1,20 @@
 import { test, expect } from '../../fixtures/superdoc.js';
+import type { Page } from '@playwright/test';
+
+async function getFirstParagraphStyleId(page: Page): Promise<string | null> {
+  return page.evaluate(() => {
+    const editor = (window as any).editor;
+    let result: string | null = null;
+    editor.state.doc.descendants((node: any) => {
+      if (node.type.name === 'paragraph') {
+        result = node.attrs?.paragraphProperties?.styleId ?? null;
+        return false;
+      }
+      return true;
+    });
+    return result;
+  });
+}
 
 test.use({ config: { toolbar: 'full', comments: 'on', trackChanges: true } });
 
@@ -19,20 +35,7 @@ test.describe('SD-2182 heading style changes in suggesting mode', () => {
     });
     await superdoc.waitForStable();
 
-    // Verify the paragraph now has styleId 'Heading1'
-    const styleId = await superdoc.page.evaluate(() => {
-      const editor = (window as any).editor;
-      let result: string | null = null;
-      editor.state.doc.descendants((node: any) => {
-        if (node.type.name === 'paragraph' && node.attrs?.paragraphProperties?.styleId) {
-          result = node.attrs.paragraphProperties.styleId;
-          return false;
-        }
-        return true;
-      });
-      return result;
-    });
-
+    const styleId = await getFirstParagraphStyleId(superdoc.page);
     expect(styleId).toBe('Heading1');
   });
 
@@ -55,20 +58,7 @@ test.describe('SD-2182 heading style changes in suggesting mode', () => {
 
     expect(result).toBe(true);
 
-    // Verify the paragraph now has styleId 'Heading1'
-    const styleId = await superdoc.page.evaluate(() => {
-      const editor = (window as any).editor;
-      let result: string | null = null;
-      editor.state.doc.descendants((node: any) => {
-        if (node.type.name === 'paragraph' && node.attrs?.paragraphProperties?.styleId) {
-          result = node.attrs.paragraphProperties.styleId;
-          return false;
-        }
-        return true;
-      });
-      return result;
-    });
-
+    const styleId = await getFirstParagraphStyleId(superdoc.page);
     expect(styleId).toBe('Heading1');
   });
 
@@ -96,20 +86,7 @@ test.describe('SD-2182 heading style changes in suggesting mode', () => {
 
     expect(result).toBe(true);
 
-    // Verify the paragraph no longer has Heading1 styleId
-    const styleId = await superdoc.page.evaluate(() => {
-      const editor = (window as any).editor;
-      let result: string | null = null;
-      editor.state.doc.descendants((node: any) => {
-        if (node.type.name === 'paragraph') {
-          result = node.attrs?.paragraphProperties?.styleId ?? null;
-          return false;
-        }
-        return true;
-      });
-      return result;
-    });
-
+    const styleId = await getFirstParagraphStyleId(superdoc.page);
     expect(styleId).toBeNull();
   });
 });