ReferenceCore
Core operations
Primary read and write operations.
17 operations. Names, descriptions, and behavior flags come from the canonical contract.
Operations
clearContentClear all document body content, leaving a single empty paragraph.mutatesdeleteDelete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode.mutatestrackedextractExtract 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().readfindSearch the document for text or node matches using SDM/1 selectors. Returns discovery-grade results: for mutation targeting, use query.match instead.readgetRead the full document as an SDDocument structure.readgetHtmlExtract the document content as an HTML string.readgetMarkdownExtract the document content as a Markdown string.readgetNodeRetrieve a single node by target position.readgetNodeByIdResolve a block ID across the body, linked headers/footers, and supported textboxes, optionally restricted by story. Paragraphs at every table-cell depth and top-level body/header/footer tables are supported; notes, comments, glossary, and nested table containers are excluded.readgetTextExtract the plain-text content of the document.readhtmlToFragmentConvert an HTML string into an SDM/1 structural fragment.readinfoReturn document summary info including word, character, paragraph, heading, table, image, comment, tracked-change, SDT-field, list, and page counts, plus outline and capabilities.readinsertInsert content into the document. Text, rich, structural, and native OOXML 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. Native type:ooxml accepts namespaces and dependency manifests, or capture accepts a portable selection.extractOoxml result. Native copies remap package and review identities and require direct mode. Rich markdown/html and structural modes use `placement` (before/after/insideStart/insideEnd) to position relative to a block target.mutatesmarkdownToFragmentConvert a Markdown string into an SDM/1 structural fragment.readprojectHtmlProject document content as HTML with review, scope, diagnostics, and provenance metadata.readprojectMarkdownProject document content as Markdown with review, scope, diagnostics, and provenance metadata.readreplaceOptional replaceMode:contents retains one paragraph, heading, or listItem container while applying text, HTML, Markdown, SDFragment, or native OOXML inlines. A retained snapshotId source restores exact same-session original markup with an expectedSnapshotId local precondition. These writes require direct mode; existing selection and structural behavior is unchanged. Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. For explicit single-paragraph text selections, expectedText rejects mismatches with PRECONDITION_FAILED before mutation. Tracked text replacements accept replacementGranularity: word (default), phrase (join neighboring edits separated only by spaces), or range (replace the complete selection). This requires an explicit single-paragraph text selection. Rich string path accepts HTML or Markdown plus a BlockNodeAddress, SelectionTarget, or ref. Structural path accepts the same locator forms plus SDFragment content. A single-paragraph rich replacement may overlap pending insertions: tracked mode drops the covered part of your own insertion, nests a deletion inside another author's insertion, and adds the content as a new insertion; direct mode removes the covered part and leaves the rest pending. A tracked rich replacement spanning paragraphs that crosses a pending insertion, or a range that mixes pending insertions with comment, bookmark, field, or content-control markup, rejects without changes; capabilities.check reports the same result. An explicit {kind:'story', storyType:'body'} target replaces the complete main body in direct mode while preserving the destination DOCX package.mutates