fix(document-api): return fresh table ref in mutation responses

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

@@ -139,6 +139,46 @@ Use `query.match` (not `find`) for this workflow. `query.match` returns `BlockNo
 
 For direct single-operation calls, prefer `item.target`. For plans or multi-step edits, prefer `item.handle.ref` so every step reuses the same resolved match.
 
+## Chain table mutations with returned refs
+
+For non-destructive table-targeted mutations, reuse `result.table.nodeId` from the previous success result. You do not need an intermediate `find()` between calls.
+
+```ts
+const created = editor.doc.create.table({
+  rows: 2,
+  columns: 2,
+});
+
+if (!created.success || !created.table) return;
+
+const bordered = editor.doc.tables.setBorder({
+  nodeId: created.table.nodeId,
+  edge: 'top',
+  lineStyle: 'single',
+  lineWeightPt: 1,
+  color: '000000',
+});
+
+if (!bordered.success || !bordered.table) return;
+
+const inserted = editor.doc.tables.insertColumn({
+  tableNodeId: bordered.table.nodeId,
+  columnIndex: 0,
+  position: 'right',
+});
+
+if (!inserted.success || !inserted.table) return;
+
+editor.doc.tables.setCellSpacing({
+  nodeId: inserted.table.nodeId,
+  spacingPt: 2,
+});
+```
+
+<Info>
+This handoff contract applies to table-targeted calls. Cell-targeted `tables.setBorder`, `tables.clearBorder`, `tables.setShading`, and `tables.clearShading` still return the targeted `tableCell` address today.
+</Info>
+
 ## Build a selection explicitly with ranges.resolve
 
 Use `ranges.resolve` when you already know the anchor points and want a transparent `SelectionTarget` plus a reusable mutation-ready ref:
@@ -240,7 +280,7 @@ editor2.destroy();
 ```
 
 <Info>
-`nodeId` stability depends on the ID source. For DOCX-imported content, `nodeId` comes from `paraId` when available and is best-effort stable across loads. For nodes created at runtime, it falls back to `sdBlockId`, which is volatile.
+`nodeId` stability depends on the ID source. For DOCX-imported content, `nodeId` comes from `paraId` when available and is best-effort stable across loads. Runtime-created content is still not guaranteed stable across loads; many nodes use session-scoped editor identity, while some structures such as tables or table cells may expose deterministic fallback IDs instead of raw `sdBlockId`.
 </Info>
 
 <Warning>

apps/docs/document-api/overview.mdx

@@ -69,15 +69,15 @@ Use `item.handle.ref` when you want multiple operations or a mutation plan to re
 
 For DOCX documents, `nodeId` is derived from the file's native `w14:paraId` attribute. In practice, this is usually stable when you reopen the same unchanged DOCX across separate editor sessions, machines, or headless CLI pipelines.
 
-For nodes created at runtime (not imported from DOCX), `nodeId` falls back to `sdBlockId`, a UUID generated when the editor opens. This fallback is volatile and changes on every load.
+For nodes created at runtime (not imported from DOCX), `nodeId` is still best-effort only. Many runtime nodes use session-scoped editor identity, and some structures such as tables or table cells may expose deterministic fallback IDs instead of a raw UUID-like `sdBlockId`. Either way, cross-session stability is not guaranteed.
 
 | ID source | Stable across loads? | When used |
 |-----------|---------------------|-----------|
 | `paraId` (from DOCX) | Best effort (usually stable for unchanged DOCX blocks) | Paragraphs and table rows imported from DOCX |
-| `sdBlockId` (runtime) | No (session-scoped) | Nodes created programmatically before first export |
+| Runtime-derived ID | No guarantee (often session-scoped; some table addresses use deterministic fallbacks) | Nodes created programmatically before first export |
 
 <Tip>
-If you need to reference blocks across separate editor sessions, use `editor.doc.query.match()` (or persist `nodeId` and reconstruct a `NodeAddress`) — don't read `node.attrs.sdBlockId` directly. The Document API resolves `paraId` first for DOCX-imported content.
+If you need to reference blocks across separate editor sessions, use `editor.doc.query.match()` (or persist `nodeId` and reconstruct a `NodeAddress`) — don't read `node.attrs.sdBlockId` directly. The Document API resolves `paraId` first for DOCX-imported content and may derive safer public IDs for some runtime structures such as tables.
 </Tip>
 
 <Warning>

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

