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

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

@@ -571,6 +571,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.getHtml` | `get-html` | Extract the document content as an HTML string. |
 | `doc.markdownToFragment` | `markdown-to-fragment` | Convert a Markdown string into an SDM/1 structural fragment. |
 | `doc.info` | `info` | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
+| `doc.extract` | `extract` | Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes — each with an ID compatible with scrollToElement(). |
 | `doc.clearContent` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
 | `doc.insert` | `insert` | Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
 | `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
@@ -580,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. |
@@ -1031,6 +1033,7 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.get_html` | `get-html` | Extract the document content as an HTML string. |
 | `doc.markdown_to_fragment` | `markdown-to-fragment` | Convert a Markdown string into an SDM/1 structural fragment. |
 | `doc.info` | `info` | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
+| `doc.extract` | `extract` | Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes — each with an ID compatible with scrollToElement(). |
 | `doc.clear_content` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
 | `doc.insert` | `insert` | Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
 | `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
@@ -1040,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

@@ -21,8 +21,17 @@ import { OPERATION_DEFINITIONS } from '../src/contract/operation-definitions.js'
 import { OPERATION_REFERENCE_DOC_PATH_MAP } from '../src/contract/reference-doc-map.js';
 import { buildDispatchTable } from '../src/invoke/invoke.js';
 
-/** Meta-methods and helper methods on DocumentApi that are not contract operations. */
-const META_MEMBER_PATHS = ['invoke', ...REFERENCE_OPERATION_ALIASES.map((alias) => alias.memberPath)];
+/**
+ * Meta-methods and helper methods on DocumentApi that are not contract
+ * operations. `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.
+ */
+const META_MEMBER_PATHS = [
+  'invoke',
+  'selection.onChange',
+  ...REFERENCE_OPERATION_ALIASES.map((alias) => alias.memberPath),
+];
 
 function collectFunctionMemberPaths(value: unknown, prefix = ''): string[] {
   if (!value || typeof value !== 'object') return [];