feat(document-api): selection.current() exposes activeCommentIds and activeChangeIds (SD-2792) (#2981)

* feat(document-api): selection.current() exposes activeCommentIds and activeChangeIds (SD-2792)

Adds two read-only id arrays to `SelectionInfo`:

- `activeCommentIds: string[]` — `commentMark.commentId`s overlapping
  the selection (or under the caret when empty)
- `activeChangeIds: string[]` — `trackInsert` / `trackDelete` /
  `trackFormat` mark ids overlapping the selection

Union semantics (NOT intersection): an id is included when *any*
character in the range carries the mark. `activeMarks` keeps its
intersection semantics; the two answer different questions and have
different defaults.

Why:

Custom sidebars need to answer "is there a comment / tracked change
under the cursor?" to render a floating "comment here" hint, highlight
the active sidebar card as the user moves the caret, disable a "new
comment" button when the selection already covers an existing comment,
and drive next/previous review navigation. Today consumers either:

- Call `comments.list()` and overlap-filter on every keystroke (full
  read per cursor move), or
- Reach into the rendered DOM via `document.querySelectorAll(
  '[data-comment-id]')` (the dropin-assessment lab does this — a
  DOM-shape coupling no migration guide should teach).

Both are escape hatches. The selection resolver (SD-2668) already
walks the selection range; collecting these ids is one extra pass on
the same nodes.

Implementation:

- `collectActiveEntityIds` walks the selection in the same shape as
  `collectActiveMarks` (caret-only branch for empty selections plus
  stored marks; nodesBetween for ranges). Bounded allocation, runs in
  O(text nodes) for both branches.
- Mark name constants are local to the resolver rather than imported
  from the comment / track-changes extensions. The resolver lives one
  package up the dependency graph; pulling in the PM plugins would
  bloat the import path for no gain. The constant set is small and
  changes when the schema does.
- `selectionInfoKey` (transaction dedupe cache) now includes the new
  fields so a comment/change id change between transactions still
  emits to subscribers.

Schema + generated reference docs updated; both fields are required
and serialize as empty arrays when no entity marks are active.

Verified: 23 resolver tests (5 new for entity-id collection covering
union semantics, both kinds, mixed marks, JSON round-trip). Document-
API: 1395 / 0 fail. Super-editor: 11893 / 13 skipped / 0 fail.
Contract parity: 389/389. `pnpm run generate:all` clean.

* fix(document-api): map activeChangeIds through canonical resolver

Addresses PR #2981 review (P2). Tracked-change marks store
`attrs.id` (the raw mark id), but `editor.doc.trackChanges.list()`
returns canonical ids derived by `groupTrackedChanges` (a portable
hash from change type + positions + author + date + excerpt).

The first cut of `activeChangeIds` returned the raw ids directly.
Consumers comparing them against `list().items[].id` to highlight
the active review-sidebar card would silently get no match — every
canonical id is a hex string, every raw id is whatever the document
imported with.

Fix: `mapRawChangeIdsToCanonical(editor, rawIds)` resolves through
`groupTrackedChanges(editor)` (cached per `editor.state.doc`, so
typical calls are O(grouped)) and translates raw → canonical.
Unmapped raw ids (partial editor mid-construction, or marks that
weren't grouped) are dropped rather than leaked, since exposing
them would re-introduce the silent-no-match bug.

`activeCommentIds` is unaffected — comment marks already carry
their canonical `commentId` directly on `attrs`.

Tests:
- Existing change-ids test now uses `vi.mock` on
  `tracked-change-resolver.js` to seed the raw → canonical map and
  asserts the canonical ids come through.
- New test for the defensive drop: an "orphan" raw id with no
  mapping must NOT appear in `activeChangeIds`.

24 resolver tests pass; super-editor 11894 / 13 skipped / 0 fail.

* fix(document-api): importedId fallback + dedupe canonical change ids (PR #2981 review)

Author: caio-pizzol

apps/docs/document-api/reference/_generated-manifest.json

@@ -1031,5 +1031,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "fa717df8cc013f9703b118596afe4cbbf655fe73f2e4e856588844110998ee2e"
+  "sourceHash": "20f0873e29e8589387d0776cc53e6eea8d5fce102a3eba9a47a183c49b5f0b13"
 }

apps/docs/document-api/reference/selection/current.mdx

@@ -40,6 +40,8 @@ Returns a SelectionInfo with `empty`, `target` (TextTarget or null), `activeMark
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
+| `activeChangeIds` | string[] | yes |  |
+| `activeCommentIds` | string[] | yes |  |
 | `activeMarks` | string[] | yes |  |
 | `empty` | boolean | yes |  |
 | `target` | TextTarget \\| null | yes | One of: TextTarget, null |
@@ -49,6 +51,12 @@ Returns a SelectionInfo with `empty`, `target` (TextTarget or null), `activeMark
 
 ```json
 {
+  "activeChangeIds": [
+    "example"
+  ],
+  "activeCommentIds": [
+    "example"
+  ],
   "activeMarks": [
     "example"
   ],
@@ -99,6 +107,18 @@ Returns a SelectionInfo with `empty`, `target` (TextTarget or null), `activeMark
 {
   "additionalProperties": false,
   "properties": {
+    "activeChangeIds": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "activeCommentIds": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
     "activeMarks": {
       "items": {
         "type": "string"
@@ -125,7 +145,9 @@ Returns a SelectionInfo with `empty`, `target` (TextTarget or null), `activeMark
   "required": [
     "empty",
     "target",
-    "activeMarks"
+    "activeMarks",
+    "activeCommentIds",
+    "activeChangeIds"
   ],
   "type": "object"
 }

packages/document-api/src/contract/schemas.ts

@@ -5299,9 +5299,11 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
             empty: { type: 'boolean' },
             target: { oneOf: [textTargetSchema, { type: 'null' }] },
             activeMarks: arraySchema({ type: 'string' }),
+            activeCommentIds: arraySchema({ type: 'string' }),
+            activeChangeIds: arraySchema({ type: 'string' }),
             text: { type: 'string' },
           },
-          ['empty', 'target', 'activeMarks'],
+          ['empty', 'target', 'activeMarks', 'activeCommentIds', 'activeChangeIds'],
         ),
       },
 

packages/document-api/src/selection/selection.types.ts

@@ -43,8 +43,34 @@ export interface SelectionInfo {
    * Active marks at the caret or across the selection. Names are
    * ProseMirror mark type names (e.g. `'bold'`, `'italic'`, `'link'`).
    * Use these to drive toolbar active-state rendering.
+   *
+   * `activeMarks` uses **intersection** semantics — a name is present
+   * only when every character in the selection carries that mark. This
+   * matches Word/Google Docs toolbar behavior.
    */
   activeMarks: string[];
+  /**
+   * Comment IDs whose `commentMark` overlaps any part of the current
+   * selection (or covers the caret when empty). Use to drive a
+   * floating "comment here" hint, highlight the active sidebar card,
+   * or disable a "new comment" button when the selection already
+   * covers an existing comment.
+   *
+   * **Union** semantics: an id is present when *any* character in the
+   * selection carries that comment, not when every character does.
+   * Multiple overlapping comments produce multiple ids.
+   */
+  activeCommentIds: string[];
+  /**
+   * Tracked-change IDs whose `trackInsert` / `trackDelete` /
+   * `trackFormat` mark overlaps any part of the current selection.
+   * Same union semantics as {@link activeCommentIds}.
+   *
+   * Use to drive review-sidebar highlighting and next/previous
+   * navigation without resolving every change individually via
+   * `trackChanges.list()`.
+   */
+  activeChangeIds: string[];
   /**
    * Quoted text of the selection. Populated only when `includeText: true`.
    * Undefined otherwise.

packages/super-editor/src/editors/v1/document-api-adapters/helpers/selection-info-resolver.test.ts

@@ -3,6 +3,23 @@ import type { Node as ProseMirrorNode } from 'prosemirror-model';
 import type { Editor } from '../../core/Editor.js';
 import { resolveCurrentSelectionInfo, subscribeToSelection } from './selection-info-resolver.js';
 
+// Stub `groupTrackedChanges` so tests don't need a fully PM-shaped
+// editor with `editor.state.doc.textBetween` and the tracked-change
+// mark walker. Each test that exercises tracked-change ids configures
+// the raw → canonical mapping it expects.
+const groupTrackedChangesMock = vi.hoisted(() =>
+  vi.fn(() => [] as Array<{ rawId: string; id: string; from: number; to: number }>),
+);
+vi.mock('./tracked-change-resolver.js', () => ({
+  groupTrackedChanges: groupTrackedChangesMock,
+}));
+
+const setTrackedChangeMapping = (mappings: Array<{ rawId: string; canonical: string }>) => {
+  groupTrackedChangesMock.mockReturnValue(
+    mappings.map((m) => ({ rawId: m.rawId, id: m.canonical, from: 0, to: 0 })) as never,
+  );
+};
+
 // ---------------------------------------------------------------------------
 // PM node stub builder
 //
@@ -21,6 +38,12 @@ type NodeOptions = {
   attrs?: Record<string, unknown>;
   /** Mark names applied to this node (only used for text nodes). */
   markNames?: string[];
+  /**
+   * Marks with attrs (commentMark, trackInsert, etc). Coexists with
+   * `markNames` — both end up in `node.marks`. Use this for tests that
+   * exercise per-mark attribute-driven id collection.
+   */
+  marksWithAttrs?: Array<{ name: string; attrs: Record<string, unknown> }>;
 };
 
 function createNode(typeName: string, children: ProseMirrorNode[] = [], options: NodeOptions = {}): ProseMirrorNode {
@@ -50,7 +73,10 @@ function createNode(typeName: string, children: ProseMirrorNode[] = [], options:
     child(index: number) {
       return children[index]!;
     },
-    marks: (options.markNames ?? []).map((name) => ({ type: { name } })),
+    marks: [
+      ...(options.markNames ?? []).map((name) => ({ type: { name }, attrs: {} as Record<string, unknown> })),
+      ...(options.marksWithAttrs ?? []).map((m) => ({ type: { name: m.name }, attrs: m.attrs })),
+    ],
     // `nodesBetween` walks the whole subtree. A minimal correct
     // implementation for our test shapes: visit self first, then recurse
     // into children with the right child-position accounting.
@@ -154,7 +180,7 @@ describe('resolveCurrentSelectionInfo', () => {
   it('returns an empty info with null target when the editor has no state', () => {
     const editor = { state: null } as unknown as Editor;
     const info = resolveCurrentSelectionInfo(editor, {});
-    expect(info).toEqual({ empty: true, target: null, activeMarks: [] });
+    expect(info).toEqual({ empty: true, target: null, activeMarks: [], activeCommentIds: [], activeChangeIds: [] });
   });
 
   it('projects a single-block selection into a one-segment TextTarget', () => {
@@ -325,6 +351,212 @@ describe('resolveCurrentSelectionInfo', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// activeCommentIds / activeChangeIds (SD-2792)
+// ---------------------------------------------------------------------------
+
+/**
+ * Marked-text helper that lets each run carry attribute-bearing marks
+ * (commentMark with commentId, trackInsert/Delete/Format with id).
+ */
+function entityMarkedTextBlock(
+  blockId: string,
+  runs: Array<{
+    text: string;
+    marks?: string[];
+    marksWithAttrs?: Array<{ name: string; attrs: Record<string, unknown> }>;
+  }>,
+): ProseMirrorNode {
+  const children = runs.map((r) =>
+    createNode('text', [], {
+      text: r.text,
+      markNames: r.marks ?? [],
+      marksWithAttrs: r.marksWithAttrs ?? [],
+    }),
+  );
+  return createNode('paragraph', children, {
+    isBlock: true,
+    inlineContent: true,
+    attrs: { sdBlockId: blockId },
+  });
+}
+
+describe('resolveCurrentSelectionInfo > entity ids', () => {
+  it('collects commentIds from commentMarks across the selection (union)', () => {
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'Hello ', marksWithAttrs: [{ name: 'commentMark', attrs: { commentId: 'c1' } }] },
+        {
+          text: 'world',
+          marksWithAttrs: [
+            { name: 'commentMark', attrs: { commentId: 'c1' } },
+            { name: 'commentMark', attrs: { commentId: 'c2' } },
+          ],
+        },
+      ]),
+    ]);
+    // Select the whole text "Hello world" (PM positions 2..13).
+    const editor = makeEditor(docNode, { from: 2, to: 13 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect([...info.activeCommentIds].sort()).toEqual(['c1', 'c2']);
+    expect(info.activeChangeIds).toEqual([]);
+  });
+
+  it('collects changeIds from trackInsert/trackDelete/trackFormat marks (translated through canonical resolver)', () => {
+    // Raw mark ids and canonical Document API ids differ: the canonical
+    // id is a derived hash from `groupTrackedChanges`. We mock that map
+    // so the resolver sees raw 'tc1' / 'tc2' / 'tc3' and returns the
+    // canonical 'tcA' / 'tcB' / 'tcC' that consumers see in
+    // `trackChanges.list().items[].id`.
+    setTrackedChangeMapping([
+      { rawId: 'tc1', canonical: 'tcA' },
+      { rawId: 'tc2', canonical: 'tcB' },
+      { rawId: 'tc3', canonical: 'tcC' },
+    ]);
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'inserted ', marksWithAttrs: [{ name: 'trackInsert', attrs: { id: 'tc1' } }] },
+        { text: 'deleted ', marksWithAttrs: [{ name: 'trackDelete', attrs: { id: 'tc2' } }] },
+        { text: 'reformat', marksWithAttrs: [{ name: 'trackFormat', attrs: { id: 'tc3' } }] },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 27 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect([...info.activeChangeIds].sort()).toEqual(['tcA', 'tcB', 'tcC']);
+    expect(info.activeCommentIds).toEqual([]);
+  });
+
+  it('drops raw change ids that have no canonical mapping (defensive)', () => {
+    // Raw id present in the document but missing from groupTrackedChanges
+    // (mid-construction editor, or a mark that wasn't grouped). Leaking
+    // the raw id past the resolver would silently produce no-match
+    // highlights in consumer sidebars; drop it instead.
+    setTrackedChangeMapping([{ rawId: 'tc1', canonical: 'tcA' }]);
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'mapped ', marksWithAttrs: [{ name: 'trackInsert', attrs: { id: 'tc1' } }] },
+        { text: 'orphan', marksWithAttrs: [{ name: 'trackInsert', attrs: { id: 'orphan-id' } }] },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 14 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect(info.activeChangeIds).toEqual(['tcA']);
+  });
+
+  it('dedupes canonical ids when two raw ids map to the same canonical (paired tracked changes)', () => {
+    // Tracked replace produces paired insert + delete halves whose
+    // raw mark ids both group to a single canonical id. A range
+    // selection across both halves must surface the canonical id
+    // once, not twice — otherwise sidebar counts and union-driven
+    // highlights would double-count the change.
+    setTrackedChangeMapping([
+      { rawId: 'tc1-insert', canonical: 'tcA' },
+      { rawId: 'tc1-delete', canonical: 'tcA' },
+    ]);
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'inserted ', marksWithAttrs: [{ name: 'trackInsert', attrs: { id: 'tc1-insert' } }] },
+        { text: 'deleted', marksWithAttrs: [{ name: 'trackDelete', attrs: { id: 'tc1-delete' } }] },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 16 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect(info.activeChangeIds).toEqual(['tcA']);
+  });
+
+  it('reports both comment and change ids when a span carries both', () => {
+    setTrackedChangeMapping([{ rawId: 'tc1', canonical: 'tcA' }]);
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        {
+          text: 'reviewed',
+          marksWithAttrs: [
+            { name: 'commentMark', attrs: { commentId: 'c1' } },
+            { name: 'trackInsert', attrs: { id: 'tc1' } },
+          ],
+        },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 10 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect(info.activeCommentIds).toEqual(['c1']);
+    expect(info.activeChangeIds).toEqual(['tcA']);
+  });
+
+  it('returns empty id arrays when no entity marks overlap the selection', () => {
+    const docNode = doc([entityMarkedTextBlock('p1', [{ text: 'Plain text', marks: ['bold'] }])]);
+    const editor = makeEditor(docNode, { from: 2, to: 12 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect(info.activeCommentIds).toEqual([]);
+    expect(info.activeChangeIds).toEqual([]);
+    expect(info.activeMarks).toEqual(['bold']);
+  });
+
+  it('uses union semantics, not intersection (one comment touching part of the selection counts)', () => {
+    // Run 1 has comment c1; run 2 is plain. activeMarks would not include
+    // a "bold" if it only touched run 1, but activeCommentIds should
+    // include c1 because we use union semantics.
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'commented', marksWithAttrs: [{ name: 'commentMark', attrs: { commentId: 'c1' } }] },
+        { text: ' tail', marks: [] },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 16 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect(info.activeCommentIds).toEqual(['c1']);
+  });
+
+  it('resolves comment ids from importedId / w:id when commentId is absent (legacy DOCX imports)', () => {
+    // Imported / legacy comment marks may carry the id on
+    // `importedId` or `w:id` instead of the post-import canonical
+    // `commentId`. The resolver must honor the same fallback chain
+    // the rest of the comment adapter graph uses
+    // (`resolveCommentIdFromAttrs`); without it,
+    // `selection.current().activeCommentIds` would stay empty over a
+    // run that `comments.list()` reports as a real comment.
+    const docNode = doc([
+      entityMarkedTextBlock('p1', [
+        { text: 'imported ', marksWithAttrs: [{ name: 'commentMark', attrs: { importedId: 'imp-1' } }] },
+        { text: 'legacy', marksWithAttrs: [{ name: 'commentMark', attrs: { 'w:id': 'leg-2' } }] },
+      ]),
+    ]);
+    const editor = makeEditor(docNode, { from: 2, to: 17 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+
+    expect([...info.activeCommentIds].sort()).toEqual(['imp-1', 'leg-2']);
+  });
+
+  it('empty arrays survive a JSON round-trip (serialization-stable shape)', () => {
+    // Schema and dispatch tests assume the SelectionInfo output is JSON-
+    // serializable with stable field presence. Empty arrays should
+    // serialize and parse back as empty arrays, not be elided.
+    const docNode = doc([textBlock('p1', 'Hello')]);
+    const editor = makeEditor(docNode, { from: 2, to: 7 });
+
+    const info = resolveCurrentSelectionInfo(editor, {});
+    const roundTripped = JSON.parse(JSON.stringify(info));
+
+    expect(roundTripped.activeCommentIds).toEqual([]);
+    expect(roundTripped.activeChangeIds).toEqual([]);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // subscribeToSelection
 // ---------------------------------------------------------------------------