Fix/79643 rtc awareness mixed block selection

[giteshsarvaiya]

What?

Closes #79643

Fixes RTC selection awareness for multi-block selections that span mixed block types (e.g. paragraph → image, heading → video). Previously the overlay rendered nothing when a collaborator's selection included any block without a RichText field. After this PR, text blocks show a semi-transparent fill overlay and non-text blocks show a CSS outline border, with a single avatar on the topmost block.

Why?

When a collaborator selects across multiple blocks, the awareness system sends two endpoints — one for each side of the selection. Both endpoints were treated identically, as if they always carried a character-level cursor position. Blocks without a RichText field (image, spacer, button, etc.) have no character position, so resolving the endpoint threw and the overlay silently produced nothing for the entire selection.

Beyond fixing the immediate bug, this PR also makes the collaborators overlay significantly more maintainable going forward:

• Type safety at the data layer: the new SelectionEndpoint discriminated union means TypeScript will catch any misuse at compile time. Before this PR, a caller could pass a text cursor position to code expecting a block position with no error — the failure only surfaced at runtime in the overlay.
• Dead code removed: getFullBlockSelectionRects and an always-empty MultiBlockResult.rects field were removed rather than left dormant.
• Consistent naming: CursorEndpoint / WholeBlockEndpoint align with the existing SelectionType.Cursor / SelectionType.WholeBlock enum values already used throughout the codebase.
• Documented non-obvious decisions: the Yjs anchoring strategy, direction-normalisation requirement, and avatar placement rule are now explained inline.

Visual approach: why not CSS outline for all blocks?

An earlier version of this PR used a CSS outline (is-collaborator-selected class + --collaborator-outline-color) applied uniformly to every block in the selection range. This was simple to implement but had meaningful drawbacks. The current PR uses a two-track approach instead.

CSS outline only (previous approach)

Pros	Simple — one rendering mechanism for all block types. Works regardless of block content or type. No dependency on DOM Range API or font rendering.
Cons	A thin border around a block does not read as "selected" — users expect a fill for selected content, not just a border. Does not match what the doer sees (they see a blue fill; the observer saw a box). The entire last block was shown as selected even when only a partial selection reached into it, making the overlay misleading for long paragraphs.

Mixed overlay + border (current approach)

Pros	Text blocks get a semi-transparent fill (15% opacity) that reads unmistakably as "selected content." Non-text blocks (image, spacer) get a CSS border — correct, because you cannot meaningfully highlight text inside an image. The last block in the selection shows only the selected portion via text-level DOM Range rects, so the visual accurately mirrors what the doer selected. Overall closer to how every other collaborative editor (Google Docs, Notion, Figma) represents remote selections.
Cons	Two rendering paths add complexity. Text block detection uses innerText.trim() as a heuristic — an empty paragraph block would be treated as a non-text block and shown with a border instead of a fill. Partial text-level rects for the last block depend on the DOM Range API and a fallback element-resolution chain, which could theoretically fail for unusual custom blocks.

The heuristic tradeoffs are acceptable: empty blocks carry no content to highlight, and the fallback chain ([data-wp-block-attribute-key] → [contenteditable] → p/h1-h6/…) covers all standard Gutenberg blocks.

Bugs fixed

Mixed-type multi-block selection renders nothing — When the selection spanned a non-text block (image, spacer, video), the overlay produced nothing. The root cause: both endpoints were resolved as if they always carried a character-level cursor position. Non-text blocks have no Y.Text anchor, so getCursorPosition returned null and the entire selection was dropped silently. Fixed by introducing a SelectionEndpoint discriminated union (CursorEndpoint / WholeBlockEndpoint) so each endpoint is resolved via the correct anchor type independently.

WholeBlock keyboard selection as an endpoint renders nothing — Selecting an image block via keyboard (Alt+click / arrow navigation) produces a WholeBlockEndpoint with no character offset. use-render-cursors had no branch for this — it fell through to single-block logic, resolveSelection threw, and the selection was dropped. Fixed by the same discriminated union: WholeBlockEndpoint is now resolved via its Y.Array slot position rather than a Y.Text offset.

