Sightmap Browser Commands: Interacting with the Live Page

Once a session is running (Browser sessions), these commands act on the live page: click, fill, hover, keypress, scroll, drag, wait-for, dialog, screenshot, bounds, and tabs. Interaction targets are either a numeric probe ID from sightmap snapshot output or a component query — a small CSS-shaped language that addresses elements by their sightmap identity.

All commands on this page except the tabs subcommands (which resolve the session address themselves) accept --addr (default localhost:7892) and --tab; pass --tab whenever two or more content tabs are open, and put flags before positional arguments (shared conventions). Session lifecycle commands live on the Browser sessions page.

Component queries

Probe IDs are extraction-local: every snapshot reassigns them, so on a page that re-renders, an ID from an earlier snapshot goes stale. A component query avoids that — the command extracts the live tree, applies your corpus, and acts, all in one atomic pass, so nothing can go stale in between. Prefer queries on dynamic pages. Queries match over component names and extracted property values, not the DOM:

Query	Matches
`SearchInput`	the component named `SearchInput`
`ProductCard[sku=12345]`	a `ProductCard` whose `sku` property equals `12345`
`ProductCard[name^="Weber"]`	property prefix (`^=`)
`ProductCard[name*="grill" i]`	property substring (`*=`); trailing `i` makes the comparison case-insensitive
`ProductCard[sku=12345][badge=Sale]`	all predicates must hold
`LoginForm UserNameInput`	whitespace is a descendant chain; the last component is the target
`FulfillmentTileButton#1`	occurrence index `#N` (0-based) — a weak fallback when nothing else disambiguates

The only predicate operators are = (exact), ^= (prefix), and *= (substring). Quote values that contain spaces. --sightmap-dir (default .sightmap) selects the corpus that resolves the query. A query that matches zero components is an error. A query that matches several is also an error — the CLI lists the candidates with their distinguishing properties so you can add a predicate or an #N index:

