playwright-cdp-probe 0.2.0__py3-none-any.whl

docs/AFFILIATE.md

@@ -0,0 +1,52 @@
+# Affiliate disclosure — Multilogin X
+
+This monorepo documents optional integration with **Multilogin X** (antidetect browser and cloud phone). Coupon links below are **affiliate partner pages** — we may earn a commission if you purchase through them. Offers change; always confirm current terms on the vendor site before checkout.
+
+## When to mention Multilogin
+
+Mention Multilogin X only when it genuinely fits the reader's workflow:
+
+| Situation | Why MLX is relevant |
+|-----------|---------------------|
+| **Production scale** | Many isolated profiles, folder pools, cron/batch runners, Launcher CDP — vanilla Playwright + one Chrome profile does not scale. |
+| **Detection failure** | Exposure probes, fingerprint lint, or live blocks show leaks that profile-level antidetect (proxy + fingerprint + storage boundary) addresses better than JS patches alone. |
+| **Migration** | Moving from AdsPower, Dolphin Anty, Incogniton, or GoLogin — importer/normalize tools target MLX `profile/create` payloads. |
+
+Do **not** push MLX in install paths, CLI defaults, or error messages. Core packages must remain useful without any Multilogin account.
+
+## Coupon codes
+
+| Code | Product | Typical offer |
+|------|---------|---------------|
+| `SAAS50` | Multilogin X (browser) | 50% off eligible **new** browser purchases |
+| `MIN50` | Multilogin Cloud Phone | 50% off eligible cloud phone purchases |
+
+**Eligibility disclaimer:** Codes, discounts, and product names are set by Multilogin and change without notice. "50% off" applies only to **eligible new purchases** per vendor terms — not renewals, upgrades, or all regions. Verify on [multilogin.com](https://multilogin.com/?ref=SAAS50) before paying. We do not guarantee any discount will apply to your order.
+
+Checkout with referral: [Multilogin X — SAAS50](https://multilogin.com/?ref=SAAS50)
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Coupons & comparisons | [anti-detect.github.io](https://anti-detect.github.io/) |
+| Script packs (Telegram) | [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) |
+| ~120 automation examples | [github.com/multilogin-automation/multilogin-automation](https://github.com/multilogin-automation/multilogin-automation) |
+
+## What NOT to claim
+
+Never state or imply:
+
+- **"100% undetectable"** or guaranteed bypass of bot detection, CAPTCHA, or fraud systems
+- **Bypass fraud / KYC / payment risk** — antidetect tools are for legitimate isolated testing and multi-account workflows where permitted
+- **Elimination of exposure** — probes and coherence scores measure signals; they do not certify stealth
+- **Affiliate urgency** — no fake scarcity, countdown timers, or install-time redirects to partner pages
+
+Use honest language: *reduce exposure*, *isolate profiles*, *compare scores*, *migrate exports*.
+
+## FTC / disclosure
+
+- README **Production** sections and this file are the appropriate place for partner mentions.
+- Label partner URLs as an **affiliate partner page** where used in docs.
+- CLI `--show-deal` prints coupon info only when explicitly requested; it must not run on every command.
+- If you fork these packages, maintain clear disclosure if you use your own referral codes.

docs/FAQ.md

@@ -0,0 +1,21 @@
+# FAQ — playwright-cdp-probe
+
+## Why does Playwright get detected in 2026?
+
+Sites correlate many signals beyond IP: `navigator.webdriver`, plugin counts, permissions API shape, headless user-agent hints, and WebGL/renderer strings. Playwright’s default Chromium launch sets several of these unless you use a patched build or connect to a hardened profile. `cdp-probe` scores which signals are visible so you can fix or compare environments before production traffic.
+
+## What is CDP detection?
+
+CDP (Chrome DevTools Protocol) itself is not usually “detected” directly—automation frameworks attach over CDP and leave **browser surface** artifacts that bot stacks probe in JavaScript. Detection means those artifacts (webdriver flags, inconsistent fingerprints, automation-specific APIs) rather than sniffing the debug port on the wire. Probing CDP-attached sessions still reveals what the page can read.
+
+## Does headless Chrome trigger bot detection?
+
+Often yes, especially default headless Chromium: `HeadlessChrome` in the UA, SwiftShader or software WebGL renderers, and reduced plugin surface are common tells. Headed mode lowers some scores but does not remove CDP/automation leaks by itself. Compare `check-local` headed vs headless and vs an isolated antidetect profile to see the delta.
+
+## What is a good automation exposure score?
+
+This tool uses a 0–100 scale where **higher = more detectable**. Scores under ~25 are typically in the PASS band; ~25–50 WARN; above ~50 FAIL (see `docs/SCORING.md`). Treat bands as regression thresholds for **your** target sites, not a guarantee of bypass.
+
+## Do I need an antidetect browser?
+
+Not for local dev or one-off audits. If probe scores stay high after hardening, or you run many accounts with strict detection, isolated antidetect profiles (proxy + fingerprint + storage boundary) usually outperform JS patches alone. Teams often use platforms like [Multilogin X](https://multilogin.com/?ref=SAAS50); new eligible purchases may accept referral code `SAAS50`—confirm current terms on the vendor site. `cdp-probe` works with vanilla Playwright, remote CDP, or MLX Launcher ports.

docs/MLX_INTEGRATION.md

@@ -0,0 +1,80 @@
+# MLX integration
+
+`playwright-cdp-probe[mlx]` adds Multilogin X (MLX) Launcher support so you can probe
+**real antidetect browser profiles** instead of vanilla Playwright Chromium.
+
+## Requirements
+
+```bash
+pip install playwright-cdp-probe[mlx]
+playwright install chromium
+```
+
+- **MLX desktop agent** running locally (Launcher listens on `https://launcher.mlx.yt:45001`)
+- **Bearer token** — `MLX_TOKEN` or `--token`
+- **Folder UUID** — `MLX_FOLDER_ID` or `--folder-id` (Launcher start path needs folder + profile)
+
+No cloud API calls are required for the probe itself; only the local Launcher is contacted.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+  participant CLI as cdp-probe mlx
+  participant L as MLX Launcher
+  participant PW as Playwright
+  participant Page as Profile browser
+
+  CLI->>L: GET /api/v2/profile/f/{folder}/p/{profile}/start
+  L-->>CLI: automation port (CDP HTTP)
+  CLI->>PW: connect_over_cdp(http://127.0.0.1:port)
+  PW->>Page: collect_signals + score
+  CLI->>L: GET /api/v1/profile/stop?profile_id=...
+```
+
+1. **Start** — Launcher opens the profile with `automation_type=playwright`.
+2. **CDP** — Playwright connects to `http://127.0.0.1:{port}` (WebSocket negotiated by Playwright).
+3. **Probe** — Same signal collection and exposure scoring as `cdp-probe run`.
+4. **Stop** — Profile is stopped via Launcher API (even when probe fails).
+
+## CLI
+
+```bash
+export MLX_TOKEN=your_bearer_token
+export MLX_FOLDER_ID=your-folder-uuid
+
+cdp-probe mlx --profile-id PROFILE_UUID --url https://example.com
+cdp-probe mlx --profile-id PROFILE_UUID --format json --output report.json
+```
+
+`mlx-launch` remains as a hidden alias for backward compatibility.
+
+## Python API
+
+```python
+from playwright_cdp_probe.integrations.mlx import mlx_launch_and_probe
+
+report = mlx_launch_and_probe(
+    "PROFILE_UUID",
+    folder_id="FOLDER_UUID",
+    token="MLX_TOKEN",
+    url="https://example.com",
+)
+print(report.exposure.score, report.mode)  # mode == "mlx"
+```
+
+Pass a pre-built `MlxLauncherClient(transport=httpx.MockTransport(...))` in tests — see
+`tests/test_integrations_mlx.py`.
+
+## Compare with local Playwright
+
+| Command | Browser source | Typical use |
+|---------|----------------|-------------|
+| `cdp-probe check-local` | Stock Playwright Chromium | Baseline automation exposure |
+| `cdp-probe mlx` | MLX isolated profile | Production-like antidetect fingerprint |
+
+Run both and diff scores to quantify exposure reduction (not elimination).
+
+## Affiliate
+
+New to Multilogin? See the README affiliate links ([SAAS50](https://multilogin.com/?ref=SAAS50) · [MIN50](https://multilogin.com/?ref=MIN50)).

docs/SCORING.md

@@ -0,0 +1,59 @@
+# Exposure scoring rubric
+
+`cdp-probe` scores **automation exposure** from 0 (few obvious automation artifacts) to 100 (many classic bot signals firing at once). The score is the **sum of triggered signal weights**, capped at 100. It is a checklist-style rubric, not a statistical model of detection probability.
+
+## How to read the score
+
+| Score | CLI exit | Band | Meaning |
+|-------|----------|------|---------|
+| 0–30 | 0 | pass | Few or no weighted findings |
+| 31–60 | 1 | warn | Some automation hints; review before production |
+| 61–100 | 2 | fail | Strong automation fingerprint; likely flagged |
+
+Internal grade labels (`low`, `moderate`, `high`, `critical`) are derived from the same score for display only.
+
+## Signal weights
+
+Each row is independent: if the condition is true, its weight is added once.
+
+| Signal key | Weight | Trigger condition |
+|------------|--------|-------------------|
+| `webdriver` | 35 | `navigator.webdriver === true` |
+| `headless_ua` | 25 | User-Agent matches `/HeadlessChrome/i` |
+| `no_plugins` | 12 | `navigator.plugins.length === 0` |
+| `no_mime_types` | 8 | `navigator.mimeTypes.length === 0` |
+| `missing_chrome_runtime` | 15 | Chromium probe and `window.chrome.runtime` is missing |
+| `swiftshader_renderer` | 12 | WebGL renderer string contains `swiftshader` (software GL) |
+| `window_size_mismatch` | 10 | Outer window is 0×0 or outer equals inner (common headless layout) |
+| `zero_languages` | 5 | `navigator.languages` is empty |
+| `zero_outer_dimensions` | 8 | `window.outerWidth` or `outerHeight` is 0 |
+
+**Maximum theoretical sum:** 130 → **capped at 100** in code.
+
+## What we do *not* score
+
+These are collected in the report JSON but **not** added to the score today:
+
+- `permissions_api`, `notification_permission`
+- `hardware_concurrency`, `device_memory`, `connection_rtt`
+- `headless_launch` (launch flag recorded for headed vs headless comparison)
+- CDP vs local launch mode
+
+Keeping the rubric small makes CI thresholds predictable. See `playwright_cdp_probe/scoring.py` for the source of truth.
+
+## Example stacks
+
+| Scenario | Typical findings | Approx. score |
+|----------|------------------|---------------|
+| Headed Chromium, normal profile | none | 0–15 |
+| Headless Chromium default | `headless_ua`, `no_plugins`, `window_size_mismatch` | 40–55 |
+| Headless + `webdriver` leak | above + `webdriver` | 75+ (fail) |
+
+## Tuning for CI
+
+```bash
+cdp-probe run --url https://example.com --format github-actions
+echo $?   # 0 pass, 1 warn, 2 fail, 3 runtime error
+```
+
+Adjust browser launch (headed, antidetect profile, MLX CDP) until score ≤ 30 for production gates.

playwright_cdp_probe/__init__.py

@@ -0,0 +1,7 @@
+"""Playwright CDP automation exposure probe."""
+
+from playwright_cdp_probe.probe import ProbeReport, ProbeRunner
+from playwright_cdp_probe.scoring import compute_exposure_score
+
+__all__ = ["ProbeReport", "ProbeRunner", "compute_exposure_score"]
+__version__ = "0.2.0"

playwright_cdp_probe/cli.py

@@ -0,0 +1,247 @@
+"""Click CLI for cdp-probe."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from playwright_cdp_probe.exit_codes import EXIT_ERROR, exit_code_for_score
+from playwright_cdp_probe.presets import PRESET_NAMES
+from playwright_cdp_probe.probe import ProbeOptions, ProbeRunner
+from playwright_cdp_probe.report import (
+    DEFAULT_REPORT_PATH,
+    ReportFormat,
+    format_report,
+    load_report,
+    save_report,
+)
+
+
+def _finish_probe(report, *, output_path: Path | None, fmt: ReportFormat) -> None:
+    path = save_report(report, output_path)
+    click.echo(format_report(report, fmt))
+    click.echo(f"\nReport saved: {path}", err=True)
+    sys.exit(exit_code_for_score(report.exposure.score))
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="playwright-cdp-probe", prog_name="cdp-probe")
+@click.option("--show-deal", is_flag=True, help="Print Multilogin coupon info and exit.")
+@click.pass_context
+def main(ctx: click.Context, show_deal: bool) -> None:
+    """Audit Playwright/CDP sessions for automation exposure signals."""
+    if show_deal:
+        from playwright_cdp_probe.deal import print_show_deal
+
+        print_show_deal()
+        ctx.exit(0)
+
+
+@main.command("run")
+@click.option("--url", default="https://example.com", show_default=True, help="Page to load.")
+@click.option("--browser", type=click.Choice(["chromium", "firefox"]), default="chromium")
+@click.option("--headless/--no-headless", default=True, show_default=True)
+@click.option("--output", "output_path", type=click.Path(path_type=Path), default=None)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "table", "github-actions"]),
+    default="table",
+    show_default=True,
+)
+@click.option("--timeout", "timeout_ms", default=30_000, show_default=True, help="Navigation ms.")
+@click.option(
+    "--preset",
+    type=click.Choice(PRESET_NAMES),
+    default=None,
+    help="Site-class signal weights from presets/ (see README).",
+)
+def run_cmd(
+    url: str,
+    browser: str,
+    headless: bool,
+    output_path: Path | None,
+    fmt: ReportFormat,
+    timeout_ms: int,
+    preset: str | None,
+) -> None:
+    """Launch Playwright, navigate, and score automation exposure."""
+    try:
+        runner = ProbeRunner(
+            ProbeOptions(
+                url=url,
+                browser=browser,  # type: ignore[arg-type]
+                headless=headless,
+                mode="run",
+                timeout_ms=timeout_ms,
+                preset=preset,
+            )
+        )
+        _finish_probe(runner.run(), output_path=output_path, fmt=fmt)
+    except Exception as exc:
+        click.echo(f"::error title=cdp-probe::{exc}", err=True)
+        sys.exit(EXIT_ERROR)
+
+
+@main.command("check-local")
+@click.option("--browser", type=click.Choice(["chromium", "firefox"]), default="chromium")
+@click.option("--headless/--no-headless", default=True, show_default=True)
+@click.option("--output", "output_path", type=click.Path(path_type=Path), default=None)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "table", "github-actions"]),
+    default="table",
+    show_default=True,
+)
+def check_local_cmd(
+    browser: str,
+    headless: bool,
+    output_path: Path | None,
+    fmt: ReportFormat,
+) -> None:
+    """Probe a locally launched browser at about:blank."""
+    try:
+        runner = ProbeRunner(
+            ProbeOptions(
+                url="about:blank",
+                browser=browser,  # type: ignore[arg-type]
+                headless=headless,
+                mode="check-local",
+            )
+        )
+        _finish_probe(runner.run(), output_path=output_path, fmt=fmt)
+    except Exception as exc:
+        click.echo(f"::error title=cdp-probe::{exc}", err=True)
+        sys.exit(EXIT_ERROR)
+
+
+@main.command("report")
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "table", "github-actions"]),
+    default="table",
+)
+@click.option("--input", "input_path", type=click.Path(path_type=Path), default=None)
+def report_cmd(fmt: ReportFormat, input_path: Path | None) -> None:
+    """Print the last saved probe report."""
+    try:
+        report = load_report(input_path)
+    except (FileNotFoundError, ValueError) as exc:
+        click.echo(f"::error title=cdp-probe::{exc}", err=True)
+        sys.exit(EXIT_ERROR)
+    click.echo(format_report(report, fmt))
+    sys.exit(exit_code_for_score(report.exposure.score))
+
+
+def _mlx_probe_cmd(
+    profile_id: str,
+    folder_id: str | None,
+    url: str,
+    token: str | None,
+    headless: bool,
+    output_path: Path | None,
+    fmt: ReportFormat,
+    *,
+    legacy_mode: str,
+) -> None:
+    from playwright_cdp_probe.integrations.mlx import mlx_launch_and_probe, require_mlx_extra
+
+    require_mlx_extra()
+    try:
+        report = mlx_launch_and_probe(
+            profile_id,
+            folder_id=folder_id,
+            token=token,
+            url=url,
+            headless=headless,
+        )
+        if legacy_mode:
+            report.mode = legacy_mode
+        path = save_report(report, output_path or DEFAULT_REPORT_PATH)
+        click.echo(format_report(report, fmt))
+        click.echo(f"\nReport saved: {path}", err=True)
+        sys.exit(exit_code_for_score(report.exposure.score))
+    except Exception as exc:
+        click.echo(f"::error title=cdp-probe::{exc}", err=True)
+        sys.exit(EXIT_ERROR)
+
+
+def _mlx_click_options(func):  # noqa: ANN001
+    options = [
+        click.option("--profile-id", required=True, help="MLX profile UUID."),
+        click.option(
+            "--folder-id",
+            envvar="MLX_FOLDER_ID",
+            help="MLX folder UUID (or MLX_FOLDER_ID).",
+        ),
+        click.option("--url", default="https://example.com", show_default=True),
+        click.option("--token", envvar="MLX_TOKEN", help="Bearer token (or MLX_TOKEN)."),
+        click.option("--headless/--no-headless", default=False, show_default=True),
+        click.option("--output", "output_path", type=click.Path(path_type=Path), default=None),
+        click.option(
+            "--format",
+            "fmt",
+            type=click.Choice(["json", "table", "github-actions"]),
+            default="table",
+            show_default=True,
+        ),
+    ]
+    for decorator in reversed(options):
+        func = decorator(func)
+    return func
+
+
+@_mlx_click_options
+@main.command("mlx")
+def mlx_cmd(
+    profile_id: str,
+    folder_id: str | None,
+    url: str,
+    token: str | None,
+    headless: bool,
+    output_path: Path | None,
+    fmt: ReportFormat,
+) -> None:
+    """Start MLX profile via Launcher API, probe over CDP, then stop (requires [mlx])."""
+    _mlx_probe_cmd(
+        profile_id,
+        folder_id,
+        url,
+        token,
+        headless,
+        output_path,
+        fmt,
+        legacy_mode="",
+    )
+
+
+@_mlx_click_options
+@main.command("mlx-launch", hidden=True)
+def mlx_launch_cmd(
+    profile_id: str,
+    folder_id: str | None,
+    url: str,
+    token: str | None,
+    headless: bool,
+    output_path: Path | None,
+    fmt: ReportFormat,
+) -> None:
+    """Deprecated alias for `cdp-probe mlx`."""
+    _mlx_probe_cmd(
+        profile_id,
+        folder_id,
+        url,
+        token,
+        headless,
+        output_path,
+        fmt,
+        legacy_mode="mlx-launch",
+    )
+
+
+if __name__ == "__main__":
+    main()

playwright_cdp_probe/deal.py

@@ -0,0 +1,15 @@
+"""Multilogin partner coupon output for --show-deal."""
+
+from __future__ import annotations
+
+import click
+
+SHOW_DEAL_TEXT = """Multilogin X — Antidetect Browser & Cloud Phone
+SAAS50: 50% off Browser (new eligible purchases)
+MIN50:  50% off Cloud Phone
+https://anti-detect.github.io/
+Scripts: https://t.me/Multilogin_Scripts_Bot"""
+
+
+def print_show_deal() -> None:
+    click.echo(SHOW_DEAL_TEXT)

playwright_cdp_probe/exit_codes.py

@@ -0,0 +1,34 @@
+"""CLI exit codes keyed to exposure score bands."""
+
+from __future__ import annotations
+
+EXIT_PASS = 0
+EXIT_WARN = 1
+EXIT_FAIL = 2
+EXIT_ERROR = 3
+
+PASS_MAX = 30
+WARN_MAX = 60
+
+
+def exit_code_for_score(score: int) -> int:
+    """Map exposure score to process exit code.
+
+    - 0 pass: score ≤ 30
+    - 1 warn: score 31–60
+    - 2 fail: score > 60
+    """
+    if score <= PASS_MAX:
+        return EXIT_PASS
+    if score <= WARN_MAX:
+        return EXIT_WARN
+    return EXIT_FAIL
+
+
+def band_label(score: int) -> str:
+    code = exit_code_for_score(score)
+    if code == EXIT_PASS:
+        return "pass"
+    if code == EXIT_WARN:
+        return "warn"
+    return "fail"

playwright_cdp_probe/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional third-party integrations."""

playwright_cdp_probe/integrations/mlx.py

@@ -0,0 +1,164 @@
+"""MLX Launcher: start profile → CDP probe → stop."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import os
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from playwright_cdp_probe.probe import ProbeOptions, ProbeRunner
+from playwright_cdp_probe.report import ProbeReport
+
+_MLX_HINT = "Install MLX support with: pip install playwright-cdp-probe[mlx]"
+
+
+def require_mlx_extra() -> None:
+    if importlib.util.find_spec("httpx") is None:
+        raise ImportError(_MLX_HINT)
+
+
+@dataclass(frozen=True, slots=True)
+class MlxSession:
+    """Active MLX Launcher automation session."""
+
+    profile_id: str
+    folder_id: str
+    http_endpoint: str
+    port: str
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+class MlxLauncherClient:
+    """httpx client for MLX Launcher start/stop → local CDP HTTP endpoint."""
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        base_url: str = "https://launcher.mlx.yt:45001",
+        timeout: float = 120.0,
+        transport: Any | None = None,
+    ) -> None:
+        require_mlx_extra()
+        import httpx  # noqa: PLC0415
+
+        kwargs: dict[str, Any] = {
+            "base_url": base_url.rstrip("/"),
+            "timeout": timeout,
+            "verify": True,
+        }
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._client = httpx.Client(**kwargs)
+        self._token = token
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        return headers
+
+    def start_profile(
+        self,
+        folder_id: str,
+        profile_id: str,
+        *,
+        automation_type: Literal["playwright", "puppeteer", "selenium"] = "playwright",
+        headless: bool = False,
+    ) -> MlxSession:
+        path = f"/api/v2/profile/f/{folder_id}/p/{profile_id}/start"
+        response = self._client.get(
+            path,
+            headers=self._headers(),
+            params={
+                "automation_type": automation_type,
+                "headless_mode": str(headless).lower(),
+            },
+        )
+        body = response.json()
+        if response.status_code >= 400:
+            status = body.get("status", {}) if isinstance(body, dict) else {}
+            message = status.get("message") if isinstance(status, dict) else response.text
+            raise RuntimeError(message or f"Launcher HTTP {response.status_code}")
+
+        data = body.get("data", {}) if isinstance(body, dict) else {}
+        port = data.get("port")
+        if port is None:
+            raise RuntimeError("Launcher did not return automation port")
+
+        return MlxSession(
+            profile_id=profile_id,
+            folder_id=folder_id,
+            http_endpoint=f"http://127.0.0.1:{port}",
+            port=str(port),
+            raw=data if isinstance(data, dict) else {},
+        )
+
+    def stop_profile(self, profile_id: str) -> dict[str, Any]:
+        response = self._client.get(
+            "/api/v1/profile/stop",
+            headers=self._headers(),
+            params={"profile_id": profile_id},
+        )
+        body = response.json()
+        if response.status_code >= 400:
+            status = body.get("status", {}) if isinstance(body, dict) else {}
+            message = status.get("message") if isinstance(status, dict) else response.text
+            raise RuntimeError(message or f"Launcher HTTP {response.status_code}")
+        if isinstance(body, dict):
+            data = body.get("data")
+            return data if isinstance(data, dict) else {"raw": data}
+        return {"raw": body}
+
+
+def mlx_launch_and_probe(
+    profile_id: str,
+    *,
+    folder_id: str | None = None,
+    token: str | None = None,
+    url: str = "https://example.com",
+    headless: bool = False,
+    timeout_ms: int = 30_000,
+    launcher: MlxLauncherClient | None = None,
+    runner: ProbeRunner | None = None,
+) -> ProbeReport:
+    """Start MLX profile, connect Playwright over CDP, probe, then stop the profile."""
+    resolved_folder = folder_id or os.environ.get("MLX_FOLDER_ID")
+    resolved_token = token or os.environ.get("MLX_TOKEN")
+    if not resolved_folder:
+        raise ValueError("folder_id or MLX_FOLDER_ID is required")
+    if not resolved_token:
+        raise ValueError("token or MLX_TOKEN is required")
+
+    owns_launcher = launcher is None
+    client = launcher or MlxLauncherClient(token=resolved_token)
+    try:
+        session = client.start_profile(
+            resolved_folder,
+            profile_id,
+            automation_type="playwright",
+            headless=headless,
+        )
+        try:
+            probe = runner or ProbeRunner(
+                ProbeOptions(
+                    url=url,
+                    browser="chromium",
+                    cdp_endpoint=session.http_endpoint,
+                    mode="mlx",
+                    headless=headless,
+                    timeout_ms=timeout_ms,
+                )
+            )
+            return probe.run()
+        finally:
+            with contextlib.suppress(RuntimeError):
+                client.stop_profile(profile_id)
+    finally:
+        if owns_launcher:
+            client.close()