@push.rocks/smartpuppeteer 2.4.0 → 2.5.0

package/dist_ts/smartpuppeteer.interfaces.livebrowser.d.ts

@@ -17,6 +17,7 @@ export interface ILiveBrowserScreencastOptions {
     maxHeight?: number;
     everyNthFrame?: number;
     maxOutstandingFrames?: number;
+    firstFrameTimeoutMs?: number;
 }
 export interface ILiveBrowserSecurityOptions {
     denyDownloads?: boolean;
@@ -117,6 +118,12 @@ export interface ILiveBrowserFrame {
     metadata: ILiveBrowserScreencastMetadata;
     data: Uint8Array;
 }
+export interface ILiveBrowserFrameIdentity {
+    tabId: string;
+    sequence: number;
+    generation: number;
+    viewportRevision: number;
+}
 export interface ILiveBrowserSnapshot {
     tabId: string;
     viewportRevision: number;
@@ -144,11 +151,7 @@ export type TLiveBrowserEventListener = (event: TLiveBrowserEvent) => void;
 export interface ILiveBrowserFrameAcknowledgement {
     accepted: boolean;
 }
-export interface ILiveBrowserFrameAcknowledgementRequest {
-    tabId: string;
-    sequence: number;
-    generation: number;
-    viewportRevision: number;
+export interface ILiveBrowserFrameAcknowledgementRequest extends ILiveBrowserFrameIdentity {
 }
 export interface ILiveBrowserCreateTabOptions {
     url?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartpuppeteer",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "private": false,
   "description": "Provides simplified access to Puppeteer for automation and testing purposes.",
   "main": "dist_ts/index.js",

package/readme.hints.md

@@ -4,6 +4,7 @@
 - `LiveBrowserSession` uses the browser's default context so all tabs and popups share one profile. Omitting both `launchOptions.userDataDir` and a `--user-data-dir` argument intentionally relies on Puppeteer's ephemeral profile lifecycle.
 - CDP is private to the live runtime. Public contracts contain transport-neutral values and `Uint8Array` image data, never `CDPSession`, raw CDP frame IDs, or base64 image strings.
 - Every published screencast frame has one private sequence-to-CDP acknowledgement entry. Public acknowledgement requires matching tab ID, sequence, generation, and viewport revision. `screencast.maxOutstandingFrames` bounds those entries independently of any application transport window; overflow retires oldest-first. Drops and all stream invalidation paths must issue each CDP acknowledgement at most once and await in-flight acknowledgements before detaching the CDP session.
+- `refreshScreencast()` installs its exact-generation waiter before starting CDP, retires the previous stream, and resolves only after the first validated frame is published. Pre-aborted and queued calls reject without changing the stream. Active caller cancellation settles only after restorative restart; shutdown, tab replacement, crash, or closure revokes restart authority and must never resurrect the stream.
 - Activation, viewport changes, navigation, tab closure, snapshots, observations, semantic actions, and shutdown share one bounded operation scheduler. Raw input and frame acknowledgement remain direct, but must validate active tab, generation, and viewport revision. Repeated internal navigation/load state updates are coalesced per tab, and shutdown cancels queued work.
 - Retain the scheduler-owned launch `AbortController` for the full browser lifetime. Shutdown aborts both the active operation and Chromium itself so a non-signal-aware Puppeteer command or disabled protocol timeout cannot retain the browser ahead of queued cleanup.
 - Viewport revision starts at 1 and advances only after `Page.setViewport()` succeeds. Stop and flush the active screencast before applying a viewport or navigation mutation, then restart it with a new generation.

package/readme.md

@@ -122,6 +122,7 @@ const session = new LiveBrowserSession({
     maxHeight: 720,
     everyNthFrame: 1,
     maxOutstandingFrames: 3,
+    firstFrameTimeoutMs: 5000,
   },
   launchOptions: {
     headless: true,
@@ -172,11 +173,11 @@ try {
 
 Only the active tab is streamed. Frames carry a session-monotonic sequence, tab/CDP generation, viewport revision, viewport, MIME type, encoded dimensions, screencast metadata, and binary `Uint8Array` data. Every delivered frame must be acknowledged with all four identity fields. A delivered frame remains pending until it is acknowledged, dropped, or retired by the runtime; mismatched, duplicate, stale, retired, or operationally failed acknowledgements return `{ accepted: false }`. Operational acknowledgement failures also emit an `error` event whose code is `frame_acknowledgement_failed`. `screencast.maxOutstandingFrames` is an integer from 1 through `liveBrowserMaxOutstandingFrames` (64) and defaults to `liveBrowserDefaultMaxOutstandingFrames` (3). At capacity, SmartPuppeteer retires and CDP-acknowledges the oldest pending frame before publishing the next one. Tab switches, navigation, resize, page cleanup, disconnect, and shutdown also retire pending frames and await their single CDP acknowledgement attempt before detaching the screencast session.
 
-The SmartPuppeteer outstanding-frame bound covers only the private frame-to-`Page.screencastFrameAck` lifecycle. It is not a binary transport window, and `acknowledgeFrame()` is not an application transport acknowledgement. A higher-level runtime must maintain and bound its application frame window separately. Screencast `format` accepts `jpeg` or `png`, `quality` accepts integers from 0 through 100, `maxWidth` and `maxHeight` accept integers from 1 through 4096 subject to an 8,294,400-pixel combined ceiling, and `everyNthFrame` accepts integers from 1 through 100.
+The SmartPuppeteer outstanding-frame bound covers only the private frame-to-`Page.screencastFrameAck` lifecycle. It is not a binary transport window, and `acknowledgeFrame()` is not an application transport acknowledgement. A higher-level runtime must maintain and bound its application frame window separately. `refreshScreencast()` retires the active stream and resolves with an `ILiveBrowserFrameIdentity` for the exact first validated frame from a new generation. Its `tabId`, `sequence`, `generation`, and `viewportRevision` fields can be passed directly to `acknowledgeFrame()`. `screencast.firstFrameTimeoutMs` bounds both the CDP restart and first-frame arrival, accepts integers from 100 through 60,000, and defaults to 5,000; timeout or another refresh failure emits fatal `screencast_refresh_failed` and shuts the session down. Screencast `format` accepts `jpeg` or `png`, `quality` accepts integers from 0 through 100, `maxWidth` and `maxHeight` accept integers from 1 through 4096 subject to an 8,294,400-pixel combined ceiling, and `everyNthFrame` accepts integers from 1 through 100.
 
 The live API includes:
 
-- Lifecycle and state: `start()`, `stop()`, `terminate()`, `getProcessState()`, `onEvent()`, and `getState()`
+- Lifecycle and state: `start()`, `stop()`, `terminate()`, `refreshScreencast()`, `getProcessState()`, `onEvent()`, and `getState()`
 - Tabs and navigation: `createTab()`, `activateTab()`, `closeTab()`, `navigate()`, `back()`, `forward()`, and `reload()`
 - Viewport and raw input: `setViewport()`, `dispatchMouse()`, `dispatchWheel()`, `dispatchKey()`, and `insertText()`
 - Agent-oriented actions: `click()`, `fill()`, and `press()` with bounded selectors and timeouts
@@ -185,7 +186,7 @@ The live API includes:
 
 Coordinate, keyboard, text, and semantic input messages include `tabId`, `generation`, and `viewportRevision`. This rejects input derived from an old stream generation, resize, or tab state. Snapshot, observation, and semantic operations are serialized with lifecycle mutations; inactive tabs receive the current session viewport before use. `viewport` takes precedence over `launchOptions.defaultViewport`; `null` falls back to 800x600. The runtime canonicalizes every page to a desktop, non-touch viewport because mobile emulation flags are outside the public viewport contract. Viewport dimensions, device scale factor, and physical pixel area are bounded, and full-page snapshots are intentionally unsupported. CDP sessions and CDP frame identifiers remain private implementation details. `LiveBrowserSession` owns launch cancellation, so callers cannot supply `launchOptions.signal`. It supports only Chromium over CDP and rejects Firefox or WebDriver BiDi launch selections.
 
-`start()`, tab and navigation methods, `setViewport()`, `captureSnapshot()`, `observe()`, semantic actions, and `evaluate()` accept a trailing `{ signal }` operation argument. A pre-aborted operation is never admitted. An operation aborted while queued is removed immediately. An active operation receives cancellation when its Puppeteer or CDP primitive supports it; otherwise its promise rejects only after the underlying work settles, and it continues to occupy the serialized queue until then. Cancellation therefore does not promise that an already-started browser side effect did not occur. `stop()`, frame acknowledgement, event/state access, and direct raw input are intentionally not caller-cancellable.
+`start()`, `refreshScreencast()`, tab and navigation methods, `setViewport()`, `captureSnapshot()`, `observe()`, semantic actions, and `evaluate()` accept a trailing `{ signal }` operation argument. A pre-aborted operation is never admitted. An operation aborted while queued is removed immediately. An active operation receives cancellation when its Puppeteer or CDP primitive supports it; otherwise its promise rejects only after the underlying work settles, and it continues to occupy the serialized queue until then. An active `refreshScreencast()` completes the restorative restart before settling caller cancellation, unless session shutdown or page invalidation revokes that restart. Cancellation therefore does not promise that an already-started browser side effect did not occur. `stop()`, frame acknowledgement, event/state access, and direct raw input are intentionally not caller-cancellable.
 
 Optional browser guards can be enabled when composing a higher-level runtime:
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartpuppeteer',
-  version: '2.4.0',
+  version: '2.5.0',
   description: 'Provides simplified access to Puppeteer for automation and testing purposes.'
 }

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -21,6 +21,7 @@ import type {
   ILiveBrowserFrame,
   ILiveBrowserFrameAcknowledgement,
   ILiveBrowserFrameAcknowledgementRequest,
+  ILiveBrowserFrameIdentity,
   ILiveBrowserInsertTextInput,
   ILiveBrowserKeyInput,
   ILiveBrowserModifierState,
@@ -64,6 +65,7 @@ const maxTextLength = 32768;
 const maxUrlLength = 16384;
 const maxTimeoutMs = 60000;
 const frameAcknowledgementTimeoutMs = 5000;
+const defaultFirstFrameTimeoutMs = 5000;
 const maxQueuedPublicOperations = 64;
 const maxQueuedInternalOperations = 128;
 const maxEvaluationScriptBytes = 262144;
@@ -123,6 +125,11 @@ interface IOwnedBrowserProcess {
   forceSignalled: boolean;
 }
 
+interface IScreencastAuthority {
+  revision: number;
+  controller: AbortController;
+}
+
 interface IPrivateLiveBrowserTab {
   id: string;
   page: plugins.puppeteer.Page;
@@ -133,6 +140,8 @@ interface IPrivateLiveBrowserTab {
   appliedViewportRevision: number;
   streaming: boolean;
   streamInvalidated: boolean;
+  streamLifecycleRevision: number;
+  screencastAuthority?: IScreencastAuthority;
   navigationInProgress: boolean;
   closing: boolean;
   stateUpdateQueued: boolean;
@@ -826,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 = {},
@@ -1771,6 +1851,9 @@ export class LiveBrowserSession {
       this.emitState();
     }
     const shutdownError = new Error('LiveBrowserSession is stopping');
+    for (const tab of this.tabs.values()) {
+      this.invalidateScreencast(tab, shutdownError);
+    }
     const activeOperation = this.activeOperation;
     const shouldAbortActiveOperation = Boolean(
       abortActiveOperation
@@ -2839,6 +2922,7 @@ export class LiveBrowserSession {
       appliedViewportRevision: 0,
       streaming: false,
       streamInvalidated: true,
+      streamLifecycleRevision: 0,
       navigationInProgress: false,
       closing: false,
       stateUpdateQueued: false,
@@ -2919,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);
@@ -2928,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;
@@ -2938,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;
@@ -3301,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
@@ -3312,80 +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,
-      );
-      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.
+      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;
@@ -3595,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) {
@@ -4047,5 +4308,13 @@ export class LiveBrowserSession {
         liveBrowserMaxOutstandingFrames,
       );
     }
+    if (options.firstFrameTimeoutMs !== undefined) {
+      validateInteger(
+        options.firstFrameTimeoutMs,
+        'screencast.firstFrameTimeoutMs',
+        100,
+        maxTimeoutMs,
+      );
+    }
   }
 }

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -25,6 +25,7 @@ export interface ILiveBrowserScreencastOptions {
   maxHeight?: number;
   everyNthFrame?: number;
   maxOutstandingFrames?: number;
+  firstFrameTimeoutMs?: number;
 }
 
 export interface ILiveBrowserSecurityOptions {
@@ -148,6 +149,13 @@ export interface ILiveBrowserFrame {
   data: Uint8Array;
 }
 
+export interface ILiveBrowserFrameIdentity {
+  tabId: string;
+  sequence: number;
+  generation: number;
+  viewportRevision: number;
+}
+
 export interface ILiveBrowserSnapshot {
   tabId: string;
   viewportRevision: number;
@@ -185,12 +193,7 @@ export interface ILiveBrowserFrameAcknowledgement {
   accepted: boolean;
 }
 
-export interface ILiveBrowserFrameAcknowledgementRequest {
-  tabId: string;
-  sequence: number;
-  generation: number;
-  viewportRevision: number;
-}
+export interface ILiveBrowserFrameAcknowledgementRequest extends ILiveBrowserFrameIdentity {}
 
 export interface ILiveBrowserCreateTabOptions {
   url?: string;