# Overview

> Route to the right surface for editing DOCX files from code, a shell, or an agent.



SuperDoc changes DOCX files without an editor UI. Some of that work is deterministic: a script knows the operation before it runs. Some of it is model-driven: an agent decides which operation to run from an instruction. Both use the same document engine and the same Document API contract.

Headless describes how these workflows run. It does not describe what you are trying to build, so start from the goal instead.

## Start from your goal [#start-from-your-goal]

| Goal                                        | Start here                                                         |
| ------------------------------------------- | ------------------------------------------------------------------ |
| Let a coding agent edit DOCX files          | [Build an agent](/agents/build/build-an-agent)                     |
| Add document tools to your product's agent  | [Build an agent](/agents/build/build-an-agent)                     |
| Run a known operation from application code | [Node.js SDK](/agents/automation/node-sdk)                         |
| Run a known operation from Python           | [Python SDK](/agents/automation/python-sdk)                        |
| Run a known operation from a shell or CI    | [CLI](/agents/automation/cli)                                      |
| Prepare review-aware HTML/Markdown for RAG  | [Output projections](/document-api/output-projections)             |
| Keep a person in the approval loop          | [Review tracked changes](/agents/workflows/review-tracked-changes) |
| Understand the operation contract itself    | [Document API mental model](/document-api/mental-model)            |

## The workflow underneath [#the-workflow-underneath]

Every headless workflow follows the same sequence, whether a script or a model chooses the operations:

```text
open → inspect state → mutate → check receipt → save → close
```

A model-driven workflow adds one step in front of it:

```text
instruction → model selects a tool → SuperDoc runs the operation → receipt
```

The split matters. The model decides what to do. SuperDoc runs the operation deterministically and reports a structured result. A model that picks the wrong operation produces a valid receipt for the wrong edit, so treat model mistakes and operation failures as separate problems.

## Which package to install [#which-package-to-install]

| Surface     | Use it when                                         | Package         |
| ----------- | --------------------------------------------------- | --------------- |
| Node.js SDK | Node.js owns the workflow, errors, and output files | `@superdoc/sdk` |
| Python SDK  | Python owns the workflow, errors, and output files  | `superdoc-sdk`  |
| CLI         | A shell script or CI job runs the workflow          | `@superdoc/cli` |

The Node.js SDK also provides the agent toolkit, so a Node.js product that embeds its own agent needs only
`@superdoc/sdk`. Do not import `@superdoc/headless` or `@superdoc/document-api-v2-adapter`. Those are implementation
details rather than integration surfaces.

## What these surfaces share with the Editor [#what-these-surfaces-share-with-the-editor]

* Queries return explicit matches, targets, handles, and revisions.
* Mutations return receipts or structured failures.
* Direct and tracked changes use the same operation contract.
* Comments, lists, tables, images, and sections are reached through Document API operations.
* DOCX remains the input and output format.

Capability availability varies by runtime and document state. Check `doc.capabilities()` before relying on an optional operation.

See [How SuperDoc works](/resources/how-superdoc-works) for the engine path and surface ownership map.

## What they do not provide [#what-they-do-not-provide]

These hosts never mount the Editor UI, so they have no toolbar, document canvas, viewport, browser selection, or pointer editing. There is no visual surface for accepting or rejecting a suggestion.

When a person must decide, write a separate DOCX and open it in the Editor or Microsoft Word. The [tracked-change review workflow](/agents/workflows/review-tracked-changes) shows that handoff end to end.

## Before you ship [#before-you-ship]

Your application owns the file and process boundary around the engine. Validate input paths, write results to a separate output until verification succeeds, bound retries, attribute changes to an explicit identity, and close sessions on success and failure alike.

[Safety](/agents/operate/safety) covers those responsibilities in full, and matters most once a model is choosing the operations.


---

# 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.


---

# 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 `documentMode` and `user` to the Editor setup from Quickstart:

**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`. 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. | — |
| `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 |
| --- | --- | --- | --- | --- | --- | --- |
| `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) |
| `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; }` | — | Optional | Configure document features that do not belong to the built-in interface. | Modules to load. | [Track changes](/editor/track-changes) |
| `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[]; 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. SuperDoc core ships no fonts; with none configured the toolbar shows the baseline and documents render with system fonts. | — |
| `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. Only the `unzip` and `render` stages are populated today; `parse` and `layout` are 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 |
| --- | --- | --- | --- | --- | --- | --- |
| `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.

## 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.


---

# 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]

Start from the [quickstart](/editor/quickstart) with `/sample.docx` in your application's `public` directory. 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 superdoc = new SuperDoc({ selector: '#editor', document: '/sample.docx' });

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;
  }
};

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

```

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]

Set `documentMode` when the Editor starts. These examples start in `suggesting`, configure the later viewing state, and
show how your application can switch to `viewing`.

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

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

let ready = false;

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  documentMode: 'suggesting',
  viewing: {
    comments: true,
    trackedChanges: 'markup',
  },
  onReady: () => {
    ready = true;
  },
});

export function switchToViewing() {
  if (!ready) return;
  superdoc.setDocumentMode('viewing');
}

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

```

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

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

