fix(v4): make locator screenshot masks reliable

[miguelg719]

Supports deep-locator screenshot masks, preserves all matches unless nth() narrows them, fixes top-layer mask geometry, and performs the paint delay outside page-controlled timers. Includes the transferred screenshot integration coverage.\n\nStacked on the Unicode snapshot PR.

---

Summary by cubic

Make Page.screenshot masks reliable across frames and Chromium’s transformed top-layer content. Supports deep-locator masks and stabilizes geometry and timing for consistent captures; adds tests.

• New Features

  • mask accepts DeepLocatorDelegate (including iframe hops); keeps all matches by default, narrowed with nth().

• Bug Fixes

  • Fix mask geometry for 2D/3D-transformed top-layer elements and their fixed descendants by neutralizing root transforms during measurement, adding a small bleed, measuring in one layout state, and restoring styles without transitions.
  • Honor fixed-position masks and wait outside page-controlled timers to guarantee a paint before capture.

^{Written for commit 2f3eb6d. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2f3eb6d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

Review completed against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

Confidence score: 4/5

• In packages/server/dom/screenshotScripts/resolveMaskRect.ts, setting the mask overlay to position: fixed based on the target element while still using localRect coordinates from the top-layer root can misalign fixed-element masks, so screenshots may hide or expose the wrong areas—align the coordinate space and positioning strategy (or compute fixed-element rects in viewport space) to de-risk this regression.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/server/dom/screenshotScripts/resolveMaskRect.ts">

<violation number="1" location="packages/server/dom/screenshotScripts/resolveMaskRect.ts:163">
P2: The new `position` field forces the mask overlay to `position: fixed` whenever the target's computed position is `fixed`, but the mask coordinates (`localRect`) are always computed relative to the top-layer root. A `fixed` overlay resolves `left/top` against the viewport unless the root itself is a fixed-containing block (root has a transform or `will-change: transform`). When a fixed descendant lives inside a top-layer root that has no transform, the root is not a containing block and the overlay's viewport-relative coordinates no longer match the root-relative `localRect`, so the mask is shifted by the root's on-page position. The previous always-`absolute` overlay resolved `localRect` against the root and stayed correct in that scenario, so this is a regression, not just an uncovered edge. Consider computing the overlay offset relative to the appropriate coordinate space (add the root's viewport offset when using `fixed` positioning on a non-transformed root), or only selecting `fixed` when the root actually remains a fixed-containing block after restore.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>