fix(ui): stale data modal shown when onChange starts while save is in-flight (#15960)

# Overview

Fixes a race condition where the "Document Modified" modal incorrectly
appears
after a user types and saves their own document.

## Key Changes

- Added `saveCounterRef` (incremented in `onSubmit`) and `isSavingRef`
(set in `onSubmit`, cleared in `onSave`) to the Edit view
- Both are captured at the start of each `onChange` and used to suppress
the stale data modal when the newer `updatedAt` the server sees came
from our own save
- Added CPU throttling to an existing lexical e2e test to reliably
reproduce the race in CI environments

<img width="1790" height="1198" alt="Screenshot 2026-03-16 at 9 32
31 AM"
src="https://github.com/user-attachments/assets/d95fffb0-fa5f-44aa-98ac-41a8564daff3"
/>

## Design Decisions

`saveCounterRef` handles form-state requests that start before
`onSubmit` — the counter
advances mid-flight, so `saveCounterAtStart` diverges and the modal is
suppressed.

`isSavingRef` handles the complementary case where a queued `onChange`
starts after
`onSubmit` (so the counter already matches) but before `onSave` has
updated
`originalUpdatedAtRef` with the new timestamp. Capturing it before the
async call means
the guard fires correctly even if the save completes before the response
arrives.

The two-user scenario is unaffected — both refs are per-instance, so
another user's
save doesn't influence the local state and the modal still appears
correctly.

Author: PatrikKozak

packages/ui/src/views/Edit/index.tsx

@@ -186,6 +186,7 @@ export function DefaultEditView({
   const hasCheckedForStaleDataRef = useRef(false)
   const originalUpdatedAtRef = useRef(data?.updatedAt)
   const saveCounterRef = useRef(0)
+  const isSavingRef = useRef(false)
 
   const lockExpiryTime = lastUpdateTime + lockDurationInMilliseconds
   const isLockExpired = Date.now() > lockExpiryTime
@@ -316,6 +317,7 @@ export function DefaultEditView({
       // This allows detecting if another user modifies the document after this save
       originalUpdatedAtRef.current = updatedAt
       hasCheckedForStaleDataRef.current = false
+      isSavingRef.current = false
 
       if (context?.incrementVersionCount !== false) {
         incrementVersionCount()
@@ -467,9 +469,10 @@ export function DefaultEditView({
     async ({ formState: prevFormState, submitted }) => {
       const controller = handleAbortRef(abortOnChangeRef)
 
-      // Capture save counter before the async form-state request so we can detect
+      // Capture save state before the async form-state request so we can detect
       // if a save was triggered while this request was in-flight
       const saveCounterAtStart = saveCounterRef.current
+      const isSavingAtStart = isSavingRef.current
 
       // Sync originalUpdatedAt with current data if it's NEWER (e.g., after router.refresh())
       if (data?.updatedAt && data.updatedAt > originalUpdatedAtRef.current) {
@@ -531,9 +534,13 @@ export function DefaultEditView({
       }
 
       // Handle stale data detection.
-      // Skip if a save was triggered after this request was initiated — the newer
-      // updatedAt the server sees is from our OWN save, not an external modification.
-      if (staleDataState?.isStale && saveCounterRef.current === saveCounterAtStart) {
+      // Skip if a save was in-flight when this request started, or if the save counter
+      // has advanced — either way the newer updatedAt is from our OWN save.
+      if (
+        staleDataState?.isStale &&
+        !isSavingAtStart &&
+        saveCounterRef.current === saveCounterAtStart
+      ) {
         setShowStaleDataModal(true)
       }
 
@@ -627,6 +634,7 @@ export function DefaultEditView({
           onChange={[onChange]}
           onSubmit={() => {
             saveCounterRef.current += 1
+            isSavingRef.current = true
           }}
           onSuccess={onSave}
         >

test/lexical/collections/Lexical/e2e/main/e2e.spec.ts

@@ -166,6 +166,46 @@ describe('lexicalMain', () => {
     await expect(page.locator('.leave-without-saving__content').first()).toBeHidden()
   })
 
+  test('should not show stale data modal after saving a lexical document with blocks (race condition)', async () => {
+    // CPU throttling widens the race window enough to reproduce reliably:
+    // the large block-based form state takes longer to process, so a queued
+    // onChange can start after onSubmit (isSaving=true) but before onSave
+    // updates originalUpdatedAtRef — causing the server to return isStale=true
+    // from our own save.
+    const client = await page.context().newCDPSession(page)
+    await client.send('Emulation.setCPUThrottlingRate', { rate: 4 })
+
+    try {
+      await navigateToLexicalFields()
+      await expect(
+        page.locator('.rich-text-lexical').nth(2).locator('.LexicalEditorTheme__block'),
+      ).toHaveCount(10)
+      await expect(page.locator('.shimmer-effect')).toHaveCount(0)
+
+      const thirdBlock = page
+        .locator('.rich-text-lexical')
+        .nth(2)
+        .locator('.LexicalEditorTheme__block')
+        .nth(2)
+      await thirdBlock.scrollIntoViewIfNeeded()
+
+      const spanInBlock = thirdBlock
+        .locator('span')
+        .getByText('Some text below relationship node 1')
+        .first()
+      await spanInBlock.scrollIntoViewIfNeeded()
+      await spanInBlock.click()
+
+      await page.keyboard.type('moretext')
+      await saveDocAndAssert(page)
+
+      await expect(page.locator('.payload__modal-container')).toBeHidden()
+    } finally {
+      await client.send('Emulation.setCPUThrottlingRate', { rate: 1 })
+      await client.detach()
+    }
+  })
+
   test('should type and save typed text', async () => {
     await navigateToLexicalFields()
     const richTextField = page.locator('.rich-text-lexical').nth(2) // second
@@ -456,8 +496,8 @@ describe('lexicalMain', () => {
       const popoverOption3BoundingBox = await popoverOption3.boundingBox()
       expect(popoverOption3BoundingBox).not.toBeNull()
       expect(popoverOption3BoundingBox).not.toBeUndefined()
-      expect(popoverOption3BoundingBox.height).toBeGreaterThan(0)
-      expect(popoverOption3BoundingBox.width).toBeGreaterThan(0)
+      expect(popoverOption3BoundingBox?.height).toBeGreaterThan(0)
+      expect(popoverOption3BoundingBox?.width).toBeGreaterThan(0)
 
       // Now click the button to see if it actually works. Simulate an actual mouse click instead of using .click()
       // by using page.mouse and the correct coordinates
@@ -466,8 +506,8 @@ describe('lexicalMain', () => {
       // This is why we use page.mouse.click() here. It's the most effective way of detecting such a z-index issue
       // and usually the only method which works.
 
-      const x = popoverOption3BoundingBox.x
-      const y = popoverOption3BoundingBox.y
+      const x = popoverOption3BoundingBox?.x ?? 0
+      const y = popoverOption3BoundingBox?.y ?? 0
 
       await page.mouse.click(x, y, { button: 'left' })
     }).toPass({
@@ -1566,7 +1606,6 @@ describe('lexicalMain', () => {
 
     const relationshipInput = page.locator('.drawer__content .rs__input').first()
     await expect(relationshipInput).toBeVisible()
-    page.getByRole('heading', { name: 'Lexical Fields' })
     await relationshipInput.click()
     const user = page.getByRole('option', { name: 'User' })
     await user.click()
@@ -1576,10 +1615,8 @@ describe('lexicalMain', () => {
       .filter({ hasText: /^User$/ })
       .first()
     await expect(userListDrawer).toBeVisible()
-    page.getByRole('heading', { name: 'Users' })
     const button = page.getByLabel('Add new User')
     await button.click()
-    page.getByText('Creating new User')
   })
 
   test('ensure custom Description component is rendered only once', async () => {

test/lexical/payload-types.ts

@@ -199,14 +199,7 @@ export interface NestedBlock {
  * via the `definition` "blockWithBlockRef".
  */
 export interface BlockWithBlockRef {
-  nestedBlocks?:
-    | {
-        text?: string | null;
-        id?: string | null;
-        blockName?: string | null;
-        blockType: 'nestedBlock';
-      }[]
-    | null;
+  nestedBlocks?: NestedBlock[] | null;
   id?: string | null;
   blockName?: string | null;
   blockType: 'blockWithBlockRef';

test/locked-documents/e2e.spec.ts

@@ -1757,37 +1757,38 @@ describe('Locked Documents', () => {
         const client = await page.context().newCDPSession(page)
         await client.send('Emulation.setCPUThrottlingRate', { rate: 50 })
 
-        const fieldA = page.locator('#field-fieldA')
-        const modalContainer = page.locator('.payload__modal-container')
-
-        // Make many rapid edits to create multiple queued autosaves
-        for (let i = 1; i <= 10; i++) {
-          await fieldA.fill(`Edit ${i}`)
-          // eslint-disable-next-line payload/no-wait-function
-          await wait(30)
-        }
-
-        // Wait for all autosaves to process
-        // eslint-disable-next-line payload/no-wait-function
-        await wait(2000)
+        try {
+          const fieldA = page.locator('#field-fieldA')
+          const modalContainer = page.locator('.payload__modal-container')
 
-        // Make one more edit to trigger stale data check
-        await fieldA.fill('Final Edit')
-        // eslint-disable-next-line payload/no-wait-function
-        await wait(500)
-
-        // Modal should NOT appear because it's the same user
-        await expect(modalContainer).toBeHidden()
+          // Make many rapid edits to create multiple queued autosaves
+          for (let i = 1; i <= 10; i++) {
+            await fieldA.fill(`Edit ${i}`)
+            // eslint-disable-next-line payload/no-wait-function
+            await wait(30)
+          }
 
-        // Clean up
-        await client.send('Emulation.setCPUThrottlingRate', { rate: 1 })
-        await client.detach()
+          // Wait for all autosaves to process
+          // eslint-disable-next-line payload/no-wait-function
+          await wait(2000)
 
-        // Clean up created autosave document
-        for (const id of createdAutosaveIDs) {
-          await payload.delete({ collection: 'autosave', id }).catch(() => {
-            // Ignore deletion errors (document might already be deleted)
-          })
+          // Make one more edit to trigger stale data check
+          await fieldA.fill('Final Edit')
+          // eslint-disable-next-line payload/no-wait-function
+          await wait(500)
+
+          // Modal should NOT appear because it's the same user
+          await expect(modalContainer).toBeHidden()
+        } finally {
+          await client.send('Emulation.setCPUThrottlingRate', { rate: 1 })
+          await client.detach()
+
+          // Clean up created autosave document
+          for (const id of createdAutosaveIDs) {
+            await payload.delete({ collection: 'autosave', id }).catch(() => {
+              // Ignore deletion errors (document might already be deleted)
+            })
+          }
         }
       })
 
@@ -2180,31 +2181,32 @@ describe('Locked Documents', () => {
         const client = await page.context().newCDPSession(page)
         await client.send('Emulation.setCPUThrottlingRate', { rate: 50 })
 
-        const textField = page.locator('#field-text')
-        const modalContainer = page.locator('.payload__modal-container')
+        try {
+          const textField = page.locator('#field-text')
+          const modalContainer = page.locator('.payload__modal-container')
 
-        // Make many rapid edits to create multiple queued autosaves
-        for (let i = 1; i <= 10; i++) {
-          await textField.fill(`Edit ${i}`)
-          // eslint-disable-next-line payload/no-wait-function
-          await wait(30)
-        }
-
-        // Wait for all autosaves to process
-        // eslint-disable-next-line payload/no-wait-function
-        await wait(2000)
+          // Make many rapid edits to create multiple queued autosaves
+          for (let i = 1; i <= 10; i++) {
+            await textField.fill(`Edit ${i}`)
+            // eslint-disable-next-line payload/no-wait-function
+            await wait(30)
+          }
 
-        // Make one more edit to trigger stale data check
-        await textField.fill('Final Edit')
-        // eslint-disable-next-line payload/no-wait-function
-        await wait(500)
+          // Wait for all autosaves to process
+          // eslint-disable-next-line payload/no-wait-function
+          await wait(2000)
 
-        // Modal should NOT appear because stale check is disabled for autosave-enabled globals
-        await expect(modalContainer).toBeHidden()
+          // Make one more edit to trigger stale data check
+          await textField.fill('Final Edit')
+          // eslint-disable-next-line payload/no-wait-function
+          await wait(500)
 
-        // Clean up
-        await client.send('Emulation.setCPUThrottlingRate', { rate: 1 })
-        await client.detach()
+          // Modal should NOT appear because stale check is disabled for autosave-enabled globals
+          await expect(modalContainer).toBeHidden()
+        } finally {
+          await client.send('Emulation.setCPUThrottlingRate', { rate: 1 })
+          await client.detach()
+        }
       })
     })
   })