React node views: caret does not move into new block on Enter since 3.28.0 (portal notification batching)

[SebiVPS]

Affected Packages

@tiptap/react

Tiptap Version

3.28.0

Browser Used

Chrome

What happened?

Description

When the paragraph node (or any block node) is rendered through ReactNodeViewRenderer, pressing Enter splits the node correctly in the ProseMirror document, but the DOM selection does not follow into the newly created block. The caret visually stays at the end of the original paragraph and continued typing is inserted there instead of the new paragraph — e.g. Hello + Enter + typing Second produces a single paragraph HelloSecond. This makes editors with React-node-view block nodes unusable for normal multi-paragraph text entry.

Native (non-node-view) nodes are unaffected. Marks are unaffected.

Steps to reproduce

1. Replace StarterKit's paragraph with a React node view:

   import Paragraph from "@tiptap/extension-paragraph";
   import { EditorContent, NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer, useEditor } from "@tiptap/react";
   import StarterKit from "@tiptap/starter-kit";
   
   const ParagraphView = () => (
       <NodeViewWrapper as="p">
           <NodeViewContent />
       </NodeViewWrapper>
   );
   
   const NodeViewParagraph = Paragraph.extend({
       addNodeView() {
           return ReactNodeViewRenderer(ParagraphView);
       },
   });
   
   function App() {
       const editor = useEditor({
           extensions: [StarterKit.configure({ paragraph: false }), NodeViewParagraph],
           content: "<p>Hello</p>",
       });
       return <EditorContent editor={editor} />;
   }

2. Click at the end of "Hello".

3. Press Enter.

4. Type anything.

Expected Behavior

Expected: a new empty paragraph is created, the caret moves into it, and the typed text lands in the new paragraph.

Actual: the document splits, but the caret stays in the old paragraph; the typed text is appended to "Hello" (the document collapses back to a single paragraph containing HelloSecond).

Immediately after step 3, window.getSelection() anchors on the node view's content element ([data-node-view-content-react]) at offset 0 with an empty client rect, instead of a renderable caret position inside the new block.

Root cause analysis

The regression is the "Batch portal store notifications during simultaneous mounts" change in 3.28.0. Diff of the portal store between 3.27.4 and 3.28.0:

// 3.27.4 — subscribers notified synchronously in setRenderer/removeRenderer
subscribers.forEach((subscriber) => subscriber());

// 3.28.0 — deferred to a microtask
const notifySubscribers = () => {
    if (isNotificationQueued || !subscribers.size) return;
    isNotificationQueued = true;
    queueMicrotask(() => {
        isNotificationQueued = false;
        subscribers.forEach((subscriber) => subscriber());
    });
};

Because the Portals component (useSyncExternalStore) is now notified in a microtask, a newly created ReactNodeView's component — and therefore its contentDOM — does not exist until after ProseMirror's current view update cycle has finished. When Enter splits a block, ProseMirror tries to map the selection into the new node view's contentDOM during that same update cycle, finds none, and the DOM selection is left behind in the old block. The browser then keeps inserting text at the stale caret position.

3.27.4 flushed the portal synchronously inside setRenderer, so contentDOM was available in time.

Environment

• @tiptap/core / @tiptap/react / @tiptap/pm / @tiptap/starter-kit / @tiptap/extension-paragraph 3.28.0
• react / react-dom 19.2.6
• Vite dev server, Chromium (also reported on Chrome stable)
• Reproduced both with a plain paragraph node view (above) and in a production setup: Bug: createTipTapRichTextBlock with textBlockStyles breaks the editing caret on Enter vivid-planet/comet#6037

Workaround

