From 372b4fa757d002a64581b1c24e786bde85f18ed6 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <bvaughn@fb.com>
Date: Tue, 15 Mar 2022 17:21:47 -0400
Subject: [PATCH 1/4] Update DevTools READMEs

---
 packages/react-devtools-core/README.md   |  39 ++++---
 packages/react-devtools-inline/README.md | 123 ++++++++++++++++++++---
 packages/react-devtools-shared/README.md |   6 ++
 packages/react-devtools/OVERVIEW.md      |  12 ++-
 packages/react-devtools/README.md        |   4 +-
 5 files changed, 150 insertions(+), 34 deletions(-)
 create mode 100644 packages/react-devtools-shared/README.md

diff --git a/packages/react-devtools-core/README.md b/packages/react-devtools-core/README.md
index d139bf2e3b9..05b754a270f 100644
--- a/packages/react-devtools-core/README.md
+++ b/packages/react-devtools-core/README.md
@@ -29,33 +29,40 @@ The `config` object may contain:
 
 ## `react-devtools-core/standalone`
 
-Renders the DevTools interface into a DOM node.
-
+Renders DevTools UI into a DOM node:
 ```js
-require("react-devtools-core/standalone")
-  .setContentDOMNode(document.getElementById("container"))
-  .setStatusListener(status => {
-    // This callback is optional...
-  })
-  .startServer(port);
-```
+import DevtoolsUI from "react-devtools-core/standalone";
 
-Renders DevTools interface into a DOM node over SSL using a custom host name (Default is localhost).
+const { setContentDOMNode, setStatusListener, startServer } = DevtoolsUI;
 
+const container = document.getElementById("container");
+
+setContentDOMNode(container);
+setStatusListener(status => {
+  // This callback is optional...
+});
+startServer(port, host, options);
+```
+
+Configures DevTools UI to use SSL with custom host name:
 ```js
+import DevtoolsUI from "react-devtools-core/standalone";
+
+const { setContentDOMNode, setStatusListener, startServer } = DevtoolsUI;
+
 const host = 'dev.server.com';
 const options = {
   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
 };
 
+const container = document.getElementById("container");
 
-require("react-devtools-core/standalone")
-  .setContentDOMNode(document.getElementById("container"))
-  .setStatusListener(status => {
-    // This callback is optional...
-  })
-  .startServer(port, host, options);
+setContentDOMNode(container);
+setStatusListener(status => {
+  // This callback is optional...
+});
+startServer(port, host, options);
 ```
 
 Reference the `react-devtools` package for a complete integration example.
diff --git a/packages/react-devtools-inline/README.md b/packages/react-devtools-inline/README.md
index 53edee429bd..0dcadbbcd39 100644
--- a/packages/react-devtools-inline/README.md
+++ b/packages/react-devtools-inline/README.md
@@ -4,7 +4,11 @@ React DevTools implementation for embedding within a browser-based IDE (e.g. [Co
 
 This is a low-level package. If you're looking for the standalone DevTools app, **use the `react-devtools` package instead.**
 
-## Usage
+---
+
+**Note** that this package (and the DevTools UI) relies on several _experimental_ APIs that are only available in the [experimental release channel](https://reactjs.org/docs/release-channels.html#experimental-channel).
+
+# Usage
 
 This package exports two entry points: a frontend (to be run in the main `window`) and a backend (to be installed and run within an `iframe`<sup>1</sup>).
 
@@ -16,9 +20,9 @@ The frontend and backend can be initialized in any order, but **the backend must
 
 <sup>1</sup> Sandboxed iframes are supported.
 
-## API
+# API
 
-### `react-devtools-inline/backend`
+## `react-devtools-inline/backend`
 
 * **`initialize(contentWindow)`** -
 Installs the global hook on the window. This hook is how React and DevTools communicate. **This method must be called before React is loaded.**<sup>2</sup>
@@ -43,7 +47,7 @@ activate(contentWindow);
 
 <sup>2</sup> The backend must be initialized before React is loaded. (This means before any `import` or `require` statements or `<script>` tags that include React.)
 
-### `react-devtools-inline/frontend`
+## `react-devtools-inline/frontend`
 
 * **`initialize(contentWindow)`** -
 Configures the DevTools interface to listen to the `window` the backend was injected into. This method returns a React component that can be rendered directly<sup>3</sup>.
@@ -62,9 +66,9 @@ const DevTools = initialize(contentWindow);
 
 <sup>3</sup> Because the DevTools interface makes use of several new React APIs (e.g. suspense, concurrent mode) it should be rendered using `ReactDOMClient.createRoot`. **It should not be rendered with `ReactDOM.render`.**
 
-## Examples
+# Examples
 
-### Supporting named hooks
+## Supporting named hooks
 
 DevTools can display hook "names" for an inspected component, although determining the "names" requires loading the source (and source-maps), parsing the code, and inferring the names based on which variables hook values get assigned to. Because the code for this is non-trivial, it's lazy-loaded only if the feature is enabled.
 
@@ -81,7 +85,7 @@ const hookNamesModuleLoaderFunction = () => import('react-devtools-inline/hookNa
 />;
 ```
 
