Correctness Under Stealth: Targets, Frames, and Time

For CloakBrowser, the difficult part of a humanized click is not drawing a curved mouse path; it is deciding which element the path should reach and proving that the element is still the right one when input is dispatched. This chapter examines the wrapper’s isolated-world reads, actionability checks, frame routing, target identity, navigation handling, and shared timeout budget. The result is a useful distinction: a behavior can look plausible yet be operationally wrong if it is aimed at a stale, covered, or misresolved target.

The isolated world narrows the read path

Humanized interaction needs information that a simple native click can leave to Playwright: whether a selector matches, whether the element is visible and enabled, what its bounding box is, whether it is an input, and whether it is already focused. CloakBrowser’s challenge is that obtaining that information through ordinary page evaluation can itself become observable. Its solution is a CDP isolated execution world attached to the page. The wrapper evaluates its selector and geometry helpers there rather than using the page’s ordinary JavaScript world for those pre-action reads.

An isolated world is a separate JavaScript execution context associated with the document. It can inspect the DOM, but page scripts do not share its ordinary global objects. CloakBrowser creates the context through CDP, caches it for subsequent reads, and evaluates a versioned result payload. The payload contains more than a bounding box: it records attached, visible, enabled, editable, input, focused, and checked state, as well as an identity for the resolved element. This gives later stages a common snapshot instead of asking each helper to resolve the selector independently.

The resolver deliberately implements a bounded selector language. It can handle ordinary CSS, the explicit CSS and text forms, XPath, selected get_by_* locators such as test ID, placeholder, alternative text, title, text, and label, and a trailing first/nth/last selection. It does not claim to reproduce every part of Playwright’s locator grammar. Role selectors require a full accessible-name algorithm; chained locators, filters, logical combinations, frame locators, and several layout-specific predicates require additional semantics. When the isolated resolver cannot represent one of those forms, it returns an unsupported result and the humanized action raises a typed error.

That refusal is a correctness decision as much as a stealth decision. Falling back silently to Playwright would make the API appear more compatible, but the fallback could perform the DOM read in the page’s main world, where a page can observe or instrument it. Worse, two resolvers might select different elements. For a cursor-based action, a wrong match is not a minor discrepancy: the wrapper could move convincingly to the wrong coordinates and activate the wrong control. CloakBrowser therefore prefers an explicit compatibility boundary to an uncertain humanized action. A caller can simplify the selector or choose a non-humanized call when broad Playwright grammar matters more than the isolated read path.

The isolated snapshot feeds Playwright-style actionability checks. Before a click, the wrapper checks that the element is attached, visible, enabled, and able to receive pointer events; an input action also needs editability. These checks are retried with increasing delays rather than treated as one instantaneous test.