@depup/react-native__dev-middleware 0.84.1-depup.1 → 0.85.0-depup.0

package/dist/inspector-proxy/DeviceEventReporter.d.ts

@@ -19,12 +19,10 @@ type DeviceMetadata = Readonly<{
 type RequestMetadata = Readonly<{
   pageId: string | null;
   frontendUserAgent: string | null;
-  prefersFuseboxFrontend: boolean | null;
 }>;
 type ResponseMetadata = Readonly<{
   pageId: string | null;
   frontendUserAgent: string | null;
-  prefersFuseboxFrontend: boolean | null;
 }>;
 declare class DeviceEventReporter {
   constructor(eventReporter: EventReporter, metadata: DeviceMetadata);
@@ -49,6 +47,5 @@ declare class DeviceEventReporter {
     error: Error,
     message: string,
   ): void;
-  logFuseboxConsoleNotice(): void;
 }
 export default DeviceEventReporter;

package/dist/inspector-proxy/DeviceEventReporter.js

@@ -51,7 +51,6 @@ class DeviceEventReporter {
         deviceName: this.#metadata.deviceName,
         pageId: metadata.pageId,
         frontendUserAgent: metadata.frontendUserAgent,
-        prefersFuseboxFrontend: metadata.prefersFuseboxFrontend,
         connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
       });
       return;
@@ -78,7 +77,6 @@ class DeviceEventReporter {
         deviceName: this.#metadata.deviceName,
         pageId: pendingCommand.metadata.pageId,
         frontendUserAgent: pendingCommand.metadata.frontendUserAgent,
-        prefersFuseboxFrontend: metadata.prefersFuseboxFrontend,
         connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
       });
       return;
@@ -96,7 +94,6 @@ class DeviceEventReporter {
       deviceName: this.#metadata.deviceName,
       pageId: pendingCommand.metadata.pageId,
       frontendUserAgent: pendingCommand.metadata.frontendUserAgent,
-      prefersFuseboxFrontend: metadata.prefersFuseboxFrontend,
       connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
     });
   }
@@ -145,7 +142,6 @@ class DeviceEventReporter {
         deviceName: this.#metadata.deviceName,
         pageId: pendingCommand.metadata.pageId,
         frontendUserAgent: pendingCommand.metadata.frontendUserAgent,
-        prefersFuseboxFrontend: pendingCommand.metadata.prefersFuseboxFrontend,
         connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
       });
     }
@@ -166,11 +162,6 @@ class DeviceEventReporter {
       connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
     });
   }
-  logFuseboxConsoleNotice() {
-    this.#eventReporter.logEvent({
-      type: "fusebox_console_notice",
-    });
-  }
   #logExpiredCommand(pendingCommand) {
     this.#eventReporter.logEvent({
       type: "debugger_command",
@@ -186,7 +177,6 @@ class DeviceEventReporter {
       deviceName: this.#metadata.deviceName,
       pageId: pendingCommand.metadata.pageId,
       frontendUserAgent: pendingCommand.metadata.frontendUserAgent,
-      prefersFuseboxFrontend: pendingCommand.metadata.prefersFuseboxFrontend,
       connectionUptime: this.#deviceConnectedTimestamp - Date.now(),
     });
   }

package/dist/inspector-proxy/DeviceEventReporter.js.flow

@@ -12,28 +12,26 @@ import type { EventReporter } from "../types/EventReporter";
 import type { CDPResponse } from "./cdp-types/messages";
 import type { DeepReadOnly } from "./types";
 
