@ticktockbent/charlotte 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to Charlotte will be documented in this file.
+
+## [0.1.0] - 2026-02-13
+
+Initial release. All six implementation phases complete.
+
+### Tools
+
+**Navigation**: `navigate`, `back`, `forward`, `reload`
+
+**Observation**: `observe` (minimal/summary/full detail levels, CSS selector scoping, computed styles), `find` (text, role, type, spatial near/within filters), `screenshot` (PNG/JPEG/WebP, element or full page), `diff` (structural comparison against snapshots)
+
+**Interaction**: `click` (left/right/double), `type` (with clear_first, press_enter), `select`, `toggle`, `submit`, `scroll` (page/container, directional), `hover`, `key` (with modifiers), `wait_for` (element state, text, selector, JS expression)
+
+**Session**: `tabs`, `tab_open`, `tab_switch`, `tab_close`, `set_cookies`, `set_headers`, `viewport` (mobile/tablet/desktop presets), `network` (3G/4G/offline throttling, URL blocking), `configure` (snapshot depth, auto-snapshot mode)
+
+**Development**: `dev_serve` (static server + file watching with auto-reload), `dev_inject` (CSS/JS injection with delta), `dev_audit` (a11y, performance, SEO, contrast, broken links)
+
+**Utilities**: `evaluate` (JS execution with timeout and promise awaiting)
+
+### Architecture
+
+- Renderer pipeline: accessibility tree + layout geometry + interactive element extraction
+- Hash-based element IDs stable across re-renders
+- Snapshot store with ring buffer and structural diffing
+- Chromium crash recovery with automatic relaunch
+- Dev mode reload events surfaced through existing tool responses (zero integration overhead)
+
+### Testing
+
+222 tests across 19 test files (unit + integration).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ticktockbent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# Charlotte
+
+**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.
+
+## How It Works
+
+Charlotte maintains a persistent headless Chromium session and acts as a translation layer between the visual web and the agent's text-native reasoning. Every page is decomposed into a structured representation:
+
+```
+┌─────────────┐     MCP Protocol     ┌──────────────────┐
+│   AI Agent  │ <───────────────────> │    Charlotte     │
+└─────────────┘                      │                  │
+                                     │  ┌────────────┐  │
+                                     │  │  Renderer  │  │
+                                     │  │  Pipeline  │  │
+                                     │  └─────┬──────┘  │
+                                     │        │         │
+                                     │  ┌─────▼──────┐  │
+                                     │  │  Headless  │  │
+                                     │  │  Chromium  │  │
+                                     │  └────────────┘  │
+                                     └──────────────────┘
+```
+
+Agents receive landmarks, headings, interactive elements with typed metadata, bounding boxes, form structures, and content summaries — all derived from what the browser already knows about every page.
+
+## Features
+
+**Navigation** — `navigate`, `back`, `forward`, `reload`
+
+**Observation** — `observe` (3 detail levels), `find` (spatial + semantic search), `screenshot`, `diff` (structural comparison against snapshots)
+
+**Interaction** — `click`, `type`, `select`, `toggle`, `submit`, `scroll`, `hover`, `key`, `wait_for` (async condition polling)
+
+**Session Management** — `tabs`, `tab_open`, `tab_switch`, `tab_close`, `viewport` (device presets), `network` (throttling, URL blocking), `set_cookies`, `set_headers`, `configure`
+
+**Development Mode** — `dev_serve` (static server + file watching with auto-reload), `dev_inject` (CSS/JS injection), `dev_audit` (a11y, performance, SEO, contrast, broken links)
+
+**Utilities** — `evaluate` (arbitrary JS execution in page context)
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 22
+- npm
+
+### Installation
+
+```bash
+git clone https://github.com/ticktockbent/charlotte.git
+cd charlotte
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run
+
+Charlotte communicates over stdio using the MCP protocol:
+
+```bash
+npm start
+```
+
+### MCP Client Configuration
+
+Add Charlotte to your MCP client configuration. For Claude Code, create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/charlotte/dist/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "charlotte": {
+      "command": "node",
+      "args": ["/path/to/charlotte/dist/index.js"]
+    }
+  }
+}
+```
+
+See [docs/mcp-setup.md](docs/mcp-setup.md) for the full setup guide, including development mode, generic MCP clients, verification steps, and troubleshooting.
+
+## Usage Examples
+
+Once connected, an agent can use Charlotte's tools:
+
+### Browse a website
+
+```
+navigate({ url: "https://example.com" })
+observe({ detail: "summary" })
+find({ type: "link", text: "About" })
+click({ element_id: "lnk-a3f1" })
+```
+
+### Fill out a form
+
+```
+observe({ detail: "minimal" })
+type({ element_id: "inp-c7e2", text: "hello@example.com" })
+select({ element_id: "sel-e8a3", value: "option-2" })
+submit({ form_id: "frm-b1d4" })
+```
+
+### Local development feedback loop
+
+```
+dev_serve({ path: "./my-site", watch: true })
+observe({ detail: "full" })
+dev_audit({ checks: ["a11y", "contrast"] })
+dev_inject({ css: "body { font-size: 18px; }" })
+```
+
+## Page Representation
+
+Charlotte returns structured representations optimized for token efficiency:
+
+```json
+{
+  "url": "https://example.com/dashboard",
+  "title": "Dashboard",
+  "viewport": { "width": 1280, "height": 720 },
+  "snapshot_id": 1,
+  "structure": {
+    "landmarks": [
+      { "role": "banner", "label": "Site header", "bounds": { "x": 0, "y": 0, "w": 1280, "h": 64 } },
+      { "role": "main", "label": "Content", "bounds": { "x": 240, "y": 64, "w": 1040, "h": 656 } }
+    ],
+    "headings": [
+      { "level": 1, "text": "Dashboard", "id": "h-1" }
+    ],
+    "content_summary": "main: 2 headings, 5 links, 1 form"
+  },
+  "interactive": [
+    {
+      "id": "btn-a3f1",
+      "type": "button",
+      "label": "Create Project",
+      "bounds": { "x": 960, "y": 80, "w": 160, "h": 40 },
+      "state": { "enabled": true, "visible": true }
+    }
+  ],
+  "forms": [],
+  "alerts": [],
+  "errors": { "console": [], "network": [] }
+}
+```
+
+Detail levels control verbosity:
+- **`minimal`** (~200-500 tokens) — Landmarks + interactive elements only
+- **`summary`** (~500-1500 tokens) — Adds content summaries, forms, errors
+- **`full`** (variable) — Includes all visible text content
+
+## Element IDs
+
+Element IDs are stable across minor DOM mutations. They're generated by hashing a composite key of element type, ARIA role, accessible name, and DOM path signature:
+
+```
+btn-a3f1  (button)    inp-c7e2  (text input)
+lnk-d4b9  (link)      sel-e8a3  (select)
+chk-f1a2  (checkbox)  frm-b1d4  (form)
+```
+
+IDs survive unrelated DOM changes and element reordering within the same container.
+
+## Development
+
+```bash
+# Run in watch mode
+npm run dev
+
+# Run all tests
+npm test
+
+# Run only unit tests
+npm run test:unit
+
+# Run only integration tests
+npm run test:integration
+
+# Type check
+npx tsc --noEmit
+```
+
+### Project Structure
+
+```
+src/
+  browser/          # Puppeteer lifecycle, tab management, CDP sessions
+  renderer/         # Accessibility tree extraction, layout, content, element IDs
+  state/            # Snapshot store, structural differ
+  tools/            # MCP tool definitions (navigation, observation, interaction, session, dev-mode)
+  dev/              # Static server, file watcher, auditor
+  types/            # TypeScript interfaces
+  utils/            # Logger, hash, wait utilities
+tests/
+  unit/             # Fast tests with mocks
+  integration/      # Full Puppeteer tests against fixture HTML
+  fixtures/pages/   # Test HTML files
+```
+
+### Architecture
+
+The **Renderer Pipeline** is the core — it calls extractors in order and assembles a `PageRepresentation`:
+
+1. Accessibility tree extraction (CDP `Accessibility.getFullAXTree`)
+2. Layout extraction (CDP `DOM.getBoxModel`)
+3. Landmark, heading, interactive element, and content extraction
+4. Element ID generation (hash-based, stable across re-renders)
+
+All tools go through `renderActivePage()` which handles snapshots, reload events, and response formatting.
+
+## Sandbox
+
+Charlotte includes a test website in `tests/sandbox/` that exercises all 30 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.
+
+## Full Specification
+
+See [docs/CHARLOTTE_SPEC.md](docs/CHARLOTTE_SPEC.md) for the complete specification including all tool parameters, the page representation format, element identity strategy, and architecture details.
+
+## License
+
+[MIT](LICENSE)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

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