export function Editor() {
  const [documentMode, setDocumentMode] = useState<DocumentMode>('suggesting');

  return (
    <>
      <button onClick={() => setDocumentMode('viewing')} type='button'>
        Switch to viewing
      </button>
      <SuperDocEditor
        document='/sample.docx'
        documentMode={documentMode}
        viewing={{
          comments: true,
          trackedChanges: 'markup',
        }}
      />
    </>
  );
}

```


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

## 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/built-in-ui/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 a DOCX, return its bytes, remove comments, or package related files.



Use `SuperDoc.export()` after the Editor is ready. It downloads a DOCX by default; set options when the application needs a backend upload, a comment-free copy, or a package of related files.

## Choose the output behavior [#choose-the-output-behavior]

| Option                 | Default      | Use it for                                                            |
| ---------------------- | ------------ | --------------------------------------------------------------------- |
| `exportType`           | `['docx']`   | Select the DOCX output for the browser Editor workflow                |
| `exportedName`         | Editor title | Set the downloaded filename without its extension                     |
| `triggerDownload`      | `true`       | Start a browser download; set it to `false` to return a `Blob` or ZIP |
| `commentsType`         | `'external'` | Keep external comments or use `'clean'` to remove comments            |
| `isFinalDoc`           | `false`      | Reserved in the export options; the v2 Editor does not apply it       |
| `additionalFiles`      | `[]`         | Add related `Blob` objects and return or download a ZIP               |
| `fieldsHighlightColor` | `null`       | Set a field highlight color in the exported DOCX                      |

## Export without comments [#export-without-comments]

This example removes comments and returns bytes for application-owned storage:

```ts
const result = await superdoc.export({
  exportType: ['docx'],
  commentsType: 'clean',
  exportedName: 'contract-without-comments',
  triggerDownload: false,
});

if (!(result instanceof Blob)) {
  throw new Error('SuperDoc did not return a DOCX blob.');
}

await saveDocument(result);
```

The v2 Editor does not apply `isFinalDoc` during export. `commentsType: 'clean'` removes comments, but it does not accept or reject tracked changes. Resolve tracked changes through the [Editor review workflow](/editor/track-changes) before exporting when the destination requires final text.

## Package related files [#package-related-files]

Pair each additional `Blob` with a filename. When export produces more than one file, SuperDoc returns or downloads a ZIP:

```ts
const bundle = await superdoc.export({
  exportType: ['docx'],
  additionalFiles: [auditLog],
  additionalFileNames: ['audit.json'],
  exportedName: 'contract-package',
  triggerDownload: false,
});
```

Keep the arrays in the same order. SuperDoc creates the package; your application still owns access control, retention, and persistence.

> **Verification target (success)**
>
> Reopen the exported DOCX. Confirm that the expected text is present and comments follow the selected policy.


For the basic download and backend upload paths, see [Load and save documents](/editor/load-and-save-documents).


---

# SuperDoc Editor

> Understand how SuperDoc edits DOCX files before you add the Editor to your application.



SuperDoc adds DOCX editing to your web application. People work in a document editor while your application controls
where files come from, where they are saved, and which workflows surround them.

## Keep DOCX as the document [#keep-docx-as-the-document]

A DOCX is a package of XML parts, relationships, and assets. An HTML-first editor converts that package into another
format for editing, then reconstructs a DOCX for export.

SuperDoc takes a different path. It reads the document's OOXML package into editable state and writes changes back to
OOXML without converting the document to HTML. The browser DOM is a rendered view, not the document format.

| Approach          | Editing model               | DOCX output                         |
| ----------------- | --------------------------- | ----------------------------------- |
| HTML-first editor | Converted HTML              | Reconstructed from HTML             |
| SuperDoc          | OOXML-backed document state | Changes written back to the package |

## Fit the Editor into your application [#fit-the-editor-into-your-application]

The browser Editor mounts inside your application and needs no SuperDoc server to render or edit a document. Your
application chooses the document source, storage, authentication, and collaboration provider.

People edit through the browser UI. Application code can use the Document API against the same open document. For
server-side automation and agent workflows, SuperDoc provides headless tools built on the same OOXML-backed model.

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

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

SuperDoc v1 used ProseMirror as its authoritative browser editing model. V2 uses an OOXML-backed document model across
browser and headless workflows. 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 install the Editor, open a DOCX, make an edit, and export the result.


---

# 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

> Show loading and error states, track unsaved edits, save, and clean up the Editor.



Connect each Editor signal to one application state: loading, ready, unsaved, saved, or unmounted.

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

Select a stage. The preview shows what your application should do and the code that drives it.

> **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 Save or Export and run document queries.
> 3. **Edit — `onEditorUpdate`:** Mark the document unsaved. Update your dirty state after an edit. Debounce autosave work if you start it here.
> 4. **Save — `export() + fetch()`:** Wait for storage. Export produces DOCX bytes. Mark the document saved only after your backend accepts 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.


## Wire the same states [#wire-the-same-states]

Replace the controls and mount point from the [Editor quickstart](/editor/quickstart):

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

Then connect them to `/sample.docx`. Replace `/api/documents/42` with your save endpoint:

```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 saveButton = requireElement<HTMLButtonElement>('#save-docx');

