Notes: inline (partial-text) notes via hybrid marker + strip-on-render approach

[adamsilverstein]

What?

Implements inline (partial-text) Notes — the next milestone in #59445, listed as a WordPress 7.1 deliverable in #76316.

Hybrid of the two earlier exploration PRs from @Mamaduka:

• #74852 — annotations-based decoration (clean frontend HTML, but offsets drift on edits).
• #75206 — core/note rich-text format (resilient anchoring, but pollutes frontend HTML).

This PR uses core/note as the in-content anchor so the marker survives edits, and strips the span wrapper on render_block so public HTML stays clean. Visual highlight is applied via @wordpress/annotations so the styling rides on existing infrastructure.

Closes #59445.

Test in Playground

https://playground.wordpress.net/?gutenberg-pr=78218

For testing with multiple users, try the User Switching Plugin - https://wordpress.org/plugins/user-switching/

Stacked on

Builds on #75147 (multi-note per block). The array shape from #75147 is required so a single block can carry multiple inline notes. Base for review: add/enable-multiple-notes-per-block — change to trunk once #75147 merges.

Screenshots/Screencast

Adding a note

user.adds.note.mp4

Notes from 4 users - notes are sorted by the order they appear in the block

Overlapping note handling

The new note truncates the previous selection

Q: what happens if a new note completely replaces the old note selection (is it lost)?

Code view in editor showing mark tags

Front end: marks are stripped

Notes sidebar still uses (reverse) chronological order

How?

Storage