@@ -0,0 +1,14 @@
+import { type Browser, type Page, type LaunchOptions } from "puppeteer";
+export declare class BrowserManager {
+    private browser;
+    private launchOptions;
+    private launching;
+    launch(options?: LaunchOptions): Promise<void>;
+    private doLaunch;
+    ensureConnected(): Promise<void>;
+    close(): Promise<void>;
+    getBrowser(): Browser;
+    newPage(): Promise<Page>;
+    isConnected(): boolean;
+}
+//# sourceMappingURL=browser-manager.d.ts.map

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

@@ -0,0 +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"}

package/dist/browser/browser-manager.js

@@ -0,0 +1,72 @@
+import puppeteer from "puppeteer";
+import { logger } from "../utils/logger.js";
+import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
+export class BrowserManager {
+    browser = null;
+    launchOptions = {};
+    launching = null;
+    async launch(options) {
+        this.launchOptions = {
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-gpu",
+                "--disable-dev-shm-usage",
+            ],
+            ...options,
+        };
+        await this.doLaunch();
+    }
+    async doLaunch() {
+        logger.info("Launching Chromium");
+        this.browser = await puppeteer.launch(this.launchOptions);
+        this.browser.on("disconnected", () => {
+            logger.warn("Chromium disconnected unexpectedly");
+            this.browser = null;
+        });
+        logger.info("Chromium launched", {
+            pid: this.browser.process()?.pid,
+        });
+    }
+    async ensureConnected() {
+        if (this.browser && this.browser.connected) {
+            return;
+        }
+        // Prevent concurrent relaunch attempts
+        if (this.launching) {
+            await this.launching;
+            return;
+        }
+        logger.info("Browser not connected, relaunching");
+        this.launching = this.doLaunch();
+        try {
+            await this.launching;
+        }
+        finally {
+            this.launching = null;
+        }
+    }
+    async close() {
+        if (this.browser) {
+            logger.info("Closing Chromium");
+            await this.browser.close();
+            this.browser = null;
+        }
+    }
+    getBrowser() {
+        if (!this.browser || !this.browser.connected) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Browser is not connected. Call ensureConnected() first.");
+        }
+        return this.browser;
+    }
+    async newPage() {
+        await this.ensureConnected();
+        const browser = this.getBrowser();
+        return browser.newPage();
+    }
+    isConnected() {
+        return this.browser !== null && this.browser.connected;
+    }
+}
+//# sourceMappingURL=browser-manager.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,7 @@
+import type { Page, CDPSession } from "puppeteer";
+export declare class CDPSessionManager {
+    private sessions;
+    getSession(page: Page): Promise<CDPSession>;
+    private enableDomains;
+}
+//# sourceMappingURL=cdp-session.d.ts.map

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

