# Overview

> Understand how an agent uses SuperDoc to edit a DOCX, then choose a starting point.





An agent can use SuperDoc to read a Word document and make changes from an instruction. For example, you can ask it to
replace a term in a contract and save the result as a new DOCX.

The model decides what to do. SuperDoc provides the tools that read and change the document. You can connect those tools
to a coding agent you already use, or add them to an agent in your own application.

## How an agent edits a document [#how-an-agent-edits-a-document]

A tool is an operation the agent can request, such as opening a file or replacing text. The agent sends arguments to
the tool and receives a result it can use to decide what to do next.

> **Diagram:** The agent sends an instruction and tool results to a model provider over the network. The model chooses a tool call. SuperDoc tools run in a local or server process, read and change an open document, and save a DOCX when asked.


For the contract example:

1. You ask the agent to replace a term and save a copy.
2. The agent uses SuperDoc tools to open the file and find the text.
3. The model chooses an edit. SuperDoc applies it and reports the result.
4. The agent saves the edited DOCX. You open the copy and check the change.

A successful tool call means the operation ran. You still need to check that the edit matches your request.

## Choose where to start [#choose-where-to-start]

### Use a coding agent you already have [#use-a-coding-agent-you-already-have]

Connect SuperDoc to Claude Code, Claude Desktop, Cursor, or Windsurf through MCP, a protocol that lets an agent call
external tools. The client starts the SuperDoc MCP server on your machine and passes tool calls to it.

Start with [Connect a coding agent](/agents/mcp/connect), then make one edit to a sample document. You do not need to
write an agent loop or choose a model provider in SuperDoc.

### Build an agent into your application [#build-an-agent-into-your-application]

Use `@superdoc/sdk` for Node.js or `superdoc-sdk` for Python. Your application opens the document, sends requests to
your model provider, runs the tools it selects, and decides when to save.

[Build an agent](/agents/build/build-an-agent) introduces the toolkit and a document-editing loop. This path gives you
control over the model, instructions, and application workflow.

If your code already knows the edit to make, you can use the [Node.js SDK](/agents/automation/node-sdk),
[Python SDK](/agents/automation/python-sdk), or [CLI](/agents/automation/cli) directly without a model.

## Where the code runs [#where-the-code-runs]

The MCP server and these SDKs run in a local or server process. They edit the document without mounting the Editor UI.
Your agent or application sends the model its instructions and tool results, which can contain document text.

The SuperDoc Editor runs in the browser. Use it when a person needs to see or review the document. In a web application,
keep the Node.js SDK on your server and call it through your application endpoints; use the Editor in the browser.
Do not import the browser `superdoc` package into a Node.js API route to run these workflows.

For the complete engine and package map, see [How SuperDoc works](/resources/how-superdoc-works).

## Start with one document [#start-with-one-document]

[Connect a coding agent over MCP](/agents/mcp/connect) to open a sample, make a tracked edit, and inspect the saved copy.
If you are building your own agent, begin with [Build an agent](/agents/build/build-an-agent).


---

# Store application data in DOCX

> Choose the DOCX structure that matches how your application stores and presents data.



Choose a document structure by what the data means and how other DOCX tools should understand it. Do not recreate the ProseMirror node or mark that previously carried it.

| What you need                                         | Use                   | Stored as                                       | How it appears        |
| ----------------------------------------------------- | --------------------- | ----------------------------------------------- | --------------------- |
| A Word-compatible citation with a bibliography source | `doc.citations`       | A citation field and source record              | From the field result |
| A calculated or cached Word field                     | `doc.fields`          | An OOXML field instruction and result           | From the field result |
| A structured region that people can edit              | `doc.contentControls` | A content control (`w:sdt`)                     | Yes                   |
| Application JSON attached to a text range             | `doc.metadata`        | A hidden inline content control plus Custom XML | Not visible by itself |
| Application data that is not attached to text         | `doc.customXml`       | A Custom XML part                               | Not visible           |

Use the public API rather than editing these XML elements directly. SuperDoc keeps the related package parts and relationships consistent when the document changes.

## Anchored application data [#anchored-application-data]

Use anchored metadata for an application-owned record such as a review finding, external reference, or backend identifier. The caller chooses the record ID and namespace:

```ts
// A user action, not module scope: the guards below return early, and `return`
// is only legal inside a function.
async function attachFinding() {
  const doc = superdoc.activeEditor?.doc;
  // `capture()` reports readiness; `current()` does not. A worker-backed read is
  // `pending` or `stale` while it settles and still carries the previous range,
  // so writing from it anchors the record to the user's earlier selection.
  //
  // Read `target`, not `selectionTarget`: `target` is always a `TextTarget`
  // (one segment per paragraph the selection touches), which is what lets a
  // selection spanning multiple paragraphs attach as one record.
  // `selectionTarget` collapses a multi-paragraph selection to its first/last
  // endpoints and cannot express that.
  const capture = superdoc.ui.selection.capture();
  const target = capture?.status === 'ready' ? capture.target : null;

  // Anchoring is one or more non-empty text ranges — one segment per
  // paragraph — in the main document **body**. Check every part of that
  // before writing, rather than handling rejections:
  //
  // - Every segment must be non-empty.
  // - `story` is per-target: a non-body target (header, footer, footnote,
  //   endnote, textbox) is rejected outright, since the adapter resolves
  //   paragraphs against the main document part only.
  // - A selection crossing deleted tracked text reports `coordinateSpace:
  //   'tracked'`, and the anchor rewrite searches visible `w:t` runs only, so
  //   the same offsets address different characters.
  //
  // These guards are necessary but not sufficient. A selection crossing a
  // table-cell or section boundary still throws, and nothing in the public
  // selection shape reports that ahead of time, so the catch below is the
  // only place that case can be handled.
  if (!doc || !target) return;
  if (target.coordinateSpace === 'tracked') return;
  if (target.segments.length === 0) return;
  if (target.segments.some((segment) => segment.range.start === segment.range.end)) return;
  if (target.story !== undefined && target.story.storyType !== 'body') return;

  // `attach()` throws for several ordinary cases instead of returning an
  // unsuccessful receipt: when the id already exists (including the second time
  // this action runs), when segments are not contiguous paragraphs (or cross a
  // table-cell/section boundary), when a segment overlaps a content control,
  // a hyperlink, or a simple field (`w:fldSimple`, code and cached result
  // alike — a complex field's cached result text, outside any wrapper, is
  // the one field-adjacent case that IS attachable), and when a paragraph is
  // not in the main document part.
  //
  // Use try/catch rather than `.catch()`. This facade is typed `MaybePromise`, so
  // on a synchronous host `attach()` returns the receipt itself and has no
  // `.catch` method, and a synchronous validation throw happens before any
  // promise exists to reject.
  try {
    const receipt = await doc.metadata.attach({
      id: 'finding-42',
      namespace: 'urn:example:review',
      target,
      payload: { sourceId: 'source-7', justification: 'Verify this statement' },
    });
    if (!receipt.success) reportToUser(receipt.failure.message);
  } catch (error) {
    reportToUser(error instanceof Error ? error.message : String(error));
  }
}
```

Metadata persists with the DOCX but does not add visible styling. Add a render-only extension visual when people need to see the anchored range.

The anchor is painted as a content control — one per paragraph it spans, all sharing the same tag when the anchor covers multiple paragraphs. A viewport hit carries the metadata ID in `tag`, while `id` identifies the underlying content control. A record with that ID existing is not proof the click landed on its anchor: nothing stops an ordinary content control from carrying a tag that matches a record anchored elsewhere, including elsewhere in the same paragraph. Comparing the clicked control's full range with where the record resolves rules out that case, though not every case, as the note after the example explains:

```ts
import type { SelectionTarget, TextTarget } from 'superdoc/ui';

// Both endpoints must be `text` to compare positions at all: a `nodeEdge`
// endpoint carries a node reference rather than a block and offset.
//
// Compare the whole story, not just its `storyType`. Two different headers are
// both `headerFooterPart`, and block ids are only unique within a story, so
// comparing the type alone lets an anchor in one header match a control in
// another. The Document API has an internal canonical key for this; until it is
// public, discriminate on the fields that identify each variant.
const storyKey = (story: SelectionTarget['story']) => {
  if (!story) return 'body';
  switch (story.storyType) {
    case 'headerFooterPart':
      return `headerFooterPart:${story.refId}`;
    case 'headerFooterSlot':
      return `headerFooterSlot:${story.section.sectionId}:${story.headerFooterKind}:${story.variant}`;
    case 'footnote':
    case 'endnote':
      return `${story.storyType}:${story.noteId}`;
    case 'textbox':
      return `textbox:${story.textboxId}`;
    default:
      return 'body';
  }
};

// `anchor.target` is a plain `SelectionTarget` for a single-paragraph anchor
// (unchanged since v1), or a `TextTarget` for one spanning multiple
// paragraphs — one control per segment, all sharing the clicked tag. A single
// clicked control is always confined to one paragraph, so match its range
// against ANY ONE of the anchor's segments rather than the whole anchor's
// start-to-end span.
const controlMatchesAnchor = (anchor: SelectionTarget | TextTarget, control: SelectionTarget) => {
  if (control.start.kind !== 'text' || control.end.kind !== 'text') return false;
  if (control.start.blockId !== control.end.blockId) return false;
  if (storyKey(anchor.story) !== storyKey(control.story)) return false;
  const controlBlockId = control.start.blockId;
  const controlStart = control.start.offset;
  const controlEnd = control.end.offset;
  if (anchor.kind === 'text') {
    return anchor.segments.some(
      (segment) =>
        segment.blockId === controlBlockId && segment.range.start === controlStart && segment.range.end === controlEnd,
    );
  }
  if (anchor.start.kind !== 'text' || anchor.end.kind !== 'text') return false;
  return (
    anchor.start.blockId === controlBlockId && anchor.start.offset === controlStart && anchor.end.offset === controlEnd
  );
};

editorShell.addEventListener('pointerdown', async (event) => {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) return;

  const context = superdoc.ui.viewport.contextAt({ x: event.clientX, y: event.clientY });
  // Hits are innermost-first, and a metadata anchor can contain an ordinary
  // nested control. Test every content-control hit rather than the innermost,
  // or a nested control shadows the anchor that encloses it.
  //
  // A non-body hit cannot be filtered out here, and it cannot be detected
  // afterwards either. `context.position` is always `null` in v2 and
  // `hit.story` is populated only for tracked-change hits, so nothing reports
  // the story of a content control. Both lookups below read the main document
  // part, and painted ids are unique only within that part, so a header,
  // footer, note, or textbox control that reuses a body anchor's id and tag
  // resolves the body record and passes every check below.
  //
  // The example opens the record because a colliding non-body control is
  // unlikely in documents this application produced. That is a judgement about
  // your corpus, not a guarantee from the API. If your documents come from
  // elsewhere, treat a match as unverified and confirm through your own
  // backend before acting on it.
  for (const hit of context.entities.filter((entity) => entity.type === 'contentControl')) {
    if (!hit.tag) continue;
    // A metadata anchor is a hidden **inline** content control, so `kind` below
    // must say `inline`. Read it from the hit rather than hardcoding it: `scope`
    // is absent when the painted control carries no scope attribute, and a
    // block control cannot be an anchor, so both cases skip.
    if (hit.scope !== 'inline') continue;

    // Read the control through the Document API rather than the UI catalog.
    // `ui.contentControls.list()` schedules its read and returns whatever is
    // cached, so an early click sees an empty or stale array; the awaited
    // Document API call always answers about the current document.
    //
    // Compare the whole range, not just the block: a colliding tag can sit in
    // the same paragraph as the real anchor.
    //
    // `get()` throws rather than returning null for an id it cannot find, and
    // an uncaught throw here would surface as an unhandled rejection from this
    // listener. Treat a failed lookup as "not this hit" and keep scanning.
    let control: Awaited<ReturnType<typeof doc.contentControls.get>> | null = null;
    let anchor: Awaited<ReturnType<typeof doc.metadata.resolve>> | null = null;
    try {
      [control, anchor] = await Promise.all([
        doc.contentControls.get({ target: { kind: 'inline', nodeType: 'sdt', nodeId: hit.id } }),
        doc.metadata.resolve({ id: hit.tag }),
      ]);
    } catch {
      continue;
    }
    if (!anchor || !control?.selectionTarget) continue;
    if (!controlMatchesAnchor(anchor.target, control.selectionTarget)) continue;

    const record = await doc.metadata.get({ id: hit.tag });
    if (record) openApplicationRecord(record);
    return;
  }
});
```

> **The range comparison narrows the risk without closing it (warning)**
>
> The adapter treats the public `w:alias` value `Anchored metadata` as proof on its own that a control is an anchor,
> without checking the rest of the anchor shape. That alias is the **Title** field in Word's content-control properties
> dialog, so any author or any other tool can set it. Same-tag controls are grouped by document position into the
> anchor's segments, so a control carrying that alias and a colliding tag near the real anchor can be absorbed as an
> extra segment (or, if it breaks the contiguous run, excluded and resolved as a separate, wrong match) — either way,
> the comparison above still succeeds, because both sides describe the same wrong control. Treat an anchored record as a
> hint from document content rather than as an authenticated identity, and keep anything security-relevant in your own
> backend, keyed by the record ID.


Anchored metadata requires one or more non-empty text ranges, in visible coordinates, anchored in the main document **body**. A single-paragraph target is a `SelectionTarget`, unchanged since v1. A target spanning multiple paragraphs is a `TextTarget` with one segment per paragraph: the segments must be contiguous paragraphs in document order, and none of the boundary they cross may be a table cell, a block-level content control, or a section — a target that crosses any of those is rejected. Within a paragraph, a segment may freely cross bold, italic, colour, or character-style boundaries — the anchor preserves each run's own formatting rather than requiring the whole segment to sit in one run — but a segment that overlaps an existing content control, a hyperlink, or a `w:fldSimple` field is rejected, since anchoring inside one of those would either nest content controls or land in text that isn't real anchorable content. A `w:fldSimple` is rejected in full, code and cached result alike; a complex field (`w:fldChar`/`w:instrText`) is different — only its instruction-code runs are rejected, and its cached result text is ordinary anchorable content, same as any other run. The adapter resolves every paragraph against the main document part, so a header, footer, or note paragraph is not found, and the anchor rewrite searches visible `w:t` runs, so a selection crossing deleted tracked text addresses different characters than its offsets suggest. Resolve the record again with `doc.metadata.resolve({ id })` after document edits instead of keeping an old range — it returns the same `SelectionTarget | TextTarget` union, narrowing to `TextTarget` only when the anchor spans more than one paragraph.

The read path carries the same body-only restriction, and gives you nothing to check it with. `contentControls.get()` and `metadata.resolve()` both read the main document part, while painted content-control ids are unique only within that part. A control in a header, footer, note, or textbox that reuses a body anchor's id and tag therefore resolves the body record, and every comparison the example makes succeeds against it. Nothing lets you tell the two apart: `context.position` is always `null` in this release, and `hit.story` is populated only for tracked-change hits, so neither reports the story of a content control.

Anything in a paragraph that is not literal text shifts the two coordinate systems apart. A selection counts a tab, a line break, and an inline image as caret positions, while the anchor rewrite accumulates offsets from `w:t` contents alone. Any of them before or inside the selection makes the stored anchor land later in the paragraph than the user selected, and a long enough run of following text absorbs the difference so the write succeeds instead of failing.

Tabs make this ordinary rather than exotic: a hanging-indent list item begins with one. There is no public option to reconcile the two coordinate systems today, so prefer selections in paragraphs with no tabs, breaks, or inline objects before the range, and verify anchors in exported files when a paragraph has them.

## Citation or application record? [#citation-or-application-record]

Use `doc.citations` when Word and other DOCX tools should recognize the value as a citation backed by a bibliography source. Use `doc.metadata` when the meaning belongs to your application and the document only needs to preserve its ID, payload, and text anchor.

These models are not interchangeable. Check the generated operation reference for the current insertion and presentation capabilities before migrating a citation workflow.

HTML and Markdown projection maps serve a different kind of citation: they map a UTF-16 range in serialized output back
to a public tracked-coordinate `TextTarget`. They do not create a Word bibliography citation. Keep the map with its
`evaluatedRevision`, and [reproject after a mutation](/document-api/output-projections#map-output-back-to-document-content)
before using the target for a comment, link, or application record.


---

# Create and resolve comment threads

> Anchor a DOCX comment to document content, add a reply, and resolve the thread.



Comments are document content. Use the Document API when code needs to create, inspect, update, or delete a thread without driving the built-in comments interface.

This guide creates one anchored thread, adds a reply, and resolves it. The operations work against an open document in the Editor and through supported headless clients.

## Run the complete workflow [#run-the-complete-workflow]

Copy the [tracked-changes fixture](/fixtures/tracked-changes.docx) to your app's public directory as `contract.docx`, then run this browser example:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const match = await doc.query.match({
      select: {
        type: 'text',
        pattern: 'Confidential Information',
      },
      require: 'exactlyOne',
    });
    const clause = match.items[0];

    if (!clause || clause.matchKind !== 'text') {
      throw new Error('The clause was not found.');
    }

    const createReceipt = await doc.comments.create(
      {
        target: clause.target,
        text: 'Confirm that this definition matches the current policy.',
      },
      { expectedRevision: match.evaluatedRevision },
    );

    if (!createReceipt.success) {
      throw new Error(`Comment creation failed: ${createReceipt.failure.message}`);
    }

    const afterCreate = await doc.comments.list({ includeResolved: true });
    const replyReceipt = await doc.comments.create(
      {
        parentCommentId: createReceipt.id,
        text: 'Confirmed against the policy dated July 2026.',
      },
      { expectedRevision: afterCreate.evaluatedRevision },
    );

    if (!replyReceipt.success) {
      throw new Error(`Reply failed: ${replyReceipt.failure.message}`);
    }

    const afterReply = await doc.comments.list({ includeResolved: true });
    const resolveReceipt = await doc.comments.patch(
      {
        commentId: createReceipt.id,
        status: 'resolved',
      },
      { expectedRevision: afterReply.evaluatedRevision },
    );

    if (!resolveReceipt.success) {
      throw new Error(`Resolve failed: ${resolveReceipt.failure.message}`);
    }

    console.log('Resolved comment:', createReceipt.id);
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

The example deliberately re-lists comments between mutations. Each mutation advances the document revision, so the next operation uses a current `expectedRevision`.

## Anchor the root comment [#anchor-the-root-comment]

A root comment needs text and a document target. A text query returns a `SelectionTarget` that can be passed directly to `comments.create()`.

Do not derive the target from the rendered DOM or from `highlightRange`. DOM positions belong to layout. `highlightRange` describes the displayed snippet. The query target addresses document content.

On success, the creation receipt includes the new thread ID. Keep that ID for replies and later lifecycle changes.

## Add replies without another target [#add-replies-without-another-target]

A reply belongs to an existing thread. Pass `parentCommentId` and text. Do not pass the root target again.

The reply is another document mutation. Inspect its receipt before resolving the thread or saving the file.

## Resolve or reopen the thread [#resolve-or-reopen-the-thread]

`comments.patch()` changes exactly one comment field per call. Set `status: 'resolved'` to resolve the root thread. Set `status: 'active'` in a later call to reopen it.

List with `includeResolved: true` when the application needs to show both states. A resolved thread remains in the DOCX unless it is explicitly deleted.

Use [comments in the built-in UI](/editor/built-in-ui/comments) for the standard human workflow. Use [a custom comments UI](/editor/custom-ui/comments) when your application owns the thread list and navigation.

## Follow comments through HTML or Markdown [#follow-comments-through-html-or-markdown]

Detailed HTML and Markdown projections include one annotation record per in-scope comment. A discontinuous comment keeps
one public ID and can have several source or output ranges. The record is `partiallyEmitted` when only some segments
survive the chosen scope.

Review mode also affects anchors. A comment attached only to inserted content is `omitted` in the original view; one
attached only to deleted content is `omitted` in the final view. An omitted record has no output range and reports why.
Do not search nearby serialized text and invent a replacement anchor. Use the record's tracked `sourceTarget` when it is
available, keep it with the projection's `evaluatedRevision`, and reproject after a mutation.

See [Project HTML and Markdown](/document-api/output-projections) for the source-map and citation round-trip contract.


---

# Document API mental model

> Query a document, identify a target, apply a mutation, and inspect its receipt.





The Document API is the operation contract for reading and changing a SuperDoc document. Browser and headless hosts expose the same operation names and data shapes.

Most workflows follow four steps:

1. Query the document.
2. Keep the returned address or target.
3. Apply a mutation to that target.
4. Inspect the mutation receipt.

> **Diagram:** A document operation moves from a query to a stable target, then through a mutation that returns a receipt.


## 1. Query [#1-query]

Use `doc.query.match(...)` to find content by meaning or structure. A query returns document-native references for the next step.

Follow [Query document content](/document-api/query-content) for a complete browser example and the result fields to keep.

### Browser

```ts
const match = await editor.doc.query.match({
  select: { type: 'text', pattern: 'termination' },
  require: 'first',
});

const result = match.items[0];
if (!result || result.matchKind !== 'text') {
  throw new Error('No matching text found.');
}

const operation = await editor.doc.replace({
  target: result.target,
  text: 'cancellation',
}, { changeMode: 'tracked' });
```

### Headless

```ts
const match = await doc.query.match({
  select: { type: 'text', pattern: 'termination' },
  require: 'first',
});

const result = match.items[0];
if (!result || result.matchKind !== 'text') {
  throw new Error('No matching text found.');
}

const operation = await doc.replace({
  target: result.target,
  text: 'cancellation',
  changeMode: 'tracked',
});
```


Do not derive mutation locations from rendered DOM nodes or copied text offsets. The DOM can change when layout changes. A Document API result belongs to the document model.

## 2. Address or target [#2-address-or-target]

An address identifies a document location or object. A target describes the content a mutation should affect. Some query results provide a mutation-ready target. Other workflows resolve an address into the target required by the operation.

Keep the target returned for the current document revision. If the document changes first, query again instead of assuming that an old target still points to the same content.

## 3. Mutate [#3-mutate]

Pass the target to the operation that makes the change. The target makes the scope explicit. It also lets each host apply the same operation contract without inspecting its UI state.

Tracked-change review follows this shape. `doc.trackChanges.list()` discovers changes. `doc.trackChanges.get()` reads one change. `doc.trackChanges.decide({ decision, target })` applies a decision to an explicit target.

## 4. Receipt [#4-receipt]

A successful mutation returns a receipt that records what the engine applied. Use it to confirm the result and continue from the resolved effects.

Treat the receipt as part of the contract. Do not infer success from a repaint, a changed file size, or the absence of an error.

**Receipt `replace`**: replacement recorded in tracked mode


## Runtime shape [#runtime-shape]

Browser calls are Promise-shaped. Other clients expose their own synchronous or asynchronous form. The operation names, inputs, outputs, targets, errors, and receipt meaning stay the same.

This separation is deliberate. The host decides how a call runs. The Document API decides what the call means.

## Use the contract in a workflow [#use-the-contract-in-a-workflow]

- [Mount an editor](/editor/quickstart): Open a DOCX, make a tracked edit, and export the result in a browser application.
- [Run a headless operation](/agents/automation/node-sdk): Query a DOCX, accept its tracked changes, and save a separate output from Node.js.
- [Connect code to human review](/agents/workflows/review-tracked-changes): Create a tracked replacement, review the exact output in the editor, and export the decision.


## Reference [#reference]

The [generated Document API reference](/document-api/reference) is derived from the canonical public contract and lists the current operations, inputs, outputs, and failure modes.


---

# Preview and apply mutation plans

> Validate several document edits, then apply them together against one document revision.





Use a mutation plan when several edits belong to one logical change. A plan resolves every target, previews the combined work without changing the document, and applies valid steps as one atomic transaction.

For one independent replacement or deletion, prefer the direct operations in [Replace and delete content](/document-api/replace-delete-content).

> **Diagram:** Two query references become one atomic plan that is previewed before all steps apply together.


## Run a complete browser example [#run-a-complete-browser-example]

Create a browser app with an `#editor` mount element and an explicit container height, as shown in the [Editor quickstart](/editor/quickstart). This example expects the [tracked-changes fixture](/fixtures/tracked-changes.docx) at `/contract.docx`. Its source lives in the docs app and is typechecked against the public v2 browser API:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const [companyResult, liabilityResult] = await Promise.all([
      doc.query.match({
        select: { type: 'text', pattern: 'Amazing' },
        require: 'exactlyOne',
      }),
      doc.query.match({
        select: { type: 'text', pattern: '$500,000' },
        require: 'exactlyOne',
      }),
    ]);

    const company = companyResult.items[0];
    const liability = liabilityResult.items[0];

    if (!company || company.matchKind !== 'text' || !liability || liability.matchKind !== 'text') {
      throw new Error('The expected contract text was not found.');
    }

    if (companyResult.evaluatedRevision !== liabilityResult.evaluatedRevision) {
      throw new Error('The document changed while the plan targets were being collected.');
    }

    const plan = {
      expectedRevision: companyResult.evaluatedRevision,
      atomic: true as const,
      changeMode: 'tracked' as const,
      steps: [
        {
          id: 'rename-company',
          op: 'text.rewrite' as const,
          where: { by: 'ref' as const, ref: company.handle.ref },
          args: { replacement: { text: 'Northstar' } },
        },
        {
          id: 'lower-liability-cap',
          op: 'text.rewrite' as const,
          where: { by: 'ref' as const, ref: liability.handle.ref },
          args: { replacement: { text: '$250,000' } },
        },
      ],
    };

    const preview = await doc.mutations.preview(plan);
    if (!preview.valid) {
      throw new Error(preview.failures?.map((failure) => failure.message).join('; ') ?? 'Plan preview failed.');
    }

    const receipt = await doc.mutations.apply(plan);
    console.log('Applied steps:', receipt.steps);
  },
});

window.addEventListener('beforeunload', () => {
  superdoc.destroy();
});

```

The example queries both targets before applying any change. It also confirms that both matches came from the same document revision before building the plan.

## Build the plan from references [#build-the-plan-from-references]

Use `item.handle.ref` for plan steps. Each ref points to content resolved by `query.match()`, and `expectedRevision` binds the plan to the document state that produced those refs.

Every plan requires:

* `atomic: true`
* `changeMode: 'direct'` or `'tracked'`
* A stable, unique `id` for every step
* A supported step `op`
* A `where` target and operation-specific `args`

Check `doc.capabilities().planEngine.supportedStepOps` before constructing plans dynamically. The generated reference remains authoritative for each step shape.

## Preview without changing the document [#preview-without-changing-the-document]

`doc.mutations.preview(plan)` resolves targets and validates every step without applying document changes.

Read:

* `valid` before calling `apply()`
* `failures` for the step ID, phase, code, and message
* `steps` for the targets each step resolved
* `evaluatedRevision` for the state used during preview

A valid preview is still a snapshot. Another writer can change the document before apply, so keep `expectedRevision` on the plan.

## Apply atomically [#apply-atomically]

`doc.mutations.apply(plan)` commits every step together. If compilation, target resolution, an assertion, or revision validation fails, the plan does not partially apply successful steps.

The returned plan receipt includes the before/after revision, a result for every step, any tracked-change addresses, and timing metadata. Use step results for verification and diagnostics, not for inventing performance claims.

> **Verification target (success)**
>
> The preview should report `valid: true`. Apply should return two changed steps, and the Editor should show `Northstar
>   Corp` plus a `$250,000` liability cap as tracked changes.


The generated [`mutations.preview` reference](/document-api/reference/mutations/preview) and [`mutations.apply` reference](/document-api/reference/mutations/apply) list supported steps, limits, outputs, and failure codes.


---

# Project HTML and Markdown

> Choose a review view, scope document content, inspect fidelity, and map serialized output back to document targets.



Use `projectHtml()` or `projectMarkdown()` when an application needs more than a display string. These asynchronous reads
return serialized content together with the document revision, diagnostics, block ranges, annotation status, and an
optional output-to-source map.

Use `doc.capabilities.check({ operation: 'projectHtml' | 'projectMarkdown', input })` when a workflow needs the same
structured support envelope used for rich writes. The check runs the detailed projector and returns its complete output
in `projection`; it does not ask you to repeat a revision-sensitive read. Direct detailed projections and support-check
projections both include the common fidelity `outcome` alongside `status`, `lossy`, and all diagnostics.

Use [`getHtml()`](/document-api/reference/get-html) or
[`getMarkdown()`](/document-api/reference/get-markdown) when only the compact string is needed. The compact methods use
the same V2 projection rules but do not expose diagnostics or provenance metadata. Migrating is additive:

```ts
const html = doc.getHtml({});

const projection = await doc.projectHtml({
  reviewMode: 'final',
  includeSourceMap: true,
});
const detailedHtml = projection.content;
```

In the browser facade, await both forms because browser reads may cross the worker boundary. The headless `DocumentApi`
keeps the compact getters synchronous for compatibility; the detailed methods are asynchronous in every host.

## Choose the review view [#choose-the-review-view]

`reviewMode` controls which side of open tracked changes becomes content:

| Mode       | Content                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `final`    | Includes insertions and destinations; excludes deletions and move sources                           |
| `original` | Includes deletions and move sources; excludes insertions and destinations                           |
| `redline`  | Includes representable before and after sides with semantic change carriers and annotation metadata |

The rule applies to inline text and structural revisions such as paragraphs, list items, table rows and cells, and
section boundaries. Formatting-only changes emit one content copy in redline with a semantic carrier. Moves share one
logical change ID and identify source and destination sides separately.

HTML uses semantic elements such as `<ins>` and `<del>` where the HTML content model allows them. Revised table and list
nodes carry change attributes when a wrapper would be invalid. Markdown uses the documented CommonMark/GFM subset and
raw semantic HTML when Markdown syntax cannot represent a structural revision without ambiguity.

## Choose the story and scope [#choose-the-story-and-scope]

Omitting `in` addresses the body story. Pass a supported `StoryLocator` to read a header, footer, footnote, or endnote.
Within that story, omit `scope` for the whole story, pass a public block address for one block, or pass a contiguous
`SelectionTarget` for a range:

```ts
const result = await doc.projectMarkdown({
  in: { kind: 'story', storyType: 'footnote', noteId: '2' },
  reviewMode: 'original',
  scope: {
    kind: 'selection',
    start: { kind: 'text', blockId: 'paragraph-a', offset: 4 },
    end: { kind: 'text', blockId: 'paragraph-b', offset: 12 },
    coordinateSpace: 'tracked',
  },
  includeSourceMap: true,
});
```

Text offsets are UTF-16 code units. A visible-coordinate selection counts the chosen rendered review view. A
tracked-coordinate selection also addresses deletion-side text. The resolved scope in the result always records the
canonical tracked target used for the projection.

Range projection fails closed when a boundary would cut through a table, field, or another structure whose partial
serialization would be misleading. Invalid or missing targets remain typed input/address errors; the projection does not
clip them into a different range.

## Inspect status and fidelity [#inspect-status-and-fidelity]

Check `outcome`, `status`, `lossy`, and `diagnostics` before consuming `content`. `outcome` distinguishes preserved,
warning-bearing, simplified, and rejected projections using the same vocabulary as rich input checks:

| Status    | Meaning                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------- |
| `success` | No lossy diagnostic or fatal error                                                                 |
| `warning` | Usable output exists, and at least one diagnostic records a lossy fallback or placeholder          |
| `failed`  | A source, scope, or representation condition prevented a truthful projection; output data is empty |

Diagnostic codes and structured fields are the stable integration surface. Message prose can change. Each diagnostic
names the source construct, disposition, story, applicable public IDs, and an output range when one exists. Diagnostics
do not include document excerpts or raw package markup.

The projection contract preserves semantic document content; it is not a DOCX layout renderer or a complete Word-file
round trip:

| Source construct                                 | HTML projection                                     | Markdown projection                                   |
| ------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------- |
| Paragraphs, headings 1-6, baseline marks         | Semantic HTML                                       | CommonMark/GFM syntax; raw `<u>` for underline        |
| Lists with exactly resolved Word labels          | Nested lists with explicit visible-label carriers   | Native syntax when exact; otherwise raw semantic HTML |
| Missing or unresolved list labels                | Readable `[list label unavailable]` placeholder     | The same raw-HTML placeholder                         |
| Rectangular, simple tables                       | Semantic table                                      | GFM table                                             |
| Row/column spans or structurally rich tables     | Semantic table with spans                           | Raw semantic HTML table                               |
| Safe links and visible field results             | Link or visible result                              | Link or visible result                                |
| Images with a public resolvable URL              | Image element                                       | Markdown image                                        |
| Package-only media, drawings, OLE, embedded data | Readable deterministic placeholder and warning      | Readable deterministic placeholder and warning        |
| Math, content controls, unsupported field shape  | Preserved readable content or diagnosed placeholder | Preserved readable content or diagnosed placeholder   |
| Section, page, and column breaks                 | Semantic marker or diagnosed placeholder            | Semantic marker or diagnosed placeholder              |

Exact Word numbering is resolved per effective list level, including legal numbering and overrides. HTML emits the
visible label explicitly instead of relying on a browser's list counter. Markdown uses native list syntax only when it
can reproduce that label and separator; custom, Roman, alphabetic, legal, tab-suffixed, or no-suffix labels can use the
documented raw-HTML list carrier. This is a deterministic semantic representation, not a claim of Word visual parity.

Use [`extract()`](/document-api/reference/extract) when the application needs the structured SDM snapshot rather than a
serialized review view. Keep the DOCX itself when the workflow requires package parts, layout, macros, embedded objects,
or Word-specific semantics that the construct matrix diagnoses or replaces.

## Map output back to document content [#map-output-back-to-document-content]

Every detailed result contains `blocks`. Block ranges cover the complete serialized carrier and use UTF-16 offsets into
`content`. A block with `identity: 'public'` includes the ID accepted by block APIs. A structurally emitted table, row,
or cell that only had a positional source locator reports `identity: 'unavailable'` instead of presenting that locator
as a stable public ID. Nested block ranges can overlap.

Set `includeSourceMap: true` for fine-grained citations. Text entries map escaped output payload ranges to public
`TextTarget` values in tracked coordinates. HTML/Markdown delimiters are intentionally unmapped. Synthetic list labels
and placeholders have output ranges but no invented text target.

```ts
const projection = await doc.projectHtml({
  reviewMode: 'redline',
  includeSourceMap: true,
});

const outputOffset = projection.content.indexOf('termination');
const entry = projection.sourceMap?.entries.find(
  (candidate) =>
    candidate.kind === 'text' && candidate.output.start <= outputOffset && outputOffset < candidate.output.end,
);

if (entry?.kind === 'text') {
  const current = await doc.info({});
  if (current.revision !== projection.evaluatedRevision) {
    throw new Error('Projection map is stale; project the document again.');
  }

  await doc.comments.create(
    { text: 'Review this source passage.', target: entry.source },
    { expectedRevision: projection.evaluatedRevision },
  );
}
```

`sourceMap.outputCoordinateSpace` is `utf16`; `sourceMap.sourceCoordinateSpace` is `tracked`. Escaped output remains
atomic: for example, the full HTML entity `&amp;` can map to one source `&` code unit. Store `evaluatedRevision` with every
saved map. Any mutation makes the map and its block ranges stale, even when a familiar paragraph ID still exists.

## Handle comments and tracked-change annotations [#handle-comments-and-tracked-change-annotations]

`annotations` is present even when the fine source map is omitted. Each comment or tracked change reports its public ID,
public block IDs when available, output ranges, side, and one of these statuses:

| Annotation status  | Meaning                                                                           |
| ------------------ | --------------------------------------------------------------------------------- |
| `emitted`          | All representable anchored content for the chosen view and scope was emitted      |
| `partiallyEmitted` | Only part of a discontinuous or scope-clipped anchor survived                     |
| `omitted`          | The view removed the anchor, or its construct could not be represented truthfully |

A comment on inserted content is omitted in `original`; a comment on deleted content is omitted in `final`. In
`redline`, both sides are represented when their structure permits it. An omitted annotation has no output range and
uses `omittedReason: 'reviewMode'` or `'unsupported'`. Do not guess an anchor by searching nearby rendered text; use its
`sourceTarget` when present or project a view in which the anchor is emitted.

## Compatibility notes [#compatibility-notes]

V2 accepts the deprecated `unflattenLists` option on `getHtml()` for source compatibility but ignores it. Omitted,
`true`, and `false` all produce canonical nested lists. Detailed `projectHtml()` does not accept the option.

See the generated [`projectHtml()`](/document-api/reference/project-html) and
[`projectMarkdown()`](/document-api/reference/project-markdown) references for the exact input and result schemas.


---

# Query document content

> Find text in an open DOCX and keep mutation-ready targets.





Use `doc.query.match()` when code needs to locate document content before reading or changing it. The query inspects the document model and returns explicit targets. It does not change the document.

This guide starts with a mounted v2 editor. Complete the [Editor quickstart](/editor/quickstart) first if you do not yet have a working `SuperDoc` instance.

## 1. Query after the editor is ready [#1-query-after-the-editor-is-ready]

Get the browser Document API from `superdoc.activeEditor.doc`. Query inside `onReady` so the document is available:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const result = await doc.query.match({
      select: {
        type: 'text',
        pattern: 'Confidential Information',
      },
      require: 'all',
    });

    console.log(`Found ${result.total} matches.`);

    for (const item of result.items) {
      if (item.matchKind !== 'text') continue;
      console.log(item.snippet, item.target, item.handle.ref);
    }
  },
});

window.addEventListener('beforeunload', () => {
  superdoc.destroy();
});

```

This source is typechecked against the public v2 browser API. The default text selector performs a case-insensitive literal match. Use `mode: 'regex'` only when a literal pattern cannot express the search.

> **Diagram:** Highlighted text in a DOCX becomes query result items with snippets, targets, and references.


## 2. Read the result [#2-read-the-result]

The result separates human-readable context from mutation-ready locations:

| Field                 | What it tells you                                                 |
| --------------------- | ----------------------------------------------------------------- |
| `total`               | Number of matches before pagination                               |
| `items`               | Matches returned on this page                                     |
| `evaluatedRevision`   | Document revision used to evaluate the query                      |
| `item.snippet`        | Matched text with nearby context                                  |
| `item.highlightRange` | Location of the match inside the snippet                          |
| `item.target`         | Direct target for one operation such as `replace()` or `delete()` |
| `item.handle.ref`     | Reference for a mutation plan tied to `evaluatedRevision`         |

Use `item.matchKind` before reading text-only fields. Node queries return a different item shape.

## 3. Choose the expected number of matches [#3-choose-the-expected-number-of-matches]

Set `require` according to what makes the operation safe:

| Value          | Behavior                                          |
| -------------- | ------------------------------------------------- |
| `'first'`      | Return only the first match                       |
| `'exactlyOne'` | Require one match and fail when the count differs |
| `'all'`        | Return all matches and fail when none exist       |
| `'any'`        | Return all matches, including an empty result     |

Prefer `'exactlyOne'` when a later mutation must affect one unique clause. Prefer `'all'` when the task intentionally handles every occurrence.

## 4. Keep targets revision-safe [#4-keep-targets-revision-safe]

A target or reference belongs to the document revision that produced it. If another operation changes the document first, run the query again before using an earlier target.

For one direct operation, keep `item.target`. For a mutation plan, keep `item.handle.ref` together with `result.evaluatedRevision` so the plan can reject stale input instead of editing the wrong content.

Pending tracked deletions are excluded from text queries by default. Set `includeDeletedText: true` only when the workflow explicitly needs to inspect deleted text.

> **Verification target (success)**
>
> `result.total` should be greater than zero, each text item should include the search phrase in its snippet, and each
> item should provide both a target and a reference.


Next, [replace and delete content](/document-api/replace-delete-content) with fresh query targets, or review the [Document API mental model](/document-api/mental-model) for the full operation lifecycle. The [generated `query.match` reference](/document-api/reference/query/match) lists every selector and failure mode.


---

# Receipts and errors

> Check capabilities, inspect mutation results, and recover safely from stale document state.





Treat every Document API mutation result as part of the operation contract. A successful receipt confirms what the engine applied. A failure receipt or rejected call explains why the workflow must stop, re-query, or change its request.

## 1. Check capabilities before acting [#1-check-capabilities-before-acting]

Capabilities describe the current document runtime. Check the operation and the requested mutation mode before presenting or running a workflow:

```ts
const capabilities = await doc.capabilities();
const replaceCapability = capabilities.operations.replace;

if (!replaceCapability.available) {
  const reasons = replaceCapability.reasons?.join(', ') ?? 'No reason reported';
  throw new Error(`Replace is unavailable: ${reasons}`);
}

if (!replaceCapability.tracked) {
  throw new Error('This document runtime cannot record replacements as tracked changes.');
}
```

Each operation capability reports `available`, `tracked`, and `dryRun`. Namespace-level flags such as `capabilities.global.trackChanges.enabled` describe broader runtime support.

A capability check is a snapshot, not a guarantee. Document state, permissions, or targets can change before the mutation runs, so always inspect the eventual result too.

## 2. Handle both failure paths [#2-handle-both-failure-paths]

Mutations can fail in two ways:

1. The call returns a receipt with `success: false` and `failure.code`.
2. The call rejects before applying anything, for example when input validation or a revision guard fails. These errors expose a machine-readable `code` and a message.

```ts
function readErrorCode(error: unknown): string | undefined {
  if (typeof error !== 'object' || error === null || !('code' in error)) return;
  return typeof error.code === 'string' ? error.code : undefined;
}

const result = await doc.query.match({
  select: { type: 'text', pattern: 'Amazing' },
  require: 'exactlyOne',
});
const match = result.items[0];

if (!match || match.matchKind !== 'text') {
  throw new Error('The company name was not found.');
}

try {
  const receipt = await doc.replace(
    { target: match.target, text: 'Northstar' },
    { changeMode: 'tracked', expectedRevision: result.evaluatedRevision },
  );

  if (!receipt.success) {
    console.error(receipt.failure?.code, receipt.failure?.message);
    return;
  }

  console.log('Mutation applied:', receipt);
} catch (error) {
  console.error(readErrorCode(error), error);
}
```

Do not treat the absence of an exception as success. Read `receipt.success` before saving, exporting, or starting a dependent operation.

> **Diagram:** A successful mutation continues, while failures either re-query current state for one retry or stop so the request can change.


## 3. Choose recovery from the code [#3-choose-recovery-from-the-code]

Use the code to select a bounded recovery path:

| Code family                                                                | Meaning                                             | Action                                                                    |
| -------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- |
| `REVISION_MISMATCH`, `STALE_REVISION`, `ADDRESS_STALE`, `TARGET_NOT_FOUND` | The document or target changed                      | Re-query current state, review the new match, and retry once              |
| `NO_OP`                                                                    | The request would not change the document           | Stop and verify whether the desired state already exists                  |
| `CAPABILITY_UNAVAILABLE`, `CAPABILITY_UNSUPPORTED`                         | The current runtime cannot perform the request      | Change the mode, operation, or runtime; do not retry unchanged            |
| `PERMISSION_DENIED`                                                        | Document policy prevents the mutation               | Keep the document unchanged and resolve authorization or protection first |
| `INVALID_INPUT`, `INVALID_TARGET`                                          | The request shape or target is invalid              | Fix the request; do not retry the same payload                            |
| `INTERNAL_ERROR`                                                           | The runtime could not complete the operation safely | Record the code and context, then stop the workflow                       |

Not every operation can return every code. Use the generated operation reference when implementing operation-specific recovery.

## 4. Retry state drift once [#4-retry-state-drift-once]

When a revision or target is stale, run the original query again and review its current result before retrying. Limit automatic retries to one. A repeated state-drift failure usually means another writer is active or the workflow is targeting unstable content.

Never remove `expectedRevision` just to make a retry pass. That guard prevents a valid operation from applying to an unintended document state.

> **Keep failures observable (warning)**
>
> Log the operation name, failure code, and a safe correlation identifier. Do not log full document contents, private
> clauses, or complete mutation payloads by default.


Continue with [Replace and delete content](/document-api/replace-delete-content) for a complete revision-guarded example. The [generated Document API reference](/document-api/reference) lists each operation's receipt and failure codes.


---

# Replace and delete content

> Use fresh query targets to change an open DOCX and inspect each mutation receipt.



Use `replace()` and `delete()` after a query has identified the exact content to change. Both operations accept a target from `query.match()` and return a receipt that says whether the mutation succeeded.

For HTML, Markdown, or `SDFragment` replacement, see [insert HTML and Markdown](/document-api/rich-content). Rich replacement uses the same fresh-target and revision-guard rules described here.

To replace every block in the main body, pass the explicit body target. This is a Document API content mutation: it keeps the open DOCX package and its terminal page setup while replacing the body blocks in one undo step.

```ts
const body = { kind: 'story', storyType: 'body' } as const;

const receipt = await doc.replace(
  { target: body, type: 'markdown', value: '# Replacement\n\nNew body.' },
  { changeMode: 'direct', expectedRevision },
);
```

The body target also accepts `text` or a preconverted `content` fragment. It is main-body-only and direct-mode-only. Tracked whole-body replacement fails with `CAPABILITY_UNSUPPORTED`; use a selection or block target when the replacement must remain a review suggestion. To open a different DOCX package, use the editor's file replacement flow instead.

This guide uses the [tracked-changes fixture](/fixtures/tracked-changes.docx). Serve it from `/contract.docx` in your app, or update the document URL in the example.

## 1. Run two targeted mutations [#1-run-two-targeted-mutations]

Wait for the editor, replace one company name, then run a fresh query before deleting a sentence:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const companyMatch = await doc.query.match({
      select: { type: 'text', pattern: 'Amazing' },
      require: 'exactlyOne',
    });
    const company = companyMatch.items[0];

    if (!company || company.matchKind !== 'text') {
      throw new Error('The company name was not found.');
    }

    const replaceReceipt = await doc.replace(
      {
        target: company.target,
        text: 'Northstar',
      },
      {
        changeMode: 'direct',
        expectedRevision: companyMatch.evaluatedRevision,
      },
    );

    if (!replaceReceipt.success) {
      throw new Error(`Replace failed: ${replaceReceipt.failure?.message ?? 'Unknown error'}`);
    }

    console.log('Replace receipt:', replaceReceipt);

    const liabilityMatch = await doc.query.match({
      select: {
        type: 'text',
        pattern: 'The total liability under this section shall not exceed $500,000.',
      },
      require: 'exactlyOne',
    });
    const liability = liabilityMatch.items[0];

    if (!liability || liability.matchKind !== 'text') {
      throw new Error('The liability sentence was not found.');
    }

    const deleteReceipt = await doc.delete(
      {
        target: liability.target,
        behavior: 'exact',
      },
      {
        changeMode: 'direct',
        expectedRevision: liabilityMatch.evaluatedRevision,
      },
    );

    if (!deleteReceipt.success) {
      throw new Error(`Delete failed: ${deleteReceipt.failure.message}`);
    }

    console.log('Delete receipt:', deleteReceipt);
  },
});

window.addEventListener('beforeunload', () => {
  superdoc.destroy();
});

```

The displayed source is typechecked against the public v2 browser API.

## 2. Re-query after a mutation [#2-re-query-after-a-mutation]

The replacement advances the document revision. The example runs a new query before deleting instead of reusing an earlier target.

`expectedRevision` makes each operation reject stale query input. `changeMode: 'direct'` applies the change immediately. Use `'tracked'` when a change should remain a suggestion for human review.

`behavior: 'exact'` removes only the resolved text range. The default `'selection'` behavior may expand to block edges when the query covers an entire boundary block.

## 3. Inspect receipts before continuing [#3-inspect-receipts-before-continuing]

Check `success` before saving, exporting, or starting another dependent operation. A failed receipt includes a stable failure code and message. A successful receipt includes the resolved target, and may include revision and effect details depending on the operation.

Common failures at this stage mean the target is stale, the text no longer matches, or the current editor mode does not allow the mutation. Re-query current document state before retrying. Do not guess offsets or silently ignore the receipt.

> **Verification target (success)**
>
> The mounted document should show `Northstar Corp` instead of `Amazing Corp`, and the liability sentence should be
> absent. Both receipts should report `success: true`.


Next, learn how to handle [receipts and errors](/document-api/receipts-and-errors) without unsafe retry loops. For several edits that must succeed together, use a revision-guarded mutation plan instead of chaining independent calls. The generated [replace reference](/document-api/reference/replace) and [delete reference](/document-api/reference/delete) list the full input and receipt shapes.


---

# Insert HTML and Markdown

> Convert, inspect, and apply bounded HTML or Markdown content to an open DOCX.



The Document API accepts HTML and Markdown as structured input. You can inspect the canonical fragment first, or pass the source directly to `insert()` or `replace()`.

HTML and Markdown are not Word package fragments. SuperDoc preserves the supported structure listed below, normalizes representation details, and reports anything it drops or downgrades.

## Convert before applying [#convert-before-applying]

Use `htmlToFragment()` or `markdownToFragment()` when your application needs to inspect diagnostics or reuse the canonical fragment:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const converted = await doc.htmlToFragment({
      html: '<h2>Scope</h2><p><strong>Review</strong> this clause.</p>',
    });
    const fatal = converted.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
    if (fatal) throw new Error(`HTML conversion failed: ${fatal.message}`);

    const insertInput = {
      type: 'html',
      value: '<h2>Scope</h2><p><strong>Review</strong> this clause.</p>',
    } as const;
    const checked = await doc.capabilities.check({
      operation: 'insert',
      input: insertInput,
      options: { changeMode: 'tracked' },
    });
    if (checked.operation !== 'insert') {
      throw new Error(`Unexpected support-check operation: ${checked.operation}`);
    }
    if (!checked.supported || !checked.guard) {
      throw new Error(`Rich insert is not supported: ${checked.failure?.message ?? checked.outcome}`);
    }

    const insertReceipt = await doc.insert(insertInput, {
      changeMode: 'tracked',
      supportCheck: checked.guard,
    });
    if (!insertReceipt.success) {
      throw new Error(`Rich insert failed: ${insertReceipt.failure?.message ?? 'unknown failure'}`);
    }

    const match = await doc.query.match({
      select: { type: 'text', pattern: 'Existing clause' },
      require: 'exactlyOne',
    });
    const clause = match.items[0];
    if (!clause || clause.matchKind !== 'text') throw new Error('The clause was not found.');

    const replaceReceipt = await doc.replace(
      {
        target: clause.target,
        type: 'markdown',
        value: '**Replacement clause** with a [reference](https://example.com/policy).',
      },
      {
        changeMode: 'tracked',
        expectedRevision: match.evaluatedRevision,
      },
    );
    if (!replaceReceipt.success) {
      throw new Error(`Rich replace failed: ${replaceReceipt.failure?.message ?? 'unknown failure'}`);
    }

    console.log(checked.outcome, insertReceipt.outcome, replaceReceipt.conversion);
  },
});

window.addEventListener('beforeunload', () => {
  superdoc.destroy();
});

```

Each result contains:

* `fragment`: the canonical structured content.
* `lossy`: `true` when conversion normalized, downgraded, or dropped source content.
* `diagnostics`: ordered, source-located conversion findings.

A warning-bearing result can still be applied. An error means there is no safe rich fragment to apply. Check diagnostic `severity` and `disposition` instead of treating every lossy result as a failure.

## Check an exact workflow before applying [#check-an-exact-workflow-before-applying]

Use `doc.capabilities()` for a cheap synchronous snapshot of general operation availability. Use
`doc.capabilities.check()` when the answer must account for exact HTML or Markdown, the current target, the requested
change mode, and the current document revision. A check does not mutate package bytes, history, tracked changes, or the
public revision.

A supported write that would change the document returns a guard. Pass it to the unchanged rich `insert()` or
`replace()` request. The write fails closed when the source, format, target, placement, story, nesting policy, mode,
analysis result, or document revision no longer matches. The guard digest detects accidental reuse; it is not a
security signature.

The common `outcome` is `preserved`, `preserved-with-warnings`, `simplified`, `rejected`, `no-op`, `invalid-target`, or
`outdated`. Read the complete conversion diagnostics and final mutation receipt before choosing application-specific
fallback behavior.

## Insert or replace raw source [#insert-or-replace-raw-source]

Pass `value` with `type: 'html'` or `type: 'markdown'` to convert and apply in one call. Rich insert supports a selection, a block with `before` or `after`, a ref, or no target for append. Rich replace accepts a selection, paragraph or heading block, whole table block, ref, or the explicit `{ kind: 'story', storyType: 'body' }` target.

The body target replaces all main-body blocks in one direct mutation while retaining the destination DOCX package and terminal section properties. It does not replace the DOCX file. Tracked mode is supported for selection and block workflows, but tracked whole-body replacement returns `CAPABILITY_UNSUPPORTED`.

Use `dryRun: true` to resolve and preflight without creating IDs, history, or document changes. Pair a mutation with `expectedRevision` when it depends on an earlier read.

Successful raw-source receipts include the final `outcome` and a `conversion` report. They may also include created entity identities, source-path effects, affected stories, text-range shifts, and a transaction ID. Check `success` before using any success-only field.

## Supported inbound constructs [#supported-inbound-constructs]

| Source construct                                                                                          | Result                                                                  |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Paragraphs, headings, bold, italic, underline, strike, hard breaks                                        | Preserved as canonical blocks and runs                                  |
| Ordered and unordered lists, including bounded nesting and ordered starts                                 | Preserved with canonical list levels                                    |
| Tables with a complete leading header row and column spans                                                | Preserved; explicit widths and broad table styling are not              |
| Safe `http`, `https`, and `mailto` links                                                                  | Preserved as external hyperlinks                                        |
| Horizontal rules                                                                                          | Preserved as durable horizontal-rule blocks                             |
| Safe bounded color, font, spacing, indentation, cell shading, and padding                                 | Normalized to typed canonical properties                                |
| Code, block quotes, task markers, and unsupported inline forms                                            | Downgraded or dropped with diagnostics                                  |
| Scripts, event handlers, unsafe URLs, raw images, nested tables, row spans, malformed or over-limit input | Sanitized with warnings when safe structure remains; otherwise rejected |

The limits are deliberate. Arbitrary CSS, embedded active content, and full DOCX package fidelity are outside the HTML/Markdown contract.

## Projection and persistence [#projection-and-persistence]

Direct changes are immediately part of the document. This inbound API creates review markup that can be accepted or
rejected through the tracked-changes API. Detailed outbound HTML and Markdown reads can then project `redline`, `final`,
or `original` views. Save and reopen the DOCX before treating a mutation workflow as complete.

Standalone outbound conversion of an `SDFragment` to HTML or Markdown is not part of this inbound API. Document reads
have a separate [HTML and Markdown projection contract](/document-api/output-projections), including compact string
getters and detailed reads with review, fidelity, and provenance metadata.

For target discovery, start with [query content](/document-api/query-content). For failure handling, see [receipts and errors](/document-api/receipts-and-errors). The generated [HTML conversion reference](/document-api/reference/html-to-fragment), [insert reference](/document-api/reference/insert), and [replace reference](/document-api/reference/replace) list the complete shapes.


---

# Work with tracked changes

> Create reviewable edits, inspect open changes, and accept or reject an explicit change.



Tracked changes connect programmatic editing to human review. Operations that report tracked-mode support can request it. The review API then lists, inspects, accepts, or rejects the resulting logical changes.

## Create a reviewable edit [#create-a-reviewable-edit]

Pass `changeMode: 'tracked'` as the mutation options argument. There is no separate operation for creating a tracked change:

```ts
const result = await doc.query.match({
  select: { type: 'text', pattern: 'Amazing' },
  require: 'exactlyOne',
});
const match = result.items[0];

if (!match || match.matchKind !== 'text') {
  throw new Error('The company name was not found.');
}

const receipt = await doc.replace(
  { target: match.target, text: 'Northstar' },
  { changeMode: 'tracked', expectedRevision: result.evaluatedRevision },
);

if (!receipt.success) {
  throw new Error(receipt.failure?.message ?? 'The tracked replacement failed.');
}
```

The replacement remains open for review. Saving the DOCX preserves that review state until a person or programmatic workflow accepts or rejects it.

## Review the result in the Editor [#review-the-result-in-the-editor]

The Editor owns document rendering, selection, and human review controls. Follow [Review tracked changes](/editor/track-changes) to open the sample DOCX and accept or reject a proposal visually.

The underlying tracked-change operations remain the same in Editor and Headless hosts.

## List and inspect changes [#list-and-inspect-changes]

`trackChanges.list()` returns a compact, paginated result. Call `trackChanges.get()` when the workflow needs full before/after details for one logical change:

```ts
const changes = await doc.trackChanges.list({ limit: 20, offset: 0 });
const change = changes.items[0];

if (!change) {
  throw new Error('The document has no open tracked changes.');
}

const detail = await doc.trackChanges.get({ id: change.id });

console.log({
  id: detail.id,
  type: detail.type,
  author: detail.author,
  before: detail.before,
  after: detail.after,
});
```

The list searches the document body by default. Pass `in: 'all'` when the workflow must include supported headers, footers, footnotes, and endnotes.

## Read final, original, or redline output [#read-final-original-or-redline-output]

Use `projectHtml()` or `projectMarkdown()` when a workflow needs a serialized review view rather than the tracked-change
catalog. `final` emits accepted-side content, `original` emits the before-side, and `redline` identifies representable
before/after content with the same logical change IDs returned here. The view applies to structural paragraph, list, and
table changes as well as inline text. Moves distinguish source and destination; formatting-only changes emit one content
copy with an annotation carrier.

The projection result records annotations removed by the selected view instead of silently dropping their identity.
Source targets and maps use tracked coordinates and are valid only at `evaluatedRevision`. Read the
[HTML and Markdown projection guide](/document-api/output-projections) before saving a map for a later review action.

## Accept or reject one change [#accept-or-reject-one-change]

Decide against the logical change ID, and guard the decision with the revision returned by the list operation:

```ts
const decisionReceipt = await doc.trackChanges.decide(
  {
    decision: 'accept',
    target: { kind: 'id', id: detail.id },
  },
  {
    expectedRevision: changes.evaluatedRevision,
  },
);

if (!decisionReceipt.success) {
  throw new Error(`${decisionReceipt.failure.code}: ${decisionReceipt.failure.message}`);
}

console.log('Resolved change:', decisionReceipt.removed);
```

Use `decision: 'reject'` to restore the change's before-state instead. A review decision resolves an existing change, so `changeMode` and `dryRun` do not apply.

Re-list changes after each decision. The receipt can invalidate or remap references, and partial range decisions can create successor fragments with new IDs.

> **Verification target (success)**
>
> After the decision succeeds, a fresh `trackChanges.list()` result should no longer contain the resolved logical change
> ID. The saved DOCX should preserve the accepted or rejected document state.


For a complete code-to-human handoff, follow [Review tracked changes](/agents/workflows/review-tracked-changes). The generated [`trackChanges` reference](/document-api/reference/track-changes) covers range, side, bulk, and story-specific targets.


---

# Build accessible Editor experiences

> Preserve keyboard access, names, focus, status announcements, and application-owned accessibility around SuperDoc.



The built-in toolbar and surfaces provide keyboard and ARIA behavior, but the complete experience includes the application shell, custom controls, dialogs, validation, and save state. Accessibility remains a shared responsibility.

## Preserve the built-in contract [#preserve-the-built-in-contract]

* Keep visible labels or accessible names when replacing toolbar text and icons.
* Do not remove focus outlines without an equally visible replacement.
* Give dialogs and floating surfaces a title, `ariaLabel`, or `ariaLabelledBy`.
* Keep Escape and focus behavior predictable. Do not trap focus in a non-modal floating tool.
* Let fit-to-width respond to zoom and container changes without preventing browser zoom.

## Own custom UI semantics [#own-custom-ui-semantics]

Use native buttons, inputs, and selects whenever possible. Mirror command `active` with `aria-pressed`, disable unavailable actions, and announce async save or mutation outcomes through a polite live region. Return focus to the document when a temporary control closes and preserve the selection when a composer takes focus.

Keyboard shortcut metadata does not install a listener. The application must bind shortcuts, prevent conflicts with browser and assistive-technology commands, and route every shortcut through the same command handle as its visible control.

Test keyboard-only navigation, high contrast, 200% browser zoom, reduced motion, and at least one screen reader on supported browsers. Automated checks catch markup defects but do not prove that document editing is understandable.


---

# Discuss a document with comments

> Add a thread to selected text, reply, and resolve it without changing the passage.



Use a comment to ask a question or discuss a passage. Use [tracked changes](/editor/track-changes) when you want to
propose an edit to the passage itself. Both work with SuperDoc's built-in UI or your own controls.

## Try a comment thread [#try-a-comment-thread]

Expand the Editor and click `September 30, 2026` to open its comment. Add a reply, then choose the checkmark to resolve
the thread. Click the date again to see its **Resolved** status and choose **Reopen comment**.

> **Interactive editor: Discuss the delivery date**
>
> Sample: [open the fixture](/fixtures/comments-sample.docx).
>
> Preset: `comments`.
>
> Comment thread: open the delivery-date comment, reply, resolve, and reopen it. The messages and status change without editing the passage. Layout and permission experiments are hidden; zoom and expansion remain available.
>
> Local DOCX selection: disabled.


The discussion changes; the date in the document does not. To start another thread, select a different passage,
right-click, and choose **Comment**.

## Add comments to your project [#add-comments-to-your-project]

Start with the [Quickstart](/editor/quickstart). Comments are enabled by default, so keep its Editor, `/sample.docx`,
and export button. Provide the current user's name and email using the
[user configuration](/editor/configuration#set-the-startup-configuration) before creating comments.

Select a passage and add a comment from the context menu. Its author should match the configured user. You do not
need a collaboration server for one person to comment on a document and export it.

## Follow the thread lifecycle [#follow-the-thread-lifecycle]

The first comment starts a **thread** anchored to the selected document text. Replies belong to that thread;
they do not need another selection.

| Action              | What changes                                                         |
| ------------------- | -------------------------------------------------------------------- |
| Reply               | Adds a message to the same discussion.                               |
| Resolve             | Marks the thread as finished but keeps its messages.                 |
| Reopen              | Makes a resolved thread active again.                                |
| Delete your comment | Removes your message; deleting your root comment removes its thread. |

Resolving a thread is not deleting it. Hiding the comments panel does not remove comments from the DOCX either.

## Save the discussion [#save-the-discussion]

Comments, replies, authors, and resolved status are stored in the DOCX. Export using the Quickstart's **Export DOCX**
button, then open the exported file in Word or load it back into SuperDoc. Confirm that the thread and its reply remain,
including the resolved status you chose.

The embedded demo only changes its in-browser document. Your application uses [Load and save](/editor/load-and-save-documents)
to persist the exported bytes. Reloading the original sample is not reopening your saved discussion.

## Choose how people interact [#choose-how-people-interact]

Keep the built-in UI unless your application needs to own the thread list or composer:

* [Configure built-in comments](/editor/built-in-ui/comments) for layout and available actions.
* [Build a custom comments panel](/editor/custom-ui/comments) for application-owned markup and selection handling.
* [Use Document API comments](/document-api/comments) to create, update, or delete comments in code.

Comment settings control browser interaction, not trusted authorization. Your backend still decides who can access
and save the document. Comment actions are separate from permission to accept or reject tracked changes.


---

# Configure the Editor

> Set how the Editor starts, then find the configuration options your integration needs.



Continue with the `/sample.docx` project from the [Quickstart](/editor/quickstart). Add a current user and choose how the
Editor starts.

## Set the startup configuration [#set-the-startup-configuration]

Add the matching import and `startupOptions` object at the top of your Quickstart file: `src/main.ts` in Vanilla or
`src/App.tsx` in React, outside the component. These options name the author and start the Editor in suggesting mode:

**Vanilla — `Startup options`**

```ts
import type { Config } from 'superdoc';

export const startupOptions = {
  documentMode: 'suggesting',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
} satisfies Partial<Config>;

```

**React — `Startup options`**

```tsx
import type { SuperDocEditorProps } from '@superdoc/react';

export const startupOptions = {
  documentMode: 'suggesting',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
} satisfies Partial<SuperDocEditorProps>;

```


In Vanilla, spread `startupOptions` into the object passed to `new SuperDoc()`. In React, spread it onto
`SuperDocEditor` as `{...startupOptions}`. Keep the callbacks and export code from Quickstart.

Reload the application and change `September 1, 2026` to `October 1, 2026`. The edit should appear as a tracked change
instead of replacing the date directly.

The `user` value identifies the author of the tracked change. This example uses a fixed user so it runs without
authentication. `satisfies` checks the field names and values during typechecking.

## Find an option [#find-an-option]

Choose a group, then choose a field. Each entry shows what it changes, its type, and its default. Some fields link to a
guide with a complete example. Expand **API details** for the generated description.

### Essentials

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `selector` | `string \| HTMLElement` | — | Required | Choose the element where the Editor mounts. | The selector or element to mount the SuperDoc into. | — |
| `document` | `DocumentSource \| null` | — | Optional | Open a document from a URL, File, Blob, or collaboration source. | Document to open. Pass a URL, file, byte source, or structured source. Use a structured document carrying `collaboration` for collaboration, or a structured source for other metadata. Omit it to open a blank DOCX. | [Load and save documents](/editor/load-and-save-documents) |
| `documentMode` | `"editing" \| "viewing" \| "suggesting"` | `'editing'` | Optional | Start in editing, suggesting, or viewing mode. | The mode of the document (default: 'editing'). | [Document modes](/editor/document-modes) |
| `user` | `{ color?: string; id?: null \| string; name?: null \| string; email?: null \| string; image?: null \| string; }` | — | Optional | Identify the current user for collaboration and tracked changes. | The current user of this SuperDoc. Typed as `AwarenessUser` (an extension of `User` with the optional `color` field) so consumers can pass an explicit awareness color and have the runtime honor it as an override - `SuperDoc#assignUserColor()` skips its hash-based assignment when `user.color` is already set. | — |

### Document

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `viewing` | `{ comments?: boolean; trackedChanges?: "original" \| "markup" \| "final"; }` | `{ comments: false, trackedChanges: 'original' }` | Optional | Choose what comments and tracked changes viewers see. | What review information is shown when `documentMode` is `viewing`. | [Document modes](/editor/document-modes) |
| `role` | `"editor" \| "viewer" \| "suggester"` | — | Optional | Limit which document modes the current user can enter. | The role of the user in this SuperDoc. | — |
| `allowSelectionInViewMode` | `boolean` | `false` | Optional | Let viewers select text without editing. | When `documentMode` is `'viewing'`, allow the user to make text selections even though editing is disabled. Defaults to `false`. Forwarded to the underlying editor as `options.allowSelectionInViewMode`. | [Document modes](/editor/document-modes) |
| `superdocId` | `string` | — | Optional | Set an ID for this Editor instance. | The ID of the SuperDoc. | — |
| `password` | `string` | — | Optional | Open an encrypted DOCX with its password. | Password for encrypted DOCX files. Forwarded during document load. | — |
| `documents` | `Document[]` | — | Optional | Load documents through the legacy multi-document field. | Documents to load. | — |
| `fieldContext` | `{ fileName?: null \| string; fullPath?: null \| string; currentUser?: null \| { name?: string \| null; initials?: string \| null; address?: string \| null; }; }` | — | Optional | Provide V2 field values for one initial document; use Document.fieldContext for multiple documents. | Default V2 field values for one initial document. For multiple documents, set Document.fieldContext on each entry. | — |
| `users` | `User[]` | — | Optional | Provide the people available for mentions. | All users of this SuperDoc (can be used for "@"-mentions). | — |
| `colors` | `string[]` | — | Optional | Provide awareness colors for users. | Colors to use for user awareness. | — |
| `title` | `string` | — | Optional | Set the fallback filename used when exporting. | Fallback filename for `export()` when `exportedName` is omitted. | — |

### Interface

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `ui` | `false \| { toolbar?: false \| true \| ToolbarConfig; comments?: false \| true \| CommentsConfig; contextMenu?: false \| true \| ContextMenuConfig; loading?: boolean; search?: false \| true \| SearchConfig; linkPopover?: false \| true \| LinkPopoverConfig; ruler?: false \| true \| RulerConfig; contentControls?: false \| true \| ContentControlsConfig; }` | — | Optional | Choose which built-in interface parts SuperDoc renders. | Which built-in interface SuperDoc renders. Omit it to keep SuperDoc's historical rendering: comments, the context menu, content-control chrome, and mode-aware hyperlink activation are on; search and the ruler are opt-in; and the toolbar renders once it has somewhere to mount. That profile is not symmetrical, and omitting this field reproduces it exactly. Pass `false` when the application owns the interface. SuperDoc then renders no controls, chrome, dialogs, or popovers, while the document, the Document API, and `superdoc.ui` keep working — so a custom UI drives the same commands the built-in one would have. Pass an object to choose per surface. An omitted key keeps that surface's default rather than following its siblings, so `{ comments: false }` disables comments and changes nothing else. | [Choose your interface](/editor/who-renders-the-ui) |
| `interaction` | `{ comments?: { level?: CommentInteractionLevel; }; trackedChanges?: { allowDecisions?: boolean; }; }` | — | Optional | Set what people can do through Editor interactions. | Client-side interaction policy. Independent of `ui`, so it still applies when the application renders its own UI. This is not an authorization boundary. | [Choose your interface](/editor/who-renders-the-ui) |
| `surfaces` | `{ resolver?: null \| (request: SurfaceRequest) => SurfaceResolution \| null \| undefined; dialog?: { closeOnEscape?: boolean; closeOnBackdrop?: boolean; maxWidth?: string \| number; }; floating?: { placement?: SurfaceFloatingPlacement; width?: string \| number; maxWidth?: string \| number; maxHeight?: string \| number; closeOnEscape?: boolean; closeOnOutsidePointerDown?: boolean; autoFocus?: boolean; }; }` | — | Optional | Configure dialogs and floating overlays. | Shared configuration for dialogs and floating overlays, including ones opened through `superdoc.openSurface()`. Stays active under `ui: false`. | [Dialogs and surfaces](/editor/dialogs-and-surfaces) |
| `uiDisplayFallbackFont` | `string` | — | Optional | Set the font used by SuperDoc interface elements. | The font-family to use for all SuperDoc UI surfaces (toolbar, comments UI, dropdowns, tooltips, etc.). This ensures consistent typography across the entire application and helps match your application's design system. The value should be a valid CSS font-family string. Example (system fonts): uiDisplayFallbackFont: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif' Example (custom font): uiDisplayFallbackFont: '"Inter", Arial, sans-serif' | — |

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `fieldUpdatePolicy` | `"refreshOnOpen"` | — | Optional | Refresh supported unlocked V2 fields when opening a local editable document. | Refresh supported unlocked V2 fields on local editable open. Omission preserves imported caches. | — |
| `hyperlinks` | `false \| { onActivate?: (context: HyperlinkActivationContext) => HyperlinkActivationResult \| null \| undefined; }` | — | Optional | Choose what happens when a person activates a hyperlink. | Hyperlink activation behavior. By default, editable links open the built-in hyperlink editor in Editing or Suggesting mode. In Viewing mode, and for links outside editable text, SuperDoc follows the URL or document anchor. Pass `false` to suppress activation in every mode. A configured `onActivate` handler stays active with `ui: false`, allowing a custom interface to handle hyperlinks. | [Hyperlinks](/editor/built-in-ui/hyperlinks) |
| `trackChanges` | `{ enabled?: boolean; replacementMode?: "grouped" \| "separate"; authorColors?: TrackChangesAuthorColorsConfig; semanticColors?: TrackChangesSemanticColorsConfig; visible?: boolean; }` | `{ enabled: true, replacementMode: 'grouped' }` | Optional | Configure replacement review and tracked-change colors. | Configure replacement review and tracked-change colors. Use `viewing.trackedChanges` to choose what a viewer sees and `interaction.trackedChanges` to allow or prevent review decisions. | [Track changes](/editor/track-changes) |
| `isLocked` | `boolean` | — | Optional | Set the initial shared lock metadata. | Initial shared lock metadata. This value does not make the document read-only. Use `documentMode` or interaction policy to restrict editing in the client. | — |
| `lockedBy` | `{ id?: null \| string; name?: null \| string; email?: null \| string; image?: null \| string; }` | — | Optional | Identify the user who locked the Editor. | User associated with the initial shared lock metadata. | — |
| `viewOptions` | `{ layout?: "print" \| "web"; }` | — | Optional | Set DOCX-compatible document view options. | Document view options (OOXML ST_View compatible). | — |
| `contained` | `boolean` | `false` | Optional | Keep the Editor inside a fixed-height scrolling container. | Enable contained mode for fixed-height container embedding. SuperDoc supports two layout modes, and the host element's height requirement differs between them: - Natural (default, `false`): the Editor grows to the document's full height and the page scrolls. The host needs no height. Setting one does not constrain the document or enable internal scrolling, because SuperDoc leaves overflow visible in this mode, though application CSS on the host can still clip what is drawn. - Contained (`true`): SuperDoc propagates `height: 100%` through its DOM tree and scrolls the document internally, so multi-page documents stay inside the host. This mode requires the host to have a definite height (for example `height: 400px`); without one there is nothing for the percentage heights to resolve against. A toolbar mounted through `Config.toolbar` or `modules.toolbar.selector` is never part of this calculation. Placed as a sibling of the host, its height adds to the host's: a 400px host with a 40px toolbar occupies 440px in total. Placed inside the host, it consumes part of the 400px instead. | [Responsive layout](/editor/built-in-ui/responsive-layout) |
| `zoom` | `{ initial?: number; mode?: "manual" \| "fit-width"; fitWidth?: SuperDocFitWidthOptions; }` | `{ initial: 100, mode: 'manual' }` | Optional | Set the initial zoom and fit-to-width behavior. | Zoom behavior: the initial zoom level and optional fit-width policy. See `SuperDocZoomConfig`. | [Responsive layout](/editor/built-in-ui/responsive-layout) |
| `measurementUnit` | `"in" \| "cm"` | `'in'` | Optional | Set the ruler and measurement unit. | Starting measurement unit for rulers and measurement fields (Word's "measurement units" preference). Defaults to `'in'` (Word's en-US default). Change it at runtime with `setMeasurementUnit()`. See `SuperDocMeasurementUnit`. | [Ruler](/editor/built-in-ui/ruler) |

### Integrations

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `modules` | `{ trackChanges?: TrackChangesModuleConfig; }` | — | The trackChanges module path is deprecated. Use the top-level trackChanges field. | Configure document features that do not belong to the built-in interface. | Modules to load. | — |
| `permissionResolver` | `(params: { permission: string; role: string; isInternal: boolean; defaultDecision: boolean; comment: null \| object; trackedChange: null \| object; currentUser: null \| User; superdoc: null \| SuperDocClass; }) => boolean \| undefined` | — | Optional | Customize client-side permission decisions. | Customize client-side permission decisions. This is not an authorization boundary. When both resolver spellings are present, this field takes precedence over the deprecated `modules.comments.permissionResolver` field. | — |
| `extensions` | `SuperDocExtension<Record<string, unknown>>[]` | — | Optional | Add extensions created with `defineSuperDocExtension`. | SuperDoc v2 extensions created with `defineSuperDocExtension`. These extensions activate without an `editorVersion` or `editorIntegration` selector. Each extension owns isolated storage, named events, commands, anchors, and render-only decorations, and mutates the document exclusively through the guarded Document API (`ctx.doc.*`). This is the v2 replacement for the v1/ProseMirror `editorExtensions` path; the two are not interchangeable. Extension arrays are mount-time config: changing the array reference requires a remount to take effect. | — |
| `handleImageUpload` | `(file: { lastModified: number; name: string; webkitRelativePath: string; size: number; type: string; arrayBuffer: () => Promise<ArrayBuffer>; bytes: () => Promise<Uint8Array<ArrayBuffer>>; slice: (start: number \| undefined, end: number \| undefined, contentType: string \| undefined) => Blob; stream: () => ReadableStream<Uint8Array<ArrayBuffer>>; text: () => Promise<string>; }) => Promise<string>` | — | Optional | Store images inserted into the document. | The function to handle image uploads. | — |
| `cspNonce` | `string` | — | Optional | Apply a Content Security Policy nonce to SuperDoc runtime styles. | Content Security Policy nonce for SuperDoc runtime styles. Editors that share a document must use the same nonce. | [Secure integration](/editor/secure-integration) |
| `licenseKey` | `string` | — | Optional | Set the client-visible license identity sent with document-open telemetry. | Client-visible license identity sent with document-open telemetry. | [License](/editor/license) |
| `telemetry` | `{ enabled: boolean; endpoint?: string; metadata?: Record<string, unknown>; }` | `{ enabled: true }` | Optional | Configure telemetry sent when a DOCX becomes ready. | Document-open telemetry settings. Enabled by default. | [Telemetry](/editor/telemetry) |
| `proofing` | `ProofingConfig` | — | Optional | Configure spelling and grammar checks. | Proofing / spellcheck configuration. | [Add proofing](/editor/platform/proofing) |
| `fonts` | `{ bundled?: false \| true \| string[] \| Record<string, unknown> \| "baseline" \| "full"; families?: FontFamilyConfig[]; map?: Record<string, string>; assetBaseUrl?: string; resolveAssetUrl?: (context: import("@superdoc/font-system").FontAssetUrlContext) => string; assetUrl?: string \| (context: import("@superdoc/font-system").FontAssetUrlContext) => string; }` | — | Optional | Configure document fonts and font asset loading. | Font system configuration. The reviewed fallback pack ships in the optional `@superdoc-dev/fonts` package: pass `superdocFonts` (bundler) or the `SuperDocFonts` global from its `superdoc-fonts.min.js` browser build (CDN). To self-host, set `fonts.assetBaseUrl` (e.g. `/fonts/` or a CDN URL) or `fonts.resolveAssetUrl` for signed/versioned hosting. Core ships no document families, so with none configured the toolbar shows the baseline and documents render with system fonts. It does ship one built-in face: a core-symbol provider requested whenever the document contains symbol or dingbat glyphs it covers, such as the • bullet, even with no `fonts` configuration. | — |
| `workerUrls` | `{ document?: string \| URL; collaboration?: string \| URL; reviewIndex?: string \| URL; }` | — | Optional | Load browser workers from same-origin URLs. | Optional same-origin URLs for v2's browser worker assets. Configure these when the application and SuperDoc bundle are served from different origins. Omitted entries keep SuperDoc's bundled worker URLs. | [Secure integration](/editor/secure-integration) |

### Lifecycle

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `onReady` | `(params: { superdoc: SuperDocClass; }) => void` | — | Optional | Enable document actions after the Editor is ready. | Callback when the SuperDoc is ready. Receives a wrapper carrying the live SuperDoc instance. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onContentError` | `(params: { error: unknown; editor: Editor; documentId: string; file: null \| File \| Blob; }) => void` | — | Optional | Handle document import and content errors. | Called when the editor cannot read or update document content. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onException` | `(params: SuperDocExceptionPayload) => void` | — | Optional | Handle SuperDoc runtime exceptions. | Callback when SuperDoc emits an `exception` event. The payload is a union of runtime shapes (store init, restore failure, editor lifecycle, built-in toolbar, hyperlink activation, structured diagnostic). Narrow with `'stage' in params` (store init), `'code' in params` (editor), `'itemName' in params` (toolbar), `'source' in params` (hyperlink), or `'diagnosticCode' in params` (structured diagnostic) before reading shape-specific fields. A structured diagnostic (`SuperDocExceptionDiagnosticPayload`, `diagnosticCode` one of `PARSE_ERROR` \| `RENDER_ERROR` \| `UNSUPPORTED_FEATURE` \| `PERFORMANCE_ERROR`) can accompany a legacy exception payload. SuperDoc filters unsupported internal records. For translated package and readiness records, it emits at most one structured diagnostic for each `(documentId, generation, internalCode)` tuple. It also suppresses a generic boot diagnostic when a more specific package diagnostic describes the same failure. A single incident can therefore raise 0..N structured diagnostics. The `unzip`, `parse`, `render`, and `export` stages are populated today; `layout` is reserved for future coverage. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onEditorCreate` | `(params: { editor: Editor; }) => void` | — | Optional | Run code after an editor is created. | Callback after an editor is created. Receives a wrapper carrying the editor. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onSourceComplete` | `() => void` | — | Optional | Run code when the document is ready for diff capture. | Callback when the v2 document source reaches source-complete posture and diff.capture is safe to call. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onSourceSignalsComplete` | `() => void` | — | Optional | Run code after source signals finish building. | Callback when v2 source signals finish building (fires after onSourceComplete; diff.capture is synchronously safe). | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onCommentsUpdate` | `(params: { type: string; comment?: Comment; changes?: { key: string; commentId: string; fileId?: string \| null; }[]; pendingSelection?: null \| SelectionInfo; }) => void` | — | Optional | React when comments change. | Callback when comments are updated. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onContentControlClick` | `(params: { target: ContentControlRef; source: "pointer"; }) => void` | — | Optional | React when a person selects a content control. | Callback when someone clicks inside a content control. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onAwarenessUpdate` | `(params: { states: AwarenessState[]; added: number[]; removed: number[]; superdoc: SuperDocClass; }) => void` | — | Optional | React when collaboration awareness changes. | Callback when awareness is updated. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onLocked` | `(params: { isLocked: boolean; lockedBy: null \| User; }) => void` | — | Optional | React when the Editor locks or unlocks. | Callback when the SuperDoc is locked or unlocked. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onPdfDocumentReady` | `() => void` | — | Optional | Run code when a PDF document is ready. | Callback when the PDF document is ready. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onSidebarToggle` | `(isOpened: boolean) => void` | — | Optional | React when the sidebar opens or closes. | Callback when the sidebar is toggled. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onCollaborationReady` | `(params: { editor: Editor; }) => void` | — | Optional | Enable shared-document actions when collaboration is ready. | Callback when collaboration is ready. Receives a wrapper carrying the editor. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onEditorUpdate` | `(params: { editor?: Editor; sourceEditor?: Editor; surface: "body" \| "header" \| "footer"; headerId: null \| string; sectionType: null \| string; }) => void` | — | Optional | React after document content changes. | Callback when document is updated. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onTrackedChangesBulkDecision` | `(params: { documentId: null \| string; decision: "accept" \| "reject"; requestedCount: number; successfulCount: number; permissionDeniedCount: number; }) => void` | — | Optional | React after Accept All or Reject All finishes, including permission-denied counts. | Callback after an Accept All or Reject All tracked-change decision. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onCommentsListChange` | `(params: { isRendered: boolean; }) => void` | — | Optional | React when the comments list is rendered. | Called when the built-in comments list is rendered or removed. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onPaginationUpdate` | `(params: { totalPages: number; superdoc: SuperDocClass; }) => void` | — | Optional | Read the page count after a layout update. | Called after each pagination layout pass with the current page count. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onZoomChange` | `(params: { zoom: number; mode: "manual" \| "fit-width"; }) => void` | — | Optional | React when the zoom level changes. | Callback when the zoom level changes. Fires for every zoom source: `setZoom()`, the toolbar zoom control, and fit-width adjustments. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onViewportChange` | `(params: { availableWidth: number; documentWidth: number; fitZoom: number; }) => void` | — | Optional | React when fit-to-width measurements change. | Callback when the implied fit changes (rounded fit zoom or base page width); pixel-level width jitter does not fire it, and `getViewportMetrics()` always reads latest. Registered before the first emit. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onPageMarginsChange` | `(params: { documentId: string; editorVersion: 2; sectionId: string; sectionIndex: number; side: "left" \| "right"; value: number; pageMargins: { top?: number; right?: number; bottom?: number; left?: number; }; }) => void` | — | Optional | React after a ruler drag changes a section margin. | Callback after a ruler drag changes the active section's left or right page margin. | [Ruler](/editor/built-in-ui/ruler) |
| `onPageCountKnown` | `(payload: { pageCount: number; generation: number; }) => void` | — | Optional | Read the page count before paint. | Experimental callback fired when paginated layout changes the page count. Runs before paint. `generation` identifies the layout pass. Does not fire in web layout. | [Lifecycle and events](/editor/lifecycle-and-events) |
| `onFontsChanged` | `(payload: { source?: "initial" \| "diagnostic-settle" \| "config-change" \| "late-load" \| "render-change"; loadSummary?: null \| FontLoadSummary; report?: FontResolutionRecord[]; missingFonts?: string[]; documentFonts?: string[]; documentFontOptions?: DocumentFontOption[]; }) => void` | — | Optional | Receive final font loading and substitution results. | Called after initial font resolution and whenever substitution or font availability changes. The payload includes the current report, missing fonts, load summary, and the reason for the update. Use `superdoc.fonts.onReport()` for the same subscription at runtime. | [Lifecycle and events](/editor/lifecycle-and-events) |

### Advanced

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `diagnostics` | `{ history?: import("./diagnostics.js").InteractionHistoryConfig; }` | — | Optional | Configure bounded local Interaction History for bug reports. | Configure bounded in-memory Interaction History for browser debugging. | — |
| `isDev` | `boolean` | — | Optional | Enable development behavior for this instance. | Whether the SuperDoc is in development mode. | — |
| `disablePiniaDevtools` | `boolean` | — | Optional | Disable Pinia and Vue devtools for this instance. | Disable Pinia/Vue devtools plugin setup for this SuperDoc instance (useful in non-Vue hosts). | — |
| `layoutEngineOptions` | `{ flowMode?: "paginated" \| "semantic"; trackedChanges?: object; virtualization?: { enabled?: boolean; window?: number; overscan?: number; }; showBookmarks?: boolean; showFormattingMarks?: boolean; paintHud?: boolean; }` | — | Optional | Override page layout and rendering behavior. | Layout engine overrides passed through to DocumentRendererRuntime (page size, margins, virtualization, zoom, debug label, etc.). | [Performance](/editor/performance-and-large-documents) |
| `isInternal` | `boolean` | — | Optional | Set whether the current user creates and reviews internal comments. | Whether the current user is internal. This affects comment visibility, new-comment metadata, and the default permission decision. It is not an authorization boundary. | — |
| `isDebug` | `boolean` | — | Optional | Enable debug behavior. | Whether to enable debug mode. | — |
| `workerStartupTimeoutMs` | `number` | `30000` | Optional | Set how long the document worker may take to start. | Budget for the document worker to start up, in milliseconds (default: 30000). Measured from worker spawn, so it covers script download, parsing, evaluation, and the worker's first response to SuperDoc. Raise it when a large worker chunk is served over a slow connection or a cold dev-server cache; lower it to fail faster. Worker load errors are reported immediately and do not wait for this budget. Must be a finite positive number no greater than 2147483647, the platform timer ceiling above which a delay would fire immediately. | [Performance](/editor/performance-and-large-documents) |
| `useLayoutEngine` | `boolean` | — | Optional | Pass or omit layout engine options when a DOCX editor opens. | Whether `layoutEngineOptions` are passed when a DOCX editor opens. Set to `false` to omit `layoutEngineOptions` and use CSS fallback styling for the initial non-default zoom. This does not select a different DOCX renderer. `viewOptions.layout` separately selects print or web layout. | — |


## Update a running Editor [#update-a-running-editor]

Configuration sets the starting state. After `onReady`, use a runtime method when a value needs to change.

| Change       | Runtime method                 |
| ------------ | ------------------------------ |
| Open a DOCX  | `replaceFile()`                |
| Switch modes | `setDocumentMode()`            |
| Change zoom  | `setZoom()` or `setZoomMode()` |

Changing the object passed to `new SuperDoc()` does not update a running Vanilla instance. In React, `documentMode`
updates as a prop. Access other runtime methods through `editorRef.current?.getInstance()`. If a Vanilla setting has no
runtime method, call `destroy()` on the current instance before creating its replacement. In React, remount
`SuperDocEditor` by changing its `key`; the wrapper destroys the old instance.

Keep React configuration objects such as `user` and `ui` outside the component or memoize them. Changing their object
identity recreates the Editor; changing `documentMode` does not.

## Continue to document modes [#continue-to-document-modes]

[Compare editing, suggesting, and viewing](/editor/document-modes), then choose what viewers see when a document has
comments or tracked changes.

For deployment-specific settings, choose [Telemetry](/editor/telemetry) or [License](/editor/license).


---

# Open dialogs and floating surfaces

> Open temporary application UI over the Editor and handle every way it can finish.



Use a surface when your application needs temporary UI over the Editor. Choose a dialog when the user must respond
before returning to the document. Choose a floating surface when the document should remain usable.

## Try both surface modes [#try-both-surface-modes]

1. Open **confirmation**. Continue submits it. Cancel, Escape, or the backdrop closes it.
2. Open **inspector** and keep editing the document. Open it again to replace the first inspector.

> **Live example: compare a dialog and a floating surface**
>
> Open confirmation to see a modal dialog finish as `submitted` or `closed`. Open inspector twice to see the first floating surface finish as `replaced` while the new inspector stays open. The floating inspector leaves the document usable. The status line reports each lifecycle result.


The status line reports `submitted`, `closed`, or `replaced`. Destroying the Editor produces the remaining outcome,
`destroyed`.

## Choose the right positioning API [#choose-the-right-positioning-api]

| Need                          | API                                                                     |
| ----------------------------- | ----------------------------------------------------------------------- |
| A modal decision              | `openSurface({ mode: 'dialog' })`                                       |
| A fixed, non-modal helper     | `openSurface({ mode: 'floating' })`                                     |
| UI that follows selected text | [Selection and viewport APIs](/editor/custom-ui/selection-and-viewport) |

A floating surface stays in one of the Editor viewport's placement slots. It does not follow a document range. Use the
selection and viewport APIs for a selection toolbar, AI prompt, or other text-anchored UI.

## Open a dialog [#open-a-dialog]

This standalone Vanilla recipe uses `public/sample.docx` from the [Quickstart](/editor/quickstart).
Replace the body of `index.html` with:

```html
<div id="surface-actions">
  <button id="open-confirmation" type="button" disabled>Open confirmation</button>
  <p id="surface-status" role="status">Opening document…</p>
</div>
<div id="editor" style="height: 70vh"></div>
<script type="module" src="/src/main.ts"></script>

```

Replace `src/main.ts` below. This example mounts plain DOM in the surface, but `render()` can mount your framework instead.

```ts
import { SuperDoc, type SurfaceOutcome } from 'superdoc';
import 'superdoc/style.css';

const actions = document.querySelector<HTMLElement>('#surface-actions');
const openButton = document.querySelector<HTMLButtonElement>('#open-confirmation');
const status = document.querySelector<HTMLElement>('#surface-status');
if (!actions || !openButton || !status) throw new Error('The surface controls are incomplete.');

const reportDocumentError = ({ error }: { error: unknown }) => {
  console.error('Could not open the document.', error);
  if (openButton.disabled) status.textContent = 'Could not open the document. Reload to try again.';
};

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  onContentError: reportDocumentError,
  onException: reportDocumentError,
  onReady: () => {
    openButton.disabled = false;
    status.textContent = '';
  },
});

type ConfirmationResult = Readonly<{ action: 'continue' }>;

export const confirmInEditor = async (message: string): Promise<boolean> => {
  const handle = superdoc.openSurface<ConfirmationResult>({
    mode: 'dialog',
    title: 'Confirm action',
    render: ({ container, close, resolve }) => {
      const text = document.createElement('p');
      text.textContent = message;

      const cancel = document.createElement('button');
      cancel.type = 'button';
      cancel.textContent = 'Cancel';

      const confirm = document.createElement('button');
      confirm.type = 'button';
      confirm.textContent = 'Continue';

      const cancelAction = () => close('cancel');
      const confirmAction = () => resolve({ action: 'continue' });
      cancel.addEventListener('click', cancelAction);
      confirm.addEventListener('click', confirmAction);
      container.append(text, cancel, confirm);

      return {
        destroy() {
          cancel.removeEventListener('click', cancelAction);
          confirm.removeEventListener('click', confirmAction);
        },
      };
    },
  });

  const outcome: SurfaceOutcome<ConfirmationResult> = await handle.result;
  switch (outcome.status) {
    case 'submitted':
      return outcome.data?.action === 'continue';
    case 'closed':
      return false;
    case 'replaced':
      return false;
    case 'destroyed':
      return false;
  }
};

openButton.addEventListener('click', async () => {
  actions.inert = true;
  try {
    const confirmed = await confirmInEditor('Continue with this action?');
    status.textContent = confirmed ? 'Confirmed.' : 'No action taken.';
  } catch (error) {
    console.error('Could not open the confirmation.', error);
    status.textContent = 'Could not open the confirmation. Try again.';
  } finally {
    actions.inert = false;
    openButton.focus({ preventScroll: true });
  }
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

Choose **Open confirmation**, then **Continue** or **Cancel**. The status reports your choice; it does not change the DOCX.

SuperDoc owns the dialog shell, position, and focus behavior. Your `render()` callback owns the content. It receives an
empty `container` plus `resolve()` and `close()`. Return `{ destroy() {} }` to remove listeners or unmount a framework
root when the surface closes.

## Handle every outcome [#handle-every-outcome]

`handle.result` resolves once. `resolve(data)` produces `submitted`. `close(reason)`, Escape, and backdrop clicks produce
`closed`. Opening another surface in the same mode produces `replaced` for the previous handle. Destroying the Editor
produces `destroyed`.

Dialog and floating modes have separate active slots, so one of each can be open. Opening a second surface in either
mode replaces only the surface in that mode.

Invalid requests throw synchronously. Normal lifecycle outcomes resolve `handle.result`; they do not reject it.

## Use the interaction defaults deliberately [#use-the-interaction-defaults-deliberately]

Dialogs trap focus, restore it when they close, and close on Escape or backdrop clicks by default. Floating surfaces
default to the top-right, focus their first control, close on Escape, and stay open after outside pointer events.

The dialog's trap covers keystrokes inside its own backdrop. Controls your application renders outside the Editor
viewport are not part of it, so moving focus to one takes the reader out of the dialog and Escape stops closing it.
While a dialog is open, make the rest of your interface unreachable — `inert` on the surrounding region is enough — and
do not rely on the trap alone to contain focus.

The trap also needs something to hold. It cycles between the first and last enabled focusable elements inside the
backdrop, so a dialog whose `render()` adds none — text-only content, or controls that are all disabled — has no cycle
to enforce and Tab leaves it on the first press. The shell itself takes initial focus but does not retain it. Give every
dialog at least one enabled control, such as a confirm or close button, even when its content is only a message.

Give every surface a visible `title`, `ariaLabel`, or `ariaLabelledBy`. Override the close and focus defaults only when
the workflow needs different behavior. These options control interaction, not authorization or transaction safety.

Configure `surfaces` for shared defaults or intent resolution. Direct `openSurface()` calls do not need a resolver.

## Verify the lifecycle [#verify-the-lifecycle]

Open a confirmation and complete it each way. Open the inspector twice and confirm the first handle reports `replaced`.
Confirm focus returns to the control that opened a dialog.

Next, [apply your product theme to the Editor UI](/editor/theming).


---

# Choose a document mode

> Choose how the Editor handles edits and what appears in viewing mode.



The [Configuration](/editor/configuration) guide starts `/sample.docx` in `suggesting` mode. Compare it with `editing`
and `viewing`, then choose the behavior your application needs.

## Try each mode [#try-each-mode]

Expand the Editor. Try the replacement in Editing, then reset the sample. Switch to Suggesting and replace `30 days`
with `60 days`. Switch to Viewing, then use Changes to compare Original, Markup, and Final against that same proposal.

> **Interactive editor: Try document modes**
>
> Sample: [open the fixture](/fixtures/document-modes.docx).
>
> Preset: `document-modes`.
>
> Try the same edit in each mode. Editing changes the document directly and is the default. Suggesting records a tracked change. After making a suggestion, switch to Viewing and use Changes to choose Original, Markup, or Final for the same proposal.
>
> Local DOCX selection: disabled.


| Mode         | What happens                       | Use it when                                       |
| ------------ | ---------------------------------- | ------------------------------------------------- |
| `editing`    | The text changes directly.         | Changes should become part of the document.       |
| `suggesting` | The edit becomes a tracked change. | Another person should review the proposed change. |
| `viewing`    | Editing is disabled.               | A person should read without changing the DOCX.   |

`editing` is the default. Modes change Editor behavior in the browser. They do not decide who can open or save the
document.

## Apply the mode to your project [#apply-the-mode-to-your-project]

Keep the Quickstart page, styles, and `/sample.docx`. Replace `src/main.ts` in Vanilla or `src/App.tsx` in React with the
matching example below. It keeps the author and export button, and adds **Switch to viewing** after the document opens.

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const exportButton = document.querySelector<HTMLButtonElement>('#export-docx');
const viewingButton = document.createElement('button');
viewingButton.type = 'button';
viewingButton.textContent = 'Switch to viewing';
viewingButton.disabled = true;

if (!exportButton) throw new Error('The export button is missing.');
exportButton.before(viewingButton);

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  documentMode: 'suggesting',
  user: { name: 'Jordan Lee', email: 'jordan@example.com' },
  viewing: {
    comments: true,
    trackedChanges: 'markup',
  },
  onReady: () => {
    exportButton.disabled = false;
    viewingButton.disabled = false;
  },
  onContentError: ({ error }) => console.error('SuperDoc could not open the document.', error),
  onException: ({ error }) => console.error('SuperDoc could not open the document.', error),
});

viewingButton.addEventListener('click', () => {
  superdoc.setDocumentMode('viewing');
  viewingButton.disabled = true;
});

exportButton.addEventListener('click', async () => {
  exportButton.disabled = true;
  try {
    await superdoc.export({ exportType: ['docx'], exportedName: 'sample-edited' });
  } catch (error) {
    console.error('SuperDoc could not export the document.', error);
  } finally {
    exportButton.disabled = false;
  }
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type DocumentMode, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const user = { name: 'Jordan Lee', email: 'jordan@example.com' };

function reportDocumentError({ error }: { error: unknown }) {
  console.error('SuperDoc could not open the document.', error);
}

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const exportingRef = useRef(false);
  const [ready, setReady] = useState(false);
  const [exporting, setExporting] = useState(false);
  const [documentMode, setDocumentMode] = useState<DocumentMode>('suggesting');

  async function exportDocument() {
    if (exportingRef.current) return;
    exportingRef.current = true;
    setExporting(true);
    try {
      await editorRef.current?.getInstance()?.export({ exportType: ['docx'], exportedName: 'sample-edited' });
    } catch (error) {
      console.error('SuperDoc could not export the document.', error);
    } finally {
      exportingRef.current = false;
      setExporting(false);
    }
  }

  return (
    <main>
      <button disabled={!ready || documentMode === 'viewing'} onClick={() => setDocumentMode('viewing')} type='button'>
        Switch to viewing
      </button>
      <button disabled={!ready || exporting} onClick={() => void exportDocument()} type='button'>
        Export DOCX
      </button>
      <SuperDocEditor
        ref={editorRef}
        user={user}
        document='/sample.docx'
        documentMode={documentMode}
        onReady={() => setReady(true)}
        onContentError={reportDocumentError}
        onException={reportDocumentError}
        viewing={{
          comments: true,
          trackedChanges: 'markup',
        }}
      />
    </main>
  );
}

```


Vanilla calls `setDocumentMode()` on the ready Editor. React updates the `documentMode` prop. Neither change remounts the
Editor.

Change the effective date while suggesting, then select **Switch to viewing**. The proposal should remain visible,
but typing should no longer change the document. **Export DOCX** should still download the document with the proposal.

## Choose how tracked changes appear [#choose-how-tracked-changes-appear]

Viewing stays read-only. Its `trackedChanges` option changes how proposals appear without accepting or rejecting them.

For the `30 days` to `60 days` proposal in the demo:

| `trackedChanges` | What appears in viewing mode                           | Use it to                                    |
| ---------------- | ------------------------------------------------------ | -------------------------------------------- |
| `original`       | `30 days`, without change marks.                       | Show the document before the proposal.       |
| `markup`         | `30 days` deleted and `60 days` inserted, both marked. | Show exactly what the proposal changes.      |
| `final`          | `60 days`, without change marks.                       | Preview the document as if it were accepted. |

`original` is the default. These options only change the display. The proposal remains in the DOCX.

Set `viewing.comments` to `true` to show comment anchors and threads. Comments are hidden by default.

To change a mounted viewer, call `superdoc.setViewingOptions({ trackedChanges: 'final' })` after `onReady`. Omitted
options keep their current values.

For review controls, see [Track changes](/editor/track-changes). For comment threads, see
[Comments](/editor/comments).

## Continue to load and save [#continue-to-load-and-save]

[Load and save a DOCX](/editor/load-and-save-documents) to connect the same project to your storage.


---

# Control DOCX export

> Download an edited DOCX, return its bytes, or package related files.



Export the document you have edited, then choose what your application does with the file. The browser Editor
exports DOCX; it does not convert the document to PDF or HTML through this method.

Use the running Editor from the [Quickstart](/editor/quickstart). The examples below belong in your export button's
handler, after `onReady`. Keep the button disabled while export is running and show any rejected promise as an error.

In Vanilla, `superdoc` is the instance you created. In React, obtain it inside the handler before using any example:

```ts
const superdoc = editorRef.current?.getInstance();
if (!superdoc) return;
```

## Download the edited document [#download-the-edited-document]

```ts
await superdoc.export({ exportedName: 'sample-edited' });
```

This starts a download named `sample-edited.docx`. Open it and confirm that your edit is present. The filename does
not need an extension, and DOCX is already the default format.

For a runnable save, edit, restore, and export flow, use the
[version-history example](https://go.superdoc.dev/examples/version-history). Its **Export current DOCX** button downloads
the document currently open in the Editor.

## Return bytes without downloading [#return-bytes-without-downloading]

Set `triggerDownload: false` when your application needs the file instead of a browser download:

```ts
const docx = await superdoc.export({ triggerDownload: false });
```

For one document without additional files, the result is a DOCX `Blob`. Export does not upload it or confirm a save.
Use the [Load and save guide](/editor/load-and-save-documents) to send those bytes to your backend and report success
only after storage confirms the write.

## Check comments and tracked changes [#check-comments-and-tracked-changes]

Export preserves comments by default. The Quickstart's default v2 worker runtime does not support
`commentsType: 'clean'`: export rejects instead of returning a copy without comments.

If you need final text, finish the
[review workflow](/editor/track-changes) before exporting. The v2 Editor does not apply `isFinalDoc`
during export; do not use that option as a review decision.

## Include related files [#include-related-files]

To deliver the DOCX alongside another file, supply a `Blob` and its filename. This example creates its own small
metadata file; it does not require an audit service:

```ts
const metadata = new Blob([JSON.stringify({ document: 'sample-edited' })], { type: 'application/json' });

const bundle = await superdoc.export({
  exportedName: 'sample-edited',
  additionalFiles: [metadata],
  additionalFileNames: ['metadata.json'],
  triggerDownload: false,
});
```

The result is a ZIP `Blob` containing `sample-edited.docx` and `metadata.json`. Keep the two additional-file arrays
in the same order, with one filename for each file. Omit `triggerDownload: false` to download `sample-edited.zip`.

## Choose options for the next export [#choose-options-for-the-next-export]

| Option                                    | Default      | Effect                                                                                |
| ----------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| `exportedName`                            | Editor title | Name the DOCX or ZIP without its extension.                                           |
| `triggerDownload`                         | `true`       | Download the result; set it to `false` to return a `Blob` or ZIP without downloading. |
| `commentsType`                            | `'external'` | Preserve comments. The default v2 worker runtime rejects `'clean'`.                   |
| `additionalFiles` / `additionalFileNames` | Empty arrays | Include related files in a ZIP.                                                       |

`exportType` defaults to `['docx']`, the browser Editor's supported export format.
The v2 Editor does not apply `fieldsHighlightColor` during export.

Use [Version history](/editor/version-history) when your application needs to retain each exported DOCX as a saved version.


---

# Resolve document fonts

> See how each DOCX font resolves, then provide licensed files for missing families.



The theme from the previous page styles controls around the document. Document fonts are separate. A DOCX stores family
names such as Aptos, but may not contain the corresponding font files.

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart). It requests Aptos for body text and Aptos Display
for headings. Start without adding a `fonts` configuration.

## Start with the available fonts [#start-with-the-available-fonts]

By default, SuperDoc keeps each font name from the DOCX. It uses an embedded font when the document contains one and its
embedding permissions allow it. Otherwise, the browser uses an installed system font with that name. With no font
provider configured, SuperDoc does not fetch a replacement for an unavailable document family.

One built-in provider is the exception. SuperDoc always registers a core-symbol face and requests it when the document
contains symbol or dingbat characters it covers — including the `•` bullet in the Quickstart sample. That request
happens with no `fonts` configuration at all, so the package's bundled font assets must stay reachable under your
Content Security Policy even before you add a provider. It supplies those glyphs only; it never substitutes a document
family.

If the requested font is unavailable, the browser paints with its fallback. The text remains editable and export keeps
the original DOCX font name, but different glyph widths can change line and page breaks.

| Your document and audience                             | Recommended path                                                      |
| ------------------------------------------------------ | --------------------------------------------------------------------- |
| The DOCX contains an eligible embedded font            | Open the document without font configuration.                         |
| Every supported device has the requested font          | Use the system font and verify each supported environment.            |
| The font is proprietary or is not installed everywhere | Host licensed web-font files and register each required face.         |
| You intentionally accept a different typeface          | Register that font, map the DOCX family to it, and verify pagination. |

The font names shown in the built-in toolbar are choices, not font files bundled with `superdoc`.

## See the resolution path [#see-the-resolution-path]

Compare what happens to the Aptos body text in the Quickstart document. The DOCX name stays the same while the available
provider changes.

> **Interactive model: how a document font resolves**
>
> | Scenario | DOCX requests | Provider | SuperDoc resolves | DOCX exports | Diagnostic |
> | --- | --- | --- | --- | --- | --- |
> | System font | Aptos | Installed Aptos | Aptos | Aptos | reason: `as_requested`; loadStatus: `unloaded`; systemAvailability: `available`; missing: `false` |
> | Hosted font | Aptos | /fonts/aptos-regular.woff2 | Aptos | Aptos | reason: `registered_face`; loadStatus: `loaded`; missing: `false` |
> | Unavailable font | Aptos | No usable Aptos face | Aptos | Aptos | reason: `as_requested`; loadStatus: `unloaded`; systemAvailability: `unavailable`; missing: `true` |


For an available system font, `loadStatus: 'unloaded'` does not mean the font is missing. It means SuperDoc did not load a
registered font asset. `systemAvailability` reports whether the browser can use the system face.

## Host a proprietary font [#host-a-proprietary-font]

Host a proprietary font only when its license permits web delivery. For the Quickstart document, place the licensed
Aptos files under `public/fonts`, then register the families and faces the document uses. Each tab is the Quickstart
file with `fonts` added, so the export button the fidelity checklist relies on keeps working:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc, type Config } from 'superdoc';
import 'superdoc/style.css';

const exportButton = document.querySelector<HTMLButtonElement>('#export-docx');

if (!exportButton) throw new Error('The export button is missing.');

const documentFonts = {
  families: [
    {
      family: 'Aptos',
      faces: [
        { source: '/fonts/aptos-regular.woff2', weight: 400, style: 'normal' },
        { source: '/fonts/aptos-bold.woff2', weight: 700, style: 'normal' },
      ],
    },
    {
      family: 'Aptos Display',
      faces: [{ source: '/fonts/aptos-display.woff2', weight: 400, style: 'normal' }],
    },
  ],
} satisfies NonNullable<Config['fonts']>;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  fonts: documentFonts,
  onReady: () => {
    exportButton.disabled = false;
  },
  onContentError: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
  onException: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
});

exportButton.addEventListener('click', async () => {
  exportButton.disabled = true;
  try {
    await superdoc.export({ exportType: ['docx'], exportedName: 'sample-edited' });
  } catch (error) {
    console.error('SuperDoc could not export the document.', error);
  } finally {
    exportButton.disabled = false;
  }
});

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocConfig, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const documentFonts = {
  families: [
    {
      family: 'Aptos',
      faces: [
        { source: '/fonts/aptos-regular.woff2', weight: 400, style: 'normal' },
        { source: '/fonts/aptos-bold.woff2', weight: 700, style: 'normal' },
      ],
    },
    {
      family: 'Aptos Display',
      faces: [{ source: '/fonts/aptos-display.woff2', weight: 400, style: 'normal' }],
    },
  ],
} satisfies NonNullable<SuperDocConfig['fonts']>;

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const exportingRef = useRef(false);
  const [ready, setReady] = useState(false);
  const [exporting, setExporting] = useState(false);

  async function exportDocument() {
    if (exportingRef.current) return;
    exportingRef.current = true;
    setExporting(true);
    try {
      await editorRef.current?.getInstance()?.export({ exportType: ['docx'], exportedName: 'sample-edited' });
    } catch (error) {
      console.error('SuperDoc could not export the document.', error);
    } finally {
      exportingRef.current = false;
      setExporting(false);
    }
  }

  return (
    <main>
      <button disabled={!ready || exporting} onClick={() => void exportDocument()} type='button'>
        Export DOCX
      </button>
      <SuperDocEditor
        document='/sample.docx'
        fonts={documentFonts}
        onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
        onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
        onReady={() => setReady(true)}
        ref={editorRef}
      />
    </main>
  );
}

```


The `Config['fonts']` type behind `documentFonts` checks the configuration while preserving its specific values. `family`
matches the logical name stored in the DOCX. Because the names match, no mapping is needed. Each `source` identifies one
physical face. Register regular, bold, italic, and bold italic when the document uses them; one face does not make the
others available.

The sample's bullet markers are set in `Symbol` by its numbering definition, so the report also lists a `Symbol` row.
That family ships with most desktop systems and is not one you would normally host; if it reports `missing: true` on a
target device, map it to a face you can provide rather than registering a licensed `Symbol` file.

A font loaded by your application's `@font-face` CSS can also be available to the browser. Prefer `fonts.families` for
document fonts so SuperDoc knows which source and face descriptors to load before it measures the document.

SuperDoc registers these providers at startup and loads required faces before measuring when it can. A missing or blocked
asset still allows the document to open, but the report identifies the fallback.

## Check what rendered [#check-what-rendered]

Subscribe after the Editor is ready. `fonts.onReport()` immediately replays the current report when one exists, then
reports changes such as a late font load. Save this helper as `src/font-report.ts`; it takes a SuperDoc instance, so
both frameworks use the same file:

```ts
import type { SuperDoc } from 'superdoc';

export function observeDocumentFonts(superdoc: SuperDoc) {
  return superdoc.fonts.onReport(({ report = [] }) => {
    for (const font of report) {
      console.log({
        logicalFamily: font.logicalFamily,
        physicalFamily: font.physicalFamily,
        reason: font.reason,
        loadStatus: font.loadStatus,
        systemAvailability: font.systemAvailability,
        exportFamily: font.exportFamily,
        missing: font.missing,
        // Face-level rows repeat a family per weight/style; without this, a failed bold is
        // indistinguishable from the regular that loaded beside it.
        face: font.face,
        // A substitution can load cleanly and still reflow the document. `evidence.lineBreakSafe`
        // is the only field that separates a metric-safe substitute from a visual-only one.
        evidence: font.evidence,
      });
    }
  });
}

```

Import it where you create the Editor and keep the returned function for teardown. These are additions to the complete
files above, not replacements — the export button and error handlers they already set up stay as they are. Vanilla
subscribes from `onReady` and unsubscribes on unload:

```ts
// src/main.ts — additions to the file you already have.
import { observeDocumentFonts } from './font-report';

let stopFontReport: (() => void) | undefined;

// Inside the existing onReady, alongside `exportButton.disabled = false`:
stopFontReport = observeDocumentFonts(superdoc);

// The Quickstart has no teardown listener yet; add one:
window.addEventListener('beforeunload', () => {
  stopFontReport?.();
});
```

React subscribes from the same callback and releases the handle when the component unmounts:

```tsx
// src/App.tsx — additions to the file you already have.
import { useEffect } from 'react';
import { observeDocumentFonts } from './font-report';

const stopFontReport = useRef<(() => void) | undefined>(undefined);

useEffect(() => () => stopFontReport.current?.(), []);

// Inside the existing onReady, alongside `setReady(true)`:
const instance = editorRef.current?.getInstance();
if (instance) stopFontReport.current = observeDocumentFonts(instance);
```

Use these fields to decide whether the document needs another font provider:

| Field                | What it tells you                                                                 |
| -------------------- | --------------------------------------------------------------------------------- |
| `logicalFamily`      | Font family requested by the DOCX.                                                |
| `physicalFamily`     | Family SuperDoc resolved for measurement and paint.                               |
| `reason`             | Why that physical family was selected.                                            |
| `loadStatus`         | State of a registered font asset.                                                 |
| `systemAvailability` | Whether an unregistered system face is available.                                 |
| `exportFamily`       | Font family that export preserves in the DOCX.                                    |
| `missing`            | Whether SuperDoc has confirmed that the requested face lacks a faithful provider. |
| `face`               | Weight and style on face-level rows; absent on family-level rows.                 |

Act on `missing: true`, not on a transient `loadStatus`. A system face with `systemAvailability: 'unknown'` is unresolved,
but SuperDoc does not call it missing without evidence.

When `reason` is `as_requested` and `missing` is `true`, `physicalFamily` remains the requested name. The browser chose a
fallback, but does not report that fallback's family to SuperDoc.

Use `superdoc.fonts.getReport()` when you only need the current snapshot.

## Map an intentional substitute [#map-an-intentional-substitute]

Use a mapping when the font you can provide has a different family name from the one stored in the DOCX. This example
substitutes Inter for both Aptos families, so place `inter-regular.woff2` and `inter-bold.woff2` in `public/fonts`
alongside the Aptos files before continuing — the mapping resolves to a browser fallback if those assets are missing.

Change only the `documentFonts` value in the file you already have: it registers Inter and maps both DOCX families onto
it. Everything else — including the `observeDocumentFonts` wiring from the previous section — stays as it is, because the
fidelity checklist below reads the report that wiring produces. The snippets show the whole file for context.

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc, type Config } from 'superdoc';
import 'superdoc/style.css';

const exportButton = document.querySelector<HTMLButtonElement>('#export-docx');

if (!exportButton) throw new Error('The export button is missing.');

const documentFonts = {
  families: [
    {
      family: 'Inter',
      faces: [
        { source: '/fonts/inter-regular.woff2', weight: 400, style: 'normal' },
        { source: '/fonts/inter-bold.woff2', weight: 700, style: 'normal' },
      ],
    },
  ],
  map: {
    Aptos: 'Inter',
    'Aptos Display': 'Inter',
  },
} satisfies NonNullable<Config['fonts']>;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  fonts: documentFonts,
  onReady: () => {
    exportButton.disabled = false;
  },
  onContentError: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
  onException: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
});

exportButton.addEventListener('click', async () => {
  exportButton.disabled = true;
  try {
    await superdoc.export({ exportType: ['docx'], exportedName: 'sample-edited' });
  } catch (error) {
    console.error('SuperDoc could not export the document.', error);
  } finally {
    exportButton.disabled = false;
  }
});

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocConfig, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const documentFonts = {
  families: [
    {
      family: 'Inter',
      faces: [
        { source: '/fonts/inter-regular.woff2', weight: 400, style: 'normal' },
        { source: '/fonts/inter-bold.woff2', weight: 700, style: 'normal' },
      ],
    },
  ],
  map: {
    Aptos: 'Inter',
    'Aptos Display': 'Inter',
  },
} satisfies NonNullable<SuperDocConfig['fonts']>;

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const exportingRef = useRef(false);
  const [ready, setReady] = useState(false);
  const [exporting, setExporting] = useState(false);

  async function exportDocument() {
    if (exportingRef.current) return;
    exportingRef.current = true;
    setExporting(true);
    try {
      await editorRef.current?.getInstance()?.export({ exportType: ['docx'], exportedName: 'sample-edited' });
    } catch (error) {
      console.error('SuperDoc could not export the document.', error);
    } finally {
      exportingRef.current = false;
      setExporting(false);
    }
  }

  return (
    <main>
      <button disabled={!ready || exporting} onClick={() => void exportDocument()} type='button'>
        Export DOCX
      </button>
      <SuperDocEditor
        document='/sample.docx'
        fonts={documentFonts}
        onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
        onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
        onReady={() => setReady(true)}
        ref={editorRef}
      />
    </main>
  );
}

```


SuperDoc registers Inter, follows each `map` entry, and loads the required faces before initial measurement. The mapping
changes measurement and paint for this document. It does not rename the fonts in the DOCX; export still preserves Aptos
and Aptos Display.

Use `superdoc.fonts.add()`, `superdoc.fonts.map()`, and `superdoc.fonts.preload()` instead when a user chooses a provider
after the document opens. `preload()` accepts logical DOCX family names and follows the active mapping.

An arbitrary substitute can change layout even when it loads successfully. Prefer the original font or a substitute
whose metrics you have evaluated for the documents you support.

## Verify font fidelity [#verify-font-fidelity]

* Confirm every report row has the expected `physicalFamily`, `missing: false`, **and** positive evidence that the face
  resolved: a registered face at `loadStatus: 'loaded'`, or a pass-through face at `systemAvailability: 'available'`.
  Both halves are needed. `missing: false` alone is not enough, because the report withholds `missing` while
  availability is `checking` or `unknown`; a loaded face alone is not enough either, because a non-metric
  `category_fallback` loads successfully and still reports `missing: true`.
* Rows whose `reason` is `bundled_substitute` or `category_fallback` also carry `evidence`. Check
  `evidence.lineBreakSafe` on those: such a row can report `loadStatus: 'loaded'` and `missing: false` while the runtime
  marks it `verdict: 'visual_only'` with `lineBreakSafe: false` — Cooper Black resolving to Caprasimo is one. Those rows
  render, but their advances do not preserve line breaks, so treat them as a layout change to review rather than a
  passing fidelity check. Every other reason, including the `custom_mapping` this page's Inter mapping produces, leaves
  `evidence` undefined; verify those with the line and page break comparison below.
* Exercise every weight and style your documents use; a loaded regular face does not verify bold or italic.
* Compare line and page breaks in SuperDoc and Word after changing a provider or mapping.
* Export and reopen the DOCX. The original logical family should remain selected.
* For cross-origin assets, allow the font origin in CORS and Content Security Policy rules.

Continue with [Track changes](/editor/track-changes) to let reviewers propose and decide edits without immediately
changing the accepted document.


---

# SuperDoc Editor

> Understand the challenge of editing DOCX on the web and how SuperDoc approaches it with an OOXML-backed document model.



SuperDoc is a document editor you embed in your web application. It lets people open, edit, and export DOCX files,
using the document's underlying format as the foundation for editing.

## A document is more than its text [#a-document-is-more-than-its-text]

A Word document can contain styles, page sections, headers, footers, comments, and tracked changes. Those details are
stored in OOXML: the XML parts, relationships, and assets packaged inside a DOCX file.

Bringing that document into a web editor is not just a matter of displaying its text. The editor must represent those
details while people work, then write their changes back to a DOCX.

When an editor converts DOCX into HTML or another editing format, it has to translate between two document models.
Details that the editing model cannot represent may be changed or dropped when the DOCX is rebuilt for export.

## Edit the document, not an HTML conversion [#edit-the-document-not-an-html-conversion]

SuperDoc reads the OOXML package into editable document state. The browser renders a view of that state; edits update
it, and export writes the changes back into the OOXML package.

The browser DOM is a view of the document, not the source used to reconstruct it. This avoids a DOCX-to-HTML-to-DOCX
conversion step and keeps document structure at the center of editing.

For the engine architecture, see [How SuperDoc works](/resources/how-superdoc-works).

## The Editor in your application [#the-editor-in-your-application]

The Editor runs in the browser and needs no SuperDoc server to render or edit a document. It provides built-in controls
for editing and review. You can configure those controls or build your own UI through the public APIs.

People edit through the interface; application code can read and change the same open document through the Document
API. Your application decides where documents come from, who can access them, and where changes are saved.

## What changed in v2? [#what-changed-in-v2]

SuperDoc v1 used ProseMirror as its authoritative browser editing model. V2 uses OOXML-backed document state instead,
with the same document engine and Document API contract across browser and supported headless workflows.

This changes how application code interacts with the document: use the public Document API rather than ProseMirror
state or commands. If you already use v1, start with [Migrate from v1](/editor/migrate-from-v1/overview).

## Open your first document [#open-your-first-document]

[Follow the Quickstart](/editor/quickstart) to open a sample DOCX, make an edit, and download the result.

SuperDoc is open source under AGPLv3. A commercial license is available for proprietary applications. See
[Licensing](/resources/license) for the requirements of each option.


---

# Configure the Editor license

> Set the browser Editor license identity.




Set the license key when you create the Editor. When telemetry is enabled, the browser Editor sends it with document-open events. It is client-visible configuration, not a secret or an authorization credential.

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  licenseKey: import.meta.env.VITE_SUPERDOC_LICENSE_KEY,
});
```

When telemetry is enabled and you omit the key, document-open events use the community and evaluation identity. Browser build variables remain visible to the person running the application. Keep document access, collaboration credentials, and service authorization separate from the license identity.

This page covers Editor configuration. See [Licensing](/resources/license) for the open-source and commercial terms and the licensing contact.

Continue with [Telemetry](/editor/telemetry) to make the Editor's network behavior explicit.


---

# Handle lifecycle and events

> Understand when the Editor is ready, what counts as an edit, and when to release it.



Your application needs to know when the document is usable, when it changes, and when to release the Editor.
Add those states to the [Quickstart](/editor/quickstart) before connecting storage or custom controls.

## Follow the lifecycle [#follow-the-lifecycle]

Select a stage to see its signal and application state. This is a simulated preview, not a live Editor.

> **Interactive model: the Editor lifecycle in your application**
>
> The preview moves `/sample.docx` through the application states that matter to a user.
>
> 1. **Mount — `new SuperDoc()`:** Show a loading state. Keep document actions disabled while the DOCX opens.
> 2. **Ready — `onReady`:** Enable document actions. The document is available. Enable Export and run document queries.
> 3. **Edit — `onEditorUpdate`:** Mark the document unsaved. Mark changes to document content as unsaved. Moving the cursor does not count as an edit.
> 4. **Export — `export()`:** Download a copy. Export downloads a DOCX. Changes remain unsaved in your application until your backend stores them.
> 5. **Unmount — `destroy()`:** Release the Editor. Call destroy() when the route or component that owns the Editor unmounts.
>
> **Load fails — `onContentError / onException`:** Show a useful error. Keep document actions disabled. Show a retry path instead of an empty mount point.


## Connect the signals [#connect-the-signals]

In the Vanilla Quickstart, replace the export button and mount point with this markup. Keep the script tag:

```html
<button id="export-docx" type="button" disabled>Export DOCX</button>
<output id="editor-status" aria-live="polite">Opening…</output>
<div id="editor"></div>
```

Replace `src/main.ts` with the example below. Keep the styles and `/sample.docx`; no backend is needed.
Copy any user or mode options you chose on the previous pages into this configuration.

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

function requireElement<ElementType extends Element>(selector: string) {
  const element = document.querySelector<ElementType>(selector);
  if (!element) throw new Error(`${selector} not found.`);
  return element;
}

const status = requireElement<HTMLOutputElement>('#editor-status');
const exportButton = requireElement<HTMLButtonElement>('#export-docx');

let isReady = false;
let hasUnsavedChanges = false;
let isExporting = false;
let isUnmounted = false;

function showLoadError(error: unknown) {
  console.error('SuperDoc error', error);
  if (isReady || isUnmounted) return;

  status.value = 'Could not open the document';
  exportButton.disabled = true;
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  onReady: () => {
    if (isUnmounted) return;
    isReady = true;
    status.value = 'Ready';
    exportButton.disabled = isExporting;
  },
  onEditorUpdate: () => {
    if (isUnmounted) return;
    hasUnsavedChanges = true;
    status.value = 'Unsaved changes';
  },
  onContentError: ({ error }) => showLoadError(error),
  onException: ({ error }) => showLoadError(error),
});

async function exportDocument(): Promise<void> {
  if (!isReady || isExporting || isUnmounted) return;

  isExporting = true;
  exportButton.disabled = true;
  try {
    await superdoc.export({ exportedName: 'sample-edited' });
    if (!isUnmounted) status.value = hasUnsavedChanges ? 'Unsaved changes' : 'Ready';
  } catch (error) {
    if (!isUnmounted) status.value = 'Export failed. Try again.';
    console.error('Could not export the document.', error);
  } finally {
    isExporting = false;
    if (!isUnmounted) exportButton.disabled = !isReady;
  }
}

exportButton.addEventListener('click', exportDocument);

export function unmountEditor(): void {
  isUnmounted = true;
  exportButton.disabled = true;
  exportButton.removeEventListener('click', exportDocument);
  superdoc.destroy();
}

```

`onReady` means the document is available for queries and export. `onEditorUpdate` reports document edits, not cursor
movement or pagination. Downloading a copy does not save changes to your application, so it does not clear the
**Unsaved changes** status.

## Release what you own [#release-what-you-own]

Call `unmountEditor()` when the owning route or component unmounts. It removes the button listener and calls
`destroy()`. The React Quickstart's `SuperDocEditor` component handles its own Editor cleanup.

For a temporary panel, use `on()` and `off()` with the same function. This fragment assumes the ready `superdoc`
instance from the example above:

```ts
import type { SuperDocZoomPayload } from 'superdoc';

const onZoom = ({ zoom }: SuperDocZoomPayload): void => {
  console.log('Zoom:', zoom);
};

superdoc.on('zoomChange', onZoom);
// When the panel closes:
superdoc.off('zoomChange', onZoom);
```

## Check the flow [#check-the-flow]

Reload the page. **Export DOCX** should stay disabled until the document opens. Edit the effective date, then export.
The browser should download `sample-edited.docx`, while the status remains **Unsaved changes**.

Temporarily change `/sample.docx` to a missing URL. The page should show a load error and keep **Export DOCX** disabled.

## Go deeper [#go-deeper]

* [Load and save documents](/editor/load-and-save-documents) connects the Editor to your backend storage.
* [Configure the Editor](/editor/configuration) lists all startup callbacks and their payload types.

## Export recent Interaction History [#export-recent-interaction-history]

The browser Editor keeps a bounded **Interaction History** in memory by default. When an edit looks wrong,
your application can request a snapshot without waiting for an exception:

```ts
const history = superdoc.diagnostics.getSnapshot();
const report = JSON.stringify(history);
// Let the customer review and share the report through your bug-report flow.
superdoc.diagnostics.clear();
```

The history records recent input attempts, commands, mutation receipts, selection changes, render progress,
and lifecycle failures. Collaboration sessions also record remote changes observed by this browser.
A snapshot is detached from the running recorder; capturing it does not query the worker or document.
You can also request one inside `onException`.

Configure retention when creating the Editor:

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  diagnostics: {
    history: {
      enabled: true,
      maxEvents: 500,
      maxBytes: 1_048_576,
      captureContent: false,
    },
  },
});
```

These are the defaults. The oldest events are removed when either limit is reached. `maxEvents` accepts
1–10,000; `maxBytes` accepts 1–16,777,216 and measures retained serialized UTF-16 payloads, excluding object
overhead. Invalid limits use the defaults. Individual events and nested payloads are also capped; snapshots
report eviction, truncation, and capture-failure counts. Set `enabled: false` to disable capture.

By default, the recorder selects metadata fields and excludes document text and error messages.
`captureContent: true` allows bounded text carried by observed events and API calls; treat those reports
as document content. Metadata can include document and transaction identifiers, so review reports before sharing.
This recorder does not upload or persist reports. Capture stops when the instance is destroyed; the history
belongs to that instance and does not survive a page reload. Capture failures are isolated from editor operations.

History is diagnostic evidence, not a complete replay or audit log. Selection events may be coalesced,
older events may be evicted, and each collaboration peer records its own observation order.


---

# Load and save a DOCX

> Load a DOCX from your application and save the edited file back to your backend.



The [Quickstart](/editor/quickstart) downloads your edits. To keep them when someone returns, load and save the DOCX
through your application API:

1. Fetch the DOCX from your API as a `Blob`.
2. Open and edit the `Blob` in SuperDoc.
3. Export the edited DOCX as a new `Blob` and send it back to your API.

SuperDoc handles the DOCX in the browser. Your application owns the API and storage.

## 1. Add a document endpoint [#1-add-a-document-endpoint]

The examples use `/api/documents/sample`. This is an application route, not a SuperDoc route.

| Request | Your endpoint must                                                          |
| ------- | --------------------------------------------------------------------------- |
| `GET`   | Return the current DOCX bytes                                               |
| `PUT`   | Store the request body and return a success status after the write finishes |

The Quickstart does not create this endpoint. Add it to your backend with the sample DOCX as its initial document.
Proxy `/api/documents/sample` from Vite to your backend, or change `endpoint` below to your API URL. For a different
origin, allow GET and PUT through CORS. Keep storage credentials and access checks in the backend.

Restart Vite after adding the proxy. Check that the GET response contains DOCX bytes, not your application's HTML
page: a fallback page can return `200` and still fail to open as a document.

## 2. Add a save action [#2-add-a-save-action]

For Vanilla, replace the export button and Editor container in `index.html` with the following markup. Keep the
`<script type="module" src="/src/main.ts"></script>` tag:

```html
<button id="save-docx" type="button" disabled>Save DOCX</button>
<output id="document-status" aria-live="polite">Opening…</output>
<div id="editor"></div>
```

The React example below renders its own controls.

## 3. Load and save the document [#3-load-and-save-the-document]

Replace `src/main.ts` in Vanilla or `src/App.tsx` in React. Keep the Quickstart styles and React entry point. Copy any
user, mode, or viewing options you chose on the previous pages into this Editor configuration; the examples otherwise
use the default editing mode.

**Vanilla — `src/main.ts`**

```ts
import { DOCX, SuperDoc } from 'superdoc';
import 'superdoc/style.css';

function requireElement<ElementType extends Element>(selector: string) {
  const element = document.querySelector<ElementType>(selector);
  if (!element) throw new Error(`${selector} not found.`);
  return element;
}

const saveButton = requireElement<HTMLButtonElement>('#save-docx');
const status = requireElement<HTMLOutputElement>('#document-status');

const endpoint = '/api/documents/sample';
let isReady = false;
let editRevision = 0;
let superdoc: SuperDoc | undefined;

function showOpenError(error: unknown) {
  console.error('Could not open the document.', error);
  if (isReady) return;

  status.value = 'Could not open the document. Reload to try again.';
  saveButton.disabled = true;
}

try {
  const response = await fetch(endpoint);
  if (!response.ok) throw new Error(`Could not load the document: ${response.status}`);

  const docx = new Blob([await response.arrayBuffer()], { type: DOCX });
  superdoc = new SuperDoc({
    selector: '#editor',
    document: docx,
    onReady: () => {
      isReady = true;
      status.value = 'Ready';
      saveButton.disabled = false;
    },
    onEditorUpdate: () => {
      editRevision += 1;
      status.value = 'Unsaved changes';
    },
    onContentError: ({ error }) => showOpenError(error),
    onException: ({ error }) => showOpenError(error),
  });
} catch (error) {
  showOpenError(error);
}

saveButton.addEventListener('click', async () => {
  if (!superdoc || !isReady) return;

  const savedRevision = editRevision;
  saveButton.disabled = true;
  status.value = 'Saving…';

  try {
    const editedDocx = await superdoc.export({
      exportType: ['docx'],
      triggerDownload: false,
    });
    if (!(editedDocx instanceof Blob)) throw new Error('Expected one DOCX file.');

    const saveResponse = await fetch(endpoint, {
      method: 'PUT',
      headers: { 'content-type': DOCX },
      body: editedDocx,
    });
    if (!saveResponse.ok) throw new Error(`Could not save the document: ${saveResponse.status}`);
    status.value = editRevision === savedRevision ? 'Saved' : 'Unsaved changes';
  } catch (error) {
    status.value = 'Save failed. Try again.';
    console.error('Could not confirm the document was saved.', error);
  } finally {
    saveButton.disabled = false;
  }
});

window.addEventListener('beforeunload', () => superdoc?.destroy());

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const endpoint = '/api/documents/sample';
const docxType = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const editRevisionRef = useRef(0);
  const savingRef = useRef(false);
  const [document, setDocument] = useState<Blob>();
  const [loadError, setLoadError] = useState(false);
  const [ready, setReady] = useState(false);
  const [saving, setSaving] = useState(false);
  const [saveStatus, setSaveStatus] = useState('');

  useEffect(() => {
    const controller = new AbortController();

    void fetch(endpoint, { signal: controller.signal })
      .then(async (response) => {
        if (!response.ok) throw new Error(`Could not load the document: ${response.status}`);
        setDocument(new Blob([await response.arrayBuffer()], { type: docxType }));
      })
      .catch((error: unknown) => {
        if (!controller.signal.aborted) {
          setLoadError(true);
          console.error(error);
        }
      });

    return () => controller.abort();
  }, []);

  function showOpenError({ error }: { error: unknown }) {
    console.error('Could not open the document.', error);
    setReady(false);
    setLoadError(true);
  }

  async function saveDocument() {
    if (savingRef.current) return;

    const superdoc = editorRef.current?.getInstance();
    if (!superdoc) return;

    const savedRevision = editRevisionRef.current;
    savingRef.current = true;
    setSaving(true);
    setSaveStatus('Saving…');
    try {
      const editedDocx = await superdoc.export({
        exportType: ['docx'],
        triggerDownload: false,
      });
      if (!(editedDocx instanceof Blob)) throw new Error('Expected one DOCX file.');

      const response = await fetch(endpoint, {
        method: 'PUT',
        headers: { 'content-type': docxType },
        body: editedDocx,
      });
      if (!response.ok) throw new Error(`Could not save the document: ${response.status}`);
      setSaveStatus(editRevisionRef.current === savedRevision ? 'Saved' : 'Unsaved changes');
    } catch (error) {
      setSaveStatus('Save failed. Try again.');
      console.error('Could not confirm the document was saved.', error);
    } finally {
      savingRef.current = false;
      setSaving(false);
    }
  }

  if (loadError) return <p>Could not open the document. Reload to try again.</p>;
  if (!document) return <p>Opening document…</p>;

  return (
    <>
      <button disabled={!ready || saving} onClick={() => void saveDocument()} type='button'>
        Save DOCX
      </button>
      <output aria-live='polite'>{saveStatus}</output>
      <SuperDocEditor
        document={document}
        onContentError={showOpenError}
        onEditorUpdate={() => {
          editRevisionRef.current += 1;
          setSaveStatus('Unsaved changes');
        }}
        onException={showOpenError}
        onReady={() => setReady(true)}
        ref={editorRef}
      />
    </>
  );
}

```


Both examples:

* fetch the DOCX before mounting the Editor;
* enable saving after `onReady`;
* call `export({ triggerDownload: false })` to receive the edited `Blob`;
* show **Saved** only after the `PUT` succeeds. Edits made during that request remain unsaved.

The revision counter tracks local edits only. This is manual saving, not autosave or protection against another user
overwriting the file.

## Use another source or destination [#use-another-source-or-destination]

| Task                           | Use                                                        |
| ------------------------------ | ---------------------------------------------------------- |
| Open a public or signed URL    | `document: url`                                            |
| Open a file selected by a user | `document: file`                                           |
| Switch the mounted Editor      | `await superdoc.replaceFile(nextDocx)`                     |
| Download instead of saving     | `await superdoc.export({ exportedName: 'sample-edited' })` |

Fetch the file yourself and pass a `Blob` when the request needs custom headers.

### Preview: check a document replacement [#preview-check-a-document-replacement]

`replaceDocument()` is a source-preview API, not part of the published Quickstart release yet.
It keeps the mounted Editor and reports whether the requested document opened. `replaceFile()` remains available
with its existing raw return value.

After fetching the next DOCX as a `Blob`, use the ready `superdoc` instance from your application:

```ts
async function switchDocument(nextDocx: Blob): Promise<void> {
  const result = await superdoc.replaceDocument(nextDocx);
  if (!result.ok) {
    throw new Error(result.detail ?? result.reason ?? 'Could not open the next document.');
  }
}
```

Save or discard current edits before switching. Disable document actions while awaiting this function and handle
rejections in your application's error UI. Update the active document name only after it succeeds.

Do not use `onReady` to decide whether a replacement succeeded: recovery can make the previous document ready again.
A failed replacement does not guarantee that the previous document survived. Custom controls can call
`superdoc.ui.document.replaceDocument(nextDocx)` for the same typed result.

## Verify the round trip [#verify-the-round-trip]

Change the effective date from `September 1, 2026` to `October 1, 2026`. Select **Save DOCX**, then reload the page. The
new date should still be present.

Then make your endpoint reject a save before writing. Confirm **Save failed** appears and your edits remain available
to retry. A network failure can happen after the server stores the file, so an error alone does not prove nothing was
saved.

## Choose your interface [#choose-your-interface]

[Choose your interface](/editor/who-renders-the-ui) to keep SuperDoc's built-in controls or replace the ones your
application needs to own. Loading and saving stay the same.

For more storage options, see [Version history](/editor/version-history) and [Export options](/editor/export-options).


---

# Tune performance for large documents

> Keep page rendering responsive, choose a layout, and measure representative DOCX workflows.



SuperDoc virtualizes paginated documents by default. Keep that baseline until measurements from representative DOCX files show a specific scrolling, memory, loading, or worker-startup problem.

## Tune the page window deliberately [#tune-the-page-window-deliberately]

The default paginated window is five pages with one overscan page. Set it explicitly only when comparing a measured alternative:

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/large-contract.docx',
  layoutEngineOptions: {
    virtualization: {
      enabled: true,
      window: 5,
      overscan: 1,
    },
  },
  onPaginationUpdate: ({ totalPages }) => {
    pageCount.textContent = String(totalPages);
  },
});
```

A larger window can reduce repaints during fast scrolling while keeping more pages mounted. A smaller window reduces mounted work but can make navigation less smooth. Change one value at a time and measure on the devices and documents the product supports.

## Choose print or web layout [#choose-print-or-web-layout]

Paginated print layout preserves page boundaries and uses page virtualization. Web layout reflows semantic content to the container and does not provide headers, footers, rulers, or page-count updates.

Use `viewOptions: { layout: 'web' }` with `layoutEngineOptions: { flowMode: 'semantic' }` for the continuous surface. [Build a responsive Editor layout](/editor/built-in-ui/responsive-layout) compares the two layouts and their host sizing requirements.

## Control worker startup [#control-worker-startup]

Keep the default 30-second `workerStartupTimeoutMs` unless measurements show that the worker bundle needs more time to download or evaluate. Use `workerUrls` when the application must serve the document, collaboration, and review-index module workers from explicit same-origin URLs.

Worker load errors fail immediately; increasing the timeout does not repair a missing file, blocked Content Security Policy, or invalid worker response. See [Secure integration](/editor/secure-integration) for the browser boundary.

## Measure the whole task [#measure-the-whole-task]

Test opening, first interaction, scrolling, editing, collaboration, and export with representative DOCX files. Record document size and page count with the result so a regression can be reproduced.

> **Verification target (success)**
>
> On the slowest supported device, open a representative large DOCX, scroll from start to end, edit text on distant
> pages, and export. No action should lose document state or leave controls permanently busy.



---

# Open and edit your first DOCX

> Install the browser Editor, open a sample DOCX, and export your first edit.



Open a sample document, change its effective date, and download the edited DOCX. This example runs in the browser
without a backend.

## 1. Create a project [#1-create-a-project]

With Node.js 22.12 or newer and pnpm installed, create a Vite project and install SuperDoc:

Choose Vanilla or React. Use the same framework for the remaining steps.

**Vanilla — `Terminal`**

```sh
pnpm create vite@latest superdoc-quickstart --template vanilla-ts
cd superdoc-quickstart
pnpm add superdoc

```

**React — `Terminal`**

```sh
pnpm create vite@latest superdoc-quickstart --template react-ts
cd superdoc-quickstart
pnpm add @superdoc/react

```


## 2. Add the sample document [#2-add-the-sample-document]

Download the sample into your project's `public` directory and rename it to `sample.docx`:

[Download the sample document](/fixtures/getting-started.docx): One-page statement of work · DOCX


Vite serves `public/sample.docx` at `/sample.docx`.

## 3. Prepare the page [#3-prepare-the-page]

Replace the generated files below. Vanilla mounts SuperDoc into `#editor`; the React wrapper creates that container
for you.

**Vanilla — `index.html`**

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SuperDoc vanilla quickstart</title>
  </head>
  <body>
    <button id="export-docx" type="button" disabled>Export DOCX</button>
    <div id="editor"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

```

**React — `src/main.tsx`**

```tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import './index.css';

const root = document.querySelector('#root');
if (!root) throw new Error('The React root is missing.');

createRoot(root).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

```


For React, also replace `src/index.css` so Vite's starter layout does not constrain the Editor:

```css
html,
body,
#root {
  min-height: 100%;
  margin: 0;
}

```

## 4. Open the document [#4-open-the-document]

Replace `src/main.ts` in Vanilla or `src/App.tsx` in React with the matching code below. It opens the document and enables
export when the Editor is ready:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const exportButton = document.querySelector<HTMLButtonElement>('#export-docx');

if (!exportButton) throw new Error('The export button is missing.');

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  onReady: () => {
    exportButton.disabled = false;
  },
  onContentError: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
  onException: ({ error }) => {
    console.error('SuperDoc could not open the document.', error);
  },
});

exportButton.addEventListener('click', async () => {
  exportButton.disabled = true;
  try {
    await superdoc.export({ exportType: ['docx'], exportedName: 'sample-edited' });
  } catch (error) {
    console.error('SuperDoc could not export the document.', error);
  } finally {
    exportButton.disabled = false;
  }
});

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

function reportDocumentError({ error }: { error: unknown }) {
  console.error('SuperDoc could not open the document.', error);
}

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const exportingRef = useRef(false);
  const [ready, setReady] = useState(false);
  const [exporting, setExporting] = useState(false);

  async function exportDocument() {
    if (exportingRef.current) return;
    exportingRef.current = true;
    setExporting(true);
    try {
      await editorRef.current?.getInstance()?.export({ exportType: ['docx'], exportedName: 'sample-edited' });
    } catch (error) {
      console.error('SuperDoc could not export the document.', error);
    } finally {
      exportingRef.current = false;
      setExporting(false);
    }
  }

  return (
    <main>
      <button disabled={!ready || exporting} onClick={() => void exportDocument()} type='button'>
        Export DOCX
      </button>
      <SuperDocEditor
        document='/sample.docx'
        onContentError={reportDocumentError}
        onException={reportDocumentError}
        onReady={() => setReady(true)}
        ref={editorRef}
      />
    </main>
  );
}

```


Run the project:

```bash
pnpm dev
```

Open the local URL printed in the terminal. You should see the statement of work. `onReady` enables **Export DOCX**
after the document opens, so the button cannot export before the Editor is ready.

If the document does not appear, check that `/sample.docx` opens at the same local address. The example also logs
document-opening errors to the browser console through `onContentError` and `onException`.

## 5. Make an edit and export [#5-make-an-edit-and-export]

Change the effective date from `September 1, 2026` to `October 1, 2026`. Then select **Export DOCX**. The browser
downloads `sample-edited.docx`.

Open `sample-edited.docx` in Word or another DOCX editor. Confirm that the effective date is `October 1, 2026` and that
the title, service list, milestone table, and signatures keep their formatting.

`export()` downloads a new file. It does not overwrite `public/sample.docx` or save changes to a server. Reloading this
example opens the original sample again.

The complete projects are available for [Vanilla](https://go.superdoc.dev/examples/vanilla) and
[React](https://go.superdoc.dev/examples/react).

## Continue to configuration [#continue-to-configuration]

[Configure the Editor](/editor/configuration) to add user information and choose a document mode. Keep this project,
including its export button and `/sample.docx`, for the next guide.


---

# Control a document review workflow

> Separate proposing edits, deciding changes, and saving the reviewed document.



Start with the [tracked-changes example](/editor/track-changes). Once people can propose and decide edits, your
application needs to decide which actions each person should have and when the result is saved.

## Separate the three responsibilities [#separate-the-three-responsibilities]

| Task             | Editor behavior                              | Application responsibility                |
| ---------------- | -------------------------------------------- | ----------------------------------------- |
| Propose an edit  | `suggesting` records changes with an author. | Supply the current user's identity.       |
| Accept or reject | Review controls decide existing proposals.   | Choose who may use those controls.        |
| Save the result  | Export produces the current DOCX.            | Authorize and persist the exported bytes. |

These tasks do not require collaboration or a custom UI. A person can export a proposal for another reviewer to open
later. Use [collaboration](/editor/collaboration) when they should work in the same shared document.

## Let a contributor propose without deciding [#let-a-contributor-propose-without-deciding]

Keep the Quickstart project and replace `src/review-options.ts` from the Track changes guide with:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  user: { name: 'Jordan Lee', email: 'jordan@example.com' },
  interaction: {
    trackedChanges: { allowDecisions: false },
  },
} satisfies Pick<Config, 'documentMode' | 'user' | 'interaction'>;
```

Keep spreading these options into the existing Vanilla configuration or React component. Make an edit: it should
become a proposal, but accept and reject should be unavailable. Comment actions have their own configuration.

For a reviewer who may decide changes, use `allowDecisions: true` when opening the document. Keep `suggesting` if the
reviewer's own edits should also become proposals. Switching to `editing` would make new edits direct; it does not
accept the proposals already present.

Your application chooses these settings from its verified permissions. Browser controls are not an authorization
boundary: protect document access and saving on your backend. A disabled button can also mean no change is selected or
the document is read-only.

## Report partial bulk decisions [#report-partial-bulk-decisions]

Accept All and Reject All can leave proposals undecided when `permissionResolver` allows only some decisions. Use
`onTrackedChangesBulkDecision` to report what happened rather than announcing that every proposal was decided.

For Vanilla, add `<output id="review-status" aria-live="polite"></output>` to the page and create
`src/report-review-decisions.ts`:

```ts
import type { Config } from 'superdoc';

export const reportReviewDecisions: NonNullable<Config['onTrackedChangesBulkDecision']> = (result) => {
  const status = document.querySelector<HTMLOutputElement>('#review-status');
  if (!status) return;

  const action = result.decision === 'accept' ? 'Accepted' : 'Rejected';
  const remaining = result.permissionDeniedCount > 0 ? ` ${result.permissionDeniedCount} left undecided.` : '';
  status.value = `${action} ${result.successfulCount} changes.${remaining}`;
};

```

Import `reportReviewDecisions` into `src/main.ts` and set `onTrackedChangesBulkDecision: reportReviewDecisions` in the
existing configuration. In React, use the same callback payload to update status state.

The payload contains `documentId`, `decision`, `requestedCount`, `successfulCount`, and `permissionDeniedCount`.
`requestedCount` equals `successfulCount + permissionDeniedCount`. These counts describe permission-filtered decisions,
not a save confirmation. The same payload is available through the `tracked-changes:bulk-decision` event.

## Hand off the reviewed document [#hand-off-the-reviewed-document]

Decide the intended proposals, then export through your existing [load and save flow](/editor/load-and-save-documents).
If your workflow requires all proposals to be decided, inspect the remaining changes before calling the document final.
Otherwise, tell the next reviewer that undecided proposals remain.

Reopen the exported file and check that accepted text remains, rejected edits are gone, and any undecided proposals
are still available. A clean-looking `final` view only hides markup; it does not finish the review. Report “Saved” only
after your storage flow confirms the write.

Use [Document API tracked changes](/document-api/tracked-changes) to inspect or decide proposals in code. Use the
[custom review panel](/editor/custom-ui/tracked-changes) when your application needs to own the review queue and controls.


---

# Secure browser document workflows

> Define trusted boundaries for document access, identity, persistence, integrations, and browser policy.



SuperDoc runs document editing in the browser. That improves data locality, but it does not make every integration private or make client code a trusted authorization boundary.

## Identify every data boundary [#identify-every-data-boundary]

* A URL document is fetched by the browser from its origin.
* A local `File` or `Blob` stays in browser memory until application code sends or persists it.
* Exported bytes remain local unless downloaded, uploaded, cached, or passed to another API.
* Collaboration providers transmit document updates and awareness data.
* Network proofing, AI, telemetry, logging, and upload handlers may transmit document content or metadata.

Publish this behavior in product privacy language. Minimize data, retention, and logs. Never log document bodies, clauses, comment text, credentials, signed URLs, or mutation payloads by default.

## Keep trusted decisions on trusted services [#keep-trusted-decisions-on-trusted-services]

Document mode, disabled buttons, permission resolvers, read-only comments, and hidden review controls guide normal browser interaction. They do not enforce access against a user who controls the browser. Authenticate document requests and enforce read, write, export, collaboration, and agent approval policy on trusted services.

Treat names and emails supplied in `user` as display identity unless they came from an authenticated application session. Validate uploaded DOCX files, set size and timeout limits, and isolate sensitive processing where your threat model requires it.

## Configure the browser boundary [#configure-the-browser-boundary]

Check [Telemetry](/editor/telemetry) separately: it is enabled by default, and its destination and metadata are
configuration decisions. The [Editor license](/editor/license) is client-visible identity, not an access credential.

Use HTTPS, restrictive CORS, and a Content Security Policy that permits only the scripts, workers, connections, images, and fonts your deployment needs. Avoid unversioned third-party runtime dependencies, and decide whether Editor assets are self-hosted before production.

## Pass a nonce to runtime styles [#pass-a-nonce-to-runtime-styles]

Leave `cspNonce` unset unless the page's CSP requires a nonce for `<style>` elements. SuperDoc creates layout and caret styles at runtime. The browser blocks those styles when their nonce does not match the page's policy.

Generate a nonce for each HTML response. Include it in the response policy and pass the same value to every SuperDoc Editor mounted in that browser document, including remounts. The relevant policy directives look like this:

```http
Content-Security-Policy: style-src-elem 'self' 'nonce-{response-nonce}'; style-src-attr 'unsafe-inline'
```

Pass the server-provided value when you create the Editor:

```ts
function createEditor(file: File, responseNonce: string) {
  return new SuperDoc({
    selector: '#editor',
    document: file,
    cspNonce: responseNonce,
  });
}
```

`cspNonce` applies only to SuperDoc's runtime `<style>` elements. It does not configure CSP, authorize scripts or workers, or apply to styles created by your application. SuperDoc uses inline style attributes for document layout, so account for them in `style-src-attr`. For a custom theme, use [`buildTheme()`](/editor/theming) and inject its CSS with the same nonce.

In the deployed application, confirm that the browser reports no `style-src` violations and that SuperDoc runtime `<style>` elements carry the response nonce.


---

# Configure telemetry

> Make the browser Editor telemetry behavior explicit.




Telemetry is enabled by default. The browser Editor sends one document-open event when each DOCX becomes ready. Configure it when you create the Editor. Set its [license identity](/editor/license) separately.

Each request body uses this structure:

```json
{
  "superdocVersion": "2.10.0",
  "browserInfo": {
    "userAgent": "Mozilla/5.0 ...",
    "currentUrl": "https://app.example.com",
    "hostname": "app.example.com",
    "screenSize": { "width": 1440, "height": 900 }
  },
  "metadata": { "application": "contract-review" },
  "events": [
    {
      "timestamp": "2026-08-29T12:00:00.000Z",
      "documentId": "document-123",
      "documentCreatedAt": "2026-08-01T09:30:00.000Z"
    }
  ]
}
```

`superdocVersion`, `browserInfo`, and optional `metadata` are request-envelope fields. Each item in `events` contains only `timestamp`, `documentId`, and `documentCreatedAt`. `browserInfo.currentUrl` contains the page origin. The payload does not include the page path, query string, fragment, or document content.

## Choose telemetry behavior [#choose-telemetry-behavior]

Disable telemetry explicitly when the deployment must not initialize the telemetry integration:

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  telemetry: { enabled: false },
});
```

When telemetry is enabled, `endpoint` selects the destination and `metadata` adds application-defined context:

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  telemetry: {
    enabled: true,
    endpoint: 'https://telemetry.example.com/v1/events',
    metadata: {
      application: 'contract-review',
      environment: 'production',
    },
  },
});
```

The Editor serializes `metadata` into the request body. Do not include document text, comments, personal data, credentials, signed URLs, or other sensitive values. Allow the selected endpoint in `connect-src`. For a cross-origin endpoint, allow the Editor page's origin, the `POST` method, and the `Content-Type` and `X-License-Key` request headers in its CORS policy.

> **Verification target (success)**
>
> Inspect browser network requests in the deployed environment. Confirm that disabled telemetry sends no telemetry
> requests, or that enabled telemetry reaches only the approved endpoint with approved metadata.


Continue with [Secure integration](/editor/secure-integration) to review every document and metadata boundary.


---

# Theme the Editor UI

> Apply product colors to SuperDoc UI, then override one component when the semantic theme is not enough.



Use `createTheme()` to turn a small set of product tokens into SuperDoc CSS variables. Apply the returned class to
`<html>` so toolbars, menus, and surfaces mounted under `document.body` inherit the same theme.

## Try a theme [#try-a-theme]

Pick a color or paste a hex value, then open the dialog. Turn on **Toolbar override** to see when a
component-specific variable is useful.

> **Live example: theme the Editor UI**
>
> Change the semantic action, surface, text, border, or radius value and the real Editor updates. The dialog inherits the same theme because the generated class is applied to `<html>`. Turning on Toolbar override adds `--sd-ui-toolbar-bg` after the semantic values. The generated `ThemeConfig` code updates with each choice.


The DOCX content and formatting do not change. These tokens style the Editor UI around the document.

## Start with semantic tokens [#start-with-semantic-tokens]

Keep the Editor you built in the [Quickstart](/editor/quickstart). In that Vite project, create `src/theme.ts`:

```ts
import { createTheme } from 'superdoc';
import 'superdoc/style.css';

type ThemeConfig = Parameters<typeof createTheme>[0];

const productTheme = {
  name: 'product',
  colors: {
    action: '#4f46e5',
    actionHover: '#4338ca',
    bg: '#f8fafc',
    text: '#1e293b',
    border: '#cbd5e1',
  },
  radius: '8px',
  // `colors.bg` also feeds `--sd-layout-page-bg`, which paints the document page. Pin the
  // page so a dark UI surface does not darken pages whose DOCX sets no background.
  vars: { '--sd-layout-page-bg': '#ffffff' },
} satisfies ThemeConfig;

const themeClass = createTheme(productTheme);
document.documentElement.classList.add(themeClass);

```

Import it once from your entry file: `src/main.ts` in Vanilla or `src/main.tsx` in React.
React projects also need `pnpm add superdoc` for the theme helpers.

```ts
import './theme';
```

Keep your existing Editor setup and controls. The theme styles them without creating another instance.

The type derived from `createTheme` gives the object autocomplete and checks its shape. A stable `name` also makes the generated class
predictable—in this example, `sd-theme-product`.

Apply the class to `document.documentElement`, not only the Editor container. SuperDoc can mount dialogs, menus, and
other temporary surfaces under `document.body`, outside that container.

### Choose a token [#choose-a-token]

All theme fields are optional. Omitted values keep the stylesheet's defaults.

| Inside `colors`                           | Controls                                                       |
| ----------------------------------------- | -------------------------------------------------------------- |
| `action`, `actionHover`, `actionText`     | Actions, their hover state, and text on action-colored buttons |
| `bg`, `hoverBg`, `activeBg`, `disabledBg` | UI backgrounds and control states                              |
| `text`, `textMuted`, `textDisabled`       | Primary, secondary, and disabled UI text                       |
| `border`                                  | Shared UI borders                                              |

Use `radius` and `shadow` for shared corners and shadows. `name` identifies the theme; `vars` overrides individual CSS
variables. `font` sets the inherited UI font, but mounted Editor and toolbar roots can override it with
`uiDisplayFallbackFont`. It does not choose the fonts stored in the DOCX.

## Override one component [#override-one-component]

Set semantic values first so related controls stay consistent. Use `vars` only when one component needs to differ:

```ts
const productTheme = {
  name: 'product',
  colors: {
    action: '#4f46e5',
    bg: '#f8fafc',
    text: '#1e293b',
    border: '#cbd5e1',
  },
  vars: {
    '--sd-layout-page-bg': '#ffffff',
    '--sd-ui-toolbar-bg': '#eef2ff',
  },
} satisfies ThemeConfig;
```

These overrides take precedence over semantic values in the same theme. Use names from the
[published stylesheet](https://cdn.jsdelivr.net/npm/superdoc@2.12.0/dist/style.css): search for `--sd-ui-` and the component
name, such as `toolbar`. The stylesheet also shows which semantic token each component inherits.

In `superdoc@2.12.0`, `vars` accepts arbitrary string keys. TypeScript will not catch an unknown variable; confirm that
the component actually changes before keeping an override.

`--sd-layout-page-bg` defaults to the theme's `bg`, which paints the document page as well as the Editor surface. Pin it
whenever `bg` is not near-white, or pages without an explicit DOCX background follow your UI color while their text does
not.

## Control style injection [#control-style-injection]

`createTheme()` injects a `<style>` element and returns its class name. For server rendering or a strict Content
Security Policy, use `buildTheme()` to receive `{ className, css }`, then pass the CSS through your application's
stylesheet or nonce-aware style pipeline. See [Secure integration](/editor/secure-integration) for the related CSP
requirements.

Emit that CSS after `superdoc/style.css`. The generated `.sd-theme-*` rule and the package defaults under `:root` have
the same specificity, so whichever loads last wins — a theme emitted first is silently replaced by the defaults.
`createTheme()` is unaffected, because it appends its `<style>` element to `document.head`.

## Verify the theme [#verify-the-theme]

Change the action color and open the dialog. The dialog action and active Editor controls should use the new color. The
toolbar background should change only when **Toolbar override** is on.

Themes style SuperDoc's own interface. They do not affect the fonts stored in the DOCX. Continue with
[Fonts](/editor/fonts) to see how each document font resolves and to provide licensed files for families the browser
cannot render.


---

# Review tracked changes

> Propose an edit, accept or reject it, and keep undecided changes in the saved DOCX.



Use tracked changes when an edit needs review before it becomes accepted text. Each proposal records what changed and
who changed it. Use [comments](/editor/comments) for a discussion that does not change the passage.

## Try the review flow [#try-the-review-flow]

Select the marked change from `30 days` to `60 days`, then use the built-in toolbar to accept or reject it. Reset the
sample to compare both decisions. Accept keeps `60 days`; Reject restores `30 days`.

> **Interactive editor: Decide a proposed edit**
>
> Sample: [open the fixture](/fixtures/tracked-review.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: select a marked proposal and use the built-in toolbar to accept or reject it. Reset the sample to compare both decisions.
>
> Local DOCX selection: disabled.


For the complete project, open the [review example](https://go.superdoc.dev/examples/document-modes?workflow=review).
Accept the existing proposal, make two more edits, reject one, and export with the other undecided. Reopen the DOCX to
check which text and proposals remain.

| Decision        | Result                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------- |
| Accept          | Keeps the proposed result and removes its revision mark.                                    |
| Reject          | Removes the proposed edit and its revision mark. For a deletion, the original text returns. |
| Leave undecided | Keeps the proposal available for another reviewer.                                          |

Both decisions change the open document. The demo does not save it to a server.

## Open the Editor for review [#open-the-editor-for-review]

Keep the project and export button from the [Quickstart](/editor/quickstart). Create `src/review-options.ts`:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
} satisfies Pick<Config, 'documentMode' | 'user'>;

```

Import `reviewOptions` into `src/main.ts` in Vanilla or `src/App.tsx` in React:

```ts
import { reviewOptions } from './review-options';
```

Add `...reviewOptions` inside your existing `new SuperDoc({ ... })` configuration, or add `{...reviewOptions}` to
the `SuperDocEditor` component. Keep `/sample.docx`, the ready/error handlers, and **Export DOCX**.

Replace the effective date in `/sample.docx`. In `suggesting` mode, the edit becomes a proposal attributed to Jordan Lee.
Your application supplies the signed-in user's identity instead of this example user.
You do not need to enable tracking separately. In `suggesting` mode, supported edits create tracked changes by default.

Select a proposed change to reveal its review actions. You can keep the built-in UI or use
[custom review controls](/editor/custom-ui/tracked-changes); the document workflow is the same.

## Save and reopen the review [#save-and-reopen-the-review]

Make three separate edits. Accept one, reject another, and leave the third undecided. Use **Export DOCX** in your project,
then open the exported file in Word or load it back into SuperDoc:

1. The accepted result should remain without a revision mark.
2. The rejected edit should be absent.
3. The undecided proposal and its author should remain available for review.

Use your normal [load and save flow](/editor/load-and-save-documents) to persist the exported bytes. Exporting does not
accept pending changes. Choosing not to export comments does not accept or reject revisions either.

## Choose the right mode [#choose-the-right-mode]

Use `suggesting` to record edits as proposals, `editing` for direct edits, and `viewing` to read without editing.
Switching to editing does not accept proposals already in the document.

For a read-only review, replace the contents of `src/review-options.ts` with:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'viewing',
  viewing: { trackedChanges: 'markup' },
} satisfies Pick<Config, 'documentMode' | 'viewing'>;
```

The display and the review decision are separate:

| `viewing.trackedChanges` | What the reader sees                                        |
| ------------------------ | ----------------------------------------------------------- |
| `original` (default)     | The text before the proposed edits, without revision marks. |
| `markup`                 | Proposed insertions and deletions with revision marks.      |
| `final`                  | The proposed result, without revision marks.                |

Viewing mode stays read-only in all three cases. Use the [document modes demo](/editor/document-modes#choose-how-tracked-changes-appear)
to compare them. A clean-looking final view is not an accepted document.

## Control review decisions [#control-review-decisions]

Use [Control a document review workflow](/editor/review-workflow) to let contributors propose without deciding,
configure reviewer actions, and hand off the saved document. Comment actions are configured separately.

Editor modes and client-side review controls are not an authorization boundary. Your application owns document access,
trusted identity, and permission to save. See [Configuration](/editor/configuration) for the full startup contract,
including replacement grouping and author colors.

## Choose how replacements are reviewed [#choose-how-replacements-are-reviewed]

Typing over selected text creates a deletion beside an insertion. By default, SuperDoc groups those parts into one
proposal. One Accept or Reject action decides the complete replacement.

Use separate replacement review when your workflow must decide the deletion and insertion independently:

```ts
import type { Config } from 'superdoc';

export const reviewOptions = {
  documentMode: 'suggesting',
  trackChanges: {
    replacementMode: 'separate',
  },
} satisfies Pick<Config, 'documentMode' | 'trackChanges'>;
```

Keep the default `'grouped'` mode when a replacement such as `30 days` to `60 days` should remain one decision. This
setting changes the review items and decisions exposed by the Editor. It does not change the accepted text.

## Keep review decisions explicit [#keep-review-decisions-explicit]

Use [Document API tracked changes](/document-api/tracked-changes) when code needs to list revisions, inspect a known
change, create a tracked edit, or decide changes by ID. Do not infer revision targets from rendered DOM attributes.

Use the [custom review panel](/editor/custom-ui/tracked-changes) when your application owns the queue and its controls.
It observes `superdoc.ui.trackChanges` rather than maintaining a second list of document revisions.

## Report permission-filtered bulk decisions [#report-permission-filtered-bulk-decisions]

Accept All and Reject All can leave changes undecided when `permissionResolver` allows only some decisions.
The [review workflow guide](/editor/review-workflow#report-partial-bulk-decisions) shows how to report those results
through `onTrackedChangesBulkDecision`, without confusing a review decision with a saved file.


---

# Add version history

> Keep each saved DOCX as an immutable version and restore one without deleting newer work.



Keep a saved DOCX you can return to without discarding newer work. SuperDoc exports and opens the files; your
application decides when to create a version and where to store it.

Autosave describes when saving happens. Version history describes which saved states you retain. Saving automatically
does not create a history unless your storage keeps those versions.

## Try saving and restoring [#try-saving-and-restoring]

Run the [version-history example](https://go.superdoc.dev/examples/version-history). It includes a document and the
controls needed for this walkthrough:

1. Choose **Save version** to keep Version 1.
2. Edit a sentence and save Version 2.
3. Choose **Restore version 1**. The earlier text returns as Version 3; Version 2 remains available.
4. Export the current DOCX, or restore Version 2 to return to the newer text.

This example stores real DOCX snapshots in browser memory. Reloading clears its history; it does not provide a server
or cross-tab conflict handling. Add those next using your [load and save flow](/editor/load-and-save-documents).

## Keep every saved version [#keep-every-saved-version]

For this history, each save creates a new snapshot instead of overwriting the previous file.

Suppose a document has two versions:

```text
Version 1 → Version 2 (current)
```

Restoring Version 1 should create Version 3 with the same document content. Version 2 remains available:

```text
Version 1 → Version 2 → Version 3 (restored from Version 1)
```

SuperDoc produces and opens the DOCX files. Your backend owns the version IDs, timestamps, authors, retention rules,
and current-version pointer.

## Add version endpoints [#add-version-endpoints]

Extend the document endpoint from the Load and save guide. These are application routes, not SuperDoc routes:

| Route                                         | Job                                               |
| --------------------------------------------- | ------------------------------------------------- |
| `GET /api/documents/sample`                   | Return the current DOCX                           |
| `POST /api/documents/sample/versions`         | Store a new immutable version and make it current |
| `GET /api/documents/sample/versions`          | List version metadata, newest first               |
| `GET /api/documents/sample/versions/:version` | Return one immutable DOCX snapshot                |

Record the creation time and author from the trusted backend. Do not accept either value from browser input.

Return the current version ID with the current DOCX, for example in an `x-version-id` response header. Return the new
`DocumentVersion` metadata from each successful save. Keep that ID as the base for the next save or restore.

Send the current version ID with each save. The backend must compare it with the current pointer in the same operation
that makes the new version current. Return `409 Conflict` if another tab or user saved first. Validate every supplied
version ID against this document.

## Save, list, and restore [#save-list-and-restore]

The following helper uses the running Editor from the Load and save guide:

```ts
import { DOCX, type SuperDoc } from 'superdoc';

const documentEndpoint = '/api/documents/sample';
const versionsEndpoint = `${documentEndpoint}/versions`;

export type DocumentVersion = {
  id: string;
  createdAt: string;
  createdBy: string;
  restoredFromVersionId?: string;
};

export async function listVersions(): Promise<DocumentVersion[]> {
  const response = await fetch(versionsEndpoint);
  if (!response.ok) throw new Error(`Could not list versions: ${response.status}`);

  return response.json() as Promise<DocumentVersion[]>;
}

async function exportDocx(superdoc: SuperDoc): Promise<Blob> {
  const docx = await superdoc.export({
    exportType: ['docx'],
    triggerDownload: false,
  });
  if (!(docx instanceof Blob)) throw new Error('Expected one DOCX file.');

  return docx;
}

export async function saveVersion(
  superdoc: SuperDoc,
  baseVersionId: string,
  restoredFromVersionId?: string,
): Promise<DocumentVersion> {
  const docx = await exportDocx(superdoc);

  const response = await fetch(versionsEndpoint, {
    method: 'POST',
    headers: {
      'content-type': DOCX,
      'x-base-version-id': baseVersionId,
      ...(restoredFromVersionId ? { 'x-restored-from-version-id': restoredFromVersionId } : {}),
    },
    body: docx,
  });
  if (response.status === 409) throw new Error('A newer version exists. Reload before saving.');
  if (!response.ok) throw new Error(`Could not save the version: ${response.status}`);

  return response.json() as Promise<DocumentVersion>;
}

async function openDocument(superdoc: SuperDoc, docx: Blob): Promise<void> {
  const result = await superdoc.replaceFile(docx);
  const state = result && typeof result === 'object' ? ((result as { state?: unknown }).state ?? null) : null;
  if (state !== null && state !== 'review-ready' && state !== 'editing-ready') {
    throw new Error('SuperDoc could not open the DOCX file.');
  }
}

export async function restoreVersion(
  superdoc: SuperDoc,
  versionId: string,
  baseVersionId: string,
): Promise<DocumentVersion> {
  const activeDocx = await exportDocx(superdoc);
  const response = await fetch(`${versionsEndpoint}/${encodeURIComponent(versionId)}`);
  if (!response.ok) throw new Error(`Could not restore the version: ${response.status}`);

  const docx = new Blob([await response.arrayBuffer()], { type: DOCX });

  try {
    await openDocument(superdoc, docx);
    return await saveVersion(superdoc, baseVersionId, versionId);
  } catch (error) {
    const rollbackDocx = await fetch(documentEndpoint)
      .then(async (current) => (current.ok ? new Blob([await current.arrayBuffer()], { type: DOCX }) : activeDocx))
      .catch(() => activeDocx);
    await openDocument(superdoc, rollbackDocx);
    throw error;
  }
}

```

In Vanilla, pass the `superdoc` instance you created earlier. In React, get that same instance from
`editorRef.current?.getInstance()`.

To restore a version, the helper opens its snapshot first and then saves it as a new version. Bytes the Editor cannot
open never become current. If the save is rejected, it tries to reload the backend's current document. If that request
fails, it attempts to restore the document that was open before the attempt. Recovery can fail too; show the error and
require a successful reload before allowing another version action.

Refresh the version list after every save or restore. Disable version actions while a request is running.
Before calling `restoreVersion`, also prevent editing: set `inert` on a wrapper containing the Editor and its toolbar,
and pause application-driven document mutations. Keep that lock through saving and recovery. Otherwise, recovery can
discard edits made while the restore request was pending. Remove the lock after a successful restore; on failure,
show the error outside the inert wrapper and require a successful reload before enabling editing and version actions.
The helper does not manage this application UI lock. The backend version check handles saves from other tabs and users.

## Verify the history [#verify-the-history]

Save Version 1, edit the statement of work, and save Version 2. Restore Version 1. The backend should create Version 3,
the Editor should show the Version 1 text, and Version 2 should remain in the list. Reload the page to confirm Version 3
is current.

Open a second tab before saving Version 2. After restoring Version 1 as Version 3, a save from that stale tab should
return `409` and leave Version 3 current.

## Restore shared documents separately [#restore-shared-documents-separately]

These helpers restore a standalone Editor, not a live collaboration room. A DOCX snapshot is not the room's saved
Yjs state. In collaboration, replacing the file can replace shared content for everyone. Do not treat a local
Restore button as a coordinated room-recovery policy.

Your application needs a server-owned recovery policy for connected editors and writes arriving during recovery.
See [Save and restore a room](/editor/collaboration/save-and-restore-a-room) for room persistence. It demonstrates
reopening saved state, not rolling a live room back to an earlier version.

Use [Secure integration](/editor/secure-integration) to protect the version routes. Use
[Export options](/editor/export-options) when saved versions need a specific comments or tracked-changes policy.


---

# Choose your interface

> Decide who renders the controls around the DOCX canvas.



Keep the document loading and saving you already built. Now choose who renders the controls around it. SuperDoc
continues to render the document and handle editing in all three approaches.

## Compare the approaches [#compare-the-approaches]

Switch between Built-in, Hybrid, and Fully custom in the diagram. The toolbar and comments panel change ownership;
the document stays with SuperDoc.

> **Interactive comparison: who renders the interface**
>
> SuperDoc renders the DOCX canvas in every approach. The configuration changes who renders the controls around it.

| Approach | Configuration | Who renders the controls |
| --- | --- | --- |
| Built-in | `ui: { toolbar: { container: '#toolbar' } }` | SuperDoc |
| Hybrid | `ui: { toolbar: { container: '#toolbar' }, comments: false }` | SuperDoc renders the toolbar; your application renders comments through `superdoc.ui.comments` |
| Fully custom | `ui: false` | Your application, through `superdoc.ui` |


Start with the built-in interface and configure it for your product. Use a hybrid interface when you need to own one
part, such as a comments panel. Choose fully custom only when your application needs to render all the controls.

## What the configuration changes [#what-the-configuration-changes]

`Config.ui` controls which built-in surfaces render. A partial `ui` object changes only the surfaces it names. Hiding a
surface does not remove its document data or public API.

For example, `ui: { comments: false }` hides the built-in comments UI. It does not create a replacement panel; your
application renders that panel and connects it to the comments API.

`SuperDocEditor` creates a built-in toolbar container by default. Vanilla integrations add their own container when they
want the toolbar.

## Continue with your choice [#continue-with-your-choice]

* [Use the built-in UI](/editor/built-in-ui/overview) to configure SuperDoc's toolbar and review surfaces.
* [Build a custom UI](/editor/custom-ui/overview) to connect application-owned controls to `superdoc.ui`.


---

# SuperDoc DOCX Engine Proprietary License

> Read the proprietary license that governs access to and use of the DOCX Engine.



**Version 2026-07-14**

Company: Harbour Enterprises, Inc., d/b/a SuperDoc, 1735A Union Street, San Francisco, CA 94123 (“Company”)

Canonical URL: [https://docs.superdoc.dev/resources/docx-engine-license](/resources/docx-engine-license)

This SuperDoc DOCX Engine Proprietary License (this “License”) governs access to and use of the proprietary package published as @superdoc/docx-engine, together with any related code, documentation, examples, tests, artifacts, and materials. It is entered into between Harbour Enterprises, Inc., d/b/a SuperDoc (“Company”), and the customer or user that accepts it (“Customer”).

This License operates in two ways: (a) where Customer and Company have entered into a SuperDoc Master Services Agreement, SuperDoc Commercial License Agreement, order form, or other written agreement governing SuperDoc or DOCX Engine (the “Base Agreement”), this License supplements and forms part of that Base Agreement with respect to DOCX Engine; and (b) where no Base Agreement exists, this License is a standalone, binding proprietary license governing Customer’s access to and use of DOCX Engine. Capitalized terms used but not defined here have the meanings given in the Base Agreement, if any.

Acceptance by use. By installing, importing, executing, copying, or otherwise using DOCX Engine — including by installing any software package that incorporates DOCX Engine as a dependency — Customer agrees to be bound by this License. This License is a conspicuous license included with the DOCX Engine package; no click-through or signature is required for it to be binding. If Customer does not agree, Customer must not install, access, or use DOCX Engine.

Existing customers; no separate acceptance required. If, at the time of access, Customer has a Base Agreement in effect that grants Customer the right to use DOCX Engine (including where the Base Agreement’s defined “Services,” “Software,” or licensed scope encompasses DOCX Engine), then the Base Agreement governs Customer’s use of DOCX Engine, this License’s acceptance requirement is deemed satisfied, and no separate or further acceptance of this License is required as a condition of access. In that case, this License applies only to supplement the Base Agreement to the extent set forth in Section 6, and any conspicuous notice or in-package license is provided for the convenience of users who lack a Base Agreement and does not impose additional terms on Customer.

Open-source notice. SuperDoc’s open-source code is available under AGPLv3. DOCX Engine, published as @superdoc/docx-engine, is proprietary software and is not open source. The open-source SuperDoc editor and the proprietary DOCX Engine are separately licensed components. Use of SuperDoc’s open-source code remains governed by the applicable open-source license. Use of DOCX Engine is governed by this DOCX Engine Proprietary License. Nothing in the open-source license grants any right to reverse engineer, deobfuscate, reconstruct, clone, or reimplement DOCX Engine, and nothing in this License modifies Customer’s rights or obligations under the AGPLv3 license for SuperDoc’s open-source code.

## 1. Definitions [#1-definitions]

1.1 “DOCX Engine” means the proprietary DOCX engine software package published as @superdoc/docx-engine, including any updates, upgrades, patches, and successor versions provided by or on behalf of Company.

1.2 “DOCX Engine Materials” means DOCX Engine and any related code, object code, minified, compiled, or obfuscated code, source maps, if ever provided, APIs, SDKs, libraries, license keys, examples, sample code, documentation, install instructions, tests, demos, package artifacts, and other materials provided by or on behalf of Company in connection with DOCX Engine.

1.3 “Derived Engine Information” means non-public behavior, outputs, performance characteristics, benchmarks, analyses, implementation details, test results, or other technical information derived from access to the DOCX Engine Materials, including information derived by inspecting, testing, benchmarking, prompting, analyzing, or running DOCX Engine for the purpose of understanding its non-public implementation, reconstructing its functionality, or creating a substitute or substantially similar implementation. For clarity, DOCX Engine Materials and Derived Engine Information do not include Customer Data, Customer-authored applications, Customer-authored integrations, or ordinary documents, files, content, or outputs created by Customer or its end users through authorized use of DOCX Engine, except to the extent such materials reveal non-public implementation details of DOCX Engine or are used to reverse engineer, benchmark, validate, train, or create a substitute or substantially similar implementation.

1.4 “Competing Product” means any document editor, document editing or rich-text SDK, collaborative editing system, document rendering or conversion engine, diffing tool, document export system, hosted document infrastructure product, or other product or service that competes with or is substantially similar to SuperDoc or any DOCX Engine Materials.

1.5 “Authorized Use” means installing and using DOCX Engine solely as a dependency of SuperDoc, including with SuperDoc’s AGPL-licensed open-source code, for evaluation, development, testing, and other use permitted under the AGPLv3 license applicable to SuperDoc’s open-source code, in each case solely in compliance with this DOCX Engine Proprietary License. For Customers with a Base Agreement, order form, selected plan, or other written agreement with Company, Authorized Use also includes any production or commercial use expressly permitted by that agreement, subject to the licensed scope, plan limits, permitted document experience(s), usage limits, and term stated therein.

1.6 “Prohibited AI Use” means uploading, submitting, disclosing, ingesting, indexing, embedding, summarizing, translating, deobfuscating, analyzing, or otherwise processing the DOCX Engine Materials, or any behavior, outputs, performance characteristics, benchmarks, analyses, implementation details, or test results derived from access to the DOCX Engine Materials, using any artificial intelligence, machine learning, code-generation, code-analysis, model-training, model-evaluation, or automated reverse-engineering system, including any large language model (LLM) or other generative AI system, for the purpose of reconstructing source code, understanding non-public implementation details, creating a substitute or substantially similar implementation, including any clean-room, black-box, or behavior-based reimplementation, or developing, training, fine-tuning, prompting, benchmarking, validating, improving, or assisting a Competing Product.

## 2. License Grant [#2-license-grant]

2.1 Subject to Customer’s continued compliance with this DOCX Engine Proprietary License, the Base Agreement, if any, and payment of all applicable fees, if any, Company grants Customer a limited, non-exclusive, non-transferable, non-sublicensable license to install and use DOCX Engine solely as a dependency of SuperDoc, including with SuperDoc’s AGPL-licensed open-source code, and solely for Authorized Use.

If Customer has a Base Agreement, order form, selected plan, or other written agreement with Company that expressly grants rights to use DOCX Engine, Customer’s use is limited to the licensed scope, plan limits, permitted document experience(s), usage limits, and term stated in that agreement.

If Customer does not have a Base Agreement, Customer may install and use DOCX Engine solely as a dependency of SuperDoc, including with SuperDoc’s AGPL-licensed open-source code, for uses permitted under the AGPLv3 license applicable to SuperDoc’s open-source code, provided that Customer complies with this DOCX Engine Proprietary License.

For clarity, this License does not permit Customer to use DOCX Engine, DOCX Engine Materials, or Derived Engine Information to reverse engineer, reconstruct, deobfuscate, clone, reimplement, validate or benchmark the DOCX Engine, nor does this License permit Customer to use DOCX Engine, DOCX Engine Materials, or Derived Engine Information, including in connection with any AI tools, to train, improve, or assist any Competing Product or substitute implementation of the DOCX Engine.

2.2 Contractors and affiliates. Customer may permit its affiliates and contractors to use DOCX Engine solely for Customer’s internal benefit and solely within Customer’s licensed scope, provided that each such affiliate and contractor is bound by written obligations no less protective of Company than this License. Customer is fully responsible and liable for all acts and omissions of its affiliates, contractors, users, and representatives as if they were Customer’s own.

2.3 Self-hosting. DOCX Engine is self-hosted by Customer. Company does not host Customer’s production deployment and does not access Customer’s document contents from Customer’s production environment unless Customer voluntarily provides such information to Company for support, troubleshooting, implementation, or other assistance.

2.4 Reservation of rights. All rights not expressly granted in this License are reserved by Company. No right or license is granted by implication, estoppel, or otherwise.

## 3. Restrictions [#3-restrictions]

3.1 Customer will not, and will not permit its affiliates, contractors, users, or representatives to, directly or indirectly:

(a) Reverse engineer, deobfuscate, decompile, disassemble, decode, reconstruct source code from, reconstruct any source map of, or otherwise attempt to discover the source code, object code, underlying structure, ideas, know-how, algorithms, or non-public implementation details of the DOCX Engine Materials or Derived Engine Information, whether manually or with the assistance of any large language model (LLM) or other AI system, except to the limited extent, and only to the extent, such restriction is prohibited by non-waivable applicable law;

(b) Modify, translate, or create derivative works based on the DOCX Engine Materials, except to the extent expressly permitted by Company or authorized within DOCX Engine;

(c) Remove, alter, or obscure any license, copyright, or other proprietary notices, banners, or labels, or any hidden, embedded, or forensic markers, contained in or accompanying the DOCX Engine Materials;

(d) Redistribute, republish, mirror, resell, rent, lease, sublicense (except to contractors as permitted in Section 2.2), or otherwise make the DOCX Engine Materials available to any third party, or make any DOCX Engine package available as a standalone package;

(e) No cloning. Use the DOCX Engine Materials or Derived Engine Information to develop, train, prompt, benchmark, validate, improve, or assist any Competing Product, substitute implementation, or substantially similar implementation, including by means of any artificial intelligence, machine learning, or automated system. For clarity, building Customer-authored applications and integrations powered by DOCX Engine, including with AI or developer-assistance tools, is permitted within Authorized Use; using the DOCX Engine Materials or Derived Engine Information to reconstruct or substitute for DOCX Engine is not.

(f) No prohibited AI use; no clean-room cloning. Engage in any Prohibited AI Use, or use DOCX Engine behavior, outputs, examples, tests, documentation, DOCX Engine Materials, or Derived Engine Information as a specification to clone, substitute for, or otherwise reimplement DOCX Engine, whether by clean-room, black-box, or behavior-based methods or with the assistance of a large language model (LLM) or other AI system.

(g) Circumvent or attempt to circumvent any obfuscation, technical protection, marker, or license-enforcement measure in the DOCX Engine Materials;

(h) Use the DOCX Engine Materials outside the scope of the Authorized Use or the licensed scope, plan, or document experience(s) without Company’s prior written approval; or

(i) Accept this License using a false or misappropriated identity, or purport to accept it on behalf of an entity without authority to bind that entity.

3.2 Customer represents, covenants, and warrants that it will use the DOCX Engine Materials and Derived Engine Information only in compliance with this License, the Base Agreement, if any, and all applicable laws and regulations.

## 4. Ownership and Proprietary Rights [#4-ownership-and-proprietary-rights]

4.1 Company owns and retains all right, title, and interest in and to the DOCX Engine Materials, all improvements, enhancements, modifications, and derivative works thereof, and all intellectual property rights in any of the foregoing. Except for the limited license expressly granted in Section 2, no ownership interest or other right in the DOCX Engine Materials is transferred to Customer.

4.2 As between the parties, Customer owns all right, title, and interest in and to Customer Data, as defined in the Base Agreement. If no Base Agreement exists, “Customer Data” means documents, files, data, content, prompts, workflows, models, outputs, materials, and other information processed through DOCX Engine by Customer or its end users, or voluntarily provided by Customer to Company.

4.3 Feedback. If Customer provides Company with suggestions, feedback, or recommendations regarding the DOCX Engine Materials, Company may use and incorporate such feedback without restriction or obligation to Customer.

## 5. Confidentiality [#5-confidentiality]

5.1 The DOCX Engine Materials are proprietary to Company. Non-public information regarding the source code, non-public implementation details, architecture, roadmap, pricing, support, implementation, security, performance, benchmarks, test results, and operation of DOCX Engine constitutes Company’s Proprietary Information and Confidential Information. The confidentiality obligations of the Base Agreement, if any, apply to such information.

5.2 If no Base Agreement exists, Customer agrees (a) to take reasonable precautions to protect the DOCX Engine Materials and Company’s other Proprietary Information, and (b) not to use or disclose such information except as necessary to exercise its rights under this License. These obligations do not apply to information that Customer can document is or becomes generally available to the public without breach of this License, was rightfully known to Customer without restriction prior to receipt, was rightfully disclosed to Customer without restriction by a third party, or was independently developed without use of Company’s Proprietary Information, or to disclosures required by law.

## 6. Order of Precedence [#6-order-of-precedence]

6.1 This License supplements the Base Agreement with respect to DOCX Engine. In the event of a conflict between this License and the Base Agreement regarding DOCX Engine: (a) to the extent the Base Agreement expressly addresses the same subject matter and affords Company protections equal to or greater than those in this License, the Base Agreement controls; and (b) to the extent this License affords Company greater protection with respect to the DOCX Engine Materials — including the restrictions in Section 3 (reverse engineering, no cloning, prohibited AI use, and proprietary notices and markers), ownership in Section 4, and the remedies in Sections 9 and 10 — this License controls.

6.2 Where no Base Agreement exists, this License is the complete and exclusive agreement between the parties governing the DOCX Engine Materials and supersedes all prior or contemporaneous understandings relating to that subject matter.

6.3 Existing customers. For Customers with a Base Agreement that expressly grants rights to use DOCX Engine, this License supplements the Base Agreement only with respect to DOCX Engine. This License does not create additional fees or expand Customer’s licensed scope, plan limits, permitted document experience(s), usage limits, or term. To the extent Customer’s Base Agreement expressly addresses the same subject matter, Section 6.1 governs order of precedence.

## 7. Term and Termination [#7-term-and-termination]

7.1 This License takes effect upon Customer’s acceptance and continues for the term of the Base Agreement or the applicable order form or selected plan. Where no Base Agreement exists, this License continues until terminated in accordance with this Section 7.

7.2 Any breach or attempted breach of Section 3 involving reverse engineering, deobfuscation, source-code reconstruction of the DOCX Engine, Prohibited AI Use, clean-room or black-box cloning of the DOCX Engine, circumvention of technical protections, removal of proprietary notices or markers, or unauthorized redistribution of the DOCX Engine automatically and immediately terminates the license granted in Section 2. For other breaches of Authorized Use, licensed scope, plan limits, or document experience limits, Company may suspend or terminate Customer’s access to DOCX Engine if Customer does not cure the breach after notice. No cure period is required for any breach that is intentional, repeated, unlawful, likely to cause material harm, or reasonably likely to compromise the confidentiality, security, ownership, or proprietary status of the DOCX Engine Materials.

7.3 Upon termination or expiration, Customer’s license rights end, and Customer will cease all use of the DOCX Engine Materials, permanently delete or destroy all copies in its possession or control, and, upon Company’s request, certify such deletion or destruction in writing. Customer remains responsible for ensuring that any continued use of SuperDoc complies with the applicable open-source license or a separate commercial license.

7.4 Survival. Sections 1, 3, 4, 5, 6, 7.3, 8, 9, 10, and 11, and any accrued payment obligations, survive termination or expiration of this License.

## 8. Warranty Disclaimer [#8-warranty-disclaimer]

THE DOCX ENGINE MATERIALS ARE PROVIDED “AS IS,” AND COMPANY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. COMPANY DOES NOT WARRANT THAT THE DOCX ENGINE MATERIALS WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY RESULTS OBTAINED FROM THEIR USE WILL BE ACCURATE OR RELIABLE. CUSTOMER ACKNOWLEDGES THAT DOCX ENGINE IS SELF-HOSTED AND THAT CUSTOMER IS RESPONSIBLE FOR OPERATING ITS OWN DEPLOYMENT ENVIRONMENT, INFRASTRUCTURE, SYSTEMS, PROMPTS, MODELS, WORKFLOWS, AND ANY THIRD-PARTY AI SYSTEMS USED WITH DOCX ENGINE.

## 9. Limitation of Liability [#9-limitation-of-liability]

9.1 EXCEPT FOR A PARTY’S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT, IN NO EVENT WILL EITHER PARTY BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOST PROFITS, REVENUE, GOODWILL, OR DATA, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

9.2 EXCEPT FOR A PARTY’S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT, EACH PARTY’S AGGREGATE LIABILITY ARISING OUT OF OR RELATING TO THIS LICENSE SHALL NOT EXCEED THE FEES PAID OR PAYABLE BY CUSTOMER FOR DOCX ENGINE IN THE TWELVE (12) MONTHS IMMEDIATELY PRECEDING THE EVENT GIVING RISE TO LIABILITY; PROVIDED THAT EACH PARTY’S AGGREGATE LIABILITY FOR CLAIMS ARISING FROM ITS CONFIDENTIALITY OBLIGATIONS, DATA SECURITY OBLIGATIONS, OR INDEMNIFICATION OBLIGATIONS SHALL NOT EXCEED TWO TIMES (2X) THE FEES PAID OR PAYABLE BY CUSTOMER FOR DOCX ENGINE IN THE TWELVE (12) MONTHS IMMEDIATELY PRECEDING THE EVENT GIVING RISE TO LIABILITY. WHERE A BASE AGREEMENT EXISTS, THE LIABILITY PROVISIONS OF THE BASE AGREEMENT GOVERN ON AN AGGREGATE BASIS ACROSS THE BASE AGREEMENT AND THIS LICENSE, AND THIS SECTION 9 DOES NOT INCREASE EITHER PARTY’S CAP UNDER THE BASE AGREEMENT. IF CUSTOMER HAS NOT PAID AND DOES NOT OWE ANY FEES FOR DOCX ENGINE, COMPANY’S AGGREGATE LIABILITY ARISING OUT OF OR RELATING TO THIS LICENSE SHALL NOT EXCEED ONE HUNDRED DOLLARS ($100).

9.3 NOTWITHSTANDING THE FOREGOING, (A) CUSTOMER’S PAYMENT OBLIGATIONS SHALL NOT BE LIMITED BY SECTION 9.2; (B) CUSTOMER’S BREACH OF SECTION 3 OR USE OF THE DOCX ENGINE MATERIALS OUTSIDE THE LICENSED SCOPE SHALL NOT LIMIT COMPANY’S RIGHT TO SEEK PAYMENT OF APPLICABLE ADDITIONAL OR UPGRADE FEES, SUSPENSION, TERMINATION, OR INJUNCTIVE OR EQUITABLE RELIEF; AND (C) TO THE EXTENT THE PARTIES HAVE A BASE AGREEMENT, THIS SECTION 9 DOES NOT LIMIT EITHER PARTY’S INDEMNIFICATION OBLIGATIONS UNDER THE BASE AGREEMENT.

## 10. Equitable Relief [#10-equitable-relief]

10.1 Customer acknowledges that any breach or threatened breach of Section 3 (Restrictions), Section 4 (Ownership), or Section 5 (Confidentiality) would cause Company irreparable harm for which monetary damages would be an inadequate remedy. Accordingly, Company is entitled to seek injunctive and other equitable relief to prevent or restrain any such breach, without the necessity of posting a bond or proving actual damages, in addition to any other remedies available at law or in equity.

## 11. General [#11-general]

11.1 Governing law. This License is governed by the laws of the State of California, without regard to its conflict-of-laws provisions. The state and federal courts located in San Francisco, California will have exclusive jurisdiction over any dispute arising out of or relating to this License, and the parties consent to such jurisdiction and venue.

11.2 Assignment. This License is not assignable or transferable by Customer without Company’s prior written consent, except that either party may assign it in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of its assets, provided that the assignee agrees in writing to be bound and the assignment does not expand Customer’s licensed scope or permitted use of the DOCX Engine Materials.

11.3 Severability and waiver. If any provision of this License is found unenforceable, it will be limited or eliminated to the minimum extent necessary so that the remainder remains in full force and effect. No waiver or modification is effective unless set forth in a writing signed by both parties, except that Company may publish updated versions of the standalone DOCX Engine license at a stable URL, and Customer’s continued use of DOCX Engine after the effective date of an updated standalone version constitutes acceptance; for Customers under a Base Agreement, changes to this License require mutual written agreement.

11.4 Versioning and records. Company may maintain records of the version, effective date, and content hash of each published version of this License and of Customer’s acceptance. Such records are admissible as evidence of the terms accepted by Customer.

11.5 Entire agreement. This License, together with the Base Agreement (if any) and any applicable order form, is the complete and exclusive statement of the parties’ agreement regarding the DOCX Engine Materials and supersedes all prior and contemporaneous communications relating to that subject matter.

## Acceptance [#acceptance]

This License becomes binding on Customer when Customer (acting through a person with authority to bind it) installs, imports, executes, copies, or otherwise uses DOCX Engine, including by installing any software package that incorporates DOCX Engine as a dependency. The person acting for Customer represents that they are authorized to bind Customer, or that they are acting in an individual capacity and will not use DOCX Engine for any entity that has not accepted these terms. No click-through, order form, or handwritten or electronic signature is required for this License to be binding.

***

Copyright © 2026 Harbour Enterprises, Inc., d/b/a SuperDoc. All rights reserved.


---

# How SuperDoc works

> Understand how SuperDoc keeps OOXML as the document source across browser and headless workflows.





SuperDoc reads, renders, edits, and writes DOCX files through their OOXML parts. It does not convert a DOCX to HTML and reconstruct the file after editing. The browser Editor and supported headless clients use the same document engine and Document API contract.

## Try the browser Editor [#try-the-browser-editor]

Select the tracked change, then accept or reject it.

> **Interactive editor: Try SuperDoc in the browser**
>
> Sample: [open the fixture](/fixtures/tracked-changes.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: select a marked proposal and use the built-in toolbar to accept or reject it. Reset the sample to compare both decisions.
>
> Local DOCX selection: disabled.


## Follow the document through the engine [#follow-the-document-through-the-engine]

1. **Open.** The engine parses content, styles, relationships, media, headers, footers, and the other OOXML parts into editable document state.
2. **Render.** The layout engine paginates that state. The browser painter projects the resolved pages into DOM. The DOM is an output, not the document format.
3. **Edit.** Editor input and headless operations update document state. The Document API defines queries, targets, mutations, and receipts.
4. **Write.** Save and export write the changes back into the OOXML package instead of rebuilding a DOCX from HTML.

This is the no-conversion boundary: OOXML remains the source of document meaning from open through export.

## Choose an execution surface [#choose-an-execution-surface]

> **Diagram:** People, services, CI, and agents use different SuperDoc surfaces that share the Document API and DOCX engine.


| Caller        | Surface              | What the surface owns                                   | Start with                                              |
| ------------- | -------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Person        | Browser Editor       | Rendering, input, selection, navigation, and review UI  | [Editor overview](/editor)                              |
| Service or CI | Node.js, Python, CLI | Sessions, files, batches, retries, and process failures | [Agents & automation](/agents/overview)                 |
| Agent         | SDK agent tools      | Tool definitions, prompts, dispatch, and review handoff | [Build an agent](/agents/build/build-an-agent)          |
| Any code      | Document API         | Structured reads, mutations, receipts, and errors       | [Document API mental model](/document-api/mental-model) |

Headless code does not have a toolbar, viewport, DOM selection, or visual review surface. Choose the surface by who or what drives the document.

## Use one operation contract [#use-one-operation-contract]

The Document API is an operation contract, not another runtime. The Editor and supported headless clients expose the same operation names and data shapes.

| Need                   | Operation families                                                               |
| ---------------------- | -------------------------------------------------------------------------------- |
| Read and discover      | Queries, extraction, document info, Markdown, and HTML views                     |
| Edit and review        | Insert, replace, delete, format, comments, tracked changes, history, and diffing |
| Structure and media    | Sections, tables, headers, footers, page setup, images, and alternative text     |
| Word data and controls | Content controls, bookmarks, fields, footnotes, custom XML, and protection       |
| Produce output         | DOCX export and template application                                             |

Support can vary by runtime, document state, and mutation mode. Check `doc.capabilities()` before presenting an operation, then inspect its receipt or error. Use the [generated reference](/document-api/reference) for the complete operation and field inventory.


---

# Licensing

> Compare SuperDoc's open-source and commercial licensing options.



SuperDoc is available under dual licensing. Choose the license that matches how you distribute and operate your application.

## Open source [#open-source]

SuperDoc's open-source code is available under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html). Use the open-source license when your application can meet the AGPLv3 requirements.

## Commercial [#commercial]

Proprietary and commercial deployments are available under the [SuperDoc Commercial License](https://www.superdocportal.dev/superdoc-terms-of-service).

For licensing questions, email [q@superdoc.dev](mailto:q@superdoc.dev).

## Contributing [#contributing]

Contributions to the open-source project are welcome:

1. Check the [issue tracker](https://github.com/superdoc/docx-editor/issues) for open work.
2. Fork the repository and create a focused branch.
3. Follow the project's code and documentation guidelines.
4. Open a pull request that explains the reason for the change.

Read the [Contributing Guide](https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md) for the complete workflow.


---

# Package compatibility

> Understand how SuperDoc declares and changes npm peer dependency compatibility.



SuperDoc changes compatibility ranges when an integration or its tested support changes, not on a fixed schedule. The `peerDependencies` and `peerDependenciesMeta` fields in each published package are the machine-readable requirements for that release.

`@superdoc/react` also carries an exact `superdoc` peer that release automation updates when the adapter and core are published together. Applications should upgrade those coordinated releases as a pair. This version-only synchronization can occur more often than an authored compatibility-policy change.

## Why peer dependencies are different [#why-peer-dependencies-are-different]

A peer dependency is supplied by the application that installs SuperDoc. It lets SuperDoc and the application share a framework or integration runtime instead of installing unrelated copies. React, Yjs, PDF.js, and collaboration providers are examples of dependencies that can participate in this contract.

A regular dependency is selected as part of SuperDoc's package tree. Updating one can still affect bundle size, security review, or runtime behavior, but it does not normally require the application to provide a matching version.

## Required and optional peers [#required-and-optional-peers]

A required peer must be available at a version accepted by the published range. Package managers can warn or fail when the application cannot provide one.

An optional peer is not needed to install the package or use unrelated features. The application must provide a compatible version when it uses the integration that depends on that peer.

Inspect the requirements for the version you install:

```bash
npm view superdoc@latest peerDependencies peerDependenciesMeta
```

Framework adapters and other published `@superdoc/*` packages declare their own peer requirements in the same fields.

## How changes are released [#how-changes-are-released]

Authored peer dependency changes receive manual review in addition to automated package checks.

| Change                                                                   | Release policy              |
| ------------------------------------------------------------------------ | --------------------------- |
| Widen a tested range                                                     | Minor release               |
| Add an optional peer                                                     | Minor release               |
| Change a peer from required to optional                                  | Minor release               |
| Narrow a range or stop accepting a previously supported version          | Breaking release            |
| Add a required peer                                                      | Breaking release            |
| Change a peer from optional to required                                  | Breaking release            |
| Remove or replace a peer contract                                        | Breaking release            |
| Synchronize a release-managed exact peer to its coordinated core release | Coordinated package release |

Except for the coordinated version-only synchronization above, breaking peer changes require a major package release, release notes, and migration guidance. A security issue can require a faster compatibility change; when that happens, the release notes identify the affected versions and the required upgrade.

Before widening a range, validate the additional versions. Narrow a range only when SuperDoc can no longer support the removed versions safely.


---

# Trust & Security

> Review SuperDoc's SOC 2 controls, deployment model, data practices, infrastructure, and vulnerability disclosure program.



SuperDoc is SOC 2 Type II certified. Independent auditors verify security, privacy, and compliance controls. Drata continuously monitors more than 100 controls for security and GDPR compliance.

**SuperDoc Editor**, the JavaScript library, is open source and self-hosted. Your documents stay on your infrastructure. The SuperDoc team cannot access your content.

**SuperDoc APIs** are covered by SOC 2 controls and do not persist document data. Documents are processed and returned without persistent storage.

## SOC 2 report [#soc-2-report]

An independent auditor maintains the SOC 2 report, certifying the controls that protect your data.

The report follows the Trust Services Criteria from the AICPA's Assurance Services Executive Committee (ASEC). It evaluates the design and effectiveness of controls for security, availability, processing integrity, confidentiality, and privacy.

## Continuous control monitoring [#continuous-control-monitoring]

Drata monitors more than 100 security and privacy controls continuously, including GDPR compliance. Automated alerts and evidence collection verify SuperDoc's compliance posture.

## Team access and training [#team-access-and-training]

All employees use two-factor authentication, have role-based access restrictions, and sign a Non-Disclosure and Confidentiality Agreement. The team completes annual security training.

## Penetration tests [#penetration-tests]

SuperDoc works with independent security firms to perform annual network and application-layer penetration tests.

## Secure software development [#secure-software-development]

Manual and automated security checks run throughout the software development lifecycle.

## Data encryption [#data-encryption]

Data is encrypted in transit with Transport Layer Security (TLS) and at rest with AES-256 encryption.

## Infrastructure [#infrastructure]

SuperDoc's cloud infrastructure runs on Google Cloud Platform (GCP). Production data storage uses Google Spanner and Google Cloud Storage. GCP provides security, compliance, and auditing controls.

## Multi-region data storage and automated backups [#multi-region-data-storage-and-automated-backups]

Cloud data is stored across multiple regions within the United States. Automatic backups replicate data across multiple US data center locations.

## Compliance, audit logs, and monitoring [#compliance-audit-logs-and-monitoring]

Third-party monitoring detects potential attacks and anomalous network behavior. User actions in SuperDoc's cloud services are logged and auditable. GCP systems are regularly audited for ongoing security and compliance, including SOC 2.

## Terms of service and privacy policy [#terms-of-service-and-privacy-policy]

SuperDoc is dual-licensed. The open-source SuperDoc project is available under the [GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0). Proprietary and commercial deployments are licensed under the [SuperDoc Commercial License](https://www.superdocportal.dev/superdoc-terms-of-service).

Use of SuperDoc websites is governed by the [Website Terms of Use](https://app.termly.io/policy-viewer/policy.html?policyUUID=0b852fc9-5d9c-4170-8c96-08b072a55a9f).

See the [Privacy Policy](https://www.harbourshare.com/privacy-policy) for how SuperDoc handles data.

## Vulnerability disclosure program [#vulnerability-disclosure-program]

Found a security issue? Email [security@superdoc.dev](mailto:security@superdoc.dev). The security team investigates all reported issues promptly.


---

# Automate a DOCX from the CLI

> Accept tracked changes and save a separate DOCX from a shell or CI job.




Use the CLI when a shell script or CI job already knows which document operation to run. This guide accepts every
tracked change in a DOCX and writes the result to a separate file.

## 1. Install the CLI [#1-install-the-cli]

```bash
pnpm add --global @superdoc/cli@latest
```

The package installs the matching native command for your platform. Published builds support macOS on Apple Silicon and
Intel, Linux on ARM64 and x64, and Windows on x64.

Confirm that the command is available:

```bash
superdoc --version
```

## 2. Prepare a document [#2-prepare-a-document]

Download the [tracked-changes fixture](/fixtures/tracked-changes.docx) and save it as `contract.docx` in your working
directory. It contains one tracked change.

[Download the tracked-changes fixture](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


## 3. Accept the changes and save [#3-accept-the-changes-and-save]

Create `accept-changes.sh`:

```sh
#!/usr/bin/env bash
set -euo pipefail

superdoc open ./contract.docx
trap 'superdoc close --discard >/dev/null 2>&1 || true' EXIT
superdoc track-changes list
superdoc track-changes accept-all
superdoc save --out ./contract.accepted.docx

```

Run it from the directory containing `contract.docx`:

```bash
bash accept-changes.sh
```

`open` creates an active document session. The review command changes that session, and `save --out` writes a separate
DOCX. The `EXIT` trap closes the session whether the script succeeds or fails. The source file is not overwritten.

> **Keep the output path clear (warning)**
>
> The CLI refuses to replace an existing output file unless you pass `--force`. Rename or inspect the existing file
> before rerunning the script.


## 4. Verify the output [#4-verify-the-output]

Open `contract.accepted.docx` in Microsoft Word or the SuperDoc editor. Every tracked change should be accepted. The
original `contract.docx` should remain unchanged.

> **Verification target (success)**
>
> The output contains the same document content and formatting with no pending tracked changes. The source file remains
> unchanged.


Use the [Node.js SDK](/agents/automation/node-sdk) or [Python SDK](/agents/automation/python-sdk) when application code
needs to own the workflow, errors, and output paths. For the operation and receipt model shared by every surface,
continue with the [Document API mental model](/document-api/mental-model).


---

# Automate a DOCX with Node.js

> Query a DOCX, accept its tracked changes, and save the result from Node.js.





Use the SDK when application code knows the operation it needs. No model is involved: the script queries, mutates, and saves deterministically.

## 1. Install the Node.js SDK [#1-install-the-nodejs-sdk]

```bash
pnpm add @superdoc/sdk@latest
```

The SDK embeds the SuperDoc runtime. You do not need a separate CLI installation to use `SuperDocClient`.

## 2. Prepare a document [#2-prepare-a-document]

Download the [tracked-changes fixture](/fixtures/tracked-changes.docx). Save it as `contract.docx` in your working directory. It contains the word `termination` and one tracked change. Any document meeting those two conditions also works.

[Download the tracked-changes fixture](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


> **Diagram:** A DOCX file enters a headless SuperDoc workflow, the SDK queries and accepts its tracked changes, and a separate DOCX file is saved.


> **Keep the source file (warning)**
>
> Write the first result to a separate path so you can compare the output with the original document.


## 3. Query, mutate, and save [#3-query-mutate-and-save]

Create `accept-changes.mjs`:

```mjs
import { SuperDocClient } from '@superdoc/sdk';

/** @param {unknown} value */
function isSuccessfulReceipt(value) {
  return typeof value === 'object' && value !== null && 'success' in value && value.success === true;
}

const client = new SuperDocClient();

try {
  await client.connect();
  const doc = await client.open({ doc: './contract.docx' });

  try {
    const match = await doc.query.match({
      select: { type: 'text', pattern: 'termination' },
      require: 'first',
    });

    console.log('Matched:', match.items[0]);

    const receipt = await doc.trackChanges.decide({
      decision: 'accept',
      target: { kind: 'all' },
    });

    console.log('Mutation receipt:', receipt);
    if (!isSuccessfulReceipt(receipt)) throw new Error('Accepting tracked changes failed.');

    await doc.save({
      out: './contract.accepted.docx',
      force: true,
    });
  } finally {
    await doc.close({ discard: true });
  }
} finally {
  await client.dispose();
}

```

Run it with Node.js:

```bash
node accept-changes.mjs
```

## 4. Verify the output [#4-verify-the-output]

Open `contract.accepted.docx` in Word or the SuperDoc editor. The tracked changes should be accepted. The original `contract.docx` remains unchanged.

Saving to a separate path leaves the source session dirty by design. After the output succeeds, `close({ discard: true })` closes that in-memory session without overwriting the source file.

> **Verification target (success)**
>
> The output should contain the same document content and formatting, with every tracked change accepted. The source
> file should remain unchanged.


For the contract behind each step, read the [Document API mental model](/document-api/mental-model).

## Open a token-authenticated collaboration document [#open-a-token-authenticated-collaboration-document]

Pass a Hocuspocus or y-websocket token in the options for that document's open request:

```js
const document = await client.open(
  {
    doc: './contract.docx',
    collaboration: {
      providerType: 'hocuspocus',
      url: 'wss://collaboration.example.com',
      documentId: 'contract-123',
    },
  },
  { collaborationAuth: { type: 'token', token: userToken } },
);
```

The credential is separate from the collaboration profile and command-line arguments. It applies to the provider
created for this open request. Per-open token authentication is not supported for Liveblocks or the standalone
document host.

Prefer Python? Follow the [Python SDK guide](/agents/automation/python-sdk) for the same deterministic workflow.


---

# Automate a DOCX with Python

> Accept tracked changes and save a separate DOCX from Python.




Use the Python SDK when application code already knows which document operation to run. This guide accepts every
tracked change in a DOCX and writes the result to a separate file.

## 1. Install the Python SDK [#1-install-the-python-sdk]

SuperDoc supports Python 3.9 and newer:

```bash
python -m pip install superdoc-sdk
```

The package installs the matching SuperDoc CLI companion automatically. You do not need Node.js or a separate CLI
installation. Published companions support macOS on Apple Silicon and Intel, Linux on ARM64 and x64, and Windows on x64.

## 2. Prepare a document [#2-prepare-a-document]

Download the [tracked-changes fixture](/fixtures/tracked-changes.docx) and save it as `contract.docx` in your working
directory. It contains one tracked change.

[Download the tracked-changes fixture](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


> **Keep the source file (warning)**
>
> Write the first result to a separate path so you can compare the output with the original document.


## 3. Accept the changes and save [#3-accept-the-changes-and-save]

Create `accept_changes.py`:

```py
from superdoc import SuperDocClient


def is_successful_receipt(value: object) -> bool:
    return isinstance(value, dict) and value.get("success") is True


with SuperDocClient() as client:
    document = client.open({"doc": "./contract.docx"})

    try:
        receipt = document.track_changes.decide(
            {
                "decision": "accept",
                "target": {"kind": "all"},
            }
        )
        if not is_successful_receipt(receipt):
            raise RuntimeError("Accepting tracked changes failed.")

        document.save(
            {
                "out": "./contract.accepted.docx",
                "force": True,
            }
        )
    finally:
        document.close({"discard": True})

```

Run it from the directory containing `contract.docx`:

```bash
python accept_changes.py
```

`SuperDocClient` owns one persistent host process. The context manager starts it on entry and disposes it on exit. The
document still has its own lifecycle, so the `finally` block closes the session even when a mutation or save fails.

## 4. Verify the output [#4-verify-the-output]

Open `contract.accepted.docx` in Microsoft Word or the SuperDoc editor. Every tracked change should be accepted. The
original `contract.docx` should remain unchanged.

> **Verification target (success)**
>
> The output contains the same document content and formatting with no pending tracked changes. The source file remains
> unchanged.


## Use the asynchronous client [#use-the-asynchronous-client]

Use `AsyncSuperDocClient` when the surrounding application already runs an event loop. Its document methods mirror the
synchronous client and are awaited:

```python
import asyncio

from superdoc import AsyncSuperDocClient


async def main():
    async with AsyncSuperDocClient() as client:
        document = await client.open({"doc": "./contract.docx"})
        try:
            info = await document.info({})
            print(info["counts"])
        finally:
            await document.close({"discard": True})


asyncio.run(main())
```

## Open a token-authenticated collaboration document [#open-a-token-authenticated-collaboration-document]

Pass a Hocuspocus or y-websocket token with the document's open request:

```python
document = await client.open(
    {
        "doc": "./contract.docx",
        "collaboration": {
            "providerType": "hocuspocus",
            "url": "wss://collaboration.example.com",
            "documentId": "contract-123",
        },
    },
    collaboration_auth={"type": "token", "token": user_token},
)
```

The credential is separate from the collaboration profile and command-line arguments. It applies to the provider
created for this open request. Per-open token authentication is not supported for Liveblocks or the standalone
document host.

Use the [Node.js SDK](/agents/automation/node-sdk) for the same deterministic workflow from JavaScript or TypeScript.
For the operation and receipt model shared by both SDKs, continue with the
[Document API mental model](/document-api/mental-model).


---

# Core action reference

> The arguments, selectors, placements, and receipts behind superdoc_inspect and superdoc_perform_action.




The `core` preset advertises two tools. `superdoc_inspect` reads a deterministic snapshot. `superdoc_perform_action` runs one named action with flat arguments and returns a receipt. This page documents both from the action registry in `@superdoc/sdk`, and the same definitions are served over MCP under `MCP_PRESET=core`.

The registry changes across SDK releases without changing the preset id. Pin the SDK version when your integration depends on a specific action set, and read the advertised schema after upgrading:

```ts
import { getToolCatalog } from '@superdoc/sdk';

const catalog = await getToolCatalog('core');
const performAction = catalog.tools.find((tool) => tool.toolName === 'superdoc_perform_action');
console.log(performAction?.inputSchema);
```

## superdoc\_inspect [#superdoc_inspect]

Every argument is optional. Prefer the narrowest call that answers the question, because the result lives in conversation history for the rest of the run.

| Argument                                                        | Effect                                                                                                      |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `countsOnly`                                                    | Return counts only. The cheapest orientation call                                                           |
| `includeDomains`                                                | Limit the snapshot to the listed domains                                                                    |
| `blockNodeTypes`                                                | Only blocks of these node types, for example `["heading"]`                                                  |
| `findText`, `findLimit`                                         | Scan the whole document server-side, report matching blocks, and center the block window on the first match |
| `blockOffset`, `blockLimit`                                     | A contiguous window of blocks. Ordinals are absolute, so windows line up across calls                       |
| `omitEmptyBlocks`, `dropTextPreview`, `blockTextLimit`          | Trim the payload of a reading pass                                                                          |
| `includeListItemRuns`, `listItemRunsLimit`                      | Inline formatting runs on list items. On by default; pass `false` for a pure read                           |
| `includeBlockRuns`, `blockRunsLimit`                            | Inline formatting runs on body blocks. Off by default. Pair with a narrow block window                      |
| `includeTableCellRuns`, `tableCellRunsLimit`                    | Inline formatting runs on table cells. Off by default                                                       |
| `listLimit`, `tableLimit`, `commentLimit`, `trackedChangeLimit` | Cap the entries returned for each domain                                                                    |

Domains: `blocks`, `lists`, `tables`, `comments`, `trackedChanges`, `sections`, `headerFooters`, `styles`, `contentControls`, `fields`, `hyperlinks`, `bookmarks`, `permissionRanges`, `images`.

Every ordinal in a snapshot is 1-based, and selectors accept the same values. Use `findText` to locate a heading or phrase in a long document instead of paging through windows.

## Selectors [#selectors]

Actions that operate on a block take a `selector`. Batch actions take `selectors[]`.

| Selector    | Shape                                                                                   | Use when                                                     |
| ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Node id     | `{ kind: "nodeId", nodeId }`                                                            | You have a `nodeId` from an inspect. The most precise choice |
| Ordinal     | `{ kind: "ordinal", ordinalKind, value }`                                               | "The third paragraph" or "the second table"                  |
| Text search | `{ kind: "textSearch", terms: [...], match?, occurrence?, caseSensitive?, nodeTypes? }` | You know the wording but not the position                    |
| Table cell  | `{ kind: "tableCell", tableOrdinal, rowIndex, columnIndex }`                            | Cell-scoped edits                                            |
| Relative    | `{ kind: "relative", position: "before" \| "after", target: <selector> }`               | "The paragraph after the heading called X"                   |

`ordinalKind` is one of `blockOrdinal`, `paragraphOrdinal`, `bodyParagraphOrdinal`, `headingOrdinal`, `listOrdinal`, `tableOrdinal`, or `sectionOrdinal`. `match` on a text search is `all` or `any`, and `nodeTypes` narrows to `paragraph`, `heading`, or `listItem`.

## Placement [#placement]

Actions that insert content take a `placement`:

```json
{ "at": "document_end" }
{ "at": "document_start" }
{ "at": "after", "selector": { "kind": "textSearch", "terms": ["Definitions"] } }
{ "at": "before", "selector": { "kind": "nodeId", "nodeId": "p42" } }
```

## changeMode [#changemode]

Actions that accept `changeMode` record the edit as a tracked change when it is `"tracked"` and edit directly otherwise. The tool schema advertises the argument once for the whole tool, so the table below is the only place that says which actions honor it. Passing it to an action marked **No** looks compliant and produces a direct edit. `move_range` declares the argument but does not support tracked mode, and rejects the request rather than applying an untracked edit.

The [safety guide](/agents/operate/safety) explains why a loop that promises reviewable output must enforce this allowlist in code.

## Actions [#actions]

Arguments marked `?` are optional. Styled text arguments (`texts`, `cellTexts`, `entries`) accept either a plain string or an object with `runs` and `marks` so new content can match its neighbors in the same call.

### Text and structure [#text-and-structure]

| Action              | Arguments                                                         | Tracked | Notes                                                                                                              |
| ------------------- | ----------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `insert_paragraphs` | `texts[]` or `text`, `placement?`, `headingLevel?`                | Yes     | The way to add a paragraph or clause. The first item can become a heading                                          |
| `insert_heading`    | `text`, `level`, `placement?`                                     | Yes     |                                                                                                                    |
| `replace_text`      | `edits[{ find, replace }]`, `selector?`, `caseSensitive?`         | Yes     | Rewrites the matched span as plain text. Keep spans minimal. Not for appending new sentences                       |
| `delete_text`       | `finds[]`, `selector?`, `caseSensitive?`                          | Yes     | Deletes text only and leaves the block. Scope with `selector` to delete stray whitespace safely                    |
| `delete_blocks`     | `selectors[]` or `selector`                                       | Yes     | Removes whole paragraphs, headings, or list items, marker included                                                 |
| `append_list`       | `items[]`, `kind?`, `headingText?`, `headingLevel?`, `placement?` | Yes     | Starts a new list. Use `add_list_items` to extend an existing one                                                  |
| `create_table`      | `rows`, `columns`, `cellTexts?`, `placement?`                     | Yes     | In tracked mode the whole insertion is one tracked change                                                          |
| `rewrite_block`     | `selector`, `text`                                                | Yes     | Replaces a block's text and preserves the run pattern over the unchanged prefix and suffix                         |
| `fill_placeholders` | `values[]` and/or `fields[{ label?, value }]`                     | Yes     |                                                                                                                    |
| `move_range`        | `fromText`, `toText?`, `afterText` or `beforeText`                | Refused | Moves a block range or a visual section identified by text. Ranges containing tables, lists, or images are refused |

### Lists and numbering [#lists-and-numbering]

| Action             | Arguments                                                                                            | Tracked | Notes                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `convert_list`     | `kind`, then `listOrdinal?` or `anchorText?`, or `fromMarker` + `toMarker`, or `fromText` + `toText` | Yes     | Converts lists, clause ranges, or plain paragraphs to a list in place                  |
| `attach_numbering` | `anchorText` or `nodeId`, `likeMarker`                                                               | Yes     | Numbers a block in the same scheme and level as the sibling rendering `likeMarker`     |
| `add_list_items`   | `anchorText` or `listOrdinal`, `entries[]` or `items[]`                                              | Yes     | Adds into an existing list and reuses its numbering. `level` is relative to the anchor |
| `split_list`       | `anchorText`, `restartNumbering?`                                                                    | No      | Splits one list into two at an item                                                    |

### History [#history]

| Action         | Arguments                | Tracked | Notes                                                                   |
| -------------- | ------------------------ | ------- | ----------------------------------------------------------------------- |
| `undo_changes` | `untilMarker?`, `steps?` | No      | Steps history back until the rendered marker reappears, or a step count |
| `redo_changes` | `steps?`                 | No      | Only valid right after an undo, before any new edit                     |

### Moving text [#moving-text]

| Action      | Arguments            | Tracked | Notes                                                                                                               |
| ----------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `move_text` | `text`, `afterText?` | Yes     | Direct mode requires `afterText`. Tracked mode records a tracked delete at the source and insert at the destination |

### Comments [#comments]

| Action               | Arguments                                      | Tracked | Notes                                                         |
| -------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------- |
| `comment_paragraphs` | `commentText`, `scope?`, `excludeBlockQuotes?` | No      | One identical comment per paragraph. For broadcast notes only |
| `add_comments`       | `commentText`, `selector` or `selectors[]`     | No      | Batch many targets into `selectors[]` in one call             |
| `resolve_comments`   | `anchorText?`, `reopen?`                       | No      | Omit `anchorText` to resolve every open comment               |
| `reply_to_comment`   | `commentText`, `anchorText` or `commentId`     | No      | Adds a threaded reply rather than a new top-level comment     |

### Tracked-change review [#tracked-change-review]

| Action                   | Arguments                | Tracked | Notes                                                          |
| ------------------------ | ------------------------ | ------- | -------------------------------------------------------------- |
| `accept_tracked_changes` | `author?`, `changeType?` | No      | `changeType` is `insert`, `delete`, `replacement`, or `format` |
| `reject_tracked_changes` | `author?`, `changeType?` | No      |                                                                |

Exclude both when a person must make the final decision. [Safety](/agents/operate/safety#keep-a-human-in-the-loop) shows the exclusion.

### Formatting [#formatting]

| Action                     | Arguments                                                                                                                                        | Tracked | Notes                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------------------------------------------------------------- |
| `format_text`              | `targetText`, `targetTexts[]`, or `selector`; `bold?`, `italic?`, `underline?`, `strike?`, `highlight?`, `color?`, `fontSize?`, `caseSensitive?` | Yes     | Applies to every occurrence of the target text                 |
| `apply_style`              | `selector`, then one of `styleId`, `headingLevel`, or `likeText`                                                                                 | No      | `likeText` copies another block's style and effective look     |
| `format_paragraph`         | `selector`, `alignment`                                                                                                                          | Yes     | Tracked mode records the former alignment as a property change |
| `set_paragraph_spacing`    | `selector`, `lineSpacing?`, `spaceBefore?`, `spaceAfter?`                                                                                        | No      |                                                                |
| `normalize_body_font_size` | `fontSize`                                                                                                                                       | Yes     | Whole-body font size                                           |
| `set_font_family`          | `fontFamily`, `selector?` or `targetText`/`targetTexts[]?`, `caseSensitive?`                                                                     | Yes     | Omit every target to set the whole body typeface               |
| `apply_letter_spacing`     | `selector`, `letterSpacing`                                                                                                                      | Yes     |                                                                |

### Layout, links, and table of contents [#layout-links-and-table-of-contents]

| Action              | Arguments                 | Tracked | Notes                                                                    |
| ------------------- | ------------------------- | ------- | ------------------------------------------------------------------------ |
| `insert_page_break` | `selector`                | No      | Sets a page break before the block instead of inserting empty paragraphs |
| `add_hyperlink`     | `text`, `url`, `tooltip?` | No      | Turns existing text into a link                                          |
| `insert_toc`        | `title?`, `placement?`    | Yes     |                                                                          |

### Tables [#tables]

| Action                | Arguments                                                                   | Tracked | Notes                                                        |
| --------------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------ |
| `style_table`         | `tableOrdinal?`, `accentColor?`                                             | No      | Accent header, bold first column, banded rows                |
| `move_table`          | `tableOrdinal?`, `placement`                                                | No      | Moves the whole table with its content in one call           |
| `delete_table`        | `tableOrdinal?`                                                             | Yes     |                                                              |
| `insert_table_row`    | `tableOrdinal?`, `rowIndex?`, `position?`, `cellTexts?`, `dryRun?`          | Yes     | `dryRun: true` reports success without changing the document |
| `insert_table_column` | `tableOrdinal?`, `columnIndex?`, `position?`, `headerText?` or `cellTexts?` | Yes     |                                                              |
| `delete_table_row`    | `tableOrdinal?`, `rowIndex`                                                 | Yes     |                                                              |
| `delete_table_column` | `tableOrdinal?`, `columnIndex`                                              | Yes     |                                                              |
| `split_table`         | `tableOrdinal?`, `rowIndex`, `separatorText?`                               | Yes     |                                                              |

`tableOrdinal` is 1-based. Omit it only when the document contains exactly one table; with several tables the action cannot resolve a target and fails. `rowIndex` and `columnIndex` are 0-based, unlike every ordinal, so `rowIndex: 0` is the first row. The `tableCell` selector uses the same 0-based row and column indices.

## Receipts [#receipts]

Every dispatched action returns a receipt. Reads return a snapshot instead, and argument validation throws before a receipt exists. [Build an agent](/agents/build/build-an-agent#read-the-receipts) explains how a loop should branch on the three cases.

| Field                                | Meaning                                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `status`                             | `ok`, `partial`, `failed`, or `aborted`. `partial` means some requested edits applied and some did not   |
| `intent`                             | The action name                                                                                          |
| `preSnapshot`, `postSnapshot`        | `revision` and `counts` before and after. Differing revisions are the evidence that the document changed |
| `selectedTargets`                    | The selectors that resolved and what they matched                                                        |
| `executedOperations`                 | The Document API operations the action ran                                                               |
| `verification`, `verificationPassed` | Post-checks run against a fresh snapshot, and their roll-up                                              |
| `errors[]`                           | `code`, a `message` written for the model, and sometimes a structured `recovery`                         |
| `nextStep`, `revertHint`, `note`     | Prose guidance for the model, and a literal undo call when several history steps were dispatched         |

Actions add their own evidence, such as `editsApplied` and `editsSkipped` on `replace_text`, `formattingMatched` on inserts that copy neighboring formatting, and `addedItems` on `add_list_items`.

Verification checks include `revision-changed`, `block-count-delta`, `comment-count-delta`, `tracked-change-count-delta`, `block-text-contains`, `table-shape`, and `list-item-count`. The standard `revision-changed` check fails when a mutation turns out to be a no-op, so `verificationPassed: false` does not by itself say whether anything changed. Read the snapshots.

## Add your own [#add-your-own]

`createAgentToolkit` accepts `customActions`, which extend this registry with named verbs of your own that dispatch through the same tool. Their receipts report `succeeded` rather than `ok`. See [Custom actions](/agents/build/custom-actions).

## Not advertised [#not-advertised]

The dispatcher also routes `superdoc_execute_code`, `agent_apply`, `agent_verify`, and `agent_operation`. They are for SDK callers, they are absent from the tool list and the system prompt, and a model-facing loop should refuse them. [Build an agent](/agents/build/build-an-agent#dispatch-only-what-you-advertised) shows the check.


---

# Build an agent

> Give your product's agent document tools with a bounded, verifiable loop.



Use the SDK toolkit when the agent lives inside your product rather than in a coding tool. The toolkit returns the three pieces an agent loop needs, already agreeing with each other: tool definitions in your provider's shape, the matching system prompt, and a dispatcher bound to the same surface.

## Get the toolkit [#get-the-toolkit]

```bash
pnpm add @superdoc/sdk@latest
```

One call produces all three pieces:

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
});
```

> **Always pass a preset (warning)**
>
> `preset: 'core'` is the surface to build on. Omitting `preset` selects the older `legacy` tool surface for backward
> compatibility, which advertises a different set of tools.


`provider` accepts `openai`, `anthropic`, `vercel`, or `generic`. It changes the wire shape of the tool definitions, not the operations available.

Assembling the three pieces separately is the most common integration mistake. A prompt that documents a tool the model cannot call teaches it to call that tool, and the failure looks like a model problem rather than a configuration one. The toolkit makes it impossible for the pieces to disagree.

## The loop [#the-loop]

An agent loop is four steps repeated under a turn limit: ask the model, dispatch any tool calls, feed each receipt back, and stop when the model stops calling tools.

```mjs
import { resolve } from 'node:path';
import { createSuperDocClient, createAgentToolkit } from '@superdoc/sdk';

const MAX_TURNS = 16;

// The tools this loop will dispatch. The core preset's dispatcher also accepts
// names it never advertises (`superdoc_execute_code`, `agent_apply`,
// `agent_verify`, `agent_operation`), which skip the tracked-mode guard below
// and return shapes this loop does not understand. A model that hallucinates
// one, or that is talked into it by content inside the document, must not reach
// them — so dispatch only what was advertised.
const ADVERTISED_TOOLS = new Set(['superdoc_inspect', 'superdoc_perform_action']);

// Tools that change the document. `superdoc_inspect` is read-only, so it is
// deliberately absent: it neither needs a change mode nor counts as a mutation.
const MUTATING_TOOLS = new Set(['superdoc_perform_action']);

// `superdoc_perform_action` advertises `changeMode` once for every action,
// but only some of them honor it — the rest ignore the argument and edit
// directly. Passing `changeMode: 'tracked'` to one of those looks compliant and
// silently produces an untracked edit, so this workflow allows only the actions
// that actually record a suggestion.
//
// `move_range` declares `changeMode` but is direct-only today: its own action
// hint says tracked mode fails without mutating, because a block-range deletion
// cannot be tracked. Allowing it would guarantee a failed run, so it is out.
const TRACKED_CAPABLE_ACTIONS = new Set([
  'add_list_items',
  'append_list',
  'apply_letter_spacing',
  'attach_numbering',
  'convert_list',
  'create_table',
  'delete_blocks',
  'delete_table',
  'delete_table_column',
  'delete_table_row',
  'delete_text',
  'fill_placeholders',
  'format_paragraph',
  'format_text',
  'insert_heading',
  'insert_paragraphs',
  'insert_table_column',
  'insert_table_row',
  'insert_toc',
  'move_text',
  'normalize_body_font_size',
  'replace_text',
  'rewrite_block',
  'set_font_family',
  'split_table',
]);

/**
 * One model turn, in OpenAI's Chat Completions shape.
 *
 * Return the assistant message unchanged from
 * `openai.chat.completions.create({ model, messages, tools })`. The loop reads
 * and writes that same shape, so nothing has to be translated in either
 * direction. For a provider with a different wire format, adapt it here and
 * where tool results are appended below.
 *
 * @typedef {{ id: string, type: 'function', function: { name: string, arguments: string } }} ToolCall
 * @typedef {{ role?: string, content?: string | null, tool_calls?: ToolCall[] }} AssistantMessage
 * @typedef {(input: { messages: unknown[], tools: unknown[] }) => Promise<AssistantMessage>} CallModel
 */

/**
 * Receipts carry action-specific evidence, so narrow the fields this loop reads.
 *
 * @param {unknown} value
 * @returns {{
 *   status?: string,
 *   verificationPassed?: boolean,
 *   preSnapshot?: { revision?: string },
 *   postSnapshot?: { revision?: string },
 * }}
 */
function asReceipt(value) {
  return typeof value === 'object' && value !== null ? value : {};
}

/**
 * Whether a receipt is evidence that the document actually changed.
 *
 * Some actions accept `dryRun: true` and report success while explicitly
 * applying nothing, so a successful receipt is not proof of a mutation. When
 * the action reports both revisions, require them to differ; fall back to the
 * argument only when the receipt does not say.
 *
 * @param {ReturnType<typeof asReceipt>} receipt
 * @param {Record<string, unknown>} args
 */
function changedTheDocument(receipt, args) {
  const before = receipt.preSnapshot?.revision;
  const after = receipt.postSnapshot?.revision;
  if (before != null && after != null) return before !== after;
  return args.dryRun !== true;
}

/**
 * Edit a DOCX from a natural-language instruction, then save to a new file.
 *
 * Produces a tracked, reviewable draft. It does not prove the model completed
 * every part of the instruction — see the guide for why that needs an explicit
 * plan rather than receipt inspection.
 *
 * @param {{
 *   input: string,
 *   output: string,
 *   instruction: string,
 *   callModel: CallModel,
 *   author: { name: string, email?: string },
 * }} options `author` names this integration in tracked changes. Give each
 *   deployment its own, so a reviewer can tell them apart.
 */
export async function runAgent({ input, output, instruction, callModel, author }) {
  // Without a user, tracked changes are attributed to a generic "CLI" author
  // shared by every unattributed workflow. Naming the agent is what makes its
  // suggestions distinguishable, so the identity is a parameter rather than a
  // constant: copying this file should not copy someone else's author.
  const client = createSuperDocClient({ user: author });
  /** @type {Awaited<ReturnType<typeof client.open>> | undefined} */
  let doc;

  try {
    await client.connect();
    doc = await client.open({ doc: input });

    // One call keeps tools, prompt, and dispatch on the same preset. Assembling
    // them separately is how a tool surface and a system prompt drift apart.
    const { tools, systemPrompt, dispatch } = await createAgentToolkit({
      provider: 'openai',
      preset: 'core',
    });

    /** @type {unknown[]} */
    const messages = [
      { role: 'system', content: systemPrompt },
      {
        role: 'user',
        content: `${instruction}\n\nMake every edit a tracked change so a reviewer can accept or reject it.`,
      },
    ];

    // A dispatched failure is terminal for the save: an edit that half-applied
    // leaves the document in a state no later receipt can prove was repaired.
    /** @type {string[]} */
    const failures = [];
    let completed = false;
    let mutations = 0;

    // Bounded: a model that keeps calling tools must still terminate.
    for (let turn = 0; turn < MAX_TURNS; turn += 1) {
      const reply = await callModel({ messages, tools });
      messages.push(reply);

      // No tool calls means the model considers the work finished.
      if (!reply.tool_calls?.length) {
        console.log(reply.content ?? '(no final message)');
        completed = true;
        break;
      }

      for (const call of reply.tool_calls) {
        /** @type {unknown} */
        let receipt;
        let label = call.function.name;
        let dispatched = false;

        try {
          const args = JSON.parse(call.function.arguments);
          if (typeof args.action === 'string') label = args.action;

          // Dispatch only what the toolkit advertised. The dispatcher itself is
          // more permissive, so this is the boundary that keeps a hallucinated
          // or injected tool name from reaching the document.
          if (!ADVERTISED_TOOLS.has(call.function.name)) {
            receipt = {
              status: 'failed',
              error: {
                code: 'TOOL_NOT_ADVERTISED',
                message: `"${call.function.name}" is not an available tool. Use one of: ${[...ADVERTISED_TOOLS].join(', ')}.`,
              },
            };
            console.error(`${call.function.name}: rejected, not an advertised tool`);
            // Unlike a correctable argument error, this is a request for
            // something that does not exist. Treat it as unfinished work so a
            // run cannot end on it and still save.
            failures.push(`${call.function.name} is not an available tool`);
            messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(receipt) });
            continue;
          }

          // The instruction asks for tracked changes, but `changeMode` is
          // optional and defaults to a direct edit, so a model that omits it
          // silently rewrites the document. Refuse the call instead of letting
          // the run produce an untracked edit it promised would be reviewable.
          if (MUTATING_TOOLS.has(call.function.name)) {
            const refusal =
              args.changeMode !== 'tracked'
                ? 'Every edit must set changeMode: "tracked". Retry this action with that argument.'
                : !TRACKED_CAPABLE_ACTIONS.has(args.action)
                  ? `The action "${args.action}" ignores changeMode and always edits directly. Use a tracked-capable action instead.`
                  : undefined;

            if (refusal) {
              // The call never reached the document, so this is a correction
              // the model can act on rather than a failed edit.
              receipt = { status: 'failed', error: { code: 'CHANGE_MODE_REQUIRED', message: refusal } };
              console.error(`${label}: rejected, ${refusal}`);
              messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(receipt) });
              continue;
            }
          }

          dispatched = true;
          receipt = await dispatch(doc, call.function.name, args);
          const parsed = asReceipt(receipt);
          const { status, verificationPassed } = parsed;
          console.log(`${label}: ${status ?? 'ok'}`);

          // A returned receipt is not a successful one. `partial` means some
          // edits applied and some did not, which must never read as success.
          if (status != null && status !== 'ok') {
            failures.push(`${label} reported ${status}`);
          } else if (verificationPassed === false) {
            console.warn('  verification did not pass');
            failures.push(`${label} failed verification`);
          } else if (call.function.name !== 'superdoc_inspect' && changedTheDocument(parsed, args)) {
            // superdoc_inspect reads without changing anything, and a dry run
            // reports success while applying nothing, so neither is evidence
            // that the edit happened.
            mutations += 1;
          }
        } catch (error) {
          // Hand the failure back to the model rather than throwing: a bad
          // argument is something it can correct on the next turn.
          const { code, message } = /** @type {{ code?: string, message: string }} */ (error);
          receipt = { status: 'failed', error: { code, message } };
          console.error(`${label}: ${code ?? message}`);

          // A throw from dispatch may have applied part of the edit before
          // failing. A throw before it (malformed arguments) never reached the
          // document, so the model can still correct that one.
          if (dispatched) failures.push(`${label} threw ${code ?? message}`);
        }

        messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(receipt) });
      }
    }

    // Only save work that finished cleanly. Running out of turns means the
    // model never signalled completion, a dispatched failure means the document
    // is in a state nobody asked for, and zero mutations means there is nothing
    // to write — saving any of them produces a plausible-looking file that no
    // receipt ever justified.
    if (!completed) {
      throw new Error(`Agent stopped after ${MAX_TURNS} turns without completing. Nothing was saved.`);
    }
    if (failures.length > 0) {
      throw new Error(`Agent finished with unresolved failures: ${failures.join('; ')}. Nothing was saved.`);
    }
    if (mutations === 0) {
      throw new Error('Agent completed without applying any change. Nothing was saved.');
    }

    // Write to a separate path so the source survives a bad run. No `force`:
    // save refuses an existing output rather than overwriting it, which turns a
    // path typo into an error instead of destroying whatever was already there.
    if (resolve(output) === resolve(input)) {
      throw new Error(`Output path is the same file as the input (${input}). Nothing was saved.`);
    }
    await doc.save({ out: output });
    console.log(`Saved: ${output}`);
  } finally {
    // Cleanup is best-effort so a close failure cannot mask the real outcome.
    if (doc) await doc.close({ discard: true }).catch((error) => console.warn(`close failed: ${error.message}`));
    await client.dispose().catch((error) => console.warn(`dispose failed: ${error.message}`));
  }
}

```

The example uses OpenAI's Chat Completions message shape, so `callModel` can return the assistant message from `openai.chat.completions.create()` unchanged. The loop reads `tool_calls` and appends `role: 'tool'` results in that same shape, which keeps the conversation valid on the next request. A provider with a different wire format needs adapting in both directions: where tool calls are read, and where tool results are appended.

Name the agent when you create the client. Without a `user`, tracked changes are attributed to a generic `CLI` author shared by every unattributed workflow, and a reviewer cannot tell which automation proposed what. The example takes the identity as a parameter so each deployment supplies its own:

```ts
await runAgent({
  input: 'contract.docx',
  output: 'contract.reviewed.docx',
  instruction: 'Rewrite the termination clause to allow 30-day notice.',
  author: { name: 'Contract bot', email: 'contract-bot@example.com' },
  callModel,
});
```

## What each piece does [#what-each-piece-does]

| Piece          | Role                                                                     |
| -------------- | ------------------------------------------------------------------------ |
| `tools`        | Tool definitions in your provider's shape. Pass through untouched.       |
| `systemPrompt` | Documents the actions the model may call. Send it as the system message. |
| `dispatch`     | Runs a named tool call against an open document and returns a receipt.   |

`dispatch` takes the document handle, so tool arguments never carry `doc` or `sessionId`. The handle injects session targeting, which means a model cannot address a document it was not given.

## Read the receipts [#read-the-receipts]

Every dispatched *action* returns a receipt rather than throwing on a rejected edit. Check `status` before treating the work as done:

| `status`  | Meaning                                                         |
| --------- | --------------------------------------------------------------- |
| `ok`      | The requested edits applied and any post-check agreed           |
| `partial` | Some applied and some did not. Never treat this as success.     |
| `failed`  | The action did not complete. Some of it may still have applied. |
| `aborted` | The action stopped before applying anything                     |

Two dispatch outcomes are not receipts at all, and code that only reads `status` mishandles both.

`superdoc_inspect` returns a document snapshot, not a receipt. It has no `status`, so testing for one treats every successful read as a failure. Branch on the tool before interpreting the result.

Argument validation throws instead of returning. An unknown, missing, or excluded argument is rejected before an action runs, so the error arrives as an exception rather than a `failed` receipt. Wrap the dispatch in `try`/`catch` and hand that error back to the model as a tool result, or one malformed call ends the whole loop.

`failed` does not mean nothing happened. An action can apply its operation and then fail its own post-check: `insert_table_row` inserts the row, compares the resulting table shape, and reports `failed` when the shape disagrees, with a `postSnapshot` revision showing the document already changed.

So a failed receipt is not a safe retry. Compare `preSnapshot.revision` with `postSnapshot.revision` and read `executedOperations` before sending the same action again, or you may apply the edit twice.

When an action runs verification the receipt also carries `verificationPassed`. A `false` value means at least one check disagreed with the intent, not that the edit landed: the standard `revision-changed` check fails just as readily when the mutation was a no-op and nothing applied. The snapshots are what separate those two cases.

The example treats a dispatched failure as terminal for this reason: it stops rather than guessing whether a partly applied edit can be repeated safely.

**Receipt `replace`**: replacement recorded in tracked mode


## Keep the loop bounded [#keep-the-loop-bounded]

A model that keeps calling tools will keep calling tools. The turn cap in the example is not decoration: without it, a confused model can loop until it exhausts a token budget.

The cap only helps if hitting it stops the save. The example refuses to save in three cases: the model ran out of turns without signalling completion, any action reported a failure, or no mutation ever succeeded. That last one matters because a model can decide the work is already done and stop without touching the document, which would otherwise write an output file identical to the input.

A failure is terminal for the save rather than something a later success clears. Once an edit half-applies, receipts cannot prove that a subsequent call repaired that exact work: a `partial` on one clause followed by a clean edit to a different clause is two facts, not a fix. Recovering from a partially applied edit is a decision for a person looking at the document. Save to a path separate from the source, and close the session in `finally` so a mid-loop failure still releases the runtime.

## Dispatch only what you advertised [#dispatch-only-what-you-advertised]

`dispatch` accepts more tool names than the toolkit advertises. Alongside `superdoc_inspect` and `superdoc_perform_action`, the core preset can route `superdoc_execute_code`, `agent_apply`, `agent_verify`, and `agent_operation` — surfaces meant for SDK callers, not for a model to select. They skip the tracked-mode check, and they return shapes a loop built around receipts will misread.

Check the tool name against the list you handed the model before dispatching. Two things make that worth doing even though the model was never told those names exist: a model can hallucinate one, and document content can suggest one. An agent reads text somebody else wrote, so treat a tool name arriving from the model as input rather than as a decision already validated.

## Do not rely on the prompt for tracked mode [#do-not-rely-on-the-prompt-for-tracked-mode]

`changeMode` is optional and defaults to a direct edit, so an instruction to work in tracked mode is a request the model can quietly skip. The argument alone is not sufficient either. `superdoc_perform_action` advertises `changeMode` once for every action, but some actions never record a tracked change: `apply_style`, `set_paragraph_spacing`, and `insert_page_break` ignore the argument and edit directly, and comment and review actions have no tracked form by nature. Passing `changeMode: 'tracked'` to any of these looks compliant and produces no suggestion. The [action reference](/agents/build/actions#changemode) marks which actions honor the argument.

Ask the toolkit to enforce the policy instead of checking each call yourself:

```ts
const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
  enforceChangeMode: 'tracked',
  allowDirectActions: ['add_comments'],
});
```

`enforceChangeMode: 'tracked'` is fail-closed and applies to all three pieces at once:

* Every action that cannot record a tracked change leaves the tool enum and the system prompt, and `dispatch` refuses it with an `INVALID_ARGUMENT` error whose `details.reason` is `direct-only`. The model never learns the verb exists.
* Every remaining action runs tracked whatever the call said. A call that omits `changeMode` or passes `'direct'` is upgraded, and the receipt reports `changeMode: 'tracked'` with `changeModeForced: true` so your logs show the upgrade happened.

`allowDirectActions` names the direct-only actions your workflow still needs. They stay advertised and run directly, and their receipts say `changeMode: 'direct'`. The list requires `enforceChangeMode`, rejects unknown names, and ignores names that already record tracked changes, so it keeps working when an action gains tracked support. `excludeActions` still wins: an action in both lists stays hidden.

A reviewer agent usually wants the four comment actions and nothing else. They annotate without altering a character of document content, so the guarantee survives intact:

```ts
allowDirectActions: ['add_comments', 'comment_paragraphs', 'reply_to_comment', 'resolve_comments'];
```

A drafting agent typically allows nothing. Pass `['*']` to allow every direct-only action while still forcing tracked mode on everything that supports it — the tools and prompt then match an unenforced agent exactly, and the policy's remaining job is the forced upgrade. Weigh that one carefully: it reopens the eight actions that change the document with nothing to review (`apply_style`, `style_table`, `move_table`, `move_range`, `set_paragraph_spacing`, `insert_page_break`, `add_hyperlink`, `split_list`), plus the review and history actions, which materialize or discard existing tracked changes.

Which actions are which is published rather than guessed. `getActionDispositions()` returns the `tracked` or `direct` disposition of every action, and the core preset's catalog carries the same table under `dispositions`. Read one of those rather than hardcoding a list, so your configuration follows the registry when an action changes bucket. The [action reference](/agents/build/actions#changemode) carries the same dispositions per action alongside each action's arguments.

The policy is the same on every surface, because all three run the same preset code. The Python SDK takes `enforce_change_mode` and `allow_direct_actions`:

```python
toolkit = create_agent_toolkit({
    'provider': 'openai',
    'preset': 'core',
    'enforceChangeMode': 'tracked',
    'allowDirectActions': ['add_comments'],
})
```

The CLI takes them as flags on `preset get-tools`, `preset get-system-prompt`, and `preset dispatch`. Pass the same values to all three so the advertised surface and the dispatch guard agree:

```bash
superdoc preset get-tools --provider openai --preset core \
  --enforceChangeMode tracked --allowDirectActions add_comments

superdoc preset dispatch --session <id> --preset core \
  --tool-name superdoc_perform_action \
  --enforceChangeMode tracked --allowDirectActions add_comments \
  --args-json '{"action":"insert_paragraphs","text":"Proposed clause."}'
```

`--allowDirectActions` is a comma-separated list, and `*` allows every direct-only action.

Two things the policy does not do. It does not audit what the engine produced: a multi-step action can apply its first steps as tracked changes and then report `partial` when the engine refuses a later one, and the receipt is where that shows up. And it does not link receipts to the tracked changes they created; count them with `superdoc_inspect` when you need that evidence.

A rejection is different from a dispatched failure. It never touched the document, so the model can correct it on the next turn and the run continues. A thrown call splits the same way: malformed arguments and policy refusals never reach the document, while a throw from `dispatch` itself may have applied part of the edit before failing, so that one is terminal.

## What this loop does not prove [#what-this-loop-does-not-prove]

The example produces a tracked, reviewable draft. It does not prove the model carried out every part of your instruction.

Nothing in the receipts carries that information. If the model asks for two edits, has one refused, corrects it, and later stops, the loop sees a sequence of independent calls: no field links a retry to the request it repairs. Guessing at the link by action name is worse than not guessing, because the same action is used for unrelated edits — a refused `replace_text` on one clause looks identical to a successful `replace_text` on another.

Two things close that gap, and both belong in your application rather than in the loop:

* **Human review.** The output is a tracked draft precisely so a person decides what landed. This is the default and it is usually enough.
* **An explicit plan.** Derive the list of required edits before execution, give each a stable id, and check them off as receipts arrive. That makes completeness a property of your plan, not an inference from tool traffic.

Reach for the second only when a workflow has to assert completeness without a reviewer.

A successful receipt is not proof of a change either. Some actions accept `dryRun: true` and report success while explicitly applying nothing, so the example counts a mutation only when the receipt's before and after revisions differ.

Returning a failed dispatch to the model as a receipt, instead of throwing, is what lets it correct a malformed argument on the next turn.

## Next [#next]

[Tools](/agents/build/tools) explains the action surface, how to narrow it, and how to replay a tool call deterministically without the model. [Safety](/agents/operate/safety) covers what to settle before an agent touches documents that matter.


---

# Add a custom action

> Extend the core preset with your own named document verb, exposed to the model through superdoc_perform_action.




The core preset ships a fixed set of built-in actions. A custom action adds one of your own, exposed to the model through the same `superdoc_perform_action` tool and reached by name like any built-in. Use it when your product has a document operation the built-ins do not cover, or a house-style sequence you want the model to invoke as one verb.

A custom action is deterministic application code. It runs in your process, and it decides what happens to the document. The model only chooses to call it and supplies arguments.

## Define an action [#define-an-action]

`defineAction` builds an action spec from a name, a description the model reads, a JSON Schema for the arguments, and exactly one execution tier.

Namespace the name as `superdoc.<verb>`. A name that collides with a built-in is rejected when the toolkit is built, rather than silently shadowing it.

There are two tiers. A `run` action calls your own function and can reach anything the Document API exposes. A `steps` action composes built-in core actions and needs no code. Reach for `run` when the operation is beyond the built-ins, and drop to `steps` when they already cover it.

### The run tier [#the-run-tier]

A run action calls your function with the session-bound document handle. Reach for it when the operation needs a Document API namespace the action registry does not expose, such as footnotes, headers and footers, bookmarks, or table borders.

```ts
import { defineAction } from '@superdoc/sdk';

const addFootnote = defineAction({
  name: 'superdoc.add_footnote',
  description: 'Insert a footnote whose marker lands immediately after the given anchor text.',
  input: {
    type: 'object',
    properties: {
      anchorText: { type: 'string' },
      content: { type: 'string' },
    },
    required: ['anchorText', 'content'],
  },
  run: async (doc, args) => {
    const anchor = String(args.anchorText);
    const { blocks } = await doc.blocks.list({ includeText: true });
    for (const block of blocks) {
      const index = (block.text ?? '').indexOf(anchor);
      if (index < 0) continue;
      const end = index + anchor.length;
      const at = { kind: 'text', segments: [{ blockId: block.nodeId, range: { start: end, end } }] };
      const inserted = await doc.footnotes.insert({ at, content: String(args.content) });
      const after = await doc.footnotes.list({});
      return { inserted, footnoteCount: after.total };
    }
    throw new Error(`anchorText ${JSON.stringify(anchor)} was not found in any block.`);
  },
});
```

Two rules make a run action usable by a model. Take arguments the model can produce, such as anchor text or an ordinal, and resolve low-level targets inside the action rather than asking a caller for a ref. Pass `includeText: true` when you search block text, because the default preview is truncated and an anchor late in a paragraph would never match.

Throw on failure. The thrown error becomes a failed receipt whose message sits at `errors[0].message`, not at a top-level `error` field.

`input` takes a plain JSON Schema object. A Zod or similar library schema is rejected with an explicit error rather than accepted with its constraints dropped, so convert it first with something like `zod-to-json-schema`.

### The steps tier [#the-steps-tier]

A steps action runs a sequence of built-in core actions instead of your own code. When the built-ins can express the operation, this is the lighter option: it inherits their target resolution, placement handling, and verified receipts, and the result is pure data that behaves the same from Node.js and Python.

```ts
import { defineAction } from '@superdoc/sdk';

const stampBanner = defineAction({
  name: 'superdoc.stamp_banner',
  description: 'Insert a confidentiality banner at the top of the document and flag it for review.',
  input: {
    type: 'object',
    properties: { label: { type: 'string', default: 'CONFIDENTIAL' } },
  },
  steps: [
    { action: 'insert_paragraphs', args: { texts: ['{{label}}'], placement: { at: 'document_start' } } },
    {
      action: 'add_comments',
      args: {
        selectors: [{ kind: 'textSearch', terms: ['{{label}}'], occurrence: 1 }],
        commentText: 'Verify distribution before sending.',
      },
    },
  ],
});
```

Templating has two forms. A step argument that is exactly `'{{label}}'` substitutes the raw argument value, so arrays and objects survive intact. A placeholder with text around it, `'Stamped: {{label}}'`, interpolates into a string. Schema defaults apply before templating, so the example above stamps `CONFIDENTIAL` when the model omits `label`.

A caller's `changeMode` flows into every step that does not pin its own, so a tracked dispatch produces tracked steps without the action restating it.

## Register with the toolkit [#register-with-the-toolkit]

Pass the specs as `customActions`. The toolkit builds the extended preset internally, so there is no preset to name, register, or thread through later dispatch calls.

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'openai',
  customActions: [stampBanner, addFootnote],
});
```

The action enum, the tool description, the system prompt, and the dispatcher all move together, so a custom action cannot be advertised without being callable, or callable without being documented.

Two optional inputs shape the surface:

| Input            | Effect                                                                       |
| ---------------- | ---------------------------------------------------------------------------- |
| `base`           | Extend a preset other than `core`                                            |
| `includeActions` | Keep only these built-ins beside your own. `[]` yields a custom-only surface |

`excludeActions` still applies to the built-ins, and the two can be combined with your custom actions in one call.

Dispatch arguments are flat, exactly as for a built-in:

```ts
const receipt = await dispatch(doc, 'superdoc_perform_action', {
  action: 'superdoc.add_footnote',
  anchorText: 'the report',
  content: 'See appendix B.',
});
```

Nesting them under an `args` key fails with an unknown-argument error.

## Read a custom-action receipt [#read-a-custom-action-receipt]

> **Custom actions report a different status (warning)**
>
> A custom action reports `succeeded`, `partial`, or `failed`. The built-in core actions report `ok`. A loop that treats
> only `ok` as success will misread every custom action as a failure.


A steps receipt carries a `steps` array with one row per built-in it ran, and each row holds that built-in's own `ok` status. A `partial` aggregate means some steps landed and the receipt names which one failed and why.

A run receipt is synthesized around your return value, with `preRevision` and `postRevision`, plus `partialMutation` and a recovery hint when the function throws. The [action reference](/agents/build/actions#receipts) covers the built-in receipt shape those rows follow.

## Python [#python]

The Python SDK exposes the same two tiers through `define_action`, with `input_schema` in place of `input`:

```python
from superdoc import create_agent_toolkit, define_action

stamp_banner = define_action(
    name="superdoc.stamp_banner",
    description="Insert a confidentiality banner at the top of the document.",
    input_schema={
        "type": "object",
        "properties": {"label": {"type": "string", "default": "CONFIDENTIAL"}},
    },
    steps=[
        {
            "action": "insert_paragraphs",
            "args": {"texts": ["{{label}}"], "placement": {"at": "document_start"}},
        },
    ],
)

kit = create_agent_toolkit({"provider": "openai", "customActions": [stamp_banner]})
```

> **Match the handle your application uses (warning)**
>
> On an `AsyncSuperDocClient`, or when the application dispatches through `dispatch_async`, a `run` action must be
> `async def` and must await every `doc.*` call. A synchronous body on an async handle receives un-awaited coroutines
> and fails with `'coroutine' object is not subscriptable`. Steps actions need no change.


## Verify before shipping [#verify-before-shipping]

Validate the contract first, without needing a document. Confirm every operation the action calls, and that your argument shapes match, through the client's own description:

```ts
console.log(await client.describeCommand({ operationId: 'footnotes.insert' }));
```

Do not confirm an argument by watching a call succeed. Some operations ignore an unknown argument and still report success, so a green result can hide a parameter that did nothing.

Then run the action against a copy of a real document and require two things: a `succeeded` receipt, and independent evidence the document changed. Re-inspect for that evidence rather than trusting the receipt, by listing footnotes for a higher count or listing blocks for the new banner. When no suitable document exists, `client.open({})` starts a session on a blank one you can build the conditions into.

## Generate an action with a coding agent [#generate-an-action-with-a-coding-agent]

The `superdoc-custom-actions` skill walks Claude Code or Codex through this page's workflow: choosing a tier, defining the action, wiring it into the toolkit, and testing it against a document. Install it from your application's root directory:

```bash
npx skills add superdoc/docx-editor/packages/sdk/skills/superdoc-custom-actions --copy
```

Then ask for the operation you need, such as an action that inserts a footnote after a piece of text. The skill instructs the agent to verify against a real document where one is available, and to label the action a draft when it could not.

## Next [#next]

[Skills](/agents/build/skills) covers both packaged skills and how each is installed. [Tools and presets](/agents/build/tools) covers the surface your actions extend.


---

# Legacy tools

> What the legacy preset advertises, why it is still the default, and how to move to core.



The `legacy` preset is the original LLM tool surface: ten grouped intent tools generated from the Document API contract. Most take an `action` argument selecting the operation within the group; `superdoc_search` does not, because it exposes a single query surface driven by `select`.

It is still the default. A `createAgentToolkit()` call that omits `preset` gets this surface. Changing that default would break integrations built before presets existed, so it stays until a coordinated SDK release moves it.

## What it advertises [#what-it-advertises]

| Tool                     | Covers                                                               |
| ------------------------ | -------------------------------------------------------------------- |
| `superdoc_get_content`   | Read compact content or detailed HTML/Markdown projections           |
| `superdoc_search`        | Find content and return stable targets. Takes `select`, not `action` |
| `superdoc_edit`          | Insert, replace, and delete text, plus undo and redo                 |
| `superdoc_format`        | Inline and paragraph formatting, styles, direction, and flow         |
| `superdoc_create`        | Create paragraphs, headings, and tables                              |
| `superdoc_list`          | Create, convert, nest, split, merge, and renumber lists              |
| `superdoc_table`         | Table structure, content, and styling                                |
| `superdoc_comment`       | Create, update, resolve, and read comment threads                    |
| `superdoc_track_changes` | List tracked changes and decide on them                              |
| `superdoc_mutations`     | Preview and apply multi-step edits as one atomic batch               |

Each tool's exact action list comes from the generated catalog and changes with the contract, so read the advertised schema rather than a copy of it:

```ts
import { getToolCatalog } from '@superdoc/sdk';

const catalog = await getToolCatalog('legacy');
for (const tool of catalog.tools) {
  console.log(
    tool.toolName,
    tool.operations.map((operation) => operation.intentAction),
  );
}
```

The [Document API reference](/document-api/reference) documents the operations these tools dispatch to.

For review-aware extraction or citation-backed RAG input, use `html_projection` or `markdown_projection` on
`superdoc_get_content`. Those actions expose review mode, scope, diagnostics, annotation status, and an optional source
map. Compact `html` and `markdown` actions still return strings. Source-map targets use tracked coordinates and are valid
only at the returned `evaluatedRevision`; discard them after any mutation. See
[Project HTML and Markdown](/document-api/output-projections) for the fidelity and omitted-anchor rules.

## Choosing between them [#choosing-between-them]

|                            | `legacy`                            | `core`                                                         |
| -------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| Advertised tools           | 10 grouped intent tools             | 2 (`superdoc_inspect`, `superdoc_perform_action`)              |
| Edit selection             | Tool plus `action` within its group | One `action` from the [action registry](/agents/build/actions) |
| `excludeActions`           | Ignored, no action surface          | Supported                                                      |
| Receipts with verification | No                                  | Yes                                                            |
| Default                    | Yes                                 | No, pass `preset: 'core'`                                      |

Build new integrations on `core`. It narrows the advertised surface, supports exclusions, and returns receipts carrying verification results.

## Moving to core [#moving-to-core]

Set the preset explicitly and re-check the tool names your dispatch layer expects:

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
});
```

Three things change. Tool names collapse to two, so any code branching on a tool name needs updating. Edits move to `action` verbs on `superdoc_perform_action`, so a prompt naming legacy tools must be replaced by the preset's own `systemPrompt`. Receipts gain `verificationPassed` when an action runs a post-check.

Presets are not versioned. A new tool *shape* ships as a new preset id rather than a new version of an existing one, so `legacy` will not silently turn into an actions-style surface.

That is not a stability guarantee for the contents. Both catalogs are generated from the Document API contract and the action registry, so a preset can gain, lose, or change operations across SDK releases without changing its id. Pin the SDK version if your integration needs the advertised surface to hold still, and re-read the catalog after upgrading.


---

# Connect a model provider

> Wire the toolkit to Anthropic, OpenAI, the Vercel AI SDK, Amazon Bedrock, or Python, and cache the static prefix.




`createAgentToolkit` returns tool definitions in the shape your provider expects. The `provider` argument changes only that shape. The actions, the system prompt content, and `dispatch` are the same for every value.

| `provider`  | Tool definition shape                                               | `cache: true` reports |
| ----------- | ------------------------------------------------------------------- | --------------------- |
| `openai`    | `{ type: 'function', function: { name, description, parameters } }` | `automatic`           |
| `anthropic` | `{ name, description, input_schema }`                               | `explicit`            |
| `vercel`    | `{ name, description, inputSchema }`                                | `unsupported`         |
| `generic`   | `{ name, description, parameters }`                                 | `unsupported`         |

The message protocol does not adapt. Each provider reads tool calls and expects tool results in its own shape, so the loop around `dispatch` is provider-specific even though the toolkit is not. The code below shows the loop body for each. Every fragment assumes an open document handle named `doc` from `createSuperDocClient().open()`, and the bounded loop, receipt checks, and save guards from [Build an agent](/agents/build/build-an-agent) apply to all of them.

## OpenAI [#openai]

[Build an agent](/agents/build/build-an-agent#the-loop) uses the Chat Completions shape. The assistant message carries `tool_calls`, and each result goes back as a `role: 'tool'` message:

```ts
import type OpenAI from 'openai';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({ provider: 'openai', preset: 'core' });

const response = await openai.chat.completions.create({
  model,
  messages,
  tools: tools as OpenAI.Chat.Completions.ChatCompletionTool[],
});
const reply = response.choices[0].message;
messages.push(reply);

for (const call of reply.tool_calls ?? []) {
  const result = await dispatch(doc, call.function.name, JSON.parse(call.function.arguments));
  messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) });
}
```

The toolkit types `tools` as `unknown[]` because the shape depends on `provider`, so cast to the client's tool type at the call site. OpenAI caches long prompts on its own, so `cache: true` changes nothing on the wire and `meta.cacheStrategy` reports `automatic`.

## Anthropic [#anthropic]

Tool calls arrive as `tool_use` content blocks. Results go back inside a `role: 'user'` message as `tool_result` blocks, all in one message. Set `is_error: true` on a result that carries a thrown error so the model knows the call did not run.

Request the system prompt through `getSystemPromptForProvider` with `cache: true`. For Anthropic it returns content blocks with `cache_control` markers, and `cache: true` on the toolkit marks the tool array the same way, so the whole static prefix is cached across turns:

```ts
import Anthropic from '@anthropic-ai/sdk';
import { createAgentToolkit, getSystemPromptForProvider } from '@superdoc/sdk';

const anthropic = new Anthropic();
const { tools, dispatch } = await createAgentToolkit({ provider: 'anthropic', preset: 'core', cache: true });
const system = await getSystemPromptForProvider({ provider: 'anthropic', preset: 'core', cache: true });

const messages: Anthropic.MessageParam[] = [{ role: 'user', content: instruction }];

const response = await anthropic.messages.create({
  model: 'claude-opus-5',
  max_tokens: 16000,
  system: system.content,
  tools: tools as Anthropic.Tool[],
  messages,
});
messages.push({ role: 'assistant', content: response.content });

const results: Anthropic.ToolResultBlockParam[] = [];
for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  try {
    const result = await dispatch(doc, block.name, block.input as Record<string, unknown>);
    results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(result) });
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    results.push({
      type: 'tool_result',
      tool_use_id: block.id,
      content: JSON.stringify({ error: message }),
      is_error: true,
    });
  }
}
if (results.length > 0) messages.push({ role: 'user', content: results });
```

Pass `excludeActions` to `getSystemPromptForProvider` as well when you pass it to the toolkit, or the prompt keeps documenting an action the model cannot call. Confirm caching with `usage.cache_read_input_tokens` on the second request. If it stays at zero while `cache_creation_input_tokens` is also zero, the prefix is below the model's minimum cacheable length. If creation tokens appear on every request, something in the prefix changes between turns.

## Vercel AI SDK [#vercel-ai-sdk]

The AI SDK runs the loop itself. Convert each toolkit tool into an AI SDK tool whose `execute` calls `dispatch`, and cap the loop with `stopWhen`:

```ts
import { generateText, jsonSchema, stepCountIs, type Tool } from 'ai';
import { createAgentToolkit } from '@superdoc/sdk';

const {
  tools: toolkitTools,
  systemPrompt,
  dispatch,
} = await createAgentToolkit({ provider: 'vercel', preset: 'core' });

type VercelToolDefinition = { name: string; description: string; inputSchema: Record<string, unknown> };

const tools: Record<string, Tool> = {};
for (const definition of toolkitTools as VercelToolDefinition[]) {
  tools[definition.name] = {
    description: definition.description,
    inputSchema: jsonSchema<Record<string, unknown>>(definition.inputSchema),
    execute: async (args) => {
      try {
        return await dispatch(doc, definition.name, args);
      } catch (error) {
        return { error: error instanceof Error ? error.message : String(error) };
      }
    },
  };
}

const { text } = await generateText({
  model,
  system: systemPrompt,
  messages: [{ role: 'user', content: instruction }],
  tools,
  stopWhen: stepCountIs(10),
});
```

Because the AI SDK owns the loop, the receipt checks from [Build an agent](/agents/build/build-an-agent#read-the-receipts) move into `execute`. Record failures there and refuse to save afterwards when any were recorded. `execute` receives the parsed arguments, so the tracked-mode check belongs there too.

## Amazon Bedrock [#amazon-bedrock]

Bedrock's Converse API takes tools as `toolSpec` entries. Request Anthropic-shaped tools from the toolkit and wrap them:

```ts
import {
  BedrockRuntimeClient,
  ConverseCommand,
  type ContentBlock,
  type Message,
  type Tool,
} from '@aws-sdk/client-bedrock-runtime';
import type { DocumentType } from '@smithy/types';
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({ provider: 'anthropic', preset: 'core' });

type AnthropicToolDefinition = { name: string; description: string; input_schema: Record<string, unknown> };

// Bedrock types JSON payloads as DocumentType. Receipts and schemas are plain
// JSON, so a serialize round-trip is the honest way to satisfy it.
const toDocument = (value: unknown): DocumentType => JSON.parse(JSON.stringify(value));

const toolConfig = {
  tools: (tools as AnthropicToolDefinition[]).map<Tool>((tool) => ({
    toolSpec: { name: tool.name, description: tool.description, inputSchema: { json: toDocument(tool.input_schema) } },
  })),
};

const bedrock = new BedrockRuntimeClient({ region: 'us-east-1' });
const messages: Message[] = [{ role: 'user', content: [{ text: instruction }] }];

const response = await bedrock.send(
  new ConverseCommand({ modelId, messages, system: [{ text: systemPrompt }], toolConfig }),
);
const output = response.output?.message;
if (output) messages.push(output);

const results: ContentBlock[] = [];
for (const block of output?.content ?? []) {
  const use = block.toolUse;
  if (!use?.name || !use.toolUseId) continue;
  const result = await dispatch(doc, use.name, (use.input ?? {}) as Record<string, unknown>);
  results.push({ toolResult: { toolUseId: use.toolUseId, content: [{ json: toDocument(result) }] } });
}
if (results.length > 0) messages.push({ role: 'user', content: results });
```

`modelId` is a Bedrock identifier, usually an inference-profile id or a foundation-model id from the Bedrock console, not an Anthropic model name. Credentials come from the AWS SDK's usual chain. No SuperDoc API key is involved.

## Python [#python]

`superdoc-sdk` exposes the same toolkit. `create_agent_toolkit` returns a dictionary with `tools`, `system_prompt`, `meta`, and two pre-bound dispatchers, `dispatch` and `dispatch_async`:

```python
import json

from openai import OpenAI
from superdoc import SuperDocClient, create_agent_toolkit

kit = create_agent_toolkit({"provider": "openai", "preset": "core"})
llm = OpenAI()

with SuperDocClient(user={"name": "Contract bot"}) as client:
    doc = client.open({"doc": "./contract.docx"})
    try:
        messages = [
            {"role": "system", "content": kit["system_prompt"]},
            {"role": "user", "content": instruction},
        ]
        failures = []
        completed = False
        for _ in range(16):
            response = llm.chat.completions.create(model=model, messages=messages, tools=kit["tools"])
            reply = response.choices[0].message
            messages.append(reply)
            if not reply.tool_calls:
                completed = True
                break
            for call in reply.tool_calls:
                try:
                    result = kit["dispatch"](doc, call.function.name, json.loads(call.function.arguments))
                except Exception as error:  # noqa: BLE001 - hand the message back to the model
                    result = {"status": "failed", "error": {"message": str(error)}}
                # Inspect returns a snapshot without status; anything else is a receipt.
                status = result.get("status") if isinstance(result, dict) else None
                if status not in (None, "ok") or (isinstance(result, dict) and result.get("verificationPassed") is False):
                    failures.append(f"{call.function.name}: {status}")
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    # Receipts can carry values json.dumps does not handle natively.
                    "content": json.dumps(result, default=str),
                })
        if not completed or failures:
            raise RuntimeError(f"Agent did not finish cleanly: {failures or 'turn limit reached'}. Nothing saved.")
        doc.save({"out": "./contract.reviewed.docx"})
    finally:
        doc.close({"discard": True})
```

The save is gated the same way as the Node.js example: a run that hits the turn limit or records any failed, partial, or unverified receipt raises instead of writing a file. [Build an agent](/agents/build/build-an-agent#keep-the-loop-bounded) explains why a later success cannot clear an earlier failure.

The input dictionary uses the same keys as the Node.js toolkit, so `excludeActions` and `cache` work unchanged. Use `dispatch_async` with `AsyncSuperDocClient`. Of the standalone functions, `choose_tools` takes the same input dictionary, while `get_system_prompt` and `dispatch_superdoc_tool` take `preset` and `exclude_actions` as keyword arguments. Whichever you use, every call must receive the same preset and exclusions. The PyPI package is `superdoc-sdk` and the import is `superdoc`.

Python has no equivalent of `getSystemPromptForProvider`. For Anthropic caching, build the system block yourself from `get_system_prompt("core")` and add `cache_control` to it.

## Choosing a model [#choosing-a-model]

Pin an exact model id rather than an alias. Aliases move between releases and can change how a model reads tool schemas. Whatever the provider, keep the toolkit's system prompt as the first part of your system message and append product rules after it. The prompt teaches argument shapes the schema alone does not convey, and dropping it lowers edit quality across every model we have measured.

## Next [#next]

[Manage context and cost](/agents/operate/context-and-cost) covers what the static prefix and tool results cost per turn and how to keep them small. [Debug an agent run](/agents/operate/debugging) separates provider-side problems from operation failures.


---

# Install the custom-actions skill

> Give Claude Code or Codex a SuperDoc skill that authors custom actions correctly.




A skill is a Markdown instruction file a coding agent loads when a task matches it. Install `superdoc-custom-actions` when someone on the project will extend the action surface, so the agent writes an action that fits the SDK instead of inventing a shape around it.

Skills and MCP solve different problems. The [MCP server](/agents/mcp/connect) lets an agent edit DOCX files directly through tools. A skill teaches an agent how to write application code against `@superdoc/sdk` or `superdoc-sdk`. A project that does both installs both.

## Install [#install]

The skill lives in the open-source repository rather than inside the npm package, so it is installed from there with the `skills` CLI. Run this from your application's root directory:

```bash
npx skills add superdoc/docx-editor/packages/sdk/skills/superdoc-custom-actions --copy
```

`--copy` vendors the skill into your project so it is committed alongside your code. Add `-a <agent>` to install it for one supported coding agent instead of all of them.

Then ask for the operation you need:

> Add a custom action that inserts a footnote after a piece of text.

## What it carries [#what-it-carries]

The skill encodes the parts of the workflow an agent gets wrong unprompted:

* Choose the tier deliberately, and stay with `steps` when the built-in actions already express the operation.
* Namespace the action as `superdoc.<verb>` so it cannot collide with a built-in.
* Take arguments a model can actually produce, such as anchor text or an ordinal, and resolve low-level targets inside the action.
* Make a Python `run` action `async def` when the host drives an async client, because a synchronous body receives un-awaited coroutines.

It also carries verification discipline. The agent is told to validate every operation against the contract, then run the action against a real document and confirm the change independently rather than trusting a receipt. When no document is available it must label the result a draft. That rule is why the skill is worth installing rather than describing: an agent that cannot verify will otherwise present unverified work as finished.

Worked example packs ship next to the skill file, in both JavaScript and Python.

## Keep it current [#keep-it-current]

`--copy` vendors the file, so it does not update itself. The skill describes an API surface that changes between releases, so re-run the install as part of the change that bumps the SDK. Otherwise the agent follows instructions for a version you no longer run.

## Next [#next]

[Custom actions](/agents/build/custom-actions) is the reference this skill teaches. For agents that should edit documents rather than write code, connect the [MCP server](/agents/mcp/connect).


---

# Tools and presets

> Understand the action surface a model sees, and narrow it when a workflow should not reach every operation.



A preset is the tool surface a model sees: the tool definitions, the system prompt describing them, and the dispatcher that runs them. The SDK ships two.

## The core preset [#the-core-preset]

`preset: 'core'` advertises two tools:

| Tool                      | Purpose                                                            |
| ------------------------- | ------------------------------------------------------------------ |
| `superdoc_inspect`        | Read-only snapshots of current document state                      |
| `superdoc_perform_action` | One named, statically validated edit verb from the action registry |

Every edit runs through the second tool with an `action` argument naming what to do. The actions are grouped by what they touch: text and structure, lists and numbering, comments, tracked-change review, formatting, tables, and history. The [action reference](/agents/build/actions) lists each one with its arguments.

Two tools instead of one per action keeps the advertised surface small while the action enum stays explicit. The model picks a verb by name rather than assembling an operation, and an unknown verb is rejected before anything touches the document.

## Narrow the surface [#narrow-the-surface]

Pass `excludeActions` when a workflow should not reach part of the surface:

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'anthropic',
  preset: 'core',
  excludeActions: ['accept_tracked_changes', 'reject_tracked_changes'],
});
```

An agent that proposes edits but never resolves them is a common shape: it can suggest, and a person still decides.

Exclusions apply to all three pieces at once. The action leaves the tool enum, its documentation leaves the system prompt, and `dispatch` refuses it even if the model guesses the name. An unknown action name throws immediately rather than silently doing nothing, so a typo in an exclusion list surfaces at startup instead of in production.

`enforceChangeMode: 'tracked'` narrows the surface by policy instead of by name: every action that cannot record a tracked change is excluded the same way, every other action is forced to run tracked, and `allowDirectActions` reopens the direct-only actions a workflow still needs. [Build an agent](/agents/build/build-an-agent#do-not-rely-on-the-prompt-for-tracked-mode) covers it in full.

## Prompt caching [#prompt-caching]

Tool definitions and system prompts are stable across requests, so they cache well:

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const { tools, meta } = await createAgentToolkit({
  provider: 'anthropic',
  preset: 'core',
  cache: true,
});
```

`meta.cacheStrategy` reports what actually happened. Anthropic marks the tool block explicitly and reports `explicit`. OpenAI caches long prompts on its own and reports `automatic`. Vercel and generic providers pass through and report `unsupported`, because caching depends on the model underneath.

## The legacy preset [#the-legacy-preset]

`preset: 'legacy'` is the older surface: ten grouped intent tools, each taking an `action` argument, generated from the Document API contract.

It remains the default when `preset` is omitted, so code written before presets existed keeps working. One consequence is worth knowing:

* A `createAgentToolkit()` call with no `preset` gets legacy, not core.

Build new integrations on `core`. Use `legacy` when you already have one running on it, and see [Legacy tools](/agents/build/legacy-tools) for what it advertises and how to move.

## Replay a call without the model [#replay-a-call-without-the-model]

Any tool call the model makes is an ordinary SDK operation underneath. When output looks wrong, run the same operation directly:

```ts
const receipt = await dispatch(doc, 'superdoc_perform_action', {
  action: 'replace_text',
  find: 'termination',
  replaceWith: 'cancellation',
  changeMode: 'tracked',
});
```

If the direct call produces the right result, the operation is fine and the model chose or parameterized it badly. If it reproduces the problem, the operation is where to look. Separating those two cases first is the fastest way to stop debugging the wrong layer.

## Next [#next]

[Custom actions](/agents/build/custom-actions) adds a verb of your own to this surface. [Safety](/agents/operate/safety) covers the operational boundary around an agent. [Receipts and errors](/document-api/receipts-and-errors) explains the result contract a dispatched action returns. Reads and validation failures do not follow it: `superdoc_inspect` returns a snapshot with no `status`, and an invalid argument throws before any receipt exists.


---

# Connect a coding agent over MCP

> Install the SuperDoc MCP server so Claude Code, Cursor, Windsurf, or Claude Desktop can open, edit, and save DOCX files.





Use the MCP server when the agent already exists and you want it to work on DOCX files. It gives any [Model Context Protocol](https://modelcontextprotocol.io) client the same document engine the Editor and SDK use, without writing an agent loop of your own.

The client spawns the server as a local subprocess and talks to it over stdio. The server keeps each open document as an in-memory session, and writes your edited DOCX when the agent saves.

> **Diagram:** A coding agent talks to the SuperDoc MCP server over stdio. The server keeps each open DOCX as an in-memory session and reads and writes files on local disk only when the agent opens or saves.


## 1. Register the server [#1-register-the-server]

The package is `@superdoc/mcp`. It needs Node.js 20 or newer on the machine that runs the client. Use the configuration below for this walkthrough.

**Claude Code**

```bash
claude mcp add superdoc -e MCP_PRESET=core -- npx @superdoc/mcp
```

**Claude Desktop**

Add the server to `claude_desktop_config.json`. On macOS the file is at `~/Library/Application Support/Claude/claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "superdoc": {
      "command": "npx",
      "args": ["@superdoc/mcp"],
      "env": { "MCP_PRESET": "core" }
    }
  }
}
```

**Cursor**

Add the same entry to `~/.cursor/mcp.json`.

**Windsurf**

Add the same entry to `~/.codeium/windsurf/mcp_config.json`.

Restart the client after editing its configuration. It starts the server on the next conversation and lists the SuperDoc tools alongside its own.

## 2. Check the connection [#2-check-the-connection]

Open a conversation in your client and check its available tools. You should see `superdoc_open`, `superdoc_inspect`,
`superdoc_perform_action`, `superdoc_save`, and `superdoc_close`.

The configuration above selects the `core` tool set used in the next guide. Keep it for this walkthrough. If those tools
do not appear, follow [Debug the MCP server](/agents/mcp/debugging) before asking the agent to edit a document.

## 3. Choose a document to work on [#3-choose-a-document-to-work-on]

The server can access files allowed by the account running it. Give the agent the absolute path to the file and ask it
to save to a new, unused path. `superdoc_save` overwrites an existing file without asking, including an earlier result
when you repeat the task. A nonexistent input path opens a blank document, so check the path before editing.

The client can send document content to its model provider through tool results. Start with the synthetic sample in
the next guide. To restrict which files MCP can reach, run the server under a dedicated user, in a container with only
the working folder mounted, or in an OS sandbox. An instruction to the model does not enforce a filesystem boundary.
[Safety](/agents/operate/safety) covers the broader responsibilities of an agent workflow.

## Continue to your first edit [#continue-to-your-first-edit]

[Edit a DOCX from a coding agent](/agents/mcp/first-document-task) to make one tracked replacement, save a copy, and
review it in the embedded Editor.


---

# Debug the MCP server

> Inspect the SuperDoc MCP server directly, read its log, and recognize the failures that look like something else.




Most MCP problems fall into three groups: the client cannot start the server, the tool list is not what you expected, or a call fails against a session. Work out which group you are in before changing configuration.

## Call the server without a client [#call-the-server-without-a-client]

The MCP Inspector spawns the server the way a client would and lets you call each tool by hand from a browser:

```bash
MCP_PRESET=core npx @modelcontextprotocol/inspector -- npx @superdoc/mcp
```

Use it to confirm the registered tool list, call `superdoc_open` with an absolute path, and read a raw receipt. If a call works here and fails from the agent, the model is choosing or parameterizing the tool badly, and the fix is in the instruction rather than in the server.

To read the instructions the server sends the client, print them from the CLI:

```bash
superdoc preset get-mcp-prompt --preset core
```

## Read the server log [#read-the-server-log]

Standard output is reserved for the protocol, so everything the server logs goes to standard error with a level tag:

```text
[mcp:log]   Regular output
[mcp:info]  Informational messages
[mcp:debug] Debug details
[mcp:warn]  Warnings
```

Where that stream lands depends on the client. Claude Code shows it in the MCP server status view, and Claude Desktop writes it to its log directory. When nothing appears at all, the client usually never managed to spawn the process.

## The server does not start [#the-server-does-not-start]

| Symptom                                      | Cause                                                             | Fix                                                                                    |
| -------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Client reports the server exited immediately | `MCP_PRESET` set to something other than `legacy` or `core`       | The server exits with an unknown-preset message. Fix the value                         |
| Client reports a JSON parse error on connect | Something wrote to standard output before the protocol handshake  | Check for a dependency or shell wrapper that prints to stdout. Run under the inspector |
| `npx` cannot find the package                | Node.js older than 20, or no network access for the first install | Confirm `node --version` and install once with network access                          |

## The tool list is wrong [#the-tool-list-is-wrong]

The surface is decided at startup from `MCP_PRESET`. If the agent sees `superdoc_edit`, `superdoc_search`, and other grouped tools, the server is running the default `legacy` preset. If it sees `superdoc_inspect` and `superdoc_perform_action`, it is running `core`. Restart the client after changing the variable, because it only reads the configuration when it spawns the server.

Under `legacy`, each tool's exact action list is generated from the Document API contract and changes with it. Read the schema the server serves rather than a copy of it.

## A call fails [#a-call-fails]

Two kinds of failure reach the agent. A thrown error arrives as an error result whose text starts with the tool name, for example `superdoc_perform_action failed: Action delete_table is excluded by configuration.` A receipt with `status: "failed"` is a normal result that the action produced after resolving targets, and it carries `errors[].message` written for the model to act on.

| Message or receipt                                             | Cause                                                                    | Fix                                                                             |
| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `No open session with id "…". Use superdoc_open first.`        | The session was closed, or the id came from an earlier server process    | Open the document again. Session ids do not survive a restart                   |
| Inspect reports zero blocks on a document you know has content | The path did not exist, so `superdoc_open` created a blank document      | Use an absolute path and check the `filePath` in the open result                |
| `status: "failed"` with `MATCH_NOT_FOUND`                      | The target text is not in the document, or drifted after an earlier edit | Nothing changed. Re-inspect with `findText` and target the current wording      |
| `status: "partial"`                                            | Some edits in a batch applied and some did not                           | Read the per-edit counts in the receipt and retry only the skipped ones         |
| A tracked edit landed as a direct edit                         | `changeMode: "tracked"` was omitted, or the action ignores it            | Check the tool call arguments and the [action reference](/agents/build/actions) |
| `Unknown tool` under `core`                                    | The model used a `legacy` tool name from an older conversation           | Start a fresh conversation so the model reads the current tool list             |

`superdoc_inspect` returns a snapshot, not a receipt. It has no `status`, so a client-side check that expects one on every result misreads every successful read as a failure.

## The file on disk is not what you expected [#the-file-on-disk-is-not-what-you-expected]

`superdoc_save` writes the resolved `out` path, or the original path when `out` is omitted, and replaces whatever is there. If the source changed when you asked for a copy, the agent omitted `out` or passed the source path. Ask for the destination explicitly and keep the source under version control or a backup while iterating on instructions.

## Next [#next]

[Debug an agent run](/agents/operate/debugging) covers the same separation of model mistakes from operation failures for agents built on the SDK, including the error codes the dispatcher throws.


---

# Edit a DOCX from a coding agent

> Make one tracked edit with your coding agent, save a copy, and review the result in the Editor.



Use your [connected coding agent](/agents/mcp/connect) to replace a term in a sample contract and save a copy.
The edit will be a tracked change: a proposal you can accept or reject after seeing it in the document.

## 1. Prepare the sample [#1-prepare-the-sample]

Download the synthetic NDA and save it as `contract.docx` in a folder your agent can access. It contains the term
`termination` and one existing tracked change.

[Download the sample contract](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


Find the file's absolute path. For example, a macOS path might be `/Users/me/docs/contract.docx`.
Use your actual path in the next step. A wrong path can open a blank document instead of the sample.

## 2. Ask for an edit [#2-ask-for-an-edit]

Give the agent this instruction, replacing both paths with yours. Choose an output filename that does not already
exist: MCP overwrites an existing output without asking. Use a new filename when repeating the task.

> Open `/Users/me/docs/contract.docx` with SuperDoc. Replace every occurrence of "termination" with "cancellation" as a tracked change. Save the result to `/Users/me/docs/contract.reviewed.docx` and close the session. Do not overwrite the original.

Watch the tool calls in your client. The agent should open and inspect the document, make the replacement, save the new
file, and close it. Opening creates a session: the working document that subsequent tool calls read or change.

If a tool reports a failure or the agent cannot find the term, stop and check the path and result before retrying.
[Debug the MCP server](/agents/mcp/debugging) explains common failures.

## 3. Review your saved copy [#3-review-your-saved-copy]

Expand the Editor below. Select **Open your DOCX** and choose `contract.reviewed.docx` from the previous step.
This opens your saved output for review; the embedded Editor does not run the agent or connect to your model provider.

> **Interactive editor: Review your agent’s edited DOCX**
>
> Sample: [open the fixture](/fixtures/tracked-changes.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: select a marked proposal and use the built-in toolbar to accept or reject it. Reset the sample to compare both decisions.
>
> Local DOCX selection: enabled. Files remain in the browser.


The initial sample is the original NDA, not an agent result. Load your saved copy to check your run.
Find the replacements: `termination` should be marked as deleted and `cancellation` as inserted. The sample's existing
tracked change should still be present. Your original `contract.docx` should remain unchanged.

Try accepting or rejecting a replacement with the review controls. This changes the browser preview; it does not write
back to your saved copy. To save your review decisions, open `contract.reviewed.docx` in Microsoft Word and review it there.

## What happened behind the edit [#what-happened-behind-the-edit]

The model chose a replacement tool call. SuperDoc applied it to the open document and returned a **receipt**, a
structured result describing the operation. The agent then saved the document to the requested output path.

In the client, find the `superdoc_perform_action` call. Its arguments should include `action: "replace_text"` and
`changeMode: "tracked"`. The latter records the replacement as a proposal instead of a direct edit.

The result should report `status: "ok"`. If it includes `verificationPassed`, that should be `true`. These checks help
confirm that the operation ran, but the document review is how you check that it did what you intended.

For the complete result fields and failure handling, see [Read the receipts](/agents/build/build-an-agent#read-the-receipts).
You do not need the full action reference to repeat this task with another term.

## Continue to a review workflow [#continue-to-a-review-workflow]

[Review tracked changes](/agents/workflows/review-tracked-changes) explains how to keep an automated proposal separate
from a person's final decision. Keep the original, proposed copy, and reviewed output as separate files.


---

# Manage context and cost

> Keep the static prefix cached, keep inspect results small, and narrow the surface so a run fits its token budget.




Every model turn resends the tool definitions, the system prompt, and the whole conversation so far. The core system prompt is long by design, because it teaches document vocabulary the schema cannot, and every tool result stays in history for the rest of the run. Left alone, a document-editing loop grows its prompt on every turn and can hit per-minute token limits within a few tool calls.

Three levers keep that in check. Cache what repeats, shrink what the model reads, and advertise only what the workflow needs.

## Cache the static prefix [#cache-the-static-prefix]

Tool definitions and the system prompt do not change between requests, so build the toolkit once at startup and reuse it across conversations:

```ts
import { createAgentToolkit } from '@superdoc/sdk';

let toolkit: Awaited<ReturnType<typeof createAgentToolkit>> | undefined;

export async function getToolkit() {
  toolkit ??= await createAgentToolkit({ provider: 'anthropic', preset: 'core', cache: true });
  return toolkit;
}
```

`cache: true` asks the preset for provider-specific cache markers, and `meta.cacheStrategy` reports what happened:

| Provider    | `cacheStrategy` | What the SDK did                                                        |
| ----------- | --------------- | ----------------------------------------------------------------------- |
| `anthropic` | `explicit`      | Marked the tool array with `cache_control` so the tools block is cached |
| `openai`    | `automatic`     | Nothing. The provider caches long prompts on its own                    |
| `vercel`    | `unsupported`   | Nothing. Caching depends on the model behind the adapter                |
| `generic`   | `unsupported`   | Nothing                                                                 |

For Anthropic, the system prompt is the other half of the prefix. Fetch it with `getSystemPromptForProvider({ provider: 'anthropic', preset: 'core', cache: true })` and pass its `content` as the `system` parameter. [Connect a model provider](/agents/build/providers#anthropic) shows both together. A cache is a prefix match, so anything that varies per request, such as a timestamp or a document name, belongs after the toolkit prompt rather than inside it.

## Inspect narrowly [#inspect-narrowly]

`superdoc_inspect` is where most tokens go, because the model is tempted to read the whole document. The system prompt already steers it toward small reads. Reinforce that in your appended instructions when documents are long, and know what the arguments do:

* `countsOnly: true` for orientation.
* `includeDomains` to fetch only the domains the task touches.
* `findText` to locate a phrase server-side instead of paging windows to find it.
* `blockOffset` and `blockLimit` for sequential reading. Ordinals are absolute, so windows line up.
* `omitEmptyBlocks`, `dropTextPreview`, and `blockTextLimit` to trim a reading pass.
* `includeListItemRuns: false` when list formatting does not matter, since runs are attached by default.

The [action reference](/agents/build/actions#superdoc_inspect) lists every argument.

## Batch with arguments, not calls [#batch-with-arguments-not-calls]

Several actions take a batch argument so one call covers many targets. `replace_text` takes `edits[]`, `add_comments` takes `selectors[]`, `format_text` takes `targetTexts[]`, and `delete_blocks` takes `selectors[]`. One call means one receipt in history instead of many.

## Narrow the surface [#narrow-the-surface]

`excludeActions` removes an action from the tool enum, from the system prompt, and from dispatch together. A product that never deletes tables or fills placeholders should say so once:

```ts
const toolkit = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
  excludeActions: ['delete_table', 'fill_placeholders'],
});
```

A smaller surface is cheaper on every turn and gives the model fewer wrong choices. [Tools and presets](/agents/build/tools#narrow-the-surface) covers the mechanics.

## Bound the loop and the history [#bound-the-loop-and-the-history]

Cap turns explicitly, as [Build an agent](/agents/build/build-an-agent#keep-the-loop-bounded) does, so a confused model produces an error rather than an exhausted budget. When a single run legitimately needs many turns, compact history by removing whole exchanges: the assistant message that made the tool calls together with every tool result that answered it, replaced by one plain assistant or user message summarizing what happened. Removing a result while its call remains, or the reverse, produces a conversation the provider rejects. Never drop the system prompt or the tool definitions.

Expect rate limiting on low provider tiers, and treat a 429 as a retry with backoff rather than a failure of the run. Plan for it before the first production document rather than after.

## Next [#next]

[Debug an agent run](/agents/operate/debugging) covers what to do when a loop repeats itself. [Safety](/agents/operate/safety) covers the boundaries that matter once cost is under control.


---

# Debug an agent run

> Separate model mistakes from operation failures, read dispatcher errors by code, and trace a run without logging document content.




A model-driven edit can go wrong in two places. The model can choose or parameterize the wrong tool, or the operation can fail against the document. They need different fixes, and most debugging time is lost working on the wrong one.

## Decide which layer failed [#decide-which-layer-failed]

Every tool call is an ordinary SDK operation underneath. Run the same call without the model:

```ts
const receipt = await dispatch(doc, 'superdoc_perform_action', {
  action: 'replace_text',
  edits: [{ find: 'termination', replace: 'cancellation' }],
  changeMode: 'tracked',
});
```

If the direct call produces the right result, the operation is fine and the model chose or parameterized it badly. Look at the instruction, the system prompt, and whether the tool list the model saw matches the dispatcher. If the direct call reproduces the problem, the operation or the document is where to look, and [Receipts and errors](/document-api/receipts-and-errors) covers that contract.

The pre-bound `dispatch` from `createAgentToolkit` cannot mismatch its preset. The standalone `dispatchSuperDocTool` defaults to `legacy`, so a replay that omits `{ preset: 'core' }` fails with an unknown tool rather than reproducing anything.

## Read what dispatch returns [#read-what-dispatch-returns]

Three outcomes come back from a dispatch, and code that checks only `status` mishandles two of them:

| Outcome                   | Shape                               | What it means                                                          |
| ------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| Snapshot                  | Object without `status`             | `superdoc_inspect` succeeded. Nothing changed                          |
| Receipt                   | Object with `status`                | The action ran. `ok`, `partial`, `failed`, or `aborted`                |
| Thrown `SuperDocCliError` | Exception with `code` and `details` | Validation or transport failed before, or independently of, the action |

A receipt that says `failed` is not proof that nothing changed. An action can apply its operation and then fail its own post-check. Compare `preSnapshot.revision` with `postSnapshot.revision` before retrying, or the retry applies the edit twice. `MATCH_NOT_FOUND` in `errors[]` is the exception: the target was not in the document and nothing was touched, so the model can re-inspect and try again safely.

## Error codes [#error-codes]

Thrown errors and `errors[].code` share one vocabulary. The codes an agent loop meets most often:

| Code                      | Where   | Meaning                                                                                                                                                                                          | Next step                                                        |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `INVALID_ARGUMENT`        | Thrown  | Missing, unknown, or malformed argument. `details.excluded: true` means a narrowed surface refused it, and `details.reason` says which rule: `excluded`, `direct-only`, or `enforce-change-mode` | Return it to the model as a tool result. It can correct the call |
| `TOOL_DISPATCH_NOT_FOUND` | Thrown  | The tool name is unknown to the selected preset                                                                                                                                                  | Fix the preset pairing, or reject a hallucinated name            |
| `MATCH_NOT_FOUND`         | Receipt | Target text or element not found. Nothing changed                                                                                                                                                | Re-inspect and target the current wording                        |
| `TARGET_NOT_FOUND`        | Receipt | A resolved block disappeared from the snapshot before the edit                                                                                                                                   | Re-inspect. Treat as a stale target                              |
| `ACTION_FAILED`           | Receipt | The action could not complete, for example a required operation is unavailable on this handle                                                                                                    | Read `errors[].message`. Check the revisions before retrying     |
| `PRESET_NOT_FOUND`        | Thrown  | An unknown preset id                                                                                                                                                                             | Use `listPresets()` to see what is registered                    |
| `DOCUMENT_CLOSED`         | Thrown  | The handle was closed before the call                                                                                                                                                            | Reopen. Usually a cleanup path ran early                         |
| `HOST_HANDSHAKE_FAILED`   | Thrown  | The embedded runtime could not start                                                                                                                                                             | Environment problem. See below                                   |
| `HOST_DISCONNECTED`       | Thrown  | The runtime exited mid-call                                                                                                                                                                      | Environment problem. The session is gone                         |
| `HOST_TIMEOUT`, `TIMEOUT` | Thrown  | The runtime did not answer in time                                                                                                                                                               | Retry once with a fresh session. Check document size             |

Only the first two are safe to hand back to the model without inspection. A thrown transport error means the document session is in an unknown state and the run should stop.

## The runtime will not start [#the-runtime-will-not-start]

`HOST_HANDSHAKE_FAILED` and `HOST_DISCONNECTED` have several distinct causes. Check them in order:

1. **Bundling removed the runtime.** The SDK loads a native runtime from a platform package installed as an optional dependency. In Next.js, list `@superdoc/sdk` in `serverExternalPackages` so the bundler leaves it alone. Other bundlers need the equivalent external setting.
2. **The binary is blocked.** On macOS, a quarantined download is killed at launch. On locked-down hosts, an execution policy can do the same. The SDK reports the exit rather than the reason, so check the platform's own logs.
3. **Unsupported platform.** Published runtimes cover macOS on Apple Silicon and Intel, Linux on ARM64 and x64, and Windows on x64. An `UNSUPPORTED_PLATFORM` error at connect time names the missing target.
4. **The runtime crashed on a document.** Reproduce with the SDK alone, with no model involved, and open the document by itself first.

## Log the run without logging the document [#log-the-run-without-logging-the-document]

Log tool names, action names, receipt `status`, `verificationPassed`, the two revisions, and error codes. Do not log arguments or full receipts. Arguments carry the text the model is inserting and receipts carry text previews, and both end up in log storage that has none of the protections the document has.

```ts
const args = JSON.parse(call.function.arguments);
console.log(`[agent] ${call.function.name}${args.action ? `:${args.action}` : ''}`);

const result = await dispatch(doc, call.function.name, args);
if (typeof result === 'object' && result !== null && 'status' in result) {
  const receipt = result as {
    status: string;
    verificationPassed?: boolean;
    preSnapshot?: { revision?: string };
    postSnapshot?: { revision?: string };
  };
  console.log(
    `[agent] ${receipt.status} verified=${receipt.verificationPassed ?? 'n/a'} ${receipt.preSnapshot?.revision}→${receipt.postSnapshot?.revision}`,
  );
}
```

For a full trace during development, set `SUPERDOC_SDK_DEBUG_TRACE=1`. The SDK appends one JSON line per runtime request and preset dispatch to `.superdoc-sdk-traces/sdk-trace-<pid>.jsonl` in the working directory, or under `SUPERDOC_SDK_DEBUG_TRACE_DIR`. Those traces include arguments, so they carry document content. Turn the variable off outside development and delete the directory afterwards.

## Common failure modes [#common-failure-modes]

| Symptom                                        | Cause                                                                         | Fix                                                                                  |
| ---------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Model calls a tool that does not exist         | Prompt from one preset paired with tools from another, or a hallucinated name | Build all three pieces with `createAgentToolkit`. Reject names you did not advertise |
| Model never calls a tool                       | `tools` not passed to the provider call, or a provider shape mismatch         | Check `meta.provider` matches the client you are calling                             |
| Same failing action repeats until the turn cap | The model cannot read the failure                                             | Return errors as tool results, not exceptions, and include `errors[].message`        |
| Edit landed directly when tracked was asked    | `changeMode` omitted, or the action ignores it                                | Enforce the allowlist from the [action reference](/agents/build/actions#changemode)  |
| `partial` receipts on batch actions            | Some targets matched and some did not                                         | Read `editsApplied` and `editsSkipped`, then retry only the skipped targets          |
| Output file identical to input                 | The model decided the work was done, or every action was a dry run            | Count mutations by comparing revisions, and refuse to save when there are none       |
| Works in a script, fails in the server         | The runtime was bundled away or blocked                                       | See the runtime section above                                                        |

## Next [#next]

The [MCP debugging page](/agents/mcp/debugging) covers the same ground for coding agents connected over MCP. [Manage context and cost](/agents/operate/context-and-cost) explains the token pressure that makes a confused model loop.


---

# Safety

> Operational boundaries to settle before an agent edits documents that matter.



An agent makes non-deterministic choices against real files. The engine runs each operation deterministically and reports what happened, but nothing stops a model from confidently choosing the wrong operation. These boundaries keep that failure recoverable.

## Prefer tracked changes for consequential edits [#prefer-tracked-changes-for-consequential-edits]

Set `changeMode: 'tracked'` when an edit changes meaning rather than formatting. The edit becomes a suggestion a person can accept or reject, so a wrong call costs a rejection instead of a restore.

The argument is optional and defaults to a direct edit, so asking for tracked mode in the prompt is not enough. When a model chooses the arguments, check for `changeMode: 'tracked'` before dispatching and refuse the call without it.

Check the action too. Not every action honors `changeMode` — `apply_style`, `set_paragraph_spacing`, and `insert_page_break` ignore it and always edit directly, while `move_range` declares it but rejects a tracked request rather than applying an untracked edit. The tool schema accepts the argument in every case. An allowlist of tracked-capable actions is the only reliable guard; without one, a run that promised reviewable suggestions can quietly rewrite the document.

Treat a successful receipt as a claim, not proof. Actions that support `dryRun` report success while applying nothing, so compare the receipt's before and after revisions when you need to know a change actually landed.

Direct edits are appropriate for mechanical work: normalizing fonts, fixing spacing, filling known placeholders. Reserve them for cases where being wrong is cheap.

## Write to a separate output [#write-to-a-separate-output]

Save to a new path and keep the source until the result is verified:

```ts
await doc.save({ out: 'contract.reviewed.docx' });
await doc.close({ discard: true });
```

`discard: true` closes the in-memory session without writing back to the source. Overwriting the input removes the only copy of what the document looked like before the agent ran.

Leave `force` off. Without it, the SDK's `save` refuses a path that already exists, so a typo in the output name fails instead of destroying whatever was there. Add it only where overwriting a known artifact is the intended behavior, such as a scheduled job that rewrites its own output each run. When the path is model-supplied or assembled from input, check that it does not resolve to the source before saving.

## Bound the loop [#bound-the-loop]

Cap turns explicitly. A model that misreads a receipt can retry the same failing action indefinitely, and an uncapped loop turns that into an exhausted token budget rather than an error.

Bound retries after a stale revision failure too, and re-query before retrying. A target resolved against an older revision may no longer point where the model thinks it does.

## Inspect receipts instead of assuming success [#inspect-receipts-instead-of-assuming-success]

A dispatch that returns is not a dispatch that worked. Check `status` on every receipt, and treat `partial` as failure that needs handling: some edits applied and some did not, which is the state most likely to be silently shipped.

`failed` needs the same care. An action can apply its operation and then fail its own post-check, so a failed receipt can sit on top of a document that already changed. Compare `preSnapshot.revision` with `postSnapshot.revision` before retrying, or the retry may apply the edit a second time.

When `verificationPassed` is `false`, at least one post-check disagreed with the intent. That does not tell you whether anything changed: it covers an edit that landed wrongly and an edit that never applied at all, because the standard `revision-changed` check also fails when a mutation turns out to be a no-op. Read `preSnapshot.revision` against `postSnapshot.revision`, and `executedOperations`, to find out which happened. Surface it either way rather than swallowing it.

> **Two different failures (warning)**
>
> A receipt reporting `failed` is an operation problem. A successful receipt for an edit nobody wanted is a model
> problem. They need different fixes, so separate them before debugging.


Receipts also cannot tell you whether the agent finished the job. They report what each call did, not whether the set of calls covered your instruction, and nothing links a retry to the request it repairs. A run where every receipt is clean can still have dropped an edit the model asked for and then abandoned.

When completeness has to be asserted without a reviewer, decide the required edits before the run, give each one a stable id, and check them off as receipts arrive. Otherwise treat a clean run as a draft worth reviewing, not as proof the instruction was carried out.

## Keep a human in the loop [#keep-a-human-in-the-loop]

Decide up front which operations an agent may complete alone. Excluding the review actions is a practical default: the agent proposes, a person decides.

```ts
import { createAgentToolkit } from '@superdoc/sdk';

const toolkit = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
  excludeActions: ['accept_tracked_changes', 'reject_tracked_changes'],
});
```

Exclusions apply to the tools, the prompt, and the dispatcher together, so an excluded action is refused even if the model guesses its name.

Naming actions one by one works when you know which ones worry you. When the requirement is that a person sees every change, name the policy instead:

```ts
const toolkit = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
  enforceChangeMode: 'tracked',
  allowDirectActions: ['add_comments'],
});
```

`enforceChangeMode: 'tracked'` is fail-closed. Every action that cannot record a tracked change is removed from the surface and refused at dispatch, and every action that can is forced to run tracked whatever the call asked for. The difference matters: an exclusion list protects against the actions you thought of, while the policy protects against the ones you did not, including actions added in a later SDK release. `allowDirectActions` reopens the ones a workflow genuinely needs, and receipts report `changeMode` with `changeModeForced` so a log shows which calls were upgraded. [Build an agent](/agents/build/build-an-agent#do-not-rely-on-the-prompt-for-tracked-mode) covers the option in full.

## Do not log document contents [#do-not-log-document-contents]

Documents carry contract terms, personal data, and unreleased material. Log operation ids, action names, receipt statuses, and error codes. Do not log document text, full mutation payloads, or complete receipts, and be deliberate about what reaches a model provider: content sent for a decision leaves your infrastructure.

## Attribute every change [#attribute-every-change]

Give the client an explicit user identity so tracked changes and comments carry a real author:

```ts
import { createSuperDocClient } from '@superdoc/sdk';

const client = createSuperDocClient({ user: { name: 'Contract bot' } });
```

Omitting it does not leave the author blank. Edits are attributed to a generic `CLI` author, which every unattributed workflow shares, so a reviewer opening a document touched by two automations cannot tell which one proposed what. Author-based accept and reject operations cannot separate them either.

Give each automation its own name for the same reason. A shared identity copied between deployments recreates the problem the identity was meant to solve.

A reviewer needs to see that a machine proposed an edit, and which machine it was.

## Handle files the engine cannot open [#handle-files-the-engine-cannot-open]

Validate input paths and file types before opening a session. Encrypted or password-protected documents fail at open, so handle that case explicitly rather than letting it surface as an unexplained crash mid-run.

## Close sessions on every path [#close-sessions-on-every-path]

Sessions hold a managed runtime. Close the document and dispose the client in `finally` so success, failure, and cancellation all release it:

```ts
try {
  // open, mutate, save
} finally {
  if (doc) await doc.close({ discard: true }).catch(() => {});
  await client.dispose().catch(() => {});
}
```

Make cleanup best-effort. A close failure that throws will mask the error that actually ended the run.

## Treat tool calls as untrusted input [#treat-tool-calls-as-untrusted-input]

A model chooses tool names from what it was shown, but nothing guarantees it stays there. It can invent a name, and it can be persuaded toward one by text inside the document it is editing.

The SDK dispatcher accepts several tool names the toolkit never advertises, including `superdoc_execute_code` and the `agent_*` surfaces. Those exist for SDK callers and bypass the checks a model-facing loop relies on. Validate the tool name against the list you advertised before dispatching, and reject anything else rather than passing it through.


---

# Review tracked changes

> Create a tracked DOCX edit in code, review it in the embedded editor, and export the decision.





Use tracked changes when code or an agent should propose an edit without making the final decision. This workflow creates a reviewable DOCX with the Node.js SDK, opens that exact file in the editor, and keeps the final decision with a person.

> **Diagram:** Code creates a tracked edit in a DOCX file, a person reviews it in the embedded editor, and the editor exports the final DOCX.


## 1. Prepare the source document [#1-prepare-the-source-document]

Download the synthetic NDA and save it as `contract.docx`. It contains the word `termination` and one existing tracked change.

[Download the tracked-changes fixture](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


Install the SDK in an empty Node.js project:

```bash
pnpm add @superdoc/sdk@latest
```

## 2. Create a tracked replacement [#2-create-a-tracked-replacement]

Create `propose-change.mjs` next to `contract.docx`:

```mjs
import { SuperDocClient } from '@superdoc/sdk';

/** @param {unknown} value */
function isSuccessfulReceipt(value) {
  return typeof value === 'object' && value !== null && 'success' in value && value.success === true;
}

const client = new SuperDocClient({
  user: { name: 'Contract assistant', email: 'assistant@example.com' },
});

try {
  await client.connect();
  const doc = await client.open({ doc: './contract.docx' });

  try {
    const match = await doc.query.match({
      select: { type: 'text', pattern: 'termination' },
      require: 'first',
    });
    const result = match.items[0];

    if (!result || result.matchKind !== 'text') {
      throw new Error('The source document does not contain “termination”.');
    }

    const operation = await doc.replace({
      target: result.target,
      text: 'cancellation',
      changeMode: 'tracked',
    });

    console.log(operation);
    const receipt = 'receipt' in operation ? operation.receipt : operation;
    if (!isSuccessfulReceipt(receipt)) throw new Error('Creating the tracked change failed.');
    await doc.save({ out: './contract.suggested.docx', force: true });
  } finally {
    await doc.close({ discard: true });
  }
} finally {
  await client.dispose();
}

```

The query returns a document-native target. Passing that target to `replace()` avoids deriving an edit location from rendered HTML or copied character offsets. `changeMode: 'tracked'` records the replacement as a suggestion. The resolved operation result contains receipt information for inspection. Check it before saving in production workflows.

**Receipt `replace`**: replacement recorded in tracked mode


## 3. Produce the review file [#3-produce-the-review-file]

Run the script:

```bash
node propose-change.mjs
```

The script writes `contract.suggested.docx` and leaves `contract.docx` unchanged. Saving to a separate path does not overwrite the open source session, so the final close explicitly discards the in-memory working state after the output is safely written.

> **Automation checkpoint (success)**
>
> Open `contract.suggested.docx` and confirm that the heading shows a tracked replacement from `Termin` to `cancell`.
> Accepting that change should make the complete word read `cancellation`.


## 4. Review the exact output [#4-review-the-exact-output]

Select **Open your DOCX** below and choose `contract.suggested.docx`. The file opens locally in the browser. The documentation site does not upload it.

> **Interactive editor: Review the suggested DOCX**
>
> Sample: [open the fixture](/fixtures/tracked-changes.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: select a marked proposal and use the built-in toolbar to accept or reject it. Reset the sample to compare both decisions.
>
> Local DOCX selection: enabled. Files remain in the browser.


Use the editor review controls to accept or reject each tracked change. The sample document is always available if you want to inspect the review experience before running the script.

## 5. Export the decision [#5-export-the-decision]

Export the reviewed document as DOCX. Reopen it in Word or SuperDoc and verify that the accepted text remains, rejected text is restored, and the surrounding formatting is intact.

> **Verification target (success)**
>
> The final DOCX should reflect the reviewer’s decisions. The original source and the proposed review file should remain
> available as separate artifacts.


The same query, target, mutation, and receipt contract works in both hosts. Read the [Document API mental model](/document-api/mental-model) for the boundary behind this workflow.


---

# Add comments to the Editor

> Let people create, reply to, and resolve comments that stay in the DOCX.



Comments are enabled by default. Provide the current user so new comments keep the correct author, then choose how the
comments UI adapts to the Editor width. For the thread lifecycle and what gets saved, start with
[Comments](/editor/comments).

## Try the comment workflow [#try-the-comment-workflow]

Expand the Editor and click `September 30, 2026` to open its comment. Add a reply, then use the controls above the document:

1. Change **Layout** between Auto, Sidebar, and Inline to compare how the comment surface uses the Editor width.
2. Change **Actions** to Read. Your reply remains, but you cannot add another. Restore Write or Resolve to reply again.
3. With **Actions → Resolve**, choose the checkmark on the thread. Click `September 30, 2026` again to see its
   **Resolved** status, then choose **Reopen comment**.

> **Interactive editor: Try comments**
>
> Sample: [open the fixture](/fixtures/comments-sample.docx).
>
> Preset: `comments`.
>
> Comment configurations available in the interactive Editor:
>
> - **Layout — `ui.comments.layout`:** choose `auto`, `sidebar`, or `inline`. Auto selects sidebar or inline from the Editor width.
> - **Actions — `interaction.comments.level`:** choose `read`, `write`, or `resolve`. Read shows threads without mutation controls. Write adds create, reply, edit, and delete. Resolve also adds resolve and reopen.
>
> The sample contains one comment thread anchored to `September 30, 2026`.
>
> Local DOCX selection: disabled.


Changing either configuration reloads the current DOCX because these are startup options. Thread changes remain; the
open comment and selection reset. The demo changes only the document in this browser. Your application saves those
changes by exporting the DOCX through the same flow you built in [Load and save](/editor/load-and-save-documents).

## Add the built-in comments UI [#add-the-built-in-comments-ui]

These standalone examples use `public/sample.docx` from the [Quickstart](/editor/quickstart). Replace `src/main.ts`
or `src/App.tsx` to try the current user and comments layout:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  user: {
    name: 'Alex Rivera',
    email: 'alex@example.com',
  },
  ui: {
    toolbar: { container: '#toolbar' },
    comments: {
      layout: 'auto',
    },
  },
});

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const editorConfig = {
  user: {
    name: 'Alex Rivera',
    email: 'alex@example.com',
  },
  ui: {
    comments: {
      layout: 'auto',
    },
  },
} satisfies Pick<SuperDocEditorProps, 'user' | 'ui'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' user={editorConfig.user} ui={editorConfig.ui} />;
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar and Editor mounts below:

```html
<div id="toolbar"></div>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

Select text and add a comment. The thread should show Alex Rivera as its author. Reply, resolve, and reopen actions are
available by default.

## Configure comments [#configure-comments]

Choose a group, then choose a field. Each entry shows its type, default, and a configuration fragment you can copy.

### Layout

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `ui.comments.layout` | `"auto" \| "sidebar" \| "inline"` | `'sidebar'` | Optional | Place threads in a sidebar, inline with the document, or according to available width. | Where comment threads render (default: `'sidebar'`). `auto` uses the available width to choose between sidebar and inline. | — |

### Responsive

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `ui.comments.responsive.target` | `string \| HTMLElement` | — | Optional | Measure this element when layout is auto. | Element whose width controls the layout. Pass an element or a CSS selector. Defaults to the nearest measurable Editor ancestor. | — |
| `ui.comments.responsive.breakpoint` | `number` | — | Optional | Switch to inline threads below this width when layout is auto. | Switch from sidebar to inline below this width, in CSS pixels. When omitted, SuperDoc derives the threshold from the document and sidebar. | — |

### Actions

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `interaction.comments.level` | `"read" \| "write" \| "resolve"` | `'resolve'` | Optional | Allow reading only, writing comments, or resolving and reopening threads. | The highest comment interaction level this Editor allows (default: `resolve`). `read` allows reading threads only. `write` also allows create, reply, edit, and delete. `resolve` also allows resolve and reopen. | — |


Use `layout: 'auto'` to switch between sidebar and inline threads according to the available width. Use
`interaction.comments.level: 'write'` when people may participate in a thread but your application keeps the final
resolve decision.

The comment level does not control tracked-change decisions. Configure those in
[Track changes](/editor/track-changes).

These options change browser interaction; they are not an authorization boundary. Enforce document access and comment
permissions in a trusted backend.

## Verify the round trip [#verify-the-round-trip]

1. Create a comment and reply to it.
2. Resolve or reopen the thread.
3. Use the export and reopen flow from [Load and save](/editor/load-and-save-documents); the standalone examples above
   only configure comments.

The thread, replies, author, and status should remain in the file.

Use [custom comments UI](/editor/custom-ui/comments) when your application should render the thread list or composer. Use
[Document API comments](/document-api/comments) when code needs to create or update comments directly.


---

# Configure the built-in toolbar

> Show only the controls your workflow needs and keep them reachable as the Editor narrows.



Choose which built-in controls appear without building a toolbar yourself. Keep your existing document loading and
saving code; this page changes only the toolbar configuration.

## Try the toolbar configurations [#try-the-toolbar-configurations]

Expand the Editor and switch between the three configurations:

1. **Focus** shows only the controls named in `items`, placed in the left, center, and right regions.
2. **Remove** starts with the default toolbar and removes Bold and Italic with `excludeItems`.
3. **Add** keeps the focused toolbar and appends an **Add note** action with `customItems`. Place the caret in the
   document, then run it to insert `Review note: `.

> **Interactive editor: Shape the built-in toolbar**
>
> Sample: [open the fixture](/fixtures/getting-started.docx).
>
> Preset: `toolbar`.
>
> Toolbar configurations available in the interactive Editor:
>
> - **Focus — `ui.toolbar.items`:** show only undo, redo, bold, italic, underline, link, document-mode, zoom across the left, center, and right regions.
> - **Remove — `ui.toolbar.excludeItems`:** start with the default toolbar and remove bold and italic.
> - **Add — `ui.toolbar.customItems`:** add an **Add note** action to the focused toolbar. Place the caret in the document and run it to insert `Review note: `.
>
> Changing a toolbar configuration recreates the Editor from its current DOCX. Document edits and document mode remain; transient selection and toolbar state reset.
>
> Local DOCX selection: disabled.


Switching configurations recreates the Editor from its current DOCX state because toolbar composition is a startup
option. Edits and document mode remain; the current selection resets.

## Build the focused toolbar [#build-the-focused-toolbar]

Start with Undo, Redo, Bold, Italic, and Zoom. Add the matching configuration beside your Editor setup. In React, keep
it outside the component so rerenders do not recreate the Editor.

**Vanilla — `src/main.ts`**

```ts
import type { ToolbarConfig } from 'superdoc';

export const toolbar = {
  container: '#toolbar',
  items: {
    left: ['undo', 'redo'],
    center: ['bold', 'italic'],
    right: ['zoom'],
  },
  responsiveTo: 'container',
} satisfies ToolbarConfig;

```

**React — `src/App.tsx`**

```tsx
import type { ToolbarConfig } from '@superdoc/react';

const toolbar = {
  items: {
    left: ['undo', 'redo'],
    center: ['bold', 'italic'],
    right: ['zoom'],
  },
  responsiveTo: 'container',
} satisfies ToolbarConfig;

export const ui = { toolbar };

```


In Vanilla, add `<div id="toolbar"></div>` before your Editor mount and pass `ui: { toolbar }` to `new SuperDoc()`.
In React, pass `ui={ui}` to `SuperDocEditor`; the wrapper creates the toolbar mount. If you already configure `ui`,
keep its other fields and replace only `toolbar`.

Reload, select text, and choose **Bold**. The five controls should be visible or reachable through the overflow menu
at narrow widths. Your existing save or export button stays separate.

## Add images and tables (optional) [#add-images-and-tables-optional]

The following standalone example uses `/sample.docx` from the [Quickstart](/editor/quickstart). It replaces the Editor
setup to demonstrate image uploads and table controls; it does not include your backend save flow.

For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar and Editor mounts below:

```html
<div id="toolbar"></div>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

React's `SuperDocEditor` creates the toolbar mount for you. Replace the matching file:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc, type ToolbarConfig } from 'superdoc';
import 'superdoc/style.css';

const toolbar = {
  container: '#toolbar',
  items: {
    left: ['undo', 'redo'],
    center: ['bold', 'italic', 'underline', 'link', 'image', 'table', 'table-actions'],
    right: ['document-mode', 'zoom'],
  },
  responsiveTo: 'container',
} satisfies ToolbarConfig;

function withImageMimeType(file: File): Blob {
  const type = file.type.toLowerCase();
  if (type === 'image/png' || type === 'image/jpeg' || type === 'image/jpg') return file;
  if (type) throw new Error('Choose a PNG or JPEG image.');
  if (/\.png$/i.test(file.name)) return file.slice(0, file.size, 'image/png');
  if (/\.jpe?g$/i.test(file.name)) return file.slice(0, file.size, 'image/jpeg');
  throw new Error('Choose a PNG or JPEG image.');
}

function handleImageUpload(file: File): Promise<string> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(String(reader.result));
    reader.onerror = () => reject(reader.error ?? new Error('Could not read image.'));
    reader.readAsDataURL(withImageMimeType(file));
  });
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  handleImageUpload,
  ui: { toolbar },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type SuperDocRef, type ToolbarConfig } from '@superdoc/react';
import '@superdoc/react/style.css';

const toolbar = {
  items: {
    left: ['undo', 'redo'],
    center: ['bold', 'italic', 'underline', 'link', 'image', 'table', 'table-actions'],
    right: ['document-mode', 'zoom'],
  },
  responsiveTo: 'container',
} satisfies ToolbarConfig;

const ui = { toolbar };

function reportDocumentError({ error }: { error: unknown }) {
  console.error('SuperDoc could not open the document.', error);
}

function withImageMimeType(file: File): Blob {
  const type = file.type.toLowerCase();
  if (type === 'image/png' || type === 'image/jpeg' || type === 'image/jpg') return file;
  if (type) throw new Error('Choose a PNG or JPEG image.');
  if (/\.png$/i.test(file.name)) return file.slice(0, file.size, 'image/png');
  if (/\.jpe?g$/i.test(file.name)) return file.slice(0, file.size, 'image/jpeg');
  throw new Error('Choose a PNG or JPEG image.');
}

function handleImageUpload(file: File): Promise<string> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(String(reader.result));
    reader.onerror = () => reject(reader.error ?? new Error('Could not read image.'));
    reader.readAsDataURL(withImageMimeType(file));
  });
}

export default function App() {
  const editorRef = useRef<SuperDocRef>(null);
  const exportingRef = useRef(false);
  const [ready, setReady] = useState(false);
  const [exporting, setExporting] = useState(false);

  async function exportDocument() {
    if (exportingRef.current) return;
    exportingRef.current = true;
    setExporting(true);
    try {
      await editorRef.current?.getInstance()?.export({ exportType: ['docx'], exportedName: 'sample-edited' });
    } catch (error) {
      console.error('SuperDoc could not export the document.', error);
    } finally {
      exportingRef.current = false;
      setExporting(false);
    }
  }

  return (
    <main>
      <button disabled={!ready || exporting} onClick={() => void exportDocument()} type='button'>
        Export DOCX
      </button>
      <SuperDocEditor
        document='/sample.docx'
        handleImageUpload={handleImageUpload}
        onContentError={reportDocumentError}
        onException={reportDocumentError}
        onReady={() => setReady(true)}
        ref={editorRef}
        ui={ui}
      />
    </main>
  );
}

```


Reload the application. The toolbar should contain eleven controls across the three regions. Select text and choose
**Bold** to confirm that the control follows the current selection.

**Table** inserts a table at the current selection. **Table actions** becomes available when the selection is inside a table;
use it to add or remove rows and columns, merge or split cells, change borders, or remove the table.

Select **Image** to choose a local file. SuperDoc invokes `handleImageUpload`. These examples return data URLs, so the
workflow needs no backend or temporary object URL. `withImageMimeType` keeps extension-accepted PNG and JPEG files
insertable when the browser leaves `file.type` empty. SuperDoc immediately fetches object or HTTP URLs returned by a
handler and embeds the image in the DOCX. The URL only needs to remain readable until that fetch completes. Same-origin
URLs need no extra server configuration. For another origin, return a public or presigned URL that the browser can read
without cross-origin cookies or custom authorization headers. Configure cross-origin requests (CORS) to allow the
application's origin.

For reusable document fields rather than toolbar actions, [Configure content controls](/editor/built-in-ui/content-controls).

## Configure the toolbar [#configure-the-toolbar]

Choose a group, then choose a field. Each entry shows its type, default, and a configuration fragment you can copy.
Leave `container` unset to let React's `SuperDocEditor` create the toolbar mount. Set it in either Vanilla or React when
your application provides an external toolbar container.

### Controls

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `items` | `{ left?: readonly ToolbarItemId[]; right?: readonly ToolbarItemId[]; center?: readonly ToolbarItemId[]; }` | — | Optional | Show only these built-in controls, grouped by toolbar region. | Built-in controls to render by region. Controls keep their built-in order. Omit to use the default toolbar. | — |
| `excludeItems` | `readonly (ToolbarItemId \| ToolbarLegacyItemId \| (string & {}))[]` | — | Optional | Remove built-in or custom controls from the toolbar. | Controls to remove. Also accepts the id of a custom item. | — |
| `customItems` | `readonly ToolbarCustomItem[]` | — | Optional | Add application buttons, dropdowns, or separators. | Application-defined controls and separators to add. | — |
| `includeItems` | `readonly ToolbarOptionalItemId[]` | — | Optional | Add optional built-in controls to the toolbar. | Additional opt-in controls. With `items`, each uses its built-in region unless already listed. | — |

### Layout

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `container` | `string \| HTMLElement` | — | Optional | Choose an app-owned element that receives the toolbar. Leave this unset to let React's SuperDocEditor create its internal mount. | Where to render the toolbar: an element, an id selector (`#toolbar`), a class selector (`.toolbar`), or a bare element id. Other CSS selector syntax resolves to nothing. | — |
| `overflow` | `"menu" \| "visible"` | `'menu'` | Optional | Move controls that do not fit into a menu, or keep them visible. | How the toolbar handles controls that no longer fit (default: `'menu'`). | — |
| `responsiveTo` | `"container" \| "viewport"` | `'viewport'` | Optional | Measure available width from the toolbar container or the viewport. | Width source used to lay out the toolbar (default: `'viewport'`). | — |

### Appearance

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `icons` | `Readonly<Partial<Record<ToolbarIconId, string>> & Record<string, unknown>>` | — | Optional | Replace built-in toolbar icons with trusted inline SVG markup. | Trusted inline SVG overrides keyed by public icon id. | — |
| `strings` | `Readonly<Partial<Record<ToolbarStringId, string>>>` | — | Optional | Replace built-in toolbar labels and tooltips. | Text overrides keyed by public string id. | — |
| `fontOptions` | `readonly ToolbarFontFamilyOption[]` | — | Optional | Choose the font families listed in the toolbar dropdown. | Options shown in the font-family dropdown. Register loadable fonts through `fonts.families`. | — |


Use `items` for a focused allowlist, `excludeItems` to remove a few controls from the default toolbar, and `customItems`
to add application actions. Controls listed in `items` keep their built-in order within each region.

For a custom item, use `command` when it can run one built-in action directly. Use `onSelect` for registered commands or
workflows that need more input; its context includes `execute` and `executeAsync`.

Keep `satisfies ToolbarConfig` from the examples. It checks control IDs, icon and string slots, font options, and custom
item shapes without widening the object. Prefer one composition strategy instead of combining a long `items` allowlist
with a long `excludeItems` list.

## Check the narrow layout [#check-the-narrow-layout]

`responsiveTo: 'container'` measures the toolbar mount instead of the browser window. With the default
`overflow: 'menu'`, controls that no longer fit move into the overflow menu. SuperDoc adds its trigger when needed; do
not list it in `items`.

Resize the Editor to your narrowest supported width. Every required control should remain reachable, and the toolbar
should not add horizontal page overflow. See [Layout](/editor/built-in-ui/responsive-layout) for document scaling,
contained scrolling, and fullscreen behavior.

The toolbar reads state from the Editor. Controls become active or disabled as the selection, document mode, and current
content change.

## Continue to comments [#continue-to-comments]

[Add the built-in comments UI](/editor/built-in-ui/comments) and preserve comment threads in the exported DOCX.


---

# Show content-control chrome

> Show or hide content-control chrome and respond when someone clicks a structured field in the DOCX.



Content controls are structured fields stored in a DOCX. Their IDs, aliases, tags, types, and content travel with the
document. SuperDoc can draw chrome around those fields so people can recognize and select them in the Editor.

## Try content controls [#try-content-controls]

Expand the Editor and click Acme Inc. or the checkbox. The demo reports the control's alias, tag, and type above the
document.

> **Interactive editor: Try content controls**
>
> Sample: [open the fixture](/fixtures/content-controls-sample.docx).
>
> Preset: `content-controls`.
>
> Content-control configuration available in the interactive Editor:
>
> - **Built-in chrome — `ui.contentControls`:** choose **Show** or **Hide**. The controls remain in the DOCX in either state.
>
> The fixture contains one text control and one checkbox. Clicking either control reports its alias, tag, and type through `onContentControlClick`.
>
> Local DOCX selection: disabled.


Set **Built-in chrome** to **Hide**. The outlines disappear, but the fields and their DOCX metadata remain. Clicking a
field still reports its metadata.

Changing this startup option reloads the current DOCX. Document edits remain, while the selection and last-clicked
status reset.

## Show the built-in chrome [#show-the-built-in-chrome]

Continue with the project from the [Quickstart](/editor/quickstart). Download the content-control sample and save it as
`public/content-controls-sample.docx`:

[Download the content-control sample](/fixtures/content-controls-sample.docx): Text field and checkbox · DOCX


Vite serves that file at `/content-controls-sample.docx`. Content-control chrome is on by default; this example enables
it explicitly and reports the field someone clicks. Replace `src/main.ts` or `src/App.tsx` with the standalone example:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const status = document.querySelector<HTMLOutputElement>('#content-control-status');

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/content-controls-sample.docx',
  ui: {
    contentControls: true,
  },
  onContentControlClick: ({ target }) => {
    if (!status) return;

    const name = target.alias ?? target.tag ?? target.id;
    status.value = `${name} · tag: ${target.tag ?? 'none'} · type: ${target.controlType}`;
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import { useCallback, useState } from 'react';
import type { ContentControlClickPayload } from 'superdoc';
import '@superdoc/react/style.css';

const editorConfig = {
  ui: {
    contentControls: true,
  },
} satisfies Pick<SuperDocEditorProps, 'ui'>;

export default function App() {
  const [status, setStatus] = useState('Click a content control.');
  const handleContentControlClick = useCallback(({ target }: ContentControlClickPayload) => {
    const name = target.alias ?? target.tag ?? target.id;
    setStatus(`${name} · tag: ${target.tag ?? 'none'} · type: ${target.controlType}`);
  }, []);

  return (
    <>
      <SuperDocEditor
        document='/content-controls-sample.docx'
        ui={editorConfig.ui}
        onContentControlClick={handleContentControlClick}
      />
      <output aria-live='polite'>{status}</output>
    </>
  );
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with the Editor mount and status element below:

```html
<div id="editor"></div>
<output id="content-control-status" aria-live="polite">Click a content control.</output>

<script type="module" src="/src/main.ts"></script>

```

Click a control. The status should show the field's alias, tag, and type from `onContentControlClick`.

Set `ui.contentControls: false` when your application should hide only SuperDoc's chrome. The content controls remain
part of the document, and the click callback continues to work.

## Choose the next layer [#choose-the-next-layer]

Use `onContentControlClick` for behavior tied to one click. Use
[custom content-control UI](/editor/custom-ui/content-controls) for a persistent field list, navigation, or
application-owned chrome.

Use the [Document API content-controls reference](/document-api/reference/content-controls/) when code needs to list,
create, update, or remove content controls.


---

# Configure the context menu

> Add application actions or open SuperDoc's document-aware menu from your interface.



SuperDoc opens its document-aware menu when a user right-clicks or types `/` after whitespace. You can add application
actions, change the slash trigger, or open the menu from your interface.

## Try the context menu [#try-the-context-menu]

Expand the Editor, then select “Select this sentence, then right-click it to open the document menu.”

1. With **Add action** selected, right-click the selection and choose **Send selection to workflow**.
2. Confirm that the status above the document reports the selected text.
3. Choose **Default** and right-click the selection again. SuperDoc's actions remain, but the application action is gone.

> **Interactive editor: Try the context menu**
>
> Sample: [open the fixture](/fixtures/context-menu-sample.docx).
>
> Preset: `context-menu`.
>
> Context-menu configurations available in the interactive Editor:
>
> - **Menu — `ui.contextMenu`:** choose **Default** or **Add action**. Add action keeps SuperDoc’s menu items and appends **Send selection to workflow** when you right-click selected text.
>
> Changing the menu configuration recreates the Editor from its current DOCX. Document edits remain; transient selection and menu state reset.
>
> Local DOCX selection: disabled.


Changing `ui.contextMenu` recreates the Editor from its current DOCX. Document edits remain, while the selection and
open menu reset.

## Add an application action [#add-an-application-action]

These standalone examples use `public/sample.docx` from the [Quickstart](/editor/quickstart). Replace `src/main.ts`
or `src/App.tsx` to add an action that appears only when the user right-clicks selected text:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc, type ContextMenuConfig } from 'superdoc';
import 'superdoc/style.css';

const contextMenu = {
  sections: [
    {
      id: 'application-actions',
      items: [
        {
          id: 'send-selection-to-workflow',
          label: 'Send selection to workflow',
          showWhen: ({ hasSelection, trigger }) => trigger === 'click' && hasSelection,
          onSelect: async ({ context }) => {
            const selectedText = (await context?.selectedTextSettled)?.trim();
            if (selectedText) console.log('Workflow selection:', selectedText);
          },
        },
      ],
    },
  ],
} satisfies ContextMenuConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: { contextMenu },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type ContextMenuConfig, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const contextMenu = {
  sections: [
    {
      id: 'application-actions',
      items: [
        {
          id: 'send-selection-to-workflow',
          label: 'Send selection to workflow',
          showWhen: ({ hasSelection, trigger }) => trigger === 'click' && hasSelection,
          onSelect: async ({ context }) => {
            const selectedText = (await context?.selectedTextSettled)?.trim();
            if (selectedText) console.log('Workflow selection:', selectedText);
          },
        },
      ],
    },
  ],
} satisfies ContextMenuConfig;

const editorConfig = {
  ui: { contextMenu },
} satisfies Pick<SuperDocEditorProps, 'ui'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' ui={editorConfig.ui} />;
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with:

```html
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

Select text, right-click, and choose **Send selection to workflow**. These examples log `Workflow selection:` and the
selected text in the browser console. Replace that log with your application's workflow.

`showWhen()` receives the document context captured when the menu opens. The example requires a right-click and an
expanded selection, so the action stays hidden after `/`, a programmatic `open()`, or a collapsed caret.

`onSelect()` runs after the menu closes. Await `context.selectedTextSettled` when the action needs the final selection
text. Use `context.selectedText` synchronously when the action must preserve user activation for a clipboard call,
`window.open()`, or a file picker.

## Configure the menu [#configure-the-menu]

Choose a group, then choose a field. Each entry shows its generated TypeScript signature and a configuration fragment
you can copy.

### Opening

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `openOnSlash` | `boolean` | `true` | Optional | Choose whether typing `/` after whitespace opens the built-in menu. | Whether typing `/` after whitespace opens the menu (default: true). | — |

### Items

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `sections` | `readonly ContextMenuSection[]` | `undefined` | Optional | Append application actions or merge them into a section with the same ID. | Application sections appended to the menu, or merged into a built-in section with the same ID. | — |
| `defaultItems` | `boolean` | `true` | Optional | Choose whether SuperDoc's built-in actions appear with your sections. | Whether to include SuperDoc's built-in items (default: true). | — |

### Advanced

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `menuProvider` | `(context: ContextMenuOpenContext, sections: readonly ContextMenuResolvedSection[]) => readonly ContextMenuResolvedSection[] \| null \| undefined` | `undefined` | Optional | Filter or reorder the resolved sections before the menu renders. | Filter or reorder the resolved sections before they render. Return `null` or `undefined` to keep the original list. | — |


Use `showWhen()` on an item for ordinary context checks. Reserve `menuProvider()` for changes that need the complete
resolved section list.

## Open the menu from your application [#open-the-menu-from-your-application]

Set `openOnSlash: false` when your application owns the keyboard shortcut. Right-click still works. A button, shortcut,
or other control can call `superdoc.ui.contextMenu.open()` at the current selection or caret. This is an alternative
example: replace the same entry file, rather than appending a second Editor:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: {
    contextMenu: { openOnSlash: false },
  },
});

document.querySelector('#open-context-menu')?.addEventListener('click', () => {
  const result = superdoc.ui.contextMenu.open();
  if (!result.ok) console.warn(`Context menu did not open: ${result.reason}`);
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor, type ContextMenuConfig, type SuperDocRef } from '@superdoc/react';
import '@superdoc/react/style.css';

const contextMenu = {
  openOnSlash: false,
} satisfies ContextMenuConfig;

const ui = { contextMenu };

export default function App() {
  const editor = useRef<SuperDocRef>(null);
  const [ready, setReady] = useState(false);

  function openContextMenu() {
    const instance = editor.current?.getInstance();
    if (!instance) return;
    const result = instance.ui.contextMenu.open();
    if (!result.ok) console.warn(`Context menu did not open: ${result.reason}`);
  }

  return (
    <>
      <button type='button' disabled={!ready} onClick={openContextMenu}>
        Open context menu
      </button>
      <SuperDocEditor ref={editor} document='/sample.docx' onReady={() => setReady(true)} ui={ui} />
    </>
  );
}

```


For this Vanilla variant, replace the contents of `<body>` in `index.html` with the button and Editor mount below:

```html
<button id="open-context-menu" type="button">Open context menu</button>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

`open()` returns `{ ok: false, reason }` when it cannot open. This includes an Editor that is not ready, a read-only
document, or missing selection geometry. Call `superdoc.ui.contextMenu.close()` to dismiss the menu; calling `close()`
when it is already closed is safe.

Continue with [Application-owned context menus](/editor/custom-ui/context-menus) when your application should render the
surface, or [Content controls](/editor/built-in-ui/content-controls) to configure structured fields in a DOCX.


---

# Configure hyperlink behavior

> Keep SuperDoc's defaults, suppress activation, or handle one hyperlink activation in your application.



Clicking a hyperlink can open SuperDoc's built-in editor, follow the link, or run behavior from your application.

## Try hyperlink activation [#try-hyperlink-activation]

Expand the Editor. Choose an activation behavior, then click **SuperDoc documentation**:

1. **Default** opens the built-in hyperlink editor in Editing mode.
2. **Do nothing** suppresses activation.
3. **Custom action** renders an action from your application beside the hyperlink.

> **Interactive editor: Try hyperlink activation**
>
> Sample: [open the fixture](/fixtures/hyperlinks-sample.docx).
>
> Preset: `hyperlinks`.
>
> Hyperlink behaviors available in the interactive Editor:
>
> - **Default:** SuperDoc opens its built-in hyperlink editor in Editing and Suggesting modes.
> - **Do nothing — `hyperlinks: false`:** activation has no effect.
> - **Custom action — `hyperlinks.onActivate`:** your application renders an action beside the hyperlink.
>
> The fixture contains one real external hyperlink. Changing the behavior recreates the Editor from its current DOCX.
>
> Local DOCX selection: disabled.


Changing the behavior recreates the Editor from its current DOCX. Document edits remain, while the open hyperlink
surface and selection reset.

## Use the mode-aware default [#use-the-mode-aware-default]

Omit `hyperlinks` when SuperDoc should choose the behavior from the document mode:

| Document mode | Default activation                      |
| ------------- | --------------------------------------- |
| Editing       | Open the built-in hyperlink editor.     |
| Suggesting    | Open the built-in hyperlink editor.     |
| Viewing       | Navigate to the URL or document anchor. |

Links outside editable text, such as linked images and links in headers or footers, navigate in every mode.

Set `hyperlinks: false` only when every hyperlink activation should do nothing.

## Handle activation in your application [#handle-activation-in-your-application]

Use `hyperlinks.onActivate` when your application needs to route, measure, suppress, or render an action for one
activation. Create `src/hyperlink-activation.ts`:

```ts
import type { HyperlinkActivationHandler } from 'superdoc';

const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
const HAS_PROTOCOL = /^[a-z][a-z0-9+.-]*:/i;

function getSafeHref(rawHref: string) {
  const href = rawHref.trim();
  if (!href) return null;
  if (href.startsWith('#')) return href;

  const candidate = HAS_PROTOCOL.test(href) ? href : `https://${href}`;

  try {
    return SAFE_PROTOCOLS.has(new URL(candidate).protocol) ? candidate : null;
  } catch {
    return null;
  }
}

export const handleHyperlinkActivation: HyperlinkActivationHandler = ({ href }) => {
  const safeHref = getSafeHref(href);
  if (!safeHref) return { type: 'suppress' };

  return {
    type: 'render',
    render: ({ container, close }) => {
      const panel = document.createElement('div');
      const link = document.createElement('a');
      const closeButton = document.createElement('button');

      link.href = safeHref;
      link.target = '_blank';
      link.rel = 'noopener noreferrer';
      link.textContent = 'Open hyperlink';

      closeButton.type = 'button';
      closeButton.textContent = 'Close';
      closeButton.addEventListener('click', close);

      panel.append(link, closeButton);
      container.append(panel);

      return {
        destroy() {
          closeButton.removeEventListener('click', close);
          panel.remove();
        },
      };
    },
  };
};

```

In the [Quickstart](/editor/quickstart) project, download this sample as `public/hyperlinks-sample.docx`. It contains a
link you can activate:

[Download the hyperlink sample](/fixtures/hyperlinks-sample.docx): Document with a link to SuperDoc documentation · DOCX


Replace `src/main.ts` or `src/App.tsx` with this standalone example. Both variants import the handler above:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
import { handleHyperlinkActivation } from './hyperlink-activation';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/hyperlinks-sample.docx',
  hyperlinks: {
    onActivate: handleHyperlinkActivation,
  },
  ui: {
    toolbar: { container: '#toolbar', items: { center: ['link'] } },
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';
import { handleHyperlinkActivation } from './hyperlink-activation';

const editorConfig = {
  hyperlinks: {
    onActivate: handleHyperlinkActivation,
  },
  ui: {
    toolbar: { items: { center: ['link'] } },
  },
} satisfies Pick<SuperDocEditorProps, 'hyperlinks' | 'ui'>;

export default function App() {
  return (
    <SuperDocEditor document='/hyperlinks-sample.docx' hyperlinks={editorConfig.hyperlinks} ui={editorConfig.ui} />
  );
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar and Editor mounts below:

```html
<div id="toolbar"></div>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

Click **SuperDoc documentation**. The application action should show **Open hyperlink** and **Close**. Choose **Close**
to dismiss it without navigating away.

Return one of these values:

* `undefined` or `{ type: 'default' }` uses the mode-aware default.
* `{ type: 'suppress' }` stops the activation.
* `{ type: 'render', render }` mounts an application-owned action beside the hyperlink.

The render callback receives an empty positioned `container` and `close()`. Return `destroy()` when the application
adds listeners or mounts a framework root.

## Configure activation [#configure-activation]

Choose the field to see its generated TypeScript signature and copy a focused configuration fragment.

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `onActivate` | `(context: HyperlinkActivationContext) => HyperlinkActivationResult \| null \| undefined` | `undefined` | Optional | Choose what happens when a user activates a hyperlink. | Use SuperDoc's default behavior, suppress this activation, or render a small custom action near the hyperlink. | — |


The context includes the `href`, current `documentMode`, and `defaultAction`. The default action is `edit` when SuperDoc
can edit the link and `navigate` otherwise.

`onActivate` must return synchronously. Work started by the handler may continue asynchronously. Call
`await context.getDocumentTarget()` from that work to resolve the exact `HyperlinkTarget` for
`editor.doc.hyperlinks.get()`, `patch()`, or `remove()`. It returns `null` when the activated link cannot be matched.

If `onActivate` throws, returns a Promise, returns an invalid result, or its render callback throws, SuperDoc suppresses
the activation and reports the failure through `onException`.

## Choose the right extension point [#choose-the-right-extension-point]

Use `onActivate` for behavior tied to one activation. Use [Custom UI](/editor/custom-ui/overview) for a persistent
toolbar, sidebar, dialog, or complete hyperlink workflow. The handler can open that custom UI.

Use the [Document API hyperlink reference](/document-api/reference/hyperlinks) when code needs to list, create, update,
or remove hyperlinks without a visual interaction.


---

# Choose a document loading UI

> Keep SuperDoc's progress overlay or replace it with an application-owned loading state.



SuperDoc shows document progress while the Editor opens. Keep this default unless your application needs to own the
entire loading experience.

## Try the built-in overlay [#try-the-built-in-overlay]

Select **Replay loading**. SuperDoc opens the document again and keeps the existing content covered until the
replacement is ready.

> **Interactive editor: Try document loading**
>
> Sample: [open the fixture](/fixtures/loading-sample.docx).
>
> Preset: `loading`.
>
> Loading behavior available in the interactive Editor:
>
> - **Built-in overlay — `ui.loading`:** enabled by default. It reports real document progress and stays visible until the Editor is ready.
> - **Replay loading:** opens the fixture again through `replaceFile()` so the same overlay covers a document replacement.
>
> Local DOCX selection: disabled.


## Keep the built-in progress overlay [#keep-the-built-in-progress-overlay]

No configuration is required. The overlay follows real document progress and stays visible until the Editor is ready.
It also appears when `replaceFile()` opens another DOCX.

In React, omit `renderLoading` so the built-in overlay remains visible. This minimal example uses
`public/sample.docx` from the [Quickstart](/editor/quickstart):

```tsx
import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';

export default function App() {
  return <SuperDocEditor document='/sample.docx' onReady={() => console.log('Document ready')} />;
}

```

Wait for `onReady` before enabling actions that depend on the document.

## Show application loading UI [#show-application-loading-ui]

The following are standalone alternatives in the Quickstart project, using the same `public/sample.docx`.

In React, replace `src/App.tsx` below. `renderLoading` replaces the initial loading experience; the wrapper hides the
Editor until `onReady`:

```tsx
'use client';

import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';
import { useState } from 'react';

export default function App() {
  const [loadFailed, setLoadFailed] = useState(false);

  return (
    <SuperDocEditor
      document='/sample.docx'
      renderLoading={() =>
        loadFailed ? (
          <p role='alert'>Could not open the document. Reload the page to retry.</p>
        ) : (
          <p role='status'>Opening document…</p>
        )
      }
      onContentError={() => setLoadFailed(true)}
      onException={() => setLoadFailed(true)}
    />
  );
}

```

This fallback also appears when changing the `document` prop. It does not run for an imperative `replaceFile()` call;
the built-in overlay still covers that operation.

For Vanilla, set `ui.loading: false` only when your application covers both the initial open and every file replacement.
Replace the body content in `index.html` below, keeping the script that loads `/src/main.ts`:

```html
<label>Open another DOCX <input id="document-file" type="file" accept=".docx" disabled /></label>
<p id="document-status" role="status">Opening document…</p>
<div id="editor" hidden></div>

```

Replace `src/main.ts`:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

function requireElement<ElementType extends HTMLElement>(selector: string) {
  const element = document.querySelector<ElementType>(selector);
  if (!element) throw new Error(`${selector} not found.`);
  return element;
}

const editor = requireElement<HTMLElement>('#editor');
const status = requireElement<HTMLElement>('#document-status');
const fileInput = requireElement<HTMLInputElement>('#document-file');
let hasOpened = false;
let replacing = false;

function showLoading() {
  fileInput.disabled = true;
  editor.hidden = true;
  status.hidden = false;
  status.textContent = 'Opening document…';
}

function showEditor() {
  hasOpened = true;
  fileInput.disabled = replacing;
  status.hidden = true;
  editor.hidden = false;
}

function showError(error: unknown) {
  console.error('Could not open the document.', error);
  fileInput.disabled = !hasOpened || replacing;
  editor.hidden = true;
  status.hidden = false;
  status.textContent = hasOpened
    ? 'Could not open the document. Choose another DOCX to retry.'
    : 'Could not open the document. Reload the page to retry.';
}

const superdoc = new SuperDoc({
  selector: editor,
  document: '/sample.docx',
  ui: { loading: false },
  onReady: showEditor,
  onContentError: ({ error }) => showError(error),
  onException: (payload) => {
    const runtimeOnly = 'itemName' in payload || 'source' in payload || 'diagnosticCode' in payload;
    if (!hasOpened && !runtimeOnly) showError(payload.error);
    else console.error('SuperDoc reported an exception.', payload);
  },
});

async function replaceDocument(file: File) {
  if (replacing) return;
  replacing = true;
  showLoading();
  try {
    const result = await superdoc.replaceFile(file);
    const state = result && typeof result === 'object' ? (result as { state?: unknown }).state : undefined;
    const replaced = state === undefined || state === null || state === 'review-ready' || state === 'editing-ready';
    if (!replaced) throw new Error('SuperDoc could not replace the document.');
    showEditor();
  } catch (error) {
    showError(error);
  } finally {
    replacing = false;
    fileInput.disabled = !hasOpened;
  }
}

fileInput.addEventListener('change', () => {
  const file = fileInput.files?.[0];
  if (file) void replaceDocument(file);
  fileInput.value = '';
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

Keep the application state visible until `onReady`. Around `replaceFile()`, keep it visible until the call returns a
ready state. If opening fails, replace the loading message with an error instead of revealing an incomplete Editor.

Reload to see the initial loading message. In Vanilla, choose another DOCX with the file picker and confirm the message
returns while it opens. If a replacement fails, choose another DOCX to retry. If the initial document fails to open,
reload the page. Unrelated runtime exceptions are logged without hiding a ready Editor.

## Configure the overlay [#configure-the-overlay]

Choose the field to see its generated TypeScript signature and copy a focused configuration fragment.

### Overlay

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `loading` | `boolean` | `true` | Optional | Choose whether SuperDoc renders the document loading overlay. | Built-in loading overlay shown while a document opens. Enabled by default. Set to `false` to show your own loading UI instead. This only decides whether SuperDoc draws the overlay. It does not change how long a document takes to open, and it does not affect loading UI the host renders (such as `renderLoading` in `@superdoc/react`). The built-in overlay also masks the document while it opens. Turning it off hands that responsibility to your UI: keep yours up until `onReady`, and around a replacement await `superdoc.replaceFile(...)`. | — |


This reference covers the core `Config` option. React's `renderLoading` is a `SuperDocEditor` prop, so it remains in the
React example above.

## Continue to custom UI [#continue-to-custom-ui]

Use [Custom UI](/editor/custom-ui/overview) when your application should own loading alongside the toolbar, comments,
review controls, and other Editor chrome.


---

# Use the built-in UI

> Let SuperDoc render common editor controls while your application owns access, workflow, and storage.



Use the built-in UI when SuperDoc's editing and review controls fit your product. Start with the defaults, then configure
only the surfaces your workflow needs.

## Explore the built-in UI [#explore-the-built-in-ui]

Choose a surface to see where it appears, how it starts, and where to configure it.

> **Interactive map: built-in Editor surfaces**
>
> - **[Toolbar](/editor/built-in-ui/configure-the-toolbar)** — Formatting commands reflect the document, selection, and mode. Controls adapt when space is tight. Initial behavior: React's `SuperDocEditor` creates a toolbar container. A Vanilla integration provides one.
> - **[Comments](/editor/built-in-ui/comments)** — Word comment threads import with the DOCX. People can create, reply to, and resolve them. Initial behavior: The comments UI is enabled by default. In viewing mode, show comments with `viewing.comments: true`.
> - **[Search](/editor/built-in-ui/search-and-replace)** — Find and replace document text, then move between matches across paginated pages. Initial behavior: Off until `ui: { search: true }`. Without it, the browser keeps its native find shortcut.
> - **[Hyperlinks](/editor/built-in-ui/hyperlinks)** — Keep the mode-aware behavior, suppress activation, or render a custom action. Initial behavior: Edit in Editing or Suggesting mode. Navigate in Viewing mode.
> - **[Context menu](/editor/built-in-ui/context-menus)** — Keep the built-in menu, add application actions, or render the complete menu yourself. Initial behavior: SuperDoc shows document-aware actions on right-click.
> - **[Content controls](/editor/built-in-ui/content-controls)** — Show structured fields stored in the DOCX and respond when someone clicks one. Initial behavior: Content-control chrome is enabled by default. Set `ui.contentControls: false` to hide it without removing the fields from the DOCX.
> - **[Ruler](/editor/built-in-ui/ruler)** — Show the active section's horizontal ruler and adjust its left and right page margins. Initial behavior: Off until `ui: { ruler: true }`.
> - **[Responsive layout](/editor/built-in-ui/responsive-layout)** — Fit the document to its container, adapt built-in chrome, and refit after fullscreen changes. Initial behavior: The toolbar responds to viewport width by default. Use `responsiveTo: 'container'` to measure its mount instead.
> - **[Loading](/editor/built-in-ui/loading)** — Keep the built-in progress overlay or let your application own the loading state. Initial behavior: SuperDoc shows document progress until the Editor is ready.
>
> Tracked changes appear as marks in the document. See [Track changes](/editor/track-changes) to review them.


Start with the toolbar, then choose only the surfaces your product needs. These guides are recipes, not steps that all
need to be completed. Each names the project files and sample document it uses.

## What your application owns [#what-your-application-owns]

The built-in UI does not choose which documents a person can access, authenticate users, save edits, or define your
product workflow. Your application owns those boundaries.

`Config.ui` decides what SuperDoc draws. It does not grant access or enforce permissions.

## Start with the toolbar [#start-with-the-toolbar]

Continue with [Configure the built-in toolbar](/editor/built-in-ui/configure-the-toolbar) to mount it, choose its
controls, and test its responsive behavior.


---

# Build a responsive Editor layout

> Fit the document to its container, adapt built-in chrome, and refit after fullscreen changes.



Fit the document to the available width while keeping the toolbar and fullscreen button in view.

## Build the shell [#build-the-shell]

This standalone Vanilla example uses `public/sample.docx` from the [Quickstart](/editor/quickstart).
Replace the body of `index.html` with this fixed-height shell. The Editor scrolls inside it; the controls stay above it:

```html
<div id="editor-shell">
  <div id="toolbar"></div>
  <button id="fullscreen" type="button" disabled>Fullscreen</button>
  <p id="layout-status" role="status">Opening document…</p>
  <div id="editor"></div>
</div>

<style>
  #editor-shell { display: flex; flex-direction: column; height: 80vh; min-width: 0; }
  #editor-shell:fullscreen { height: 100vh; background: white; }
  #toolbar, #fullscreen, #layout-status { flex: none; }
  #fullscreen { align-self: flex-start; }
  #editor { flex: 1; min-height: 0; min-width: 0; }
</style>

<script type="module" src="/src/main.ts"></script>

```

## Fit to the container [#fit-to-the-container]

Replace `src/main.ts` to fit the document to its container and refit after fullscreen changes:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const shell = document.querySelector<HTMLElement>('#editor-shell');
const fullscreen = document.querySelector<HTMLButtonElement>('#fullscreen');
const status = document.querySelector<HTMLElement>('#layout-status');

if (!shell || !fullscreen || !status) throw new Error('The responsive editor shell is incomplete.');
let ready = false;

const showError = ({ error }: { error: unknown }) => {
  console.error('Could not open the document.', error);
  status.textContent = 'Could not open the document. Reload to retry.';
};

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  contained: true,
  onContentError: showError,
  onException: showError,
  onReady: () => {
    ready = true;
    fullscreen.disabled = !document.fullscreenEnabled;
    status.textContent = document.fullscreenEnabled ? '' : 'Fullscreen is unavailable in this browser.';
  },
  zoom: {
    mode: 'fit-width',
    fitWidth: { min: 40, max: 100, padding: 24 },
  },
  ui: {
    toolbar: {
      container: '#toolbar',
      responsiveTo: 'container',
    },
    comments: { layout: 'auto' },
  },
});

const toggleFullscreen = async () => {
  try {
    if (document.fullscreenElement) await document.exitFullscreen();
    else await shell.requestFullscreen();
    status.textContent = '';
  } catch (error) {
    console.error('Could not change fullscreen mode.', error);
    status.textContent = 'Could not change fullscreen mode. You can keep editing here.';
  }
};
const refit = () => {
  fullscreen.textContent = document.fullscreenElement === shell ? 'Exit fullscreen' : 'Fullscreen';
  if (ready) superdoc.setZoomMode('fit-width');
};

fullscreen.addEventListener('click', toggleFullscreen);
document.addEventListener('fullscreenchange', refit);

window.addEventListener('beforeunload', () => {
  fullscreen.removeEventListener('click', toggleFullscreen);
  document.removeEventListener('fullscreenchange', refit);
  superdoc.destroy();
});

```

`zoom.mode: 'fit-width'` continuously follows the available document width. The `min`, `max`, and `padding` values constrain that policy. Calling `setZoom()` switches to manual mode; call `setZoomMode('fit-width')` to resume automatic fitting.

In `superdoc@2.12.0`, automatic fitting can shrink a DOCX to the minimum zoom instead of filling its container.
If you encounter this, use manual zoom (`zoom: { mode: 'manual' }`) and let readers adjust it.
Remove the `setZoomMode('fit-width')` call from `refit()` too. Manual zoom does not refit when the container changes size.

`responsiveTo: 'container'` measures the toolbar mount instead of the browser window. Lower-priority controls move into
the overflow menu when space becomes tight. `comments.layout: 'auto'` lets the review UI move between the sidebar and
inline threads.

Auto layout measures the nearest Editor ancestor with a width and derives when to switch. Override that behavior only
when another element defines the available space or your application needs a fixed breakpoint:

```ts
const config = {
  ui: {
    comments: {
      layout: 'auto',
      responsive: {
        target: '#editor-shell',
        breakpoint: 1200,
      },
    },
  },
};
```

`target` accepts a CSS selector or an `HTMLElement`. Below `breakpoint`, measured in CSS pixels, comments render inline.

## Reflow document content [#reflow-document-content]

Fit-to-width preserves print pages and scales them. To remove visible page boundaries and rewrap DOCX content when the Editor container changes width, select web layout instead:

```ts
const viewOptions = { layout: 'web' } as const;
```

Define this before the constructor and add `viewOptions` to its configuration, then narrow the window. Text wraps to the host width instead of shrinking the
printed page. No layout-engine option is required.

Web layout does not show headers, footers, the ruler, or page-count updates. Keep print layout when those matter.

Set `contained: true` only when the host has a deliberate fixed height and should own an internal scroll region. Leave it off when the document should expand with the page. Avoid nesting the Editor inside another horizontal scroller.

## Check the layout [#check-the-layout]

Narrow the window: print pages should shrink, toolbar controls should move into overflow, and the fullscreen button
should stay visible as you scroll. Enter and exit fullscreen to check that the document fits again. If the browser
rejects the request, the status explains the failure without blocking editing.

Continue with [Loading UI](/editor/built-in-ui/loading) to choose what people see while a document opens.


---

# Show the ruler

> Show the horizontal ruler and let people adjust a section's left and right page margins.



## Try the ruler [#try-the-ruler]

Expand the Editor and click in the document to activate its section. Drag either margin handle to reflow the page, then
switch between inches and centimeters without changing the margins.

> **Interactive editor: Adjust page margins**
>
> Sample: [open the fixture](/fixtures/ruler-sample.docx).
>
> Preset: `ruler`.
>
> Ruler controls available in the interactive Editor:
>
> - **Ruler — `ui.ruler`:** show or hide the horizontal ruler. Click in the document to activate a section, then drag its handles to change the left and right page margins.
> - **Measurements — `measurementUnit`:** display Editor measurements in inches or centimeters. Switching units does not change the margins.
>
> Local DOCX selection: disabled.


The ruler follows the active section. In Viewing mode it remains visible but read-only. Web layout hides it.

## Show the ruler [#show-the-ruler]

These standalone examples use `public/sample.docx` from the [Quickstart](/editor/quickstart). Replace `src/main.ts`
or `src/App.tsx` to enable the ruler:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: {
    ruler: true,
  },
  measurementUnit: 'in',
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const editorConfig = {
  ui: {
    ruler: true,
  },
  measurementUnit: 'in',
} satisfies Pick<SuperDocEditorProps, 'ui' | 'measurementUnit'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' {...editorConfig} />;
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with:

```html
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

`ui.ruler` controls the built-in surface. Show or hide it later with `toggleRuler()`.

`measurementUnit` is an Editor-wide preference, so it stays at the top level rather than inside `ui.ruler`. Set the
initial unit to inches or centimeters, then change it with `setMeasurementUnit()`.

## Configure the ruler [#configure-the-ruler]

Choose a field to see its type, default, and a configuration fragment you can copy.

### Ruler

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `ui.ruler` | `false \| true \| { container?: string \| HTMLElement; }` | `false` | Optional | Show the horizontal ruler, or provide a container for an external mount. | Built-in ruler. Disabled by default. | — |

### Measurements

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `measurementUnit` | `"in" \| "cm"` | `'in'` | Optional | Display measurements across this Editor in inches or centimeters. | Starting measurement unit for rulers and measurement fields (Word's "measurement units" preference). Defaults to `'in'` (Word's en-US default). Change it at runtime with `setMeasurementUnit()`. See `SuperDocMeasurementUnit`. | — |

### Events

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `onPageMarginsChange` | `(params: { documentId: string; editorVersion: 2; sectionId: string; sectionIndex: number; side: "left" \| "right"; value: number; pageMargins: { top?: number; right?: number; bottom?: number; left?: number; }; }) => void` | — | Optional | Run application code after a ruler drag changes a section margin. | Callback after a ruler drag changes the active section's left or right page margin. | — |


`onPageMarginsChange` reports the changed side and the section's current margins in inches. Use the
[Document API sections reference](/document-api/reference/sections/) for other page setup changes.

Continue with [Responsive layout](/editor/built-in-ui/responsive-layout) to fit the Editor to its container and adapt
its chrome when space becomes tight.


---

# Search and replace document text

> Enable document-aware search, move through matches, and choose which search controls SuperDoc renders.



Use the built-in search surface to find text across the open document without leaving the Editor.

## Try search and replace [#try-search-and-replace]

Expand the Editor and open Search from the toolbar. The sample has three short pages built for these checks:

1. Search for `Client` and confirm that there are eight matches.
2. Move through the results with Previous and Next, and watch the Editor scroll between pages.
3. Turn on Match case and confirm that the count changes to seven.
4. Turn Match case off. Expand the replacement row with the arrow beside Find, enter `Customer`, then choose **Replace**.
5. Search for `Legacy` with **Tracked deletions** set to **Exclude** and confirm that there are no matches.
6. Set **Tracked deletions** to **Include**, reopen Search, and search for `Legacy` again. The pending deletion is the
   only match.

> **Interactive editor: Try search and replace**
>
> Sample: [open the fixture](/fixtures/search-sample.docx).
>
> Preset: `search`.
>
> Search configurations available in the interactive Editor:
>
> - **Mode — `documentMode`:** Editing allows replacement. Search remains available in Viewing, but replace controls are hidden.
> - **Replace controls — `ui.search.replaceControls`:** choose Show or Hide. Hide removes the built-in replacement row in every document mode.
> - **Tracked deletions — `ui.search.includeTrackedDeletions`:** choose Exclude or Include. The sample has one pending deletion containing `Legacy`.
>
> The three-page fixture has eight case-insensitive `Client` matches and seven case-sensitive matches. `Legacy` has zero matches when tracked deletions are excluded and one when they are included. Moving between results scrolls the Editor to each match. Changing a Search startup option recreates the Editor from its current DOCX. Document edits and document mode remain; the active search resets.
>
> Local DOCX selection: disabled.


Set **Replace controls** to **Hide**. Search remains available, but the replacement row disappears. The demo reloads the
current document when you change either option because they configure Search at startup. Document edits remain, while
the active search resets.

Switch to Viewing after the search. The matches and navigation controls remain available, while the replace controls
disappear because Viewing cannot change the document.

## Enable built-in search [#enable-built-in-search]

These standalone examples use `public/sample.docx` from the [Quickstart](/editor/quickstart). Replace `src/main.ts`
or `src/App.tsx` to enable the search surface:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: {
    toolbar: { container: '#toolbar' },
    search: true,
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const editorConfig = {
  ui: {
    search: true,
  },
} satisfies Pick<SuperDocEditorProps, 'ui'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' ui={editorConfig.ui} />;
}

```


For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar and Editor mounts below:

```html
<div id="toolbar"></div>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

`ui: { search: true }` connects the toolbar Search button and `Ctrl+F` or `Command+F` to the same document search.
Without it, the browser keeps its native page search shortcut.

Open Search with both methods. Search for `Client` and confirm that each method shows the same match count and active
result.

## Configure the search surface [#configure-the-search-surface]

Choose a group, then choose a field. Each entry shows its type, default, and a configuration fragment you can copy.

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `replaceControls` | `boolean` | `true` | Optional | Show replace controls (default: true). This changes the built-in UI only; it does not authorize or disable `superdoc.ui.search.replace()`. | Show replace controls (default: true). This changes the built-in UI only; it does not authorize or disable `superdoc.ui.search.replace()`. | — |
| `includeTrackedDeletions` | `boolean` | `false` | Optional | Include text from pending tracked deletions in each search (default: false). | Include text from pending tracked deletions in each search (default: false). | — |

### Position & size

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `floating.placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left" \| "top-center" \| "bottom-center"` | `'top-right'` | Optional | Position preset (default: `'top-right'`). Explicit insets override it. | Position preset (default: `'top-right'`). Explicit insets override it. | — |
| `floating.top` | `string \| number` | — | Optional | Top inset in pixels or as a CSS length. | Top inset in pixels or as a CSS length. | — |
| `floating.right` | `string \| number` | — | Optional | Right inset in pixels or as a CSS length. | Right inset in pixels or as a CSS length. | — |
| `floating.bottom` | `string \| number` | — | Optional | Bottom inset in pixels or as a CSS length. | Bottom inset in pixels or as a CSS length. | — |
| `floating.left` | `string \| number` | — | Optional | Left inset in pixels or as a CSS length. | Left inset in pixels or as a CSS length. | — |
| `floating.width` | `string \| number` | `420` | Optional | Surface width in pixels or as a CSS length. | Surface width in pixels or as a CSS length. | — |
| `floating.maxWidth` | `string \| number` | — | Optional | Maximum surface width in pixels or as a CSS length. | Maximum surface width in pixels or as a CSS length. | — |
| `floating.maxHeight` | `string \| number` | — | Optional | Maximum surface height in pixels or as a CSS length. | Maximum surface height in pixels or as a CSS length. | — |

### Focus

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `floating.autoFocus` | `boolean` | `true` | Optional | Focus the find input when the surface opens (default: true). | Focus the find input when the surface opens (default: true). | — |
| `floating.closeOnOutsidePointerDown` | `boolean` | `false` | Optional | Close the surface when a pointer press occurs outside it (default: false). | Close the surface when a pointer press occurs outside it (default: false). | — |

### Text

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `strings.findPlaceholder` | `string` | `'Find'` | Optional | Input placeholder for the find field. | Input placeholder for the find field. | — |
| `strings.replacePlaceholder` | `string` | `'Replace'` | Optional | Input placeholder for the replace field. | Input placeholder for the replace field. | — |
| `strings.noResults` | `string` | `'No results'` | Optional | Text shown when there are no matches. | Text shown when there are no matches. | — |
| `strings.previousMatchTitle` | `string` | `'Previous match (Shift+Enter)'` | Optional | Tooltip for the previous-match button. | Tooltip for the previous-match button. | — |
| `strings.nextMatchTitle` | `string` | `'Next match (Enter)'` | Optional | Tooltip for the next-match button. | Tooltip for the next-match button. | — |
| `strings.closeTitle` | `string` | `'Close (Escape)'` | Optional | Tooltip for the close button. | Tooltip for the close button. | — |
| `strings.replace` | `string` | `'Replace'` | Optional | Replace button text. | Replace button text. | — |
| `strings.replaceAll` | `string` | `'All'` | Optional | Replace-all button text. | Replace-all button text. | — |
| `strings.toggleReplaceTitle` | `string` | `'Toggle replace'` | Optional | Tooltip for the button that expands or collapses replace controls. | Tooltip for the button that expands or collapses replace controls. | — |
| `strings.matchCase` | `string` | `'Aa'` | Optional | Match case toggle text. | Match case toggle text. | — |
| `strings.ignoreDiacritics` | `string` | `'ä≡a'` | Optional | Ignore diacritics toggle text. | Ignore diacritics toggle text. | — |
| `strings.regex` | `string` | `'.*'` | Optional | Regex toggle text. | Regex toggle text. | — |
| `strings.invalidPattern` | `string` | `'Invalid pattern'` | Optional | Inline error shown when the regex pattern is invalid or unsafe. | Inline error shown when the regex pattern is invalid or unsafe. | — |

### Accessibility

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `strings.findAriaLabel` | `string` | `'Find text'` | Optional | Accessible label for the find input. | Accessible label for the find input. | — |
| `strings.replaceAriaLabel` | `string` | `'Replace text'` | Optional | Accessible label for the replace input. | Accessible label for the replace input. | — |
| `strings.previousMatchAriaLabel` | `string` | `'Previous match'` | Optional | Accessible label for previous match button. | Accessible label for previous match button. | — |
| `strings.nextMatchAriaLabel` | `string` | `'Next match'` | Optional | Accessible label for next match button. | Accessible label for next match button. | — |
| `strings.closeAriaLabel` | `string` | `'Close find and replace'` | Optional | Accessible label for close button. | Accessible label for close button. | — |
| `strings.toggleReplaceAriaLabel` | `string` | `'Toggle replace'` | Optional | Accessible label for toggle replace button. | Accessible label for toggle replace button. | — |
| `strings.matchCaseAriaLabel` | `string` | `'Match case'` | Optional | Accessible label for match case toggle. | Accessible label for match case toggle. | — |
| `strings.ignoreDiacriticsAriaLabel` | `string` | `'Ignore diacritics'` | Optional | Accessible label for ignore diacritics toggle. | Accessible label for ignore diacritics toggle. | — |
| `strings.regexAriaLabel` | `string` | `'Use regular expression'` | Optional | Accessible label for the regex toggle. | Accessible label for the regex toggle. | — |


`replaceControls: false` changes only the built-in UI. It does not disable `superdoc.ui.search.replace()` or enforce a
permission. Keep application-owned replacement controls synchronized with `canReplace` from
`superdoc.ui.search.observe()`.

Search also supports match case and regular expressions. Invalid regular expressions show an error instead of running a
partial search.

Finding a pending deletion does not restore, accept, or reject it. It only adds that text to the current search results.

Search highlights and the active match are temporary Editor state. Replacements change the document, so use the save
flow from [Load and save](/editor/load-and-save-documents) to persist them.

Use [custom search controls](/editor/custom-ui/search) when your application should render the search surface. Use
[Document API queries](/document-api/query-content) when code needs document targets instead of a visual search session.


---

# Connect two editors

> Run the local example and watch an edit appear in another browser.



Connect Alex and Sam to the same document. Start with the working example, then look at the configuration that connects them.

## Try it here [#try-it-here]

The editors connect automatically. Expand the demo, then change Monday to Friday in Alex's document. Watch Sam's document update. Alex's cursor is blue; Sam's is green. This sample is temporary; do not enter private information.

> **Live collaboration demo:** Two real editors connect automatically in a temporary room. Expand the collapsed preview, change Monday to Friday in Alex’s editor, and watch Sam’s editor update. Alex’s cursor is blue; Sam’s is green. The demo requires a configured collaboration server; when unavailable, use the local example below. Hosted rooms keep edits temporarily for reconnect and expire after 15 minutes. Use sample text only.


## 1. Start the example [#1-start-the-example]

Download or clone the [collaboration example](https://go.superdoc.dev/examples/collaboration). It includes the browser app, a sample DOCX, and a local Hocuspocus server.

You need Node.js 22.12 or newer and pnpm 11. In the example's `collaboration` directory, run:

```bash
pnpm install --ignore-scripts
pnpm dev
```

The example pins SuperDoc 2.11.0 and Hocuspocus 2.15.3. The install command skips dependency lifecycle scripts. Keep the terminal running: it serves the app on port `5173` and the collaboration connection on port `1234`.

> **Local example only (note)**
>
> This server has no authentication or persistent storage. Use the included sample, not private documents. Restarting
> the server clears its rooms.


## 2. Open Alex and Sam's editors [#2-open-alex-and-sams-editors]

Open these addresses in separate tabs, in this order:

| Editor | Address                                        | What happens                         |
| ------ | ---------------------------------------------- | ------------------------------------ |
| Alex   | `http://localhost:5173/?mode=create&user=Alex` | Creates a room from the sample DOCX. |
| Sam    | `http://localhost:5173/?user=Sam`              | Joins Alex's room.                   |

Wait for Alex's tab to show `Connected.` before opening Sam's. Then wait for Sam's tab to show the same status. Place the browser windows side by side so you can see both documents.

## 3. Edit together [#3-edit-together]

In Alex's editor, change Monday to Friday. Watch the delivery date update in Sam's editor without reloading.

Now type a reply in Sam's editor. It appears in Alex's editor too. Both editors can send and receive changes; neither is a read-only preview of the other.

## Configure your application [#configure-your-application]

The connection belongs to the document. Both editors use the same server and room ID; the creator uses `create`, and everyone else uses `join`.

> **Preview API (note)**
>
> The `collaboration` configuration and typed connection failures below require the upcoming SuperDoc release. They are
> available in the current source, not in the pinned 2.11.0 example. Run that example unchanged to try the behavior.


```ts
import { SuperDoc, type DocumentCollaborationConfig } from 'superdoc';
import 'superdoc/style.css';

const collaboration = {
  providerType: 'hocuspocus',
  documentId: 'example-room',
  serverUrl: 'ws://127.0.0.1:1234',
  roomMode: 'join',
} satisfies DocumentCollaborationConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: { url: '/sample.docx', collaboration },
  user: { name: 'Sam', email: 'sam@example.com' },
});
```

Provide an `#editor` element and serve your DOCX at `/sample.docx`. Use these settings when integrating the preview API into your application, not as a patch to the pinned example.

| Setting                        | Its job                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `providerType` and `serverUrl` | Connect to the Hocuspocus server you started.                                |
| `documentId`                   | Put both editors in the same room.                                           |
| `roomMode`                     | Create the room once, then join it. Alex uses `'create'`; Sam uses `'join'`. |

The `mode` and `user` URL parameters belong to this example, not SuperDoc. The app reads them to choose the room operation and display name.

Both editors supply the sample DOCX. The creator uses it to initialize the room. The joiner reads the room's shared content; supplying the file again does not overwrite it.

The example shows `Connected.` when `onCollaborationReady` fires. That means initial synchronization and editor readiness have completed, not that the server has saved the document. Call `destroy()` when your owning route or component unmounts to release the connection; the standalone example does this when the page closes.

## Reopen or start over [#reopen-or-start-over]

To reopen the existing room, use a join address such as `http://localhost:5173/?user=Alex`. Reloading the original `mode=create` address tries to create the room again and fails.

To start over, restart the example server, then open the create address followed by the join address.

If the example shows `Connection failed.`, inspect the error reported by `onException`. Check that the server is still running, both editors use the same `documentId`, and the creator reached `Connected.` before the joiner opened. A failed join is not a reason to overwrite the room with a local file.

## Show who is editing [#show-who-is-editing]

Next, [add presence and cursors](/editor/collaboration/presence-and-awareness) so Alex and Sam can identify each other while they work.


---

# Control access to a room

> Check credentials and document permissions before an editor joins a shared room.



Decide who may open a shared document. A room ID identifies it; it does not grant access. A cursor's display name is not
proof of identity. This walkthrough adds authorization to the local example; it does not require persistent storage.

Edit Alex's document, then connect Sam to see the same edits. Connect Taylor: the server rejects the request because Taylor has no permission for this room.

> **Live access demo:** Alex opens a temporary shared document automatically. Edit it, then connect Sam to receive the same edits. Connect Taylor: the server rejects the request because Taylor has no permission for this room. These are simulated identities with public test credentials, checked by a real server. The demo reports access denied only after server confirmation, not for every connection failure. Demo edits are not saved. If the server is unavailable, follow the local example below.


## Let the server decide [#let-the-server-decide]

| Browser                                 | Collaboration server                                    | Result                               |
| --------------------------------------- | ------------------------------------------------------- | ------------------------------------ |
| Sends a credential and requests a room. | Verifies the credential and checks access to that room. | Allows the connection or rejects it. |

Keep both checks on the server. Hiding a document link or disabling an editor control does not protect the room.

## 1. Enable the access example [#1-enable-the-access-example]

Use the [local collaboration example](/editor/collaboration/connect-two-editors). Stop its development command, then run:

```bash
COLLABORATION_DEMO_AUTH=1 VITE_COLLABORATION_DEMO_AUTH=1 pnpm dev
```

The first flag enables server checks. The second lets the browser select a test credential for each example user.

To keep the storage from the previous guide too, add `COLLABORATION_STORAGE_DIR=.collaboration-data` to the same
command. If `example-room` is already saved, open both Alex and Sam with their join addresses below, not `mode=create`.

> **Public test credentials only (note)**
>
> This example simulates signed-in users with fixed, public credentials. Anyone can select Alex's credential. It teaches
> the connection checks, not a production login system. Use only the sample document.


## 2. Allow Alex and Sam [#2-allow-alex-and-sam]

For a new room, open `http://localhost:5173/?mode=create&user=Alex`. If `example-room` is already saved,
open `http://localhost:5173/?user=Alex` instead. Wait for `Connected.`, then open `http://localhost:5173/?user=Sam`.

Type in Alex's editor and confirm that Sam receives the edit. The server allows both credentials to access `example-room`.

## 3. Reject Taylor [#3-reject-taylor]

Open `http://localhost:5173/?user=Taylor`. Taylor's credential is recognized, but it has no room permissions. The page should show `Connection failed.` and keep **Export DOCX** disabled. Taylor must not receive Alex's shared edits.

This is different from an unknown credential, which the server also rejects. Knowing who someone is does not mean they can open every document.

## Check the credential and room together [#check-the-credential-and-room-together]

The example's `demo-access.ts` supplies Hocuspocus's `onAuthenticate` hook:

```ts
import type { Configuration, onAuthenticatePayload } from '@hocuspocus/server';

// Public fixtures for the local walkthrough, not production credentials.
const exampleProviderRoom = 'sd2/v2.1/example-room';
const sessions = new Map([
  ['demo-alex', { userId: 'alex', rooms: [exampleProviderRoom] }],
  ['demo-sam', { userId: 'sam', rooms: [exampleProviderRoom] }],
  ['demo-taylor', { userId: 'taylor', rooms: [] }],
]);

export async function authenticateRoom({ token, documentName }: Pick<onAuthenticatePayload, 'token' | 'documentName'>) {
  const session = sessions.get(token);
  if (!session || !session.rooms.includes(documentName)) {
    throw new Error('Access denied');
  }
  return { userId: session.userId };
}

export const demoAccess = { onAuthenticate: authenticateRoom } satisfies Pick<Configuration, 'onAuthenticate'>;

```

For the pinned SuperDoc 2.11.0 example, `documentId: 'example-room'` reaches Hocuspocus as `sd2/v2.1/example-room`. The hook checks that exact provider room name, not just whether the token is valid. Keep this mapping with your document permissions; do not authorize by matching only a suffix.

Returning allows the connection; throwing rejects it. This example grants the same room access to creators and joiners; it does not implement separate create, read-only, or edit roles.

In the [preview configuration API](/editor/collaboration/connect-two-editors#configure-your-application), send the browser credential through `document.collaboration.token`. It is separate from `user`, which supplies display identity for the editor.

## Handle a rejected connection [#handle-a-rejected-connection]

The preview API adds `collaborationReason` to connection failures reported by `onException`. Add this callback to your editor configuration:

```ts
import type { Config } from 'superdoc';

const onException: NonNullable<Config['onException']> = (failure) => {
  if ('collaborationReason' in failure) {
    switch (failure.collaborationReason) {
      case 'access-denied':
        console.error('Check your sign-in and permission to open this document.');
        break;
      case 'connection-failed':
      case 'sync-timeout':
        console.error('Could not connect. Check your connection and try again.');
        break;
    }
    return;
  }
  console.error(failure.error);
};
```

`access-denied` means the provider explicitly rejected the connection. It does not distinguish an invalid credential from missing room permission. A timeout is not proof of denied access, and a worker startup failure is not a collaboration rejection. Do not parse error messages or show the server's raw rejection text to users.

The pinned 2.11.0 example reports only `Connection failed.`; keep its existing error handling until you upgrade. The embedded demo confirms rejection with its example server.

## Connect your application's sign-in flow [#connect-your-applications-sign-in-flow]

Replace the public credential map with server-side validation of your application's session or access token. Look up the verified user's permission for the requested document. Do not accept a browser-supplied user ID as proof of identity.

On the browser side, replace `src/demo-credentials.ts` and its name-based selection with a credential obtained through your authenticated application. Never put production secrets in a `VITE_` variable, source file, or URL. Use HTTPS and secure WebSockets outside local development.

Returning `userId` from this server hook does not make the browser's cursor label trustworthy. Keep authorization tied to the verified server identity, not awareness names or colors.

Protect the source DOCX download and export storage too; room authorization does not secure separate file endpoints. Rechecking access after token expiry or permission changes needs an explicit server policy, not just this initial connection check.

Next, [run a collaboration server](/editor/collaboration/run-a-server) to review provider choices and deployment responsibilities.


---

# Understand collaboration

> Let people edit the same document together, using your existing editor UI.



Without collaboration, two people opening the same DOCX are editing separate copies. With collaboration, they work on a shared document: an edit in one person's editor appears in the other's.

## One document, two editors [#one-document-two-editors]

Alex changes a delivery date. Sam sees the new date without reloading the document or opening another file.

> **Illustration: two editors, one shared document.** Alex changes the delivery date to Friday. A provider carries the change through their shared room, and Sam sees Friday in the other editor. Both people can edit.


Both people can edit. SuperDoc synchronizes their document changes while each person keeps their own view and selection.

## Connect through a room [#connect-through-a-room]

A **room** connects the editors working on one shared document. Your application gives that room an ID so each editor knows which document to join. Opening the same file URL in two browsers does not connect them.

A **provider** carries changes between the connected editors. You can run a collaboration server yourself or use a hosted service. The next guide starts with a local Hocuspocus server.

The first editor creates the room from a DOCX. The second joins that room. From then on, they work with its shared content.

Sharing edits is separate from reviewing them. Use [tracked changes](/editor/track-changes) when edits should remain
proposals, or [comments](/editor/built-in-ui/comments) for discussion. Collaboration carries the shared document changes;
it does not decide which proposals to accept.

## Keep the UI you already built [#keep-the-ui-you-already-built]

Collaboration works with built-in controls, custom controls, or a mix of both. You add a connection to the document; you do not need to rebuild your toolbar or review panels.

Your application still decides who can access the document and how it is saved. Those are server responsibilities, separate from showing another person's edits.

## Insert bookmark anchors [#insert-bookmark-anchors]

In a V2 collaboration room, `doc.bookmarks.insert()` supports a text range within one paragraph of the document body, including a zero-length range for an insertion-point bookmark. Wait for `collaboration-ready` before calling it. The bookmark's start and end offsets are preserved in `bookmarks.get()` and `bookmarks.list()`, on connected peers, and when exporting and reopening the DOCX.

Use a unique bookmark name and a valid range in the target paragraph. Insertion across paragraphs is not supported; it returns `CROSS_BLOCK_MATCH` without creating a bookmark. The same single-paragraph range and point behavior is supported in solo editing.

## Try it with two editors [#try-it-with-two-editors]

[Connect two editors](/editor/collaboration/connect-two-editors) walks you through creating a room, joining from another tab, and watching an edit appear in both. Start there, then add presence and persistent storage.


---

# Initialize a shared document

> Create a room from a DOCX once, then join it for every later editing session.



Your application has a DOCX that Alex and Sam need to edit together. Choose one place to create its shared room. After that, everyone—including the creator—joins the existing room.

Start with the [local two-editor example](/editor/collaboration/connect-two-editors). Keep its Hocuspocus server running throughout this walkthrough; it stores rooms only in memory.

## Create once, then join [#create-once-then-join]

| First open                             | Another person arrives                           | Return to the document                             |
| -------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
| Alex **creates** a room from the DOCX. | Sam **joins** the room and receives its content. | Alex **joins** the same room, including its edits. |
| `roomMode: 'create'`                   | `roomMode: 'join'`                               | `roomMode: 'join'`                                 |

`create` is not “open or create.” It fails if the room already exists. `join` does not initialize a missing room from the supplied file.

## 1. Create the room from a DOCX [#1-create-the-room-from-a-docx]

In the example, open `http://localhost:5173/?mode=create&user=Alex`. Alex's editor imports the sample DOCX into a new room and shows `Connected.` when it is ready.

With the [preview configuration API](/editor/collaboration/connect-two-editors#configure-your-application), put the connection in the document's `collaboration` field. These are the creator's settings:

```ts
import type { DocumentCollaborationConfig } from 'superdoc';

const createConnection = {
  providerType: 'hocuspocus',
  serverUrl: 'ws://127.0.0.1:1234',
  documentId: 'example-room',
  roomMode: 'create',
} satisfies DocumentCollaborationConfig;
```

In your application's document configuration, use `collaboration: createConnection` for this first open. Leave the pinned example unchanged; its URL selects the same room operation.

In your application, assign a stable room ID to each shared document. Store that association so future editors can find the same room. Do not generate a new ID on every page load or reuse one room for unrelated documents.

The application chooses who initializes the room. Do not make every visitor try to create it. The collaboration server must still authorize access; knowing a room ID does not grant permission.

## 2. Join the existing room [#2-join-the-existing-room]

After Alex's tab shows `Connected.`, open `http://localhost:5173/?user=Sam`. The server address and room ID stay the same; only the operation changes:

```ts
const joinConnection = {
  ...createConnection,
  roomMode: 'join',
} satisfies DocumentCollaborationConfig;
```

Use `collaboration: joinConnection` for later opens. The example still supplies the sample DOCX, but the joiner receives the room's shared content. Supplying the original file does not reset the room.

Type a short sentence in Sam's editor and confirm that Alex sees it.

## 3. Reopen without resetting [#3-reopen-without-resetting]

Keep Alex connected while you close Sam's tab and reopen `http://localhost:5173/?user=Sam`. His sentence should still be there. With Sam connected again, Alex can close his tab and return using `http://localhost:5173/?user=Alex`.

Do not reuse Alex's original `mode=create` address to reopen the document. The person who created the room is now a joiner too.

If creation reports that the room exists, reopen the intended document with `join`; do not overwrite it. If joining fails, check the connection, room ID, access, and whether initialization completed. A failed join is not permission to create a replacement from an older file.

## Choose where initialization belongs [#choose-where-initialization-belongs]

The browser path above works when the first editor supplies the DOCX. Two other starting points have different owners:

| Your application starts with…                                        | Initialize through…                                                                                                                                           |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A DOCX opened for its first shared editing session                   | The browser editor, as above.                                                                                                                                 |
| A local editor with unsaved changes that someone wants to share      | [`upgradeToCollaboration()`](/editor/collaboration/upgrade-a-document), which creates a new room from the current document.                                   |
| A backend workflow that prepares the document before anyone opens it | The [Node.js SDK](/agents/automation/node-sdk), opening the DOCX with a collaboration target and explicit `roomMode: 'create'`. Browsers then join that room. |

The Hocuspocus server transports shared state; it does not import a DOCX by itself. Server-side initialization still needs a SuperDoc client to read the file and create the document in the room. Choose one initialization path, not competing browser and backend creators.

## Keep the room after a restart [#keep-the-room-after-a-restart]

Reopening this example proves that a new editor receives the existing room's edits. It does not prove durable saving. This server has no storage integration: restarting it clears its rooms, and a room can also be unloaded after its last editor leaves. Keep at least one editor connected during the walkthrough.

`onCollaborationReady` is not a storage acknowledgment. To reopen after everyone leaves or the server restarts, your server needs persistent room storage.

Next, [save and restore a room](/editor/collaboration/save-and-restore-a-room) so the document survives everyone leaving and the server restarting.


---

# Show who is editing

> Give collaborators names and cursor colors, then show who is connected.



Alex and Sam can now edit the same document. Give each person a name so they can recognize the other person's cursor. Add a participant list when your application also needs to show who is here.

## Watch someone leave and return [#watch-someone-leave-and-return]

Expand the demo and type in Sam's editor. Select **Disconnect Sam**: his name leaves the participant list and his cursor disappears from Alex's editor, but his edits remain. Select **Reconnect Sam** to bring him back into the same room.

> **Live presence demo:** Alex and Sam edit a temporary shared document. The participant list comes from Alex’s awareness updates and includes Alex himself. Type in Sam’s editor, then disconnect Sam: his presence disappears while his edits remain in Alex’s document. Reconnect Sam to rejoin the same room. This requires a configured collaboration server; otherwise follow the local two-editor example. Hosted rooms keep edits temporarily for reconnect and expire after 15 minutes. Use sample text only.


This is a temporary sample. Do not enter private information. Without the hosted demo, use the [local two-editor example](/editor/collaboration/connect-two-editors): close Sam's tab, then reopen his join address.

## Identify each person [#identify-each-person]

The local example already supplies `user` when it creates each editor. In your application, use the display identity from the signed-in session. For example, Alex's configuration includes:

```ts
const user = {
  id: 'alex',
  name: 'Alex',
  email: 'alex@example.com',
};
```

Pass this object as `user` in the editor configuration. SuperDoc displays remote cursors and names; you do not need to draw them yourself. Each person keeps their own selection and viewport.

SuperDoc assigns cursor colors from a palette. To use your application's colors, provide the same palette to each editor:

```ts
const colors = ['#1355ff', '#00853d', '#9333ea'];
```

Pass the array as `colors` in the editor configuration. A palette is not a guarantee of a unique color for every person. Keep names visible so color is not the only way to identify a collaborator.

## Show a participant list [#show-a-participant-list]

**Awareness** is the live presence information exchanged during the session. Use `onAwarenessUpdate` to render that information in your own UI. You do not need this callback just to display the editor's remote cursors.

The [collaboration example](https://go.superdoc.dev/examples/collaboration) includes this element in `index.html`:

```html
<ul id="participants" aria-label="Connected participants"></ul>
```

Its `src/participants.ts` renders each update using the public payload type:

```ts
import type { SuperDocAwarenessUpdatePayload } from 'superdoc';

export function renderParticipants({ states }: SuperDocAwarenessUpdatePayload) {
  const list = document.querySelector<HTMLUListElement>('#participants');
  if (!list) return;

  const items = states.map((participant) => {
    const item = document.createElement('li');
    item.textContent = participant.name || 'Guest';
    return item;
  });
  list.replaceChildren(...items);
}

```

In `src/main.ts`, import the handler:

```ts
import { renderParticipants } from './participants';
```

Then add `onAwarenessUpdate: renderParticipants` to the existing `new SuperDoc(...)` configuration. Open Alex and Sam's tabs: each list should show both names once. Close Sam's tab and check that Alex's list returns to one name.

In V2, `states` includes the current user. Render the snapshot as supplied; do not append yourself again. Read fields such as `name` and `color` directly from each entry, not from `state.user`. Use presence `clientId` values only within the current editor session, not as account IDs.

If a separate UI component subscribes later with `superdoc.on('awareness-update', listener)`, remove that same listener with `superdoc.off('awareness-update', listener)` when the component unmounts. Continue to call `superdoc.destroy()` when the editor itself unmounts.

## Presence is not document state [#presence-is-not-document-state]

Leaving removes a person's live presence, not their edits. After an abrupt network loss, presence may take time to disappear; it is not an immediate connection-health check.

The `users` configuration is a directory for people and mentions, not a list of connected participants. Neither that directory nor awareness grants access to a room. Keep permissions on the server, and do not use presence as an audit log or a saved indicator.

## Keep the shared document [#keep-the-shared-document]

You can now show shared edits and the people making them. Next, [initialize a shared document](/editor/collaboration/initialize-a-document): choose who creates the room and how everyone reopens it.


---

# Run a collaboration server

> Choose a provider and connect room access, storage, and recovery before deployment.



The [two-editor example](/editor/collaboration/connect-two-editors) already runs a Hocuspocus server. Keep it for local
development. Before deployment, choose who operates the provider and how rooms are authorized, saved, and recovered.

## Run the server separately [#run-the-server-separately]

The [collaboration example](https://go.superdoc.dev/examples/collaboration) pins Hocuspocus 2.15.3. Its `pnpm dev` command
starts both the browser app and server. You do not need a second server process.

To run only the server, stop `pnpm dev`, then run this from the example directory:

```bash
pnpm exec tsx server.ts
```

The example listens on port `1234` and keeps rooms in memory. Restarting the process clears them. With no storage integration, unloading a room after its last editor disconnects also loses its state.

Start the browser app separately with `pnpm exec vite`, or return to `pnpm dev` after stopping the standalone server.

Use the [two-editor walkthrough](/editor/collaboration/connect-two-editors#2-open-alex-and-sams-editors) to check the
connection. For storage, pass `COLLABORATION_STORAGE_DIR` to the server command. For the access example, pass
`COLLABORATION_DEMO_AUTH=1` to the server command and `VITE_COLLABORATION_DEMO_AUTH=1` to the Vite command.
The default commands enable neither storage nor access checks.

## Prepare for production [#prepare-for-production]

### Choose a provider [#choose-a-provider]

Hocuspocus is the local example's default, not a requirement. The document's `collaboration` field accepts these targets through `DocumentCollaborationConfig` in the [preview API](/editor/collaboration/connect-two-editors#configure-your-application):

| `providerType`  | Room and connection                     | Authentication                                  |
| --------------- | --------------------------------------- | ----------------------------------------------- |
| `'hocuspocus'`  | `documentId` and `serverUrl` (or `url`) | `token` or string `params`                      |
| `'y-websocket'` | `documentId` and `serverUrl` (or `url`) | String `params` forwarded to your server        |
| `'liveblocks'`  | `documentId` or `roomId`                | Exactly one of `authEndpoint` or `publicApiKey` |

For Liveblocks, use an authenticated endpoint when access must be checked per room; a public key does not provide that check. Configure the chosen provider's server or service before pointing the editor at it. SuperDoc owns the browser connection and local shared state; pass connection settings, not an external `{ ydoc, provider }` pair.

### Authorize access [#authorize-access]

The minimal server deliberately has no authentication or durable storage. Before deployment, authenticate the WebSocket connection, authorize each room, persist room updates, set connection and document limits, and define backup and recovery behavior in the server layer.

[Control access to a room](/editor/collaboration/control-room-access) demonstrates credential validation and per-room permission checks. Your server owns authorization; browser controls and display identity do not enforce it.

### Initialize the document [#initialize-the-document]

[Initialize a shared document](/editor/collaboration/initialize-a-document) explains who imports the DOCX, when to create or join, and how browser and backend initialization differ. The Hocuspocus server transports and stores shared state; it does not import the DOCX itself.

### Persist the room separately from DOCX files [#persist-the-room-separately-from-docx-files]

[Save and restore a room](/editor/collaboration/save-and-restore-a-room) shows how to store binary Yjs state, restart the server, and reopen with edits intact. It also explains why DOCX exports and presence are separate from room storage.

If your application starts with a local document, [upgrade it to collaboration](/editor/collaboration/upgrade-a-document) when someone invites another person to edit.


---

# Save and restore a room

> Keep collaborative edits after everyone leaves or the server restarts.



Alex and Sam can reopen a room while another editor keeps it alive. Now make it survive everyone leaving and the server restarting.

Use the [collaboration example](/editor/collaboration/connect-two-editors). This page adds local storage to its Hocuspocus server; the browser configuration stays the same.

## What should you save? [#what-should-you-save]

A `Y.Doc` holds a local copy of the shared document state. Each client has its own copy; the provider exchanges Yjs updates between them. SuperDoc manages the browser's copy inside its worker. Your application supplies connection settings, not its own `Y.Doc`.

| Data                  | Keep it for…                                                      |
| --------------------- | ----------------------------------------------------------------- |
| Binary Yjs room state | Reopening the same collaborative document, including its edits.   |
| Exported DOCX         | Downloading, sharing, or keeping a file snapshot.                 |
| Awareness             | Showing who is here now. It is temporary, not saved room content. |

Saving only DOCX snapshots does not persist the Yjs room. Saving room state does not automatically write a DOCX to your file storage.

## 1. Enable local storage [#1-enable-local-storage]

Stop the example's development command. In the same directory, restart it with:

```bash
COLLABORATION_STORAGE_DIR=.collaboration-data pnpm dev
```

The directory is created automatically and ignored by Git. It contains binary room snapshots, not DOCX files. Keep using this directory when restarting the server.

This local example has no authentication. Use the sample document, not private information. The embedded docs demo remains temporary.

Use the local server for this step: reconnecting the embedded demo cannot demonstrate a storage write or server restart.

## 2. Edit and wait for a save [#2-edit-and-wait-for-a-save]

Open `http://localhost:5173/?mode=create&user=Alex`, then `http://localhost:5173/?user=Sam`. If this room already exists in your storage directory, use the join addresses for both people instead.

Type “Saved after restart.” in Sam's editor. Wait for the server terminal to print `Room state saved.` after the edit. Hocuspocus schedules storage writes; a keystroke does not mean the room has been saved yet.

Close both tabs. Stop the development command, then restart it with the same command and directory.

## 3. Restore the room [#3-restore-the-room]

Open `http://localhost:5173/?user=Alex`, using `join`, not `create`. Confirm that “Saved after restart.” is still there. Join as Sam and make another edit to check that collaboration still works.

Select **Export DOCX** to download a file containing the restored edits. Exporting is separate from saving the room.

## How the server saves and loads [#how-the-server-saves-and-loads]

The example enables these hooks only when `COLLABORATION_STORAGE_DIR` is set:

```ts
import { createHash } from 'node:crypto';
import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { Configuration } from '@hocuspocus/server';
import { applyUpdate, encodeStateAsUpdate, type Doc } from 'yjs';

type RoomState = { document: Doc; documentName: string };

export function localStorage(directory: string) {
  mkdirSync(directory, { recursive: true });
  const filename = (name: string) => join(directory, `${createHash('sha256').update(name).digest('hex')}.yjs`);

  return {
    async onLoadDocument({ document, documentName }: RoomState) {
      let state: Buffer;
      try {
        state = readFileSync(filename(documentName));
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
        throw error;
      }
      applyUpdate(document, state);
    },
    async onStoreDocument({ document, documentName }: RoomState) {
      const target = filename(documentName);
      // Synchronous writes serialize this single-process example; rename avoids exposing a partial snapshot.
      writeFileSync(`${target}.tmp`, encodeStateAsUpdate(document));
      renameSync(`${target}.tmp`, target);
      console.log('Room state saved.');
    },
  } satisfies Pick<Configuration, 'onLoadDocument' | 'onStoreDocument'>;
}

```

`encodeStateAsUpdate()` produces a complete state update for the current `Y.Doc`. `applyUpdate()` restores those bytes before clients synchronize. Store binary data, not `Y.Doc.toJSON()`.

Only a missing file is treated as a new room. Unreadable or corrupt state must fail rather than silently replace saved content with the original DOCX.

## Before using production storage [#before-using-production-storage]

This single-process example uses synchronous writes and a temporary-file rename. It does not provide multi-server coordination, backups, or a power-loss durability guarantee. Use your provider's storage integration for your database or object store, with authorization and a recovery policy.

`onCollaborationReady` means the editor has synchronized and is ready. It is not a storage acknowledgment. Show “Saved” only when your storage flow confirms the changes it committed.

Next, [control access to a room](/editor/collaboration/control-room-access) so only authorized users can connect to the saved document.


---

# Upgrade a local document to collaboration

> Create a new collaboration room from the DOCX already open in a local Editor.



Use `upgradeToCollaboration()` when a single local DOCX is already open and the person decides to make that live Editor collaborative. The operation creates a new room from the current document and comments, then attaches the Editor to it in place.

## Create the room [#create-the-room]

Wait until the local Editor is ready, then pass a supported collaboration target in create mode. This snippet uses the [preview configuration API](/editor/collaboration/connect-two-editors#configure-your-application):

Here, `superdoc` is your existing Editor and `session.collaborationToken` comes from your application's authenticated
session. Replace the example server address with your configured provider. The token must be authorized to create
`contract-123`; this snippet does not provide a server or sign-in flow.

```ts
await superdoc.upgradeToCollaboration({
  collaboration: {
    providerType: 'hocuspocus',
    documentId: 'contract-123',
    serverUrl: 'wss://collaboration.example.com',
    token: session.collaborationToken,
    roomMode: 'create',
  },
});
```

The promise resolves when the collaborative runtime is ready. The same Editor instance stays mounted, so application controls and lifecycle ownership remain in place.

The operation supports one DOCX and a new v2 room. It does not join an existing room or merge the local document with remote content. If the target already exists, stop and let the application choose a different room or reopen the document with `roomMode: 'join'`.

> **Verification target (success)**
>
> After the upgrade resolves, open a second Editor that joins the new room. An edit in either Editor should appear in
> the other.


## Migrate existing collaboration data separately [#migrate-existing-collaboration-data-separately]

Moving a final v1 recovery bundle into a v2 room is a server-side migration, not a live browser upgrade. The Node-only `superdoc/collaboration-upgrade-engine` subpath builds and validates provider-free upgrade artifacts without connecting to a room. It requires Node.js 20 or newer and should be paired with provider-specific read, write, and fresh-client validation.

Start with [Migrate from v1](/editor/migrate-from-v1/overview) before planning that operation. For ordinary browser connections, use [Connect two editors](/editor/collaboration/connect-two-editors).


---

# Add fields to a DOCX template

> Turn document selections into tagged inline and block-level content controls.



Use this workflow when your DOCX does not yet have fields your application can find. Wrap a client name in an inline
field, then create a block field for a confidentiality clause. If your template already has fields, start with
[Fill a DOCX template](/editor/content-controls/fill-a-docx-template).

## Add both field shapes [#add-both-field-shapes]

Select the client name and add the inline field. Then place the caret on the empty line below **Confidentiality** and add
the block field.

> **Interactive editor: add template fields**
>
> Select “Acme Products, Inc.” and add an inline text field tagged `client.legalName`. Then place the caret on the empty line below Confidentiality and add a block rich-text field tagged `agreement.confidentiality`. The detected-fields list reports each field’s alias, tag, placement, and control type. Export downloads the authored DOCX.


## Create the fields [#create-the-fields]

Use the [complete Vanilla TypeScript example](https://go.superdoc.dev/examples/content-controls?workflow=add) and choose
**Add fields**. It includes the untagged agreement, selection controls, Editor setup, and export button.

Pass the current selection target to `create.contentControl()`. Here, the inline call wraps a text selection. The block
call targets an empty paragraph and replaces it with the supplied HTML content:

```ts
import type { BrowserDocumentApi, SelectionTarget } from 'superdoc/ui';

export async function addClientNameField(doc: BrowserDocumentApi, selection: SelectionTarget) {
  return doc.create.contentControl({
    kind: 'inline',
    controlType: 'text',
    tag: 'client.legalName',
    alias: 'Client legal name',
    at: selection,
  });
}

export async function addConfidentialityField(doc: BrowserDocumentApi, caret: SelectionTarget) {
  return doc.create.contentControl({
    kind: 'block',
    controlType: 'richText',
    tag: 'agreement.confidentiality',
    alias: 'Confidentiality clause',
    html: '<p>Each party will protect confidential information with reasonable care.</p>',
    at: caret,
  });
}

```

`kind` controls placement. `controlType` controls field behavior:

| Property      | This example         | Meaning                                          |
| ------------- | -------------------- | ------------------------------------------------ |
| `kind`        | `inline`, `block`    | Where the control sits in the document structure |
| `controlType` | `text`, `richText`   | Which content-control operations apply           |
| `tag`         | `client.legalName`   | Application lookup and grouping key              |
| `alias`       | `Client legal name`  | Readable title stored in the DOCX                |
| `id`          | Assigned on creation | One control occurrence in the document           |

The example obtains the selection from the Editor-owned UI controller after readiness. The helper needs a current
selection target, not the selected text alone. Check the creation receipt before treating the field as available.

## Keep the fields in your template [#keep-the-fields-in-your-template]

Export the DOCX from the standalone example and reopen it. Confirm that the client name is an inline text control and
the confidentiality clause is a block rich-text control, with the tags and titles shown above. Keep this file as the
template you fill later; reopening the original draft will not include the fields you just added.

Continue with [Fill a DOCX template](/editor/content-controls/fill-a-docx-template) to update fields from application
data. Use the [`create.contentControl()` reference](/document-api/reference/content-controls/create/) for every input
shape.


---

# Fill a DOCX template

> Update every content-control occurrence that represents an application field, then export the DOCX.



Use a prepared template when your application already knows the values to put in a document. This agreement has a
client name in three places and an auto-renew checkbox. The fields are already present; your application fills them.

## Try the workflow [#try-the-workflow]

Expand the Editor and change the client name. All three occurrences update. Then toggle auto-renew to change the
checkbox in the document.

> **Interactive editor: Fill the template**
>
> The application form updates real Word content controls in the service-agreement DOCX.
>
> - Client legal name (`client.legalName`): one form value updates 3 document occurrences.
> - Auto-renew (`agreement.autoRenew`): the checkbox updates the Word checkbox control.
>
> The demo reports how many matching controls changed. Reset restores the prepared template, and Export DOCX downloads the filled document.


## Start with the prepared example [#start-with-the-prepared-example]

Open the [complete Vanilla TypeScript example](https://go.superdoc.dev/examples/content-controls?workflow=fill) and
choose **Fill fields**. It includes the template, form, occurrence arrows, Editor setup, and export button. The snippets below are from
that project; they are not a separate Editor setup.

In your own integration, keep the Editor from the [Quickstart](/editor/quickstart) and load a DOCX with content controls,
such as the [service-agreement template](/fixtures/service-agreement-template.docx). Obtain `superdoc.activeEditor.doc`
after `onReady` before calling the field helpers. The Quickstart's original sample does not contain these fields.

## Define the field map [#define-the-field-map]

The client-name controls share the tag `client.legalName`. Their IDs differ because each ID identifies one occurrence.
Changing a control does not automatically change others with the same tag; the example updates every match.

Keep the tag and expected type together. For example, `client.legalName` expects a text control and
`agreement.autoRenew` expects a checkbox.

<details>
  <summary>
    View the example's field map
  </summary>

  ```ts
  export const templateFields = [
    {
      key: 'clientLegalName',
      label: 'Client legal name',
      tag: 'client.legalName',
      type: 'text',
    },
    {
      key: 'clientAddress',
      label: 'Client address',
      tag: 'client.address',
      type: 'text',
    },
    {
      key: 'effectiveDate',
      label: 'Effective date',
      tag: 'agreement.effectiveDate',
      type: 'text',
    },
    {
      key: 'autoRenew',
      label: 'Auto-renew',
      tag: 'agreement.autoRenew',
      type: 'checkbox',
    },
  ] as const;

  export type TemplateField = (typeof templateFields)[number];
  export type TemplateFieldKey = TemplateField['key'];

  type TaggedContentControl = {
    readonly controlType: string;
    readonly properties: { readonly tag?: string };
  };

  export function hasCompatibleTemplateFields(items: readonly TaggedContentControl[]) {
    return templateFields.every((field) =>
      items.some((item) => item.properties.tag === field.tag && item.controlType === field.type),
    );
  }

  ```
</details>

## Update every occurrence [#update-every-occurrence]

The example's `updateTextField()` and `updateCheckboxField()` helpers follow three steps:

1. Find matching controls with `selectByTag()`.
2. Check each control's type, then call `text.setValue()` or `checkbox.setState()` on its target.
3. Count updated, unchanged, and failed occurrences from the mutation receipts.

<details>
  <summary>
    View the typed update helpers
  </summary>

  ```ts
  import type { BrowserDocumentApi, ContentControlInfo } from 'superdoc/ui';

  export type FieldUpdateResult = {
    failures: string[];
    matched: number;
    unchanged: number;
    updated: number;
  };

  type ControlType = 'checkbox' | 'text';

  async function updateControls(
    doc: BrowserDocumentApi,
    tag: string,
    expectedType: ControlType,
    mutate: (control: ContentControlInfo) => Promise<{ success: boolean; failure?: { code?: string; message?: string } }>,
  ): Promise<FieldUpdateResult> {
    let items: readonly ContentControlInfo[];
    try {
      ({ items } = await doc.contentControls.selectByTag({ tag }));
    } catch (error) {
      return {
        failures: [error instanceof Error ? error.message : `Could not find controls for ${tag}.`],
        matched: 0,
        unchanged: 0,
        updated: 0,
      };
    }
    const result: FieldUpdateResult = { failures: [], matched: items.length, unchanged: 0, updated: 0 };

    for (const control of items) {
      if (control.controlType !== expectedType) {
        result.failures.push(`${control.id} is ${control.controlType}, not ${expectedType}.`);
        continue;
      }

      try {
        const receipt = await mutate(control);
        if (receipt.success) result.updated += 1;
        else if (receipt.failure?.code === 'NO_OP') result.unchanged += 1;
        else result.failures.push(receipt.failure?.message ?? `Could not update ${control.id}.`);
      } catch (error) {
        result.failures.push(error instanceof Error ? error.message : `Could not update ${control.id}.`);
      }
    }

    return result;
  }

  export function updateTextField(doc: BrowserDocumentApi, tag: string, value: string) {
    return updateControls(doc, tag, 'text', (control) =>
      Promise.resolve(doc.contentControls.text.setValue({ target: control.target, value })),
    );
  }

  export function updateCheckboxField(doc: BrowserDocumentApi, tag: string, checked: boolean) {
    return updateControls(doc, tag, 'checkbox', (control) =>
      Promise.resolve(doc.contentControls.checkbox.setState({ target: control.target, checked })),
    );
  }

  export function didUpdateEveryMatch(result: { failures: readonly string[]; matched: number }) {
    return result.matched > 0 && result.failures.length === 0;
  }

  export function describeUpdate(result: FieldUpdateResult) {
    if (result.failures.length > 0 && result.matched === 0) return 'The document could not be updated.';
    if (result.matched === 0) return 'No matching controls.';
    if (result.failures.length > 0) return `Updated ${result.updated} of ${result.matched} locations.`;
    if (result.updated === 0) return `${result.matched} locations already match.`;
    return `Updated ${result.updated} ${result.updated === 1 ? 'location' : 'locations'}.`;
  }

  ```
</details>

Use the same lookup and receipt pattern for other supported field types. Check `controlType`, call the matching typed
operation, and use the returned receipt to decide what the application reports.

No matches means the template is missing the expected field. A locked or incompatible occurrence can fail after other
occurrences have changed: these individual updates are not one atomic transaction. The example reports partial results
and blocks export until failed fields are corrected.

## Export and check the result [#export-and-check-the-result]

In the standalone example, choose **Export DOCX** after the updates finish. Reopen the file in SuperDoc or Word and
check all three client names and the checkbox. Field tags remain in the DOCX for later updates.

The embedded demo does not save to your server. Use [Load and save](/editor/load-and-save-documents) to persist the
exported bytes in your application.

Next, [add fields to your own template](/editor/content-controls/add-fields-to-a-docx-template). For an application-owned
field list, see [custom content-control UI](/editor/custom-ui/content-controls).


---

# Templates and fields

> Connect application data to named regions in a DOCX, from a client name to a reusable clause.



Suppose a client name appears three times in an agreement. Your application needs to update all three without searching
for the old name or changing unrelated text.

A **content control** marks a region of the document and gives it metadata your application can find. In these guides,
a template field is a content control used for a value or clause. It stays part of the DOCX, whether you use built-in
controls or a custom UI.

Start with [Fill a DOCX template](/editor/content-controls/fill-a-docx-template). Its prepared agreement lets you change
one client name and see all three occurrences update. You do not need to create fields or build a custom toolbar first.

## Choose a workflow [#choose-a-workflow]

- [Fill a DOCX template](/editor/content-controls/fill-a-docx-template): Update prepared fields from application data and export the result.
- [Add fields to a DOCX template](/editor/content-controls/add-fields-to-a-docx-template): Turn selected content into tagged inline and block-level fields.
- [Replace clauses from your application](/editor/content-controls/replace-clauses-from-your-application): Use tagged block-level fields as application-managed clause slots.
- [Lock template fields](/editor/content-controls/lock-template-fields): Keep a field, its contents, or both from being changed during normal DOCX editing.


## Choose what the region holds [#choose-what-the-region-holds]

**Content-control shapes**

| Shape | Wraps | Common use |
| --- | --- | --- |
| Inline | Part of a paragraph | Repeated values and typed inputs |
| Block-level | Paragraphs or tables | Clause slots and document sections |
| Repeating section | A collection of items | Line items and repeated records |


Start with text fields. Add other controls when the document needs them:

* **Typed inputs:** Use text, checkbox, date, and choice controls for values with known input behavior.
* **Repeating records:** Add, clone, and remove repeating-section items for lists such as line items or questionnaire
  responses.
* **Custom field UI:** Build a field list, navigation panel, or workflow around the controls in the open document.

Use the [Document API reference](/document-api/reference/content-controls/) for the complete operation set. Use
[custom content-control UI](/editor/custom-ui/content-controls) to connect document selection and navigation to your
application.

## Identify a control [#identify-a-control]

Use a tag as the application lookup key. The alias gives people a readable title, while the ID identifies one occurrence
inside the document.

| Word property | SuperDoc value     | Use it for                                                                                  |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| Tag           | `properties.tag`   | Connect one application field to every matching control. Multiple controls can share a tag. |
| Title         | `properties.alias` | Show a human-readable field name in Word or your application UI.                            |
| ID            | `id`               | Address one occurrence of the field in the DOCX.                                            |

A shared tag groups controls for lookup. It does not synchronize their content. Your application decides how values flow
between its data and each document occurrence.

Content controls are stored as `w:sdt` elements in the DOCX. You do not need to edit that XML to use the Document API.


---

# Lock template fields

> Keep a content control, its contents, or both from being changed during normal DOCX editing.



Content-control locks use the same two choices as Word. Protect the field wrapper when it must remain in the template,
and protect its contents when people should not change the value.

## Try both locks [#try-both-locks]

Expand the editor, toggle either lock, then click the client address and type. Use **Delete field** to test whether the
control itself can be removed.

> **Interactive editor: Lock a template field**
>
> The service-agreement DOCX contains one text control tagged `client.address`. The demo applies the same two locking choices that Word exposes:
>
> - **Content control cannot be deleted** protects the field wrapper.
> - **Contents cannot be edited** blocks changes inside the field.
>
> Toggle either choice, then edit or delete the field. Reset restores the prepared document.


## Set the lock mode [#set-the-lock-mode]

In the [runnable Fill example](https://go.superdoc.dev/examples/content-controls?workflow=fill), update the address,
then select **Lock address after filling**. Export the DOCX to keep both the value and its lock. Clear the checkbox to
allow edits again.

Continue with the [filled template](/editor/content-controls/fill-a-docx-template). After `onReady`, pass
`superdoc.activeEditor.doc`, the tag `client.address`, and a mode below to this helper. That tag identifies the single
address control used in the demo. The helper requires exactly one match; `client.legalName` has three occurrences.
It uses the types shipped with `superdoc`; no separate Document API package is needed.

Find the field by tag and apply the matching DOCX lock:

```ts
import type { BrowserDocumentApi, ContentControlInfo } from 'superdoc/ui';

export async function setTemplateFieldLock(
  doc: BrowserDocumentApi,
  tag: string,
  lockMode: ContentControlInfo['lockMode'],
) {
  const { items } = await doc.contentControls.selectByTag({ tag });

  if (items.length !== 1) {
    throw new Error(`Expected one content control tagged "${tag}", found ${items.length}.`);
  }

  return doc.contentControls.setLockMode({
    target: items[0].target,
    lockMode,
  });
}

```

| Content control cannot be deleted | Contents cannot be edited | `lockMode`         |
| --------------------------------- | ------------------------- | ------------------ |
| Off                               | Off                       | `unlocked`         |
| On                                | Off                       | `sdtLocked`        |
| Off                               | On                        | `contentLocked`    |
| On                                | On                        | `sdtContentLocked` |

Set a content lock after filling the field. `contentLocked` and `sdtContentLocked` reject text changes inside the
control.

Export with your existing [load and save flow](/editor/load-and-save-documents), then reopen the file and try the same
edit or deletion. Check the lock on the saved control, not just the state of your application's checkbox.

## Keep authorization separate [#keep-authorization-separate]

Locks travel with the DOCX and constrain normal editing in SuperDoc and Word. They do not authenticate users or decide
who may access or save the file. Enforce those permissions in a trusted backend. See
[Secure your integration](/editor/secure-integration).

Use the [`contentControls.setLockMode()` reference](/document-api/reference/content-controls/set-lock-mode/) for the
complete operation contract.


---

# Replace clauses from your application

> Replace a tagged block-level field from application-owned UI.



Use a block-level content control as a clause slot. The DOCX owns where the clause appears. Your application owns the
available clauses and chooses which content fills that slot.

## Try a clause slot [#try-a-clause-slot]

Choose a clause below. The Editor replaces the paragraph inside the control tagged `agreement.confidentiality`.

> **Interactive editor: Choose a confidentiality clause**
>
> The DOCX contains one block-level content control tagged `agreement.confidentiality`.
>
> - **Mutual:** Each party must protect the other party's confidential information and use it only to perform this agreement.
> - **Recipient only:** The receiving party must protect the disclosing party's confidential information and use it only to perform this agreement.
> - **Limited use:** The recipient may use confidential information only to evaluate and perform the services described in this agreement.
>
> Choosing an option replaces the paragraph inside the control. Reset restores the original clause.


## Replace the clause [#replace-the-clause]

For a complete project, use the [Add fields example](https://go.superdoc.dev/examples/content-controls?workflow=add).
Create the block field, then choose **Use mutual confidentiality clause**. The paragraph changes while its tag remains.

Continue with an Editor that has finished loading, and use `superdoc.activeEditor.doc` as `doc`. The
[clause sample](/fixtures/clause-library-sample.docx) already contains the required slot; the Quickstart sample does not.
Create `src/replace-clause.ts` with this helper and call it from your clause picker:

Find the slot by tag, require one block-level control, then replace its content:

```ts
import type { BrowserDocumentApi } from 'superdoc/ui';

export async function replaceClause(doc: BrowserDocumentApi, tag: string, content: string) {
  const { items } = await doc.contentControls.selectByTag({ tag });

  if (items.length !== 1) {
    throw new Error(`Expected one content control tagged "${tag}", found ${items.length}.`);
  }

  const [control] = items;
  if (control.kind !== 'block') {
    throw new Error(`Content control "${tag}" must be block-level.`);
  }

  return doc.contentControls.replaceContent({
    target: control.target,
    content,
    format: 'text',
  });
}

```

`replaceContent()` changes the content inside the control. Its tag and ID remain attached to the slot. Inspect the
mutation receipt before updating your application UI.

In the current Editor, replacement content is rebuilt as text. Keep each replaceable clause to one paragraph. Your
application can store approval state, versions, and clause metadata outside the DOCX.

Export through your existing [load and save flow](/editor/load-and-save-documents). Reopen the saved DOCX and confirm
that the chosen paragraph and its `agreement.confidentiality` tag remain.

Continue with [Lock template fields](/editor/content-controls/lock-template-fields) to keep a clause slot or its contents
from being removed. Use the [Document API reference](/document-api/reference/content-controls/) for every
content-control operation.


---

# Keep custom controls in sync

> Render selection-aware controls and confirm what each command did.



The Bold button from the [first control guide](/editor/custom-ui/controller-setup) changes as you move the selection. It
does not inspect the document DOM. It renders command state from the Editor, runs the command, and handles the result.

## Follow one control through the loop [#follow-one-control-through-the-loop]

Choose each sample selection below, then press **Bold** when it is available. This simulation isolates the state your
control renders and the result it handles. The first control guide runs the same loop in a real Editor.

> **Interactive model: watch one control follow the selection**
>
> The sample selection is simulated. Normal text reports `enabled: true` and `active: false`. Pressing Bold changes `active` to `true` and reports `{ success: true }`. Bold text starts with `active: true`. A locked heading reports `enabled: false`, `active: false`, and a disabled reason. State describes what the control should render; the execution result confirms what the command did.


Every custom control repeats the same four steps:

1. Read the command's current state.
2. Render that state in your control.
3. Run the command from the user's action.
4. Inspect the result before reporting success or starting dependent work.

## Render the current state [#render-the-current-state]

Each command exposes a small state object:

| Field       | What your control should do                                       |
| ----------- | ----------------------------------------------------------------- |
| `enabled`   | Disable the action when it cannot run                             |
| `active`    | Show whether a toggle is applied                                  |
| `value`     | Show the current value for a picker                               |
| `reason`    | Explain why an action is disabled                                 |
| `supported` | Check whether the controller recognizes and can route the command |

Use `getState()` for the initial value and `observe()` for later changes. In React, `useSuperDocCommand(id)` does both
and rerenders the component when the state changes.

Do not derive state from the rendered document DOM. Selection, mode, history, and document content can all change
whether a command is available.

Disable a control when `enabled` is `false`. Show `reason` when it helps someone recover. Remove the control only when
the workflow does not need it.

## Confirm the command result [#confirm-the-command-result]

Use `executeAsync()` when your interface or later work depends on the action:

| Result               | Meaning                                               |
| -------------------- | ----------------------------------------------------- |
| `false`              | The controller could not route the command            |
| `true`               | The host completed the command without a receipt      |
| `{ success: true }`  | The document operation completed                      |
| `{ success: false }` | The receipt explains why the operation did not finish |

Command state is a snapshot, so check the result even when `enabled` was `true`. For receipt failure codes, see
[Receipts and errors](/document-api/receipts-and-errors).

## Choose commands deliberately [#choose-commands-deliberately]

Use `BuiltInCommandId` when a control accepts only SuperDoc commands. Use `CommandId` when it can also accept commands
registered by your application. Both types are exported from `superdoc/ui`.

`ui.commands.ids` lists the commands known to the current controller, and `ui.commands.has(id)` checks one ID. Use those
methods for discovery or capability checks. Choose the actions your workflow needs instead of generating a toolbar from
the entire list.

Next, [build a custom toolbar](/editor/custom-ui/formatting-controls) that applies this loop to Bold, font, and size. If
you do not need to own the toolbar's markup or interaction design, configure the
[built-in toolbar](/editor/built-in-ui/configure-the-toolbar) instead.


---

# Build a custom comments panel

> Render comment threads, create one from selected text, and connect each row to its document anchor.



Keep the [built-in comments UI](/editor/built-in-ui/comments) when its layout and actions fit your product. Build a
custom panel when your application needs to own the markup or workflow.

This guide covers one complete custom workflow: list root threads, add a comment to selected text, navigate to its
anchor, and resolve or reopen it. Use [Document API comments](/document-api/comments) for direct operations and the
complete comment lifecycle.

## Try the custom workflow [#try-the-custom-workflow]

The example replaces only the comments panel. SuperDoc still renders its toolbar and a three-page DOCX.

1. Choose **Show in document** on each existing thread. The document moves between the first and final pages.
2. On the middle page, select `approval criteria`, then choose **Comment on selection** and add a comment.
3. Resolve or reopen a thread.

> **Live example: replace the comments panel**
>
> SuperDoc renders the toolbar and a three-page DOCX while the application renders the comments panel. Existing threads on the first and final pages make `setActive()` and `scrollTo()` visible; the middle page provides text for `createFromCapture()`. The panel observes `ui.comments` and reports resolve or reopen receipts. Setting `ui.comments` to `false` removes the built-in comments panel without removing comments from the document.


The panel is application markup driven by `ui.comments`. The document, selection, comment anchors, and mutations still
belong to SuperDoc.

## Build the same panel [#build-the-same-panel]

Start from [Build your first custom control](/editor/custom-ui/controller-setup). This example keeps `/sample.docx`, the
built-in toolbar, and every other built-in surface so comments remain the only new concern. If you already built a custom
toolbar, keep it and apply the same comments changes.

For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar, Editor, and panel mounts below:

```html
<div id="toolbar"></div>

<main class="comments-layout">
  <div id="editor" style="height: 70vh; overflow: auto"></div>

  <aside aria-labelledby="comments-heading">
    <h2 id="comments-heading">Comments</h2>
    <p id="comment-count">Opening document...</p>

    <button id="start-comment" type="button" disabled>Comment on selection</button>
    <form id="comment-composer" hidden>
      <label for="comment-text">New comment</label>
      <textarea id="comment-text" rows="3"></textarea>
      <button id="add-comment" type="submit" disabled>Add comment</button>
      <button id="cancel-comment" type="button">Cancel</button>
    </form>

    <p id="comments-status" role="status">Select text to start a comment.</p>
    <ul id="comment-list"></ul>
  </aside>
</main>

<script type="module" src="/src/main.ts"></script>

```

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { CommentsSlice, SelectionCapture, SelectionSlice, WorkflowReceipt } from 'superdoc/ui';
import 'superdoc/style.css';

function getElement<T extends Element>(selector: string): T {
  const element = document.querySelector<T>(selector);
  if (!element) throw new Error(`Missing comments element: ${selector}`);
  return element;
}

const startComment = getElement<HTMLButtonElement>('#start-comment');
const toolbar = getElement<HTMLDivElement>('#toolbar');
const composer = getElement<HTMLFormElement>('#comment-composer');
const commentText = getElement<HTMLTextAreaElement>('#comment-text');
const addComment = getElement<HTMLButtonElement>('#add-comment');
const cancelComment = getElement<HTMLButtonElement>('#cancel-comment');
const commentCount = getElement<HTMLParagraphElement>('#comment-count');
const commentsStatus = getElement<HTMLParagraphElement>('#comments-status');
const commentList = getElement<HTMLUListElement>('#comment-list');

const editorUi = {
  comments: false,
  toolbar: { container: toolbar, responsiveTo: 'container' },
} satisfies UIConfig;
let capture: SelectionCapture | null = null;
let stopBindings: (() => void) | null = null;

function report(receipt: Awaited<WorkflowReceipt>, success: string): boolean {
  commentsStatus.textContent = receipt.success ? success : receipt.failure.message;
  return receipt.success;
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  user: { name: 'Alex Rivera', email: 'alex@example.com' },
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    stopBindings?.();
    capture = null;
    composer.hidden = true;
    commentText.value = '';
    addComment.disabled = true;
    const { ui } = readySuperDoc;
    let selectionIsEmpty = true;

    let pendingCapture: SelectionCapture | null = null;

    const updateComposer = () => {
      commentText.disabled = pendingCapture !== null;
      addComment.disabled = pendingCapture !== null || !capture || commentText.value.trim().length === 0;
      cancelComment.disabled = pendingCapture !== null;
    };

    const closeComposer = () => {
      capture = null;
      commentText.value = '';
      composer.hidden = true;
      startComment.disabled = selectionIsEmpty;
      updateComposer();
      startComment.focus();
    };

    const renderSelection = (selection: SelectionSlice) => {
      selectionIsEmpty = selection.empty;
      startComment.disabled = selection.empty || !composer.hidden;
    };

    const renderComments = (commentState: CommentsSlice) => {
      const threads = commentState.items.filter((comment) => !comment.parentCommentId);
      commentCount.textContent =
        commentState.listStatus === 'pending' ? 'Loading comments...' : `${threads.length} threads`;
      commentList.replaceChildren();

      for (const thread of threads) {
        const row = document.createElement('li');
        const body = document.createElement('span');
        const show = document.createElement('button');
        const toggleStatus = document.createElement('button');

        body.textContent = thread.text || 'Comment without text';
        show.type = 'button';
        show.textContent = 'Show in document';
        show.addEventListener('click', async () => {
          if (!ui.comments.setActive(thread.id)) {
            commentsStatus.textContent = 'The comment is no longer available.';
            return;
          }
          const result = await ui.comments.scrollTo(thread.id);
          commentsStatus.textContent = result.success
            ? 'Showing the comment in the document.'
            : (result.reason ?? 'The comment could not be shown.');
        });

        toggleStatus.type = 'button';
        toggleStatus.textContent = thread.status === 'resolved' ? 'Reopen' : 'Resolve';
        toggleStatus.addEventListener('click', async () => {
          const receipt =
            thread.status === 'resolved' ? await ui.comments.reopen(thread.id) : await ui.comments.resolve(thread.id);
          report(receipt, thread.status === 'resolved' ? 'Comment reopened.' : 'Comment resolved.');
        });

        row.append(body, show, toggleStatus);
        commentList.append(row);
      }
    };

    const captureSelection = () => {
      capture = ui.selection.capture();
    };

    const openComposer = (event: MouseEvent) => {
      if (event.detail === 0) capture = ui.selection.capture();
      else capture ??= ui.selection.capture();
      if (!capture) {
        commentsStatus.textContent = 'Select text before starting a comment.';
        return;
      }
      composer.hidden = false;
      startComment.disabled = true;
      commentText.focus();
      updateComposer();
    };

    const createComment = async (event: SubmitEvent) => {
      event.preventDefault();
      if (!capture || pendingCapture) return;
      // Lock the composer until the receipt settles so a repeated submit cannot
      // send the same draft twice, and a draft opened later is not closed by
      // this receipt.
      pendingCapture = capture;
      updateComposer();
      const receipt = await ui.comments.createFromCapture(pendingCapture, { text: commentText.value.trim() });
      const stillCurrent = capture === pendingCapture;
      pendingCapture = null;
      if (report(receipt, 'Comment added.') && stillCurrent) closeComposer();
      else updateComposer();
    };

    renderSelection(ui.selection.getSnapshot());
    renderComments(ui.comments.getSnapshot());
    const stopSelection = ui.selection.observe(renderSelection);
    const stopComments = ui.comments.observe(renderComments);

    startComment.addEventListener('mousedown', captureSelection);
    startComment.addEventListener('click', openComposer);
    commentText.addEventListener('input', updateComposer);
    composer.addEventListener('submit', createComment);
    cancelComment.addEventListener('click', closeComposer);

    stopBindings = () => {
      stopSelection();
      stopComments();
      startComment.removeEventListener('mousedown', captureSelection);
      startComment.removeEventListener('click', openComposer);
      commentText.removeEventListener('input', updateComposer);
      composer.removeEventListener('submit', createComment);
      cancelComment.removeEventListener('click', closeComposer);
    };
  },
  onContentError: ({ error }) => {
    commentsStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    commentsStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopBindings?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useRef, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { SelectionCapture, WorkflowReceipt } from 'superdoc/ui';
import {
  SuperDocUIProvider,
  useSetSuperDoc,
  useSuperDocComments,
  useSuperDocSelection,
  useSuperDocUI,
} from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = { comments: false } satisfies UIConfig;
const currentUser = { name: 'Alex Rivera', email: 'alex@example.com' };

export default function App() {
  return (
    <SuperDocUIProvider>
      <main className='comments-layout'>
        <Editor />
        <CommentsPanel />
      </main>
    </SuperDocUIProvider>
  );
}

function Editor() {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/sample.docx'
      onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
      ui={editorUi}
      user={currentUser}
    />
  );
}

function CommentsPanel() {
  const ui = useSuperDocUI();
  const commentState = useSuperDocComments();
  const selection = useSuperDocSelection();
  const startCommentRef = useRef<HTMLButtonElement>(null);
  const pressedCapture = useRef<SelectionCapture | null>(null);
  const restoreFocus = useRef(false);
  const [capture, setCapture] = useState<SelectionCapture | null>(null);
  const [pending, setPending] = useState(false);
  const [text, setText] = useState('');
  const [status, setStatus] = useState('Select text to start a comment.');

  const threads = commentState.items.filter((comment) => !comment.parentCommentId);

  useEffect(() => {
    if (capture || !restoreFocus.current) return;
    restoreFocus.current = false;
    startCommentRef.current?.focus();
  }, [capture]);

  function report(receipt: Awaited<WorkflowReceipt>, success: string): boolean {
    setStatus(receipt.success ? success : receipt.failure.message);
    return receipt.success;
  }

  function captureSelection() {
    pressedCapture.current = ui?.selection.capture() ?? null;
  }

  function openComposer(event: React.MouseEvent<HTMLButtonElement>) {
    const nextCapture =
      event.detail === 0
        ? (ui?.selection.capture() ?? null)
        : (pressedCapture.current ?? ui?.selection.capture() ?? null);
    pressedCapture.current = null;
    if (!nextCapture) {
      setStatus('Select text before starting a comment.');
      return;
    }
    setCapture(nextCapture);
  }

  function closeComposer() {
    restoreFocus.current = true;
    pressedCapture.current = null;
    setCapture(null);
    setText('');
  }

  async function createComment() {
    if (!ui || !capture || pending) return;
    // Lock the composer until the receipt settles so a repeated submit cannot
    // send the same draft twice, and a draft opened later is not closed by
    // this receipt.
    setPending(true);
    const receipt = await ui.comments.createFromCapture(capture, { text: text.trim() });
    setPending(false);
    if (report(receipt, 'Comment added.')) closeComposer();
  }

  async function showThread(commentId: string) {
    if (!ui?.comments.setActive(commentId)) {
      setStatus('The comment is no longer available.');
      return;
    }
    const result = await ui.comments.scrollTo(commentId);
    setStatus(
      result.success ? 'Showing the comment in the document.' : (result.reason ?? 'The comment could not be shown.'),
    );
  }

  if (!ui) return <aside aria-label='Comments'>Opening document...</aside>;

  return (
    <aside aria-labelledby='comments-heading'>
      <h2 id='comments-heading'>Comments</h2>
      <p>{commentState.listStatus === 'pending' ? 'Loading comments...' : `${threads.length} threads`}</p>

      <button
        disabled={selection.empty || capture !== null}
        onClick={openComposer}
        onMouseDown={captureSelection}
        ref={startCommentRef}
        type='button'
      >
        Comment on selection
      </button>

      {capture && (
        <form
          onSubmit={(event) => {
            event.preventDefault();
            void createComment();
          }}
        >
          <label>
            New comment
            <textarea
              autoFocus
              disabled={pending}
              onChange={(event) => setText(event.target.value)}
              rows={3}
              value={text}
            />
          </label>
          <button disabled={pending || text.trim().length === 0} type='submit'>
            Add comment
          </button>
          <button disabled={pending} onClick={closeComposer} type='button'>
            Cancel
          </button>
        </form>
      )}

      <ul>
        {threads.map((thread) => (
          <li aria-current={thread.id === commentState.activeId ? 'true' : undefined} key={thread.id}>
            <span>{thread.text || 'Comment without text'}</span>
            <button onClick={() => void showThread(thread.id)} type='button'>
              Show in document
            </button>
            <button
              onClick={async () => {
                const receipt =
                  thread.status === 'resolved'
                    ? await ui.comments.reopen(thread.id)
                    : await ui.comments.resolve(thread.id);
                report(receipt, thread.status === 'resolved' ? 'Comment reopened.' : 'Comment resolved.');
              }}
              type='button'
            >
              {thread.status === 'resolved' ? 'Reopen' : 'Resolve'}
            </button>
          </li>
        ))}
      </ul>

      <p aria-live='polite' role='status'>
        {status}
      </p>
    </aside>
  );
}

```


Both versions follow the same loop:

1. Set `ui.comments` to `false` to remove SuperDoc's comments panel without removing comments from the DOCX.
2. Observe `ui.comments` and render root threads from its current snapshot.
3. Capture the document selection before the composer takes focus.
4. Run `createFromCapture()`, `setActive()` with `scrollTo()`, or `resolve()` and `reopen()`. Show the returned result.

## Keep the comment target stable [#keep-the-comment-target-stable]

Capture the selection when the composer opens. The pointer path captures on `mousedown`, before focus moves to the
button. Keyboard activation captures in the click handler. Submitting the saved capture keeps the draft anchored to the
text that started it, even if the selection changes while someone writes.

Use `ui.comments.createFromSelection()` only for an immediate action that does not move focus into a composer. Do not
reconstruct a comment target from DOM ranges. See [Selection and viewport](/editor/custom-ui/selection-and-viewport)
when you also need to position an application-owned popover.

## Match the configured actions [#match-the-configured-actions]

With the built-in panel disabled, `ui.comments.layout` no longer affects your markup. The configured
`interaction.comments.level` still limits controller mutations. Render only the actions your application allows. Handle
every receipt because document mode or stale state can still block an action. See the
[comments configuration reference](/editor/built-in-ui/comments#configure-comments) for the complete contract.

## Verify the workflow [#verify-the-workflow]

Run the project and add a comment to selected text. Confirm that the new row appears, **Show in document** returns to its
anchor, and Resolve changes to Reopen. The built-in toolbar should remain visible, and SuperDoc's comments panel should
not appear beside yours.

To accept or reject revisions, build a [tracked-change panel](/editor/custom-ui/tracked-changes). That guide restarts
from the setup project with its own document and markup, so it is a separate workflow rather than a panel you add to
this one. Otherwise, return to the [Custom UI overview](/editor/custom-ui/overview) and choose another workflow.


---

# Build a document field panel

> Observe document fields, navigate to each one, and update typed values from application UI.



Built-in content-control chrome helps someone recognize and click a field in the document. Build a custom panel when
your application needs to keep every field visible, move between them, or render a field-specific input.

This guide replaces only the field panel. SuperDoc continues to render the toolbar, document, selection, and
content-control chrome.

## Try the field workflow [#try-the-field-workflow]

The example loads a text field and a checkbox on two short pages.

1. Change **Client name**, then choose **Update**. The value changes in the document.
2. Choose **Show in document** for **Review approved**. The Editor moves to the checkbox on page 2.
3. Check **Approved**, then return to **Client name** with **Show in document**.

> **Live example: edit document fields from an application-owned panel**
>
> SuperDoc renders its toolbar and a two-page DOCX while the application renders a persistent field panel. Show in document moves between a text field on page 1 and a checkbox on page 2. The panel observes `ui.contentControls`, runs `activeEditor.doc.contentControls.text.setValue()` or `checkbox.setState()`, and stays pending until the observed field contains the new value.


The panel follows the same custom-UI loop as Comments and Track changes: observe Editor state, render application
controls, run an action, and wait for the observed state to confirm the result.

## Build the same panel [#build-the-same-panel]

Start from [Build your first custom control](/editor/custom-ui/controller-setup). Download the
[two-page field fixture](/fixtures/custom-content-controls-workflow.docx) to your app's `public` directory as
`contract.docx`.

For Vanilla, replace the contents of `<body>` in `index.html` with the Editor and panel below:

```html
<main class="fields-layout">
  <div id="editor" style="height: 70vh; overflow: auto"></div>

  <aside aria-labelledby="fields-heading">
    <h2 id="fields-heading">Document fields</h2>
    <p id="fields-count">Opening document...</p>
    <ul id="field-list"></ul>
    <p id="fields-status" role="status">Choose a field to edit it.</p>
  </aside>
</main>

<script type="module" src="/src/main.ts"></script>

```

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { ContentControlInfo, ContentControlsSlice } from 'superdoc/ui';
import 'superdoc/style.css';

type PendingMutation =
  | { checked: boolean; controlId: string; controlName: string; kind: 'checkbox' }
  | { controlId: string; controlName: string; kind: 'text'; value: string };

function getElement<T extends Element>(selector: string): T {
  const element = document.querySelector<T>(selector);
  if (!element) throw new Error(`Missing field panel element: ${selector}`);
  return element;
}

function fieldName(control: ContentControlInfo) {
  return control.properties.alias ?? control.properties.tag ?? control.controlType;
}

function isContentLocked(control: ContentControlInfo) {
  return control.lockMode === 'contentLocked' || control.lockMode === 'sdtContentLocked';
}

function mutationIsObserved(control: ContentControlInfo, mutation: PendingMutation) {
  if (control.id !== mutation.controlId) return false;
  if (mutation.kind === 'checkbox') return control.properties.checked === mutation.checked;
  return control.text === mutation.value;
}

const fieldCount = getElement<HTMLParagraphElement>('#fields-count');
const fieldList = getElement<HTMLUListElement>('#field-list');
const fieldsStatus = getElement<HTMLParagraphElement>('#fields-status');

const drafts = new Map<string, string>();
let pendingMutation: PendingMutation | null = null;
let stopContentControls: (() => void) | null = null;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: ({ superdoc: readySuperDoc }) => {
    stopContentControls?.();
    const documentApi = readySuperDoc.activeEditor?.doc;
    if (!documentApi) throw new Error('The Document API is not ready.');

    const { ui } = readySuperDoc;

    const showField = async (control: ContentControlInfo) => {
      if (pendingMutation) return;
      const name = fieldName(control);
      const result = await ui.contentControls.focus({ id: control.id });
      fieldsStatus.textContent = result.success
        ? `Showing ${name} in the document.`
        : `${name} could not be shown in the document.`;
    };

    // Rerender from the last observed snapshot so pending state changes are
    // reflected without an extra catalog read.
    let lastControls: ContentControlsSlice | null = null;
    let mutationInFlight = false;

    const failMutation = (message: string) => {
      pendingMutation = null;
      fieldsStatus.textContent = message;
      if (lastControls) render(lastControls);
    };

    let catalogRequest = 0;
    const readFields = async (
      snapshot: ContentControlsSlice,
      failureMessage = 'The field list could not be refreshed.',
    ) => {
      const request = ++catalogRequest;
      try {
        const catalog = await documentApi.contentControls.list();
        if (request !== catalogRequest) return;
        render({ ...snapshot, status: 'ready', items: catalog.items, total: catalog.total });
      } catch {
        if (request !== catalogRequest) return;
        if (!mutationInFlight) failMutation(failureMessage);
      }
    };

    const refreshFields = async () => {
      await readFields(
        ui.contentControls.getSnapshot(),
        'The document changed, but the field list could not be refreshed.',
      );
    };

    const updateTextField = async (control: ContentControlInfo, value: string) => {
      if (pendingMutation) return;
      mutationInFlight = true;
      catalogRequest += 1;
      const name = fieldName(control);
      // Keep the submitted value as the draft so a failed update does not
      // reset the input to the document's old text.
      drafts.set(control.id, value);
      pendingMutation = { controlId: control.id, controlName: name, kind: 'text', value };
      fieldsStatus.textContent = `Updating ${name}…`;
      if (lastControls) render(lastControls);

      try {
        const receipt = await documentApi.contentControls.text.setValue({ target: control.target, value });
        mutationInFlight = false;
        if (!receipt.success) failMutation(receipt.failure.message);
        else await refreshFields();
      } catch (error) {
        mutationInFlight = false;
        failMutation(error instanceof Error ? error.message : `${name} could not be updated.`);
      }
    };

    const updateCheckbox = async (control: ContentControlInfo, checked: boolean) => {
      if (pendingMutation) return;
      mutationInFlight = true;
      catalogRequest += 1;
      const name = fieldName(control);
      pendingMutation = { checked, controlId: control.id, controlName: name, kind: 'checkbox' };
      fieldsStatus.textContent = `Updating ${name}…`;
      if (lastControls) render(lastControls);

      try {
        const receipt = await documentApi.contentControls.checkbox.setState({ target: control.target, checked });
        mutationInFlight = false;
        if (!receipt.success) failMutation(receipt.failure.message);
        else await refreshFields();
      } catch (error) {
        mutationInFlight = false;
        failMutation(error instanceof Error ? error.message : `${name} could not be updated.`);
      }
    };

    const render = (controls: ContentControlsSlice) => {
      lastControls = controls;
      const currentMutation = pendingMutation;
      const observedMutation =
        currentMutation && controls.items.find((control) => mutationIsObserved(control, currentMutation));
      if (currentMutation && observedMutation && !mutationInFlight) {
        const completedMutation = currentMutation;
        pendingMutation = null;
        if (completedMutation.kind === 'text') drafts.delete(completedMutation.controlId);
        fieldsStatus.textContent =
          completedMutation.kind === 'checkbox'
            ? `${completedMutation.controlName} ${completedMutation.checked ? 'checked' : 'unchecked'}.`
            : `${completedMutation.controlName} updated.`;
      }

      fieldCount.textContent = controls.status === 'pending' ? 'Loading fields…' : `${controls.total} document fields`;
      fieldList.replaceChildren();

      for (const control of controls.items) {
        const row = document.createElement('li');
        const label = document.createElement('strong');
        const show = document.createElement('button');
        const name = fieldName(control);
        const locked = isContentLocked(control);

        label.textContent = name;
        show.type = 'button';
        show.textContent = controls.activeIds.includes(control.id) ? 'Showing' : 'Show in document';
        show.disabled = pendingMutation !== null;
        show.addEventListener('click', () => void showField(control));
        row.append(label, show);

        if (control.controlType === 'text') {
          const input = document.createElement('input');
          const update = document.createElement('button');
          const currentValue = control.text ?? '';

          input.type = 'text';
          input.value = drafts.get(control.id) ?? currentValue;
          input.disabled = locked || pendingMutation !== null;
          input.setAttribute('aria-label', `Value for ${name}`);
          input.addEventListener('input', () => {
            drafts.set(control.id, input.value);
            update.disabled = locked || pendingMutation !== null || input.value === currentValue;
          });
          update.type = 'button';
          update.textContent = pendingMutation?.controlId === control.id ? 'Updating…' : 'Update';
          update.disabled = locked || pendingMutation !== null || input.value === currentValue;
          update.addEventListener('click', () => void updateTextField(control, input.value));
          row.append(input, update);
        }

        if (control.controlType === 'checkbox') {
          const checkboxLabel = document.createElement('label');
          const checkbox = document.createElement('input');

          checkbox.type = 'checkbox';
          checkbox.checked =
            pendingMutation?.kind === 'checkbox' && pendingMutation.controlId === control.id
              ? pendingMutation.checked
              : (control.properties.checked ?? false);
          checkbox.disabled = locked || pendingMutation !== null;
          checkbox.addEventListener('change', () => void updateCheckbox(control, checkbox.checked));
          checkboxLabel.append(checkbox, ' Approved');
          row.append(checkboxLabel);
        }

        fieldList.append(row);
      }
    };

    const stop = ui.contentControls.observe((snapshot) => {
      void readFields(snapshot);
    });
    stopContentControls = () => {
      catalogRequest += 1;
      stop();
    };
  },
  onContentError: ({ error }) => {
    fieldsStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    fieldsStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopContentControls?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useRef, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { ContentControlInfo, ContentControlsSlice } from 'superdoc/ui';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocHost, useSuperDocUI } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

type PendingMutation =
  | { checked: boolean; controlId: string; controlName: string; kind: 'checkbox' }
  | { controlId: string; controlName: string; kind: 'text'; value: string };

function fieldName(control: ContentControlInfo) {
  return control.properties.alias ?? control.properties.tag ?? control.controlType;
}

function isContentLocked(control: ContentControlInfo) {
  return control.lockMode === 'contentLocked' || control.lockMode === 'sdtContentLocked';
}

function mutationIsObserved(control: ContentControlInfo, mutation: PendingMutation) {
  if (control.id !== mutation.controlId) return false;
  if (mutation.kind === 'checkbox') return control.properties.checked === mutation.checked;
  return control.text === mutation.value;
}

export default function App() {
  return (
    <SuperDocUIProvider>
      <main className='fields-layout'>
        <Editor />
        <FieldPanel />
      </main>
    </SuperDocUIProvider>
  );
}

function Editor() {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/contract.docx'
      onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
    />
  );
}

function FieldPanel() {
  const host = useSuperDocHost();
  const ui = useSuperDocUI();
  const [fields, setFields] = useState<ContentControlsSlice>({
    status: 'pending',
    items: [],
    total: 0,
    activeId: null,
    activeIds: [],
  });
  const [drafts, setDrafts] = useState<Record<string, string>>({});
  const [pendingMutation, setPendingMutation] = useState<PendingMutation | null>(null);
  const [status, setStatus] = useState('Choose a field to edit it.');
  const catalogRequest = useRef(0);
  const mutationInFlight = useRef(false);

  async function readFields(snapshot: ContentControlsSlice, failureMessage = 'The field list could not be refreshed.') {
    const request = ++catalogRequest.current;
    try {
      const catalog = await host?.activeEditor?.doc?.contentControls?.list?.();
      if (!catalog) throw new Error('Field catalog unavailable.');
      if (request !== catalogRequest.current) return;
      setFields({ ...snapshot, status: 'ready', items: catalog.items, total: catalog.total });
    } catch {
      if (request !== catalogRequest.current) return;
      if (mutationInFlight.current) return;
      setPendingMutation(null);
      setStatus(failureMessage);
    }
  }

  useEffect(() => {
    if (!ui) return;
    const stop = ui.contentControls.observe((snapshot) => {
      void readFields(snapshot);
    });
    return () => {
      catalogRequest.current += 1;
      stop();
    };
  }, [ui, host]);

  async function refreshFields() {
    if (!ui) {
      setPendingMutation(null);
      setStatus('Editor unavailable.');
      return;
    }
    await readFields(
      ui.contentControls.getSnapshot(),
      'The document changed, but the field list could not be refreshed.',
    );
  }

  useEffect(() => {
    if (!pendingMutation || mutationInFlight.current) return;
    const updatedField = fields.items.find((field) => mutationIsObserved(field, pendingMutation));
    if (!updatedField) return;

    if (pendingMutation.kind === 'text') {
      setDrafts((current) => {
        const next = { ...current };
        delete next[pendingMutation.controlId];
        return next;
      });
    }
    setStatus(
      pendingMutation.kind === 'checkbox'
        ? `${pendingMutation.controlName} ${pendingMutation.checked ? 'checked' : 'unchecked'}.`
        : `${pendingMutation.controlName} updated.`,
    );
    setPendingMutation(null);
  }, [fields.items, pendingMutation]);

  async function showField(control: ContentControlInfo) {
    if (!ui || pendingMutation) return;
    const name = fieldName(control);
    const result = await ui.contentControls.focus({ id: control.id });
    setStatus(result.success ? `Showing ${name} in the document.` : `${name} could not be shown in the document.`);
  }

  async function updateTextField(control: ContentControlInfo, value: string) {
    if (pendingMutation || mutationInFlight.current) return;
    const documentApi = host?.activeEditor?.doc;
    if (!documentApi?.contentControls?.text?.setValue) {
      setStatus('Text field editing is unavailable.');
      return;
    }

    const name = fieldName(control);
    const mutation: PendingMutation = { controlId: control.id, controlName: name, kind: 'text', value };
    mutationInFlight.current = true;
    catalogRequest.current += 1;
    setPendingMutation(mutation);
    setStatus(`Updating ${name}…`);
    try {
      const receipt = await documentApi.contentControls.text.setValue({ target: control.target, value });
      mutationInFlight.current = false;
      if (!receipt.success) {
        setPendingMutation(null);
        setStatus(receipt.failure.message);
      } else await refreshFields();
    } catch (error) {
      mutationInFlight.current = false;
      setPendingMutation(null);
      setStatus(error instanceof Error ? error.message : `${name} could not be updated.`);
    }
  }

  async function updateCheckbox(control: ContentControlInfo, checked: boolean) {
    if (pendingMutation || mutationInFlight.current) return;
    const documentApi = host?.activeEditor?.doc;
    if (!documentApi?.contentControls?.checkbox?.setState) {
      setStatus('Checkbox editing is unavailable.');
      return;
    }

    const name = fieldName(control);
    const mutation: PendingMutation = { checked, controlId: control.id, controlName: name, kind: 'checkbox' };
    mutationInFlight.current = true;
    catalogRequest.current += 1;
    setPendingMutation(mutation);
    setStatus(`Updating ${name}…`);
    try {
      const receipt = await documentApi.contentControls.checkbox.setState({ target: control.target, checked });
      mutationInFlight.current = false;
      if (!receipt.success) {
        setPendingMutation(null);
        setStatus(receipt.failure.message);
      } else await refreshFields();
    } catch (error) {
      mutationInFlight.current = false;
      setPendingMutation(null);
      setStatus(error instanceof Error ? error.message : `${name} could not be updated.`);
    }
  }

  return (
    <aside aria-labelledby='fields-heading'>
      <h2 id='fields-heading'>Document fields</h2>
      <p>{fields.status === 'pending' ? 'Loading fields…' : `${fields.total} document fields`}</p>

      <ul>
        {fields.items.map((field) => {
          const name = fieldName(field);
          const locked = isContentLocked(field);
          const draft = drafts[field.id] ?? field.text ?? '';
          const checked =
            pendingMutation?.kind === 'checkbox' && pendingMutation.controlId === field.id
              ? pendingMutation.checked
              : (field.properties.checked ?? false);

          return (
            <li aria-current={fields.activeIds.includes(field.id) ? 'true' : undefined} key={field.id}>
              <strong>{name}</strong>
              <button disabled={pendingMutation !== null} onClick={() => void showField(field)} type='button'>
                {fields.activeIds.includes(field.id) ? 'Showing' : 'Show in document'}
              </button>

              {field.controlType === 'text' && (
                <>
                  <input
                    aria-label={`Value for ${name}`}
                    disabled={locked || pendingMutation !== null}
                    onChange={(event) => setDrafts((current) => ({ ...current, [field.id]: event.target.value }))}
                    type='text'
                    value={draft}
                  />
                  <button
                    disabled={locked || pendingMutation !== null || draft === (field.text ?? '')}
                    onClick={() => void updateTextField(field, draft)}
                    type='button'
                  >
                    {pendingMutation?.kind === 'text' && pendingMutation.controlId === field.id
                      ? 'Updating…'
                      : 'Update'}
                  </button>
                </>
              )}

              {field.controlType === 'checkbox' && (
                <label>
                  <input
                    checked={checked}
                    disabled={locked || pendingMutation !== null}
                    onChange={(event) => void updateCheckbox(field, event.target.checked)}
                    type='checkbox'
                  />
                  Approved
                </label>
              )}
            </li>
          );
        })}
      </ul>

      <p aria-live='polite' role='status'>
        {status}
      </p>
    </aside>
  );
}

```


## Connect field state to typed mutations [#connect-field-state-to-typed-mutations]

The panel uses two public surfaces with different jobs:

* `ui.contentControls` supplies the observed field catalog, active field IDs, and `focus()` navigation.
* `activeEditor.doc.contentControls` supplies type-specific document mutations. This example uses `text.setValue()` and
  `checkbox.setState()`.

Each catalog item carries its `controlType`, `lockMode`, properties, current value, and mutation target. Use those values
instead of inspecting the rendered document DOM.

Keep every action disabled while a mutation is pending. A successful receipt confirms that the Document API accepted
the mutation. Confirm the updated field value before clearing the draft and reporting success.

In `superdoc@2.12.0`, the observed catalog can remain stale after a programmatic update. These examples read
`contentControls.list()` after mutations and observer notifications, ignoring older responses. A failed refresh reports
that the document changed but the panel could not refresh; it does not report the mutation as failed.

## Highlight a field from your panel [#highlight-a-field-from-your-panel]

Use `highlight()` when a pointer enters a panel row, and `clearHighlight()` when it leaves:

```ts
row.addEventListener('pointerenter', () => {
  void ui.contentControls.highlight({ id: control.id });
});
row.addEventListener('pointerleave', () => ui.contentControls.clearHighlight());
```

The browser Editor highlights the control's text across paragraphs and table cells without moving focus, selection,
or scroll. One highlight is active at a time. A successful request replaces it; a failed request preserves it.
The result is `{ success: true }` or `{ success: false, reason }`. Unknown IDs, empty controls, and unavailable Editors
fail explicitly. Offscreen text appears highlighted when its page mounts. Clearing cancels pending requests, and
opening another document clears the highlight. This also works in viewing mode and does not change saved document content.

The default background is yellow (`#ffff00`). Set a CSS variable on your Editor wrapper to override it:

```css
.contract-editor {
  --sd-content-controls-highlight-bg: #b9e8ff;
}
```

No JavaScript color option is needed. Removing the variable restores the yellow default.

## Render the field type you support [#render-the-field-type-you-support]

This panel handles text fields and checkboxes. Date, choice, rich-text, and repeating controls have their own operations.
Render an input only when its `controlType` matches an operation your panel implements. Disable content mutations for
`contentLocked` and `sdtContentLocked` fields, and still inspect every mutation receipt.

Use [Content controls](/editor/content-controls) to create template fields, fill repeated values, and choose lock modes.
The [Document API reference](/document-api/reference/content-controls/) lists every content-control type and operation.

## Verify the field panel [#verify-the-field-panel]

Run the project. Move to the checkbox on page 2, change it, then return to the text field on page 1 and update its value.
Each successful mutation should appear in both the document and the panel before its status changes from pending.

Return to the [Custom UI overview](/editor/custom-ui/overview) to choose another workflow.


---

# Build an application-owned context menu

> Replace SuperDoc's menu while keeping actions connected to document entities and selections.



Add application actions to the [built-in context menu](/editor/built-in-ui/context-menus) with `ui.contextMenu.sections`
when its interaction and presentation fit your product. Continue here only when your application needs to render the
entire menu.

Start from [Custom UI setup](/editor/custom-ui/controller-setup). Download the sample to `public/contract.docx`:

[Download the tracked-changes sample](/fixtures/tracked-changes.docx): Tracked insertions and deletions · DOCX


## Add the menu surface [#add-the-menu-surface]

For Vanilla, replace the contents of `<body>` in `index.html` with the Editor and menu below:

```html
<div id="editor"></div>

<div id="document-menu" aria-label="Document actions" hidden role="menu" tabindex="-1">
  <button data-menu-action="accept" role="menuitem" type="button">Accept change</button>
  <button data-menu-action="reject" role="menuitem" type="button">Reject change</button>
  <button data-menu-action="copy" role="menuitem" type="button">Copy selected text</button>
</div>

<p id="menu-status" aria-live="polite">Right-click the document or press Shift+F10.</p>

<script type="module" src="/src/main.ts"></script>

```

## Connect the menu to the document [#connect-the-menu-to-the-document]

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { BorrowedSuperDocUI, CommandExecutionResult } from 'superdoc/ui';
import 'superdoc/style.css';

const editorUi = { contextMenu: false } satisfies UIConfig;

const editorHost = document.querySelector<HTMLElement>('#editor');
const menu = document.querySelector<HTMLElement>('#document-menu');
const acceptButton = document.querySelector<HTMLButtonElement>('[data-menu-action="accept"]');
const rejectButton = document.querySelector<HTMLButtonElement>('[data-menu-action="reject"]');
const copyButton = document.querySelector<HTMLButtonElement>('[data-menu-action="copy"]');
const status = document.querySelector<HTMLParagraphElement>('#menu-status');

if (!editorHost || !menu || !acceptButton || !rejectButton || !copyButton || !status) {
  throw new Error('The custom context-menu controls are incomplete.');
}

type ChangeTarget = { id: string; story?: unknown };

let ui: BorrowedSuperDocUI | null = null;
let changeTarget: ChangeTarget | null = null;
let decisionPending = false;
// Each open menu gets its own id, and dismissal retires it, so a decision
// that settles late closes only the menu that started it and is still open.
let menuId = 0;
let stopSelectionObserver: (() => void) | null = null;

const menuItems = [acceptButton, rejectButton, copyButton];

const describeResult = (result: CommandExecutionResult, success: string): string => {
  if (result === false) return 'That action is unavailable.';
  if (typeof result === 'object' && !result.success) return result.failure.message;
  return success;
};

const closeMenu = (restoreEditorFocus: boolean) => {
  // Any dismissal retires the current menu, so an action still in flight
  // cannot close it later or move focus away from wherever the user went.
  menuId += 1;
  menu.hidden = true;
  changeTarget = null;
  stopSelectionObserver?.();
  stopSelectionObserver = null;
  if (restoreEditorFocus) superdoc.focus();
};

const syncDecisionButtons = () => {
  acceptButton.disabled = !changeTarget || decisionPending;
  rejectButton.disabled = !changeTarget || decisionPending;
};

const positionMenu = ({ x, y }: { x: number; y: number }) => {
  menu.style.position = 'fixed';
  menu.style.left = '0px';
  menu.style.top = '0px';
  menu.style.zIndex = '10';
  menu.hidden = false;

  const bounds = menu.getBoundingClientRect();
  const edge = 8;
  menu.style.left = `${Math.max(edge, Math.min(x, window.innerWidth - bounds.width - edge))}px`;
  menu.style.top = `${Math.max(edge, Math.min(y, window.innerHeight - bounds.height - edge))}px`;
};

const openMenu = (point: { x: number; y: number }) => {
  if (!ui) return;

  const context = ui.contextMenu.contextAt(point);
  const trackedChange = context.entities.find((entity) => entity.type === 'trackedChange');
  changeTarget = trackedChange
    ? { id: trackedChange.id, ...(trackedChange.story === undefined ? {} : { story: trackedChange.story }) }
    : null;

  menuId += 1;
  syncDecisionButtons();
  // The selection can still be settling when the menu opens. Follow it while
  // the menu is open so Copy enables once it is ready.
  stopSelectionObserver?.();
  stopSelectionObserver = ui.selection.observe((selection) => {
    copyButton.disabled = selection.status !== 'ready' || selection.empty || selection.quotedText.length === 0;
  });

  positionMenu(point);
  const firstAvailable = menuItems.find((item) => !item.disabled);
  (firstAvailable ?? menu).focus();
};

const decideChange = async (decision: 'accept' | 'reject', success: string) => {
  if (!ui || !changeTarget || decisionPending) return;
  const startedFrom = menuId;
  decisionPending = true;
  syncDecisionButtons();
  try {
    const result =
      decision === 'accept'
        ? await ui.trackChanges.acceptAsync(changeTarget)
        : await ui.trackChanges.rejectAsync(changeTarget);
    status.textContent = describeResult(result, success);
  } finally {
    decisionPending = false;
    syncDecisionButtons();
  }
  if (menuId === startedFrom) closeMenu(true);
};

const copySelection = async () => {
  const selection = ui?.selection.getSnapshot();
  const text = selection?.status === 'ready' && !selection.empty ? selection.quotedText : '';
  if (!text) return;
  const startedFrom = menuId;

  try {
    await navigator.clipboard.writeText(text);
    status.textContent = 'Selection copied.';
  } catch {
    status.textContent = 'The browser did not allow clipboard access.';
  }
  if (menuId === startedFrom) closeMenu(true);
};

const handleContextMenu = (event: MouseEvent) => {
  event.preventDefault();
  openMenu({ x: event.clientX, y: event.clientY });
};

const handleContextMenuKey = (event: KeyboardEvent) => {
  const requested = event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10');
  if (!requested || !ui) return;

  const anchor = ui.selection.getAnchorRect({ placement: 'center' });
  if (!anchor) return;

  event.preventDefault();
  openMenu({ x: (anchor.left + anchor.right) / 2, y: (anchor.top + anchor.bottom) / 2 });
};

const handleMenuKey = (event: KeyboardEvent) => {
  if (event.key === 'Escape' || event.key === 'Tab') {
    closeMenu(event.key === 'Escape');
    return;
  }

  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
  event.preventDefault();

  const available = menuItems.filter((item) => !item.disabled);
  const current = available.indexOf(document.activeElement as HTMLButtonElement);
  const direction = event.key === 'ArrowDown' ? 1 : -1;
  available[(current + direction + available.length) % available.length]?.focus();
};

const handleOutsidePointer = (event: PointerEvent) => {
  if (!menu.hidden && !menu.contains(event.target as Node)) closeMenu(false);
};

const handleViewportChange = () => {
  if (!menu.hidden) closeMenu(false);
};

const handleAccept = () => void decideChange('accept', 'Change accepted.');
const handleReject = () => void decideChange('reject', 'Change rejected.');
const handleCopy = () => void copySelection();

const superdoc = new SuperDoc({
  selector: editorHost,
  document: '/contract.docx',
  documentMode: 'suggesting',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    ui = readySuperDoc.ui;
  },
});

acceptButton.addEventListener('click', handleAccept);
rejectButton.addEventListener('click', handleReject);
copyButton.addEventListener('click', handleCopy);
editorHost.addEventListener('contextmenu', handleContextMenu);
editorHost.addEventListener('keydown', handleContextMenuKey, true);
menu.addEventListener('keydown', handleMenuKey);
document.addEventListener('pointerdown', handleOutsidePointer);
document.addEventListener('scroll', handleViewportChange, true);
window.addEventListener('resize', handleViewportChange);

window.addEventListener('beforeunload', () => {
  acceptButton.removeEventListener('click', handleAccept);
  rejectButton.removeEventListener('click', handleReject);
  copyButton.removeEventListener('click', handleCopy);
  editorHost.removeEventListener('contextmenu', handleContextMenu);
  editorHost.removeEventListener('keydown', handleContextMenuKey, true);
  menu.removeEventListener('keydown', handleMenuKey);
  document.removeEventListener('pointerdown', handleOutsidePointer);
  document.removeEventListener('scroll', handleViewportChange, true);
  window.removeEventListener('resize', handleViewportChange);
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useLayoutEffect, useRef, useState } from 'react';
import type { KeyboardEvent as ReactKeyboardEvent, MouseEvent as ReactMouseEvent } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { SuperDoc, UIConfig } from 'superdoc';
import type { CommandExecutionResult } from 'superdoc/ui';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocSelection, useSuperDocUI } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = { contextMenu: false } satisfies UIConfig;

type ChangeTarget = { id: string; story?: unknown };
type MenuState = {
  id: number;
  x: number;
  y: number;
  changeTarget: ChangeTarget | null;
};

export default function App() {
  return (
    <SuperDocUIProvider>
      <ContextMenuEditor />
    </SuperDocUIProvider>
  );
}

function ContextMenuEditor() {
  const ui = useSuperDocUI();
  // The selection can still be settling when the menu opens. Subscribing keeps
  // Copy in step with the live selection instead of the snapshot at open time.
  const selection = useSuperDocSelection();
  const setSuperDoc = useSetSuperDoc();
  const superdocRef = useRef<SuperDoc | null>(null);
  const menuRef = useRef<HTMLDivElement | null>(null);
  const menuIdRef = useRef(0);
  const [menu, setMenu] = useState<MenuState | null>(null);
  const [decisionPending, setDecisionPending] = useState(false);
  const [status, setStatus] = useState('Right-click the document or press Shift+F10.');

  const selectedText = selection.status === 'ready' && !selection.empty ? selection.quotedText : '';

  function closeMenu(restoreEditorFocus: boolean) {
    // Any dismissal retires the current menu, so an action still in flight
    // cannot close it later or move focus away from wherever the user went.
    menuIdRef.current += 1;
    setMenu(null);
    if (restoreEditorFocus) requestAnimationFrame(() => superdocRef.current?.focus());
  }

  function openMenu(point: { x: number; y: number }) {
    if (!ui) return;

    const context = ui.contextMenu.contextAt(point);
    const trackedChange = context.entities.find((entity) => entity.type === 'trackedChange');

    menuIdRef.current += 1;
    setMenu({
      id: menuIdRef.current,
      x: context.point?.x ?? point.x,
      y: context.point?.y ?? point.y,
      changeTarget: trackedChange
        ? {
            id: trackedChange.id,
            ...(trackedChange.story === undefined ? {} : { story: trackedChange.story }),
          }
        : null,
    });
  }

  useLayoutEffect(() => {
    const element = menuRef.current;
    if (!menu || !element) return;

    const bounds = element.getBoundingClientRect();
    const edge = 8;
    element.style.left = `${Math.max(edge, Math.min(menu.x, window.innerWidth - bounds.width - edge))}px`;
    element.style.top = `${Math.max(edge, Math.min(menu.y, window.innerHeight - bounds.height - edge))}px`;
    (element.querySelector<HTMLButtonElement>('button:not(:disabled)') ?? element).focus();
  }, [menu]);

  useEffect(() => {
    if (!menu) return;

    const handleOutsidePointer = (event: PointerEvent) => {
      if (!menuRef.current?.contains(event.target as Node)) closeMenu(false);
    };
    const handleViewportChange = () => closeMenu(false);

    document.addEventListener('pointerdown', handleOutsidePointer);
    document.addEventListener('scroll', handleViewportChange, true);
    window.addEventListener('resize', handleViewportChange);
    return () => {
      document.removeEventListener('pointerdown', handleOutsidePointer);
      document.removeEventListener('scroll', handleViewportChange, true);
      window.removeEventListener('resize', handleViewportChange);
    };
  }, [menu]);

  function report(result: CommandExecutionResult, success: string) {
    if (result === false) setStatus('That action is unavailable.');
    else if (result === true || result.success) setStatus(success);
    else setStatus(result.failure.message);
  }

  async function decideChange(decision: 'accept' | 'reject') {
    if (!ui || !menu?.changeTarget || decisionPending) return;
    // Only the menu that started this decision may close when it settles. The
    // user can dismiss it, or open another one, before the mutation lands.
    const menuId = menu.id;
    setDecisionPending(true);
    try {
      const result =
        decision === 'accept'
          ? await ui.trackChanges.acceptAsync(menu.changeTarget)
          : await ui.trackChanges.rejectAsync(menu.changeTarget);
      report(result, decision === 'accept' ? 'Change accepted.' : 'Change rejected.');
    } finally {
      setDecisionPending(false);
    }
    if (menuIdRef.current === menuId) closeMenu(true);
  }

  async function copySelection() {
    if (!selectedText) return;
    const menuId = menu?.id;
    try {
      await navigator.clipboard.writeText(selectedText);
      setStatus('Selection copied.');
    } catch {
      setStatus('The browser did not allow clipboard access.');
    }
    if (menuIdRef.current === menuId) closeMenu(true);
  }

  // SuperDocEditor renders its toolbar beside the editor container. Only
  // events from inside the editor open the document menu; the toolbar and any
  // other application chrome keep their own context behaviour.
  function isInsideEditor(target: EventTarget | null) {
    return target instanceof Element && target.closest('.superdoc-editor-container') !== null;
  }

  function handleContextMenu(event: ReactMouseEvent<HTMLElement>) {
    if (!isInsideEditor(event.target)) return;
    event.preventDefault();
    openMenu({ x: event.clientX, y: event.clientY });
  }

  function handleContextMenuKey(event: ReactKeyboardEvent<HTMLElement>) {
    const requested = event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10');
    if (!requested || !ui || !isInsideEditor(event.target)) return;

    const anchor = ui.selection.getAnchorRect({ placement: 'center' });
    if (!anchor) return;

    event.preventDefault();
    openMenu({ x: (anchor.left + anchor.right) / 2, y: (anchor.top + anchor.bottom) / 2 });
  }

  function handleMenuKey(event: ReactKeyboardEvent<HTMLDivElement>) {
    if (event.key === 'Escape' || event.key === 'Tab') {
      closeMenu(event.key === 'Escape');
      return;
    }
    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;

    event.preventDefault();
    const items = Array.from(menuRef.current?.querySelectorAll<HTMLButtonElement>('button:not(:disabled)') ?? []);
    const current = items.indexOf(document.activeElement as HTMLButtonElement);
    const direction = event.key === 'ArrowDown' ? 1 : -1;
    items[(current + direction + items.length) % items.length]?.focus();
  }

  return (
    <>
      <section onContextMenu={handleContextMenu} onKeyDownCapture={handleContextMenuKey}>
        <SuperDocEditor
          document='/contract.docx'
          documentMode='suggesting'
          onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
          onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
          onReady={({ superdoc }) => {
            superdocRef.current = superdoc;
            setSuperDoc(superdoc);
          }}
          ui={editorUi}
        />
      </section>

      {menu && (
        <div
          aria-label='Document actions'
          onKeyDown={handleMenuKey}
          ref={menuRef}
          role='menu'
          style={{ left: menu.x, position: 'fixed', top: menu.y, zIndex: 10 }}
          tabIndex={-1}
        >
          <button
            disabled={!menu.changeTarget || decisionPending}
            onClick={() => void decideChange('accept')}
            role='menuitem'
            type='button'
          >
            Accept change
          </button>
          <button
            disabled={!menu.changeTarget || decisionPending}
            onClick={() => void decideChange('reject')}
            role='menuitem'
            type='button'
          >
            Reject change
          </button>
          <button disabled={!selectedText} onClick={() => void copySelection()} role='menuitem' type='button'>
            Copy selected text
          </button>
        </div>
      )}

      <p aria-live='polite' role='status'>
        {status}
      </p>
    </>
  );
}

```


`ui: { contextMenu: false }` hides SuperDoc's menu. It does not disable `superdoc.ui.contextMenu`.

Pass the browser event's `clientX` and `clientY` to `ui.contextMenu.contextAt()`. Its `point` positions the menu,
`entities` identifies document objects under the pointer, and `selection` carries the current selection. The example
enables tracked-change decisions only over a tracked change and Copy only when selected text is ready.

`contextAt()` returns the current snapshot immediately. Check `selection.status === 'ready'` before using selected text;
`pending` and `stale` can carry text from an earlier selection.

## Own the complete interaction [#own-the-complete-interaction]

The browser's `contextmenu` event covers pointer input. The Context Menu key and `Shift+F10` use
`ui.selection.getAnchorRect()` to position the same surface from the keyboard.

Once the menu opens, your application owns focus, arrow keys, Escape, outside-click dismissal, and repositioning or
dismissal after scroll and resize. It also owns action feedback. Await the action result before reporting success.

`contextAt()` resolves supported entities and selection state, not an arbitrary insertion position under plain text.
Use [Selection and position](/editor/custom-ui/selection-and-viewport) when another custom surface needs document targets
or painted geometry.

## Verify the menu [#verify-the-menu]

Right-click a tracked change and accept or reject it. Select text, then press `Shift+F10` and copy it. Right-click
ordinary text without a selection and confirm that unsupported actions stay disabled.

Build a [tracked-change panel](/editor/custom-ui/tracked-changes) when reviewers also need a complete queue. Otherwise,
return to the [Custom UI overview](/editor/custom-ui/overview).


---

# Build your first custom control

> Move Bold into your application while SuperDoc renders the document and remaining toolbar.



Start from the [Editor quickstart](/editor/quickstart). Remove Bold from SuperDoc's toolbar, then render a Bold button in
your application. This is the smallest step from configuring the built-in UI to owning part of it.

## Try the ownership handoff [#try-the-ownership-handoff]

Select text in the document. Use **Bold** under **Your application**, then use **Italic** under **SuperDoc UI**. Both
controls should follow the same selection.

> **Live example: move one control into your application**
>
> Select text in the real DOCX. The application-owned Bold button and SuperDoc's remaining toolbar act on the same Editor selection. Bold is excluded from the built-in toolbar, but its command remains available through `superdoc.ui`.


Only the visible Bold control changed owner. SuperDoc still renders the DOCX canvas and the remaining toolbar.

## Build the same handoff [#build-the-same-handoff]

Choose Vanilla or React below. Your choice stays active across the examples.

If you chose React in the quickstart, add `superdoc` as a direct dependency. The custom UI hooks come from its
`superdoc/ui/react` entry point:

```bash
pnpm add superdoc
```

## 1. Move Bold into your application [#1-move-bold-into-your-application]

Vanilla needs a button next to its existing Editor container. React renders the button inside the component in the next
step and keeps the quickstart's `index.html`. Vanilla also needs a mount for the remaining built-in toolbar. If you use
Vanilla, replace the contents of `<body>` in `index.html` with:

```html
<div id="toolbar"></div>
<div aria-label="Document controls" role="toolbar">
  <button id="bold" type="button" disabled aria-pressed="false">Bold</button>
</div>
<output id="status" aria-live="polite" role="status">Select text to format it.</output>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

## 2. Connect Bold to the Editor [#2-connect-bold-to-the-editor]

Replace the quickstart Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import 'superdoc/style.css';

const boldButton = document.querySelector<HTMLButtonElement>('#bold');
const status = document.querySelector<HTMLOutputElement>('#status');
if (!boldButton || !status) throw new Error('The custom controls are missing.');

let stopObserving: (() => void) | null = null;
let removeHandlers: (() => void) | null = null;

const editorUi = {
  toolbar: {
    container: '#toolbar',
    excludeItems: ['bold'],
  },
} satisfies UIConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    stopObserving?.();
    removeHandlers?.();
    const bold = readySuperDoc.ui.commands.get('bold');

    let pending = false;
    const render = (state: ReturnType<typeof bold.getState>) => {
      boldButton.disabled = pending || !state.enabled;
      boldButton.setAttribute('aria-pressed', String(state.active));
      boldButton.title = state.reason ?? 'Toggle bold';
    };

    const onBoldClick = async () => {
      if (pending) return;
      const message = bold.getState().active ? 'Bold removed.' : 'Bold applied.';
      pending = true;
      render(bold.getState());
      try {
        const result = await bold.executeAsync();
        const applied = result === true || (typeof result === 'object' && result.success);
        status.textContent = applied ? message : 'Bold was not changed.';
      } finally {
        pending = false;
        render(bold.getState());
      }
    };

    const preserveSelection = (event: MouseEvent) => event.preventDefault();
    render(bold.getState());
    stopObserving = bold.observe(render);
    boldButton.addEventListener('mousedown', preserveSelection);
    boldButton.addEventListener('click', onBoldClick);
    removeHandlers = () => {
      boldButton.removeEventListener('mousedown', preserveSelection);
      boldButton.removeEventListener('click', onBoldClick);
    };
  },
  onContentError: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopObserving?.();
  removeHandlers?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocCommand } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = {
  toolbar: { excludeItems: ['bold'] },
} satisfies UIConfig;

export default function App() {
  return (
    <SuperDocUIProvider>
      <BoldControl />
      <Editor />
    </SuperDocUIProvider>
  );
}

function BoldControl() {
  const bold = useSuperDocCommand('bold');
  const [pending, setPending] = useState(false);
  const [status, setStatus] = useState({ id: 0, message: 'Select text to format it.' });

  async function toggleBold() {
    if (pending) return;
    const message = bold.active ? 'Bold removed.' : 'Bold applied.';
    setPending(true);
    try {
      const result = await bold.executeAsync();
      const applied = result === true || (typeof result === 'object' && result.success);
      setStatus((current) => ({ id: current.id + 1, message: applied ? message : 'Bold was not changed.' }));
    } finally {
      setPending(false);
    }
  }

  return (
    <>
      <div aria-label='Document controls' role='toolbar'>
        <button
          aria-pressed={bold.active}
          disabled={!bold.enabled || pending}
          onClick={() => void toggleBold()}
          onMouseDown={(event) => event.preventDefault()}
          title={bold.reason ?? 'Toggle bold'}
          type='button'
        >
          Bold
        </button>
      </div>
      <output aria-live='polite' role='status'>
        <span key={status.id}>{status.message}</span>
      </output>
    </>
  );
}

function Editor() {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/sample.docx'
      onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
      ui={editorUi}
    />
  );
}

```


Both versions make the same ownership change:

* `toolbar.excludeItems` removes the built-in Bold button. The Bold command remains available.
* The application-owned button reads that command's state and runs it through `superdoc.ui`.
* The Editor owns the controller. Your application releases only the subscription and event handlers it created.

The `mousedown` handler keeps the document selection active when the custom button receives a mouse click. Keyboard
activation continues to use the button's normal focus and click behavior. [Selection and position](/editor/custom-ui/selection-and-viewport)
explains that pattern for menus, popovers, and other application UI.

## 3. Run the control [#3-run-the-control]

Run the project:

```bash
pnpm dev
```

Select text in the DOCX. **Bold** becomes enabled and reflects whether the selection is bold. Choose it and confirm that
the status reports whether bold was applied or removed. The remaining built-in toolbar controls should still render.

The [runnable custom UI example](https://go.superdoc.dev/examples/custom-ui) also verifies the exported DOCX.

Continue with [Commands and state](/editor/custom-ui/commands-and-state) to apply the same state and execution pattern to
other controls.


---

# Register an application command

> Define one application action, then reuse its behavior and state from more than one control.



A normal function is enough when one control owns an action. Register a custom command when two or more controls need
the same execution path and enabled state.

## Try one command from two controls [#try-one-command-from-two-controls]

1. Place the caret at the end of a sentence.
2. Choose **Insert clause**. The status identifies the button and confirms the insertion.
3. Move the caret, then press **Control-Shift-Y**. The status identifies the shortcut and confirms the same action.

> **Live example: run one application command from two controls**
>
> Place the caret in the real DOCX. Insert clause and Control-Shift-Y execute the same registered `application.insertClause` command. The button observes the command handle for its enabled state, and the result identifies which trigger ran and whether the clause was inserted.


Both controls execute `application.insertClause`. The button observes the registered command's state; neither control
owns a separate insertion function.

## Choose a function or a command [#choose-a-function-or-a-command]

| Your action                                      | Use                                     |
| ------------------------------------------------ | --------------------------------------- |
| Runs from one application control                | A normal function                       |
| Runs from multiple controls with shared state    | A registered application command        |
| Already exists in SuperDoc, such as Bold or Undo | Its existing handle under `superdoc.ui` |

Do not wrap a built-in SuperDoc command in a custom command. Reuse its existing handle so every control reads the same
state and result.

## Build the same command [#build-the-same-command]

This standalone Vanilla recipe uses the project from [Build your first custom control](/editor/custom-ui/controller-setup).
Keep its `public/sample.docx`; the example retains the built-in toolbar.

Replace the contents of `<body>` in `index.html` to add the application action beside the Editor:

```html
<div id="command-demo">
  <div id="toolbar"></div>
  <div aria-label="Application actions" role="toolbar">
    <button aria-keyshortcuts="Control+Shift+Y" id="insert-clause" type="button" disabled>
      Insert clause
    </button>
    <kbd>Control-Shift-Y</kbd>
  </div>
  <output id="command-status" aria-live="polite">Place the caret in the document.</output>
  <div id="editor" style="height: 70vh"></div>
</div>

<script type="module" src="/src/main.ts"></script>

```

Replace `src/main.ts` to register the command and connect both triggers to its typed handle:

```ts
import { SuperDoc } from 'superdoc';
import type { CommandExecutionResult, CustomCommandHandle } from 'superdoc/ui';
import 'superdoc/style.css';

type InsertClausePayload = Readonly<{
  text: string;
  trigger: 'button' | 'shortcut';
}>;

const commandDemo = document.querySelector<HTMLDivElement>('#command-demo');
const insertClause = document.querySelector<HTMLButtonElement>('#insert-clause');
const status = document.querySelector<HTMLOutputElement>('#command-status');

if (!commandDemo || !insertClause || !status) throw new Error('The custom command controls are incomplete.');

const clauseText = ' This agreement is governed by the laws of California.';
let command: CustomCommandHandle<InsertClausePayload> | null = null;
let unregisterCommand: (() => void) | null = null;
let stopCommandState: (() => void) | null = null;
let removeHandlers: (() => void) | null = null;
let pending = false;

const report = (result: CommandExecutionResult, trigger: InsertClausePayload['trigger']) => {
  if (result === false) {
    status.textContent = 'The command could not run.';
  } else if (typeof result === 'object' && !result.success) {
    status.textContent = result.failure?.message ?? 'The clause was not inserted.';
  } else {
    status.textContent = `${trigger === 'button' ? 'Button' : 'Shortcut'} inserted the clause.`;
  }
};

const render = () => {
  const state = command?.getState();
  insertClause.disabled = pending || !state?.enabled;
  insertClause.title = state?.reason ?? 'Insert standard clause';
};

const run = async (trigger: InsertClausePayload['trigger']) => {
  if (!command || pending) return;
  if (!command.getState().enabled) {
    status.textContent = 'Place the caret in the document first.';
    return;
  }

  pending = true;
  render();
  try {
    report(await command.executeAsync({ text: clauseText, trigger }), trigger);
  } catch (error) {
    status.textContent = error instanceof Error ? error.message : 'The clause was not inserted.';
  } finally {
    pending = false;
    render();
  }
};

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: { toolbar: { container: '#toolbar' } },
  onReady: ({ superdoc: readySuperDoc }) => {
    stopCommandState?.();
    removeHandlers?.();
    unregisterCommand?.();
    pending = false;

    const ui = readySuperDoc.ui;
    const registration = ui.commands.register<InsertClausePayload>({
      id: 'application.insertClause',
      shortcut: 'Ctrl-Shift-Y',
      getState: ({ state, selection, documentMode }) => {
        const settled = state.ready && selection.status === 'ready';
        // `status: 'ready'` only means the selection read settled. Before the reader places a
        // caret both targets are null, and `insertText()` then has no insertion point.
        // Insert at a non-collapsed range degrades to a replace, which would delete the
        // reader's selection, so require a collapsed caret rather than any target.
        const hasCaret = Boolean(selection.selectionTarget ?? selection.target) && selection.empty;
        return {
          enabled: settled && hasCaret && documentMode !== 'viewing',
          active: false,
          supported: true,
          reason: !settled
            ? 'not-ready'
            : !hasCaret
              ? 'selection-required'
              : documentMode === 'viewing'
                ? 'document-readonly'
                : undefined,
        };
      },
      execute: ({ payload, insertText }) => (payload?.text ? insertText(payload.text) : false),
    });
    command = registration.handle;

    const preserveSelection = (event: MouseEvent) => event.preventDefault();
    const runButton = () => void run('button');
    const runShortcut = (event: KeyboardEvent) => {
      if (!event.composedPath().includes(commandDemo)) return;
      if (event.repeat) return;
      // Match the advertised character. Alt is excluded, so `event.key` is not an AltGr
      // composition here, and `event.code` would match a US physical position instead.
      // An IME can emit a matching keydown mid-composition; ignore those.
      if (event.isComposing) return;
      if (!event.ctrlKey || !event.shiftKey || event.altKey || event.metaKey || event.key.toLowerCase() !== 'y') return;
      event.preventDefault();
      void run('shortcut');
    };

    render();
    stopCommandState = command.observe(render);
    unregisterCommand = registration.unregister;
    insertClause.addEventListener('mousedown', preserveSelection);
    insertClause.addEventListener('click', runButton);
    window.addEventListener('keydown', runShortcut, true);

    removeHandlers = () => {
      insertClause.removeEventListener('mousedown', preserveSelection);
      insertClause.removeEventListener('click', runButton);
      window.removeEventListener('keydown', runShortcut, true);
    };
  },
});

window.addEventListener('beforeunload', () => {
  stopCommandState?.();
  removeHandlers?.();
  unregisterCommand?.();
  superdoc.destroy();
});

```

The registration defines the shared contract:

* `getState()` derives whether the action is available from the live Editor state.
* `execute()` owns the insertion and receives the typed payload.
* `shortcut` records the intended key binding. Your application still owns the keyboard listener and conflict policy.
* `observe()` keeps the button synchronized as the Editor state changes.
* `executeAsync()` returns the settled result for either trigger.

`getState()` describes availability; it does not block custom-command execution. Check `handle.getState().enabled` in
every trigger before calling `executeAsync()`. Scope global keyboard listeners to the Editor experience so they do not
take over the rest of your application.

Custom commands do not create an authorization boundary. Checking `enabled` in each trigger keeps the interface honest,
but a caller can invoke the handle directly. Your backend must still enforce document access, identity, persistence, and
collaboration permissions.

## Verify the shared action [#verify-the-shared-action]

Run the project and place the caret in `/sample.docx`. Insert the clause once with the button and once with the shortcut.
Confirm that both paths insert the same text and that the output identifies the trigger that ran. Move focus outside the
Editor experience and confirm that the shortcut no longer runs.

Keep custom commands focused on one user intent. Use `context.insertText()` for text insertion, call another command
through `context.executeAsync()`, or use `context.doc` for Document API operations. Do not reach into Editor state, view
objects, or DOM offsets.

Custom commands are optional. Return to the [Custom UI overview](/editor/custom-ui/overview) to choose another surface
for your application.


---

# Build a custom toolbar

> Scale one working custom control into an application-owned toolbar that follows the current selection.



Configure the [built-in toolbar](/editor/built-in-ui/configure-the-toolbar) when you only need to choose which controls it
shows. Continue here when your application needs to own the toolbar's markup, layout, accessibility, or feedback.

The Bold button from [Commands and state](/editor/custom-ui/commands-and-state) already observes state, renders it, runs
a command, and handles the result. Keep that loop. Add font-family and font-size pickers to turn it into a small toolbar.

## Try the loop at toolbar scale [#try-the-loop-at-toolbar-scale]

Select the first sentence below. Apply Bold, then choose **Courier New** and **18**. Reselect that sentence to see all three
controls recover its formatting. Extend that formatted selection into the next plain sentence and the pickers show
**Mixed**.

> **Live example: scale one control into a custom toolbar**
>
> Select text in the real DOCX, then use the application-owned Bold, font-family, and font-size controls. The toolbar reads `active`, `value`, and `enabled` from the corresponding command handles. Formatting one sentence and extending the selection into plain text makes the font and size pickers show `Mixed`. Each action reports the result from `executeAsync()`.


The toolbar demonstrates three reusable control shapes:

* A toggle renders `active` through `aria-pressed`.
* A picker renders `value`, or **Mixed** when the selection has no single value.
* Every control renders `enabled` through its disabled state and reports what `executeAsync()` returns.

SuperDoc owns the document behavior and publishes command state. Your application owns the toolbar element, control
labels, focus behavior, and action feedback.

## Build the same toolbar [#build-the-same-toolbar]

Continue with the `/sample.docx` project from [Build your first custom control](/editor/custom-ui/controller-setup). This
time, set `toolbar: false` to remove the remaining built-in toolbar.

## Add the toolbar surface [#add-the-toolbar-surface]

For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar and Editor mounts below.
React renders the controls in `App.tsx` and keeps the quickstart HTML.

```html
<div aria-label="Formatting controls" role="toolbar">
  <button id="bold" type="button" aria-pressed="false" disabled>Bold</button>
  <label>
    Font
    <select id="font-family" disabled>
      <option value="">Mixed</option>
    </select>
  </label>
  <label>
    Size
    <select id="font-size" disabled>
      <option value="">Mixed</option>
    </select>
  </label>
</div>

<p id="formatting-status" role="status">Opening document...</p>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

## Bind the commands and options [#bind-the-commands-and-options]

Replace the first-control Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { CommandExecutionResult } from 'superdoc/ui';
import 'superdoc/style.css';

function getElement<T extends Element>(selector: string): T {
  const element = document.querySelector<T>(selector);
  if (!element) throw new Error(`Missing custom toolbar element: ${selector}`);
  return element;
}

const boldButton = getElement<HTMLButtonElement>('#bold');
const fontFamilySelect = getElement<HTMLSelectElement>('#font-family');
const fontSizeSelect = getElement<HTMLSelectElement>('#font-size');
const status = getElement<HTMLParagraphElement>('#formatting-status');

const editorUi = { toolbar: false } satisfies UIConfig;
let stopBindings: (() => void) | null = null;
let pending = false;

function syncOptions(
  select: HTMLSelectElement,
  options: readonly { value: string; label: string }[],
  selectedValue: unknown,
) {
  const selected = typeof selectedValue === 'string' || typeof selectedValue === 'number' ? String(selectedValue) : '';
  // `Mixed` describes a selection with no single value. It is not a command
  // payload, so it stays visible but cannot be chosen.
  const mixed = document.createElement('option');
  mixed.value = '';
  mixed.textContent = 'Mixed';
  mixed.disabled = true;
  // A uniform value outside the preset list is still one value. Keep it
  // selectable so the picker shows what the document has.
  const choices =
    selected && !options.some(({ value }) => value === selected)
      ? [{ value: selected, label: selected }, ...options]
      : options;
  select.replaceChildren(
    mixed,
    ...choices.map(({ value, label }) => {
      const option = document.createElement('option');
      option.value = value;
      option.textContent = label;
      return option;
    }),
  );
  select.value = selected;
}

function report(result: CommandExecutionResult, message: string) {
  if (result === false) {
    status.textContent = 'The formatting action is unavailable.';
  } else if (typeof result === 'object' && !result.success) {
    status.textContent = result.failure.message;
  } else {
    status.textContent = message;
  }
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    stopBindings?.();

    const { ui } = readySuperDoc;
    const bold = ui.commands.get('bold');
    const fontFamily = ui.commands.get('font-family');
    const fontSize = ui.commands.get('font-size');

    const render = () => {
      const fonts = ui.fonts.getSnapshot();
      const boldState = bold.getState();
      const familyState = fontFamily.getState();
      const sizeState = fontSize.getState();

      boldButton.disabled = pending || !boldState.enabled;
      boldButton.setAttribute('aria-pressed', String(boldState.active));
      syncOptions(fontFamilySelect, fonts.options, familyState.value);
      syncOptions(fontSizeSelect, fonts.sizeOptions, sizeState.value);
      fontFamilySelect.disabled = pending || !familyState.enabled;
      fontSizeSelect.disabled = pending || !sizeState.enabled;
    };

    // One action at a time. A second click before the first settles would
    // dispatch a second toggle, and overlapping picker changes could report
    // their results out of order.
    const run = async (action: () => Promise<CommandExecutionResult>, message: string) => {
      if (pending) return;
      pending = true;
      render();
      try {
        report(await action(), message);
      } finally {
        pending = false;
        render();
      }
    };

    const preserveSelection = (event: MouseEvent) => event.preventDefault();
    const toggleBold = () => run(() => bold.executeAsync(), bold.getState().active ? 'Bold removed.' : 'Bold applied.');
    // Read the chosen value before `run()` rerenders the select, which resets
    // it to the command's current value.
    const setFontFamily = () => {
      const value = fontFamilySelect.value;
      return run(() => fontFamily.executeAsync(value), 'Font updated.');
    };
    const setFontSize = () => {
      const value = fontSizeSelect.value;
      return run(() => fontSize.executeAsync(value), 'Font size updated.');
    };

    const stopObservers = [
      ui.fonts.observe(render),
      bold.observe(render),
      fontFamily.observe(render),
      fontSize.observe(render),
    ];

    boldButton.addEventListener('mousedown', preserveSelection);
    boldButton.addEventListener('click', toggleBold);
    fontFamilySelect.addEventListener('change', setFontFamily);
    fontSizeSelect.addEventListener('change', setFontSize);

    stopBindings = () => {
      for (const stop of stopObservers) stop();
      boldButton.removeEventListener('mousedown', preserveSelection);
      boldButton.removeEventListener('click', toggleBold);
      fontFamilySelect.removeEventListener('change', setFontFamily);
      fontSizeSelect.removeEventListener('change', setFontSize);
    };

    render();
    status.textContent = 'Select text to format it.';
  },
  onContentError: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopBindings?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { CommandExecutionResult } from 'superdoc/ui';
import {
  SuperDocUIProvider,
  useSetSuperDoc,
  useSuperDocCommand,
  useSuperDocFontOptions,
  useSuperDocFontSizeOptions,
} from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = { toolbar: false } satisfies UIConfig;

type PickerOption = { value: string; label: string };

// A uniform value outside the preset list is still one value. Keep it
// selectable so the picker shows what the document has.
function getPickerChoices(options: readonly PickerOption[], commandValue: unknown): PickerOption[] {
  const selected = typeof commandValue === 'string' || typeof commandValue === 'number' ? String(commandValue) : '';
  if (!selected || options.some(({ value }) => value === selected)) return [...options];
  return [{ value: selected, label: selected }, ...options];
}

function getSelectedOptionValue(commandValue: unknown): string {
  return typeof commandValue === 'string' || typeof commandValue === 'number' ? String(commandValue) : '';
}

export default function App() {
  return (
    <SuperDocUIProvider>
      <FormattingToolbar />
      <Editor />
    </SuperDocUIProvider>
  );
}

function FormattingToolbar() {
  const bold = useSuperDocCommand('bold');
  const fontFamily = useSuperDocCommand('font-family');
  const fontSize = useSuperDocCommand('font-size');
  const fontOptions = useSuperDocFontOptions();
  const sizeOptions = useSuperDocFontSizeOptions();
  const [pending, setPending] = useState(false);
  const [status, setStatus] = useState('Select text to format it.');

  function report(result: CommandExecutionResult, message: string) {
    if (result === false) {
      setStatus('The formatting action is unavailable.');
    } else if (typeof result === 'object' && !result.success) {
      setStatus(result.failure.message);
    } else {
      setStatus(message);
    }
  }

  // One action at a time. A second click before the first settles would
  // dispatch a second toggle, and overlapping picker changes could report
  // their results out of order.
  async function run(action: () => Promise<CommandExecutionResult>, message: string) {
    if (pending) return;
    setPending(true);
    try {
      report(await action(), message);
    } finally {
      setPending(false);
    }
  }

  const familyValue = getSelectedOptionValue(fontFamily.value);
  const sizeValue = getSelectedOptionValue(fontSize.value);
  const familyChoices = getPickerChoices(fontOptions, fontFamily.value);
  const sizeChoices = getPickerChoices(sizeOptions, fontSize.value);

  return (
    <>
      <div aria-label='Formatting controls' role='toolbar'>
        <button
          aria-pressed={bold.active}
          disabled={pending || !bold.enabled}
          onClick={() => void run(() => bold.executeAsync(), bold.active ? 'Bold removed.' : 'Bold applied.')}
          onMouseDown={(event) => event.preventDefault()}
          type='button'
        >
          Bold
        </button>
        <label>
          Font
          <select
            disabled={pending || !fontFamily.enabled}
            onChange={(event) => void run(() => fontFamily.executeAsync(event.target.value), 'Font updated.')}
            value={familyValue}
          >
            <option disabled value=''>
              Mixed
            </option>
            {familyChoices.map((option) => (
              <option key={option.value} value={option.value}>
                {option.label}
              </option>
            ))}
          </select>
        </label>
        <label>
          Size
          <select
            disabled={pending || !fontSize.enabled}
            onChange={(event) => void run(() => fontSize.executeAsync(event.target.value), 'Font size updated.')}
            value={sizeValue}
          >
            <option disabled value=''>
              Mixed
            </option>
            {sizeChoices.map((option) => (
              <option key={option.value} value={option.value}>
                {option.label}
              </option>
            ))}
          </select>
        </label>
      </div>
      <output aria-live='polite' role='status'>
        {status}
      </output>
    </>
  );
}

function Editor() {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/sample.docx'
      onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
      ui={editorUi}
    />
  );
}

```


Both versions scale the same control loop:

* Get one command handle for Bold, font family, and font size.
* Read `ui.fonts` for the values each picker can send.
* Render each command's current `enabled`, `active`, or `value` state.
* Run the command and report whether it finished.

The React hook exposes state and execution on the same object. Vanilla uses the equivalent command handle returned by
`ui.commands.get(id)`.

## Represent picker values [#represent-picker-values]

Pass each option's `value` to its command. A font option's `previewFamily` is only a CSS value for previewing that choice
in your interface.

A mixed selection has no single command `value`. Show a non-selectable **Mixed** option until the selection resolves to
one font or size. Continue to let the command state drive the control; do not inspect the rendered document DOM.

## Verify the toolbar [#verify-the-toolbar]

Run the project. Select text in `/sample.docx` and change all three controls. Move the selection away, then select the
formatted text again. Bold, font, and size should recover the values you applied. Extend the selection into neighboring
text that kept its original formatting. Both pickers should show **Mixed**.

For an alternative recipe, [build application document controls](/editor/custom-ui/zoom-and-document-state) for zoom
and download. It replaces this example and keeps the built-in formatting toolbar. Use
[Custom commands](/editor/custom-ui/custom-commands) later for application actions that SuperDoc does not provide.


---

# Build a custom UI

> Keep SuperDoc's DOCX canvas while your application renders task-specific controls.



Build a custom UI when your product needs focused controls or workflows around a DOCX document. SuperDoc continues to
render the document and handle editing. Your application renders the toolbar, panels, and other controls it needs.

> **Diagram: the custom UI ownership boundary**
>
> SuperDoc renders the document, layout, selection, and editing behavior. The application renders the controls around it — a toolbar above, panels beside. Reactive state (selection, command state, comments) flows out of the editor to those controls, and commands and document operations flow back in.


You can replace one surface or the complete interface. For example, keep the built-in toolbar while rendering your own
comments panel, or set `ui: false` and render every control yourself.

## Choose the right surface [#choose-the-right-surface]

| You need to                                | Use           |
| ------------------------------------------ | ------------- |
| Choose which built-in surfaces render      | `Config.ui`   |
| Observe UI state and run Editor actions    | `superdoc.ui` |
| Read or mutate an explicit document target | `editor.doc`  |
| Decide which interactions are allowed      | `interaction` |

These surfaces work together. Setting `ui: { comments: false }` removes SuperDoc's comments interface, but your custom
panel can still use `superdoc.ui.comments`. The `interaction` configuration decides whether that panel may read, write,
or resolve comments.

`superdoc.ui` is the controller. Import its types from `superdoc/ui`. React applications use the provider and hooks from
`superdoc/ui/react`, and Vue applications use the composables from `superdoc/ui/vue`. Each binding exposes the same
controller.

## Try one custom control [#try-one-custom-control]

Select text in the document, then choose **Bold**. The application-owned button observes the command's live state and
executes the action through the same controller as SuperDoc's built-in toolbar.

> **Live example: one custom control on a real document**
>
> A Bold button rendered by the application, running against a real Editor. It reads `enabled` and `active` from the `bold` command handle, sets `disabled` and `aria-pressed` from those values rather than inspecting the selection, and reports the outcome from what `executeAsync()` resolves with. `CommandExecutionResult` is `boolean | receipt`, so both shapes are handled.


The control follows one reusable pattern: observe state, render it, execute the action, and inspect the result. The
[custom UI example](https://go.superdoc.dev/examples/custom-ui) contains the complete runnable project.

## Start with one control [#start-with-one-control]

If this is your first custom UI, read these guides in this order:

1. [Build your first custom control](/editor/custom-ui/controller-setup) and move Bold into your application.
2. [Keep commands and controls in sync](/editor/custom-ui/commands-and-state) as the selection changes.

Then choose the controls your application needs:

* [Build a custom toolbar](/editor/custom-ui/formatting-controls) to own formatting controls and their layout.
* [Add document controls](/editor/custom-ui/zoom-and-document-state) to own zoom and download while keeping the built-in toolbar.

These are alternative recipes. Each replaces the first control's Editor code; neither requires the other.

## Choose a workflow [#choose-a-workflow]

After the first control, choose only the workflows your product needs. These guides are independent unless a page names
a prerequisite.

| Your application needs to                                    | Guide                                                              |
| ------------------------------------------------------------ | ------------------------------------------------------------------ |
| Own the comment thread list and actions                      | [Comments](/editor/custom-ui/comments)                             |
| Own the queue for accepting or rejecting revisions           | [Track changes](/editor/custom-ui/tracked-changes)                 |
| Navigate and edit structured document fields                 | [Content controls](/editor/custom-ui/content-controls)             |
| Own a visual find and replace session                        | [Search](/editor/custom-ui/search)                                 |
| Replace the menu shown for a pointer or keyboard interaction | [Context menu](/editor/custom-ui/context-menus)                    |
| Show table actions that follow the active cell               | [Tables](/editor/custom-ui/tables)                                 |
| Position an AI prompt beside selected text                   | [Selection and position](/editor/custom-ui/selection-and-viewport) |
| Turn an application finding into a tracked suggestion        | [Review findings](/editor/custom-ui/review-highlights)             |
| Share one application action across multiple controls        | [Custom commands](/editor/custom-ui/custom-commands)               |

Use [Dialogs and surfaces](/editor/dialogs-and-surfaces) when your application only needs content in a SuperDoc-managed
layer. Use [Theming](/editor/theming) to apply product colors to SuperDoc UI.


---

# Turn AI findings into tracked suggestions

> Save an application-owned AI finding with its source text, then propose a document edit as a tracked change.



An AI response can flag a risk without changing the document. Save it as a finding so your application can return to the
same text. If the finding leads to a rewrite, add that rewrite as a tracked suggestion.

## Try the review flow [#try-the-review-flow]

1. Select `the fees Customer paid in the twelve months before the claim`, then choose **Ask AI**.
2. Ask `What should I review?`, then choose **Save as finding**.
3. Choose **Show in document** to return to the risk.
4. Choose **Suggest edit**. The application paint disappears, and SuperDoc shows the rewrite as a tracked change. The
   finding stays in the panel as the reason for the edit.

> **Live example: turn an AI finding into a tracked suggestion**
>
> The embedded example runs the steps above in a two-page DOCX. The model response is simulated locally; metadata and the tracked replacement use SuperDoc.


The response is simulated locally. Saving the finding and creating the tracked change use the real Document API. To keep
either after a reload, export the changed DOCX and save it through your application's storage flow.

## Give each layer one job [#give-each-layer-one-job]

| Responsibility                      | Public surface                                | Included in export |
| ----------------------------------- | --------------------------------------------- | ------------------ |
| Finding, text anchor, and JSON data | `doc.metadata`                                | Yes                |
| Risk paint over the resolved text   | `ctx.visuals.highlight()`                     | No                 |
| Proposed rewrite for human review   | `doc.replace(..., { changeMode: 'tracked' })` | Yes                |

Metadata does not render by itself. List and resolve findings when the document opens, then paint their current ranges.
Use tracked changes for edits because SuperDoc already renders and exports them as reviewable revisions.

The [Track changes](/editor/custom-ui/tracked-changes) page owns navigation and accept/reject controls. Use
[comments](/editor/custom-ui/comments) instead when people need a Word comment thread.

## Run the complete example [#run-the-complete-example]

Use the Vanilla project from [Custom UI setup](/editor/custom-ui/controller-setup). Save this sample as
`public/contract.docx`:

[Download the selection sample](/fixtures/custom-selection-workflow.docx): Two pages of selectable contract text · DOCX


Copy the two files under [Controller implementation](#controller-implementation) into `src/`.
Replace the contents of `<body>` in `index.html` with:

```html
<div id="toolbar"></div>
<div id="editor" style="height: 65vh; overflow: auto"></div>
<aside aria-label="AI review">
  <button id="ask" type="button" disabled>Ask AI about selection</button>
  <form id="prompt" hidden>
    <blockquote id="quote"></blockquote>
    <label>Question <input id="question" value="What should I review?" required /></label>
    <p>Simulated response: consider whether this wording needs a clearer limit.</p>
    <label>Suggested wording <textarea id="suggested" required></textarea></label>
    <button type="submit">Save as finding</button>
    <button id="cancel" type="button">Cancel</button>
  </form>
  <ul id="findings"></ul>
  <button id="download" type="button" disabled>Download DOCX</button>
  <p id="status" role="status">Opening document…</p>
</aside>
<script type="module" src="/src/main.ts"></script>

```

Replace `src/main.ts` with:

```ts
import { SuperDoc } from 'superdoc';
import { createReviewFindings, isSupersededRefresh } from './review-highlights';
import type { BoundReviewSelection, ReviewFinding } from './review-highlights';
import 'superdoc/style.css';

function element<T extends HTMLElement>(id: string): T {
  const node = document.querySelector<T>(`#${id}`);
  if (!node) throw new Error(`Missing review element: ${id}`);
  return node;
}

const ask = element<HTMLButtonElement>('ask');
const prompt = element<HTMLFormElement>('prompt');
const quote = element<HTMLQuoteElement>('quote');
const question = element<HTMLInputElement>('question');
const suggested = element<HTMLTextAreaElement>('suggested');
const cancel = element<HTMLButtonElement>('cancel');
const list = element<HTMLUListElement>('findings');
const download = element<HTMLButtonElement>('download');
const status = element<HTMLParagraphElement>('status');
let selection: BoundReviewSelection | null = null;
let rows: readonly ReviewFinding[] = [];
let pending = false;
let ready = false;
let stopSelection: (() => void) | undefined;

const review = createReviewFindings({
  onFindingsChanged: renderFindings,
  onFindingsError: (error) => {
    if (isSupersededRefresh(error)) return;
    renderFindings([]);
    showError(error);
  },
});

function showError(error: unknown) {
  if (isSupersededRefresh(error)) return;
  status.textContent = error instanceof Error ? error.message : String(error);
}

function renderControls() {
  ask.disabled = !ready || pending || !prompt.hidden || superdoc.ui.selection.getSnapshot().empty;
  download.disabled = !ready || pending;
  for (const control of prompt.querySelectorAll<HTMLInputElement | HTMLTextAreaElement | HTMLButtonElement>(
    'input, textarea, button',
  ))
    control.disabled = pending;
}

function renderFindings(findings: readonly ReviewFinding[]) {
  rows = findings;
  list.replaceChildren();
  for (const finding of findings) {
    const row = document.createElement('li');
    const summary = document.createElement('p');
    summary.textContent = `Simulated response: ${finding.payload.summary}`;
    const show = document.createElement('button');
    show.textContent = 'Show in document';
    show.disabled = pending || finding.anchorStatus !== 'resolved';
    show.onclick = () =>
      void run(async () => {
        const result = await superdoc.ui.metadata.scrollIntoView({ id: finding.id, block: 'center' });
        if (!result.success) throw new Error('The finding could not be shown.');
        status.textContent = 'Showing the finding.';
      });
    const suggest = document.createElement('button');
    suggest.textContent =
      finding.payload.suggestionStatus === 'pending'
        ? 'Check document'
        : finding.payload.suggestionStatus === 'created'
          ? 'Suggestion created'
          : 'Suggest edit';
    suggest.disabled = pending || finding.anchorStatus !== 'resolved' || Boolean(finding.payload.suggestionStatus);
    suggest.onclick = () =>
      void run(async () => {
        const result = await review.suggest(superdoc.activeEditor?.doc, finding);
        if (!result.success) throw new Error(result.message);
        status.textContent = 'Tracked suggestion added. Review it with the built-in toolbar.';
        await refresh();
      });
    row.append(summary, show, suggest);
    list.append(row);
  }
}

async function refresh() {
  renderFindings(await review.refresh(superdoc.activeEditor?.doc));
}

async function run(action: () => Promise<void>) {
  if (pending || !ready) return;
  pending = true;
  renderControls();
  renderFindings(rows);
  try {
    await action();
  } catch (error) {
    showError(error);
  } finally {
    pending = false;
    renderControls();
    renderFindings(rows);
  }
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  extensions: [review.extension],
  ui: { toolbar: { container: '#toolbar' } },
  user: { name: 'Review assistant', email: 'review-assistant@example.com' },
  onReady: () => {
    ready = true;
    stopSelection?.();
    stopSelection = superdoc.ui.selection.observe(renderControls);
    void run(async () => {
      await refresh();
      status.textContent = 'Select one short paragraph, then ask AI.';
    });
  },
  onContentError: ({ error }) => showError(error),
  onException: ({ error }) => showError(error),
});

function captureSelection() {
  const capture = superdoc.ui.selection.capture();
  selection = capture ? review.bindSelection(capture) : null;
}
ask.addEventListener('mousedown', captureSelection);
ask.addEventListener('click', (event) => {
  if (event.detail === 0) captureSelection();
  if (!selection) {
    status.textContent = 'Select plain body text in one paragraph.';
    return;
  }
  quote.textContent = selection.capture.quotedText;
  suggested.value = `${selection.capture.quotedText} (subject to the agreed limit)`;
  prompt.hidden = false;
  renderControls();
  question.focus();
});
cancel.onclick = () => {
  selection = null;
  prompt.hidden = true;
  renderControls();
};
prompt.onsubmit = (event) => {
  event.preventDefault();
  const boundSelection = selection;
  if (!boundSelection) return;
  void run(async () => {
    const result = await review.save(superdoc.activeEditor?.doc, boundSelection, {
      question: question.value,
      quote: boundSelection.capture.quotedText,
      summary: 'Consider whether this wording needs a clearer limit.',
      suggestedText: suggested.value,
    });
    if (!result.success) throw new Error(result.message);
    selection = null;
    prompt.hidden = true;
    await refresh();
    status.textContent = 'Finding saved in the document.';
  });
};
download.onclick = () =>
  void run(async () => {
    await superdoc.export({ exportType: ['docx'], triggerDownload: true });
    status.textContent = 'DOCX downloaded.';
  });
window.addEventListener('beforeunload', () => {
  stopSelection?.();
  superdoc.destroy();
});

```

Select a short phrase, choose **Ask AI about selection**, and save the simulated response as a finding. Then choose
**Suggest edit** and **Download DOCX**. The example uses no model service. Edit the suggested wording before saving;
the supplied response only demonstrates the workflow, not legal advice.

This standalone example opens one document. It disables review actions and download while an action is pending.
Keep the replacement guards below if you add file switching.

## Extend an existing selection workflow [#extend-an-existing-selection-workflow]

This advanced recipe builds on [Selection and position](/editor/custom-ui/selection-and-viewport). It reuses the captured
selection and sample document. Your application supplies the model response and finding panel; the controller below
owns saving findings, resolving their anchors, and creating tracked suggestions.

Keep the implementation to three actions: save a finding, show its text, and suggest an edit. Add more controls only when
your workflow needs them.

Create `src/review-highlights.ts` and `src/review-highlights.css` from the [controller implementation](#controller-implementation)
at the end of this guide. The integration fragments below belong in your existing selection workflow; they are not a
second standalone Editor.

Create one controller for each Editor. Pass its extension through `extensions`, not the removed `editorExtensions`
option. Set `user` to the identity that should author tracked suggestions from this Editor:

```ts
import { createReviewFindings, isSupersededRefresh } from './review-highlights';

function showRefreshError(error: unknown): void {
  if (isSupersededRefresh(error)) return;
  renderFindingPanel([]);
  showError(error);
}

const reviewFindings = createReviewFindings({
  // Called after an edit moves a finding's anchor and the controller re-resolves it.
  onFindingsChanged: renderFindingPanel,
  onFindingsError: showRefreshError,
});

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  extensions: [reviewFindings.extension],
  user: { name: 'Review assistant', email: 'review-assistant@example.com' },
  onReady: ({ superdoc }) => {
    void reviewFindings.refresh(superdoc.activeEditor?.doc).then(renderFindingPanel, showRefreshError);
  },
});
```

Only the newest `refresh()` publishes. `showRefreshError` ignores an older call's expected rejection and reports real
failures through your application's `showError` handler.

Bind the selection before sending the model request. The controller checks this binding before issuing a write and
rejects it if the document has changed:

```ts
const reviewSelection = reviewFindings.bindSelection(capture);
if (!reviewSelection) {
  showError('Select plain body text before asking AI.');
  return;
}
```

Do not call `replaceFile()` while `save()`, `suggest()`, or `remove()` is pending. Await pending review actions before
replacing the document, and prevent new review actions until replacement finishes. Binding rejects stale work before
dispatch; it does not cancel a write already sent to the Editor. `expectedRevision` guards edits within one document,
not document identity across replacements.

Every action also carries the `doc` it runs against. Once `refresh()` has named this controller's document, an action
carrying a different Editor's `doc` is refused: two Editors showing copies of one DOCX share block IDs, so the wrong
document would accept the target and attach the finding to unrelated content.

`refresh()` may bind a different document — that is how a replacement is adopted — but doing so retires the rows and
captures from the previous binding. Re-render the panel from the value the new `refresh()` returns; a row or selection
held across the swap is refused even though it carries the same activation.

Before replacement, call `renderFindingPanel(await reviewFindings.refresh(null))` to clear the panel and retire pending
reads. After `replaceFile()` resolves, refresh `superdoc.activeEditor?.doc` and pass the result to `renderFindingPanel`,
using `showRefreshError` for failures. Do not rely on the initial `onReady` callback to load the replacement's findings.

Refresh on both outcomes, not only on success. `replaceFile()` reports its result through `state`: a value other than
`review-ready` or `editing-ready` means the replacement was rejected and the previous document was reopened and
remounted. The panel has already been cleared by then, so skipping the refresh leaves that restored document with an
empty panel and leaves the controller with no document to run its mutation refreshes against.

Save the model's analysis and proposed replacement in one typed payload. `save()` persists the record; it does not
re-render your panel, so refresh on success and show the message on failure:

```ts
const doc = superdoc.activeEditor?.doc;
const result = await reviewFindings.save(doc, reviewSelection, {
  question,
  quote: reviewSelection.capture.quotedText,
  summary: answer.summary,
  suggestedText: answer.suggestedText,
});

if (result.success) {
  void reviewFindings.refresh(doc).then(renderFindingPanel, showRefreshError);
} else {
  showError(result.message);
}
```

`save()` refuses a selection that the reader edited while the model request was in flight, because the captured offsets
no longer describe the same text. Ask for the selection again when that happens.

When the reader chooses **Suggest edit**, resolve the finding's current anchor and create a tracked replacement:

```ts
const result = await reviewFindings.suggest(superdoc.activeEditor?.doc, finding);

if (!result.success) {
  showError(result.message);
}
```

Use `superdoc.ui.metadata.scrollIntoView({ id: finding.id, block: 'center' })` for **Show in document**. Disable that
control, and **Suggest edit**, while `finding.anchorStatus` is not `resolved`: neither can act on a finding whose anchor
the document no longer contains.

Also disable **Suggest edit** when `finding.payload.suggestionStatus` is set. The controller saves `pending` before
requesting the edit, then `created` after it succeeds. This status travels with the exported DOCX, so reopening does not
offer the same suggestion again. If a request is interrupted, show **Check document** for `pending`: the edit may have
succeeded even though its final status was not saved. Inspect the document before creating a new finding.

Use the controller's `remove()` method to delete the finding without deleting its text or any tracked suggestion already
created from it. Like `save()`, it returns a result rather than re-rendering, so refresh the panel the same way:

```ts
const doc = superdoc.activeEditor?.doc;
const result = await reviewFindings.remove(doc, finding);

if (result.success) {
  void reviewFindings.refresh(doc).then(renderFindingPanel, showRefreshError);
} else {
  showError(result.message);
}
```

The sample accepts one-paragraph body-text selections, and enforces it: `save()` rejects a selection that spans
paragraphs, because `suggest()` can only replace text inside one. See
[Store application data in DOCX](/document-api/application-data) for all metadata target rules, collaboration behavior,
and the application-data trust boundary.

## Verify the result [#verify-the-result]

Save one finding and confirm that a risk mark and panel card appear. Choose **Suggest edit** and confirm that SuperDoc
replaces the mark with a tracked revision. The finding card should remain available to explain the change.

If the same application action will appear in more than one control, use
[Custom commands](/editor/custom-ui/custom-commands) to share its behavior and state. Otherwise, return to the
[Custom UI overview](/editor/custom-ui/overview).

## Controller implementation [#controller-implementation]

The controller uses `defineSuperDocExtension()` to register its visual layer and document lifecycle handlers. It validates
stored data, re-resolves anchors after edits, and rejects stale selections. Keep these checks when adapting it.

Save as `src/review-highlights.ts`:

```ts
import { defineSuperDocExtension } from 'superdoc';
import type { SuperDocExtension, SuperDocVisualHandle, SuperDocVisualTarget } from 'superdoc';
import type { BrowserDocumentApi, SelectionCapture, SelectionTarget, TextTarget } from 'superdoc/ui';
import './review-highlights.css';

const FINDING_NAMESPACE = 'urn:example:ai-review-findings:1';

export type ReviewFindingPayload = {
  kind: 'risk';
  question: string;
  quote: string;
  summary: string;
  suggestedText?: string;
  suggestionStatus?: 'pending' | 'created';
};

export type ReviewFinding = {
  anchorStatus: 'orphan' | 'resolved';
  id: string;
  /**
   * The activation that listed this row. Carried on the row itself so an immutable copy
   * (`{ ...finding }`) stays valid, while a row retained across a document swap does not —
   * a replacement DOCX can reuse metadata IDs, so the ID alone is not proof of provenance.
   */
  sourceToken: string;
  /**
   * The document binding that listed this row. `sourceToken` proves the activation, not the
   * document: `refresh()` can bind a different Editor's `doc` within one activation, and two
   * copies of a DOCX share metadata IDs.
   */
  documentEpoch: number;
  payload: ReviewFindingPayload;
  /** A tracked suggestion was created from this finding. */
  suggested: boolean;
};

export type BoundReviewSelection = {
  capture: SelectionCapture;
};

export type ReviewFindingsOptions = {
  /** Called with the current rows whenever an edit forces the findings to re-resolve. */
  onFindingsChanged?: (findings: readonly ReviewFinding[]) => void;
  /** Called when a re-resolve fails and the stale highlights have been cleared. */
  onFindingsError?: (error: unknown) => void;
};

type FindingActionResult = { success: true; id: string } | { success: false; message: string };
type AttachableCapture = SelectionCapture & { target: TextTarget };

/**
 * `ranges.resolve()` truncates its verification preview past this many UTF-16 units and sets
 * `preview.truncated`, which `suggest()` treats as unverifiable. Saving a longer capture would
 * strand a finding that can never be applied.
 */
const MAX_VERIFIABLE_CAPTURE_LENGTH = 200;

const SUPERSEDED_REFRESH = 'ReviewFindingsRefreshSuperseded';

/** A refresh another call or another document already owns. Safe for a caller to ignore. */
function supersededRefresh(message: string): Error {
  const error = new Error(message);
  error.name = SUPERSEDED_REFRESH;
  return error;
}

export function isSupersededRefresh(error: unknown): boolean {
  return error instanceof Error && error.name === SUPERSEDED_REFRESH;
}

const STALE_SELECTION_MESSAGE = 'The document changed after this text was selected. Select the text again.';
const STALE_FINDING_MESSAGE = 'The document changed after this finding was listed. Refresh the findings.';

function isReviewFindingPayload(value: unknown): value is ReviewFindingPayload {
  if (typeof value !== 'object' || value === null) return false;
  const candidate = value as Partial<ReviewFindingPayload>;
  return (
    candidate.kind === 'risk' &&
    typeof candidate.question === 'string' &&
    typeof candidate.quote === 'string' &&
    typeof candidate.summary === 'string' &&
    (candidate.suggestedText === undefined || typeof candidate.suggestedText === 'string') &&
    (candidate.suggestionStatus === undefined ||
      candidate.suggestionStatus === 'pending' ||
      candidate.suggestionStatus === 'created')
  );
}

function toSelectionTarget(target: SelectionTarget | TextTarget): SelectionTarget | null {
  if (target.kind === 'selection') return target.coordinateSpace === 'tracked' ? null : target;
  if (target.coordinateSpace === 'tracked' || target.segments.length === 0) return null;

  const first = target.segments[0];
  const last = target.segments[target.segments.length - 1];
  if (first.blockId !== last.blockId) return null;

  return {
    kind: 'selection',
    start: { kind: 'text', blockId: first.blockId, offset: first.range.start },
    end: { kind: 'text', blockId: last.blockId, offset: last.range.end },
    ...(target.story ? { story: target.story } : {}),
  };
}

function toVisualTargets(target: SelectionTarget | TextTarget): SuperDocVisualTarget[] {
  if (target.kind === 'text') {
    return target.segments.map((segment) => ({
      kind: 'text',
      blockId: segment.blockId,
      range: { start: segment.range.start, end: segment.range.end },
    }));
  }
  if (target.start.kind !== 'text' || target.end.kind !== 'text') return [];
  if (target.start.blockId !== target.end.blockId) return [];
  return [
    {
      kind: 'text',
      blockId: target.start.blockId,
      range: { start: target.start.offset, end: target.end.offset },
    },
  ];
}

function canAttach(capture: SelectionCapture | null | undefined): capture is AttachableCapture {
  const target = capture?.status === 'ready' ? capture.target : null;
  if (!target || target.coordinateSpace === 'tracked') return false;
  if (target.story !== undefined && target.story.storyType !== 'body') return false;
  if (!target.segments.every((segment) => segment.range.start < segment.range.end)) return false;
  // Save only what `suggest()` can act on. `toSelectionTarget()` rejects a target that
  // spans paragraphs, so accepting one here would persist a finding that can never be
  // suggested. It also rejects an empty segment list.
  if (toSelectionTarget(target) === null) return false;
  const length = target.segments.reduce((total, segment) => total + (segment.range.end - segment.range.start), 0);
  return length <= MAX_VERIFIABLE_CAPTURE_LENGTH;
}

export function createReviewFindings(options: ReviewFindingsOptions = {}) {
  let highlightLayer: SuperDocVisualHandle | null = null;
  const suggestedFindingIds = new Set<string>();
  const visualTargetsByFindingId = new Map<string, readonly SuperDocVisualTarget[]>();
  // A replacement document can reuse block IDs, so each action is bound to the extension activation that produced it
  // and to the document that activation last listed.
  // Disposal invalidates the checks before dispatch, but cannot cancel issued writes.
  // The application must await pending review actions before replacing the document.
  let activeSource: object | null = null;

  const sourceBindings = new WeakMap<object, object>();
  // Per-activation token stamped onto every listed row. Survives immutable copies and, unlike
  // the metadata ID, is not reused by a replacement document.
  let activeSourceToken = '';
  // A bound capture holds frozen block offsets. Any committed edit can move the text under
  // them, and the document identity does not change, so record the edit count at bind time
  // and refuse to attach across it.
  let mutationEpoch = 0;
  const boundMutationEpoch = new WeakMap<BoundReviewSelection, number>();
  // Only the newest refresh may publish. Two overlapping calls both pass the source check,
  // and the older one finishing last would otherwise restore its stale listing.
  let refreshSequence = 0;
  let lastRefreshedDoc: BrowserDocumentApi | null = null;
  // Increments whenever `refresh()` binds a different document. Stamped onto every listed row
  // and bound capture so work from an earlier binding fails its provenance check.
  let documentEpoch = 0;
  const boundDocumentEpoch = new WeakMap<BoundReviewSelection, number>();

  /**
   * One mutation refresh at a time, with at most one queued behind it. A typing burst
   * otherwise starts a listing plus a `get` and `resolve` per finding on every keystroke;
   * the sequence guard stops stale results publishing but cannot cancel the requests.
   */
  let mutationRefreshRunning = false;
  let mutationRefreshQueued = false;

  function runMutationRefresh(): void {
    const doc = lastRefreshedDoc;
    if (!doc) return;
    if (mutationRefreshRunning) {
      refreshSequence += 1;
      mutationRefreshQueued = true;
      return;
    }
    mutationRefreshRunning = true;
    void refresh(doc)
      .then(
        (findings) => options.onFindingsChanged?.(findings),
        (error) => {
          if (isSupersededRefresh(error)) return;
          options.onFindingsError?.(error);
        },
      )
      .finally(() => {
        mutationRefreshRunning = false;
        if (!mutationRefreshQueued) return;
        mutationRefreshQueued = false;
        runMutationRefresh();
      });
  }

  function paintFindings(layer = highlightLayer) {
    layer?.replace(
      [...visualTargetsByFindingId].flatMap(([id, targets]) => (suggestedFindingIds.has(id) ? [] : targets)),
    );
  }

  const extension: SuperDocExtension = defineSuperDocExtension({
    id: 'example.aiReviewFindings',
    activate(ctx) {
      const source = {};
      activeSource = source;
      suggestedFindingIds.clear();
      visualTargetsByFindingId.clear();
      // Unique across controller instances too: two Editors showing copies of the same DOCX
      // share metadata IDs, so a per-controller counter would collide on their first
      // activations.
      activeSourceToken = globalThis.crypto.randomUUID();
      lastRefreshedDoc = null;
      const layer = ctx.visuals.highlight('findings', {
        className: 'review-finding-highlight',
        scope: 'text',
      });
      highlightLayer = layer;
      ctx.disposables.add(layer);

      // Cached visual targets are numeric. An edit moves the durable metadata anchor but not
      // the paint, so re-resolve instead of leaving a highlight over different text.
      ctx.disposables.add(
        ctx.onMutation({ affects: ['text', 'block'] }, () => {
          mutationEpoch += 1;
          if (activeSource !== source) return;
          runMutationRefresh();
        }),
      );

      return {
        dispose() {
          if (activeSource === source) activeSource = null;
          if (highlightLayer === layer) highlightLayer = null;
        },
      };
    },
  });

  function bindSelection(capture: SelectionCapture): BoundReviewSelection | null {
    const source = activeSource;
    if (!source || !canAttach(capture)) return null;
    const selection = { capture } satisfies BoundReviewSelection;
    sourceBindings.set(selection, source);
    boundMutationEpoch.set(selection, mutationEpoch);
    boundDocumentEpoch.set(selection, documentEpoch);
    return selection;
  }

  function sourceIsCurrent(value: BoundReviewSelection | ReviewFinding, doc: BrowserDocumentApi) {
    if (activeSource === null) return false;
    // The application supplies `doc` on every call, so an action can arrive carrying a second
    // Editor's document. Copies of one DOCX reuse block IDs, so that target would resolve and
    // attach this finding to unrelated content. Once a refresh has named this activation's
    // document, refuse every other one; before that there is nothing to contradict.
    if (lastRefreshedDoc !== null && lastRefreshedDoc !== doc) return false;
    if ('sourceToken' in value) {
      return value.sourceToken === activeSourceToken && value.documentEpoch === documentEpoch;
    }
    return sourceBindings.get(value) === activeSource && boundDocumentEpoch.get(value) === documentEpoch;
  }

  function captureIsCurrent(value: BoundReviewSelection, doc: BrowserDocumentApi) {
    return sourceIsCurrent(value, doc) && boundMutationEpoch.get(value) === mutationEpoch;
  }

  async function refresh(doc: BrowserDocumentApi | null | undefined): Promise<readonly ReviewFinding[]> {
    const sequence = (refreshSequence += 1);
    // Rebinding is legitimate — a replacement document, or a swap racing an in-flight refresh —
    // but rows and captures from the previous binding must not survive it. The activation token
    // cannot see this: it is unchanged by a document swap within one activation.
    if ((doc ?? null) !== lastRefreshedDoc) documentEpoch += 1;
    lastRefreshedDoc = doc ?? null;
    if (!doc) {
      visualTargetsByFindingId.clear();
      suggestedFindingIds.clear();
      highlightLayer?.clear();
      return [];
    }

    const expectedSource = activeSource;
    const sourceToken = activeSourceToken;
    const epoch = documentEpoch;
    const layer = highlightLayer;
    try {
      const listed = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
      const rows = await Promise.all(
        listed.items.map(async (item) => {
          const [record, resolved] = await Promise.all([
            doc.metadata.get({ id: item.id }),
            doc.metadata.resolve({ id: item.id }),
          ]);
          if (!record || !isReviewFindingPayload(record.payload)) return null;
          return {
            finding: {
              id: item.id,
              anchorStatus: item.anchorStatus,
              payload: record.payload,
              suggested: record.payload.suggestionStatus === 'created' || suggestedFindingIds.has(item.id),
              sourceToken,
              documentEpoch: epoch,
            } satisfies ReviewFinding,
            visualTargets: resolved ? toVisualTargets(resolved.target) : [],
          };
        }),
      );

      if (expectedSource !== activeSource || layer !== highlightLayer) {
        throw supersededRefresh('The document changed while its findings were loading. Refresh the findings again.');
      }
      if (sequence !== refreshSequence) {
        throw supersededRefresh('A newer refresh replaced this one. Render the newer result instead.');
      }

      visualTargetsByFindingId.clear();
      for (const row of rows) {
        if (row) visualTargetsByFindingId.set(row.finding.id, row.finding.suggested ? [] : row.visualTargets);
      }
      paintFindings(layer);
      return rows.flatMap((row) => {
        if (!row) return [];

        return [row.finding];
      });
    } catch (error) {
      if (isSupersededRefresh(error)) throw error;
      if (expectedSource !== activeSource || layer !== highlightLayer || sequence !== refreshSequence) {
        throw supersededRefresh('A newer document or refresh owns these findings.');
      }
      visualTargetsByFindingId.clear();
      paintFindings(layer);
      throw error;
    }
  }

  async function save(
    doc: BrowserDocumentApi | null | undefined,
    context: BoundReviewSelection | null,
    payload: Omit<ReviewFindingPayload, 'kind' | 'suggestionStatus'>,
  ): Promise<FindingActionResult> {
    const capture = context?.capture;
    if (!doc || !canAttach(capture) || !capture.target) {
      return {
        success: false,
        message: 'Select up to 200 characters inside one paragraph of plain body text before saving the finding.',
      };
    }
    if (!context || !captureIsCurrent(context, doc)) {
      return { success: false, message: STALE_SELECTION_MESSAGE };
    }

    try {
      const overlapping = await doc.metadata.list({ within: capture.target });
      if (!captureIsCurrent(context, doc)) {
        return { success: false, message: STALE_SELECTION_MESSAGE };
      }
      if (overlapping.items.length > 0) {
        return { success: false, message: 'That text already has an attached record.' };
      }

      // The record anchors to `capture.target`, so a quote that disagrees with the captured
      // text makes every later `suggest()` report a changed document and can never be applied.
      // Refuse it here rather than persisting a finding that is dead on arrival.
      if (payload.quote !== capture.quotedText) {
        return {
          success: false,
          message: 'The quote does not match the selected text. Save the finding from the current selection.',
        };
      }

      const receipt = await doc.metadata.attach(
        {
          namespace: FINDING_NAMESPACE,
          target: capture.target,
          payload: {
            kind: 'risk',
            question: payload.question,
            quote: payload.quote,
            summary: payload.summary,
            ...(payload.suggestedText !== undefined ? { suggestedText: payload.suggestedText } : {}),
          } satisfies ReviewFindingPayload,
        },
        { expectedRevision: overlapping.evaluatedRevision },
      );
      if (!receipt.success) return { success: false, message: receipt.failure.message };

      return { success: true, id: receipt.id };
    } catch (error) {
      return { success: false, message: error instanceof Error ? error.message : String(error) };
    }
  }

  async function suggest(
    doc: BrowserDocumentApi | null | undefined,
    finding: ReviewFinding,
  ): Promise<FindingActionResult> {
    if (!doc) return { success: false, message: 'The document is not ready.' };
    // `''` is a valid suggestion: it proposes deleting the anchored text. Only an absent
    // value means the finding carries no edit, which is how the payload type and `save()`
    // already treat it.
    if (finding.payload.suggestedText === undefined) {
      return { success: false, message: 'This finding does not include a suggested edit.' };
    }
    // A rendered row keeps its suggestedText after the tracked change is created, so a panel
    // that re-renders from `refresh()` would otherwise offer the action a second time.
    if (suggestedFindingIds.has(finding.id)) {
      return { success: false, message: 'This finding already has a tracked suggestion.' };
    }
    if (!sourceIsCurrent(finding, doc)) {
      return { success: false, message: STALE_FINDING_MESSAGE };
    }

    let releaseBeforeReplace: (() => Promise<void>) | undefined;
    try {
      const current = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
      if (!sourceIsCurrent(finding, doc)) {
        return { success: false, message: STALE_FINDING_MESSAGE };
      }
      if (!current.items.some((item) => item.id === finding.id)) {
        return { success: false, message: 'That finding is no longer available.' };
      }

      // The panel row can predate another writer's update. `expectedRevision` accepts the
      // newer revision, so read the stored payload back rather than replacing with the
      // suggestion the panel happens to be holding.
      const [record, resolved] = await Promise.all([
        doc.metadata.get({ id: finding.id }),
        doc.metadata.resolve({ id: finding.id }),
      ]);
      if (!sourceIsCurrent(finding, doc)) {
        return { success: false, message: STALE_FINDING_MESSAGE };
      }
      if (!record || !isReviewFindingPayload(record.payload)) {
        return { success: false, message: 'That finding is no longer available.' };
      }
      if (record.payload.suggestionStatus) {
        return {
          success: false,
          message: 'A suggestion was already requested. Check the document before creating another.',
        };
      }
      const suggestedText = record.payload.suggestedText;
      if (suggestedText === undefined) {
        return { success: false, message: 'This finding no longer includes a suggested edit.' };
      }
      let target = resolved ? toSelectionTarget(resolved.target) : null;
      if (!target) {
        return { success: false, message: 'The finding is not anchored to one editable paragraph.' };
      }

      const releaseReservation = async () => {
        releaseBeforeReplace = undefined;
        if (!sourceIsCurrent(finding, doc)) return;
        const current = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
        const latest = await doc.metadata.get({ id: finding.id });
        if (!sourceIsCurrent(finding, doc)) return;
        if (
          latest &&
          isReviewFindingPayload(latest.payload) &&
          latest.payload.suggestionStatus === 'pending' &&
          latest.payload.suggestedText === suggestedText
        ) {
          const payload = { ...latest.payload };
          delete payload.suggestionStatus;
          const released = await doc.metadata.update(
            { id: finding.id, payload },
            { expectedRevision: current.evaluatedRevision },
          );
          if (!released.success) throw new Error(released.failure.message);
        }
      };

      // Reserve the action durably before editing: an interrupted call must not become a retry after reopening.
      const reserved = await doc.metadata.update(
        { id: finding.id, payload: { ...record.payload, suggestionStatus: 'pending' } },
        { expectedRevision: current.evaluatedRevision },
      );
      if (!reserved.success) return { success: false, message: reserved.failure.message };
      releaseBeforeReplace = releaseReservation;
      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      const afterReservation = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
      const pending = await doc.metadata.get({ id: finding.id });
      const currentAnchor = await doc.metadata.resolve({ id: finding.id });
      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      // The reservation only pins status. Another writer can still change the quote before
      // these reads, and the verification below compares against the pre-reservation quote,
      // so a mismatch here would apply an edit the stored finding no longer describes.
      if (
        !pending ||
        !isReviewFindingPayload(pending.payload) ||
        pending.payload.suggestionStatus !== 'pending' ||
        pending.payload.suggestedText !== suggestedText ||
        pending.payload.quote !== record.payload.quote
      ) {
        // A quote-only change leaves our reservation in place, so clear it or the finding stays
        // durably pending and its action stays disabled. releaseReservation() no-ops when the
        // pending row is no longer ours.
        await releaseReservation();
        return { success: false, message: 'The finding changed while requesting its suggestion. Check the document.' };
      }
      target = currentAnchor ? toSelectionTarget(currentAnchor.target) : null;
      if (!target) {
        await releaseReservation();
        return { success: false, message: 'The finding is no longer anchored to editable text.' };
      }
      const range = await doc.ranges.resolve({
        start: { kind: 'point', point: target.start },
        end: { kind: 'point', point: target.end },
        expectedRevision: afterReservation.evaluatedRevision,
      });
      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      if (range.preview.truncated || range.preview.text !== record.payload.quote) {
        await releaseReservation();
        return {
          success: false,
          message: range.preview.truncated
            ? 'The text is too long to verify. Ask AI about a shorter selection.'
            : 'The text changed since this finding was saved. Ask AI about the current text.',
        };
      }
      releaseBeforeReplace = undefined;
      const receipt = await doc.replace(
        { target, text: suggestedText },
        { changeMode: 'tracked', expectedRevision: afterReservation.evaluatedRevision },
      );
      if (!receipt.success) {
        await releaseReservation();
        return { success: false, message: receipt.failure?.message ?? 'The tracked suggestion could not be added.' };
      }

      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      const afterEdit = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
      const latest = await doc.metadata.get({ id: finding.id });
      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      if (!latest || !isReviewFindingPayload(latest.payload)) {
        return { success: false, message: 'The edit was added, but its finding is no longer available.' };
      }
      // Promoting to `created` records which quote the tracked replacement came from, so a quote
      // rewritten between `doc.replace()` and this read must not be marked as its source.
      if (
        latest.payload.suggestionStatus !== 'pending' ||
        latest.payload.suggestedText !== suggestedText ||
        latest.payload.quote !== record.payload.quote
      ) {
        return { success: false, message: 'The edit was added, but the finding changed. Check the document.' };
      }
      const recorded = await doc.metadata.update(
        { id: finding.id, payload: { ...latest.payload, suggestionStatus: 'created' } },
        { expectedRevision: afterEdit.evaluatedRevision },
      );
      if (!recorded.success)
        return {
          success: false,
          message: 'The edit was added, but its status could not be saved. Check the document.',
        };
      if (!sourceIsCurrent(finding, doc)) return { success: false, message: STALE_FINDING_MESSAGE };
      suggestedFindingIds.add(finding.id);
      paintFindings();
      return { success: true, id: finding.id };
    } catch (error) {
      try {
        await releaseBeforeReplace?.();
      } catch {
        return {
          success: false,
          message: 'The suggestion was not sent, but its pending status could not be cleared. Check the document.',
        };
      }
      return { success: false, message: error instanceof Error ? error.message : String(error) };
    } finally {
      if (sourceIsCurrent(finding, doc)) runMutationRefresh();
    }
  }

  async function remove(
    doc: BrowserDocumentApi | null | undefined,
    finding: ReviewFinding,
  ): Promise<FindingActionResult> {
    if (!doc) return { success: false, message: 'The document is not ready.' };
    if (!sourceIsCurrent(finding, doc)) {
      return { success: false, message: STALE_FINDING_MESSAGE };
    }

    try {
      const current = await doc.metadata.list({ namespace: FINDING_NAMESPACE });
      if (!sourceIsCurrent(finding, doc)) {
        return { success: false, message: STALE_FINDING_MESSAGE };
      }
      if (!current.items.some((item) => item.id === finding.id)) {
        return { success: false, message: 'That finding is no longer available.' };
      }

      const receipt = await doc.metadata.remove({ id: finding.id }, { expectedRevision: current.evaluatedRevision });
      if (!receipt.success) return { success: false, message: receipt.failure.message };

      suggestedFindingIds.delete(finding.id);
      visualTargetsByFindingId.delete(finding.id);
      paintFindings();
      return { success: true, id: receipt.id };
    } catch (error) {
      return { success: false, message: error instanceof Error ? error.message : String(error) };
    }
  }

  return { bindSelection, extension, refresh, remove, save, suggest };
}

```

Save as `src/review-highlights.css`:

```css
.review-finding-highlight {
  background: rgb(180 35 24 / 12%);
  box-shadow: inset 0 -2px #b42318;
}

```


---

# Build custom find and replace controls

> Render Search in your application while SuperDoc finds, highlights, and replaces document text.



Use [built-in Search](/editor/built-in-ui/search-and-replace) when its standard controls fit. Build custom controls when
Search belongs in your application shell or needs different interaction design.

This guide replaces only the Search surface. SuperDoc continues to find and highlight matches, move the active match
into view, and apply replacements.

## Try application-owned Search [#try-application-owned-search]

The example starts with eight case-insensitive matches for `Client` across three pages.

1. Choose **Next** and watch the active match move through the document.
2. Turn on **Match case**. The count changes from eight to seven.
3. Replace the active match with `Customer`. The document and count update together.

> **Live example: drive Search from application-owned controls**
>
> SuperDoc renders its toolbar and a three-page DOCX while the application renders Find, Match case, Previous, Next, and Replace controls. The example starts with eight case-insensitive `Client` matches. `ui.search` paints and navigates the matches, while the panel observes the same session for its active index, total, and `canReplace` state. The document starts at 80% on wide layouts and fits to width on narrow layouts.


The controls call `ui.search` instead of reading the rendered document. The same Search session paints the highlights,
tracks the active match, and reports whether replacement is currently available.

## Build the same controls [#build-the-same-controls]

Start from [Build your first custom control](/editor/custom-ui/controller-setup). Download the sample to
your app's `public` directory as `search-sample.docx`:

[Download the Search sample](/fixtures/search-sample.docx): Three pages and one pending deletion · DOCX


For Vanilla, replace the contents of `<body>` in `index.html` with the controls and Editor below:

```html
<form id="search-controls" role="search">
  <input id="search-query" type="search" placeholder="Find in document" aria-label="Find in document" />
  <label><input id="match-case" type="checkbox" /> Match case</label>
  <label><input id="include-deletions" type="checkbox" /> Include pending deletions</label>
  <button id="previous-match" type="button" disabled>Previous</button>
  <button id="next-match" type="button" disabled>Next</button>
  <output id="search-count" for="search-query">No matches</output>

  <input id="replacement" type="text" placeholder="Replacement" aria-label="Replacement text" />
  <button id="replace-match" type="button" disabled>Replace</button>
  <button id="replace-all" type="button" disabled>Replace all</button>
</form>

<p id="search-status" role="status"></p>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { SearchSnapshot, WorkflowActionResult } from 'superdoc/ui';
import 'superdoc/style.css';

function getElement<T extends Element>(selector: string): T {
  const element = document.querySelector<T>(selector);
  if (!element) throw new Error(`Missing search control: ${selector}`);
  return element;
}

const searchForm = getElement<HTMLFormElement>('#search-controls');
const query = getElement<HTMLInputElement>('#search-query');
const matchCase = getElement<HTMLInputElement>('#match-case');
const includeDeletions = getElement<HTMLInputElement>('#include-deletions');
const previous = getElement<HTMLButtonElement>('#previous-match');
const next = getElement<HTMLButtonElement>('#next-match');
const count = getElement<HTMLOutputElement>('#search-count');
const replacement = getElement<HTMLInputElement>('#replacement');
const replace = getElement<HTMLButtonElement>('#replace-match');
const replaceAll = getElement<HTMLButtonElement>('#replace-all');
const status = getElement<HTMLParagraphElement>('#search-status');

const editorUi = { search: false } satisfies UIConfig;
let stopBindings: (() => void) | null = null;
let replacementPending = false;
let actionStatus = '';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/search-sample.docx',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    stopBindings?.();
    replacementPending = false;
    actionStatus = '';
    const { search } = readySuperDoc.ui;

    const render = (snapshot: SearchSnapshot) => {
      const hasMatches = snapshot.total > 0;
      query.disabled = replacementPending;
      matchCase.disabled = replacementPending;
      includeDeletions.disabled = replacementPending;
      previous.disabled = !hasMatches || replacementPending;
      next.disabled = !hasMatches || replacementPending;
      replacement.disabled = replacementPending;
      // `canReplace` is document mutability; a replacement still needs a match.
      replace.disabled = !hasMatches || !snapshot.canReplace || replacementPending;
      // A truncated match set can replace the active match but not all of them.
      replaceAll.disabled = !snapshot.canReplaceAll || replacementPending;
      count.textContent = hasMatches
        ? snapshot.activeIndex >= 0
          ? `${snapshot.activeIndex + 1} of ${snapshot.total}`
          : `${snapshot.total} matches`
        : 'No matches';
      status.textContent = snapshot.reason ?? actionStatus;
    };

    const runSearch = () => {
      actionStatus = '';
      if (!query.value) {
        search.clear();
        return;
      }
      search.find(query.value, {
        caseSensitive: matchCase.checked,
        includeTrackedDeletions: includeDeletions.checked,
      });
    };

    const report = (result: WorkflowActionResult) => {
      actionStatus = result.ok ? '' : (result.reason ?? 'The search action is unavailable.');
      status.textContent = actionStatus;
    };

    const runReplacement = async (action: () => WorkflowActionResult | Promise<WorkflowActionResult>) => {
      if (replacementPending) return;
      replacementPending = true;
      render(search.getSnapshot());
      try {
        report(await action());
      } finally {
        replacementPending = false;
        render(search.getSnapshot());
      }
    };
    const replaceCurrent = () => runReplacement(() => search.replace(replacement.value));
    const replaceEveryMatch = () => runReplacement(() => search.replaceAll(replacement.value));
    const goPrevious = () => report(search.previous());
    const goNext = () => report(search.next());
    const preventSubmit = (event: SubmitEvent) => event.preventDefault();

    const stopSearch = search.observe(render);
    searchForm.addEventListener('submit', preventSubmit);
    query.addEventListener('input', runSearch);
    matchCase.addEventListener('change', runSearch);
    includeDeletions.addEventListener('change', runSearch);
    // Text typed before the document opened has no session yet. Run it now.
    runSearch();
    previous.addEventListener('click', goPrevious);
    next.addEventListener('click', goNext);
    replace.addEventListener('click', replaceCurrent);
    replaceAll.addEventListener('click', replaceEveryMatch);

    stopBindings = () => {
      stopSearch();
      search.close();
      searchForm.removeEventListener('submit', preventSubmit);
      query.removeEventListener('input', runSearch);
      matchCase.removeEventListener('change', runSearch);
      includeDeletions.removeEventListener('change', runSearch);
      previous.removeEventListener('click', goPrevious);
      next.removeEventListener('click', goNext);
      replace.removeEventListener('click', replaceCurrent);
      replaceAll.removeEventListener('click', replaceEveryMatch);
    };
  },
  onContentError: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    status.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopBindings?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { WorkflowActionResult } from 'superdoc/ui';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocSearch, useSuperDocUI } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = { search: false } satisfies UIConfig;

export default function App() {
  return (
    <SuperDocUIProvider>
      <main className='search-layout'>
        <SearchControls />
        <Editor />
      </main>
    </SuperDocUIProvider>
  );
}

function Editor() {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/search-sample.docx'
      onContentError={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onException={({ error }) => console.error('SuperDoc could not open the document.', error)}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
      ui={editorUi}
    />
  );
}

function SearchControls() {
  const ui = useSuperDocUI();
  const search = useSuperDocSearch();
  const [query, setQuery] = useState('');
  const [replacement, setReplacement] = useState('');
  const [matchCase, setMatchCase] = useState(false);
  const [includeDeletions, setIncludeDeletions] = useState(false);
  const [replacementPending, setReplacementPending] = useState(false);
  const [status, setStatus] = useState('');

  // Runs on mount, whenever the query or its options change, and again once
  // the Editor becomes ready, so text typed while loading still searches.
  useEffect(() => {
    if (!ui) return;
    setStatus('');
    if (!query) {
      ui.search.clear();
      return;
    }
    ui.search.find(query, { caseSensitive: matchCase, includeTrackedDeletions: includeDeletions });
  }, [includeDeletions, matchCase, query, ui]);

  useEffect(() => () => ui?.search.close(), [ui]);

  function report(result: WorkflowActionResult) {
    setStatus(result.ok ? '' : (result.reason ?? 'The search action is unavailable.'));
  }

  function goPrevious() {
    if (ui && !replacementPending) report(ui.search.previous());
  }

  function goNext() {
    if (ui && !replacementPending) report(ui.search.next());
  }

  async function runReplacement(action: () => WorkflowActionResult | Promise<WorkflowActionResult>) {
    if (replacementPending) return;
    setReplacementPending(true);
    try {
      report(await action());
    } finally {
      setReplacementPending(false);
    }
  }

  function replaceCurrent() {
    if (ui) return runReplacement(() => ui.search.replace(replacement));
  }

  function replaceEveryMatch() {
    if (ui) return runReplacement(() => ui.search.replaceAll(replacement));
  }

  const hasMatches = search.total > 0;
  const matchCount =
    search.activeIndex >= 0 ? `${search.activeIndex + 1} of ${search.total}` : `${search.total} matches`;

  return (
    <form onSubmit={(event) => event.preventDefault()} role='search'>
      <input
        aria-label='Find in document'
        disabled={replacementPending}
        onChange={(event) => setQuery(event.target.value)}
        placeholder='Find in document'
        type='search'
        value={query}
      />
      <label>
        <input
          checked={matchCase}
          disabled={replacementPending}
          onChange={(event) => setMatchCase(event.target.checked)}
          type='checkbox'
        />
        Match case
      </label>
      <label>
        <input
          checked={includeDeletions}
          disabled={replacementPending}
          onChange={(event) => setIncludeDeletions(event.target.checked)}
          type='checkbox'
        />
        Include pending deletions
      </label>
      <button disabled={!hasMatches || replacementPending} onClick={goPrevious} type='button'>
        Previous
      </button>
      <button disabled={!hasMatches || replacementPending} onClick={goNext} type='button'>
        Next
      </button>
      <output>{hasMatches ? matchCount : 'No matches'}</output>

      <input
        aria-label='Replacement text'
        disabled={replacementPending}
        onChange={(event) => setReplacement(event.target.value)}
        placeholder='Replacement'
        type='text'
        value={replacement}
      />
      <button
        disabled={!hasMatches || !search.canReplace || replacementPending}
        onClick={() => void replaceCurrent()}
        type='button'
      >
        {replacementPending ? 'Replacing…' : 'Replace'}
      </button>
      <button
        disabled={!search.canReplaceAll || replacementPending}
        onClick={() => void replaceEveryMatch()}
        type='button'
      >
        Replace all
      </button>
      <p aria-live='polite' role='status'>
        {search.reason ?? status}
      </p>
    </form>
  );
}

```


`ui: { search: false }` hides SuperDoc's Search surface. It does not disable `superdoc.ui.search`.
This example keeps the controls visible. If your surface opens on demand, your application also owns its keyboard
shortcut and focus behavior.

## Keep controls synchronized [#keep-controls-synchronized]

`find()` starts a visual Search session. SuperDoc highlights the matches, and `next()` or `previous()` moves the active
match into view. `observe()` in Vanilla and `useSuperDocSearch()` in React keep the result count and replacement controls
synchronized as the session settles.

`canReplace` reflects the current document mode, not the match count, so it can be `true` before a query runs. Keep
**Replace** disabled unless there is a match, `canReplace` is `true`, and no replacement is pending. Gate **Replace
all** on `canReplaceAll` instead: it already requires a match, and a session with more matches than SuperDoc
enumerates can still replace the active match but refuses to replace every match. Check the action result because the
document can change after the controls render.

## Include pending deletions when needed [#include-pending-deletions-when-needed]

Pending tracked deletions are excluded by default. Both examples expose the option as an **Include pending deletions**
checkbox that passes `includeTrackedDeletions` to `find()`. For a one-off review search, call it directly:

```ts
import type { SuperDoc } from 'superdoc';

export function findPendingDeletion(superdoc: SuperDoc) {
  return superdoc.ui.search.find('Legacy', {
    includeTrackedDeletions: true,
  });
}

```

This finds the deleted text. It does not accept, reject, or restore the tracked change.

## Verify the controls [#verify-the-controls]

Run the project. Search for `Client`, then move through the eight matches across three pages. Replace one match and
confirm that the count updates. Turn on **Include pending deletions** and search for `Legacy`; the pending deletion
should be the only match.

Use [Document API queries](/document-api/query-content) when code needs document targets instead of a visual Search
session. Build an [application-owned context menu](/editor/custom-ui/context-menus) when actions depend on the entity or
selection under the pointer. Otherwise, return to the [Custom UI overview](/editor/custom-ui/overview).


---

# Build an AI prompt menu for selected text

> Capture selected document text, place an application-owned AI prompt beside it, and keep the target when focus moves.



Show a small **Ask AI** action beside selected text, then expand it into a prompt that keeps the same document range as
context.

## Try the selection prompt [#try-the-selection-prompt]

1. Select the liability cap on the first page. A small **Ask AI** action appears above it.
2. Choose **Ask AI**. The action expands into a question field without losing the captured context.
3. Enter `What does this limit?`, then choose **Ask**.
4. Scroll the document or change its zoom. The prompt follows the selected text while it is visible.
5. Choose **Show selection** to reapply the captured range in the document.

> **Live example: ask AI about selected document text**
>
> Select text in the two-page DOCX. A compact Ask AI action appears first, then expands into a question field. The application captures the text and document target before focus moves. The demo response is local: no text is sent to a model. Scrolling or zooming resolves the same target again, and Show selection reapplies it in the Editor.


The demo creates its response locally and sends no text to a model. In your application, send the question and captured
text through your own server-side model integration.

## Build the same interaction [#build-the-same-interaction]

Start from [Custom UI setup](/editor/custom-ui/controller-setup). Copy this sample to your application's `public`
directory as `contract.docx`, or use another DOCX with selectable text.

[Download the selection sample](/fixtures/custom-selection-workflow.docx): Two pages of selectable contract text · DOCX


### Add the prompt [#add-the-prompt]

Vanilla places the application-owned prompt inside a positioned shell with the Editor. React renders that shell and
prompt in the component below and keeps the quickstart `index.html`. For Vanilla, replace the contents of `<body>` in
`index.html` with:

```html
<div id="toolbar"></div>
<div id="editor-shell" style="position: relative">
  <div id="editor" style="height: 70vh; overflow: auto"></div>
  <aside aria-label="Actions for selected text" data-mode="actions" id="prompt-card" hidden style="position: absolute; z-index: 2">
    <div id="selection-actions">
      <button aria-controls="selection-composer" aria-expanded="false" aria-haspopup="dialog" id="open-selection-prompt" type="button">Ask AI</button>
    </div>
    <div aria-label="Ask AI about selected text" id="selection-composer" hidden role="dialog" style="width: min(19rem, calc(100% - 1rem))">
      <strong>Ask about this</strong>
      <button aria-label="Close AI prompt" id="close-selection-prompt" type="button">Close</button>
      <p id="selection-preview"></p>
      <form id="selection-prompt">
        <label for="selection-question">Ask about this selection</label>
        <textarea id="selection-question" placeholder="What does this limit?" rows="2" style="resize: none"></textarea>
        <button id="ask-selection" disabled type="submit">Ask</button>
      </form>
      <div id="prompt-response" hidden>
        <strong>Response</strong>
        <p id="prompt-answer"></p>
      </div>
      <button id="show-selection" type="button">Show selection</button>
    </div>
  </aside>
</div>

<output id="selection-status" aria-live="polite">Select text in the document.</output>

<script type="module" src="/src/main.ts"></script>

```

### Capture its context and position [#capture-its-context-and-position]

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { SelectionCapture, SelectionSlice } from 'superdoc/ui';
import 'superdoc/style.css';

type SelectionPromptRequest = Readonly<{
  context: string;
  question: string;
}>;

type SelectionPromptResponse = Readonly<{
  answer: string;
}>;

const editorShell = document.querySelector<HTMLDivElement>('#editor-shell');
const editor = document.querySelector<HTMLDivElement>('#editor');
const promptCard = document.querySelector<HTMLElement>('#prompt-card');
const selectionActions = document.querySelector<HTMLDivElement>('#selection-actions');
const openPromptButton = document.querySelector<HTMLButtonElement>('#open-selection-prompt');
const composer = document.querySelector<HTMLDivElement>('#selection-composer');
const closePromptButton = document.querySelector<HTMLButtonElement>('#close-selection-prompt');
const preview = document.querySelector<HTMLParagraphElement>('#selection-preview');
const form = document.querySelector<HTMLFormElement>('#selection-prompt');
const question = document.querySelector<HTMLTextAreaElement>('#selection-question');
const askButton = document.querySelector<HTMLButtonElement>('#ask-selection');
const response = document.querySelector<HTMLDivElement>('#prompt-response');
const answer = document.querySelector<HTMLParagraphElement>('#prompt-answer');
const showSelectionButton = document.querySelector<HTMLButtonElement>('#show-selection');
const status = document.querySelector<HTMLOutputElement>('#selection-status');

// Set only when the card is hidden while it owns focus, so unhiding restores focus to the
// reader who had it and never steals it from the Editor on the card's first appearance.
let restorePromptFocus: HTMLElement | null = null;

if (
  !editorShell ||
  !editor ||
  !promptCard ||
  !selectionActions ||
  !openPromptButton ||
  !composer ||
  !closePromptButton ||
  !preview ||
  !form ||
  !question ||
  !askButton ||
  !response ||
  !answer ||
  !showSelectionButton ||
  !status
) {
  throw new Error('The selection prompt UI is incomplete.');
}

let capture: SelectionCapture | null = null;
let capturedTargetKey = '';
let promptRequestId = 0;
let isComposerOpen = false;
let stopSelection: (() => void) | null = null;
let stopViewport: (() => void) | null = null;
let removeHandlers: (() => void) | null = null;
let interactionStatus = 'Select text in the document.';

const reportInteraction = (message: string) => {
  interactionStatus = message;
  status.textContent = message;
};

const setComposerOpen = (open: boolean) => {
  isComposerOpen = open;
  selectionActions.hidden = open;
  composer.hidden = !open;
  promptCard.dataset.mode = open ? 'composer' : 'actions';
  promptCard.setAttribute('aria-label', open ? 'Ask AI about selected text' : 'Actions for selected text');
  openPromptButton.setAttribute('aria-expanded', String(open));
};

const resetComposer = () => {
  promptRequestId += 1;
  question.value = '';
  answer.textContent = '';
  response.hidden = true;
  askButton.disabled = true;
  setComposerOpen(false);
};

const readModelResponse = (value: unknown): SelectionPromptResponse => {
  if (typeof value !== 'object' || value === null || !('answer' in value) || typeof value.answer !== 'string') {
    throw new Error('The model endpoint returned an invalid response.');
  }
  return { answer: value.answer };
};

const askModel = async (request: SelectionPromptRequest): Promise<SelectionPromptResponse> => {
  const modelResponse = await fetch('/api/selection-prompt', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request),
  });
  if (!modelResponse.ok) throw new Error(`The model request failed with status ${modelResponse.status}.`);
  return readModelResponse(await modelResponse.json());
};

const editorUi = {
  comments: false,
  toolbar: { container: '#toolbar' },
} satisfies UIConfig;

// Restoration must not outrank a deliberate focus move. Hiding the card unmounts the focused
// control, so the browser parks focus on <body>; anything else holding it means the reader
// moved on, and keeping their place matters more than returning to the prompt.
function focusIsUnclaimed() {
  const active = document.activeElement;
  return active === null || active === document.body;
}

function focusedPromptControl(card: HTMLElement): HTMLElement | null {
  if (!(document.activeElement instanceof HTMLElement)) return null;
  return card.contains(document.activeElement) ? document.activeElement : null;
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    const ui = readySuperDoc.ui;

    const positionPrompt = () => {
      const target = capture?.selectionTarget ?? capture?.target;
      if (!target) {
        // Capture only on the visible -> hidden transition. A second invalidation while the
        // card is already hidden would otherwise see focus on the body and clear ownership.
        if (!promptCard.hidden) restorePromptFocus = focusedPromptControl(promptCard);
        promptCard.hidden = true;
        return;
      }

      const geometry = ui.viewport.getRect({ target, relativeTo: editorShell });
      if (!geometry.found || !geometry.rect) {
        // Capture only on the visible -> hidden transition. A second invalidation while the
        // card is already hidden would otherwise see focus on the body and clear ownership.
        if (!promptCard.hidden) restorePromptFocus = focusedPromptControl(promptCard);
        promptCard.hidden = true;
        status.textContent = geometry.reason ?? 'The selection is not currently painted.';
        return;
      }

      const shellBounds = editorShell.getBoundingClientRect();
      const editorBounds = editor.getBoundingClientRect();
      const visibleTop = editorBounds.top - shellBounds.top;
      const visibleBottom = editorBounds.bottom - shellBounds.top;
      const visibleLeft = editorBounds.left - shellBounds.left;
      const visibleRight = editorBounds.right - shellBounds.left;
      const anchorRect = geometry.rects.find(
        (rect) =>
          rect.bottom >= visibleTop &&
          rect.top <= visibleBottom &&
          rect.right >= visibleLeft &&
          rect.left <= visibleRight,
      );
      if (!anchorRect) {
        // Capture only on the visible -> hidden transition. A second invalidation while the
        // card is already hidden would otherwise see focus on the body and clear ownership.
        if (!promptCard.hidden) restorePromptFocus = focusedPromptControl(promptCard);
        promptCard.hidden = true;
        status.textContent = 'Scroll back to the selection to show its prompt.';
        return;
      }

      // Hiding the card removes the focused control from the rendered tree, so focus falls to
      // the document body. Restore it when the range scrolls back into view, or a keyboard
      // user has to rediscover the prompt.
      promptCard.hidden = false;
      if (restorePromptFocus) {
        // The card is only hidden, never removed, so the exact control the reader was on is
        // still focusable; returning them to the textarea would undo the navigation they did.
        const control = restorePromptFocus;
        restorePromptFocus = null;
        if (focusIsUnclaimed()) {
          (control.isConnected ? control : composer.hidden ? openPromptButton : question).focus();
        }
      }
      status.textContent = interactionStatus;
      const edge = 8;
      const gap = 12;
      const maxLeft = Math.max(edge, editorShell.clientWidth - promptCard.offsetWidth - edge);
      const minTop = editorBounds.top - shellBounds.top + edge;
      const maxTop = Math.max(minTop, editorBounds.bottom - shellBounds.top - promptCard.offsetHeight - edge);
      const centeredLeft = anchorRect.left + anchorRect.width / 2 - promptCard.offsetWidth / 2;
      const above = anchorRect.top - promptCard.offsetHeight - gap;
      const below = anchorRect.bottom + gap;
      const belowFits = below + promptCard.offsetHeight <= visibleBottom - edge;
      const preferredTop = isComposerOpen && belowFits ? below : above >= minTop ? above : below;
      promptCard.style.left = `${Math.max(edge, Math.min(centeredLeft, maxLeft))}px`;
      promptCard.style.top = `${Math.max(minTop, Math.min(preferredTop, maxTop))}px`;
    };

    const renderSelection = (selection: SelectionSlice) => {
      if (selection.status !== 'ready' || selection.empty) return;

      const nextCapture = ui.selection.capture();
      if (!nextCapture) return;

      const nextTargetKey = JSON.stringify([nextCapture.selectionTarget ?? nextCapture.target, nextCapture.quotedText]);
      capture = nextCapture;
      if (nextTargetKey !== capturedTargetKey) {
        capturedTargetKey = nextTargetKey;
        resetComposer();
      }
      preview.textContent = `“${nextCapture.quotedText}”`;
      reportInteraction('Selection captured. Choose Ask AI.');
      positionPrompt();
    };

    const openComposer = () => {
      if (!capture) return;
      setComposerOpen(true);
      reportInteraction('The composer kept the captured text as context.');
      positionPrompt();
      question.focus();
    };

    const closeComposer = () => {
      resetComposer();
      reportInteraction('Selection captured. Choose Ask AI.');
      positionPrompt();
      openPromptButton.focus();
    };

    const showSelection = () => {
      if (!capture) return;
      const result = ui.selection.restore(capture);
      reportInteraction(
        result.success ? 'Selection shown.' : `Could not show selection: ${result.reason ?? 'unknown'}`,
      );
    };

    const updateQuestion = () => {
      promptRequestId += 1;
      answer.textContent = '';
      response.hidden = true;
      askButton.disabled = question.value.trim().length === 0;
      reportInteraction('The prompt kept its captured document context.');
    };

    const submitPrompt = async (event: SubmitEvent) => {
      event.preventDefault();
      const currentCapture = capture;
      const currentQuestion = question.value.trim();
      if (!currentCapture || !currentQuestion) return;

      const requestId = (promptRequestId += 1);
      askButton.disabled = true;
      response.hidden = true;
      reportInteraction('Asking the model about the captured text…');

      try {
        const result = await askModel({ context: currentCapture.quotedText, question: currentQuestion });
        if (requestId !== promptRequestId) return;
        answer.textContent = result.answer;
        response.hidden = false;
        reportInteraction('Response received for the captured text.');
        positionPrompt();
      } catch (error) {
        if (requestId !== promptRequestId) return;
        reportInteraction(error instanceof Error ? error.message : 'The model request failed.');
      } finally {
        if (requestId === promptRequestId) askButton.disabled = question.value.trim().length === 0;
      }
    };

    renderSelection(ui.selection.getSnapshot());
    stopSelection = ui.selection.observe(renderSelection);
    stopViewport = ui.viewport.observe(positionPrompt);
    openPromptButton.addEventListener('click', openComposer);
    closePromptButton.addEventListener('click', closeComposer);
    showSelectionButton.addEventListener('click', showSelection);
    question.addEventListener('input', updateQuestion);
    form.addEventListener('submit', submitPrompt);
    removeHandlers = () => {
      openPromptButton.removeEventListener('click', openComposer);
      closePromptButton.removeEventListener('click', closeComposer);
      showSelectionButton.removeEventListener('click', showSelection);
      question.removeEventListener('input', updateQuestion);
      form.removeEventListener('submit', submitPrompt);
    };
  },
  onContentError: ({ error }) => {
    reportInteraction('The document could not be read.');
    console.error(error);
  },
  onException: ({ error }) => {
    reportInteraction('The editor reported a runtime error.');
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  promptRequestId += 1;
  stopSelection?.();
  stopViewport?.();
  removeHandlers?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useCallback, useEffect, useLayoutEffect, useRef, useState, type FormEvent } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { SelectionCapture } from 'superdoc/ui';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocSelection, useSuperDocUI } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

type PromptPosition = { left: number; top: number };
type SelectionPromptRequest = Readonly<{ context: string; question: string }>;
type SelectionPromptResponse = Readonly<{ answer: string }>;

const editorUi = { comments: false } satisfies UIConfig;

// Restoration must not outrank a deliberate focus move. Hiding the card unmounts the focused
// control, so the browser parks focus on <body>; anything else holding it means the reader
// moved on, and keeping their place matters more than returning to the prompt.
function focusIsUnclaimed() {
  const active = document.activeElement;
  return active === null || active === document.body;
}

// The card remounts on scroll-back with fresh elements, so the reader's position is recorded
// as a control name rather than a node. Returning them to the textarea when they were on
// Close or Ask would make them navigate back to what they had already reached.
function promptControlName(card: HTMLElement | null): string | null {
  if (!card || !(document.activeElement instanceof HTMLElement)) return null;
  if (!card.contains(document.activeElement)) return null;
  return document.activeElement.closest('[data-prompt-control]')?.getAttribute('data-prompt-control') ?? '';
}

function focusPromptControl(card: HTMLElement | null, name: string | null): boolean {
  if (!card || !name) return false;
  const control = card.querySelector(`[data-prompt-control="${name}"]`);
  if (!(control instanceof HTMLElement)) return false;
  control.focus();
  return true;
}

function readModelResponse(value: unknown): SelectionPromptResponse {
  if (typeof value !== 'object' || value === null || !('answer' in value) || typeof value.answer !== 'string') {
    throw new Error('The model endpoint returned an invalid response.');
  }
  return { answer: value.answer };
}

async function askModel(request: SelectionPromptRequest): Promise<SelectionPromptResponse> {
  const response = await fetch('/api/selection-prompt', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request),
  });
  if (!response.ok) throw new Error(`The model request failed with status ${response.status}.`);
  return readModelResponse(await response.json());
}

export default function App() {
  return (
    <SuperDocUIProvider>
      <SelectionPromptEditor />
    </SuperDocUIProvider>
  );
}

function SelectionPromptEditor() {
  const ui = useSuperDocUI();
  const selection = useSuperDocSelection();
  const setSuperDoc = useSetSuperDoc();
  const shellRef = useRef<HTMLDivElement>(null);
  const promptRef = useRef<HTMLElement>(null);
  const actionButtonRef = useRef<HTMLButtonElement>(null);
  const questionRef = useRef<HTMLTextAreaElement>(null);
  const captureKeyRef = useRef('');
  const promptRequestIdRef = useRef(0);
  const restoreActionFocusRef = useRef(false);
  // The composer keeps `isComposerOpen` true across a scroll-away, so visibility alone must
  // not refocus it: only opening it, or having owned focus when it was hidden, may.
  const restoreComposerFocusRef = useRef<string | null>(null);
  const wasComposerOpenRef = useRef(false);
  const [capture, setCapture] = useState<SelectionCapture | null>(null);
  const [position, setPosition] = useState<PromptPosition | null>(null);
  const [prompt, setPrompt] = useState('');
  const [answer, setAnswer] = useState('');
  const [isAsking, setIsAsking] = useState(false);
  const [isComposerOpen, setIsComposerOpen] = useState(false);
  const [status, setStatus] = useState('Select text in the document.');
  const [geometryStatus, setGeometryStatus] = useState<string | null>(null);

  const positionPrompt = useCallback(() => {
    const shell = shellRef.current;
    const target = capture?.selectionTarget ?? capture?.target;
    if (!ui || !shell || !target) {
      setPosition(null);
      setGeometryStatus(null);
      return;
    }

    const geometry = ui.viewport.getRect({ target, relativeTo: shell });
    if (!geometry.found || !geometry.rect) {
      setPosition(null);
      setGeometryStatus('The selection is not currently painted.');
      return;
    }

    const host = ui.viewport.getHost();
    if (!host) {
      setPosition(null);
      setGeometryStatus('The editor viewport is not currently available.');
      return;
    }

    const shellBounds = shell.getBoundingClientRect();
    const hostBounds = host.getBoundingClientRect();
    const visibleTop = hostBounds.top - shellBounds.top;
    const visibleBottom = hostBounds.bottom - shellBounds.top;
    const visibleLeft = hostBounds.left - shellBounds.left;
    const visibleRight = hostBounds.right - shellBounds.left;
    const anchorRect = geometry.rects.find(
      (rect) =>
        rect.bottom >= visibleTop &&
        rect.top <= visibleBottom &&
        rect.right >= visibleLeft &&
        rect.left <= visibleRight,
    );
    if (!anchorRect) {
      setPosition(null);
      setGeometryStatus('Scroll back to the selection to show its prompt.');
      return;
    }

    const edge = 8;
    const gap = 12;
    const promptWidth = promptRef.current?.offsetWidth ?? (isComposerOpen ? 304 : 104);
    const promptHeight = promptRef.current?.offsetHeight ?? (isComposerOpen ? 300 : 40);
    const maxLeft = Math.max(edge, shell.clientWidth - promptWidth - edge);
    const minTop = visibleTop + edge;
    const maxTop = Math.max(minTop, visibleBottom - promptHeight - edge);
    const centeredLeft = anchorRect.left + anchorRect.width / 2 - promptWidth / 2;
    const above = anchorRect.top - promptHeight - gap;
    const below = anchorRect.bottom + gap;
    const belowFits = below + promptHeight <= visibleBottom - edge;
    const preferredTop = isComposerOpen && belowFits ? below : above >= minTop ? above : below;

    setGeometryStatus(null);
    setPosition({
      left: Math.max(edge, Math.min(centeredLeft, maxLeft)),
      top: Math.max(minTop, Math.min(preferredTop, maxTop)),
    });
  }, [capture, isComposerOpen, ui]);

  useEffect(() => {
    if (!ui || selection.status !== 'ready' || selection.empty) return;
    const nextCapture = ui.selection.capture();
    if (!nextCapture) return;

    const nextKey = JSON.stringify([nextCapture.selectionTarget ?? nextCapture.target, nextCapture.quotedText]);
    if (nextKey !== captureKeyRef.current) {
      captureKeyRef.current = nextKey;
      promptRequestIdRef.current += 1;
      setPrompt('');
      setAnswer('');
      setIsAsking(false);
      setIsComposerOpen(false);
    }
    setCapture(nextCapture);
    setStatus('Selection captured. Choose Ask AI.');
  }, [selection, ui]);

  const isPromptVisible = position !== null;
  useLayoutEffect(positionPrompt, [answer, isComposerOpen, isPromptVisible, positionPrompt]);
  useEffect(() => ui?.viewport.observe(positionPrompt), [positionPrompt, ui]);

  // Record whether any prompt control — textarea, Close, Ask, Show selection — owned focus
  // just before the card unmounts, so a scroll-back restores it to the reader who had it
  // rather than pulling it from wherever it moved.
  useLayoutEffect(() => {
    if (!isPromptVisible) return undefined;
    return () => {
      restoreComposerFocusRef.current = promptControlName(promptRef.current);
    };
  }, [isPromptVisible]);

  useEffect(() => {
    // The card unmounts whenever the captured range scrolls out of view. isComposerOpen does
    // not change across that, so visibility has to drive focus restoration too.
    const composerJustOpened = isComposerOpen && !wasComposerOpenRef.current;
    wasComposerOpenRef.current = isComposerOpen;
    if (!isPromptVisible) return;
    const restoreTarget = restoreComposerFocusRef.current;
    if (isComposerOpen) {
      if (!composerJustOpened && restoreTarget === null) return;
      restoreComposerFocusRef.current = null;
      if (composerJustOpened) {
        questionRef.current?.focus();
        return;
      }
      if (focusIsUnclaimed() && !focusPromptControl(promptRef.current, restoreTarget)) {
        questionRef.current?.focus();
      }
      return;
    }
    // The capture is card-wide, so the compact action button's ownership lands in the same
    // record; either signal restores this branch. Closing the composer is deliberate and always
    // lands focus; a scroll-back only reclaims focus that nobody else took.
    const closedComposer = restoreActionFocusRef.current;
    if (!closedComposer && restoreTarget === null) return;
    restoreActionFocusRef.current = false;
    restoreComposerFocusRef.current = null;
    if (closedComposer) {
      actionButtonRef.current?.focus();
      return;
    }
    if (focusIsUnclaimed() && !focusPromptControl(promptRef.current, restoreTarget)) {
      actionButtonRef.current?.focus();
    }
  }, [isComposerOpen, isPromptVisible]);

  useEffect(
    () => () => {
      promptRequestIdRef.current += 1;
    },
    [],
  );

  function showSelection() {
    if (!ui || !capture) return;
    const result = ui.selection.restore(capture);
    setStatus(result.success ? 'Selection shown.' : `Could not show selection: ${result.reason ?? 'unknown'}.`);
  }

  function closeComposer() {
    restoreActionFocusRef.current = true;
    promptRequestIdRef.current += 1;
    setIsAsking(false);
    setPrompt('');
    setAnswer('');
    setIsComposerOpen(false);
    setStatus('Selection captured. Choose Ask AI.');
  }

  function openComposer() {
    restoreActionFocusRef.current = false;
    setIsComposerOpen(true);
    setStatus('The composer kept the captured text as context.');
  }

  async function submitPrompt(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const currentCapture = capture;
    const question = prompt.trim();
    if (!currentCapture || !question || isAsking) return;

    const requestId = (promptRequestIdRef.current += 1);
    setIsAsking(true);
    setAnswer('');
    setStatus('Asking the model about the captured text…');

    try {
      const result = await askModel({ context: currentCapture.quotedText, question });
      if (requestId !== promptRequestIdRef.current) return;
      setAnswer(result.answer);
      setStatus('Response received for the captured text.');
    } catch (error) {
      if (requestId !== promptRequestIdRef.current) return;
      setStatus(error instanceof Error ? error.message : 'The model request failed.');
    } finally {
      if (requestId === promptRequestIdRef.current) setIsAsking(false);
    }
  }

  return (
    <>
      <div ref={shellRef} style={{ position: 'relative' }}>
        <SuperDocEditor
          document='/contract.docx'
          onContentError={({ error }) => {
            setGeometryStatus(null);
            setStatus('The document could not be read.');
            console.error(error);
          }}
          onException={({ error }) => {
            setGeometryStatus(null);
            setStatus('The editor reported a runtime error.');
            console.error(error);
          }}
          onReady={({ superdoc }) => setSuperDoc(superdoc)}
          ui={editorUi}
        />

        {capture && position ? (
          <aside
            aria-label={isComposerOpen ? 'Ask AI about selected text' : 'Actions for selected text'}
            ref={promptRef}
            style={{
              left: position.left,
              position: 'absolute',
              top: position.top,
              width: isComposerOpen ? 'min(19rem, calc(100% - 1rem))' : 'max-content',
            }}
            role={isComposerOpen ? 'dialog' : undefined}
          >
            {isComposerOpen ? (
              <>
                <strong>Ask about this</strong>
                <button aria-label='Close AI prompt' data-prompt-control='close' onClick={closeComposer} type='button'>
                  Close
                </button>
                <p>“{capture.quotedText}”</p>
                <form onSubmit={(event) => void submitPrompt(event)}>
                  <label htmlFor='selection-question'>Ask about this selection</label>
                  <textarea
                    data-prompt-control='question'
                    id='selection-question'
                    onChange={(event) => {
                      promptRequestIdRef.current += 1;
                      setPrompt(event.target.value);
                      setAnswer('');
                      setIsAsking(false);
                      setStatus('The prompt kept its captured document context.');
                    }}
                    placeholder='What does this limit?'
                    ref={questionRef}
                    rows={2}
                    style={{ resize: 'none' }}
                    value={prompt}
                  />
                  <button data-prompt-control='ask' disabled={isAsking || !prompt.trim()} type='submit'>
                    {isAsking ? 'Asking…' : 'Ask'}
                  </button>
                </form>
                {answer ? (
                  <div>
                    <strong>Response</strong>
                    <p>{answer}</p>
                  </div>
                ) : null}
                <button data-prompt-control='show' onClick={showSelection} type='button'>
                  Show selection
                </button>
              </>
            ) : (
              <button
                aria-haspopup='dialog'
                data-prompt-control='action'
                onClick={openComposer}
                ref={actionButtonRef}
                type='button'
              >
                Ask AI
              </button>
            )}
          </aside>
        ) : null}
      </div>
      <output aria-live='polite'>{geometryStatus ?? status}</output>
    </>
  );
}

```


`ui.selection.capture()` preserves two things the prompt needs: `quotedText` for model context and a document target
that remains available when the **Ask AI** button and question field take browser focus. The example sends the captured
text, not the live browser selection. A new selection closes the composer and clears its previous question and response.

`ui.viewport.getRect({ target, relativeTo: editorShell })` resolves the target against the current painted layout and
returns coordinates for the prompt's containing block. `ui.viewport.observe()` tells the application to measure again
after scrolling, zooming, resizing, pagination, or repainting changes that geometry. Stop the observer when the custom UI
unmounts.

The example expects this application-owned endpoint:

```http
POST /api/selection-prompt
Content-Type: application/json

{ "context": "the fees Customer paid in the twelve months before the claim", "question": "What does this limit?" }
```

Return a JSON object with an `answer` string. Keep provider credentials and document-access checks on the server.
SuperDoc does not choose a model or send the captured text for you.

> **Keep the target, not its coordinates (warning)**
>
> Do not cache rectangle coordinates as document identity. Coordinates become stale when layout changes. Keep the
> capture and call `getRect()` again.


## Verify the prompt [#verify-the-prompt]

Select text and confirm that only the compact **Ask AI** action appears. Open it and type a question. Confirm that the
request contains the captured `quotedText`, even after the textarea takes focus. Scroll or zoom while the text remains
visible and confirm that the prompt moves with it. Show the selection, then select text on the other page and confirm
that the composer closes and its previous question and response are cleared.

Continue with [Review findings](/editor/custom-ui/review-highlights) when a model result or another application finding
needs durable data anchored to document text.

## Advanced target handling [#advanced-target-handling]

For explicit selections and pointer hit-testing, see the
[Selection and position reference](/editor/custom-ui/selection-reference). It covers target shapes, entity hits,
citation listeners, and story limitations.


---

# Selection and position reference

> Choose document targets, resolve their geometry, and identify supported entities under a pointer.



Use this reference when your custom interface needs explicit selections or pointer hit-testing. For a complete
selection-anchored interaction, start with [Build an AI prompt menu](/editor/custom-ui/selection-and-viewport).

## Choose the target source [#choose-the-target-source]

Use the method that matches where your interface's target comes from:

| Need                                                 | Method                                                |
| ---------------------------------------------------- | ----------------------------------------------------- |
| Preserve selected context after focus moves          | `selection.capture()` and `selection.restore()`       |
| Read the live caret or selection                     | `selection.current()` or `selection.observe()`        |
| Select an explicit `SelectionTarget`                 | `selection.apply(selectionTarget)`                    |
| Position UI from the live selection                  | `selection.getAnchorRect()` or `selection.getRects()` |
| Position UI from a capture or query result           | `viewport.getRect({ target })`                        |
| Identify supported document entities under a pointer | `viewport.entityAt({ x, y })`                         |

`entityAt()` identifies comments, tracked changes, content controls, and citations. It does not return an arbitrary text
position. Use [Context menu](/editor/custom-ui/context-menus) for a complete pointer and keyboard interaction.

`selection.apply()` takes a `SelectionTarget` — the explicit start/end form. `selection.current()` carries both shapes:
`selectionTarget` is that form, and `target` is a `TextTarget` for geometry. Either works for `viewport.getRect()`, which
allows the geometry fallback `selectionTarget ?? target`, but only `selectionTarget` is accepted by
`apply()`. Read it directly and handle `null` rather than reusing that geometry fallback.

## Resolve entities under a point [#resolve-entities-under-a-point]

`ui.viewport.entityAt()` answers the opposite question: which document entities are painted under a screen point. Coordinates are `MouseEvent` `clientX` and `clientY` space, so a pointer handler can pass its own event through:

```ts
editorShell.addEventListener('pointerdown', (event) => {
  const hits = ui.viewport.entityAt({ x: event.clientX, y: event.clientY });
  const control = hits.find((hit) => hit.type === 'contentControl');
  if (control) console.info('content control under pointer', control.id);
});
```

It returns a `ViewportEntityHit[]` ordered innermost first. Every hit carries a `type` and an `id`. Content-control hits can also carry their `tag` and `scope`.

The hits are tracked changes, comments, content controls, and citations. A point over ordinary text carries none of those, so an empty array is the normal answer, not an error. Branch on what you find; do not treat `[]` as a failed lookup.

For citation cards, attach the listener to the public host and match the hit against the citation list. The hit id is the same id as the matching list item. Treat it as opaque and compare it only for equality. Your application supplies `openCitationCard()`:

```ts
const host = ui.viewport.getHost();

const onClick = async (event: MouseEvent) => {
  const hit = ui.viewport.entityAt({ x: event.clientX, y: event.clientY }).find((entity) => entity.type === 'citation');
  if (!hit) return;

  const citations = await Promise.resolve(superdoc.activeEditor?.doc.citations.list());
  const citation = citations?.items.find((item) => item.id === hit.id);
  if (citation) openCitationCard(citation);
};

host?.addEventListener('click', onClick);
// When this custom UI unmounts:
host?.removeEventListener('click', onClick);
```

Do not recover citation identity with `event.target.closest(...)`; the painter DOM is not a public API.

Anchored metadata uses a hidden content control rather than its own hit type, so its record ID arrives as the content-control hit's `tag`. A record with that ID existing does not prove the pointer hit its anchor: an ordinary control can carry a colliding tag. Compare the hit control's `selectionTarget` with `doc.metadata.resolve({ id: hit.tag })` before treating the hit as application metadata.

That comparison narrows the risk without settling it. Content-control hits carry no story, both lookups resolve against the main document part, and painted ids are unique only within that part, so a control in a header, footer, note, or textbox that reuses a body anchor's id and tag passes every check. For documents your own application produced the collision is unlikely; for externally authored files, treat a match as unverified and confirm through your own records. See [Store application data in DOCX](/document-api/application-data).

`story` is not a general field on a hit. Only tracked-change hits carry it, and only when the change is painted outside the body, in a footnote, endnote, header, footer, or textbox. It exists because one tracked-change id can repeat across stories, so `story` names the occurrence actually under the point. Comment and content-control hits are returned normally in those stories but carry no `story`, so do not write story-sensitive handling for them. Use `ui.trackChanges.getAt()` when you need the full tracked-change row rather than the hit.

Pass the object form. The legacy positional form `entityAt(x, y)` fails closed and returns `null`, because the addresses it produced are not resolvable by `getRect()`.


---

# Build selection-aware table controls

> Enable application-owned table actions only when the current selection resolves to a table cell.



A DOCX table does not require custom UI. Build these controls only when your application needs actions outside the
document that follow the active cell, such as **Add row** in an application toolbar. Use `ui.tables` to read that
selection context and `ui.commands` to run actions against it.

If your application already has an explicit table target, use the
[Document API tables reference](/document-api/reference/tables/) instead.

This standalone Vanilla recipe uses the project from [Build your first custom control](/editor/custom-ui/controller-setup).
Save this document as `public/contract.docx`:

[Download the table sample](/fixtures/getting-started.docx): Statement of work with a milestone table · DOCX


## Add the controls [#add-the-controls]

Replace the contents of `<body>` in `index.html` with the table actions, download button, and Editor container:

```html
<aside aria-labelledby="table-heading">
  <h2 id="table-heading">Table controls</h2>
  <p id="table-position" role="status">Place the caret in a table.</p>
  <button id="add-row" type="button" disabled>Add row below</button>
  <button id="delete-row" type="button" disabled>Delete row</button>
  <button id="download" type="button" disabled>Download DOCX</button>
  <p id="table-status" role="status"></p>
</aside>

<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

## Bind actions to table context [#bind-actions-to-table-context]

Replace `src/main.ts`. The example reads `superdoc.ui` after the Editor is ready:

```ts
import { SuperDoc } from 'superdoc';
import type { CommandExecutionResult } from 'superdoc/ui';
import 'superdoc/style.css';

const tablePosition = document.querySelector<HTMLParagraphElement>('#table-position');
const addRowButton = document.querySelector<HTMLButtonElement>('#add-row');
const deleteRowButton = document.querySelector<HTMLButtonElement>('#delete-row');
const tableStatus = document.querySelector<HTMLParagraphElement>('#table-status');
const downloadButton = document.querySelector<HTMLButtonElement>('#download');

if (!tablePosition || !addRowButton || !deleteRowButton || !tableStatus || !downloadButton) {
  throw new Error('The table controls are incomplete.');
}

let stopAddRow: (() => void) | null = null;
let stopDeleteRow: (() => void) | null = null;
let removeHandlers: (() => void) | null = null;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onReady: ({ superdoc: readySuperDoc }) => {
    downloadButton.disabled = false;
    const ui = readySuperDoc.ui;
    const addRow = ui.commands.get('table-add-row-after');
    const deleteRow = ui.commands.get('table-delete-row');

    const render = () => {
      const context = ui.tables.getContext();
      const addState = addRow.getState();
      const deleteState = deleteRow.getState();

      tablePosition.textContent = context.inTable
        ? `Row ${(context.rowIndex ?? 0) + 1}, column ${(context.columnIndex ?? 0) + 1}`
        : 'Place the caret in a table.';
      addRowButton.disabled = !addState.enabled;
      deleteRowButton.disabled = !deleteState.enabled;
      tableStatus.textContent = addState.reason ?? deleteState.reason ?? '';
    };

    const report = (result: CommandExecutionResult, successMessage: string) => {
      if (result === false) {
        tableStatus.textContent = 'The table action is unavailable.';
        return;
      }
      if (typeof result === 'object' && !result.success) {
        tableStatus.textContent = result.failure.message;
        return;
      }
      tableStatus.textContent = successMessage;
    };

    const insertRow = async () => report(await addRow.executeAsync(), 'Row added.');
    const removeRow = async () => report(await deleteRow.executeAsync(), 'Row deleted.');

    stopAddRow = addRow.observe(render);
    stopDeleteRow = deleteRow.observe(render);
    addRowButton.addEventListener('click', insertRow);
    deleteRowButton.addEventListener('click', removeRow);

    removeHandlers = () => {
      addRowButton.removeEventListener('click', insertRow);
      deleteRowButton.removeEventListener('click', removeRow);
    };
  },
});

downloadButton.addEventListener('click', async () => {
  downloadButton.disabled = true;
  try {
    const file = await superdoc.export({ triggerDownload: true });
    tableStatus.textContent = file ? 'DOCX downloaded.' : 'The document could not be exported.';
  } catch (error) {
    console.error('Could not export the document.', error);
    tableStatus.textContent = 'Could not export the document. Try again.';
  } finally {
    downloadButton.disabled = false;
  }
});

window.addEventListener('beforeunload', () => {
  stopAddRow?.();
  stopDeleteRow?.();
  removeHandlers?.();
  superdoc.destroy();
});

```

The example does not construct table locators. The controller resolves the enclosing table, row, column, and cell from
the live selection. It then builds the Document API input for each command.

## Render command state, not assumptions [#render-command-state-not-assumptions]

Each table command reports whether it is supported and enabled. Outside a table, contextual actions fail closed with
`table-context-unavailable`. In viewing mode, mutations report `document-readonly`.

Use `getState()` for the initial render and `observe()` for later selection, mode, and capability changes. Still inspect
the result from `executeAsync()`. Context can change between rendering a button and clicking it.

The routed table command family includes inserting or deleting rows and columns, deleting a table, merging cells,
splitting a cell, and removing borders. Add only the controls your workflow needs. Do not render every catalog command
as a toolbar.

## Keep context tied to selection [#keep-context-tied-to-selection]

`ui.tables.getContext()` returns the current table ID, row and column indices, cell ID, and dimensions when the host can
resolve them. Treat that snapshot as presentation state. Do not cache it as a durable mutation target or derive table
identity from painted DOM attributes.

## Verify the controls [#verify-the-controls]

Place the caret in the milestone table, add a row, delete a row, and choose **Download DOCX**. Outside the table, both row buttons should disable
with a contextual reason.

Use the [Document API tables reference](/document-api/reference/tables/) for explicit targets or operations that are not
selection-driven. Return to the [Custom UI overview](/editor/custom-ui/overview) to choose another workflow.


---

# Build a custom review panel

> Render open tracked changes and let reviewers navigate, accept, or reject each one.



Configure [built-in tracked changes](/editor/track-changes) when the standard review controls fit your workflow. Build a
custom panel when your application needs to own the review queue, layout, or status messages.

This guide replaces only the review sidebar. Your application renders the queue and actions. SuperDoc keeps the queue
synchronized with the marks in the DOCX.

## Try the review workflow [#try-the-review-workflow]

The example keeps SuperDoc's toolbar and loads three changes across three short pages.

1. Use **Previous** and **Next** to move through the review queue.
2. Choose **Show in document** on any row to return to that change.
3. Accept or reject one change. Its row disappears and the open-change count decreases.

> **Live example: review changes from an application-owned panel**
>
> SuperDoc renders its toolbar and a three-page DOCX while the application renders the review queue. Previous, Next, and Show in document move between three real tracked changes. Accepting or rejecting one removes its row and decreases the open-change count. The panel observes `ui.trackChanges`; setting `ui.comments` to `false` removes the built-in comments and review sidebar without removing tracked changes from the document.


The panel follows the same loop as the comments example: observe state, render application markup, run an action, and
report its result.

## Build the same panel [#build-the-same-panel]

Start from [Build your first custom control](/editor/custom-ui/controller-setup). Download the
[custom review fixture](/fixtures/custom-track-changes-workflow.docx) to your app's `public` directory as
`contract.docx`.

For Vanilla, replace the contents of `<body>` in `index.html` with the toolbar, Editor, and panel mounts below:

```html
<div id="toolbar"></div>

<main class="review-layout">
  <div id="editor" style="height: 70vh; overflow: auto"></div>

  <aside aria-labelledby="review-heading">
    <h2 id="review-heading">Review changes</h2>
    <p id="change-count">Opening document...</p>
    <nav aria-label="Tracked change navigation">
      <button id="previous-change" type="button">Previous</button>
      <button id="next-change" type="button">Next</button>
    </nav>
    <ul id="change-list"></ul>
    <p id="review-status" role="status">Choose a change to review it.</p>
  </aside>
</main>

<script type="module" src="/src/main.ts"></script>

```

## Connect the panel [#connect-the-panel]

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { CommandExecutionResult, TrackChangesItem, TrackChangesSlice } from 'superdoc/ui';
import 'superdoc/style.css';

function getElement<T extends Element>(selector: string): T {
  const element = document.querySelector<T>(selector);
  if (!element) throw new Error(`Missing review panel element: ${selector}`);
  return element;
}

const toolbar = getElement<HTMLDivElement>('#toolbar');
const changeCount = getElement<HTMLParagraphElement>('#change-count');
const changeList = getElement<HTMLUListElement>('#change-list');
const previousChange = getElement<HTMLButtonElement>('#previous-change');
const nextChange = getElement<HTMLButtonElement>('#next-change');
const reviewStatus = getElement<HTMLParagraphElement>('#review-status');

const editorUi = {
  comments: false,
  toolbar: { container: toolbar, responsiveTo: 'container' },
} satisfies UIConfig;
type Decision = 'accept' | 'reject';

let pendingDecision: { key: string; decision: Decision } | null = null;
// The occurrence this panel focused. `activeId` alone cannot tell a body row
// from a same-id footnote or header row, so the panel remembers which one it
// asked for and only trusts it while the controller still reports that id.
let activeRow: { id: string; key: string } | null = null;
let stopTrackChanges: (() => void) | null = null;
// The last snapshot from `observe()`. It is the complete review directory;
// the passive snapshot is bounded to the painted page window.
let lastChanges: TrackChangesSlice | null = null;

function decisionFailure(result: CommandExecutionResult): string | null {
  if (result === false) return 'The review decision is unavailable.';
  if (result === true || result.success) return null;
  return result.failure.message;
}

/** A row's exact occurrence: the id plus its story when the change is outside the body. */
function decisionTarget(change: TrackChangesItem): { id: string; story?: unknown } {
  const story = change.address?.story;
  return story ? { id: change.id, story } : { id: change.id };
}

/** Stable per-occurrence key. The same id can appear in the body and in a footnote or header. */
function rowKey(change: TrackChangesItem): string {
  return `${change.id}:${JSON.stringify(change.address?.story ?? null)}`;
}

/** Whether this row is the active occurrence, not merely a row sharing the active id. */
function isActiveRow(change: TrackChangesItem, activeId: string | null): boolean {
  if (change.id !== activeId) return false;
  return activeRow === null || activeRow.id !== activeId || activeRow.key === rowKey(change);
}

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  documentMode: 'suggesting',
  ui: editorUi,
  user: { name: 'Alex Rivera', email: 'alex@example.com' },
  onReady: ({ superdoc: readySuperDoc }) => {
    stopTrackChanges?.();
    const { ui } = readySuperDoc;

    const showChange = async (change: TrackChangesItem) => {
      if (pendingDecision) return;
      // The row's { id, story } pins the clicked occurrence for both focus and
      // reveal when the same id appears in the body and a footnote or header.
      const target = decisionTarget(change);
      if (!ui.trackChanges.setActive(target)) {
        reviewStatus.textContent = 'The tracked change is no longer available.';
        return;
      }
      activeRow = { id: change.id, key: rowKey(change) };
      if (lastChanges) render(lastChanges);

      const result = await ui.trackChanges.scrollTo(target);
      reviewStatus.textContent = result.success
        ? 'Showing the change in the document.'
        : (result.reason ?? 'The tracked change could not be shown.');
    };

    const navigate = async (direction: 'previous' | 'next') => {
      if (pendingDecision) return;
      // Navigation picks the occurrence, so the panel stops asserting its own.
      activeRow = null;
      const result =
        direction === 'previous' ? await ui.trackChanges.navigatePrevious() : await ui.trackChanges.navigateNext();
      reviewStatus.textContent = result.success
        ? `Showing the ${direction} change.`
        : 'No tracked change could be shown.';
    };

    const decideChange = async (decision: Decision, change: TrackChangesItem) => {
      if (pendingDecision) return;
      pendingDecision = { key: rowKey(change), decision };
      reviewStatus.textContent = decision === 'accept' ? 'Accepting change...' : 'Rejecting change...';
      if (lastChanges) render(lastChanges);

      // The async form resolves once the document operation settles, so a
      // late failure still clears the pending state and reaches the reader.
      const target = decisionTarget(change);
      const result =
        decision === 'accept' ? await ui.trackChanges.acceptAsync(target) : await ui.trackChanges.rejectAsync(target);

      pendingDecision = null;
      reviewStatus.textContent =
        decisionFailure(result) ?? (decision === 'accept' ? 'Change accepted.' : 'Change rejected.');
      if (lastChanges) render(lastChanges);
    };

    const render = (changes: TrackChangesSlice) => {
      lastChanges = changes;
      changeCount.textContent =
        changes.status === 'pending'
          ? 'Loading changes...'
          : `${changes.total} open ${changes.total === 1 ? 'change' : 'changes'}`;
      changeList.replaceChildren();
      previousChange.disabled = changes.status === 'pending' || changes.total === 0 || pendingDecision !== null;
      nextChange.disabled = previousChange.disabled;

      for (const change of changes.items) {
        const row = document.createElement('li');
        const summary = document.createElement('span');
        const show = document.createElement('button');
        const accept = document.createElement('button');
        const reject = document.createElement('button');
        const detail =
          change.excerpt ?? change.insertedText ?? change.deletedText ?? change.formattingDeltaSummary ?? change.type;

        summary.textContent = `${detail}${change.author ? ` by ${change.author}` : ''}`;

        const active = isActiveRow(change, changes.activeId);
        const pending = pendingDecision?.key === rowKey(change) ? pendingDecision.decision : null;
        if (active) row.setAttribute('aria-current', 'true');

        show.type = 'button';
        show.textContent = active ? 'Showing' : 'Show in document';
        show.disabled = pendingDecision !== null;
        show.addEventListener('click', () => void showChange(change));

        accept.type = 'button';
        accept.textContent = pending === 'accept' ? 'Accepting...' : 'Accept';
        accept.disabled = pendingDecision !== null;
        accept.addEventListener('click', () => void decideChange('accept', change));

        reject.type = 'button';
        reject.textContent = pending === 'reject' ? 'Rejecting...' : 'Reject';
        reject.disabled = pendingDecision !== null;
        reject.addEventListener('click', () => void decideChange('reject', change));

        row.append(summary, show, accept, reject);
        changeList.append(row);
      }
    };

    stopTrackChanges = ui.trackChanges.observe(render);
    previousChange.addEventListener('click', () => void navigate('previous'));
    nextChange.addEventListener('click', () => void navigate('next'));
  },
  onContentError: ({ error }) => {
    reviewStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
  onException: ({ error }) => {
    reviewStatus.textContent = 'The document could not be opened.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  stopTrackChanges?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useEffect, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { CommandExecutionResult, TrackChangesItem } from 'superdoc/ui';
import { SuperDocUIProvider, useSetSuperDoc, useSuperDocTrackChanges, useSuperDocUI } from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = { comments: false } satisfies UIConfig;
const currentUser = { name: 'Alex Rivera', email: 'alex@example.com' };
type Decision = 'accept' | 'reject';

function decisionFailure(result: CommandExecutionResult): string | null {
  if (result === false) return 'The review decision is unavailable.';
  if (result === true || result.success) return null;
  return result.failure.message;
}

/** A row's exact occurrence: the id plus its story when the change is outside the body. */
function decisionTarget(change: TrackChangesItem): { id: string; story?: unknown } {
  const story = change.address?.story;
  return story ? { id: change.id, story } : { id: change.id };
}

/** Stable per-occurrence key. The same id can appear in the body and in a footnote or header. */
function rowKey(change: TrackChangesItem): string {
  return `${change.id}:${JSON.stringify(change.address?.story ?? null)}`;
}

type ActiveRow = { id: string; key: string };

/** Whether this row is the active occurrence, not merely a row sharing the active id. */
function isActiveRow(change: TrackChangesItem, activeId: string | null, activeRow: ActiveRow | null): boolean {
  if (change.id !== activeId) return false;
  return activeRow === null || activeRow.id !== activeId || activeRow.key === rowKey(change);
}

export default function App() {
  const [loadError, setLoadError] = useState<string | null>(null);

  return (
    <SuperDocUIProvider>
      <main className='review-layout'>
        <Editor onLoadError={setLoadError} />
        <ReviewPanel loadError={loadError} />
      </main>
    </SuperDocUIProvider>
  );
}

function Editor({ onLoadError }: { onLoadError: (message: string) => void }) {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/contract.docx'
      documentMode='suggesting'
      onContentError={() => onLoadError('The document could not be opened.')}
      onException={() => onLoadError('The document could not be opened.')}
      onReady={({ superdoc }) => setSuperDoc(superdoc)}
      ui={editorUi}
      user={currentUser}
    />
  );
}

function ReviewPanel({ loadError }: { loadError: string | null }) {
  const ui = useSuperDocUI();
  const changes = useSuperDocTrackChanges();
  const [pendingKey, setPendingKey] = useState<string | null>(null);
  const [pendingDecision, setPendingDecision] = useState<Decision | null>(null);
  // The occurrence this panel focused. `activeId` alone cannot tell a body row
  // from a same-id footnote or header row, so the panel remembers which one it
  // asked for and only trusts it while the controller still reports that id.
  const [activeRow, setActiveRow] = useState<ActiveRow | null>(null);
  const [status, setStatus] = useState('Choose a change to review it.');

  useEffect(() => {
    if (loadError) setStatus(loadError);
  }, [loadError]);

  async function showChange(change: TrackChangesItem) {
    if (pendingKey) return;
    // The row's { id, story } pins the clicked occurrence for both focus and
    // reveal when the same id appears in the body and a footnote or header.
    const target = decisionTarget(change);
    if (!ui?.trackChanges.setActive(target)) {
      setStatus('The tracked change is no longer available.');
      return;
    }
    setActiveRow({ id: change.id, key: rowKey(change) });

    const result = await ui.trackChanges.scrollTo(target);
    setStatus(
      result.success
        ? 'Showing the change in the document.'
        : (result.reason ?? 'The tracked change could not be shown.'),
    );
  }

  async function navigate(direction: 'previous' | 'next') {
    if (!ui || pendingKey) return;
    // Navigation picks the occurrence, so the panel stops asserting its own.
    setActiveRow(null);
    const result =
      direction === 'previous' ? await ui.trackChanges.navigatePrevious() : await ui.trackChanges.navigateNext();
    setStatus(result.success ? `Showing the ${direction} change.` : 'No tracked change could be shown.');
  }

  async function decideChange(decision: Decision, change: TrackChangesItem) {
    if (!ui || pendingKey) return;
    setPendingKey(rowKey(change));
    setPendingDecision(decision);
    setStatus(decision === 'accept' ? 'Accepting change...' : 'Rejecting change...');

    // The async form resolves once the document operation settles, so a late
    // failure still clears the pending state and reaches the reader.
    const target = decisionTarget(change);
    const result =
      decision === 'accept' ? await ui.trackChanges.acceptAsync(target) : await ui.trackChanges.rejectAsync(target);

    setPendingKey(null);
    setPendingDecision(null);
    setStatus(decisionFailure(result) ?? (decision === 'accept' ? 'Change accepted.' : 'Change rejected.'));
  }

  return (
    <aside aria-labelledby='review-heading'>
      <h2 id='review-heading'>Review changes</h2>
      <p>
        {loadError
          ? 'Document unavailable'
          : changes.status === 'pending'
            ? 'Loading changes...'
            : `${changes.total} open ${changes.total === 1 ? 'change' : 'changes'}`}
      </p>

      <nav aria-label='Tracked change navigation'>
        <button
          disabled={!ui || changes.status === 'pending' || changes.total === 0 || pendingKey !== null}
          onClick={() => void navigate('previous')}
          type='button'
        >
          Previous
        </button>
        <button
          disabled={!ui || changes.status === 'pending' || changes.total === 0 || pendingKey !== null}
          onClick={() => void navigate('next')}
          type='button'
        >
          Next
        </button>
      </nav>

      <ul>
        {changes.items.map((change) => {
          const detail =
            change.excerpt ?? change.insertedText ?? change.deletedText ?? change.formattingDeltaSummary ?? change.type;
          const active = isActiveRow(change, changes.activeId, activeRow);
          const pending = pendingKey === rowKey(change) ? pendingDecision : null;

          return (
            <li aria-current={active ? 'true' : undefined} key={rowKey(change)}>
              <span>{`${detail}${change.author ? ` by ${change.author}` : ''}`}</span>
              <button disabled={pendingKey !== null} onClick={() => void showChange(change)} type='button'>
                {active ? 'Showing' : 'Show in document'}
              </button>
              <button disabled={pendingKey !== null} onClick={() => void decideChange('accept', change)} type='button'>
                {pending === 'accept' ? 'Accepting...' : 'Accept'}
              </button>
              <button disabled={pendingKey !== null} onClick={() => void decideChange('reject', change)} type='button'>
                {pending === 'reject' ? 'Rejecting...' : 'Reject'}
              </button>
            </li>
          );
        })}
      </ul>

      <p aria-live='polite' role='status'>
        {status}
      </p>
    </aside>
  );
}

```


Both versions use one domain handle:

* Set `ui.comments` to `false` to remove SuperDoc's comments and review sidebar without removing review data from the
  DOCX.
* Use `observe()` or `useSuperDocTrackChanges()` to keep the list and active change current.
* Run `setActive()` with `scrollTo()`, or `navigatePrevious()` and `navigateNext()`, to move between document marks.
* Run `acceptAsync()` or `rejectAsync()` with the row's `{ id, story }` and await the settled result. Keep the panel
  pending until it resolves, then report success or the failure message.

## Keep decisions synchronized [#keep-decisions-synchronized]

A decision can still fail after it is routed because the document is read-only, the change no longer exists, or the
Editor's interaction policy blocks it. Awaiting the async form is what lets the panel clear its pending state and show
that failure. The sync `accept()` and `reject()` return the routed result before the operation settles, so a panel that
waits for the row to disappear can lock forever. See [Review tracked changes](/editor/track-changes) for modes and
interaction policy.

Pass the row's `story` with its `id`. The same tracked-change id can appear in the body and in a footnote or header, and
the story is what pins the decision to the occurrence the reviewer clicked.

Accepting or rejecting changes updates the open document. It does not save the DOCX. Follow
[Load and save documents](/editor/load-and-save-documents) when the review result must persist.

## Verify the panel [#verify-the-panel]

Run the project. Move to a change on another page, then accept or reject it. The document should move to the selected
mark. A successful decision should remove one row and decrease the count.

Use [Document API tracked changes](/document-api/tracked-changes) when application code reviews known change IDs without
driving an Editor panel.

Return to the [Custom UI overview](/editor/custom-ui/overview) to choose another workflow.


---

# Build application document controls

> Add application-owned zoom and DOCX download while SuperDoc keeps the remaining built-in controls.



Zoom and download apply to the document or its view, not the current selection. Put them in your application header,
observe the Editor state that keeps them current, and leave the rest of the built-in toolbar in place.

## Try document-wide controls [#try-document-wide-controls]

1. Use **Zoom out**, **Zoom in**, and **Fit width**. The document and percentage update together.
2. Choose **Download DOCX**. The status reports when the export is ready.

> **Live example: build document-wide controls without replacing the toolbar**
>
> The application renders Zoom, the current document mode, and Download DOCX. SuperDoc renders the remaining built-in toolbar without its Zoom control. Changing zoom updates the percentage, and Download DOCX exports the current document.


The application owns these document-wide controls. SuperDoc still renders the Editor and the remaining toolbar without
its Zoom control.

## Build zoom and download controls [#build-zoom-and-download-controls]

Start from [Custom UI setup](/editor/custom-ui/controller-setup) with `/sample.docx` in your application's `public`
directory.

The examples below use manual zoom. In `superdoc@2.12.0`, automatic Fit width can shrink the document to 10% after
resizing. The demo above includes a docs-only fitting helper; the copied examples do not depend on it.

### Add the controls [#add-the-controls]

Vanilla adds mounts for the remaining built-in toolbar and the application controls. React creates the built-in toolbar
mount and renders the controls in the component below. For Vanilla, replace the contents of `<body>` in `index.html` with:

```html
<div id="toolbar"></div>
<div class="document-controls" aria-label="Document controls" role="toolbar">
  <button id="zoom-out" type="button" disabled>Zoom out</button>
  <button id="zoom-in" type="button" disabled>Zoom in</button>
  <button id="export" type="button" disabled>Download DOCX</button>
  <output id="document-status" aria-live="polite" role="status">Loading the document…</output>
</div>
<p id="document-error" role="alert"></p>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

### Connect them to the Editor [#connect-them-to-the-editor]

Replace the setup guide's Editor code:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import type { UIConfig } from 'superdoc';
import type { DocumentSlice } from 'superdoc/ui';
import 'superdoc/style.css';

const zoomOut = document.querySelector<HTMLButtonElement>('#zoom-out');
const zoomIn = document.querySelector<HTMLButtonElement>('#zoom-in');
const exportButton = document.querySelector<HTMLButtonElement>('#export');
const status = document.querySelector<HTMLOutputElement>('#document-status');
const errorMessage = document.querySelector<HTMLParagraphElement>('#document-error');

if (!zoomOut || !zoomIn || !exportButton || !status || !errorMessage) {
  throw new Error('The document controls are incomplete.');
}

let stopObservers: Array<() => void> = [];
let removeHandlers: (() => void) | null = null;
let actionMessage = '';
let exportInFlight = false;

function modeLabel(mode: DocumentSlice['mode']) {
  if (mode === 'editing') return 'Editing';
  if (mode === 'suggesting') return 'Suggesting';
  if (mode === 'viewing') return 'Viewing';
  return 'Ready';
}

const editorUi = {
  toolbar: {
    container: '#toolbar',
    excludeItems: ['zoom'],
  },
} satisfies UIConfig;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: editorUi,
  onReady: ({ superdoc: readySuperDoc }) => {
    for (const stop of stopObservers) stop();
    removeHandlers?.();
    actionMessage = '';
    exportInFlight = false;
    errorMessage.textContent = '';

    const ui = readySuperDoc.ui;

    const render = () => {
      const zoom = ui.zoom.getSnapshot();
      const currentDocument = ui.document.getSnapshot();
      zoomOut.disabled = zoom.value <= zoom.min;
      zoomIn.disabled = zoom.value >= zoom.max;
      exportButton.disabled = !currentDocument.ready || exportInFlight;
      status.value = currentDocument.ready
        ? `${modeLabel(currentDocument.mode)} · ${zoom.value}%${actionMessage ? ` · ${actionMessage}` : ''}`
        : 'Loading the document…';
    };

    const changeZoom = (delta: number) => {
      const zoom = ui.zoom.getSnapshot();
      ui.zoom.set(Math.min(zoom.max, Math.max(zoom.min, zoom.value + delta)));
    };
    const zoomOutHandler = () => changeZoom(-10);
    const zoomInHandler = () => changeZoom(10);
    const exportHandler = async () => {
      if (exportInFlight) return;

      exportInFlight = true;
      actionMessage = 'Preparing the DOCX…';
      render();
      try {
        const pendingExport = ui.document.export({ exportType: ['docx'], triggerDownload: true });
        if (!pendingExport) {
          actionMessage = 'Export is unavailable in this host.';
          return;
        }
        await pendingExport;
        actionMessage = 'DOCX downloaded.';
      } catch (error) {
        actionMessage = error instanceof Error ? error.message : 'The DOCX could not be exported.';
      } finally {
        exportInFlight = false;
        render();
      }
    };

    stopObservers = [ui.zoom.observe(render), ui.document.observe(render)];
    zoomOut.addEventListener('click', zoomOutHandler);
    zoomIn.addEventListener('click', zoomInHandler);
    exportButton.addEventListener('click', exportHandler);

    removeHandlers = () => {
      zoomOut.removeEventListener('click', zoomOutHandler);
      zoomIn.removeEventListener('click', zoomInHandler);
      exportButton.removeEventListener('click', exportHandler);
    };
  },
  onContentError: ({ error }) => {
    errorMessage.textContent = 'The document could not be read or updated.';
    console.error(error);
  },
  onException: ({ error }) => {
    errorMessage.textContent = 'The editor reported a runtime error.';
    console.error(error);
  },
});

window.addEventListener('beforeunload', () => {
  for (const stop of stopObservers) stop();
  removeHandlers?.();
  superdoc.destroy();
});

```

**React — `src/App.tsx`**

```tsx
import { useRef, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { UIConfig } from 'superdoc';
import type { DocumentSlice } from 'superdoc/ui';
import {
  SuperDocUIProvider,
  useSetSuperDoc,
  useSuperDocDocument,
  useSuperDocUI,
  useSuperDocZoom,
} from 'superdoc/ui/react';
import '@superdoc/react/style.css';

const editorUi = {
  toolbar: { excludeItems: ['zoom'] },
} satisfies UIConfig;

function modeLabel(mode: DocumentSlice['mode']) {
  if (mode === 'editing') return 'Editing';
  if (mode === 'suggesting') return 'Suggesting';
  if (mode === 'viewing') return 'Viewing';
  return 'Ready';
}

export default function App() {
  const [errorMessage, setErrorMessage] = useState('');

  return (
    <SuperDocUIProvider>
      <DocumentControls errorMessage={errorMessage} />
      <Editor onError={setErrorMessage} />
    </SuperDocUIProvider>
  );
}

function DocumentControls({ errorMessage }: { errorMessage: string }) {
  const ui = useSuperDocUI();
  const zoom = useSuperDocZoom();
  const documentState = useSuperDocDocument();
  const [actionMessage, setActionMessage] = useState('');
  const [isExporting, setIsExporting] = useState(false);
  const exportInFlight = useRef(false);

  function changeZoom(delta: number) {
    ui?.zoom.set(Math.min(zoom.max, Math.max(zoom.min, zoom.value + delta)));
  }

  async function downloadDocx() {
    if (exportInFlight.current) return;

    exportInFlight.current = true;
    setIsExporting(true);
    setActionMessage('Preparing the DOCX…');
    try {
      const pendingExport = ui?.document.export({ exportType: ['docx'], triggerDownload: true });
      if (!pendingExport) {
        setActionMessage('Export is unavailable in this host.');
        return;
      }
      await pendingExport;
      setActionMessage('DOCX downloaded.');
    } catch (error) {
      setActionMessage(error instanceof Error ? error.message : 'The DOCX could not be exported.');
    } finally {
      exportInFlight.current = false;
      setIsExporting(false);
    }
  }

  const status = documentState.ready
    ? `${modeLabel(documentState.mode)} · ${zoom.value}%${actionMessage ? ` · ${actionMessage}` : ''}`
    : 'Loading the document…';

  return (
    <>
      <div aria-label='Document controls' role='toolbar'>
        <button disabled={!ui || zoom.value <= zoom.min} onClick={() => changeZoom(-10)} type='button'>
          Zoom out
        </button>
        <button disabled={!ui || zoom.value >= zoom.max} onClick={() => changeZoom(10)} type='button'>
          Zoom in
        </button>
        <button disabled={!ui || !documentState.ready || isExporting} onClick={() => void downloadDocx()} type='button'>
          Download DOCX
        </button>
        <output aria-live='polite' role='status'>
          {status}
        </output>
      </div>
      {errorMessage ? <p role='alert'>{errorMessage}</p> : null}
    </>
  );
}

function Editor({ onError }: { onError: (message: string) => void }) {
  const setSuperDoc = useSetSuperDoc();

  return (
    <SuperDocEditor
      document='/sample.docx'
      onContentError={({ error }) => {
        onError('The document could not be read or updated.');
        console.error(error);
      }}
      onException={({ error }) => {
        onError('The editor reported a runtime error.');
        console.error(error);
      }}
      onReady={({ superdoc }) => {
        onError('');
        setSuperDoc(superdoc);
      }}
      ui={editorUi}
    />
  );
}

```


`toolbar.excludeItems` removes only Zoom. SuperDoc continues to render the other built-in toolbar controls. Vanilla also
sets `toolbar.container` because the application owns that mount. React creates one when `container` is omitted. Use
`toolbar: false` only when your application will render the complete toolbar.

`ui.zoom` reports the current percentage and supported range. `set()` switches to manual zoom. Zoom changes the view,
not the DOCX.

The document snapshot's `ready` field tells you when document actions can run, and its `mode` field reports whether
the Editor is in editing, suggesting, or viewing mode. Read them from `ui.document.getSnapshot()` or receive them from
`ui.document.observe()`, as the examples do, so application controls follow both values without reading the rendered
document DOM.

`ui.document.export()` accepts the same typed DOCX options as `superdoc.export()`. It returns `undefined` when the bound
host cannot export. The example passes `triggerDownload: true` so a successful browser export downloads the returned
DOCX.

## Verify the controls [#verify-the-controls]

Run the project. The built-in toolbar should render without Zoom. Change the zoom and download the DOCX. The
application status should follow the current percentage and document mode.

Use [Load and save documents](/editor/load-and-save-documents) to send exported bytes to your storage layer. Use
[Document modes](/editor/document-modes) to control editing, suggesting, and viewing.

Return to the [Custom UI overview](/editor/custom-ui/overview) and choose the
workflow your product needs.


---

# Migrate from v1

> Move a browser editor from SuperDoc v1 to the v2 DOCX engine.




If your v1 application mounts `SuperDoc` from the package root, waits for readiness, and exports through the same instance, most of that integration remains valid. The migration is mainly about selecting the v2 package and removing dependencies on v1 internals.

> **This guide covers local browser editing (note)**
>
> V2 collaboration rooms use a different document format and require a separate migration. Do not connect a v2 editor
> directly to an existing v1 collaboration room.


> **The React wrapper has a new package name in v2 (warning)**
>
> `@superdoc-dev/react` is the v1 wrapper. Install `@superdoc/react` for v2. The `superdoc/ui/react` subpath is a
> different surface for custom controls; it does not replace the `SuperDocEditor` wrapper component.


**Migrating with an AI coding agent?** Use this prompt:

```text
Help me migrate this project from SuperDoc v1 to v2.

First, read these sources of truth:
/md/editor/migrate-from-v1/overview.md
/migration/v1-to-v2.json

Inspect the project and report:
1. Removed imports and package subpaths
2. Any direct editor.* access, including commands, state, view, chain(), helpers, comments, presentationEditor, and on()
3. Legacy configuration and collaboration usage
4. Custom UI, extensions, and DOM selectors that require redesign
5. Synchronous Document API reads such as doc.extract(), doc.getMarkdown(), and doc.selection.current(), which the browser resolves as Promises

Do not change code yet. Classify each finding using the migration catalog,
then propose the smallest safe migration sequence and a verification plan.
```


## 1. Install the v2 package [#1-install-the-v2-package]

SuperDoc v2 is the current `latest` release. The core editor keeps the unscoped `superdoc` package name:

```bash
pnpm add superdoc
```

Keep the package name `superdoc`. Do not add `editorVersion`, `v2`, or `v2Integration` to the editor configuration. The v2 package always runs the v2 DOCX engine and has no runtime fallback to v1.

The React wrapper moved to the new npm scope:

| Integration              | V1 package                        | V2 package          |
| ------------------------ | --------------------------------- | ------------------- |
| Core browser editor      | `superdoc`                        | `superdoc`          |
| React wrapper component  | `@superdoc-dev/react`             | `@superdoc/react`   |
| React custom UI bindings | `superdoc/headless-toolbar/react` | `superdoc/ui/react` |

If your v1 application renders `SuperDocEditor`, replace the wrapper package:

```bash
pnpm remove @superdoc-dev/react
pnpm add @superdoc/react
```

`@superdoc/react` declares the compatible `superdoc` release. Install the wrapper by package name instead of trying to
match its version number to the editor version.

## 2. Keep the supported root integration [#2-keep-the-supported-root-integration]

These browser integration points remain the same:

| Integration point | V2 path                                  |
| ----------------- | ---------------------------------------- |
| Editor class      | `SuperDoc` from `superdoc`               |
| Styles            | `superdoc/style.css`                     |
| Document input    | `document` with a `File`, `Blob`, or URL |
| Ready lifecycle   | `onReady` or the `ready` event           |
| Mode changes      | `setDocumentMode()`                      |
| DOCX output       | `export()`                               |
| Cleanup           | `destroy()`                              |

A minimal v2 mount still looks familiar:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  onReady: ({ superdoc }) => {
    superdoc.setDocumentMode('editing');
  },
});
```

Call document-dependent methods only after `onReady`. V2 opens and renders the DOCX progressively, so readiness is the public boundary for starting product interaction.

## 3. Remove legacy package subpaths [#3-remove-legacy-package-subpaths]

SuperDoc v2 exposes a smaller public package surface:

| V1 import                                                               | V2 replacement                                                                       |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `superdoc/types`                                                        | Not a rename. See [Removed in v2](/editor/migrate-from-v1/removed-apis)              |
| `superdoc/headless-toolbar`                                             | `superdoc.ui`, the controller the instance owns                                      |
| `superdoc/headless-toolbar/react`                                       | Hooks and providers from `superdoc/ui/react`                                         |
| `superdoc/headless-toolbar/vue`                                         | Provider and composables from `superdoc/ui/vue`                                      |
| `superdoc/super-editor`                                                 | Use the `SuperDoc` instance and its public active-editor facade                      |
| `superdoc/converter`, `superdoc/docx-zipper`, or `superdoc/file-zipper` | Use the supported `SuperDoc` load and export workflow; there is no direct v2 subpath |

Do not replace a removed public path with an internal package. Packages such as `@superdoc/v2-host`, `@superdoc/headless`, and `@superdoc/document-api-v2-adapter` are implementation details, not customer integration surfaces.

### Migrate a custom toolbar [#migrate-a-custom-toolbar]

A v1 custom toolbar is not restored by changing only its import. Bind the application UI to the controller owned by the ready `SuperDoc` instance, then move each control's state and execution to a public command handle.

| V1 integration responsibility                | V2 path                                                                                                                                                        |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Import React headless-toolbar bindings       | Import `SuperDocUIProvider`, `useSetSuperDoc`, and hooks from `superdoc/ui/react`                                                                              |
| Publish the controller to your control tree  | Render `SuperDocUIProvider` (React) or call `provideSuperDocUI()` (Vue) in an **ancestor** of the controls; a component cannot consume what it provides itself |
| Bind controls to an editor or toolbar scope  | Capture `const setSuperDoc = useSetSuperDoc()` in the component, call it from `onReady`                                                                        |
| Read whether a control is active or disabled | Read `active`, `enabled`, `value`, and `reason` from `useSuperDocCommand(id)`                                                                                  |
| Run a toolbar action                         | Await `superdoc.ui.commands.executeAsync(id, payload)` and inspect `false` or an unsuccessful receipt                                                          |
| Replace the document in the mounted editor   | Call `superdoc.replaceFile(file)` and keep the existing controller binding                                                                                     |
| Replace the entire `SuperDoc` instance       | Bind the new instance from its `onReady` and destroy the instances your application created                                                                    |

Do not create a controller for every render, tab, or document. One `SuperDoc` instance owns one stable controller. Replacing its document resets document-scoped state while existing command hooks stay subscribed. Replacing the entire instance is different: the provider must receive the new ready instance.

Follow [Build your first custom control](/editor/custom-ui/controller-setup) for a React toolbar that reports command
outcomes. Use [Commands and state](/editor/custom-ui/commands-and-state) for the shared controller contract.

## 4. Replace direct editor internals [#4-replace-direct-editor-internals]

V1 code could reach through the editor to ProseMirror state and commands:

```ts
new SuperDoc({
  selector: '#editor',
  document: file,
  onEditorCreate: ({ editor }) => {
    const text = editor.state.doc.textContent;
    console.log(text);
  },
});
```

In v2, read and change document content through the public Document API after the editor is ready:

```ts
new SuperDoc({
  selector: '#editor',
  document: file,
  onReady: async ({ superdoc }) => {
    const doc = superdoc.activeEditor?.doc;
    if (!doc) throw new Error('The active document is unavailable.');

    const text = await doc.getText({});
    console.log(text);
  },
});
```

Do not use `editor.state`, `editor.view`, DOM text offsets, or private command objects as the document model. Use the Document API for fresh reads and mutations, and `superdoc/ui` for reactive custom UI state.

### Move UI interactions off the document runtime [#move-ui-interactions-off-the-document-runtime]

`DocumentRendererRuntime` is part of SuperDoc's rendering path. V1 integrations sometimes retrieved it with
`getDocumentRuntimeForDocument()` and called navigation methods on it. That lookup is not the V2 readiness boundary. It
can return `null` when the renderer is not available, which often surfaces as an application error such as
`DocumentRuntime is not available`.

Read the instance-owned controller from `superdoc.ui` after `onReady` instead. The controller groups state and actions by
the feature your interface is showing. It also owns the navigation needed to reveal content on a virtualized page.

#### Scroll to a tracked change [#scroll-to-a-tracked-change]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function scrollToChange(superdoc: SuperDoc, changeId: string): Promise<boolean> {
  const result = await superdoc.ui.trackChanges.scrollTo(changeId);
  return result.success;
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export async function scrollToChange(
  superdoc: SuperDoc,
  documentId: string,
  changeId: string,
): Promise<boolean> {
  const runtime = superdoc.getDocumentRuntimeForDocument(documentId);
  if (!runtime?.scrollToElement) throw new Error('DocumentRuntime is not available.');
  return Boolean(await runtime.scrollToElement(changeId));
}
```


Use the narrowest navigation method for the target you already know:

| Target you have    | V2 navigation method                                       |
| ------------------ | ---------------------------------------------------------- |
| Tracked-change ID  | `superdoc.ui.trackChanges.scrollTo(changeId)`              |
| Comment ID         | `superdoc.ui.comments.scrollTo(commentId)`                 |
| Content-control ID | `superdoc.ui.contentControls.scrollIntoView({ id })`       |
| Paragraph block ID | `superdoc.ui.viewport.scrollIntoView({ target: { ... } })` |

The first three return structured results and keep feature state, such as the active tracked change, in the same
controller. A paragraph block ID has no feature handle, so wrap it in a `TextAddress` and scroll the viewport directly:

```ts
import type { SuperDoc } from 'superdoc';
import type { TextAddress } from 'superdoc/ui';

// Take the story from `TextAddress` itself. The root `superdoc` package also
// exports a `StoryLocator`, but that is the legacy `string | Record<string,
// unknown>` alias and is not assignable to the Document API locator this
// address requires.
async function revealBlock(
  superdoc: SuperDoc,
  blockId: string,
  maxSteps: number,
  story?: TextAddress['story'],
): Promise<boolean> {
  // Carry the paragraph's story. Omitting it defaults the address to the body,
  // so a header, footer, or note paragraph never resolves however many times
  // you retry.
  const target: TextAddress = { kind: 'text', blockId, range: { start: 0, end: 0 }, ...(story ? { story } : {}) };

  // A block beyond the retained frontier of a long virtualized document needs
  // more than one pass: the host performs one bounded reveal step per call and
  // returns `success: false` while the target is still out of reach. Retry
  // against a step budget rather than treating the first result as final.
  //
  // `maxSteps` is yours to choose and to bound: a stale or unreachable ID
  // fails on every pass, so an unbounded loop never terminates. Measure it
  // against your own longest document rather than copying a number.
  for (let step = 0; step < maxSteps; step += 1) {
    const result = await superdoc.ui.viewport.scrollIntoView({ target, block: 'center' });
    if (result.success) return true;
  }
  return false;
}
```

`scrollIntoView` also accepts a `TextTarget` for a multi-segment range, or an `EntityAddress` when you would rather
address a comment or tracked change by ID than go through its feature handle. The feature-specific methods delegate to
the same one-step host call, so a deep target reached through `ui.trackChanges.scrollTo()`, `ui.comments.scrollTo()`, or
`ui.contentControls.scrollIntoView()` needs the same bounded retry. Apply the pattern above to whichever call you use,
and keep the step budget: a stale or unreachable ID returns `success: false` forever, so a loop with no ceiling never
terminates.

> **Only paragraph IDs work with this recipe (warning)**
>
> `TextAddress` is a single-block **text** range, and the host resolves an off-screen `blockId` through its paragraph
> index. A structural block such as a table, image, TOC, or content control has no entry there, so wrapping its ID this
> way resolves nothing. Reach those through the surface that owns them, such as
> `superdoc.ui.contentControls.scrollIntoView({id})`, or navigate to a paragraph inside them.


> **Root navigation is not a working replacement yet (warning)**
>
> `superdoc.scrollToElement()` and `superdoc.navigateTo()` read the renderer runtime slot directly, and nothing on the
> V2 path populates it, so both return `false` for every target in current V2 packages. Use the method for your target
> type above instead. If you hold a stable extracted ID and do not know its type, resolve the type through the Document
> API first, then choose from the table.


You do not need to import the normal controller from `superdoc/ui`. The `superdoc.ui` getter creates it once, and
`superdoc.destroy()` owns its cleanup. Import `createSuperDocUI` from `superdoc/ui` only when you need a separately owned
controller with its own lifecycle. Continue with [Custom UI controller setup](/editor/custom-ui/controller-setup) for
subscriptions and cleanup, or the [tracked-changes UI guide](/editor/custom-ui/tracked-changes) for review navigation.

## 5. Map common editor and ProseMirror internals [#5-map-common-editor-and-prosemirror-internals]

These are the mappings most applications need: reading text, resolving a selection, inserting at it, and exporting. Each example includes its imports, inputs, async boundary, and returned value. V2 is selected by default;
switching an example switches every example on this page.

For everything else, work from [Removed in v2](/editor/migrate-from-v1/removed-apis). Each entry names the v1
symbol, what you will observe when it breaks, and the v2 replacement if one exists. Entries link to a canonical API
page where one covers the replacement.

### Document API [#document-api]

#### getText [#gettext]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function readText(superdoc: SuperDoc): Promise<string> {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');
  return doc.getText({});
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export function readText(superdoc: SuperDoc): string {
  return superdoc.activeEditor!.state.doc.textContent;
}
```


#### selection.current [#selectioncurrent]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function currentSelection(superdoc: SuperDoc) {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');
  return doc.selection.current({ includeText: true });
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export function currentSelection(superdoc: SuperDoc) {
  return superdoc.activeEditor!.state.selection;
}
```


#### selection.current().selectionTarget [#selectioncurrentselectiontarget]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function selectionTarget(superdoc: SuperDoc) {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');
  const selection = await doc.selection.current({});
  return selection.selectionTarget;
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export function selectionRange(superdoc: SuperDoc) {
  const { from, to } = superdoc.activeEditor!.state.selection;
  return { from, to };
}
```


#### insert [#insert]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function insertText(superdoc: SuperDoc, text: string) {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');
  // A targetless insert appends at the end of the document. V1 inserted at
  // the caret, so a missing target is a lost selection, not a default.
  // Failing loudly beats silently putting the text somewhere else.
  const selection = await doc.selection.current({});
  if (!selection.selectionTarget) {
    throw new Error('No selection target. Capture one while the editor has focus, or pass an explicit target.');
  }
  const result = (await doc.insert({ value: text, target: selection.selectionTarget })) as
    | { success: boolean }
    | { receipt: { success: boolean } };
  const receipt = 'receipt' in result ? result.receipt : result;
  if (!receipt.success) throw new Error('Text insertion failed.');
  return result;
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export function insertText(superdoc: SuperDoc, text: string) {
  const editor = superdoc.activeEditor!;
  return editor.view.dispatch(editor.state.tr.insertText(text));
}
```


Pass a target unless you mean to append. `doc.insert({ value })` with no `target` or `ref` routes to the end of the
document, so a direct port of `tr.insertText(text)` appends instead of inserting at the caret. In a browser this
example throws rather than falling back, because losing the selection means the text would land somewhere the user did
not choose. Headless callers with no selection can omit the target deliberately and take the append.

The Editor returns a mutation receipt directly, while the headless SDK returns an operation envelope containing the
receipt. Normalize the two shapes before checking `success`, as shown above. Headless callers can also use the envelope's
`target`, `resolvedRange`, and `context` for details about the applied mutation. Verify persisted output by saving and
reopening the DOCX when insertion is part of an automated workflow.

### Export [#export]

#### getMarkdown [#getmarkdown]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function markdown(superdoc: SuperDoc): Promise<string> {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');
  return doc.getMarkdown({});
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export function markdown(superdoc: SuperDoc): string {
  return superdoc.activeEditor!.getMarkdown();
}
```


#### export [#export-1]

**V2**

```ts
import type { SuperDoc } from 'superdoc';

export async function exportDocx(superdoc: SuperDoc) {
  return superdoc.export({ exportType: ['docx'], triggerDownload: false });
}
```

**V1**

```ts
import type { SuperDoc } from 'superdoc';

export async function exportDocx(superdoc: SuperDoc) {
  return superdoc.export({ exportType: ['docx'], triggerDownload: false });
}
```


## 6. Migrate changed integration contracts [#6-migrate-changed-integration-contracts]

The following changes are public V2 contracts rather than replacements for ProseMirror internals. Treat the browser
Document API as asynchronous, keep document and UI namespaces explicit, and preserve every returned cleanup function.

### Content-control clicks [#content-control-clicks]

V2 keeps the `onContentControlClick` configuration callback. The equivalent instance event is
`content-control:click`:

```ts
const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  onContentControlClick: ({ target, source }) => {
    console.log(target.id, target.scope, source);
  },
});

const handleClick = ({ target, source }) => {
  console.log(target.id, target.controlType, source);
};

superdoc.on('content-control:click', handleClick);
```

Each user click emits once for the innermost clicked content control. `target` contains `id`, `controlType`,
`scope: 'inline' | 'block'`, and the optional `tag` and `alias`; `source` is `'pointer'`. The listener remains active
after document replacement and collaboration updates. Programmatic `focus()` and selection changes do not emit this
event. Use `superdoc.ui.contentControls` — for example `observe()` and `activeIds` — when the integration needs
focus or selection state instead. See [Custom content controls](/editor/custom-ui/content-controls).

### Collaboration [#collaboration]

V1 applications supplied an external Y.Doc and provider through `modules.collaboration`. V2 instead takes a supported provider target and owns the provider lifecycle. Do not port the external pair directly.

The [preview API](/editor/collaboration/connect-two-editors#configure-your-application) names that target `document.collaboration`, typed as `DocumentCollaborationConfig`. It also accepts `collaboration` in `upgradeToCollaboration()`. The older `v2Collaboration` field and `V2CollaborationConfig` type remain supported for existing integrations; new code should use the unversioned names. When both fields are supplied, `collaboration` wins as a whole—settings are not merged. On a document, `collaboration: null` explicitly opens locally.

[Connect two editors](/editor/collaboration/connect-two-editors) explains create/join, readiness, connection failures, and cleanup. [Run a server](/editor/collaboration/run-a-server) covers provider targets and server responsibilities. Use [Upgrade a document](/editor/collaboration/upgrade-a-document) when a local Editor should create a new room without remounting.

#### Split-origin worker assets [#split-origin-worker-assets]

If your JavaScript bundle is served from a different origin than the application, copy the three emitted v2 worker
assets to the application's origin and pass their URLs explicitly:

```ts
new SuperDoc({
  selector: '#editor',
  document,
  workerUrls: {
    document: '/superdoc-workers/document.js',
    collaboration: '/superdoc-workers/collaboration.js',
    reviewIndex: '/superdoc-workers/review-index.js',
  },
});
```

Each URL must be same-origin with the page and serve a module worker. Omit this option when SuperDoc and the
application share an origin; the bundled worker URLs remain the default.

## 7. Verify one DOCX round trip [#7-verify-one-docx-round-trip]

Before migrating advanced UI or automation, verify the smallest complete path:

1. Open a representative DOCX in v2.
2. Wait for `onReady`.
3. Make one direct or tracked edit.
4. Export the document with `SuperDoc.export()`.
5. Reopen the result in Microsoft Word or another DOCX reader.
6. Confirm the edited content, formatting, comments, and tracked changes still match the intended document state.

Keep v1 and v2 on separate branches or deployments while comparing the same input documents. A package upgrade should remain easy to reverse until the documents that matter to your product complete this round trip.

Once that round trip holds, migrate whatever else your application uses, working from [Removed in
v2](/editor/migrate-from-v1/removed-apis) and the canonical API pages it links to.

Next, follow the [Editor quickstart](/editor/quickstart) for a complete v2 mount, or learn the [Document API mental model](/document-api/mental-model) before migrating programmatic edits.


---

# Removed in v2

> Every v1 import and editor internal that no longer works in SuperDoc v2, and what replaces it.





Upgrading breaks three things, and they surface at different times. Removed subpaths always fail module resolution. Removed root exports fail the build under ESM and TypeScript, but a CommonJS `require` binds them to `undefined` and fails later at the call site. Configuration and editor internals that v2 no longer honors fail only once the editor is running, often without naming SuperDoc at all.

Work through them in that order. The import failures are the loudest, and fixing them tells you where the rest of the work is.

This page describes `superdoc@2.16.0` compared against `superdoc@1.45.0`. A machine-readable version is available at [`/migration/v1-to-v2.json`](/migration/v1-to-v2.json).

## How to read the Migration column [#how-to-read-the-migration-column]

* **Mechanical** — A direct substitution with equivalent behavior. Safe to apply mechanically, and required to be backed by a compiled fixture before it carries this label.
* **Redesign** — A replacement exists, but the semantics differ. Read the replacement and re-verify the behavior; do not apply it as a find-and-replace.
* **No equivalent** — No v2 equivalent. The capability must be removed or rebuilt outside SuperDoc.

Nothing here is currently classified as Mechanical, so this page is an inventory and a decision aid, not a codemod. Do not apply any of it as an automated find-and-replace.

## Search the reference [#search-the-reference]

> **Searchable migration reference.**
>
> The interactive explorer filters the same entries listed in the tables below,
> by symbol name, by when the failure surfaces, and by how much work the migration is.
> A machine-readable version of every entry is published at `/migration/v1-to-v2.json`.


Every entry is also listed in full below, grouped by when the failure surfaces. The tables are the canonical form: they work without JavaScript and are what `llms.txt` and search engines read.

## Your application no longer imports [#your-application-no-longer-imports]

### Removed package subpaths [#removed-package-subpaths]

v1 published 10 code subpaths. v2 publishes 5: `superdoc/collaboration-upgrade-engine`, `superdoc/collaboration-worker`, `superdoc/ui`, `superdoc/ui/react`, `superdoc/ui/vue`.

| v1                                | v2                      | Migration     | Notes                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------- | ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `superdoc/types`                  | `superdoc`              | Redesign      | Not a path rename. v1 re-exported 116 names here, almost all of them ProseMirror and schema types, and none of them exist on the v2 root. Integration types such as `Config`, `DocumentMode`, `User`, and `DocumentApi` are exported from `superdoc`; types describing ProseMirror nodes, marks, commands, and transactions have no v2 equivalent because the model they described is gone. [Read more](/document-api/mental-model) |
| `superdoc/super-editor`           | `superdoc.activeEditor` | Redesign      | v2 has no importable editor class. Reach the active document through the `SuperDoc` instance and its Document API facade. [Read more](/document-api/mental-model)                                                                                                                                                                                                                                                                   |
| `superdoc/converter`              | *None*                  | No equivalent | v2 owns DOCX parsing and serialization internally. Load documents through `document` and produce output through `export()`. [Read more](/editor/load-and-save-documents)                                                                                                                                                                                                                                                            |
| `superdoc/docx-zipper`            | *None*                  | No equivalent | No public archive surface in v2. Use the supported load and export workflow.                                                                                                                                                                                                                                                                                                                                                        |
| `superdoc/file-zipper`            | *None*                  | No equivalent | No public archive surface in v2. Use the supported load and export workflow.                                                                                                                                                                                                                                                                                                                                                        |
| `superdoc/headless-toolbar`       | `superdoc.ui`           | Redesign      | `superdoc.ui` is a getter that lazily creates and owns the controller. It returns `BorrowedSuperDocUI`, which omits `destroy()` because `superdoc.destroy()` owns teardown. Call `createSuperDocUI({ superdoc })` from `superdoc/ui` only when you want an independently owned controller to dispose yourself. [Read more](/editor/custom-ui/overview)                                                                              |
| `superdoc/headless-toolbar/react` | `superdoc/ui/react`     | Redesign      | Hooks and providers moved and now bind to the instance-owned controller. [Read more](/editor/custom-ui/overview)                                                                                                                                                                                                                                                                                                                    |
| `superdoc/headless-toolbar/vue`   | `superdoc/ui/vue`       | Redesign      | Composables moved and now bind to the instance-owned controller. Provide it once with `provideSuperDocUI()`, then read slices with the `useSuperDoc*` composables. [Read more](/editor/custom-ui/overview)                                                                                                                                                                                                                          |

A removed subpath fails module resolution in every module system, because it is absent from the package's exports map. Do not work around it by importing an internal package: names such as `@superdoc/v2-host` and `@superdoc/document-api-v2-adapter` are implementation details with no compatibility guarantee.

### Removed root exports [#removed-root-exports]

v1 exported 41 runtime values from the package root. v2 exports 10: `BlankDOCX`, `DOCX`, `HTML`, `PDF`, `SuperDoc`, `buildTheme`, `compareVersions`, `createTheme`, `defineSuperDocExtension`, `getFileObject`.

Everything below was removed. `defineSuperDocExtension` is the one value v2 adds.

#### Editor internals [#editor-internals]

| v1                          | v2                                       | Migration     | Notes                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | ---------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Editor`                    | `superdoc.activeEditor`                  | Redesign      | v2 exposes no editor constructor. Mount through `SuperDoc` and read the active document via its Document API facade. [Read more](/document-api/mental-model)                                                                                                                                                                    |
| `PresentationEditor`        | *None*                                   | No equivalent | v2 owns rendering internally. There is no public presentation-editor surface.                                                                                                                                                                                                                                                   |
| `SuperEditor`               | `SuperDoc`                               | Redesign      | The mounting capability survives, the component does not. v1 rendered a Vue component taking `fileSource`, `documentId`, `state`, and `options` props; v2 mounts imperatively with `new SuperDoc({ selector, document })`. A React or Vue wrapper is now application code around that instance. [Read more](/editor/quickstart) |
| `SuperInput`                | *None*                                   | No equivalent | v2 ships no importable single-line input component, and no v2 surface is a drop-in equivalent. Build the control in your application.                                                                                                                                                                                           |
| `superEditorHelpers`        | `superdoc.activeEditor.doc`              | Redesign      | Helper bags are replaced by explicit Document API operations. [Read more](/document-api/mental-model)                                                                                                                                                                                                                           |
| `trackChangesHelpers`       | `superdoc.activeEditor.doc.trackChanges` | Redesign      | Helper bag replaced by explicit Document API operations for listing, navigating, and deciding tracked changes. [Read more](/document-api/tracked-changes)                                                                                                                                                                       |
| `fieldAnnotationHelpers`    | `superdoc.activeEditor.doc`              | Redesign      | Field and annotation work moves to Document API operations.                                                                                                                                                                                                                                                                     |
| `AnnotatorHelpers`          | `superdoc.activeEditor.doc`              | Redesign      | Helper bag replaced by explicit Document API operations. Field and annotation work goes through `doc`, not a helper namespace.                                                                                                                                                                                                  |
| `SectionHelpers`            | `superdoc.activeEditor.doc.sections`     | Redesign      | Verify coverage before migrating: linked-section workflows may not have full v2 equivalents.                                                                                                                                                                                                                                    |
| `getAllowedImageDimensions` | *None*                                   | No equivalent | No public sizing helper in v2. Compute the constraint in your application, or let the engine apply its own bounds on insert.                                                                                                                                                                                                    |
| `CommentsPluginKey`         | `superdoc.activeEditor.doc.comments`     | Redesign      | v2 exposes no ProseMirror plugin keys. Use the Document API comments operations. [Read more](/document-api/comments)                                                                                                                                                                                                            |
| `TrackChangesBasePluginKey` | `superdoc.activeEditor.doc.trackChanges` | Redesign      | v2 exposes no ProseMirror plugin keys. [Read more](/document-api/tracked-changes)                                                                                                                                                                                                                                               |

#### Converter and archives [#converter-and-archives]

| v1               | v2     | Migration     | Notes                                                                                                                                                     |
| ---------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SuperConverter` | *None* | No equivalent | DOCX conversion is internal to the v2 engine. Load through `document` and produce output through `export()`. [Read more](/editor/load-and-save-documents) |
| `DocxZipper`     | *None* | No equivalent | No public archive surface in v2.                                                                                                                          |
| `createZip`      | *None* | No equivalent | No public archive surface in v2.                                                                                                                          |

#### Custom UI [#custom-ui]

| v1                      | v2                                      | Migration | Notes                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SuperToolbar`          | `config.toolbar`                        | Redesign  | For the built-in toolbar, pass a container through `toolbar` in the config. For a custom toolbar, drive `superdoc.ui`. [Read more](/editor/built-in-ui/configure-the-toolbar)                                                                                                                                                                                                                      |
| `Toolbar`               | `config.toolbar`                        | Redesign  | The built-in toolbar is configured, not imported and rendered by the consumer. [Read more](/editor/built-in-ui/configure-the-toolbar)                                                                                                                                                                                                                                                              |
| `ContextMenu`           | `superdoc.ui.viewport.contextAt`        | Redesign  | The component is gone, not the workflow. Add actions to the built-in menu with `ui.contextMenu.sections`. For a fully application-owned menu, set `ui: { contextMenu: false }`, listen on the Editor host, and resolve entities and selection with `superdoc.ui.viewport.contextAt({ x, y })`. This does not restore arbitrary ProseMirror positions. [Read more](/editor/custom-ui/context-menus) |
| `SlashMenu`             | `config.ui.contextMenu.sections`        | Redesign  | The v2 built-in surface combines right-click and slash actions under `ui.contextMenu`. Add application sections with `sections`; use the application-owned context-menu path when your product replaces the complete surface. [Read more](/editor/custom-ui/context-menus)                                                                                                                         |
| `AIWriter`              | `ui.toolbar.customItems + Document API` | Redesign  | Add an application-owned toolbar action with `ui.toolbar.customItems`. Send the model request from your application, then apply the result with `doc.insert()` or `doc.replace()`.                                                                                                                                                                                                                 |
| `getMarksFromSelection` | `superdoc.ui`                           | Redesign  | Active formatting is published as reactive controller state rather than read from a selection. [Read more](/editor/custom-ui/overview)                                                                                                                                                                                                                                                             |
| `getActiveFormatting`   | `superdoc.ui`                           | Redesign  | Active formatting is published as reactive controller state rather than read from a selection. [Read more](/editor/custom-ui/overview)                                                                                                                                                                                                                                                             |

#### Extensions [#extensions]

| v1                       | v2                        | Migration     | Notes                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Extensions`             | `defineSuperDocExtension` | Redesign      | v2 extensions receive commands, anchors, and decorations. They do not receive ProseMirror state, custom schema, or mutable DOM, so extensions that defined custom nodes or marks may have no v2 equivalent. [Read more](/editor/custom-ui/review-highlights) |
| `defineNode`             | *None*                    | No equivalent | v2 has no custom-schema surface. Custom document nodes cannot be reproduced.                                                                                                                                                                                 |
| `defineMark`             | *None*                    | No equivalent | v2 has no custom-schema surface. Custom marks cannot be reproduced.                                                                                                                                                                                          |
| `getStarterExtensions`   | *None*                    | No equivalent | v2 loads its own document capabilities. There is no consumer-assembled extension list.                                                                                                                                                                       |
| `getRichTextExtensions`  | *None*                    | No equivalent | v2 loads its own document capabilities. There is no consumer-assembled extension list.                                                                                                                                                                       |
| `isNodeType`             | *None*                    | No equivalent | ProseMirror node predicates have no v2 equivalent. Query structure through the Document API. [Read more](/document-api/query-content)                                                                                                                        |
| `assertNodeType`         | *None*                    | No equivalent | ProseMirror node predicates have no v2 equivalent. Query structure through the Document API. [Read more](/document-api/query-content)                                                                                                                        |
| `isMarkType`             | *None*                    | No equivalent | ProseMirror mark predicates have no v2 equivalent.                                                                                                                                                                                                           |
| `getSchemaIntrospection` | *None*                    | No equivalent | v2 exposes no ProseMirror schema to introspect.                                                                                                                                                                                                              |
| `registeredHandlers`     | *None*                    | No equivalent | Marked internal in v1 and removed in v2.                                                                                                                                                                                                                     |

A missing named export is only reliably caught at build time under ESM and TypeScript. In CommonJS, `const { Editor } = require('superdoc')` binds `undefined` and fails later wherever the value is used, so a CommonJS integration can appear to upgrade cleanly and then break at the call site.

### Names dropped from subpaths that still exist [#names-dropped-from-subpaths-that-still-exist]

A subpath surviving is not the same as its exports surviving. These paths still resolve, so only the named import fails.

| v1                         | v2            | Migration | What you see                                                                                                                                                          | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `superdoc/ui type exports` | `superdoc/ui` | Redesign  | The import path still resolves, so only the named type fails. TypeScript reports the missing name; a plain JavaScript build sees nothing because these are type-only. | `ContextMenuContribution`, `ContextMenuWhenInput`, `DocumentExportInput`, `DynamicCommandHandle`, `PublicToolbarItemId`, `SelectionAnchorRectOptions`, `TextSegment`, `ToolbarCommandHandleState`, `UIToolbarCommandState`, `ViewportContextAtInput`, `ViewportEntityAtInput`, `ViewportPositionAtInput`, `ViewportPositionHit`, `ZoomMode`, `ZoomViewportMetrics`. v2 rebuilt `superdoc/ui` as a native controller rather than re-exporting v1, so these 15 type names did not carry over. Use the controller types v2 publishes from the same path. [Read more](/editor/custom-ui/overview) |

## Your application imports successfully, then fails when it runs [#your-application-imports-successfully-then-fails-when-it-runs]

These compile. Some of them typecheck against the v2 configuration. They fail, or do nothing, once the editor is running.

| v1                                                                                     | v2                                                           | Migration     | What you see                                                                                                                                                                                                                 | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `editor.commands`                                                                      | `superdoc.activeEditor.doc`                                  | Redesign      | A null-property error at the point of use. The message names the command, not SuperDoc, so it does not read as a migration failure.                                                                                          | The v2 facade exposes `commands` as null rather than removing it. Optional chaining converts the throw into a silent no-op, which is harder to notice. [Read more](/document-api/mental-model)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `editor.state`                                                                         | `superdoc.activeEditor.doc`                                  | Redesign      | A null-property error, or `undefined` when accessed with optional chaining.                                                                                                                                                  | There is no ProseMirror document model in v2. Positions expressed as numeric offsets have no equivalent; use addresses and targets. [Read more](/document-api/query-content)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `editor.view`                                                                          | *None*                                                       | No equivalent | A null-property error, or `undefined` when accessed with optional chaining.                                                                                                                                                  | v2 renders through its own engine and exposes no editor view or mutable DOM.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `superdoc.getDocumentRuntimeForDocument(documentId)`                                   | `superdoc.ui`                                                | Redesign      | The lookup returns `null`, and application code that treats the renderer as the ready UI surface throws an error such as `DocumentRuntime is not available`.                                                                 | V2 custom UI does not need to retrieve the renderer runtime. Read the instance-owned `superdoc.ui` controller after `onReady`; it publishes reactive feature state and routes UI actions without exposing the renderer object. `superdoc.ui` is a getter, not an import. The instance creates it once and owns its cleanup. [Read more](/editor/migrate-from-v1/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `documentRuntime.scrollToElement(elementId)`                                           | `superdoc.ui.*.scrollTo`                                     | Redesign      | The preceding runtime lookup returns `null`, so navigation throws or is skipped even though the document is mounted.                                                                                                         | Route known entities through their feature handle: `ui.trackChanges.scrollTo(changeId)`, `ui.comments.scrollTo(commentId)`, or `ui.contentControls.scrollIntoView({ id })`. For a paragraph block id, wrap it in a `TextAddress` and call `ui.viewport.scrollIntoView({ target })`, carrying the paragraph `story` when it is not in the body: an omitted story defaults to body and the paragraph never resolves. That form is a single-block text range resolved through the paragraph index, so a table, image, or content-control id needs the surface that owns it instead. Every one of these reveals one bounded step per call, so retry while `success` is false against a fixed step budget: a stale or unreachable id fails forever, and an unbounded loop never terminates. Do not substitute `superdoc.scrollToElement()` or `superdoc.navigateTo()`: both read the renderer runtime slot that nothing on the V2 path populates, so they return `false` for every target in current V2 packages. [Read more](/editor/migrate-from-v1/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `editor.view.dispatch(tr.setSelection(...))`                                           | `superdoc.ui.selection.apply`                                | Redesign      | A null-property error on `view`, or `undefined` under optional chaining.                                                                                                                                                     | Setting the selection programmatically is supported. Pass a `SelectionTarget` to `selection.apply()` rather than dispatching a transaction. Read it from `selection.current().selectionTarget` or a query result; there is no ProseMirror position to hand it. [Read more](/editor/custom-ui/selection-reference)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `editor.view.posAtCoords`                                                              | `superdoc.ui.viewport.entityAt`                              | Redesign      | A null-property error on `view`, or `undefined` under optional chaining.                                                                                                                                                     | Partial. `viewport.entityAt({ x, y })` resolves the public entities painted under a point (tracked changes, comments, content controls, and citations), innermost first, and returns `[]` over plain text. That covers hit-testing, which is what most `posAtCoords` callers wanted, but v2 ships no general point-to-document-position resolver, so a caller that needs an arbitrary position under the cursor has no equivalent. The legacy positional form `entityAt(x, y)` fails closed and returns `null`. [Read more](/editor/custom-ui/selection-reference)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `editor.view.coordsAtPos`                                                              | `superdoc.ui.viewport.getRect`                               | Redesign      | A null-property error on `view`, or `undefined` under optional chaining.                                                                                                                                                     | The opposite direction from `entityAt`, and a different surface. `viewport.getRect({ target })` resolves painted geometry for a public target and returns `{ found, rects, rect, reason }`. It is keyed on a target, not a numeric position, so obtain one from `selection.capture()` or a query result first. [Read more](/editor/custom-ui/selection-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `manual tracked-change traversal through editor.state`                                 | `superdoc.ui.trackChanges.navigateNext`                      | Redesign      | A null-property error on `state`, or `undefined` under optional chaining.                                                                                                                                                    | Review navigation is supported. `trackChanges.navigateNext()` moves through changes and `trackChanges.list()` reads the catalog. The catalog resolves asynchronously, so observe the slice until `status` is `ready` before consuming `items`. [Read more](/editor/custom-ui/tracked-changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `editorExtensions`                                                                     | `extensions`                                                 | Redesign      | The config typechecks and the editor mounts, but the extensions never run. SuperDoc logs a console warning naming the field.                                                                                                 | A legacy ProseMirror concept that v2 ignores. Rebuild against `extensions` with `defineSuperDocExtension`; extensions defining custom nodes or marks may have no equivalent. [Read more](/editor/custom-ui/review-highlights)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `modules.collaboration`                                                                | `document.collaboration`                                     | Redesign      | The config typechecks, then SuperDoc refuses to attach the provider and reports a terminal compatibility failure.                                                                                                            | The preview API uses document.collaboration; released integrations may use the supported v2Collaboration alias. SuperDoc owns the provider and Y.Doc. V2 rooms use a different format and must not be pointed at an existing v1 room. [Read more](/editor/migrate-from-v1/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `editor.commands.replaceWithFieldAnnotation (citation)`                                | `doc.citations.insert`                                       | Redesign      | A null-property error on `commands`, or a silent no-op under optional chaining.                                                                                                                                              | `editor.commands.replaceWithFieldAnnotation`. One v1 node type did two jobs and v2 splits them, so decide which this annotation was before porting it. This row is the citation branch: a marker backed by a source record is `citations.sources.insert()` followed by `citations.insert({ at, sourceIds })`, where `sourceIds` carries the canonical `sourceId` from the receipt rather than the source tag. The inserted field has a visible cached result such as `[Parity Handbook]`, and changing `sourceIds` with `citations.update` recomputes it. Not a rename, and not an atomic replacement: `citations.insert` accepts only a collapsed target. To replace selected text, derive its start as the insertion caret, delete the selected range, and only then pass the resulting collapsed caret to `citations.insert`. The returned `CitationAddress.anchor` spans the complete visible result in flattened paragraph offsets, while `CitationAddress.story` identifies the body, header/footer, note, or textbox containing it. If the annotation was application-owned data rather than a citation, use the `metadata.attach` row instead. [Read more](/document-api/reference/citations/insert)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `editor.commands.replaceWithFieldAnnotation (application annotation)`                  | `doc.metadata.attach`                                        | Redesign      | A null-property error on `commands`, or a silent no-op under optional chaining.                                                                                                                                              | `editor.commands.replaceWithFieldAnnotation`. The other half of the same v1 call. An annotation carrying application-owned data anchored to a range is `metadata.attach({ id, namespace, target, payload })`, and the entries it creates are not v1 field annotations: the ids, the payloads, and the anchoring model all differ, so treat this as remodelling rather than a rename. Read them back with `metadata.list({})` and `metadata.get({ id })`. If the annotation was a citation with a source record, use the `citations.insert` row instead. [Read more](/document-api/reference/metadata/attach)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `editor.state.doc.descendants (application review marks)`                              | `doc.metadata + ctx.visuals.highlight`                       | Redesign      | A null-property error on `state`, or `undefined` under optional chaining.                                                                                                                                                    | `editor.state.doc.descendants`. Split the old mark into two responsibilities. Store caller-owned identity and JSON payload with anchored metadata, resolve its current target with `metadata.resolve({ id })`, and paint that target through an extension visual. Metadata persists but renders nothing; visuals render but never enter the DOCX. [Read more](/editor/custom-ui/review-highlights)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `editor.state.doc.descendants (citation nodes)`                                        | `doc.citations.list`                                         | Redesign      | A null-property error on `state`, or `undefined` under optional chaining.                                                                                                                                                    | Reading citations no longer means walking a node tree. `citations.list()` returns the rows with their addresses and `sourceIds`. Item order can drive application-owned numbering, but that produces local UI labels only: it does not change the citation field result stored in the DOCX. The call is synchronous in some hosts and asynchronous in others, so shared browser and headless code should normalize with `await Promise.resolve(doc.citations.list())`. [Read more](/document-api/reference/citations/list)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `editor.helpers.fieldAnnotations.getAll()`                                             | `doc.metadata.list`                                          | Redesign      | A null-property error on `helpers`, or `undefined` under optional chaining.                                                                                                                                                  | A shape change, not a rename. `getAll()` returned v1 field annotations; `metadata.list({})` returns anchored-metadata entries whose ids, payloads, and anchoring model all differ. `metadata.list` is the discovery call and `metadata.get({ id })` reads one payload, so pair them when you need the collection. `get` returns null for an entry that disappeared between the two calls. Treat legacy field annotations as something to remodel rather than something this call returns. [Read more](/document-api/reference/metadata/list)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `tr.setNodeMarkup(pos, undefined, { resolvedText })`                                   | `doc.citations.insert + ctx.visuals.inlineBox`               | Redesign      | A null-property error reaching the transaction.                                                                                                                                                                              | Insert and update citations through `doc.citations`; v2 writes and recomputes the visible cached field result from the source tags. For application-owned presentation, convert the returned address to `{ kind: "text", blockId: address.anchor.start.blockId, range: { start: address.anchor.start.offset, end: address.anchor.end.offset }, story: address.story }`. Create a visual handle with `const citationPill = ctx.visuals.inlineBox("citations", { layout: { paddingInline: 5, paddingBlock: 2, borderWidth: 1 }, appearance: { borderColor: "#8aa8d8", borderRadius: 8 } })`, then pass the target to `citationPill.replace([target])`. The offsets already span the complete citation result, and carrying `story` ensures a citation outside the body resolves and paints in its owning header, footer, note, or textbox. Local typing rebases the target. Remote edits fail closed until the extension re-queries. Presentation is render-only and never changes the DOCX. [Read more](/document-api/reference/citations/insert)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `.superdoc-text-run[data-pm-start] (citation pill styling)`                            | `ctx.visuals.inlineBox`                                      | Redesign      | Nothing breaks, which is the problem. The painter still stamps `data-pm-start` on runs, so the selector keeps matching and the code keeps mutating renderer-owned DOM.                                                       | This one does not fail on upgrade. `layout-engine/dom-contract` stamps `data-pm-start` and `data-pm-end` alongside the editor-neutral attributes specifically so v1 consumers keep working, and `.superdoc-text-run` is still the painted class. What you lose is the guarantee: the DOM shape is renderer-owned and carries no stability contract, so this is worth migrating before a paint change breaks it silently rather than after. Replace a padded pill with `ctx.visuals.inlineBox(id, options)`. Its integer-pixel padding, gaps, and border participate in wrapping and pagination; `className` remains paint-only. A `CitationAddress` is not itself a visual target, but converting one is mechanical: `{ kind: "text", blockId: citation.address.anchor.start.blockId, range: { start: citation.address.anchor.start.offset, end: citation.address.anchor.end.offset }, story: citation.address.story }`. Carry `CitationAddress.story` so repeated block ids resolve in the owning body, header/footer, note, or textbox. Wrapped ranges clone box edges on each line. Overlaps, RTL targets, header/footer slot locators, and tracked-coordinate targets fail closed. Local typing, undo, and redo rebase the anchor; remote edits may briefly remove the pill until the extension re-queries. Deleting the whole range drops the box. The presentation is render-only, adds repaint and measurement cost when targets change, and never reaches the DOCX.                                                                                                                                                                     |
| `superdoc.on('fieldAnnotationClicked')`                                                | `superdoc.ui.viewport.entityAt`                              | Redesign      | The subscription is accepted and the handler never fires.                                                                                                                                                                    | v2 emits no generic field-annotation click event, and the replacement depends on what the annotation became. For citations, register a listener on `superdoc.ui.viewport.getHost()`, call `viewport.entityAt({ x, y })`, and select the `{ type: "citation", id }` hit; that `id` matches a `doc.citations.list().items` row. For anchored metadata, read the record id from the content-control hit's `tag` and compare the hit control's `selectionTarget` with `doc.metadata.resolve({ id: tag }).target`. That comparison narrows the risk but does not confirm the hit: content-control hits carry no story, both lookups resolve against the body, and painted ids are unique only within the main document part, so a header, footer, note, or textbox control reusing a body anchor's id and tag passes every check. Treat a match as unverified for externally authored files. Remove the listener when the custom UI unmounts. Decide the document model before choosing the interaction path. [Read more](/editor/custom-ui/selection-reference)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `editor.state.selection`                                                               | `superdoc.ui.selection.current`                              | Redesign      | A null-property error on `state`, or `undefined` under optional chaining.                                                                                                                                                    | A v1 `Selection` was one live object used for both reading and preserving, and v2 splits those. To read the current selection use `selection.current()` or the observed snapshot; both describe a collapsed caret. To preserve a selection across something that moves focus, use `capture()` and then `restore()`. Do not reach for `capture()` as the general read: it returns null whenever the selection is empty, which includes a collapsed caret, so caret-dependent code migrated onto it loses the selection it was trying to keep. Either way the payload is document addresses rather than numeric positions. [Read more](/editor/custom-ui/selection-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `document.getSelection().getRangeAt(0).getBoundingClientRect()`                        | `superdoc.ui.selection.getAnchorRect`                        | Redesign      | The browser selection reflects rendered DOM rather than document state, so the rectangle is wrong or the call throws on an empty range.                                                                                      | `getAnchorRect()` resolves one rectangle from the document selection against the painted layout, and accepts `'start'`, `'end'`, or `'center'`. v1's `'union'` placement has no v2 value: use `selection.getRects()` when a bubble needs the full multi-line union.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `document.querySelector('[data-comment-id="..."]')`                                    | `superdoc.ui.viewport.getRect`                               | Redesign      | Depends on the sidebar, which is the trap. With the built-in comments UI enabled the selector matches a sidebar card and positions against the wrong element; with it disabled the same selector matches nothing.            | The painter stamps no singular `data-comment-id` on document content, but `FloatingComments.vue` binds one on each sidebar placeholder, so an integration running the built-in comments UI gets a match that is a panel card rather than the painted anchor. Code that scrolls or positions from it silently targets the sidebar. Turn the sidebar off and the same selector returns null, so the failure changes shape with configuration rather than being absent. There is a second near miss: the painter stamps `data-comment-ids`, plural and comma-separated, on `.superdoc-comment-highlight`, and retargeting the selector there puts you back on renderer-owned DOM with no stability contract. Read the comment through `ui.comments.getById()` and resolve its target with `viewport.getRect({ target })` instead. Treat a `null` from `getById()` as "not loaded yet" rather than "no such comment": it checks the loaded snapshot, then falls back to the Document API, and returns `null` when that fallback is a pending promise, which is the normal browser case. It does not prime the read either, unlike `contentControls.getById()`, and `comments.list()` returns `[]` on the same path. Gate on the observed comments slice, and gate on `listStatus` rather than `status`: `status` folds in the live selection read, so an unrelated selection change holds it at `pending` while the list is ready. Do not cache the rectangle as identity: geometry changes on scroll, zoom, resize, and pagination, and `viewport.observe()` is the signal to measure again. [Read more](/editor/custom-ui/selection-and-viewport) |
| `document.querySelector('[data-track-change-id="..."]').scrollIntoView()`              | `superdoc.ui.trackChanges.scrollTo`                          | Redesign      | Usually a match, and a `TypeError` when not. The call as written dereferences the result, so a change that is not painted takes down whatever runs it, and the same code works in a short document and throws in a long one. | This survives the upgrade, which is why it is worth migrating deliberately. The v2 painter still stamps `data-track-change-id` on painted runs, so the selector keeps resolving and nothing announces that it has become unreliable. It misses in two different ways. A change on a page that is not currently painted has no element at all, because `querySelector` sees only mounted DOM and virtualization leaves the rest of the document unrendered. And where several changes affect one marker, only one id lands in the singular attribute: the rest are in `data-track-change-ids`, comma-separated, so a secondary overlapping change is unreachable by the selector even while it is on screen. Both misses reach `.scrollIntoView()` on `null` and throw, unless the call is guarded. The attribute is renderer-owned and carries no stability contract either. `trackChanges.scrollTo(changeId)` takes the id rather than a selector, mounts the target page when it has to, resolves overlapping changes through the same catalog the review UI uses, and reports whether it succeeded. [Read more](/editor/custom-ui/tracked-changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `new MutationObserver(...) on the editor element`                                      | `superdoc.ui.viewport.observe`                               | Redesign      | The observer attaches and fires on repaints that do not correspond to document changes, or never fires for layout changes that produce no mutations.                                                                         | Watching the rendered DOM was always a proxy for the question consumers were asking. `viewport.observe()` fires when painted geometry is invalidated, including scroll, zoom, resize, pagination, and virtualized page mounts, which a subtree MutationObserver either misses or floods on. [Read more](/editor/custom-ui/selection-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `element.scrollIntoView() on a content-control element`                                | `superdoc.ui.contentControls.scrollIntoView`                 | Redesign      | There is no element to hold: the query that produced it matches nothing, so the call throws or is skipped.                                                                                                                   | Address the control by id rather than by element: `contentControls.scrollIntoView({ id, block })` resolves it through the host, including on pages that are not currently painted. A DOM-held reference cannot survive virtualization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `editor.comments.filter((c) => c.isTrackedChange)`                                     | `superdoc.ui.trackChanges.list`                              | Redesign      | A null-property error on `comments`. Once ported, the more damaging failure is quiet: a document full of tracked changes reports none.                                                                                       | v2 separates tracked changes from comments instead of tagging one list. The trap is readiness, not the split: the catalog is an async read, so a synchronous `list()` on a controller that has not settled returns an empty snapshot rather than an error. Observe the slice and consume `items` once `status` is `ready`. `total` and `authors` come from the same slice and carry the same caveat. [Read more](/editor/custom-ui/tracked-changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `editor.presentationEditor`                                                            | `superdoc.activeEditor.pageMetrics`                          | Redesign      | A null-property error on `presentationEditor`, or `undefined` under optional chaining.                                                                                                                                       | `presentationEditor.getPages`, `presentationEditor.onLayoutUpdated`, `presentationEditor.element`. Page metrics survive as a capability. `pageMetrics` exposes `getSnapshot`, `subscribe`, `setZoom`, `scrollToPage`, `revealBodyTarget`, and `pageIndexForBodyTarget`, and `ui.viewport.getHost()` replaces reading `presentationEditor.element`. The facade types `pageMetrics` as `unknown`, so consuming it means declaring the shape yourself and re-verifying it on upgrade; it is not part of the typed public surface the rest of this catalog points at.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `.superdoc-page[data-page-index] (page element lookup)`                                | `superdoc.activeEditor.pageMetrics`                          | Redesign      | Usually nothing, which hides the two cases that matter. The painter still stamps `data-page-index` on `.superdoc-page`, so the selector keeps matching for mounted pages and returns null for virtualized ones.              | The DOM lookup survives the upgrade rather than breaking, so this migrates on correctness rather than on a build error. Page windowing means only mounted pages have elements, and a page outside the window returns null from the selector while still having metrics. Read the page from the metrics snapshot instead. The same untyped-surface caveat applies as for `presentationEditor`, and the painted DOM carries no stability contract even where it currently answers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `onTransaction`                                                                        | `defineSuperDocExtension + ctx.onMutation`                   | Redesign      | The config typechecks and the editor mounts, and the callback never fires.                                                                                                                                                   | v2 has no transactions to hand back. Declare an extension and subscribe through its activation context: `ctx.onMutation({ origin, sourceComplete, affects }, handler)`. The filter is the point of the redesign, because a v1 handler had to inspect every transaction and decide whether it mattered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `editor.chain().insertPageBreak().run()`                                               | `doc.create.paragraph + doc.format.paragraph.setFlowOptions` | Redesign      | A null-property error on `chain`, or `undefined` under optional chaining.                                                                                                                                                    | Not a behavioral equivalent, and the difference decides the port. v1 broke at the caret. v2 creates a paragraph at an address you supply and sets `pageBreakBefore` on it, which starts that paragraph on a new page rather than inserting a standalone break character. A mid-paragraph caret has no address of its own, so code that broke mid-paragraph must split the paragraph first or accept a block boundary. Await the creation: its returned address is the target of the formatting call. [Read more](/document-api/reference/format/paragraph/set-flow-options)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `doc.extract({}) / doc.getMarkdown({}) / doc.selection.current({}) read synchronously` | `the same operations, awaited`                               | Redesign      | The call returns a Promise where the code expected a value, so reads look empty and downstream property access yields `undefined`.                                                                                           | The v2 browser facade can route reads and mutations through a worker even when the underlying operation is synchronous in headless Node, so the same code is sync in one host and async in the other. Await browser calls, or normalize shared browser and headless code with `await Promise.resolve(call)`, and keep author overrides or other scoped state active until an awaited mutation settles. [Read more](/document-api/mental-model)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ui.createScope().register(...)`                                                       | `superdoc.ui.commands.register`                              | Redesign      | A null-property error on `createScope`, or `undefined` under optional chaining.                                                                                                                                              | Register on the instance-owned controller: `superdoc.ui` is created once on first read and reused, and its type omits `destroy()` because the instance owns teardown. The registration result is callable and also exposes `unregister()`; keep either and call it on unmount. Command callbacks receive the public `doc`, `ui`, selection, and mode rather than ProseMirror command state, and the selection should be read from `context.selection`, which is synchronous and always present, not through the deep-partial `context.doc`. [Read more](/editor/custom-ui/custom-commands)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `editor.on('selectionUpdate')`                                                         | `superdoc.ui.selection.subscribe`                            | Redesign      | The subscription is accepted and the handler never fires.                                                                                                                                                                    | `subscribe` fires immediately and passes `{ snapshot }`; `observe` is the value-shaped alias. Both return an unsubscribe function, where v1 required a matching `off`. The payload is a public selection slice with document addresses, not a ProseMirror selection, so handlers that read positions have to be rewritten rather than rebound.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `trackedChange.authorColor`                                                            | `superdoc.ui.trackChanges.list`                              | Redesign      | Present on some rows and absent on others. Rows without it render `undefined` as a color, and nothing errors.                                                                                                                | Conditional rather than removed. The row projection passes the v2 tracked-changes facade fields through, so `list()` returns `authorColor` for rows whose host supplies one. It is not declared on `TrackChangeInfo`, so it is not part of the typed public surface and reading it means asserting the shape yourself. `trackChanges.authors` is flattened to `readonly string[]` and drops the per-author color the facade returns, so it is not the fallback either. Keep an application-owned default rather than assuming the field is there, and do not mutate the readonly slice arrays to add one. [Read more](/editor/custom-ui/tracked-changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `editor.view.dom.addEventListener('paste', ...)`                                       | `the element your application passed as the SuperDoc host`   | Redesign      | A null-property error on `view`, or `undefined` under optional chaining.                                                                                                                                                     | The capability survives as ordinary DOM work, but the element does not: v2 owns and re-paints its internal DOM, so attach the listener to the stable host element you passed to SuperDoc and remove it on unmount. A bubbling listener is enough when validation only needs `preventDefault()`. This guards browser input only; programmatic Document API mutations emit no DOM paste events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

The editor internals are the harder half. v2 exposes `commands`, `state`, and `view` as `null` rather than removing them, so reading a property off one raises a generic null-property error that names your command and not SuperDoc. Optional chaining is worse: it turns the same mistake into a silent no-op that never errors at all.

Exact error wording varies by browser, bundler, and minifier. Treat the "What you see" column as symptoms to recognize, not as strings to match on.

## Before you start [#before-you-start]

Collaboration is not a configuration change. v2 rooms use a different document format, v2 owns the provider and `Y.Doc`, and a v2 editor must never be pointed at an existing v1 room. If your application uses collaboration, plan that migration separately before upgrading anything else.

Continue with the [v1 migration guide](/editor/migrate-from-v1/overview) for the full upgrade path, or the [Document API mental model](/document-api/mental-model) to understand what replaces direct editor access.


---

# Add spelling and grammar proofing

> Connect a spelling or grammar provider to SuperDoc.



Proofing helps people catch spelling and grammar mistakes while they write. SuperDoc underlines the issues; a provider
you choose checks the text and suggests replacements. It does not include a dictionary or grammar checker.

## Try a correction [#try-a-correction]

Expand the Editor and type `teh` followed by a space. Right-click its underline and choose **the**. Type `teh` again
and choose **Ignore** instead: the text stays unchanged, but the issue is dismissed for this editor session.

> **Interactive editor: Try proofing**
>
> Preset: `proofing`.
>
> Proofing: type `mispelled`, `workng`, or `teh`, then right-click the underline.
>
> Local DOCX selection: disabled.


## Enable proofing [#enable-proofing]

Keep the Editor, sample document, and export button from the [Quickstart](/editor/quickstart). Create
`src/proofing-provider.ts` with this local provider:

```ts
import type { Config } from 'superdoc';

export const proofing = {
  enabled: true,
  provider: {
    id: 'local-example',
    check: async ({ segments, signal }) => {
      signal?.throwIfAborted();
      return {
        issues: segments.flatMap((segment) => {
          return Array.from(
            segment.text.matchAll(/(?<![\p{L}\p{M}\p{N}_])teh(?![\p{L}\p{M}\p{N}_])/gu),
            ({ index }) => ({
              segmentId: segment.id,
              start: index,
              end: index + 3,
              kind: 'spelling' as const,
              replacements: ['the'],
            }),
          );
        }),
      };
    },
  },
} satisfies NonNullable<Config['proofing']>;

```

Import `proofing` into `src/main.ts` in Vanilla or `src/App.tsx` in React:

```ts
import { proofing } from './proofing-provider';
```

Add `proofing` to your existing `new SuperDoc({ ... })` configuration, or pass `proofing={proofing}` to
`SuperDocEditor`. Keep your existing readiness and cleanup handlers.

This provider flags only the lowercase word `teh`, not every spelling mistake. Type `teh teh` and confirm that both
words receive suggestions. It runs locally and needs no service credentials.

## Connect a full checker [#connect-a-full-checker]

Use the [proofing example](https://go.superdoc.dev/examples/proofing) for a local English dictionary. Grammar and style
checking require a provider that detects those issue kinds; enabling proofing alone does not add them.

SuperDoc sends text segments to the provider after edits. Return each issue with its `segmentId` and zero-based UTF-16
offsets into that segment, with an exclusive `end`. Return suggestions in `replacements`; do not edit the document
inside `check()`. Honor the request's `signal` so SuperDoc can cancel stale or timed-out checks.

Report provider failures through `onProofingError`. A failed check does not mean the document has no mistakes.

## Save corrected text [#save-corrected-text]

Choose a replacement, export with the Quickstart's **Export DOCX** button, and reopen the file to check the corrected
word. **Ignore** does not replace text or add a word to a persistent dictionary. Use `ignoredWords` if your application
needs to supply its own saved list of words to skip.

## Configure proofing [#configure-proofing]

Start with **Setup**, then open the other groups only when you need them. Proofing runs only when both `enabled: true` and `provider` are present.

### Setup

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `enabled` | `boolean` | `false` | Optional | Enables proofing. A provider is also required before SuperDoc runs checks. | Enables proofing. A provider is also required before SuperDoc runs checks. | — |
| `provider` | `{ id: string; getCapabilities?: () => ProofingCapabilities \| Promise<ProofingCapabilities>; check: (request: ProofingCheckRequest) => Promise<ProofingCheckResult>; dispose?: () => void \| Promise<void>; } \| null` | `null` | Optional | Checks the text segments SuperDoc supplies and returns spelling, grammar, or style issues. | Checks the text segments SuperDoc supplies and returns spelling, grammar, or style issues. | — |

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `defaultLanguage` | `string \| null` | `null` | Optional | Fallback language passed to the provider when a text segment has no resolved language. | Fallback language passed to the provider when a text segment has no resolved language. | — |
| `debounceMs` | `number` | `500` | Optional | Delay in milliseconds between an edit and the next proofing check. Values at or below 0 run without a delay. | Delay in milliseconds between an edit and the next proofing check. Values at or below 0 run without a delay. | — |
| `maxSuggestions` | `number` | — | Optional | Suggestion limit passed to the provider. The provider decides how to apply it. | Suggestion limit passed to the provider. The provider decides how to apply it. | — |
| `allowIgnoreWord` | `boolean` | `true` | Optional | Shows Ignore in the proofing context menu. Ignored words remain suppressed for this editor session. | Shows Ignore in the proofing context menu. Ignored words remain suppressed for this editor session. | — |
| `ignoredWords` | `string[]` | `[]` | Optional | Words whose proofing issues SuperDoc suppresses. Matching is case-insensitive after Unicode normalization. | Words whose proofing issues SuperDoc suppresses. Matching is case-insensitive after Unicode normalization. | — |
| `timeoutMs` | `number` | `10000` | Optional | Maximum provider call time in milliseconds. Non-positive or non-finite values use the default. | Maximum provider call time in milliseconds. Non-positive or non-finite values use the default. | — |

### Events

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `onProofingError` | `(error: { kind: "provider-error" \| "validation-error" \| "timeout"; message: string; segmentIds?: string[]; cause?: unknown; }) => void` | — | Optional | Runs when a provider check fails or times out. | Runs when a provider check fails or times out. | — |
| `onStatusChange` | `(status: ProofingStatus) => void` | — | Optional | Runs when the proofing lifecycle status changes. | Runs when the proofing lifecycle status changes. | — |

### Reserved

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `visibleFirst` | `boolean` | — | Optional | Prioritize checking visible pages first. | Prioritize checking visible pages first. | — |
| `maxConcurrentRequests` | `number` | — | Optional | Maximum concurrent provider requests. | Maximum concurrent provider requests. | — |
| `maxSegmentsPerBatch` | `number` | — | Optional | Maximum segments per provider call. | Maximum segments per provider call. | — |


Options under **Reserved** are present in the TypeScript type but do not affect the current runtime.

## Protect document text [#protect-document-text]

If the provider uses a network, document text leaves the browser. Obtain user consent, send only the required segments over authenticated encrypted transport, define how the service retains and deletes the text, and never include document text in URLs or logs.