[docs] decision: BiDi is exposed in three API layers

[AutomatedTester]

💥 What does this PR do?

Proposes a foundational design decision record: BiDi is exposed in three API layers.

The BiDi ergonomics series (#17671–#17677, #17681) keeps hitting the same unanswered question — raised directly in review of the storage ADR (#17673): is a new BiDi ergonomic a new explicit namespace users opt into, or does the high-level API stay unified and pick Classic/BiDi under the hood? This record answers it once, for the whole series, with three layers and a placement rule (each capability lives at the highest layer it fits):

• Layer 1 — the unified high-level API (the 80%). The existing Classic-shaped surface stays primary and, when a BiDi session is active, is implemented as a facade that delegates to the Layer 2 BiDi modules (e.g. driver.get → browsing_context.navigate), with Classic HTTP as the fallback. Signatures are unchanged; new capabilities are surfaced in Classic idiom (the concept, not the protocol noun).
• Layer 2 — explicit BiDi modules (power users). The handle objects, expect_*, network interception, typed storage, emulation, permissions — i.e. the [docs] decision: BiDi events are awaited with expect_* context managers #17671–[docs] decision: browsing contexts are exposed as handle objects #17681 series. Honestly named (UserContext, BrowsingContext); a tool beside the Classic API, never a replacement.
• Layer 3 — raw protocol. The escape hatch.

🔧 Implementation Notes

• Follows the docs/decisions/ process ([docs] add design decision record process and template #17665, already in trunk); adds only docs/decisions/0010-*.md (renames to this PR's number).
• Reframes the module ADRs as Layer 2, which should remove the recurring "new namespace vs. reuse" debate and simplify getting them merged.
• Layer 1 being delegated onto Layer 2 is the target architecture, rolled out one Classic API at a time, each with Classic-vs-BiDi parity tests. The window-handle string already equals the BiDi context id in the drivers Selenium targets, which is what lets Layer 1 delegate without a translation table — a high-risk wire-level area.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial draft of the decision record, synthesising the layering question raised across the BiDi ergonomics ADRs and the review feedback on them; revised through discussion
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• Intended to be agreed early, since it scopes the rest of the series; each module ADR declares its layer in its Context.
• Follow-up: a per-Classic-API routing decision as Layer 1 is delegated onto BiDi (windows/switch_to ↔ browsing contexts, manage().addCookie ↔ storage). The exact spelling of new Layer 1 affordances (e.g. isolation) is owned by the relevant module ADR (e.g. [docs] decision: browsing contexts are exposed as handle objects #17681).

🔄 Types of changes

• Documentation (design decision record)

[pujagani]

I agree with the layer 1 bit. I need to further look into the layer 2 approach, it seems there are 2 parts to it, one is the CDDL generated modules and commands and another is the proposed ADRs. Is that correct? Layer 3 is something, I do not think it is required. If we are doing CDDL generation for all language bindings, won't all the modules be available at regular cadence with each release. We can probably go over this in the TLC meeting.

[AutomatedTester]

This ADR can be closed if we solve https://github.com/SeleniumHQ/selenium/pull/17701/changes#r3473957666 in a good way

[titusfortner]

My primary concern is that this changes the direction we agreed to 2 years ago for having a distinct, deliberately designed protocol-neutral API for new event driven features.

What we previously agreed to was two user-facing surfaces. One was protocol neutral and the other was not:

• The existing Selenium API plus specifically designed APIs for new capabilities such as Network and Script/Logs (what we've been calling the "High Level API").
• The complete BiDi protocol implementation which remains callable but unsupported because it may be awkward to use

#17670 was supposed to be an easy win codifying the concept we've been working under for 2 years and proposing some specifics on the extent of the ramifications of it that we could quickly accept/reject.

This ADR removes protocol neutrality as a requirement for new supported capability APIs. It places the previously agreed Network and Script/Logs APIs inside a broader, explicitly BiDi-shaped Layer 2, alongside additional conveniences and wrappers. Further, the boundaries between the proposed API layers, support contracts, and implementation layers are not clear to me.

Specific questions:

• Is Layer 2 fully supported and subject to our normal deprecation policy?
• Do generated CDDL methods/types belong to Layer 2 or Layer 3?
• Must Layer 1 depend on a public Layer 2, or can both use shared private orchestration?
• Is Layer 2 a bounded API inventory or a standing commitment to wrap future BiDi capabilities?

[AutomatedTester]

#17670 was supposed to be an easy win codifying the concept we've been working under for 2 years and proposing some specifics on the extent of the ramifications of it that we could quickly accept/reject.

While I get the sentiment, we need to appreciate how the spec has moved in that time. It has moved to align more with puppeteer/playwright while trying to make sure that classic webdriver could be written using bidi. A goal we all share.

The existing Selenium API plus specifically designed APIs for new capabilities such as Network and Script/Logs (what we've been calling the "High Level API").

Network and Logging to me are controversial as they fall in the "subscriptions" model of listen and act. Those I am happy to be driver. One thing to note is if we retrofit user contexts this could become tricky but we can probably compose webdriver better with a BrowsingContext, like Page as others use it. Script is an interesting use case as UserContext can really confuse things depending on where people want it. It can be on driver but when user contexts are added we need to make sure that people who do driver.executeScript("return document.cookies") only get their user context they're in which is where composition of driver will likely need changing.

Is Layer 2 fully supported and subject to our normal deprecation policy?

Yes

Do generated CDDL methods/types belong to Layer 2 or Layer 3?

I don't care enough here, happy with your orchestration example which is kinda 2. I merged the 3 into 2 in mine to make things more callable.

Must Layer 1 depend on a public Layer 2, or can both use shared private orchestration?

Yes, To me Layer 1 is "rewrite classic in Bidi" layer.

Is Layer 2 a bounded API inventory or a standing commitment to wrap future BiDi capabilities?

Layer 2 is a curated inventory, not a standing promise to wrap every future BiDi capability. New capabilities are always reachable immediately at Layer 3 (raw protocol); they only get a first-class Layer 2 module when a module ADR decides the ergonomics justify it, per the placement rule. So the durable commitment is the criterion for what earns Layer 2 surface — not an obligation to mirror the whole protocol. The list in this ADR is today's inventory, expected to grow by deliberate per-capability ADRs, not automatically.

[titusfortner]

I think we agree on Layer 1: existing Selenium APIs should be able to use WebDriver BiDi underneath, while preserving their current user-facing contracts.

If we can create a cddl-generated executable representation of the entire BiDi spec as (part of?) layer 3, then we wouldn't need a layer 2 to implement either layer 1 or the high level network/script APIs we've been discussing. Under that model what would you want layer 2 to look like?

I've been thinking of the "layers" in the context of how we support them:

1. Public: Selenium 4 API + High Level Network & Script APIs (includes user-facing implementation classes)
2. Private: Orchestration code for subscriptions, event dispatch, intercept mappings, collectors, lifecycle management, and other stateful coordination
3. Internal: cddl-generated executable code representing all modules, commands, parameters, types
4. Private: Transport code for WebSocket listening, command correlation, response queues, and send/receive handling.

Where Internal means publicly accessible but not "supported" which means not subject to our deprecation policy (implicitly if it is generated we don't control it, so I want us to declare it explicitly).

If the goal of Layer 2 is to extend the public surface to include more than just network/script, I'm ok with that, but I would like for us to be very cautious about how much more we're adding, the value it provides over the executable cddl-code and the extent to which it is bidi-protocol-shaped.

[AutomatedTester]

I think 2 and 3 can be merged for the most part as the whole point of the spec to be more stable than CDP.

[AutomatedTester]

Closing in favour of #17670