@@ -0,0 +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"}

package/dist/browser/cdp-session.js

@@ -0,0 +1,35 @@
+import { logger } from "../utils/logger.js";
+const REQUIRED_DOMAINS = [
+    "Accessibility",
+    "DOM",
+    "CSS",
+    "Page",
+    "Network",
+];
+export class CDPSessionManager {
+    sessions = new WeakMap();
+    async getSession(page) {
+        const existing = this.sessions.get(page);
+        if (existing) {
+            return existing;
+        }
+        logger.debug("Creating new CDP session");
+        const session = await page.createCDPSession();
+        await this.enableDomains(session);
+        this.sessions.set(page, session);
+        return session;
+    }
+    async enableDomains(session) {
+        for (const domain of REQUIRED_DOMAINS) {
+            try {
+                await session.send(`${domain}.enable`);
+                logger.debug(`Enabled CDP domain: ${domain}`);
+            }
+            catch (error) {
+                // Some domains may not need explicit enabling
+                logger.debug(`Could not enable CDP domain: ${domain}`, error);
+            }
+        }
+    }
+}
+//# sourceMappingURL=cdp-session.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,30 @@
+import type { Page } from "puppeteer";
+import type { BrowserManager } from "./browser-manager.js";
+export interface TabInfo {
+    id: string;
+    url: string;
+    title: string;
+    active: boolean;
+}
+export declare class PageManager {
+    private pages;
+    private activeTabId;
+    openTab(browserManager: BrowserManager, url?: string): Promise<string>;
+    switchTab(tabId: string): Promise<Page>;
+    closeTab(tabId: string): Promise<void>;
+    listTabs(): Promise<TabInfo[]>;
+    getActivePage(): Page;
+    getActiveTabId(): string;
+    getConsoleErrors(): Array<{
+        level: string;
+        text: string;
+    }>;
+    getNetworkErrors(): Array<{
+        url: string;
+        status: number;
+        statusText: string;
+    }>;
+    clearErrors(): void;
+    hasPages(): boolean;
+}
+//# sourceMappingURL=page-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-manager.d.ts","sourceRoot":"","sources":["../../src/browser/page-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,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,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,WAAW,CAAuB;IAEpC,OAAO,CAAC,cAAc,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4CtE,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,gBAAgB,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAM1D,gBAAgB,IAAI,KAAK,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IAMF,WAAW,IAAI,IAAI;IASnB,QAAQ,IAAI,OAAO;CAGpB"}

