@dxos/ui-editor 0.10.0 → 0.11.0

package/src/extensions/{comments.ts → review/comments.ts}

@@ -3,16 +3,24 @@
 //
 
 import { invertedEffects } from '@codemirror/commands';
-import { type ChangeDesc, type Extension, StateEffect, StateField, type Text } from '@codemirror/state';
+import { getChunks } from '@codemirror/merge';
+import {
+  type ChangeDesc,
+  EditorSelection,
+  type Extension,
+  StateEffect,
+  StateField,
+  type Text,
+} from '@codemirror/state';
 import {
   type Command,
   Decoration,
   EditorView,
-  type PluginValue,
   type Rect,
+  RectangleMarker,
   ViewPlugin,
-  hoverTooltip,
   keymap,
+  layer,
 } from '@codemirror/view';
 import sortBy from 'lodash.sortby';
 
@@ -20,10 +28,219 @@ import { type CleanupFn, debounce } from '@dxos/async';
 import { log } from '@dxos/log';
 import { isNonNullable } from '@dxos/util';
 
-import { type Comment, type Range, type RenderCallback } from '../types';
-import { Cursor, singleValueFacet, wrapWithCatch } from '../util';
-import { markerMark, markerTheme } from './marker';
-import { documentId } from './selection';
+import { type Comment, type Range } from '../../types';
+import { Cursor, singleValueFacet, wrapWithCatch } from '../../util';
+import { documentId } from '../state/selection';
+
+//
+// Options
+//
+
+export type CommentsOptions = {
+  /**
+   * Document id.
+   */
+  id: string;
+  /**
+   * Key shortcut to create a new thread.
+   */
+  key?: string;
+  /**
+   * Get the current comments.
+   */
+  getComments?: () => Comment[];
+  /**
+   * Subscribe to external comment updates.
+   */
+  subscribe?: (sink: () => void) => CleanupFn;
+  /**
+   * The branch under review; new comments are tagged with it (undefined = main/unbranched). Scopes
+   * a comment to the branch being reviewed so its visibility tracks the active diff.
+   */
+  reviewBranch?: string;
+  /**
+   * Prohibit creating new comments (e.g. on a per-user suggestion branch). Existing comments still
+   * render; the create command becomes a no-op.
+   */
+  readonly?: boolean;
+  /**
+   * Called to create a new thread and return the thread id.
+   */
+  onCreate?: (params: { cursor: string; from: number; location?: Rect | null; branch?: string }) => void;
+  /**
+   * Selection cut/deleted.
+   */
+  onDelete?: (params: { id: string }) => void;
+  /**
+   * Called when a comment is moved.
+   */
+  onUpdate?: (params: { id: string; cursor: string }) => void;
+  /**
+   * Called to notify which thread is currently closest to the cursor.
+   */
+  onSelect?: (state: CommentsState) => void;
+  /**
+   * Called when a comment is deliberately activated (clicked). Distinct from `onSelect` (passive
+   * cursor-proximity): a click is an explicit user intent, e.g. to reveal the thread in a companion.
+   * The editor-side selection/highlight is already applied by the time this fires.
+   */
+  onActivate?: (id: string) => void;
+};
+
+/**
+ * Comment threads.
+ * 1). Updates the EditorModel to store relative selections for a set of comments threads.
+ *     Since the selections are relative, they do not need to be updated when the document is edited.
+ * 2). Implements a StateField to track absolute selections corresponding to the comments (i.e., when the document is edited).
+ * 3). Creates decoration marks to apply classes to each selection.
+ * 4). Tracks the current cursor position to:
+ *     a). Update the decoration to show if the cursor is within a current selection.
+ *     b). Calls a handler to indicate which is the closest selection (e.g., to update the thread sidebar).
+ * 5). Optionally, implements a hoverTooltip to show hints when creating a selection range.
+ */
+export const comments = (options: CommentsOptions): Extension => {
+  const { key: shortcut = "meta-'" } = options;
+
+  const handleSelect = debounce((state: CommentsState) => options.onSelect?.(state), 200);
+
+  return [
+    optionsFacet.of(options),
+    options.id ? documentId.of(options.id) : undefined,
+    commentsState,
+    commentsDecorations,
+    commentsHighlightLayer,
+    handleCommentClick,
+    styles,
+
+    //
+    // External comment synchronization.
+    //
+    ViewPlugin.fromClass(
+      class {
+        private readonly unsubscribe: () => void;
+        constructor(view: EditorView) {
+          const { id } = options;
+          const updateComments = () => {
+            const comments = options.getComments?.() ?? [];
+            // Local `id` const so the truthiness narrowing survives into the microtask closure.
+            if (id && id === view.state.facet(documentId)) {
+              queueMicrotask(() => view.dispatch({ effects: setComments.of({ id, comments }) }));
+            }
+          };
+
+          this.unsubscribe = options.subscribe?.(updateComments) ?? (() => {});
+          // Prime the initial decoration pass: `subscribe` may not emit for an already-resolved source
+          // (e.g. an ECHO query whose results resolved before mount), so read once now that the source is
+          // subscribed. Owning this here means adapters never have to prime manually.
+          updateComments();
+        }
+
+        destroy = () => {
+          this.unsubscribe();
+        };
+      },
+    ),
+
+    //
+    // Keymap.
+    //
+    options.onCreate &&
+      keymap.of([
+        {
+          key: shortcut,
+          run: wrapWithCatch(createComment),
+        },
+      ]),
+
+    //
+    // Track deleted ranges and update ranges for decorations.
+    //
+    EditorView.updateListener.of(({ view, state, changes }) => {
+      let mod = false;
+      const { comments, ...value } = state.field(commentsState);
+      changes.iterChanges((from, to, from2, to2) => {
+        comments.forEach(({ comment, range }) => {
+          // Only comments with a cursor reach this state (setComments filters cursor-less ones).
+          if (!comment.cursor) {
+            return;
+          }
+
+          // Test if range deleted.
+          if (from2 === to2) {
+            const newRange = Cursor.getRangeFromCursor(view.state, comment.cursor);
+            if (!newRange || newRange.to - newRange.from === 0) {
+              options.onDelete?.({ id: comment.id });
+            }
+          }
+
+          // Update range.
+          if (from <= range.to) {
+            const newRange = Cursor.getRangeFromCursor(view.state, comment.cursor);
+            Object.assign(range, newRange);
+            mod = true;
+          }
+        });
+      });
+
+      if (mod) {
+        view.dispatch({ effects: setCommentState.of({ comments, ...value }) });
+      }
+    }),
+
+    //
+    // Track selection/proximity.
+    //
+    EditorView.updateListener.of(({ view, state, transactions }) => {
+      let min = Infinity;
+      const { selection: applied, comments } = state.field(commentsState);
+      const { current, closest } = applied;
+
+      const notify = (selection: SelectionState) =>
+        handleSelect({
+          selection,
+          id: state.facet(documentId),
+          comments: comments.map(({ comment, range }) => ({
+            comment,
+            range,
+            location: view.coordsAtPos(range.from),
+          })),
+        });
+
+      // An explicit `setSelection` is authoritative: selecting a thread in the comments companion sets
+      // `current` and moves the caret in one transaction, and the caret does not always land inside the
+      // tracked range — proximity would then clear the very selection that transaction just made. Report
+      // the applied selection so the app still learns which thread is current, but leave it as set.
+      if (transactions.some((tr) => tr.effects.some((effect) => effect.is(setSelection)))) {
+        notify(applied);
+        return;
+      }
+
+      const { head } = state.selection.main;
+      const selection: SelectionState = {};
+      comments.forEach(({ comment, range }) => {
+        if (head >= range.from && head <= range.to) {
+          selection.current = comment.id;
+          selection.closest = undefined;
+        }
+
+        if (!selection.current) {
+          const d = Math.min(Math.abs(head - range.from), Math.abs(head - range.to));
+          if (d < min) {
+            selection.closest = comment.id;
+            min = d;
+          }
+        }
+      });
+
+      if (selection.current !== current || selection.closest !== closest) {
+        view.dispatch({ effects: setSelection.of(selection) });
+        notify(selection);
+      }
+    }),
+
+    options.onUpdate && trackPastedComments(options.onUpdate),
+  ].filter(isNonNullable);
+};
 
 //
 // State management.