Ctrl+A (select entire post) not visible to collaborators — Ctrl+A produces a SelectionInMultipleBlocks with WholeBlockEndpoint on both sides. The overlay had no path for this combination — the entire selection was silently dropped, so collaborators saw nothing. Fixed as a consequence of the two changes above: both endpoints are now resolvable regardless of block type.

Backward selection also works — All three fixes above apply regardless of selection direction. Endpoints are normalised to DOM order internally before any rect computation, so dragging from image → paragraph is identical to paragraph → image on the observer's side.

List block showing per-item stripes instead of one unified highlight — When a selection endpoint lands inside a list, Yjs resolves it to the specific core/list-item (the innermost block with a Y.Text), not the parent core/list. The sibling list-items between that endpoint and the other selection end then appeared as individual middle blocks, each getting its own fill rect, producing a striped banded look rather than one rect covering the whole list.

The fix promotes each endpoint to its nearest [data-block] ancestor before computing rects:

// cursor-dom-utils.ts — new helper
export const blockContainerOf = ( el: HTMLElement ): HTMLElement =>
    el.parentElement?.closest< HTMLElement >( '[data-block]' ) ?? el;

blockContainerOf walks up the DOM from the resolved endpoint element and returns the nearest element with a data-block attribute — the parent block. If the element is already a top-level block it returns itself unchanged.

Applied in computeMultiBlockOverlayRects:

const effectiveFirstEl = blockContainerOf( docFirstEl ); // list-item → list block
const effectiveLastEl  = blockContainerOf( docLastEl  ); // paragraph → itself (no parent)

const middleEls = getBlocksBetween( effectiveFirstId, effectiveLastId, editorDocument )
    .filter( el => ! effectiveFirstEl.contains( el ) && ! effectiveLastEl.contains( el ) );

With effectiveFirstEl = the list block, getBlocksBetween(listId, joId) returns the list-items in the DOM range — but the .filter removes every element the list block .contains(), which is all of them. middleEls becomes empty. The list block is then rendered as a single full bounding-box rect covering all its items.

When both endpoints promote to the same container (e.g. selecting from list-item 1 to list-item 3, all inside one list), an early return emits exactly one rect for the container:

if ( effectiveFirstId && effectiveFirstId === effectiveLastId ) {
    return effectiveFirstEl.innerText?.trim()
        ? { selectionRects: [ blockBoundingRect( effectiveFirstEl, overlayRect ) ] }
        : {};
}

Approaches considered and rejected:

1. Skip descendants of start/end elements in getBlocksBetween — Would work when the list block itself is the endpoint, but not when a list-item is the endpoint: siblings of a list-item are not its descendants, so no filtering would occur.

2. Post-process middleEls to merge consecutive items with the same [data-block] parent — Works but requires an extra DOM traversal per middle block and couples the merging logic to the iteration order. More moving parts for the same outcome.

3. Promote before DOM-order normalization — Direction normalization uses the raw endpoint elements for isNodeBefore comparison. Promoting first would compare container elements, which could give wrong ordering when both endpoints share the same container.

The chosen approach — promote after normalization, filter descendants, check equality — is one helper function, two .contains() calls, and one equality check. It generalises to any nesting depth (columns inside groups, etc.) without additional code.

---

Video of behavior before this PR

before.mp4

Video of behavior after this PR

after-fixing-multiselect.mp4

---

How?

The fix is split across 5 commits, layered from the data model up to the overlay rendering.

---

Commit 1 — core-data: add CursorEndpoint/WholeBlockEndpoint discriminated union

Introduces a SelectionEndpoint discriminated union so the receiver knows how to resolve each side of a multi-block selection:

• CursorEndpoint (kind: 'cursor'): the endpoint lands inside a RichText field with a known character offset. Anchored to a Y.Text relative position. Any block type can produce this — a paragraph mid-word, a table cell, a heading.
• WholeBlockEndpoint (kind: 'whole-block'): no character offset — either the block has no RichText field (image, spacer) or it is selected as a whole block via keyboard. Anchored to the block's slot in its parent Y.Array.

