Skip to content

[docs] decision: browsing contexts are exposed as handle objects#17681

Open
AutomatedTester wants to merge 3 commits into
trunkfrom
adr-bidi-context-handles
Open

[docs] decision: browsing contexts are exposed as handle objects#17681
AutomatedTester wants to merge 3 commits into
trunkfrom
adr-bidi-context-handles

Conversation

@AutomatedTester

Copy link
Copy Markdown
Member

💥 What does this PR do?

Proposes a design decision record: browsing contexts are exposed as handle objects.

Working with multiple tabs/windows over BiDi is awkward because there is no object representing a single browsing context — every operation is called on one shared module instance and takes the context id explicitly (browsing_context.navigate(context=id, ...)). For parallel work this means each worker repeats context= bookkeeping against shared state, with no per-tab unit to own. This record proposes a per-context handle object (returned by create/get_tree/expect_page) that carries the per-context operations as methods and scopes events to that context — matching the Playwright model where operations live on the object, which is exactly what makes one-context-per-worker parallelism clean. The flat module API stays as the compatibility surface.

🔧 Implementation Notes

🤖 AI assistance

  • AI assisted (complete below)
    • Tool(s): Claude Code
    • What was generated: Initial draft of the decision record, derived from a review of the current browsing_context surface and BiDi transport against Playwright's object/concurrency model; revised through discussion and review
    • I reviewed all AI output and can explain the change

💡 Additional Considerations

Extends the set of BiDi ergonomics decision records (#17671#17677) with the parallelisation/object-model concept. The cross-binding name of the handle (Page-like / Tab / BrowsingContextHandle) is part of what's being decided. Cross-binding convergence is tracked in the binding-status table.

🔄 Types of changes

  • Documentation (design decision record)

@AutomatedTester AutomatedTester force-pushed the adr-bidi-context-handles branch from 7a177ac to 6b5f6f8 Compare June 15, 2026 09:08
@AutomatedTester AutomatedTester added the A-needs decision TLC needs to discuss and agree label Jun 15, 2026
Add user contexts (BiDi isolation unit) to the handle object model rather
than a separate record: isolated= shortcut for the common case, the
create_user_context() factory for shared partitions, session-option
inheritance, and internal/private isolation types. Rename the file to use
the PR number (17681) instead of an ADR number.
… contextCreated

Point cross-references at the PR-number filenames, add expect_popup to the
return-type change note, and list browsingContext.contextCreated (which backs
expect_page/expect_popup) in the appendix for consistency with 17671.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-needs decision TLC needs to discuss and agree

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant