[fix]: support <frame> elements in XPath frame detection

[shrey150]

Summary

• IFRAME_STEP_RE regex only matched iframe steps, causing act() to fail on legacy <frameset> pages where observe() returns XPaths containing frame[N] (e.g. /html[1]/frameset[1]/frame[4]/html[1]/body[1]/...)
• Changed regex from /^iframe(?:\[\d+])?$/i to /^i?frame(?:\[\d+])?$/i so both <iframe> and <frame> are recognized as frame boundaries
• Consolidated the duplicate IFRAME_STEP_RE constant (was defined in both deepLocator.ts and focusSelectors.ts) into a single shared export

Test plan

• Scratchpad repro confirms current regex misses frame, frame[4], FRAME — all pass with fix
• 10 new unit tests added to snapshot-focus-selectors-utils.test.ts covering:
  • Regex matches iframe, iframe[N], frame, frame[N] (case-insensitive)
  • Regex rejects frameset, frameset[N], div, body, html
  • Full XPath parse + walk for frameset page XPaths detects correct frame boundary
  • Standard iframe XPaths still detected correctly
  • frameset is not false-positive detected as a frame boundary
• All 15 tests pass, build + typecheck pass

🤖 Generated with Claude Code

---

Summary by cubic

Adds support for in XPath frame boundary detection so navigation works on legacy pages. iframe and frame steps are treated as frame boundaries.

• Bug Fixes

  • Updated regex from /^iframe(?:[\d+])?$/i to /^i?frame(?:[\d+])?$/i to match iframe and frame (case-insensitive) without matching frameset.
  • Added focused tests for iframe/frame and frameset XPaths, including parse + boundary detection; trimmed low-value cases.
  • Added a changeset for a patch release.

• Refactors

  • Consolidated IFRAME_STEP_RE into a shared export from focusSelectors and used it in deepLocator.

^{Written for commit 4d09b02. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4d09b02

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 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Agent as Stagehand Agent
    participant DL as DeepLocator
    participant FS as focusSelectors (Utils)
    participant Browser as Browser/DOM Context

    Note over Agent,Browser: Cross-Frame Element Resolution Flow

    Agent->>DL: act/observe(selector/xpath)
    
    DL->>FS: parseXPathToSteps(xpath)
    FS-->>DL: Array of Steps (e.g. html, frameset, frame[4], body)

    loop For each XPath Step
        DL->>DL: CHANGED: Match step name against shared IFRAME_STEP_RE
        
        alt Step matches /^i?frame(?:\[\d+])?$/i
            Note over DL: NEW: Now matches legacy <frame> <br/>in addition to <iframe>
            DL->>Browser: Resolve FrameLocator for boundary
            Browser-->>DL: New Frame Context
        else Step is standard element (e.g. div, frameset, body)
            DL->>Browser: Continue path resolution in current context
        end
    end

    alt Element Found
        DL-->>Agent: Return ElementHandle
    else Frame Detection Failed (Old behavior for <frame>)
        DL-->>Agent: Throw StagehandInvalidArgumentError
    end

Loading

[greptile-apps]

Greptile Summary

Fixed frame detection regex to support legacy <frame> elements in addition to <iframe> elements. Changed IFRAME_STEP_RE from /^iframe(?:\[\d+])?$/i to /^i?frame(?:\[\d+])?$/i, making the "i" prefix optional so both element types are recognized as frame boundaries in XPath parsing.

• Updated regex in focusSelectors.ts and exported it for shared use
• Removed duplicate regex definition in deepLocator.ts, now imports from single source
• Added 10 comprehensive unit tests covering frame, frame[N], case-insensitivity, and negative cases (frameset, other elements)
• Fixes act() failures on legacy <frameset> pages where observe() returns XPaths like /html[1]/frameset[1]/frame[4]/html[1]/body[1]/...

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The change is surgical and well-tested - only modifies a regex pattern to add support for legacy <frame> elements. The regex change is minimal (adding i? to make the "i" optional), consolidates duplicate code, and includes comprehensive test coverage with 10 new tests covering all edge cases. No breaking changes or risky logic modifications.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/a11y/snapshot/focusSelectors.ts	Changed IFRAME_STEP_RE regex from /^iframe(?:\[\d+])?$/i to /^i?frame(?:\[\d+])?$/i and exported it, now correctly matches both <iframe> and <frame> elements in XPaths
packages/core/lib/v3/understudy/deepLocator.ts	Removed duplicate IFRAME_STEP_RE constant definition and imports it from focusSelectors.ts instead, consolidating the regex to a single source of truth
packages/core/tests/snapshot-focus-selectors-utils.test.ts	Added 10 comprehensive unit tests covering regex matches for frame/iframe variants, case-insensitivity, negative cases (frameset, other elements), and full XPath parsing for frameset pages

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[XPath with frame elements] --> B[parseXPathToSteps]
    B --> C{For each step}
    C --> D[Extract name by removing index]
    D --> E{Test with IFRAME_STEP_RE}
    E -->|Matches iframe or iframe N| F[Detected as frame boundary]
    E -->|Matches frame or frame N - NEW| F
    E -->|Does not match frameset or other| G[Regular element]
    F --> H[Navigate into child frame]
    G --> J[Add to current frame buffer]
    H --> K[Continue parsing in child frame]
    J --> K

Loading

_{Last reviewed commit: 80d56e3}

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}