@push.rocks/smartpuppeteer 2.0.7 → 2.1.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -0,0 +1,2298 @@
+import { getEnvAwareBrowserInstance } from './smartpuppeteer.classes.smartpuppeteer.js';
+import type {
+  ILiveBrowserClickOptions,
+  ILiveBrowserCreateTabOptions,
+  ILiveBrowserError,
+  ILiveBrowserFillOptions,
+  ILiveBrowserFrame,
+  ILiveBrowserFrameAcknowledgement,
+  ILiveBrowserFrameAcknowledgementRequest,
+  ILiveBrowserInsertTextInput,
+  ILiveBrowserKeyInput,
+  ILiveBrowserModifierState,
+  ILiveBrowserMouseInput,
+  ILiveBrowserNavigateOptions,
+  ILiveBrowserNavigationOptions,
+  ILiveBrowserObservation,
+  ILiveBrowserObserveOptions,
+  ILiveBrowserPressOptions,
+  ILiveBrowserSessionOptions,
+  ILiveBrowserSnapshot,
+  ILiveBrowserSnapshotOptions,
+  ILiveBrowserState,
+  ILiveBrowserTabState,
+  ILiveBrowserViewport,
+  ILiveBrowserWheelInput,
+  TLiveBrowserEvent,
+  TLiveBrowserEventListener,
+  TLiveBrowserImageFormat,
+  TLiveBrowserWaitUntil,
+} from './smartpuppeteer.interfaces.livebrowser.js';
+import * as plugins from './smartpuppeteer.plugins.js';
+
+const defaultViewport: ILiveBrowserViewport = {
+  width: 800,
+  height: 600,
+  deviceScaleFactor: 1,
+};
+
+const maxViewportWidth = 4096;
+const maxViewportHeight = 4096;
+const maxDeviceScaleFactor = 3;
+const maxViewportPixelArea = 8294400;
+const maxSelectorLength = 4096;
+const maxTextLength = 32768;
+const maxUrlLength = 16384;
+const maxTimeoutMs = 60000;
+const maxOutstandingFrames = 3;
+const maxQueuedPublicOperations = 64;
+const maxQueuedInternalOperations = 128;
+
+type TScreencastFrameEvent = plugins.puppeteer.Protocol.Page.ScreencastFrameEvent;
+type TScreencastFrameListener = (event: TScreencastFrameEvent) => void;
+type TCdpSessionDetachedListener = (session: plugins.puppeteer.CDPSession) => void;
+
+interface IPrivateLiveBrowserTab {
+  id: string;
+  page: plugins.puppeteer.Page;
+  url: string;
+  title: string;
+  status: 'open' | 'crashed';
+  generation: number;
+  appliedViewportRevision: number;
+  streaming: boolean;
+  streamInvalidated: boolean;
+  navigationInProgress: boolean;
+  closing: boolean;
+  stateUpdateQueued: boolean;
+  stateUpdatePending: boolean;
+  navigationResetPending: boolean;
+  cdpSession?: plugins.puppeteer.CDPSession;
+  cdpConnection?: plugins.puppeteer.Connection;
+  screencastFrameListener?: TScreencastFrameListener;
+  cdpSessionDetachedListener?: TCdpSessionDetachedListener;
+  removeListeners: Array<() => void>;
+}
+
+interface IOutstandingFrame {
+  tabId: string;
+  generation: number;
+  viewportRevision: number;
+  cdpSessionId: number;
+  cdpSession: plugins.puppeteer.CDPSession;
+}
+
+interface IImageDimensions {
+  width: number;
+  height: number;
+}
+
+type TQueuedOperationKind = 'public' | 'internal' | 'shutdown';
+
+interface IQueuedOperation {
+  kind: TQueuedOperationKind;
+  controller: AbortController;
+  run: (signal: AbortSignal) => Promise<unknown>;
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+}
+
+const validateBoundedString = (
+  value: unknown,
+  name: string,
+  minLength: number,
+  maxLength: number,
+): string => {
+  if (
+    typeof value !== 'string'
+    || value.length < minLength
+    || value.length > maxLength
+  ) {
+    throw new Error(`${name} must contain between ${minLength} and ${maxLength} characters`);
+  }
+  return value;
+};
+
+const validateFiniteNumber = (
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum: number,
+): number => {
+  if (
+    typeof value !== 'number'
+    || !Number.isFinite(value)
+    || value < minimum
+    || value > maximum
+  ) {
+    throw new Error(`${name} must be a finite number between ${minimum} and ${maximum}`);
+  }
+  return value;
+};
+
+const validateInteger = (
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum: number,
+): number => {
+  const validatedValue = validateFiniteNumber(value, name, minimum, maximum);
+  if (!Number.isInteger(validatedValue)) {
+    throw new Error(`${name} must be an integer`);
+  }
+  return validatedValue;
+};
+
+const validateOptionalBoolean = (value: unknown, name: string): void => {
+  if (value !== undefined && typeof value !== 'boolean') {
+    throw new Error(`${name} must be a boolean`);
+  }
+};
+
+const truncate = (value: string, maxLength: number): string => {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+};
+
+const normalizeErrorMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return truncate(error.message, 2048);
+  }
+  return truncate(String(error), 2048);
+};
+
+const readUint32 = (data: Uint8Array, offset: number): number => {
+  return (
+    data[offset]! * 0x1000000
+    + data[offset + 1]! * 0x10000
+    + data[offset + 2]! * 0x100
+    + data[offset + 3]!
+  );
+};
+
+const readImageDimensions = (
+  data: Uint8Array,
+  format: TLiveBrowserImageFormat,
+  fallback: IImageDimensions,
+): IImageDimensions => {
+  if (
+    format === 'png'
+    && data.length >= 24
+    && data[0] === 0x89
+    && data[1] === 0x50
+    && data[2] === 0x4e
+    && data[3] === 0x47
+  ) {
+    return {
+      width: readUint32(data, 16),
+      height: readUint32(data, 20),
+    };
+  }
+
+  if (format === 'jpeg' && data.length >= 4 && data[0] === 0xff && data[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 8 < data.length) {
+      if (data[offset] !== 0xff) {
+        offset += 1;
+        continue;
+      }
+      const marker = data[offset + 1]!;
+      if (marker === 0xd8 || marker === 0xd9) {
+        offset += 2;
+        continue;
+      }
+      const segmentLength = (data[offset + 2]! << 8) + data[offset + 3]!;
+      if (segmentLength < 2 || offset + segmentLength + 2 > data.length) {
+        break;
+      }
+      if (
+        marker === 0xc0
+        || marker === 0xc1
+        || marker === 0xc2
+        || marker === 0xc3
+        || marker === 0xc5
+        || marker === 0xc6
+        || marker === 0xc7
+        || marker === 0xc9
+        || marker === 0xca
+        || marker === 0xcb
+        || marker === 0xcd
+        || marker === 0xce
+        || marker === 0xcf
+      ) {
+        return {
+          height: (data[offset + 5]! << 8) + data[offset + 6]!,
+          width: (data[offset + 7]! << 8) + data[offset + 8]!,
+        };
+      }
+      offset += segmentLength + 2;
+    }
+  }
+
+  return fallback;
+};
+
+const normalizeViewport = (viewport: ILiveBrowserViewport): ILiveBrowserViewport => {
+  const normalizedViewport = {
+    width: validateInteger(viewport.width, 'viewport.width', 1, maxViewportWidth),
+    height: validateInteger(viewport.height, 'viewport.height', 1, maxViewportHeight),
+    deviceScaleFactor: validateFiniteNumber(
+      viewport.deviceScaleFactor,
+      'viewport.deviceScaleFactor',
+      0.25,
+      maxDeviceScaleFactor,
+    ),
+  };
+  const physicalWidth = Math.ceil(
+    normalizedViewport.width * normalizedViewport.deviceScaleFactor,
+  );
+  const physicalHeight = Math.ceil(
+    normalizedViewport.height * normalizedViewport.deviceScaleFactor,
+  );
+  if (physicalWidth * physicalHeight > maxViewportPixelArea) {
+    throw new Error(
+      `viewport pixel area must not exceed ${maxViewportPixelArea} physical pixels`,
+    );
+  }
+  return normalizedViewport;
+};
+
+const createPuppeteerViewport = (
+  viewport: ILiveBrowserViewport,
+): plugins.puppeteer.Viewport => ({
+  ...viewport,
+  isMobile: false,
+  isLandscape: false,
+  hasTouch: false,
+});
+
+export class LiveBrowserSession {
+  private readonly options: ILiveBrowserSessionOptions;
+  private readonly eventListeners = new Set<TLiveBrowserEventListener>();
+  private readonly tabs = new Map<string, IPrivateLiveBrowserTab>();
+  private readonly tabIdsByPage = new WeakMap<plugins.puppeteer.Page, string>();
+  private readonly outstandingFrames = new Map<number, IOutstandingFrame>();
+
+  private browser?: plugins.puppeteer.Browser;
+  private browserContext?: plugins.puppeteer.BrowserContext;
+  private browserLifetimeController?: AbortController;
+  private browserDisconnectedListener?: () => void;
+  private readonly operationQueue: IQueuedOperation[] = [];
+  private activeOperation?: IQueuedOperation;
+  private operationRunning = false;
+  private admittedPublicOperations = 0;
+  private admittedInternalOperations = 0;
+  private shutdownPromise?: Promise<void>;
+  private status: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
+  private activeTabId: string | null = null;
+  private viewport: ILiveBrowserViewport = { ...defaultViewport };
+  private viewportRevision = 1;
+  private tabSequence = 0;
+  private frameSequence = 0;
+  private normalStopRequested = false;
+  private lastError?: ILiveBrowserError;
+
+  constructor(optionsArg: ILiveBrowserSessionOptions = {}) {
+    if (
+      optionsArg.launchOptions?.protocol
+      && optionsArg.launchOptions.protocol !== 'cdp'
+    ) {
+      throw new Error('LiveBrowserSession only supports Puppeteer CDP transport');
+    }
+    if (
+      optionsArg.launchOptions?.browser
+      && optionsArg.launchOptions.browser !== 'chrome'
+    ) {
+      throw new Error('LiveBrowserSession requires Chromium');
+    }
+    if (optionsArg.launchOptions && 'signal' in optionsArg.launchOptions) {
+      throw new Error('LiveBrowserSession owns launch cancellation; launchOptions.signal is unsupported');
+    }
+    const launchViewport = optionsArg.launchOptions?.defaultViewport;
+    const viewport = normalizeViewport(
+      optionsArg.viewport
+      ?? (launchViewport
+        ? {
+            width: launchViewport.width,
+            height: launchViewport.height,
+            deviceScaleFactor: launchViewport.deviceScaleFactor ?? 1,
+          }
+        : defaultViewport),
+    );
+    this.options = {
+      ...optionsArg,
+      launchOptions: {
+        ...optionsArg.launchOptions,
+        args: [...(optionsArg.launchOptions?.args ?? [])],
+        defaultViewport: createPuppeteerViewport(viewport),
+      },
+      viewport,
+      screencast: optionsArg.screencast ? { ...optionsArg.screencast } : undefined,
+    };
+    this.viewport = { ...viewport };
+    this.validateScreencastOptions();
+  }
+
+  public onEvent(listener: TLiveBrowserEventListener): () => void {
+    if (typeof listener !== 'function') {
+      throw new Error('listener must be a function');
+    }
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+
+  public getState(): ILiveBrowserState {
+    return {
+      status: this.status,
+      activeTabId: this.activeTabId,
+      viewportRevision: this.viewportRevision,
+      viewport: { ...this.viewport },
+      tabs: [...this.tabs.values()].map((tab) => this.createTabState(tab)),
+      ...(this.lastError ? { lastError: { ...this.lastError } } : {}),
+    };
+  }
+
+  public async start(): Promise<void> {
+    return this.enqueuePublicOperation(async (signal) => {
+      if (this.status === 'running' || this.status === 'starting') {
+        return;
+      }
+
+      this.normalStopRequested = false;
+      this.lastError = undefined;
+      this.viewportRevision = 1;
+      const browserLifetimeController = new AbortController();
+      this.browserLifetimeController = browserLifetimeController;
+      this.status = 'starting';
+      this.emitState();
+
+      try {
+        if (signal.aborted) {
+          throw signal.reason;
+        }
+        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,
+          },
+        });
+        if (signal.aborted) {
+          throw signal.reason;
+        }
+        this.browserContext = this.browser.defaultBrowserContext();
+        this.browserDisconnectedListener = () => {
+          if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
+            return;
+          }
+          const error: ILiveBrowserError = {
+            code: 'browser_disconnected',
+            message: 'The Chromium process disconnected',
+            fatal: true,
+          };
+          this.emitError(error);
+          void this.requestShutdown(error).catch((cleanupError) => {
+            this.emitError({
+              code: 'browser_disconnect_cleanup_failed',
+              message: normalizeErrorMessage(cleanupError),
+              fatal: true,
+            });
+          });
+        };
+        this.browser.on('disconnected', this.browserDisconnectedListener);
+
+        const initialPages = await this.browserContext.pages();
+        if (initialPages.length === 0) {
+          initialPages.push(await this.browserContext.newPage());
+        }
+        const initialPage = initialPages[0]!;
+        if (initialPage.url() !== 'about:blank') {
+          await initialPage.goto('about:blank');
+        }
+
+        for (const page of initialPages) {
+          await this.registerPage(page);
+        }
+
+        const firstTab = this.tabs.values().next().value as IPrivateLiveBrowserTab | undefined;
+        if (!firstTab) {
+          throw new Error('Chromium did not provide an initial page');
+        }
+        this.activeTabId = firstTab.id;
+        await firstTab.page.bringToFront();
+        this.status = 'running';
+        this.emitState();
+        await this.startScreencast(firstTab);
+      } catch (error) {
+        if (signal.aborted || this.normalStopRequested) {
+          await this.stopInternal();
+          throw error;
+        }
+        const startError: ILiveBrowserError = {
+          code: 'start_failed',
+          message: normalizeErrorMessage(error),
+          fatal: true,
+        };
+        this.emitError(startError);
+        await this.stopInternal(startError);
+        throw error;
+      }
+    });
+  }
+
+  public async stop(): Promise<void> {
+    this.normalStopRequested = true;
+    return this.requestShutdown();
+  }
+
+  public async acknowledgeFrame(
+    acknowledgement: ILiveBrowserFrameAcknowledgementRequest,
+  ): Promise<ILiveBrowserFrameAcknowledgement> {
+    if (!acknowledgement || typeof acknowledgement !== 'object') {
+      return { accepted: false };
+    }
+    const { tabId, sequence, generation, viewportRevision } = acknowledgement;
+    if (
+      typeof tabId !== 'string'
+      || tabId.length < 1
+      || tabId.length > 128
+      || !Number.isInteger(sequence)
+      || sequence < 1
+      || !Number.isInteger(generation)
+      || generation < 0
+      || !Number.isInteger(viewportRevision)
+      || viewportRevision < 1
+    ) {
+      return { accepted: false };
+    }
+    const outstandingFrame = this.outstandingFrames.get(sequence);
+    if (!outstandingFrame) {
+      return { accepted: false };
+    }
+    if (
+      outstandingFrame.tabId !== tabId
+      || outstandingFrame.generation !== generation
+      || outstandingFrame.viewportRevision !== viewportRevision
+    ) {
+      return { accepted: false };
+    }
+
+    const tab = this.tabs.get(outstandingFrame.tabId);
+    if (
+      !tab
+      || this.activeTabId !== tab.id
+      || tab.generation !== outstandingFrame.generation
+      || this.viewportRevision !== outstandingFrame.viewportRevision
+      || tab.cdpSession !== outstandingFrame.cdpSession
+      || outstandingFrame.cdpSession.detached
+    ) {
+      this.outstandingFrames.delete(sequence);
+      await this.acknowledgeCdpFrame(outstandingFrame);
+      return { accepted: false };
+    }
+
+    this.outstandingFrames.delete(sequence);
+    return {
+      accepted: await this.acknowledgeCdpFrame(outstandingFrame),
+    };
+  }
+
+  public async createTab(
+    optionsArg: ILiveBrowserCreateTabOptions = {},
+  ): Promise<ILiveBrowserTabState> {
+    const url = optionsArg.url === undefined ? undefined : this.validateUrl(optionsArg.url);
+    const activate = optionsArg.activate ?? true;
+    validateOptionalBoolean(optionsArg.activate, 'activate');
+    const timeout = this.validateTimeout(optionsArg.timeoutMs, 30000);
+    const waitUntil = this.validateWaitUntil(optionsArg.waitUntil);
+    return this.enqueuePublicOperation(async (signal) => {
+      const context = this.requireBrowserContext();
+      const previousActiveTabId = this.activeTabId;
+      let page: plugins.puppeteer.Page | undefined;
+      let tab: IPrivateLiveBrowserTab | undefined;
+      try {
+        page = await context.newPage();
+        if (signal.aborted) {
+          throw signal.reason;
+        }
+        tab = await this.registerPage(page);
+        if (url !== undefined) {
+          await this.navigateTab(
+            tab,
+            async () => {
+              await tab!.page.goto(url, { timeout, waitUntil, signal });
+            },
+            signal,
+          );
+        }
+
+        if (activate) {
+          await this.activateTabInternal(tab.id);
+        } else {
+          const previousActiveTab = previousActiveTabId
+            ? this.tabs.get(previousActiveTabId)
+            : undefined;
+          if (previousActiveTab && !previousActiveTab.page.isClosed()) {
+            await previousActiveTab.page.bringToFront();
+          }
+          this.emitState();
+        }
+        return this.createTabState(tab);
+      } catch (error) {
+        if (page) {
+          const rollbackError = await this.rollbackCreatedPage(
+            page,
+            tab,
+            previousActiveTabId,
+          );
+          if (rollbackError) {
+            throw new AggregateError(
+              [error, rollbackError],
+              'Tab creation failed and its page could not be closed cleanly',
+            );
+          }
+        }
+        throw error;
+      }
+    });
+  }
+
+  public async activateTab(tabId: string): Promise<void> {
+    return this.enqueuePublicOperation(async () => {
+      await this.activateTabInternal(tabId);
+    });
+  }
+
+  public async closeTab(tabId: string): Promise<void> {
+    return this.enqueuePublicOperation(async () => {
+      const tab = this.requireTab(tabId);
+      const wasActive = this.activeTabId === tab.id;
+      if (wasActive) {
+        await this.stopScreencast(tab);
+      } else {
+        await this.retireOutstandingFrames((frame) => frame.tabId === tab.id);
+      }
+      try {
+        if (!tab.page.isClosed()) {
+          await tab.page.close();
+        }
+      } catch (error) {
+        if (
+          wasActive
+          && this.status === 'running'
+          && this.activeTabId === tab.id
+          && tab.status === 'open'
+        ) {
+          await this.startScreencast(tab);
+        }
+        this.emitState();
+        throw error;
+      }
+
+      tab.closing = true;
+      this.removePageListeners(tab);
+      this.tabs.delete(tab.id);
+      this.tabIdsByPage.delete(tab.page);
+
+      if (wasActive) {
+        this.activeTabId = null;
+        await this.activateReplacementTab();
+      } else {
+        this.emitState();
+      }
+    });
+  }
+
+  public async navigate(optionsArg: ILiveBrowserNavigateOptions): Promise<void> {
+    const url = this.validateUrl(optionsArg.url);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveNavigationTab(optionsArg.tabId);
+      await this.navigateTab(
+        tab,
+        async () => {
+          await tab.page.goto(url, this.createPuppeteerNavigationOptions(optionsArg, signal));
+        },
+        signal,
+      );
+    });
+  }
+
+  public async back(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveNavigationTab(optionsArg.tabId);
+      await this.navigateTab(
+        tab,
+        async () => {
+          await tab.page.goBack(this.createPuppeteerNavigationOptions(optionsArg, signal));
+        },
+        signal,
+      );
+    });
+  }
+
+  public async forward(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveNavigationTab(optionsArg.tabId);
+      await this.navigateTab(
+        tab,
+        async () => {
+          await tab.page.goForward(this.createPuppeteerNavigationOptions(optionsArg, signal));
+        },
+        signal,
+      );
+    });
+  }
+
+  public async reload(optionsArg: ILiveBrowserNavigationOptions = {}): Promise<void> {
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveNavigationTab(optionsArg.tabId);
+      await this.navigateTab(
+        tab,
+        async () => {
+          await tab.page.reload(this.createPuppeteerNavigationOptions(optionsArg, signal));
+        },
+        signal,
+      );
+    });
+  }
+
+  public async setViewport(viewportArg: ILiveBrowserViewport): Promise<void> {
+    const viewport = normalizeViewport(viewportArg);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.requireActiveTab();
+      await this.stopScreencast(tab);
+      try {
+        if (signal.aborted) {
+          throw signal.reason;
+        }
+        await tab.page.setViewport(createPuppeteerViewport(viewport));
+        this.viewport = { ...viewport };
+        this.viewportRevision += 1;
+        tab.appliedViewportRevision = this.viewportRevision;
+        this.emitState();
+      } finally {
+        if (this.status === 'running' && this.activeTabId === tab.id && tab.status === 'open') {
+          await this.startScreencast(tab);
+        }
+      }
+    });
+  }
+
+  public async dispatchMouse(input: ILiveBrowserMouseInput): Promise<void> {
+    const { tab, cdpSession } = this.requireRawInputTarget(input);
+    this.validateCoordinates(input.x, input.y);
+    const type = input.type === 'move'
+      ? 'mouseMoved'
+      : input.type === 'down'
+        ? 'mousePressed'
+        : input.type === 'up'
+          ? 'mouseReleased'
+          : undefined;
+    if (!type) {
+      throw new Error('mouse input type must be move, down, or up');
+    }
+    const allowedButtons = ['none', 'left', 'middle', 'right', 'back', 'forward'];
+    const button = input.button ?? (type === 'mouseMoved' ? 'none' : 'left');
+    if (!allowedButtons.includes(button)) {
+      throw new Error('mouse button is invalid');
+    }
+    const buttons = input.buttons === undefined
+      ? undefined
+      : validateInteger(input.buttons, 'buttons', 0, 31);
+    const clickCount = input.clickCount === undefined
+      ? undefined
+      : validateInteger(input.clickCount, 'clickCount', 0, 3);
+
+    try {
+      await cdpSession.send('Input.dispatchMouseEvent', {
+        type,
+        x: input.x,
+        y: input.y,
+        button,
+        buttons,
+        clickCount,
+        modifiers: this.createModifierMask(input.modifiers),
+        pointerType: 'mouse',
+      });
+    } catch (error) {
+      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
+      throw error;
+    }
+  }
+
+  public async dispatchWheel(input: ILiveBrowserWheelInput): Promise<void> {
+    const { tab, cdpSession } = this.requireRawInputTarget(input);
+    this.validateCoordinates(input.x, input.y);
+    validateFiniteNumber(input.deltaX, 'deltaX', -1000000, 1000000);
+    validateFiniteNumber(input.deltaY, 'deltaY', -1000000, 1000000);
+    try {
+      await cdpSession.send('Input.dispatchMouseEvent', {
+        type: 'mouseWheel',
+        x: input.x,
+        y: input.y,
+        deltaX: input.deltaX,
+        deltaY: input.deltaY,
+        modifiers: this.createModifierMask(input.modifiers),
+        pointerType: 'mouse',
+      });
+    } catch (error) {
+      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
+      throw error;
+    }
+  }
+
+  public async dispatchKey(input: ILiveBrowserKeyInput): Promise<void> {
+    const { tab, cdpSession } = this.requireRawInputTarget(input);
+    const type = input.type === 'down'
+      ? 'keyDown'
+      : input.type === 'up'
+        ? 'keyUp'
+        : undefined;
+    if (!type) {
+      throw new Error('key input type must be down or up');
+    }
+    const key = validateBoundedString(input.key, 'key', 1, 64);
+    const code = input.code === undefined
+      ? undefined
+      : validateBoundedString(input.code, 'code', 1, 64);
+    const text = input.text === undefined
+      ? undefined
+      : validateBoundedString(input.text, 'text', 0, 1024);
+    const unmodifiedText = input.unmodifiedText === undefined
+      ? undefined
+      : validateBoundedString(input.unmodifiedText, 'unmodifiedText', 0, 1024);
+    const windowsVirtualKeyCode = input.windowsVirtualKeyCode === undefined
+      ? undefined
+      : validateInteger(input.windowsVirtualKeyCode, 'windowsVirtualKeyCode', 0, 65535);
+    const nativeVirtualKeyCode = input.nativeVirtualKeyCode === undefined
+      ? undefined
+      : validateInteger(input.nativeVirtualKeyCode, 'nativeVirtualKeyCode', 0, 65535);
+    const location = input.location === undefined
+      ? undefined
+      : validateInteger(input.location, 'location', 0, 3);
+    validateOptionalBoolean(input.autoRepeat, 'autoRepeat');
+    validateOptionalBoolean(input.isKeypad, 'isKeypad');
+
+    try {
+      await cdpSession.send('Input.dispatchKeyEvent', {
+        type,
+        key,
+        code,
+        text,
+        unmodifiedText,
+        windowsVirtualKeyCode,
+        nativeVirtualKeyCode,
+        autoRepeat: input.autoRepeat,
+        isKeypad: input.isKeypad,
+        location,
+        modifiers: this.createModifierMask(input.modifiers),
+      });
+    } catch (error) {
+      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
+      throw error;
+    }
+  }
+
+  public async insertText(input: ILiveBrowserInsertTextInput): Promise<void> {
+    const { tab, cdpSession } = this.requireRawInputTarget(input);
+    const text = validateBoundedString(input.text, 'text', 0, maxTextLength);
+    try {
+      await cdpSession.send('Input.insertText', { text });
+    } catch (error) {
+      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
+      throw error;
+    }
+  }
+
+  public async captureSnapshot(
+    optionsArg: ILiveBrowserSnapshotOptions = {},
+  ): Promise<ILiveBrowserSnapshot> {
+    const format = optionsArg.format ?? 'jpeg';
+    if (format !== 'jpeg' && format !== 'png') {
+      throw new Error('snapshot format must be jpeg or png');
+    }
+    const quality = optionsArg.quality === undefined
+      ? undefined
+      : validateInteger(optionsArg.quality, 'quality', 0, 100);
+    if (format === 'png' && quality !== undefined) {
+      throw new Error('quality is only supported for jpeg snapshots');
+    }
+    if ('fullPage' in optionsArg) {
+      throw new Error('fullPage snapshots are not supported by LiveBrowserSession');
+    }
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveActionTab(optionsArg.tabId);
+      await this.ensureTabViewport(tab);
+      const capturedTab = this.resolveActionTab(tab.id);
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      const viewport = { ...this.viewport };
+      const viewportRevision = this.viewportRevision;
+      const data = await capturedTab.page.screenshot({
+        type: format,
+        ...(format === 'jpeg' && quality !== undefined ? { quality } : {}),
+      });
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      const dimensions = readImageDimensions(data, format, {
+        width: Math.round(viewport.width * viewport.deviceScaleFactor),
+        height: Math.round(viewport.height * viewport.deviceScaleFactor),
+      });
+      return {
+        tabId: capturedTab.id,
+        viewportRevision,
+        viewport,
+        format,
+        mimeType: format === 'jpeg' ? 'image/jpeg' : 'image/png',
+        ...dimensions,
+        data,
+      };
+    });
+  }
+
+  public async observe(optionsArg: ILiveBrowserObserveOptions = {}): Promise<ILiveBrowserObservation> {
+    const maxCharacters = optionsArg.maxCharacters === undefined
+      ? 12000
+      : validateInteger(optionsArg.maxCharacters, 'maxCharacters', 256, 50000);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.resolveActionTab(optionsArg.tabId);
+      await this.ensureTabViewport(tab);
+      const observedTab = this.resolveActionTab(tab.id);
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      await this.refreshTab(observedTab);
+      const accessibilitySnapshot = await observedTab.page.accessibility.snapshot({
+        interestingOnly: true,
+      });
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      const header = [
+        `Tab: ${observedTab.id}`,
+        `Status: ${observedTab.status}`,
+        `Title: ${observedTab.title}`,
+        `URL: ${observedTab.url}`,
+        'Accessibility:',
+      ];
+      const lines = [...header];
+      let reachedTraversalLimit = false;
+
+      const appendNode = (
+        node: plugins.puppeteer.SerializedAXNode,
+        depth: number,
+      ): void => {
+        if (lines.join('\n').length >= maxCharacters) {
+          reachedTraversalLimit = true;
+          return;
+        }
+        const details: string[] = [node.role];
+        if (node.name) {
+          details.push(`"${truncate(node.name, 512)}"`);
+        }
+        if (node.value !== undefined) {
+          details.push(`value="${truncate(String(node.value), 512)}"`);
+        }
+        for (const property of [
+          'disabled',
+          'expanded',
+          'focused',
+          'readonly',
+          'required',
+          'selected',
+          'checked',
+          'pressed',
+        ] as const) {
+          const value = node[property];
+          if (value !== undefined && value !== false) {
+            details.push(`${property}=${String(value)}`);
+          }
+        }
+        lines.push(`${'  '.repeat(Math.min(depth, 20))}- ${details.join(' ')}`);
+        for (const child of node.children ?? []) {
+          appendNode(child, depth + 1);
+          if (reachedTraversalLimit) {
+            break;
+          }
+        }
+      };
+
+      if (accessibilitySnapshot) {
+        appendNode(accessibilitySnapshot, 0);
+      } else {
+        lines.push('- No accessibility nodes');
+      }
+
+      const unboundedText = lines.join('\n');
+      const truncatedText = unboundedText.length > maxCharacters
+        ? unboundedText.slice(0, maxCharacters)
+        : unboundedText;
+      const state = this.getState();
+      return {
+        tabId: observedTab.id,
+        url: observedTab.url,
+        title: observedTab.title,
+        tab: this.createTabState(observedTab),
+        state,
+        text: truncatedText,
+        truncated: reachedTraversalLimit || unboundedText.length > maxCharacters,
+      };
+    });
+  }
+
+  public async click(optionsArg: ILiveBrowserClickOptions): Promise<void> {
+    const selector = validateBoundedString(
+      optionsArg.selector,
+      'selector',
+      1,
+      maxSelectorLength,
+    );
+    const timeout = this.validateTimeout(optionsArg.timeoutMs);
+    const allowedButtons = ['left', 'middle', 'right'];
+    if (optionsArg.button !== undefined && !allowedButtons.includes(optionsArg.button)) {
+      throw new Error('click button is invalid');
+    }
+    const clickCount = optionsArg.clickCount === undefined
+      ? undefined
+      : validateInteger(optionsArg.clickCount, 'clickCount', 1, 3);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.requireSemanticActionTarget(optionsArg);
+      await this.ensureTabViewport(tab);
+      const actionTab = this.requireSemanticActionTarget(optionsArg);
+      await actionTab.page.locator(selector).setTimeout(timeout).click({
+        button: optionsArg.button,
+        count: clickCount,
+        signal,
+      });
+      await this.refreshTab(actionTab);
+      this.emitState();
+    });
+  }
+
+  public async fill(optionsArg: ILiveBrowserFillOptions): Promise<void> {
+    const selector = validateBoundedString(
+      optionsArg.selector,
+      'selector',
+      1,
+      maxSelectorLength,
+    );
+    const text = validateBoundedString(optionsArg.text, 'text', 0, maxTextLength);
+    const timeout = this.validateTimeout(optionsArg.timeoutMs);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.requireSemanticActionTarget(optionsArg);
+      await this.ensureTabViewport(tab);
+      const actionTab = this.requireSemanticActionTarget(optionsArg);
+      await actionTab.page.locator(selector).setTimeout(timeout).fill(text, { signal });
+      await this.refreshTab(actionTab);
+      this.emitState();
+    });
+  }
+
+  public async press(optionsArg: ILiveBrowserPressOptions): Promise<void> {
+    const selector = validateBoundedString(
+      optionsArg.selector,
+      'selector',
+      1,
+      maxSelectorLength,
+    );
+    const key = validateBoundedString(optionsArg.key, 'key', 1, 64);
+    const timeout = this.validateTimeout(optionsArg.timeoutMs);
+    return this.enqueuePublicOperation(async (signal) => {
+      const tab = this.requireSemanticActionTarget(optionsArg);
+      await this.ensureTabViewport(tab);
+      const actionTab = this.requireSemanticActionTarget(optionsArg);
+      const element = await actionTab.page.waitForSelector(selector, {
+        visible: true,
+        timeout,
+        signal,
+      });
+      if (!element) {
+        throw new Error(`No visible element matched selector: ${selector}`);
+      }
+      try {
+        await element.press(key as plugins.puppeteer.KeyInput);
+      } finally {
+        await element.dispose();
+      }
+      await this.refreshTab(actionTab);
+      this.emitState();
+    });
+  }
+
+  private enqueuePublicOperation<T>(
+    operation: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    if (
+      this.status === 'stopping'
+      || this.normalStopRequested
+      || (this.status === 'stopped' && this.operationRunning)
+    ) {
+      return Promise.reject(new Error('LiveBrowserSession is stopping'));
+    }
+    if (this.admittedPublicOperations >= maxQueuedPublicOperations) {
+      return Promise.reject(new Error('LiveBrowserSession operation queue is full'));
+    }
+    this.admittedPublicOperations += 1;
+    return this.enqueueQueuedOperation('public', operation);
+  }
+
+  private enqueueInternalOperation(
+    operation: (signal: AbortSignal) => Promise<void>,
+    priority = false,
+  ): Promise<void> {
+    if (this.status === 'stopped' || this.status === 'stopping') {
+      return Promise.reject(new Error('LiveBrowserSession is stopping'));
+    }
+    this.admittedInternalOperations += 1;
+    return this.enqueueQueuedOperation('internal', operation, priority);
+  }
+
+  private enqueueQueuedOperation<T>(
+    kind: TQueuedOperationKind,
+    operation: (signal: AbortSignal) => Promise<T>,
+    priority = false,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const queuedOperation: IQueuedOperation = {
+        kind,
+        controller: new AbortController(),
+        run: operation,
+        resolve: (value) => resolve(value as T),
+        reject,
+      };
+      if (priority) {
+        this.operationQueue.unshift(queuedOperation);
+      } else {
+        this.operationQueue.push(queuedOperation);
+      }
+      this.drainOperationQueue();
+    });
+  }
+
+  private drainOperationQueue(): void {
+    if (this.operationRunning) {
+      return;
+    }
+    const queuedOperation = this.operationQueue.shift();
+    if (!queuedOperation) {
+      return;
+    }
+    this.operationRunning = true;
+    this.activeOperation = queuedOperation;
+    void this.executeQueuedOperation(queuedOperation).catch((error) => {
+      this.operationRunning = false;
+      this.activeOperation = undefined;
+      this.emitError({
+        code: 'operation_scheduler_failed',
+        message: normalizeErrorMessage(error),
+        fatal: true,
+      });
+      this.drainOperationQueue();
+    });
+  }
+
+  private async executeQueuedOperation(queuedOperation: IQueuedOperation): Promise<void> {
+    try {
+      if (queuedOperation.controller.signal.aborted) {
+        throw queuedOperation.controller.signal.reason;
+      }
+      queuedOperation.resolve(await queuedOperation.run(queuedOperation.controller.signal));
+    } catch (error) {
+      queuedOperation.reject(error);
+    } finally {
+      if (queuedOperation.kind === 'public') {
+        this.admittedPublicOperations -= 1;
+      } else if (queuedOperation.kind === 'internal') {
+        this.admittedInternalOperations -= 1;
+      }
+      if (this.activeOperation === queuedOperation) {
+        this.activeOperation = undefined;
+      }
+      this.operationRunning = false;
+      if (
+        this.status === 'stopped'
+        && !this.operationQueue.some((operation) => operation.kind === 'shutdown')
+      ) {
+        this.normalStopRequested = false;
+      }
+      this.drainOperationQueue();
+    }
+  }
+
+  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);
+    }
+  }
+
+  private beginShutdown(abortActiveOperation: boolean): void {
+    if (this.status !== 'stopped' && this.status !== 'stopping') {
+      this.status = 'stopping';
+      this.emitState();
+    }
+    const shutdownError = new Error('LiveBrowserSession is stopping');
+    if (
+      abortActiveOperation
+      && this.activeOperation
+      && this.activeOperation.kind !== 'shutdown'
+    ) {
+      this.activeOperation.controller.abort(shutdownError);
+    }
+    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
+      this.browserLifetimeController.abort(shutdownError);
+    }
+    this.cancelQueuedOperations(shutdownError);
+  }
+
+  private requestShutdown(error?: ILiveBrowserError): Promise<void> {
+    if (this.status === 'stopped') {
+      return Promise.resolve();
+    }
+    if (this.shutdownPromise) {
+      return this.shutdownPromise;
+    }
+    this.beginShutdown(true);
+    const shutdownPromise = this.enqueueQueuedOperation(
+      'shutdown',
+      async () => this.stopInternal(error),
+      true,
+    );
+    this.shutdownPromise = shutdownPromise;
+    void shutdownPromise.then(
+      () => {
+        if (this.shutdownPromise === shutdownPromise) {
+          this.shutdownPromise = undefined;
+        }
+      },
+      () => {
+        if (this.shutdownPromise === shutdownPromise) {
+          this.shutdownPromise = undefined;
+        }
+      },
+    );
+    return shutdownPromise;
+  }
+
+  private scheduleOperation(
+    operation: (signal: AbortSignal) => Promise<void>,
+    errorCode: string,
+    tabId?: string,
+    priority = false,
+  ): boolean {
+    if (this.admittedInternalOperations >= maxQueuedInternalOperations) {
+      const queueError = new Error('LiveBrowserSession internal operation queue is full');
+      const liveBrowserError: ILiveBrowserError = {
+        code: 'internal_operation_queue_full',
+        message: queueError.message,
+        fatal: priority,
+        ...(tabId ? { tabId } : {}),
+      };
+      this.emitError(liveBrowserError);
+      if (priority) {
+        void this.requestShutdown(liveBrowserError).catch((error) => {
+          this.emitError({
+            code: 'queue_overflow_shutdown_failed',
+            message: normalizeErrorMessage(error),
+            fatal: true,
+          });
+        });
+      }
+      return false;
+    }
+    void this.enqueueInternalOperation(operation, priority).catch((error) => {
+      if (
+        this.status === 'stopped'
+        || this.status === 'stopping'
+        || this.normalStopRequested
+      ) {
+        return;
+      }
+      this.emitError({
+        code: errorCode,
+        message: normalizeErrorMessage(error),
+        fatal: false,
+        ...(tabId ? { tabId } : {}),
+      });
+    });
+    return true;
+  }
+
+  private emitEvent(event: TLiveBrowserEvent): void {
+    for (const listener of [...this.eventListeners]) {
+      try {
+        listener(event);
+      } catch {
+        // A consumer listener must not interrupt browser lifecycle cleanup.
+      }
+    }
+  }
+
+  private emitState(): void {
+    this.emitEvent({
+      type: 'state',
+      state: this.getState(),
+    });
+  }
+
+  private emitError(error: ILiveBrowserError): void {
+    if (error.fatal) {
+      this.lastError = { ...error };
+    }
+    this.emitEvent({
+      type: 'error',
+      error: { ...error },
+    });
+    this.emitState();
+  }
+
+  private createTabState(tab: IPrivateLiveBrowserTab): ILiveBrowserTabState {
+    return {
+      id: tab.id,
+      url: tab.url,
+      title: tab.title,
+      active: this.activeTabId === tab.id,
+      status: tab.status,
+      generation: tab.generation,
+      appliedViewportRevision: tab.appliedViewportRevision,
+      streaming: tab.streaming,
+    };
+  }
+
+  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.browserDisconnectedListener) {
+      browser.off('disconnected', this.browserDisconnectedListener);
+    }
+    this.browserDisconnectedListener = undefined;
+
+    const shutdownErrors: unknown[] = [];
+    for (const tab of [...this.tabs.values()]) {
+      tab.closing = true;
+      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);
+      }
+    }
+
+    for (const tab of this.tabs.values()) {
+      this.tabIdsByPage.delete(tab.page);
+    }
+    this.tabs.clear();
+    this.outstandingFrames.clear();
+    this.browser = undefined;
+    this.browserContext = undefined;
+    this.browserLifetimeController = undefined;
+    this.activeTabId = null;
+    this.status = 'stopped';
+    this.emitState();
+    if (shutdownErrors.length > 0 && !error) {
+      throw new AggregateError(shutdownErrors, 'LiveBrowserSession shutdown was incomplete');
+    }
+  }
+
+  private requireBrowserContext(): plugins.puppeteer.BrowserContext {
+    if (this.status !== 'running' || !this.browserContext) {
+      throw new Error('LiveBrowserSession is not running');
+    }
+    return this.browserContext;
+  }
+
+  private requireTab(tabId: string): IPrivateLiveBrowserTab {
+    validateBoundedString(tabId, 'tabId', 1, 128);
+    const tab = this.tabs.get(tabId);
+    if (!tab) {
+      throw new Error(`Unknown tab: ${tabId}`);
+    }
+    return tab;
+  }
+
+  private requireActiveTab(): IPrivateLiveBrowserTab {
+    if (this.status !== 'running' || !this.activeTabId) {
+      throw new Error('LiveBrowserSession has no active tab');
+    }
+    const tab = this.requireTab(this.activeTabId);
+    if (tab.status !== 'open' || tab.page.isClosed()) {
+      throw new Error(`Active tab is not available: ${tab.id}`);
+    }
+    return tab;
+  }
+
+  private resolveActionTab(tabId?: string): IPrivateLiveBrowserTab {
+    if (this.status !== 'running') {
+      throw new Error('LiveBrowserSession is not running');
+    }
+    const tab = tabId ? this.requireTab(tabId) : this.requireActiveTab();
+    if (tab.status !== 'open' || tab.page.isClosed()) {
+      throw new Error(`Tab is not available: ${tab.id}`);
+    }
+    return tab;
+  }
+
+  private resolveNavigationTab(tabId?: string): IPrivateLiveBrowserTab {
+    return this.resolveActionTab(tabId);
+  }
+
+  private async ensureTabViewport(tab: IPrivateLiveBrowserTab): Promise<void> {
+    if (tab.appliedViewportRevision === this.viewportRevision) {
+      return;
+    }
+    const shouldRestartScreencast = this.activeTabId === tab.id && tab.streaming;
+    if (shouldRestartScreencast) {
+      await this.stopScreencast(tab);
+    }
+    try {
+      await tab.page.setViewport(createPuppeteerViewport(this.viewport));
+      tab.appliedViewportRevision = this.viewportRevision;
+    } finally {
+      if (
+        shouldRestartScreencast
+        && this.status === 'running'
+        && this.activeTabId === tab.id
+        && tab.status === 'open'
+        && !tab.page.isClosed()
+      ) {
+        await this.startScreencast(tab);
+      }
+    }
+  }
+
+  private async registerPage(page: plugins.puppeteer.Page): Promise<IPrivateLiveBrowserTab> {
+    const existingTabId = this.tabIdsByPage.get(page);
+    if (existingTabId) {
+      return this.requireTab(existingTabId);
+    }
+    if (page.isClosed()) {
+      throw new Error('Cannot register a closed page');
+    }
+
+    const tab: IPrivateLiveBrowserTab = {
+      id: `tab-${++this.tabSequence}`,
+      page,
+      url: truncate(page.url(), 4096),
+      title: '',
+      status: 'open',
+      generation: 0,
+      appliedViewportRevision: 0,
+      streaming: false,
+      streamInvalidated: true,
+      navigationInProgress: false,
+      closing: false,
+      stateUpdateQueued: false,
+      stateUpdatePending: false,
+      navigationResetPending: false,
+      removeListeners: [],
+    };
+    this.tabs.set(tab.id, tab);
+    this.tabIdsByPage.set(page, tab.id);
+    try {
+      await this.ensureTabViewport(tab);
+      await this.refreshTab(tab);
+
+      const onPopup = (popup: plugins.puppeteer.Page | null): void => {
+        if (
+          !popup
+          || this.normalStopRequested
+          || this.status === 'stopped'
+          || this.status === 'stopping'
+        ) {
+          return;
+        }
+        const popupWasScheduled = this.scheduleOperation(async () => {
+          if (popup.isClosed()) {
+            return;
+          }
+          const previousActiveTabId = this.activeTabId;
+          let popupTab: IPrivateLiveBrowserTab | undefined;
+          try {
+            popupTab = await this.registerPage(popup);
+            await this.activateTabInternal(popupTab.id);
+          } catch (error) {
+            const rollbackError = await this.rollbackCreatedPage(
+              popup,
+              popupTab,
+              previousActiveTabId,
+            );
+            if (rollbackError) {
+              throw new AggregateError([error, rollbackError], 'Popup registration rollback failed');
+            }
+            throw error;
+          }
+        }, 'popup_registration_failed', tab.id);
+        if (!popupWasScheduled) {
+          const popupError: ILiveBrowserError = {
+            code: 'popup_registration_capacity_exceeded',
+            message: 'A popup could not be admitted to the internal operation queue',
+            fatal: true,
+            tabId: tab.id,
+          };
+          this.emitError(popupError);
+          void this.requestShutdown(popupError).catch((shutdownError) => {
+            this.emitError({
+              code: 'untracked_popup_shutdown_failed',
+              message: normalizeErrorMessage(shutdownError),
+              fatal: true,
+              tabId: tab.id,
+            });
+          });
+        }
+      };
+      const onFrameNavigated = (frame: plugins.puppeteer.Frame): void => {
+        if (frame !== page.mainFrame() || tab.closing) {
+          return;
+        }
+        const navigationReset = !tab.navigationInProgress;
+        if (navigationReset) {
+          tab.streamInvalidated = true;
+          this.retireFramesForTabInBackground(tab.id);
+        }
+        this.requestTabStateUpdate(tab, navigationReset);
+      };
+      const onLoad = (): void => {
+        this.requestTabStateUpdate(tab, false);
+      };
+      const onClose = (): void => {
+        tab.streamInvalidated = true;
+        this.retireFramesForTabInBackground(tab.id);
+        if (tab.closing || this.normalStopRequested) {
+          return;
+        }
+        this.scheduleOperation(async () => {
+          await this.handleUnexpectedPageClose(tab);
+        }, 'page_close_cleanup_failed', tab.id, true);
+      };
+      const onCrash = (error: Error): void => {
+        tab.streamInvalidated = true;
+        this.retireFramesForTabInBackground(tab.id);
+        if (tab.closing || this.normalStopRequested) {
+          return;
+        }
+        this.scheduleOperation(async () => {
+          if (!this.tabs.has(tab.id) || tab.status === 'crashed') {
+            return;
+          }
+          await this.stopScreencast(tab);
+          tab.status = 'crashed';
+          const wasActive = this.activeTabId === tab.id;
+          if (wasActive) {
+            this.activeTabId = null;
+          }
+          this.emitError({
+            code: 'page_crashed',
+            message: normalizeErrorMessage(error),
+            fatal: false,
+            tabId: tab.id,
+          });
+          if (wasActive) {
+            await this.activateReplacementTab();
+          }
+        }, 'page_crash_cleanup_failed', tab.id, true);
+      };
+      const onPageError = (error: unknown): void => {
+        if (tab.closing || this.normalStopRequested) {
+          return;
+        }
+        this.emitError({
+          code: 'page_error',
+          message: normalizeErrorMessage(error),
+          fatal: false,
+          tabId: tab.id,
+        });
+      };
+
+      page.on('popup', onPopup);
+      page.on('framenavigated', onFrameNavigated);
+      page.on('load', onLoad);
+      page.on('close', onClose);
+      page.on('error', onCrash);
+      page.on('pageerror', onPageError);
+      tab.removeListeners.push(
+        () => page.off('popup', onPopup),
+        () => page.off('framenavigated', onFrameNavigated),
+        () => page.off('load', onLoad),
+        () => page.off('close', onClose),
+        () => page.off('error', onCrash),
+        () => page.off('pageerror', onPageError),
+      );
+      return tab;
+    } catch (error) {
+      this.removePageListeners(tab);
+      this.tabs.delete(tab.id);
+      this.tabIdsByPage.delete(page);
+      throw error;
+    }
+  }
+
+  private removePageListeners(tab: IPrivateLiveBrowserTab): void {
+    for (const removeListener of tab.removeListeners.splice(0)) {
+      removeListener();
+    }
+  }
+
+  private retireFramesForTabInBackground(tabId: string): void {
+    void this.retireOutstandingFrames((frame) => frame.tabId === tabId).catch((error) => {
+      if (this.status === 'running' && !this.normalStopRequested) {
+        this.emitError({
+          code: 'frame_retirement_failed',
+          message: normalizeErrorMessage(error),
+          fatal: false,
+          tabId,
+        });
+      }
+    });
+  }
+
+  private requestTabStateUpdate(
+    tab: IPrivateLiveBrowserTab,
+    navigationReset: boolean,
+  ): void {
+    if (!this.tabs.has(tab.id) || tab.closing) {
+      return;
+    }
+    tab.stateUpdatePending = true;
+    tab.navigationResetPending ||= navigationReset;
+    if (tab.stateUpdateQueued) {
+      return;
+    }
+    tab.stateUpdateQueued = true;
+    const wasScheduled = this.scheduleOperation(async () => {
+      try {
+        const shouldResetNavigation = tab.navigationResetPending;
+        tab.stateUpdatePending = false;
+        tab.navigationResetPending = false;
+        if (!this.tabs.has(tab.id) || tab.closing) {
+          return;
+        }
+        if (shouldResetNavigation && this.activeTabId === tab.id) {
+          await this.stopScreencast(tab);
+        }
+        await this.refreshTab(tab);
+        this.emitState();
+        if (
+          shouldResetNavigation
+          && this.activeTabId === tab.id
+          && this.status === 'running'
+          && tab.status === 'open'
+        ) {
+          await this.startScreencast(tab);
+        }
+      } finally {
+        tab.stateUpdateQueued = false;
+        if (
+          tab.stateUpdatePending
+          && this.tabs.has(tab.id)
+          && this.status === 'running'
+          && !tab.closing
+        ) {
+          this.requestTabStateUpdate(tab, false);
+        }
+      }
+    }, 'page_state_update_failed', tab.id);
+    if (!wasScheduled) {
+      tab.stateUpdateQueued = false;
+    }
+  }
+
+  private async rollbackCreatedPage(
+    page: plugins.puppeteer.Page,
+    tab: IPrivateLiveBrowserTab | undefined,
+    previousActiveTabId: string | null,
+  ): Promise<Error | undefined> {
+    const rollbackErrors: unknown[] = [];
+    if (tab) {
+      try {
+        await this.stopScreencast(tab);
+      } catch (error) {
+        rollbackErrors.push(error);
+      }
+      tab.closing = true;
+    }
+    try {
+      if (!page.isClosed()) {
+        await page.close();
+      }
+    } catch (error) {
+      rollbackErrors.push(error);
+    }
+    const pageClosed = page.isClosed();
+    if (tab) {
+      if (pageClosed) {
+        this.removePageListeners(tab);
+        this.tabs.delete(tab.id);
+        this.tabIdsByPage.delete(tab.page);
+      } else {
+        tab.closing = false;
+        try {
+          await this.refreshTab(tab);
+        } catch (error) {
+          rollbackErrors.push(error);
+        }
+      }
+    } else {
+      this.tabIdsByPage.delete(page);
+      if (!pageClosed) {
+        const rollbackError: ILiveBrowserError = {
+          code: 'untracked_page_rollback_failed',
+          message: 'A failed page registration could not close its Chromium page',
+          fatal: true,
+        };
+        if (!this.normalStopRequested && this.status === 'running') {
+          this.emitError(rollbackError);
+        }
+        this.normalStopRequested = true;
+        this.beginShutdown(false);
+        try {
+          await this.stopInternal();
+        } catch (error) {
+          rollbackErrors.push(error);
+        }
+      }
+    }
+
+    const previousActiveTab = previousActiveTabId
+      ? this.tabs.get(previousActiveTabId)
+      : undefined;
+    this.activeTabId = previousActiveTab?.id ?? null;
+    if (
+      previousActiveTab
+      && previousActiveTab.status === 'open'
+      && !previousActiveTab.page.isClosed()
+    ) {
+      try {
+        await this.ensureTabViewport(previousActiveTab);
+        await previousActiveTab.page.bringToFront();
+        if (this.status === 'running' && !previousActiveTab.streaming) {
+          await this.startScreencast(previousActiveTab);
+        }
+      } catch (error) {
+        rollbackErrors.push(error);
+      }
+    }
+    this.emitState();
+    if (rollbackErrors.length === 0) {
+      return undefined;
+    }
+    return new AggregateError(rollbackErrors, 'Failed to roll back a new tab');
+  }
+
+  private async handleUnexpectedPageClose(tab: IPrivateLiveBrowserTab): Promise<void> {
+    if (!this.tabs.has(tab.id)) {
+      return;
+    }
+    await this.stopScreencast(tab);
+    this.removePageListeners(tab);
+    this.tabs.delete(tab.id);
+    this.tabIdsByPage.delete(tab.page);
+
+    if (this.activeTabId === tab.id) {
+      this.activeTabId = null;
+      await this.activateReplacementTab();
+    } else {
+      this.emitState();
+    }
+  }
+
+  private async activateTabInternal(tabId: string): Promise<void> {
+    const tab = this.requireTab(tabId);
+    if (tab.status !== 'open' || tab.page.isClosed()) {
+      throw new Error(`Tab is not available: ${tab.id}`);
+    }
+    if (this.activeTabId === tab.id && tab.streaming) {
+      await tab.page.bringToFront();
+      return;
+    }
+
+    const currentTab = this.activeTabId ? this.tabs.get(this.activeTabId) : undefined;
+    if (currentTab) {
+      await this.stopScreencast(currentTab);
+    }
+    try {
+      await this.ensureTabViewport(tab);
+      await tab.page.bringToFront();
+      this.activeTabId = tab.id;
+      this.emitState();
+      if (this.status === 'running') {
+        await this.startScreencast(tab);
+      }
+    } catch (error) {
+      if (currentTab && this.tabs.has(currentTab.id) && !currentTab.page.isClosed()) {
+        this.activeTabId = currentTab.id;
+        await this.ensureTabViewport(currentTab);
+        await currentTab.page.bringToFront();
+        if (this.status === 'running' && !currentTab.streaming) {
+          await this.startScreencast(currentTab);
+        }
+      }
+      this.emitState();
+      throw error;
+    }
+  }
+
+  private async activateReplacementTab(): Promise<void> {
+    const attemptedTabIds = new Set<string>();
+    while (true) {
+      const replacementTab = [...this.tabs.values()].find((tab) => (
+        !attemptedTabIds.has(tab.id)
+        && tab.status === 'open'
+        && !tab.page.isClosed()
+      ));
+      if (!replacementTab) {
+        this.activeTabId = null;
+        this.normalStopRequested = true;
+        this.beginShutdown(false);
+        await this.stopInternal();
+        return;
+      }
+
+      attemptedTabIds.add(replacementTab.id);
+      try {
+        await this.activateTabInternal(replacementTab.id);
+        return;
+      } catch (error) {
+        this.activeTabId = null;
+        this.emitError({
+          code: 'replacement_tab_activation_failed',
+          message: normalizeErrorMessage(error),
+          fatal: false,
+          tabId: replacementTab.id,
+        });
+      }
+    }
+  }
+
+  private async navigateTab(
+    tab: IPrivateLiveBrowserTab,
+    navigation: () => Promise<void>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const isActive = this.activeTabId === tab.id;
+    tab.navigationInProgress = true;
+    if (isActive) {
+      await this.stopScreencast(tab);
+    }
+    try {
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      await navigation();
+    } finally {
+      tab.navigationInProgress = false;
+      if (this.tabs.has(tab.id) && !tab.page.isClosed()) {
+        await this.refreshTab(tab);
+        this.emitState();
+        if (
+          isActive
+          && this.activeTabId === tab.id
+          && this.status === 'running'
+          && tab.status === 'open'
+          && !signal.aborted
+        ) {
+          await this.startScreencast(tab);
+        }
+      }
+    }
+  }
+
+  private createPuppeteerNavigationOptions(
+    options: ILiveBrowserNavigationOptions,
+    signal: AbortSignal,
+  ): plugins.puppeteer.WaitForOptions {
+    return {
+      timeout: this.validateTimeout(options.timeoutMs, 30000),
+      waitUntil: this.validateWaitUntil(options.waitUntil),
+      signal,
+    };
+  }
+
+  private async refreshTab(tab: IPrivateLiveBrowserTab): Promise<void> {
+    if (tab.page.isClosed()) {
+      return;
+    }
+    tab.url = truncate(tab.page.url(), 4096);
+    try {
+      tab.title = truncate(await tab.page.title(), 1024);
+    } catch (error) {
+      if (!tab.page.isClosed() && !tab.closing) {
+        throw error;
+      }
+    }
+  }
+
+  private async startScreencast(tab: IPrivateLiveBrowserTab): Promise<void> {
+    if (
+      this.status !== 'running'
+      || this.activeTabId !== tab.id
+      || tab.status !== 'open'
+      || tab.page.isClosed()
+      || tab.streaming
+    ) {
+      return;
+    }
+
+    await this.ensureTabViewport(tab);
+
+    const cdpSession = await tab.page.createCDPSession();
+    const generation = tab.generation + 1;
+    const frameListener: TScreencastFrameListener = (event) => {
+      this.handleScreencastFrame(tab, cdpSession, generation, event);
+    };
+    const cdpConnection = cdpSession.connection();
+    const cdpSessionDetachedListener: TCdpSessionDetachedListener = (detachedSession) => {
+      if (detachedSession !== cdpSession) {
+        return;
+      }
+      this.handlePossibleCdpDisconnection(
+        tab,
+        cdpSession,
+        new Error('The tab CDP session disconnected'),
+      );
+    };
+    tab.cdpSession = cdpSession;
+    tab.cdpConnection = cdpConnection;
+    tab.screencastFrameListener = frameListener;
+    tab.cdpSessionDetachedListener = cdpSessionDetachedListener;
+    tab.generation = generation;
+    tab.streaming = true;
+    tab.streamInvalidated = false;
+    cdpSession.on('Page.screencastFrame', frameListener);
+    cdpConnection?.on(
+      plugins.puppeteer.CDPSessionEvent.SessionDetached,
+      cdpSessionDetachedListener,
+    );
+
+    const format = this.options.screencast?.format ?? 'jpeg';
+    try {
+      await cdpSession.send('Page.startScreencast', {
+        format,
+        quality: this.options.screencast?.quality ?? 80,
+        maxWidth: this.options.screencast?.maxWidth,
+        maxHeight: this.options.screencast?.maxHeight,
+        everyNthFrame: this.options.screencast?.everyNthFrame ?? 1,
+      });
+      this.emitState();
+    } catch (error) {
+      tab.streaming = false;
+      tab.streamInvalidated = true;
+      tab.cdpSession = undefined;
+      tab.cdpConnection = undefined;
+      tab.screencastFrameListener = undefined;
+      tab.cdpSessionDetachedListener = undefined;
+      cdpSession.off('Page.screencastFrame', frameListener);
+      cdpConnection?.off(
+        plugins.puppeteer.CDPSessionEvent.SessionDetached,
+        cdpSessionDetachedListener,
+      );
+      if (!cdpSession.detached) {
+        try {
+          await cdpSession.detach();
+        } catch {
+          // The target may have closed while screencast startup was failing.
+        }
+      }
+      throw error;
+    }
+  }
+
+  private async stopScreencast(tab: IPrivateLiveBrowserTab): Promise<void> {
+    const cdpSession = tab.cdpSession;
+    const cdpConnection = tab.cdpConnection;
+    const frameListener = tab.screencastFrameListener;
+    const cdpSessionDetachedListener = tab.cdpSessionDetachedListener;
+    tab.streaming = false;
+    tab.streamInvalidated = true;
+    tab.cdpSession = undefined;
+    tab.cdpConnection = undefined;
+    tab.screencastFrameListener = undefined;
+    tab.cdpSessionDetachedListener = undefined;
+    await this.retireOutstandingFrames((frame) => frame.tabId === tab.id);
+    if (!cdpSession) {
+      return;
+    }
+
+    if (!cdpSession.detached) {
+      try {
+        await cdpSession.send('Page.stopScreencast');
+      } catch {
+        // Page close and browser disconnect detach the target before cleanup runs.
+      }
+    }
+    await this.retireOutstandingFrames((frame) => frame.tabId === tab.id);
+    if (frameListener) {
+      cdpSession.off('Page.screencastFrame', frameListener);
+    }
+    if (cdpConnection && cdpSessionDetachedListener) {
+      cdpConnection.off(
+        plugins.puppeteer.CDPSessionEvent.SessionDetached,
+        cdpSessionDetachedListener,
+      );
+    }
+    if (!cdpSession.detached) {
+      try {
+        await cdpSession.detach();
+      } catch {
+        // A concurrent page close can detach the session first.
+      }
+    }
+  }
+
+  private handleScreencastFrame(
+    tab: IPrivateLiveBrowserTab,
+    cdpSession: plugins.puppeteer.CDPSession,
+    generation: number,
+    event: TScreencastFrameEvent,
+  ): void {
+    if (
+      this.status !== 'running'
+      || this.activeTabId !== tab.id
+      || tab.status !== 'open'
+      || tab.streamInvalidated
+      || !tab.streaming
+      || tab.generation !== generation
+      || tab.appliedViewportRevision !== this.viewportRevision
+      || tab.cdpSession !== cdpSession
+    ) {
+      this.acknowledgeCdpFrameInBackground({
+        tabId: tab.id,
+        generation,
+        viewportRevision: this.viewportRevision,
+        cdpSessionId: event.sessionId,
+        cdpSession,
+      });
+      return;
+    }
+
+    const format = this.options.screencast?.format ?? 'jpeg';
+    const data = new Uint8Array(plugins.Buffer.from(event.data, 'base64'));
+    const dimensions = readImageDimensions(data, format, {
+      width: Math.max(1, Math.round(event.metadata.deviceWidth)),
+      height: Math.max(1, Math.round(event.metadata.deviceHeight)),
+    });
+    const sequence = ++this.frameSequence;
+    const outstandingFrame: IOutstandingFrame = {
+      tabId: tab.id,
+      generation,
+      viewportRevision: this.viewportRevision,
+      cdpSessionId: event.sessionId,
+      cdpSession,
+    };
+    while (this.outstandingFrames.size >= maxOutstandingFrames) {
+      const oldestFrameEntry = this.outstandingFrames.entries().next().value as
+        | [number, IOutstandingFrame]
+        | undefined;
+      if (!oldestFrameEntry) {
+        break;
+      }
+      this.outstandingFrames.delete(oldestFrameEntry[0]);
+      this.acknowledgeCdpFrameInBackground(oldestFrameEntry[1]);
+    }
+    this.outstandingFrames.set(sequence, outstandingFrame);
+    const frame: ILiveBrowserFrame = {
+      tabId: tab.id,
+      sequence,
+      generation,
+      viewportRevision: this.viewportRevision,
+      viewport: { ...this.viewport },
+      format,
+      mimeType: format === 'jpeg' ? 'image/jpeg' : 'image/png',
+      ...dimensions,
+      metadata: {
+        offsetTop: event.metadata.offsetTop,
+        pageScaleFactor: event.metadata.pageScaleFactor,
+        deviceWidth: event.metadata.deviceWidth,
+        deviceHeight: event.metadata.deviceHeight,
+        scrollOffsetX: event.metadata.scrollOffsetX,
+        scrollOffsetY: event.metadata.scrollOffsetY,
+        ...(event.metadata.timestamp !== undefined
+          ? { timestamp: event.metadata.timestamp }
+          : {}),
+      },
+      data,
+    };
+    this.emitEvent({ type: 'frame', frame });
+  }
+
+  private async acknowledgeCdpFrame(frame: IOutstandingFrame): Promise<boolean> {
+    if (frame.cdpSession.detached) {
+      this.handleFrameAcknowledgementFailure(
+        frame,
+        new Error('CDP session detached before frame acknowledgement'),
+      );
+      return false;
+    }
+    try {
+      await frame.cdpSession.send('Page.screencastFrameAck', {
+        sessionId: frame.cdpSessionId,
+      });
+      return true;
+    } catch (error) {
+      this.handleFrameAcknowledgementFailure(frame, error);
+      return false;
+    }
+  }
+
+  private acknowledgeCdpFrameInBackground(frame: IOutstandingFrame): void {
+    void this.acknowledgeCdpFrame(frame);
+  }
+
+  private handleFrameAcknowledgementFailure(
+    frame: IOutstandingFrame,
+    error: unknown,
+  ): void {
+    const tab = this.tabs.get(frame.tabId);
+    const isCurrentStream = Boolean(
+      tab
+      && tab.cdpSession === frame.cdpSession
+      && !tab.streamInvalidated,
+    );
+    if (
+      isCurrentStream
+      && this.status === 'running'
+      && !this.normalStopRequested
+    ) {
+      this.emitError({
+        code: 'frame_acknowledgement_failed',
+        message: normalizeErrorMessage(error),
+        fatal: false,
+        tabId: frame.tabId,
+      });
+    }
+    if (tab) {
+      this.handlePossibleCdpDisconnection(tab, frame.cdpSession, error);
+    }
+  }
+
+  private async retireOutstandingFrames(
+    predicate: (frame: IOutstandingFrame) => boolean,
+  ): Promise<void> {
+    const acknowledgements: Array<Promise<boolean>> = [];
+    for (const [sequence, frame] of this.outstandingFrames) {
+      if (!predicate(frame)) {
+        continue;
+      }
+      this.outstandingFrames.delete(sequence);
+      acknowledgements.push(this.acknowledgeCdpFrame(frame));
+    }
+    await Promise.all(acknowledgements);
+  }
+
+  private handlePossibleCdpDisconnection(
+    tab: IPrivateLiveBrowserTab,
+    cdpSession: plugins.puppeteer.CDPSession,
+    error: unknown,
+  ): void {
+    if (
+      this.normalStopRequested
+      || this.status !== 'running'
+      || tab.cdpSession !== cdpSession
+      || tab.streamInvalidated
+      || !cdpSession.detached
+    ) {
+      return;
+    }
+    tab.streamInvalidated = true;
+    this.retireFramesForTabInBackground(tab.id);
+    this.scheduleOperation(async () => {
+      if (!this.tabs.has(tab.id) || tab.cdpSession !== cdpSession) {
+        return;
+      }
+      await this.stopScreencast(tab);
+      tab.status = 'crashed';
+      const wasActive = this.activeTabId === tab.id;
+      if (wasActive) {
+        this.activeTabId = null;
+      }
+      this.emitError({
+        code: 'cdp_disconnected',
+        message: normalizeErrorMessage(error),
+        fatal: false,
+        tabId: tab.id,
+      });
+      if (wasActive) {
+        await this.activateReplacementTab();
+      }
+    }, 'cdp_disconnect_cleanup_failed', tab.id, true);
+  }
+
+  private requireRawInputTarget(
+    input: { tabId: string; generation: number; viewportRevision: number },
+  ): { tab: IPrivateLiveBrowserTab; cdpSession: plugins.puppeteer.CDPSession } {
+    const tab = this.requireInputTarget(input, true);
+    const cdpSession = tab.cdpSession;
+    if (!tab.streaming || tab.streamInvalidated || !cdpSession || cdpSession.detached) {
+      throw new Error(`Tab input transport is not available: ${tab.id}`);
+    }
+    return { tab, cdpSession };
+  }
+
+  private requireSemanticActionTarget(
+    input: { tabId: string; generation: number; viewportRevision: number },
+  ): IPrivateLiveBrowserTab {
+    return this.requireInputTarget(input, false);
+  }
+
+  private requireInputTarget(
+    input: { tabId: string; generation: number; viewportRevision: number },
+    requireActive: boolean,
+  ): IPrivateLiveBrowserTab {
+    if (this.status !== 'running') {
+      throw new Error('LiveBrowserSession is not running');
+    }
+    const tab = this.requireTab(input.tabId);
+    if (requireActive && this.activeTabId !== tab.id) {
+      throw new Error(`Tab is not active: ${tab.id}`);
+    }
+    if (!Number.isInteger(input.generation) || input.generation !== tab.generation) {
+      throw new Error(
+        `Stale tab generation ${input.generation}; current generation is ${tab.generation}`,
+      );
+    }
+    if (input.viewportRevision !== this.viewportRevision) {
+      throw new Error(
+        `Stale viewport revision ${input.viewportRevision}; current revision is ${this.viewportRevision}`,
+      );
+    }
+    if (tab.status !== 'open' || tab.page.isClosed()) {
+      throw new Error(`Tab is not available: ${tab.id}`);
+    }
+    return tab;
+  }
+
+  private validateCoordinates(x: number, y: number): void {
+    validateFiniteNumber(x, 'x', 0, this.viewport.width);
+    validateFiniteNumber(y, 'y', 0, this.viewport.height);
+    if (x >= this.viewport.width) {
+      throw new Error(`x must be less than viewport width ${this.viewport.width}`);
+    }
+    if (y >= this.viewport.height) {
+      throw new Error(`y must be less than viewport height ${this.viewport.height}`);
+    }
+  }
+
+  private createModifierMask(modifiers?: ILiveBrowserModifierState): number {
+    if (modifiers === undefined) {
+      return 0;
+    }
+    if (!modifiers || typeof modifiers !== 'object' || Array.isArray(modifiers)) {
+      throw new Error('modifiers must be an object');
+    }
+    const allowedKeys = new Set(['alt', 'control', 'meta', 'shift']);
+    for (const key of Object.keys(modifiers)) {
+      if (!allowedKeys.has(key)) {
+        throw new Error(`Unknown modifier: ${key}`);
+      }
+    }
+    validateOptionalBoolean(modifiers.alt, 'modifiers.alt');
+    validateOptionalBoolean(modifiers.control, 'modifiers.control');
+    validateOptionalBoolean(modifiers.meta, 'modifiers.meta');
+    validateOptionalBoolean(modifiers.shift, 'modifiers.shift');
+    return (
+      (modifiers.alt ? 1 : 0)
+      | (modifiers.control ? 2 : 0)
+      | (modifiers.meta ? 4 : 0)
+      | (modifiers.shift ? 8 : 0)
+    );
+  }
+
+  private validateUrl(url: unknown): string {
+    const validatedUrl = validateBoundedString(url, 'url', 1, maxUrlLength);
+    try {
+      new URL(validatedUrl);
+    } catch {
+      throw new Error('url must be absolute');
+    }
+    return validatedUrl;
+  }
+
+  private validateTimeout(timeoutMs?: number, defaultValue = 5000): number {
+    if (timeoutMs === undefined) {
+      return defaultValue;
+    }
+    return validateInteger(timeoutMs, 'timeoutMs', 1, maxTimeoutMs);
+  }
+
+  private validateWaitUntil(waitUntil?: TLiveBrowserWaitUntil): TLiveBrowserWaitUntil {
+    const validatedWaitUntil = waitUntil ?? 'load';
+    if (!['load', 'domcontentloaded', 'networkidle0', 'networkidle2'].includes(validatedWaitUntil)) {
+      throw new Error('waitUntil must be load, domcontentloaded, networkidle0, or networkidle2');
+    }
+    return validatedWaitUntil;
+  }
+
+  private validateScreencastOptions(): void {
+    const options = this.options.screencast;
+    if (!options) {
+      return;
+    }
+    if (options.format !== undefined && options.format !== 'jpeg' && options.format !== 'png') {
+      throw new Error('screencast.format must be jpeg or png');
+    }
+    if (options.quality !== undefined) {
+      validateInteger(options.quality, 'screencast.quality', 0, 100);
+    }
+    if (options.maxWidth !== undefined) {
+      validateInteger(options.maxWidth, 'screencast.maxWidth', 1, maxViewportWidth);
+    }
+    if (options.maxHeight !== undefined) {
+      validateInteger(options.maxHeight, 'screencast.maxHeight', 1, maxViewportHeight);
+    }
+    if (
+      options.maxWidth !== undefined
+      && options.maxHeight !== undefined
+      && options.maxWidth * options.maxHeight > maxViewportPixelArea
+    ) {
+      throw new Error(
+        `screencast pixel area must not exceed ${maxViewportPixelArea} pixels`,
+      );
+    }
+    if (options.everyNthFrame !== undefined) {
+      validateInteger(options.everyNthFrame, 'screencast.everyNthFrame', 1, 100);
+    }
+  }
+}