@push.rocks/smartpuppeteer 2.2.0 → 2.4.0

package/dist_ts/smartpuppeteer.helpers.process.d.ts

@@ -0,0 +1,14 @@
+export interface IOwnedProcessIdentity {
+    pid: number;
+    parentPid: number;
+    processGroupId: number;
+    sessionId: number;
+    startTime: string;
+    state: string;
+}
+export declare const readOwnedProcessIdentity: (pid: number) => Promise<IOwnedProcessIdentity | undefined>;
+export declare const listOwnedProcessGroupMembers: (rootIdentity: IOwnedProcessIdentity) => Promise<IOwnedProcessIdentity[]>;
+export declare const killFrozenOwnedProcessGroup: (rootIdentity: IOwnedProcessIdentity) => boolean;
+export declare const signalOwnedProcessGroup: (rootIdentity: IOwnedProcessIdentity, signal: NodeJS.Signals) => Promise<boolean>;
+export declare const signalOwnedProcessIdentity: (identity: IOwnedProcessIdentity, signal: NodeJS.Signals) => Promise<boolean>;
+export declare const delay: (milliseconds: number) => Promise<void>;

package/dist_ts/smartpuppeteer.helpers.process.js

@@ -0,0 +1,132 @@
+import * as plugins from './smartpuppeteer.plugins.js';
+const maxOwnedGroupProcesses = 4096;
+const maxVisibleProcesses = 65536;
+const processReadBatchSize = 64;
+const parseProcessStat = (pid, stat) => {
+    const commandEnd = stat.lastIndexOf(')');
+    if (commandEnd < 0) {
+        throw new Error(`Unable to parse process identity for PID ${pid}`);
+    }
+    const fields = stat.slice(commandEnd + 2).trim().split(/\s+/);
+    const state = fields[0];
+    const parentPid = Number(fields[1]);
+    const processGroupId = Number(fields[2]);
+    const sessionId = Number(fields[3]);
+    const startTime = fields[19];
+    if (typeof state !== 'string'
+        || state.length !== 1
+        || !Number.isInteger(parentPid)
+        || parentPid < 0
+        || !Number.isInteger(processGroupId)
+        || processGroupId < 0
+        || !Number.isInteger(sessionId)
+        || sessionId < 0
+        || typeof startTime !== 'string'
+        || !/^[0-9]+$/.test(startTime)) {
+        throw new Error(`Unable to parse process identity for PID ${pid}`);
+    }
+    return { pid, parentPid, processGroupId, sessionId, startTime, state };
+};
+export const readOwnedProcessIdentity = async (pid) => {
+    if (process.platform !== 'linux') {
+        throw new Error('Confirmed browser process ownership is supported on Linux only');
+    }
+    try {
+        const stat = await plugins.fs.promises.readFile(`/proc/${pid}/stat`, 'utf8');
+        return parseProcessStat(pid, stat);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT'
+            || error.code === 'ESRCH') {
+            return undefined;
+        }
+        throw error;
+    }
+};
+const listProcessIdentities = async () => {
+    const entries = await plugins.fs.promises.readdir('/proc', { withFileTypes: true });
+    const pids = entries
+        .filter((entry) => entry.isDirectory() && /^[0-9]+$/.test(entry.name))
+        .map((entry) => Number(entry.name));
+    if (pids.length > maxVisibleProcesses) {
+        throw new Error(`Refusing to inspect more than ${maxVisibleProcesses} processes`);
+    }
+    const identities = [];
+    for (let index = 0; index < pids.length; index += processReadBatchSize) {
+        identities.push(...await Promise.all(pids.slice(index, index + processReadBatchSize).map((pid) => readOwnedProcessIdentity(pid))));
+    }
+    return identities.filter((identity) => Boolean(identity));
+};
+export const listOwnedProcessGroupMembers = async (rootIdentity) => {
+    const currentRoot = await readOwnedProcessIdentity(rootIdentity.pid);
+    if (currentRoot && currentRoot.startTime !== rootIdentity.startTime) {
+        throw new Error('The owned browser PID was reused by another process');
+    }
+    if (currentRoot
+        && (currentRoot.processGroupId !== rootIdentity.processGroupId
+            || currentRoot.sessionId !== rootIdentity.sessionId)) {
+        throw new Error('The owned browser process changed its process-group identity');
+    }
+    const members = (await listProcessIdentities()).filter((identity) => (identity.processGroupId === rootIdentity.processGroupId
+        && identity.sessionId === rootIdentity.sessionId));
+    if (members.length > maxOwnedGroupProcesses) {
+        throw new Error(`Owned browser process group exceeded ${maxOwnedGroupProcesses} processes`);
+    }
+    return members;
+};
+export const killFrozenOwnedProcessGroup = (rootIdentity) => {
+    try {
+        process.kill(-rootIdentity.processGroupId, 'SIGKILL');
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH') {
+            return false;
+        }
+        throw error;
+    }
+};
+export const signalOwnedProcessGroup = async (rootIdentity, signal) => {
+    const currentRoot = await readOwnedProcessIdentity(rootIdentity.pid);
+    if (!currentRoot) {
+        return false;
+    }
+    if (currentRoot.startTime !== rootIdentity.startTime
+        || currentRoot.processGroupId !== rootIdentity.processGroupId
+        || currentRoot.sessionId !== rootIdentity.sessionId) {
+        throw new Error('Refusing to signal a reused browser process-group leader');
+    }
+    try {
+        process.kill(-rootIdentity.processGroupId, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH') {
+            return false;
+        }
+        throw error;
+    }
+};
+export const signalOwnedProcessIdentity = async (identity, signal) => {
+    const currentIdentity = await readOwnedProcessIdentity(identity.pid);
+    if (!currentIdentity) {
+        return false;
+    }
+    if (currentIdentity.startTime !== identity.startTime) {
+        throw new Error(`Refusing to signal reused PID ${identity.pid}`);
+    }
+    try {
+        process.kill(identity.pid, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH') {
+            return false;
+        }
+        throw error;
+    }
+};
+export const delay = async (milliseconds) => {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRwdXBwZXRlZXIuaGVscGVycy5wcm9jZXNzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvc21hcnRwdXBwZXRlZXIuaGVscGVycy5wcm9jZXNzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sNkJBQTZCLENBQUM7QUFXdkQsTUFBTSxzQkFBc0IsR0FBRyxJQUFJLENBQUM7QUFDcEMsTUFBTSxtQkFBbUIsR0FBRyxLQUFLLENBQUM7QUFDbEMsTUFBTSxvQkFBb0IsR0FBRyxFQUFFLENBQUM7QUFFaEMsTUFBTSxnQkFBZ0IsR0FBRyxDQUFDLEdBQVcsRUFBRSxJQUFZLEVBQXlCLEVBQUU7SUFDNUUsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUN6QyxJQUFJLFVBQVUsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUNuQixNQUFNLElBQUksS0FBSyxDQUFDLDRDQUE0QyxHQUFHLEVBQUUsQ0FBQyxDQUFDO0lBQ3JFLENBQUM7SUFDRCxNQUFNLE1BQU0sR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLFVBQVUsR0FBRyxDQUFDLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLENBQUM7SUFDOUQsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3hCLE1BQU0sU0FBUyxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUNwQyxNQUFNLGNBQWMsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDekMsTUFBTSxTQUFTLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3BDLE1BQU0sU0FBUyxHQUFHLE1BQU0sQ0FBQyxFQUFFLENBQUMsQ0FBQztJQUM3QixJQUNFLE9BQU8sS0FBSyxLQUFL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

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

@@ -3,6 +3,8 @@ export type TLiveBrowserStatus = 'stopped' | 'starting' | 'running' | 'stopping'
 export type TLiveBrowserImageFormat = 'jpeg' | 'png';
 export type TLiveBrowserTabStatus = 'open' | 'crashed';
 export type TLiveBrowserWaitUntil = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+export declare const liveBrowserDefaultMaxOutstandingFrames = 3;
+export declare const liveBrowserMaxOutstandingFrames = 64;
 export interface ILiveBrowserViewport {
     width: number;
     height: number;
@@ -14,12 +16,18 @@ export interface ILiveBrowserScreencastOptions {
     maxWidth?: number;
     maxHeight?: number;
     everyNthFrame?: number;
+    maxOutstandingFrames?: number;
 }
 export interface ILiveBrowserSecurityOptions {
     denyDownloads?: boolean;
     denyFileChoosers?: boolean;
     denyPermissions?: boolean;
     httpNavigationOnly?: boolean;
+    proxyCredentials?: ILiveBrowserProxyCredentials;
+}
+export interface ILiveBrowserProxyCredentials {
+    username: string;
+    password: string;
 }
 export interface ILiveBrowserOperationOptions {
     signal?: AbortSignal;
@@ -45,6 +53,24 @@ export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'laun
     security?: ILiveBrowserSecurityOptions;
     allowEvaluation?: boolean;
 }
+export interface ILiveBrowserProcessState {
+    generation: number;
+    pid: number | null;
+    processGroupId: number | null;
+    running: boolean;
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+}
+export interface ILiveBrowserTerminationOptions {
+    gracefulTimeoutMs?: number;
+    forceTimeoutMs?: number;
+}
+export interface ILiveBrowserTerminationResult extends ILiveBrowserProcessState {
+    forced: boolean;
+    shutdownComplete: boolean;
+    confirmedDead: boolean;
+    errors: string[];
+}
 export interface ILiveBrowserTabState {
     id: string;
     url: string;

package/dist_ts/smartpuppeteer.interfaces.livebrowser.js

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

package/dist_ts/smartpuppeteer.plugins.d.ts

@@ -1,6 +1,8 @@
 import { Buffer } from 'node:buffer';
-import * as os from 'os';
-export { Buffer, os };
+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 smartdelay from '@push.rocks/smartdelay';
 import * as smartshell from '@push.rocks/smartshell';
 export { smartdelay, smartshell };

package/dist_ts/smartpuppeteer.plugins.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartpuppeteer",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "private": false,
   "description": "Provides simplified access to Puppeteer for automation and testing purposes.",
   "main": "dist_ts/index.js",
@@ -19,8 +19,8 @@
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.1",
-    "@push.rocks/smartshell": "^3.5.0",
-    "puppeteer": "^25.4.0",
+    "@push.rocks/smartshell": "^4.1.0",
+    "puppeteer": "^25.5.0",
     "tree-kill": "^1.2.2"
   },
   "files": [

package/readme.hints.md

@@ -3,7 +3,7 @@
 - `getEnvAwareBrowserInstance()` is the only Chromium launch path. Merge caller arguments before adding environment-required sandbox arguments, retain the pipe default, and do not run executable discovery when the caller selected a browser, channel, or executable.
 - `LiveBrowserSession` uses the browser's default context so all tabs and popups share one profile. Omitting both `launchOptions.userDataDir` and a `--user-data-dir` argument intentionally relies on Puppeteer's ephemeral profile lifecycle.
 - CDP is private to the live runtime. Public contracts contain transport-neutral values and `Uint8Array` image data, never `CDPSession`, raw CDP frame IDs, or base64 image strings.
-- Every published screencast frame has one private sequence-to-CDP acknowledgement entry. Public acknowledgement requires matching tab ID, sequence, generation, and viewport revision. Pending frames are bounded; drops and all stream invalidation paths must retire and acknowledge entries before detaching the CDP session.
+- Every published screencast frame has one private sequence-to-CDP acknowledgement entry. Public acknowledgement requires matching tab ID, sequence, generation, and viewport revision. `screencast.maxOutstandingFrames` bounds those entries independently of any application transport window; overflow retires oldest-first. Drops and all stream invalidation paths must issue each CDP acknowledgement at most once and await in-flight acknowledgements before detaching the CDP session.
 - Activation, viewport changes, navigation, tab closure, snapshots, observations, semantic actions, and shutdown share one bounded operation scheduler. Raw input and frame acknowledgement remain direct, but must validate active tab, generation, and viewport revision. Repeated internal navigation/load state updates are coalesced per tab, and shutdown cancels queued work.
 - Retain the scheduler-owned launch `AbortController` for the full browser lifetime. Shutdown aborts both the active operation and Chromium itself so a non-signal-aware Puppeteer command or disabled protocol timeout cannot retain the browser ahead of queued cleanup.
 - Viewport revision starts at 1 and advances only after `Page.setViewport()` succeeds. Stop and flush the active screencast before applying a viewport or navigation mutation, then restart it with a new generation.

package/readme.md

@@ -120,6 +120,8 @@ const session = new LiveBrowserSession({
     quality: 80,
     maxWidth: 1280,
     maxHeight: 720,
+    everyNthFrame: 1,
+    maxOutstandingFrames: 3,
   },
   launchOptions: {
     headless: true,
@@ -168,11 +170,13 @@ try {
 }
 ```
 
-Only the active tab is streamed. Frames carry a session-monotonic sequence, tab/CDP generation, viewport revision, viewport, MIME type, encoded dimensions, screencast metadata, and binary `Uint8Array` data. Every delivered frame must be acknowledged with all four identity fields. A delivered frame remains pending until it is acknowledged, dropped, or retired by the runtime; mismatched, duplicate, stale, retired, or operationally failed acknowledgements return `{ accepted: false }`. Operational acknowledgement failures also emit an `error` event whose code is `frame_acknowledgement_failed`. The runtime bounds pending frames and CDP-acknowledges an oldest frame when it must be dropped. Tab switches, navigation, resize, page cleanup, disconnect, and shutdown retire pending frames and acknowledge them while their CDP session remains available.
+Only the active tab is streamed. Frames carry a session-monotonic sequence, tab/CDP generation, viewport revision, viewport, MIME type, encoded dimensions, screencast metadata, and binary `Uint8Array` data. Every delivered frame must be acknowledged with all four identity fields. A delivered frame remains pending until it is acknowledged, dropped, or retired by the runtime; mismatched, duplicate, stale, retired, or operationally failed acknowledgements return `{ accepted: false }`. Operational acknowledgement failures also emit an `error` event whose code is `frame_acknowledgement_failed`. `screencast.maxOutstandingFrames` is an integer from 1 through `liveBrowserMaxOutstandingFrames` (64) and defaults to `liveBrowserDefaultMaxOutstandingFrames` (3). At capacity, SmartPuppeteer retires and CDP-acknowledges the oldest pending frame before publishing the next one. Tab switches, navigation, resize, page cleanup, disconnect, and shutdown also retire pending frames and await their single CDP acknowledgement attempt before detaching the screencast session.
+
+The SmartPuppeteer outstanding-frame bound covers only the private frame-to-`Page.screencastFrameAck` lifecycle. It is not a binary transport window, and `acknowledgeFrame()` is not an application transport acknowledgement. A higher-level runtime must maintain and bound its application frame window separately. Screencast `format` accepts `jpeg` or `png`, `quality` accepts integers from 0 through 100, `maxWidth` and `maxHeight` accept integers from 1 through 4096 subject to an 8,294,400-pixel combined ceiling, and `everyNthFrame` accepts integers from 1 through 100.
 
 The live API includes:
 
-- Lifecycle and state: `start()`, `stop()`, `onEvent()`, and `getState()`
+- Lifecycle and state: `start()`, `stop()`, `terminate()`, `getProcessState()`, `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
@@ -188,17 +192,31 @@ Optional browser guards can be enabled when composing a higher-level runtime:
 ```typescript
 const guardedSession = new LiveBrowserSession({
   requireSandbox: true,
+  launchOptions: {
+    args: [
+      '--proxy-server=http://127.0.0.1:8080',
+      '--proxy-bypass-list=<-loopback>',
+    ],
+  },
   security: {
     denyDownloads: true,
     denyFileChoosers: true,
     denyPermissions: true,
     httpNavigationOnly: true,
+    proxyCredentials: {
+      username: 'proxy-user',
+      password: 'proxy-password',
+    },
   },
 });
 ```
 
 `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.
 
+`proxyCredentials` handles authenticated-proxy challenges for existing and future page and dedicated-worker traffic. SmartPuppeteer supplies credentials only when CDP identifies the challenge source as `Proxy`; origin-server and unknown challenges are cancelled without credentials, and a repeated challenge for the same request is cancelled. Setup commands are queued from Puppeteer's public CDP session-attachment event before Puppeteer resumes a new target. Setup failure rejects `start()` and closes the browser. During a running session, an unexpected browser security-session detach, a live target without a protected replacement session, or a proxy protocol failure is fatal and requests termination; Linux termination is confirmed only when `terminate()` resolves. The caller still owns proxy selection, Chromium proxy arguments, bypass rules, DNS behavior, egress policy, and proxy trust. Credentials remain in process memory for the session lifetime.
+
+On Linux, Puppeteer launches Chromium as a dedicated process-group and session leader. `getProcessState()` reports the generation, root PID, process-group ID, and Node.js exit state. `terminate({ gracefulTimeoutMs, forceTimeoutMs })` is idempotent for concurrent callers, first requests normal shutdown, then freezes and kills the owned process group if the graceful deadline expires. It resolves with `confirmedDead: true` only after `/proc` contains no member of that owned process group, the Node.js child exit is observed, and session shutdown settles. PID reuse, permission failures, surviving members, or an unsettled shutdown reject confirmation and keep restart blocked. Confirmed process-group termination is Linux-only; use `stop()` for portable best-effort lifecycle cleanup.
+
 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

package/ts/00_commitinfo_data.ts

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