sightmap browser: query FulfillmentTileButton is ambiguous: 2 components match. Add a property predicate or an occurrence index (#N):
  #0  id=112  FulfillmentTileButton label="Pickup"
  #1  id=118  FulfillmentTileButton label="Delivery"

Property predicates depend on properties: extraction in your corpus, which is a draft spec extension — implemented by the Go CLI but not part of sightmap spec v1, and subject to change. Robust targeting and property authoring reinforce each other: a component with no properties can only be addressed by name or #N index.

`browser click`

Clicks an element. The target is a probe ID, a component query, or raw --x/--y coordinates (a layout-fragile escape hatch). Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--sightmap-dir`	`.sightmap`	Path to `.sightmap/` dir (for component queries)
`--tab`	the lone content tab	Target tab ID (from `browser start` output)
`--x`	`-1`	Absolute x coordinate (skips node lookup)
`--y`	`-1`	Absolute y coordinate (skips node lookup)

sightmap browser click 'ProductCard[name^="Weber"] AddToCartButton'

Off-screen targets can be missed. Scroll the element into view first with browser scroll --component-id, then click.

`browser fill`

Types a value into an input. Takes two positionals: the target (probe ID or component query) and the value. Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--clear`	off	Clear the field via JS before typing (use for React-controlled inputs)
`--sightmap-dir`	`.sightmap`	Path to `.sightmap/` dir (for component queries)
`--tab`	the lone content tab	Target tab ID (from `browser start` output)

sightmap browser fill --clear SearchInput 'garden hose'

React-controlled inputs may append instead of replace. Pass --clear, or set the value through the native setter with browser eval:

sightmap browser eval 'var el = document.querySelector("INPUT_SELECTOR"); Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value").set.call(el, "new value"); el.dispatchEvent(new Event("input", {bubbles: true}))'

`browser hover`

Moves the pointer over an element — for hover-revealed menus and tooltips. Same targeting as click: probe ID, component query, or --x/--y. Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--sightmap-dir`	`.sightmap`	Path to `.sightmap/` dir (for component queries)
`--tab`	the lone content tab	Target tab ID (from `browser start` output)
`--x`	`-1`	Absolute x coordinate (skips node lookup)
`--y`	`-1`	Absolute y coordinate (skips node lookup)

sightmap browser hover 'AccountMenu'

`browser keypress`

Sends a key event to the currently focused element — click or fill a field first to focus it. The key name is a positional argument: Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, Space, and so on. Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--tab`	the lone content tab	Target tab ID (from `browser start` output)

sightmap browser fill SearchInput 'garden hose'
sightmap browser keypress Enter

`browser scroll`

Scrolls the page by pixel deltas, scrolls a component into view, or both — --component-id first brings the target into view, then any deltas apply. Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--component-id`	none	Component ID or `'ComponentQuery'` to scroll into view first
`--delta-x`	`0`	Horizontal scroll delta in pixels
`--delta-y`	`0`	Vertical scroll delta in pixels
`--sightmap-dir`	`.sightmap`	Path to `.sightmap/` dir (for component queries)
`--tab`	the lone content tab	Target tab ID (from `browser start` output)

sightmap browser scroll --delta-y 800
sightmap browser scroll --component-id 'FooterLinks'

`browser drag`

Drags an element by pixel deltas — for sliders and drag handles. The target is a positional probe ID from snapshot output (component queries are not supported here). Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--delta-x`	`0`	Horizontal drag delta in pixels
`--delta-y`	`0`	Vertical drag delta in pixels
`--tab`	the lone content tab	Target tab ID (from `browser start` output)

sightmap browser drag 214 --delta-x 120 --delta-y 0

`browser wait-for`

Blocks until a condition holds — exactly one of --url, --selector, or --load. Prints nothing on success; exits 1 if the timeout elapses first. Use it after a click that triggers navigation or async rendering, before you snapshot or act again.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--load`	off	Wait for the page load event
`--selector`	none	Wait until a DOM element matching this selector appears
`--timeout-ms`	`10000`	Timeout in milliseconds
`--url`	none	Wait until the page URL contains this pattern

sightmap browser click 'CheckoutButton'
sightmap browser wait-for --url '/checkout' --timeout-ms 15000

`browser dialog`

Resolves a blocking JavaScript dialog (alert, confirm, prompt). The action is a positional argument: accept or dismiss. Prints nothing on success.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--tab`	the lone content tab	Target tab ID (from `browser start` output)
`--text`	none	Prompt input text (prompt dialogs only)

sightmap browser dialog accept --text 'Springfield'

`browser screenshot`

Captures the current page as a PNG.

Flag	Default	Description
`--out`	`screenshot.png`	Output file path
`--stdout`	off	Write image bytes to stdout (for piping)

sightmap browser screenshot --out cart.png

screenshot saved: cart.png

`browser bounds`

Emits bounding boxes as JSON — as viewport percentages (mapping directly onto a screenshot taken at the same browser state) plus raw pixels. Query by positional component names (exact, case-insensitive — this is name lookup, not the component-query DSL), by raw CSS selector, or dump every matched component with --all. Offscreen matches are skipped unless you ask for them.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address (host:port)
`--all`	off	Emit bounds for every matched component (ignores positional queries)
`--include-offscreen`	off	Include components whose bounds fall entirely outside the viewport
`--selector`	none	Query raw DOM elements by CSS selector instead of component name
`--sightmap-dir`	`.sightmap`	Path to `.sightmap/` dir (for component-name queries)
`--substring`	off	Match component names by case-insensitive substring (default: exact, case-insensitive)
`--tab`	the lone content tab	Target tab ID (from `browser start` output)

sightmap browser bounds SearchInput

viewport: 1440x900
[
  {
    "comp": "SearchInput",
    "label": "Search products",
    "id": "27",
    "top": 2.1,
    "left": 30.6,
    "width": 38.9,
    "height": 4.9,
    "px": {
      "x": 440,
      "y": 19,
      "width": 560,
      "height": 44
    },
    "inViewport": true
  }
]

`browser tabs`

Tab management for the session. browser start prints your tab’s ID; tabs list shows every open content tab.

Subcommand	Description
`tabs list`	List open tabs (TargetID, URL, Title)
`tabs new [URL]`	Open a new tab; prints its TargetID
`tabs select <target-id>`	Deprecated — pass `--tab <ID>` on individual commands instead
`tabs close <target-id>`	Close a tab
`tabs resize <width> <height>`	Resize the viewport of the current tab

sightmap browser tabs list

8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D	https://shop.example.com/	Example Shop — Home
F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A	https://shop.example.com/cart	Your Cart

Typical flow

Read the page

sightmap snapshot prints the annotated component tree — component names, extracted properties, and probe IDs (Capturing pages).

Act by identity

browser click 'ProductCard[name^="Weber"] AddToCartButton', browser fill --clear SearchInput 'garden hose' — component queries stay valid across re-renders.

Wait for the result

browser wait-for --url '/cart' (or --selector/--load) before the next action.

Verify

Re-snapshot to read the new state, or browser screenshot --out after.png — pair with browser bounds to locate components in the image.

Overview

Browser

Capture and coverage

Selectors and corpus

Integrations

Sightmap Browser Commands: Interacting with the Live Page

Component queries

`browser click`

`browser fill`

`browser hover`

`browser keypress`

`browser scroll`

`browser drag`

`browser wait-for`

`browser dialog`

`browser screenshot`

`browser bounds`

`browser tabs`

Typical flow

​Component queries

​browser click

​browser fill

​browser hover

​browser keypress

​browser scroll

​browser drag

​browser wait-for

​browser dialog

​browser screenshot

​browser bounds

​browser tabs

​Typical flow

Component queries

`browser click`

`browser fill`

`browser hover`

`browser keypress`

`browser scroll`

`browser drag`

`browser wait-for`

`browser dialog`

`browser screenshot`

`browser bounds`

`browser tabs`

Typical flow