@docx-editor.dev/editor-api

getReviewItemRangefunctionSource ↗

The range a review item covers, by the key the editor's review queue gives it.

Pass the key of an item from editor.getReviewItems() or useReview().items. A tracked change resolves to the characters it covers. A paired replacement key resolves to one range over both its deletion and its insertion. A comment or reply resolves to the range its thread is anchored to. The range is a snapshot like any other.

To act on the card's own change, use [getReviewItemRevisions](getReviewItemRevisions). [Range.revisions](Range.revisions) on this range also lists nested or adjacent changes that the range overlaps.

A key that names nothing in the document, such as one whose change was already accepted, or a comment with no anchor in the document, fails the sync with ItemNotFound. Use [getReviewItemRangeOrNullObject](getReviewItemRangeOrNullObject) to test for that instead. A custom node's key refuses with NotSupported at the call.

This is a DocxEditor addition. Office.js has no review queue and no key for a revision.

declare function getReviewItemRange(context: RequestContext, key: string): Range;

Read the words a comment card is about 


```ts
import { getReviewItemRange } from '@docx-editor.dev/editor-api/browser';

const key = item.key; // From useReview().items or editor.getReviewItems().
const text = await runtime.run(async (context) => {
  const range = getReviewItemRange(context, key);
  range.load('text');
  await context.sync();
  return range.text;
});
```

getReviewItemRangeOrNullObjectfunctionSource ↗

The range a review item covers, or a null object when the key names nothing.

The same lookup as [getReviewItemRange](getReviewItemRange). A key that names nothing in the document answers a range whose isNullObject is true after the sync, instead of failing it.

This is a DocxEditor addition. Office.js has no review queue and no key for a revision.

declare function getReviewItemRangeOrNullObject(context: RequestContext, key: string): Range;

Skip a card whose change another reviewer already resolved 


```ts
import { getReviewItemRangeOrNullObject } from '@docx-editor.dev/editor-api/browser';

const key = item.key; // From useReview().items or editor.getReviewItems().
await runtime.run(async (context) => {
  const range = getReviewItemRangeOrNullObject(context, key);
  range.load('text');
  await context.sync();

  if (range.isNullObject) return;
  console.log(range.text);
});
```

getReviewItemRevisionsfunctionSource ↗

The tracked changes a review card stands for, by the key the editor's review queue gives it.

Pass the key of a revision item from editor.getReviewItems() or useReview().items. The collection holds that change only, or the deletion and the insertion of a paired replacement. Unlike [Range.revisions](Range.revisions) on the card's range, it never holds a nested or adjacent change by another author.

A key that names nothing in the document, such as one whose change was already resolved, loads an empty collection, and acceptAll() or rejectAll() on it refuses with InvalidObjectPath. A comment or custom node key refuses with NotSupported at the call. resolve() and setAuthor() refuse with NotSupported on this collection.

This is a DocxEditor addition. Office.js has no review queue and no key for a revision.

declare function getReviewItemRevisions(context: RequestContext, key: string): RevisionCollection;

Accept the change a review card shows 


```ts
import { getReviewItemRevisions } from '@docx-editor.dev/editor-api/browser';

const key = item.key; // From useReview().items or editor.getReviewItems().
await runtime.run(async (context) => {
  getReviewItemRevisions(context, key).acceptAll();
  await context.sync();
});
```

isDocxEditorErrorfunctionSource ↗

Whether a caught value is one of ours.