Pin @tiptap/* to 3.27.4.

One note: I verified the caret desync end-to-end in the Comet setup (TextBlockStyleParagraph); the minimal snippet in the issue is the standard pattern distilled from it but wasn't run standalone — if you want, I can spin it up quickly (e.g. in the cms-admin Storybook stories, which already have a plain node-view story) before you submit, so the repro is guaranteed against the exact snippet.

Reproducible Example URL (Optional)

No response

Additional Context (Optional)

No response

[coderabbitai]

🔗 Related PRs

#8095 - fix(react): onCreate fired twice under React.StrictMode in useEditor [open]
#8104 - fix(pm): bump prosemirror-model to ^1.25.11 to fix paste adding empty paragraphs (#8014) [open]
#8106 - fix(core): return undefined from NodeView getPos() instead of throwing during view updates [open]
#8107 - fix(vue-3): use NodeViewContent element as contentDOM instead of nesting a wrapper (#7950) [open]
#8113 - fix(react): update useEditorState when editable changes (#7498) [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Coding Plan

Summary

The caret bug comes from portal commits being deferred to a microtask, so a new node view's contentDOM isn't attached when ProseMirror restores the selection.

We add a small flush() method to the portal store that fires a pending notification immediately, without removing the default microtask batching.

We call that flush() inside the existing flushSync block in ReactRenderer, so node views created during a transaction commit their portal (and attach contentDOM) synchronously — restoring 3.27.4 behavior for the caret while keeping 3.28.0's batching for large simultaneous mounts.

We add tests for the new synchronous flush and for the Enter/split caret scenario.

Design Choices

Design Choice 1: How should we make contentDOM ready in time without bringing back the "too many updates" warning that batching was meant to fix?

Options Considered:

1. Add a small "flush now" method to the portal store, and call it inside the existing flushSync block in ReactRenderer so the new node view commits synchronously. Keep microtask batching everywhere else.
2. Revert notifySubscribers to always notify synchronously (undo the batching entirely).
3. Make setRenderer/removeRenderer always notify synchronously.

Chosen Option: 1

Rationale: It fixes the caret for the exact path that needs it (node views created during a transaction) while keeping the microtask batching for the initial/mass-mount path that motivated the 3.28.0 change.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Give the portal store a way to flush notifications immediately

Right now the store only ever notifies "later" (on a microtask). We're adding an opt-in way to notify "right now", so a caller that truly needs the DOM committed synchronously can ask for it. The default batching behavior stays exactly the same for everyone else.

Task 1: Add a synchronous flush to the content component store

Extend the store so a pending notification can be fired immediately instead of waiting for the microtask.

• Update createContentComponent() in packages/react/src/EditorContent.tsx.
• Keep notifySubscribers batching via queueMicrotask and the isNotificationQueued guard as-is (this is what protects mass mounts).
• Refactor the microtask callback so it checks the isNotificationQueued flag before firing. This lets a manual flush "cancel" the already-scheduled microtask (so we never notify twice).
• Add a new flush() method: if a notification is currently queued, clear the flag and call all subscribers immediately.

Task 2: Expose flush on the store's type

Make the new method part of the public shape so callers can use it with correct typing.

• Update the ContentComponent type in packages/react/src/Editor.ts to include flush: () => void.

🤖 Prompt for AI agents

Goal: give the portal store a way to notify subscribers immediately, on demand,
while keeping its existing microtask batching as the default behavior.

- In `packages/react/src/EditorContent.tsx`, update `createContentComponent()`:
- Keep `notifySubscribers` scheduling via `queueMicrotask` and keep using the
`isNotificationQueued` guard, exactly as it works today (this protects mass
mounts).
- Refactor the microtask callback so it first checks the `isNotificationQueued`
flag before firing subscribers. This way, if someone manually flushes before the
microtask runs, the microtask callback becomes a no-op (no duplicate
notification).
- Add a new `flush()` method to the store: if a notification is currently
queued, clear the `isNotificationQueued` flag and call all subscribers
immediately (synchronously).
- In `packages/react/src/Editor.ts`, update the `ContentComponent` type to add
`flush: () => void`, so the new method is properly typed for callers.

Phase 2: Commit new node view portals synchronously during a transaction

The ReactRenderer already wraps its first render in flushSync when the editor content is initialized. The problem is that render() only schedules a microtask notification, so flushSync has nothing to commit. We fix this by flushing the store notification inside that same flushSync boundary.

Flush the store inside the existing flushSync block

Make sure the portal actually commits (and contentDOM gets attached) before control returns to ProseMirror.

• Update the constructor of ReactRenderer in packages/react/src/ReactRenderer.tsx.
• In the if (this.editor.isEditorContentInitialized) branch, keep flushSync(() => this.render()), but also call this.editor.contentComponent?.flush() inside the same flushSync callback (right after render()).
• Leave the else branch (initial mount) on the queueMicrotask path untouched, so the initial/mass-mount batching still works.
• Rationale: this follows the guidance of "batch the mutations, then flush once" — render() records the change, and the single flush() commits it synchronously so ReactNodeView's constructor can find and attach its contentDOM in the same tick.

Note: no change is needed in ReactNodeViewRenderer.tsx. Its constructor already tries to find [data-node-view-content] and attach contentDOMElement; once the portal commits synchronously (from this fix), that lookup will succeed as it did in 3.27.4.

🤖 Prompt for AI agents

Goal: make sure a new node view's portal actually commits to the DOM before
control returns to ProseMirror, so `contentDOM` is attached in time for caret
placement.

- In `packages/react/src/ReactRenderer.tsx`, update the constructor:
- In the `if (this.editor.isEditorContentInitialized)` branch, keep the existing
`flushSync(() => this.render())` call.
- Inside that same `flushSync` callback, right after `render()`, also call
`this.editor.contentComponent?.flush()`.
- Leave the `else` branch (used for the initial mount) untouched — it should
keep using the `queueMicrotask` path so batching for big/simultaneous mounts
still works.
- Do not change `ReactNodeViewRenderer.tsx`. Its constructor already looks for
`[data-node-view-content]` and attaches `contentDOMElement`; once the portal
commits synchronously thanks to this fix, that lookup will succeed just like it
did before the regression.

Phase 3: Tests to lock in the fix

Prove the caret works again, and make sure we didn't break the existing batching contract.

Task 1: Cover the new synchronous flush in the store test

Verify batching still works by default, and that flush() notifies immediately.

• Update packages/react/src/EditorContent.spec.ts.
• Keep the existing "batches synchronous renderer change notifications" test (it must still pass unchanged).
• Add a test: after setRenderer, calling flush() calls subscribers synchronously, and the later microtask does not fire a duplicate notification.

Task 2: Add a test for the Enter/split caret scenario

Guard against this regression coming back.

• Add a test in packages/react/src/ReactNodeViewRenderer.spec.ts.
• Set up a paragraph rendered via ReactNodeViewRenderer (with NodeViewWrapper/NodeViewContent), split the block (Enter / splitBlock), then assert the new node view's contentDOM is attached synchronously and the selection lands inside the new block.
• Make sure the four existing mid-transaction tests still pass.

🤖 Prompt for AI agents

Goal: add tests that prove the caret bug is fixed and that the store's existing
batching behavior is not broken.

- In `packages/react/src/EditorContent.spec.ts`:
- Keep the existing "batches synchronous renderer change notifications" test
passing unchanged.
- Add a new test: after calling `setRenderer`, calling `flush()` should call
subscribers synchronously, and the microtask that would normally fire later
should not cause a duplicate notification.
- In `packages/react/src/ReactNodeViewRenderer.spec.ts`:
- Add a new test that sets up a paragraph rendered via `ReactNodeViewRenderer`
(using `NodeViewWrapper`/`NodeViewContent`), then splits the block (simulating
Enter / using `splitBlock`).
- Assert that the new node view's `contentDOM` is attached synchronously and
that the selection lands inside the new block.
  - Make sure all four existing mid-transaction tests still pass.

Research

The React package (packages/react/src) renders each node/mark view through a ReactRenderer, which registers a portal in a small store created by createContentComponent() in EditorContent.tsx. A Portals component subscribes to that store via useSyncExternalStore and commits the portals into the DOM.

In v3.28.0 the store started deferring its "something changed" notification with queueMicrotask, so the actual portal commit (and therefore contentDOM attachment) now lags one microtask behind. ProseMirror (packages/pm, an unmodified re-export of prosemirror-view) restores the DOM selection synchronously inside view.updateState, so it needs the new node view's contentDOM to already be attached before that call returns.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Goal: give the portal store a way to notify subscribers immediately, on demand,
while keeping its existing microtask batching as the default behavior.

- In `packages/react/src/EditorContent.tsx`, update `createContentComponent()`:
- Keep `notifySubscribers` scheduling via `queueMicrotask` and keep using the
`isNotificationQueued` guard, exactly as it works today (this protects mass
mounts).
- Refactor the microtask callback so it first checks the `isNotificationQueued`
flag before firing subscribers. This way, if someone manually flushes before the
microtask runs, the microtask callback becomes a no-op (no duplicate
notification).
- Add a new `flush()` method to the store: if a notification is currently
queued, clear the `isNotificationQueued` flag and call all subscribers
immediately (synchronously).
- In `packages/react/src/Editor.ts`, update the `ContentComponent` type to add
`flush: () => void`, so the new method is properly typed for callers.
===============================================================================

Task: 2

Goal: make sure a new node view's portal actually commits to the DOM before
control returns to ProseMirror, so `contentDOM` is attached in time for caret
placement.

- In `packages/react/src/ReactRenderer.tsx`, update the constructor:
- In the `if (this.editor.isEditorContentInitialized)` branch, keep the existing
`flushSync(() => this.render())` call.
- Inside that same `flushSync` callback, right after `render()`, also call
`this.editor.contentComponent?.flush()`.
- Leave the `else` branch (used for the initial mount) untouched — it should
keep using the `queueMicrotask` path so batching for big/simultaneous mounts
still works.
- Do not change `ReactNodeViewRenderer.tsx`. Its constructor already looks for
`[data-node-view-content]` and attaches `contentDOMElement`; once the portal
commits synchronously thanks to this fix, that lookup will succeed just like it
did before the regression.
===============================================================================

Task: 3

Goal: add tests that prove the caret bug is fixed and that the store's existing
batching behavior is not broken.

- In `packages/react/src/EditorContent.spec.ts`:
- Keep the existing "batches synchronous renderer change notifications" test
passing unchanged.
- Add a new test: after calling `setRenderer`, calling `flush()` should call
subscribers synchronously, and the microtask that would normally fire later
should not cause a duplicate notification.
- In `packages/react/src/ReactNodeViewRenderer.spec.ts`:
- Add a new test that sets up a paragraph rendered via `ReactNodeViewRenderer`
(using `NodeViewWrapper`/`NodeViewContent`), then splits the block (simulating
Enter / using `splitBlock`).
- Assert that the new node view's `contentDOM` is attached synchronously and
that the selection lands inside the new block.
  - Make sure all four existing mid-transaction tests still pass.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[bdbch]

Looking into it right now.

[evanhammer]

Thanks for working on this!! Unfortunately I'm still reproducing on 3.29.1 (the fix from #8127 doesn't resolve it for us).

Our setup is a task-list editor where taskItem (content: paragraph taskList?) is rendered through ReactNodeViewRenderer, with NodeViewContent a couple of levels down inside NodeViewWrapper.

Bisect (same test, only the @tiptap/* version changed):

version	result
3.27.4	pass
3.28.0	fail
3.29.0	fail
3.29.1	fail

Observed after pressing Enter at the end of a row: the document splits correctly (two <li> in the DOM), but window.getSelection() is still anchored in the old paragraph's text node. Typing then appends there, so Alpha + Enter + Beta collapses to a single row AlphaBeta and the new row stays empty.

By the time we sample it asynchronously, the new node view is fully and correctly rendered — [data-node-view-content] and [data-node-view-content-react] both present, with <p><br class="ProseMirror-trailingBreak"></p> inside. So the DOM ends up right; the selection just never follows, and nothing re-syncs it afterwards.

Root cause looks unchanged in 3.29.1. createContentComponent's notifySubscribers still defers to a microtask:

const notifySubscribers = () => {
  if (isNotificationQueued || !subscribers.size) return
  isNotificationQueued = true
  queueMicrotask(() => {
    isNotificationQueued = false
    subscribers.forEach((subscriber) => subscriber())
  })
}

ReactRenderer's flushSync(() => this.render()) can't compensate, since render() only calls setRenderer() → notifySubscribers(), which queues rather than scheduling React work — so there is nothing pending for flushSync to flush. The portal therefore still mounts after ProseMirror's update cycle, and #8127's this.dom.appendChild(this.contentDOMElement) fallback doesn't rescue our case.

Confirmation: patching only notifySubscribers back to the synchronous 3.27.4 form, on top of an otherwise untouched 3.29.1 —

const notifySubscribers = () => {
  subscribers.forEach((subscriber) => subscriber())
}

— fixes it completely: the caret follows into the new row, and our full end-to-end suite goes from 14 passed / 19 failed to 33/33 green. We also stress-tested the case the batching was presumably added for (a document with ~40 React node views all mounting at once on load) and saw no React errors or warnings in the console.

Is there any other information that would be useful to you?