Reading
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)
Clearing
For agents
Theget_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.