Selections

A selection is one point or region inside one rendered target, with a stable S<n> label and an optional note. This page covers the controls a person uses in the Lens dock: creating and adjusting selections, inspecting their images, managing Open and History, and keyboard access. How Lens works explains what a selection carries and how an agent uses it.

To use these controls in your own notebook, install marimo-lens and keep this cell displayed:

from marimo_lens import Lens

lens = Lens()
lens

Getting started includes the installation command. The interactive chart on this page already mounts its own Lens.

Create a selection

Press Select, or use Option+L on macOS and Alt+L elsewhere. Click once for a point or drag at least five pixels along both axes for a region. Smaller gestures become points. Click the code of a cell without output to select that cell. Lens exits selection mode after it creates the selection and opens the optional note editor.

Try both gestures on the chart:

1 Press Select, then click a bar2 Press Select, then drag across bars

Each new selection appears in Open with a stable S<n> label. Labels are never reused during the Lens instance lifetime. Use the row actions to edit its note, preview its selection image, or remove it.

Drag a point or region marker to move it. The current region exposes four resize handles. Lens clamps the marker to its target. Press Escape during a move or resize to restore the committed geometry.

Inspect selection images

Lens starts image capture after it stores a new selection. The selection stays available when capture is pending or fails.

Image state	What you can do
Preparing image	Use the selection reference and available graph context while capture runs.
View image	Hover or focus to open the preview. Click to pin it.
View previous image	Inspect the retained image from before the marker moved while replacement capture runs.
Image unavailable	Continue with the selection details and retry by moving or recreating the selection when pixels are required.

The preview reports its pixel dimensions. A previous image is marked outdated in the API because its point or region no longer matches the current marker. Read How Lens works for image states and the separate cell-output image used after an agent change.

Work with open selections

Open Selections to review open selections and their notes. The dock shows the Open count. Drag the grip to move the dock out of the way. Lens remembers its position in this browser for the site, including after a reload. Collapse the dock to a compact Lens button, which you can also drag. The button keeps the Open count visible.

Focus the grip or collapsed button and use arrow keys to move it. Hold Shift for larger steps, press Home to reset to bottom center, or press Escape to cancel a drag. Selections open toward the available space and stay inside the viewport.

Lens focuses the current selection in the Open tab. That selection is the likely referent when you ask an agent to change “this” or inspect “here.”

Choose another row to make it current. Editing its note, moving it, or resizing it also makes it current. If the current selection leaves Open, Lens focuses the most recently activated selection that remains.

Open the note editor from a row, describe what the agent should inspect or change, then press Done, or Command+Enter on macOS and Ctrl+Enter elsewhere.

Press Select again when the request refers to another point or region. An agent can resolve those selections together after one verified change.

Use Remove selection to delete one Open selection. Use Clear selections to delete every Open selection. These operations release their selection-image bytes. They do not clear History. Removing the current selection makes the most recently current remaining selection current.

Lens can reattach an Open selection after its target element is replaced within the same browser document:

Selection detail	What Lens keeps
Label and note	The S<n> label stays stable and is never reused.
Target	The same document ID and path plus the cell ID or exact DOM selector identify the target. DOM targets also require the same source identities, producing-cell ID set, and selector eligibility.
Producing cells	A DOM target includes producing cells from published source records or nested runtime metadata. Unkeyed roots remain tied to their original elements.
Selection image	Moving or resizing starts a fresh PNG capture. The previous image remains available and is marked outdated until the new capture succeeds.

A full document replacement creates a new opaque document identity. The old selection then remains Open with Target unavailable until it is removed or resolved. Cross-origin images and inaccessible iframes can block image capture. The selection details remain available. Custom targets explains DOM target identity.

Resolve or reopen a selection

After verifying the work, an agent calls resolve(). Lens moves each resolved selection from Open to History with its target, note, point or region, timestamps, and optional resolution summary. Each owning browser document shows a temporary resolution receipt for the selections it owns, with the visible status Addressed.

Selections resolved by the same verified change can move together and share one resolution summary.

The receipt remains for six seconds and pauses while hovered or focused. Open it to inspect the matching History entries.

To continue a request, open History and press Reopen while the target is available. Lens keeps the History entry, restores the selection as current in Open, and starts a fresh selection-image capture from the current target. When the target is unavailable, the History entry remains unchanged. Restore the target in the same browser document, then try again.

Use Clear history to remove every History entry. Open selections and their images remain. Clearing History also removes prior-resolution metadata from currently reopened selections. History keeps the newest 64 entries within a 64,000-byte metadata budget and evicts the oldest entries when either bound is reached.

Open selections, History, and stored selection images last for the lifetime of the live Lens instance. lens.close() or notebook-runtime teardown releases them.

Keyboard

Use these keys while selection mode is active:

Keys	Result
Option+L on macOS or Alt+L elsewhere	Start or refocus selection mode from the notebook or a same-origin output frame.
↑ / ↓	Move between selectable targets.
Enter	Create a point in the center of the focused target.
Tab	Exit selection mode and continue to the next dock control.
Escape	Exit selection mode and return focus to Select.

Open Selections for row, tab, and note controls:

Keys	Result
↑ / ↓ on an open selection	Move focus between selection rows.
Enter on an open selection	Make the focused selection current.
← / → on Open or History	Switch tabs when the other tab contains items.
Tab / Shift+Tab	Move through row actions. In the note editor, cycle through its controls.
Escape in Selections	Close the sheet and return focus to Selections.
Command+Enter or Ctrl+Enter in the note editor	Save the note and close the editor.
Escape in the note editor	Close the editor and return focus to the selection marker or Lens dock.
Enter or Space on an image action	Pin the preview and move focus to its close control.
Escape in an image preview	Close the preview and restore focus to its image action.

Use these keys on the current region's resize handles:

Keys	Result
Arrow key	Move the selected corner by 1 percent of the target dimension.
Shift plus an arrow key	Move the selected corner by 5 percent.
Escape	Cancel the current resize and restore the committed region.

Lens announces selection-mode changes, saved selections, attempts to use an unavailable target, and agent attention through polite live regions for screen-reader users.

Multiple Lens instances

The first displayed Lens view in a document owns interaction. Additional views render no Lens UI and log a warning to the browser console. Use marimo_lens.agent.connect() to access the Lens that owns the visible dock. Ownership passes to the next view when the current owner closes. A Lens in another same-origin document has its own owner.

How Lens works distinguishes activity, reveal, resolution, History entries, and resolution receipts. The Python API defines the agent-facing operations.