Description

Currently, each block can have at most one top-level note attached to it. Subsequent notes are always forced to be a reply to the existing thread. This is because the block→note relationship is created by storing a single noteId in the block's metadata (block.attributes.metadata.noteId).

This limitation causes issues in several scenarios:

Related Issues

• Note appears as being attached to a deleted block when two users add them at exactly the same moment using real-time collaboration #74751
• [Experimental] Notes: Support partial text selection notes #74852 - Only the first text selection starts a new thread

Current Implementation

The current code in packages/editor/src/components/collab-sidebar/hooks.js:

1. Creates a 1:1 mapping: blocksWithComments[clientId] = commentId (single value)
2. Overwrites on create: When a new note is created during collaborative editing before a sync, it overwrites any existing note (instead of having two separate top level notes added)
3. Clears entirely on delete: Removes the entire noteId instead of a specific ID

Proposed Solution

Extend the existing noteId field to support either a scalar (number) or an array (number[]):

• Backwards compatible: Existing posts with scalar noteId values work unchanged
• Lazy migration: Scalar converts to array only when a second note is added
• Same field name: No new metadata field required

Implementation Changes

1. Add utility functions to normalize noteId handling:

   • getNoteIdsFromMetadata() - returns array for both scalar and array input
   • addNoteIdToMetadata() - appends to array
   • removeNoteIdFromMetadata() - removes specific ID from array

2. Update useBlockComments() hook to build array-based mappings

3. Update onCreate() to append rather than overwrite

4. Update onDelete() to remove specific ID from array

5. In floating notes mode, the first added note is aligned with the block and subsequent notes are placed below that.

Benefits

• Fixes real-time collaboration race condition (Note appears as being attached to a deleted block when two users add them at exactly the same moment using real-time collaboration #74751)
• Enables multiple independent note threads per block
• Supports future features like partial text selection notes ([Experimental] Notes: Support partial text selection notes #74852)
• Fully backwards compatible with existing content