@@ -67,6 +67,10 @@ Returns a CreateTableResult with the new table block ID and address.
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+On success, `result.table` is the created table address. Reuse `result.table.nodeId` for follow-up table operations in the same session.
+</Tip>
+
 ### Example response
 
 ```json
@@ -75,7 +79,7 @@ Returns a CreateTableResult with the new table block ID and address.
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

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

@@ -68,7 +68,7 @@ The tables below are grouped by namespace.
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-markdown"><code>getMarkdown</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getMarkdown(...)</code></span> | Extract the document content as a Markdown string. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/get-html"><code>getHtml</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.getHtml(...)</code></span> | Extract the document content as an HTML string. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/markdown-to-fragment"><code>markdownToFragment</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.markdownToFragment(...)</code></span> | Convert a Markdown string into an SDM/1 structural fragment. |
-| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, and list counts, plus outline and capabilities. |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/info"><code>info</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/clear-content"><code>clearContent</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.clearContent(...)</code></span> | Clear all document body content, leaving a single empty paragraph. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/insert"><code>insert</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.insert(...)</code></span> | Insert content into the document. Two input shapes: legacy string-based (value + type) inserts inline content at a text position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target is omitted, content appends at the end of the document. Legacy 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. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/replace"><code>replace</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.replace(...)</code></span> | 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. |

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

@@ -1,7 +1,7 @@
 ---
 title: info
 sidebarTitle: info
-description: Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, and list counts, plus outline and capabilities.
+description: Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities.
 ---
 
 {/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
@@ -10,7 +10,7 @@ description: Return document summary info including word, character, paragraph,
 
 ## Summary
 
-Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, and list counts, plus outline and capabilities.
+Return document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities.
 
 - Operation ID: `info`
 - API member path: `editor.doc.info(...)`
@@ -22,7 +22,7 @@ Return document summary info including word, character, paragraph, heading, tabl
 
 ## Expected result
 
-Returns a DocumentInfo object with counts (words, characters, paragraphs, headings, tables, images, comments, trackedChanges, sdtFields, lists), document outline, capability flags, and revision.
+Returns a DocumentInfo object with counts (words, characters, paragraphs, headings, tables, images, comments, trackedChanges, sdtFields, lists, and optionally pages when pagination is active), document outline, capability flags, and revision.
 
 ## Input fields
 
@@ -49,6 +49,7 @@ _No fields._
 | `counts.headings` | integer | yes |  |
 | `counts.images` | integer | yes |  |
 | `counts.lists` | integer | yes |  |
+| `counts.pages` | integer | no |  |
 | `counts.paragraphs` | integer | yes |  |
 | `counts.sdtFields` | integer | yes |  |
 | `counts.tables` | integer | yes |  |
@@ -73,6 +74,7 @@ _No fields._
     "headings": 3,
     "images": 2,
     "lists": 1,
+    "pages": 1,
     "paragraphs": 12,
     "sdtFields": 1,
     "tables": 1,
@@ -157,6 +159,9 @@ _No fields._
         "lists": {
           "type": "integer"
         },
+        "pages": {
+          "type": "integer"
+        },
         "paragraphs": {
           "type": "integer"
         },

apps/docs/document-api/reference/tables/apply-border-preset.mdx

@@ -38,12 +38,11 @@ _No fields._
 
 ```json
 {
-  "nodeId": "node-def456",
   "preset": "box",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -71,6 +70,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -79,7 +82,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/clear-border.mdx

@@ -39,11 +39,10 @@ _No fields._
 ```json
 {
   "edge": "top",
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -71,6 +70,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -79,7 +82,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/clear-cell-spacing.mdx

@@ -38,11 +38,10 @@ _No fields._
 
 ```json
 {
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -70,6 +69,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -78,7 +81,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/clear-contents.mdx

@@ -38,11 +38,10 @@ _No fields._
 
 ```json
 {
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -70,6 +69,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -78,7 +81,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/clear-shading.mdx

@@ -38,11 +38,10 @@ _No fields._
 
 ```json
 {
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -70,6 +69,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -78,7 +81,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/clear-style.mdx

@@ -38,11 +38,10 @@ _No fields._
 
 ```json
 {
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -70,6 +69,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -78,7 +81,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {

apps/docs/document-api/reference/tables/convert-from-text.mdx

@@ -39,11 +39,10 @@ _No fields._
 ```json
 {
   "delimiter": "tab",
-  "nodeId": "node-def456",
   "target": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   }
 }
 ```
@@ -71,6 +70,10 @@ _No fields._
 | `failure.message` | string | yes |  |
 | `success` | `false` | yes | Constant: `false` |
 
+<Tip>
+When present, `result.table` is the follow-up address to reuse after this call. For non-destructive table-targeted mutations, pass `result.table.nodeId` to the next table operation instead of re-running `find()`. Destructive operations may omit `table`, and cell-targeted border/shading calls may still return a `tableCell` address.
+</Tip>
+
 ### Example response
 
 ```json
@@ -79,7 +82,7 @@ _No fields._
   "table": {
     "kind": "block",
     "nodeId": "node-def456",
-    "nodeType": "paragraph"
+    "nodeType": "table"
   },
   "trackedChangeRefs": [
     {