getSelectionEndpoint tries a Y.Text anchor first; if the selection carries no character offset it falls back to the Y.Array slot anchor.

Also updates all test fixtures and assertions to use the renamed endpoint types.

---

Commit 2 — editor: fix getBlocksBetween to skip blocks already covered by a parent

getBlocksBetween previously returned all [data-block] elements between the two endpoints, including nested ones. Selecting a list block would return both the list and each of its list items, causing every item to be double-highlighted.

The fix: skip any block element that is a descendant of a block already in the result. JSDoc updated to reflect the new behaviour.

---

Commit 3 — editor: handle SelectionInMultipleBlocks in the collaborators overlay

The main fix. Three files change together as one logical unit:

use-render-cursors — a dedicated branch now resolves each endpoint independently via its kind discriminant, avoiding the throw that occurred for non-text endpoints.

compute-selection — the multi-block path is wired up; no cursor coords are emitted (avatar comes from use-block-highlighting only). MultiBlockResult.rects (always empty) and getFullBlockSelectionRects (no callers) are removed as dead code.

use-block-highlighting — extended to cover SelectionInMultipleBlocks. Resolves start/end block IDs, normalises to DOM order, collects intermediate blocks via getBlocksBetween, applies highlights, and places the avatar on the topmost block only. Non-obvious decisions (Yjs direction normalisation, avatar placement rule, as any cast) are documented inline.

---

Commit 4 — editor: mixed visual treatment for multi-block awareness (overlay + outline)

Replaces CSS-outline-only highlighting with a two-track visual system:

Text blocks (innerText.trim() is non-empty — paragraph, heading, list, etc.):

• Full bounding-box semi-transparent fill (15% opacity) via selectionRects
• First block: full bounding-box when cursor starts at offset 0; partial text-level rects when it starts mid-block
• Middle blocks: always the full bounding-box
• Last block: always partial text-level rects from 0 to the cursor offset, so the unselected tail is not covered

Non-text blocks (image, spacer — innerText empty):

• CSS is-collaborator-selected outline only; no fill so image content is not obscured

Also in this commit:

• Stale CSS class bug fixed: is-collaborator-selected is reset for every block on each render before being conditionally re-applied, preventing it from persisting when a block transitions between selection types
• resolveTargetElement gets a richer fallback chain ([data-wp-block-attribute-key] → [contenteditable] → p/h1–h6/pre/blockquote/…) so partial text rects work even when the block is not actively focused by the observer
• Text block detection uses innerText.trim() because [contenteditable="true"] and [data-wp-block-attribute-key] are absent on blocks the observer has not clicked into

---

Commit 5 — editor: promote inner blocks to container for multi-block highlights

Fixes the list-item striping bug described in Case 4 above. See the Case 4 section for a detailed explanation of the root cause, the fix, and the approaches considered.

Key additions:

• blockContainerOf helper exported from cursor-dom-utils — single responsibility, reused in both compute-selection and use-block-highlighting
• Promotion applied to both endpoints before getBlocksBetween and before building the CSS outline block list, so both the fill-overlay path and the CSS-border path treat the container as one unit
• Same-container equality check prevents emitting two rects when both endpoints happen to be inner blocks of the same parent

After running /code-review in a Claude Code (Sonnet 4.6) session, four additional bugs were found and fixed:

Commit 6 — isNodeBefore bitmask

compareDocumentPosition returns a bitmask, not an exact value. The strict
=== Node.DOCUMENT_POSITION_FOLLOWING check (=== 4) returned false when b
was a following descendant of a (result is 4 | 16 = 20), silently skipping
DOM-order normalization for nested endpoint pairs. Fixed with a bitwise AND check.

Commit 7 — blockContainerOf over-promotion

el.parentElement?.closest('[data-block]') walked arbitrarily far up the ancestor
chain. A core/list inside core/group has a non-[data-block] wrapper div
between them, so closest() would skip past the list and promote to the group —
wrong block highlighted. Fixed by checking only the immediate parentElement.

