@push.rocks/smartpuppeteer 2.1.0 → 2.3.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -1,8 +1,18 @@
 import { getEnvAwareBrowserInstance } from './smartpuppeteer.classes.smartpuppeteer.js';
+import {
+  delay,
+  type IOwnedProcessIdentity,
+  killFrozenOwnedProcessGroup,
+  listOwnedProcessGroupMembers,
+  readOwnedProcessIdentity,
+  signalOwnedProcessIdentity,
+  signalOwnedProcessGroup,
+} from './smartpuppeteer.helpers.process.js';
 import type {
   ILiveBrowserClickOptions,
   ILiveBrowserCreateTabOptions,
   ILiveBrowserError,
+  ILiveBrowserEvaluateOptions,
   ILiveBrowserFillOptions,
   ILiveBrowserFrame,
   ILiveBrowserFrameAcknowledgement,
@@ -15,17 +25,22 @@ import type {
   ILiveBrowserNavigationOptions,
   ILiveBrowserObservation,
   ILiveBrowserObserveOptions,
+  ILiveBrowserOperationOptions,
   ILiveBrowserPressOptions,
+  ILiveBrowserProcessState,
   ILiveBrowserSessionOptions,
   ILiveBrowserSnapshot,
   ILiveBrowserSnapshotOptions,
   ILiveBrowserState,
   ILiveBrowserTabState,
+  ILiveBrowserTerminationOptions,
+  ILiveBrowserTerminationResult,
   ILiveBrowserViewport,
   ILiveBrowserWheelInput,
   TLiveBrowserEvent,
   TLiveBrowserEventListener,
   TLiveBrowserImageFormat,
+  TLiveBrowserJsonValue,
   TLiveBrowserWaitUntil,
 } from './smartpuppeteer.interfaces.livebrowser.js';
 import * as plugins from './smartpuppeteer.plugins.js';
@@ -47,10 +62,62 @@ const maxTimeoutMs = 60000;
 const maxOutstandingFrames = 3;
 const maxQueuedPublicOperations = 64;
 const maxQueuedInternalOperations = 128;
+const maxEvaluationScriptBytes = 262144;
+const maxEvaluationOutputBytes = 1048576;
+const maxEvaluationDepth = 32;
+const maxEvaluationNodes = 50000;
+const maxEvaluationStringBytes = 262144;
+const maxEvaluationArrayLength = 10000;
+const maxEvaluationObjectKeys = 10000;
+const evaluationBootstrapKey = '__smartpuppeteerEvaluate';
+const evaluationCancelKey = '__smartpuppeteerCancel';
+const evaluationCleanupKey = '__smartpuppeteerCleanup';
+const maxProxySecuritySessions = 256;
+const maxTrackedProxyRequests = 1024;
+const maxTotalTrackedProxyRequests = 4096;
+const maxProxySecurityOperations = 2048;
+const proxySeedTargetTypes = new Set([
+  'background_page',
+  'page',
+  'service_worker',
+  'shared_worker',
+  'webview',
+]);
+const proxyFetchUnsupportedTargetTypes = new Set(['tab', 'worker']);
 
 type TScreencastFrameEvent = plugins.puppeteer.Protocol.Page.ScreencastFrameEvent;
 type TScreencastFrameListener = (event: TScreencastFrameEvent) => void;
 type TCdpSessionDetachedListener = (session: plugins.puppeteer.CDPSession) => void;
+type TOwnedChildProcess = NonNullable<ReturnType<plugins.puppeteer.Browser['process']>>;
+type TProxyAuthRequiredEvent = plugins.puppeteer.Protocol.Fetch.AuthRequiredEvent;
+type TProxyRequestPausedEvent = plugins.puppeteer.Protocol.Fetch.RequestPausedEvent;
+type TNetworkLoadingFinishedEvent = plugins.puppeteer.Protocol.Network.LoadingFinishedEvent;
+type TNetworkLoadingFailedEvent = plugins.puppeteer.Protocol.Network.LoadingFailedEvent;
+
+interface IProxySecuritySession {
+  session: plugins.puppeteer.CDPSession;
+  generation: number;
+  targetId?: string;
+  targetType?: string;
+  fetchEnabled: boolean;
+  allowLiveTargetDetach: boolean;
+  ownedByProxySecurity: boolean;
+  attemptedAuthentications: Set<string>;
+  requestIdsByNetworkId: Map<string, string>;
+  authRequiredListener: (event: TProxyAuthRequiredEvent) => void;
+  requestPausedListener: (event: TProxyRequestPausedEvent) => void;
+  loadingFinishedListener: (event: TNetworkLoadingFinishedEvent) => void;
+  loadingFailedListener: (event: TNetworkLoadingFailedEvent) => void;
+  setupPromise: Promise<void>;
+}
+
+interface IOwnedBrowserProcess {
+  generation: number;
+  childProcess: TOwnedChildProcess;
+  identity?: IOwnedProcessIdentity;
+  exitPromise: Promise<void>;
+  forceSignalled: boolean;
+}
 
 interface IPrivateLiveBrowserTab {
   id: string;
@@ -67,6 +134,8 @@ interface IPrivateLiveBrowserTab {
   stateUpdateQueued: boolean;
   stateUpdatePending: boolean;
   navigationResetPending: boolean;
+  evaluationExecutionContextId?: number;
+  securityCdpSession?: plugins.puppeteer.CDPSession;
   cdpSession?: plugins.puppeteer.CDPSession;
   cdpConnection?: plugins.puppeteer.Connection;
   screencastFrameListener?: TScreencastFrameListener;
@@ -87,14 +156,34 @@ interface IImageDimensions {
   height: number;
 }
 
+interface INormalizedEvaluationOptions {
+  timeoutMs: number;
+  maxOutputBytes: number;
+  maxDepth: number;
+  maxNodes: number;
+  maxStringBytes: number;
+  maxArrayLength: number;
+  maxObjectKeys: number;
+}
+
+interface IEvaluationEnvelope {
+  ok: boolean;
+  json?: string;
+  error?: string;
+}
+
 type TQueuedOperationKind = 'public' | 'internal' | 'shutdown';
+type TQueuedOperationState = 'queued' | 'active' | 'settled';
 
 interface IQueuedOperation {
   kind: TQueuedOperationKind;
+  state: TQueuedOperationState;
   controller: AbortController;
   run: (signal: AbortSignal) => Promise<unknown>;
   resolve: (value: unknown) => void;
   reject: (error: unknown) => void;
+  capacityReleased: boolean;
+  removeCallerAbortListener?: () => void;
 }
 
 const validateBoundedString = (
@@ -163,6 +252,10 @@ const normalizeErrorMessage = (error: unknown): string => {
   return truncate(String(error), 2048);
 };
 
+const normalizeAbortReason = (signal: AbortSignal): unknown => {
+  return signal.reason ?? new Error('The browser operation was aborted');
+};
+
 const readUint32 = (data: Uint8Array, offset: number): number => {
   return (
     data[offset]! * 0x1000000
@@ -279,6 +372,20 @@ export class LiveBrowserSession {
   private browserContext?: plugins.puppeteer.BrowserContext;
   private browserLifetimeController?: AbortController;
   private browserDisconnectedListener?: () => void;
+  private browserTargetCreatedListener?: (target: plugins.puppeteer.Target) => void;
+  private browserSecurityCdpSession?: plugins.puppeteer.CDPSession;
+  private browserSecurityConnection?: plugins.puppeteer.Connection;
+  private browserSecuritySessionAttachedListener?: (session: plugins.puppeteer.CDPSession) => void;
+  private browserSecuritySessionDetachedListener?: TCdpSessionDetachedListener;
+  private readonly proxySecuritySessions = new Map<string, IProxySecuritySession>();
+  private readonly proxySecurityOperations = new Set<Promise<void>>();
+  private proxySecurityGeneration = 0;
+  private proxySecurityStopping = false;
+  private ownedBrowserProcess?: IOwnedBrowserProcess;
+  private processGeneration = 0;
+  private startRequestCount = 0;
+  private terminationSettled = true;
+  private terminationPromise?: Promise<ILiveBrowserTerminationResult>;
   private readonly operationQueue: IQueuedOperation[] = [];
   private activeOperation?: IQueuedOperation;
   private operationRunning = false;
@@ -291,6 +398,7 @@ export class LiveBrowserSession {
   private viewportRevision = 1;
   private tabSequence = 0;
   private frameSequence = 0;
+  private evaluationSequence = 0;
   private normalStopRequested = false;
   private lastError?: ILiveBrowserError;
 
@@ -310,6 +418,33 @@ export class LiveBrowserSession {
     if (optionsArg.launchOptions && 'signal' in optionsArg.launchOptions) {
       throw new Error('LiveBrowserSession owns launch cancellation; launchOptions.signal is unsupported');
     }
+    validateOptionalBoolean(optionsArg.allowEvaluation, 'allowEvaluation');
+    for (const name of [
+      'denyDownloads',
+      'denyFileChoosers',
+      'denyPermissions',
+      'httpNavigationOnly',
+    ] as const) {
+      validateOptionalBoolean(optionsArg.security?.[name], `security.${name}`);
+    }
+    const proxyCredentials = optionsArg.security?.proxyCredentials;
+    if (proxyCredentials !== undefined) {
+      if (!proxyCredentials || typeof proxyCredentials !== 'object') {
+        throw new Error('security.proxyCredentials must be an object');
+      }
+      validateBoundedString(
+        proxyCredentials.username,
+        'security.proxyCredentials.username',
+        1,
+        256,
+      );
+      validateBoundedString(
+        proxyCredentials.password,
+        'security.proxyCredentials.password',
+        1,
+        1024,
+      );
+    }
     const launchViewport = optionsArg.launchOptions?.defaultViewport;
     const viewport = normalizeViewport(
       optionsArg.viewport
@@ -327,9 +462,18 @@ export class LiveBrowserSession {
         ...optionsArg.launchOptions,
         args: [...(optionsArg.launchOptions?.args ?? [])],
         defaultViewport: createPuppeteerViewport(viewport),
+        ...(optionsArg.security?.denyDownloads
+          ? { downloadBehavior: { policy: 'deny' as const } }
+          : {}),
       },
       viewport,
       screencast: optionsArg.screencast ? { ...optionsArg.screencast } : undefined,
+      security: optionsArg.security
+        ? {
+            ...optionsArg.security,
+            proxyCredentials: proxyCredentials ? { ...proxyCredentials } : undefined,
+          }
+        : undefined,
     };
     this.viewport = { ...viewport };
     this.validateScreencastOptions();
@@ -356,12 +500,86 @@ export class LiveBrowserSession {
     };
   }
 
-  public async start(): Promise<void> {
-    return this.enqueuePublicOperation(async (signal) => {
+  public getProcessState(): ILiveBrowserProcessState {
+    const ownedProcess = this.ownedBrowserProcess;
+    if (!ownedProcess) {
+      return {
+        generation: this.processGeneration,
+        pid: null,
+        processGroupId: null,
+        running: false,
+        exitCode: null,
+        signalCode: null,
+      };
+    }
+    const childProcess = ownedProcess.childProcess;
+    return {
+      generation: ownedProcess.generation,
+      pid: childProcess.pid ?? null,
+      processGroupId: ownedProcess.identity?.processGroupId ?? null,
+      running: childProcess.exitCode === null && childProcess.signalCode === null,
+      exitCode: childProcess.exitCode,
+      signalCode: childProcess.signalCode,
+    };
+  }
+
+  public terminate(
+    optionsArg: ILiveBrowserTerminationOptions = {},
+  ): Promise<ILiveBrowserTerminationResult> {
+    if (this.terminationPromise) {
+      return this.terminationPromise;
+    }
+    const gracefulTimeoutMs = optionsArg.gracefulTimeoutMs === undefined
+      ? 5000
+      : validateInteger(optionsArg.gracefulTimeoutMs, 'gracefulTimeoutMs', 1, 60000);
+    const forceTimeoutMs = optionsArg.forceTimeoutMs === undefined
+      ? 5000
+      : validateInteger(optionsArg.forceTimeoutMs, 'forceTimeoutMs', 1, 60000);
+    let resolveTermination!: (result: ILiveBrowserTerminationResult) => void;
+    let rejectTermination!: (error: unknown) => void;
+    const terminationPromise = new Promise<ILiveBrowserTerminationResult>((resolve, reject) => {
+      resolveTermination = resolve;
+      rejectTermination = reject;
+    });
+    this.terminationPromise = terminationPromise;
+    this.terminationSettled = false;
+    void this.terminateInternal(gracefulTimeoutMs, forceTimeoutMs).then(
+      (result) => {
+        this.terminationSettled = true;
+        resolveTermination(result);
+      },
+      (error) => {
+        if (this.terminationPromise === terminationPromise) {
+          this.terminationPromise = undefined;
+        }
+        this.terminationSettled = true;
+        rejectTermination(error);
+      },
+    );
+    return terminationPromise;
+  }
+
+  public start(operationOptions: ILiveBrowserOperationOptions = {}): Promise<void> {
+    if (!this.terminationSettled) {
+      return Promise.reject(new Error('A browser termination is still in progress'));
+    }
+    if (!this.ownedBrowserProcess && this.status === 'stopped') {
+      this.terminationPromise = undefined;
+    }
+    this.startRequestCount += 1;
+    const startPromise = this.enqueuePublicOperation(async (signal) => {
       if (this.status === 'running' || this.status === 'starting') {
         return;
       }
 
+      await this.releaseExitedOwnedProcess();
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      if (this.ownedBrowserProcess) {
+        throw new Error('A previous owned Chromium process has not been confirmed dead');
+      }
+
       this.normalStopRequested = false;
       this.lastError = undefined;
       this.viewportRevision = 1;
@@ -377,19 +595,77 @@ export class LiveBrowserSession {
         if (browserLifetimeController.signal.aborted) {
           throw browserLifetimeController.signal.reason;
         }
-        this.browser = await getEnvAwareBrowserInstance({
-          forceNoSandbox: this.options.forceNoSandbox,
-          usePipe: this.options.usePipe,
-          launchOptions: {
-            ...this.options.launchOptions,
-            protocol: 'cdp',
-            signal: browserLifetimeController.signal,
-          },
+        const abortBrowserLaunch = (): void => {
+          if (!browserLifetimeController.signal.aborted) {
+            browserLifetimeController.abort(normalizeAbortReason(signal));
+          }
+        };
+        signal.addEventListener('abort', abortBrowserLaunch, { once: true });
+        try {
+          this.browser = await getEnvAwareBrowserInstance({
+            forceNoSandbox: this.options.forceNoSandbox,
+            requireSandbox: this.options.requireSandbox,
+            usePipe: this.options.usePipe,
+            launchOptions: {
+              ...this.options.launchOptions,
+              protocol: 'cdp',
+              signal: browserLifetimeController.signal,
+            },
+          });
+        } finally {
+          signal.removeEventListener('abort', abortBrowserLaunch);
+        }
+        const childProcess = this.browser.process();
+        if (!childProcess?.pid) {
+          throw new Error('LiveBrowserSession did not receive an owned Chromium process');
+        }
+        const exitPromise = new Promise<void>((resolve) => {
+          if (childProcess.exitCode !== null || childProcess.signalCode !== null) {
+            resolve();
+            return;
+          }
+          childProcess.once('exit', () => resolve());
         });
+        this.processGeneration += 1;
+        this.ownedBrowserProcess = {
+          generation: this.processGeneration,
+          childProcess,
+          exitPromise,
+          forceSignalled: false,
+        };
+        const identity = process.platform === 'linux'
+          ? await readOwnedProcessIdentity(childProcess.pid)
+          : undefined;
+        if (process.platform === 'linux' && !identity) {
+          throw new Error('The owned Chromium process exited before its identity was captured');
+        }
+        if (
+          identity
+          && (identity.processGroupId !== childProcess.pid || identity.sessionId !== childProcess.pid)
+        ) {
+          throw new Error('Chromium was not launched as a dedicated process-group leader');
+        }
+        this.ownedBrowserProcess.identity = identity;
         if (signal.aborted) {
           throw signal.reason;
         }
         this.browserContext = this.browser.defaultBrowserContext();
+        this.browserTargetCreatedListener = (target) => {
+          if (target.type() !== 'page' || target.browserContext() !== this.browserContext) {
+            return;
+          }
+          void target.page().then((page) => {
+            if (page) {
+              this.scheduleDiscoveredPageRegistration(page);
+            }
+          }).catch((error) => {
+            if (!this.normalStopRequested && this.status !== 'stopped' && this.status !== 'stopping') {
+              this.handleDiscoveredPageFailure(error);
+            }
+          });
+        };
+        this.browser.on('targetcreated', this.browserTargetCreatedListener);
+        await this.configureBrowserSecurity(this.browser);
         this.browserDisconnectedListener = () => {
           if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
             return;
@@ -432,9 +708,19 @@ export class LiveBrowserSession {
         this.status = 'running';
         this.emitState();
         await this.startScreencast(firstTab);
+        if (signal.aborted) {
+          throw normalizeAbortReason(signal);
+        }
       } catch (error) {
         if (signal.aborted || this.normalStopRequested) {
-          await this.stopInternal();
+          try {
+            await this.stopInternal();
+          } catch (cleanupError) {
+            throw new AggregateError(
+              [error, cleanupError],
+              'Cancelled browser startup cleanup was incomplete',
+            );
+          }
           throw error;
         }
         const startError: ILiveBrowserError = {
@@ -443,9 +729,19 @@ export class LiveBrowserSession {
           fatal: true,
         };
         this.emitError(startError);
-        await this.stopInternal(startError);
+        try {
+          await this.stopInternal(startError);
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'Browser startup failed and cleanup was incomplete',
+          );
+        }
         throw error;
       }
+    }, operationOptions);
+    return startPromise.finally(() => {
+      this.startRequestCount -= 1;
     });
   }
 
@@ -508,6 +804,7 @@ export class LiveBrowserSession {
 
   public async createTab(
     optionsArg: ILiveBrowserCreateTabOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
   ): Promise<ILiveBrowserTabState> {
     const url = optionsArg.url === undefined ? undefined : this.validateUrl(optionsArg.url);
     const activate = optionsArg.activate ?? true;
@@ -563,16 +860,22 @@ export class LiveBrowserSession {
         }
         throw error;
       }
-    });
+    }, operationOptions);
   }
 
-  public async activateTab(tabId: string): Promise<void> {
+  public async activateTab(
+    tabId: string,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     return this.enqueuePublicOperation(async () => {
       await this.activateTabInternal(tabId);
-    });
+    }, operationOptions);
   }
 
-  public async closeTab(tabId: string): Promise<void> {
+  public async closeTab(
+    tabId: string,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     return this.enqueuePublicOperation(async () => {
       const tab = this.requireTab(tabId);
       const wasActive = this.activeTabId === tab.id;
@@ -609,10 +912,13 @@ export class LiveBrowserSession {
       } else {
         this.emitState();
       }
-    });
+    }, operationOptions);
   }
 
-  public async navigate(optionsArg: ILiveBrowserNavigateOptions): Promise<void> {
+  public async navigate(
+    optionsArg: ILiveBrowserNavigateOptions,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const url = this.validateUrl(optionsArg.url);
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.resolveNavigationTab(optionsArg.tabId);
@@ -623,10 +929,13 @@ export class LiveBrowserSession {
         },
         signal,
       );
-    });
+    }, operationOptions);
   }
 
-  public async back(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+  public async back(
+    optionsArg: ILiveBrowserNavigationOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.resolveNavigationTab(optionsArg.tabId);
       await this.navigateTab(
@@ -636,10 +945,13 @@ export class LiveBrowserSession {
         },
         signal,
       );
-    });
+    }, operationOptions);
   }
 
-  public async forward(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+  public async forward(
+    optionsArg: ILiveBrowserNavigationOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.resolveNavigationTab(optionsArg.tabId);
       await this.navigateTab(
@@ -649,10 +961,13 @@ export class LiveBrowserSession {
         },
         signal,
       );
-    });
+    }, operationOptions);
   }
 
