Module caret_highlight 

An ambient band behind the sentence — or paragraph — the caret is in.

CaretHighlightSession owns a range session on a [TextDocument] (see add_range_session_with_priority) holding at most one range: the extent of whatever the caret is currently inside. It is the writing-comfort counterpart of FindSession — same registry, same staleness discipline, opposite intent. Find answers “where is this text”; this answers “where am I”.

Only the view being written in bands

Two panes over one document each own a session, and an inactive view clears its range. So the union of what the document carries is exactly one band, at the caret of the pane being written in, and neither view needs a HighlightMask to say so. That is also what makes the band vanish the moment focus leaves the editor, which is what you want: the band marks where you are writing, not where a caret happens to rest.

A selection makes a view inactive for the same reason. The band answers “where am I writing”; a selection answers it better and more precisely, so while one is up the band is redundant. It was also actively wrong: the range is resolved from the caret, which during a selection is its moving end, so the band skipped from sentence to sentence underneath a growing selection.

Priority, not registration order

The session registers at CARET_HIGHLIGHT_PRIORITY, below every other layer, so a find match or a spell squiggle always paints over the band. Registration order could not express that: a view’s session is registered when the view appears, so a split pane opened after the find banner would outrank it in that pane and not in its sibling.

Staleness on edit

The range is an absolute char offset frozen at push time, and text-document does not re-anchor a range session the way it re-anchors carets. Like FindSession this one subscribes to its document and marks itself stale on any content edit; the host calls CaretHighlightSession::refresh each frame with the live caret, which is cheap — a caret that has not moved into a different sentence pushes nothing at all.

Structs

CaretHighlight

The band an editor should draw, or the absence of one.

Enums

CaretHighlightScope

How much text around the caret the band covers.

Constants

CARET_HIGHLIGHT_PRIORITY

Where the caret-highlight session sits in the document’s merge order.