feat(document-api): selection primitives + multi-block comment targets (SD-2668) (#2941)

* feat(document-api): selection primitives + multi-block comment targets (SD-2668)

Adds `editor.doc.selection.current()` and `editor.doc.selection.onChange()` so
consumers can build custom toolbars, comments sidebars, and selection-driven
UIs without reaching into ProseMirror internals. Widens `comments.create`
target to accept `TextTarget` so multi-block selections anchor across blocks
instead of silently collapsing to the first segment.

- Consumers previously had to resolve PM positions through
  `editor.state.doc`, walk the PM tree for the containing block's `sdBlockId`,
  and convert to flattened-text offsets — ~30 lines of editor internals.
  `selection.current()` returns a portable `SelectionInfo { empty, target,
  activeMarks, text? }` with a multi-segment `TextTarget` ready for
  `comments.create`.
- `comments.list().target` already used multi-segment `TextTarget`; the
  write side (`comments.create`) only accepted single-block `TextAddress`,
  so drag-selecting across paragraphs lost data with no warning.
- Contract, schemas, dispatch, and adapter wired. Super-editor adapter
  projects PM selections into the flattened-text model via the existing
  `computeTextContentLength` helper.

Part of the SD-2667 drop-in assessment umbrella.

* fix(document-api): address PR review on selection + comments scope

1. Drop the aspirational `in: StoryLocator` parameter from
   `selection.current`. The adapter always read the live editor selection
   and merely copied `input.in` into the returned `TextTarget.story`, so a
   body selection could be mislabeled as a header/footer selection. The
   operation now documents that it always reflects whichever story holds
   focus; story-scoped selection reads are out of scope.
2. Narrow `comments.create` multi-segment handling to contiguous ranges.
   Validation previously accepted any non-empty segment array; the handler
   spanned `first.start → last.end` as a single PM range, so disjoint or
   out-of-order segments would silently anchor the comment over text the
   caller never selected. `addCommentHandler` now resolves every segment,
   rejects out-of-order pairs, and rejects any pair with non-empty text
   between them (`INVALID_TARGET`).
3. Fix schema inconsistency: `SelectionInfo.target` is `TextTarget | null`
   at the type level, but the published schema required it as an `object`.
   Schema now uses `oneOf: [textTargetSchema, { type: 'null' }]` so empty
   selections validate against the exported contract.
4. Make `SelectionAdapter` optional on `DocumentApiAdapters`. This is a
   public exported interface; adding a required member is a source
   breaking change for external adapter constructors. The factory now
   throws `SELECTION_ADAPTER_UNAVAILABLE` when selection operations are
   called without a registered adapter.

Tests: add 3 new cases (multi-segment forward, missing-adapter for
`current` + `onChange`). 1374 pass, 0 fail.

* fix(document-api): correct selection offset mapping + cancel pending flush

Two bot findings on PR 2924:

- P1: `collectTextSegments` was deriving block-relative offsets with
  `selStart - blockStart`, treating raw PM positions as flattened text
  offsets. That's only equivalent when the block contains pure text; it
  diverges whenever the block has inline wrappers (e.g. `run` marks) or
  leaf atoms whose PM boundary tokens do not count in the flattened
  model. A selection inside a run would therefore return a `TextTarget`
  off by the number of wrapper boundary tokens, and `comments.create`
  using that target would anchor to the wrong text.

  Added `pmPositionToTextOffset(blockNode, blockPos, pmPos)` alongside
  the existing `resolveTextRangeInBlock` in `text-offset-resolver.ts` —
  it walks the block with the same flattened model (text = length,
  leaf = 1, block separator = 1, inline wrapper tokens = 0) and
  returns the correct offset. `collectTextSegments` now uses it for
  both endpoints.

- P2: `subscribeToSelection` scheduled `flush` via `queueMicrotask` but
  the returned unsubscribe only detached listeners — a microtask
  already queued before cleanup would still fire, invoking the listener
  after unsubscribe returned (stale state updates on component unmount).
  Added a `cancelled` closure flag set by unsubscribe and checked in
  `flush` and `schedule`.

Tests: 5 new cases for `pmPositionToTextOffset` covering plain text,
inline wrapper transparency, leaf atoms with `nodeSize > 1`, before-
block-start, and past-block-end. 11515 super-editor pass, 0 fail.

* test(document-api): positive-path + write-side selection coverage

Addresses PR review findings on test coverage:

- Adds `selection-info-resolver.test.ts` (11 cases) covering
  `resolveCurrentSelectionInfo` projection (empty state, single-block
  selection, multi-block segment-per-touched-block, missing blockId,
  includeText on/off, active-marks empty path) and
  `subscribeToSelection` (listener fires once per tick, unsubscribe
  stops firing, queued-microtask-cancellation on unmount).
- Adds 3 write-side cases to `comments-wrappers.test.ts` for the
  multi-segment path: out-of-order rejection with INVALID_TARGET /
  "document order" message, non-contiguous-gap rejection with
  "contiguous" message, and the contiguous-success path verifying
  the spanned PM range [first.from, last.to] is applied.
- Updates `assemble-adapters.test.ts` to assert both
  `selection.current` and `selection.onChange` are wired on the
  adapter bag.
- Adds a new section in `tests/consumer-typecheck/src/customer-scenario.ts`
  exercising the exported `editor.doc.selection.current()` surface,
  `SelectionInfo` destructuring, multi-segment `TextTarget` pass-through
  to `comments.create`, and the `onChange` subscription shape. Requires
  threading the new types through `packages/super-editor/src/index.ts`
  and `packages/superdoc/src/index.js` JSDoc typedefs so they are
  reachable from the `superdoc` package entrypoint.
- Exempts `selection.onChange` from the contract-parity member-path
  check via `META_MEMBER_PATHS` — it is a subscription primitive, not
  a request/response operation, so it does not belong in
  `OPERATION_DEFINITIONS` / schemas / dispatch. Fixes the `validate`
  CI job that otherwise rejects the new runtime member.

Deferred to SD-2671 (follow-up):
- doc-api-stories/comments/multi-segment-target.ts (CLI-harness story)
- doc-api-stories/selection story
- Playwright behavior test that drives selection.current → comments.create

Verified: document-api 1374 pass, super-editor 11529 pass,
tests/consumer-typecheck compiles clean against the packed tarball.

* fix(document-api): type-guard comment target routing + intersect marks per-node

Two bot findings on PR 2941:

- Comment-target routing used `'segments' in target` to pick between
  the TextAddress and TextTarget branches. That misclassifies a
  TextAddress that happens to carry an extra `segments` field (e.g.
  from object spread or a caller with wider union types) and then
  crashes on `segments[0]` inside `targetToSegments`. Replaced with an
  `isTextTargetShape` guard that requires `kind === 'text'` plus a
  non-empty `segments` array — matching the runtime contract the
  document-api validator already enforces. Malformed payloads now fall
  through to the single-block branch and surface as clean
  `INVALID_TARGET` responses.

- `markTypesPresentEverywhere` expanded each text node's mark set once
  per selected character and intersected those arrays afterwards. For a
  10 KB selection that allocated 10,000 Set references per event, and
  `selection.onChange` fires frequently during editing. Rewrote as a
  running intersection over text nodes: initialise from the first
  overlapping node's mark set, intersect with each subsequent node,
  stop descending once the intersection empties. O(text-nodes) with
  bounded allocation; same return value.

Tests: +4 regression cases (type-guard misclassification, per-node
intersection across multiple runs, empty-intersection for a mixed
marked/unmarked selection, 10k-char selection completes under 50ms).
Adapter suite 3190 pass, 0 fail.

* fix(document-api): close 5 multi-segment / selection edge cases on PR 2941

Five real correctness regressions surfaced in review-round-2:

- Hybrid TextAddress+TextTarget payloads (both shapes carried in one
  object) passed both `isTextAddress` and `isTextTarget` validators, then
  routed through the segments branch and silently dropped blockId/range.
  Hardened `isTextTargetShape` to reject TextAddress-style fields, so
  hybrids fall through to the explicit-block path.

- Two collapsed segments in different blocks slipped both the order +
  contiguity guards AND the spanning-range collapse check (because
  firstResolved.from < lastResolved.to across the block boundary), then
  silently anchored a comment over content the caller never selected.
  Added a per-segment collapse check before the resolution loop.

- `textBetween(prev.to, curr.from, '')` returns '' when the gap is
  composed entirely of inline atoms (images, math, etc), so an
  atom-only gap passed the contiguity check. Pass a `leafText`
  callback so atoms still register as gap content. Block separators
  remain represented by an empty `blockSeparator`, so legitimate
  cross-block adjacency still produces an empty gap and accepts.

- `collectTextSegments` skipped textblocks with no addressable id and
  emitted segments for the rest, returning a TextTarget that didn't
  cover the user's selection. Now bails out and returns null for the
  whole selection so callers can refuse the action rather than act on
  partial data.

- `subscribeToSelection` listened to both `selectionUpdate` and
  `transaction` to catch programmatic selection changes that don't fire
  the former. The `transaction` event also fires on every keystroke, so
  the listener ran per character even when SelectionInfo was unchanged.
  Added a content-key dedupe (empty + segments + activeMarks) so
  identical states fire the listener once. The listener still fires
  immediately when SelectionInfo changes for any reason.

Also: relaxed the 10k-char wall-clock perf bound from 50ms to 500ms
(the functional assertion is the real correctness check; the timing
is a smoke check that won't flake on noisy CI workers).

Tests: +6 regression cases (hybrid routing, collapsed multi-block,
atom-only gap, non-addressable block aborts the walk, transaction
dedupe, dedupe doesn't become sticky after a real change).
Adapter suite 3198 pass, 0 fail.

Author: caio-pizzol

apps/docs/document-api/available-operations.mdx

@@ -41,6 +41,7 @@ Use the tables below to see what operations are available and where each one is
 | Query | 1 | 0 | 1 | [Reference](/document-api/reference/query/index) |
 | Ranges | 1 | 0 | 1 | [Reference](/document-api/reference/ranges/index) |
 | Sections | 18 | 0 | 18 | [Reference](/document-api/reference/sections/index) |
+| Selection | 1 | 0 | 1 | [Reference](/document-api/reference/selection/index) |
 | Styles | 1 | 0 | 1 | [Reference](/document-api/reference/styles/index) |
 | Table of Authorities | 11 | 0 | 11 | [Reference](/document-api/reference/authorities/index) |
 | Table of Contents | 10 | 0 | 10 | [Reference](/document-api/reference/toc/index) |
@@ -366,6 +367,7 @@ Use the tables below to see what operations are available and where each one is
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setLinkToPrevious(...)</code></span> | [`sections.setLinkToPrevious`](/document-api/reference/sections/set-link-to-previous) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setPageBorders(...)</code></span> | [`sections.setPageBorders`](/document-api/reference/sections/set-page-borders) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.clearPageBorders(...)</code></span> | [`sections.clearPageBorders`](/document-api/reference/sections/clear-page-borders) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.selection.current(...)</code></span> | [`selection.current`](/document-api/reference/selection/current) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.styles.apply(...)</code></span> | [`styles.apply`](/document-api/reference/styles/apply) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.authorities.list(...)</code></span> | [`authorities.list`](/document-api/reference/authorities/list) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.authorities.get(...)</code></span> | [`authorities.get`](/document-api/reference/authorities/get) |

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

@@ -355,6 +355,8 @@
     "apps/docs/document-api/reference/sections/set-section-direction.mdx",
     "apps/docs/document-api/reference/sections/set-title-page.mdx",
     "apps/docs/document-api/reference/sections/set-vertical-align.mdx",
+    "apps/docs/document-api/reference/selection/current.mdx",
+    "apps/docs/document-api/reference/selection/index.mdx",
     "apps/docs/document-api/reference/styles/apply.mdx",
     "apps/docs/document-api/reference/styles/index.mdx",
     "apps/docs/document-api/reference/styles/paragraph/clear-style.mdx",
@@ -989,6 +991,13 @@
       "pagePath": "apps/docs/document-api/reference/ranges/index.mdx",
       "title": "Ranges"
     },
+    {
+      "aliasMemberPaths": [],
+      "key": "selection",
+      "operationIds": ["selection.current"],
+      "pagePath": "apps/docs/document-api/reference/selection/index.mdx",
+      "title": "Selection"
+    },
     {
       "aliasMemberPaths": [],
       "key": "diff",
@@ -1018,5 +1027,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "c8670fb494b56c19fbd09a7bada35974fbb3c22d938f6a5e01eee6e8467961c0"
+  "sourceHash": "f5c0786256e77432e9b9a58bc2009e39e2e832f6b0b2b625ee6dbeb3a762bdd6"
 }

apps/docs/document-api/reference/capabilities/get.mdx

@@ -1895,6 +1895,11 @@ _No fields._
 | `operations.sections.setVerticalAlign.dryRun` | boolean | yes |  |
 | `operations.sections.setVerticalAlign.reasons` | enum[] | no |  |
 | `operations.sections.setVerticalAlign.tracked` | boolean | yes |  |
+| `operations.selection.current` | object | yes |  |
+| `operations.selection.current.available` | boolean | yes |  |
+| `operations.selection.current.dryRun` | boolean | yes |  |
+| `operations.selection.current.reasons` | enum[] | no |  |
+| `operations.selection.current.tracked` | boolean | yes |  |
 | `operations.styles.apply` | object | yes |  |
 | `operations.styles.apply.available` | boolean | yes |  |
 | `operations.styles.apply.dryRun` | boolean | yes |  |
@@ -4116,6 +4121,11 @@ _No fields._
       "dryRun": true,
       "tracked": false
     },
+    "selection.current": {
+      "available": true,
+      "dryRun": false,
+      "tracked": false
+    },
     "styles.apply": {
       "available": true,
       "dryRun": true,
@@ -17469,6 +17479,41 @@ _No fields._
           ],
           "type": "object"
         },
