@push.rocks/smartpuppeteer 2.6.0 → 2.7.0

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -33,6 +33,8 @@ import type {
   ILiveBrowserOperationOptions,
   ILiveBrowserPressOptions,
   ILiveBrowserProcessState,
+  ILiveBrowserScreencastOptions,
+  ILiveBrowserScreencastUpdateOptions,
   ILiveBrowserSessionOptions,
   ILiveBrowserSnapshot,
   ILiveBrowserSnapshotOptions,
@@ -64,6 +66,7 @@ const maxSelectorLength = 4096;
 const maxTextLength = 32768;
 const maxUrlLength = 16384;
 const maxTimeoutMs = 60000;
+const maxWheelDelta = 1000000;
 const frameAcknowledgementTimeoutMs = 5000;
 const defaultFirstFrameTimeoutMs = 5000;
 const maxQueuedPublicOperations = 64;
@@ -136,6 +139,34 @@ interface IScreencastAuthority {
   controller: AbortController;
 }
 
+interface IPendingWheelDispatch {
+  cdpSession: plugins.puppeteer.CDPSession;
+  generation: number;
+  viewportRevision: number;
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+  modifiers: number;
+  promise: Promise<void>;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+}
+
+interface IQueuedWheelInput {
+  kind: 'wheel';
+  dispatch: IPendingWheelDispatch;
+}
+
+interface IQueuedEventInput {
+  kind: 'event';
+  send: () => Promise<void>;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+}
+
+type TQueuedTabInput = IQueuedWheelInput | IQueuedEventInput;
+
 interface IPrivateLiveBrowserTab {
   id: string;
   page: plugins.puppeteer.Page;
@@ -160,6 +191,9 @@ interface IPrivateLiveBrowserTab {
   cdpConnection?: plugins.puppeteer.Connection;
   screencastFrameListener?: TScreencastFrameListener;
   cdpSessionDetachedListener?: TCdpSessionDetachedListener;
+  inputQueue: TQueuedTabInput[];
+  inputPumpActive: boolean;
+  wheelDispatchInFlight?: Promise<void>;
   removeListeners: Array<() => void>;
 }
 
@@ -386,6 +420,80 @@ const createPuppeteerViewport = (
   hasTouch: false,
 });
 
+const validateScreencastOptions = (
+  options: ILiveBrowserScreencastOptions | undefined,
+): void => {
+  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);
+  }
+  if (options.maxOutstandingFrames !== undefined) {
+    validateInteger(
+      options.maxOutstandingFrames,
+      'screencast.maxOutstandingFrames',
+      1,
+      liveBrowserMaxOutstandingFrames,
+    );
+  }
+  if (options.firstFrameTimeoutMs !== undefined) {
+    validateInteger(
+      options.firstFrameTimeoutMs,
+      'screencast.firstFrameTimeoutMs',
+      100,
+      maxTimeoutMs,
+    );
+  }
+};
+
+const screencastUpdateKeys = ['quality', 'maxWidth', 'maxHeight', 'everyNthFrame'] as const;
+
+const normalizeScreencastUpdate = (
+  optionsArg: ILiveBrowserScreencastUpdateOptions,
+): ILiveBrowserScreencastUpdateOptions => {
+  if (!optionsArg || typeof optionsArg !== 'object' || Array.isArray(optionsArg)) {
+    throw new Error('screencast update options must be an object');
+  }
+  const update: ILiveBrowserScreencastUpdateOptions = {};
+  for (const key of Object.keys(optionsArg)) {
+    if (!(screencastUpdateKeys as readonly string[]).includes(key)) {
+      throw new Error(`Unknown screencast update option: ${key}`);
+    }
+    const value = optionsArg[key as keyof ILiveBrowserScreencastUpdateOptions];
+    if (value !== undefined) {
+      update[key as keyof ILiveBrowserScreencastUpdateOptions] = value;
+    }
+  }
+  validateScreencastOptions(update);
+  return update;
+};
+
+const clampWheelDelta = (value: number): number => {
+  return Math.max(-maxWheelDelta, Math.min(maxWheelDelta, value));
+};
+
 export class LiveBrowserSession {
   private readonly options: ILiveBrowserSessionOptions;
   private readonly eventListeners = new Set<TLiveBrowserEventListener>();
@@ -524,7 +632,7 @@ export class LiveBrowserSession {
         : undefined,
     };
     this.viewport = { ...viewport };
-    this.validateScreencastOptions();
+    validateScreencastOptions(this.options.screencast);
     this.maxOutstandingFrames = this.options.screencast?.maxOutstandingFrames
       ?? liveBrowserDefaultMaxOutstandingFrames;
   }
