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

# Selection

> Read the selection, and keep it while your own UI takes focus.

Selection is exposed semantically — blocks and offsets, marks, comment and
suggestion IDs — never as canvas geometry. Your UI stays decoupled from how
Revise lays text out.

## Reading

```ts theme={null}
const snapshot = editor.selection.getSnapshot();

snapshot.empty;            // caret rather than a range
snapshot.text;             // the selected text
snapshot.target;           // portable ranges for comments and formatting
snapshot.selectionTarget;  // explicit start/end for insert and replace
snapshot.activeMarks;      // ["bold", "italic"]
snapshot.activeCommentIds;
snapshot.activeChangeIds;
```

Subscribe to follow it:

```ts theme={null}
useEffect(() => editor.selection.observe(setSelection), [editor]);
```

`observe()` publishes the snapshot directly; `subscribe()` publishes
`{ snapshot }` if you prefer the event shape. Both return an unsubscribe
function and are memoised, so identical selections do not re-render your UI.

## Capture and restore

The problem: your "Add comment" popover has an input. The moment the user
clicks into it, the editor loses focus and the selection they were commenting
on is gone.

```ts theme={null}
const capture = editor.selection.capture();
// ... user types in your popover, editor loses focus ...
const result = editor.selection.restore(capture);

if (!result.success) {
  // The blocks moved or were deleted while your UI was open.
}
```

`capture()` returns a deeply frozen, document-scoped snapshot that stays valid
after focus moves away. It returns `null` only when there is no addressable
selection or caret at all.

`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, or the captured blocks no longer
exist — all of which are ordinary outcomes when your UI stays open across an
agent edit.

<Tip>
  Capture on open, restore on submit. Do not hold a capture across a document
  switch: it is scoped to one document and will refuse to restore into another.
</Tip>

## Clearing

```ts theme={null}
editor.selection.clear();
```

## For agents

Agents get the same information through the `get_selection` tool, which returns
one semantic snapshot: selected text, caret or range positions, portable target
segments, active formatting, comment IDs, and suggestion IDs — and no geometry.

This matters because an outside agent does not receive the context Revise's own
agent gets injected automatically. If your model needs to act on "the bit the
user highlighted", give it `get_selection`.