STG-2196 Shadow DOM fix

[monadoid]

why

Before this PR, if we passed a Stagehand selector like /html[1]/body[1]/shadow-host[1]//div[1]/div[1]/select[1], it could return no match when the shadow host also had a regular DOM <div>. In that case, countXPathMatches returned 0 and resolveXPathAtIndex returned null, even though the target <select> existed inside the host's shadow root.

This matters because Stagehand-generated selectors use non-leading // to represent entering a shadow root. When resolution fails there, deterministic actions like selectOptionFromDropdown can fail with element-not-found.

what changed

Added a regression test for that selector shape. Then changed the XPath resolver so it keeps the existing descendant-axis behavior when that resolves, but if that path finds nothing, it resolves the non-leading // as a Stagehand shadow-root hop. With the same selector now, countXPathMatches returns 1 and resolveXPathAtIndex returns #target.

test plan

• pnpm --filter @browserbasehq/stagehand run lint
• pnpm --filter @browserbasehq/stagehand run build-dom-scripts && pnpm --filter @browserbasehq/stagehand run build:esm
• pnpm --filter @browserbasehq/stagehand exec vitest run --config /Users/samfinton/code/browserbase/stagehand/packages/core/vitest.esm.config.mjs /Users/samfinton/code/browserbase/stagehand/packages/core/dist/esm/tests/unit/xpath-resolver.test.js

[changeset-bot]

🦋 Changeset detected

Latest commit: e65b851

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-v3	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]

1 issue found across 2 files

Confidence score: 3/5

• In packages/core/lib/v3/dom/locatorScripts/xpathResolver.ts, resolveXPathAtIndex appears to treat out-of-range indices as a shadow-hop fallback path, which can return behavior that disagrees with countXPathMatches; merging as-is risks inconsistent selector results and hard-to-debug locator failures in consumers—align out-of-range handling between these two functions (and add/adjust tests for index bounds) before merging.

Architecture diagram

sequenceDiagram
    participant Caller as Test / Stagehand
    participant Resolver as XPathResolver (countXPathMatches / resolveXPathAtIndex)
    participant Composed as resolveXPathComposedMatches
    participant ShadowHop as resolveStagehandShadowHopMatches (NEW)
    participant Parser as parseXPathSteps
    participant DOM as Browser DOM

    Note over Caller,Resolver: Entry
    Caller->>Resolver: countXPathMatches(selector) or resolveXPathAtIndex(selector, index)

    Resolver->>Composed: resolveXPathComposedMatches(xp, shadowCtx)
    Composed->>DOM: traverse composed tree (descendant axis)
    DOM-->>Composed: Element[]
    Composed-->>Resolver: composedMatches

    alt composedMatches has results AND index within range
        Resolver-->>Caller: return count / Element
    else composedMatches empty or index out of range (NEW fallback)
        Resolver->>ShadowHop: resolveStagehandShadowHopMatches(xp, shadowCtx)
        Note over ShadowHop: Only triggered when composed traversal found nothing

        ShadowHop->>Parser: parseXPathSteps(xp)
        Parser-->>ShadowHop: steps[]

        loop for each step i
            alt axis = "child"
                ShadowHop->>DOM: domChildren(currentRoot) (NEW)
                Note over DOM: Returns only direct DOM children (no shadow root)
                DOM-->>ShadowHop: child elements
            else axis = "desc" and i > 0 (shadow‑hop)
                ShadowHop->>DOM: shadowRootChildren(currentRoot, getClosedRoot) (NEW)
                Note over DOM: Returns only shadow root children (open/closed)
                DOM-->>ShadowHop: shadow root elements
            else i = 0 (initial descendant)
                ShadowHop->>DOM: composedDescendants(document)
                DOM-->>ShadowHop: initial elements
            end
        end

        alt shadowHopElements[targetIndex] exists
            ShadowHop-->>Resolver: matched Element
        else
            ShadowHop-->>Resolver: null / empty
        end

        alt resolved via shadow‑hop
            Resolver-->>Caller: return count / Element
        else still no match
            Resolver-->>Caller: return 0 / null
        end
    end

Loading

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

Fix all with cubic | Re-trigger cubic</sub>