appium-remote-debugger 15.2.13 → 15.3.0

package/build/lib/rpc/rpc-client.js

@@ -28,57 +28,43 @@ const NO_TARGET_PRESENT_YET_ERRORS = [
 exports.NEW_APP_CONNECTED_ERROR = 'New application has connected';
 exports.EMPTY_PAGE_DICTIONARY_ERROR = 'Empty page dictionary received';
 const ON_PAGE_INITIALIZED_EVENT = 'onPageInitialized';
+/**
+ * Base class for RPC clients that communicate with the Web Inspector.
+ * Provides functionality for managing targets, sending commands, and handling
+ * page initialization. Subclasses must implement device-specific connection logic.
+ */
 class RpcClient {
-    /** @type {RpcMessageHandler|undefined} */
     messageHandler;
-    /** @type {RemoteMessages|undefined} */
     remoteMessages;
-    /** @type {boolean} */
     connected;
-    /** @type {boolean} */
     isSafari;
-    /** @type {string} */
     connId;
-    /** @type {string} */
     senderId;
-    /** @type {number} */
     msgId;
-    /** @type {string|undefined} */
     udid;
-    /** @type {boolean|undefined} */
     logAllCommunication;
-    /** @type {boolean|undefined} */
     logAllCommunicationHexDump;
-    /** @type {number|undefined} */
     socketChunkSize;
-    /** @type {number|undefined} */
     webInspectorMaxFrameLength;
-    /** @type {boolean|undefined} */
     fullPageInitialization;
-    /** @type {string|undefined} */
     bundleId;
-    /** @type {number | undefined} */
     pageLoadTimeoutMs;
-    /** @type {string} */
     platformVersion;
-    /** @type {string[]} */
     _contexts;
-    /** @type {AppToTargetsMap} */
     _targets;
-    /** @type {EventEmitter} */
     _targetSubscriptions;
-    /** @type {PendingPageTargetDetails | undefined} */
     _pendingTargetNotification;
-    /** @type {number} */
     _targetCreationTimeoutMs;
+    _provisionedPages;
+    _pageSelectionLock;
+    _pageSelectionMonitor;
     /**
-     *
-     * @param {RpcClientOptions} [opts={}]
+     * @param opts - Options for configuring the RPC client.
      */
     constructor(opts = {}) {
         const { bundleId, platformVersion = '', isSafari = true, logAllCommunication = false, logAllCommunicationHexDump = false, webInspectorMaxFrameLength, socketChunkSize, fullPageInitialization = false, udid, pageLoadTimeoutMs, targetCreationTimeoutMs = DEFAULT_TARGET_CREATION_TIMEOUT_MS, } = opts;
         this.isSafari = isSafari;
-        this.isConnected = false;
+        this.connected = false;
         this.connId = support_1.util.uuidV4();
         this.senderId = support_1.util.uuidV4();
         this.msgId = 0;
@@ -108,72 +94,137 @@ class RpcClient {
         this.messageHandler.on('Heap.garbageCollected', this.onGarbageCollected.bind(this));
     }
     /**
-     * @returns {string[]}
+     * Gets the list of execution context IDs.
+     *
+     * @returns Array of execution context IDs.
      */
     get contexts() {
         return this._contexts;
     }
     /**
-     * @returns {AppToTargetsMap}
+     * Gets the mapping of applications to their pages and targets.
+     *
+     * @returns The targets mapping structure.
      */
     get targets() {
         return this._targets;
     }
     /**
-     * @returns {boolean}
+     * Gets whether the client is currently connected.
+     *
+     * @returns True if connected, false otherwise.
      */
     get isConnected() {
         return this.connected;
     }
     /**
-     * @param {boolean} connected
+     * Sets the connection status.
+     *
+     * @param connected - The connection status to set.
      */
     set isConnected(connected) {
         this.connected = !!connected;
     }
     /**
-     * @returns {EventEmitter}
+     * Gets the event emitter for target subscriptions.
+     *
+     * @returns The target subscriptions event emitter.
      */
     get targetSubscriptions() {
         return this._targetSubscriptions;
     }
     /**
+     * Registers an event listener on the message handler.
+     *
+     * Supported events include:
+     *
+     * **RPC-level events:**
+     * - `_rpc_reportSetup:` - Emitted when the debugger setup is reported
+     * - `_rpc_reportConnectedApplicationList:` - Emitted when the list of connected applications is reported
+     * - `_rpc_forwardGetListing:` - Emitted when an application sends a page listing
+     * - `_rpc_applicationConnected:` - Emitted when a new application connects
+     * - `_rpc_applicationDisconnected:` - Emitted when an application disconnects
+     * - `_rpc_applicationUpdated:` - Emitted when an application is updated
+     * - `_rpc_reportConnectedDriverList:` - Emitted when the list of connected drivers is reported
+     * - `_rpc_reportCurrentState:` - Emitted when the current state is reported
      *
-     * @param {string} event
-     * @param {Function} listener
-     * @returns {this}
+     * **Target events:**
+     * - `Target.targetCreated` - Emitted when a new target is created (args: error, appIdKey, targetInfo)
+     * - `Target.targetDestroyed` - Emitted when a target is destroyed (args: error, appIdKey, targetInfo)
+     * - `Target.didCommitProvisionalTarget` - Emitted when a provisional target commits (args: error, appIdKey, provisionalTargetInfo)
+     *
+     * **Page events:**
+     * - `Page.frameStoppedLoading` - Emitted when a frame stops loading
+     * - `Page.frameNavigated` - Emitted when a frame navigates
+     * - `Page.frameDetached` - Emitted when a frame is detached
+     * - `Page.loadEventFired` - Emitted when the page load event fires
+     *
+     * **Runtime events:**
+     * - `Runtime.executionContextCreated` - Emitted when an execution context is created (args: error, context)
+     *
+     * **Console events:**
+     * - `Console.messageAdded` - Emitted when a console message is added (args: error, message)
+     * - `Console.messageRepeatCountUpdated` - Emitted when a console message repeat count is updated
+     * - `ConsoleEvent` - Aggregate event for all Console.* events (args: error, params, methodName)
+     *
+     * **Network events:**
+     * - `NetworkEvent` - Aggregate event for all Network.* events (args: error, params, methodName)
+     *
+     * **Timeline events:**
+     * - `Timeline.eventRecorded` - Emitted when a timeline event is recorded (args: error, record)
+     *
+     * **Heap events:**
+     * - `Heap.garbageCollected` - Emitted when garbage collection occurs
+     *
+     * **Message ID events:**
+     * - Any numeric string (message ID) - Emitted for command responses (args: error, result)
+     *
+     * @param event - The event name to listen for.
+     * @param listener - The listener function to call when the event is emitted.
+     *                  The listener receives (error, ...args) where error may be null/undefined.
+     * @returns This instance for method chaining.
      */
     on(event, listener) {
-        // @ts-ignore messageHandler must be defined here
         this.messageHandler.on(event, listener);
         return this;
     }
     /**
+     * Registers a one-time event listener on the message handler.
+     * The listener will be automatically removed after being called once.
      *
-     * @param {string} event
-     * @param {Function} listener
-     * @returns {this}
+     * See {@link RpcClient.on} for a list of supported events.
+     *
+     * @param event - The event name to listen for.
+     * @param listener - The listener function to call when the event is emitted.
+     *                  The listener receives (error, ...args) where error may be null/undefined.
+     * @returns This instance for method chaining.
      */
     once(event, listener) {
-        // @ts-ignore messageHandler must be defined here
         this.messageHandler.once(event, listener);
         return this;
     }
     /**
-     * @param {string} event
-     * @param {Function} listener
-     * @returns {this}
+     * Removes an event listener from the message handler.
+     *
+     * See {@link RpcClient.on} for a list of supported events.
+     *
+     * @param event - The event name to stop listening for.
+     * @param listener - The listener function to remove.
+     * @returns This instance for method chaining.
      */
     off(event, listener) {
-        // @ts-ignore messageHandler must be defined here
         this.messageHandler.off(event, listener);
         return this;
     }
     /**
+     * Waits for a target to be created for the specified app and page.
+     * If the target already exists, returns it immediately. Otherwise,
+     * waits up to the configured timeout for the target to be created.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @returns {Promise<import('../types').TargetId | undefined>}
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @returns A promise that resolves to the target ID if found, undefined otherwise.
+     * @throws Error if no target is found after the timeout.
      */
     async waitForTarget(appIdKey, pageIdKey) {
         let target = this.getTarget(appIdKey, pageIdKey);
@@ -203,11 +254,14 @@ class RpcClient {
         }
     }
     /**
+     * Sends a command to the remote debugger with automatic retry logic
+     * for target-related errors. Handles cases where targets are not yet
+     * available or not supported.
      *
-     * @param {string} command
-     * @param {import('../types').RemoteCommandOpts} opts
-     * @param {boolean} [waitForResponse=true]
-     * @returns {Promise<any>}
+     * @param command - The command name to send.
+     * @param opts - Options for the command.
+     * @param waitForResponse - Whether to wait for a response. Defaults to true.
+     * @returns A promise that resolves to the command result or options.
      */
     async send(command, opts, waitForResponse = true) {
         const timer = new support_1.timing.Timer().start();
@@ -221,7 +275,7 @@ class RpcClient {
                 return await this.sendToDevice(command, opts, waitForResponse);
             }
             else if (appIdKey && NO_TARGET_PRESENT_YET_ERRORS.some((error) => messageLc.includes(error))) {
-                await this.waitForTarget(appIdKey, /** @type {import('../types').PageIdKey} */ (pageIdKey));
+                await this.waitForTarget(appIdKey, pageIdKey);
                 return await this.sendToDevice(command, opts, waitForResponse);
             }
             throw err;
@@ -231,14 +285,17 @@ class RpcClient {
         }
     }
     /**
+     * Sends a command directly to the device, handling message routing,
+     * response waiting, and error handling.
      *
-     * @template {boolean} TWaitForResponse
-     * @param {string} command
-     * @param {import('../types').RemoteCommandOpts} opts
-     * @param {TWaitForResponse} [waitForResponse=true]
-     * @returns {Promise<TWaitForResponse extends true ? import('../types').RemoteCommandOpts : any>}
+     * @template TWaitForResponse - Whether to wait for a response.
+     * @param command - The command name to send.
+     * @param opts - Options for the command.
+     * @param waitForResponse - Whether to wait for a response. Defaults to true.
+     * @returns A promise that resolves based on waitForResponse:
+     *          - If true: resolves to the response value
+     *          - If false: resolves to the full options object
      */
-    // @ts-ignore Compiler issue
     async sendToDevice(command, opts, waitForResponse = true) {
         return await new bluebird_1.default(async (resolve, reject) => {
             // promise to be resolved whenever remote debugger
@@ -248,7 +305,6 @@ class RpcClient {
             // for target-base communication, everything is wrapped up
             const wrapperMsgId = this.msgId++;
             // acknowledge wrapper message
-            // @ts-ignore messageHandler must be defined
             this.messageHandler.on(wrapperMsgId.toString(), function (err) {
                 if (err) {
                     reject(err);
@@ -258,24 +314,20 @@ class RpcClient {
             const pageIdKey = opts.pageIdKey;
             const targetId = opts.targetId ?? this.getTarget(appIdKey, pageIdKey);
             // retrieve the correct command to send
-            /** @type {import('../types').RemoteCommandOpts} */
             const fullOpts = lodash_1.default.defaults({
                 connId: this.connId,
                 senderId: this.senderId,
                 targetId,
-                id: msgId,
+                id: msgId.toString(),
             }, opts);
-            /** @type {import('../types').RawRemoteCommand} */
             let cmd;
             try {
-                // @ts-ignore remoteMessages must be defined
                 cmd = this.remoteMessages.getRemoteCommand(command, fullOpts);
             }
             catch (err) {
                 logger_1.log.error(err);
                 return reject(err);
             }
-            /** @type {import('../types').RemoteCommand} */
             const finalCommand = {
                 __argument: lodash_1.default.omit(cmd.__argument, ['WIRSocketDataKey']),
                 __selector: cmd.__selector,
@@ -283,19 +335,18 @@ class RpcClient {
             const hasSocketData = lodash_1.default.isPlainObject(cmd.__argument?.WIRSocketDataKey);
             if (hasSocketData) {
                 // make sure the message being sent has all the information that is needed
-                // @ts-ignore We have asserted it's a plain object above
-                if (lodash_1.default.isNil(cmd.__argument.WIRSocketDataKey.id)) {
-                    // @ts-ignore We have already asserted it's a plain object above
-                    cmd.__argument.WIRSocketDataKey.id = wrapperMsgId;
+                const socketData = cmd.__argument.WIRSocketDataKey;
+                if (!lodash_1.default.isInteger(socketData.id)) {
+                    // ! This must be a number
+                    socketData.id = wrapperMsgId;
                 }
-                finalCommand.__argument.WIRSocketDataKey = Buffer.from(JSON.stringify(cmd.__argument.WIRSocketDataKey));
+                finalCommand.__argument.WIRSocketDataKey = Buffer.from(JSON.stringify(socketData));
             }
             let messageHandled = true;
             if (!waitForResponse) {
                 // the promise will be resolved as soon as the socket has been sent
                 messageHandled = false;
                 // do not log receipts
-                // @ts-ignore messageHandler must be defined
                 this.messageHandler.once(msgId.toString(), (err) => {
                     if (err) {
                         // we are not waiting for this, and if it errors it is most likely
@@ -303,26 +354,22 @@ class RpcClient {
                         logger_1.log.error(`Received error from send that is not being waited for (id: ${msgId}): ` +
                             lodash_1.default.truncate(JSON.stringify(err), DATA_LOG_LENGTH));
                         // reject, though it is very rare that this will be triggered, since
-                        // the promise is resolved directlty after send. On the off chance,
+                        // the promise is resolved directly after send. On the off chance,
                         // though, it will alert of a protocol change.
                         reject(err);
                     }
                 });
-                // @ts-ignore messageHandler must be defined
             }
-            else if (this.messageHandler.listeners(cmd.__selector).length) {
-                // @ts-ignore messageHandler must be defined
+            else if (this.messageHandler.listenerCount(cmd.__selector)) {
                 this.messageHandler.prependOnceListener(cmd.__selector, (err, ...args) => {
                     if (err) {
                         return reject(err);
                     }
                     logger_1.log.debug(`Received response from send (id: ${msgId}): '${lodash_1.default.truncate(JSON.stringify(args), DATA_LOG_LENGTH)}'`);
-                    // @ts-ignore This is ok
                     resolve(args);
                 });
             }
             else if (hasSocketData) {
-                // @ts-ignore messageHandler must be defined
                 this.messageHandler.once(msgId.toString(), (err, value) => {
                     if (err) {
                         return reject(new Error(`Remote debugger error with code '${err.code}': ${err.message}`));
@@ -346,7 +393,6 @@ class RpcClient {
                 if (!messageHandled) {
                     // There are no handlers waiting for a response before resolving,
                     // and no errors sending the message over the socket, so resolve
-                    // @ts-ignore This is ok
                     resolve(fullOpts);
                 }
             }
@@ -355,34 +401,47 @@ class RpcClient {
             }
         });
     }
+    /**
+     * Connects to the remote debugger. Must be implemented by subclasses.
+     *
+     * @throws Error indicating that subclasses must implement this method.
+     */
     async connect() {
         throw new Error(`Sub-classes need to implement a 'connect' function`);
     }
+    /**
+     * Disconnects from the remote debugger and cleans up event listeners.
+     */
     async disconnect() {
-        this.messageHandler?.removeAllListeners();
+        this.messageHandler.removeAllListeners();
     }
     /**
-     * @param {import('../types').RemoteCommand} command
-     * @returns {Promise<void>}
+     * Sends a message to the device. Must be implemented by subclasses.
+     *
+     * @param _command - The command to send.
+     * @throws Error indicating that subclasses must implement this method.
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    async sendMessage(command) {
+    async sendMessage(_command) {
         throw new Error(`Sub-classes need to implement a 'sendMessage' function`);
     }
     /**
-     * @param {any} data
-     * @returns {Promise<void>}
+     * Receives data from the device. Must be implemented by subclasses.
+     *
+     * @param _data - The data received from the device.
+     * @throws Error indicating that subclasses must implement this method.
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    async receive(data) {
+    async receive(_data) {
         throw new Error(`Sub-classes need to implement a 'receive' function`);
     }
     /**
+     * Handles the creation of a new target for an application and page.
+     * Initializes the page and waits for readiness if configured.
      *
-     * @param {Error | undefined} err
-     * @param {import('../types').AppIdKey} app
-     * @param {import('../types').TargetInfo} targetInfo
-     * @returns {Promise<void>}
+     * @param err - Error if one occurred, undefined otherwise.
+     * @param app - The application identifier key.
+     * @param targetInfo - Information about the created target.
      */
     async addTarget(err, app, targetInfo) {
         if (lodash_1.default.isNil(targetInfo?.targetId)) {
@@ -444,7 +503,8 @@ class RpcClient {
         }
         logger_1.log.debug(`Target created for app '${appIdKey}' and page '${pageIdKey}': ${JSON.stringify(targetInfo)}`);
         if (lodash_1.default.has(this.targets[appIdKey], pageIdKey)) {
-            logger_1.log.debug(`There is already a target for this app and page ('${this.targets[appIdKey][pageIdKey]}'). ` +
+            const existingTarget = this.targets[appIdKey][pageIdKey];
+            logger_1.log.debug(`There is already a target for this app and page ('${existingTarget}'). ` +
                 `This might cause problems`);
         }
         this.targets[appIdKey][pageIdKey] = targetInfo.targetId;
@@ -491,11 +551,11 @@ class RpcClient {
         }
     }
     /**
+     * Handles updates to provisional targets when they commit.
      *
-     * @param {Error | undefined} err
-     * @param {import('../types').AppIdKey} app
-     * @param {import('../types').ProvisionalTargetInfo} targetInfo
-     * @returns {Promise<void>}
+     * @param err - Error if one occurred, undefined otherwise.
+     * @param app - The application identifier key.
+     * @param targetInfo - Information about the provisional target update.
      */
     async updateTarget(err, app, targetInfo) {
         const { oldTargetId, newTargetId, } = targetInfo;
@@ -512,11 +572,11 @@ class RpcClient {
         };
     }
     /**
+     * Handles the destruction of a target, including cleanup of provisional targets.
      *
-     * @param {Error | undefined} err
-     * @param {import('../types').AppIdKey} app
-     * @param {import('../types').TargetInfo} targetInfo
-     * @returns {Promise<void>}
+     * @param err - Error if one occurred, undefined otherwise.
+     * @param app - The application identifier key.
+     * @param targetInfo - Information about the destroyed target.
      */
     async removeTarget(err, app, targetInfo) {
         if (lodash_1.default.isNil(targetInfo?.targetId)) {
@@ -552,21 +612,27 @@ class RpcClient {
         logger_1.log.debug(`Target '${targetInfo.targetId}' deleted for app '${app}', but no such target exists`);
     }
     /**
-     * @param {import('../types').AppIdKey} [appIdKey]
-     * @param {import('../types').PageIdKey} [pageIdKey]
-     * @returns {string | undefined}
+     * Gets the target ID for a specific app and page combination.
+     *
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @returns The target ID if found, undefined otherwise.
      */
     getTarget(appIdKey, pageIdKey) {
         if (!appIdKey || !pageIdKey) {
             return;
         }
-        return this.targets[appIdKey]?.[pageIdKey];
+        const target = this.targets[appIdKey]?.[pageIdKey];
+        return target && typeof target === 'string' ? target : undefined;
     }
     /**
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @param {PageReadinessDetector} [pageReadinessDetector]
-     * @returns {Promise<void>}
+     * Selects a page within an application, setting up the Web Inspector session
+     * and waiting for the page to be initialized. Mimics the steps that Desktop
+     * Safari uses to initialize a Web Inspector session.
+     *
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @param pageReadinessDetector - Optional detector for determining when the page is ready.
      */
     async selectPage(appIdKey, pageIdKey, pageReadinessDetector) {
         await this._pageSelectionLock.acquire(toPageSelectionKey(appIdKey, pageIdKey), async () => {
@@ -598,20 +664,18 @@ class RpcClient {
             const msLeft = Math.max(timeoutMs - Math.trunc(timer.getDuration().asMilliSeconds), 1000);
             logger_1.log.debug(`Waiting up to ${msLeft}ms for page '${pageIdKey}' of app '${appIdKey}' to be selected`);
             await new Promise((resolve) => {
-                const onPageInitialized = (
-                /** @type {import("../types").AppIdKey} */ notifiedAppIdKey, 
-                /** @type {import("../types").PageIdKey} */ notifiedPageIdKey) => {
+                const onPageInitialized = (notifiedAppIdKey, notifiedPageIdKey) => {
                     const timeoutHandler = setTimeout(() => {
                         this._pageSelectionMonitor.off(ON_PAGE_INITIALIZED_EVENT, onPageInitialized);
                         logger_1.log.warn(`Page '${pageIdKey}' for app '${appIdKey}' has not been selected ` +
                             `within ${timer.getDuration().asMilliSeconds}ms. Continuing anyway`);
-                        resolve(false);
+                        resolve();
                     }, msLeft);
                     if (notifiedAppIdKey === appIdKey && notifiedPageIdKey === pageIdKey) {
                         clearTimeout(timeoutHandler);
                         this._pageSelectionMonitor.off(ON_PAGE_INITIALIZED_EVENT, onPageInitialized);
                         logger_1.log.debug(`Selected the page ${pageIdKey}@${appIdKey} after ${timer.getDuration().asMilliSeconds}ms`);
-                        resolve(true);
+                        resolve();
                     }
                     else {
                         logger_1.log.debug(`Got notified that page ${notifiedPageIdKey}@${notifiedAppIdKey} is initialized, ` +
@@ -623,13 +687,15 @@ class RpcClient {
         });
     }
     /**
-     * Mimic every step that Desktop Safari Develop tools uses to initialize a
-     * Web Inspector session
+     * Initializes a page by enabling various Web Inspector domains.
+     * Can perform either simple or full initialization based on configuration.
+     * Mimics the steps that Desktop Safari Develop tools uses to initialize
+     * a Web Inspector session.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @param {import('../types').TargetId} [targetId]
-     * @returns {Promise<boolean>}
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @param targetId - Optional target ID. If not provided, will be retrieved from the targets map.
+     * @returns A promise that resolves to true if initialization succeeded, false otherwise.
      */
     async _initializePage(appIdKey, pageIdKey, targetId) {
         const sendOpts = {
@@ -725,7 +791,7 @@ class RpcClient {
             try {
                 const res = await this.send(domain, opts);
                 if (domain === 'Console.getLoggingChannels') {
-                    for (const source of (res?.channels || []).map((/** @type {{ source: any; }} */ entry) => entry.source)) {
+                    for (const source of (res?.channels || []).map((entry) => entry.source)) {
                         try {
                             await this.send('Console.setLoggingChannelLevel', Object.assign({
                                 source,
@@ -753,9 +819,13 @@ class RpcClient {
         return true;
     }
     /**
+     * Connects to a specific application and returns its page dictionary.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @returns {Promise<[string, Record<string, any>]>}
+     * @param appIdKey - The application identifier key to connect to.
+     * @returns A promise that resolves to a tuple containing the connected app ID key
+     *          and the page dictionary.
+     * @throws Error if a new application connects during the process or if the page
+     *               dictionary is empty.
      */
     async selectApp(appIdKey) {
         return await new bluebird_1.default((resolve, reject) => {
@@ -777,7 +847,7 @@ class RpcClient {
                 }
                 reject(new Error(exports.NEW_APP_CONNECTED_ERROR));
             };
-            this.messageHandler?.prependOnceListener('_rpc_applicationConnected:', onAppChange);
+            this.messageHandler.prependOnceListener('_rpc_applicationConnected:', onAppChange);
             // do the actual connecting to the app
             (async () => {
                 try {
@@ -796,15 +866,16 @@ class RpcClient {
                     reject(err);
                 }
                 finally {
-                    this.messageHandler?.off('_rpc_applicationConnected:', onAppChange);
+                    this.messageHandler.off('_rpc_applicationConnected:', onAppChange);
                 }
             })();
         });
     }
     /**
+     * Handles execution context creation events by storing the context ID.
      *
-     * @param {Error?} err
-     * @param {Record<string, any>} context
+     * @param err - Error if one occurred, undefined otherwise.
+     * @param context - The execution context information.
      */
     onExecutionContextCreated(err, context) {
         // { id: 2, isPageContext: true, name: '', frameId: '0.1' }
@@ -813,27 +884,29 @@ class RpcClient {
         this.contexts.push(context.id);
     }
     /**
-     * @returns {void}
+     * Handles garbage collection events by logging them.
+     * Garbage collection can affect operation timing.
      */
     onGarbageCollected() {
-        // just want to log that this is happening, as it can affect opertion
+        // just want to log that this is happening, as it can affect operation
         logger_1.log.debug(`Web Inspector garbage collected`);
     }
     /**
+     * Handles script parsing events by logging script information.
      *
-     * @param {Error?} err
-     * @param {Record<string, any>} scriptInfo
+     * @param err - Error if one occurred, undefined otherwise.
+     * @param scriptInfo - Information about the parsed script.
      */
     onScriptParsed(err, scriptInfo) {
         // { scriptId: '13', url: '', startLine: 0, startColumn: 0, endLine: 82, endColumn: 3 }
         logger_1.log.debug(`Script parsed: ${JSON.stringify(scriptInfo)}`);
     }
     /**
+     * Resumes a paused target.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @param {import('../types').TargetId} targetId
-     * @returns {Promise<void>}
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @param targetId - The target ID to resume.
      */
     async _resumeTarget(appIdKey, pageIdKey, targetId) {
         try {
@@ -849,12 +922,13 @@ class RpcClient {
         }
     }
     /**
+     * Waits for a page to be ready by periodically checking the document readyState.
+     * Uses the provided readiness detector to determine when the page is ready.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @param {import('../types').TargetId} targetId
-     * @param {PageReadinessDetector} [pageReadinessDetector]
-     * @returns {Promise<void>}
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @param targetId - The target ID.
+     * @param pageReadinessDetector - The detector for determining page readiness.
      */
     async _waitForPageReadiness(appIdKey, pageIdKey, targetId, pageReadinessDetector) {
         if (!pageReadinessDetector) {
@@ -863,7 +937,6 @@ class RpcClient {
         logger_1.log.debug(`Waiting up to ${pageReadinessDetector.timeoutMs}ms for page readiness`);
         const timer = new support_1.timing.Timer().start();
         while (pageReadinessDetector.timeoutMs - timer.getDuration().asMilliSeconds > 0) {
-            /** @type {string} */
             let readyState;
             try {
                 const commandTimeoutMs = Math.max(100, Math.trunc((pageReadinessDetector.timeoutMs - timer.getDuration().asMilliSeconds) * 0.8));
@@ -891,10 +964,12 @@ class RpcClient {
             `${timer.getDuration().asMilliSeconds}ms. Continuing anyway`);
     }
     /**
+     * Waits for a page to be initialized by acquiring locks on both the page
+     * target lock and the page selection lock.
      *
-     * @param {import('../types').AppIdKey} appIdKey
-     * @param {import('../types').PageIdKey} pageIdKey
-     * @returns {Promise<void>}
+     * @param appIdKey - The application identifier key.
+     * @param pageIdKey - The page identifier key.
+     * @throws Error if no targets are found for the application.
      */
     async waitForPage(appIdKey, pageIdKey) {
         const appTargetsMap = this.targets[appIdKey];
@@ -913,14 +988,15 @@ class RpcClient {
         }
     }
     /**
-     * Get the pending target details if there is a pending request.
+     * Gets the pending target details if there is a pending request for the given app.
+     * Filters out non-page target types (e.g., 'frame').
      *
-     * @param {import('../types').AppIdKey} appId
-     * @param {import('../types').TargetInfo} targetInfo
-     * @returns {PendingPageTargetDetails | undefined}
+     * @param appId - The application identifier key.
+     * @param targetInfo - Information about the target.
+     * @returns The pending page target details if there's a match, undefined otherwise.
      */
     _getPendingPageTargetDetails(appId, targetInfo) {
-        const logInfo = (/** @type {string} */ message) => void logger_1.log.info(`Skipping 'Target.targetCreated' event ${message} for app '${appId}': ${JSON.stringify(targetInfo)}`);
+        const logInfo = (message) => void logger_1.log.info(`Skipping 'Target.targetCreated' event ${message} for app '${appId}': ${JSON.stringify(targetInfo)}`);
         if (!this._pendingTargetNotification) {
             return logInfo('with no pending request');
         }
@@ -938,45 +1014,13 @@ class RpcClient {
 }
 exports.RpcClient = RpcClient;
 /**
+ * Creates a unique key for page selection based on app and page IDs.
  *
- * @param {import('../types').AppIdKey} appIdKey
- * @param {import('../types').PageIdKey} pageIdKey
- * @returns {string}
+ * @param appIdKey - The application identifier key.
+ * @param pageIdKey - The page identifier key.
+ * @returns A string key combining both identifiers.
  */
 function toPageSelectionKey(appIdKey, pageIdKey) {
     return `${appIdKey}:${pageIdKey}`;
 }
-exports.default = RpcClient;
-/**
- * @typedef {Object} RpcClientOptions
- * @property {string} [bundleId]
- * @property {string} [platformVersion='']
- * @property {boolean} [isSafari=true]
- * @property {boolean} [logAllCommunication=false]
- * @property {boolean} [logAllCommunicationHexDump=false]
- * @property {number} [webInspectorMaxFrameLength]
- * @property {number} [socketChunkSize]
- * @property {boolean} [fullPageInitialization=false]
- * @property {number} [pageLoadTimeoutMs]
- * @property {string} [udid]
- * @property {number} [targetCreationTimeoutMs]
- */
-/**
- * @typedef {Object} PendingPageTargetDetails
- * @property {import('../types').AppIdKey} appIdKey
- * @property {import('../types').PageIdKey} pageIdKey
- * @property {PageReadinessDetector | undefined} pageReadinessDetector
- */
-/**
- * @typedef {{[key: import('../types').PageIdKey]: import('../types').TargetId}} PageDict
- */
-/**
- * @typedef {PageDict & {provisional?: import('../types').ProvisionalTargetInfo, lock: AsyncLock}} PagesToTargets
- * @typedef {{[key: import('../types').AppIdKey]: PagesToTargets}} AppToTargetsMap
- */
-/**
- * @typedef {Object} PageReadinessDetector
- * @property {number} timeoutMs
- * @property {(readyState: string) => boolean} readinessDetector
- */
 //# sourceMappingURL=rpc-client.js.map