Problem

Text-selection comments currently have two competing presentation modes:

In the comments/discussions panel, the focused selection can be shown as a compact fragment card.

Inside embedded comment content, block fragment embeds can still render as a full block with range highlighting.

The full-block rendering is useful for context, but it is too tall and visually heavy for comment threads, replies, and embedded discussions. It also makes a short selected phrase feel secondary to the surrounding paragraph.

This creates a mismatch: users are commenting on a specific selected fragment, but the UI often presents the entire source block as the primary object.

Solution

Introduce a reusable Block Fragment Annotation Card for block-range links and text-selection comments.

The card renders only the selected fragment as the primary content, with a small label indicating that it is selected text. The selected fragment keeps the source text formatting, including annotations such as bold, italic, code, links, and inline embeds.

Expected behavior:

Text-selection comments show the fragment card by default.

Block fragment embeds use the same fragment card when the embed link includes a valid block range.

Non-fragment block embeds continue to render as they do today.

Invalid or unsupported ranges safely fall back to the existing full-block renderer.

Suggested demo materials to add:

Screenshot/video of the old full-block highlighted embed.

Screenshot/video of the new compact fragment card in the discussions panel.

Screenshot/video of the same card used inside a comment embed.

Example with rich formatting inside the selected range.

Scope

Estimated implementation scope: 1–2 development days.

Completed / expected work includes:

Create a reusable BlockFragment UI component.

Extract selected text ranges by Unicode codepoint offsets.

Preserve and shift inline annotations for the selected fragment.

Integrate the card into text-selection comments.

Integrate the same card into block-fragment embeds.

Preserve existing fallback behavior for unsupported fragments.

Add focused tests for fragment extraction and component rendering.

Run typecheck and targeted tests.

Additional polish, if desired, can be handled as follow-up work:

Final visual tweaks after design review.

More examples in Storybook or a lightweight demo page.

Optional expand/collapse context affordance if users ask for it.

Rabbit Holes

Potential areas that can expand the scope:

Rendering multi-block selections instead of single-block text ranges.

Supporting non-text block fragments such as images, files, embeds, videos, or query blocks.

Building a full rich-text renderer separate from the existing viewer/editor rendering stack.

Adding bidirectional “show context / hide context” controls everywhere.

Changing the comment/thread data model instead of treating this as a rendering concern.

Redesigning all embeds or all comment cards at the same time.

Solving unrelated embed selection/focus styling issues.

No Gos

For this feature, we should not:

Change how comment targets are stored.

Change block-range URL semantics.

Replace the existing full-block viewer entirely.

Remove fallback behavior for invalid or unsupported ranges.

Strip formatting from selected fragments.

Use brittle string slicing based on UTF-16 offsets.

Expand the project into a general redesign of comments, embeds, or document typography.

Add complex context controls before validating whether users need them.

Meeting Notes

The key proposal is simple:

When a comment or embed points to a selected text range, render the selected fragment as the main object. Use full-block context only as fallback or future optional expansion.

This makes comments and embeds shorter, clearer, and more consistent with what the user actually selected.