let isReady = false;
let editRevision = 0;

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

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  onReady: () => {
    isReady = true;
    status.value = 'Ready';
    saveButton.disabled = false;
  },
  onEditorUpdate: () => {
    editRevision += 1;
    status.value = 'Unsaved changes';
  },
  onContentError: ({ error }) => showLoadError(error),
  onException: ({ error }) => showLoadError(error),
});

async function saveDocument() {
  if (!isReady) return;

  const savedRevision = editRevision;
  saveButton.disabled = true;
  status.value = 'Saving…';
  try {
    const file = await superdoc.export({
      exportType: ['docx'],
      triggerDownload: false,
    });
    if (!(file instanceof Blob)) throw new Error('Expected one DOCX file.');

    const response = await fetch('/api/documents/42', {
      method: 'PUT',
      headers: {
        'content-type': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
      },
      body: file,
    });
    if (!response.ok) throw new Error(`Save failed with ${response.status}.`);
    status.value = editRevision === savedRevision ? 'Saved' : 'Unsaved changes';
  } catch (error) {
    status.value = 'Save failed';
    console.error('The document was not saved.', error);
  } finally {
    saveButton.disabled = false;
  }
}

saveButton.addEventListener('click', saveDocument);

export function unmountEditor() {
  saveButton.removeEventListener('click', saveDocument);
  superdoc.destroy();
}

```

Call `unmountEditor()` from the route or component that owns the Editor. If a listener belongs to a temporary panel,
register it with `on()` when the panel opens and remove it with `off()` when the panel closes.

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

With your save endpoint running, reload the page. **Save DOCX** should stay disabled until the document opens. Make an
edit, then save. The status should change from **Unsaved changes** to **Saved** only after the request succeeds.

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

## Go deeper [#go-deeper]

* [Load and save documents](/editor/load-and-save-documents) connects the Editor to your backend storage.
* [Connect two editors](/editor/collaboration/connect-two-editors) adds the separate collaboration-ready boundary and connection cleanup.
* [Tune performance for large documents](/editor/performance-and-large-documents) shows how to react to pagination without treating layout as an edit.


---

# Load and save a DOCX

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



Continue with `/sample.docx` from the [Quickstart](/editor/quickstart). Replace the local file with a backend round trip:

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 Vite project does not create this endpoint. Connect the example to your application API, or add a local
endpoint with this contract.

The endpoint can read from a database or an object store such as Amazon S3. The browser code stays the same. Keep
storage credentials and access checks in your backend.

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

For Vanilla, replace the Quickstart controls with a save action and status:

```html
<button id="save-docx" type="button" disabled>Save DOCX</button>
<output id="document-status">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]

The examples show the complete storage flow. Add any user, mode, or viewing options you chose on the previous pages to
the Editor configuration.

**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('The document was not 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: 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('The document was not 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={({ error }) => showOpenError(error)}
        onEditorUpdate={() => {
          editRevisionRef.current += 1;
          setSaveStatus('Unsaved changes');
        }}
        onException={({ error }) => showOpenError(error)}
        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.

## 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' })` |

A URL from another origin must allow the browser request through CORS. Fetch the file yourself and pass a `Blob` when
the request needs custom headers.

## 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. If the `PUT` fails, the status should show **Save failed** and the stored file should
remain unchanged.

## Continue from here [#continue-from-here]

* [Version history](/editor/version-history) keeps earlier saves so users can restore them.
* [Export options](/editor/export-options) changes the filename, comment policy, or related files.
* If your content starts as HTML or Markdown, see [rich content](/document-api/rich-content) and
  [output projections](/document-api/output-projections). These APIs do not open either format as a DOCX file.


---

# 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.



Choose Vanilla or React below. Your choice stays active for every code example on this page.

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

Create a Vite project, enter it, and install SuperDoc:

**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 and save it as `public/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. Add the page [#3-add-the-page]

Add the application surface. 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>,
);

```


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

Add the Editor and enable export after the document opens:

**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';

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={({ 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>
  );
}

```


Run the project:

```bash
pnpm dev
```

Open the printed URL. When the statement of work appears, **Export DOCX** becomes enabled. `onReady` keeps the button
disabled until the document is open.

## 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`.

> **Check the exported document (success)**
>
> Open `sample-edited.docx` in Word or SuperDoc. Confirm that the effective date is `October 1, 2026` and that the
> title, service list, milestone table, and signatures keep their formatting.


## What just happened [#what-just-happened]

* `selector` mounted the Vanilla Editor; the React wrapper owned its container.
* `document` gave the browser a DOCX URL to open.
* `onReady` marked the first safe moment to enable document actions.
* `export()` created the edited DOCX and triggered the download.

If the document does not appear, check the `onContentError` or `onException` message in the browser console. They
report import and startup failures instead of leaving an unexplained empty mount point.

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, choose a document mode, and handle startup
errors while keeping the same `/sample.docx` project.


---

# 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]

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]

Change a semantic color or the border radius, 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]

Start from the [quickstart](/editor/quickstart) with `/sample.docx` in your application's `public` directory.

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

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);

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
});

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

