Notes: Mark the text an unsent note is about with a draft marker

[Mamaduka]

What?

Follow-up to #84110. See #73473.

When a note is started from a text selection, the selected text is wrapped with a core/note marker (id new) until the note is sent; submit swaps in the saved ID, cancel strips it.

Before, if the draft stayed open across a canvas click or block switch, the note submitted silently as a block-level note. Also, with no notes on the post, selecting a block with an unsent draft again did not reopen the draft until "Add note" was pressed.

Why?

onCreate read the inline anchor from the live block-editor selection at submit, which matched only the selection at form open, while any focus-out closed the form. Drafts broke that assumption.

The draft restore lived in useNoteSelection inside Notes, which only mounts while a note surface shows, so with zero notes nobody watched block transitions once the board unmounted.

How?

The marker is a real format, so rich text tracks its range through edits and the existing wrapInlineNote / removeInlineNote / updateNoteAnchor helpers do all the work; no store state and no editor-only format.

The front end already unwraps every mark.wp-note by class, so a marker saved mid-draft never leaks publicly; after a reload it stays as an inert tinted marker until the caret enters it (opens the form, Cancel strips it) or "Add note" runs on that block.

Known cost: the post is dirty while an inline draft exists and stays dirty after Cancel, since hasEditsForEntityRecord checks that a blocks edit exists, not that it differs.

Testing Instructions

1. Open a post with two paragraphs, select a word in the first one, and choose "Add note" from the block options menu. The word is highlighted.
2. Type a note, click the second paragraph, then click the first one again. The form returns.
3. Edit the paragraph before the word, then send the note. The marker wraps the word.
4. Start another note on a selection and press Cancel. The highlight is gone.

Screenshots or screencast

CleanShot.2026-10-06.at.19.49.21.mp4

Use of AI Tools

Assisted by Claude.

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +101 B (0%)

Total Size: 8.3 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	623 kB	+101 B (+0.02%)