+        "selection.current": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "HELPER_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE",
+                  "STYLES_PART_MISSING",
+                  "COLLABORATION_ACTIVE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
         "styles.apply": {
           "additionalProperties": false,
           "properties": {
@@ -19756,6 +19801,7 @@ _No fields._
         "trackChanges.decide",
         "query.match",
         "ranges.resolve",
+        "selection.current",
         "mutations.preview",
         "mutations.apply",
         "capabilities.get",

apps/docs/document-api/reference/comments/create.mdx

@@ -27,12 +27,7 @@ Returns a Receipt confirming the comment was created; reports NO_OP if the ancho
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `parentCommentId` | string | no |  |
-| `target` | TextAddress | no | TextAddress |
-| `target.blockId` | string | no |  |
-| `target.kind` | `"text"` | no | Constant: `"text"` |
-| `target.range` | Range | no | Range |
-| `target.range.end` | integer | no |  |
-| `target.range.start` | integer | no |  |
+| `target` | TextAddress \\| TextTarget | no | One of: TextAddress, TextTarget |
 | `text` | string | yes |  |
 
 ### Example request
@@ -118,8 +113,15 @@ Returns a Receipt confirming the comment was created; reports NO_OP if the ancho
       "type": "string"
     },
     "target": {
-      "$ref": "#/$defs/TextAddress",
-      "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
+      "description": "Text range to anchor the comment. Accepts either a single-block TextAddress {kind:'text', blockId, range} or a multi-segment TextTarget {kind:'text', segments:[{blockId, range}, ...]} for selections that span blocks.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/TextAddress"
+        },
+        {
+          "$ref": "#/$defs/TextTarget"
+        }
+      ]
     },
     "text": {
       "description": "Comment text content.",

apps/docs/document-api/reference/index.mdx

@@ -49,6 +49,7 @@ This reference is sourced from `packages/document-api/src/contract/*`.
 | Citations | 15 | 0 | 15 | [Open](/document-api/reference/citations/index) |
 | Table of Authorities | 11 | 0 | 11 | [Open](/document-api/reference/authorities/index) |
 | Ranges | 1 | 0 | 1 | [Open](/document-api/reference/ranges/index) |
+| Selection | 1 | 0 | 1 | [Open](/document-api/reference/selection/index) |
 | Diff | 3 | 0 | 3 | [Open](/document-api/reference/diff/index) |
 | Protection | 3 | 0 | 3 | [Open](/document-api/reference/protection/index) |
 | Permission Ranges | 5 | 0 | 5 | [Open](/document-api/reference/permission-ranges/index) |
@@ -583,6 +584,12 @@ The tables below are grouped by namespace.
 | --- | --- | --- |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/ranges/resolve"><code>ranges.resolve</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.ranges.resolve(...)</code></span> | Resolve two explicit anchors into a contiguous document range. Returns a transparent SelectionTarget, a mutation-ready ref, and preview metadata. Stateless and deterministic. |
 
+#### Selection
+
+| Operation | API member path | Description |
+| --- | --- | --- |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/selection/current"><code>selection.current</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.selection.current(...)</code></span> | Read the editor's current selection as a portable SelectionInfo with a text-anchored TextTarget. Primitive for building custom comments UIs, floating toolbars, and other selection-driven components without reaching into ProseMirror internals. |
+
 #### Diff
 
 | Operation | API member path | Description |

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

@@ -0,0 +1,133 @@
+---
+title: selection.current
+sidebarTitle: selection.current
+description: "Read the editor's current selection as a portable SelectionInfo with a text-anchored TextTarget. Primitive for building custom comments UIs, floating toolbars, and other selection-driven components without reaching into ProseMirror internals."
+---
+
+{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
+
+## Summary
+
+Read the editor's current selection as a portable SelectionInfo with a text-anchored TextTarget. Primitive for building custom comments UIs, floating toolbars, and other selection-driven components without reaching into ProseMirror internals.
+
+- Operation ID: `selection.current`
+- API member path: `editor.doc.selection.current(...)`
+- Mutates document: `no`
+- Idempotency: `idempotent`
+- Supports tracked mode: `no`
+- Supports dry run: `no`
+- Deterministic target resolution: `yes`
+
+## Expected result
+
+Returns a SelectionInfo with `empty`, `target` (TextTarget or null), `activeMarks`, and optionally `text` when `includeText: true`.
+
+## Input fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `includeText` | boolean | no |  |
+
+### Example request
+
+```json
+{
+  "includeText": true
+}
+```
+
+## Output fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `activeMarks` | string[] | yes |  |
+| `empty` | boolean | yes |  |
+| `target` | TextTarget \\| null | yes | One of: TextTarget, null |
+| `text` | string | no |  |
+
+### Example response
+
+```json
+{
+  "activeMarks": [
+    "example"
+  ],
+  "empty": true,
+  "target": {
+    "kind": "text",
+    "segments": [
+      {
+        "blockId": "block-abc123",
+        "range": {
+          "end": 10,
+          "start": 0
+        }
+      }
+    ]
+  },
+  "text": "Hello, world."
+}
+```
+
+## Pre-apply throws
+
+- `INVALID_INPUT`
+- `INVALID_CONTEXT`
+
+## Non-applied failure codes
+
+- None
+
+## Raw schemas
+
+<Accordion title="Raw input schema">
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "includeText": {
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}
+```
+</Accordion>
+
+<Accordion title="Raw output schema">
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "activeMarks": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "empty": {
+      "type": "boolean"
+    },
+    "target": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/TextTarget"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "empty",
+    "target",
+    "activeMarks"
+  ],
+  "type": "object"
+}
+```
+</Accordion>

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

@@ -0,0 +1,16 @@
+---
+title: Selection operations
+sidebarTitle: Selection
+description: Selection operation reference from the canonical Document API contract.
+---
+
+{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
+
+[Back to full reference](../index)
+
+Read the editor's current selection as a portable, addressable target.
+
+| Operation | Member path | Mutates | Idempotency | Tracked | Dry run |
+| --- | --- | --- | --- | --- | --- |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/selection/current"><code>selection.current</code></a></span> | `selection.current` | No | `idempotent` | No | No |
+

apps/docs/document-engine/sdks.mdx

@@ -581,6 +581,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.blocks.deleteRange` | `blocks delete-range` | Delete a contiguous range of top-level blocks between two endpoints (inclusive). Both endpoints must be direct children of the document node. Supports dry-run preview. |
 | `doc.query.match` | `query match` | Deterministic selector-based search returning mutation-grade addresses and text ranges. Use this to discover targets before any mutation. |
 | `doc.ranges.resolve` | `ranges resolve` | Resolve two explicit anchors into a contiguous document range. Returns a transparent SelectionTarget, a mutation-ready ref, and preview metadata. Stateless and deterministic. |
+| `doc.selection.current` | `selection current` | Read the editor's current selection as a portable SelectionInfo with a text-anchored TextTarget. Primitive for building custom comments UIs, floating toolbars, and other selection-driven components without reaching into ProseMirror internals. |
 | `doc.mutations.preview` | `mutations preview` | Dry-run a mutation plan, returning resolved targets without applying changes. |
 | `doc.mutations.apply` | `mutations apply` | Execute a mutation plan atomically against the document. |
 | `doc.capabilities.get` | `capabilities` | Query runtime capabilities supported by the current document engine. |
@@ -1042,6 +1043,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.blocks.delete_range` | `blocks delete-range` | Delete a contiguous range of top-level blocks between two endpoints (inclusive). Both endpoints must be direct children of the document node. Supports dry-run preview. |
 | `doc.query.match` | `query match` | Deterministic selector-based search returning mutation-grade addresses and text ranges. Use this to discover targets before any mutation. |
 | `doc.ranges.resolve` | `ranges resolve` | Resolve two explicit anchors into a contiguous document range. Returns a transparent SelectionTarget, a mutation-ready ref, and preview metadata. Stateless and deterministic. |
+| `doc.selection.current` | `selection current` | Read the editor's current selection as a portable SelectionInfo with a text-anchored TextTarget. Primitive for building custom comments UIs, floating toolbars, and other selection-driven components without reaching into ProseMirror internals. |
 | `doc.mutations.preview` | `mutations preview` | Dry-run a mutation plan, returning resolved targets without applying changes. |
 | `doc.mutations.apply` | `mutations apply` | Execute a mutation plan atomically against the document. |
 | `doc.capabilities.get` | `capabilities` | Query runtime capabilities supported by the current document engine. |

packages/document-api/scripts/check-contract-parity.ts

@@ -23,15 +23,23 @@ import { buildDispatchTable } from '../src/invoke/invoke.js';
 
 /**
  * Meta-methods and helper methods on DocumentApi that are not contract
- * operations. `ranges.scrollIntoView` is a browser-only UI side-effect
- * (scrolls the viewport via the presentation editor) — it has no
- * headless implementation, so it is intentionally excluded from the RPC
- * dispatch surface and the CLI command catalog. Direct calls through
- * `editor.doc.ranges.scrollIntoView()` are still supported.
+ * operations:
+ *
+ * - `ranges.scrollIntoView` is a browser-only UI side-effect (scrolls
+ *   the viewport via the presentation editor). It has no headless
+ *   implementation, so it is intentionally excluded from the RPC
+ *   dispatch surface and the CLI command catalog. Direct calls through
+ *   `editor.doc.ranges.scrollIntoView()` are still supported.
+ * - `selection.onChange` is a subscription primitive (push-based, no
+ *   request/response shape) rather than a request-response operation,
+ *   so it is not represented in `OPERATION_DEFINITIONS` / schemas /
+ *   dispatch. Direct calls through `editor.doc.selection.onChange()`
+ *   are still supported.
  */
 const META_MEMBER_PATHS = [
   'invoke',
   'ranges.scrollIntoView',
+  'selection.onChange',
   ...REFERENCE_OPERATION_ALIASES.map((alias) => alias.memberPath),
 ];