Commit 8 — null endpoint guard in use-block-highlighting

When an endpoint block is absent from the DOM (concurrent deletion),
effectiveFirstEl was null. null?.contains(el) returns undefined,
!undefined is true, so every intermediate block passed the containment
filter — spuriously highlighting the entire range. Fixed with an early return
when either endpoint element is missing.

Commit 9 — move inner-block promotion to use-render-cursors

computeMultiBlockOverlayRects is a pure computation function; DOM-based
inner-block promotion was an architectural mismatch. Moved the promote step to
use-render-cursors where resolved endpoints are built, before
computeSelectionVisual is called. computeMultiBlockOverlayRects now receives
container-level IDs directly and drops the effectiveFirstEl/wasPromoted
variables.

---

Testing Instructions

1. Start wp-env with RTC enabled and open a post with paragraphs, an image block, and a heading.
2. Open the same post in a second browser window as a different user.
3. In window 1, drag a selection from the paragraph through the image into the heading.
4. In window 2, verify:
   • Paragraph and heading show a semi-transparent fill overlay
   • Image block shows a CSS border outline (no fill)
   • Avatar appears on the topmost selected block only
5. In window 1, drag a selection that ends partway through a long paragraph.
6. In window 2, verify only the selected portion of the paragraph is highlighted — the unselected tail has no overlay.
7. Drag in reverse (heading → paragraph) — result should be identical to step 4.
8. Press Ctrl+A in window 1. In window 2, verify all blocks show the appropriate highlight.
9. In window 1, drag a selection from a paragraph through a list block into another paragraph.
10. In window 2, verify the list block shows as one unified fill rect — not one rect per list item.
11. Verify no regressions:
    • Single-block text selection still shows highlight rects and a cursor label
    • Selecting a single image block (whole-block selection) still shows CSS outline and avatar
    • A cursor with no selection still shows the cursor label

Known issue discovered during testing

Reproduction: User A has a multi-block selection active. User B (the observer) deletes the first or last block of that selection. On User B's screen, the entire awareness overlay for User A disappears — both the selection highlight and the avatar. On User A's screen, their own selection also clears shortly after (once Yjs syncs the deletion).

Root cause — two contributing layers, both pre-existing:

1. Rendering layer: When an endpoint block is deleted from the DOM, computeMultiBlockOverlayRects can no longer find it by [data-block] selector and returns {}, clearing all rects. This is the same defensive early-return behaviour trunk already uses for single-block WholeBlock selections — deleting a keyboard-selected block causes its CSS outline to disappear there too. Deleting a middle block does not trigger this — only the first or last block (the selection endpoints) causes the early return.

2. Yjs layer: Once the deletion syncs to User A, their Y.RelativePosition anchor for the deleted endpoint block can no longer be resolved. resolveSelection throws, the try/catch swallows it silently, and awareness clears on User A's side too. This exists on trunk independently of this PR.

Question for reviewer: Should this be fixed here, or tracked as a separate issue?

Arguments for fixing here: the rendering-layer half of the bug is in code directly touched by this PR. A partial fix — falling back to the remaining valid blocks when an endpoint block is deleted — could be made here without touching the Yjs layer.

Arguments for a separate issue: fully eliminating the bug also requires fixing the Yjs Y.RelativePosition resolution on User A's side, which is out of scope for a rendering-focused PR. Tracking the full fix as a follow-up keeps this PR focused.

I feel I should open a separate issue, hence I am opening one, but thats just what I think, let me know your thoughts.

Edit: the new issue at #79867

Notes

• getBlocksBetween behaviour changed (descendant filtering). It has no callers outside the overlay folder and is not in the editor package's public API barrel — low risk.
• getFullBlockSelectionRects was removed. Same scope caveat.
• This PR does not fix RTC: Awareness redraws are not immediate on window resize events #79645 (details block awareness) — that is a separate issue and will be a follow-up PR.

Use of AI Tools (updated)

This PR was developed with AI assistance (Claude Code, Sonnet 4.6) across two sessions:

