@push.rocks/smartpuppeteer 2.0.6 → 2.1.0

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

@@ -2,5 +2,7 @@ import * as plugins from './smartpuppeteer.plugins.js';
 export interface IEnvAwareOptions {
     forceNoSandbox?: 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,37 +1,62 @@
 import * as plugins from './smartpuppeteer.plugins.js';
+export const resolveBrowserExecutablePath = (candidateNamesArg = [
+    'google-chrome',
+    'chromium',
+    'chromium-browser',
+]) => {
+    for (const candidateName of candidateNamesArg) {
+        const executablePath = plugins.smartshell.which.sync(candidateName, {
+            nothrow: true,
+        });
+        if (executablePath) {
+            return executablePath;
+        }
+    }
+    return undefined;
+};
 export const getEnvAwareBrowserInstance = async (optionsArg = {}) => {
     const options = {
         forceNoSandbox: false,
         ...optionsArg,
     };
-    let chromeArgs = [];
+    const launchOptions = options.launchOptions ?? {};
+    let chromeArgs = [...(launchOptions.args ?? [])];
     if (process.env.CI ||
         options.forceNoSandbox ||
         plugins.os.userInfo().username === 'root') {
-        chromeArgs = chromeArgs.concat(['--no-sandbox', '--disable-setuid-sandbox']);
+        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 = plugins.smartshell.which.sync('google-chrome') ||
-        plugins.smartshell.which.sync('chromium') ||
-        plugins.smartshell.which.sync('chromium-browser');
+    // 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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuY2xhc3Nlcy5zbWFydHB1cHBldGVlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmNsYXNzZXMuc21hcnRwdXBwZXRlZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSw2QkFBNkIsQ0FBQztBQU92RCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxLQUFLLEVBQzdDLGFBQStCLEVBQUUsRUFDRyxFQUFFO0lBQ3RDLE1BQU0sT0FBTyxHQUFxQjtRQUNoQyxjQUFjLEVBQUUsS0FBSztRQUNyQixHQUFHLFVBQVU7S0FDZCxDQUFDO0lBRUYsSUFBSSxVQUFVLEdBQWEsRUFBRSxDQUFDO0lBQzlCLElBQ0UsT0FBTyxDQUFDLEdBQUcsQ0FBQyxFQUFFO1FBQ2QsT0FBTyxDQUFDLGNBQWM7UUFDdEIsT0FBTyxDQUFDLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxRQUFRLEtBQUssTUFBTSxFQUN6QyxDQUFDO1FBQ0QsVUFBVSxHQUFHLFVBQVUsQ0FBQyxNQUFNLENBQUMsQ0FBQyxjQUFjLEVBQUUsMEJBQTBCLENBQUMsQ0FBQyxDQUFDO1FBQzdFLE9BQU8sQ0FBQyxJQUFJLENBQUMsMERBQTBELENBQUMsQ0FBQztRQUN6RSxPQUFPLENBQUMsSUFBSSxDQUFDLG1FQUFtRSxDQUFDLENBQUM7UUFDbEYsT0FBTyxDQUFDLElBQUksQ0FBQywwREFBMEQsQ0FBQyxDQUFDO0lBQzNFLENBQUM7SUFFRCwrR0FBK0c7SUFDL0csTUFBTSxRQUFRLEdBQ1osT0FBTyxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLGVBQWUsQ0FBQztRQUM5QyxPQUFPLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDO1FBQ3pDLE9BQU8sQ0FBQyxVQUFVLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxrQkFBa0IsQ0FBQyxDQUFDO0lBRXBELE1BQU0scUJBQXFCLEdBQUcsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLGNBQWMsRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBRTNFLE9BQU8sQ0FBQyxHQUFHLENBQUMsNkNBQTZDLENBQUMsQ0FBQztJQUMzRCxPQUFPLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQ3hCLElBQUksUUFBUSxFQUFFLENBQUM7UUFDYixPQUFPLENBQUMsR0FBRyxDQUFDLHFCQUFxQixRQUFRLEVBQUUsQ0FBQyxDQUFDO0lBQy9DLENBQUM7U0FBTSxDQUFDO1FBQ04sT0FBTyxDQUFDLEdBQUcsQ0FBQywwRUFBMEUsQ0FBQyxDQUFDO0lBQzFGLENBQUM7SUFFRCxNQUFNLGVBQWUsR0FBRyxNQUFNLE9BQU8sQ0FBQyxTQUFTLENBQUMsTUFBTSxDQUFDO1FBQ3JELElBQUksRUFBRSxVQUFVO1FBQ2hCLElBQUksRUFBRSxPQUFPLENBQUMsT0FBTyxJQUFJLElBQUk7UUFDN0IsUUFBUSxFQUFFLElBQUk7UUFDZCxHQUFHLHFCQUFxQjtLQUN6QixDQUFDLENBQUM7SUFFSCxPQUFPLGVBQWUsQ0FBQztBQUN6QixDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuY2xhc3Nlcy5zbWFydHB1cHBldGVlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0cHVwcGV0ZWVyLmNsYXNzZXMuc21hcnRwdXBwZXRlZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSw2QkFBNkIsQ0FBQztBQVF2RCxNQUFNLENBQUMsTUFBTSw0QkFBNEIsR0FBRyxDQUMxQyxvQkFBOEI7SUFDNUIsZUFBZTtJQUNmLFVBQVU7SUFDVixrQkFBa0I7Q0FDbkIsRUFDbUIsRUFBRTtJQUN0QixLQUFLLE1BQU0sYUFBYSxJQUFJLGlCQUFpQixFQUFFLENBQUM7UUFDOUMsTUFBTSxjQUFjLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLGFBQWEsRUFBRTtZQUNsRSxPQUFPLEVBQUUsSUFBSTtTQUNkLENBQUMsQ0FBQztRQUNILElBQUksY0FBYyxFQUFFLENBQUM7WUFDbkIsT0FBTyxjQUFjLENBQUM7UUFDeEIsQ0FBQztJQUNILENBQUM7SUFDRCxPQUFPLFNBQVMsQ0FBQztBQUNuQixDQUFDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxLQUFLLEVBQzdDLGFBQStCLEVBQUUsRUFDRyxFQUFFO0lBQ3RDLE1BQU0sT0FBTyxHQUFxQjtRQUNoQyxjQUFjLEVBQUUsS0FBSztRQUNyQixHQUFHLFVBQVU7S0FDZCxDQUFDO0lBRUYsTUFBTSxhQUFhLEdBQUcsT0FBTyxDQUFDLGFBQWEsSUFBSSxFQUFFLENBQUM7SUFDbEQsSUFBSSxVQUFVLEdBQWEsQ0FBQyxHQUFHLENBQUMsYUFBYSxDQUFDLElBQUksSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQzNELElBQ0UsT0FBTyxDQUFDLEdBQUcsQ0FBQyxFQUFFO1FBQ2QsT0FBTyxDQUFDLGNBQWM7UUFDdEIsT0FBTyxDQUFDLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxRQUFRLEtBQUssTUFBTSxFQUN6QyxDQUFDO1FBQ0QsS0FBSyxNQUFNLFVBQVUsSUFBSSxDQUFDLGNBQWMsRUFBRSwwQkFBMEIsQ0FBQyxFQUFFLENBQUM7WUFDdEUsSUFBSSxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FBQztnQkFDckMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsQ0FBQztZQUM5QixDQUFDO1FBQ0gsQ0FBQztRQUNELE9BQU8sQ0FBQyxJQUFJLENBQUMsMERBQTBELENBQUMsQ0FBQztRQUN6RSxPQUFPLENBQUMsSUFBSSxDQUFDLG1FQUFtRSxDQUFDLENBQUM7UUFDbEYsT0FBTyxDQUFDLElBQUksQ0FBQywwREFBMEQsQ0FBQyxDQUFDO0lBQzNFLENBQUM7SUFFRCw4RUFBOEU7SUFDOUUsTUFBTSxxQkFBcUIsR0FDekIsYUFBYSxDQUFDLE9BQU8sS0FBSyxTQUFTO1dBQ2hDLGFBQWEsQ0FBQyxPQUFPLEtBQUssU0FBUztXQUNuQyxhQUFhLENBQUMsY0FBYyxLQUFLLFNBQVMsQ0FBQztJQUNoRCxNQUFNLFFBQVEsR0FBRyxxQkFBcUIsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyw0QkFBNEIsRUFBRSxDQUFDO0lBRXBGLE1BQU0scUJBQXFCLEdBQUcsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLGNBQWMsRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBRTNFLE9BQU8sQ0FBQyxHQUFHLENBQUMsNkNBQTZDLENBQUMsQ0FBQztJQUMzRCxPQUFPLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQ3hCLElBQUksUUFBUSxFQUFFLENBQUM7UUFDYixPQUFPLENBQUMsR0FBRyxDQUFDLHFCQUFxQixRQUFRLEVBQUUsQ0FBQyxDQUFDO0lBQy9DLENBQUM7U0FBTSxJQUFJLHFCQUFxQixFQUFFLENBQUM7UUFDakMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxxREFBcUQsQ0FBQyxDQUFDO0lBQ3JFLENBQUM7U0FBTSxDQUFDO1FBQ04sT0FBTyxDQUFDLEdBQUcsQ0FBQywwRUFBMEUsQ0FBQyxDQUFDO0lBQzFGLENBQUM7SUFFRCxNQUFNLGVBQWUsR0FBRyxNQUFNLE9BQU8sQ0FBQyxTQUFTLENBQUMsTUFBTSxDQUFDO1FBQ3JELFFBQVEsRUFBRSxJQUFJO1FBQ2QsR0FBRyxhQUFhO1FBQ2hCLElBQUksRUFBRSxVQUFVO1FBQ2hCLElBQUksRUFBRSxPQUFPLENBQUMsT0FBTyxJQUFJLGFBQWEsQ0FBQyxJQUFJLElBQUksSUFBSTtRQUNuRCxHQUFHLHFCQUFxQjtLQUN6QixDQUFDLENBQUM7SUFFSCxPQUFPLGVBQWUsQ0FBQztBQUN6QixDQUFDLENBQUMifQ==

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

@@ -0,0 +1,191 @@
+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 type TLiveBrowserLaunchOptions = Omit<NonNullable<IEnvAwareOptions['launchOptions']>, 'signal'>;
+export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'launchOptions'> {
+    launchOptions?: TLiveBrowserLaunchOptions;
+    viewport?: ILiveBrowserViewport;
+    screencast?: ILiveBrowserScreencastOptions;
+}
+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.6",
+  "version": "2.1.0",
   "private": false,
   "description": "Provides simplified access to Puppeteer for automation and testing purposes.",
   "main": "dist_ts/index.js",
@@ -8,28 +8,24 @@
   "type": "module",
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
-  "scripts": {
-    "test": "tstest test/",
-    "format": "gitzone format",
-    "build": "tsbuild --web",
-    "buildDocs": "tsdoc"
+  "engines": {
+    "node": ">=22.12.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsrun": "^2.0.3",
-    "@git.zone/tstest": "^3.6.3",
-    "@types/node": "^25.6.0"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.1.2"
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.1",
-    "@push.rocks/smartshell": "^3.3.8",
-    "puppeteer": "^24.42.0",
+    "@push.rocks/smartshell": "^3.5.0",
+    "puppeteer": "^25.4.0",
     "tree-kill": "^1.2.2"
   },
   "files": [
     "ts/**/*",
     "ts_web/**/*",
-    "dist/**/*",
     "dist_*/**/*",
     "dist_ts/**/*",
     "dist_ts_web/**/*",
@@ -56,5 +52,11 @@
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartpuppeteer.git"
+  },
+  "scripts": {
+    "test": "tstest test/",
+    "format": "gitzone format",
+    "build": "tsbuild --web",
+    "buildDocs": "tsdoc"
   }
-}
+}

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

@@ -1,19 +1,21 @@
 # @push.rocks/smartpuppeteer
-simplified access to puppeteer
 
-## Install
-To install `@push.rocks/smartpuppeteer` in your project, run the following command using npm:
+Simplified access to Puppeteer with environment-aware browser startup helpers.
 
-```sh
-npm install @push.rocks/smartpuppeteer --save
-```
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-Or using yarn:
+## Install
+
+Install `@push.rocks/smartpuppeteer` with pnpm:
 
 ```sh
-yarn add @push.rocks/smartpuppeteer
+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,12 +30,31 @@ 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;
 };
 ```
 
+`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.
+
+Use `resolveBrowserExecutablePath()` directly when you need to inspect the selected executable or provide your own ordered candidate list:
+
+```typescript
+import { resolveBrowserExecutablePath } from '@push.rocks/smartpuppeteer';
+
+const executablePath: string | undefined = resolveBrowserExecutablePath([
+  'chromium',
+  'chromium-browser',
+]);
+```
+
 ### Opening a Page and Navigating
 After obtaining a browser instance, you commonly want to open a page and navigate to a URL:
 
@@ -76,6 +97,89 @@ 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
+
+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.
+
+`LiveBrowserSession` is a browser runtime, not a security policy layer. It does not authenticate callers, authorize actions, restrict URLs, or enforce network/egress policy. 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:
 
@@ -115,19 +219,21 @@ incognitoBrowser.start()
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartpuppeteer',
-  version: '2.0.6',
+  version: '2.1.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';