-  public async reload(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+  public async reload(
+    optionsArg: ILiveBrowserNavigationOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.resolveNavigationTab(optionsArg.tabId);
       await this.navigateTab(
@@ -662,10 +977,13 @@ export class LiveBrowserSession {
         },
         signal,
       );
-    });
+    }, operationOptions);
   }
 
-  public async setViewport(viewportArg: ILiveBrowserViewport): Promise<void> {
+  public async setViewport(
+    viewportArg: ILiveBrowserViewport,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const viewport = normalizeViewport(viewportArg);
     return this.enqueuePublicOperation(async (signal) => {
       const tab = this.requireActiveTab();
@@ -684,7 +1002,7 @@ export class LiveBrowserSession {
           await this.startScreencast(tab);
         }
       }
-    });
+    }, operationOptions);
   }
 
   public async dispatchMouse(input: ILiveBrowserMouseInput): Promise<void> {
@@ -815,6 +1133,7 @@ export class LiveBrowserSession {
 
   public async captureSnapshot(
     optionsArg: ILiveBrowserSnapshotOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
   ): Promise<ILiveBrowserSnapshot> {
     const format = optionsArg.format ?? 'jpeg';
     if (format !== 'jpeg' && format !== 'png') {
@@ -858,10 +1177,13 @@ export class LiveBrowserSession {
         ...dimensions,
         data,
       };
-    });
+    }, operationOptions);
   }
 
