@push.rocks/smartpuppeteer 2.3.0 → 2.4.0

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

@@ -3,6 +3,8 @@ export type TLiveBrowserStatus = 'stopped' | 'starting' | 'running' | 'stopping'
 export type TLiveBrowserImageFormat = 'jpeg' | 'png';
 export type TLiveBrowserTabStatus = 'open' | 'crashed';
 export type TLiveBrowserWaitUntil = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+export declare const liveBrowserDefaultMaxOutstandingFrames = 3;
+export declare const liveBrowserMaxOutstandingFrames = 64;
 export interface ILiveBrowserViewport {
     width: number;
     height: number;
@@ -14,6 +16,7 @@ export interface ILiveBrowserScreencastOptions {
     maxWidth?: number;
     maxHeight?: number;
     everyNthFrame?: number;
+    maxOutstandingFrames?: number;
 }
 export interface ILiveBrowserSecurityOptions {
     denyDownloads?: boolean;

package/dist_ts/smartpuppeteer.interfaces.livebrowser.js

@@ -1,2 +1,3 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuaW50ZXJmYWNlcy5saXZlYnJvd3Nlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmludGVyZmFjZXMubGl2ZWJyb3dzZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
+export const liveBrowserDefaultMaxOutstandingFrames = 3;
+export const liveBrowserMaxOutstandingFrames = 64;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuaW50ZXJmYWNlcy5saXZlYnJvd3Nlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmludGVyZmFjZXMubGl2ZWJyb3dzZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBV0EsTUFBTSxDQUFDLE1BQU0sc0NBQXNDLEdBQUcsQ0FBQyxDQUFDO0FBQ3hELE1BQU0sQ0FBQyxNQUFNLCtCQUErQixHQUFHLEVBQUUsQ0FBQyJ9

package/package.json

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

package/readme.hints.md

@@ -3,7 +3,7 @@
 - `getEnvAwareBrowserInstance()` is the only Chromium launch path. Merge caller arguments before adding environment-required sandbox arguments, retain the pipe default, and do not run executable discovery when the caller selected a browser, channel, or executable.
 - `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. Pending frames are bounded; drops and all stream invalidation paths must retire and acknowledge entries before detaching the CDP session.
+- 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.
 - 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

@@ -120,6 +120,8 @@ const session = new LiveBrowserSession({
     quality: 80,
     maxWidth: 1280,
     maxHeight: 720,
+    everyNthFrame: 1,
+    maxOutstandingFrames: 3,
   },
   launchOptions: {
     headless: true,
@@ -168,7 +170,9 @@ 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`. The runtime bounds pending frames and CDP-acknowledges an oldest frame when it must be dropped. Tab switches, navigation, resize, page cleanup, disconnect, and shutdown retire pending frames and acknowledge them while their CDP session remains available.
+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 live API includes:
 

package/ts/00_commitinfo_data.ts

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

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,
@@ -59,7 +63,7 @@ const maxSelectorLength = 4096;
 const maxTextLength = 32768;
 const maxUrlLength = 16384;
 const maxTimeoutMs = 60000;
-const maxOutstandingFrames = 3;
+const frameAcknowledgementTimeoutMs = 5000;
 const maxQueuedPublicOperations = 64;
 const maxQueuedInternalOperations = 128;
 const maxEvaluationScriptBytes = 262144;
@@ -143,12 +147,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 +376,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 +403,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 +430,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 +499,8 @@ export class LiveBrowserSession {
     };
     this.viewport = { ...viewport };
     this.validateScreencastOptions();
+    this.maxOutstandingFrames = this.options.screencast?.maxOutstandingFrames
+      ?? liveBrowserDefaultMaxOutstandingFrames;
   }
 
   public onEvent(listener: TLiveBrowserEventListener): () => void {
@@ -1747,15 +1771,27 @@ export class LiveBrowserSession {
       this.emitState();
     }
     const shutdownError = new Error('LiveBrowserSession is stopping');
-    if (
+    const activeOperation = this.activeOperation;
+    const shouldAbortActiveOperation = Boolean(
       abortActiveOperation
-      && this.activeOperation
-      && this.activeOperation.kind !== 'shutdown'
-    ) {
-      this.activeOperation.controller.abort(shutdownError);
-    }
-    if (this.browserLifetimeController && !this.browserLifetimeController.signal.aborted) {
-      this.browserLifetimeController.abort(shutdownError);
+      && 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 +2162,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 +2173,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 +2214,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 {
@@ -3321,6 +3366,8 @@ export class LiveBrowserSession {
         plugins.puppeteer.CDPSessionEvent.SessionDetached,
         cdpSessionDetachedListener,
       );
+      await this.retireOutstandingFrames((frame) => frame.cdpSession === cdpSession);
+      await this.waitForCdpFrameAcknowledgements(cdpSession);
       if (!cdpSession.detached) {
         try {
           await cdpSession.detach();
@@ -3365,6 +3412,7 @@ export class LiveBrowserSession {
         cdpSessionDetachedListener,
       );
     }
+    await this.waitForCdpFrameAcknowledgements(cdpSession);
     if (!cdpSession.detached) {
       try {
         await cdpSession.detach();
@@ -3409,12 +3457,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 +3499,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 +3572,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,
@@ -3972,5 +4039,13 @@ 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,
+      );
+    }
   }
 }

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -9,6 +9,9 @@ export type TLiveBrowserWaitUntil =
   | 'networkidle0'
   | 'networkidle2';
 
+export const liveBrowserDefaultMaxOutstandingFrames = 3;
+export const liveBrowserMaxOutstandingFrames = 64;
+
 export interface ILiveBrowserViewport {
   width: number;
   height: number;
@@ -21,6 +24,7 @@ export interface ILiveBrowserScreencastOptions {
   maxWidth?: number;
   maxHeight?: number;
   everyNthFrame?: number;
+  maxOutstandingFrames?: number;
 }
 
 export interface ILiveBrowserSecurityOptions {