Skip to main content
A component definition needs a way to find its DOM nodes. Sightmap uses CSS selectors because browsers and browser automation tools already support them, regardless of which framework rendered the page.

​
Choose selectors from the rendered DOM

Framework component handles are tied to React, Vue, or another runtime. XPath can address the DOM but tends to encode more structure than a CSS selector. IDs injected by an observing tool exist only for that tool and change the page being observed. CSS selectors operate on the DOM that the agent already sees. Their stability depends on what they target: source-controlled attributes usually outlast generated class names, text content, and positional structure.
Sightmap supports tag, ID, class, and attribute selectors; descendant and child (>) combinators; and the pseudo-classes :not(), :is(), :where(), and :has(). It does not support sibling combinators (+, ~) or positional pseudo-classes such as :nth-child(). Verify selectors with sightmap sel-probe or sightmap sel-check. See Selector tools.

​
Use arrays for fallbacks

A selector can be one CSS string or an ordered array. Sightmap uses the first selector that matches one or more elements.
In this example, data-component is the preferred hook, data-picker supports older markup, and the class selector is the last fallback. Remove stale alternatives after the migration is complete. If the selected pattern matches several elements, Sightmap gives all of them the component name. Child selectors run within each matched parent’s subtree, so two unrelated card components can both contain button.primary without colliding.

​
The data-component convention

When the app has no stable selector, add data-component="ComponentName" to the component’s root element:
This creates an explicit hook controlled by the application instead of relying on styling classes or DOM position. If the app already exposes a stable data-testid, ID, or semantic attribute, use that instead of adding another marker. The CLI’s selector tools recognize both data-testid and data-component as stable authoring hooks.
Quote attribute selectors in YAML. selector: [data-component="X"] is parsed as a YAML flow sequence and fails validation. Write selector: '[data-component="X"]'.

​
Three matching rules

Components, views, and requests resolve matches differently: View routes are scored by segment: a literal scores 3, :param scores 2, * scores 1, and ** scores 0. For /users/admin, the route /users/admin scores 6 and beats /users/*, which scores 4. A broad request entry such as /api/** and a specific entry such as /api/flights/search can both match one call. Use the broad entry only for metadata or memory that applies to every matching request. See Route matching for the glob syntax and scoring rules.