@ticktockbent/charlotte 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to Charlotte will be documented in this file.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-03-14
+
+### Added
+
+- **Popup and target="_blank" tab capture** — Clicks on `target="_blank"` links and `window.open()` calls were silently lost because PageManager had no `popup` event handler. New tabs are now auto-captured via `page.on("popup")`, auto-cleaned when pages close themselves, and surfaced as `opened_tabs` in tool responses using single-consumption semantics. Fixes #103, #98.
+- **Contributor issue templates** — Bug report, feature request, and tool request templates added to the repository. Community links added to README. (#102)
+
+### Changed
+
+- Renamed AXIOM to ASM across Charlotte site (#100).
+- Bumped hono dependency (#99).
+
+## [0.5.0] - 2026-03-09
+
+### Added
+
+- **Iframe content extraction** — Child frames are now discovered and their content (interactive elements, content summaries, full text) is merged into the parent page representation. Configurable depth limit (default 3). Iframe interactive elements are included in the `interactive` array and `interactive_summary`. Closes #23.
+- **Structural tree view** — `charlotte:observe` now accepts a `view` parameter with `"tree"` and `"tree-labeled"` modes that render the page as a hierarchical tree with indentation, replacing the flat JSON representation. Tree-labeled mode annotates interactive elements with their IDs for direct use.
+- **File output for large responses** — `charlotte:observe` and `charlotte:screenshot` accept an `output_file` parameter to write results to disk instead of returning inline, reducing token consumption for large pages. Relative paths resolve against `output_dir` (configurable via `charlotte:configure` or `--output-dir` CLI flag). Closes GAP-13, #16.
+- **Screenshot artifact management** — `charlotte:screenshots` (list), `charlotte:screenshot_get` (retrieve), `charlotte:screenshot_delete` (remove) tools for managing persistent screenshot files. `charlotte:screenshot` gains a `save` parameter for persistence.
+- **Code quality tooling** — ESLint, Prettier, and coverage configuration added to the project.
+
+### Fixed
+
+- **`wait_for` JS evaluation** — Replaced `new Function("return " + expr)` with CDP `Runtime.evaluate`, fixing multi-statement JS conditions that silently returned `undefined` due to ASI. Now consistent with `charlotte:evaluate`. Fixes #73.
+- **Browser reconnection race** — `getBrowser()` now calls `ensureConnected()` to auto-recover instead of throwing immediately. `ensureConnected()` verifies browser health after awaiting concurrent launches. Fixes #83.
+- **Renderer pipeline resilience** — Malformed AX properties no longer crash accessibility extraction (#86). Content extraction skips failed nodes instead of aborting (#79). Recursive frame traversal catches errors per-frame (#74). Batch layout extraction uses `Promise.allSettled()` for partial failure tolerance (#77).
+- **Event listener cleanup** — `closeTab()` now explicitly removes all page event listeners before `page.close()` to prevent memory leaks across tab cycles. Fixes #89.
+- **Dialog handler error handling** — Dialog event handler wrapped in try/catch to prevent unhandled promise rejections when dialog is already dismissed. Fixes #75.
+- **Dev mode shutdown resilience** — `DevModeState.stopAll()` catches errors per substep so a file watcher or static server failure doesn't prevent browser cleanup. Fixes #80.
+- **Form field matching null guard** — `resolveId()` null return no longer produces false-positive form field matches. Fixes #76.
+- **Landmark ID collision** — Main-frame landmarks now pass explicit `"main"` frameId for consistent hash input, preventing rare cross-frame ID collisions. Fixes #82.
+- **CLI argument parsing** — `--output-dir=`, `--profile=`, and `--tools=` flags now use `substring(indexOf("=") + 1)` instead of `split("=")[1]`, preserving paths containing `=`. Fixes #70.
+- **Zod bounds validation** — Added `.min()`/`.max()` constraints to `quality` (1-100), viewport `width`/`height` (>=1), and key `delay` (>=0). Fixes #81.
+- **Test cleanup** — File output integration test no longer leaks artifact store temp directory. Fixes #71.
+- **File output security** — Path traversal prevention, mkdir-before-validation fix, and CLI `output-dir` initialization hardened. Fixes security issues from #16 review.
+
+### Changed
+
+- README rewritten with problem-first opening, expanded MCP client setup configs (Cursor, Windsurf, VS Code, Cline, Amp), and updated tool counts.
+- npm package description and keywords updated for discoverability.
+- Site meta descriptions updated to lead with token-efficiency comparison.
+
 ## [0.4.2] - 2026-03-06
 
 ### Added

package/README.md

@@ -2,17 +2,23 @@
 
 **The Web, Readable.**
 
-Charlotte is an MCP server that renders web pages into structured, agent-readable representations using headless Chromium. It exposes the browser's semantic understanding — accessibility tree, layout geometry, interactive elements — to AI agents via [Model Context Protocol](https://modelcontextprotocol.io/) tools, enabling navigation, observation, and interaction without vision models or brittle selectors.
+Your AI agent spends 60,000 tokens just to look at a web page. Charlotte does it in 336.
+
+Charlotte is an MCP server that gives AI agents structured, token-efficient access to the web.
+Instead of dumping the full accessibility tree on every call, Charlotte returns only what
+the agent needs: a compact page summary on arrival, targeted queries for specific elements,
+and full detail only when explicitly requested. The result is 25-182x less data per page
+compared to [Playwright MCP](https://github.com/anthropics/playwright-mcp), saving thousands of dollars across production workloads.
 
 ## Why Charlotte?
 
 Most browser MCP servers dump the entire accessibility tree on every call — a flat text blob that can exceed a million characters on content-heavy pages. Agents pay for all of it whether they need it or not.
 
-Charlotte takes a different approach. It decomposes each page into a typed, structured representation — landmarks, headings, interactive elements, forms, content summaries — and lets agents control how much they receive with three detail levels. When an agent navigates to a new page, it gets a compact orientation (336 characters for Hacker News) instead of the full element dump (61,000+ characters). When it needs specifics, it asks for them.
+Charlotte decomposes each page into a typed, structured representation — landmarks, headings, interactive elements, forms, content summaries — and lets agents control how much they receive with three detail levels. When an agent navigates to a new page, it gets a compact orientation (336 characters for Hacker News) instead of the full element dump (61,000+ characters). When it needs specifics, it asks for them.
 
 ### Benchmarks
 
-Charlotte v0.4.2 vs Playwright MCP, measured by characters returned per tool call on real websites:
+Charlotte v0.5.1 vs Playwright MCP, measured by characters returned per tool call on real websites:
 
 **Navigation** (first contact with a page):
 
@@ -33,7 +39,7 @@ Charlotte's `navigate` returns minimal detail by default — landmarks, headings
 | browse (default) | 23 | ~3,900 | **~47%** |
 | core | 7 | 1,677 | **~77%** |
 
-Tool definitions are sent on every API round-trip. With the default `browse` profile, Charlotte carries ~47% less definition overhead than loading all 42 tools. Over a 20-call browsing session, that's **~38% fewer total tokens**. See the [profile benchmark report](docs/charlotte-profile-benchmark-report.md) for full results.
+Tool definitions are sent on every API round-trip. With the default `browse` profile, Charlotte carries ~47% less definition overhead than loading all tools. Over a 20-call browsing session, that's **~38% fewer total tokens**. See the [profile benchmark report](docs/charlotte-profile-benchmark-report.md) for full results.
 
 **The workflow difference:** Playwright agents receive 61K+ characters every time they look at Hacker News, whether they're reading headlines or looking for a login button. Charlotte agents get 336 characters on arrival, call `find({ type: "link", text: "login" })` to get exactly what they need, and never pay for the rest.
 
@@ -63,7 +69,7 @@ Agents receive landmarks, headings, interactive elements with typed metadata, bo
 
 **Navigation** — `navigate`, `back`, `forward`, `reload`
 
-**Observation** — `observe` (3 detail levels), `find` (spatial + semantic search, CSS selector mode), `screenshot`, `diff` (structural comparison against snapshots)
+**Observation** — `observe` (3 detail levels, structural tree view), `find` (spatial + semantic search, CSS selector mode), `screenshot` (with persistent artifact management), `screenshots`, `screenshot_get`, `screenshot_delete`, `diff` (structural comparison against snapshots)
 
 **Interaction** — `click`, `click_at` (coordinate-based), `type`, `select`, `toggle`, `submit`, `scroll`, `hover`, `drag`, `key` (single/sequence with element targeting), `wait_for` (async condition polling), `upload` (file input), `dialog` (accept/dismiss JS dialogs)
 
@@ -77,7 +83,7 @@ Agents receive landmarks, headings, interactive elements with typed metadata, bo
 
 ## Tool Profiles
 
-Charlotte ships 42 tools, but most workflows only need a subset. Startup profiles control which tools load into the agent's context, reducing definition overhead by up to 77%.
+Charlotte ships 42 tools (41 registered + the `charlotte:tools` meta-tool), but most workflows only need a subset. Startup profiles control which tools load into the agent's context, reducing definition overhead by up to 77%.
 
 ```bash
 charlotte --profile browse    # 23 tools (default) — navigate, observe, interact, tabs
@@ -150,7 +156,9 @@ npm start
 
 ### MCP Client Configuration
 
-Add Charlotte to your MCP client configuration. For Claude Code, create `.mcp.json` in your project root:
+#### Claude Code
+
+Create `.mcp.json` in your project root:
 
 ```json
 {
@@ -165,7 +173,85 @@ Add Charlotte to your MCP client configuration. For Claude Code, create `.mcp.js
 }
 ```
 
-For Claude Desktop, add to `claude_desktop_config.json`:
+#### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "command": "npx",
+      "args": ["@ticktockbent/charlotte"]
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "command": "npx",
+      "args": ["@ticktockbent/charlotte"]
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "command": "npx",
+      "args": ["@ticktockbent/charlotte"]
+    }
+  }
+}
+```
+
+#### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "charlotte": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@ticktockbent/charlotte"]
+    }
+  }
+}
+```
+
+#### Cline
+
+Add to Cline MCP settings (via the Cline sidebar > MCP Servers > Configure):
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "command": "npx",
+      "args": ["@ticktockbent/charlotte"]
+    }
+  }
+}
+```
+
+#### Amp
+
+Add to `~/.amp/settings.json`:
 
 ```json
 {
@@ -347,20 +433,18 @@ All tools go through `renderActivePage()` which handles snapshots, reload events
 
 ## Sandbox
 
-Charlotte includes a test website in `tests/sandbox/` that exercises all 42 tools without touching the public internet. Serve it locally with:
+Charlotte includes a test website in `tests/sandbox/` that exercises all tools without touching the public internet. Serve it locally with:
 
 ```
 dev_serve({ path: "tests/sandbox" })
 ```
 
-Four pages cover navigation, forms, interactive elements, delayed content, scroll containers, and more. See [docs/sandbox.md](docs/sandbox.md) for the full page reference and a tool-by-tool exercise checklist.
+Five pages cover navigation, forms, interactive elements, popups, delayed content, scroll containers, and more. See [docs/sandbox.md](docs/sandbox.md) for the full page reference and a tool-by-tool exercise checklist.
 
 ## Known Issues
 
 **Tool naming convention** — Charlotte uses `:` as a namespace separator in tool names (e.g., `charlotte:navigate`, `charlotte:observe`). MCP SDK v1.26.0+ logs validation warnings for this character, as the emerging [SEP standard](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/986) restricts tool names to `[A-Za-z0-9_.-]`. This does not affect functionality — all tools work correctly — but produces stderr warnings on server startup. Will be addressed in a future release to comply with the SEP standard.
 
-**Iframe content not captured** — Charlotte reads the main frame's accessibility tree only. Content inside iframes (same-origin or cross-origin) is not included in the page representation. See the Roadmap for planned iframe support.
-
 **Shadow DOM** — Open shadow DOM works transparently. Chromium's accessibility tree pierces open shadow boundaries, so web components (e.g., GitHub's `<relative-time>`, `<tool-tip>`) render their content into Charlotte's representation without special handling. Closed shadow roots are opaque to the accessibility tree and will not be captured.
 
 ## Roadmap
