chromiumfish 0.1.0__tar.gz

chromiumfish-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+npm-debug.log*
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Browser cache / downloaded builds
+.cache/
+*.tar.gz
+*.zip
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+
+# Local secrets / env
+.env
+*.local

chromiumfish-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Arman Hossain
+
+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.
+
+---
+
+This package distributes builds of the Chromium project, which is licensed
+under the BSD 3-Clause License and includes third-party components under their
+respective licenses. The full Chromium license text and credits are bundled
+with each browser release. "Chromium" and "Google Chrome" are trademarks of
+Google LLC. ChromiumFish is an independent fork and is not affiliated with,
+sponsored by, or endorsed by Google LLC.

chromiumfish-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: chromiumfish
+Version: 0.1.0
+Summary: Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser.
+Project-URL: Homepage, https://chromiumfish.com
+Project-URL: Repository, https://github.com/arman-bd/chromiumfish
+Project-URL: Documentation, https://chromiumfish.com
+Project-URL: Releases, https://github.com/arman-bd/chromiumfish/releases
+Author: Arman Hossain
+License: MIT
+License-File: LICENSE
+Keywords: anti-detect,automation,chromium,fingerprint,playwright,stealth
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: playwright>=1.40
+Description-Content-Type: text/markdown
+
+# chromiumfish (Python)
+
+Stealth Chromium with a drop-in [Playwright](https://playwright.dev) harness.
+
+```bash
+pip install chromiumfish
+chromiumfish fetch        # download + cache the browser build
+```
+
+## Usage
+
+**Sync**
+
+```python
+from chromiumfish.sync_api import Chromiumfish
+
+with Chromiumfish(persona_seed=27182, headless=True) as browser:
+    page = browser.new_page()
+    page.goto("https://abrahamjuliot.github.io/creepjs/")
+    page.screenshot(path="fp.png")
+```
+
+**Async**
+
+```python
+import asyncio
+from chromiumfish.async_api import AsyncChromiumfish
+
+async def main():
+    async with AsyncChromiumfish(persona_seed=27182) as browser:
+        page = await browser.new_page()
+        await page.goto("https://example.com")
+        print(await page.title())
+
+asyncio.run(main())
+```
+
+The returned object is a standard Playwright `Browser`, so `new_context`,
+`new_page`, routing, tracing, etc. all work as usual.
+
+## Options
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `persona_seed` | `None` | Integer seed for a stable, internally-consistent fingerprint persona. |
+| `headless` | `True` | Run headless (SwiftShader). |
+| `proxy` | `None` | Playwright proxy dict, e.g. `{"server": "http://host:port", "username": ..., "password": ...}`. |
+| `window_size` | `(1920, 1080)` | Window dimensions. |
+| `version` | pinned | Override the browser build version. |
+| `download` | `True` | Auto-download the build if missing. |
+| `args` | `None` | Extra Chromium flags. |
+| `**launch_kwargs` | — | Forwarded to `chromium.launch()`. |
+
+## CLI
+
+```bash
+chromiumfish fetch [--browser-version X] [--force]   # download + cache
+chromiumfish path                                     # print binary path
+chromiumfish clear                                    # wipe the cache
+chromiumfish --version
+```
+
+Builds are cached under `~/.cache/chromiumfish/<version>/` (override with
+`CHROMIUMFISH_CACHE_DIR`). Pin a build with `CHROMIUMFISH_VERSION`.
+
+## License
+
+MIT © Arman Hossain. See the [repository](https://github.com/arman-bd/chromiumfish).

chromiumfish-0.1.0/README.md

@@ -0,0 +1,68 @@
+# chromiumfish (Python)
+
+Stealth Chromium with a drop-in [Playwright](https://playwright.dev) harness.
+
+```bash
+pip install chromiumfish
+chromiumfish fetch        # download + cache the browser build
+```
+
+## Usage
+
+**Sync**
+
+```python
+from chromiumfish.sync_api import Chromiumfish
+
+with Chromiumfish(persona_seed=27182, headless=True) as browser:
+    page = browser.new_page()
+    page.goto("https://abrahamjuliot.github.io/creepjs/")
+    page.screenshot(path="fp.png")
+```
+
+**Async**
+
+```python
+import asyncio
+from chromiumfish.async_api import AsyncChromiumfish
+
+async def main():
+    async with AsyncChromiumfish(persona_seed=27182) as browser:
+        page = await browser.new_page()
+        await page.goto("https://example.com")
+        print(await page.title())
+
+asyncio.run(main())
+```
+
+The returned object is a standard Playwright `Browser`, so `new_context`,
+`new_page`, routing, tracing, etc. all work as usual.
+
+## Options
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `persona_seed` | `None` | Integer seed for a stable, internally-consistent fingerprint persona. |
+| `headless` | `True` | Run headless (SwiftShader). |
+| `proxy` | `None` | Playwright proxy dict, e.g. `{"server": "http://host:port", "username": ..., "password": ...}`. |
+| `window_size` | `(1920, 1080)` | Window dimensions. |
+| `version` | pinned | Override the browser build version. |
+| `download` | `True` | Auto-download the build if missing. |
+| `args` | `None` | Extra Chromium flags. |
+| `**launch_kwargs` | — | Forwarded to `chromium.launch()`. |
+
+## CLI
+
+```bash
+chromiumfish fetch [--browser-version X] [--force]   # download + cache
+chromiumfish path                                     # print binary path
+chromiumfish clear                                    # wipe the cache
+chromiumfish --version
+```
+
+Builds are cached under `~/.cache/chromiumfish/<version>/` (override with
+`CHROMIUMFISH_CACHE_DIR`). Pin a build with `CHROMIUMFISH_VERSION`.
+
+## License
+
+MIT © Arman Hossain. See the [repository](https://github.com/arman-bd/chromiumfish).

chromiumfish-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chromiumfish"
+dynamic = ["version"]
+description = "Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+authors = [{ name = "Arman Hossain" }]
+keywords = ["playwright", "chromium", "stealth", "fingerprint", "automation", "anti-detect"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "playwright>=1.40",
+]
+
+[project.urls]
+Homepage = "https://chromiumfish.com"
+Repository = "https://github.com/arman-bd/chromiumfish"
+Documentation = "https://chromiumfish.com"
+Releases = "https://github.com/arman-bd/chromiumfish/releases"
+
+[project.scripts]
+chromiumfish = "chromiumfish.cli:main"
+
+[tool.hatch.version]
+path = "src/chromiumfish/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chromiumfish"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/chromiumfish", "README.md", "LICENSE"]

chromiumfish-0.1.0/src/chromiumfish/__init__.py

@@ -0,0 +1,30 @@
+"""ChromiumFish — a stealth Chromium build with a Playwright harness.
+
+Quick start (sync)::
+
+    from chromiumfish.sync_api import Chromiumfish
+
+    with Chromiumfish(persona_seed=27182) as browser:
+        page = browser.new_page()
+        page.goto("https://example.com")
+
+Quick start (async)::
+
+    from chromiumfish.async_api import AsyncChromiumfish
+
+    async with AsyncChromiumfish(persona_seed=27182) as browser:
+        page = await browser.new_page()
+"""
+from __future__ import annotations
+
+from .fetch import binary_path, fetch, install_dir
+from .version import DEFAULT_BROWSER_VERSION, __version__, browser_version
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BROWSER_VERSION",
+    "browser_version",
+    "fetch",
+    "binary_path",
+    "install_dir",
+]

chromiumfish-0.1.0/src/chromiumfish/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

chromiumfish-0.1.0/src/chromiumfish/async_api.py

@@ -0,0 +1,65 @@
+"""Async Playwright wrapper for ChromiumFish.
+
+    from chromiumfish.async_api import AsyncChromiumfish
+
+    async with AsyncChromiumfish(persona_seed=27182, headless=True) as browser:
+        page = await browser.new_page()
+        await page.goto("https://example.com")
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from playwright.async_api import Browser, async_playwright
+
+from .fetch import binary_path
+from .launcher import launch_options
+
+
+class AsyncChromiumfish:
+    def __init__(
+        self,
+        *,
+        persona_seed: int | None = None,
+        headless: bool = True,
+        proxy: dict[str, Any] | None = None,
+        window_size: tuple[int, int] | None = (1920, 1080),
+        version: str | None = None,
+        download: bool = True,
+        args: list[str] | None = None,
+        **launch_kwargs: Any,
+    ) -> None:
+        self._opts = dict(
+            persona_seed=persona_seed,
+            headless=headless,
+            proxy=proxy,
+            window_size=window_size,
+            args=args,
+            extra=launch_kwargs,
+        )
+        self._version = version
+        self._download = download
+        self._pw = None
+        self._browser: Browser | None = None
+
+    async def start(self) -> Browser:
+        exe = binary_path(self._version, download=self._download)
+        self._pw = await async_playwright().start()
+        self._browser = await self._pw.chromium.launch(
+            **launch_options(executable_path=exe, **self._opts)
+        )
+        return self._browser
+
+    async def close(self) -> None:
+        if self._browser:
+            await self._browser.close()
+            self._browser = None
+        if self._pw:
+            await self._pw.stop()
+            self._pw = None
+
+    async def __aenter__(self) -> Browser:
+        return await self.start()
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

chromiumfish-0.1.0/src/chromiumfish/cli.py

@@ -0,0 +1,51 @@
+"""`chromiumfish` command-line interface."""
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+
+from .fetch import binary_path, cache_root, fetch, install_dir
+from .version import __version__, browser_version
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="chromiumfish",
+        description="Fetch and manage the ChromiumFish browser build.",
+    )
+    parser.add_argument("-V", "--version", action="version",
+                        version=f"chromiumfish {__version__} (browser {browser_version()})")
+    sub = parser.add_subparsers(dest="cmd")
+
+    f = sub.add_parser("fetch", help="download + cache the browser build")
+    f.add_argument("--browser-version", default=None, help="override the build version")
+    f.add_argument("--force", action="store_true", help="re-download even if cached")
+
+    sub.add_parser("path", help="print the cached binary path (fetching if missing)")
+    sub.add_parser("clear", help="remove all cached browser builds")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "fetch":
+        path = fetch(args.browser_version, force=args.force)
+        print(path)
+        return 0
+    if args.cmd == "path":
+        print(binary_path())
+        return 0
+    if args.cmd == "clear":
+        root = cache_root()
+        if root.exists():
+            shutil.rmtree(root, ignore_errors=True)
+            print(f"removed {root}")
+        else:
+            print("nothing to remove")
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

chromiumfish-0.1.0/src/chromiumfish/fetch.py

@@ -0,0 +1,201 @@
+"""Download, verify, and cache the ChromiumFish browser build.
+
+Fetch model: resolve ``version × platform`` to a GitHub
+Release asset, verify its SHA-256, extract it to a per-version cache dir, and
+return the path to the launchable binary.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from .version import browser_version, release_base_url
+
+
+class UnsupportedPlatformError(RuntimeError):
+    pass
+
+
+def cache_root() -> Path:
+    env = os.environ.get("CHROMIUMFISH_CACHE_DIR")
+    if env:
+        return Path(env).expanduser()
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "chromiumfish"
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local"))
+        return Path(base) / "chromiumfish"
+    return Path(os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))) / "chromiumfish"
+
+
+def platform_slug() -> str:
+    """e.g. ``linux-x64``, ``win-x64``, ``mac-arm64``."""
+    machine = platform.machine().lower()
+    arch = {
+        "x86_64": "x64", "amd64": "x64",
+        "aarch64": "arm64", "arm64": "arm64",
+    }.get(machine)
+    if arch is None:
+        raise UnsupportedPlatformError(f"unsupported architecture: {machine}")
+    if sys.platform.startswith("linux"):
+        return f"linux-{arch}"
+    if sys.platform == "darwin":
+        return f"mac-{arch}"
+    if os.name == "nt":
+        return f"win-{arch}"
+    raise UnsupportedPlatformError(f"unsupported platform: {sys.platform}")
+
+
+def _asset_name(version: str) -> str:
+    slug = platform_slug()
+    ext = "zip" if slug.startswith("win") else "tar.gz"
+    return f"chromiumfish-{version}-{slug}.{ext}"
+
+
+def _binary_name() -> str:
+    if os.name == "nt":
+        return "chromiumfish.exe"
+    return "chromiumfish"  # falls back to "chrome" during discovery
+
+
+def install_dir(version: str | None = None) -> Path:
+    version = version or browser_version()
+    return cache_root() / version / platform_slug()
+
+
+def find_binary(root: Path) -> Path | None:
+    """Locate the launchable binary inside an extracted build."""
+    candidates = ["chromiumfish", "chrome", "chromiumfish.exe", "chrome.exe", "ChromiumFish"]
+    for name in candidates:
+        direct = root / name
+        if direct.is_file():
+            return direct
+    for name in candidates:
+        for hit in root.rglob(name):
+            if hit.is_file():
+                return hit
+    return None
+
+
+def _download(url: str, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    print(f"[chromiumfish] downloading {url}", file=sys.stderr)
+    with urllib.request.urlopen(url) as resp, open(dest, "wb") as out:  # noqa: S310
+        total = int(resp.headers.get("Content-Length", 0))
+        read = 0
+        while chunk := resp.read(1 << 20):
+            out.write(chunk)
+            read += len(chunk)
+            if total:
+                pct = read * 100 // total
+                print(f"\r[chromiumfish] {pct:3d}%  ({read >> 20} / {total >> 20} MiB)",
+                      end="", file=sys.stderr)
+        print("", file=sys.stderr)
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(1 << 20):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _verify(archive: Path, base_url: str, asset: str) -> None:
+    try:
+        with urllib.request.urlopen(f"{base_url}/{asset}.sha256") as r:  # noqa: S310
+            expected = r.read().decode().split()[0].strip()
+    except Exception:  # noqa: BLE001
+        print("[chromiumfish] warning: no .sha256 published, skipping verification", file=sys.stderr)
+        return
+    actual = _sha256(archive)
+    if actual != expected:
+        archive.unlink(missing_ok=True)
+        raise RuntimeError(f"checksum mismatch for {asset}: {actual} != {expected}")
+
+
+def _extract(archive: Path, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    if archive.name.endswith(".zip"):
+        with zipfile.ZipFile(archive) as z:
+            z.extractall(dest)
+    else:
+        with tarfile.open(archive) as t:
+            t.extractall(dest)  # noqa: S202 - trusted first-party asset
+
+
+def _macos_prepare(target: Path) -> None:
+    """Identity-clean macOS prep.
+
+    1. Strip the ``com.apple.quarantine`` flag. Programmatic downloads usually
+       don't set it, but browsers/tools might — removing it avoids Gatekeeper's
+       "unidentified developer" block without any notarization.
+    2. Ensure the bundle is ad-hoc signed (``codesign -s -``). Apple Silicon
+       refuses to run an unsigned binary; ad-hoc signing fixes that and embeds
+       NO certificate, name, or identity. (Release builds ship ad-hoc signed;
+       this is a defensive fallback.)
+    """
+    if sys.platform != "darwin":
+        return
+    app = next(target.glob("*.app"), None)
+    sign_target = app or find_binary(target)
+    subprocess.run(["xattr", "-dr", "com.apple.quarantine", str(target)],
+                   check=False, capture_output=True)
+    if sign_target:
+        valid = subprocess.run(["codesign", "--verify", "--quiet", str(sign_target)],
+                               capture_output=True).returncode == 0
+        if not valid:
+            subprocess.run(["codesign", "--force", "--deep", "--sign", "-", str(sign_target)],
+                           check=False, capture_output=True)
+
+
+def fetch(version: str | None = None, *, force: bool = False) -> Path:
+    """Ensure the browser build is present and return the binary path."""
+    version = version or browser_version()
+    target = install_dir(version)
+
+    if force and target.exists():
+        shutil.rmtree(target, ignore_errors=True)
+
+    if target.exists():
+        binp = find_binary(target)
+        if binp:
+            return binp
+
+    base = release_base_url(version)
+    asset = _asset_name(version)
+    archive = cache_root() / version / asset
+    _download(f"{base}/{asset}", archive)
+    _verify(archive, base, asset)
+    _extract(archive, target)
+    archive.unlink(missing_ok=True)
+    _macos_prepare(target)
+
+    binp = find_binary(target)
+    if not binp:
+        raise RuntimeError(f"no browser binary found in extracted build at {target}")
+    if os.name != "nt":
+        binp.chmod(0o755)
+    print(f"[chromiumfish] ready: {binp}", file=sys.stderr)
+    return binp
+
+
+def binary_path(version: str | None = None, *, download: bool = True) -> Path:
+    """Path to the cached binary, fetching it if needed (and allowed)."""
+    version = version or browser_version()
+    existing = find_binary(install_dir(version))
+    if existing:
+        return existing
+    if not download:
+        raise FileNotFoundError(
+            f"ChromiumFish {version} not installed. Run `chromiumfish fetch`."
+        )
+    return fetch(version)

chromiumfish-0.1.0/src/chromiumfish/launcher.py

@@ -0,0 +1,56 @@
+"""Shared launch-argument construction for the sync/async wrappers."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+# Flags that keep the GPU-less / SwiftShader path working and the persona
+# engine happy. Mirrors the production launch_lean.sh defaults (minus anything
+# that is now baked into the build / bundled addon).
+BASE_ARGS: list[str] = [
+    "--no-sandbox",
+    "--no-zygote",
+    "--disable-dev-shm-usage",
+    "--use-gl=angle",
+    "--use-angle=swiftshader",
+    "--enable-unsafe-swiftshader",
+]
+
+
+def build_args(
+    *,
+    persona_seed: int | None = None,
+    window_size: tuple[int, int] | None = (1920, 1080),
+    extra_args: list[str] | None = None,
+) -> list[str]:
+    args = list(BASE_ARGS)
+    if persona_seed is not None:
+        args.append(f"--persona-seed={persona_seed}")
+    if window_size is not None:
+        args.append(f"--window-size={window_size[0]},{window_size[1]}")
+    if extra_args:
+        args.extend(extra_args)
+    return args
+
+
+def launch_options(
+    *,
+    executable_path: Path,
+    headless: bool,
+    persona_seed: int | None,
+    proxy: dict[str, Any] | None,
+    window_size: tuple[int, int] | None,
+    args: list[str] | None,
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    opts: dict[str, Any] = {
+        "executable_path": str(executable_path),
+        "headless": headless,
+        "args": build_args(
+            persona_seed=persona_seed, window_size=window_size, extra_args=args
+        ),
+    }
+    if proxy is not None:
+        opts["proxy"] = proxy
+    opts.update(extra)
+    return opts

chromiumfish-0.1.0/src/chromiumfish/sync_api.py

@@ -0,0 +1,65 @@
+"""Sync Playwright wrapper for ChromiumFish.
+
+    from chromiumfish.sync_api import Chromiumfish
+
+    with Chromiumfish(persona_seed=27182, headless=True) as browser:
+        page = browser.new_page()
+        page.goto("https://example.com")
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from playwright.sync_api import Browser, sync_playwright
+
+from .fetch import binary_path
+from .launcher import launch_options
+
+
+class Chromiumfish:
+    def __init__(
+        self,
+        *,
+        persona_seed: int | None = None,
+        headless: bool = True,
+        proxy: dict[str, Any] | None = None,
+        window_size: tuple[int, int] | None = (1920, 1080),
+        version: str | None = None,
+        download: bool = True,
+        args: list[str] | None = None,
+        **launch_kwargs: Any,
+    ) -> None:
+        self._opts = dict(
+            persona_seed=persona_seed,
+            headless=headless,
+            proxy=proxy,
+            window_size=window_size,
+            args=args,
+            extra=launch_kwargs,
+        )
+        self._version = version
+        self._download = download
+        self._pw = None
+        self._browser: Browser | None = None
+
+    def start(self) -> Browser:
+        exe = binary_path(self._version, download=self._download)
+        self._pw = sync_playwright().start()
+        self._browser = self._pw.chromium.launch(
+            **launch_options(executable_path=exe, **self._opts)
+        )
+        return self._browser
+
+    def close(self) -> None:
+        if self._browser:
+            self._browser.close()
+            self._browser = None
+        if self._pw:
+            self._pw.stop()
+            self._pw = None
+
+    def __enter__(self) -> Browser:
+        return self.start()
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

chromiumfish-0.1.0/src/chromiumfish/version.py

@@ -0,0 +1,30 @@
+"""Pinned browser build + release coordinates.
+
+The browser is built privately and published to this repo's GitHub Releases.
+`BROWSER_VERSION` is the release tag (without the leading ``v``) the SDK
+downloads by default; override it at runtime with ``CHROMIUMFISH_VERSION``.
+"""
+from __future__ import annotations
+
+import os
+
+# SDK package version. Single source of truth: pyproject.toml reads this via
+# [tool.hatch.version] (dynamic = ["version"]).
+__version__ = "0.1.0"
+
+# Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION.
+DEFAULT_BROWSER_VERSION = "150.0.7844"
+
+# GitHub repo that hosts the release assets (public; binary built from the
+# private chromiumfish-browser repo).
+RELEASE_REPO = "arman-bd/chromiumfish"
+
+
+def browser_version() -> str:
+    """Resolved browser version (env override wins)."""
+    return os.environ.get("CHROMIUMFISH_VERSION", DEFAULT_BROWSER_VERSION)
+
+
+def release_base_url(version: str | None = None) -> str:
+    version = version or browser_version()
+    return f"https://github.com/{RELEASE_REPO}/releases/download/v{version}"