```

`ThemeConfig` 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.

## 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;
```

TypeScript restricts `vars` keys to names that start with `--sd-`. These values take precedence over the semantic
values generated by the same theme.

`--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.


---

# Review tracked changes

> Let people propose, inspect, accept, and reject changes in the Editor.



Tracked changes let a person propose an edit without immediately changing the accepted document. The Editor displays each proposal inline in the document and provides controls for accepting or rejecting it.

Use this page for the human review experience. Use [Document API tracked changes](/document-api/tracked-changes) when application code needs to create, list, inspect, or decide changes programmatically.

## Open the Editor for review [#open-the-editor-for-review]

Start in `suggesting` mode when a reviewer should create new tracked changes while inspecting existing ones. Provide the current user so exported changes retain their author.

Use the same toolbar and Editor containers from [Configure the built-in toolbar](/editor/built-in-ui/configure-the-toolbar), then initialize SuperDoc:

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  documentMode: 'suggesting',
  toolbar: '#toolbar',
  user: {
    name: 'Jordan Lee',
    email: 'jordan@example.com',
  },
});

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

```

Copy the [tracked-changes fixture](/fixtures/tracked-changes.docx) to your app's public directory as `contract.docx`, or update the document URL.

The built-in toolbar reads the active selection and exposes accept or reject actions when a tracked change can be decided. Anything you type in suggesting mode becomes a new proposal rather than a direct edit.

## Try the review flow [#try-the-review-flow]

The sample opens automatically with one tracked change. Select the change, then accept or reject it.

> **Interactive editor: Review a tracked change**
>
> Sample: [open the fixture](/fixtures/tracked-changes.docx).
>
> Preset: `tracked-review`.
>
> Tracked-change review: accept or reject the sample change.
>
> Local DOCX selection: disabled.


Accepting a change keeps the proposed result and removes the review mark. Rejecting it restores the prior content and removes the review mark. Both decisions change the open document and must be followed by your normal save or export flow.

## Choose the right mode [#choose-the-right-mode]

| Reviewer task                                      | Mode         | Tracked-change visibility                      |
| -------------------------------------------------- | ------------ | ---------------------------------------------- |
| Propose edits and decide existing changes          | `suggesting` | Review marks are shown                         |
| Edit directly while deciding existing changes      | `editing`    | Review marks are shown                         |
| Inspect proposals without changing the document    | `viewing`    | Set `modules.trackChanges.visible` to `true`   |
| Read the document as if no proposals had been made | `viewing`    | Leave tracked-change visibility at its default |

Viewing mode is read-only. Showing tracked changes in that mode does not grant permission to accept, reject, or create them.

## Control review decisions [#control-review-decisions]

Turn off accept and reject when someone may inspect or discuss proposals but should not decide them:

```ts
const config = {
  interaction: {
    trackedChanges: {
      allowDecisions: false,
    },
  },
};
```

This does not stop someone from proposing changes. Use `documentMode: 'suggesting'` to record their edits as proposals,
or `documentMode: 'viewing'` to prevent document edits entirely.

## Keep review decisions explicit [#keep-review-decisions-explicit]

The built-in controls and `superdoc/ui` use the same tracked-change state. A control can be disabled because there is no active change, the document is read-only, or the current client interaction policy does not allow the decision.

Do not infer the active change from document DOM attributes. Use the built-in controls or the public custom UI controller. Use the Document API when a service or application workflow decides a known change by ID.

Editor modes and client-side review controls are not an authorization boundary. Your application still owns access to the DOCX, trusted user identity, persistence, and collaboration authorization.

Verify the completed workflow by exporting the DOCX and reopening it. Accepted text should remain without a pending review mark. Rejected text should be restored. Unresolved changes should remain available for another reviewer.

## Report permission-filtered bulk decisions [#report-permission-filtered-bulk-decisions]

Accept All and Reject All can leave some changes open when the permission resolver allows the decision for only part of the document. SuperDoc does not choose how to present that outcome. Subscribe to `onTrackedChangesBulkDecision` and render a toast, banner, activity entry, or other application-owned UI.

```ts
const status = document.querySelector<HTMLOutputElement>('#review-status');

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  onTrackedChangesBulkDecision: (result) => {
    if (!status || result.permissionDeniedCount === 0) return;

    const action = result.decision === 'accept' ? 'Accepted' : 'Rejected';
    status.value = `${action} ${result.successfulCount} changes. ${result.permissionDeniedCount} changes were left because you do not have permission.`;
  },
});
```

The same payload is available through `superdoc.on('tracked-changes:bulk-decision', listener)` when the listener belongs to a later application lifecycle.

| Field                   | Meaning                                                               |
| ----------------------- | --------------------------------------------------------------------- |
| `documentId`            | Document that received the bulk decision                              |
| `decision`              | Requested operation: `accept` or `reject`                             |
| `requestedCount`        | Unique tracked changes considered                                     |
| `successfulCount`       | Changes successfully decided                                          |
| `permissionDeniedCount` | Changes left open because the permission resolver denied the decision |

