fix(extract): emit a block per cell paragraph for table contents (SD-2653)

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

@@ -20,7 +20,7 @@ Use the tables below to see what operations are available and where each one is
 | Citations | 15 | 0 | 15 | [Reference](/document-api/reference/citations/index) |
 | Comments | 5 | 0 | 5 | [Reference](/document-api/reference/comments/index) |
 | Content Controls | 55 | 0 | 55 | [Reference](/document-api/reference/content-controls/index) |
-| Core | 13 | 0 | 13 | [Reference](/document-api/reference/core/index) |
+| Core | 14 | 0 | 14 | [Reference](/document-api/reference/core/index) |
 | Create | 6 | 0 | 6 | [Reference](/document-api/reference/create/index) |
 | Cross-References | 5 | 0 | 5 | [Reference](/document-api/reference/cross-refs/index) |
 | Diff | 3 | 0 | 3 | [Reference](/document-api/reference/diff/index) |
@@ -148,6 +148,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.getHtml(...)</code></span> | [`getHtml`](/document-api/reference/get-html) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.markdownToFragment(...)</code></span> | [`markdownToFragment`](/document-api/reference/markdown-to-fragment) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | [`info`](/document-api/reference/info) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.extract(...)</code></span> | [`extract`](/document-api/reference/extract) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.clearContent(...)</code></span> | [`clearContent`](/document-api/reference/clear-content) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.insert(...)</code></span> | [`insert`](/document-api/reference/insert) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | [`replace`](/document-api/reference/replace) |

apps/docs/document-api/common-workflows.mdx

@@ -333,6 +333,42 @@ for (const tc of content.trackedChanges) {
 }
 ```
 
+### Tables
+
+Tables are expanded into their constituent paragraphs — one block per paragraph inside each cell. Cell paragraphs carry a `tableContext` with the enclosing table ID and their row/column coordinates:
+
+```ts
+for (const block of content.blocks) {
+  if (!block.tableContext) continue;
+  const { tableNodeId, rowIndex, colIndex } = block.tableContext;
+  console.log(`${tableNodeId} r${rowIndex}c${colIndex}:`, block.text);
+  // → 'table-1 r0c0: Shape'
+  // → 'table-1 r1c0: Cone'
+  // → 'table-1 r1c1: 3'
+}
+```
+
+- `tableNodeId` groups blocks that belong to the same table (useful for multiple or nested tables).
+- Cells can hold multiple paragraphs; each emits its own block with the same `tableContext` coordinates and a distinct `nodeId`.
+
+Group cells into row-level chunks for better RAG retrieval:
+
+```ts
+const rows = new Map<string, typeof content.blocks>();
+for (const block of content.blocks) {
+  if (!block.tableContext) continue;
+  const key = `${block.tableContext.tableNodeId}::${block.tableContext.rowIndex}`;
+  (rows.get(key) ?? rows.set(key, []).get(key)!).push(block);
+}
+
+for (const rowBlocks of rows.values()) {
+  rowBlocks.sort((a, b) => a.tableContext!.colIndex - b.tableContext!.colIndex);
+  const rowText = rowBlocks.map((b) => b.text).join(" | ");
+  // → 'Cone | 3 | 1 | 1'
+  // Embed this row text; scrollToElement(rowBlocks[0].nodeId) navigates to it.
+}
+```
+
 ### RAG pipeline pattern
 
 Extract content, chunk it, store the IDs, and navigate back on click:
@@ -349,6 +385,7 @@ const chunks = blocks
     text: b.text,
     type: b.type,
     headingLevel: b.headingLevel,
+    tableContext: b.tableContext,
   }));
 const embeddings = await embedChunks(chunks);
 

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

@@ -130,6 +130,7 @@
     "apps/docs/document-api/reference/diff/capture.mdx",
     "apps/docs/document-api/reference/diff/compare.mdx",
     "apps/docs/document-api/reference/diff/index.mdx",
+    "apps/docs/document-api/reference/extract.mdx",
     "apps/docs/document-api/reference/fields/get.mdx",
     "apps/docs/document-api/reference/fields/index.mdx",
     "apps/docs/document-api/reference/fields/insert.mdx",
@@ -436,6 +437,7 @@
         "getHtml",
         "markdownToFragment",
         "info",
+        "extract",
         "clearContent",
         "insert",
         "replace",
@@ -1016,5 +1018,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "b61fad6a3a330af8a57b78ded260c8d8918486c9829b50804227fbeb15e8bf53"
+  "sourceHash": "49a093393b35e57695836273aa8a8aedd05514a2539553981570714ab1b5d2b8"
 }

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

@@ -855,6 +855,11 @@ _No fields._
 | `operations.diff.compare.dryRun` | boolean | yes |  |
 | `operations.diff.compare.reasons` | enum[] | no |  |
 | `operations.diff.compare.tracked` | boolean | yes |  |
+| `operations.extract` | object | yes |  |
+| `operations.extract.available` | boolean | yes |  |
+| `operations.extract.dryRun` | boolean | yes |  |
+| `operations.extract.reasons` | enum[] | no |  |
+| `operations.extract.tracked` | boolean | yes |  |
 | `operations.fields.get` | object | yes |  |
 | `operations.fields.get.available` | boolean | yes |  |
 | `operations.fields.get.dryRun` | boolean | yes |  |
@@ -3071,6 +3076,11 @@ _No fields._
       "dryRun": false,
       "tracked": false
     },
+    "extract": {
+      "available": true,
+      "dryRun": false,
+      "tracked": false
+    },
     "fields.get": {
       "available": true,
       "dryRun": false,
@@ -10179,6 +10189,41 @@ _No fields._
           ],
           "type": "object"
         },
+        "extract": {
+          "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"
+        },
         "fields.get": {
           "additionalProperties": false,
           "properties": {
@@ -19570,6 +19615,7 @@ _No fields._
         "getHtml",
         "markdownToFragment",
         "info",
+        "extract",
         "clearContent",
         "insert",
         "replace",

apps/docs/document-api/reference/content-controls/create.mdx

@@ -27,6 +27,10 @@ Returns a ContentControlMutationResult with the created content control target.
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `alias` | string | no |  |
+| `at` | SelectionTarget | no | SelectionTarget |
+| `at.end` | SelectionPoint | no | SelectionPoint |
+| `at.kind` | `"selection"` | no | Constant: `"selection"` |
+| `at.start` | SelectionPoint | no | SelectionPoint |
 | `content` | string | no |  |
 | `controlType` | string | no |  |
 | `kind` | enum | yes | `"block"`, `"inline"` |
@@ -120,6 +124,9 @@ Returns a ContentControlMutationResult with the created content control target.
     "alias": {
       "type": "string"
     },
+    "at": {
+      "$ref": "#/$defs/SelectionTarget"
+    },
     "content": {
       "type": "string"
     },

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

@@ -21,6 +21,7 @@ Primary read and write operations.
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-html"><code>getHtml</code></a></span> | `getHtml` | No | `idempotent` | No | No |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/markdown-to-fragment"><code>markdownToFragment</code></a></span> | `markdownToFragment` | No | `idempotent` | No | No |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | `info` | No | `idempotent` | No | No |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/extract"><code>extract</code></a></span> | `extract` | No | `idempotent` | No | No |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/clear-content"><code>clearContent</code></a></span> | `clearContent` | Yes | `conditional` | No | No |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/insert"><code>insert</code></a></span> | `insert` | Yes | `non-idempotent` | Yes | Yes |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | `replace` | Yes | `conditional` | Yes | Yes |