@@ -379,20 +463,14 @@ Four pages cover navigation, forms, interactive elements, delayed content, scrol
 
 **Configuration File** — Support a `--config` CLI argument to load settings from a JSON file, simplifying repeatable setups and CI/CD integration.
 
-**File Output** — Add an optional `filename` parameter to `screenshot`, `observe`, and future monitoring tools so large responses can be written to disk instead of returned inline, reducing token consumption.
-
 **Full Device Emulation** — Extend `charlotte:viewport` to accept named devices (e.g., "iPhone 15") and configure user agent, touch support, and device pixel ratio via CDP, not just viewport dimensions.
 
 ### Feature Roadmap
 
-**Screenshot Artifacts** — Save screenshots as persistent file artifacts rather than only returning inline data, enabling agents to reference and manage captured images across sessions.
-
 **Video Recording** — Record interactions as video, capturing the full sequence of agent-driven navigation and manipulation for debugging, documentation, and review.
 
 **ARM64 Docker Images** — Add `linux/arm64` platform support to the Docker publish workflow for native performance on Apple Silicon Macs and ARM servers.
 
-**Iframe Content Extraction** — Traverse child frames via CDP to include iframe content in the page representation. Currently, Charlotte only reads the main frame's accessibility tree; same-origin and cross-origin iframe content is invisible.
-
 See [docs/playwright-mcp-gap-analysis.md](docs/playwright-mcp-gap-analysis.md) for the full gap analysis against Playwright MCP, including lower-priority items (vision tools, testing/verification, tracing, transport, security) and areas where Charlotte has advantages.
 
 ## Full Specification