`requestedCount` equals `successfulCount + permissionDeniedCount`. A zero `permissionDeniedCount` means the permission resolver allowed every considered change; applications can ignore that outcome when they only need to report leftover changes.

Continue with [Load and save documents](/editor/load-and-save-documents), or build application-owned controls with the [Custom UI overview](/editor/custom-ui/overview).


---

# Add version history

> Keep each saved DOCX as an immutable version and restore one without deleting newer work.



Continue from [Load and save](/editor/load-and-save-documents). You already export a DOCX and wait for your backend to
store it. Version history changes one rule: each save creates a new snapshot instead of overwriting the previous file.

## Keep every saved version [#keep-every-saved-version]

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.

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 current = await fetch(documentEndpoint).catch(() => null);
    const rollbackDocx = current?.ok ? new Blob([await current.arrayBuffer()], { type: DOCX }) : 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 reloads the backend's current document. If that request fails,
it restores the document that was open before the attempt.

Refresh the version list after every save or restore. Disable version actions while a request is running. 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. A save from that stale tab should return `409` and leave Version 3 current.

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.



SuperDoc always renders the DOCX canvas. Choose how much of the surrounding interface SuperDoc renders and how much
your application owns. This choice does not change how you load, edit, or save the document.

## Compare the approaches [#compare-the-approaches]

Switch between the three approaches. The toolbar and comments panel change ownership; the DOCX canvas does not.

> **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. Move to a hybrid or fully custom interface only for controls your application needs
to own.

## Set the interface boundary [#set-the-interface-boundary]

`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.

`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`.

A hybrid interface uses both paths: keep the built-in surfaces that fit and replace only the ones your application owns.


---

# 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: accept or reject the sample change.
>
> 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).


---

# 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 all forty actions,
// 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 example rejects any mutating call that omits `changeMode: 'tracked'` before it reaches the document, and returns that rejection as a receipt so the model can retry with the argument.

The argument alone is not sufficient either. `superdoc_perform_action` advertises `changeMode` once for all forty actions, but only some of them honor it: `apply_style`, `set_paragraph_spacing`, and `insert_page_break` ignore it and always edit directly. `move_range` is a third case — it accepts the argument and then fails without mutating, because a block-range deletion cannot be tracked. Passing `changeMode: 'tracked'` to any of these looks compliant and does not produce a suggestion, so the example allows only the actions that actually record one and tells the model to pick a different action otherwise.

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 never reach the document, while a throw from `dispatch` itself may have applied part of the edit before failing, so that one is terminal.

Enforce the constraint in code whenever the output is supposed to be reviewable. A prompt describes intent, and a permissive schema describes what is accepted rather than what is honored. Only the dispatch boundary decides what reaches the document.

## 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.


---

# 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 a 40-verb registry              |
| `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.


---

# 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. Forty actions are available, grouped by what they touch: text and structure, lists and numbering, comments, tracked-change review, formatting, tables, and history.

Two tools instead of forty 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.

## 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]

[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.


---

# 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` accepts it and then fails without mutating. 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.

## 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: accept or reject the sample change.
>
> 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.

## Try the comment workflow [#try-the-comment-workflow]

Expand the Editor and find the existing comment anchored to `September 30, 2026`. Use the controls above the document to
compare both configuration axes:

1. Change **Layout** between Auto, Sidebar, and Inline to compare how the comment surface uses the Editor width.
2. Change **Actions** between Read, Write, and Resolve to compare the maximum comment action the Editor allows.

> **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]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart). Add the current user and set the 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} />;
}

```


Vanilla also needs separate toolbar and Editor mounts:

```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. Export the DOCX and open it again.

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.



Compare three ways to shape the built-in toolbar, then add a focused version to the `/sample.docx` project from the
[Quickstart](/editor/quickstart).

## 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/formatting-sample.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]

Vanilla needs separate toolbar and Editor mounts:

```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. Add the focused configuration to the Editor setup:

**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 },
});

```

**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;

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={({ 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}
        ui={{ toolbar }}
      />
    </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:

**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>
    </>
  );
}

```


Vanilla also needs an Editor mount and a status element:

```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 line below the Editor reports the selection.
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]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart). Append 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} />;
}

```


Vanilla also needs an Editor mount:

```html
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

`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:

**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} />
    </>
  );
}

```


Vanilla also needs the button and Editor mount:

```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();
        },
      };
    },
  };
};

```

Add the handler to the `/sample.docx` project from the [Quickstart](/editor/quickstart):

**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: '/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='/sample.docx' hyperlinks={editorConfig.hyperlinks} ui={editorConfig.ui} />;
}

```


Vanilla also needs toolbar and Editor mounts:

```html
<div id="toolbar"></div>
<div id="editor"></div>

<script type="module" src="/src/main.ts"></script>

```

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:

```tsx
import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';

