Smart locators and DOM selection

An element pin combines a stable selector, DOM path, tag, id, name, test id, role, classes, text, label, and geometry. During reopen, Pinar evaluates selector, structure, semantics, and geometry rather than trusting one fragile path.

A match can be exact, probable, ambiguous, or unresolved. When two candidates are too similar, Pinar keeps alternatives instead of snapping the pin to the wrong element. Cross-origin iframe targets can remain unresolved.

At capture time Pinar prefers a selector that uniquely matches the node by id, data-testid or data-test, or tag plus name. If none of those is unique, it stores a structural CSS path instead. Class names that look generated are dropped from the fingerprint so hashed CSS modules do not become the only signal.

On reopen, candidates from stable-selector, structure, semantic, and geometry strategies are merged and ranked. Exact confidence requires a high-scoring stable selector or structure hit; semantic and geometry matches stay probable. When the top two viable scores differ by less than a narrow margin, the result is ambiguous and no element is chosen.

• A positional :nth-of-type selector is scored lower when other nodes share the same tag, text, and classes.
• Area pins are rejected as element targets and remain unresolved during locator scoring.
• When an iframe contentDocument is unreadable, relocation stops with a cross-origin-frame warning instead of guessing.