@push.rocks/smartpuppeteer 2.7.0 → 2.8.1

package/ts/smartpuppeteer.classes.livebrowsersession.ts

@@ -1,4 +1,7 @@
 import { getEnvAwareBrowserInstance } from './smartpuppeteer.classes.smartpuppeteer.js';
+import { LiveBrowserVideo } from './classes.livevideo.js';
+import { normalizeLiveVideoOptions, type ILiveVideoDescription, type ILiveVideoOffer,
+  type ILiveVideoStatistics } from './interfaces.livevideo.js';
 import {
   liveBrowserDefaultMaxOutstandingFrames,
   liveBrowserMaxOutstandingFrames,
@@ -504,6 +507,8 @@ export class LiveBrowserSession {
   private readonly maxOutstandingFrames: number;
 
   private browser?: plugins.puppeteer.Browser;
+  private video?: LiveBrowserVideo;
+  private frameCaptureEnabled: boolean;
   private browserContext?: plugins.puppeteer.BrowserContext;
   private browserLifetimeController?: AbortController;
   private browserDisconnectedListener?: () => void;
@@ -549,6 +554,14 @@ export class LiveBrowserSession {
   private lastError?: ILiveBrowserError;
 
   constructor(optionsArg: ILiveBrowserSessionOptions = {}) {
+    validateOptionalBoolean(optionsArg.screencast?.enabled, 'screencast.enabled');
+    this.frameCaptureEnabled = optionsArg.screencast?.enabled ?? true;
+    if (optionsArg.video) {
+      normalizeLiveVideoOptions(optionsArg.video);
+      if (!(optionsArg.usePipe ?? optionsArg.launchOptions?.pipe ?? true)) {
+        throw new Error('Browser video requires the private CDP pipe transport.');
+      }
+    }
     if (
       optionsArg.launchOptions?.protocol
       && optionsArg.launchOptions.protocol !== 'cdp'
@@ -655,6 +668,7 @@ export class LiveBrowserSession {
       viewport: { ...this.viewport },
       tabs: [...this.tabs.values()].map((tab) => this.createTabState(tab)),
       ...(this.lastError ? { lastError: { ...this.lastError } } : {}),
+      ...(this.video ? { videoAcceleration: this.video.getAcceleration() } : {}),
     };
   }
 
@@ -766,6 +780,10 @@ export class LiveBrowserSession {
             usePipe: this.options.usePipe,
             launchOptions: {
               ...this.options.launchOptions,
+              ...(this.options.video ? {
+                enableExtensions: true,
+                args: this.videoLaunchArguments(),
+              } : {}),
               protocol: 'cdp',
               signal: browserLifetimeController.signal,
             },
@@ -808,8 +826,14 @@ export class LiveBrowserSession {
           throw signal.reason;
         }
         this.browserContext = this.browser.defaultBrowserContext();
+        if (this.options.video) {
+          if (this.options.launchOptions?.args?.includes('--disable-extensions')) {
+            throw new Error('Browser video requires its private capture extension.');
+          }
+          this.video = new LiveBrowserVideo(this.browser, this.options.video);
+        }
         this.browserTargetCreatedListener = (target) => {
-          if (target.type() !== 'page' || target.browserContext() !== this.browserContext) {
+          if (this.video?.ownsTarget(target) || target.type() !== 'page' || target.browserContext() !== this.browserContext) {
             return;
           }
           void target.page().then((page) => {
@@ -824,6 +848,7 @@ export class LiveBrowserSession {
         };
         this.browser.on('targetcreated', this.browserTargetCreatedListener);
         await this.configureBrowserSecurity(this.browser);
+        await this.video?.start();
         this.browserDisconnectedListener = () => {
           if (this.normalStopRequested || this.status === 'stopped' || this.status === 'stopping') {
             return;
@@ -844,7 +869,7 @@ export class LiveBrowserSession {
         };
         this.browser.on('disconnected', this.browserDisconnectedListener);
 
-        const initialPages = await this.browserContext.pages();
+        const initialPages = (await this.browserContext.pages()).filter(page => !this.video?.ownsTarget(page.target()));
         if (initialPages.length === 0) {
           initialPages.push(await this.browserContext.newPage());
         }
@@ -969,6 +994,71 @@ export class LiveBrowserSession {
     );
   }
 
+  private videoLaunchArguments(): string[] {
+    const args = [...(this.options.launchOptions?.args ?? [])];
+    if (this.options.video?.gpu === 'disabled') return [...args, '--disable-gpu'];
+    if (args.includes('--disable-gpu')) throw new Error('Use video.gpu="disabled" to disable video GPU acceleration.');
+    if (!args.includes('--enable-gpu')) args.push('--enable-gpu');
+    if (process.platform === 'linux') {
+      if (!args.some(arg => arg.startsWith('--use-angle='))) args.push('--use-angle=vulkan');
+      if (args.includes('--use-angle=vulkan')) {
+        const features = new Set(args.filter(arg => arg.startsWith('--enable-features='))
+          .flatMap(arg => arg.slice('--enable-features='.length).split(',')));
+        features.add('Vulkan');
+        for (let index = args.length - 1; index >= 0; index--) {
+          if (args[index]!.startsWith('--enable-features=')) args.splice(index, 1);
+        }
+        args.push(`--enable-features=${[...features].join(',')}`);
+        if (!args.includes('--disable-vulkan-surface')) args.push('--disable-vulkan-surface');
+      }
+    }
+    return args;
+  }
+
+  public setFrameCaptureEnabled(enabled: boolean, options: ILiveBrowserOperationOptions = {}): Promise<void> {
+    if (typeof enabled !== 'boolean') throw new Error('Frame capture enabled must be a boolean.');
+    return this.enqueuePublicOperation(async signal => {
+      signal.throwIfAborted();
+      if (enabled === this.frameCaptureEnabled) return;
+      const tab = this.requireActiveTab();
+      if (!tab.cdpSession || !tab.streaming) throw new Error('Browser input transport is unavailable.');
+      if (enabled) {
+        await tab.cdpSession.send('Page.startScreencast', this.screencastParameters());
+      } else {
+        await tab.cdpSession.send('Page.stopScreencast');
+        await this.retireOutstandingFrames(frame => frame.tabId === tab.id);
+      }
+      this.frameCaptureEnabled = enabled;
+    }, options);
+  }
+
+  public openVideoPeer(peerId: string, options: ILiveBrowserOperationOptions = {}): Promise<ILiveVideoOffer> {
+    return this.enqueuePublicOperation(async signal => {
+      const tab = this.requireActiveTab();
+      if (!this.video) throw new Error('Browser video is not enabled.');
+      return this.video.open(peerId, tab.page, { tabId: tab.id, generation: tab.generation,
+        viewportRevision: this.viewportRevision, viewport: { ...this.viewport } }, signal);
+    }, options);
+  }
+
+  public answerVideoPeer(peerId: string, negotiationId: string, description: ILiveVideoDescription,
+    options: ILiveBrowserOperationOptions = {}): Promise<void> {
+    return this.enqueuePublicOperation(async signal => {
+      signal.throwIfAborted();
+      if (!this.video) throw new Error('Browser video is not enabled.');
+      await this.video.answer(peerId, negotiationId, description);
+    }, options);
+  }
+
+  public closeVideoPeer(peerId: string): Promise<void> {
+    return this.video?.close(peerId) ?? Promise.resolve();
+  }
+
+  public getVideoStatistics(peerId: string): Promise<ILiveVideoStatistics> {
+    if (!this.video) return Promise.reject(new Error('Browser video is not enabled.'));
+    return this.video.getStatistics(peerId);
+  }
+
   public async updateScreencastOptions(
     optionsArg: ILiveBrowserScreencastUpdateOptions,
     operationOptions: ILiveBrowserOperationOptions = {},
@@ -985,7 +1075,7 @@ export class LiveBrowserSession {
       const activeTab = this.status === 'running' && this.activeTabId
         ? this.tabs.get(this.activeTabId)
         : undefined;
-      if (!activeTab?.streaming) {
+      if (!activeTab?.streaming || !this.frameCaptureEnabled) {
         return null;
       }
       return this.restartActiveScreencast(signal);
@@ -995,6 +1085,7 @@ export class LiveBrowserSession {
   private async restartActiveScreencast(
     signal: AbortSignal,
   ): Promise<ILiveBrowserFrameIdentity> {
+    if (!this.frameCaptureEnabled) throw new Error('Frame capture is not enabled.');
     signal.throwIfAborted();
     const tab = this.requireActiveTab();
     let firstFrame: ReturnType<LiveBrowserSession['waitForScreencastFrame']> | undefined;
@@ -2274,7 +2365,7 @@ export class LiveBrowserSession {
       status: tab.status,
       generation: tab.generation,
       appliedViewportRevision: tab.appliedViewportRevision,
-      streaming: tab.streaming,
+      streaming: tab.streaming && !tab.streamInvalidated,
     };
   }
 
@@ -2540,6 +2631,10 @@ export class LiveBrowserSession {
     this.browserDisconnectedListener = undefined;
 
     const shutdownErrors: unknown[] = [];
+    if (this.video) {
+      await this.video.stop().catch(error => shutdownErrors.push(error));
+      this.video = undefined;
+    }
     const shutdownFrameDrainPromise = this.shutdownFrameDrainPromise;
     this.shutdownFrameDrainPromise = undefined;
     if (shutdownFrameDrainPromise) {
@@ -2971,7 +3066,9 @@ export class LiveBrowserSession {
         session.send('Fetch.continueWithAuth', {
           requestId: event.requestId,
           authChallengeResponse,
-        }, proxySecurityCommandOptions).then(() => undefined),
+        }, proxySecurityCommandOptions).then(() => undefined).catch(error => (
+          this.reconcileClosedProxyRequest(proxySecuritySession, error)
+        )),
         generation,
         'proxy_security_protocol_failed',
       );
@@ -3008,7 +3105,9 @@ export class LiveBrowserSession {
           'Fetch.continueRequest',
           { requestId: event.requestId },
           proxySecurityCommandOptions,
-        ).then(() => undefined),
+        ).then(() => undefined).catch(error => (
+          this.reconcileClosedProxyRequest(proxySecuritySession, error)
+        )),
         generation,
         'proxy_security_protocol_failed',
       );
@@ -3156,6 +3255,7 @@ export class LiveBrowserSession {
   private async waitForProxySecurityTargetCoverage(
     targetId: string,
     generation: number,
+    excludedSession?: plugins.puppeteer.CDPSession,
   ): Promise<boolean> {
     for (let attempt = 0; attempt < 3; attempt += 1) {
       const generationSessions = [...this.proxySecuritySessions.values()].filter((candidate) => (
@@ -3165,6 +3265,7 @@ export class LiveBrowserSession {
       const hasReplacement = [...this.proxySecuritySessions.values()].some((candidate) => (
         candidate.generation === generation
         && candidate.targetId === targetId
+        && candidate.session !== excludedSession
         && candidate.fetchEnabled
         && !candidate.session.detached
       ));
@@ -3187,6 +3288,22 @@ export class LiveBrowserSession {
     return !targetInfos.some((targetInfo) => targetInfo.targetId === targetId);
   }
 
+  private async reconcileClosedProxyRequest(
+    record: IProxySecuritySession,
+    error: unknown,
+  ): Promise<void> {
+    if (this.proxySecurityStopping || this.normalStopRequested
+      || record.generation !== this.proxySecurityGeneration) return;
+    // An in-flight Fetch command can reject after its worker/session has retired.
+    // Retain the original record: detach handling may already have removed it.
+    await record.setupPromise;
+    if (!record.session.detached || !record.targetId) throw error;
+    if (await this.waitForProxySecurityTargetCoverage(
+      record.targetId, record.generation, record.session,
+    )) return;
+    throw error;
+  }
+
   private removeProxySecuritySession(proxySecuritySession: IProxySecuritySession): void {
     if (this.proxySecuritySessions.get(proxySecuritySession.session.id()) !== proxySecuritySession) {
       return;
@@ -4195,17 +4312,11 @@ export class LiveBrowserSession {
         cdpSessionDetachedListener,
       );
 
-      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,
-      );
+      if (this.frameCaptureEnabled) {
+        await this.waitForScreencastAuthority(
+          cdpSession.send('Page.startScreencast', this.screencastParameters()), authority,
+        );
+      }
       this.assertScreencastAuthority(tab, authority);
       this.emitState();
     } catch (error) {
@@ -4318,6 +4429,7 @@ export class LiveBrowserSession {
   }
 
   private invalidateScreencast(tab: IPrivateLiveBrowserTab, reason: unknown): void {
+    const wasStreaming = tab.streaming && !tab.streamInvalidated;
     tab.streamInvalidated = true;
     tab.streamLifecycleRevision += 1;
     const authority = tab.screencastAuthority;
@@ -4325,6 +4437,9 @@ export class LiveBrowserSession {
     if (authority && !authority.controller.signal.aborted) {
       authority.controller.abort(reason);
     }
+    // Input authority is revoked synchronously on renderer navigation. Publish
+    // that same boundary before the queued page/title refresh can yield.
+    if (wasStreaming) this.emitState();
   }
 
   private waitForScreencastFrame(
@@ -4377,7 +4492,15 @@ export class LiveBrowserSession {
     };
   }
 
+  private screencastParameters(): plugins.puppeteer.Protocol.Page.StartScreencastRequest {
+    return { format: this.options.screencast?.format ?? 'jpeg',
+      quality: this.options.screencast?.quality ?? 80,
+      maxWidth: this.options.screencast?.maxWidth, maxHeight: this.options.screencast?.maxHeight,
+      everyNthFrame: this.options.screencast?.everyNthFrame ?? 1 };
+  }
+
   private async stopScreencast(tab: IPrivateLiveBrowserTab): Promise<void> {
+    if (this.video && this.activeTabId === tab.id) await this.video.invalidate();
     const cdpSession = tab.cdpSession;
     const cdpConnection = tab.cdpConnection;
     const frameListener = tab.screencastFrameListener;

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -1,4 +1,5 @@
 import type { IEnvAwareOptions } from './smartpuppeteer.classes.smartpuppeteer.js';
+import type { ILiveVideoOptions, ILiveVideoAcceleration } from './interfaces.livevideo.js';
 
 export type TLiveBrowserStatus = 'stopped' | 'starting' | 'running' | 'stopping';
 export type TLiveBrowserImageFormat = 'jpeg' | 'png';
@@ -19,6 +20,8 @@ export interface ILiveBrowserViewport {
 }
 
 export interface ILiveBrowserScreencastOptions {
+  /** JPEG/PNG production can be enabled on demand independently of input. */
+  enabled?: boolean;
   format?: TLiveBrowserImageFormat;
   quality?: number;
   maxWidth?: number;
@@ -79,6 +82,7 @@ export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'laun
   launchOptions?: TLiveBrowserLaunchOptions;
   viewport?: ILiveBrowserViewport;
   screencast?: ILiveBrowserScreencastOptions;
+  video?: ILiveVideoOptions;
   security?: ILiveBrowserSecurityOptions;
   allowEvaluation?: boolean;
 }
@@ -129,6 +133,7 @@ export interface ILiveBrowserState {
   viewport: ILiveBrowserViewport;
   tabs: ILiveBrowserTabState[];
   lastError?: ILiveBrowserError;
+  videoAcceleration?: ILiveVideoAcceleration;
 }
 
 export interface ILiveBrowserScreencastMetadata {

package/ts/smartpuppeteer.plugins.ts

@@ -3,8 +3,10 @@ import { Buffer } from 'node:buffer';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import * as url from 'node:url';
 
-export { Buffer, fs, http, os };
+export { Buffer, fs, http, os, crypto, url };
 
 // @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';

package/readme.hints.md

@@ -1,20 +0,0 @@
-# Implementation Hints
-
-- `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. `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.
-- A refresh timeout or restart failure on a tab that is still restorable is not runtime-fatal. Revoke the restart authority, wait for the in-flight `startScreencast()` to unwind, stop whatever it established, and emit non-fatal `screencast_refresh_failed` with the tab left open, non-streaming, and invalidated. `refreshScreencast()` therefore also accepts a non-streaming active tab; `updateScreencastOptions()` shares that restart core after storing validated options. Browser loss stays fatal and is normally reported by the disconnect listener first.
-- Raw input is dispatched through a per-tab queue. Chromium does not keep a pipelined mouse or key command behind an earlier `mouseWheel` command, so anything queued behind wheel input waits until that wheel CDP call settles. Wheel input arriving while a wheel dispatch is in flight merges into the trailing wheel entry for the same CDP session, generation, and viewport revision; a non-wheel entry ends that batch.
-- 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.
-- Track the applied viewport revision on every tab. Before an inactive tab is captured, observed, activated, or acted upon, apply the current global viewport and report metadata from that exact viewport. Full-page capture is outside the initial live-runtime scope.
-- Canonicalize the configured viewport once. `viewport` wins over `launchOptions.defaultViewport`, `null` uses 800x600, and every Puppeteer viewport explicitly disables mobile, landscape, and touch emulation. The operation scheduler owns `LaunchOptions.signal`; never accept a caller signal for `LiveBrowserSession`.
-- New-page registration and navigation are transactional: validate before creating a page where possible and restore page, listener, tab-map, active-tab, viewport, and screencast ownership on failure. Keep listeners attached during `page.close()` so a failed close remains observed and recoverable.
-- Browser disconnect is runtime-fatal. Page crash or current CDP-session loss is tab-scoped: activate another usable tab, trying all candidates, or stop cleanly when none remains.
-- Every popup is either registered, closed, or escalated to browser-wide shutdown. Queue saturation and startup-time popup events must never leave an untracked live page.
-- Authenticated proxy coverage owns a filtered browser-target auto-attach scope for service workers. Configure Fetch and Network before resuming each owned worker, use the hidden page-target lifecycle observer to release stopped or request-drained redundant workers, bound every security command and detach wait, and keep Puppeteer's target sessions independent.
-- A navigation metadata refresh failure must not consume screencast restoration ownership. Restore the active stream first, preserve newer navigation revisions, and report the metadata failure separately.
-- Verify Puppeteer behavior against the installed Puppeteer 25 declarations and implementation. Do not add a direct `devtools-protocol` dependency; Puppeteer's public protocol typing is sufficient for private CDP calls.