[feat]: add exclusion options to page.snapshot()

[seanmcguire12]

why

• to give users a way to exclude components of the hybrid tree returned by page.snapshot()
• for now, this only adds support for exclusion of iframes, but it is designed to be extensible with the anticipation that there will be other element/node types that users may want to exclude in the future

what changed

• added an optional PageSnapshotOptions parameter with includeIframes?: boolean and updated page.snapshot() to accept and forward it. Internally SnapshotOptions now mirrors that flag downstream in captureHybridSnapshot()
• the internal captureHybridSnapshot() function now computes framesInScope, and passes that filtered list to buildSessionIndexes(), collectPerFrameMaps(), computeFramePrefixes(), and mergeFramesIntoSnapshot(), so each stage only processes the intended frames while scoped snapshots (tryScopedSnapshot()) still run before the filter is applied
• updated various helpers to adhere to the filtered list of frames:
  • collectPerFrameMaps() iterates only on the provided frames
  • computeFramePrefixes() skips any children which should be ignored
  • mergeFramesIntoSnapshot() only merges the frames that are in scope
• page.snapshot() defaults to current behaviour (iframe inclusion)

test plan

• added additional unit tests:
  • snapshot-capture-orchestration.test.ts now asserts that collectPerFrameMaps() ignores omitted frames, & scoped snapshots still succeed with includeIframes: false, & the full capture path drops iframe data when requested
  • snapshot-frame-merge.test.ts now exercises the helper functions with filtered frame sets to check that prefixes, merges, and per-frame payloads are suppressed for excluded IDs
  • added a new page-snapshot.test.ts to check that the public page.snapshot() API forwards the option (both explicit false and default true) into captureHybridSnapshot()

---

Summary by cubic

Add an optional includeIframes flag to page.snapshot() so users can exclude iframe subtrees from the hybrid snapshot. Defaults to current behavior; use page.snapshot({ includeIframes: false }) to drop iframe content. Addresses Linear STG-1190.

• New Features
  • page.snapshot(options?: { includeIframes?: boolean }) now forwards the flag to captureHybridSnapshot.
  • SnapshotOptions gains includeIframes (default true).
  • Internals compute framesInScope and only process those frames; scoped snapshots still run before filtering.
  • Updated helpers to respect filtering: collectPerFrameMaps, computeFramePrefixes, mergeFramesIntoSnapshot.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a61c30b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cubic-dev-ai]

No issues found across 7 files

[greptile-apps]

Greptile Summary

This PR adds an includeIframes option to page.snapshot() that allows users to exclude iframe content from the hybrid snapshot tree. The implementation correctly filters frames at the capture entry point and threads the filtered list through all helper functions (buildSessionIndexes, collectPerFrameMaps, computeFramePrefixes, and mergeFramesIntoSnapshot). The option defaults to true (current behavior), and false limits the snapshot to only the root frame.

Key changes:

• Added PageSnapshotOptions type with includeIframes?: boolean to public API
• Updated internal SnapshotOptions to mirror the flag
• Modified captureHybridSnapshot() to compute framesInScope based on the option
• Updated all downstream helpers to respect the filtered frame list
• Scoped snapshots (via focusSelector) continue to work correctly regardless of iframe inclusion setting

Test coverage:

• Unit tests verify that collectPerFrameMaps() skips excluded frames
• Tests confirm scoped snapshots work with includeIframes: false
• Tests validate full capture path drops iframe data when requested
• Tests check prefix computation and merge logic ignore excluded frames

Minor discrepancy:

• PR description mentions adding page-snapshot.test.ts but the file is not in the changes

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is clean, well-tested, and follows good engineering practices. The filtering logic is applied at the right level and consistently threaded through all affected functions. The default behavior preserves backward compatibility. Comprehensive unit tests cover the main code paths and edge cases.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/page.ts	Updates page.snapshot() to accept options and forward includeIframes to internal capture function
packages/core/lib/v3/understudy/a11y/snapshot/capture.ts	Implements iframe exclusion by filtering frames before processing, correctly threading framesInScope through all helper functions
packages/core/tests/snapshot-capture-orchestration.test.ts	Adds comprehensive tests for iframe exclusion in collectPerFrameMaps and full capture path, including scoped snapshot edge case
packages/core/tests/snapshot-frame-merge.test.ts	Adds tests for prefix computation and merge logic with filtered frame sets to ensure excluded frames are not processed

Sequence Diagram

sequenceDiagram
    participant Client
    participant Page
    participant captureHybridSnapshot
    participant buildSessionIndexes
    participant collectPerFrameMaps
    participant computeFramePrefixes
    participant mergeFramesIntoSnapshot

    Client->>Page: snapshot({includeIframes: false})
    Page->>captureHybridSnapshot: {pierceShadow: true, includeIframes: false}
    
    Note over captureHybridSnapshot: includeIframes = options?.includeIframes !== false
    
    alt includeIframes is false
        captureHybridSnapshot->>captureHybridSnapshot: framesInScope = [context.rootId]
    else includeIframes is true (default)
        captureHybridSnapshot->>captureHybridSnapshot: framesInScope = [...context.frames]
    end
    
    captureHybridSnapshot->>captureHybridSnapshot: Ensure rootId is in framesInScope
    
    captureHybridSnapshot->>buildSessionIndexes: (page, framesInScope, pierce)
    buildSessionIndexes-->>captureHybridSnapshot: sessionToIndex Map
    
    captureHybridSnapshot->>collectPerFrameMaps: (page, context, sessionToIndex, options, pierce, framesInScope)
    Note over collectPerFrameMaps: Only iterates frameIds in framesInScope
    collectPerFrameMaps-->>captureHybridSnapshot: {perFrameMaps, perFrameOutlines}
    
    captureHybridSnapshot->>computeFramePrefixes: (page, context, perFrameMaps, framesInScope)
    Note over computeFramePrefixes: Skips children not in framesInScope
    computeFramePrefixes-->>captureHybridSnapshot: {absPrefix, iframeHostEncByChild}
    
    captureHybridSnapshot->>mergeFramesIntoSnapshot: (context, perFrameMaps, perFrameOutlines, absPrefix, iframeHostEncByChild, framesInScope)
    Note over mergeFramesIntoSnapshot: Only merges frames in framesInScope
    mergeFramesIntoSnapshot-->>captureHybridSnapshot: HybridSnapshot
    
    captureHybridSnapshot-->>Page: HybridSnapshot
    Page-->>Client: SnapshotResult

Loading

[greptile-apps]

_{6 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}