@the-forge-flow/camoufox-pi 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MonsieurBarti
+
+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,209 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/MonsieurBarti/The-Forge-Flow-CC/refs/heads/main/assets/forge-banner.png" alt="The Forge Flow" width="100%">
+
+  <h1>@the-forge-flow/camoufox-pi</h1>
+
+  <p>
+    <strong>Stealth web search and URL fetching for the PI coding agent</strong>
+  </p>
+
+  <p>
+    <a href="https://github.com/MonsieurBarti/camoufox-pi/actions/workflows/ci.yml">
+      <img src="https://img.shields.io/github/actions/workflow/status/MonsieurBarti/camoufox-pi/ci.yml?label=CI&style=flat-square" alt="CI Status">
+    </a>
+    <a href="https://www.npmjs.com/package/@the-forge-flow/camoufox-pi">
+      <img src="https://img.shields.io/npm/v/@the-forge-flow/camoufox-pi?style=flat-square" alt="npm version">
+    </a>
+    <a href="LICENSE">
+      <img src="https://img.shields.io/github/license/MonsieurBarti/camoufox-pi?style=flat-square" alt="License">
+    </a>
+  </p>
+</div>
+
+---
+
+## What it does
+
+PI extension that wraps [Camoufox](https://github.com/daijro/camoufox) — a Firefox fork patched at the C++ level for anti-fingerprint resistance — to give the coding agent a stealth-capable web search and URL fetcher. For sites that block conventional headless browsers (Cloudflare, DataDome, PerimeterX, Turnstile, Google's bot wall, LinkedIn, etc.).
+
+Sibling to [`@the-forge-flow/lightpanda-pi`](https://github.com/MonsieurBarti/lightpanda-pi). Where `lightpanda-pi` is the fast/light choice for cooperative targets, `camoufox-pi` is the choice when sites actively block bots. Camoufox patches fingerprint surfaces inside SpiderMonkey / Gecko C++, before JavaScript can observe them — fundamentally more robust than runtime JS-injection approaches like `puppeteer-extra-plugin-stealth`. Independent benchmarks report ~100% bypass rate vs ~33% for Playwright-Chromium.
+
+## Features
+
+- `tff-fetch_url` — fetch a URL via stealth Firefox and return HTML
+- `tff-search_web` — web search via DuckDuckGo (Google lands in a follow-up slice)
+- **Stealth properties** — C++-level fingerprint spoofing, patched canvas/WebGL, Juggler (Firefox remote) protocol — not CDP
+- **SSRF protection** — private IP ranges, link-local, loopback, cloud metadata, and CGNAT blocked pre-navigation
+- **Scheme allow-list** — only `http:` / `https:` accepted at the tool boundary; `file:`, `javascript:`, `data:`, `chrome://` rejected
+- **Response size caps** — UTF-8-safe truncation at `max_bytes` (default 2 MiB, max 50 MiB) with `truncated` flag
+- **`isolate: true` opt-in** — one-shot browser context per call, no cookie/storage bleed
+- **Lazy binary download** — ~500 MB Camoufox binary fetched on first use, not install
+
+## Trade-offs vs lightpanda-pi
+
+| | lightpanda-pi | camoufox-pi |
+|---|---|---|
+| RSS per session | ~50 MB | 200–1300 MB |
+| Binary size | few MB | 300–700 MB (lazy download on first use) |
+| Cold start | instant | 1–3 s |
+| Cooperative sites | yes | yes |
+| WAF-protected sites | no | yes |
+| Canvas/WebGL | not rendered | spoofed (except post-2026-03 regression — see SPEC §17) |
+| TLS/JA3 fingerprint | libcurl | Firefox (unspoofed — use proxy if target fingerprints TLS) |
+
+Pick one based on target profile. They can coexist but share no runtime.
+
+## Requirements
+
+- Node.js >= 22.5.0
+- PI (`pi` CLI) installed
+- ~500 MB disk space for the Camoufox binary (lazy downloaded on first use)
+- macOS or Linux (Windows untested)
+
+## Installation
+
+```bash
+# From npm (recommended)
+pi install npm:@the-forge-flow/camoufox-pi
+
+# Project-local only
+pi install -l npm:@the-forge-flow/camoufox-pi
+
+# From GitHub (tracks main)
+pi install git:github.com/MonsieurBarti/camoufox-pi
+
+# Pin a version
+pi install npm:@the-forge-flow/camoufox-pi@0.1.0
+```
+
+Then reload PI with `/reload` (or restart it). First tool call downloads the Camoufox binary (~500 MB, one-time).
+
+## Usage
+
+### Tools
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `tff-fetch_url` | Fetch a URL via stealth Firefox, return HTML | `url`, `timeout_ms`, `max_bytes`, `isolate` |
+| `tff-search_web` | Web search (DuckDuckGo) | `query`, `max_results`, `timeout_ms`, `isolate` |
+
+**`tff-fetch_url`** returns `{ url, finalUrl, status, html, bytes, truncated }`. HTML is returned raw (no markdown conversion in v0.1.0). `truncated: true` means the response exceeded `max_bytes` and was cut at a UTF-8-safe boundary.
+
+**`tff-search_web`** returns `{ engine, query, results[], atLimit }` where each result is `{ title, url, snippet, rank }`. `atLimit` means `results.length === max_results` — could mean DDG had more, or exactly that many. No ground-truth "has_more" signal is available from the engine.
+
+### Security
+
+- **Scheme allow-list.** Only `http:` and `https:` accepted at the tool boundary. `file:`, `javascript:`, `data:`, `chrome://` and similar are rejected before any navigation.
+- **SSRF protection.** Targets that resolve to private IP ranges (loopback, RFC1918, link-local, cloud metadata 169.254.169.254, CGNAT, IPv6 ULAs) are rejected pre-navigation. No opt-out in v0.1.0.
+- **Response truncation.** Bodies exceeding `max_bytes` are cut at a UTF-8-safe byte boundary and flagged `truncated: true`. Default 2 MiB, max 50 MiB.
+- **Untrusted content.** The `tff-fetch_url` prompt guidelines explicitly warn the LLM that fetched HTML is UNTRUSTED and must not be executed, eval'd, or treated as authoritative instructions.
+- **`isolate: true`** for sensitive fetches — fresh `BrowserContext` per call, no cookie/storage reuse with the shared session context.
+
+## Configuration
+
+v0.1.0 does **not** load a config file. All configuration is per-call via tool parameters. A layered config (project-local + user-global + env + fs.watch reload) lands in a later slice.
+
+Defaults baked into `DEFAULT_CONFIG`:
+
+| Field | Default | Description |
+|---|---|---|
+| `timeoutMs` | `30000` | Per-navigation timeout (ms), overridable via `timeout_ms` |
+| `maxBytes` | `2097152` | 2 MiB response cap for `fetch_url`, overridable via `max_bytes` |
+| `defaultEngine` | `"duckduckgo"` | Only valid value in v0.1.0 |
+
+## Architecture
+
+```
+┌─────────────────────┐
+│ PI host process      │
+│ └─ loads extension   │
+└─────────┬────────────┘
+          │  session_start
+          ▼
+┌──────────────────────────────────────────────────────┐
+│ camoufox-pi extension (in PI process)                │
+│                                                      │
+│   CamoufoxService (singleton)                        │
+│   └─ CamoufoxClient                                  │
+│       ├─ one Browser                                 │
+│       ├─ one BrowserContext (cookies persist)        │
+│       └─ Launcher (camoufox-js, isolated)            │
+│                                                      │
+│   Tools: tff-fetch_url / tff-search_web ─┐           │
+│                                          ▼           │
+│                             CamoufoxClient.navigate  │
+└──────────────────────────────────────────────────────┘
+                         │  Playwright (Juggler)
+                         ▼
+              ┌──────────────────────┐
+              │ Camoufox process     │
+              │ (patched Firefox)    │
+              └──────────────────────┘
+```
+
+**Launcher isolation.** `src/client/launcher.ts` is the **only** file that imports `camoufox-js`. Every other file uses the `Launcher` interface. This keeps the third-party Node wrapper (Apify's port of Python-official Camoufox) swappable — a future official binding, patchright, or a Python subprocess slots in with a one-file change.
+
+**Fake-launcher test seam.** `tests/helpers/fake-launcher.ts` injects a stub `BrowserContext` so every unit test runs without downloading the ~500 MB binary or spawning a real Firefox.
+
+Key components in `src/`:
+
+| File | Purpose |
+|---|---|
+| `src/index.ts` | Extension factory — session lifecycle, tool/command/hook registration |
+| `src/services/camoufox-service.ts` | Singleton service owning the `CamoufoxClient`, kicks off `ensureReady()` from `session_start` |
+| `src/client/camoufox-client.ts` | Lifecycle + `navigate` + `fetchUrl` + `search` + `close` |
+| `src/client/launcher.ts` | `Launcher` interface + `RealLauncher` (sole `camoufox-js` importer) |
+| `src/client/signal.ts` | `combineSignals(external, timeoutMs)` — turn-signal + timeout composition |
+| `src/errors.ts` | `CamoufoxError` discriminated union + `CamoufoxErrorBox` + `mapPlaywrightError` |
+| `src/security/ssrf.ts` | Private-IP + link-local + cloud-metadata blocklist, pre-navigation |
+| `src/search/adapters/duckduckgo.ts` | DOM-query SERP parser against `html.duckduckgo.com` |
+| `src/tools/fetch-url.ts` | `tff-fetch_url` tool definition |
+| `src/tools/search-web.ts` | `tff-search_web` tool definition |
+| `src/tools/formats.ts` | TypeBox `format: "uri"` scheme allow-list hook |
+| `src/tools/types.ts` | `ToolDefinition` structural interface |
+| `src/types.ts` | `CamoufoxConfig` + `DEFAULT_CONFIG` |
+
+## Development
+
+```bash
+bun install              # install deps
+bun run test             # vitest once
+bun run test:watch       # vitest watch mode
+bun run test:coverage    # v8 coverage
+bun run lint             # biome check
+bun run lint:fix         # auto-fix
+bun run build            # tsc → dist/
+bun run typecheck        # type-only check
+```
+
+Pre-commit hooks (lefthook) run biome, typecheck, and tests in parallel.
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) — enforced by commitlint.
+
+## Known limitations
+
+v0.1.0 is the foundational slice. The following are deliberately deferred to later slices:
+
+- **DuckDuckGo only.** Google / Brave / Bing adapters land in follow-up slices; Google requires stealth tuning that deserves its own slice.
+- **No retries.** `network`, `timeout`, `playwright_disconnected`, and `browser_crashed` surface as errors — no exponential backoff.
+- **No cache.** No in-memory LRU, no on-disk cache, no request coalescing.
+- **No blocked-detection.** CF/DataDome/PerimeterX challenge pages return as HTTP 200 with challenge HTML; no structured `{ type: "blocked" }` yet.
+- **No observability.** No metrics, no event-bus events, no span IDs. `binary_download_progress` not emitted (only `console.debug`).
+- **No config layering.** No config file, no env vars, no `fs.watch` reload. Per-call params and `DEFAULT_CONFIG` only.
+- **TLS/JA3 fingerprint not spoofed.** Camoufox inherits Firefox's ClientHello. Targets that fingerprint TLS (aggressive DataDome, Akamai Bot Manager tier 3) will still detect. Mitigation deferred to a proxy-integration slice.
+- **Sticky launch failure.** A failed `ensureReady()` marks the client permanently failed. Retrying requires reconstructing the service. Auto-reconnect lands in the retry-and-reconnect slice.
+- **Third-party Node wrapper.** Upstream Camoufox endorses only the Python wrapper. `camoufox-js` (Apify, MPL-2.0) is the Node port; launcher isolation keeps it swappable.
+
+Detailed design and deferred-feature landing plan live in local-only `docs/` (not published).
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing`)
+3. Commit with conventional commits (`git commit -m "feat: add something"`)
+4. Push to the branch (`git push origin feature/amazing`)
+5. Open a Pull Request
+
+## License
+
+MIT

package/dist/client/camoufox-client.d.ts

@@ -0,0 +1,62 @@
+import type { Browser, BrowserContext, Page } from "playwright-core";
+import type { RawResult } from "../search/types.js";
+import { type LookupFn } from "../security/ssrf.js";
+import type { CamoufoxConfig } from "../types.js";
+import type { Launcher } from "./launcher.js";
+export interface CamoufoxClientOptions {
+    readonly launcher: Launcher;
+    readonly config?: CamoufoxConfig;
+    /** Optional DNS lookup override; used to inject stubs in tests. */
+    readonly ssrfLookup?: LookupFn;
+}
+export declare class CamoufoxClient {
+    private readonly launcher;
+    private readonly config;
+    private readonly ssrfLookup;
+    private state;
+    constructor(opts: CamoufoxClientOptions);
+    isAlive(): boolean;
+    ensureReady(signal?: AbortSignal): Promise<void>;
+    fetchUrl(url: string, opts: {
+        signal: AbortSignal;
+        timeoutMs?: number;
+        maxBytes?: number;
+        isolate?: boolean;
+    }): Promise<{
+        html: string;
+        status: number;
+        finalUrl: string;
+        bytes: number;
+        truncated: boolean;
+    }>;
+    search(query: string, opts: {
+        signal: AbortSignal;
+        maxResults?: number;
+        timeoutMs?: number;
+        isolate?: boolean;
+    }): Promise<{
+        results: RawResult[];
+        engine: "duckduckgo";
+        query: string;
+    }>;
+    protected navigate(url: string, opts: {
+        signal: AbortSignal;
+        timeoutMs: number;
+        waitUntil: "load" | "domcontentloaded" | "networkidle";
+        isolate?: boolean;
+    }): Promise<{
+        page: Page;
+        response: {
+            status(): number;
+            url(): string;
+        };
+        cleanup: () => void;
+    }>;
+    close(): Promise<void>;
+    protected getConfig(): CamoufoxConfig;
+    protected getContext(): BrowserContext;
+    protected getBrowser(): Browser;
+    private doLaunch;
+    private awaitWithSignal;
+}
+//# sourceMappingURL=camoufox-client.d.ts.map

package/dist/client/camoufox-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camoufox-client.d.ts","sourceRoot":"","sources":["../../src/client/camoufox-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAIrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,KAAK,QAAQ,EAAoB,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAY9C,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;CAC/B;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,KAAK,CAAkC;gBAEnC,IAAI,EAAE,qBAAqB;IAMvC,OAAO,IAAI,OAAO;IAIZ,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,QAAQ,CACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QACL,MAAM,EAAE,WAAW,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KAClB,GACC,OAAO,CAAC;QACV,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,OAAO,CAAC;KACnB,CAAC;IAqEI,MAAM,CACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;QACL,MAAM,EAAE,WAAW,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KAClB,GACC,OAAO,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;cAiDzD,QAAQ,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QACL,MAAM,EAAE,WAAW,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,CAAC;QACvD,OAAO,CAAC,EAAE,OAAO,CAAC;KAClB,GACC,OAAO,CAAC;QACV,IAAI,EAAE,IAAI,CAAC;QACX,QAAQ,EAAE;YAAE,MAAM,IAAI,MAAM,CAAC;YAAC,GAAG,IAAI,MAAM,CAAA;SAAE,CAAC;QAC9C,OAAO,EAAE,MAAM,IAAI,CAAC;KACpB,CAAC;IAuDI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,SAAS,CAAC,SAAS,IAAI,cAAc;IAIrC,SAAS,CAAC,UAAU,IAAI,cAAc;IAUtC,SAAS,CAAC,UAAU,IAAI,OAAO;YAUjB,QAAQ;YAsBR,eAAe;CAqB7B"}

package/dist/client/camoufox-client.js

@@ -0,0 +1,277 @@
+import { CamoufoxErrorBox, mapPlaywrightError } from "../errors.js";
+import { duckduckgoAdapter } from "../search/adapters/duckduckgo.js";
+import { assertSafeTarget } from "../security/ssrf.js";
+import { DEFAULT_CONFIG } from "../types.js";
+import { combineSignals } from "./signal.js";
+export class CamoufoxClient {
+    launcher;
+    config;
+    ssrfLookup;
+    state = { status: "idle" };
+    constructor(opts) {
+        this.launcher = opts.launcher;
+        this.config = opts.config ?? DEFAULT_CONFIG;
+        this.ssrfLookup = opts.ssrfLookup;
+    }
+    isAlive() {
+        return this.state.status === "ready" && this.state.browser?.isConnected() === true;
+    }
+    async ensureReady(signal) {
+        if (this.state.status === "ready")
+            return;
+        if (this.state.status === "failed" && this.state.error)
+            throw this.state.error;
+        if (this.state.status === "closed") {
+            throw new CamoufoxErrorBox({ type: "playwright_disconnected" });
+        }
+        if (this.state.status === "launching" && this.state.launchPromise) {
+            await this.awaitWithSignal(this.state.launchPromise, signal);
+            return;
+        }
+        const launchPromise = this.doLaunch();
+        this.state = { status: "launching", launchPromise };
+        await this.awaitWithSignal(launchPromise, signal);
+    }
+    async fetchUrl(url, opts) {
+        await this.ensureReady(opts.signal);
+        if (opts.timeoutMs !== undefined &&
+            (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs < 1_000 || opts.timeoutMs > 120_000)) {
+            throw new CamoufoxErrorBox({
+                type: "config_invalid",
+                field: "timeoutMs",
+                reason: `must be integer in [1000, 120000], got ${opts.timeoutMs}`,
+            });
+        }
+        if (opts.maxBytes !== undefined &&
+            (!Number.isInteger(opts.maxBytes) || opts.maxBytes < 1_024 || opts.maxBytes > 52_428_800)) {
+            throw new CamoufoxErrorBox({
+                type: "config_invalid",
+                field: "maxBytes",
+                reason: `must be integer in [1024, 52428800], got ${opts.maxBytes}`,
+            });
+        }
+        try {
+            await assertSafeTarget(url, this.ssrfLookup ? { lookup: this.ssrfLookup } : {});
+        }
+        catch (err) {
+            throw new CamoufoxErrorBox({
+                type: "config_invalid",
+                field: "url",
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const navOpts = {
+            signal: opts.signal,
+            timeoutMs: opts.timeoutMs ?? this.config.timeoutMs,
+            waitUntil: "load",
+        };
+        if (opts.isolate !== undefined)
+            navOpts.isolate = opts.isolate;
+        const { page, response, cleanup } = await this.navigate(url, navOpts);
+        try {
+            const rawHtml = await page.content();
+            const maxBytes = opts.maxBytes ?? this.config.maxBytes;
+            const rawBytes = Buffer.byteLength(rawHtml, "utf8");
+            let html = rawHtml;
+            let bytes = rawBytes;
+            let truncated = false;
+            if (rawBytes > maxBytes) {
+                const buf = Buffer.from(rawHtml, "utf8");
+                html = buf.subarray(0, maxBytes).toString("utf8");
+                bytes = Buffer.byteLength(html, "utf8");
+                truncated = true;
+            }
+            return { html, status: response.status(), finalUrl: response.url(), bytes, truncated };
+        }
+        catch (err) {
+            if (opts.signal.aborted) {
+                throw new CamoufoxErrorBox({ type: "aborted" });
+            }
+            if (err instanceof CamoufoxErrorBox)
+                throw err;
+            throw err;
+        }
+        finally {
+            cleanup();
+            await page.close().catch(() => undefined);
+        }
+    }
+    async search(query, opts) {
+        await this.ensureReady(opts.signal);
+        const maxResults = opts.maxResults ?? 10;
+        if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 50) {
+            throw new CamoufoxErrorBox({
+                type: "config_invalid",
+                field: "maxResults",
+                reason: `must be integer in [1, 50], got ${maxResults}`,
+            });
+        }
+        if (opts.timeoutMs !== undefined &&
+            (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs < 1_000 || opts.timeoutMs > 120_000)) {
+            throw new CamoufoxErrorBox({
+                type: "config_invalid",
+                field: "timeoutMs",
+                reason: `must be integer in [1000, 120000], got ${opts.timeoutMs}`,
+            });
+        }
+        const adapter = duckduckgoAdapter;
+        const url = adapter.buildUrl(query);
+        const navOpts = {
+            signal: opts.signal,
+            timeoutMs: opts.timeoutMs ?? this.config.timeoutMs,
+            waitUntil: adapter.waitStrategy.readyState,
+        };
+        if (opts.isolate !== undefined)
+            navOpts.isolate = opts.isolate;
+        const { page, cleanup } = await this.navigate(url, navOpts);
+        try {
+            const results = await adapter.parseResults(page, maxResults);
+            return { results, engine: "duckduckgo", query };
+        }
+        catch (err) {
+            if (opts.signal.aborted) {
+                throw new CamoufoxErrorBox({ type: "aborted" });
+            }
+            if (err instanceof CamoufoxErrorBox)
+                throw err;
+            throw err;
+        }
+        finally {
+            cleanup();
+            await page.close().catch(() => undefined);
+        }
+    }
+    async navigate(url, opts) {
+        let context;
+        let ownContext = false;
+        if (opts.isolate) {
+            const browser = this.getBrowser();
+            context = await browser.newContext();
+            ownContext = true;
+        }
+        else {
+            context = this.getContext();
+        }
+        const combined = combineSignals(opts.signal, opts.timeoutMs);
+        const page = await context.newPage();
+        const abortHandler = () => {
+            page.close().catch(() => undefined);
+        };
+        combined.signal.addEventListener("abort", abortHandler, { once: true });
+        const cleanup = () => {
+            combined.signal.removeEventListener("abort", abortHandler);
+            combined.cleanup();
+            if (ownContext) {
+                context.close().catch(() => undefined);
+            }
+        };
+        const started = Date.now();
+        try {
+            const response = await page.goto(url, {
+                timeout: opts.timeoutMs,
+                waitUntil: opts.waitUntil,
+            });
+            if (!response) {
+                throw new CamoufoxErrorBox({
+                    type: "network",
+                    cause: "goto returned null",
+                    url,
+                });
+            }
+            const status = response.status();
+            if (status >= 400) {
+                throw new CamoufoxErrorBox({ type: "http", status, url: response.url() });
+            }
+            return { page, response, cleanup };
+        }
+        catch (err) {
+            cleanup();
+            await page.close().catch(() => undefined);
+            if (err instanceof CamoufoxErrorBox)
+                throw err;
+            const mapped = mapPlaywrightError(err, {
+                url,
+                phase: "nav",
+                elapsedMs: Date.now() - started,
+                signal: opts.signal,
+            });
+            throw new CamoufoxErrorBox(mapped);
+        }
+    }
+    async close() {
+        const browser = this.state.browser;
+        this.state = { status: "closed" };
+        if (browser) {
+            try {
+                await browser.close();
+            }
+            catch {
+                // browser already dead — ignore
+            }
+        }
+    }
+    getConfig() {
+        return this.config;
+    }
+    getContext() {
+        if (this.state.status !== "ready" || !this.state.context) {
+            throw new CamoufoxErrorBox({ type: "playwright_disconnected" });
+        }
+        if (this.state.browser?.isConnected() !== true) {
+            throw new CamoufoxErrorBox({ type: "playwright_disconnected" });
+        }
+        return this.state.context;
+    }
+    getBrowser() {
+        if (this.state.status !== "ready" || !this.state.browser) {
+            throw new CamoufoxErrorBox({ type: "playwright_disconnected" });
+        }
+        if (!this.state.browser.isConnected()) {
+            throw new CamoufoxErrorBox({ type: "playwright_disconnected" });
+        }
+        return this.state.browser;
+    }
+    async doLaunch() {
+        try {
+            const { browser, context, version } = await this.launcher.launch();
+            // If close() was called while we were launching, tear down the fresh
+            // browser instead of resurrecting into ready. Leaves state as "closed".
+            if (this.state.status !== "launching") {
+                await browser.close().catch(() => undefined);
+                return;
+            }
+            this.state = { status: "ready", browser, context, version };
+        }
+        catch (err) {
+            const stderr = err instanceof Error ? err.message : String(err);
+            const boxed = new CamoufoxErrorBox({ type: "browser_launch_failed", stderr });
+            // If close() was called during the failed launch, keep the closed state
+            // (don't overwrite it with failed — closed is terminal).
+            if (this.state.status === "launching") {
+                this.state = { status: "failed", error: boxed };
+            }
+            throw boxed;
+        }
+    }
+    async awaitWithSignal(p, signal) {
+        if (!signal)
+            return p;
+        if (signal.aborted)
+            throw new CamoufoxErrorBox({ type: "aborted" });
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                signal.removeEventListener("abort", onAbort);
+                reject(new CamoufoxErrorBox({ type: "aborted" }));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            p.then((v) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(v);
+            }, (e) => {
+                signal.removeEventListener("abort", onAbort);
+                reject(e);
+            });
+        });
+    }
+}
+//# sourceMappingURL=camoufox-client.js.map

package/dist/client/camoufox-client.js.map

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

package/dist/client/launcher.d.ts

@@ -0,0 +1,28 @@
+import { type Browser, type BrowserContext } from "playwright-core";
+export interface LaunchedBrowser {
+    readonly browser: Browser;
+    readonly context: BrowserContext;
+    readonly version: string;
+}
+export interface Launcher {
+    launch(): Promise<LaunchedBrowser>;
+}
+export interface RealLauncherOptions {
+    /** Headless? Default: true. Override for local debugging. */
+    readonly headless?: boolean;
+    /** Override the Camoufox binary path. */
+    readonly binaryPath?: string;
+}
+/**
+ * Real launcher: calls camoufox-js for fingerprint + binary-aware
+ * launch options, then drives playwright-core's firefox.launch.
+ * This is the ONLY file in the codebase that may import camoufox-js.
+ * Spec: §2, §8.
+ */
+export declare class RealLauncher implements Launcher {
+    private readonly headless;
+    private readonly binaryPath;
+    constructor(opts?: RealLauncherOptions);
+    launch(): Promise<LaunchedBrowser>;
+}
+//# sourceMappingURL=launcher.d.ts.map

package/dist/client/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/client/launcher.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAW,MAAM,iBAAiB,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACxB,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,IAAI,GAAE,mBAAwB;IAKpC,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC;CAUxC"}

package/dist/client/launcher.js

@@ -0,0 +1,30 @@
+// Launcher interface. The ONE place that may import camoufox-js.
+// RealLauncher lands in a later task; tests use a fake via tests/helpers/fake-launcher.
+// Spec: §2, §4.3, §8.
+import { launchOptions as camoufoxLaunchOptions } from "camoufox-js";
+import { firefox } from "playwright-core";
+/**
+ * Real launcher: calls camoufox-js for fingerprint + binary-aware
+ * launch options, then drives playwright-core's firefox.launch.
+ * This is the ONLY file in the codebase that may import camoufox-js.
+ * Spec: §2, §8.
+ */
+export class RealLauncher {
+    headless;
+    binaryPath;
+    constructor(opts = {}) {
+        this.headless = opts.headless ?? true;
+        this.binaryPath = opts.binaryPath;
+    }
+    async launch() {
+        const launchOpts = (await camoufoxLaunchOptions({
+            headless: this.headless,
+            ...(this.binaryPath !== undefined ? { executablePath: this.binaryPath } : {}),
+        }));
+        const browser = await firefox.launch(launchOpts);
+        const context = await browser.newContext();
+        const version = browser.version();
+        return { browser, context, version };
+    }
+}
+//# sourceMappingURL=launcher.js.map

package/dist/client/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/client/launcher.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,wFAAwF;AACxF,sBAAsB;AAEtB,OAAO,EAAE,aAAa,IAAI,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAqC,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAmB7E;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACP,QAAQ,CAAU;IAClB,UAAU,CAAqB;IAEhD,YAAY,OAA4B,EAAE;QACzC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,MAAM;QACX,MAAM,UAAU,GAAG,CAAC,MAAM,qBAAqB,CAAC;YAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E,CAAC,CAAyC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;CACD"}