Update spec to define things in terms of Navigables

[jgraham]

whatwg/html#6315 is going to update the HTML spec to change the session history model, and introduce the concept of "navigables" which correspond to things in the browser that can be navigated. "Top-level navigables" are (usually) tabs and windows in the browser UI.

This concept of "top-level navigable" is exactly what WebDriver means by "window", and is in fact a better match for what we want to expose in the API than "top-level browsing context". That's because the top-level browsing context in a particular tab can change over time (e.g. with COOP/COEP). We don't necessarily need to expose those changes to the user, and in particular want to expose an identifier that's constant over the full life of the tab/window.

It's not clear to me if we should update everything related to browsing contexts to instead expose navigables (with or without changing all the naming), or if we should expose both seperately.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Using navigable terminology.

The full IRC log of that discussion

<AutomatedTester> topic: Using navigable terminology
<AutomatedTester> github: https://github.com//issues/91
<AutomatedTester> jgraham: in the spec we have the browsing context module
<AutomatedTester> ... [describes how this changes in the site isolation case]
<AutomatedTester> ... Jake Archibald is improving the html spec around navigable terminology
<AutomatedTester> ... so what changes do we want to make?
<AutomatedTester> ... we have the browser context id and in webdriver http we use it for navigation
<AutomatedTester> ... should we change the concept of browsing context module to a navigable object?
<AutomatedTester> q?
<foolip> q+
<AutomatedTester> ack foolip
<AutomatedTester> foolip: I just had a quick look at Jakes PR
<AutomatedTester> ... could you summarize what this means for us?
<AutomatedTester> ... or we can change the name or...
<AutomatedTester> jgraham: I don't know how this works for iframes but I think the relationship is that a browsing context lives within a navigable
<AutomatedTester> ... I think this is how it works
<AutomatedTester> ... a navigable will own a series of browsing contexts as you traverse history
<AutomatedTester> foolip: and this clarifies that a navigable is not similar to browsing context
<AutomatedTester> ... and we need to adapt to be more like html
<AutomatedTester> jgraham: and perhaps my bias is kicking in and I need to double check everything
<AutomatedTester> ... I think we can just replace browsing context here with navigable for how we want to use it
<AutomatedTester> ... one use case we need to think about is if I return a window handle via executescript should it return a navigable or the window id? how would that work
<AutomatedTester> q?
<AutomatedTester> ... I don't think we need to decide now but we need to sort this soon as it will be a backwards breaking change
<AutomatedTester> ... so if we can try have an opinion soon

[foolip]

Since there's a "top-level navigable" I take it there's a tree of navigables. Does every navigable have a browsing context, and do browing contexts still form a tree by themselves, or only implicitly by each one belonging to a navigable. I'm hoping that we only need to expose one "frame tree".

[jgraham]

I think there's one tree at any given point in the session history. https://github.com/whatwg/html/pull/6315/files#diff-41cf6794ba4200b839c53531555f0f3998df4cbb01a4d5cb0b94e3ca5e23947dR82662-R82678 defines the properties of a navigable and if I've understood correctly, a navigable holds a list of browsing sessions, which hold a list of browsing contexts, but at any given time there's a 1:1 relationship between the active browsing contexts and navigables, however when you navigate through history the actual context changes.

Maybe @jakearchibald could confirm that's correct.

I think where we want to end up is that we use something that maps to navigable as the concept we expose to users as the handle to a specific tab/frame. In terms of selecting where commands should run, or where events originated the fact that they can only happen in active contexts means that we can unambiguously use navigables everywhere.

One question is what should happen if you run a script like return window. We want some way to get a handle that you can then pass into other commands e.g. so you can something like let frame_id = session.execute_script("return frames[0]", navigable=top_level_id).await.navigable; session.navigate("http://example.org", navigable=frame_id);. But it weould be weird if after the navigation returning the WindowProxy object from the new frame ended up with an indistinguishable response even though it refers to a different object. Maybe it should return something with both an object id that refers to the actual window object, and also an id of the navigable that you can use for other commands.