@@ -403,6 +481,14 @@ See [docs/CHARLOTTE_SPEC.md](docs/CHARLOTTE_SPEC.md) for the complete specificat
 
 [MIT](LICENSE)
 
+## Community
+
+- Open a [bug report](https://github.com/TickTockBent/charlotte/issues/new?template=bug_report.md) for reproducible defects, regressions, or MCP-client-specific problems.
+- Open a [feature request](https://github.com/TickTockBent/charlotte/issues/new?template=feature_request.md) for workflow improvements or new capabilities.
+- Open a [tool request](https://github.com/TickTockBent/charlotte/issues/new?template=tool_request.md) if you want to propose a new tool, parameter surface, or profile placement.
+- Browse [open issues](https://github.com/TickTockBent/charlotte/issues) to find current work and discussion.
+- Check the planned [good first issue filter](https://github.com/TickTockBent/charlotte/issues?q=is%3Aopen+label%3A%22good+first+issue%22) as maintainers tag starter-friendly tasks.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/dist/browser/browser-manager.d.ts

@@ -7,7 +7,7 @@ export declare class BrowserManager {
     private doLaunch;
     ensureConnected(): Promise<void>;
     close(): Promise<void>;
-    getBrowser(): Browser;
+    getBrowser(): Promise<Browser>;
     newPage(): Promise<Page>;
     isConnected(): boolean;
 }

package/dist/browser/browser-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-manager.d.ts","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAkB,EAAE,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAInF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,SAAS,CAA8B;IAEzC,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;YAetC,QAAQ;IAchB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,UAAU,IAAI,OAAO;IAUf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,WAAW,IAAI,OAAO;CAGvB"}
+{"version":3,"file":"browser-manager.d.ts","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAkB,EAAE,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAInF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,SAAS,CAA8B;IAEzC,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;YAetC,QAAQ;IAchB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAW9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,WAAW,IAAI,OAAO;CAGvB"}

package/dist/browser/browser-manager.js

@@ -36,6 +36,10 @@ export class BrowserManager {
         // Prevent concurrent relaunch attempts
         if (this.launching) {
             await this.launching;
+            // Verify the concurrent launch actually succeeded
+            if (!this.browser || !this.browser.connected) {
+                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Browser launch failed during concurrent reconnection attempt.");
+            }
             return;
         }
         logger.info("Browser not connected, relaunching");
@@ -54,15 +58,15 @@ export class BrowserManager {
             this.browser = null;
         }
     }
-    getBrowser() {
+    async getBrowser() {
+        await this.ensureConnected();
         if (!this.browser || !this.browser.connected) {
-            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Browser is not connected. Call ensureConnected() first.");
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Browser is not connected after ensureConnected().");
         }
         return this.browser;
     }
     async newPage() {
-        await this.ensureConnected();
-        const browser = this.getBrowser();
+        const browser = await this.getBrowser();
         return browser.newPage();
     }
     isConnected() {

package/dist/browser/browser-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser-manager.js","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAO,SAA0D,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExE,MAAM,OAAO,cAAc;IACjB,OAAO,GAAmB,IAAI,CAAC;IAC/B,aAAa,GAAkB,EAAE,CAAC;IAClC,SAAS,GAAyB,IAAI,CAAC;IAE/C,KAAK,CAAC,MAAM,CAAC,OAAuB;QAClC,IAAI,CAAC,aAAa,GAAG;YACnB,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE;gBACJ,cAAc;gBACd,0BAA0B;gBAC1B,eAAe;gBACf,yBAAyB;aAC1B;YACD,GAAG,OAAO;SACX,CAAC;QAEF,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAE1D,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;YACnC,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;YAClD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC/B,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,GAAG;SACjC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QAED,uCAAuC;QACvC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,SAAS,CAAC;YACrB,OAAO;QACT,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAChC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;IAED,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAC7C,MAAM,IAAI,cAAc,CACtB,kBAAkB,CAAC,aAAa,EAChC,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IACzD,CAAC;CACF"}
+{"version":3,"file":"browser-manager.js","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"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"}

package/dist/browser/cdp-session.d.ts

@@ -1,7 +1,15 @@
-import type { Page, CDPSession } from "puppeteer";
+import type { Page, CDPSession, Frame } from "puppeteer";
 export declare class CDPSessionManager {
     private sessions;
+    private frameSessions;
     getSession(page: Page): Promise<CDPSession>;
+    /**
+     * Get or create a CDP session for a child frame.
+     * Uses the frame's own client for out-of-process (cross-origin) frames.
+     */
+    getFrameSession(frame: Frame): Promise<CDPSession>;
+    /** Extract the CDP frame ID from a Puppeteer Frame. */
+    getFrameId(frame: Frame): string;
     private enableDomains;
 }
 //# sourceMappingURL=cdp-session.d.ts.map

package/dist/browser/cdp-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdp-session.d.ts","sourceRoot":"","sources":["../../src/browser/cdp-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWlD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAA4C;IAEtD,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;YAanC,aAAa;CAW5B"}
+{"version":3,"file":"cdp-session.d.ts","sourceRoot":"","sources":["../../src/browser/cdp-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAQzD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAA4C;IAC5D,OAAO,CAAC,aAAa,CAAiC;IAEhD,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IAajD;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBxD,uDAAuD;IACvD,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;YAMlB,aAAa;CAc5B"}

package/dist/browser/cdp-session.js

@@ -1,13 +1,10 @@
 import { logger } from "../utils/logger.js";
-const REQUIRED_DOMAINS = [
-    "Accessibility",
-    "DOM",
-    "CSS",
-    "Page",
-    "Network",
-];
+const REQUIRED_DOMAINS = ["Accessibility", "DOM", "CSS", "Page", "Network"];
+/** Domains needed for iframe frame sessions (subset — no Page/Network). */
+const FRAME_DOMAINS = ["Accessibility", "DOM", "CSS"];
 export class CDPSessionManager {
     sessions = new WeakMap();
+    frameSessions = new Map();
     async getSession(page) {
         const existing = this.sessions.get(page);
         if (existing) {
@@ -15,12 +12,37 @@ export class CDPSessionManager {
         }
         logger.debug("Creating new CDP session");
         const session = await page.createCDPSession();
-        await this.enableDomains(session);
+        await this.enableDomains(session, REQUIRED_DOMAINS);
         this.sessions.set(page, session);
         return session;
     }
-    async enableDomains(session) {
-        for (const domain of REQUIRED_DOMAINS) {
+    /**
+     * Get or create a CDP session for a child frame.
+     * Uses the frame's own client for out-of-process (cross-origin) frames.
+     */
+    async getFrameSession(frame) {
+        const frameId = this.getFrameId(frame);
+        const existing = this.frameSessions.get(frameId);
+        if (existing) {
+            return existing;
+        }
+        logger.debug("Creating CDP session for frame", { frameId, url: frame.url() });
+        // CdpFrame exposes .client which is the CDP session for that frame's target.
+        // This is a Puppeteer internal (tested with puppeteer 24.x). If Puppeteer
+        // changes the internal API, this will need updating.
+        const session = frame.client;
+        await this.enableDomains(session, FRAME_DOMAINS);
+        this.frameSessions.set(frameId, session);
+        return session;
+    }
+    /** Extract the CDP frame ID from a Puppeteer Frame. */
+    getFrameId(frame) {
+        // Puppeteer Frame exposes _id as the CDP frame ID.
+        // This is a Puppeteer internal (tested with puppeteer 24.x).
+        return frame._id;
+    }
+    async enableDomains(session, domains) {
+        for (const domain of domains) {
             try {
                 await session.send(`${domain}.enable`);
                 logger.debug(`Enabled CDP domain: ${domain}`);

package/dist/browser/cdp-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"cdp-session.js","sourceRoot":"","sources":["../../src/browser/cdp-session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,gBAAgB,GAAG;IACvB,eAAe;IACf,KAAK;IACL,KAAK;IACL,MAAM;IACN,SAAS;CACD,CAAC;AAEX,MAAM,OAAO,iBAAiB;IACpB,QAAQ,GAA8B,IAAI,OAAO,EAAE,CAAC;IAE5D,KAAK,CAAC,UAAU,CAAC,IAAU;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,OAAmB;QAC7C,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,SAAgB,CAAC,CAAC;gBAC9C,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,8CAA8C;gBAC9C,MAAM,CAAC,KAAK,CAAC,gCAAgC,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"cdp-session.js","sourceRoot":"","sources":["../../src/browser/cdp-session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,gBAAgB,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAErF,2EAA2E;AAC3E,MAAM,aAAa,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAE/D,MAAM,OAAO,iBAAiB;IACpB,QAAQ,GAA8B,IAAI,OAAO,EAAE,CAAC;IACpD,aAAa,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEtD,KAAK,CAAC,UAAU,CAAC,IAAU;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;QACpD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,KAAY;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC9E,6EAA6E;QAC7E,0EAA0E;QAC1E,qDAAqD;QACrD,MAAM,OAAO,GAAI,KAAa,CAAC,MAAoB,CAAC;QACpD,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,uDAAuD;IACvD,UAAU,CAAC,KAAY;QACrB,mDAAmD;QACnD,6DAA6D;QAC7D,OAAQ,KAAa,CAAC,GAAa,CAAC;IACtC,CAAC;IAEO,KAAK,CAAC,aAAa,CACzB,OAAmB,EACnB,OAA0B;QAE1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,SAAgB,CAAC,CAAC;gBAC9C,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,8CAA8C;gBAC9C,MAAM,CAAC,KAAK,CAAC,gCAAgC,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/browser/page-manager.d.ts

@@ -25,7 +25,23 @@ export declare class PageManager {
     private pages;
     private activeTabId;
     private config;
+    /** Tab IDs of pages opened by popups since the last drain. */
+    private newTabQueue;
     constructor(config?: CharlotteConfig);
+    /**
+     * Wire up event listeners on a managed page: console, network, dialog,
+     * framenavigated, popup, and close. Shared by openTab() and the popup handler.
+     */
+    private wirePageListeners;
+    /**
+     * Register a popup page as a managed tab. Called by the popup event handler.
+     */
+    private registerPopupPage;
+    /**
+     * Drain the new-tab queue. Returns tab IDs of pages opened by popups since
+     * the last call, then clears the queue (single-consumption semantics).
+     */
+    consumeNewTabs(): string[];
     openTab(browserManager: BrowserManager, url?: string): Promise<string>;
     switchTab(tabId: string): Promise<Page>;
     closeTab(tabId: string): Promise<void>;

package/dist/browser/page-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-manager.d.ts","sourceRoot":"","sources":["../../src/browser/page-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1D,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,CAAC,EAAE,eAAe;IAK9B,OAAO,CAAC,cAAc,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuFtE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBtC,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAapC,aAAa,IAAI,IAAI;IAmBrB,cAAc,IAAI,MAAM;IAUxB,+EAA+E;IAC/E,gBAAgB,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAS1D,uFAAuF;IACvF,gBAAgB,IAAI,KAAK,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IASF,iEAAiE;IACjE,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE;IAUpD,wDAAwD;IACxD,kBAAkB,IAAI,cAAc,EAAE;IAOtC,oBAAoB,IAAI,IAAI;IAQ5B,oBAAoB,IAAI,IAAI;IAQ5B,WAAW,IAAI,IAAI;IASnB,oBAAoB,IAAI,aAAa,GAAG,IAAI;IAM5C,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAMjC,kBAAkB,IAAI,IAAI;IAS1B,QAAQ,IAAI,OAAO;CAGpB"}
+{"version":3,"file":"page-manager.d.ts","sourceRoot":"","sources":["../../src/browser/page-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1D,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAkB;IAChC,8DAA8D;IAC9D,OAAO,CAAC,WAAW,CAAgB;gBAEvB,MAAM,CAAC,EAAE,eAAe;IAKpC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA6FzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;OAGG;IACH,cAAc,IAAI,MAAM,EAAE;IAOpB,OAAO,CAAC,cAAc,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BtE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBtC,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAapC,aAAa,IAAI,IAAI;IAmBrB,cAAc,IAAI,MAAM;IAOxB,+EAA+E;IAC/E,gBAAgB,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAS1D,uFAAuF;IACvF,gBAAgB,IAAI,KAAK,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IASF,iEAAiE;IACjE,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE;IAUpD,wDAAwD;IACxD,kBAAkB,IAAI,cAAc,EAAE;IAOtC,oBAAoB,IAAI,IAAI;IAQ5B,oBAAoB,IAAI,IAAI;IAQ5B,WAAW,IAAI,IAAI;IASnB,oBAAoB,IAAI,aAAa,GAAG,IAAI;IAM5C,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAMjC,kBAAkB,IAAI,IAAI;IAS1B,QAAQ,IAAI,OAAO;CAGpB"}

package/dist/browser/page-manager.js

@@ -11,21 +11,18 @@ export class PageManager {
     pages = new Map();
     activeTabId = null;
     config;
+    /** Tab IDs of pages opened by popups since the last drain. */
+    newTabQueue = [];
     constructor(config) {
         // Accept optional config; callers without config get a permissive default
         this.config = config ?? createDefaultConfig();
     }
-    async openTab(browserManager, url) {
-        const page = await browserManager.newPage();
-        const tabId = generateTabId();
-        const managedPage = {
-            id: tabId,
-            page,
-            consoleMessages: [],
-            networkRequests: [],
-            pendingDialog: null,
-            pendingDialogInfo: null,
-        };
+    /**
+     * Wire up event listeners on a managed page: console, network, dialog,
+     * framenavigated, popup, and close. Shared by openTab() and the popup handler.
+     */
+    wirePageListeners(managedPage) {
+        const { page, id: tabId } = managedPage;
         // Collect all console messages
         page.on("console", (msg) => {
             if (managedPage.consoleMessages.length >= MAX_CONSOLE_MESSAGES) {
@@ -53,26 +50,32 @@ export class PageManager {
         });
         // Handle JavaScript dialogs (alert, confirm, prompt, beforeunload)
         page.on("dialog", async (dialog) => {
-            const dialogType = dialog.type();
-            const autoDismiss = this.config.dialogAutoDismiss;
-            logger.info("Dialog appeared", { tabId, type: dialogType, message: dialog.message() });
-            // Auto-dismiss logic
-            if (autoDismiss === "accept_all" || (autoDismiss === "accept_alerts" && dialogType === "alert")) {
-                await dialog.accept();
-                return;
+            try {
+                const dialogType = dialog.type();
+                const autoDismiss = this.config.dialogAutoDismiss;
+                logger.info("Dialog appeared", { tabId, type: dialogType, message: dialog.message() });
+                // Auto-dismiss logic
+                if (autoDismiss === "accept_all" ||
+                    (autoDismiss === "accept_alerts" && dialogType === "alert")) {
+                    await dialog.accept();
+                    return;
+                }
+                if (autoDismiss === "dismiss_all") {
+                    await dialog.dismiss();
+                    return;
+                }
+                // Queue for manual handling
+                managedPage.pendingDialog = dialog;
+                managedPage.pendingDialogInfo = {
+                    type: dialogType,
+                    message: dialog.message(),
+                    ...(dialogType === "prompt" ? { default_value: dialog.defaultValue() } : {}),
+                    timestamp: new Date().toISOString(),
+                };
             }
-            if (autoDismiss === "dismiss_all") {
-                await dialog.dismiss();
-                return;
+            catch (error) {
+                logger.warn("Dialog handler failed", { tabId, error });
             }
-            // Queue for manual handling
-            managedPage.pendingDialog = dialog;
-            managedPage.pendingDialogInfo = {
-                type: dialogType,
-                message: dialog.message(),
-                ...(dialogType === "prompt" ? { default_value: dialog.defaultValue() } : {}),
-                timestamp: new Date().toISOString(),
-            };
         });
         // Clear stale dialog references on main-frame navigation only.
         // Subframe navigations (iframes, ads, embeds) must not wipe dialog state.
@@ -82,6 +85,65 @@ export class PageManager {
                 managedPage.pendingDialogInfo = null;
             }
         });
+        // Capture popups (target="_blank" links, window.open()) as managed tabs
+        page.on("popup", (popupPage) => {
+            if (popupPage) {
+                this.registerPopupPage(popupPage);
+            }
+        });
+        // Auto-clean when a page closes itself (window.close(), site-initiated)
+        page.on("close", () => {
+            if (this.pages.has(tabId)) {
+                this.pages.delete(tabId);
+                logger.info(`Tab ${tabId} closed by page`);
+                if (this.activeTabId === tabId) {
+                    const remaining = this.pages.keys().next();
+                    this.activeTabId = remaining.done ? null : remaining.value;
+                }
+            }
+        });
+    }
+    /**
+     * Register a popup page as a managed tab. Called by the popup event handler.
+     */
+    registerPopupPage(popupPage) {
+        const popupTabId = generateTabId();
+        const managedPopup = {
+            id: popupTabId,
+            page: popupPage,
+            consoleMessages: [],
+            networkRequests: [],
+            pendingDialog: null,
+            pendingDialogInfo: null,
+        };
+        this.wirePageListeners(managedPopup);
+        this.pages.set(popupTabId, managedPopup);
+        this.newTabQueue.push(popupTabId);
+        logger.info(`Captured popup as ${popupTabId}`, { url: popupPage.url() });
+    }
+    /**
+     * Drain the new-tab queue. Returns tab IDs of pages opened by popups since
+     * the last call, then clears the queue (single-consumption semantics).
+     */
+    consumeNewTabs() {
+        if (this.newTabQueue.length === 0)
+            return [];
+        const tabs = [...this.newTabQueue];
+        this.newTabQueue = [];
+        return tabs;
+    }
+    async openTab(browserManager, url) {
+        const page = await browserManager.newPage();
+        const tabId = generateTabId();
+        const managedPage = {
+            id: tabId,
+            page,
+            consoleMessages: [],
+            networkRequests: [],
+            pendingDialog: null,
+            pendingDialogInfo: null,
+        };
+        this.wirePageListeners(managedPage);
         this.pages.set(tabId, managedPage);
         this.activeTabId = tabId;
         if (url) {
@@ -104,6 +166,12 @@ export class PageManager {
         if (!managedPage) {
             throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Tab '${tabId}' not found`);
         }
+        managedPage.page.removeAllListeners("console");
+        managedPage.page.removeAllListeners("response");
+        managedPage.page.removeAllListeners("dialog");
+        managedPage.page.removeAllListeners("framenavigated");
+        managedPage.page.removeAllListeners("popup");
+        managedPage.page.removeAllListeners("close");
         await managedPage.page.close();
         this.pages.delete(tabId);
         if (this.activeTabId === tabId) {