feat(selenium-devtools-py): register the collector at document start via BiDi preload

[vishnuv688]

What & why

Type of change

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Polish (an improvement to an existing feature)
• Breaking change (existing behavior changes for users)
• Documentation
• Internal (build, CI, dependencies, tooling)

Packages touched

• shared (types and contracts)
• core (framework-agnostic capture/reporting)
• elements (published element/snapshot API — @wdio/elements)
• service (WebdriverIO adapter)
• nightwatch-devtools (Nightwatch adapter)
• selenium-devtools (Selenium adapter)
• backend (server)
• app (UI)
• script (page-injected runtime)
• selenium-devtools-py

Notes for reviewers

Screenshots / recordings

[greptile-apps]

Greptile Summary

The PR registers the Python Selenium collector as a session-wide BiDi preload so new documents are instrumented from document start, while retaining per-document injection as a fallback.

• Adds BiDi preload registration with capability and failure handling.
• Separates raw collector-source loading from the injectable IIFE wrapper.
• Recovers documents missed by preload registration when a trace read reports that the collector is absent.
• Adds focused tests for registration, fallback behavior, recovery, and Selenium’s global preload call shape.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/selenium-devtools-py/src/selenium_devtools/bidi_preload.py	Adds capability-gated, session-wide BiDi preload registration with graceful fallback.
packages/selenium-devtools-py/src/selenium_devtools/instrumentation.py	Registers the collector preload during session setup and passes preload state into snapshot capture.
packages/selenium-devtools-py/src/selenium_devtools/snapshot.py	Separates raw and wrapped collector sources and adds trace-read-driven recovery for documents without a collector.
packages/selenium-devtools-py/tests/test_bidi_preload.py	Covers preload registration, fallback behavior, missed-document recovery, and Selenium API dispatch.
packages/selenium-devtools-py/tests/test_snapshot.py	Updates snapshot injection tests for readiness-first probing and retryable source loading.

Sequence Diagram

sequenceDiagram
    participant Setup as Session setup
    participant BiDi as Selenium BiDi
    participant Page as Current document
    participant Snap as SnapshotCapturer

    Setup->>BiDi: Pin collector preload
    alt Registration succeeds
        BiDi->>Page: Run collector at document start
        Setup->>Snap: "Start with preloaded=true"
    else BiDi unavailable
        Setup->>Snap: "Start with preloaded=false"
        Snap->>Page: Inject collector script
    end

    Snap->>Page: Read and drain trace
    alt Collector absent
        Snap->>Page: Inject fallback collector
        Snap->>Page: Read trace again
    end

Loading

_{Reviews (4): Last reviewed commit: "fix(selenium-devtools-py): recover a doc..." | Re-trigger Greptile}

[vishnuv688]

@greptile-apps