@push.rocks/smartpuppeteer 2.3.0 → 2.5.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -1,4 +1,8 @@
 import { getEnvAwareBrowserInstance } from './smartpuppeteer.classes.smartpuppeteer.js';
+import {
+  liveBrowserDefaultMaxOutstandingFrames,
+  liveBrowserMaxOutstandingFrames,
+} from './smartpuppeteer.interfaces.livebrowser.js';
 import {
   delay,
   type IOwnedProcessIdentity,
@@ -17,6 +21,7 @@ import type {
   ILiveBrowserFrame,
   ILiveBrowserFrameAcknowledgement,
   ILiveBrowserFrameAcknowledgementRequest,
+  ILiveBrowserFrameIdentity,
   ILiveBrowserInsertTextInput,
   ILiveBrowserKeyInput,
   ILiveBrowserModifierState,
@@ -59,7 +64,8 @@ const maxSelectorLength = 4096;
 const maxTextLength = 32768;
 const maxUrlLength = 16384;
 const maxTimeoutMs = 60000;
-const maxOutstandingFrames = 3;
+const frameAcknowledgementTimeoutMs = 5000;
+const defaultFirstFrameTimeoutMs = 5000;
 const maxQueuedPublicOperations = 64;
 const maxQueuedInternalOperations = 128;
 const maxEvaluationScriptBytes = 262144;
@@ -119,6 +125,11 @@ interface IOwnedBrowserProcess {
   forceSignalled: boolean;
 }
 
+interface IScreencastAuthority {
+  revision: number;
+  controller: AbortController;
+}
+
 interface IPrivateLiveBrowserTab {
   id: string;
   page: plugins.puppeteer.Page;
@@ -129,6 +140,8 @@ interface IPrivateLiveBrowserTab {
   appliedViewportRevision: number;
   streaming: boolean;
   streamInvalidated: boolean;
+  streamLifecycleRevision: number;
+  screencastAuthority?: IScreencastAuthority;
   navigationInProgress: boolean;
   closing: boolean;
   stateUpdateQueued: boolean;
@@ -143,12 +156,17 @@ interface IPrivateLiveBrowserTab {
   removeListeners: Array<() => void>;
 }
 
-interface IOutstandingFrame {
+interface ICdpScreencastFrame {
   tabId: string;
   generation: number;
   viewportRevision: number;
   cdpSessionId: number;
   cdpSession: plugins.puppeteer.CDPSession;
+  acknowledgementPromise?: Promise<boolean>;
+}
+
+interface IOutstandingFrame extends ICdpScreencastFrame {
+  sequence: number;
 }
 
 interface IImageDimensions {
@@ -367,6 +385,8 @@ export class LiveBrowserSession {
   private readonly tabs = new Map<string, IPrivateLiveBrowserTab>();
   private readonly tabIdsByPage = new WeakMap<plugins.puppeteer.Page, string>();
   private readonly outstandingFrames = new Map<number, IOutstandingFrame>();
+  private readonly cdpFramesBeingAcknowledged = new Set<ICdpScreencastFrame>();
+  private readonly maxOutstandingFrames: number;
 
   private browser?: plugins.puppeteer.Browser;
   private browserContext?: plugins.puppeteer.BrowserContext;
@@ -392,6 +412,7 @@ export class LiveBrowserSession {
   private admittedPublicOperations = 0;
   private admittedInternalOperations = 0;
   private shutdownPromise?: Promise<void>;
+  private shutdownFrameDrainPromise?: Promise<void>;
   private status: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
   private activeTabId: string | null = null;
   private viewport: ILiveBrowserViewport = { ...defaultViewport };
@@ -418,6 +439,16 @@ export class LiveBrowserSession {
     if (optionsArg.launchOptions && 'signal' in optionsArg.launchOptions) {
       throw new Error('LiveBrowserSession owns launch cancellation; launchOptions.signal is unsupported');
     }
+    if (
+      optionsArg.screencast !== undefined
+      && (
+        !optionsArg.screencast
+        || typeof optionsArg.screencast !== 'object'
+        || Array.isArray(optionsArg.screencast)
+      )
+    ) {
+      throw new Error('screencast must be an object');
+    }
     validateOptionalBoolean(optionsArg.allowEvaluation, 'allowEvaluation');
     for (const name of [
       'denyDownloads',
@@ -477,6 +508,8 @@ export class LiveBrowserSession {
     };
     this.viewport = { ...viewport };
     this.validateScreencastOptions();
+    this.maxOutstandingFrames = this.options.screencast?.maxOutstandingFrames
+      ?? liveBrowserDefaultMaxOutstandingFrames;
   }
 
   public onEvent(listener: TLiveBrowserEventListener): () => void {
@@ -802,6 +835,77 @@ export class LiveBrowserSession {
     };
   }
 
+  public refreshScreencast(
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<ILiveBrowserFrameIdentity> {
+    return this.enqueuePublicOperation(async (signal) => {
+      signal.throwIfAborted();
+      const tab = this.requireActiveTab();
+      if (!tab.streaming || tab.streamInvalidated) {
+        throw new Error(`Tab input transport is not available: ${tab.id}`);
+      }
+      let firstFrame: ReturnType<LiveBrowserSession['waitForScreencastFrame']> | undefined;
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const previousLifecycleRevision = tab.streamLifecycleRevision;
+        await this.stopScreencast(tab);
+        const refreshLifecycleRevision = previousLifecycleRevision + 1;
+        if (
+          !this.canRestoreScreencast(tab)
+          || tab.streamLifecycleRevision !== refreshLifecycleRevision
+        ) {
+          throw new Error(`Screencast lifecycle changed while refreshing tab: ${tab.id}`);
+        }
+        const authority = this.createScreencastAuthority(tab, refreshLifecycleRevision);
+        const generation = tab.generation + 1;
+        firstFrame = this.waitForScreencastFrame(
+          tab,
+          generation,
+          this.viewportRevision,
+          authority.controller.signal,
+        );
+        const refreshTimeoutMs = this.options.screencast?.firstFrameTimeoutMs
+          ?? defaultFirstFrameTimeoutMs;
+        const refreshTimeout = new Promise<never>((_resolve, reject) => {
+          timeout = setTimeout(() => {
+            reject(new Error(
+              `Screencast generation ${generation} did not restart and produce a frame within ${
+                refreshTimeoutMs
+              }ms`,
+            ));
+          }, refreshTimeoutMs);
+        });
+        const restartPromise = this.startScreencast(tab, authority);
+        const [, identity] = await Promise.race([
+          Promise.all([restartPromise, firstFrame.promise]),
+          refreshTimeout,
+        ]);
+        return identity;
+      } catch (error) {
+        if (!this.canRestoreScreencast(tab)) throw error;
+        const refreshError: ILiveBrowserError = {
+          code: 'screencast_refresh_failed',
+          message: normalizeErrorMessage(error),
+          fatal: true,
+          tabId: tab.id,
+        };
+        this.emitError(refreshError);
+        void this.requestShutdown(refreshError).catch((shutdownError) => {
+          this.emitError({
+            code: 'screencast_refresh_shutdown_failed',
+            message: normalizeErrorMessage(shutdownError),
+            fatal: true,
+            tabId: tab.id,
+          });
+        });
+        throw error;
+      } finally {
+        if (timeout) clearTimeout(timeout);
+        firstFrame?.cancel();
+      }
+    }, operationOptions);
+  }
+
   public async createTab(
     optionsArg: ILiveBrowserCreateTabOptions = {},
     operationOptions: ILiveBrowserOperationOptions = {},
@@ -1747,15 +1851,30 @@ export class LiveBrowserSession {
       this.emitState();
     }
     const shutdownError = new Error('LiveBrowserSession is stopping');
-    if (
-      abortActiveOperation
-      && this.activeOperation
-      && this.activeOperation.kind !== 'shutdown'
-    ) {
-      this.activeOperation.controller.abort(shutdownError);
+    for (const tab of this.tabs.values()) {
+      this.invalidateScreencast(tab, shutdownError);
     }
-    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
-      this.browserLifetimeController.abort(shutdownError);
+    const activeOperation = this.activeOperation;
+    const shouldAbortActiveOperation = Boolean(
+      abortActiveOperation
+      && activeOperation
+      && activeOperation.kind !== 'shutdown'
+    );
+    if (shouldAbortActiveOperation && activeOperation) {
+      const browserLifetimeController = this.browserLifetimeController;
+      const frameDrainPromise = (async () => {
+        try {
+          await this.retireOutstandingFrames(() => true);
+          await this.waitForCdpFrameAcknowledgements();
+        } finally {
+          if (browserLifetimeController && !browserLifetimeController.signal.aborted) {
+            browserLifetimeController.abort(shutdownError);
+          }
+        }
+      })();
+      this.shutdownFrameDrainPromise = frameDrainPromise;
+      void frameDrainPromise.catch(() => {});
+      activeOperation.controller.abort(shutdownError);
     }
     this.cancelQueuedOperations(shutdownError);
   }
@@ -2126,10 +2245,6 @@ export class LiveBrowserSession {
       this.lastError = { ...error };
     }
     this.emitState();
-    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
-      this.browserLifetimeController.abort(new Error('LiveBrowserSession is stopping'));
-    }
-
     const browser = this.browser;
     if (browser && this.browserTargetCreatedListener) {
       browser.off('targetcreated', this.browserTargetCreatedListener);
@@ -2141,6 +2256,15 @@ export class LiveBrowserSession {
     this.browserDisconnectedListener = undefined;
 
     const shutdownErrors: unknown[] = [];
+    const shutdownFrameDrainPromise = this.shutdownFrameDrainPromise;
+    this.shutdownFrameDrainPromise = undefined;
+    if (shutdownFrameDrainPromise) {
+      try {
+        await shutdownFrameDrainPromise;
+      } catch (cleanupError) {
+        shutdownErrors.push(cleanupError);
+      }
+    }
     try {
       await this.teardownProxySecurity();
     } catch (cleanupError) {
@@ -2173,6 +2297,10 @@ export class LiveBrowserSession {
     } catch (cleanupError) {
       shutdownErrors.push(cleanupError);
     }
+    await this.waitForCdpFrameAcknowledgements();
+    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
+      this.browserLifetimeController.abort(new Error('LiveBrowserSession is stopping'));
+    }
 
     if (browser) {
       try {
@@ -2794,6 +2922,7 @@ export class LiveBrowserSession {
       appliedViewportRevision: 0,
       streaming: false,
       streamInvalidated: true,
+      streamLifecycleRevision: 0,
       navigationInProgress: false,
       closing: false,
       stateUpdateQueued: false,
@@ -2874,7 +3003,7 @@ export class LiveBrowserSession {
         tab.evaluationExecutionContextId = undefined;
         const navigationReset = !tab.navigationInProgress;
         if (navigationReset) {
-          tab.streamInvalidated = true;
+          this.invalidateScreencast(tab, new Error('Page navigation invalidated the screencast'));
           this.retireFramesForTabInBackground(tab.id);
         }
         this.requestTabStateUpdate(tab, navigationReset);
@@ -2883,7 +3012,7 @@ export class LiveBrowserSession {
         this.requestTabStateUpdate(tab, false);
       };
       const onClose = (): void => {
-        tab.streamInvalidated = true;
+        this.invalidateScreencast(tab, new Error('Page closure invalidated the screencast'));
         this.retireFramesForTabInBackground(tab.id);
         if (tab.closing || this.normalStopRequested) {
           return;
@@ -2893,7 +3022,7 @@ export class LiveBrowserSession {
         }, 'page_close_cleanup_failed', tab.id, true);
       };
       const onCrash = (error: Error): void => {
-        tab.streamInvalidated = true;
+        this.invalidateScreencast(tab, error);
         this.retireFramesForTabInBackground(tab.id);
         if (tab.closing || this.normalStopRequested) {
           return;
@@ -3256,7 +3385,10 @@ export class LiveBrowserSession {
     }
   }
 
-  private async startScreencast(tab: IPrivateLiveBrowserTab): Promise<void> {
+  private async startScreencast(
+    tab: IPrivateLiveBrowserTab,
+    authorityArg?: IScreencastAuthority,
+  ): Promise<void> {
     if (
       this.status !== 'running'
       || this.activeTabId !== tab.id
@@ -3267,78 +3399,254 @@ export class LiveBrowserSession {
       return;
     }
 
-    await this.ensureTabViewport(tab);
+    const authority = authorityArg
+      ?? this.createScreencastAuthority(tab, tab.streamLifecycleRevision);
+    let cdpSession: plugins.puppeteer.CDPSession | undefined;
+    let cdpConnection: plugins.puppeteer.Connection | undefined;
+    let frameListener: TScreencastFrameListener | undefined;
+    let cdpSessionDetachedListener: TCdpSessionDetachedListener | undefined;
+    try {
+      this.assertScreencastAuthority(tab, authority);
+      await this.waitForScreencastAuthority(this.ensureTabViewport(tab), authority);
+      this.assertScreencastAuthority(tab, authority);
 
-    const cdpSession = await tab.page.createCDPSession();
-    this.allowOperationalCdpSessionDetach(cdpSession);
-    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'),
+      const cdpSessionPromise = tab.page.createCDPSession();
+      void cdpSessionPromise.then(async (createdSession) => {
+        if (
+          tab.screencastAuthority === authority
+          && !authority.controller.signal.aborted
+        ) {
+          return;
+        }
+        this.allowOperationalCdpSessionDetach(createdSession);
+        if (!createdSession.detached) {
+          try {
+            await createdSession.detach();
+          } catch {
+            // Browser shutdown may detach a late-created session first.
+          }
+        }
+      }).catch(() => {});
+      cdpSession = await this.waitForScreencastAuthority(cdpSessionPromise, authority);
+      this.allowOperationalCdpSessionDetach(cdpSession);
+      this.assertScreencastAuthority(tab, authority);
+      const generation = tab.generation + 1;
+      frameListener = (event) => {
+        this.handleScreencastFrame(tab, cdpSession!, generation, event);
+      };
+      cdpConnection = cdpSession.connection();
+      cdpSessionDetachedListener = (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,
       );
-    };
-    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,
-      });
+      const format = this.options.screencast?.format ?? 'jpeg';
+      await this.waitForScreencastAuthority(
+        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,
+        }),
+        authority,
+      );
+      this.assertScreencastAuthority(tab, authority);
       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.
+      if (tab.cdpSession === cdpSession) {
+        tab.streaming = false;
+        tab.cdpSession = undefined;
+        tab.cdpConnection = undefined;
+        tab.screencastFrameListener = undefined;
+        tab.cdpSessionDetachedListener = undefined;
+      }
+      if (tab.screencastAuthority === authority) {
+        this.invalidateScreencast(tab, error);
+      }
+      if (cdpSession) {
+        if (frameListener) {
+          cdpSession.off('Page.screencastFrame', frameListener);
+        }
+        if (cdpConnection && cdpSessionDetachedListener) {
+          cdpConnection.off(
+            plugins.puppeteer.CDPSessionEvent.SessionDetached,
+            cdpSessionDetachedListener,
+          );
+        }
+        await this.retireOutstandingFrames((frame) => frame.cdpSession === cdpSession);
+        await this.waitForCdpFrameAcknowledgements(cdpSession);
+        if (!cdpSession.detached) {
+          try {
+            await cdpSession.detach();
+          } catch {
+            // The target may have closed while screencast startup was failing.
+          }
         }
       }
       throw error;
     }
   }
 
+  private canRestoreScreencast(tab: IPrivateLiveBrowserTab): boolean {
+    return this.status === 'running'
+      && !this.normalStopRequested
+      && this.activeTabId === tab.id
+      && this.tabs.get(tab.id) === tab
+      && tab.status === 'open'
+      && !tab.closing
+      && !tab.page.isClosed();
+  }
+
+  private createScreencastAuthority(
+    tab: IPrivateLiveBrowserTab,
+    expectedLifecycleRevision: number,
+  ): IScreencastAuthority {
+    if (
+      !this.canRestoreScreencast(tab)
+      || tab.streaming
+      || tab.streamLifecycleRevision !== expectedLifecycleRevision
+    ) {
+      throw new Error(`Screencast lifecycle authority is unavailable for tab: ${tab.id}`);
+    }
+    const authority: IScreencastAuthority = {
+      revision: expectedLifecycleRevision,
+      controller: new AbortController(),
+    };
+    tab.screencastAuthority = authority;
+    return authority;
+  }
+
+  private assertScreencastAuthority(
+    tab: IPrivateLiveBrowserTab,
+    authority: IScreencastAuthority,
+  ): void {
+    if (
+      this.canRestoreScreencast(tab)
+      && tab.streamLifecycleRevision === authority.revision
+      && tab.screencastAuthority === authority
+      && !authority.controller.signal.aborted
+    ) {
+      return;
+    }
+    throw authority.controller.signal.aborted
+      ? normalizeAbortReason(authority.controller.signal)
+      : new Error(`Screencast lifecycle authority was revoked for tab: ${tab.id}`);
+  }
+
+  private waitForScreencastAuthority<T>(
+    operation: Promise<T>,
+    authority: IScreencastAuthority,
+  ): Promise<T> {
+    const signal = authority.controller.signal;
+    if (signal.aborted) {
+      return Promise.reject(normalizeAbortReason(signal));
+    }
+    return new Promise<T>((resolve, reject) => {
+      let settled = false;
+      const finish = (actionArg: () => void): void => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener('abort', handleAbort);
+        actionArg();
+      };
+      const handleAbort = (): void => {
+        finish(() => reject(normalizeAbortReason(signal)));
+      };
+      signal.addEventListener('abort', handleAbort, { once: true });
+      operation.then(
+        (value) => finish(() => resolve(value)),
+        (error) => finish(() => reject(error)),
+      );
+      if (signal.aborted) handleAbort();
+    });
+  }
+
+  private invalidateScreencast(tab: IPrivateLiveBrowserTab, reason: unknown): void {
+    tab.streamInvalidated = true;
+    tab.streamLifecycleRevision += 1;
+    const authority = tab.screencastAuthority;
+    tab.screencastAuthority = undefined;
+    if (authority && !authority.controller.signal.aborted) {
+      authority.controller.abort(reason);
+    }
+  }
+
+  private waitForScreencastFrame(
+    tab: IPrivateLiveBrowserTab,
+    generation: number,
+    viewportRevision: number,
+    invalidationSignal: AbortSignal,
+  ): {
+    promise: Promise<ILiveBrowserFrameIdentity>;
+    cancel: () => void;
+  } {
+    let settled = false;
+    let resolvePromise!: (identityArg: ILiveBrowserFrameIdentity) => void;
+    let rejectPromise!: (errorArg: unknown) => void;
+    const promise = new Promise<ILiveBrowserFrameIdentity>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    void promise.catch(() => {});
+    let unsubscribe: () => void = () => {};
+    const finish = (actionArg: () => void) => {
+      if (settled) return;
+      settled = true;
+      invalidationSignal.removeEventListener('abort', handleAbort);
+      unsubscribe();
+      actionArg();
+    };
+    const handleAbort = () => {
+      finish(() => rejectPromise(normalizeAbortReason(invalidationSignal)));
+    };
+    unsubscribe = this.onEvent((eventArg) => {
+      if (
+        eventArg.type !== 'frame'
+        || eventArg.frame.tabId !== tab.id
+        || eventArg.frame.generation !== generation
+        || eventArg.frame.viewportRevision !== viewportRevision
+      ) return;
+      finish(() => resolvePromise({
+        tabId: eventArg.frame.tabId,
+        sequence: eventArg.frame.sequence,
+        generation: eventArg.frame.generation,
+        viewportRevision: eventArg.frame.viewportRevision,
+      }));
+    });
+    invalidationSignal.addEventListener('abort', handleAbort, { once: true });
+    if (invalidationSignal.aborted) handleAbort();
+    return {
+      promise,
+      cancel: () => finish(() => rejectPromise(new Error('Screencast frame wait was cancelled'))),
+    };
+  }
+
   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;
+    this.invalidateScreencast(tab, new Error('Screencast stopped'));
     tab.cdpSession = undefined;
     tab.cdpConnection = undefined;
     tab.screencastFrameListener = undefined;
@@ -3365,6 +3673,7 @@ export class LiveBrowserSession {
         cdpSessionDetachedListener,
       );
     }
+    await this.waitForCdpFrameAcknowledgements(cdpSession);
     if (!cdpSession.detached) {
       try {
         await cdpSession.detach();
@@ -3409,12 +3718,13 @@ export class LiveBrowserSession {
     const sequence = ++this.frameSequence;
     const outstandingFrame: IOutstandingFrame = {
       tabId: tab.id,
+      sequence,
       generation,
       viewportRevision: this.viewportRevision,
       cdpSessionId: event.sessionId,
       cdpSession,
     };
-    while (this.outstandingFrames.size >= maxOutstandingFrames) {
+    while (this.outstandingFrames.size >= this.maxOutstandingFrames) {
       const oldestFrameEntry = this.outstandingFrames.entries().next().value as
         | [number, IOutstandingFrame]
         | undefined;
@@ -3450,31 +3760,40 @@ export class LiveBrowserSession {
     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;
+  private acknowledgeCdpFrame(frame: ICdpScreencastFrame): Promise<boolean> {
+    if (frame.acknowledgementPromise) {
+      return frame.acknowledgementPromise;
     }
-    try {
+    let resolveAcknowledgement!: (accepted: boolean) => void;
+    const acknowledgementPromise = new Promise<boolean>((resolve) => {
+      resolveAcknowledgement = resolve;
+    });
+    frame.acknowledgementPromise = acknowledgementPromise;
+    this.cdpFramesBeingAcknowledged.add(frame);
+    void (async (): Promise<boolean> => {
+      if (frame.cdpSession.detached) {
+        throw new Error('CDP session detached before frame acknowledgement');
+      }
       await frame.cdpSession.send('Page.screencastFrameAck', {
         sessionId: frame.cdpSessionId,
-      });
+      }, { timeout: frameAcknowledgementTimeoutMs });
       return true;
-    } catch (error) {
+    })().then(resolveAcknowledgement, (error) => {
       this.handleFrameAcknowledgementFailure(frame, error);
-      return false;
-    }
+      resolveAcknowledgement(false);
+    });
+    void acknowledgementPromise.then(() => {
+      this.cdpFramesBeingAcknowledged.delete(frame);
+    });
+    return acknowledgementPromise;
   }
 
-  private acknowledgeCdpFrameInBackground(frame: IOutstandingFrame): void {
+  private acknowledgeCdpFrameInBackground(frame: ICdpScreencastFrame): void {
     void this.acknowledgeCdpFrame(frame);
   }
 
   private handleFrameAcknowledgementFailure(
-    frame: IOutstandingFrame,
+    frame: ICdpScreencastFrame,
     error: unknown,
   ): void {
     const tab = this.tabs.get(frame.tabId);
@@ -3514,6 +3833,15 @@ export class LiveBrowserSession {
     await Promise.all(acknowledgements);
   }
 
+  private async waitForCdpFrameAcknowledgements(
+    cdpSession?: plugins.puppeteer.CDPSession,
+  ): Promise<void> {
+    const acknowledgements = [...this.cdpFramesBeingAcknowledged]
+      .filter((frame) => !cdpSession || frame.cdpSession === cdpSession)
+      .map((frame) => frame.acknowledgementPromise!);
+    await Promise.all(acknowledgements);
+  }
+
   private handlePossibleCdpDisconnection(
     tab: IPrivateLiveBrowserTab,
     cdpSession: plugins.puppeteer.CDPSession,
@@ -3528,7 +3856,7 @@ export class LiveBrowserSession {
     ) {
       return;
     }
-    tab.streamInvalidated = true;
+    this.invalidateScreencast(tab, error);
     this.retireFramesForTabInBackground(tab.id);
     this.scheduleOperation(async () => {
       if (!this.tabs.has(tab.id) || tab.cdpSession !== cdpSession) {
@@ -3972,5 +4300,21 @@ export class LiveBrowserSession {
     if (options.everyNthFrame !== undefined) {
       validateInteger(options.everyNthFrame, 'screencast.everyNthFrame', 1, 100);
     }
+    if (options.maxOutstandingFrames !== undefined) {
+      validateInteger(
+        options.maxOutstandingFrames,
+        'screencast.maxOutstandingFrames',
+        1,
+        liveBrowserMaxOutstandingFrames,
+      );
+    }
+    if (options.firstFrameTimeoutMs !== undefined) {
+      validateInteger(
+        options.firstFrameTimeoutMs,
+        'screencast.firstFrameTimeoutMs',
+        100,
+        maxTimeoutMs,
+      );
+    }
   }
 }