feat(document-api): clear content command

apps/cli/scripts/export-sdk-contract.ts

@@ -57,6 +57,7 @@ const INTENT_NAMES = {
   'doc.getHtml': 'get_document_html',
   'doc.info': 'get_document_info',
   'doc.capabilities.get': 'get_capabilities',
+  'doc.clearContent': 'clear_content',
   'doc.insert': 'insert_content',
   'doc.replace': 'replace_content',
   'doc.delete': 'delete_content',

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -1943,6 +1943,14 @@ export const SUCCESS_SCENARIOS = {
       ],
     };
   },
+  'doc.clearContent': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-clear-content-success');
+    const docPath = await harness.copyFixtureDoc('doc-clear-content');
+    return {
+      stateDir,
+      args: ['clear-content', docPath, '--out', harness.createOutputPath('doc-clear-content-output')],
+    };
+  },
   'doc.insert': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-insert-success');
     const docPath = await harness.copyFixtureDoc('doc-insert');

apps/cli/src/cli/operation-hints.ts

@@ -78,6 +78,7 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   getMarkdown: 'extracted markdown',
   getHtml: 'extracted html',
   info: 'retrieved info',
+  clearContent: 'cleared document content',
   insert: 'inserted text',
   replace: 'replaced text',
   delete: 'deleted text',
@@ -240,6 +241,7 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   getMarkdown: 'plain',
   getHtml: 'plain',
   info: 'documentInfo',
+  clearContent: 'receipt',
   insert: 'mutationReceipt',
   replace: 'mutationReceipt',
   delete: 'mutationReceipt',
@@ -386,6 +388,7 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   getMarkdown: 'markdown',
   getHtml: 'html',
   info: null,
+  clearContent: 'receipt',
   insert: null,
   replace: null,
   delete: null,
@@ -561,6 +564,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   getMarkdown: 'query',
   getHtml: 'query',
   info: 'general',
+  clearContent: 'general',
   insert: 'textMutation',
   replace: 'textMutation',
   delete: 'textMutation',

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

@@ -17,7 +17,7 @@ Use the tables below to see what operations are available and where each one is
 | Blocks | 1 | 0 | 1 | [Reference](/document-api/reference/blocks/index) |
 | Capabilities | 1 | 0 | 1 | [Reference](/document-api/reference/capabilities/index) |
 | Comments | 5 | 0 | 5 | [Reference](/document-api/reference/comments/index) |
-| Core | 10 | 0 | 10 | [Reference](/document-api/reference/core/index) |
+| Core | 11 | 0 | 11 | [Reference](/document-api/reference/core/index) |
 | Create | 6 | 0 | 6 | [Reference](/document-api/reference/create/index) |
 | Format | 44 | 1 | 45 | [Reference](/document-api/reference/format/index) |
 | History | 3 | 0 | 3 | [Reference](/document-api/reference/history/index) |
@@ -50,6 +50,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.getMarkdown(...)</code></span> | [`getMarkdown`](/document-api/reference/get-markdown) |
 | <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.info(...)</code></span> | [`info`](/document-api/reference/info) |
+| <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) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.delete(...)</code></span> | [`delete`](/document-api/reference/delete) |

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

@@ -5,6 +5,7 @@
     "apps/docs/document-api/reference/blocks/index.mdx",
     "apps/docs/document-api/reference/capabilities/get.mdx",
     "apps/docs/document-api/reference/capabilities/index.mdx",
+    "apps/docs/document-api/reference/clear-content.mdx",
     "apps/docs/document-api/reference/comments/create.mdx",
     "apps/docs/document-api/reference/comments/delete.mdx",
     "apps/docs/document-api/reference/comments/get.mdx",
@@ -262,6 +263,7 @@
         "getMarkdown",
         "getHtml",
         "info",
+        "clearContent",
         "insert",
         "replace",
         "delete"
@@ -604,5 +606,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "d1b97baae61be333b72dc1211180bc02dd451e14a3767328d56929bf77a10132"
+  "sourceHash": "fb9f6aa91bd10748ac21af2465aa97ce59b8e4a9043f6fd0aa07fb7e175cd5c6"
 }

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

@@ -282,6 +282,11 @@ _No fields._
 | `operations.capabilities.get.dryRun` | boolean | yes |  |
 | `operations.capabilities.get.reasons` | enum[] | no |  |
 | `operations.capabilities.get.tracked` | boolean | yes |  |
+| `operations.clearContent` | object | yes |  |
+| `operations.clearContent.available` | boolean | yes |  |
+| `operations.clearContent.dryRun` | boolean | yes |  |
+| `operations.clearContent.reasons` | enum[] | no |  |
+| `operations.clearContent.tracked` | boolean | yes |  |
 | `operations.comments.create` | object | yes |  |
 | `operations.comments.create.available` | boolean | yes |  |
 | `operations.comments.create.dryRun` | boolean | yes |  |
@@ -1729,6 +1734,14 @@ _No fields._
       ],
       "tracked": true
     },