-  public async observe(optionsArg: ILiveBrowserObserveOptions = {}): Promise<ILiveBrowserObservation> {
+  public async observe(
+    optionsArg: ILiveBrowserObserveOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<ILiveBrowserObservation> {
     const maxCharacters = optionsArg.maxCharacters === undefined
       ? 12000
       : validateInteger(optionsArg.maxCharacters, 'maxCharacters', 256, 50000);
@@ -948,10 +1270,203 @@ export class LiveBrowserSession {
         text: truncatedText,
         truncated: reachedTraversalLimit || unboundedText.length > maxCharacters,
       };
-    });
+    }, operationOptions);
+  }
+
+  public async evaluate(
+    expressionArg: string,
+    optionsArg: ILiveBrowserEvaluateOptions = {},
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<TLiveBrowserJsonValue> {
+    if (!this.options.allowEvaluation) {
+      throw new Error('LiveBrowserSession evaluation is disabled');
+    }
+    const expression = validateBoundedString(
+      expressionArg,
+      'expression',
+      1,
+      maxEvaluationScriptBytes,
+    );
+    const expressionBytes = new TextEncoder().encode(expression).byteLength;
+    if (expressionBytes > maxEvaluationScriptBytes) {
+      throw new Error(`expression must not exceed ${maxEvaluationScriptBytes} UTF-8 bytes`);
+    }
+    const evaluationOptions = this.normalizeEvaluationOptions(optionsArg);
+    const evaluationId = ++this.evaluationSequence;
+    const cancellationKey = `__smartpuppeteerCancel${evaluationId}`;
+    const evaluationExpression = this.createEvaluationExpression(
+      expression,
+      evaluationOptions,
+      cancellationKey,
+    );
+
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveActionTab(optionsArg.tabId);
+      const cdpSession = await tab.page.createCDPSession();
+      this.allowOperationalCdpSessionDetach(cdpSession);
+      let executionContextId: number | undefined;
+      let cancellationPromise: Promise<void> | undefined;
+      let terminationPromise: Promise<void> | undefined;
+      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+      let evaluationTimedOut = false;
+      const terminateEvaluation = (): void => {
+        terminationPromise ??= cdpSession.send('Runtime.terminateExecution').then(() => undefined);
+      };
+      const cancelEvaluation = (): void => {
+        if (executionContextId === undefined) {
+          return;
+        }
+        cancellationPromise ??= cdpSession.send('Runtime.evaluate', {
+          expression: `globalThis[${JSON.stringify(evaluationCancelKey)}]?.(${JSON.stringify(cancellationKey)})`,
+          contextId: executionContextId,
+          returnByValue: true,
+          awaitPromise: false,
+          includeCommandLineAPI: false,
+          userGesture: false,
+          disableBreaks: true,
+        }).then(() => undefined);
+      };
+      signal.addEventListener('abort', cancelEvaluation, { once: true });
+      let evaluationError: unknown;
+      let evaluationFailed = false;
+      try {
+        if (signal.aborted) {
+          throw normalizeAbortReason(signal);
+        }
+        executionContextId = tab.evaluationExecutionContextId;
+        if (executionContextId === undefined) {
+          const frameTreeResponse = await cdpSession.send('Page.getFrameTree');
+          if (signal.aborted) {
+            throw normalizeAbortReason(signal);
+          }
+          const isolatedWorld = await cdpSession.send('Page.createIsolatedWorld', {
+            frameId: frameTreeResponse.frameTree.frame.id,
+            worldName: 'smartpuppeteer-evaluation',
+            grantUniveralAccess: false,
+          });
+          executionContextId = isolatedWorld.executionContextId;
+          tab.evaluationExecutionContextId = executionContextId;
+        }
+        if (signal.aborted) {
+          throw normalizeAbortReason(signal);
+        }
+        const bootstrapResponse = await cdpSession.send('Runtime.evaluate', {
+          expression: this.createEvaluationBootstrapExpression(),
+          contextId: executionContextId,
+          returnByValue: true,
+          awaitPromise: true,
+          includeCommandLineAPI: false,
+          userGesture: false,
+          disableBreaks: true,
+        });
+        if (bootstrapResponse.exceptionDetails) {
+          throw new Error(this.readCdpExceptionMessage(bootstrapResponse.exceptionDetails));
+        }
+        if (signal.aborted) {
+          throw normalizeAbortReason(signal);
+        }
+        timeoutHandle = setTimeout(() => {
+          evaluationTimedOut = true;
+          terminateEvaluation();
+        }, evaluationOptions.timeoutMs + 250);
+        const evaluationResponse = await cdpSession.send('Runtime.evaluate', {
+          expression: evaluationExpression,
+          contextId: executionContextId,
+          returnByValue: true,
+          awaitPromise: true,
+          timeout: evaluationOptions.timeoutMs + 250,
+          includeCommandLineAPI: false,
+          userGesture: false,
+          disableBreaks: true,
+          allowUnsafeEvalBlockedByCSP: true,
+        });
+        if (evaluationTimedOut) {
+          throw new Error(`Evaluation timed out after ${evaluationOptions.timeoutMs}ms`);
+        }
+        if (signal.aborted) {
+          throw normalizeAbortReason(signal);
+        }
+        if (evaluationResponse.exceptionDetails) {
+          throw new Error(this.readCdpExceptionMessage(evaluationResponse.exceptionDetails));
+        }
+        const envelope = evaluationResponse.result.value as IEvaluationEnvelope | undefined;
+        if (!envelope || typeof envelope !== 'object' || typeof envelope.ok !== 'boolean') {
+          throw new Error('Evaluation returned an invalid result envelope');
+        }
+        if (!envelope.ok) {
+          throw new Error(
+            typeof envelope.error === 'string'
+              ? truncate(envelope.error, 2048)
+              : 'Evaluation failed',
+          );
+        }
+        if (typeof envelope.json !== 'string') {
+          throw new Error('Evaluation returned an invalid JSON result');
+        }
+        if (new TextEncoder().encode(envelope.json).byteLength > evaluationOptions.maxOutputBytes) {
+          throw new Error('Evaluation result exceeded maxOutputBytes during transfer');
+        }
+        return JSON.parse(envelope.json) as TLiveBrowserJsonValue;
+      } catch (error) {
+        evaluationError = error;
+        evaluationFailed = true;
+        throw error;
+      } finally {
+        signal.removeEventListener('abort', cancelEvaluation);
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+        const cleanupErrors: unknown[] = [];
+        if (cancellationPromise) {
+          try {
+            await cancellationPromise;
+          } catch (error) {
+            cleanupErrors.push(error);
+          }
+        }
+        if (terminationPromise) {
+          try {
+            await terminationPromise;
+          } catch (error) {
+            cleanupErrors.push(error);
+          }
+        }
+        if (executionContextId !== undefined && !cdpSession.detached) {
+          try {
+            await cdpSession.send('Runtime.evaluate', {
+              expression: `globalThis[${JSON.stringify(evaluationCleanupKey)}]?.(${JSON.stringify(cancellationKey)})`,
+              contextId: executionContextId,
+              returnByValue: true,
+              awaitPromise: false,
+              includeCommandLineAPI: false,
+              userGesture: false,
+              disableBreaks: true,
+            });
+          } catch {
+            // Navigation destroys the old execution context and its cancellation registry.
+          }
+        }
+        if (!cdpSession.detached) {
+          try {
+            await cdpSession.detach();
+          } catch (error) {
+            cleanupErrors.push(error);
+          }
+        }
+        if (cleanupErrors.length > 0) {
+          throw new AggregateError(
+            evaluationFailed ? [evaluationError, ...cleanupErrors] : cleanupErrors,
+            'Evaluation cleanup was incomplete',
+          );
+        }
+      }
+    }, operationOptions);
   }
 
-  public async click(optionsArg: ILiveBrowserClickOptions): Promise<void> {
+  public async click(
+    optionsArg: ILiveBrowserClickOptions,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const selector = validateBoundedString(
       optionsArg.selector,
       'selector',
@@ -977,10 +1492,13 @@ export class LiveBrowserSession {
       });
       await this.refreshTab(actionTab);
       this.emitState();
-    });
+    }, operationOptions);
   }
 
-  public async fill(optionsArg: ILiveBrowserFillOptions): Promise<void> {
+  public async fill(
+    optionsArg: ILiveBrowserFillOptions,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const selector = validateBoundedString(
       optionsArg.selector,
       'selector',
@@ -996,10 +1514,13 @@ export class LiveBrowserSession {
       await actionTab.page.locator(selector).setTimeout(timeout).fill(text, { signal });
       await this.refreshTab(actionTab);
       this.emitState();
-    });
+    }, operationOptions);
   }
 
