Source code
Revision control
Copy as Markdown
Other Tools
# Objects Replaced by Navigations
There are 3 major types of navigations, each of which can cause different
objects to be replaced. The general rules look something like this:
| Class/Id | [in-process navigations](#in-process-navigations) | [cross-process navigations](#cross-process-navigations) | [cross-group navigations](#cross-group-navigations) |
| --- | --- | --- | --- |
| BrowserId [^bid] | preserved | preserved | preserved |
| BrowsingContextWebProgress | preserved | preserved | preserved |
| BrowsingContextGroup | preserved | preserved | replaced |
| BrowsingContext | preserved | preserved | replaced |
| nsFrameLoader | preserved | replaced | replaced |
| RemoteBrowser | preserved | replaced | replaced |
| Browser{Parent,Child} | preserved | replaced | replaced |
| nsDocShell | preserved | replaced | replaced |
| nsGlobalWindowOuter | preserved | replaced | replaced |
| nsGlobalWindowInner | replaced [^inner] | replaced | replaced |
| WindowContext | replaced [^inner] | replaced | replaced |
| WindowGlobal{Parent,Child} | replaced [^inner] | replaced | replaced |
| Document | replaced | replaced | replaced |
[^bid]: The BrowserId is a unique ID on each `BrowsingContext` object, obtained
using `GetBrowserId`, not a class. This ID will persist even when a
`BrowsingContext` is replaced (e.g. due to
`Cross-Origin-Opener-Policy`).
[^inner]: When navigating from the initial `about:blank` document to a same-origin
document, the same `nsGlobalWindowInner`, `WindowContext` and
`WindowGlobal{Parent,Child}` may be used. This initial `about:blank`
document is the one created when synchronously accessing a newly-created
pop-up window from `window.open`, or a newly-created document in an
`<iframe>`.
## Types of Navigations
(in-process-navigations)=
### in-process navigations
An in-process navigation is the traditional type of navigation, and the most
common type of navigation when {ref}`Fission` is not enabled.
These navigations are used when no process switching or BrowsingContext
replacement is required, which includes most navigations with Fission
disabled, and most same site-origin navigations when Fission is enabled.
(cross-process-navigations)=
### cross-process navigations
A cross-process navigation is used when a navigation requires a process
switch to occur, and no BrowsingContext replacement is required. This is a
common type of load when {ref}`Fission` is enabled, though it is also used
Fission is disabled.
These process changes are triggered by `DocumentLoadListener` when it
determines that a process switch is required. See that class's documentation
for more details.
(cross-group-navigations)=
### cross-group navigations
A cross-group navigation is used when the navigation's [response requires
a browsing context group switch](https://html.spec.whatwg.org/multipage/origin.html#browsing-context-group-switches-due-to-cross-origin-opener-policy).
These types of switches may or may not cause the process to change, but will
finish within a different `BrowsingContextGroup` than they started with.
Like {ref}`cross-process navigations`, these navigations are triggered using
the process switching logic in `DocumentLoadListener`.
As the parent of a content browsing context cannot change due to a navigation,
only toplevel content browsing contexts can cross-group navigate. Navigations in
chrome browsing contexts [^chromebc] or content subframes only experience
either in-process or cross-process navigations.
As of the time of this writing, we currently trigger a cross-group navigation
in the following circumstances, though this may change in the future:
- If the [Cross-Origin-Opener-Policy](https://html.spec.whatwg.org/multipage/origin.html#the-cross-origin-opener-policy-header)
header is specified, and a mismatch is detected.
- When switching processes between the parent process, and a content process.
- When loading an extension document in a toplevel browsing context.
- When navigating away from a preloaded `about:newtab` document.
- When putting a `BrowsingContext` into BFCache for the session history
in-parent BFCache implementation. This will happen on most toplevel
navigations without opener relationships when the `fission.bfcacheInParent`
pref is enabled.
State which needs to be saved over cross-group navigations on
`BrowsingContext` instances is copied in the
`CanonicalBrowsingContext::ReplacedBy` method.
[^chromebc]: A chrome browsing context does **not** refer to pages with the system
principal loaded in the content area such as `about:preferences`.
Chrome browsing contexts are generally used as the root context in a chrome
window, such where `browser.xhtml` is loaded for a browser window.
All chrome browsing contexts exclusively load in the parent process and
cannot process switch when navigating.