accept locators for screenshot mask in golang sdk

[seanmcguire12]

why

• for consistency with TS/Python screenshot masks, Go should accept page-bound locator wrappers instead of generated locator descriptor schemas

what changed

• adds a handwritten Go ScreenshotOptions type for Page.Screenshot
• changes ScreenshotOptions.Mask to accept []*PageLocator
• converts mask locators to generated LocatorDescriptor values before sending the page.screenshot RPC
• validates that mask locators belong to the screenshot target page before sending the request
• preserves existing screenshot options like animations, caret, clip, full page, mask color, omit background, quality, scale, style, timeout, and type

SDK Shape

Go:

png, err := page.Screenshot(ctx, &stagehand.ScreenshotOptions{
	FullPage: &fullPage,
	Mask: []*stagehand.PageLocator{
		page.Locator(".secret"),
	},
	MaskColor: &maskColor,
})

behavioural notes:

• Page.Screenshot still returns decoded screenshot bytes
• nil screenshot options still send no protocol options
• mask locators serialize to generated LocatorDescriptor values internally, including pageId, selector, and optional nth
• mask locators from another page are rejected before RPC
• non-mask screenshot options continue to pass through unchanged
• TS/Python screenshot behavior and protocol schemas are unchanged

test plan

• Go SDK tests cover handwritten ScreenshotOptions conversion to generated protocol options
• Go SDK tests cover *PageLocator mask serialization, including nth
• Go SDK tests cover cross-page mask locator rejection before RPC
• Go SDK tests cover preservation of existing non-mask screenshot options

---

Summary by cubic

Go SDK: Page.Screenshot now accepts page-bound locator masks with strict validation while keeping screenshot behavior unchanged. This also moves act/observe/extract to locator-based scoping across SDKs, updates snapshotting, and standardizes examples to read result data via .data.

• New Features

  • Page.Screenshot Mask accepts []*PageLocator; nil and cross-page locators are rejected; converts to protocol descriptors before RPC.
  • act/observe/extract accept locator and ignoreLocators (with .nth), validate same-page locators, and serialize in TS batch callbacks.
  • Snapshot capture uses focusLocator/ignoreLocators; locator-scoped calls bypass server cache (responses show cache status DISABLED).

• Migration

  • Go: replace *PageScreenshotOptions with *ScreenshotOptions; pass page.Locator("...") in Mask.
  • Replace selector/ignoreSelectors with locator/ignoreLocators for act/observe/extract in TS/Python/Go; use .nth(index) when needed.
  • Examples now access result.data instead of the full response.

^{Written for commit 0baf98c. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0baf98c

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]

All reported issues were addressed across 3 files

Architecture diagram

sequenceDiagram
    participant Caller as Go SDK Caller
    participant Page as Page.Screenshot
    participant Conv as screenshotProtocolOptions
    participant Desc as locatorDescriptorsForScreenshot
    participant RPC as Protocol Client (rpc.call)

    Caller->>Page: Screenshot(ctx, &ScreenshotOptions{Mask: []*PageLocator})
    Page->>Page: Get target pageID
    Page->>Conv: screenshotProtocolOptions(options, pageID)
    alt options == nil
        Conv-->>Page: nil protocol options
    else options != nil
        Conv->>Conv: Copy non-mask options to PageScreenshotOptions
        alt options.Mask != nil
            Conv->>Desc: locatorDescriptorsForScreenshot(mask, pageID)
            loop each mask locator
                Desc->>Desc: locator.Descriptor() -> pageId, selector, nth
                alt locator.PageID != pageID
                    Desc-->>Page: error: mask locator must belong to the target page
                    Page-->>Caller: error (no RPC sent)
                end
            end
            Desc-->>Conv: []LocatorDescriptor
            Conv->>Conv: Set protocolOptions.Mask
        end
        Conv-->>Page: *PageScreenshotOptions
    end
    Page->>RPC: page.screenshot (PageScreenshotParams)
    RPC-->>Page: PageScreenshotResult (base64 data)
    Page->>Page: Decode base64 payload
    Page-->>Caller: []byte screenshot

Loading

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

Re-trigger cubic</sub>