-  public async press(optionsArg: ILiveBrowserPressOptions): Promise<void> {
+  public async press(
+    optionsArg: ILiveBrowserPressOptions,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const selector = validateBoundedString(
       optionsArg.selector,
       'selector',
@@ -1027,12 +1548,27 @@ export class LiveBrowserSession {
       }
       await this.refreshTab(actionTab);
       this.emitState();
-    });
+    }, operationOptions);
   }
 
   private enqueuePublicOperation<T>(
     operation: (signal: AbortSignal) => Promise<T>,
+    operationOptions: ILiveBrowserOperationOptions = {},
   ): Promise<T> {
+    const callerSignal = operationOptions.signal;
+    if (
+      callerSignal !== undefined
+      && (
+        typeof callerSignal !== 'object'
+        || typeof callerSignal.addEventListener !== 'function'
+        || typeof callerSignal.removeEventListener !== 'function'
+      )
+    ) {
+      return Promise.reject(new Error('operationOptions.signal must be an AbortSignal'));
+    }
+    if (callerSignal?.aborted) {
+      return Promise.reject(normalizeAbortReason(callerSignal));
+    }
     if (
       this.status === 'stopping'
       || this.normalStopRequested
@@ -1044,7 +1580,25 @@ export class LiveBrowserSession {
       return Promise.reject(new Error('LiveBrowserSession operation queue is full'));
     }
     this.admittedPublicOperations += 1;
-    return this.enqueueQueuedOperation('public', operation);
+    return this.enqueueQueuedOperation('public', async (signal) => {
+      this.assertProxySecurityReady();
+      return operation(signal);
+    }, false, callerSignal);
+  }
+
+  private assertProxySecurityReady(): void {
+    if (!this.options.security?.proxyCredentials || this.status !== 'running') {
+      return;
+    }
+    if (
+      !this.browserSecurityConnection
+      || !this.browserSecurityCdpSession
+      || this.browserSecurityCdpSession.detached
+    ) {
+      const error = new Error('Authenticated proxy security is not attached');
+      this.handleProxySecurityFailure('proxy_security_unavailable', error);
+      throw error;
+    }
   }
 
   private enqueueInternalOperation(
@@ -1062,15 +1616,45 @@ export class LiveBrowserSession {
     kind: TQueuedOperationKind,
     operation: (signal: AbortSignal) => Promise<T>,
     priority = false,
+    callerSignal?: AbortSignal,
   ): Promise<T> {
     return new Promise<T>((resolve, reject) => {
       const queuedOperation: IQueuedOperation = {
         kind,
+        state: 'queued',
         controller: new AbortController(),
         run: operation,
         resolve: (value) => resolve(value as T),
         reject,
+        capacityReleased: false,
       };
+      if (callerSignal) {
+        const onCallerAbort = (): void => {
+          const abortReason = normalizeAbortReason(callerSignal);
+          if (queuedOperation.state === 'queued') {
+            const operationIndex = this.operationQueue.indexOf(queuedOperation);
+            if (operationIndex >= 0) {
+              this.operationQueue.splice(operationIndex, 1);
+            }
+            queuedOperation.controller.abort(abortReason);
+            queuedOperation.reject(abortReason);
+            this.finalizeQueuedOperation(queuedOperation);
+            this.drainOperationQueue();
+          } else if (queuedOperation.state === 'active') {
+            queuedOperation.controller.abort(abortReason);
+          }
+        };
+        callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        queuedOperation.removeCallerAbortListener = () => {
+          callerSignal.removeEventListener('abort', onCallerAbort);
+        };
+        if (callerSignal.aborted) {
+          onCallerAbort();
+        }
+      }
+      if (queuedOperation.state !== 'queued') {
+        return;
+      }
       if (priority) {
         this.operationQueue.unshift(queuedOperation);
       } else {
@@ -1090,6 +1674,7 @@ export class LiveBrowserSession {
     }
     this.operationRunning = true;
     this.activeOperation = queuedOperation;
+    queuedOperation.state = 'active';
     void this.executeQueuedOperation(queuedOperation).catch((error) => {
       this.operationRunning = false;
       this.activeOperation = undefined;
@@ -1107,15 +1692,15 @@ export class LiveBrowserSession {
       if (queuedOperation.controller.signal.aborted) {
         throw queuedOperation.controller.signal.reason;
       }
-      queuedOperation.resolve(await queuedOperation.run(queuedOperation.controller.signal));
+      const value = await queuedOperation.run(queuedOperation.controller.signal);
+      if (queuedOperation.controller.signal.aborted) {
+        throw queuedOperation.controller.signal.reason;
+      }
+      queuedOperation.resolve(value);
     } catch (error) {
       queuedOperation.reject(error);
     } finally {
-      if (queuedOperation.kind === 'public') {
-        this.admittedPublicOperations -= 1;
-      } else if (queuedOperation.kind === 'internal') {
-        this.admittedInternalOperations -= 1;
-      }
+      this.finalizeQueuedOperation(queuedOperation);
       if (this.activeOperation === queuedOperation) {
         this.activeOperation = undefined;
       }
@@ -1130,15 +1715,29 @@ export class LiveBrowserSession {
     }
   }
 
+  private finalizeQueuedOperation(queuedOperation: IQueuedOperation): void {
+    if (queuedOperation.state === 'settled') {
+      return;
+    }
+    queuedOperation.state = 'settled';
+    queuedOperation.removeCallerAbortListener?.();
+    queuedOperation.removeCallerAbortListener = undefined;
+    if (queuedOperation.capacityReleased) {
+      return;
+    }
+    queuedOperation.capacityReleased = true;
+    if (queuedOperation.kind === 'public') {
+      this.admittedPublicOperations -= 1;
+    } else if (queuedOperation.kind === 'internal') {
+      this.admittedInternalOperations -= 1;
+    }
+  }
+
   private cancelQueuedOperations(error: Error): void {
     for (const queuedOperation of this.operationQueue.splice(0)) {
       queuedOperation.controller.abort(error);
-      if (queuedOperation.kind === 'public') {
-        this.admittedPublicOperations -= 1;
-      } else if (queuedOperation.kind === 'internal') {
-        this.admittedInternalOperations -= 1;
-      }
       queuedOperation.reject(error);
+      this.finalizeQueuedOperation(queuedOperation);
     }
   }
 
@@ -1162,7 +1761,8 @@ export class LiveBrowserSession {
   }
 
   private requestShutdown(error?: ILiveBrowserError): Promise<void> {
-    if (this.status === 'stopped') {
+    if (this.status === 'stopped' && !this.operationRunning && this.startRequestCount === 0) {
+      this.normalStopRequested = false;
       return Promise.resolve();
     }
     if (this.shutdownPromise) {
@@ -1275,57 +1875,325 @@ export class LiveBrowserSession {
     };
   }
 
-  private async stopInternal(error?: ILiveBrowserError): Promise<void> {
-    if (this.status === 'stopped') {
+  private async releaseExitedOwnedProcess(): Promise<void> {
+    const ownedProcess = this.ownedBrowserProcess;
+    if (!ownedProcess) {
       return;
     }
-    this.status = 'stopping';
-    if (error) {
-      this.lastError = { ...error };
+    if (
+      ownedProcess.childProcess.exitCode === null
+      && ownedProcess.childProcess.signalCode === null
+    ) {
+      await Promise.race([ownedProcess.exitPromise, delay(100)]);
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        return;
+      }
     }
-    this.emitState();
-    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
-      this.browserLifetimeController.abort(new Error('LiveBrowserSession is stopping'));
+    if (process.platform === 'linux' && !ownedProcess.identity) {
+      return;
     }
-
-    const browser = this.browser;
-    if (browser && this.browserDisconnectedListener) {
-      browser.off('disconnected', this.browserDisconnectedListener);
+    if (ownedProcess.identity) {
+      const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (members.length > 0) {
+        return;
+      }
     }
-    this.browserDisconnectedListener = undefined;
+    this.ownedBrowserProcess = undefined;
+  }
 
-    const shutdownErrors: unknown[] = [];
-    for (const tab of [...this.tabs.values()]) {
-      tab.closing = true;
-      try {
-        await this.stopScreencast(tab);
-      } catch (cleanupError) {
-        shutdownErrors.push(cleanupError);
+  private async terminateInternal(
+    gracefulTimeoutMs: number,
+    forceTimeoutMs: number,
+  ): Promise<ILiveBrowserTerminationResult> {
+    const errors: string[] = [];
+    let shutdownSettled = this.status === 'stopped';
+    const shutdownObserved = this.stop().then(
+      () => {
+        shutdownSettled = true;
+      },
+      (error) => {
+        errors.push(normalizeErrorMessage(error));
+        shutdownSettled = true;
+      },
+    );
+    const createConfirmedResult = (
+      ownedProcess: IOwnedBrowserProcess | undefined,
+      forced: boolean,
+    ): ILiveBrowserTerminationResult => {
+      const childProcess = ownedProcess?.childProcess;
+      const result: ILiveBrowserTerminationResult = {
+        generation: ownedProcess?.generation ?? this.processGeneration,
+        pid: childProcess?.pid ?? null,
+        processGroupId: ownedProcess?.identity?.processGroupId ?? null,
+        running: false,
+        exitCode: childProcess?.exitCode ?? null,
+        signalCode: childProcess?.signalCode ?? null,
+        forced: forced || Boolean(ownedProcess?.forceSignalled),
+        shutdownComplete: true,
+        confirmedDead: true,
+        errors,
+      };
+      if (this.ownedBrowserProcess === ownedProcess) {
+        this.ownedBrowserProcess = undefined;
       }
-      try {
-        this.removePageListeners(tab);
-      } catch (cleanupError) {
-        shutdownErrors.push(cleanupError);
+      return result;
+    };
+    const isConfirmedDead = async (
+      ownedProcess: IOwnedBrowserProcess | undefined,
+    ): Promise<boolean> => {
+      if (!ownedProcess) {
+        return true;
       }
-    }
-    try {
-      await this.retireOutstandingFrames(() => true);
-    } catch (cleanupError) {
-      shutdownErrors.push(cleanupError);
-    }
+      if (process.platform !== 'linux' || !ownedProcess.identity) {
+        if (process.platform === 'linux' && this.startRequestCount > 0) {
+          return false;
+        }
+        throw new Error('Confirmed browser process-group termination is supported on Linux only');
+      }
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        return false;
+      }
+      const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (members.length > 0) {
+        return false;
+      }
+      return true;
+    };
 
-    if (browser) {
-      try {
-        await browser.close();
-      } catch (closeError) {
-        shutdownErrors.push(closeError);
+    const gracefulDeadline = Date.now() + gracefulTimeoutMs;
+    while (Date.now() < gracefulDeadline) {
+      const ownedProcess = this.ownedBrowserProcess;
+      if (
+        await isConfirmedDead(ownedProcess)
+        && shutdownSettled
+        && this.status === 'stopped'
+      ) {
+        return createConfirmedResult(ownedProcess, false);
+      }
+      if (shutdownSettled) {
+        await delay(100);
+      } else {
+        await Promise.race([shutdownObserved, delay(100)]);
       }
     }
 
-    for (const tab of this.tabs.values()) {
-      this.tabIdsByPage.delete(tab.page);
+    const ownedProcess = this.ownedBrowserProcess;
+    let forced = false;
+    if (ownedProcess) {
+      if (process.platform !== 'linux') {
+        throw new Error('Confirmed browser process-group termination is supported on Linux only');
+      }
+      if (ownedProcess.identity) {
+        const membersBeforeFreeze = await listOwnedProcessGroupMembers(ownedProcess.identity);
+        if (membersBeforeFreeze.length > 0) {
+          forced = true;
+          const groupStopped = await signalOwnedProcessGroup(ownedProcess.identity, 'SIGSTOP');
+          if (groupStopped) {
+            killFrozenOwnedProcessGroup(ownedProcess.identity);
+          } else {
+            await this.killOwnedProcessGroupSurvivors(ownedProcess.identity, membersBeforeFreeze);
+          }
+        }
+      } else if (this.startRequestCount === 0) {
+        throw new Error('Owned Chromium process identity was never confirmed');
+      }
     }
-    this.tabs.clear();
+
+    const forceDeadline = Date.now() + forceTimeoutMs;
+    while (Date.now() < forceDeadline) {
+      const currentOwnedProcess = this.ownedBrowserProcess;
+      if (
+        await isConfirmedDead(currentOwnedProcess)
+        && shutdownSettled
+        && this.status === 'stopped'
+      ) {
+        return createConfirmedResult(currentOwnedProcess, forced);
+      }
+      if (shutdownSettled) {
+        await delay(100);
+      } else {
+        await Promise.race([shutdownObserved, delay(100)]);
+      }
+    }
+
+    const remainingOwnedProcess = this.ownedBrowserProcess;
+    if (remainingOwnedProcess?.identity) {
+      const survivors = await listOwnedProcessGroupMembers(remainingOwnedProcess.identity);
+      if (survivors.length > 0) {
+        throw new Error(
+          `Owned Chromium process group did not terminate: ${survivors.map((item) => item.pid).join(', ')}`,
+        );
+      }
+    }
+    if (!shutdownSettled || this.status !== 'stopped') {
+      throw new Error(
+        'Owned Chromium process group exited but LiveBrowserSession shutdown did not settle',
+      );
+    }
+    throw new Error('Owned Chromium process exit was not confirmed by Node.js');
+  }
+
+  private async killOwnedProcessGroupSurvivors(
+    rootIdentity: IOwnedProcessIdentity,
+    initialMembers: IOwnedProcessIdentity[],
+  ): Promise<void> {
+    let previousKeys = new Set(initialMembers.map((member) => `${member.pid}:${member.startTime}`));
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      const members = await listOwnedProcessGroupMembers(rootIdentity);
+      if (members.length === 0) {
+        return;
+      }
+      for (const member of members) {
+        await signalOwnedProcessIdentity(member, 'SIGSTOP');
+      }
+      await delay(10);
+      const frozenMembers = await listOwnedProcessGroupMembers(rootIdentity);
+      const currentKeys = new Set(
+        frozenMembers.map((member) => `${member.pid}:${member.startTime}`),
+      );
+      const sameMembers = currentKeys.size === previousKeys.size
+        && [...currentKeys].every((key) => previousKeys.has(key));
+      const allFrozen = frozenMembers.every((member) => (
+        member.state === 'T' || member.state === 't' || member.state === 'Z'
+      ));
+      if (sameMembers && allFrozen) {
+        for (const member of frozenMembers) {
+          await signalOwnedProcessIdentity(member, 'SIGKILL');
+        }
+        return;
+      }
+      previousKeys = currentKeys;
+    }
+    throw new Error('Unable to stabilize the surviving Chromium process group');
+  }
+
+  private async forceOwnedBrowserProcessGroup(
+    ownedProcess: IOwnedBrowserProcess,
+  ): Promise<void> {
+    ownedProcess.forceSignalled = true;
+    if (process.platform !== 'linux') {
+      ownedProcess.childProcess.kill('SIGKILL');
+      await Promise.race([ownedProcess.exitPromise, delay(5000)]);
+      if (
+        ownedProcess.childProcess.exitCode === null
+        && ownedProcess.childProcess.signalCode === null
+      ) {
+        throw new Error('Owned Chromium process did not exit after SIGKILL');
+      }
+      return;
+    }
+    if (!ownedProcess.identity) {
+      throw new Error('Owned Chromium process identity was never confirmed');
+    }
+    const members = await listOwnedProcessGroupMembers(ownedProcess.identity);
+    if (members.length > 0) {
+      const groupStopped = await signalOwnedProcessGroup(ownedProcess.identity, 'SIGSTOP');
+      if (groupStopped) {
+        killFrozenOwnedProcessGroup(ownedProcess.identity);
+      } else {
+        await this.killOwnedProcessGroupSurvivors(ownedProcess.identity, members);
+      }
+    }
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+      const survivors = await listOwnedProcessGroupMembers(ownedProcess.identity);
+      if (survivors.length === 0) {
+        await Promise.race([ownedProcess.exitPromise, delay(100)]);
+        if (
+          ownedProcess.childProcess.exitCode !== null
+          || ownedProcess.childProcess.signalCode !== null
+        ) {
+          return;
+        }
+      }
+      await delay(100);
+    }
+    throw new Error('Owned Chromium process group survived forced startup cleanup');
+  }
+
+  private async stopInternal(error?: ILiveBrowserError): Promise<void> {
+    if (this.status === 'stopped') {
+      return;
+    }
+    this.status = 'stopping';
+    if (error) {
+      this.lastError = { ...error };
+    }
+    this.emitState();
+    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
+      this.browserLifetimeController.abort(new Error('LiveBrowserSession is stopping'));
+    }
+
+    const browser = this.browser;
+    if (browser && this.browserTargetCreatedListener) {
+      browser.off('targetcreated', this.browserTargetCreatedListener);
+    }
+    this.browserTargetCreatedListener = undefined;
+    if (browser && this.browserDisconnectedListener) {
+      browser.off('disconnected', this.browserDisconnectedListener);
+    }
+    this.browserDisconnectedListener = undefined;
+
+    const shutdownErrors: unknown[] = [];
+    try {
+      await this.teardownProxySecurity();
+    } catch (cleanupError) {
+      shutdownErrors.push(cleanupError);
+    }
+    for (const tab of [...this.tabs.values()]) {
+      tab.closing = true;
+      const securityCdpSession = tab.securityCdpSession;
+      tab.securityCdpSession = undefined;
+      if (securityCdpSession && !securityCdpSession.detached) {
+        try {
+          await securityCdpSession.detach();
+        } catch {
+          // Browser lifetime cancellation may close the target before explicit detach settles.
+        }
+      }
+      try {
+        await this.stopScreencast(tab);
+      } catch (cleanupError) {
+        shutdownErrors.push(cleanupError);
+      }
+      try {
+        this.removePageListeners(tab);
+      } catch (cleanupError) {
+        shutdownErrors.push(cleanupError);
+      }
+    }
+    try {
+      await this.retireOutstandingFrames(() => true);
+    } catch (cleanupError) {
+      shutdownErrors.push(cleanupError);
+    }
+
+    if (browser) {
+      try {
+        await browser.close();
+      } catch (closeError) {
+        shutdownErrors.push(closeError);
+        const ownedProcess = this.ownedBrowserProcess;
+        if (ownedProcess) {
+          try {
+            await this.forceOwnedBrowserProcessGroup(ownedProcess);
+          } catch (forceError) {
+            shutdownErrors.push(forceError);
+          }
+        }
+      }
+    }
+
+    for (const tab of this.tabs.values()) {
+      this.tabIdsByPage.delete(tab.page);
+    }
+    this.tabs.clear();
     this.outstandingFrames.clear();
     this.browser = undefined;
     this.browserContext = undefined;
@@ -1333,11 +2201,452 @@ export class LiveBrowserSession {
     this.activeTabId = null;
     this.status = 'stopped';
     this.emitState();
-    if (shutdownErrors.length > 0 && !error) {
+    if (shutdownErrors.length > 0) {
       throw new AggregateError(shutdownErrors, 'LiveBrowserSession shutdown was incomplete');
     }
   }
 
+  private async configureBrowserSecurity(
+    browser: plugins.puppeteer.Browser,
+  ): Promise<void> {
+    const denyPermissions = this.options.security?.denyPermissions;
+    const proxyCredentials = this.options.security?.proxyCredentials;
+    if (!denyPermissions && !proxyCredentials) {
+      return;
+    }
+    const cdpSession = await browser.target().createCDPSession();
+    if (!proxyCredentials) {
+      try {
+        if (denyPermissions) {
+          await cdpSession.send('Browser.grantPermissions', { permissions: [] });
+        }
+      } finally {
+        if (!cdpSession.detached) {
+          await cdpSession.detach();
+        }
+      }
+      return;
+    }
+
+    const generation = this.ownedBrowserProcess?.generation;
+    if (generation === undefined) {
+      throw new Error('Proxy security requires an owned browser generation');
+    }
+    this.proxySecurityStopping = false;
+    this.proxySecurityGeneration = generation;
+    this.browserSecurityCdpSession = cdpSession;
+    try {
+      if (denyPermissions) {
+        await cdpSession.send('Browser.grantPermissions', { permissions: [] });
+      }
+      const browserSecurityConnection = cdpSession.connection();
+      if (!browserSecurityConnection) {
+        throw new Error('Browser security CDP session has no connection');
+      }
+      this.browserSecurityConnection = browserSecurityConnection;
+      this.browserSecuritySessionAttachedListener = (attachedSession) => {
+        this.trackProxySecurityOperation(
+          this.configureProxySecuritySession(attachedSession, generation),
+          generation,
+          'proxy_security_session_setup_failed',
+        );
+      };
+      this.browserSecuritySessionDetachedListener = (detachedSession) => {
+        if (detachedSession === cdpSession) {
+          this.handleProxySecurityFailure(
+            'proxy_security_browser_session_detached',
+            new Error('Browser security CDP session detached unexpectedly'),
+            generation,
+          );
+          return;
+        }
+        this.trackProxySecurityOperation(
+          this.verifyProxySecuritySessionDetached(detachedSession, generation),
+          generation,
+          'proxy_security_detach_verification_failed',
+        );
+      };
+      browserSecurityConnection.on(
+        'sessionattached',
+        this.browserSecuritySessionAttachedListener,
+      );
+      browserSecurityConnection.on(
+        'sessiondetached',
+        this.browserSecuritySessionDetachedListener,
+      );
+
+      for (const target of browser.targets()) {
+        if (!proxySeedTargetTypes.has(target.type())) {
+          continue;
+        }
+        const securitySession = await target.createCDPSession();
+        const securityRecord = this.proxySecuritySessions.get(securitySession.id());
+        if (!securityRecord) {
+          throw new Error(`Proxy security did not observe session ${securitySession.id()}`);
+        }
+        securityRecord.ownedByProxySecurity = true;
+        await securityRecord.setupPromise;
+      }
+    } catch (error) {
+      await this.teardownProxySecurity();
+      throw error;
+    }
+  }
+
+  private configureProxySecuritySession(
+    session: plugins.puppeteer.CDPSession,
+    generation: number,
+  ): Promise<void> {
+    const existing = this.proxySecuritySessions.get(session.id());
+    if (existing) {
+      if (existing.generation !== generation) {
+        return Promise.reject(new Error(`CDP session ${session.id()} crossed browser generations`));
+      }
+      return existing.setupPromise;
+    }
+    if (this.proxySecuritySessions.size >= maxProxySecuritySessions) {
+      return Promise.reject(
+        new Error(`Proxy security exceeded ${maxProxySecuritySessions} CDP sessions`),
+      );
+    }
+
+    const attemptedAuthentications = new Set<string>();
+    const requestIdsByNetworkId = new Map<string, string>();
+    const handleProtocolFailure = (operation: string, error: unknown): void => {
+      this.handleProxySecurityFailure(
+        'proxy_security_protocol_failed',
+        new Error(`${operation}: ${normalizeErrorMessage(error)}`),
+        generation,
+      );
+    };
+    const authRequiredListener = (event: TProxyAuthRequiredEvent): void => {
+      const credentials = this.options.security?.proxyCredentials;
+      const totalTrackedRequests = [...this.proxySecuritySessions.values()].reduce(
+        (total, record) => total
+          + record.attemptedAuthentications.size
+          + record.requestIdsByNetworkId.size,
+        0,
+      );
+      const hasTrackingCapacity = attemptedAuthentications.size < maxTrackedProxyRequests
+        && totalTrackedRequests < maxTotalTrackedProxyRequests;
+      const isFirstProxyAttempt = event.authChallenge.source === 'Proxy'
+        && !attemptedAuthentications.has(event.requestId)
+        && hasTrackingCapacity;
+      if (isFirstProxyAttempt) {
+        attemptedAuthentications.add(event.requestId);
+      } else if (
+        event.authChallenge.source === 'Proxy'
+        && !attemptedAuthentications.has(event.requestId)
+        && !hasTrackingCapacity
+      ) {
+        handleProtocolFailure(
+          'Proxy authentication tracking failed',
+          new Error(`A security session exceeded ${maxTrackedProxyRequests} tracked requests`),
+        );
+      }
+      const authChallengeResponse = isFirstProxyAttempt && credentials
+        ? {
+            response: 'ProvideCredentials' as const,
+            username: credentials.username,
+            password: credentials.password,
+          }
+        : { response: 'CancelAuth' as const };
+      this.trackProxySecurityOperation(
+        session.send('Fetch.continueWithAuth', {
+          requestId: event.requestId,
+          authChallengeResponse,
+        }).then(() => undefined),
+        generation,
+        'proxy_security_protocol_failed',
+      );
+    };
+    const requestPausedListener = (event: TProxyRequestPausedEvent): void => {
+      if (event.networkId) {
+        const totalTrackedRequests = [...this.proxySecuritySessions.values()].reduce(
+          (total, record) => total
+            + record.attemptedAuthentications.size
+            + record.requestIdsByNetworkId.size,
+          0,
+        );
+        if (
+          !requestIdsByNetworkId.has(event.networkId)
+          && (
+            requestIdsByNetworkId.size >= maxTrackedProxyRequests
+            || totalTrackedRequests >= maxTotalTrackedProxyRequests
+          )
+        ) {
+          handleProtocolFailure(
+            'Proxy request tracking failed',
+            new Error(`A security session exceeded ${maxTrackedProxyRequests} tracked requests`),
+          );
+        } else {
+          const previousRequestId = requestIdsByNetworkId.get(event.networkId);
+          if (previousRequestId && previousRequestId !== event.requestId) {
+            attemptedAuthentications.delete(previousRequestId);
+          }
+          requestIdsByNetworkId.set(event.networkId, event.requestId);
+        }
+      }
+      this.trackProxySecurityOperation(
+        session.send('Fetch.continueRequest', { requestId: event.requestId }).then(() => undefined),
+        generation,
+        'proxy_security_protocol_failed',
+      );
+    };
+    const forgetAuthentication = (networkId: string): void => {
+      const requestId = requestIdsByNetworkId.get(networkId);
+      if (!requestId) {
+        return;
+      }
+      requestIdsByNetworkId.delete(networkId);
+      attemptedAuthentications.delete(requestId);
+    };
+    const loadingFinishedListener = (event: TNetworkLoadingFinishedEvent): void => {
+      forgetAuthentication(event.requestId);
+    };
+    const loadingFailedListener = (event: TNetworkLoadingFailedEvent): void => {
+      forgetAuthentication(event.requestId);
+    };
+    session.on('Fetch.authRequired', authRequiredListener);
+    session.on('Fetch.requestPaused', requestPausedListener);
+    session.on('Network.loadingFinished', loadingFinishedListener);
+    session.on('Network.loadingFailed', loadingFailedListener);
+
+    const proxySecuritySession: IProxySecuritySession = {
+      session,
+      generation,
+      fetchEnabled: false,
+      allowLiveTargetDetach: false,
+      ownedByProxySecurity: false,
+      attemptedAuthentications,
+      requestIdsByNetworkId,
+      authRequiredListener,
+      requestPausedListener,
+      loadingFinishedListener,
+      loadingFailedListener,
+      setupPromise: Promise.resolve(),
+    };
+    const targetInfoPromise = session.send('Target.getTargetInfo');
+    const networkEnablePromise = session.send('Network.enable');
+    const fetchEnablePromise = session.send('Fetch.enable', {
+      handleAuthRequests: true,
+      patterns: [{ urlPattern: '*' }],
+    });
+    const commandResultsPromise = Promise.allSettled([
+      targetInfoPromise,
+      networkEnablePromise,
+      fetchEnablePromise,
+    ]);
+    const setupPromise = (async (): Promise<void> => {
+      try {
+        const [targetInfoResult, networkResult, fetchResult] = await commandResultsPromise;
+        if (targetInfoResult.status === 'rejected') {
+          throw targetInfoResult.reason;
+        }
+        const { targetInfo } = targetInfoResult.value;
+        proxySecuritySession.targetId = targetInfo.targetId;
+        proxySecuritySession.targetType = targetInfo.type;
+        if (fetchResult.status === 'rejected') {
+          const unsupportedTarget = proxyFetchUnsupportedTargetTypes.has(targetInfo.type)
+            && fetchResult.reason instanceof plugins.puppeteer.ProtocolError
+            && fetchResult.reason.originalMessage === "'Fetch.enable' wasn't found";
+          if (unsupportedTarget) {
+            this.removeProxySecuritySession(proxySecuritySession);
+            return;
+          }
+          throw fetchResult.reason;
+        }
+        if (networkResult.status === 'rejected') {
+          throw networkResult.reason;
+        }
+        proxySecuritySession.fetchEnabled = true;
+      } catch (error) {
+        this.removeProxySecuritySession(proxySecuritySession);
+        if (session.detached || this.proxySecurityStopping || this.normalStopRequested) {
+          return;
+        }
+        throw error;
+      }
+    })();
+    proxySecuritySession.setupPromise = setupPromise;
+    this.proxySecuritySessions.set(session.id(), proxySecuritySession);
+    return setupPromise;
+  }
+
+  private async verifyProxySecuritySessionDetached(
+    session: plugins.puppeteer.CDPSession,
+    generation: number,
+  ): Promise<void> {
+    const proxySecuritySession = this.proxySecuritySessions.get(session.id());
+    if (!proxySecuritySession || proxySecuritySession.generation !== generation) {
+      return;
+    }
+    this.removeProxySecuritySession(proxySecuritySession);
+    if (this.proxySecurityStopping || this.normalStopRequested || this.status !== 'running') {
+      return;
+    }
+    if (proxySecuritySession.allowLiveTargetDetach) {
+      return;
+    }
+    if (!proxySecuritySession.targetId) {
+      throw new Error(`Proxy security session detached before target identification: ${session.id()}`);
+    }
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const generationSessions = [...this.proxySecuritySessions.values()].filter((candidate) => (
+        candidate.generation === generation
+      ));
+      await Promise.allSettled(generationSessions.map((candidate) => candidate.setupPromise));
+      const hasReplacement = [...this.proxySecuritySessions.values()].some((candidate) => (
+        candidate.generation === generation
+        && candidate.targetId === proxySecuritySession.targetId
+        && candidate.fetchEnabled
+        && !candidate.session.detached
+      ));
+      if (hasReplacement) {
+        return;
+      }
+      if (attempt < 2) {
+        await delay(25);
+      }
+    }
+    const browserSecurityCdpSession = this.browserSecurityCdpSession;
+    if (!browserSecurityCdpSession || browserSecurityCdpSession.detached) {
+      throw new Error('Browser security CDP session detached unexpectedly');
+    }
+    const { targetInfos } = await browserSecurityCdpSession.send('Target.getTargets');
+    if (targetInfos.some((targetInfo) => targetInfo.targetId === proxySecuritySession.targetId)) {
+      throw new Error(
+        `Proxy security detached from live target ${proxySecuritySession.targetId}`,
+      );
+    }
+  }
+
+  private removeProxySecuritySession(proxySecuritySession: IProxySecuritySession): void {
+    if (this.proxySecuritySessions.get(proxySecuritySession.session.id()) !== proxySecuritySession) {
+      return;
+    }
+    proxySecuritySession.session.off('Fetch.authRequired', proxySecuritySession.authRequiredListener);
+    proxySecuritySession.session.off('Fetch.requestPaused', proxySecuritySession.requestPausedListener);
+    proxySecuritySession.session.off(
+      'Network.loadingFinished',
+      proxySecuritySession.loadingFinishedListener,
+    );
+    proxySecuritySession.session.off(
+      'Network.loadingFailed',
+      proxySecuritySession.loadingFailedListener,
+    );
+    proxySecuritySession.attemptedAuthentications.clear();
+    proxySecuritySession.requestIdsByNetworkId.clear();
+    this.proxySecuritySessions.delete(proxySecuritySession.session.id());
+  }
+
+  private allowOperationalCdpSessionDetach(session: plugins.puppeteer.CDPSession): void {
+    const proxySecuritySession = this.proxySecuritySessions.get(session.id());
+    if (proxySecuritySession) {
+      proxySecuritySession.allowLiveTargetDetach = true;
+    }
+  }
+
+  private trackProxySecurityOperation(
+    operation: Promise<void>,
+    generation: number,
+    errorCode: string,
+  ): void {
+    if (this.proxySecurityOperations.size >= maxProxySecurityOperations) {
+      void operation.catch(() => undefined);
+      this.handleProxySecurityFailure(
+        'proxy_security_operation_capacity_exceeded',
+        new Error(`Proxy security exceeded ${maxProxySecurityOperations} protocol operations`),
+        generation,
+      );
+      return;
+    }
+    let trackedOperation: Promise<void>;
+    trackedOperation = operation.catch((error) => {
+      this.handleProxySecurityFailure(errorCode, error, generation);
+    }).finally(() => {
+      this.proxySecurityOperations.delete(trackedOperation);
+    });
+    this.proxySecurityOperations.add(trackedOperation);
+  }
+
+  private handleProxySecurityFailure(
+    code: string,
+    error: unknown,
+    generation = this.proxySecurityGeneration,
+  ): void {
+    if (
+      generation !== this.proxySecurityGeneration
+      || this.proxySecurityStopping
+      || this.normalStopRequested
+      || this.status === 'stopped'
+      || this.status === 'stopping'
+    ) {
+      return;
+    }
+    const liveBrowserError: ILiveBrowserError = {
+      code,
+      message: normalizeErrorMessage(error),
+      fatal: true,
+    };
+    this.emitError(liveBrowserError);
+    this.beginShutdown(true);
+    void this.terminate().catch((terminationError) => {
+      this.emitError({
+        code: 'proxy_security_termination_failed',
+        message: normalizeErrorMessage(terminationError),
+        fatal: true,
+      });
+    });
+  }
+
+  private async teardownProxySecurity(): Promise<void> {
+    this.proxySecurityStopping = true;
+    if (this.browserSecurityConnection && this.browserSecuritySessionAttachedListener) {
+      this.browserSecurityConnection.off(
+        'sessionattached',
+        this.browserSecuritySessionAttachedListener,
+      );
+    }
+    if (this.browserSecurityConnection && this.browserSecuritySessionDetachedListener) {
+      this.browserSecurityConnection.off(
+        'sessiondetached',
+        this.browserSecuritySessionDetachedListener,
+      );
+    }
+    this.browserSecuritySessionAttachedListener = undefined;
+    this.browserSecuritySessionDetachedListener = undefined;
+    this.browserSecurityConnection = undefined;
+    const ownedSessions = [...this.proxySecuritySessions.values()]
+      .filter((record) => record.ownedByProxySecurity)
+      .map((record) => record.session);
+    for (const proxySecuritySession of [...this.proxySecuritySessions.values()]) {
+      this.removeProxySecuritySession(proxySecuritySession);
+    }
+    for (const ownedSession of ownedSessions) {
+      if (!ownedSession.detached) {
+        try {
+          await ownedSession.detach();
+        } catch {
+          // Browser shutdown can close a target before explicit detach settles.
+        }
+      }
+    }
+    const browserSecurityCdpSession = this.browserSecurityCdpSession;
+    this.browserSecurityCdpSession = undefined;
+    if (browserSecurityCdpSession && !browserSecurityCdpSession.detached) {
+      try {
+        await browserSecurityCdpSession.detach();
+      } catch {
+        // Browser shutdown can detach the browser target first.
+      }
+    }
+    while (this.proxySecurityOperations.size > 0) {
+      await Promise.allSettled([...this.proxySecurityOperations]);
+    }
+    this.proxySecurityGeneration = 0;
+  }
+
   private requireBrowserContext(): plugins.puppeteer.BrowserContext {
     if (this.status !== 'running' || !this.browserContext) {
       throw new Error('LiveBrowserSession is not running');
@@ -1404,6 +2713,68 @@ export class LiveBrowserSession {
     }
   }
 
+  private scheduleDiscoveredPageRegistration(page: plugins.puppeteer.Page): void {
+    if (
+      page.isClosed()
+      || this.tabIdsByPage.has(page)
+      || this.normalStopRequested
+      || this.status === 'stopped'
+      || this.status === 'stopping'
+    ) {
+      return;
+    }
+    const wasScheduled = this.scheduleOperation(async () => {
+      if (page.isClosed() || this.tabIdsByPage.has(page)) {
+        return;
+      }
+      const previousActiveTabId = this.activeTabId;
+      let discoveredTab: IPrivateLiveBrowserTab | undefined;
+      try {
+        discoveredTab = await this.registerPage(page);
+        await this.activateTabInternal(discoveredTab.id);
+      } catch (error) {
+        const rollbackError = await this.rollbackCreatedPage(
+          page,
+          discoveredTab,
+          previousActiveTabId,
+        );
+        if (rollbackError) {
+          const aggregateError = new AggregateError(
+            [error, rollbackError],
+            'Discovered page registration rollback failed',
+          );
+          this.handleDiscoveredPageFailure(aggregateError);
+          throw aggregateError;
+        }
+        throw error;
+      }
+    }, 'discovered_page_registration_failed', undefined, true);
+    if (!wasScheduled) {
+      this.handleDiscoveredPageFailure(
+        new Error('A discovered page could not be admitted to the internal operation queue'),
+      );
+    }
+  }
+
+  private handleDiscoveredPageFailure(error: unknown): void {
+    if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
+      return;
+    }
+    const liveBrowserError: ILiveBrowserError = {
+      code: 'untracked_page_detected',
+      message: normalizeErrorMessage(error),
+      fatal: true,
+    };
+    this.emitError(liveBrowserError);
+    void this.requestShutdown(liveBrowserError).catch((shutdownError) => {
+      this.emitError({
+        code: 'untracked_page_shutdown_failed',
+        message: normalizeErrorMessage(shutdownError),
+        fatal: true,
+      });
+    });
+  }
+
   private async registerPage(page: plugins.puppeteer.Page): Promise<IPrivateLiveBrowserTab> {
     const existingTabId = this.tabIdsByPage.get(page);
     if (existingTabId) {
@@ -1433,6 +2804,18 @@ export class LiveBrowserSession {
     this.tabs.set(tab.id, tab);
     this.tabIdsByPage.set(page, tab.id);
     try {
+      if (this.options.security?.denyFileChoosers) {
+        const securityCdpSession = await page.createCDPSession();
+        this.allowOperationalCdpSessionDetach(securityCdpSession);
+        tab.securityCdpSession = securityCdpSession;
+        await securityCdpSession.send('Page.enable', {
+          enableFileChooserOpenedEvent: true,
+        });
+        await securityCdpSession.send('Page.setInterceptFileChooserDialog', {
+          enabled: true,
+          cancel: true,
+        });
+      }
       await this.ensureTabViewport(tab);
       await this.refreshTab(tab);
 
@@ -1488,6 +2871,7 @@ export class LiveBrowserSession {
         if (frame !== page.mainFrame() || tab.closing) {
           return;
         }
+        tab.evaluationExecutionContextId = undefined;
         const navigationReset = !tab.navigationInProgress;
         if (navigationReset) {
           tab.streamInvalidated = true;
@@ -1563,6 +2947,13 @@ export class LiveBrowserSession {
       );
       return tab;
     } catch (error) {
+      if (tab.securityCdpSession && !tab.securityCdpSession.detached) {
+        try {
+          await tab.securityCdpSession.detach();
+        } catch {
+          // The page may have closed while security setup was failing.
+        }
+      }
       this.removePageListeners(tab);
       this.tabs.delete(tab.id);
       this.tabIdsByPage.delete(page);
@@ -1813,6 +3204,7 @@ export class LiveBrowserSession {
     signal: AbortSignal,
   ): Promise<void> {
     const isActive = this.activeTabId === tab.id;
+    tab.evaluationExecutionContextId = undefined;
     tab.navigationInProgress = true;
     if (isActive) {
       await this.stopScreencast(tab);
@@ -1832,7 +3224,6 @@ export class LiveBrowserSession {
           && this.activeTabId === tab.id
           && this.status === 'running'
           && tab.status === 'open'
-          && !signal.aborted
         ) {
           await this.startScreencast(tab);
         }
@@ -1879,6 +3270,7 @@ export class LiveBrowserSession {
     await this.ensureTabViewport(tab);
 
     const cdpSession = await tab.page.createCDPSession();
+    this.allowOperationalCdpSessionDetach(cdpSession);
     const generation = tab.generation + 1;
     const frameListener: TScreencastFrameListener = (event) => {
       this.handleScreencastFrame(tab, cdpSession, generation, event);
@@ -2242,14 +3634,300 @@ export class LiveBrowserSession {
 
   private validateUrl(url: unknown): string {
     const validatedUrl = validateBoundedString(url, 'url', 1, maxUrlLength);
+    let parsedUrl: URL;
     try {
-      new URL(validatedUrl);
+      parsedUrl = new URL(validatedUrl);
     } catch {
       throw new Error('url must be absolute');
     }
+    if (
+      this.options.security?.httpNavigationOnly
+      && parsedUrl.protocol !== 'http:'
+      && parsedUrl.protocol !== 'https:'
+    ) {
+      throw new Error('url protocol must be http or https');
+    }
     return validatedUrl;
   }
 
+  private normalizeEvaluationOptions(
+    options: ILiveBrowserEvaluateOptions,
+  ): INormalizedEvaluationOptions {
+    return {
+      timeoutMs: options.timeoutMs === undefined
+        ? 5000
+        : validateInteger(options.timeoutMs, 'timeoutMs', 1, 30000),
+      maxOutputBytes: options.maxOutputBytes === undefined
+        ? 262144
+        : validateInteger(
+            options.maxOutputBytes,
+            'maxOutputBytes',
+            1,
+            maxEvaluationOutputBytes,
+          ),
+      maxDepth: options.maxDepth === undefined
+        ? 16
+        : validateInteger(options.maxDepth, 'maxDepth', 1, maxEvaluationDepth),
+      maxNodes: options.maxNodes === undefined
+        ? 10000
+        : validateInteger(options.maxNodes, 'maxNodes', 1, maxEvaluationNodes),
+      maxStringBytes: options.maxStringBytes === undefined
+        ? 65536
+        : validateInteger(
+            options.maxStringBytes,
+            'maxStringBytes',
+            0,
+            maxEvaluationStringBytes,
+          ),
+      maxArrayLength: options.maxArrayLength === undefined
+        ? 1000
+        : validateInteger(
+            options.maxArrayLength,
+            'maxArrayLength',
+            0,
+            maxEvaluationArrayLength,
+          ),
+      maxObjectKeys: options.maxObjectKeys === undefined
+        ? 1000
+        : validateInteger(
+            options.maxObjectKeys,
+            'maxObjectKeys',
+            0,
+            maxEvaluationObjectKeys,
+          ),
+    };
+  }
+
+  private readCdpExceptionMessage(
+    exceptionDetails: plugins.puppeteer.Protocol.Runtime.ExceptionDetails,
+  ): string {
+    const description = exceptionDetails.exception?.description;
+    if (typeof description === 'string' && description.length > 0) {
+      return truncate(description, 2048);
+    }
+    return truncate(exceptionDetails.text, 2048);
+  }
+
+  private createEvaluationBootstrapExpression(): string {
+    const bootstrapKeyLiteral = JSON.stringify(evaluationBootstrapKey);
+    const cancelKeyLiteral = JSON.stringify(evaluationCancelKey);
+    const cleanupKeyLiteral = JSON.stringify(evaluationCleanupKey);
+    return `(() => {
+      'use strict';
+      if (typeof globalThis[${bootstrapKeyLiteral}] === 'function') {
+        return true;
+      }
+      const safeGlobalThis = globalThis;
+      const SafeArray = Array;
+      const SafeError = Error;
+      const SafeFunction = Function;
+      const SafeJSON = JSON;
+      const SafeMap = Map;
+      const SafeNumber = Number;
+      const SafeObject = Object;
+      const SafePromise = Promise;
+      const SafeString = String;
+      const SafeTextEncoder = TextEncoder;
+      const SafeWeakSet = WeakSet;
+      const SafeClearTimeout = clearTimeout;
+      const SafeSetTimeout = setTimeout;
+      const safeCreate = SafeObject.create;
+      const safeDefineProperty = SafeObject.defineProperty;
+      const safeGetOwnPropertyDescriptor = SafeObject.getOwnPropertyDescriptor;
+      const safeGetOwnPropertySymbols = SafeObject.getOwnPropertySymbols;
+      const safeGetPrototypeOf = SafeObject.getPrototypeOf;
+      const safeIsArray = SafeArray.isArray;
+      const safeIsFinite = SafeNumber.isFinite;
+      const safeKeys = SafeObject.keys;
+      const safeSetPrototypeOf = SafeObject.setPrototypeOf;
+      const safeStringify = SafeJSON.stringify;
+      const safeMapDelete = SafeFunction.prototype.call.bind(SafeMap.prototype.delete);
+      const safeMapGet = SafeFunction.prototype.call.bind(SafeMap.prototype.get);
+      const safeMapSet = SafeFunction.prototype.call.bind(SafeMap.prototype.set);
+      const safePromiseThen = SafeFunction.prototype.call.bind(SafePromise.prototype.then);
+      const safeWeakSetAdd = SafeFunction.prototype.call.bind(SafeWeakSet.prototype.add);
+      const safeWeakSetHas = SafeFunction.prototype.call.bind(SafeWeakSet.prototype.has);
+      const safeEncode = SafeFunction.prototype.call.bind(SafeTextEncoder.prototype.encode);
+      const encoder = new SafeTextEncoder();
+      const cancellationHandlers = new SafeMap();
+
+      const createEnvelope = (ok, value) => {
+        const envelope = safeCreate(null);
+        envelope.ok = ok;
+        if (ok) {
+          envelope.json = value;
+        } else {
+          envelope.error = value;
+        }
+        return envelope;
+      };
+      const byteLength = (value) => safeEncode(encoder, value).byteLength;
+      const cancelEvaluation = (cancellationKey) => {
+        const handler = safeMapGet(cancellationHandlers, cancellationKey);
+        if (typeof handler === 'function') {
+          handler();
+        }
+        return safeMapDelete(cancellationHandlers, cancellationKey);
+      };
+      const evaluate = async (source, options, cancellationKey) => {
+        const seen = new SafeWeakSet();
+        let visitedNodes = 0;
+        const normalize = (value, depth) => {
+          visitedNodes += 1;
+          if (visitedNodes > options.maxNodes) {
+            throw new SafeError('Evaluation result exceeded maxNodes');
+          }
+          if (depth > options.maxDepth) {
+            throw new SafeError('Evaluation result exceeded maxDepth');
+          }
+          if (value === null || typeof value === 'boolean') {
+            return value;
+          }
+          if (typeof value === 'number') {
+            if (!safeIsFinite(value)) {
+              throw new SafeError('Evaluation result contains a non-finite number');
+            }
+            return value;
+          }
+          if (typeof value === 'string') {
+            if (byteLength(value) > options.maxStringBytes) {
+              throw new SafeError('Evaluation result string exceeded maxStringBytes');
+            }
+            return value;
+          }
+          if (typeof value !== 'object') {
+            throw new SafeError('Evaluation result contains a non-JSON value');
+          }
+          if (safeWeakSetHas(seen, value)) {
+            throw new SafeError('Evaluation result contains a cycle or repeated object');
+          }
+          safeWeakSetAdd(seen, value);
+
+          if (safeIsArray(value)) {
+            if (value.length > options.maxArrayLength) {
+              throw new SafeError('Evaluation result array exceeded maxArrayLength');
+            }
+            const keys = safeKeys(value);
+            if (keys.length !== value.length) {
+              throw new SafeError('Evaluation result contains a sparse or extended array');
+            }
+            const output = SafeArray(value.length);
+            safeSetPrototypeOf(output, null);
+            for (let index = 0; index < value.length; index += 1) {
+              const descriptor = safeGetOwnPropertyDescriptor(value, SafeString(index));
+              if (!descriptor || !('value' in descriptor)) {
+                throw new SafeError('Evaluation result contains an array accessor');
+              }
+              output[index] = normalize(descriptor.value, depth + 1);
+            }
+            return output;
+          }
+
+          const prototype = safeGetPrototypeOf(value);
+          if (prototype !== SafeObject.prototype && prototype !== null) {
+            throw new SafeError('Evaluation result contains a non-plain object');
+          }
+          if (safeGetOwnPropertySymbols(value).length > 0) {
+            throw new SafeError('Evaluation result contains symbol properties');
+          }
+          const keys = safeKeys(value);
+          if (keys.length > options.maxObjectKeys) {
+            throw new SafeError('Evaluation result object exceeded maxObjectKeys');
+          }
+          const output = safeCreate(null);
+          for (let index = 0; index < keys.length; index += 1) {
+            const key = keys[index];
+            if (byteLength(key) > options.maxStringBytes) {
+              throw new SafeError('Evaluation result key exceeded maxStringBytes');
+            }
+            const descriptor = safeGetOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor)) {
+              throw new SafeError('Evaluation result contains an object accessor');
+            }
+            output[key] = normalize(descriptor.value, depth + 1);
+          }
+          return output;
+        };
+
+        try {
+          const execute = SafeFunction(
+            '\"use strict\"; return (async () => (' + source + '\\n))();',
+          );
+          const boundedExecution = new SafePromise((resolve, reject) => {
+            let timeout;
+            safeMapSet(cancellationHandlers, cancellationKey, () => {
+              if (timeout !== undefined) {
+                SafeClearTimeout(timeout);
+              }
+              reject(new SafeError('Evaluation cancelled'));
+            });
+            timeout = SafeSetTimeout(() => {
+              reject(new SafeError('Evaluation timed out after ' + options.timeoutMs + 'ms'));
+            }, options.timeoutMs);
+            safePromiseThen(
+              execute(),
+              (value) => {
+                SafeClearTimeout(timeout);
+                resolve(value);
+              },
+              (error) => {
+                SafeClearTimeout(timeout);
+                reject(error);
+              },
+            );
+          });
+          let normalizedResult;
+          try {
+            normalizedResult = normalize(await boundedExecution, 0);
+          } finally {
+            safeMapDelete(cancellationHandlers, cancellationKey);
+          }
+          const json = safeStringify(normalizedResult);
+          if (typeof json !== 'string' || byteLength(json) > options.maxOutputBytes) {
+            throw new SafeError('Evaluation result exceeded maxOutputBytes');
+          }
+          return createEnvelope(true, json);
+        } catch (error) {
+          let message = 'Evaluation failed';
+          if (typeof error === 'string') {
+            message = error;
+          } else if (error && typeof error === 'object') {
+            const descriptor = safeGetOwnPropertyDescriptor(error, 'message');
+            if (descriptor && 'value' in descriptor && typeof descriptor.value === 'string') {
+              message = descriptor.value;
+            }
+          }
+          if (byteLength(message) > 2048) {
+            message = 'Evaluation failed with an oversized error';
+          }
+          return createEnvelope(false, message);
+        }
+      };
+
+      for (const [key, value] of [
+        [${bootstrapKeyLiteral}, evaluate],
+        [${cancelKeyLiteral}, cancelEvaluation],
+        [${cleanupKeyLiteral}, cancelEvaluation],
+      ]) {
+        safeDefineProperty(safeGlobalThis, key, {
+          value,
+          configurable: false,
+          enumerable: false,
+          writable: false,
+        });
+      }
+      return true;
+    })()`;
+  }
+
+  private createEvaluationExpression(
+    expression: string,
+    options: INormalizedEvaluationOptions,
+    cancellationKey: string,
+  ): string {
+    return `globalThis[${JSON.stringify(evaluationBootstrapKey)}](${JSON.stringify(expression)}, ${JSON.stringify(options)}, ${JSON.stringify(cancellationKey)})`;
+  }
+
   private validateTimeout(timeoutMs?: number, defaultValue = 5000): number {
     if (timeoutMs === undefined) {
       return defaultValue;