@push.rocks/smartpuppeteer 2.7.0 → 2.8.1

package/dist_ts/smartpuppeteer.interfaces.livebrowser.d.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';
 export type TLiveBrowserTabStatus = 'open' | 'crashed';
@@ -11,6 +12,8 @@ export interface ILiveBrowserViewport {
     deviceScaleFactor: number;
 }
 export interface ILiveBrowserScreencastOptions {
+    /** JPEG/PNG production can be enabled on demand independently of input. */
+    enabled?: boolean;
     format?: TLiveBrowserImageFormat;
     quality?: number;
     maxWidth?: number;
@@ -53,6 +56,7 @@ export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'laun
     launchOptions?: TLiveBrowserLaunchOptions;
     viewport?: ILiveBrowserViewport;
     screencast?: ILiveBrowserScreencastOptions;
+    video?: ILiveVideoOptions;
     security?: ILiveBrowserSecurityOptions;
     allowEvaluation?: boolean;
 }
@@ -97,6 +101,7 @@ export interface ILiveBrowserState {
     viewport: ILiveBrowserViewport;
     tabs: ILiveBrowserTabState[];
     lastError?: ILiveBrowserError;
+    videoAcceleration?: ILiveVideoAcceleration;
 }
 export interface ILiveBrowserScreencastMetadata {
     offsetTop: number;

package/dist_ts/smartpuppeteer.interfaces.livebrowser.js

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

package/dist_ts/smartpuppeteer.plugins.d.ts

@@ -2,7 +2,9 @@ import { Buffer } from 'node:buffer';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as os from 'node:os';
-export { Buffer, fs, http, os };
+import * as crypto from 'node:crypto';
+import * as url from 'node:url';
+export { Buffer, fs, http, os, crypto, url };
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartshell from '@push.rocks/smartshell';
 export { smartdelay, smartshell };

package/dist_ts/smartpuppeteer.plugins.js

@@ -3,7 +3,9 @@ import { Buffer } from 'node:buffer';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as os from 'node:os';
-export { Buffer, fs, http, os };
+import * as crypto from 'node:crypto';
+import * as url from 'node:url';
+export { Buffer, fs, http, os, crypto, url };
 // @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartshell from '@push.rocks/smartshell';
@@ -12,4 +14,4 @@ export { smartdelay, smartshell };
 import * as puppeteer from 'puppeteer';
 import treeKill from 'tree-kill';
 export { puppeteer, treeKill };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUIsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFDbEMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFFOUIsT0FBTyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLEVBQUUsRUFBRSxDQUFDO0FBRWhDLG1CQUFtQjtBQUNuQixPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxVQUFVLE1BQU0sd0JBQXdCLENBQUM7QUFFckQsT0FBTyxFQUFFLFVBQVUsRUFBRSxVQUFVLEVBQUUsQ0FBQztBQUVsQyxvQkFBb0I7QUFDcEIsT0FBTyxLQUFLLFNBQVMsTUFBTSxXQUFXLENBQUM7QUFDdkMsT0FBTyxRQUFRLE1BQU0sV0FBVyxDQUFDO0FBRWpDLE9BQU8sRUFBRSxTQUFTLEVBQUUsUUFBUSxFQUFFLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUIsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFDbEMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUIsT0FBTyxLQUFLLE1BQU0sTUFBTSxhQUFhLENBQUM7QUFDdEMsT0FBTyxLQUFLLEdBQUcsTUFBTSxVQUFVLENBQUM7QUFFaEMsT0FBTyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLEVBQUUsRUFBRSxNQUFNLEVBQUUsR0FBRyxFQUFFLENBQUM7QUFFN0MsbUJBQW1CO0FBQ25CLE9BQU8sS0FBSyxVQUFVLE1BQU0sd0JBQXdCLENBQUM7QUFDckQsT0FBTyxLQUFLLFVBQVUsTUFBTSx3QkFBd0IsQ0FBQztBQUVyRCxPQUFPLEVBQUUsVUFBVSxFQUFFLFVBQVUsRUFBRSxDQUFDO0FBRWxDLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssU0FBUyxNQUFNLFdBQVcsQ0FBQztBQUN2QyxPQUFPLFFBQVEsTUFBTSxXQUFXLENBQUM7QUFFakMsT0FBTyxFQUFFLFNBQVMsRUFBRSxRQUFRLEVBQUUsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartpuppeteer",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "private": false,
   "description": "Provides simplified access to Puppeteer for automation and testing purposes.",
   "main": "dist_ts/index.js",
@@ -12,9 +12,9 @@
     "node": ">=22.12.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsbuild": "^4.4.3",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
+    "@git.zone/tstest": "^6.0.0",
     "@types/node": "^26.4.1"
   },
   "dependencies": {

package/readme.md

@@ -190,6 +190,8 @@ if (identity) {
 }
 ```
 
+Synchronous screencast invalidation, including renderer-initiated navigation, immediately publishes a state event with `streaming: false`. The tab remains nonstreaming in public state until the replacement generation starts, so viewers can fence input before asynchronous page metadata refresh completes.
+
 The live API includes:
 
 - Lifecycle and state: `start()`, `stop()`, `terminate()`, `refreshScreencast()`, `updateScreencastOptions()`, `getProcessState()`, `onEvent()`, and `getState()`
@@ -252,6 +254,40 @@ The default evaluation limits are a 5-second timeout, 256 KiB transferred output
 
 `LiveBrowserSession` remains a browser runtime, not a complete security policy layer. The optional guards do not authenticate callers, authorize actions, enforce network egress, own profile-directory cleanup, isolate operating-system resources, or contain a compromised Chromium process. Adapters must apply those controls before invoking it. `stop()` rejects active and queued operations and aborts Chromium independently of Puppeteer operation timeouts. Closing the final usable tab also stops the session. Browser-wide loss stops the runtime without automatic relaunch. Page or CDP loss is tab-scoped: another usable tab becomes active when possible, otherwise the runtime stops. Popup registration queue saturation emits `popup_registration_capacity_exceeded` and stops the session rather than leaving an untracked page.
 
+### Native WebRTC video
+
+Enable `video` for native Chromium tab capture and WebRTC delivery:
+
+```typescript
+const session = new LiveBrowserSession({
+  requireSandbox: true,
+  viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+  screencast: { enabled: false },
+  video: { gpu: 'auto', maxFrameRate: 30, maxBitrate: 8_000_000 },
+});
+await session.start();
+const offer = await session.openVideoPeer('authorized-viewer');
+// Send offer to the authorized receiver over your existing signaling transport.
+// Receiver creates an RTCPeerConnection using offer.iceServers/iceTransportPolicy,
+// applies offer.description, and returns its gathered answer description.
+await session.answerVideoPeer(offer.peerId, offer.negotiationId, answerDescription);
+const statistics = await session.getVideoStatistics(offer.peerId);
+await session.closeVideoPeer(offer.peerId);
+await session.stop();
+```
+
+Capture is a native tab `MediaStreamTrack` in a fixed packaged private extension. Video does not pass through JPEG, base64, a JavaScript canvas, or a Node video encoder. Chromium owns congestion control and codec selection; sustained encoder CPU pressure additionally reduces per-viewer resolution and recovery restores it. The source is shared by viewers, each with an independent peer and encoding budget. Closing the last peer stops capture. Opening another peer starts it again. The default capacity is eight viewers, bounded to 32.
+
+Direct ICE with no external service is the default, suitable for reachable LAN and VPN peers. The host can supply `iceServers` and `iceTransportPolicy: 'relay'` for deployments requiring TURN. Relay-only configuration requires a TURN URL. Signaling and peer IDs must be authorized by the embedding host; never let a visited page configure peers or ICE services. SDP is limited to 48 KiB and one video media section; audio and data channels are not accepted. Offers finish ICE gathering before returning, and peers have a 30-second connection deadline.
+
+The private extension requires Chromium's CDP pipe (the default); `--disable-extensions` is incompatible. It has no content scripts, externally connected messages, or web-accessible resources. Existing page WebRTC routing restrictions remain in force. The extension's host-authorized peer traffic is independent of the HTTP proxy, so the host must permit the intended LAN/VPN path.
+
+`gpu: 'auto'` enables GPU rendering when Chrome and its drivers support it; Linux headless capture uses ANGLE Vulkan unless a caller selected another ANGLE backend. `gpu: 'disabled'` explicitly uses software rendering. `getState().videoAcceleration` reports Chrome's renderer, compositing and video-encoding capability; `getVideoStatistics()` reports the encoder actually used. GPU rendering does not imply hardware video encoding.
+
+Every offer includes a unique `negotiationId`, required when submitting its answer, and its source `{ tabId, generation, viewportRevision, viewport }`. Navigation, tab activation and viewport changes retire existing peers. Receivers must reject stale negotiation, reopen against the current source, and allow input only after a frame from that source is presented. `openVideoPeer()` and `answerVideoPeer()` participate in the serialized browser operation queue. `closeVideoPeer()` is idempotent, and the private media queue is bounded.
+
+`screencast.enabled` defaults to `true` for frame consumers. Set it to `false` when using video alone, then use `setFrameCaptureEnabled(true/false)` to follow actual JPEG/PNG subscriber demand. This leaves input and video available. Snapshot capture remains independent. `refreshScreencast()` requires frame capture to be enabled.
+
 ### Handling Browser Events
 It's important to handle browser events, such as disconnections, which might occur due to various reasons:
 

package/ts/00_commitinfo_data.ts

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

package/ts/classes.livevideo.ts

@@ -0,0 +1,210 @@
+import * as plugins from './smartpuppeteer.plugins.js';
+import {
+  normalizeLiveVideoOptions, validateLiveVideoDescription,
+  type ILiveVideoOptions, type ILiveVideoSource, type ILiveVideoOffer,
+  type ILiveVideoDescription, type ILiveVideoStatistics, type ILiveVideoAcceleration,
+} from './interfaces.livevideo.js';
+
+interface IPrivateVideoApi {
+  offer(input: { peerId: string }): Promise<ILiveVideoDescription>;
+  answer(input: { peerId: string; description: ILiveVideoDescription }): Promise<void>;
+  stats(input: { peerId: string }): Promise<ILiveVideoStatistics>;
+  close(input: { peerId: string }): void;
+  stop(): void;
+  arm(input: { requestId: string; options: Required<ILiveVideoOptions> }): void;
+  result(requestId: string): { requestId: string; ready?: boolean; error?: string } | null;
+}
+
+/** Private extension bridge; never evaluates in a visited page or exposes CDP. */
+export class LiveBrowserVideo {
+  public readonly options: Required<ILiveVideoOptions>;
+  private extensionId?: string;
+  private capturePage?: plugins.puppeteer.Page;
+  private captureSource?: ILiveVideoSource;
+  private readonly peers = new Map<string, string>();
+  private operation: Promise<unknown> = Promise.resolve();
+  private closed = false;
+  private pendingOperations = 0;
+  private acceleration?: ILiveVideoAcceleration;
+
+  constructor(private browser: plugins.puppeteer.Browser, options: ILiveVideoOptions) {
+    this.options = normalizeLiveVideoOptions(options);
+  }
+
+  public async start(): Promise<void> {
+    this.extensionId = await this.browser.installExtension(
+      plugins.url.fileURLToPath(new URL('../assets/livevideo/', import.meta.url)),
+    );
+    const session = await this.browser.target().createCDPSession();
+    try {
+      const { gpu } = await session.send('SystemInfo.getInfo');
+      const attributes = gpu.auxAttributes as Record<string, unknown> | undefined;
+      const features = gpu.featureStatus as Record<string, unknown> | undefined;
+      this.acceleration = {
+        renderer: String(attributes?.glRenderer ?? 'unknown'),
+        compositing: String(features?.gpu_compositing ?? 'unknown'),
+        videoEncoding: String(features?.video_encode ?? 'unknown'),
+      };
+    } finally { await session.detach(); }
+  }
+
+  public getAcceleration(): ILiveVideoAcceleration | undefined {
+    return this.acceleration ? { ...this.acceleration } : undefined;
+  }
+
+  public ownsTarget(target: plugins.puppeteer.Target): boolean {
+    return !!this.extensionId && target.url().startsWith(`chrome-extension://${this.extensionId}/`);
+  }
+
+  public hasPeer(peerId: string): boolean { return this.peers.has(peerId); }
+
+  public open(
+    peerId: string,
+    page: plugins.puppeteer.Page,
+    source: ILiveVideoSource,
+    signal?: AbortSignal,
+  ): Promise<ILiveVideoOffer> {
+    return this.enqueue(async () => {
+      signal?.throwIfAborted();
+      if (!/^[a-zA-Z0-9_-]{1,128}$/.test(peerId)) throw new Error('Invalid video peer identity.');
+      if (this.peers.has(peerId)) await this.closeInternal(peerId);
+      if (this.peers.size >= this.options.maxViewers) throw new Error('Video viewer capacity reached.');
+      try {
+        if (!this.sameSource(source)) await this.stopCapture();
+        if (!this.captureSource) await this.capture(page, source);
+        signal?.throwIfAborted();
+        const description = await this.capturePage!.evaluate(async input => (
+          (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.offer(input)
+        ), { peerId });
+        validateLiveVideoDescription(description, 'offer');
+        signal?.throwIfAborted();
+        const negotiationId = plugins.crypto.randomUUID();
+        this.peers.set(peerId, negotiationId);
+        return { peerId, negotiationId, source: structuredClone(source), description,
+          iceServers: structuredClone(this.options.iceServers), iceTransportPolicy: this.options.iceTransportPolicy };
+      } catch (error) {
+        await this.closeInternal(peerId);
+        throw error;
+      }
+    });
+  }
+
+  public answer(peerId: string, negotiationId: string, description: ILiveVideoDescription): Promise<void> {
+    validateLiveVideoDescription(description, 'answer');
+    return this.enqueue(async () => {
+      this.requirePeer(peerId);
+      if (this.peers.get(peerId) !== negotiationId) throw new Error('Video negotiation is stale.');
+      await this.capturePage!.evaluate(async input => (
+        (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.answer(input)
+      ), { peerId, description });
+    });
+  }
+
+  public getStatistics(peerId: string): Promise<ILiveVideoStatistics> {
+    return this.enqueue(async () => {
+      this.requirePeer(peerId);
+      return this.capturePage!.evaluate(async input => (
+        (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.stats(input)
+      ), { peerId });
+    });
+  }
+
+  public close(peerId: string): Promise<void> { return this.enqueue(() => this.closeInternal(peerId)); }
+
+  /** Retires media before changing tab/viewport identity. Control stays independent. */
+  public invalidate(): Promise<void> { return this.enqueue(() => this.stopCapture()); }
+
+  public async stop(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.operation;
+    await this.stopCapture();
+    this.capturePage = undefined;
+    // The extension is process-local and the owning browser closes immediately
+    // afterward; no extension or media profile is installed into a user's browser.
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed) return Promise.reject(new Error('Browser video is closed.'));
+    if (this.pendingOperations >= 128) return Promise.reject(new Error('Browser video operation capacity reached.'));
+    this.pendingOperations++;
+    const task = this.operation.then(operation).finally(() => { this.pendingOperations--; });
+    this.operation = task.then(() => undefined, () => undefined);
+    return task;
+  }
+
+  private sameSource(source: ILiveVideoSource): boolean {
+    return this.captureSource?.tabId === source.tabId && this.captureSource.generation === source.generation
+      && this.captureSource.viewportRevision === source.viewportRevision;
+  }
+
+  private requirePeer(peerId: string): void {
+    if (!this.peers.has(peerId) || !this.capturePage || this.capturePage.isClosed()) {
+      throw new Error('Video peer is unavailable.');
+    }
+  }
+
+  private async closeInternal(peerId: string): Promise<void> {
+    if (this.capturePage && !this.capturePage.isClosed()) {
+      await this.capturePage.evaluate(input => (
+        (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.close(input)
+      ), { peerId });
+    }
+    this.peers.delete(peerId);
+    if (!this.peers.size) await this.stopCapture();
+  }
+
+  private async stopCapture(): Promise<void> {
+    if (this.capturePage && !this.capturePage.isClosed()) {
+      await this.capturePage.evaluate(() => (
+        (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.stop()
+      ));
+    }
+    this.peers.clear();
+    this.captureSource = undefined;
+  }
+
+  private async capture(page: plugins.puppeteer.Page, source: ILiveVideoSource): Promise<void> {
+    if (!this.extensionId) throw new Error('Private browser video extension is not initialized.');
+    const extension = (await this.browser.extensions()).get(this.extensionId);
+    if (!extension) throw new Error('Private browser video extension is unavailable.');
+    // The action wakes MV3 workers. Capture authority lives in the offscreen
+    // document so ordinary worker retirement cannot strand a saved CDP context.
+    if (!this.capturePage || this.capturePage.isClosed()) {
+      await page.triggerExtensionAction(extension);
+      const target = await this.browser.waitForTarget(candidate => (
+        candidate.url() === `chrome-extension://${this.extensionId}/capture.html`
+      ), { timeout: 10_000 });
+      this.capturePage = await target.asPage();
+      await this.capturePage.waitForFunction(() => (
+        !!(globalThis as unknown as { smartpuppeteerVideo?: IPrivateVideoApi }).smartpuppeteerVideo
+      ), { timeout: 10_000 });
+    }
+    const requestId = plugins.crypto.randomUUID();
+    try {
+      await this.capturePage.evaluate(input => (
+        (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo.arm(input)
+      ), { requestId, options: { ...this.options,
+        maxWidth: Math.min(this.options.maxWidth, Math.round(source.viewport.width * source.viewport.deviceScaleFactor)),
+        maxHeight: Math.min(this.options.maxHeight, Math.round(source.viewport.height * source.viewport.deviceScaleFactor)),
+      } });
+      await page.triggerExtensionAction(extension);
+      const result = await this.capturePage.evaluate(async expected => {
+        const api = (globalThis as unknown as { smartpuppeteerVideo: IPrivateVideoApi }).smartpuppeteerVideo;
+        const deadline = Date.now() + 10_000;
+        while (Date.now() < deadline) {
+          const result = api.result(expected);
+          if (result) return result;
+          await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        throw new Error('Private browser video capture startup timed out.');
+      }, requestId);
+      if (result.error || !result.ready) throw new Error(result.error ?? 'Browser video capture failed.');
+      this.captureSource = structuredClone(source);
+    } catch (error) {
+      try { await this.stopCapture(); }
+      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Browser video capture and cleanup failed.'); }
+      throw error;
+    }
+  }
+}

package/ts/index.ts

@@ -4,6 +4,7 @@ export * from './smartpuppeteer.classes.smartpuppeteer.js';
 export * from './smartpuppeteer.classes.incognitobrowser.js';
 export * from './smartpuppeteer.interfaces.livebrowser.js';
 export * from './smartpuppeteer.classes.livebrowsersession.js';
+export * from './interfaces.livevideo.js';
 
 // direct exports
 import { puppeteer } from './smartpuppeteer.plugins.js';

package/ts/interfaces.livevideo.ts

@@ -0,0 +1,103 @@
+/** Host-provided ICE services. Never accept relay configuration from a visited page. */
+export interface ILiveVideoIceServer {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+export interface ILiveVideoOptions {
+  iceServers?: ILiveVideoIceServer[];
+  iceTransportPolicy?: 'all' | 'relay';
+  maxViewers?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+  maxFrameRate?: number;
+  maxBitrate?: number;
+  gpu?: 'auto' | 'disabled';
+}
+
+export interface ILiveVideoSource {
+  tabId: string;
+  generation: number;
+  viewportRevision: number;
+  viewport: { width: number; height: number; deviceScaleFactor: number };
+}
+
+export interface ILiveVideoDescription {
+  type: 'offer' | 'answer';
+  sdp: string;
+}
+
+export interface ILiveVideoOffer {
+  peerId: string;
+  negotiationId: string;
+  source: ILiveVideoSource;
+  description: ILiveVideoDescription;
+  iceServers: ILiveVideoIceServer[];
+  iceTransportPolicy: 'all' | 'relay';
+}
+
+export interface ILiveVideoStatistics {
+  connectionState: string;
+  visible: boolean;
+  framesEncoded: number;
+  bytesSent: number;
+  frameWidth?: number;
+  frameHeight?: number;
+  framesPerSecond?: number;
+  encoderImplementation?: string;
+  powerEfficientEncoder?: boolean;
+  qualityLimitationReason?: string;
+  roundTripTime?: number;
+}
+
+export interface ILiveVideoAcceleration {
+  renderer: string;
+  compositing: string;
+  videoEncoding: string;
+}
+
+export const normalizeLiveVideoOptions = (input: ILiveVideoOptions): Required<ILiveVideoOptions> => {
+  const integer = (value: number | undefined, fallback: number, min: number, max: number): number => {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < min || result > max) {
+      throw new Error(`Video option must be an integer between ${min} and ${max}.`);
+    }
+    return result;
+  };
+  if (input.gpu !== undefined && !['auto', 'disabled'].includes(input.gpu)) throw new Error('Invalid video GPU mode.');
+  if (input.iceTransportPolicy !== undefined && !['all', 'relay'].includes(input.iceTransportPolicy)) {
+    throw new Error('Invalid video ICE transport policy.');
+  }
+  if (input.iceServers !== undefined && (!Array.isArray(input.iceServers) || input.iceServers.length > 8)) {
+    throw new Error('Video supports at most eight ICE services.');
+  }
+  const iceServers = (input.iceServers ?? []).map(server => {
+    const urls = typeof server.urls === 'string' ? [server.urls] : server.urls;
+    if (!Array.isArray(urls) || !urls.length || urls.length > 8 || urls.some(url => (
+      typeof url !== 'string' || url.length > 2048 || !/^(stun|stuns|turn|turns):[^\s@]+$/.test(url)
+    ))) throw new Error('Invalid video ICE service URL.');
+    for (const value of [server.username, server.credential]) {
+      if (value !== undefined && (typeof value !== 'string' || value.length > 2048)) throw new Error('Invalid video ICE credentials.');
+    }
+    return { urls: [...urls], ...(server.username === undefined ? {} : { username: server.username }),
+      ...(server.credential === undefined ? {} : { credential: server.credential }) };
+  });
+  if (input.iceTransportPolicy === 'relay' && !iceServers.some(server => server.urls.some(url => /^turns?:/.test(url)))) {
+    throw new Error('Relay-only video requires a TURN service.');
+  }
+  return { iceServers, iceTransportPolicy: input.iceTransportPolicy ?? 'all',
+    maxViewers: integer(input.maxViewers, 8, 1, 32), maxWidth: integer(input.maxWidth, 2560, 320, 4096),
+    maxHeight: integer(input.maxHeight, 1600, 240, 4096), maxFrameRate: integer(input.maxFrameRate, 30, 1, 60),
+    maxBitrate: integer(input.maxBitrate, 8_000_000, 100_000, 50_000_000), gpu: input.gpu ?? 'auto' };
+};
+
+export const validateLiveVideoDescription = (description: ILiveVideoDescription, type: 'offer' | 'answer'): void => {
+  if (!description || description.type !== type || typeof description.sdp !== 'string'
+    || description.sdp.length > 48 * 1024 || !description.sdp.startsWith('v=0\r\n')) {
+    throw new Error('Invalid video session description.');
+  }
+  if ((description.sdp.match(/^m=/gm) ?? []).length !== 1 || !/^m=video /m.test(description.sdp)) {
+    throw new Error('Video negotiation accepts only a video media section.');
+  }
+};