Developer Docs
Revise Developer Platform menu
SDKCLIAPI

ReviseEditorHandle

The controllers your application drives the editor with.

View as Markdown

These docs are for version 2.3.x. See the latest version.

onReady passes you a ReviseEditorHandle. Store it in a ref. Every controller on it is stable for the life of the component.

TypeScript
const editor = useRef<ReviseEditorHandle | null>(null);

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

Routing#

Document-local controllers act on the active document. Each one can be bound to a specific document instead:

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

open(document, options?)Promise<ReviseDocumentHandle>

Opens and parses a document. { activate: false } loads it in the background.

close(documentId)boolean
activate(documentId)boolean
get(documentId?)ReviseDocumentHandle | null
require(documentId?)ReviseDocumentHandle

As get, but throws instead of returning null.

getActiveId()string | null
list()ReviseOpenDocument[]
getState()ReviseDocumentCollectionState
subscribe(listener)() => void

tools#

getDefinitions()ReviseEditorToolDefinition[]

Native document-local tool schemas, without the delegation tool. Hand these to your own model. editor.getToolDefinitions() returns the same tools with an execute function each, plus revise_run_agent when an agent is configured.

execute(name, input?, options?)Promise<ReviseToolResult<Name>>

Typed inputs from the shared tool contract. Expected failures return { ok: false }. Options: { documentId?, directMode? }. context_notes, which a model uses to carry context between reads, is optional here and defaults to "N/A".

executeDynamic(name, input?, options?)Promise<ReviseToolResult<string>>

For untrusted model-provided calls, browser-only tools (get_selection, view_image, revise_run_agent), and model-facing document_id routing.

call(name, input?, options?)Promise<ReviseToolResponse<Name>>

Returns the successful response, or throws ReviseToolError.

exportDocx(documentId?)Promise<Blob>
export(options?, documentId?)Promise<Blob>

Export as "docx" (default), "pdf", "html", "markdown", or "txt". With mode: "review" (default) a .docx keeps pending tracked changes and comments, and other formats show the text with changes accepted. mode: "final" accepts every pending change and drops comments first — a clean copy. See export.

acceptAllSuggestions(documentId?)ReviseSuggestionDecision
rejectAllSuggestions(documentId?)ReviseSuggestionDecision

toolbar#

getState() / subscribe(listener)ReviseToolbarState

Live selection formatting, block type, undo/redo availability, and review counts.

setActiveTab(tab) / openFind()void

setActiveTab switches the ribbon's row. The SDK has no tab strip for the ribbon, so connect your own controls to toolbar.setActiveTab("layout" | "insert" | "review" | "edit"). Page and section breaks are on the Layout row. The SDK has no Tools row. Get word and character counts from editor.getStatistics().

Commands return false when they cannot apply.

AreaMethods
History and clipboardundo, redo, copy, copyAs, cut, paste, pasteTextOnly, pasteFormattingOnly
InlinetoggleInline, toggleBold, toggleItalic, toggleUnderline, toggleStrikethrough, toggleDoubleStrikethrough, toggleSmallCaps, toggleAllCaps, toggleCode, toggleLatex, toggleSuperscript, toggleSubscript, clearFormatting
TypesetFontFamily, setFontSize, setLetterSpacing, setTextColor, setHighlightColor
ParagraphsetHeading, setAlignment, setLineSpacing, toggleList, createLink, increaseIndent, decreaseIndent
InsertinsertTable, insertImage, insertContainer, insertCodeBlock, insertMathBlock, insertDiagram, insertFootnote, insertPageNumber, insertPageBreak, insertSectionBreak
ReviewopenReview, closeReview, reviewPrevious, reviewNext, acceptCurrent, rejectCurrent, acceptAll, rejectAll, setShowRemovals, setSuggestionViewMode

view#

Title, document mode, comments panel, and review panel.

getState() / subscribe(listener)ReviseViewState

{ ready, title, documentMode, readOnly, commentsOpen, commentCount, reviewOpen, reviewTargetCount }

setTitle(title)void
setDocumentMode(mode)void
setCommentsOpen(open)void
setReviewOpen(open)void

review#

getState() / subscribe(listener)ReviseReviewState

Open state, target counts, suggestion IDs, active comment, display mode, and every comment thread.

AreaMethods
Navigationopen, close, previous, next, nextAgentSuggestion, navigateToSuggestion, navigateWithinSuggestions
DecisionsacceptCurrent, rejectCurrent, acceptAll, rejectAll, acceptSuggestions, rejectSuggestions
PreviewpreviewCurrent, previewAll, previewSuggestions
DisplaysetShowRemovals, setSuggestionViewMode, getOpenSuggestionIds
CommentsopenComments, closeComments, selectComment, addCommentAtSelection, addCommentToRanges, addCommentToBlock, addCommentForSuggestion, replyToComment, setCommentResolved, deleteComment, getRelatedSuggestionIds, acceptCommentSuggestions, rejectCommentSuggestions
listChanges()ReviseTrackedChange[]

Every pending change with kind, author, authorType, createdAt, blockIds, insertedText/deletedText, and description. It is not part of the subscribed state. Each call reads the document once. See building your own review panel.

getChange(suggestionId)ReviseTrackedChange | null

One change, or null after it is resolved.

selection#

getSnapshot()ReviseSelectionSnapshot
observe(listener) / subscribe(listener)() => void
capture()ReviseSelectionCapture | null

Saves the selection so it survives focus moving into your UI. Returns null when nothing is selected.

restore(capture)ReviseSelectionRestoreResult

Returns a typed failure when the document has changed since the capture.

clear()void

zoom#

getState(){ zoom, scale }
setZoom(zoom) / fitWidth()void
subscribe(listener)() => void

agent#

run(task, options?)Promise<ReviseAgentRunResult>
steer(message)boolean

Send guidance to a run in progress.

cancel()void
subscribe(listener)() => void

comments#

Agent runs scoped to a single comment thread.

run(threadId, prompt?)Promise<CommentAgentRunResult>
steer(threadId, message)boolean
cancel(threadId)void
getState(threadId)CommentAgentRunState | undefined
subscribe(listener)() => void

Publishes a map of every run in progress.

collaboration#

Presence and sync state for a shared document. See collaboration.

getState()ReviseCollaborationState

{ enabled, synced, peers }. peers lists everyone in the room, including the local participant (isLocal: true), each with the color their caret is drawn in. Empty when no awareness was supplied.

subscribe(listener)() => void

Fires on join, leave, caret movement, and sync-state changes.

Convenience#

Shorthands that act on the active document unless given an ID.

onReady fires before any document exists. Subscriptions can be added immediately and attach when a document opens. Calls that act on a document throw until one is open. Wait for onDocumentReady, or await editor.whenReady().

TypeScript
await editor.whenReady();             // resolves when a document is open
editor.getRole(documentId?);          // "editor" | "suggester" | "viewer"
editor.getDocument(documentId?);
editor.getStatistics(documentId?);    // { wordCount, characterCount }
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?);

getStatistics() counts are computed without a layout pass, so they are safe to call per keystroke behind a debounce. Counts follow the markup view, as in Word: pending insertions count and pending deletions do not. In the "original" suggestion view mode, counts use the text as if all suggestions were rejected. editor.document(id).getStatistics() takes no argument.