package/dist/browser/page-manager.js

@@ -0,0 +1,123 @@
+import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
+import { logger } from "../utils/logger.js";
+let nextTabIdCounter = 1;
+function generateTabId() {
+    return `tab-${nextTabIdCounter++}`;
+}
+export class PageManager {
+    pages = new Map();
+    activeTabId = null;
+    async openTab(browserManager, url) {
+        const page = await browserManager.newPage();
+        const tabId = generateTabId();
+        const managedPage = {
+            id: tabId,
+            page,
+            consoleErrors: [],
+            networkErrors: [],
+        };
+        // Collect console errors
+        page.on("console", (msg) => {
+            const level = msg.type();
+            if (level === "error" || level === "warn") {
+                managedPage.consoleErrors.push({
+                    level,
+                    text: msg.text(),
+                });
+            }
+        });
+        // Collect network errors
+        page.on("response", (response) => {
+            if (response.status() >= 400) {
+                managedPage.networkErrors.push({
+                    url: response.url(),
+                    status: response.status(),
+                    statusText: response.statusText(),
+                });
+            }
+        });
+        this.pages.set(tabId, managedPage);
+        this.activeTabId = tabId;
+        if (url) {
+            await page.goto(url, { waitUntil: "load" });
+        }
+        logger.info(`Opened tab ${tabId}`, { url });
+        return tabId;
+    }
+    async switchTab(tabId) {
+        const managedPage = this.pages.get(tabId);
+        if (!managedPage) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Tab '${tabId}' not found`);
+        }
+        this.activeTabId = tabId;
+        await managedPage.page.bringToFront();
+        return managedPage.page;
+    }
+    async closeTab(tabId) {
+        const managedPage = this.pages.get(tabId);
+        if (!managedPage) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Tab '${tabId}' not found`);
+        }
+        await managedPage.page.close();
+        this.pages.delete(tabId);
+        if (this.activeTabId === tabId) {
+            // Switch to the first remaining tab
+            const remaining = this.pages.keys().next();
+            this.activeTabId = remaining.done ? null : remaining.value;
+        }
+        logger.info(`Closed tab ${tabId}`);
+    }
+    async listTabs() {
+        const tabs = [];
+        for (const [id, managedPage] of this.pages) {
+            tabs.push({
+                id,
+                url: managedPage.page.url(),
+                title: await managedPage.page.title(),
+                active: id === this.activeTabId,
+            });
+        }
+        return tabs;
+    }
+    getActivePage() {
+        if (!this.activeTabId) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "No active tab. Open a tab first.");
+        }
+        const managedPage = this.pages.get(this.activeTabId);
+        if (!managedPage) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Active tab not found. This is a bug.");
+        }
+        return managedPage.page;
+    }
+    getActiveTabId() {
+        if (!this.activeTabId) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "No active tab");
+        }
+        return this.activeTabId;
+    }
+    getConsoleErrors() {
+        if (!this.activeTabId)
+            return [];
+        const managedPage = this.pages.get(this.activeTabId);
+        return managedPage?.consoleErrors ?? [];
+    }
+    getNetworkErrors() {
+        if (!this.activeTabId)
+            return [];
+        const managedPage = this.pages.get(this.activeTabId);
+        return managedPage?.networkErrors ?? [];
+    }
+    clearErrors() {
+        if (!this.activeTabId)
+            return;
+        const managedPage = this.pages.get(this.activeTabId);
+        if (managedPage) {
+            managedPage.consoleErrors = [];
+            managedPage.networkErrors = [];
+        }
+    }
+    hasPages() {
+        return this.pages.size > 0;
+    }
+}
+//# sourceMappingURL=page-manager.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-manager.js","sourceRoot":"","sources":["../../src/browser/page-manager.ts"],"names":[],"mappings":"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"}