• Initial implementation: feature development, bug investigation, and commit structuring.
• Post-implementation review: the /code-review command in Claude Code surfaced 6 findings (3 correctness bugs, 1 null-safety bug, 2 efficiency/architecture issues). Bugs 1–3 and the architectural finding were fixed in commits 6–9 above. The two efficiency findings (getBlocksBetween O(n²) scan and missing loop break) were deferred as low-priority given realistic document sizes.

All changes were reviewed and verified by me before submission.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @giteshsarvaiya! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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: giteshsarvaiya <giteshsarvaiya@git.wordpress.org>
Co-authored-by: alecgeatches <alecgeatches@git.wordpress.org>
Co-authored-by: ingeniumed <ingeniumed@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

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

[giteshsarvaiya]

@props-bot refresh

[giteshsarvaiya]

Hi @nerrad ! I'm working on this issue — the bugs reported by @alecgeatches are now resolved.
I'm currently testing to confirm no new regressions are introduced by the PR. So far, I've tested all the edge cases I could think of and haven't found any new issues. I'll take one more day to finish verifying before converting this out of Draft.
In the meantime, feel free to check out the PR — it already implements the fix for the reported bugs.

[ingeniumed]

👋🏾 @giteshsarvaiya I've added @alecgeatches and I as reviewers on your PR. Could you fix the merge conflicts and we can take a look? Thanks for putting it up!

[giteshsarvaiya]

@ingeniumed @alecgeatches Thanks for taking a look! I've resolved the merge conflicts. Looking forward to your feedback.

[alecgeatches]

I see the explanation in the comments, but I'm not sure why we need these two new types. CursorEndpoint appears to contain exactly the same data as SelectionCursor, and WholeBlockEndpoint also matches SelectionWholeBlock.

If we need the endpoint concept, can we use a type SelectionEndpoint = SelectionCursor | SelectionWholeBlock instead and reuse the same inner types? I think we could also drop areEndpointsEqual() and related endpoint-specific functions in this PR unless we need a new wrapping type for a good reason.

[alecgeatches]

This element-finding logic overlaps with computeMultiBlockOverlayRects() (get DOM elements, find nodes between). Could we extract shared logic and use the same in both places? Ideally this will reduce useBlockHighlighting's size at it's getting pretty big, and also make the logic between the two functions exactly the same.

[alecgeatches]

usersWithAvatar should probably use user IDs instead of colors, since we only have 7 colors built-in. It's okay if multiple users have the same color when more than 7 users are present, but I think this logic will skip any users after the first 7.

[alecgeatches]

@giteshsarvaiya Thank you for your work here! I left some code comments above, and also noticed that scroll-to-avatar stops working with multiblock selection:

scroll-to-avatar.mov

Above, I show clicking an avatar works for selection within a block, but when a user has multiblock selection running the jump-to-avatar button doesn't work anymore.

Overall I think this works well and didn't see any other issues in my testing. I'd like to take another run once you've had a look at the code comments, but I think this looks pretty good already.

[giteshsarvaiya]

Thanks @alecgeatches for the review and the walkthrough video, it made the issue easy to reproduce.

I've addressed all four points:

• Fixed the scroll-to-avatar regression.
• Switched usersWithAvatar to key by user ID.
• Dropped the redundant CursorEndpoint/WholeBlockEndpoint types in favour of SelectionEndpoint = SelectionCursor | SelectionWholeBlock.
• Extracted the shared querySelector + normalise + promote + middle-blocks pattern into a getOrderedBlockRange helper in cursor-dom-utils.ts, now used by both useBlockHighlighting and computeMultiBlockOverlayRects.

The PR is ready for a second round of review.

[alecgeatches]

@giteshsarvaiya Good job on the fixes! I ran through testing and all is working well for me. I'm seeing one failed e2e run, doubt it's related, will see if that passes with a trunk merge. Thank you!

[giteshsarvaiya]

hooray! the tests passed.

[ingeniumed]

I've gone ahead and merged this in. Thanks for working on this!