feat: extend document-api with format, examples, create.heading

apps/docs/__tests__/doctest.test.ts

@@ -65,6 +65,7 @@ for (const [file, fileExamples] of byFile) {
         const editor = await Editor.open(Buffer.from(fixtureBuffer), {
           extensions: getStarterExtensions(),
           suppressDefaultDocxStyles: true,
+          telemetry: { enabled: false },
         });
 
         try {

apps/docs/document-api/overview.mdx

@@ -31,8 +31,8 @@ Use the tables below to see what operations are available and where each one is
 | --- | --- | --- |
 | Core | 8 | [Reference](/document-api/reference/core/index) |
 | Capabilities | 1 | [Reference](/document-api/reference/capabilities/index) |
-| Create | 1 | [Reference](/document-api/reference/create/index) |
-| Format | 1 | [Reference](/document-api/reference/format/index) |
+| Create | 2 | [Reference](/document-api/reference/create/index) |
+| Format | 4 | [Reference](/document-api/reference/format/index) |
 | Lists | 8 | [Reference](/document-api/reference/lists/index) |
 | Comments | 11 | [Reference](/document-api/reference/comments/index) |
 | Track Changes | 6 | [Reference](/document-api/reference/track-changes/index) |
@@ -48,7 +48,11 @@ Use the tables below to see what operations are available and where each one is
 | `editor.doc.replace(...)` | [`replace`](/document-api/reference/replace) |
 | `editor.doc.delete(...)` | [`delete`](/document-api/reference/delete) |
 | `editor.doc.format.bold(...)` | [`format.bold`](/document-api/reference/format/bold) |
+| `editor.doc.format.italic(...)` | [`format.italic`](/document-api/reference/format/italic) |
+| `editor.doc.format.underline(...)` | [`format.underline`](/document-api/reference/format/underline) |
+| `editor.doc.format.strikethrough(...)` | [`format.strikethrough`](/document-api/reference/format/strikethrough) |
 | `editor.doc.create.paragraph(...)` | [`create.paragraph`](/document-api/reference/create/paragraph) |
+| `editor.doc.create.heading(...)` | [`create.heading`](/document-api/reference/create/heading) |
 | `editor.doc.lists.list(...)` | [`lists.list`](/document-api/reference/lists/list) |
 | `editor.doc.lists.get(...)` | [`lists.get`](/document-api/reference/lists/get) |
 | `editor.doc.lists.insert(...)` | [`lists.insert`](/document-api/reference/lists/insert) |
@@ -76,3 +80,76 @@ Use the tables below to see what operations are available and where each one is
 | `editor.doc.trackChanges.rejectAll(...)` | [`trackChanges.rejectAll`](/document-api/reference/track-changes/reject-all) |
 | `editor.doc.capabilities()` | [`capabilities.get`](/document-api/reference/capabilities/get) |
 {/* DOC_API_OPERATIONS_END */}
+
+## Common workflows
+
+These patterns show how operations compose to cover typical tasks.
+
+### Find and mutate
+
+Locate text in the document, then replace it:
+
+```ts
+const result = editor.doc.find({ type: 'text', text: 'foo' });
+const target = result.context?.[0]?.textRanges?.[0];
+if (target) {
+  editor.doc.replace({ target, text: 'bar' });
+}
+```
+
+### Tracked-mode insert
+
+Insert text as a tracked change so reviewers can accept or reject it:
+
+```ts
+const receipt = editor.doc.insert(
+  { text: 'new content' },
+  { changeMode: 'tracked' },
+);
+```
+
+The receipt includes a `resolution` with the resolved insertion point and `inserted` entries with tracked-change IDs.
+
+### Check capabilities before acting
+
+Use `capabilities()` to branch on what the editor supports:
+
+```ts
+const caps = editor.doc.capabilities();
+
+if (caps.operations['format.bold'].available) {
+  editor.doc.format.bold({ target });
+}
+
+if (caps.global.trackChanges.enabled) {
+  editor.doc.insert({ text: 'tracked' }, { changeMode: 'tracked' });
+}
+```
+
+### Dry-run preview
+
+Pass `dryRun: true` to validate an operation without applying it:
+
+```ts
+const preview = editor.doc.insert(
+  { target, text: 'hello' },
+  { dryRun: true },
+);
+// preview.success tells you whether the insert would succeed
+// preview.resolution shows the resolved target range
+```
+
+## Programmatic invocation
+
+Every operation is also available through a dynamic `invoke` method on the Document API instance. It accepts an `operationId` string and dispatches to the corresponding method. This is useful when the operation to run is determined at runtime (for example, from a tool-use payload).
+
+```ts
+// doc is the DocumentApi instance (editor.doc)
+const result = doc.invoke({
+  operationId: 'insert',
+  input: { text: 'hello' },
+  options: { changeMode: 'tracked' },
+});
+```
+
+`invoke` delegates to the same direct methods — there is no separate execution path. Type safety is available through `InvokeRequest<T>` for callers who know the operation at compile time, and `DynamicInvokeRequest` for dynamic dispatch.

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

@@ -16,12 +16,16 @@
     "apps/docs/document-api/reference/comments/set-active.mdx",
     "apps/docs/document-api/reference/comments/set-internal.mdx",
     "apps/docs/document-api/reference/core/index.mdx",
+    "apps/docs/document-api/reference/create/heading.mdx",
     "apps/docs/document-api/reference/create/index.mdx",
     "apps/docs/document-api/reference/create/paragraph.mdx",
     "apps/docs/document-api/reference/delete.mdx",
     "apps/docs/document-api/reference/find.mdx",
     "apps/docs/document-api/reference/format/bold.mdx",
     "apps/docs/document-api/reference/format/index.mdx",
+    "apps/docs/document-api/reference/format/italic.mdx",
+    "apps/docs/document-api/reference/format/strikethrough.mdx",
+    "apps/docs/document-api/reference/format/underline.mdx",
     "apps/docs/document-api/reference/get-node-by-id.mdx",
     "apps/docs/document-api/reference/get-node.mdx",
     "apps/docs/document-api/reference/get-text.mdx",
@@ -62,13 +66,13 @@
     },
     {
       "key": "create",
-      "operationIds": ["create.paragraph"],
+      "operationIds": ["create.paragraph", "create.heading"],
       "pagePath": "apps/docs/document-api/reference/create/index.mdx",
       "title": "Create"
     },
     {
       "key": "format",
-      "operationIds": ["format.bold"],
+      "operationIds": ["format.bold", "format.italic", "format.underline", "format.strikethrough"],
       "pagePath": "apps/docs/document-api/reference/format/index.mdx",
       "title": "Format"
     },
@@ -120,5 +124,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "8d875ceb279d213c1e779882f103d39fa2106545ce94c6b1553ae06b6c321e03"
+  "sourceHash": "3e7edc551feb80b42bfa59f928a0ce1f34ecb7cf71952d5a489107089105d543"
 }

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