By name as well as by instanceof: a consumer can end up with two copies of this module (a bundle plus a dependency's), and an instanceof that fails across them would send a perfectly ordinary PropertyNotLoaded down a consumer's unexpected-error path.

declare function isDocxEditorError(value: unknown): value is DocxEditorError;

Body_2class

A story: the main body of a document, a header or footer variant, or a note's body — and everything in it in reading order.

Its paragraphs are the DOCUMENT'S, not just the top level's. A paragraph inside a table cell, or inside a table inside a cell, or inside a block-level content control, is an ordinary editable paragraph and appears here, exactly as it does in Word's own paragraph collection. A collection listing only direct children would describe a smaller document than the one on screen.

[Body.clear](Body.clear) leaves one empty paragraph, matching what Word produces when a reader selects everything and deletes. A body that already holds no paragraph reports InvalidArgument rather than inventing a block.

declare class Body extends ModelObject

BookmarkclassSource ↗

A name a document gives to a stretch of itself.

A bookmark IS its name. OOXML writes it as a pair of markers around the text, and the name is the only thing identifying it — so this object is a name plus the range those markers currently enclose. A bookmark whose markers left with the text they surrounded refuses rather than answering where they used to be.

start and end are absent by design: they are document-wide character offsets, the coordinate space this API does not maintain.

declare class Bookmark extends ModelObject implements PromisedItem

BookmarkCollectionclassSource ↗

The bookmarks of a story or a range, as of the batch that loaded them.

Like every collection here, items is the LOADED answer rather than a live view: bookmarks added after the load are not in it, and reaching them means loading again.

declare class BookmarkCollection extends HandleCollection<Bookmark>

ClientObjectclassSource ↗

The base every document proxy extends.

A proxy is three things and no more: the context it belongs to, the path that says whether it can be addressed, and the properties a completed load filled in.

A RELEASED proxy still answers what it already knew. Reading a property loaded before the run ended is served from memory, because that value is a copy the consumer already holds — it is not a reach into a document. Anything that would talk to the document (load, a write, a method) refuses with InvalidObjectPath. The line is "does this need the document", not "does this look like a read".

declare abstract class ClientObject implements RuntimeManagedObject

ClientResultclassSource ↗

A value a queued method promised to produce, readable after the next sync().

Deliberately not a Promise. A method call inside a batch has not been sent yet, so there is no pending work to await and nothing that could resolve on its own — awaiting one would deadlock a consumer who then never calls sync(). A result is a box that stays EMPTY until the sync fills it, and reading it early is ValueNotLoaded rather than undefined flowing onwards into something that misinterprets it.

RevisionCollection.resolve returns a ClientResult with the resolved and skipped decisions.

declare class ClientResult<T>

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the ClientResult class.

Comment_2class

A comment: a conversation about a stretch of the document, not a single remark.

[Comment.replies](Comment.replies) holds the answers, and resolving is a property of the whole thread — assigning resolved marks this comment and everything answering it, which is what Word's own pane does.

authorEmail and a writable content are absent: CT_Comment records only an author and initials (Word's addresses live in people.xml, which this API does not read), and a body rewrite is not an operation the canonical write path offers. The comment's text is published as text.

declare class Comment extends CommentBase

CommentCollectionclassSource ↗

The comments on a document, story or range, as of the batch that loaded them.

declare class CommentCollection extends HandleCollection<Comment>

CommentReplyclassSource ↗

One answer in a comment thread.

Authored over the parent comment's own range, because that is where the conversation is anchored and OOXML gives a reply no other place to be. Resolving is a property of the whole thread rather than of any one reply — see [Comment.resolved](Comment.resolved).

declare class CommentReply extends CommentBase

CommentReplyCollectionclassSource ↗

The replies to one comment, in thread order, as of the batch that loaded them.

declare class CommentReplyCollection extends HandleCollection<CommentReply>

ContentControlclassSource ↗

A part of a document a template marked as a field.

A control is NOT its w:id. The attribute is optional in OOXML and unique nowhere, so a document may hold one control with no id and two with the same one. This object is addressed by an opaque host-minted handle instead, and [ContentControl.id](ContentControl.id) is answered as METADATA — a label the file wrote, empty where it wrote none. getById still exists, because a template author knows their own numbering, and it answers the first match in document order rather than refusing.

A control's contents are not its value. text reads the characters; setValue writes in the vocabulary the control's own type accepts — a declared item for a dropdown, an ISO date for a date picker, a state for a checkbox — because writing "true" into a checkbox's runs would produce a document whose glyph and whose w14:checked disagree.

declare class ContentControl extends ModelObject implements PromisedItem

ContentControlCollectionclassSource ↗

The content controls of a document, story or range, as of the batch that loaded them.

getById answers the first match in document order, because w:id is optional in OOXML and unique nowhere — see [ContentControl](ContentControl) for why choosing predictably beats refusing.

declare class ContentControlCollection extends HandleCollection<ContentControl>

Document_2class

The document: the root every other object is reached from.

Deliberately thin. A document here is not a bag of content — it is the thing that HAS stories. It publishes the main story as [Document.body](Document.body), plus that story's paragraphs directly as document.paragraphs, because that is how source-compatible code walks a document.

Reached once per [RequestContext](RequestContext) and memoized: context.document is the same object every time, so a property loaded through one reference reads back through any other.

declare class Document extends ModelObject

```ts
await runtime.run(async (context) => {
  const paragraphs = context.document.paragraphs;
  paragraphs.load('items');
  await context.sync();

  for (const paragraph of paragraphs.items) paragraph.load('text');
  await context.sync();

  for (const paragraph of paragraphs.items) console.log(paragraph.text);
});
```


 The first sync retrieves the collection's items. Once those items are available, the second sync retrieves each paragraph's text.

DocumentPropertiesclassSource ↗

Core document properties. Load explicit names before reads; assignments commit at sync. Values are XML-safe strings of at most 4096 characters. Tracked writes are unsupported. Individual dates and custom properties are unsupported. Document.removeDocumentInformation can remove property parts. Collaborative writes require an existing core-properties part. Create properties before joining collaboration when the input omits that part.

declare class DocumentProperties extends ModelObject

DocxEditorErrorclassSource ↗

Every refusal this runtime throws.

Branch on [DocxEditorError.code](DocxEditorError.code), never on the message. Codes are stable public API — added rather than repurposed — so a consumer that handles PropertyNotLoaded by loading and syncing again keeps working across versions.

Nothing from the engine appears in the message. Host rejection reasons, opaque handle refs and offset ranges are all withheld: a ref in a message is a name a consumer can start depending on, and a store's rejection reason would become a documented one the moment somebody matched on it. What a consumer gets instead is a stable code, a fixed sentence, and target — the consumer-facing path they wrote themselves.

declare class DocxEditorError extends Error

```ts
try {
  await context.sync();
} catch (error) {
  if (isDocxEditorError(error) && error.code === 'StaleDocument') {
    // Re-read, re-anchor, and reconsider: someone else changed the document first.
  }
}
```

FieldclassSource ↗

An inert Word field. Code writes and evaluation support PAGE and NUMPAGES. A field inside a pending tracked insertion reads, but refuses code writes and updateResult until accepted. Its cached result reads and writes through [Field.result](Field.result).

declare class Field extends ModelObject implements PromisedItem

FieldCollectionclassSource ↗

Fields contained within a body or range.

declare class FieldCollection extends ItemCollection<Field>

FontclassSource ↗

The character formatting of whatever it belongs to: a story, a stretch of one, or a paragraph.

A font has no identity of its own — it is a view onto its owner's characters and shares its owner's path, so a font reached from a deleted paragraph's range refuses at the same moment the range does rather than holding a stale address.

Reading is AGREEMENT, and null means "no agreed value": every run the owner covers says bold, or the answer is null. Null is also the answer when nothing in range authors the property at all. Both are one answer on purpose, because this API reads what the document AUTHORS rather than what the style cascade computes — a heading whose bold comes from styles.xml reads null. Answering the cascade would let a caller read an inherited value, write it straight back, and silently freeze it into the paragraph as if the author had chosen it.

Assignments within one sync() are ONE write: font.bold = true; font.size = 12 accumulates into a single run-property operation. That is required, not an optimisation — a run-property write carries the run's whole property bag, so a second write planned from the same pre-batch tree would carry a bag the first had already superseded, which the host refuses with ConflictingChanges.

declare class Font extends ModelObject

InlinePictureclassSource ↗

An inline PNG or JPEG picture. Measurements use points.

declare class InlinePicture extends ModelObject implements PromisedItem

InlinePictureCollectionclassSource ↗

Inline pictures within a body or range. Load items before enumeration.

declare class InlinePictureCollection extends ItemCollection<InlinePicture>

ListclassSource ↗

A list: the set of paragraphs sharing one numbering id.

A list is not an ELEMENT. OOXML has no list — it has paragraphs that each name a w:numId, and a list is the set that name the same one. So [List.id](List.id) is that number, [List.paragraphs](List.paragraphs) is the set, and a list exists exactly as long as some paragraph is still in it.

declare class List extends ModelObject implements PromisedItem

ListCollectionclassSource ↗

The lists in a story, as of the batch that loaded them.

declare class ListCollection extends HandleCollection<List>

ListItemclassSource ↗

A paragraph's membership of a list: which list, and at what level.

listString (the "3." or "iv)" a reader sees) and siblingIndex are absent because they are PAINTED, not authored — computed during layout by a counter that walks the story applying numbering.xml, its abstract-numbering indirection, restarts and overrides. Answering them here would mean a second counter that disagrees with the one on screen the first time a document overrides a level.

declare class ListItem extends ModelObject

NoteItemclassSource ↗

One footnote or endnote: text that belongs to the document but not to its flow.

A note IS a story. Its [NoteItem.body](NoteItem.body) is an ordinary [Body](Body) — paragraphs, formatting, styles, the same operations — laid out at the foot of a page or the end of the document rather than in the column, so everything the object model can do to the main story it can do to a note without a second vocabulary.

delete() removes the reference too. A note's body and the citation that reached it are one thing to a reader, and deleting the body alone would leave a mark pointing at nothing. The engine spells that as a package-level transaction, which is why it travels alone in its batch.

declare class NoteItem extends ModelObject implements PromisedItem

NoteItemCollectionclassSource ↗

The notes of one kind, in the order the notes part writes them.

DocxEditor's own collection type: the pinned reference fixture does not carry Word.NoteItemCollection, so it is not measured for conformance — recorded as an omission in compat/manifest.json — while NoteItem itself is. Without it a note would be unreachable, which is the one thing worse than an unmeasured collection.

declare class NoteItemCollection extends HandleCollection<NoteItem>

PageSetupclassSource ↗

The page a section is laid out on: paper size, margins, and orientation.

This is w:sectPr — everything a caller usually wants from a section lives here rather than on [Section](Section) itself, which is mostly navigation.

declare class PageSetup extends ModelObject

ParagraphclassSource ↗

One paragraph: what it says, what it is, and the ways it can be changed.

Identity is the document's own. [Paragraph.uniqueLocalId](Paragraph.uniqueLocalId) is the w14:paraId the file carries — the value Word writes, and the one commentsExtended.xml and coauthoring merges already anchor to — never a position in a collection. Deleting the paragraph above this one does not change it, which is the point: an agent that read a document, thought about it, and now wants to write to "the paragraph I was looking at" cannot express that with an index. A paragraph the file gave no id gets one deterministically at open, so the same bytes always answer the same identities and saving writes them back.

A structural edit owns its paragraph for the batch: delete(), split() and insertParagraph() change what offsets mean, so a second call in the same sync() that also touches this paragraph is refused with ConflictingChanges rather than planned against coordinates that have stopped describing it. Two syncs get both edits, each exactly as asked.

declare class Paragraph extends ModelObject implements PromisedItem

ParagraphCollectionclassSource ↗

The paragraphs of a story, a range, or a list, as of the batch that loaded them.

Contains paragraphs at every depth — inside table cells, nested tables, and block-level content controls — matching Word's own collection rather than only the owner's direct children.

One of the two collections whose members are not plain handles: the pieces a [Paragraph.split](Paragraph.split) answers are filled in by the split's own command rather than by a separate listing read.

Load the paragraphs and a property of each in one sync with an items/ path, such as paragraphs.load('items/text').

declare class ParagraphCollection extends ItemCollection<Paragraph>

Range_2class

A stretch of a story: two endpoints, each a paragraph and a UTF-16 offset.

A range is a SNAPSHOT, not a tracked region. Its endpoints name the paragraphs they were found in and the offsets they were found at, so it stays meaningful across edits ELSEWHERE in the document and becomes an explicit InvalidObjectPath refusal once one of its paragraphs is gone. What it deliberately does not do is follow edits INSIDE itself: once its paragraph gains a word at offset 0, a range over "alpha" fails with StaleDocument when used, rather than reading or editing whatever now sits at offsets 0..5. Edits after the range, and formatting changes, keep it valid. Word's own ranges do move, by keeping a live region in the document; this API has none, and pretending otherwise would answer text from a place the caller was not looking at.

That is also why start and end are absent rather than unimplemented — they are document-wide character positions, a different addressing scheme from this API's paragraph identity plus UTF-16 offset. Ask a range for its [Range.paragraphs](Range.paragraphs) instead.

declare class Range extends ModelObject implements PromisedItem

RangeCollectionclassSource ↗

Ranges a read produced — the hits of a search, or the pieces a split answered.

Its members are SPANS rather than handles, which is what separates it from the handle-backed collections: each item carries its own paragraph-plus-offset endpoints instead of an opaque host-minted id.

Load the ranges and a property of each in one sync with an items/ path, such as results.load('items/text').

declare class RangeCollection extends ItemCollection<Range>

RequestContextclassSource ↗

What a run hands its callback: one queue, one document, one sync at a time.

sync() commits all queued commands in one atomic transaction. Supported read-derived proxy dependencies can require additional read-only transport calls before that commit. These reads and the final write share one revision; a concurrent change refuses the sync. A read on an object that a write in the same sync returns (the range insertText wrote, the paragraph insertParagraph created) is answered after that commit, on the revision it produced. If that read fails, the writes stay applied and sync() rejects with the read's error code, with debugInfo.innerError.code edit.read-after-commit: read again, and do not apply the same edit again. A write on such an object requires a separate sync.

Conditional writes come from the same place. A context that has READ from the document remembers the revision it read at, and a later batch that writes goes out conditional on it, failing StaleDocument if the document moved. That is what stops a decision made from a cached read being applied to a document that has since changed — the hazard the read-decide-write shape of any batching API invites. A context that has read nothing has nothing to be stale about, so its writes go out unconditionally.

declare class RequestContext

RevisionclassSource ↗

One tracked change.

A row is listed as Insert or Delete, and a cell or tracked numbering by its own type. A structural card with no single type, such as table grid history, is omitted rather than shipped with an unpublishable type. That listing is not the collection decision set: see [RevisionCollection](RevisionCollection).

declare class Revision extends ModelObject implements PromisedItem

RevisionCollectionclassSource ↗

The tracked changes on a document, story or range, as of the batch that loaded them.

items omits a structural card with no single revision type; see [Revision](Revision). On a story's collection, acceptAll / rejectAll still resolve every store-resolvable revision in the story and refuse atomically if any read-only or otherwise unsupported revision remains. On [Range.revisions](Range.revisions) and getReviewItemRevisions, they resolve the changes the range overlaps or the key names, and resolve and setAuthor refuse with NotSupported.

declare class RevisionCollection extends HandleCollection<Revision>

SectionclassSource ↗

One section: the document's layout, not its content.

Everything a caller usually wants — paper size, margins, orientation — is on [Section.pageSetup](Section.pageSetup). The section itself is mostly navigation: the story it governs, the header and footer stories it declares, and the section after it.

getHeader and getFooter answer a body that may not exist yet. A section with no first-page header inherits the previous section's. When no section declares one, the answer is an empty body: every read on it answers as an empty story, and asking does not create the part. The first text written into it creates the header or footer; asking alone would make a READ write to the document, and a header that exists only because it was asked about is a header the author never added.

declare class Section extends ModelObject implements PromisedItem

SectionCollectionclassSource ↗

The sections of a document, in document order, as of the batch that loaded them.

declare class SectionCollection extends HandleCollection<Section>

ShapeclassSource ↗

One floating or inline shape in a body or paragraph.

id, name and type are read-only. [Shape.body](Shape.body) exposes a supported shape's own text story, including text-bearing geometric shapes. Other shapes refuse body access.

declare class Shape extends ModelObject implements PromisedItem

ShapeCollectionclassSource ↗

The floating and inline shapes in a body or paragraph, in reading order.

declare class ShapeCollection extends ItemCollection<Shape>

StyleclassSource ↗

One style the document's styles part defines. Every property is read-only and needs a load before it is read; load() with no arguments reads them all.

nameLocal is the name the styles part declares. Only a style whose type is Paragraph can be assigned to paragraph.style, range.style, or body.style; those setters refuse character, table, and list style names. Table.style accepts the nameLocal of a listed table style.

declare class Style extends ModelObject

Offer the paragraph styles a reader would see 


```ts
const styles = context.document.getStyles();
styles.load('items/nameLocal,items/type,items/visibility,items/unhideWhenUsed,items/priority');
await context.sync();

// Keep hidden styles that unhide once used, such as heading 2, so they can be applied too.
// Many styles share priority 99, so sort by name next for a stable order.
const choices = styles.items
  .filter((style) => style.type === 'Paragraph' && (style.visibility || style.unhideWhenUsed))
  .sort((a, b) => a.priority - b.priority || a.nameLocal.localeCompare(b.nameLocal))
  .map((style) => style.nameLocal);
```

StyleCollectionclassSource ↗

The styles a document defines, of every kind, in the order its styles part writes them, as of the sync that loaded them.

The listing holds paragraph, character, table, and list styles. The paragraph.style, range.style, and body.style setters accept paragraph style names only; they refuse character, table, and list names. Check type before assigning a nameLocal. Every listed paragraph style applies through those setters. Styles with no name, an invalid name, or an unknown kind are not listed. A document with no styles part lists none.

load() with no arguments, or load('items'), reads every property of each style in the same sync. Name items/ paths to read fewer, such as styles.load('items/nameLocal,items/type').

declare class StyleCollection extends ModelObject

TableclassSource ↗

A canonical table. Reads require load() and sync().

declare class Table extends ModelObject implements PromisedItem

TableCellclassSource ↗

A table cell. Column width uses points and changes the whole grid column.

declare class TableCell extends ModelObject implements PromisedItem

TableCellCollectionclassSource ↗

A loaded collection of TableCell objects.

declare class TableCellCollection extends HandleCollection<TableCell>

TableCollectionclassSource ↗

A loaded collection of Table objects.

declare class TableCollection extends HandleCollection<Table>

TableRowclassSource ↗

A row with stable identity. Its cells follow document order.

declare class TableRow extends ModelObject implements PromisedItem

TableRowCollectionclassSource ↗

A loaded collection of TableRow objects.

declare class TableRowCollection extends HandleCollection<TableRow>

TrackedObjectsclassSource ↗

The objects a context keeps addressable beyond the run that created them.

An ordinary proxy stops being usable when its run ends. Tracking one keeps its address alive so a later run(object, callback) can adopt it, and untracking releases it — which matters for long-lived callers, since a tracked object is a document reference that will not be collected on its own.

declare class TrackedObjects

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the TrackedObjects class.

CommitPreviewOptionsinterfaceSource ↗

Options for [DocumentPreview.commit](DocumentPreview.commit).

interface CommitPreviewOptions

```ts
await preview.commit({ rebase: true });
```

CreateServerOptionsinterfaceSource ↗

How DocxEditor.createServer opens a document.

Opening DOCX bytes is a bounded parse: decompression-ratio and size caps, part and relationship path validation, DTD- and entity-free XML. Malformed input returns InvalidArgument. Resource refusals return ResourceLimitExceeded, with limit identifying the exceeded cap. File-controlled details and internal parser messages are never included.

The bounded parse is complete when this promise resolves. The runtime does not retain the caller's Uint8Array, so the caller may reuse or transfer that input buffer afterward.

interface CreateServerOptions

DocumentCapabilitiesinterfaceSource ↗

Capabilities exposed by a DocxEditor runtime, frozen for its lifetime.

interface DocumentCapabilities

DocumentCompareOptionsinterfaceSource ↗

Options of Document.compareFromBase64.

Supported: authorName, compareTarget (CompareTargetCurrent only), detectFormatChanges, and removeDateAndTime. addToRecentFiles and ignoreAllComparisonWarnings are accepted and have no effect: there is no recent-files list and no warning prompt. true for removePersonalInformation refuses with NotSupported.

interface DocumentCompareOptions

DocumentLimitsinterfaceSource ↗

Resource budgets applied while opening DOCX bytes, subject to engine ceilings.

interface DocumentLimits

DocumentPreviewinterfaceSource ↗

Other wording, shown in the page over the live document until it is committed or discarded. Answered by [DocxEditorRuntime.preview](DocxEditorRuntime.preview).

This is DocxEditor infrastructure with no Office.js equivalent.

interface DocumentPreview<T = void>

```ts
const preview = await runtime.preview(async (context) => {
  context.document.changeTrackingMode = 'TrackMineOnly';
  const range = context.document.body.search('thirty (30) days').getFirst();
  range.insertText('forty-five (45) days', 'Replace');
  await context.sync();
});
preview.reveal(); // scroll to the counter-proposal
// The page shows it as a tracked change. The live document is unchanged.
if (userAccepted) await preview.commit();
else preview.discard();
```

DocumentXmlLimitsinterfaceSource ↗

Resource limits for each parsed XML part.

interface DocumentXmlLimits

DocumentZipLimitsinterfaceSource ↗

Resource limits for the DOCX archive.

interface DocumentZipLimits

DocxEditorDebugInfointerfaceSource ↗

Debug details in the shape of Office.js OfficeExtension.DebugInfo.

interface DocxEditorDebugInfo

DocxEditorErrorInitinterfaceSource ↗

The fields a [DocxEditorError](DocxEditorError) is constructed from.

interface DocxEditorErrorInit

DocxEditorInnerErrorinterfaceSource ↗

Why the engine refused, as a public diagnostic code with its fixed hint.

interface DocxEditorInnerError

DocxEditorNamespaceinterfaceSource ↗

The entry point, as much of it as works without an editor.

An object rather than a TypeScript namespace: a namespace with runtime members is a declaration-merging construct that does not survive being re-exported through a bundler as predictably, and DocxEditor.createServer reads the same either way.

Import from @docx-editor.dev/editor-api/browser for the same namespace plus createBrowser.

interface DocxEditorNamespace

DocxEditorRuntimeinterfaceSource ↗

A runtime: one document host, many runs.

Runs are ISOLATED, not serialized. Every [DocxEditorRuntime.run](DocxEditorRuntime.run) gets its own context and its own queue, so two runs cannot interleave into one batch, and a run started inside another run works instead of waiting for a lock its own caller holds. Batches are still ordered — each sync() commits writes atomically; read dependencies can use additional read-only batches.

Disposal is final: [DocxEditorRuntime.dispose](DocxEditorRuntime.dispose) releases the host once and is safe to call again, and every later run fails with RuntimeDisposed.

interface DocxEditorRuntime

DocxEditorServerRuntimeinterfaceSource ↗

A runtime over DOCX bytes rather than a live editor — what DocxEditor.createServer answers.

Adds [DocxEditorServerRuntime.save](DocxEditorServerRuntime.save) to the shared contract, because a server runtime owns its document and can serialize it; a browser runtime borrows the editor's and cannot.

interface DocxEditorServerRuntime extends DocxEditorRuntime

EditorModuleinterfaceSource ↗

Capability module accepted by [createServer](createServer). Collaboration attaches through a collaboration contribution. Other contributions are ignored here.

interface EditorModule

LoadQueryOptionsinterfaceSource ↗

The object form of load(...): which properties, and how much of a collection.

An unknown key, a non-integer top, a property name that is not an identifier, or a value of the wrong type is refused as InvalidArgument here, naming the option — a misspelled key is the difference between "load selected properties" and "load nothing", which would otherwise surface as a PropertyNotLoaded much later at a call that looks correct.

interface LoadQueryOptions

RevisionAuthorOptionsinterfaceSource ↗

Options for [RevisionCollection.setAuthor](RevisionCollection.setAuthor).

interface RevisionAuthorOptions

RevisionAuthorSelectioninterfaceSource ↗

Select every change these authors made, for [RevisionCollection.setAuthor](RevisionCollection.setAuthor). Matches w:author exactly.

interface RevisionAuthorSelection

RunOptionsinterfaceSource ↗

Options for [DocxEditorRuntime.run](DocxEditorRuntime.run), passed before the callback.

This is DocxEditor infrastructure, not part of the Office.js object model: the Office.js run function has no options and no undo grouping.

interface RunOptions

```ts
// One review decision, one undo step: the editor's writes and every sync of the run.
const decision = editor.beginHistoryGroup();
try {
  const resolved = editor.exec(
    { type: 'resolveAllReviewChanges', action: 'reject', keys },
    { historyGroup: decision }
  );
  if (!resolved.ok) throw new Error(resolved.reason);
  await runtime.run({ historyGroup: decision }, async (context) => {
    const ranges = context.document.body.search('30 days');
    ranges.load('items');
    await context.sync();
    const target = ranges.items[0];
    if (!target) throw new Error('The document has no "30 days" text.');
    const replaced = target.insertText('45 days', 'Replace');
    await context.sync();
    replaced.insertComment('Counter-proposal: 45 days.');
    await context.sync();
  });
} finally {
  decision.end();
}
```

SearchOptionsinterfaceSource ↗

How a search is narrowed.

Every flag is honoured or REFUSED — never quietly ignored. A search that accepted matchWildcards and then ran a plain-text scan would answer the wrong offsets to a caller who edits at them, so the unimplemented options reach the host and come back as NotSupported.

They are declared here rather than left off the type because omitting them would make { matchWildcards: true } a compile error in code that is otherwise source-compatible with Word. The honest answer to that code is a runtime refusal naming the option, not a type error naming the interface.

interface SearchOptions

ServerPaginationOptionsinterfaceSource ↗

Explicit measurement inputs for headless field calculation.

interface ServerPaginationOptions extends AutomationPaginationOptions

BesideLocationtypeSource ↗

Which side of a paragraph or a range a new paragraph goes on.

type BesideLocation = Extract<RangeInsertTextLocation, 'Before' | 'After'>;

BodyInsertParagraphLocationtypeSource ↗

Where a story accepts a paragraph. Start/End mean "before the first"/"after the last".

type BodyInsertParagraphLocation = Extract<RangeInsertTextLocation, 'Start' | 'End'>;

BodyInsertTextLocationtypeSource ↗

Where a story accepts text: over all of it, or at either edge.

type BodyInsertTextLocation = Extract<RangeInsertTextLocation, 'Replace' | 'Start' | 'End'>;

ContentControlLockStatetypeSource ↗

The lock a control carries. ST_Lock, spelled as the schema spells it.

type ContentControlLockState = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';

ContentControlSubtypetypeSource ↗

The control types this API can create. Picture and repeating section are deferred.

type ContentControlSubtype = 'richText' | 'plainText' | 'dropDownList' | 'comboBox' | 'date';

ContentControlValuetypeSource ↗

What a control's own type accepts as a value.

A discriminated union rather than unknown: a dropdown and a checkbox do not take the same kind of thing, and a single setValue(value: string) would have to guess what 'true' means to a date picker.

type ContentControlValue = {
    readonly kind: 'text';
    readonly text: string;
} | {
    readonly kind: 'listItem';
    readonly value: string;
} | {
    readonly kind: 'checkbox';
    readonly checked: boolean;
}
/** `YYYY-MM-DD`, or a full ISO-8601 instant. */
 | {
    readonly kind: 'date';
    readonly iso: string;
};

CreateCollaborativeOptionstypeSource ↗

Options for [createCollaborative](createCollaborative).

type CreateCollaborativeOptions = CreateServerOptions;

DocumentPreviewStatustypeSource ↗

Where a [DocumentPreview](DocumentPreview) is in its life.

- active: the page shows the preview, and the live document has not moved since the preview began. - stale: the live document moved after the preview began: a collaboration peer edited it, or a local write landed while the callback ran. The page still shows the preview. commit() refuses with StaleDocument; commit({ rebase: true }) replays it on the current document instead. - ended: the preview was committed, discarded, or ended because its runtime was disposed or the editor loaded, detached, or remounted. The page shows the live document. Final.

type DocumentPreviewStatus = 'active' | 'stale' | 'ended';

```ts
preview.onStatusChanged((status) => {
  applyButton.textContent = status === 'stale' ? 'Apply to the current text' : 'Apply';
});
```

DocxEditorErrorCodetypeSource ↗

What went wrong, as a value a consumer may branch on.

type DocxEditorErrorCode = 
/** A property was read before a `load(...)` for it completed in a `sync()`. */
'PropertyNotLoaded'
/** A `ClientResult` value was read before the sync that fills it. */
 | 'ValueNotLoaded'
/**
 * The object cannot be addressed, in one of three ways.
 *
 * NOT YET: an item accessor answers a proxy the read that names it has not answered for, and it
 * becomes usable at the next `sync()`. NOT ANY MORE: its run ended and nothing tracked it, which
 * is terminal. GONE: the document no longer holds the object, because an edit removed or merged
 * it; `debugInfo.innerError.code` is then `edit.stale-target` and the message says so. One
 * code because from a consumer's side all three are "this object cannot be used here"; the
 * message says which one, because the fix for one is not the fix for the others.
 */
 | 'InvalidObjectPath'
/** The object still belongs to a run that has not finished, so it cannot be handed over. */
 | 'ObjectInUse'
/** An argument or load option this API does not accept. */
 | 'InvalidArgument'
/** Opening the document exceeded a bounded reader resource limit. */
 | 'ResourceLimitExceeded'
/** The collection has no such item — `getFirst()` on an empty one. */
 | 'ItemNotFound'
/**
 * The call is outside the supported subset for this host, mode, or content, and nothing
 * changed. Examples: a server has no selection to move; `TrackMineOnly` has no tracked form
 * for the operation; the OOXML or the field result holds content the subset does not take.
 *
 * Never retry the same call. Read `debugInfo.innerError.code` for the rule, then choose a
 * supported call, another mode, or other content.
 */
 | 'NotSupported'
/**
 * The member or rule is one this API does not implement for the target, and nothing changed.
 * Examples: a range member that a field result does not support; a tracked edit that touches
 * your own pending change or another author's pending structural change.
 *
 * Never retry the same call. Read `debugInfo.innerError.code` for the rule, then read the
 * target again and edit a different range, decide the pending change first, or use another
 * member.
 */
 | 'NotImplemented'
/**
 * Two calls in one batch make claims on the same paragraph that cannot both hold.
 *
 * A batch is one transaction planned against the state at its start, which stops being
 * unambiguous once two calls restructure the same paragraph. Split them across two `sync()`
 * calls and each gets exactly what it asked for.
 */
 | 'ConflictingChanges'
/** The request context's `run` has finished, so it can no longer be used. */
 | 'InvalidRequestContext'
/** The runtime was disposed. Every later operation fails this way. */
 | 'RuntimeDisposed'
/**
 * The request was built from an older read, so nothing was applied: another writer moved the
 * document, or a range's text moved since the range was read, including by this context's own
 * earlier sync. Read again before retrying.
 */
 | 'StaleDocument'
/** The host is live but holds no document right now — an editor between mounts. */
 | 'DocumentUnavailable'
/**
 * A preview is open over the editor, so it refuses this write or a second preview. Commit or
 * discard the open preview first. Browser runtime only.
 */
 | 'PreviewActive'
/** The preview has ended — committed, discarded, or replaced by a remount — so it cannot commit. */
 | 'PreviewEnded'
/** The document refused the change, or answered something this runtime cannot use. */
 | 'GeneralException';

FieldTypeLiteraltypeSource ↗

String forms of Office field types.

type FieldTypeLiteral = `${FieldType}`;

HeaderFooterTypetypeSource ↗

Which header or footer of a section: Word's own three variants.

type HeaderFooterType = 'Primary' | 'FirstPage' | 'EvenPages';

LoadOptiontypeSource ↗

Everything load(...) accepts: one property name, several, or a [LoadQueryOptions](LoadQueryOptions) object.

type LoadOption = string | readonly string[] | LoadQueryOptions;

```ts
paragraph.load('text');
paragraph.load(['text', 'style']);
paragraphs.load({ select: 'items', top: 5 });
paragraphs.load('items/text,items/style');
```


 On a collection, `items/<property>` loads `items` and that property on each item in the same `context.sync()`. A property name without the `items/` prefix means the same thing on a collection, so `paragraphs.load('text')` equals `paragraphs.load('items/text')`.  

Only one level of navigation is supported. A deeper path, such as `items/font/bold`, and a navigation path on an object that is not a collection, such as `font/bold`, are refused as `InvalidArgument`, with the path as the error's `target`. Load the navigation object itself instead, for example `paragraph.font.load('bold')` for each item.

NoteItemTypetypeSource ↗

Which kind of note: Word's own two.

type NoteItemType = 'Footnote' | 'Endnote';

ParagraphAlignmenttypeSource ↗

Paragraph alignment values readable and writable through this object model.

type ParagraphAlignment = Alignment | 'Mixed' | 'Unknown' | 'Left' | 'Centered' | 'Right' | 'Justified';

ParagraphInsertTextLocationtypeSource ↗

Where a paragraph accepts text: over all of it, or at either edge of it.

type ParagraphInsertTextLocation = Extract<RangeInsertTextLocation, 'Replace' | 'Start' | 'End'>;

ParagraphReadingOrdertypeSource ↗

A paragraph's base direction, as [Paragraph.readingOrder](Paragraph.readingOrder) reads and writes it.

type ParagraphReadingOrder = 'LeftToRight' | 'RightToLeft';

PreviewCallbacktypeSource ↗

What [DocxEditorRuntime.preview](DocxEditorRuntime.preview) hands its callback: an ordinary request context whose reads and writes address the preview, not the live document.

Write it as you would write the final edit, from data you already have. The editor stays editable while the callback runs, so a callback that waits on a model call lets the document move under it, and the preview then starts stale. Ask the model first, then preview.

Text and formatting edits work in the body, headers, footers, and notes. The callback cannot write tables, pictures, fields, lists, hyperlinks, content controls, or page setup, create or delete headers, footers, or notes, or move the selection: context.sync() refuses those with NotSupported. Comments are written in the body only, as in run().

type PreviewCallback<T = void> = (context: RequestContext) => Promise<T>;

```ts
const proposal = await model.propose(clauseText); // before the preview, not inside it
const preview = await runtime.preview(async (context) => {
  context.document.changeTrackingMode = 'TrackMineOnly';
  const range = context.document.body.search(proposal.find).getFirst();
  range.insertText(proposal.replace, 'Replace');
  await context.sync();
});
```

RangeInsertTextLocationtypeSource ↗

Where a range accepts text. See Range#insertText for what Before/Start mean here.

type RangeInsertTextLocation = 'Replace' | 'Start' | 'End' | 'Before' | 'After';

RevisionTextViewtypeSource ↗

The tracked-revision view used by this runtime's ordinary Office-compatible text reads.

allMarkup preserves the historical behavior. original matches Word's Original review view: pending deletions remain visible and pending insertions stay hidden.

This is a DocxEditor runtime option. It is not part of the Office.js object model.

type RevisionTextView = 'allMarkup' | 'original';

RevisionTypetypeSource ↗

Word's own names for a kind of change.

The WHOLE upstream vocabulary, because a declaration says what a caller may be handed and a caller switching on it should not have to be told which subset this engine happens to produce. Nine of these occur as published objects: Insert, Delete, Property, MovedFrom, MovedTo, CellInsertion, CellDeletion, CellMerge and ParagraphNumber. A structural card with no single type, such as table grid history, is omitted from items; collection-wide decisions still resolve every store-resolvable revision. See compat/manifest.json.

type RevisionType = 'None' | 'Insert' | 'Delete' | 'Property' | 'ParagraphNumber' | 'DisplayField' | 'Reconcile' | 'Conflict' | 'Style' | 'Replace' | 'ParagraphProperty' | 'TableProperty' | 'SectionProperty' | 'StyleDefinition' | 'MovedFrom' | 'MovedTo' | 'CellInsertion' | 'CellDeletion' | 'CellMerge' | 'CellSplit' | 'ConflictInsert' | 'ConflictDelete';

RunCallbacktypeSource ↗

What a run callback is given, and what it may answer with.

type RunCallback<T> = (context: RequestContext) => Promise<T>;

RuntimeDiagnostictypeSource ↗

A diagnostic from a headless runtime: the open, and each refused batch. Each one is also a valid EditorDiagnostic, so a telemetry module written for the editor receives these unchanged.

type RuntimeDiagnostic = {
    readonly schemaVersion: number;
    readonly editorSessionId: string;
    readonly time: number;
} & ({
    readonly kind: 'document.open';
    readonly outcome: 'opened';
    readonly sizeBucket: ByteSizeBucket;
    readonly durationMs: number;
} | {
    readonly kind: 'document.open';
    readonly outcome: 'rejected';
    readonly code: DocumentOpenDiagnosticCode;
    readonly sizeBucket?: ByteSizeBucket;
    readonly cause?: string;
    readonly part?: DocumentPartKind;
    readonly errorName?: DiagnosticErrorName;
} | {
    readonly kind: 'edit.rejected';
    readonly code: EditDiagnosticCode;
    readonly origin: 'automation';
    readonly tracked: boolean;
    readonly cause?: string;
    readonly errorName?: DiagnosticErrorName;
    readonly stage?: 'automation';
} | {
    readonly kind: 'review.skipped';
    readonly code: ReviewDiagnosticCode;
    readonly count: number;
    readonly operation?: ReviewOperation;
    readonly cause?: string;
});

SelectionMode_2type

Where a selection lands: over the range, or collapsed to one of its edges.

type SelectionMode = 'Select' | 'Start' | 'End';

AlignmentenumSource ↗

Paragraph alignment vocabulary. Mixed and unknown are read states, not authoring modes.

declare enum Alignment

BreakTypeenumSource ↗

Office break vocabulary; enum presence does not imply support for every break kind.

declare enum BreakType

ChangeTrackingModeenumSource ↗

Tracking policy vocabulary. Unsupported policies fail explicitly at sync.

declare enum ChangeTrackingMode

ChangeTrackingVersionenumSource ↗

Which version of tracked text getReviewedText reads: as if every pending revision were rejected (Original) or accepted (Current).

declare enum ChangeTrackingVersion

CompareTargetenumSource ↗

Where a document compare puts its result. Only CompareTargetCurrent is supported: the revisions go into the document the call is made on.

declare enum CompareTarget

ContentControlTypeenumSource ↗

Content-control kinds, including the read subtypes that insertion does not accept.

declare enum ContentControlType

FieldTypeenumSource ↗

Office field types. This runtime authors Page, NumPages, Ref, PageRef, NoteRef, Seq, StyleRef, Date, Time, TOC, and Empty with an instruction of one of those types.

declare enum FieldType

InsertLocationenumSource ↗

Locations used by Office-shaped insertion calls. Each call validates its allowed subset.

declare enum InsertLocation

ListBulletenumSource ↗

Supported Word bullet styles.

declare enum ListBullet

ListNumberingenumSource ↗

Supported Word numbering styles.

declare enum ListNumbering

PageOrientationenumSource ↗

Physical page orientation.

declare enum PageOrientation

RangeLocationenumSource ↗

Which part of an object a getRange call answers. Each call validates its allowed subset; Range.getRange supports Whole, Content, Start, and End.

declare enum RangeLocation

RemoveDocInfoTypeenumSource ↗

Document information categories. Only DocumentProperties removal is supported.

declare enum RemoveDocInfoType

ShapeTypeenumSource ↗

Word's shape types. Supported text-bearing shapes expose their own body.

declare enum ShapeType

StyleTypeenumSource ↗

The kind of a style.

declare enum StyleType

UnderlineTypeenumSource ↗

Office.js underline values. Unsupported runtime modes refuse at sync.

declare enum UnderlineType

VerticalAlignmentenumSource ↗

Vertical placement of content within a table cell. Mixed cannot be authored.

declare enum VerticalAlignment

DocxEditorconstSource ↗

The entry point: open a document and get a runtime to work against.

Import from @docx-editor.dev/editor-api/browser for the same namespace plus createBrowser, which borrows a live editor instead of owning bytes.

DocxEditor: DocxEditorNamespace

```ts
import { DocxEditor } from '@docx-editor.dev/editor-api';

const runtime = await DocxEditor.createServer(bytes, { author: 'Payroll bot' });
await runtime.run(async (context) => {
  const body = context.document.body;
  body.load('text');
  await context.sync();
});
const saved = await runtime.save();
```