Document, Window, BrowsingContext

Three closely related primitives anchor Gecko's view of the web:

Type	Lifetime	Role
Document (dom/base/Document.h)	One per loaded HTML/XHTML/SVG document	Root of the DOM tree
Inner / Outer Window (dom/base/nsGlobalWindowInner.h, dom/base/nsGlobalWindowOuter.h)	Outer survives navigations; inner is recreated	The JS global; window.foo
BrowsingContext (docshell/base/BrowsingContext.h)	One per tab/iframe; shared across processes	The web's "browsing context" concept

Why three types

The HTML spec separates the browsing context (the navigable thing — a tab, an iframe), the WindowProxy (the cross-origin-aware proxy), and the Window itself. Gecko mirrors that, and adds the inner/outer split to keep the JS global stable across in-place navigations like back/forward bfcache.

How they relate

graph LR
    BC[BrowsingContext<br/>per-tab/iframe<br/>shared across processes] --> Outer[Outer Window<br/>nsGlobalWindowOuter]
    Outer -->|swap on navigation| Inner1[Inner Window 1<br/>page A]
    Outer -. later .-> Inner2[Inner Window 2<br/>page B]
    Inner1 --> Doc1[Document A]
    Inner2 --> Doc2[Document B]

• Inner Window holds the JS global object. It's destroyed on navigation; a new one is created for the next page.
• Outer Window is the proxy script holds onto. It outlives navigations.
• BrowsingContext is the cross-process replicated object. Each process that hosts content for a tab has a BrowsingContext for it; they synchronize state via IPDL.
• CanonicalBrowsingContext (docshell/base/CanonicalBrowsingContext.h) is the parent-process authoritative copy.

Document lifecycle

A Document is created when content starts loading, transitions through interactive/complete, and is destroyed when its window is unloaded. The nsContentDLF (nsContentDLF.cpp) is the document loader factory that picks the right document subclass (HTML, SVG, …).

Common operations

• nsContentUtils::GetCurrentJSContext() — get the active JSContext.
• Document::GetWindow() — current inner window.
• Document::GetBrowsingContext() — owning context.
• BrowsingContext::Get(uint64_t) — look up by ID.
• WindowGlobalParent::GetByInnerWindowId(...) — parent-side lookup.

Related

• DOM
• Process model
• Fission