feat: support external browser + page in puppeteer options

[Adi1231234]

Adds support for passing a pre-existing browser and page via options.puppeteer, so the Client can work with a browser you already control (e.g. Electron's built-in Chromium, or a shared browser pool).

When both browser and page are provided, the Client skips puppeteer.launch() / puppeteer.connect() and uses them directly. Existing behavior is unchanged when these options are not set.

What changed

initialize() - new if branch before the existing browserWSEndpoint check:

if (puppeteerOpts.browser && puppeteerOpts.page) {
    browser = puppeteerOpts.browser;
    page = puppeteerOpts.page;
}

destroy() / logout() - use browser.process() to decide cleanup:

• process() !== null (we launched it) -> browser.close() as before
• process() === null (external browser) -> browser.disconnect() only

Without this, browser.close() sends CDP Browser.close which kills the entire external browser, not just this client's session. disconnect() only closes the WebSocket, leaving the browser running.

This is the same pattern puppeteer uses internally in Symbol.dispose.

Example

const browser = await puppeteer.connect({ browserWSEndpoint: '...' });
const page = /* your page */;

const client = new Client({
    puppeteer: { browser, page }
});
await client.initialize();

Backwards compatibility

Fully backwards compatible. The new branch only triggers when both browser and page are explicitly passed in puppeteer options - existing users see no behavior change.

[Adi1231234]

@sofi-ans Can you check this PR? 🙏

[sofi-ans]

@sofi-ans Can you check this PR? 🙏

LGTM. One suggestion: if only browser is passed without page, you could create a new page instead of falling through to a new browser:

if (puppeteerOpts.browser) {
    browser = puppeteerOpts.browser;
    page = puppeteerOpts.page || await browser.newPage();
}

This matches what the browserWSEndpoint path already does.

[Adi1231234]

@sofi-ans Can you check this PR? 🙏

LGTM. One suggestion: if only browser is passed without page, you could create a new page instead of falling through to a new browser:

if (puppeteerOpts.browser) {
    browser = puppeteerOpts.browser;
    page = puppeteerOpts.page || await browser.newPage();
}

This matches what the browserWSEndpoint path already does.

Done 🙏

[sofi-ans]

@sofi-ans Can you check this PR? 🙏

LGTM. One suggestion: if only browser is passed without page, you could create a new page instead of falling through to a new browser:

if (puppeteerOpts.browser) {
    browser = puppeteerOpts.browser;
    page = puppeteerOpts.page || await browser.newPage();
}

This matches what the browserWSEndpoint path already does.

Done 🙏

Looks good, approved

[shaked28th-dotcom]

Awesome to see someone finally opened a PR for this, I’ve literally been relying on patches for this exact issue