export default function App() {
  return <SuperDocEditor document='/contract.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]

In React, pass `renderLoading` to replace 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='/contract.docx'
      renderLoading={() =>
        loadFailed ? <p role='alert'>Could not open the document.</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:

```html
<p id="document-status" role="status">Opening document…</p>
<div id="editor" hidden></div>

```

```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');

function showLoading() {
  editor.hidden = true;
  status.hidden = false;
  status.textContent = 'Opening document…';
}

function showEditor() {
  status.hidden = true;
  editor.hidden = false;
}

function showError(error: unknown) {
  console.error('Could not open the document.', error);
  editor.hidden = true;
  status.hidden = false;
  status.textContent = 'Could not open the document. Try again.';
}

const superdoc = new SuperDoc({
  selector: editor,
  document: '/contract.docx',
  ui: { loading: false },
  onReady: showEditor,
  onContentError: ({ error }) => showError(error),
});

async function replaceDocument(file: File) {
  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);
  }
}

export { replaceDocument };

```

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.

## 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.


The map groups related surfaces by task rather than listing every implementation component. **Hyperlinks** covers what
happens when a person activates a link. **Context menu** covers right-click actions. **Content controls** covers
structured fields. **Ruler** covers left and right page margins. **Responsive layout** covers zoom and the Editor shell.
**Loading** covers the progress UI shown while a document opens.

## 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.



Responsive Editor layouts have three independent concerns: the document scale, the available toolbar width, and whether the document scrolls inside a fixed-height host. Configure each explicitly.

## Build the shell [#build-the-shell]

Request fullscreen on an element that contains the toolbar, the fullscreen button, and the Editor:

```html
<div id="editor-shell">
  <div id="toolbar"></div>
  <button id="fullscreen" type="button">Fullscreen</button>
  <div id="editor"></div>
</div>

<script type="module" src="/src/main.ts"></script>

```

## Fit to the container [#fit-to-the-container]

Configure fit-to-width and container-aware chrome, then refit after the browser enters or exits fullscreen:

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

const shell = document.querySelector<HTMLElement>('#editor-shell');
const fullscreen = document.querySelector<HTMLButtonElement>('#fullscreen');

if (!shell || !fullscreen) throw new Error('The responsive editor shell is incomplete.');

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  contained: true,
  zoom: {
    mode: 'fit-width',
    fitWidth: { min: 40, max: 100, padding: 24 },
  },
  ui: {
    toolbar: {
      container: '#toolbar',
      responsiveTo: 'container',
    },
    comments: { layout: 'auto' },
  },
});

const toggleFullscreen = async () => {
  if (document.fullscreenElement) await document.exitFullscreen();
  else await shell.requestFullscreen();
};
const refit = () => 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.

`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 superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  viewOptions: { layout: 'web' },
});
```

Web layout selects a retained semantic document surface; no layout-engine option is required. The browser owns normal-flow wrapping, so the document follows the Editor host's inner width without a page-layout pass.

The browser Editor's web layout does not show headers, footers, the ruler, or page-count updates. It updates changed semantic blocks in place rather than rendering page windows. Use print layout when page-specific presentation or page virtualization is required.

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.

The Fullscreen API is browser-owned, so the application must provide the button and handle rejected fullscreen requests where required by its product. The explicit `fullscreenchange` refit prevents the document from keeping dimensions calculated for the previous viewport.


---

# 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]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart), then 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} />;
}

```


Vanilla also needs an Editor mount:

```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, then replace one result with `Customer`.
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]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart), then 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} />;
}

```


Vanilla also needs separate toolbar and Editor mounts:

```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. Demo edits are not saved.


## 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, type “Delivery is due Friday.” Watch it appear 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.



Your shared document now survives a restart. Next, decide who may open it. A room ID identifies the document; it does not grant access. A cursor's display name is not proof of identity.

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.

> **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]

Open `http://localhost:5173/?mode=create&user=Alex`. 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.

## 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.

## 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. Demo edits are not saved.


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

> Start the local Hocuspocus server used by the SuperDoc collaboration example.



Run a local Hocuspocus server when you need to test a complete collaboration room before connecting production authentication and persistence.

## 1. Use the example server [#1-use-the-example-server]