-type DeviceMetadata = $ReadOnly<{
+type DeviceMetadata = Readonly<{
   appId: string,
   deviceId: string,
   deviceName: string,
 }>;
 
-type RequestMetadata = $ReadOnly<{
+type RequestMetadata = Readonly<{
   pageId: string | null,
   frontendUserAgent: string | null,
-  prefersFuseboxFrontend: boolean | null,
 }>;
 
-type ResponseMetadata = $ReadOnly<{
+type ResponseMetadata = Readonly<{
   pageId: string | null,
   frontendUserAgent: string | null,
-  prefersFuseboxFrontend: boolean | null,
 }>;
 
 declare class DeviceEventReporter {
   constructor(eventReporter: EventReporter, metadata: DeviceMetadata): void;
   logRequest(
-    req: $ReadOnly<{ id: number, method: string, ... }>,
+    req: Readonly<{ id: number, method: string, ... }>,
     origin: "debugger" | "proxy",
     metadata: RequestMetadata,
   ): void;
@@ -45,7 +43,7 @@ declare class DeviceEventReporter {
   logProfilingTargetRegistered(): void;
   logConnection(
     connectedEntity: "debugger",
-    metadata: $ReadOnly<{
+    metadata: Readonly<{
       pageId: string,
       frontendUserAgent: string | null,
     }>,
@@ -56,7 +54,6 @@ declare class DeviceEventReporter {
     error: Error,
     message: string,
   ): void;
-  logFuseboxConsoleNotice(): void;
 }
 
 declare export default typeof DeviceEventReporter;

package/dist/inspector-proxy/InspectorProxy.d.ts

@@ -11,12 +11,13 @@
 import type { EventReporter } from "../types/EventReporter";
 import type { Experiments } from "../types/Experiments";
 import type { Logger } from "../types/Logger";
+import type { ReadonlyURL } from "../types/ReadonlyURL";
 import type { CreateCustomMessageHandlerFn } from "./CustomMessageHandler";
 import type { PageDescription } from "./types";
 import type { IncomingMessage, ServerResponse } from "http";
 import WS from "ws";
 export type GetPageDescriptionsConfig = {
-  requestorRelativeBaseUrl: URL;
+  requestorRelativeBaseUrl: ReadonlyURL;
   logNoPagesForConnectedDevice?: boolean;
 };
 export interface InspectorProxyQueries {
@@ -33,7 +34,7 @@ export interface InspectorProxyQueries {
  */
 declare class InspectorProxy implements InspectorProxyQueries {
   constructor(
-    serverBaseUrl: string,
+    serverBaseUrl: ReadonlyURL,
     eventReporter: null | undefined | EventReporter,
     experiments: Experiments,
     logger?: Logger,

package/dist/inspector-proxy/InspectorProxy.js

@@ -18,12 +18,17 @@ var _InspectorProxyHeartbeat = _interopRequireDefault(
   require("./InspectorProxyHeartbeat"),
 );
 var _nullthrows = _interopRequireDefault(require("nullthrows"));
-var _url = _interopRequireDefault(require("url"));
 var _ws = _interopRequireDefault(require("ws"));
 function _interopRequireDefault(e) {
   return e && e.__esModule ? e : { default: e };
 }
 const debug = require("debug")("Metro:InspectorProxy");
+const WS_DEBUGGER_ALLOWED_ORIGIN_HOSTNAMES = new Set([
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "[::]",
+]);
 const WS_DEVICE_URL = "/inspector/device";
 const WS_DEBUGGER_URL = "/inspector/debug";
 const PAGES_LIST_JSON_URL = "/json";
@@ -59,7 +64,7 @@ class InspectorProxy {
     customMessageHandler,
     trackEventLoopPerf = false,
   ) {
-    this.#serverBaseUrl = new URL(serverBaseUrl);
+    this.#serverBaseUrl = serverBaseUrl;
     this.#devices = new Map();
     this.#eventReporter = eventReporter;
     this.#experiments = experiments;
@@ -139,7 +144,7 @@ class InspectorProxy {
     return result;
   }
   processRequest(request, response, next) {
-    const pathname = _url.default.parse(request.url).pathname;
+    const pathname = new URL(request.url, "http://example.com").pathname;
     if (
       pathname === PAGES_LIST_JSON_URL ||
       pathname === PAGES_LIST_JSON_URL_2
@@ -175,10 +180,9 @@ class InspectorProxy {
     const devtoolsFrontendUrl = (0, _getDevToolsFrontendUrl.default)(
       this.#experiments,
       webSocketDebuggerUrl,
-      this.#serverBaseUrl.origin,
+      new URL(this.#serverBaseUrl),
       {
         relative: true,
-        useFuseboxEntryPoint: page.capabilities.prefersFuseboxFrontend,
       },
     );
     return {
@@ -238,11 +242,11 @@ class InspectorProxy {
     wss.on("connection", async (socket, req) => {
       const wssTimestamp = Date.now();
       const fallbackDeviceId = String(this.#deviceCounter++);
-      const query = _url.default.parse(req.url || "", true).query || {};
-      const deviceId = query.device || fallbackDeviceId;
-      const deviceName = query.name || "Unknown";
-      const appName = query.app || "Unknown";
-      const isProfilingBuild = query.profiling === "true";
+      const query = tryParseQueryParams(req.url);
+      const deviceId = query?.get("device") || fallbackDeviceId;
+      const deviceName = query?.get("name") || "Unknown";
+      const appName = query?.get("app") || "Unknown";
+      const isProfilingBuild = query?.get("profiling") === "true";
       try {
         const deviceRelativeBaseUrl =
           (0, _getBaseUrlFromRequest.default)(req) ?? this.#serverBaseUrl;
@@ -258,6 +262,7 @@ class InspectorProxy {
           deviceRelativeBaseUrl,
           serverRelativeBaseUrl: this.#serverBaseUrl,
           isProfilingBuild,
+          experiments: this.#experiments,
         };
         if (oldDevice) {
           oldDevice.dangerouslyRecreateDevice(deviceOptions);
@@ -361,12 +366,31 @@ class InspectorProxy {
       noServer: true,
       perMessageDeflate: false,
       maxPayload: 0,
+      verifyClient: (info) => {
+        if (this.#serverBaseUrl.origin === info.origin) {
+          return true;
+        }
+        if (URL.canParse(info.origin)) {
+          const { hostname } = new URL(info.origin);
+          if (WS_DEBUGGER_ALLOWED_ORIGIN_HOSTNAMES.has(hostname)) {
+            return true;
+          }
+        }
+        this.#logger?.error(
+          "Connection from DevTools failed to be established for origin '%s' and path '%s'. Was expecting origin: '%s', or origin hostname to be one of: %s",
+          info.origin,
+          info.req.url,
+          this.#serverBaseUrl.origin,
+          Array.from(WS_DEBUGGER_ALLOWED_ORIGIN_HOSTNAMES).join(", "),
+        );
+        return false;
+      },
     });
     wss.on("connection", async (socket, req) => {
       const wssTimestamp = Date.now();
-      const query = _url.default.parse(req.url || "", true).query || {};
-      const deviceId = query.device;
-      const pageId = query.page;
+      const query = tryParseQueryParams(req.url);
+      const deviceId = query?.get("device") || null;
+      const pageId = query?.get("page") || null;
       const debuggerRelativeBaseUrl =
         (0, _getBaseUrlFromRequest.default)(req) ?? this.#serverBaseUrl;
       const device = deviceId ? this.#devices.get(deviceId) : undefined;
@@ -435,7 +459,8 @@ class InspectorProxy {
         );
         device.handleDebuggerConnection(socket, pageId, {
           debuggerRelativeBaseUrl,
-          userAgent: req.headers["user-agent"] ?? query.userAgent ?? null,
+          userAgent:
+            req.headers["user-agent"] ?? query?.get("userAgent") ?? null,
         });
         socket.on("close", (code, reason) => {
           debug(
@@ -459,7 +484,7 @@ class InspectorProxy {
           "Connection failed to be established with DevTools for app='%s' on device='%s' and device id='%s' with error:",
           device?.getApp() || "unknown",
           device?.getName() || "unknown",
-          deviceId,
+          deviceId || "unknown",
           error,
         );
         socket.close(INTERNAL_ERROR_CODE, error?.toString() ?? "Unknown error");
@@ -475,3 +500,10 @@ class InspectorProxy {
   }
 }
 exports.default = InspectorProxy;
+function tryParseQueryParams(urlString) {
+  try {
+    return new URL(urlString, "http://example.com").searchParams;
+  } catch {
+    return null;
+  }
+}

package/dist/inspector-proxy/InspectorProxy.js.flow

@@ -11,6 +11,7 @@
 import type { EventReporter } from "../types/EventReporter";
 import type { Experiments } from "../types/Experiments";
 import type { Logger } from "../types/Logger";
+import type { ReadonlyURL } from "../types/ReadonlyURL";
 import type { CreateCustomMessageHandlerFn } from "./CustomMessageHandler";
 import type { PageDescription } from "./types";
 import type { IncomingMessage, ServerResponse } from "http";
@@ -18,7 +19,7 @@ import type { IncomingMessage, ServerResponse } from "http";
 import WS from "ws";
 
 export type GetPageDescriptionsConfig = {
-  requestorRelativeBaseUrl: URL,
+  requestorRelativeBaseUrl: ReadonlyURL,
   logNoPagesForConnectedDevice?: boolean,
 };
 
@@ -37,7 +38,7 @@ export interface InspectorProxyQueries {
  */
 declare export default class InspectorProxy implements InspectorProxyQueries {
   constructor(
-    serverBaseUrl: string,
+    serverBaseUrl: ReadonlyURL,
     eventReporter: ?EventReporter,
     experiments: Experiments,
     logger?: Logger,

package/dist/inspector-proxy/__docs__/README.md

@@ -0,0 +1,324 @@
+# 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, sessionId: string }`                       | Prepare for debugger connection to page.      |
+| `disconnect`   | `{ pageId: string, sessionId: string }`                       | Terminate debugger session for page.          |
+| `wrappedEvent` | `{ pageId: string, sessionId: 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, sessionId?: string }`                       | Notify that page disconnected or rejected connection. |
+| `wrappedEvent` | `{ pageId: string, sessionId?: 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
+    supportsMultipleDebuggers?: boolean; // Supports concurrent debugger sessions
+  };
+}
+```
+
+**Note**: The value of `supportsMultipleDebuggers` SHOULD be consistent across
+all pages for a given device.
+
+### 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, sessionId}      │
+   │                  │                            │
+   │── CDP Request ──▶│── wrappedEvent ───────────▶│
+   │                  │   {pageId, sessionId,      │
+   │                  │    wrappedEvent}           │
+   │                  │                            │
+   │                  │◀── wrappedEvent ───────────│
+   │◀── CDP Response ─│   {pageId, sessionId,      │
+   │                  │    wrappedEvent}           │
+   │                  │                            │
+   │── WS Close ─────▶│── disconnect ─────────────▶│
+   │                  │   {pageId, sessionId}      │
+```
+
+**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
+
+#### Multi-Debugger Support
+
+Multiple debuggers can connect simultaneously to the same page when **both** the
+proxy and device support session multiplexing:
+
+1. **Session IDs**: The proxy assigns a unique, non-empty `sessionId` to each
+   debugger connection. All messages include this `sessionId` for routing. This
+   SHOULD be a UUID or other suitably unique and ephemeral identifier.
+
+2. **Capability Detection**: Devices report `supportsMultipleDebuggers: true` in
+   their page capabilities to indicate session support.
+
+3. **Backwards Compatibility**: Legacy devices ignore `sessionId` fields in
+   incoming messages and don't include them in responses.
+
+#### Connection Rules
+
+1. **Session-Capable Device**: Multiple debuggers can connect to the same page
+   simultaneously. Each connection has an independent session.
+
+2. **Legacy Device (no `supportsMultipleDebuggers`)**: New debugger connections
+   to an already-connected page disconnect the existing debugger. The proxy MUST
+   NOT allow multiple debuggers to connect to the same page.
+
+3. **Device Reconnection**: If a device reconnects with the same `device` ID
+   while debugger connections to the same logical device are open in the proxy,
+   the proxy may attempt to preserve active debugger sessions by forwarding them
+   to the new device.
+
+### 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
+    };
+  };
+}
+```
+
+## 🔗 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.

package/dist/inspector-proxy/cdp-types/messages.js.flow

@@ -12,18 +12,18 @@ import type { JSONSerializable } from "../types";
 import type { Commands, Events } from "./protocol";
 
 // Note: A CDP event is a JSON-RPC notification with no `id` member.
-export type CDPEvent<TEvent: $Keys<Events> = "unknown"> = {
+export type CDPEvent<TEvent: keyof Events = "unknown"> = {
   method: TEvent,
   params: Events[TEvent],
 };
 
-export type CDPRequest<TCommand: $Keys<Commands> = "unknown"> = {
+export type CDPRequest<TCommand: keyof Commands = "unknown"> = {
   method: TCommand,
   params: Commands[TCommand]["paramsType"],
   id: number,
 };
 
-export type CDPResponse<TCommand: $Keys<Commands> = "unknown"> =
+export type CDPResponse<TCommand: keyof Commands = "unknown"> =
   | {
       result: Commands[TCommand]["resultType"],
       id: number,