@push.rocks/smartpuppeteer 2.0.7 → 2.2.0

package/dist_ts/smartpuppeteer.classes.smartpuppeteer.d.ts

@@ -1,7 +1,9 @@
 import * as plugins from './smartpuppeteer.plugins.js';
 export interface IEnvAwareOptions {
     forceNoSandbox?: boolean;
+    requireSandbox?: boolean;
     usePipe?: boolean;
+    launchOptions?: plugins.puppeteer.LaunchOptions;
 }
 export declare const resolveBrowserExecutablePath: (candidateNamesArg?: string[]) => string | undefined;
 export declare const getEnvAwareBrowserInstance: (optionsArg?: IEnvAwareOptions) => Promise<plugins.puppeteer.Browser>;

package/dist_ts/smartpuppeteer.classes.smartpuppeteer.js

@@ -1,4 +1,10 @@
 import * as plugins from './smartpuppeteer.plugins.js';
+const sandboxDisablingArguments = [
+    '--disable-gpu-sandbox',
+    '--disable-seccomp-filter-sandbox',
+    '--disable-setuid-sandbox',
+    '--no-sandbox',
+];
 export const resolveBrowserExecutablePath = (candidateNamesArg = [
     'google-chrome',
     'chromium',
@@ -17,34 +23,59 @@ export const resolveBrowserExecutablePath = (candidateNamesArg = [
 export const getEnvAwareBrowserInstance = async (optionsArg = {}) => {
     const options = {
         forceNoSandbox: false,
+        requireSandbox: false,
         ...optionsArg,
     };
-    let chromeArgs = [];
-    if (process.env.CI ||
-        options.forceNoSandbox ||
-        plugins.os.userInfo().username === 'root') {
-        chromeArgs = chromeArgs.concat(['--no-sandbox', '--disable-setuid-sandbox']);
+    if (options.forceNoSandbox && options.requireSandbox) {
+        throw new Error('forceNoSandbox and requireSandbox are mutually exclusive');
+    }
+    const launchOptions = options.launchOptions ?? {};
+    let chromeArgs = [...(launchOptions.args ?? [])];
+    if (options.requireSandbox) {
+        const forbiddenArgument = chromeArgs.find((argument) => (sandboxDisablingArguments.includes(argument.split('=', 1)[0])));
+        if (forbiddenArgument) {
+            throw new Error(`Sandbox-required browser launch rejects argument: ${forbiddenArgument}`);
+        }
+        if (process.platform === 'linux' && process.getuid?.() === 0) {
+            throw new Error('Sandbox-required Chromium cannot be launched as root');
+        }
+    }
+    else if (process.env.CI
+        || options.forceNoSandbox
+        || plugins.os.userInfo().username === 'root') {
+        for (const sandboxArg of ['--no-sandbox', '--disable-setuid-sandbox']) {
+            if (!chromeArgs.includes(sandboxArg)) {
+                chromeArgs.push(sandboxArg);
+            }
+        }
         console.warn('********************************************************');
         console.warn('WARNING: Launching browser without sandbox. This can be insecure!');
         console.warn('********************************************************');
     }
-    // Automatically choose an executable if available: prefer google-chrome, then chromium, then chromium-browser.
-    const execPath = resolveBrowserExecutablePath();
+    // Automatically choose an executable only when the caller did not select one.
+    const callerSelectedBrowser = launchOptions.browser !== undefined
+        || launchOptions.channel !== undefined
+        || launchOptions.executablePath !== undefined;
+    const execPath = callerSelectedBrowser ? undefined : resolveBrowserExecutablePath();
     const executablePathOptions = execPath ? { executablePath: execPath } : {};
     console.log('Launching puppeteer browser with arguments:');
     console.log(chromeArgs);
     if (execPath) {
         console.log(`Using executable: ${execPath}`);
     }
+    else if (callerSelectedBrowser) {
+        console.log('Using browser selection from caller launch options.');
+    }
     else {
         console.log('No specific browser executable found; falling back to Puppeteer default.');
     }
     const headlessBrowser = await plugins.puppeteer.launch({
-        args: chromeArgs,
-        pipe: options.usePipe ?? true,
         headless: true,
+        ...launchOptions,
+        args: chromeArgs,
+        pipe: options.usePipe ?? launchOptions.pipe ?? true,
         ...executablePathOptions,
     });
     return headlessBrowser;
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuY2xhc3Nlcy5zbWFydHB1cHBldGVlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmNsYXNzZXMuc21hcnRwdXBwZXRlZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSw2QkFBNkIsQ0FBQztBQU92RCxNQUFNLENBQUMsTUFBTSw0QkFBNEIsR0FBRyxDQUMxQyxvQkFBOEI7SUFDNUIsZUFBZTtJQUNmLFVBQVU7SUFDVixrQkFBa0I7Q0FDbkIsRUFDbUIsRUFBRTtJQUN0QixLQUFLLE1BQU0sYUFBYSxJQUFJLGlCQUFpQixFQUFFLENBQUM7UUFDOUMsTUFBTSxjQUFjLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLGFBQWEsRUFBRTtZQUNsRSxPQUFPLEVBQUUsSUFBSTtTQUNkLENBQUMsQ0FBQztRQUNILElBQUksY0FBYyxFQUFFLENBQUM7WUFDbkIsT0FBTyxjQUFjLENBQUM7UUFDeEIsQ0FBQztJQUNILENBQUM7SUFDRCxPQUFPLFNBQVMsQ0FBQztBQUNuQixDQUFDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxLQUFLLEVBQzdDLGFBQStCLEVBQUUsRUFDRyxFQUFFO0lBQ3RDLE1BQU0sT0FBTyxHQUFxQjtRQUNoQyxjQUFjLEVBQUUsS0FBSztRQUNyQixHQUFHLFVBQVU7S0FDZCxDQUFDO0lBRUYsSUFBSSxVQUFVLEdBQWEsRUFBRSxDQUFDO0lBQzlCLElBQ0UsT0FBTyxDQUFDLEdBQUcsQ0FBQyxFQUFFO1FBQ2QsT0FBTyxDQUFDLGNBQWM7UUFDdEIsT0FBTyxDQUFDLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxRQUFRLEtBQUssTUFBTSxFQUN6QyxDQUFDO1FBQ0QsVUFBVSxHQUFHLFVBQVUsQ0FBQyxNQUFNLENBQUMsQ0FBQyxjQUFjLEVBQUUsMEJBQTBCLENBQUMsQ0FBQyxDQUFDO1FBQzdFLE9BQU8sQ0FBQyxJQUFJLENBQUMsMERBQTBELENBQUMsQ0FBQztRQUN6RSxPQUFPLENBQUMsSUFBSSxDQUFDLG1FQUFtRSxDQUFDLENBQUM7UUFDbEYsT0FBTyxDQUFDLElBQUksQ0FBQywwREFBMEQsQ0FBQyxDQUFDO0lBQzNFLENBQUM7SUFFRCwrR0FBK0c7SUFDL0csTUFBTSxRQUFRLEdBQUcsNEJBQTRCLEVBQUUsQ0FBQztJQUVoRCxNQUFNLHFCQUFxQixHQUFHLFFBQVEsQ0FBQyxDQUFDLENBQUMsRUFBRSxjQUFjLEVBQUUsUUFBUSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUUzRSxPQUFPLENBQUMsR0FBRyxDQUFDLDZDQUE2QyxDQUFDLENBQUM7SUFDM0QsT0FBTyxDQUFDLEdBQUcsQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUN4QixJQUFJLFFBQVEsRUFBRSxDQUFDO1FBQ2IsT0FBTyxDQUFDLEdBQUcsQ0FBQyxxQkFBcUIsUUFBUSxFQUFFLENBQUMsQ0FBQztJQUMvQyxDQUFDO1NBQU0sQ0FBQztRQUNOLE9BQU8sQ0FBQyxHQUFHLENBQUMsMEVBQTBFLENBQUMsQ0FBQztJQUMxRixDQUFDO0lBRUQsTUFBTSxlQUFlLEdBQUcsTUFBTSxPQUFPLENBQUMsU0FBUyxDQUFDLE1BQU0sQ0FBQztRQUNyRCxJQUFJLEVBQUUsVUFBVTtRQUNoQixJQUFJLEVBQUUsT0FBTyxDQUFDLE9BQU8sSUFBSSxJQUFJO1FBQzdCLFFBQVEsRUFBRSxJQUFJO1FBQ2QsR0FBRyxxQkFBcUI7S0FDekIsQ0FBQyxDQUFDO0lBRUgsT0FBTyxlQUFlLENBQUM7QUFDekIsQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuY2xhc3Nlcy5zbWFydHB1cHBldGVlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmNsYXNzZXMuc21hcnRwdXBwZXRlZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSw2QkFBNkIsQ0FBQztBQVN2RCxNQUFNLHlCQUF5QixHQUFHO0lBQ2hDLHVCQUF1QjtJQUN2QixrQ0FBa0M7SUFDbEMsMEJBQTBCO0lBQzFCLGNBQWM7Q0FDZixDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sNEJBQTRCLEdBQUcsQ0FDMUMsb0JBQThCO0lBQzVCLGVBQWU7SUFDZixVQUFVO0lBQ1Ysa0JBQWtCO0NBQ25CLEVBQ21CLEVBQUU7SUFDdEIsS0FBSyxNQUFNLGFBQWEsSUFBSSxpQkFBaUIsRUFBRSxDQUFDO1FBQzlDLE1BQU0sY0FBYyxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxhQUFhLEVBQUU7WUFDbEUsT0FBTyxFQUFFLElBQUk7U0FDZCxDQUFDLENBQUM7UUFDSCxJQUFJLGNBQWMsRUFBRSxDQUFDO1lBQ25CLE9BQU8sY0FBYyxDQUFDO1FBQ3hCLENBQUM7SUFDSCxDQUFDO0lBQ0QsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsS0FBSyxFQUM3QyxhQUErQixFQUFFLEVBQ0csRUFBRTtJQUN0QyxNQUFNLE9BQU8sR0FBcUI7UUFDaEMsY0FBYyxFQUFFLEtBQUs7UUFDckIsY0FBYyxFQUFFLEtBQUs7UUFDckIsR0FBRyxVQUFVO0tBQ2QsQ0FBQztJQUVGLElBQUksT0FBTyxDQUFDLGNBQWMsSUFBSSxPQUFPLENBQUMsY0FBYyxFQUFFLENBQUM7UUFDckQsTUFBTSxJQUFJLEtBQUssQ0FBQywwREFBMEQsQ0FBQyxDQUFDO0lBQzlFLENBQUM7SUFFRCxN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

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

@@ -0,0 +1,215 @@
+import type { IEnvAwareOptions } from './smartpuppeteer.classes.smartpuppeteer.js';
+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 interface ILiveBrowserViewport {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+}
+export interface ILiveBrowserScreencastOptions {
+    format?: TLiveBrowserImageFormat;
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    everyNthFrame?: number;
+}
+export interface ILiveBrowserSecurityOptions {
+    denyDownloads?: boolean;
+    denyFileChoosers?: boolean;
+    denyPermissions?: boolean;
+    httpNavigationOnly?: boolean;
+}
+export interface ILiveBrowserOperationOptions {
+    signal?: AbortSignal;
+}
+export type TLiveBrowserJsonValue = null | boolean | number | string | TLiveBrowserJsonValue[] | {
+    [key: string]: TLiveBrowserJsonValue;
+};
+export interface ILiveBrowserEvaluateOptions {
+    tabId?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    maxDepth?: number;
+    maxNodes?: number;
+    maxStringBytes?: number;
+    maxArrayLength?: number;
+    maxObjectKeys?: number;
+}
+export type TLiveBrowserLaunchOptions = Omit<NonNullable<IEnvAwareOptions['launchOptions']>, 'signal'>;
+export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'launchOptions'> {
+    launchOptions?: TLiveBrowserLaunchOptions;
+    viewport?: ILiveBrowserViewport;
+    screencast?: ILiveBrowserScreencastOptions;
+    security?: ILiveBrowserSecurityOptions;
+    allowEvaluation?: boolean;
+}
+export interface ILiveBrowserTabState {
+    id: string;
+    url: string;
+    title: string;
+    active: boolean;
+    status: TLiveBrowserTabStatus;
+    generation: number;
+    appliedViewportRevision: number;
+    streaming: boolean;
+}
+export interface ILiveBrowserError {
+    code: string;
+    message: string;
+    fatal: boolean;
+    tabId?: string;
+}
+export interface ILiveBrowserState {
+    status: TLiveBrowserStatus;
+    activeTabId: string | null;
+    viewportRevision: number;
+    viewport: ILiveBrowserViewport;
+    tabs: ILiveBrowserTabState[];
+    lastError?: ILiveBrowserError;
+}
+export interface ILiveBrowserScreencastMetadata {
+    offsetTop: number;
+    pageScaleFactor: number;
+    deviceWidth: number;
+    deviceHeight: number;
+    scrollOffsetX: number;
+    scrollOffsetY: number;
+    timestamp?: number;
+}
+export interface ILiveBrowserFrame {
+    tabId: string;
+    sequence: number;
+    generation: number;
+    viewportRevision: number;
+    viewport: ILiveBrowserViewport;
+    format: TLiveBrowserImageFormat;
+    mimeType: 'image/jpeg' | 'image/png';
+    width: number;
+    height: number;
+    metadata: ILiveBrowserScreencastMetadata;
+    data: Uint8Array;
+}
+export interface ILiveBrowserSnapshot {
+    tabId: string;
+    viewportRevision: number;
+    viewport: ILiveBrowserViewport;
+    format: TLiveBrowserImageFormat;
+    mimeType: 'image/jpeg' | 'image/png';
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export interface ILiveBrowserStateEvent {
+    type: 'state';
+    state: ILiveBrowserState;
+}
+export interface ILiveBrowserFrameEvent {
+    type: 'frame';
+    frame: ILiveBrowserFrame;
+}
+export interface ILiveBrowserErrorEvent {
+    type: 'error';
+    error: ILiveBrowserError;
+}
+export type TLiveBrowserEvent = ILiveBrowserStateEvent | ILiveBrowserFrameEvent | ILiveBrowserErrorEvent;
+export type TLiveBrowserEventListener = (event: TLiveBrowserEvent) => void;
+export interface ILiveBrowserFrameAcknowledgement {
+    accepted: boolean;
+}
+export interface ILiveBrowserFrameAcknowledgementRequest {
+    tabId: string;
+    sequence: number;
+    generation: number;
+    viewportRevision: number;
+}
+export interface ILiveBrowserCreateTabOptions {
+    url?: string;
+    activate?: boolean;
+    timeoutMs?: number;
+    waitUntil?: TLiveBrowserWaitUntil;
+}
+export interface ILiveBrowserNavigationOptions {
+    tabId?: string;
+    timeoutMs?: number;
+    waitUntil?: TLiveBrowserWaitUntil;
+}
+export interface ILiveBrowserNavigateOptions extends ILiveBrowserNavigationOptions {
+    url: string;
+}
+export interface ILiveBrowserModifierState {
+    alt?: boolean;
+    control?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+}
+export interface ILiveBrowserInputBase {
+    tabId: string;
+    generation: number;
+    viewportRevision: number;
+}
+export interface ILiveBrowserMouseInput extends ILiveBrowserInputBase {
+    type: 'move' | 'down' | 'up';
+    x: number;
+    y: number;
+    button?: 'none' | 'left' | 'middle' | 'right' | 'back' | 'forward';
+    buttons?: number;
+    clickCount?: number;
+    modifiers?: ILiveBrowserModifierState;
+}
+export interface ILiveBrowserWheelInput extends ILiveBrowserInputBase {
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+    modifiers?: ILiveBrowserModifierState;
+}
+export interface ILiveBrowserKeyInput extends ILiveBrowserInputBase {
+    type: 'down' | 'up';
+    key: string;
+    code?: string;
+    text?: string;
+    unmodifiedText?: string;
+    windowsVirtualKeyCode?: number;
+    nativeVirtualKeyCode?: number;
+    autoRepeat?: boolean;
+    isKeypad?: boolean;
+    location?: number;
+    modifiers?: ILiveBrowserModifierState;
+}
+export interface ILiveBrowserInsertTextInput extends ILiveBrowserInputBase {
+    text: string;
+}
+export interface ILiveBrowserSemanticActionBase extends ILiveBrowserInputBase {
+    selector: string;
+    timeoutMs?: number;
+}
+export interface ILiveBrowserClickOptions extends ILiveBrowserSemanticActionBase {
+    button?: 'left' | 'middle' | 'right';
+    clickCount?: number;
+}
+export interface ILiveBrowserFillOptions extends ILiveBrowserSemanticActionBase {
+    text: string;
+}
+export interface ILiveBrowserPressOptions extends ILiveBrowserSemanticActionBase {
+    key: string;
+}
+export interface ILiveBrowserSnapshotOptions {
+    tabId?: string;
+    format?: TLiveBrowserImageFormat;
+    quality?: number;
+}
+export interface ILiveBrowserObserveOptions {
+    tabId?: string;
+    maxCharacters?: number;
+}
+export interface ILiveBrowserObservation {
+    tabId: string;
+    url: string;
+    title: string;
+    tab: ILiveBrowserTabState;
+    state: ILiveBrowserState;
+    text: string;
+    truncated: boolean;
+}

package/dist_ts/smartpuppeteer.interfaces.livebrowser.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuaW50ZXJmYWNlcy5saXZlYnJvd3Nlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmludGVyZmFjZXMubGl2ZWJyb3dzZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/smartpuppeteer.plugins.d.ts

@@ -1,8 +1,9 @@
+import { Buffer } from 'node:buffer';
 import * as os from 'os';
-export { os };
+export { Buffer, os };
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartshell from '@push.rocks/smartshell';
 export { smartdelay, smartshell };
-import puppeteer from 'puppeteer';
+import * as puppeteer from 'puppeteer';
 import treeKill from 'tree-kill';
 export { puppeteer, treeKill };

package/dist_ts/smartpuppeteer.plugins.js

@@ -1,12 +1,13 @@
 // node native scope
+import { Buffer } from 'node:buffer';
 import * as os from 'os';
-export { os };
+export { Buffer, os };
 // @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartshell from '@push.rocks/smartshell';
 export { smartdelay, smartshell };
 // third party scope
-import puppeteer from 'puppeteer';
+import * as puppeteer from 'puppeteer';
 import treeKill from 'tree-kill';
 export { puppeteer, treeKill };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBRXpCLE9BQU8sRUFBRSxFQUFFLEVBQUUsQ0FBQztBQUVkLG1CQUFtQjtBQUNuQixPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxVQUFVLE1BQU0sd0JBQXdCLENBQUM7QUFFckQsT0FBTyxFQUFFLFVBQVUsRUFBRSxVQUFVLEVBQUUsQ0FBQztBQUVsQyxvQkFBb0I7QUFDcEIsT0FBTyxTQUFTLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sUUFBUSxNQUFNLFdBQVcsQ0FBQztBQUVqQyxPQUFPLEVBQUUsU0FBUyxFQUFFLFFBQVEsRUFBRSxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLEVBQUUsTUFBTSxJQUFJLENBQUM7QUFFekIsT0FBTyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsQ0FBQztBQUV0QixtQkFBbUI7QUFDbkIsT0FBTyxLQUFLLFVBQVUsTUFBTSx3QkFBd0IsQ0FBQztBQUNyRCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBRXJELE9BQU8sRUFBRSxVQUFVLEVBQUUsVUFBVSxFQUFFLENBQUM7QUFFbEMsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxTQUFTLE1BQU0sV0FBVyxDQUFDO0FBQ3ZDLE9BQU8sUUFBUSxNQUFNLFdBQVcsQ0FBQztBQUVqQyxPQUFPLEVBQUUsU0FBUyxFQUFFLFFBQVEsRUFBRSxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartpuppeteer",
-  "version": "2.0.7",
+  "version": "2.2.0",
   "private": false,
   "description": "Provides simplified access to Puppeteer for automation and testing purposes.",
   "main": "dist_ts/index.js",
@@ -8,22 +8,24 @@
   "type": "module",
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsrun": "^2.0.5",
-    "@git.zone/tstest": "^3.6.7",
-    "@types/node": "^25.9.5"
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.2.0"
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.1",
     "@push.rocks/smartshell": "^3.5.0",
-    "puppeteer": "^24.42.0",
+    "puppeteer": "^25.4.0",
     "tree-kill": "^1.2.2"
   },
   "files": [
     "ts/**/*",
     "ts_web/**/*",
-    "dist/**/*",
     "dist_*/**/*",
     "dist_ts/**/*",
     "dist_ts_web/**/*",

package/readme.hints.md

@@ -1 +1,15 @@
- 
+# 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. Pending frames are bounded; drops and all stream invalidation paths must retire and acknowledge entries 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.
+- 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.
+- 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.

package/readme.md

@@ -14,6 +14,8 @@ Install `@push.rocks/smartpuppeteer` with pnpm:
 pnpm add @push.rocks/smartpuppeteer
 ```
 
+Puppeteer 25 requires Node.js 22.12.0 or newer.
+
 ## Usage
 `@push.rocks/smartpuppeteer` simplifies interaction with Puppeteer, providing easier ways to launch Puppeteer instances considering environment constraints, such as running in a CI pipeline or as root, which necessitates certain flags for Chrome.
 
@@ -28,7 +30,11 @@ import { getEnvAwareBrowserInstance, IncognitoBrowser, puppeteer } from '@push.r
 // Usually, you would initialize the browser instance at the start of your script or application logic
 const initializeBrowser = async () => {
   const browser = await getEnvAwareBrowserInstance({
-    forceNoSandbox: true, // A flag useful for certain environments; use it with caution
+    launchOptions: {
+      headless: true,
+      defaultViewport: { width: 1280, height: 720 },
+      args: ['--lang=en-US'],
+    },
   });
   return browser;
 };
@@ -36,6 +42,10 @@ const initializeBrowser = async () => {
 
 `getEnvAwareBrowserInstance()` checks `google-chrome`, `chromium`, and `chromium-browser` in that order. Missing candidates are skipped safely. When none resolve, Puppeteer chooses its default executable.
 
+Caller `launchOptions` are passed to Puppeteer. Caller arguments are retained when the environment requires `--no-sandbox` and `--disable-setuid-sandbox`, and the required arguments are added without duplication. This no-sandbox behavior remains limited to root users, CI environments, or callers that explicitly set `forceNoSandbox`; disabling Chromium's sandbox reduces process isolation. The existing pipe transport remains enabled by default; set `usePipe: false` to request Puppeteer's WebSocket transport. Executable discovery is skipped when `launchOptions.browser`, `launchOptions.channel`, or `launchOptions.executablePath` is present.
+
+Set `requireSandbox: true` when a caller must fail closed instead of accepting the environment-aware no-sandbox behavior. This rejects `forceNoSandbox`, known sandbox-disabling Chromium arguments, and Linux launches as root. It also prevents `CI` from adding no-sandbox arguments. This option prevents SmartPuppeteer from disabling Chromium's sandbox; a successful process launch is still not an independent verification of Chromium's internal sandbox state.
+
 Use `resolveBrowserExecutablePath()` directly when you need to inspect the selected executable or provide your own ordered candidate list:
 
 ```typescript
@@ -89,6 +99,123 @@ useIncognitoBrowser()
 ### Advanced Configuration
 `@push.rocks/smartpuppeteer` allows further customization for launching the Puppeteer browser, such as disabling the sandbox environment (not recommended for production).
 
+### Live Browser Sessions
+
+`LiveBrowserSession` provides a transport-neutral runtime for remote browser and agent adapters. It owns one Chromium process and one default-context profile. All tabs and popups therefore share cookies, local storage, cache, and other profile state. Puppeteer creates an ephemeral profile when neither `launchOptions.userDataDir` nor a `--user-data-dir` argument is supplied. Either explicit form persists potentially sensitive authentication and browsing data, must not be shared concurrently between Chromium processes, and must be protected by the caller.
+
+```typescript
+import {
+  LiveBrowserSession,
+  type ILiveBrowserFrame,
+} from '@push.rocks/smartpuppeteer';
+
+const session = new LiveBrowserSession({
+  viewport: {
+    width: 1280,
+    height: 720,
+    deviceScaleFactor: 1,
+  },
+  screencast: {
+    format: 'jpeg',
+    quality: 80,
+    maxWidth: 1280,
+    maxHeight: 720,
+  },
+  launchOptions: {
+    headless: true,
+    // userDataDir: '/explicit/profile/path',
+  },
+});
+
+const unsubscribe = session.onEvent((event) => {
+  if (event.type !== 'frame') {
+    return;
+  }
+  const frame: ILiveBrowserFrame = event.frame;
+  console.log(frame.mimeType, frame.data.byteLength);
+  void session.acknowledgeFrame({
+    tabId: frame.tabId,
+    sequence: frame.sequence,
+    generation: frame.generation,
+    viewportRevision: frame.viewportRevision,
+  });
+});
+
+await session.start();
+try {
+  const state = session.getState();
+  const tabId = state.activeTabId!;
+
+  await session.navigate({
+    tabId,
+    url: 'data:text/html,<title>Live session</title><button>Continue</button>',
+  });
+
+  const observation = await session.observe({ tabId });
+  console.log(observation.text);
+
+  const currentState = session.getState();
+  const currentTab = currentState.tabs.find((tab) => tab.id === tabId)!;
+  await session.click({
+    tabId,
+    generation: currentTab.generation,
+    viewportRevision: currentState.viewportRevision,
+    selector: 'button',
+  });
+} finally {
+  unsubscribe();
+  await session.stop();
+}
+```
+
+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.
+
+The live API includes:
+
+- Lifecycle and state: `start()`, `stop()`, `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
+- Capture and observation: `captureSnapshot()` returns viewport-only JPEG or PNG bytes; `observe()` returns bounded URL, title, tab state, and textual accessibility content without image bytes
+- Optional evaluation: `evaluate()` returns bounded JSON values when the session explicitly sets `allowEvaluation: true`
+
+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.
+
+Optional browser guards can be enabled when composing a higher-level runtime:
+
+```typescript
+const guardedSession = new LiveBrowserSession({
+  requireSandbox: true,
+  security: {
+    denyDownloads: true,
+    denyFileChoosers: true,
+    denyPermissions: true,
+    httpNavigationOnly: true,
+  },
+});
+```
+
+`denyDownloads` installs a default-context download denial at launch. `denyPermissions` applies an empty browser-wide permission grant before the first page is exposed, causing unlisted permissions to be denied. `denyFileChoosers` installs persistent CDP cancellation on each registered page. `httpNavigationOnly` limits URLs passed to `createTab()` and `navigate()` to `http:` and `https:`; it does not inspect or rewrite renderer-initiated navigation.
+
+Evaluation is disabled by default. Once enabled, it accepts a JavaScript expression, runs it in a dedicated main-frame isolated world, awaits its result, and returns only JSON-compatible values:
+
+```typescript
+const evaluationSession = new LiveBrowserSession({ allowEvaluation: true });
+await evaluationSession.start();
+const result = await evaluationSession.evaluate(
+  `({ title: document.title, links: document.links.length })`,
+  { timeoutMs: 2000, maxOutputBytes: 65536 },
+);
+```
+
+The default evaluation limits are a 5-second timeout, 256 KiB transferred output, depth 16, 10,000 total nodes, 64 KiB per string or key, 1,000 array entries, and 1,000 object keys. Hard ceilings are 30 seconds, 1 MiB output, depth 32, 50,000 nodes, 256 KiB per string or key, and 10,000 array entries or object keys. Expressions are limited to 256 KiB of UTF-8 source. Results reject non-finite numbers, `undefined`, bigint, symbols, functions, sparse or extended arrays, accessors, non-plain objects, cycles, and repeated object references. Output is normalized and measured inside the renderer before bounded JSON text is transferred, then measured again before host parsing.
+
+`evaluate()` is trusted-caller code execution, not a JavaScript sandbox. An expression can mutate or navigate the page, initiate network activity, consume renderer resources, or crash the renderer. User-started asynchronous work can outlive a returned result, timeout, or caller cancellation; a higher-level runtime that requires strict quiescence must stop or quarantine the browser. Keep evaluation disabled unless a higher-level policy explicitly authorizes it.
+
+`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.
+
 ### 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.0.7',
+  version: '2.2.0',
   description: 'Provides simplified access to Puppeteer for automation and testing purposes.'
 }

package/ts/index.ts

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