Another question is whether we want to actually use the term Navigable or if that's too obscure. I think my preference is to try to align with the spec terminology where possible, even if that isn't already familiar to client authors (I find the use of e.g. Page in CDP confusing, because it's hard to know what it actually represents).

[jakearchibald]

The idea is that a navigable has a current session history entry. The session history entry will have the browsing context & document.

The top-level navigable is "traversable", meaning it manages the session history of itself and nested navigables. It holds all the session history entries for itself and all nested navigables. It's responsible for assigning a session history entry to the current session history entry for a navigable.

I'm not set on this naming in case you have better ideas.

[jakearchibald]

a navigable holds a list of browsing sessions

I had to change this relatively recently. It doesn't make sense for a navigable to hold its own session history, since the navigable can be destroyed (eg, an iframe when the parent page is unloaded) and later the session history can be reapplied to a different navigable (eg, an iframe when the parent page is reloaded by going 'back').

Now all the history data is in the "traversable" navigable, which is usually top-level (although that might not be true with prerender) https://github.com/whatwg/html/pull/6315/files#diff-41cf6794ba4200b839c53531555f0f3998df4cbb01a4d5cb0b94e3ca5e23947dR82753

[jgraham]

This HTML PR has merged!

So we need to audit BiDi to make sure we're correctly making the distinction between Browsing Context and Navigable. I think at the moment we are using context to mean both, although typically more in line with Navigable than Browsing Context, but there are probably also cases where we really mean the latter.

A question is whether, in cases where the context parameter is really about a specific navigable, are we in a position to change the protocol to match the newer terminology, or do we just have to document how we're using the term.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Update spec to define things in terms of Navigables.

The full IRC log of that discussion

<jgraham> topic: Update spec to define things in terms of Navigables
<jgraham> github: https://github.com//issues/91
<sadym> q+
<AutomatedTester> q+
<brwalder> jgraham: Navigables have been added to the HTML spec to represent a "window" that has history. We've been using browsing contexts for this concept so far. Navigables do a better job of expressing cross-origin navigations. Browsing contexts are more relevant for script where you care about what context code was evaluated in. Should we introduce the navigable concept to bidi and differentiate between these somehow?
<jgraham> ack sadym
<brwalder> sadym: Is there a 1:1 mapping between browsing context and document?
<brwalder> jgraham: A frame is a navigable because you can navigate a frame. A browsing context is 1:1 with a window proxy.
<jgraham> q?
<jgraham> ack AutomatedTester
<sadym> q+
<brwalder> AutomatedTester: How many clients are using bidi right now that could be broken by this change? Seems like this number is small so we should just make the change and notify clients.
<jgraham> ack sadym
<cb> WebdriverIO will have Bidi support with upcoming v8 release so from my side I think it will be fine to go with the breaking change.
<brwalder> sadym: Could we simply rename current usage of browsing context -> navigable and find a different name for browsing contexts?
<brwalder> jgraham: Yes this should be possible and could help implement this without a breaking change.
<sadym> q+
<brwalder> jgraham: Let's investigate soon and see if we can do this in a non-breaking way.
<jgraham> ack sadym
<brwalder> sadym: People who have started experimenting with bidi will be impacted by the change.
<brwalder> AutomatedTester: The Selenium community is creating some new clients for bidi and we have a short window to address this before the change becomes risky.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Update spec to align with HTML changes.

The full IRC log of that discussion

<jgraham> Topic: Update spec to align with HTML changes
<jgraham> GitHub: https://github.com//issues/91
<jgraham> jgraham: The HTML spec has been updated with navigables taking on the role of "things that can be navigated" which we previously called [Browsing] Contexts. Proposal is that we use the `context` name in parameters to refer to a navigable and document that it's a legacy feature. For cases where we really want to refer to a specific document/window we could use the sharedId of the Document. Then a
<jgraham> question is if we're OK with keeping the `browsingContext` module name, given that it doesn't really mean that, or if we think it's worthwhile to change it now.
<whimboo> q+
<jgraham> ack whimboo
<simons> q+
<jgraham> whimboo: Would it be possible to have a context module and some kind of alias to keep compatibility for a while?
<jgraham> whimboo: Especially for events.
<sadym> q+
<jgraham> jgraham: I think it's theoretically possible, but it might be a lot of effort; not sure if it would be worthwhile
<jgraham> ack simons
<jgraham> simons: I think there are few enough implementations that we could do the rename now and it would be reasonably safe.
<jgraham> ack sadym
<whimboo> q+
<jgraham> sadym: From our perspective we can change the naming, the question is what's a good naming.
<jgraham> jgraham: context in parameters, or browsingContext the module name?
<jgraham> sadym: browsingContext in the module name is confusing
<jgraham> ack whimboo
<jgraham> whimboo: How much of BiDi is already shipping in Selenium? Could that cause problems if browsers change?
<jgraham> simons: We ship every six weeks. The functionality isn't being used much yet, so I think it will be fine to make a change now. We can communicate the information to users if needed. It's not ideal, but it's not yet in heavy use and it's still marked as experimetnal, so people should be able to upgrade quickly.
<jgraham> whimboo: Each browser should try to do this change at the same time.
<jgraham> simons: That would help, but we can also pin browsers until everyone has made the change. It would be nice for everyone to upgrade at the same time.
<sadym> q+
<jgraham> ack sadym
<jgraham> sadym: There is a way to pin the specific versions of browsers in selenium?
<jgraham> simons: Selenium ships with Selenium-Manager which will download the requested version of a browser if people specify it. It's not like Puppeteer where there's a 1:1 correspondence between the library and the browser.
<jgraham> jgraham: Sounds like if we made the change now we could all agree to ship in the new year. But we need to agree a name.
<jgraham> whimboo: What are the options?
<jgraham> jgraham: context, page, …
<jgraham> whimboo: navigable might not be stable over time, context seems pretty generic
<jgraham> jgraham: I will write this up on the PR
<sadym> target
<sadym> q+

[whimboo]

As we agreed on in the W3C meeting on Dec 14th 2022, we want to rename the browsingContext module to context.

I talked with @jgraham and he will work on a PR soon.

[whimboo]

As time passed by we now have clients implementing WebDriver BiDi and have picked up the module names, e.g. WebDriverIO automatically generates TypeScript code based on the CDDL definition.

As discussed with @jgraham it's most likely too late to make that change. Instead a section should be added to the BiDi spec explaining that the browsingContext term is outdated and basically refers to Navigable those days.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Final decision if browsingContext module should be renamed or not, and agreed to the following:

• ACTION: documenting navigable properly in the spec with browsing context

The full IRC log of that discussion

<AutomatedTester> Topic: Final decision if browsingContext module should be renamed or not
<AutomatedTester> github: https://github.com//issues/91
<AutomatedTester> jgraham: A while we discussed that the browsing context doesn't match what the html spec has
<shs96c> q+
<orkon> q+
<AutomatedTester> ... I think we are reaching a point that renaming it is going to start annoying people
<AutomatedTester> ... and in spec land people might notice but not care
<AutomatedTester> ... so we can see about leaving it and just going through the spec and make sure that everything is documented properly
<AutomatedTester> ack next
<AutomatedTester> shs96c: I would advocate that make sure the name is correct rather than telling people in the spec that the term is correct
<AutomatedTester> ... I think we should be thinking that the spec will be around for years
<AutomatedTester> ... so we have the opportunity so we should take it
<AutomatedTester> ack next
<AutomatedTester> orkon: is browsing context still used in the html spec? Has it been replaced by navigable?
<AutomatedTester> jgraham: a document still has a browsing context in some circumstances
<AutomatedTester> ... there are cases when the routing can change things
<AutomatedTester> ... navigable is conceptually the tab/iframe
<AutomatedTester> orkon: There is a discussion item later about prerendering
<AutomatedTester> ... so if we keep browsing context in there . If we don't change it how will it be with that?
<AutomatedTester> jgraham: I would surprised if they have multiple browsing contexts
<AutomatedTester> ... I think navigable can only have 1 session history entry
<jcraig> s/a11y engine is part of web rendering engine/each web rendering engine maintains an internal model of accessibility before it exposes it to the platform-specific accessibility APIs/
<AutomatedTester> ... and 1 active document
<AutomatedTester> orkon: on our side we would like to prefer not to rename things due to the amount of work
<AutomatedTester> ... but for future ambiguity then perhaps we should probably fix it
<AutomatedTester> ... I think it's constrained on the spec work
<jcraig> s/In the context of automation there is platform-specific automation. AT-driver will be later today. /In separate contexts, there is platform-specific automation and AT automation. Lola and Matt's AT-Driver session will be later this afternoon. Not directly related to this request. /
<AutomatedTester> jgraham: <describes the spec work involved... tl;dr; it's not find/replace>
<jcraig> s/Some existing solutions here with DOM as source of truth./Some other existing "client-side automation" solutions (like Deque's Axe-Core) treat the DOM as source of accessibility truth./
<AutomatedTester> ... we would need to see if we can find someone that do the spec work and then coordinating the amount of work that is also doing the tests
<jcraig> s/Want to test conflicts e.g. required vs aria-required. /In addition to the 50+ other aria attributes, we want to test conflicts with host language attributes... e.g. required vs aria-required on the same element. /
<AutomatedTester> ... we can't defer this any longer
<AutomatedTester> ... the amount of work on this part of thinks this is not worth it and we might have html churn things again the future
<jcraig> s/Stakeholders agree on the goals in those issues. /I think all the stakeholders involved in 197 agree on the following goals. /
<AutomatedTester> ... but we need to make sure that navigable is documented properly
<orkon> agreed not to rename
<AutomatedTester> shs96c: I suggest leaving things as is and adding action on documenting navigable properly
<AutomatedTester> ACTION: documenting navigable properly in the spec with browsing context
<jcraig> s/neither is a11y tooling itself./neither is assistive technology (AT, e.g screen readers) automation itself. (Caveat: Driving AT is obvs in scope for separate issue: AT Driver)/