Download or clone the [collaboration example](https://go.superdoc.dev/examples/collaboration) and follow its [installation steps](/editor/collaboration/connect-two-editors#1-start-the-example). It pins Hocuspocus 2.15.3 and includes the server and optional storage hooks.

## 2. Start it [#2-start-it]

```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.

## 3. Connect two editors [#3-connect-two-editors]

Configure the first browser with a Hocuspocus target and `roomMode: 'create'`. After the room exists, open a second browser with the same `documentId` and `roomMode: 'join'`. [Connect two editors](/editor/collaboration/connect-two-editors) walks through the browser setup.

The complete two-browser project is available at [go.superdoc.dev/examples/collaboration](https://go.superdoc.dev/examples/collaboration).

> **Verification target (success)**
>
> Edit the first browser. The second browser should show the change and export a DOCX containing the synchronized text.


## 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.

## 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):

```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 an inline field for content inside a paragraph. Use a block field for one or more whole paragraphs, such as a clause
slot.

## 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]

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 [content-controls example](https://go.superdoc.dev/examples/content-controls?workflow=add) contains the complete
Vanilla TypeScript workflow and verifies both fields after export and reopen.

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.



Treat your application data as the source of truth. Find controls by tag, update every returned target, and inspect each
mutation receipt before reporting success.

## Try the workflow [#try-the-workflow]

Change the client name. All three occurrences update. Toggle auto-renew to change the Word checkbox stored in the DOCX.

> **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.


## Define the field map [#define-the-field-map]

Keep business-field keys in application code. A tag connects one field to one or more controls in the document:

```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),
  );
}

```

## Update every occurrence [#update-every-occurrence]

`selectByTag()` returns each matching control. Update them one at a time so the result can distinguish complete,
partial, and failed updates:

```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'}.`;
}

```

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.

The [content-controls example](https://go.superdoc.dev/examples/content-controls?workflow=fill) contains the complete
Vanilla TypeScript workflow. It also focuses repeated occurrences, exports the DOCX, and verifies the result after
reopening it.

Continue with [Replace clauses from your application](/editor/content-controls/replace-clauses-from-your-application)
for block-level content. Use [custom content-control UI](/editor/custom-ui/content-controls) when your application needs
a persistent field list or richer navigation.


---

# Content controls

> Use structured DOCX regions for fields, clauses, repeating content, and application-owned workflows.



Content controls are structured regions stored as `w:sdt` elements in a DOCX. They let your application find and change
document content by metadata instead of matching the visible text.

**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 |


## Choose a workflow [#choose-a-workflow]

- [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.
- [Fill a DOCX template](/editor/content-controls/fill-a-docx-template): Connect application data to repeated values and typed controls.
- [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.


Beyond these workflows, content controls support:

* **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.


---

# 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]

Find the field by tag and apply the matching DOCX lock:

```ts
import type { LockMode } from '@superdoc/document-api';
import type { BrowserDocumentApi } from 'superdoc/ui';

export async function setTemplateFieldLock(doc: BrowserDocumentApi, tag: string, lockMode: 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.

## 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]

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.

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. Press **Bold** when it is available. The model shows the state your control renders
and the result it handles after the command runs.

> **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.

Vanilla needs toolbar, Editor, and panel mounts:

```html
<div id="toolbar"></div>

<main class="comments-layout">
  <div id="editor" style="height: 70vh"></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`.

Vanilla adds the panel beside its existing Editor container. Replace `index.html` with:

```html
<main class="fields-layout">
  <div id="editor" style="height: 70vh"></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;

    const failMutation = (message: string) => {
      pendingMutation = null;
      fieldsStatus.textContent = message;
      if (lastControls) render(lastControls);
    };

    const updateTextField = async (control: ContentControlInfo, value: string) => {
      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 });
        if (!receipt.success) failMutation(receipt.failure.message);
      } catch (error) {
        failMutation(error instanceof Error ? error.message : `${name} could not be updated.`);
      }
    };

    const updateCheckbox = async (control: ContentControlInfo, checked: boolean) => {
      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 });
        if (!receipt.success) failMutation(receipt.failure.message);
      } catch (error) {
        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) {
        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.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);
      }
    };

    stopContentControls = ui.contentControls.observe(render);
  },
  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, useState } from 'react';
import { SuperDocEditor } from '@superdoc/react';
import type { ContentControlInfo } from 'superdoc/ui';
import {
  SuperDocUIProvider,
  useSetSuperDoc,
  useSuperDocContentControls,
  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 = useSuperDocContentControls();
  const [drafts, setDrafts] = useState<Record<string, string>>({});
  const [pendingMutation, setPendingMutation] = useState<PendingMutation | null>(null);
  const [status, setStatus] = useState('Choose a field to edit it.');

  useEffect(() => {
    if (!pendingMutation) 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) {
    const documentApi = host?.activeEditor?.doc;
    if (!documentApi?.contentControls?.text?.setValue) {
      setStatus('Text field editing is unavailable.');
      return;
    }

    const name = fieldName(control);
    setPendingMutation({ controlId: control.id, controlName: name, kind: 'text', value });
    setStatus(`Updating ${name}…`);
    try {
      const receipt = await documentApi.contentControls.text.setValue({ target: control.target, value });
      if (!receipt.success) {
        setPendingMutation(null);
        setStatus(receipt.failure.message);
      }
    } catch (error) {
      setPendingMutation(null);
      setStatus(error instanceof Error ? error.message : `${name} could not be updated.`);
    }
  }

  async function updateCheckbox(control: ContentControlInfo, checked: boolean) {
    const documentApi = host?.activeEditor?.doc;
    if (!documentApi?.contentControls?.checkbox?.setState) {
      setStatus('Checkbox editing is unavailable.');
      return;
    }

    const name = fieldName(control);
    setPendingMutation({ checked, controlId: control.id, controlName: name, kind: 'checkbox' });
    setStatus(`Updating ${name}…`);
    try {
      const receipt = await documentApi.contentControls.checkbox.setState({ target: control.target, checked });
      if (!receipt.success) {
        setPendingMutation(null);
        setStatus(receipt.failure.message);
      }
    } catch (error) {
      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. Keep the panel pending until the observer returns the updated value, then clear any local draft and report
success. If the receipt fails or the operation throws, clear the pending state and show the failure.

## 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]

Vanilla adds the menu beside its Editor container. Replace `index.html` with:

```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 `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]

Complete [Build your first custom control](/editor/custom-ui/controller-setup) first. Continue with its `/sample.docx`
and built-in toolbar.

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>

```

Register the command, then 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 a font and size. 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 `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**.

Next, [build application document controls](/editor/custom-ui/zoom-and-document-state) to apply the same loop to
actions that target the document instead of the current selection. 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.

## Follow the core path [#follow-the-core-path]

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.
3. [Build a custom toolbar](/editor/custom-ui/formatting-controls) with a toggle and value pickers.
4. [Add document controls](/editor/custom-ui/zoom-and-document-state) for zoom and DOCX download.

Only the first guide is a prerequisite. It establishes the controller setup the rest build on, so you can stop after
any step. Step 2 explains how command state stays in sync and asks you to change nothing; steps 3 and 4 each replace
that setup's Editor code rather than the guide before it.

Steps 3 and 4 take the toolbar in different directions and are alternatives rather than a sequence: the custom toolbar
owns the toolbar markup outright, while document controls keep SuperDoc's toolbar and remove only Zoom. Read both before
combining them.

## 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.

## Build the same flow [#build-the-same-flow]

Complete [Selection and position](/editor/custom-ui/selection-and-viewport) first. This step reuses its captured
selection and sample document:

[Download the selection sample](/fixtures/custom-selection-workflow.docx): Two pages of selectable contract text · DOCX


Save this as `review-highlights.ts`. The controller uses `defineSuperDocExtension()` to validate stored data, refresh the
visual layer, re-resolve anchors after edits, and reject actions bound to text that has since changed:

```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 };
}

