> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.revise.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracked changes

> Suggestions your users can accept or reject, from people and agents alike.

## Modes

A document in `suggesting` mode records every change as a tracked suggestion
instead of applying it. This applies to typing, toolbar commands, and agent
tool calls equally — which is what makes "let the model draft it, then review
every change" work without any special casing.

```ts theme={null}
editor.view.setDocumentMode("suggesting");
```

Set the starting mode per document, or editor-wide:

```tsx theme={null}
<ReviseEditor
  defaultDocumentMode="suggesting"
  initialDocuments={[{ id: "a", docx: file, documentMode: "editing" }]}
/>
```

<Note>
  `defaultDocumentMode` seeds the mode; it does not control it. Changing the
  prop later will not move a document that has already opened — use
  `view.setDocumentMode()` for that.
</Note>

## Reviewing

The `review` controller is the host-facing surface for tracked changes. It is
deliberately *not* an agent tool: it exposes interactive state and moves the
caret and viewport.

```ts theme={null}
const state = editor.review.getState();
// { open, targetCount, openSuggestionIds, currentSuggestionIds, ... }

editor.review.open();
editor.review.next();
editor.review.acceptCurrent();
editor.review.rejectCurrent();
editor.review.acceptAll();
```

Subscribe to render your own review UI:

```ts theme={null}
useEffect(() => editor.review.subscribe(setReviewState), [editor]);
```

### Targeted operations

When you know which suggestions you care about — for instance, everything a
particular agent run produced — operate on the IDs directly:

```ts theme={null}
const ids = editor.review.getOpenSuggestionIds();

editor.review.navigateToSuggestion(ids[0]);
editor.review.previewSuggestions(ids, "accept"); // non-destructive preview
editor.review.acceptSuggestions(ids);            // returns the count applied
```

`previewCurrent()` and `previewAll()` do the same for the current stop and the
whole document. Pass `null` to clear a preview.

### Display

```ts theme={null}
editor.review.setShowRemovals(false);
editor.review.setSuggestionViewMode("final"); // "all-markup" | "final" | "original"
```

`"final"` shows the document as it would read with everything accepted;
`"original"` as it read before. Useful for a read-only "clean copy" toggle
without mutating anything.

## Direct mode

Sometimes an agent edit should just apply — a formatting sweep, a
find-and-replace the user explicitly asked for. Pass `directMode` per call:

```ts theme={null}
await editor.tools.execute(
  "style_blocks",
  { selectors: "*", attrs: [{ name: "fontFamily", value: "Georgia" }] },
  { directMode: true },
);
```

For a delegated agent run, the mode is inherited by every tool call in the
loop, so one flag governs the whole task.

<Warning>
  Direct mode bypasses the tracked-change trail. Reserve it for changes the
  user has already approved in your own UI; anything speculative should stay a
  suggestion.
</Warning>

## Attribution

Suggestions carry their author, and agent-authored ones are distinguishable
from human edits. `review.getState().visibleAgentSuggestionIds` narrows to the
agent's own work, and `nextAgentSuggestion()` steps through only those — enough
to build a "review what the AI changed" flow that skips the user's own typing.

## Export

Tracked changes survive `exportDocx()` as Word revision marks, so a reviewer
who opens the file in Word sees the same suggestions, and accepting them there
produces the same result as accepting them in Revise.