Repository navigation
2026 11 18 tabs design
History. Drafted 2026-11-18 for issue #178, a prerequisite of sub-sessions (#94, ACT-43). Dr K's rulings are 1 to 7 below. Shipped as
taband the automatic popup follow. What it asked for now lives in ACT-45 to ACT-53 in browser-actions.md, WS-76 in workspaces-and-sessions.md and FLOW-59 in saved-flows.md. Nothing in it was overtaken; the BiDi action layer and transport setting stay with #177. The build is the tabs plan.
A browser holds tabs, and a page can open a popup, such as an SSO sign-in. selenium-flow knows one window. A popup is invisible to the agent, and the next call still acts on the window it was in. Nothing lists, opens, switches to or closes a tab, and once the current window closes, every call fails until the browser is ended. Sub-sessions (#94) assume each session can follow its own popups, so this comes first.
- Every action acts on WebDriver's current window. No code reads or switches window handles.
- Each browser has a BiDi socket, used by capture, the monitor and site data.
browsingContext.getTreeover it lists the top-level contexts with their URLs, without switching (monitor/monitor.py,site_data/transfer.py). WebDriver BiDi defines a classic window handle as the same string as its browsing context id. - One row of
core.capabilities.CAPABILITIESis an MCP tool, a REST route and a flow step, and each ends in one method ofcore.actions.Actions(ACT-42, FLOW-7). - MCP and REST calls go through
Workspaces.act, which holds the session's turn and notes where the result says the browser is (_arrived): secret scope follows the result'surl. Flow steps call theActionsmethod directly, andHooks.in_scoperuns after each step, still inside the run's turn. -
workspace://currentreadsin_frameandwindowlive from the browser when it is live (WS-43), and every key it carries is listed inCONTEXT_KEYS(WS-64).
-
A
tabtool:tab(action="list" | "open" | "switch" | "close", id=…, url=…). Every other tool acts on the current tab, as now. - Popups are followed automatically. A tab that appears becomes the current tab: the newest, when several appear. When the current tab closes, the session goes back to the tab it came from, or to the newest one left when that one is gone too.
-
A tab's id is short:
t1,t2, … kept in the session's record and never reused while that browser lives. A new browser starts again att1. -
Flows reach a popup without knowing its id:
switchwith noidgoes to the newest tab, andswitchwithurlgoes to the tab whose URL contains that text. - Background tabs are mentioned once, in the tool's description. Chrome stops rendering a tab that is not in front, and Firefox throttles its timers. Results carry nothing about it.
-
The context always shows the tabs:
workspace://currentandworkspace://current/tabs. -
Flows may use it.
tabis a capability row, so it is a step like any other (FLOW-7). A flow follows popups within its own session only (#94's ruling).
click(selector={"css": "#sso"})
→ {"url": "https://sso.example/login", "title": "Sign in", "tab": "t2",
"opened": [{"tab": "t2", "url": "https://sso.example/login"}], ...}
write(...); click(...) # the popup submits and closes itself
→ {"url": "https://shop.test/account", "title": "Account", "tab": "t1", "closed": ["t2"], ...}
tab(action="list")
→ {"tabs": [{"tab": "t1", "url": "https://shop.test/account", "title": "Account", "current": true}]}
tab(action="open", url="https://shop.test/help")
→ {"tab": "t3", "url": "https://shop.test/help", "title": "Help", ...}
tab(action="switch", id="t1") # or url="shop.test/account", or no id: the newest
tab(action="close", id="t3") # no id: the current tab
-
tabis in a result only when the current tab changed during the call. Atabcall always carries it. -
openedandclosedare in a result only when non-empty. - When the session moved, the result's
urlandtitleare the new current tab's, so the origin the server notes, and secret scope with it, follow the move.
Every call on the browser, whether a tool, a route or a flow step, checks the tabs before it acts and again after:
- Before: a popup that opened after the last call, or a current tab that closed since then (by the page, or by a person in control), is caught before the call acts. The call then acts on the tab the session moved to, and its result says so.
- After: a tab the call opened is followed, and a current tab the call closed is left.
A check is one browsingContext.getTree over BiDi (window_handles only when BiDi cannot
answer), compared with the tabs the server knows for that browser. They are kept in the store under the Grid session id, beside the workspace's record and
with its TTL, never inside it:
# selenium-flow:tabs:<grid session id>
next: 4 # the next id is t4
current: t1
known: # in the order first seen
- {tab: t1, handle: 4F2A…, from: null}
- {tab: t3, handle: 9C11…, from: t1}Keyed by the browser, the state starts empty for every new browser, so ids restart at t1 with
no reset step and no migration of old records. It never contends with the record's own
compare-and-set writes. A handle the server has not seen gets the next id, with from set to the
tab that was current when it appeared. Several handles first seen together get ids in the order
the browser lists them. Newest always means the highest id.
list and the context give each tab's url and title, read without switching: URLs from
browsingContext.getTree, titles from one script.evaluate of document.title per tab over
BiDi. When BiDi cannot answer, the current tab is read over classic and the others are left with
url and title null. The order is opening order.
-
The last tab:
closeon it is refused, sayingend_browserends the browser. -
Unknown id, or no tab matches
url: a 400 that lists the tab ids and URLs. -
idandurltogether: refused, as two selectors are (ACT-2's style). -
A switch leaves any frame: WebDriver puts the session at the top of the new tab, so a
tabresult carriesin_frame: false. -
A tab closed in the middle of a call: a popup whose submit closes it is the common case. The
action has already happened, so reading the page after it does not fail. The session moves
(ruling 2), and the result carries the new tab's page and
closed. An action that fails because its window vanished before it could act fails with a message naming the tab the session is now on. In a flow, that step fails like any other, and itsonErrorapplies. -
What is browser-wide stays browser-wide: downloads, capture (console and network across all
tabs), recording and site data.
outline,screenshotandprintact on the current tab only. -
The visible tab: the live view and the recording show whichever tab is in front. The
current tab must be the one in front, so a person sees what the agent acts on. It is brought
there with
browsingContext.activate, which keeps the session's frame. A classicswitch_to.window, even to the window the session is already on, puts it back at the top page (measured on Chrome 152 and Firefox 155), so the driver switches only when it is on another window. Without BiDi, no tab is brought forward. - A person switching tabs in the live view does not move the session: WebDriver's current window is unchanged. The next call still acts on the session's current tab, which is then brought back to the front. This is Claude's call, and the simplest rule a person can predict.
- Checking at both ends of every call. Following only after a call would leave a late popup's first call on the wrong tab.
-
tabonly on change, andopened/closedonly when non-empty, to keep results short. - Following moves the result's
urlandtitle, because secret scope is keyed on the result's URL. -
switchwithurltakes the newest matching tab. - Titles over BiDi, falling back to null rather than switching to read them. A switch would move the visible tab and change what Chrome renders.
-
Where the check runs. One method on
Actions,check_tabs(session_id), reads the handles, reconciles them with the stored state, switches when following, and answers what changed. TheActionsobject is given the tab store when it is built. The MCP/REST bracket (_said) calls it before and after the call. The flow engine calls it around each step, since steps bypassact.tabitself is an ordinaryActionsmethod using the same store. -
The check runs before secret scope is read. In
_said, the before-check comes beforeorigins.currentis read. A move is noted as an arrival (its URL andin_framefalse). The call is then scrubbed with the origin it actually acted on. A flow step does the same. -
Any result where the session moved carries
in_frame: false, not onlytabresults. That way the noted frame state is corrected. -
A popup that opens and closes within one call is never seen by either check. It gets no
id and is not reported. Capture's
browsingContextevents could tell it later. -
Handle equals BiDi context id is measured first, on Chrome 152 and Firefox 155 behind the
Grid, and holds on both. The check lists the tabs from
getTreeand activates by context id, so it relies on it. Chrome holdswindow_handleswhile a popup loads a host that never answers;getTreeanswers at once. -
One BiDi channel per check. A check, or a
tabcall, lists and activates over one channel. When BiDi will not open or answer, that browser's checks usewindow_handlesalone for 30 s, so a route that hangs costs one call its timeout, not every call. -
An action's own
urlnavigates the tab that is current after the before-check.tab'surlis a match text forswitchand a load target foropen. No sharedurlhandling may treat it as a navigation. -
window, the window size in the record and the context, is untouched. The context gains onlytabs.
- The admin UI. A tab list on the Session tab is a later round.
- Separate windows.
openmakes a tab, never a new window. - The BiDi action layer and the transport setting, which are #177.
- Filtering capture by tab.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network