Skip to main content
The selection is exposed as blocks and offsets, marks, comment IDs, and suggestion IDs. It never includes canvas geometry, so your UI does not depend on how Revise lays out text.

Reading

Subscribe to follow it:
observe() publishes the snapshot. subscribe() publishes { snapshot }. Both return an unsubscribe function. Both are memoized, so an identical selection does not re-render your UI.

Capture and restore

When the user clicks into an input in your own UI, such as a comment popover, the editor loses focus and the selection is lost. Capture it first and restore it afterward.
capture() returns a frozen snapshot scoped to the current document. It stays valid after focus moves away. It returns null when there is no selection or caret. restore() puts the selection back and refocuses the editor. It returns a typed failure when:
  • the editor is unavailable
  • the document is read-only
  • the capture belongs to a different document
  • the captured blocks no longer exist (for example, after an agent edit)
Capture when your UI opens and restore when it submits. A capture is scoped to one document and does not restore into another.

Clearing

For agents

The get_selection tool returns the same snapshot to an agent: selected text, caret or range positions, portable target segments, active formatting, comment IDs, and suggestion IDs. It includes no geometry. Your own agent does not receive the selection automatically. Give it get_selection when it needs to act on the text the user selected.