[docs] decision: storage exposes a typed cookie API and storage_state save/restore

[AutomatedTester]

💥 What does this PR do?

Proposes a design decision record: storage exposes a typed cookie API and storage_state save/restore.

BiDi cookies use an awkward wire shape (value is a BytesValue descriptor, partitioning via a descriptor), so the common "set a session cookie" case carries needless ceremony. And the most-requested workflow — log in once, capture state, restore it to skip login in later sessions (Playwright's storage_state) — has no Selenium equivalent. This record proposes a typed Cookie value for set_cookie/get_cookies plus a save_state/load_state pair, while being explicit that cookies come from the BiDi protocol whereas localStorage is captured via script.evaluate and IndexedDB is out of scope.

🔧 Implementation Notes

• Follows the docs/decisions/ process from [docs] add design decision record process and template #17665 — depends on [docs] add design decision record process and template #17665 landing (adds only docs/decisions/0003-*.md).
• Cookies are fully BiDi; web storage is not in the spec, so storage_state captures localStorage by evaluating script per origin — the record documents this split deliberately rather than implying uniform protocol support.
• No wire-protocol change.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial draft of the decision record, derived from a CDDL-validated comparison of the Python BiDi surface against Playwright; revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

One of a set of BiDi ergonomics decision records proposed together. The cookie convenience and storage_state are kept in one record as a single cohesive storage-ergonomics decision; reviewers who prefer them split can request that. Cross-binding convergence is tracked in the binding-status table.

🔄 Types of changes

• Documentation (design decision record)

[diemol]

I know we have in some bindings the storage namespace for BiDi. So, unless I am wrong, we are assuming a new top-level namespace in this ADR (driver.storage), but driver.manage().addCookie() already exists and does the same job from the user point of view.

Unless this ADR refers to a middle-layer API, we should agree on which strategy:

Option A: Explicit BiDi API. driver.storage is for BiDi sessions. Classic APIs stay for Classic sessions. Users opt in knowingly. Eventually, we need to migrate users from one to the other.

Option B: Transparent abstraction. The high-level API stays unified, and the binding picks Classic or BiDi under the hood. Then, driver.storage should be an internal or middle-layer API.

This pattern repeats across every module in this series (navigation, network, emulation, etc.), so the answer affects all of them.

[AutomatedTester]

You've put your finger on the cross-cutting question exactly, and I think it deserved a decision of its own rather than being answered ad-hoc in each module ADR — so I've written up #17709 ("BiDi is exposed in three API layers") to settle it for the whole series.

Short version: it's both A and B, layered.

• Layer 1 — the unified high-level API. driver.manage().addCookie() stays the primary surface and, when a BiDi session is active, becomes BiDi-backed under the hood (your Option B). Users don't change their code or learn a namespace.
• Layer 2 — explicit BiDi modules. driver.storage (this ADR) is the power-user tool beside the Classic cookie API, not a replacement — your "then driver.storage should be a middle-layer API." It's where things with no Classic shape live: storage_state save/restore, and partition-scoped cookies (targeting a specific user context, which manage().addCookie() can't express).

I've added a line to this ADR's Context declaring it a Layer 2 decision. Could you take a look at #17709? If we agree on the layering there, this one (and navigation/network/emulation) stop competing with the Classic surface — which I think is what made them feel like duplicate namespaces.