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

# ReviseEditorHandle

> The controllers your application drives the editor with.

`onReady` hands you a `ReviseEditorHandle`. Keep it in a ref; every controller
on it is stable for the life of the component.

```ts theme={null}
const editor = useRef<ReviseEditorHandle | null>(null);

<ReviseEditor onReady={(handle) => (editor.current = handle)} />;
```

## Routing

Every document-local controller resolves against the active document, and every
one can be bound to a specific document instead:

```ts theme={null}
editor.review.next();
editor.review.forDocument("exhibit-a").next();
editor.document("exhibit-a").review.next();  // equivalent
```

Scoped controllers: `tools`, `toolbar`, `review`, `view`, `zoom`, `selection`,
`agent`, `comments`.

## documents

<ResponseField name="open(document, options?)" type="Promise<ReviseDocumentHandle>">
  Opens and parses a document. `{ activate: false }` loads it in the background.
</ResponseField>

<ResponseField name="close(documentId)" type="boolean" />

<ResponseField name="activate(documentId)" type="boolean" />

<ResponseField name="get(documentId?)" type="ReviseDocumentHandle | null" />

<ResponseField name="require(documentId?)" type="ReviseDocumentHandle">
  As `get`, but throws instead of returning `null`.
</ResponseField>

<ResponseField name="getActiveId()" type="string | null" />

<ResponseField name="list()" type="ReviseOpenDocument[]" />

<ResponseField name="getState()" type="ReviseDocumentCollectionState" />

<ResponseField name="subscribe(listener)" type="() => void" />

## tools

<ResponseField name="getDefinitions()" type="ReviseEditorToolDefinition[]">
  Native document-local tool schemas, excluding the delegation tool.
</ResponseField>

<ResponseField name="execute(name, input?, options?)" type="Promise<ReviseEditorToolExecutionResult>">
  Options: `{ documentId?, directMode? }`.
</ResponseField>

<ResponseField name="exportDocx(documentId?)" type="Promise<Blob>" />

<ResponseField name="acceptAllSuggestions(documentId?)" type="number" />

<ResponseField name="rejectAllSuggestions(documentId?)" type="number" />

## toolbar

<ResponseField name="getState() / subscribe(listener)" type="ReviseToolbarState">
  Live selection formatting, block type, undo/redo availability, and review
  counts.
</ResponseField>

<ResponseField name="setActiveTab(tab) / openFind()" type="void" />

Commands return `false` when they cannot apply. Grouped by area:

| Area                  | Methods                                                                                                                                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| History and clipboard | `undo`, `redo`, `copy`, `copyAs`, `cut`, `paste`, `pasteTextOnly`, `pasteFormattingOnly`                                                                                                                                                        |
| Inline                | `toggleInline`, `toggleBold`, `toggleItalic`, `toggleUnderline`, `toggleStrikethrough`, `toggleDoubleStrikethrough`, `toggleSmallCaps`, `toggleAllCaps`, `toggleCode`, `toggleLatex`, `toggleSuperscript`, `toggleSubscript`, `clearFormatting` |
| Type                  | `setFontFamily`, `setFontSize`, `setLetterSpacing`, `setTextColor`, `setHighlightColor`                                                                                                                                                         |
| Paragraph             | `setHeading`, `setAlignment`, `setLineSpacing`, `toggleList`, `createLink`, `increaseIndent`, `decreaseIndent`                                                                                                                                  |
| Insert                | `insertTable`, `insertImage`, `insertContainer`, `insertCodeBlock`, `insertMathBlock`, `insertDiagram`, `insertFootnote`, `insertPageNumber`, `insertPageBreak`, `insertSectionBreak`                                                           |
| Review                | `openReview`, `closeReview`, `reviewPrevious`, `reviewNext`, `acceptCurrent`, `rejectCurrent`, `acceptAll`, `rejectAll`, `setShowRemovals`, `setSuggestionViewMode`                                                                             |

## view

Title and the chrome the SDK no longer renders buttons for.

<ResponseField name="getState() / subscribe(listener)" type="ReviseViewState">
  `{ ready, title, documentMode, readOnly, commentsOpen, commentCount, reviewOpen, reviewTargetCount }`
</ResponseField>

<ResponseField name="setTitle(title)" type="void" />

<ResponseField name="setDocumentMode(mode)" type="void" />

<ResponseField name="setCommentsOpen(open)" type="void" />

<ResponseField name="setReviewOpen(open)" type="void" />

## review

<ResponseField name="getState() / subscribe(listener)" type="ReviseReviewState">
  Open state, target counts, suggestion IDs, active comment, display mode, and
  every comment thread.
</ResponseField>

| Area       | Methods                                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Navigation | `open`, `close`, `previous`, `next`, `nextAgentSuggestion`, `navigateToSuggestion`, `navigateWithinSuggestions`                                                                                                                                                                             |
| Decisions  | `acceptCurrent`, `rejectCurrent`, `acceptAll`, `rejectAll`, `acceptSuggestions`, `rejectSuggestions`                                                                                                                                                                                        |
| Preview    | `previewCurrent`, `previewAll`, `previewSuggestions`                                                                                                                                                                                                                                        |
| Display    | `setShowRemovals`, `setSuggestionViewMode`, `getOpenSuggestionIds`                                                                                                                                                                                                                          |
| Comments   | `openComments`, `closeComments`, `selectComment`, `addCommentAtSelection`, `addCommentToRanges`, `addCommentToBlock`, `addCommentForSuggestion`, `replyToComment`, `setCommentResolved`, `deleteComment`, `getRelatedSuggestionIds`, `acceptCommentSuggestions`, `rejectCommentSuggestions` |

## selection

<ResponseField name="getSnapshot()" type="ReviseSelectionSnapshot" />

<ResponseField name="observe(listener) / subscribe(listener)" type="() => void" />

<ResponseField name="capture()" type="ReviseSelectionCapture | null">
  Survives focus moving into your UI. `null` when there is nothing addressable.
</ResponseField>

<ResponseField name="restore(capture)" type="ReviseSelectionRestoreResult">
  Typed failure when the document changed underneath it.
</ResponseField>

<ResponseField name="clear()" type="void" />

## zoom

<ResponseField name="getState()" type="{ zoom, scale }" />

<ResponseField name="setZoom(zoom) / fitWidth()" type="void" />

<ResponseField name="subscribe(listener)" type="() => void" />

## agent

<ResponseField name="run(task, options?)" type="Promise<ReviseAgentRunResult>" />

<ResponseField name="steer(message)" type="boolean">
  Guidance for a run already in flight.
</ResponseField>

<ResponseField name="cancel()" type="void" />

<ResponseField name="subscribe(listener)" type="() => void" />

## comments

Agent runs scoped to a single comment thread.

<ResponseField name="run(threadId, prompt?)" type="Promise<CommentAgentRunResult>" />

<ResponseField name="steer(threadId, message)" type="boolean" />

<ResponseField name="cancel(threadId)" type="void" />

<ResponseField name="getState(threadId)" type="CommentAgentRunState | undefined" />

<ResponseField name="subscribe(listener)" type="() => void">
  Publishes a map of every in-flight run.
</ResponseField>

## Convenience

Shorthands that route to the active document unless given an ID:

```ts theme={null}
editor.getDocument(documentId?);
editor.getDocumentMode(documentId?);
editor.setDocumentMode(mode, documentId?);
editor.getToolDefinitions(documentId?);
editor.focus(documentId?);
editor.openReview(documentId?);
editor.closeReview(documentId?);
editor.openComments(documentId?);
editor.closeComments(documentId?);
```