_{3f5847d Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	9dc5831	trunk	% Change
timeToFirstByte	44.3 ms +6.21% -1.13%	44.25 ms +4.75% -2.49%	0.11%
largestContentfulPaint	80 ms +0% -7.5%	80 ms +0% -10%	0%
lcpMinusTtfb	30.2 ms +18.87% -5.46%	31.15 ms +14.61% -9.15%	-3.05%
wpBeforeTemplate	21.87 ms +11.39% -1.46%	21.52 ms +3.95% -0.56%	1.63%
wpTemplate	19.23 ms +3.07% -3.43%	18.81 ms +3.67% -1.97%	2.23%
wpTotal	41.11 ms +6.59% -0.97%	40.96 ms +4.83% -2.22%	0.37%
wpMemoryUsage	7.67 MB +0% -0%	7.64 MB +0% -0%	0.45%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	9dc5831	trunk	% Change
timeToFirstByte	36.6 ms +12.57% -3.28%	36.55 ms +4.38% -3.97%	0.14%
largestContentfulPaint	80 ms +7.5% -0%	80 ms +2.5% -0%	0%
lcpMinusTtfb	44.6 ms +3.14% -2.58%	43.55 ms +3.21% -2.99%	2.41%
wpBeforeTemplate	19.44 ms +13.32% -2.67%	19.17 ms +8.35% -1.98%	1.41%
wpTemplate	14.35 ms +1.74% -3.76%	14.13 ms +5.1% -2.55%	1.56%
wpTotal	33.88 ms +12.22% -3.98%	33.82 ms +4.58% -3.87%	0.18%
wpMemoryUsage	6.29 MB +0% -0%	6.25 MB +0% -0%	0.7%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	9dc5831	trunk	% Change
mediaProcessingJpeg	323.9 ms +1.12% -0.78%	323.92 ms +0.81% -0.95%	-0.01%
mediaProcessingAvif	4829.21 ms +0.17% -0.27%	4808.38 ms +0.14% -0.07%	0.43%
mediaProcessingJpegToAvif	3339.02 ms +0.28% -0.08%	3371.04 ms +0.13% -0.18%	-0.95%

media-upload

Metric	9dc5831	trunk	% Change
jpegUploadProcessing	1420.94 ms +1.2% -0.69%	1405.41 ms +0.84% -1.01%	1.11%
pngUploadProcessing	216.32 ms +34.36% -14.88%	186.14 ms +2.74% -7.55%	16.21%
largeJpegUploadProcessing	1401.37 ms +0.77% -0.26%	1407.36 ms +0.42% -0.3%	-0.43%
multipleImageUploadProcessing	1480.96 ms +0.51% -1.8%	1484.17 ms +0.23% -0.66%	-0.22%

post-editor

Metric	9dc5831	trunk	% Change
serverResponse	496.22 ms +4.98% -3.6%	514.01 ms +2.67% -2.88%	-3.46%
firstPaint	241.74 ms +17.18% -8.29%	273.58 ms +12.25% -8.21%	-11.64%
domContentLoaded	1130.01 ms +2.04% -1.61%	1137.92 ms +1.9% -2.44%	-0.7%
loaded	1131.44 ms +2.02% -1.63%	1139.27 ms +1.89% -2.43%	-0.69%
firstContentfulPaint	464.14 ms +3.08% -1.93%	467.4 ms +5.06% -2.55%	-0.7%
firstBlock	3414.15 ms +1.98% -1.51%	3437.24 ms +1.08% -2.46%	-0.67%
type	18.23 ms +9.43% -4.99%	20.35 ms +2.85% -2.11%	-10.42%
typeWithoutInspector	20.35 ms +0.93% -4.77%	18.9 ms +2.8% -2.75%	7.67%
typeWithTopToolbar	24.71 ms +6.72% -6.92%	24.56 ms +2.61% -6.19%	0.61%
typeContainer	9.54 ms +8.91% -4.61%	9.16 ms +6.66% -2.62%	4.15%
focus	117.42 ms +6.91% -2.06%	112.19 ms +1.73% -1.71%	4.66%
firstFocus	230.8 ms +0% -0%	225.65 ms +0% -0%	2.28%
selectAll	552.24 ms +15.29% -0.54%	549.01 ms +4.44% -6.55%	0.59%
listViewOpen	82.56 ms +5.08% -5.12%	80.32 ms +5.84% -6.88%	2.79%
inserterOpen	41.42 ms +9.51% -9.2%	43.97 ms +7.41% -9.55%	-5.8%
inserterHover	12.07 ms +13.75% -5.88%	12.88 ms +6.21% -6.21%	-6.29%
inserterSearch	8.76 ms +4.79% -8.9%	8.73 ms +8.48% -6.3%	0.34%
loadPatterns	663.64 ms +4.58% -6.81%	619.87 ms +7.59% -3.99%	7.06%
wpTotal	486.62 ms +4.93% -3.65%	503.94 ms +2.8% -2.95%	-3.44%
wpMemoryUsage	13.23 MB +0% -0%	13.20 MB +0% -0%	0.25%
wpDbQueries	54 +0% -1.85%	54 +0% -1.85%	0%

site-editor

Metric	9dc5831	trunk	% Change
serverResponse	238.1 ms +2.28% -0.96%	235.5 ms +3.74% -8.42%	1.1%
firstPaint	164.32 ms +16.44% -14.3%	188.27 ms +5.38% -25.33%	-12.72%
domContentLoaded	675.08 ms +3.35% -1.69%	682.95 ms +2.37% -2.22%	-1.15%
loaded	676.02 ms +3.34% -1.67%	683.94 ms +2.36% -2.22%	-1.16%
firstContentfulPaint	285.01 ms +0.28% -1.44%	297.47 ms +2.79% -4%	-4.19%
firstBlock	2447.16 ms +1.99% -1.25%	2419.24 ms +1.5% -0.71%	1.15%
type	11.9 ms +4.45% -2.35%	12.81 ms +0.86% -4.37%	-7.1%
navigate	85.11 ms +2.17% -14.5%	90.17 ms +1.65% -3.08%	-5.61%
loadPatterns	964.34 ms +10.54% -9.04%	879.01 ms +14.85% -15.92%	9.71%
loadPages	1018.55 ms +1.72% -0.55%	1012.94 ms +4.76% -3.39%	0.55%
wpTotal	232.09 ms +2.24% -1.18%	229.47 ms +3.83% -8.65%	1.14%
wpMemoryUsage	12.27 MB +0% -0%	12.23 MB +0% -0%	0.3%
wpDbQueries	43.5 +1.15% -1.15%	43.5 +1.15% -1.15%	0%

_{3f5847d Run}

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Navigates the items list via UP/DOWN arrow keys in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js, passed after 1 failed attempt.

Error: expect(locator).toBeFocused() failed

Locator:  getByLabel('Page Two')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" getByLabel('Page Two') with timeout 5000ms
  - waiting for getByLabel('Page Two')
    14 × locator resolved to <button type="button" tabindex="-1" aria-pressed="false" id="view-list-0-349-item-wrapper" class="dataviews-view-list__item" aria-labelledby="view-list-0-349-label" aria-describedby="view-list-0-349-description"></button>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js:146:49

_{3f5847d Run}

[Mamaduka]

A small, side effect of this change is that now selection is highlighted when you're adding the inline note. I think this creates a better connection between the text and the note.

[jasmussen]

It sounds like this mainly fixes a bug, nice one, thanks for iterating. Ship it after a code glance.

A small, side effect of this change is that now selection is highlighted when you're adding the inline note. I think this creates a better connection between the text and the note.

I like note highlights, in some of the mockups it's mostly opacity changes; semi-opaque when unselected, more opaque when selected. But I think since those mockups, to ensure contrast in every possible scenario, a colour-mixed bottom border may have been added as well in an unmerged PR, just something to remember (and an important one to land!)

But what's also important to remember: the colour of the marking is meant to be the user avatar colour of the person who left it:

I.e. even in its resting/unselected state, it should ideally retain some colour so you can glance who left it.

[Mamaduka]

But what's also important to remember: the colour of the marking is meant to be the user avatar colour of the person who left it

The placeholder marker uses the same highlighting system, and its color matches the current author.

[jasmussen]

Ah perfect, all good then. It just looked grey in one of the images, I guess that's just the unfocused text selection inside the iframe, rather than the final marking. Thanks.

[t-hamano]

This might be a bit of a stretch, but could we use @wordpress/annotations for draft note markers? For instance, we could have a core/note-draft annotation format, and once the draft is saved, it would be serialized into the content as core/note. I'm aware that using annotations for the note feature itself was initially discussed and ultimately rejected, but it might actually be the best fit for draft notes. What do you think? The advantage is that it prevents orphan note markers from being created in the content, but I think the downside is that the markers can become unstable.

That said, if this isn't the best approach, I'm completely fine with moving forward with this PR, as the benefits outweigh the downsides.

[Mamaduka]

Thanks, @t-hamano!

I looked at an editor-only format for the draft marker, including @wordpress/annotations, before going with the real core/note marker.

The main problem is that rich text only feeds annotation formats through select/dispatch. Annotations are built on the __experimentalGetPropsForEditableTreePreparation and __experimentalCreateOnChangeEditableValue hooks, so the range has to live in a store and be synced back through updateAnnotationRange on every change. That's the instability you mentioned: the range is tracked next to the content, not inside it. With a real marker, rich text tracks the range through edits on its own, and resolve/delete already strip and re-wrap markers the same way.

It would also add a new @wordpress/editor dependency and a store just for one temporary marker, and swapping it for core/note at submit means reading the range back from that store. That's a lot more code for the same visual result.

Orphans are limited. They only happen if the post is saved while a draft is open. The frontend unwraps every mark.wp-note by class, so the marker never shows publicly. In the editor, putting the caret inside it reopens the empty form, and Cancel strips it. If that becomes a real problem, we can look into sweeping stray new markers in a follow-up.

[adamsilverstein]

Overall this worked as expected testing in Playground. One thing I noticed that this PR makes more obvious I think is that while selections are highlighted when adding a note, but the block is not highlighted when adding a block level note. Which makes me wonder:

1. should we consider highlighting a block the user is leaving a note on and
2. could/should we just mark the entire block when a block level note is added, ideally removing the distinction between block and inline notes?

[adamsilverstein]

@Mamaduka thanks for picking this up, the draft-follows-edits behavior is a nice improvement. I ran a review pass and most of what turned up traces back to one choice: the new marker living in the real block content. I sketched a few ways forward below, your call on which (if any) makes sense.

Claude reviewed the diff and drafted the findings and options below:

Findings (not all verified in a browser yet):

1. The marker can leak. With an empty new note form open, clicking an existing thread in another block runs selectNote( threadId ) before the form's deferred focus-out, so getSelectedNote() === 'new' is already false and onDiscard is skipped. syncWithBlock also sees a non-new selection and skips its discard. The marker stays in the first block, tinted, and the post is dirty.

   gutenberg/packages/editor/src/components/collab-sidebar/add-note.jsx

   Line 58 in 4505a4a

   if ( getSelectedNote() === 'new' && ! hasDraft() ) {

2. Any leftover new marker gets adopted. onCreate calls removeInlineNote( attributes, 'new' ) unconditionally, so a stale marker (from 1, a reload, or an earlier session) becomes the anchor of a block-level note started from a collapsed selection.

   gutenberg/packages/editor/src/components/collab-sidebar/hooks.js

   Line 297 in 4505a4a

   const draft = removeInlineNote( attributes, 'new' );

3. Saved posts carry the marker. The PR notes the dirty-post cost, but the follow-on is that save or autosave writes <mark class="wp-note" data-id="new"> to post_content, and after a reload the caret entering it opens an empty form with no draft behind it.

   gutenberg/packages/editor/src/components/collab-sidebar/hooks.js

   Line 244 in 4505a4a

   onDiscard( clientId );

4. Real-time collaboration shares drafts. Every peer receives every other peer's new marker and tints it in their own color. If user B sends a note in that block, B's onCreate takes over user A's marker, and A's note later falls back to block-level.

   gutenberg/packages/editor/src/components/collab-sidebar/note-highlight-styles.js

   Line 76 in 4505a4a

   [ ...threads, { id: 'new', author: currentUserId } ],

5. Undo can drop the marker. updateNoteAnchor writes with history: 'ignore', so undoing an edit made before Add note restores a snapshot with no marker, and the note quietly sends as block-level.

   gutenberg/packages/editor/src/components/collab-sidebar/hooks.js

   Line 205 in 4505a4a

   };

6. useNoteSelection now runs in NotesSidebar unconditionally, including distraction-free and hidden display modes, where NoteFormat deliberately stays out of note selection (the canShowFloatingNotes guard). Leaving distraction-free mode can show a note already selected that the user never picked.

   gutenberg/packages/editor/src/components/collab-sidebar/index.jsx

   Line 72 in 4505a4a

   useNoteSelection( { notes, drafts, onDiscard } );

7. A split marker is only partly kept. If a paste or an edit inside the marked text splits the new format into two runs, removeNoteFormat strips both but findNoteRange returns only the first, so the saved note covers part of the highlighted text.
8. onStart discards and wraps in two separate persistent updates. If wrapInlineNote returns null, the old marker is gone with nothing in its place. Wrapping removed.value and writing once through updateNoteAnchor avoids both.

   gutenberg/packages/editor/src/components/collab-sidebar/hooks.js

   Line 251 in 4505a4a

   if ( wrapped ) {

9. All new markers share one selector, so drafts in two blocks light up together when either form opens.

Possible directions:

Option A - keep the marker in content, harden it. Smallest change, keeps the "rich text tracks the range for free" win.

• Give each draft its own id, eg. new-<userId>-<counter>, stored in the drafts Map, so onCreate only consumes its own marker. Fixes 2, 4 and 9, and the highlight CSS can skip other users' draft ids.
• Discard on the selectedNote transition away from new (a subscription in useNoteSelection) instead of relying on the form's focus-out. Fixes 1.
• Strip orphaned draft markers (ones with no entry in the drafts Map) once on editor load, and before save. Covers 3 for reloads, though the post still goes dirty while a draft is open.
• Gate useNoteSelection on the same canShowFloatingNotes condition. Fixes 6.
• Merge all runs in findNoteRange for draft ids, and fold onStart into a single update. Fixes 7 and 8.
• Leaves 5 open unless the marker write joins normal history, which brings its own oddity (undo strips the marker while the form stays open).

Pros: small, builds on what is already here, the anchor follows edits. Cons: the post is still dirty while drafting, an editor-only concept still round trips through post_content and the collaboration doc, and every new entry point needs its own cleanup path. That last one is how 1 happened.

Option B - keep the draft out of content. Store { attributeKey, start, end, text } in the drafts Map at onStart, and paint the highlight with a non-persisted rich text decoration (the format type's __experimentalCreatePrepareEditableTree hook, the same mechanism @wordpress/annotations uses) instead of a saved format.

• On send, check that the stored range still matches text. If not, search the attribute for text, and fall back to block-level only when it cannot be found.

Pros: fixes 1 through 5 and 9 by construction. No dirty post, nothing saved, nothing synced to collaborators, undo is untouched. Cons: the range no longer follows edits automatically, so step 3 of the testing instructions relies on the text match, which can pick the wrong spot for a repeated word. It is also the "editor-only format" the PR set out to avoid, and the decoration API is still experimental.

Option C - capture the range only, no highlight. Same storage as B without the decoration.

Pros: the smallest fix for the original bug, where the selection is lost on canvas click. Cons: no visual cue while drafting, which is a regression from this PR's UX, and it has the same edit-tracking limits as B.

If the follow-the-edits behavior is the main goal, A is the shortest path. If keeping drafts out of saved content and the collaboration doc matters more, B is cleaner long-term.

Happy to help with whichever direction you pick.

[Mamaduka]

Thanks, @adamsilverstein!

I'm going with A and keeping the marker in content. B is the editor-only format I looked at in #84125 (comment), and I tried a range snapshot like C first; without a marker, a stale anchor is invisible to the user.

• 1: The caret-driven selection PR (Notes: Select the note under the caret #84147), which lands together with this one, fixes it for other blocks and markers. Picking another note in the same block still leaks; I'll fix that there.
• 2, 3: Accepted cost for now; the same way saved note markers already live in the content (the frontend unwraps both). If feedback shows it's a problem, the rough follow-up plan is to sweep orphaned new markers once on load, then strip them before save if that's still not enough.
• 4: RTC is still experimental and doesn't ship with WP. I'll revisit it, likely with per-user draft IDs, when it does.
• 5: Same as every other anchor written through updateNoteAnchor. It was an accepted trade-off when that landed.
• 6: Fixed. The distraction-free check now lives in NotesSidebarContainer, next to the code editor and revisions checks. In hidden mode, selection follows the caret by design.
• 7: Pre-existing in findNoteRange; delete → Undo restores a partial marker too. I'll fix it separately in the helper.
• 8: Intentional, simpler than merging the two updates.
• 9: Cosmetic, and it only shows with drafts open in two blocks.

[Mamaduka]

7: Pre-existing in findNoteRange; delete → Undo restores a partial marker too. I'll fix it separately in the helper.

Realized this was a general RichText issue. A format shouldn't split on paste or edit. Fixed separately in #84303.

[t-hamano]

Last feedback: It seems that an empty floating notes area can appear when a block has resolved notes. For example:

1. Create a new post with a paragraph.
2. Add a note to the paragraph, then click "Resolve" on its floating thread.
3. Click the post title.
4. Click the paragraph.
5. An empty "Unresolved notes" area appears. On trunk, nothing appears.

empty-floating-note-area.mp4

Suggested change

	// Here rather than in `Notes`, which unmounts with its surface: a draft
	// must be restored on block selection even while no note is shown.
	useNoteSelection( { notes, drafts, onDiscard } );
	// Here rather than in `Notes`, which unmounts with its surface: a draft
	// must be restored on block selection even while no note is shown. Sync
	// against the threads the open surface lists: floating notes omit resolved.
	useNoteSelection( {
	notes: isAllNotesSidebarOpen ? notes : unresolvedNotes,
	drafts,
	onDiscard,
	} );

This change seems to fix it.

[Mamaduka]

Thanks, @t-hamano!

I'm refactoring selection handling in #84147. That bug seems more suitable there, IMO. Noted, and I'll try to fix it here.

[t-hamano]

I see. In that case, I think this PR is good to merge as is 👍

[adamsilverstein]

Nice work!