+    "clearContent": {
+      "available": true,
+      "dryRun": true,
+      "reasons": [
+        "COMMAND_UNAVAILABLE"
+      ],
+      "tracked": true
+    },
     "comments.create": {
       "available": true,
       "dryRun": true,
@@ -5272,6 +5285,41 @@ _No fields._
           ],
           "type": "object"
         },
+        "clearContent": {
+          "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"
+        },
         "comments.create": {
           "additionalProperties": false,
           "properties": {
@@ -13156,6 +13204,7 @@ _No fields._
         "getMarkdown",
         "getHtml",
         "info",
+        "clearContent",
         "insert",
         "replace",
         "delete",

apps/docs/document-api/reference/clear-content.mdx

@@ -0,0 +1,187 @@
+---
+title: clearContent
+sidebarTitle: clearContent
+description: Clear all document body content, leaving a single empty paragraph.
+---
+
+{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
+
+> Alpha: Document API is currently alpha and subject to breaking changes.
+
+## Summary
+
+Clear all document body content, leaving a single empty paragraph.
+
+- Operation ID: `clearContent`
+- API member path: `editor.doc.clearContent(...)`
+- Mutates document: `yes`
+- Idempotency: `conditional`
+- Supports tracked mode: `no`
+- Supports dry run: `no`
+- Deterministic target resolution: `yes`
+
+## Expected result
+
+Returns a Receipt with success status; reports NO_OP if the document is already empty.
+
+## Input fields
+
+_No fields._
+
+### Example request
+
+```json
+{}
+```
+
+## Output fields
+
+### Variant 1 (success=true)
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `inserted` | EntityAddress[] | no |  |
+| `removed` | EntityAddress[] | no |  |
+| `success` | `true` | yes | Constant: `true` |
+| `updated` | EntityAddress[] | no |  |
+
+### Variant 2 (success=false)
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `failure` | object | yes |  |
+| `failure.code` | enum | yes | `"NO_OP"` |
+| `failure.details` | any | no |  |
+| `failure.message` | string | yes |  |
+| `success` | `false` | yes | Constant: `false` |
+
+### Example response
+
+```json
+{
+  "inserted": [
+    {
+      "entityId": "entity-789",
+      "entityType": "comment",
+      "kind": "entity"
+    }
+  ],
+  "success": true,
+  "updated": [
+    {
+      "entityId": "entity-789",
+      "entityType": "comment",
+      "kind": "entity"
+    }
+  ]
+}
+```
+
+## Pre-apply throws
+
+- `CAPABILITY_UNAVAILABLE`
+
+## Non-applied failure codes
+
+- `NO_OP`
+
+## Raw schemas
+
+<Accordion title="Raw input schema">
+```json
+{
+  "additionalProperties": false,
+  "properties": {},
+  "type": "object"
+}
+```
+</Accordion>
+
+<Accordion title="Raw output schema">
+```json
+{
+  "oneOf": [
+    {
+      "$ref": "#/$defs/ReceiptSuccess"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "failure": {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "enum": [
+                "NO_OP"
+              ]
+            },
+            "details": {},
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        },
+        "success": {
+          "const": false
+        }
+      },
+      "required": [
+        "success",
+        "failure"
+      ],
+      "type": "object"
+    }
+  ]
+}
+```
+</Accordion>
+
+<Accordion title="Raw success schema">
+```json
+{
+  "$ref": "#/$defs/ReceiptSuccess"
+}
+```
+</Accordion>
+
+<Accordion title="Raw failure schema">
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "failure": {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "enum": [
+            "NO_OP"
+          ]
+        },
+        "details": {},
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "type": "object"
+    },
+    "success": {
+      "const": false
+    }
+  },
+  "required": [
+    "success",
+    "failure"
+  ],
+  "type": "object"
+}
+```
+</Accordion>

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-markdown"><code>getMarkdown</code></a></span> | `getMarkdown` | No | `idempotent` | No | No |
 | <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/info"><code>info</code></a></span> | `info` | 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 |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/delete"><code>delete</code></a></span> | `delete` | Yes | `conditional` | Yes | Yes |

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

@@ -20,7 +20,7 @@ Document API is currently alpha and subject to breaking changes.
 
 | Namespace | Canonical ops | Aliases | Total surface | Reference |
 | --- | --- | --- | --- | --- |
-| Core | 10 | 0 | 10 | [Open](/document-api/reference/core/index) |
+| Core | 11 | 0 | 11 | [Open](/document-api/reference/core/index) |
 | Blocks | 1 | 0 | 1 | [Open](/document-api/reference/blocks/index) |
 | Capabilities | 1 | 0 | 1 | [Open](/document-api/reference/capabilities/index) |
 | Create | 6 | 0 | 6 | [Open](/document-api/reference/create/index) |
@@ -55,6 +55,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/info"><code>info</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.info(...)</code></span> | Return document metadata including revision, node count, 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 at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the `type` field. |
 | <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 target position with new text or inline content. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/delete"><code>delete</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.delete(...)</code></span> | Delete content at a target position. |