```

Create `review-highlights.css` beside it for the finding's visual mark:

```css
.review-finding-highlight {
  background: rgb(180 35 24 / 12%);
  box-shadow: inset 0 -2px #b42318;
}

```

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).


---

# 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


Vanilla adds the controls beside its existing Editor container. Replace `index.html` with:

```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`. If you use Vanilla, replace `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.


## Choose the target source [#choose-the-target-source]

Use the method that matches where the prompt 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
is why the capture above falls back with `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:

```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()`.

## 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.


---

# 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.

Start from [Build your first custom control](/editor/custom-ui/controller-setup). This example expects `/contract.docx`
to contain a table.

## Add the controls [#add-the-controls]

Create two table actions, context output, status output, and an 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>
  <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]

Read the Editor's controller, `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');

if (!tablePosition || !addRowButton || !deleteRowButton || !tableStatus) {
  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 }) => {
    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);
    };
  },
});

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 a table, add a row, delete a row, and export the DOCX. Outside the table, both 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`.

Vanilla needs toolbar, Editor, and panel mounts. If you use Vanilla, replace `index.html` with:

```html
<div id="toolbar"></div>

<main class="review-layout">
  <div id="editor" style="height: 70vh"></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`;
      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`}
      </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 the same controls [#build-the-same-controls]

Start from [Custom UI setup](/editor/custom-ui/controller-setup) with `/sample.docx` in your application's `public`
directory.

### 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. If you use Vanilla, replace `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="fit-width" type="button" disabled>Fit width</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 fitWidth = document.querySelector<HTMLButtonElement>('#fit-width');
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 || !fitWidth || !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;
      fitWidth.disabled = false;
      fitWidth.setAttribute('aria-pressed', String(zoom.mode === 'fit-width'));
      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 fitWidthHandler = () => ui.zoom.setMode('fit-width');
    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);
    fitWidth.addEventListener('click', fitWidthHandler);
    exportButton.addEventListener('click', exportHandler);

    removeHandlers = () => {
      zoomOut.removeEventListener('click', zoomOutHandler);
      zoomIn.removeEventListener('click', zoomInHandler);
      fitWidth.removeEventListener('click', fitWidthHandler);
      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
          aria-pressed={zoom.mode === 'fit-width'}
          disabled={!ui}
          onClick={() => ui?.zoom.setMode('fit-width')}
          type='button'
        >
          Fit width
        </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. `setMode('fit-width')`
keeps the document fitted when the Editor container changes width. 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.

This completes the core Custom UI path. 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.13.0-next.11` 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-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `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-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `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-and-viewport)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `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, before those mistakes reach a reader. Word processors usually underline an issue so the writer can replace or ignore it without leaving the document.

> **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]

SuperDoc schedules checks, underlines issues, and handles Ignore and replacements. It does not include a dictionary or grammar checker, so you provide one:

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  proofing: {
    enabled: true,
    provider: {
      id: 'local-example',
      check: async ({ segments }) => ({
        issues: segments.flatMap((segment) => {
          const start = segment.text.indexOf('teh');
          return start < 0
            ? []
            : [{ segmentId: segment.id, start, end: start + 3, kind: 'spelling', replacements: ['the'] }];
        }),
      }),
    },
  },
});

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

```

This provider flags only `teh`. For a complete local dictionary, see the [proofing example](https://go.superdoc.dev/examples/proofing).

SuperDoc sends text segments to the provider after edits. Return spelling, grammar, or style issues with zero-based UTF-16 offsets. Honor the request's `signal` so SuperDoc can cancel stale or timed-out checks.

## 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.