-### Configuring a same-origin `iframe`
+## Configuring a same-origin `iframe`
 
 The simplest way to use this package is to install the hook from the parent `window`. This is possible if the `iframe` is not sandboxed and there are no cross-origin restrictions.
 
@@ -116,7 +120,7 @@ const DevTools = initializeFrontend(contentWindow);
 activateBackend(contentWindow);
 ```
 
-### Configuring a sandboxed `iframe`
+## Configuring a sandboxed `iframe`
 
 Sandboxed `iframe`s are also supported but require more complex initialization.
 
@@ -169,7 +173,7 @@ iframe.onload = () => {
 };
 ```
 
-### Advanced integration with custom "wall"
+## Advanced: Custom "wall"
 
 Below is an example of an advanced integration with a website like [Replay.io](https://replay.io/) or Code Sandbox's Sandpack (where more than one DevTools instance may be rendered per page).
 
@@ -235,25 +239,116 @@ const wall = {
 };
 ```
 
-## Local development
+## Advanced: Node + browser
+
+Below is an example of an advanced integration that could be used to connect React running in a Node process to React DevTools running in a browser.
+
+#### Sample Node "backend"
+```js
+const {
+  activate,
+  createBridge,
+  initialize,
+} = require('react-devtools-inline/backend');
+const { createServer } = require('http');
+const SocketIO = require('socket.io');
+
+const server = createServer();
+const socket = SocketIO(server, {
+  cors: {
+    origin: "*",
+    methods: ["GET", "POST"],
+    allowedHeaders: [],
+    credentials: true
+  }
+});
+socket.on('connection', client => {
+  const wall = {
+    listen(listener) {
+      client.on('message', data => {
+        if (data.uid === UID) {
+          listener(data);
+        }
+      });
+    },
+    send(event, payload) {
+      const data = {event, payload, uid: UID};
+      client.emit('message', data);
+    },
+  };
+
+  const bridge = createBridge(global, wall);
+
+  client.on('disconnect', () => {
+    bridge.shutdown();
+  });
+
+  activate(global, { bridge });
+});
+socket.listen(PORT);
+```
+
+#### Sample Web "frontend"
+```js
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import {
+  createBridge,
+  createStore,
+  initialize as createDevTools,
+} from 'react-devtools-inline/frontend';
+import { io } from "socket.io-client";
+
+let root = null;
+
+const socket = io(`http://${HOST}:${PORT}`);
+socket.on("connect", () => {
+  const wall = {
+    listen(listener) {
+      socket.on("message", (data) => {
+        if (data.uid === UID) {
+          listener(data);
+        }
+      });
+    },
+    send(event, payload) {
+      const data = { event, payload, uid: UID };
+      socket.emit('message', data);
+    },
+  };
+
+  const bridge = createBridge(window, wall);
+  const store = createStore(bridge);
+  const DevTools = createDevTools(window, { bridge, store });
+
+  root = createRoot(document.getElementById('root'));
+  root.render(createElement(DevTools));
+});
+socket.on("disconnect", () => {
+  root.unmount();
+  root = null;
+});
+```
+
+# Local development
 You can also build and test this package from source.
 
-### Prerequisite steps
+## Prerequisite steps
 DevTools depends on local versions of several NPM packages<sup>1</sup> also in this workspace. You'll need to either build or download those packages first.
 
 <sup>1</sup> Note that at this time, an _experimental_ build is required because DevTools depends on the `createRoot` API.
 
-#### Build from source
+### Build from source
 To build dependencies from source, run the following command from the root of the repository:
 ```sh
 yarn build-for-devtools
 ```
-#### Download from CI
+### Download from CI
 To use the latest build from CI, run the following command from the root of the repository:
 ```sh
 ./scripts/release/download-experimental-build.js
 ```
-### Build steps
+## Build steps
 Once the above packages have been built or downloaded, you can watch for changes made to the source code and automatically rebuild by running:
 ```sh
 yarn start
diff --git a/packages/react-devtools-shared/README.md b/packages/react-devtools-shared/README.md
new file mode 100644
index 00000000000..6dafc8eb034
--- /dev/null
+++ b/packages/react-devtools-shared/README.md
@@ -0,0 +1,6 @@
+This directory contains code shared between several DevTools packages:
+* /packages/react-devtools-core
+* /packages/react-devtools-extensions
+* /packages/react-devtools-inline
+
+It is not published or released anywhere directly.
\ No newline at end of file
diff --git a/packages/react-devtools/OVERVIEW.md b/packages/react-devtools/OVERVIEW.md
index 01ed4bd02a8..76aeff3343c 100644
--- a/packages/react-devtools/OVERVIEW.md
+++ b/packages/react-devtools/OVERVIEW.md
@@ -293,11 +293,13 @@ To mitigate the performance impact of re-rendering a component, DevTools does th
 
 ## Profiler
 
-The Profiler UI is a powerful tool for identifying and fixing performance problems. The primary goal of the new profiler is to minimize its impact (CPU usage) while profiling is active. This can be accomplished by:
+DevTools provides a suite of profiling tools for identifying and fixing performance problems. React 16.9+ supports a "legacy" profiler and React 18+ adds the ["timeline" profiler](https://github.com/facebook/react/tree/main/packages/react-devtools-timeline/src) support. These profilers are explained below, but at a high level– the architecture of each profiler aims to minimize the impact (CPU usage) while profiling is active. This can be accomplished by:
 * Minimizing bridge traffic.
 * Making expensive computations lazy.
 
-The majority of profiling information is stored on the backend. The backend push-notifies the frontend of when profiling starts or stops by sending a "_profilingStatus_" message. The frontend also asks for the current status after mounting by sending a "_getProfilingStatus_" message. (This is done to support the reload-and-profile functionality.)
+The majority of profiling information is stored in the DevTools backend. The backend push-notifies the frontend of when profiling starts or stops by sending a "_profilingStatus_" message. The frontend also asks for the current status after mounting by sending a "_getProfilingStatus_" message. (This is done to support the reload-and-profile functionality.)
+
+### Legacy profiler
 
 When profiling begins, the frontend takes a snapshot/copy of each root. This snapshot includes the id, name, key, and child IDs for each node in the tree. (This information is already present on the frontend, so it does not require any additional bridge traffic.) While profiling is active, each time React commits– the frontend also stores a copy of the "_operations_" message (described above). Once profiling has finished, the frontend can use the original snapshot along with each of the stored "_operations_" messages to reconstruct the tree for each of the profiled commits.
 
@@ -308,6 +310,12 @@ When profiling begins, the backend records the base durations of each fiber curr
 
 This information will eventually be required by the frontend in order to render its profiling graphs, but it will not be sent across the bridge until profiling has completed (to minimize the performance impact of profiling).
 
+### Timeline profiler
+
+Timeline profiling data can come from one of two places:
+* The React DevTools backend, which injects a [set of profiling hooks](https://github.com/facebook/react/blob/main/packages/react-devtools-shared/src/backend/profilingHooks.js) that React calls while rendering. When profiling, these hooks store information in memory which gets passed to DevTools when profiling is stopped.
+* A Chrome performance export (JSON) containing React data (as User Timing marks) and other browser data like CPU samples, Network traffic, and native commits. (This method is not as convenient but provides more detailed browser performance data.)
+
 ### Combining profiling data
 
 Once profiling is finished, the frontend requests profiling data from the backend one renderer at a time by sending a "_getProfilingData_" message. The backend responds with a "_profilingData_" message that contains per-root commit timing and duration information. The frontend then combines this information with its own snapshots to form a complete picture of the profiling session. Using this data, charts and graphs are lazily computed (and incrementally cached) on demand, based on which commits and views are selected in the Profiler UI.
diff --git a/packages/react-devtools/README.md b/packages/react-devtools/README.md
index b6e1516d67f..939950d1104 100644
--- a/packages/react-devtools/README.md
+++ b/packages/react-devtools/README.md
@@ -32,12 +32,12 @@ Run `react-devtools` from the terminal to launch the standalone DevTools app:
 react-devtools
 ```
 
-If you're not in a simulator then you also need to run the following in a command prompt:
+If you're not using a local simulator, you'll also need to forward ports used by React DevTools:
 ```sh
 adb reverse tcp:8097 tcp:8097
 ```
 
-If you're using React Native 0.43 or higher, it should connect to your simulator within a few seconds.
+If you're using React Native 0.43 or higher, it should connect to your simulator within a few seconds. (If this doesn't happen automatically, try reloading the React Native app.)
 
 ### Integration with React Native Inspector
 

From bcb4aa447df8751968c4b2cf0f42a7d6fe2dba4c Mon Sep 17 00:00:00 2001
From: Brian Vaughn <bvaughn@fb.com>
Date: Wed, 16 Mar 2022 11:20:52 -0400
Subject: [PATCH 2/4] Cleaned up react-devtools-core README

---
 packages/react-devtools-core/README.md | 135 +++++++++++++++++--------
 1 file changed, 93 insertions(+), 42 deletions(-)

diff --git a/packages/react-devtools-core/README.md b/packages/react-devtools-core/README.md
index 05b754a270f..4ee323fc991 100644
--- a/packages/react-devtools-core/README.md
+++ b/packages/react-devtools-core/README.md
@@ -1,73 +1,122 @@
 # `react-devtools-core`
 
-A standalone React DevTools implementation.
+This package provides low-level APIs to support renderers like [React Native](https://github.com/facebook/react-native). If you're looking for the standalone React DevTools UI, **we suggest using [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools) instead of using this package directly**.
 
-This is a low-level package. If you're looking for the Electron app you can run, **use `react-devtools` package instead.**
+This package provides two entrypoints: labeled "backend" and "standalone" (frontend). Both APIs are described below.
 
-## API
+# Backend API
 
-### `react-devtools-core`
+Backend APIs are embedded in _development_ builds of renderers like [React Native](https://github.com/facebook/react-native) in order to connect to the React DevTools UI.
 
-This is similar requiring the `react-devtools` package, but provides several configurable options. Unlike `react-devtools`, requiring `react-devtools-core` doesn't connect immediately but instead exports a function:
+### Example
+
+If you are building a non-browser-based React renderer, you can use the backend API like so:
 
 ```js
-const { connectToDevTools } = require("react-devtools-core");
-connectToDevTools(config);
+if (process.env.NODE_ENV !== 'production') {
+  const { connectToDevTools } = require("react-devtools-core");
+
+  // Must be called before packages like react or react-native are imported
+  connectToDevTools({
+    ...config
+  });
+}
 ```
 
-Run `connectToDevTools()` in the same context as React to set up a connection to DevTools.  
-Be sure to run this function *before* importing e.g. `react`, `react-dom`, `react-native`.
+> **NOTE** that this API (`connectToDevTools`) must be (1) run in the same context as React and (2) must be called before React packages are imported (e.g. `react`, `react-dom`, `react-native`).
+
+### `connectToDevTools` options
+| Prop | Default | Description |
+|---|---|---|
+| `host` | `"localhost"` | Socket connection to frontend should use this host. |
+| `isAppActive` |  | (Optional) function that returns true/false, telling DevTools when it's ready to connect to React. |
+| `port` | `8097` | Socket connection to frontend should use this port. |
+| `resolveRNStyle` |  | (Optional) function that accepts a key (number) and returns a style (object); used by React Native. |
+| `retryConnectionDelay` | `200` | Delay (ms) to wait between retrying a failed Websocket connection |
+| `useHttps` | `false` | Socket connection to frontend should use secure protocol (wss). |
+| `websocket` |  | Custom `WebSocket` connection to frontend; overrides `host` and `port` settings. |
 
-The `config` object may contain:
-* `host: string` (defaults to "localhost") - Websocket will connect to this host.
-* `port: number` (defaults to `8097`) - Websocket will connect to this port.
-* `useHttps: boolean` (defaults to `false`) - Websocket should use a secure protocol (wss).
-* `websocket: Websocket` - Custom websocket to use. Overrides `host` and `port` settings if provided.
-* `resolveRNStyle: (style: number) => ?Object` - Used by the React Native style plug-in.
-* `retryConnectionDelay: number` (defaults to `2000`) - Milliseconds delay to wait between retrying a failed Websocket connection.
-* `isAppActive: () => boolean` - If provided, DevTools will poll this method and wait until it returns true before connecting to React.
+# Frontend API
 
-## `react-devtools-core/standalone`
+Frontend APIs can be used to render the DevTools UI into a DOM node. One example of this is [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools) which wraps DevTools in an Electron app.
 
-Renders DevTools UI into a DOM node:
+### Example
 ```js
 import DevtoolsUI from "react-devtools-core/standalone";
 
-const { setContentDOMNode, setStatusListener, startServer } = DevtoolsUI;
+// See the full list of API methods in documentation below.
+const { setContentDOMNode, startServer } = DevtoolsUI;
+
+// Render DevTools UI into a DOM element.
+setContentDOMNode(document.getElementById("container"));
+
+// Start socket server used to communicate between backend and frontend.
+startServer(
+  // Port defaults to 8097
+  1234,
 
-const container = document.getElementById("container");
+  // Host defaults to "localhost"
+  "example.devserver.com",
 
-setContentDOMNode(container);
-setStatusListener(status => {
-  // This callback is optional...
-});
-startServer(port, host, options);
+  // Optional config for secure socket (WSS).
+  {
+    key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+    cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+  }
+);
 ```
 
-Configures DevTools UI to use SSL with custom host name:
+### Exported methods
+The `default` export is an object defining the methods described below.
+
+These methods support chaining for convenience. For example:
 ```js
-import DevtoolsUI from "react-devtools-core/standalone";
+const DevtoolsUI = require("react-devtools-core/standalone");
+DevtoolsUI.setContentDOMNode(element).startServer();
+```
 
-const { setContentDOMNode, setStatusListener, startServer } = DevtoolsUI;
+#### `connectToSocket(socket: WebSocket)`
+> This is an advanced config function that is typically not used.
 
-const host = 'dev.server.com';
-const options = {
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
-};
+Custom `WebSocket` connection to use for communication between DevTools frontend and backend. Calling this method automatically initializes the DevTools UI (similar to calling `startServer()`).
 
-const container = document.getElementById("container");
+#### `openProfiler()`
+Automatically select the "Profiler" tab in the DevTools UI.
 
-setContentDOMNode(container);
-setStatusListener(status => {
-  // This callback is optional...
-});
-startServer(port, host, options);
+#### `setContentDOMNode(element: HTMLElement)`
+Set the DOM element DevTools UI should be rendered into on initialization.
+
+#### `setDisconnectedCallback(callback: Function)`
+_Optional_ callback to be notified when DevTools `WebSocket` closes (or errors).
+
+#### `setProjectRoots(roots: Array<string>)`
+_Optional_ set of root directores for source files. These roots can be used to open an inspected component's source code using an IDE.
+
+#### `setStatusListener(callback: Function)`
+_Optional_ callback to be notified of socket server events (e.g. initialized, errored, connected).
+
+This callback receives two parameters:
+```js
+function onStatus(
+  message: string,
+  status: 'server-connected' | 'devtools-connected' | 'error'
+): void {
+  // ...
+}
 ```
 
-Reference the `react-devtools` package for a complete integration example.
+#### `startServer(port?: number, host?: string, httpsOptions?: Object, loggerOptions?: Object)`
+Start a socket server (used to communicate between backend and frontend) and renders the DevTools UI.
+
+This method accepts the following parameters:
+| Name | Default | Description |
+|---|---|---|
+| `port` | `8097` | Socket connection to backend should use this port. |
+| `host` | `"localhost"` | Socket connection to backend should use this host. |
+| `httpsOptions` | | _Optional_ object defining `key` and `cert` strings. |
+| `loggerOptions` | | _Optional_ object defining a `surface` string (to be included with DevTools logging events). |
 
-## Development
+# Development
 
 Watch for changes made to the backend entry point and rebuild:
 ```sh
@@ -78,3 +127,5 @@ Watch for changes made to the standalone UI entry point and rebuild:
 ```sh
 yarn start:standalone
 ```
+
+Run the standalone UI using `yarn start` in the [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools).
\ No newline at end of file

From fd87078168629ea42d3013920e69ced202fa58b0 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <bvaughn@fb.com>
Date: Wed, 16 Mar 2022 11:25:09 -0400
Subject: [PATCH 3/4] Updated react-devtools README intro description

---
 packages/react-devtools/README.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/react-devtools/README.md b/packages/react-devtools/README.md
index 939950d1104..cb13ff78a7c 100644
--- a/packages/react-devtools/README.md
+++ b/packages/react-devtools/README.md
@@ -1,8 +1,6 @@
 # `react-devtools`
 
-React DevTools is available as a built-in extension for Chrome and Firefox browsers. This package enables you to debug a React app elsewhere (e.g. a mobile browser, an embedded webview, Safari, inside an iframe).
-
-It works both with React DOM and React Native.
+This package can be used to debug non-browser-based React applications (e.g. React Native, mobile browser or embedded webview, Safari).
 
 ![React DevTools screenshot](https://user-images.githubusercontent.com/29597/63811956-bdd9b580-c8dd-11e9-8962-c568e475c425.png)
 

From 88b5c43462ce316b2a10e337710bf875aea2743a Mon Sep 17 00:00:00 2001
From: Brian Vaughn <bvaughn@fb.com>
Date: Wed, 16 Mar 2022 11:34:11 -0400
Subject: [PATCH 4/4] Updated react-devtools-inline README

---
 packages/react-devtools-inline/README.md | 48 +++++++++++++-----------
 1 file changed, 26 insertions(+), 22 deletions(-)

diff --git a/packages/react-devtools-inline/README.md b/packages/react-devtools-inline/README.md
index 0dcadbbcd39..23374147673 100644
--- a/packages/react-devtools-inline/README.md
+++ b/packages/react-devtools-inline/README.md
@@ -1,12 +1,14 @@
 # `react-devtools-inline`
 
-React DevTools implementation for embedding within a browser-based IDE (e.g. [CodeSandbox](https://codesandbox.io/), [StackBlitz](https://stackblitz.com/)).
+This package can be used to embed React DevTools into browser-based tools like [CodeSandbox](https://codesandbox.io/), [StackBlitz](https://stackblitz.com/), and [Replay](https://replay.io).
 
-This is a low-level package. If you're looking for the standalone DevTools app, **use the `react-devtools` package instead.**
+If you're looking for the standalone React DevTools UI, **we suggest using [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools) instead of using this package directly**.
 
 ---
 
-**Note** that this package (and the DevTools UI) relies on several _experimental_ APIs that are only available in the [experimental release channel](https://reactjs.org/docs/release-channels.html#experimental-channel).
+> **Note** that this package (and the DevTools UI) relies on several _experimental_ APIs that are **only available in the [experimental release channel](https://reactjs.org/docs/release-channels.html#experimental-channel)**. This means that you will need to install `react@experimental` and `react-dom@experimenal`.
+
+---
 
 # Usage
 
@@ -20,15 +22,18 @@ The frontend and backend can be initialized in any order, but **the backend must
 
 <sup>1</sup> Sandboxed iframes are supported.
 
-# API
+# Backend APIs
+### `initialize(windowOrGlobal)`
+
+Installs the global hook on the window/global object. This hook is how React and DevTools communicate.
 
-## `react-devtools-inline/backend`
+> **This method must be called before React is loaded.** (This includes `import`/`require` statements and `<script>` tags that include React.)
+
+### `activate(windowOrGlobal)`
 
-* **`initialize(contentWindow)`** -
-Installs the global hook on the window. This hook is how React and DevTools communicate. **This method must be called before React is loaded.**<sup>2</sup>
-* **`activate(contentWindow)`** -
 Lets the backend know when the frontend is ready. It should not be called until after the frontend has been initialized, else the frontend might miss important tree-initialization events.
 
+### Example
 ```js
 import { activate, initialize } from 'react-devtools-inline/backend';
 
@@ -45,13 +50,14 @@ initialize(contentWindow);
 activate(contentWindow);
 ```
 
-<sup>2</sup> The backend must be initialized before React is loaded. (This means before any `import` or `require` statements or `<script>` tags that include React.)
+# Frontend APIs
 
-## `react-devtools-inline/frontend`
+### `initialize(windowOrGlobal)`
+Configures the DevTools interface to listen to the `window` (or `global` object) the backend was injected into. This method returns a React component that can be rendered directly.
 
-* **`initialize(contentWindow)`** -
-Configures the DevTools interface to listen to the `window` the backend was injected into. This method returns a React component that can be rendered directly<sup>3</sup>.
+> Because the DevTools interface makes use of several new React concurrent features (like Suspense) **it should be rendered using `ReactDOMClient.createRoot` instead of `ReactDOM.render`.**
 
+### Example
 ```js
 import { initialize } from 'react-devtools-inline/frontend';
 
@@ -64,11 +70,9 @@ const contentWindow = iframe.contentWindow;
 const DevTools = initialize(contentWindow);
 ```
 
-<sup>3</sup> Because the DevTools interface makes use of several new React APIs (e.g. suspense, concurrent mode) it should be rendered using `ReactDOMClient.createRoot`. **It should not be rendered with `ReactDOM.render`.**
-
-# Examples
+# Advanced examples
 
-## Supporting named hooks
+### Supporting named hooks
 
 DevTools can display hook "names" for an inspected component, although determining the "names" requires loading the source (and source-maps), parsing the code, and inferring the names based on which variables hook values get assigned to. Because the code for this is non-trivial, it's lazy-loaded only if the feature is enabled.
 
@@ -85,7 +89,7 @@ const hookNamesModuleLoaderFunction = () => import('react-devtools-inline/hookNa
 />;
 ```
 
-## Configuring a same-origin `iframe`
+### Configuring a same-origin `iframe`
 
 The simplest way to use this package is to install the hook from the parent `window`. This is possible if the `iframe` is not sandboxed and there are no cross-origin restrictions.
 
@@ -120,7 +124,7 @@ const DevTools = initializeFrontend(contentWindow);
 activateBackend(contentWindow);
 ```
 
-## Configuring a sandboxed `iframe`
+### Configuring a sandboxed `iframe`
 
 Sandboxed `iframe`s are also supported but require more complex initialization.
 
@@ -173,7 +177,7 @@ iframe.onload = () => {
 };
 ```
 
-## Advanced: Custom "wall"
+### Advanced: Custom "wall"
 
 Below is an example of an advanced integration with a website like [Replay.io](https://replay.io/) or Code Sandbox's Sandpack (where more than one DevTools instance may be rendered per page).
 
@@ -239,11 +243,11 @@ const wall = {
 };
 ```
 
-## Advanced: Node + browser
+### Advanced: Node + browser
 
 Below is an example of an advanced integration that could be used to connect React running in a Node process to React DevTools running in a browser.
 
-#### Sample Node "backend"
+##### Sample Node backend
 ```js
 const {
   activate,
@@ -288,7 +292,7 @@ socket.on('connection', client => {
 socket.listen(PORT);
 ```
 
-#### Sample Web "frontend"
+##### Sample Web frontend
 ```js
 import { createElement } from 'react';
 import { createRoot } from 'react-dom/client';