@push.rocks/smartpuppeteer 2.1.0 → 2.2.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -3,6 +3,7 @@ import type {
   ILiveBrowserClickOptions,
   ILiveBrowserCreateTabOptions,
   ILiveBrowserError,
+  ILiveBrowserEvaluateOptions,
   ILiveBrowserFillOptions,
   ILiveBrowserFrame,
   ILiveBrowserFrameAcknowledgement,
@@ -15,6 +16,7 @@ import type {
   ILiveBrowserNavigationOptions,
   ILiveBrowserObservation,
   ILiveBrowserObserveOptions,
+  ILiveBrowserOperationOptions,
   ILiveBrowserPressOptions,
   ILiveBrowserSessionOptions,
   ILiveBrowserSnapshot,
@@ -26,6 +28,7 @@ import type {
   TLiveBrowserEvent,
   TLiveBrowserEventListener,
   TLiveBrowserImageFormat,
+  TLiveBrowserJsonValue,
   TLiveBrowserWaitUntil,
 } from './smartpuppeteer.interfaces.livebrowser.js';
 import * as plugins from './smartpuppeteer.plugins.js';
@@ -47,6 +50,16 @@ 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';
 
 type TScreencastFrameEvent = plugins.puppeteer.Protocol.Page.ScreencastFrameEvent;
 type TScreencastFrameListener = (event: TScreencastFrameEvent) => void;
@@ -67,6 +80,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 +102,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 +198,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
@@ -291,6 +330,7 @@ export class LiveBrowserSession {
   private viewportRevision = 1;
   private tabSequence = 0;
   private frameSequence = 0;
+  private evaluationSequence = 0;
   private normalStopRequested = false;
   private lastError?: ILiveBrowserError;
 
@@ -310,6 +350,10 @@ 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, value] of Object.entries(optionsArg.security ?? {})) {
+      validateOptionalBoolean(value, `security.${name}`);
+    }
     const launchViewport = optionsArg.launchOptions?.defaultViewport;
     const viewport = normalizeViewport(
       optionsArg.viewport
@@ -327,9 +371,13 @@ 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 } : undefined,
     };
     this.viewport = { ...viewport };
     this.validateScreencastOptions();
@@ -356,7 +404,7 @@ export class LiveBrowserSession {
     };
   }
 
-  public async start(): Promise<void> {
+  public async start(operationOptions: ILiveBrowserOperationOptions = {}): Promise<void> {
     return this.enqueuePublicOperation(async (signal) => {
       if (this.status === 'running' || this.status === 'starting') {
         return;
@@ -377,19 +425,31 @@ 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);
+        }
         if (signal.aborted) {
           throw signal.reason;
         }
         this.browserContext = this.browser.defaultBrowserContext();
+        await this.configureBrowserSecurity(this.browser);
         this.browserDisconnectedListener = () => {
           if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
             return;
@@ -432,6 +492,9 @@ 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();
@@ -446,7 +509,7 @@ export class LiveBrowserSession {
         await this.stopInternal(startError);
         throw error;
       }
-    });
+    }, operationOptions);
   }
 
   public async stop(): Promise<void> {
@@ -508,6 +571,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 +627,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 +679,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 +696,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 +712,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 +728,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 +744,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 +769,7 @@ export class LiveBrowserSession {
           await this.startScreencast(tab);
         }
       }
-    });
+    }, operationOptions);
   }
 
   public async dispatchMouse(input: ILiveBrowserMouseInput): Promise<void> {
@@ -815,6 +900,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 +944,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 +1037,202 @@ export class LiveBrowserSession {
         text: truncatedText,
         truncated: reachedTraversalLimit || unboundedText.length > maxCharacters,
       };
-    });
+    }, operationOptions);
   }
 
-  public async click(optionsArg: ILiveBrowserClickOptions): Promise<void> {
+  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();
+      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,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<void> {
     const selector = validateBoundedString(
       optionsArg.selector,
       'selector',
@@ -977,10 +1258,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 +1280,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 +1314,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 +1346,7 @@ 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', operation, false, callerSignal);
   }
 
   private enqueueInternalOperation(
@@ -1062,15 +1364,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 +1422,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 +1440,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 +1463,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);
     }
   }
 
@@ -1297,6 +1644,15 @@ export class LiveBrowserSession {
     const shutdownErrors: unknown[] = [];
     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) {
@@ -1338,6 +1694,22 @@ export class LiveBrowserSession {
     }
   }
 
+  private async configureBrowserSecurity(
+    browser: plugins.puppeteer.Browser,
+  ): Promise<void> {
+    if (!this.options.security?.denyPermissions) {
+      return;
+    }
+    const cdpSession = await browser.target().createCDPSession();
+    try {
+      await cdpSession.send('Browser.grantPermissions', { permissions: [] });
+    } finally {
+      if (!cdpSession.detached) {
+        await cdpSession.detach();
+      }
+    }
+  }
+
   private requireBrowserContext(): plugins.puppeteer.BrowserContext {
     if (this.status !== 'running' || !this.browserContext) {
       throw new Error('LiveBrowserSession is not running');
@@ -1433,6 +1805,17 @@ 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();
+        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 +1871,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 +1947,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 +2204,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 +2224,6 @@ export class LiveBrowserSession {
           && this.activeTabId === tab.id
           && this.status === 'running'
           && tab.status === 'open'
-          && !signal.aborted
         ) {
           await this.startScreencast(tab);
         }
@@ -2242,14 +2633,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;