@@ -855,58 +963,95 @@ export class LiveBrowserSession {
   public refreshScreencast(
     operationOptions: ILiveBrowserOperationOptions = {},
   ): Promise<ILiveBrowserFrameIdentity> {
+    return this.enqueuePublicOperation(
+      (signal) => this.restartActiveScreencast(signal),
+      operationOptions,
+    );
+  }
+
+  public async updateScreencastOptions(
+    optionsArg: ILiveBrowserScreencastUpdateOptions,
+    operationOptions: ILiveBrowserOperationOptions = {},
+  ): Promise<ILiveBrowserFrameIdentity | null> {
+    const update = normalizeScreencastUpdate(optionsArg);
     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}`);
+      const screencast: ILiveBrowserScreencastOptions = {
+        ...this.options.screencast,
+        ...update,
+      };
+      validateScreencastOptions(screencast);
+      this.options.screencast = screencast;
+      const activeTab = this.status === 'running' && this.activeTabId
+        ? this.tabs.get(this.activeTabId)
+        : undefined;
+      if (!activeTab?.streaming) {
+        return null;
       }
-      let firstFrame: ReturnType<LiveBrowserSession['waitForScreencastFrame']> | undefined;
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-      try {
-        const previousLifecycleRevision = tab.streamLifecycleRevision;
+      return this.restartActiveScreencast(signal);
+    }, operationOptions);
+  }
+
+  private async restartActiveScreencast(
+    signal: AbortSignal,
+  ): Promise<ILiveBrowserFrameIdentity> {
+    signal.throwIfAborted();
+    const tab = this.requireActiveTab();
+    let firstFrame: ReturnType<LiveBrowserSession['waitForScreencastFrame']> | undefined;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let restartPromise: Promise<void> | undefined;
+    try {
+      let refreshLifecycleRevision = tab.streamLifecycleRevision;
+      if (tab.streaming) {
         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);
+        refreshLifecycleRevision += 1;
+      }
+      if (
+        !this.canRestoreScreencast(tab)
+        || tab.streaming
+        || 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);
+      });
+      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;
+      await this.abandonScreencastRestart(tab, restartPromise, error);
+      // Browser loss is the only refresh failure that is not tab-recoverable; the
+      // disconnect listener normally revokes restoration first, so this stays a guard.
+      const fatal = this.browser !== undefined && !this.browser.connected;
+      const refreshError: ILiveBrowserError = {
+        code: 'screencast_refresh_failed',
+        message: normalizeErrorMessage(error),
+        fatal,
+        tabId: tab.id,
+      };
+      this.emitError(refreshError);
+      if (fatal) {
         void this.requestShutdown(refreshError).catch((shutdownError) => {
           this.emitError({
             code: 'screencast_refresh_shutdown_failed',
@@ -915,12 +1060,27 @@ export class LiveBrowserSession {
             tabId: tab.id,
           });
         });
-        throw error;
-      } finally {
-        if (timeout) clearTimeout(timeout);
-        firstFrame?.cancel();
       }
-    }, operationOptions);
+      throw error;
+    } finally {
+      if (timeout) clearTimeout(timeout);
+      firstFrame?.cancel();
+    }
+  }
+
+  private async abandonScreencastRestart(
+    tab: IPrivateLiveBrowserTab,
+    restartPromise: Promise<void> | undefined,
+    reason: unknown,
+  ): Promise<void> {
+    // Revoke the restart authority so an in-flight startScreencast() unwinds, then
+    // retire anything it already established. The tab stays open and invalidated so
+    // a later refresh, viewport change, or activation can start a new generation.
+    this.invalidateScreencast(tab, reason);
+    if (restartPromise) {
+      await restartPromise.catch(() => {});
+    }
+    await this.stopScreencast(tab);
   }
 
   public async createTab(
@@ -1150,43 +1310,73 @@ export class LiveBrowserSession {
     const clickCount = input.clickCount === undefined
       ? undefined
       : validateInteger(input.clickCount, 'clickCount', 0, 3);
+    const modifiers = this.createModifierMask(input.modifiers);
 
-    try {
-      await cdpSession.send('Input.dispatchMouseEvent', {
+    await this.dispatchTabInput(tab, cdpSession, () => cdpSession.send(
+      'Input.dispatchMouseEvent',
+      {
         type,
         x: input.x,
         y: input.y,
         button,
         buttons,
         clickCount,
-        modifiers: this.createModifierMask(input.modifiers),
+        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',
+    const deltaX = validateFiniteNumber(input.deltaX, 'deltaX', -maxWheelDelta, maxWheelDelta);
+    const deltaY = validateFiniteNumber(input.deltaY, 'deltaY', -maxWheelDelta, maxWheelDelta);
+    const modifiers = this.createModifierMask(input.modifiers);
+
+    // Queued input only waits while an earlier wheel dispatch is in flight; wheel
+    // input for the same stream merges into a wheel entry still waiting at the tail.
+    const lastQueuedInput = tab.inputQueue[tab.inputQueue.length - 1];
+    if (
+      lastQueuedInput?.kind === 'wheel'
+      && lastQueuedInput.dispatch.cdpSession === cdpSession
+      && lastQueuedInput.dispatch.generation === input.generation
+      && lastQueuedInput.dispatch.viewportRevision === input.viewportRevision
+    ) {
+      const pendingDispatch = lastQueuedInput.dispatch;
+      pendingDispatch.x = input.x;
+      pendingDispatch.y = input.y;
+      pendingDispatch.deltaX = clampWheelDelta(pendingDispatch.deltaX + deltaX);
+      pendingDispatch.deltaY = clampWheelDelta(pendingDispatch.deltaY + deltaY);
+      pendingDispatch.modifiers = modifiers;
+      return pendingDispatch.promise;
+    }
+
+    let resolveDispatch!: () => void;
+    let rejectDispatch!: (error: unknown) => void;
+    const promise = new Promise<void>((resolve, reject) => {
+      resolveDispatch = resolve;
+      rejectDispatch = reject;
+    });
+    void promise.catch(() => {});
+    tab.inputQueue.push({
+      kind: 'wheel',
+      dispatch: {
+        cdpSession,
+        generation: input.generation,
+        viewportRevision: input.viewportRevision,
         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;
-    }
+        deltaX,
+        deltaY,
+        modifiers,
+        promise,
+        resolve: resolveDispatch,
+        reject: rejectDispatch,
+      },
+    });
+    this.pumpTabInput(tab);
+    return promise;
   }
 
   public async dispatchKey(input: ILiveBrowserKeyInput): Promise<void> {
@@ -1220,9 +1410,11 @@ export class LiveBrowserSession {
       : validateInteger(input.location, 'location', 0, 3);
     validateOptionalBoolean(input.autoRepeat, 'autoRepeat');
     validateOptionalBoolean(input.isKeypad, 'isKeypad');
+    const modifiers = this.createModifierMask(input.modifiers);
 
-    try {
-      await cdpSession.send('Input.dispatchKeyEvent', {
+    await this.dispatchTabInput(tab, cdpSession, () => cdpSession.send(
+      'Input.dispatchKeyEvent',
+      {
         type,
         key,
         code,
@@ -1233,22 +1425,97 @@ export class LiveBrowserSession {
         autoRepeat: input.autoRepeat,
         isKeypad: input.isKeypad,
         location,
-        modifiers: this.createModifierMask(input.modifiers),
-      });
-    } catch (error) {
-      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
-      throw error;
-    }
+        modifiers,
+      },
+    ));
   }
 
   public async insertText(input: ILiveBrowserInsertTextInput): Promise<void> {
     const { tab, cdpSession } = this.requireRawInputTarget(input);
     const text = validateBoundedString(input.text, 'text', 0, maxTextLength);
+    await this.dispatchTabInput(tab, cdpSession, () => cdpSession.send(
+      'Input.insertText',
+      { text },
+    ));
+  }
+
+  private dispatchTabInput(
+    tab: IPrivateLiveBrowserTab,
+    cdpSession: plugins.puppeteer.CDPSession,
+    send: () => Promise<unknown>,
+  ): Promise<void> {
+    const guardedSend = async (): Promise<void> => {
+      try {
+        await send();
+      } catch (error) {
+        this.handlePossibleCdpDisconnection(tab, cdpSession, error);
+        throw error;
+      }
+    };
+    // Chromium does not keep a pipelined mouse or key event behind an earlier wheel
+    // command, so any input behind wheel input waits until that wheel dispatch settles.
+    if (tab.inputQueue.length === 0 && !tab.wheelDispatchInFlight) {
+      return guardedSend();
+    }
+    return new Promise<void>((resolve, reject) => {
+      tab.inputQueue.push({ kind: 'event', send: guardedSend, resolve, reject });
+      this.pumpTabInput(tab);
+    });
+  }
+
+  private pumpTabInput(tab: IPrivateLiveBrowserTab): void {
+    if (tab.inputPumpActive) {
+      return;
+    }
+    tab.inputPumpActive = true;
+    void (async () => {
+      try {
+        while (tab.inputQueue.length > 0) {
+          const wheelDispatchInFlight = tab.wheelDispatchInFlight;
+          if (wheelDispatchInFlight) {
+            await wheelDispatchInFlight;
+            if (tab.wheelDispatchInFlight === wheelDispatchInFlight) {
+              tab.wheelDispatchInFlight = undefined;
+            }
+            continue;
+          }
+          const nextInput = tab.inputQueue.shift()!;
+          if (nextInput.kind === 'wheel') {
+            const inFlight = this.performWheelDispatch(tab, nextInput.dispatch);
+            tab.wheelDispatchInFlight = inFlight;
+            void inFlight.then(() => {
+              if (tab.wheelDispatchInFlight === inFlight) {
+                tab.wheelDispatchInFlight = undefined;
+              }
+            });
+          } else {
+            nextInput.send().then(nextInput.resolve, nextInput.reject);
+          }
+        }
+      } finally {
+        tab.inputPumpActive = false;
+      }
+    })();
+  }
+
+  private async performWheelDispatch(
+    tab: IPrivateLiveBrowserTab,
+    dispatch: IPendingWheelDispatch,
+  ): Promise<void> {
     try {
-      await cdpSession.send('Input.insertText', { text });
+      await dispatch.cdpSession.send('Input.dispatchMouseEvent', {
+        type: 'mouseWheel',
+        x: dispatch.x,
+        y: dispatch.y,
+        deltaX: dispatch.deltaX,
+        deltaY: dispatch.deltaY,
+        modifiers: dispatch.modifiers,
+        pointerType: 'mouse',
+      });
+      dispatch.resolve();
     } catch (error) {
-      this.handlePossibleCdpDisconnection(tab, cdpSession, error);
-      throw error;
+      this.handlePossibleCdpDisconnection(tab, dispatch.cdpSession, error);
+      dispatch.reject(error);
     }
   }
 
@@ -3349,6 +3616,8 @@ export class LiveBrowserSession {
       stateUpdatePending: false,
       navigationResetRevision: 0,
       restoredNavigationRevision: 0,
+      inputQueue: [],
+      inputPumpActive: false,
       removeListeners: [],
     };
     this.tabs.set(tab.id, tab);
@@ -4739,50 +5008,4 @@ export class LiveBrowserSession {
     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);
-    }
-    if (options.maxOutstandingFrames !== undefined) {
-      validateInteger(
-        options.maxOutstandingFrames,
-        'screencast.maxOutstandingFrames',
-        1,
-        liveBrowserMaxOutstandingFrames,
-      );
-    }
-    if (options.firstFrameTimeoutMs !== undefined) {
-      validateInteger(
-        options.firstFrameTimeoutMs,
-        'screencast.firstFrameTimeoutMs',
-        100,
-        maxTimeoutMs,
-      );
-    }
-  }
 }

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -28,6 +28,12 @@ export interface ILiveBrowserScreencastOptions {
   firstFrameTimeoutMs?: number;
 }
 
+export interface ILiveBrowserScreencastUpdateOptions
+  extends Pick<
+    ILiveBrowserScreencastOptions,
+    'quality' | 'maxWidth' | 'maxHeight' | 'everyNthFrame'
+  > {}
+
 export interface ILiveBrowserSecurityOptions {
   denyDownloads?: boolean;
   denyFileChoosers?: boolean;