@@ -55,6 +272,7 @@ const setCommentState = StateEffect.define<CommentsState>();
 /**
  * State field (reducer) that tracks comment ranges.
  * The ranges are tracked as Automerge cursors from which the absolute indexed ranges can be computed.
+ * Included by {@link comments}; exported for direct state reads.
  */
 export const commentsState = StateField.define<CommentsState>({
   create: (state) => ({
@@ -97,19 +315,8 @@ export const commentsState = StateField.define<CommentsState>({
   },
 });
 
-/**
- * NOTE: Matches search.
- */
-// Surface/box-shadow come from the shared `markerTheme`, tinted by the mark's `data-hue`; the comment
-// just adds the pointer affordance.
-const styles = EditorView.theme({
-  '.cm-comment > span': {
-    cursor: 'pointer',
-  },
-});
-
 const createCommentMark = (id: string, isCurrent: boolean) =>
-  markerMark(isCurrent ? 'orange' : 'teal', {
+  Decoration.mark({
     class: 'cm-comment',
     attributes: {
       'data-testid': 'cm-comment',
@@ -119,7 +326,8 @@ const createCommentMark = (id: string, isCurrent: boolean) =>
   });
 
 /**
- * Decorate ranges.
+ * Transparent inline marks that carry `data-comment-id` for click routing (see `handleCommentClick`).
+ * The colour comes from `commentsHighlightLayer`.
  */
 const commentsDecorations = EditorView.decorations.compute([commentsState], (state) => {
   const {
@@ -146,32 +354,87 @@ const commentsDecorations = EditorView.decorations.compute([commentsState], (sta
   return Decoration.set(decorations);
 });
 
-export const commentClickedEffect = StateEffect.define<string>();
+/**
+ * Selection-style highlight: draws each comment range as a layer of rectangle markers below the text.
+ * `RectangleMarker.forRange` extends wrapped (non-final) lines to the line edge, so a multi-line comment
+ * reads as one continuous block rather than ragged per-word inline backgrounds.
+ */
+const commentsHighlightLayer = layer({
+  above: false,
+  class: 'cm-commentsHighlightLayer',
+  update: (update) =>
+    update.docChanged ||
+    update.viewportChanged ||
+    update.geometryChanged ||
+    update.selectionSet ||
+    update.transactions.some((tr) =>
+      tr.effects.some((effect) => effect.is(setSelection) || effect.is(setComments) || effect.is(setCommentState)),
+    ),
+  markers: (view) => {
+    const {
+      selection: { current },
+      comments,
+    } = view.state.field(commentsState);
+
+    return sortBy(comments ?? [], (comment) => comment.range.from).flatMap((comment) => {
+      const { from, to } = comment.range;
+      if (from >= to) {
+        return [];
+      }
+
+      const className =
+        comment.comment.id === current ? 'cm-comment-highlight cm-comment-highlight-current' : 'cm-comment-highlight';
+      const range = EditorSelection.range(from, to);
+      const markers = RectangleMarker.forRange(view, className, range);
+      // A single rectangle means the comment fits on one visual line — round its corners.
+      return markers.length === 1
+        ? RectangleMarker.forRange(view, `${className} cm-comment-highlight-single`, range)
+        : markers;
+    });
+  },
+});
 
 const handleCommentClick = EditorView.domEventHandlers({
   click: (event, view) => {
-    let target = event.target as HTMLElement;
-    const editorRoot = view.dom;
-
-    // Traverse up the DOM tree looking for an element with data-comment-id
-    // Stop if we reach the editor root or find the comment id
-    while (target && target !== editorRoot && !target.hasAttribute('data-comment-id')) {
-      target = target.parentElement as HTMLElement;
+    const id = commentIdAtClick(event, view);
+    if (!id) {
+      return false;
     }
 
-    // Check if we found a comment id and are still within the editor
-    if (target && target !== editorRoot) {
-      const commentId = target.getAttribute('data-comment-id');
-      if (commentId) {
-        view.dispatch({ effects: commentClickedEffect.of(commentId) });
-        return true;
-      }
-    }
-
-    return false;
+    // Select the clicked thread in the editor (moves the caret into the range so the proximity tracker
+    // keeps it current) and notify the app for deliberate-click behaviour (e.g. reveal in a companion).
+    scrollCommentIntoView(view, id);
+    view.state.facet(optionsFacet).onActivate?.(id);
+    return true;
   },
 });
 
+/**
+ * Resolve the comment id under a click. Prefers the DOM target (a direct hit on the `.cm-comment`
+ * span), then falls back to a document-position hit-test: the highlight-layer rectangles
+ * (pointer-events: none) sit over the text, so a click often lands on the `.cm-line` (an ancestor of
+ * the span) and an upward target walk would miss it.
+ */
+const commentIdAtClick = (event: MouseEvent, view: EditorView): string | undefined => {
+  let target = event.target as HTMLElement | null;
+  const editorRoot = view.dom;
+  while (target && target !== editorRoot && !target.hasAttribute?.('data-comment-id')) {
+    target = target.parentElement;
+  }
+  const domId = target && target !== editorRoot ? target.getAttribute('data-comment-id') : null;
+  if (domId) {
+    return domId;
+  }
+
+  const pos = view.posAtCoords({ x: event.clientX, y: event.clientY });
+  if (pos != null) {
+    const commentState = view.state.field(commentsState, false);
+    return commentState?.comments.find(({ range }) => pos >= range.from && pos <= range.to)?.comment.id;
+  }
+
+  return undefined;
+};
+
 //
 // Cut-and-paste.
 //
@@ -290,218 +553,65 @@ const mapTrackedComment = (comment: TrackedComment, changes: ChangeDesc) => ({
  * These are attached to undone/redone transactions in the editor for the purpose of restoring comments
  * that were deleted by the original changes.
  */
-const restoreCommentEffect = StateEffect.define<TrackedComment>({ map: mapTrackedComment });
+const restoreCommentEffect = StateEffect.define<TrackedComment>({
+  map: mapTrackedComment,
+});
+
+const optionsFacet = singleValueFacet<CommentsOptions>();
 
 /**
  * Create comment thread action.
  */
 export const createComment: Command = (view) => {
   const options = view.state.facet(optionsFacet);
-  const { from, to } = view.state.selection.main;
-  if (from === to) {
+  // Comment creation is prohibited on this surface (e.g. a suggestion branch).
+  if (options.readonly) {
     return false;
   }
 
-  // Don't allow selection at end of document.
-  if (to === view.state.doc.length) {
-    view.dispatch({
-      changes: {
-        from: to,
-        insert: '\n',
-      },
-    });
+  let { from, to } = view.state.selection.main;
+
+  // Snap to the largest logical region so commenting never depends on a precise selection. Inside a
+  // (unified) diff hunk the comment covers the whole changed hunk (a bare cursor in the hunk is
+  // enough); otherwise, with no selection, it expands to the word under the cursor. The diff case
+  // takes precedence so a comment on a change visibly covers it.
+  const merge = getChunks(view.state);
+  const chunk = merge?.chunks.find((candidate) => candidate.fromB <= to && candidate.endB >= from);
+  if (chunk) {
+    from = chunk.fromB;
+    to = Math.min(chunk.endB, view.state.doc.length);
+  } else if (from === to) {
+    const word = view.state.wordAt(from);
+    if (word) {
+      from = word.from;
+      to = word.to;
+    }
+  }
+
+  // Exclude trailing newlines so the anchor stays within content and never reaches the document end.
+  // Anchoring at the very end previously required inserting a newline to stabilise the end cursor — a
+  // visible, unwanted mutation; the end cursor instead associates with the preceding character.
+  while (to > from && view.state.doc.sliceString(to - 1, to) === '\n') {
+    to--;
+  }
+
+  if (from === to) {
+    return false;
   }
 
   const cursor = Cursor.getCursorFromRange(view.state, { from, to });
   if (cursor) {
-    // Create thread via callback.
-    options.onCreate?.({ cursor, from, location: view.coordsAtPos(from) });
+    // Collapse the text selection now that the range is captured by the comment (the caret stays within
+    // the new comment, keeping it the current thread).
+    view.dispatch({ selection: { anchor: from } });
+    // Create thread via callback; branch-tag it with the branch under review (undefined = main).
+    options.onCreate?.({ cursor, from, location: view.coordsAtPos(from), branch: options.reviewBranch });
     return true;
   }
 
   return false;
 };
 
-//
-// Options
-//
-
-export type CommentsOptions = {
-  /**
-   * Document id.
-   */
-  id?: string;
-  /**
-   * Key shortcut to create a new thread.
-   */
-  key?: string;
-  /**
-   * Called to render tooltip.
-   */
-  renderTooltip?: RenderCallback<{ shortcut: string }>;
-  /**
-   * Called to create a new thread and return the thread id.
-   */
-  onCreate?: (params: { cursor: string; from: number; location?: Rect | null }) => void;
-  /**
-   * Selection cut/deleted.
-   */
-  onDelete?: (params: { id: string }) => void;
-  /**
-   * Called when a comment is moved.
-   */
-  onUpdate?: (params: { id: string; cursor: string }) => void;
-  /**
-   * Called to notify which thread is currently closest to the cursor.
-   */
-  onSelect?: (state: CommentsState) => void;
-};
-
-const optionsFacet = singleValueFacet<CommentsOptions>();
-
-/**
- * Comment threads.
- * 1). Updates the EditorModel to store relative selections for a set of comments threads.
- *     Since the selections are relative, they do not need to be updated when the document is edited.
- * 2). Implements a StateField to track absolute selections corresponding to the comments (i.e., when the document is edited).
- * 3). Creates decoration marks to apply classes to each selection.
- * 4). Tracks the current cursor position to:
- *     a). Update the decoration to show if the cursor is within a current selection.
- *     b). Calls a handler to indicate which is the closest selection (e.g., to update the thread sidebar).
- * 5). Optionally, implements a hoverTooltip to show hints when creating a selection range.
- */
-export const comments = (options: CommentsOptions = {}): Extension => {
-  const { key: shortcut = "meta-'" } = options;
-
-  const handleSelect = debounce((state: CommentsState) => options.onSelect?.(state), 200);
-
-  return [
-    optionsFacet.of(options),
-    options.id ? documentId.of(options.id) : undefined,
-    commentsState,
-    commentsDecorations,
-    handleCommentClick,
-    markerTheme(),
-    styles,
-
-    //
-    // Keymap.
-    //
-    options.onCreate &&
-      keymap.of([
-        {
-          key: shortcut,
-          run: wrapWithCatch(createComment),
-        },
-      ]),
-
-    //
-    // Hover tooltip (for key shortcut hints, etc.)
-    // TODO(burdon): Factor out to generic hints extension for current selection/line.
-    //
-    options.renderTooltip &&
-      hoverTooltip(
-        (view, pos) => {
-          const selection = view.state.selection.main;
-          if (selection && pos >= selection.from && pos <= selection.to) {
-            return {
-              pos: selection.from,
-              end: selection.to,
-              above: true,
-              create: () => {
-                const el = document.createElement('div');
-                options.renderTooltip!(el, { shortcut }, view);
-                return { dom: el, offset: { x: 0, y: 8 } };
-              },
-            };
-          }
-
-          return null;
-        },
-        {
-          // TODO(burdon): Hide on change triggered immediately?
-          // hideOnChange: true,
-          hoverTime: 1_000,
-        },
-      ),
-
-    //
-    // Track deleted ranges and update ranges for decorations.
-    //
-    EditorView.updateListener.of(({ view, state, changes }) => {
-      let mod = false;
-      const { comments, ...value } = state.field(commentsState);
-      changes.iterChanges((from, to, from2, to2) => {
-        comments.forEach(({ comment, range }) => {
-          // Test if range deleted.
-          if (from2 === to2) {
-            const newRange = Cursor.getRangeFromCursor(view.state, comment.cursor!);
-            if (!newRange || newRange.to - newRange.from === 0) {
-              options.onDelete?.({ id: comment.id });
-            }
-          }
-
-          // Update range.
-          if (from <= range.to) {
-            const newRange = Cursor.getRangeFromCursor(view.state, comment.cursor!);
-            Object.assign(range, newRange);
-            mod = true;
-          }
-        });
-      });
-
-      if (mod) {
-        view.dispatch({ effects: setCommentState.of({ comments, ...value }) });
-      }
-    }),
-
-    //
-    // Track selection/proximity.
-    //
-    EditorView.updateListener.of(({ view, state }) => {
-      let min = Infinity;
-      const {
-        selection: { current, closest },
-        comments,
-      } = state.field(commentsState);
-
-      const { head } = state.selection.main;
-      const selection: SelectionState = {};
-      comments.forEach(({ comment, range }) => {
-        if (head >= range.from && head <= range.to) {
-          selection.current = comment.id;
-          selection.closest = undefined;
-        }
-
-        if (!selection.current) {
-          const d = Math.min(Math.abs(head - range.from), Math.abs(head - range.to));
-          if (d < min) {
-            selection.closest = comment.id;
-            min = d;
-          }
-        }
-      });
-
-      if (selection.current !== current || selection.closest !== closest) {
-        view.dispatch({ effects: setSelection.of(selection) });
-
-        // Update callback.
-        handleSelect({
-          selection,
-          id: state.facet(documentId),
-          comments: comments.map(({ comment, range }) => ({
-            comment,
-            range,
-            location: view.coordsAtPos(range.from),
-          })),
-        });
-      }
-    }),
-
-    options.onUpdate && trackPastedComments(options.onUpdate),
-  ].filter(isNonNullable);
-};
-
 //
 // Utils.
 //
@@ -532,7 +642,7 @@ export type ScrollThreadOptions = {
  * Scroll the comment thread with the given id into view (if not already entirely
  * visible) and mark it the current comment so the editor highlights it.
  */
-export const scrollThreadIntoView = (
+export const scrollCommentIntoView = (
   view: EditorView,
   id: string,
   { y = 'center', yMargin }: ScrollThreadOptions = {},
@@ -548,7 +658,9 @@ export const scrollThreadIntoView = (
   }
 
   const { from, to } = view.state.selection.main;
-  const needsSelectionUpdate = from !== range.from || to !== range.from;
+  // Never collapse a live selection: an attention change in the comments companion can land while the
+  // user is selecting text, and moving the caret would silently retarget the comment they create next.
+  const needsSelectionUpdate = from === to && from !== range.from;
   view.dispatch({
     selection: needsSelectionUpdate ? { anchor: range.from } : undefined,
     effects: [
@@ -560,38 +672,54 @@ export const scrollThreadIntoView = (
 };
 
 /**
- * Manages external comment synchronization for the editor.
- * This class subscribes to external comment updates and applies them to the editor view.
+ * NOTE: Matches search.
  */
-class ExternalCommentSync implements PluginValue {
-  private readonly unsubscribe: () => void;
-
-  constructor(view: EditorView, id: string, subscribe: (sink: () => void) => CleanupFn, getComments: () => Comment[]) {
-    const updateComments = () => {
-      const comments = getComments();
-      if (id === view.state.facet(documentId)) {
-        queueMicrotask(() => view.dispatch({ effects: setComments.of({ id, comments }) }));
-      }
-    };
-
-    this.unsubscribe = subscribe(updateComments);
-  }
-
-  destroy = () => {
-    this.unsubscribe();
-  };
-}
-
-// TODO(burdon): Needs comment.
-export const createExternalCommentSync = (
-  id: string,
-  subscribe: (sink: () => void) => CleanupFn,
-  getComments: () => Comment[],
-): Extension =>
-  ViewPlugin.fromClass(
-    class {
-      constructor(view: EditorView) {
-        return new ExternalCommentSync(view, id, subscribe, getComments);
-      }
-    },
-  );
+// The visible highlight is drawn by `commentsHighlightLayer` (below) as a layer of rectangle markers,
+// so — like a text selection — it fills wrapped lines to the line edge instead of stopping at the last
+// glyph. The inline `cm-comment` mark is now transparent and exists only to carry `data-comment-id`
+// (click routing) and the pointer affordance. No `border-radius`: the per-line rectangles abut, so
+// rounding each would pinch the interior edges into notches on a multi-line comment.
+const styles = EditorView.theme({
+  // The layer only paints the background; text colour comes from the inline mark, which wraps exactly
+  // the comment text. `!important` and the descendant selector win over markdown syntax-highlight tokens
+  // nested inside the range.
+  '.cm-comment, .cm-comment *': {
+    color: 'var(--color-teal-fg) !important',
+  },
+  '.cm-comment[data-current="1"], .cm-comment[data-current="1"] *': {
+    color: 'var(--color-orange-fg) !important',
+  },
+  '.cm-comment': {
+    cursor: 'pointer',
+  },
+  // Layer wrapper: sit behind the text and never swallow clicks meant for the `cm-comment` mark.
+  '.cm-commentsHighlightLayer': {
+    pointerEvents: 'none',
+  },
+  // `box-shadow` with a 1px spread extends the block 1px on every side in the same colour — visual
+  // padding without changing layout. Vertically adjacent line rectangles paint into each other's gap
+  // with the same colour, so a multi-line comment stays seamless.
+  // 2px horizontal breathing room around the text: `padding-inline` widens the background box and the
+  // compensating negative `margin-inline` keeps it aligned to the text; `content-box` makes the padding
+  // grow the box (rather than shrink the content) so the fill and border-radius extend with it.
+  // `pointer-events: none` on the rectangles themselves (not only the layer wrapper) so a click over a
+  // comment passes through to the `.cm-comment` mark's `data-comment-id` (and reaches `handleCommentClick`)
+  // instead of landing on a highlight rectangle that carries no id.
+  '.cm-comment-highlight': {
+    backgroundColor: 'var(--color-teal-bg)',
+    boxShadow: '0 0 0 1px var(--color-teal-bg)',
+    boxSizing: 'content-box',
+    marginInline: '-2px',
+    paddingInline: '2px',
+    pointerEvents: 'none',
+  },
+  '.cm-comment-highlight-current': {
+    backgroundColor: 'var(--color-orange-bg)',
+    boxShadow: '0 0 0 1px var(--color-orange-bg)',
+  },
+  // Only round a comment that occupies a single visual line: a multi-line comment is drawn as several
+  // abutting rectangles, so rounding each would notch the interior edges.
+  '.cm-comment-highlight-single': {
+    borderRadius: '0.25rem',
+  },
+});