4 files changed, 346 insertions, 0 deletions
diff --git a/dom/docs/navigation/BrowsingContext.rst b/dom/docs/navigation/BrowsingContext.rst
new file mode 100644
index 0000000000..213b2fcce5
--- /dev/null
+++ b/dom/docs/navigation/BrowsingContext.rst
@@ -0,0 +1,149 @@
+BrowsingContext and WindowContext
+=================================
+
+The ``BrowsingContext`` is the Gecko representation of the spec-defined
+`Browsing Context`_ object.
+
+.. _Browsing Context: https://html.spec.whatwg.org/multipage/browsers.html#browsing-context
+
+
+The Browsing Context Tree
+-------------------------
+
+``BrowsingContext`` and ``WindowContext`` objects form a tree, corresponding
+to the tree of frame elements which was used to construct them.
+
+
+Example
+^^^^^^^
+
+Loading the HTML documents listed here, would end up creating a set of BrowsingContexts and WindowContexts forming the tree.
+
+.. code-block:: html
+
+  <!-- http://example.com/top.html -->
+  <iframe src="frame1.html"></iframe>
+  <iframe src="http://mozilla.org/"></iframe>
+
+  <!-- http://example.com/frame1.html -->
+  <iframe src="http://example.com/frame2.html"></iframe>
+
+  <!-- http://mozilla.org -->
+  <iframe></iframe>
+  <iframe></iframe>
+
+.. digraph:: browsingcontext
+
+  node [shape=rectangle]
+
+  "BC1" [label="BrowsingContext A"]
+  "BC2" [label="BrowsingContext B"]
+  "BC3" [label="BrowsingContext C"]
+  "BC4" [label="BrowsingContext D"]
+  "BC5" [label="BrowsingContext E"]
+  "BC6" [label="BrowsingContext F"]
+
+  "WC1" [label="WindowContext\n(http://example.com/top.html)"]
+  "WC2" [label="WindowContext\n(http://example.com/frame1.html)"]
+  "WC3" [label="WindowContext\n(http://mozilla.org)"]
+  "WC4" [label="WindowContext\n(http://example.com/frame2.html)"]
+  "WC5" [label="WindowContext\n(about:blank)"]
+  "WC6" [label="WindowContext\n(about:blank)"]
+
+  "BC1" -> "WC1";
+  "WC1" -> "BC2";
+  "WC1" -> "BC3";
+  "BC2" -> "WC2";
+  "BC3" -> "WC3";
+  "WC2" -> "BC4";
+  "BC4" -> "WC4";
+  "WC3" -> "BC5";
+  "BC5" -> "WC5";
+  "WC3" -> "BC6";
+  "BC6" -> "WC6";
+
+
+Synced Fields
+-------------
+
+WIP - In-progress documentation at `<https://wiki.mozilla.org/Project_Fission/BrowsingContext>`_.
+
+
+API Documentation
+-----------------
+
+.. cpp:class:: BrowsingContext
+
+  .. hlist::
+    :columns: 3
+
+    * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.h>`_
+    * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.cpp>`_
+    * `html spec <https://html.spec.whatwg.org/multipage/browsers.html#browsing-context>`_
+
+  This is a synced-context type. Instances of it will exist in every
+  "relevant" content process for the navigation.
+
+  Instances of :cpp:class:`BrowsingContext` created in the parent processes
+  will be :cpp:class:`CanonicalBrowsingContext`.
+
+  .. cpp:function:: WindowContext* GetParentWindowContext()
+
+    Get the parent ``WindowContext`` embedding this context, or ``nullptr``,
+    if this is the toplevel context.
+
+  .. cpp:function:: WindowContext* GetTopWindowContext()
+
+    Get the toplevel ``WindowContext`` embedding this context, or ``nullptr``
+    if this is the toplevel context.
+
+    This is equivalent to repeatedly calling ``GetParentWindowContext()``
+    until it returns nullptr.
+
+  .. cpp:function:: BrowsingContext* GetParent()
+
+  .. cpp:function:: BrowsingContext* Top()
+
+  .. cpp:function:: static already_AddRefed<BrowsingContext> Get(uint64_t aId)
+
+    Look up a specific ``BrowsingContext`` by it's unique ID. Callers should
+    check if the returned context has already been discarded using
+    ``IsDiscarded`` before using it.
+
+.. cpp:class:: CanonicalBrowsingContext : public BrowsingContext
+
+  .. hlist::
+    :columns: 3
+
+    * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.h>`_
+    * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.cpp>`_
+
+  When a :cpp:class:`BrowsingContext` is constructed in the parent process,
+  it is actually an instance of :cpp:class:`CanonicalBrowsingContext`.
+
+  Due to being in the parent process, more information about the context is
+  available from a ``CanonicalBrowsingContext``.
+
+.. cpp:class:: WindowContext
+
+  .. hlist::
+    :columns: 3
+
+    * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.h>`_
+    * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.cpp>`_
+
+.. cpp:class:: WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent
+
+  .. hlist::
+    :columns: 3
+
+    * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.h>`_
+    * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.cpp>`_
+
+.. cpp:class:: WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild
+
+  .. hlist::
+    :columns: 3
+
+    * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.h>`_
+    * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.cpp>`_
diff --git a/dom/docs/navigation/embedding.rst b/dom/docs/navigation/embedding.rst
new file mode 100644
index 0000000000..b213b03ea4
--- /dev/null
+++ b/dom/docs/navigation/embedding.rst
@@ -0,0 +1,93 @@
+Browsing Context Embedding
+==========================
+
+Embedder Element to nsDocShell
+------------------------------
+
+In order to render the contents of a ``BrowsingContext``, the embedding
+element needs to be able to communicate with the ``nsDocShell`` which is
+currently being used to host it's content. This is done in 3 different ways
+depending on which combination of processes is in-use.
+
+- *in-process*: The ``nsFrameLoader`` directly embeds the ``nsDocShell``.
+- *remote tab*: The parent process is the embedder, and uses a ``PBrowser``,
+  via a ``BrowserHost``. The ``BrowserChild`` actor holds the actual
+  ``nsDocShell`` alive.
+- *remote subframe*: A content process is the embedder, and uses a
+  ``PBrowserBridge``, via a ``BrowserBridgeHost`` to communicate with the
+  parent process. The parent process then uses a ``BrowserParent``, as in the
+  *remote tab* case, to communicate with the ``nsDocShell``.
+
+Diagram
+^^^^^^^
+
+.. digraph:: embedding
+
+  node [shape=rectangle]
+
+  subgraph cluster_choice {
+    color=transparent;
+    node [shape=none];
+
+    "In-Process";
+    "Remote Tab";
+    "Remote Subframe";
+  }
+
+  "nsFrameLoaderOwner" [label="nsFrameLoaderOwner\ne.g. <iframe>, <xul:browser>, <embed>"]
+
+  "nsFrameLoaderOwner" -> "nsFrameLoader";
+
+  "nsFrameLoader" -> "In-Process" [dir=none];
+  "nsFrameLoader" -> "Remote Tab" [dir=none];
+  "nsFrameLoader" -> "Remote Subframe" [dir=none];
+
+  "In-Process" -> "nsDocShell";
+  "Remote Tab" -> "BrowserHost";
+  "Remote Subframe" -> "BrowserBridgeHost";
+
+  "BrowserHost" -> "BrowserParent";
+  "BrowserParent" -> "BrowserChild" [label="PBrowser" style=dotted];
+  "BrowserChild" -> "nsDocShell";
+
+  "BrowserBridgeHost" -> "BrowserBridgeChild";
+  "BrowserBridgeChild" -> "BrowserBridgeParent" [label="PBrowserBridge", style=dotted];
+  "BrowserBridgeParent" -> "BrowserParent";
+
+nsDocShell to Document
+----------------------
+
+Embedding an individual document within a ``nsDocShell`` is done within the
+content process, which has that docshell.
+
+
+Diagram
+^^^^^^^
+
+This diagram shows the objects involved in a content process which is being
+used to host a given ``BrowsingContext``, along with rough relationships
+between them. Dotted lines represent a "current" relationship, whereas solid
+lines are a stronger lifetime relationship.
+
+.. graph:: document
+
+  node [shape=rectangle]
+
+  "BrowsingContext" -- "nsDocShell" [style=dotted];
+  "nsDocShell" -- "nsGlobalWindowOuter";
+  "nsGlobalWindowOuter" -- "nsGlobalWindowInner" [style=dotted];
+  "nsGlobalWindowInner" -- "Document" [style=dotted];
+
+  "nsDocShell" -- "nsDocumentViewer" [style=dotted];
+  "nsDocumentViewer" -- "Document";
+  "nsDocumentViewer" -- "PresShell";
+
+  "nsGlobalWindowInner" -- "WindowGlobalChild";
+  "BrowsingContext" -- "WindowContext" [style=dotted];
+  "WindowContext" -- "nsGlobalWindowInner";
+
+  subgraph cluster_synced {
+    label = "Synced Contexts";
+    "BrowsingContext" "WindowContext";
+  }
+
diff --git a/dom/docs/navigation/index.rst b/dom/docs/navigation/index.rst
new file mode 100644
index 0000000000..b322855eb6
--- /dev/null
+++ b/dom/docs/navigation/index.rst
@@ -0,0 +1,9 @@
+DOM Navigation
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   embedding
+   BrowsingContext
+   nav_replace
diff --git a/dom/docs/navigation/nav_replace.rst b/dom/docs/navigation/nav_replace.rst
new file mode 100644
index 0000000000..bed1a30b95
--- /dev/null
+++ b/dom/docs/navigation/nav_replace.rst
@@ -0,0 +1,95 @@
+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:
+
+.. csv-table:: objects replaced or preserved across navigations
+   :header: "Class/Id", ":ref:`in-process navigations`", ":ref:`cross-process navigations`", ":ref:`cross-group navigations`"
+
+   "BrowserId [#bid]_", |preserve|, |preserve|, |preserve|
+   "BrowsingContextWebProgress", |preserve|, |preserve|, |preserve|
+   "BrowsingContextGroup", |preserve|, |preserve|, |replace|
+   "BrowsingContext", |preserve|, |preserve|, |replace|
+   "nsFrameLoader", |preserve|, |replace|, |replace|
+   "RemoteBrowser", |preserve|, |replace|, |replace|
+   "Browser{Parent,Child}", |preserve|, |replace|, |replace|
+   "nsDocShell", |preserve|, |replace|, |replace|
+   "nsGlobalWindowOuter", |preserve|, |replace|, |replace|
+   "nsGlobalWindowInner", "|replace| [#inner]_", |replace|, |replace|
+   "WindowContext", "|replace| [#inner]_", |replace|, |replace|
+   "WindowGlobal{Parent,Child}", "|replace| [#inner]_", |replace|, |replace|
+   "Document", "|replace|", |replace|, |replace|
+
+
+.. |replace| replace:: ❌ replaced
+.. |preserve| replace:: ✔️ preserved
+
+.. [#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`` 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
+^^^^^^^^^^^^^^^^^^^^^^
+
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+for navigations to and from special URLs like ``file://`` URIs when
+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
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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 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.
+- Sometimes, when loading a document with the ``Large-Allocation`` header on
+  32-bit windows.
+
+State which needs to be saved over cross-group navigations on
+``BrowsingContext`` instances is copied in the
+``CanonicalBrowsingContext::ReplacedBy`` method.