facebook · motiz88 · Jan 6, 2026 · Jan 6, 2026
diff --git a/__docs__/README.md b/__docs__/README.md
@@ -55,7 +55,9 @@ TODO: Explain the different components of React Native at a high level.
       - Globals and environment setup
       - Error handling
     - Developer Tools
-      - React DevTools
+      - React Native DevTools
+        - Infrastructure
+          - [Inspector proxy protocol](../packages/dev-middleware/src/inspector-proxy/__docs__/README.md)
       - LogBox
     - Misc
       - Web APIs
@@ -91,8 +93,6 @@ TODO: Explain the different components of React Native at a high level.
     - ESLint
   - Integration / E2E
     - [Fantom](../private/react-native-fantom/__docs__/README.md)
-- Tooling
-  - React Native DevTools
 
 ### Used by this
 

diff --git a/packages/dev-middleware/src/inspector-proxy/__docs__/README.md b/packages/dev-middleware/src/inspector-proxy/__docs__/README.md
@@ -0,0 +1,298 @@
+# Inspector Proxy Protocol
+
+[🏠 Home](../../../../../__docs__/README.md)
+
+The inspector-proxy protocol facilitates Chrome DevTools Protocol (CDP) target
+discovery and communication between **debuggers** (e.g., Chrome DevTools, VS
+Code) and **devices** (processes containing React Native hosts). The proxy
+multiplexes connections over a single WebSocket per device, allowing multiple
+debuggers to connect to multiple pages on the same device.
+
+## 🚀 Usage
+
+### Target Discovery (HTTP)
+
+We implement a subset of the
+[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)'s
+[HTTP endpoints](https://chromedevtools.github.io/devtools-protocol/#:~:text=a%20reconnect%20button.-,HTTP%20Endpoints,-If%20started%20with)
+to allow debuggers to discover targets.
+
+| Endpoint                    | Description              |
+| --------------------------- | ------------------------ |
+| `GET /json` or `/json/list` | List of debuggable pages |
+| `GET /json/version`         | Protocol version info    |
+
+### Device Registration (WebSocket)
+
+Devices register themselves with the proxy by connecting to `/inspector/device`:
+
+```text
+ws://{host}/inspector/device?device={id}&name={name}&app={bundle_id}&profiling={true|false}
+```
+
+| Parameter   | Required | Description                                                  |
+| ----------- | -------- | ------------------------------------------------------------ |
+| `device`    | No\*     | Logical device identifier. Auto-generated if omitted.        |
+| `name`      | No       | Human-readable device name. Defaults to "Unknown".           |
+| `app`       | No       | App bundle identifier. Defaults to "Unknown".                |
+| `profiling` | No       | "true" if this is a profiling build. (Used for logging only) |
+
+\*Recommended for connection persistence across app restarts.
+
+#### Requirements for the `device` parameter
+
+The intent of the logical device ID is to help with target discovery and
+especially *re*discovery - to reduce the number of times users need to
+explicitly close and restart the debugger frontend (e.g. after an app crash).
+
+If provided, the logical device ID:
+
+1. SHOULD be stable for the current combination of physical device (or emulator
+   instance) and app.
+2. SHOULD be stable across installs/launches of the same app on the same device
+   (or emulator instance), though it MAY be user-resettable (so as to not
+   require any special privacy permissions).
+3. MUST be unique across different apps on the same physical device (or
+   emulator).
+4. MUST be unique across physical devices (or emulators).
+5. MUST be unique for each concurrent _instance_ of the same app on the same
+   physical device (or emulator).
+
+NOTE: The uniqueness requirements are stronger (MUST) than the stability
+requirements (SHOULD). In particular, on platforms that allow multiple instances
+of the same app to run concurrently, requirements 1 and/or 2 MAY be violated in
+order to meet requirement 5. This is relevant, for example, on desktop
+platforms.
+
+### Debugger Connection (WebSocket)
+
+Debuggers connect to `/inspector/debug` to form a CDP session with a page:
+
+```text
+ws://{host}/inspector/debug?device={device_id}&page={page_id}
+```
+
+Both `device` and `page` query parameters are required.
+
+## 📐 Design
+
+### Architecture
+
+```text
+┌─────────────────┐     ┌─────────────────────────┐     ┌────────────────┐
+│    Debugger     │────▶│    Inspector Proxy      │◀────│     Device     │
+│ (Chrome/VSCode) │     │      (Node.js)          │     │ (iOS/Android)  │
+└─────────────────┘     └─────────────────────────┘     └────────────────┘
+   WebSocket               HTTP + WebSocket               WebSocket
+   /inspector/debug        /json, /json/list              /inspector/device
+                           /json/version
+```
+
+### Device ↔ Proxy Protocol
+
+All messages are JSON-encoded WebSocket text frames:
+
+```typescript
+interface Message {
+  event: string;
+  payload?: /* depends on event */;
+}
+```
+
+#### Proxy → Device Messages
+
+| Event          | Payload                                    | Description                                   |
+| -------------- | ------------------------------------------ | --------------------------------------------- |
+| `getPages`     | _(none)_                                   | Request current page list. Sent periodically. |
+| `connect`      | `{ pageId: string }`                       | Prepare for debugger connection to page.      |
+| `disconnect`   | `{ pageId: string }`                       | Terminate debugger session for page.          |
+| `wrappedEvent` | `{ pageId: string, wrappedEvent: string }` | Forward CDP message (JSON string) to page.    |
+
+#### Device → Proxy Messages
+
+| Event          | Payload                                    | Description                                           |
+| -------------- | ------------------------------------------ | ----------------------------------------------------- |
+| `getPages`     | `Page[]`                                   | Current list of inspectable pages.                    |
+| `disconnect`   | `{ pageId: string }`                       | Notify that page disconnected or rejected connection. |
+| `wrappedEvent` | `{ pageId: string, wrappedEvent: string }` | Forward CDP message (JSON string) from page.          |
+
+#### Page Object
+
+```typescript
+interface Page {
+  id: string; // Unique page identifier (typically numeric string)
+  title: string; // Display title
+  app: string; // App bundle identifier
+  description?: string; // Additional description
+  capabilities?: {
+    nativePageReloads?: boolean; // Target keeps the socket open across reloads
+    nativeSourceCodeFetching?: boolean; // Target supports Network.loadNetworkResource
+    prefersFuseboxFrontend?: boolean; // Target is designed for React Native DevTools
+  };
+}
+```
+
+### Connection Lifecycle
+
+**Device Registration:**
+
+```text
+Device                              Proxy
+   │                                  │
+   │──── WS Connect ─────────────────▶│
+   │     /inspector/device?...        │
+   │                                  │
+   │◀──── getPages ───────────────────│  (periodically)
+   │                                  │
+   │───── getPages response ─────────▶│
+   │      (page list)                 │
+```
+
+**Debugger Session:**
+
+```text
+Debugger            Proxy                        Device
+   │                  │                            │
+   │── WS Connect ───▶│                            │
+   │   ?device&page   │── connect ────────────────▶│
+   │                  │   {pageId}                 │
+   │                  │                            │
+   │── CDP Request ──▶│── wrappedEvent ───────────▶│
+   │                  │   {pageId, wrappedEvent}   │
+   │                  │                            │
+   │                  │◀── wrappedEvent ───────────│
+   │◀── CDP Response ─│   {pageId, wrappedEvent}   │
+   │                  │                            │
+   │── WS Close ─────▶│── disconnect ─────────────▶│
+   │                  │   {pageId}                 │
+```
+
+**Connection Rejection:**
+
+If a device cannot accept a `connect` (e.g., page doesn't exist), it should send
+a `disconnect` back to the proxy for that `pageId`.
+
+### Connection Semantics
+
+1. **One Debugger Per Page**: New debugger connections to an already-connected
+   page disconnect the existing debugger.
+
+2. **Device Reconnection**: If a device reconnects with the same `device` ID,
+   the proxy may attempt to preserve active debugger sessions by forwarding them
+   to the new device connection.
+
+### WebSocket Close Reasons
+
+The proxy uses specific close reasons that DevTools frontends may recognize:
+
+| Reason                  | Context                                 |
+| ----------------------- | --------------------------------------- |
+| `[PAGE_NOT_FOUND]`      | Debugger connected to non-existent page |
+| `[CONNECTION_LOST]`     | Device disconnected                     |
+| `[RECREATING_DEVICE]`   | Device is reconnecting                  |
+| `[NEW_DEBUGGER_OPENED]` | Another debugger took over this page    |
+| `[UNREGISTERED_DEVICE]` | Device ID not found                     |
+| `[INCORRECT_URL]`       | Missing device/page query parameters    |
+
+### PageDescription (HTTP Response)
+
+The `/json` endpoint returns enriched page descriptions based on those reported
+by the device.
+
+```typescript
+interface PageDescription {
+  // Used for target selection
+  id: string; // "{deviceId}-{pageId}"
+
+  // Used for display
+  title: string;
+  description: string;
+  deviceName: string;
+
+  // Used for target matching
+  appId: string;
+
+  // Used for debugger connection
+  webSocketDebuggerUrl: string;
+
+  // React Native-specific metadata
+  reactNative: {
+    logicalDeviceId: string; // Used for target matching
+    capabilities: {
+      nativePageReloads?: boolean; // Used for target filtering
+      prefersFuseboxFrontend?: boolean; // Used for frontend selection
+    };
+  };
+}
+```
+
+## 🔗 Relationship with other systems
+
+### Part of this
+
+- **Device.js** - Per-device connection handler in the proxy
+- **InspectorProxy.js** - Main proxy HTTP/WebSocket server
+
+### Used by this
+
+- **Chrome DevTools Protocol (CDP)** - The wrapped messages are CDP messages
+  exchanged between DevTools frontends and JavaScript runtimes.
+- **WebSocket** - Transport layer for device and debugger connections.
+
+### Uses this
+
+- **InspectorPackagerConnection (C++)** - Shared device-side protocol
+  implementation in `ReactCommon/jsinspector-modern/`.
+- **Platform layers** - iOS (`RCTInspectorDevServerHelper.mm`), Android
+  (`DevServerHelper.kt`), and ReactCxxPlatform (`Inspector.cpp`) provide
+  WebSocket I/O and threading.
+- **openDebuggerMiddleware** - Uses `/json` to discover targets for the
+  `/open-debugger` endpoint.
+- **OpenDebuggerKeyboardHandler** - Uses `/json` to display target selection in
+  the CLI.
+
+---
+
+## Legacy Features
+
+The following features exist for backward compatibility with older React Native
+targets that lack modern capabilities. New implementations should set
+appropriate capability flags and may ignore this section.
+
+### Synthetic Reloadable Page (Page ID `-1`)
+
+For targets without the `nativePageReloads` capability, the proxy exposes a
+synthetic page with ID `-1` titled "React Native Experimental (Improved Chrome
+Reloads)". Debuggers connecting to this page are automatically redirected to the
+most recent React Native page, surviving page reloads.
+
+When a new React Native page appears while a debugger is connected to `-1`:
+
+1. Proxy sends `disconnect` for the old page, `connect` for the new page
+2. Proxy sends `Runtime.enable` and `Debugger.enable` CDP commands to the new
+   page
+3. When `Runtime.executionContextCreated` is received, proxy sends
+   `Runtime.executionContextsCleared` to debugger, then `Debugger.resume` to
+   device
+
+### URL Rewriting
+
+For targets without the `nativeSourceCodeFetching` capability, the proxy
+rewrites URLs in CDP messages:
+
+- **Debugger.scriptParsed** (device → debugger): Device-relative URLs are
+  rewritten to debugger-relative URLs
+- **Debugger.setBreakpointByUrl** (debugger → device): URLs are rewritten back
+  to device-relative form
+- **Debugger.getScriptSource**: Intercepted and handled by proxy via HTTP fetch
+- **Network.loadNetworkResource**: Returns CDP error (code -32601) to force
+  frontend fallback
+
+Additionally, if a script URL matches `^[0-9a-z]+$` (alphanumeric ID), the proxy
+prepends `file://` to ensure Chrome downloads source maps.
+
+### Legacy Reload Notification
+
+For targets without `nativePageReloads`, when a `disconnect` event is received
+for a page, the proxy sends `{method: 'reload'}` to the connected debugger to
+signal a page reload.