package/dist/dev/auditor.d.ts

@@ -0,0 +1,39 @@
+import type { Page, CDPSession } from "puppeteer";
+export type AuditCategory = "a11y" | "performance" | "seo" | "contrast" | "links";
+export interface AuditFinding {
+    category: AuditCategory;
+    severity: "error" | "warning" | "info";
+    message: string;
+    element?: string;
+    recommendation: string;
+}
+export interface AuditResult {
+    categories_checked: AuditCategory[];
+    findings: AuditFinding[];
+    summary: string;
+}
+/**
+ * Compute relative luminance of a color per WCAG 2.1.
+ * Input: r, g, b in 0-255 range.
+ */
+export declare function relativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Compute WCAG 2.1 contrast ratio between two colors.
+ * Returns a ratio >= 1.
+ */
+export declare function contrastRatio(foregroundRgb: [number, number, number], backgroundRgb: [number, number, number]): number;
+/**
+ * Parse a CSS color string like "rgb(255, 0, 0)" or "rgba(255, 0, 0, 1)" to [r, g, b].
+ * Returns null if unparseable.
+ */
+export declare function parseRgbColor(colorString: string): [number, number, number] | null;
+export declare class Auditor {
+    audit(page: Page, session: CDPSession, categories?: AuditCategory[]): Promise<AuditResult>;
+    private runCategoryAudit;
+    private auditAccessibility;
+    private auditPerformance;
+    private auditSeo;
+    private auditContrast;
+    private auditLinks;
+}
+//# sourceMappingURL=auditor.d.ts.map

package/dist/dev/auditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../../src/dev/auditor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGlD,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,aAAa,GACb,KAAK,GACL,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,kBAAkB,EAAE,aAAa,EAAE,CAAC;IACpC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACvC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACtC,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,GAClB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAYjC;AAmBD,qBAAa,OAAO;IACZ,KAAK,CACT,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,UAAU,EACnB,UAAU,CAAC,EAAE,aAAa,EAAE,GAC3B,OAAO,CAAC,WAAW,CAAC;YAiCT,gBAAgB;YAmBhB,kBAAkB;YAkGlB,gBAAgB;YA4EhB,QAAQ;YA2GR,aAAa;YAsGb,UAAU;CA+EzB"}