• New comment meta _wp_note_selection = { attributeKey, start, end } registered in lib/compat/wordpress-6.9/block-comments.php. Fallback anchor when the in-content marker can't be found.
• metadata.noteId array (from Notes: Support multiple note threads per block #75147) tracks which threads belong to a block — inline notes are added to it like block-level notes.

Anchoring

• New core/note rich-text format, registered in packages/editor/src/components/collab-sidebar/format.js. Serializes as <span class="wp-note" data-id="N">…</span>.
• useNoteActions.onCreate now captures a non-collapsed in-rich-text selection, saves the comment with _wp_note_selection meta, and wraps the selected text with the core/note format.
• findNoteRange( richText, noteId ) (new in utils.js) scans a rich-text record for the marker and returns its current { start, end } — meaning offsets re-derive after edits rather than going stale.

Frontend HTML stays clean

• gutenberg_strip_inline_note_markers() is hooked to render_block. It unwraps <span class="wp-note">…</span> so the public output never contains the marker, while raw post_content (and the REST raw view, revisions, exports) keeps the mark so the editor can re-attach on reload.

Visual decoration

• New useAnnotateBlocks hook reads unresolved threads, prefers findNoteRange for offsets, falls back to the stored meta, and registers each range with the annotations store under the core-note source.
• New CSS at .annotation-text-core-note uses admin-theme tinting at 20% / 40% opacity (matching @jasmussen's design comment in Inline block commenting  #59445). Always visible — no need to open the sidebar.

Forward compatibility with Yjs / CRDT

Real-time collaboration with Yjs is on the roadmap (see crdt-blocks.ts work). The architecture here is intentionally shaped so the inline-note feature carries over with a single, localized swap rather than a rewrite:

• Offsets are derived, not stored. findNoteRange re-scans the rich-text record for the marker on every read. There are no absolute indices baked into the document. This matches how CRDT positions work — they are references that resolve to current offsets, never frozen ones. When Yjs lands, findNoteRange is the single function that switches from "scan for marker" to "resolve Y.RelativePosition / yjs range," and every consumer (useAnnotateBlocks, sidebar, anchor preview) keeps working unchanged.
• Threads are linked by identity, not by position. The marker carries data-id="N" and the block's metadata.noteId array stores comment IDs. The thread ↔ anchor relationship is identity-based, which is the same model a yjs-anchored range would use (a stable id pointing at a CRDT range). Migrating means swapping the anchor representation, not the linkage model.
• Visual decoration is decoupled from persistence. Annotations are computed at runtime from (content, threads) and never written back into the content or the store. Whatever produces { start, end } — today the marker, tomorrow a yjs range — feeds the same useAnnotateBlocks pipeline. The styling layer is yjs-ready as-is.
• The strip filter is one removable hook. gutenberg_strip_inline_note_markers() is a single render_block filter in one file. When CRDT anchoring replaces the in-content marker, deleting that filter (and the core/note format registration) is the entire frontend-cleanup story — no scattered cleanup across rendering, REST, or export paths.
• Meta-based fallback survives the migration. _wp_note_selection is stored on the comment, not on the block. It already works without the in-content marker, so it remains a valid fallback during and after a CRDT migration (e.g., for legacy posts authored before yjs was enabled).
• Multi-note array shape (Notes: Support multiple note threads per block #75147) is CRDT-friendly. metadata.noteId is an unordered set of IDs per block — no positional coupling between the array order and where the notes anchor in text. Cross-block notes (#73416) and yjs-anchored notes both fit this shape without schema changes.

Net effect: when crdt-blocks.ts exposes range/position primitives, the migration is roughly (1) swap the body of findNoteRange, (2) drop the core/note format + strip filter. The data model, the sidebar, the annotations decoration, and the storage in comment meta all carry over.

Testing instructions

1. Open a post or page.
2. In a paragraph, select part of the text → click the "Add note" button in the toolbar (when text is selected, the rich-text toolbar shows the comment icon).
3. Confirm the selected text gets the theme-colour highlight.
4. Add a second inline note in the same block on different text — both decorations visible, both threads in the sidebar.
5. Type inside the marked range — the highlight expands/contracts with the text.
6. Save the post → view it on the frontend → no <span class="wp-note"> in the HTML, content reads cleanly.
7. Reload the editor → marks and decorations re-attach to the original text.
8. Resolve a note → its decoration disappears; reopen → reappears.

Automated tests

• JS: 7 new cases in test/utils.js for findNoteRange covering RichTextData/string input, id matching/mismatch, numeric/string coercion, and null guards. 63 total in this suite, all passing.

  npm run test:unit -- --testPathPattern=collab-sidebar
  

• PHP: 6 new cases in phpunit/tests/strip-inline-note-markers-test.php covering single/multiple wrappers, no-op when no marker, classes alongside others, unrelated spans, and end-to-end render_block filter behavior.

  composer test -- --filter Strip_Inline_Note_Markers
  

Follow-ups (out of scope)

• UI polish — anchor preview on each inline thread + unresolved/resolved divider in the All notes sidebar — is stacked in #78219 and reviews independently of this PR.
• Floating "Add note" button next to the live text selection (Medium / Google Docs pattern). The rich-text toolbar button registered here already provides the create-on-selection entry point; the popover variant is tracked separately in #78220.
• E2E coverage for the full create → save → frontend strip → reload round-trip. Deferred to a follow-up PR since it needs careful interaction with the rich-text floating toolbar.
• Cross-block inline notes #73416 — the array noteIds shape from Notes: Support multiple note threads per block #75147 supports this; UI/storage work is its own iteration.
• CRDT/Yjs anchoring path — see Forward compatibility with Yjs / CRDT above. When crdt-blocks.ts exposes range primitives, retire the in-content marker in favor of CRDT-anchored ranges and remove the strip filter.

AI usage

Implementation drafted with Claude Code: spec, plan, and code. Plan reviewed and approved by me before edits, all commits and the PR reviewed before push.

Refs #59445, #76316.

[Mamaduka]

I think this is ready to merge. The real user testing is what we need right now; we can always iterate on code rough edges in post.

Left a minor note. The annotations package is still referenced in the TS config.

[adamsilverstein]

@westonruter this pr says you are requesting changes, please give it another pass I believe I have addressed everything.

[westonruter]

A couple minor comments, but the PHP LGTM. (The JS I'm not familiar with, so I'll let others more qualified approve that.)

[westonruter]

Suggested change

	private function get_span() {
	private function get_span(): WP_HTML_Span {

[westonruter]

Or will this method rather be removed as was done in WordPress/wordpress-develop#12215?

[westonruter]

Suggested change

	public function remove_token() {
	public function remove_token(): void {

[adamsilverstein]

@westonruter the PR merged automatically with your approval; i will address your feedback in a follow up.