"""Launch the pinned Chromium the harness drives — Playwright's bundled build only.

We deliberately use ONLY Playwright's own pinned Chromium: no silent fallback to a
system browser. A different browser can resolve CSS ``@import`` / relative URLs
differently and invent findings that don't reproduce — we hit exactly that once, a
system-Chrome fallback conjuring a ``/global-tokens.css`` 404 the pinned browser
never sees. If the browser isn't installed, Playwright fails loudly with "run
playwright install" — the right fix, not a silent substitution. Keeping resolution
in one place means every fixture and script drives the identical build.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from playwright.sync_api import Browser, Playwright


def launch_browser(pw: Playwright, *, headless: bool = True) -> Browser:
    """Return a launched, pinned bundled Chromium.

    We deliberately use ONLY Playwright's pinned Chromium — no silent fallback to a
    system browser. A different browser can resolve CSS ``@import`` / relative URLs
    differently and produce findings that don't reproduce (we hit exactly this: a
    system-Chrome fallback invented a ``/global-tokens.css`` 404 the pinned browser
    never sees). If the browser is missing, Playwright fails loudly with "run
    playwright install" — the right fix, not a silent substitution.
    """
    return pw.chromium.launch(headless=headless)