@@ -537,6 +537,38 @@ description: Generated reference for capabilities.get
           ],
           "type": "object"
         },
+        "create.heading": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
         "create.paragraph": {
           "additionalProperties": false,
           "properties": {
@@ -665,6 +697,102 @@ description: Generated reference for capabilities.get
           ],
           "type": "object"
         },
+        "format.italic": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
+        "format.strikethrough": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
+        "format.underline": {
+          "additionalProperties": false,
+          "properties": {
+            "available": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "reasons": {
+              "items": {
+                "enum": [
+                  "COMMAND_UNAVAILABLE",
+                  "OPERATION_UNAVAILABLE",
+                  "TRACKED_MODE_UNAVAILABLE",
+                  "DRY_RUN_UNAVAILABLE",
+                  "NAMESPACE_UNAVAILABLE"
+                ]
+              },
+              "type": "array"
+            },
+            "tracked": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "available",
+            "tracked",
+            "dryRun"
+          ],
+          "type": "object"
+        },
         "getNode": {
           "additionalProperties": false,
           "properties": {
@@ -1316,7 +1444,11 @@ description: Generated reference for capabilities.get
         "replace",
         "delete",
         "format.bold",
+        "format.italic",
+        "format.underline",
+        "format.strikethrough",
         "create.paragraph",
+        "create.heading",
         "lists.list",
         "lists.get",
         "lists.insert",