invisible-firefox 0.2.0__tar.gz

invisible_firefox-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/

invisible_firefox-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Federico Elia
+
+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.

invisible_firefox-0.2.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: invisible-firefox
+Version: 0.2.0
+Summary: Antidetect browser profile manager for the patched Firefox (manual use).
+Project-URL: Homepage, https://github.com/feder-cr/invisible_firefox
+Project-URL: Repository, https://github.com/feder-cr/invisible_firefox
+Project-URL: Issues, https://github.com/feder-cr/invisible_firefox/issues
+Author-email: feder-cr <85809106+feder-cr@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anti-detect,browser,fingerprint,firefox,profile-manager
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: invisible-core==18.0.0
+Requires-Dist: platformdirs>=4
+Requires-Dist: psutil>=5.9
+Requires-Dist: pywebview>=4.4; sys_platform != 'linux'
+Requires-Dist: pywebview[qt]>=4.4; sys_platform == 'linux'
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p>
+  <a href="https://github.com/feder-cr/invisible_firefox/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/license.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/python.svg" alt="Python 3.11+"></a>
+  <a href="https://github.com/feder-cr/firefox_antidetect_patch/releases"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/firefox.svg" alt="Firefox 151.0"></a>
+</p>
+
+<h3 align="center">Run many undetectable browser profiles on one patched Firefox.</h3>
+
+One desktop app, many identities. Each profile is a distinct fingerprint (GPU, canvas, fonts, audio, WebRTC) set at the C++ source level plus its own proxy and saved logins, so every profile passes bot detection on its own. Hit Launch and a real Firefox window opens with that identity.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/6485164a1bb54e85e6c215d020501dc3a0f90f47/docs/screenshot.png" alt="invisible_firefox" width="820">
+</div>
+
+## Install
+
+```bash
+pip install invisible-firefox
+python -m invisible_firefox
+```
+
+Everything it needs is downloaded automatically, nothing to fetch by hand: the patched Firefox binary (once, SHA256-verified, cached) the moment the app opens, and the GeoIP database when a proxy needs it. Runs on **Windows**, **Linux** and **macOS**.
+
+Built on [invisible_core](https://github.com/feder-cr/invisible_core); it launches the binary directly, no Playwright.
+
+## What you get
+
+- **One identity per profile** - GPU, screen, fonts and ~400 other fields from a seed, stable across launches.
+- **Persistent** - each profile keeps its own cookies, storage and logins in its own directory.
+- **Per-profile proxy** - none, or [sx.org](https://sx.org/?c=invisible_playwright) residential, with country and city per profile.
+- **Live status** - see which profiles are running; close the browser and the list updates itself.
+
+## Proxies
+
+Around 90% of proxies are public, so their IPs are already known and blocked. For the clean 10%, residential IPs that aren't already known, we recommend [sx.org](https://sx.org/?c=invisible_playwright): set your API key once in the Proxies menu, then pick a country and city per profile. New accounts get 3 GB free with code `STEALTH`.
+
+## Related projects
+
+- **[invisible_core](https://github.com/feder-cr/invisible_core)** - the pure-config engine (seed to fingerprint to prefs, binary download, proxy, geo) this app runs on.
+- **[invisible_playwright](https://github.com/feder-cr/invisible_playwright)** - the same patched Firefox driven by Playwright, for automation.
+- **[firefox_antidetect_patch](https://github.com/feder-cr/firefox_antidetect_patch)** - the C++ patches against Firefox that produce the binary.
+
+## License
+
+MIT - see [LICENSE](https://github.com/feder-cr/invisible_firefox/blob/main/LICENSE). The patched Firefox binary is distributed under the MPL-2.0 (Firefox upstream license).
+
+## Disclaimer
+
+This project is for educational purposes only. It is provided as-is, with no warranties. I take no responsibility for how it is used. Use it at your own risk and in compliance with the laws of your jurisdiction.
+
+---
+
+<p align="center">
+  Built by <a href="https://it.linkedin.com/in/federico-elia-5199951b6">Federico Elia</a>
+  &nbsp;<a href="https://it.linkedin.com/in/federico-elia-5199951b6"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/linkedin.svg" alt="LinkedIn"></a>
+</p>

invisible_firefox-0.2.0/README.md

@@ -0,0 +1,56 @@
+<p>
+  <a href="https://github.com/feder-cr/invisible_firefox/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/license.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/python.svg" alt="Python 3.11+"></a>
+  <a href="https://github.com/feder-cr/firefox_antidetect_patch/releases"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/firefox.svg" alt="Firefox 151.0"></a>
+</p>
+
+<h3 align="center">Run many undetectable browser profiles on one patched Firefox.</h3>
+
+One desktop app, many identities. Each profile is a distinct fingerprint (GPU, canvas, fonts, audio, WebRTC) set at the C++ source level plus its own proxy and saved logins, so every profile passes bot detection on its own. Hit Launch and a real Firefox window opens with that identity.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/6485164a1bb54e85e6c215d020501dc3a0f90f47/docs/screenshot.png" alt="invisible_firefox" width="820">
+</div>
+
+## Install
+
+```bash
+pip install invisible-firefox
+python -m invisible_firefox
+```
+
+Everything it needs is downloaded automatically, nothing to fetch by hand: the patched Firefox binary (once, SHA256-verified, cached) the moment the app opens, and the GeoIP database when a proxy needs it. Runs on **Windows**, **Linux** and **macOS**.
+
+Built on [invisible_core](https://github.com/feder-cr/invisible_core); it launches the binary directly, no Playwright.
+
+## What you get
+
+- **One identity per profile** - GPU, screen, fonts and ~400 other fields from a seed, stable across launches.
+- **Persistent** - each profile keeps its own cookies, storage and logins in its own directory.
+- **Per-profile proxy** - none, or [sx.org](https://sx.org/?c=invisible_playwright) residential, with country and city per profile.
+- **Live status** - see which profiles are running; close the browser and the list updates itself.
+
+## Proxies
+
+Around 90% of proxies are public, so their IPs are already known and blocked. For the clean 10%, residential IPs that aren't already known, we recommend [sx.org](https://sx.org/?c=invisible_playwright): set your API key once in the Proxies menu, then pick a country and city per profile. New accounts get 3 GB free with code `STEALTH`.
+
+## Related projects
+
+- **[invisible_core](https://github.com/feder-cr/invisible_core)** - the pure-config engine (seed to fingerprint to prefs, binary download, proxy, geo) this app runs on.
+- **[invisible_playwright](https://github.com/feder-cr/invisible_playwright)** - the same patched Firefox driven by Playwright, for automation.
+- **[firefox_antidetect_patch](https://github.com/feder-cr/firefox_antidetect_patch)** - the C++ patches against Firefox that produce the binary.
+
+## License
+
+MIT - see [LICENSE](https://github.com/feder-cr/invisible_firefox/blob/main/LICENSE). The patched Firefox binary is distributed under the MPL-2.0 (Firefox upstream license).
+
+## Disclaimer
+
+This project is for educational purposes only. It is provided as-is, with no warranties. I take no responsibility for how it is used. Use it at your own risk and in compliance with the laws of your jurisdiction.
+
+---
+
+<p align="center">
+  Built by <a href="https://it.linkedin.com/in/federico-elia-5199951b6">Federico Elia</a>
+  &nbsp;<a href="https://it.linkedin.com/in/federico-elia-5199951b6"><img src="https://raw.githubusercontent.com/feder-cr/invisible_firefox/main/docs/badges/linkedin.svg" alt="LinkedIn"></a>
+</p>

invisible_firefox-0.2.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "invisible-firefox"
+version = "0.2.0"
+description = "Antidetect browser profile manager for the patched Firefox (manual use)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "feder-cr", email = "85809106+feder-cr@users.noreply.github.com" }]
+keywords = ["firefox", "browser", "profile-manager", "anti-detect", "fingerprint"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    # An exact version, resolved from the index. It is the ONLY place the expected
+    # core version is written: the import-time check in invisible_firefox/__init__.py
+    # reads this requirement back with importlib.metadata.requires(), so there is no
+    # second copy to drift.
+    #
+    # Why exact and not a bare direct reference (which is what this was until the
+    # move to the index): a direct reference carries no version specifier, so there
+    # is nothing for pip to compare - `pip check` returns "No broken requirements
+    # found", exit 0, on a definitively broken environment, and direct_url.json goes
+    # on recording the old commit. The same mismatch written as a specifier is caught
+    # with exit 1, and a plain `pip install invisible-firefox` repairs a broken env
+    # because pip still follows Requires-Dist.
+    #
+    # The cost, accepted deliberately: a core-only release (CORE_REVISION bump) now
+    # needs this literal moved and a manager release. The residue an exact pin still
+    # cannot see (--no-deps, lockfile installs, a hand-patched site-packages) is what
+    # the import-time check in __init__.py is for.
+    "invisible-core==18.0.0",
+    "platformdirs>=4",
+    # cross-platform process tree: on Windows firefox.exe is a launcher stub
+    # that spawns the browser as a child and exits, so we track the real
+    # browser process (found by profile dir) via psutil - same code Win/Linux/mac.
+    "psutil>=5.9",
+    # pywebview backend per OS: Windows -> WebView2, macOS -> WKWebView (native,
+    # no extra deps); Linux needs an explicit webview backend, so pull the Qt one
+    # (pip-installable, unlike the GTK/WebKit2GTK system packages).
+    "pywebview>=4.4; sys_platform != 'linux'",
+    "pywebview[qt]>=4.4; sys_platform == 'linux'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build>=1"]
+
+# GUI app: gui-scripts so launching it does not open a console window on Windows.
+# `python -m invisible_firefox` stays the documented path and is the one to use
+# when something fails at import, because it keeps stderr attached.
+[project.gui-scripts]
+invisible-firefox = "invisible_firefox.ui.app:run"
+
+[project.urls]
+Homepage = "https://github.com/feder-cr/invisible_firefox"
+Repository = "https://github.com/feder-cr/invisible_firefox"
+Issues = "https://github.com/feder-cr/invisible_firefox/issues"
+
+# No [tool.hatch.metadata] allow-direct-references: with the opt-in absent,
+# hatchling refuses to build a direct reference back into the metadata, so the
+# `invisible-core==` pin above cannot silently regress to a git URL - PyPI would
+# reject the upload anyway, but this fails at build time instead.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/invisible_firefox"]
+
+# Without an explicit include list hatchling falls back to "everything the VCS
+# does not ignore", which shipped .githooks/pre-push, the whole docs/ folder (a
+# 96 KB screenshot plus four badge SVGs the README loads from raw.githubusercontent,
+# not from the archive) and packaging/ (the PyInstaller recipe for the standalone
+# bundle - a build input, not a runtime input): 38 members, now 30. Same shape as
+# the other two packages: source, tests, README, LICENSE, pyproject. .gitignore
+# stays either way - hatchling puts it in every sdist, include list or not.
+[tool.hatch.build.targets.sdist]
+include = ["src/invisible_firefox", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+addopts = "-m 'not integration'"
+markers = ["integration: launches the real patched Firefox binary named by the seal"]

invisible_firefox-0.2.0/src/invisible_firefox/__init__.py

@@ -0,0 +1,88 @@
+"""invisible_firefox - profile manager for the patched Firefox.
+
+The check below runs before anything else in this package is imported. It
+compares the invisible-core that will actually execute against the
+`invisible-core==` pin this distribution declares in its own metadata, so a
+core from another engine release is never quietly used to launch a browser
+whose configuration nobody matched.
+
+A mismatch is REPAIRED, not just reported: invisible_core._pin installs the
+declared core and picks it up in this process, so the script that imported us
+keeps running. That is only sound at this exact point, while invisible_core has
+not been imported by anybody yet, so the snapshot below is taken BEFORE the
+import and passed in. If it says the core was already loaded, the repair refuses
+itself and the message is printed instead. Every other failure of the repair
+(no network, a read-only site-packages, no pip) degrades to that same message.
+
+The comparison, the repair and the requirement parser all live in
+invisible_core._pin, shared with the other consumer, and the expected version is
+read back from this package's Requires-Dist. Nothing here holds a version
+literal.
+
+WHAT IS LOCAL, AND WHY. A module inside invisible_core cannot report that
+invisible_core is absent, unimportable, or too damaged to derive its own
+version: by the time it runs, it imported. So the try/except below is the only
+part of the check this package owns, and it classifies the failure three ways:
+
+  * an ImportError naming a module under invisible_core - the core is missing or
+    too old to carry the check;
+  * an ImportError naming anything else - the core is there but one of ITS
+    dependencies is not, which is what `pip install --no-deps` leaves behind;
+  * anything that is not an ImportError - the core is on disk and partially
+    destroyed. Measured: delete invisible_core/seal.json and the import dies
+    with a raw FileNotFoundError naming an absolute path, because
+    invisible_core.__init__ reaches _version.py, which reads the seal.
+
+All three remedies are `pip install --force-reinstall invisible-firefox`, so pip
+resolves the right core version out of our own Requires-Dist and no version
+literal appears here. None of the three is auto-repaired: the version to install
+can only come from the requirement parser, which is inside the core that just
+failed to import, and the only remedy that needs no version literal is a
+force-reinstall of the distribution that is halfway through importing right now.
+
+This package has no Playwright and no protocol channel to the browser, so this
+is its only cross-check. Keep it that way: _pin must stay import-cheap.
+"""
+
+import sys as _sys
+
+# Captured BEFORE the core is imported. It is the whole soundness argument for
+# the in-process repair: if nothing has imported invisible_core yet, nobody is
+# holding an object from the version the repair is about to replace. One line
+# later this is always True, so it has to be read here.
+_CORE_PREIMPORTED = any(
+    _name == "invisible_core" or _name.startswith("invisible_core.")
+    for _name in list(_sys.modules)
+)
+
+try:
+    from invisible_core._pin import enforce_core_pin as _enforce_core_pin
+except ImportError as _e:  # pragma: no cover - exercised by tests/test_seal_floor.py
+    _missing = getattr(_e, "name", "") or ""
+    if _missing and not _missing.startswith("invisible_core"):
+        raise ImportError(
+            f"invisible-core is installed but cannot be imported: no module named "
+            f"{_missing!r}.\n"
+            f"That is one of its own dependencies, so it was installed without "
+            f"dependency resolution (pip install --no-deps, or a lockfile that "
+            f"lists the packages separately).\n"
+            f"Run: pip install --force-reinstall invisible-firefox"
+        ) from _e
+    raise ImportError(
+        "invisible-core is missing, or too old for this invisible-firefox: it does "
+        "not carry the release-pin check (invisible_core._pin), so the engine it "
+        "downloads cannot be matched against the configuration this package ships.\n"
+        "Run: pip install --force-reinstall invisible-firefox"
+    ) from _e
+except Exception as _e:  # pragma: no cover - exercised by tests/test_seal_floor.py
+    raise ImportError(
+        f"invisible-core is installed but it cannot even determine its own version: "
+        f"importing it raised {type(_e).__name__}: {_e}\n"
+        f"That is a partial or damaged installation, not an old one. A missing or "
+        f"unreadable invisible_core/seal.json is the usual cause, and it is read "
+        f"while invisible_core is still importing, so nothing inside the core can "
+        f"report it.\n"
+        f"Run: pip install --force-reinstall invisible-firefox"
+    ) from _e
+
+_enforce_core_pin("invisible-firefox", core_preimported=_CORE_PREIMPORTED)

invisible_firefox-0.2.0/src/invisible_firefox/__main__.py

@@ -0,0 +1,4 @@
+from .ui.app import run
+
+if __name__ == "__main__":
+    raise SystemExit(run())

invisible_firefox-0.2.0/src/invisible_firefox/manager/fingerprint.py

@@ -0,0 +1,36 @@
+"""Display-ready fingerprint summary for the preview panel."""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Optional
+
+from invisible_core import generate_profile
+
+
+def _clean_gpu(renderer: str, vendor: str) -> str:
+    """Turn a raw WebGL renderer string into a short, human-readable GPU name.
+
+    Real renderers are ugly ANGLE strings, e.g.
+      ``ANGLE (NVIDIA, NVIDIA GeForce RTX 4060 Laptop GPU (0x00002D58) Direct3D11 vs_5_0 ps_5_0, D3D11)``
+    -> ``NVIDIA GeForce RTX 4060 Laptop GPU``.
+    """
+    r = (renderer or vendor or "").strip()
+    if r.upper().startswith("ANGLE") and "(" in r:
+        inner = r[r.find("(") + 1: r.rfind(")")] if ")" in r else r[r.find("(") + 1:]
+        parts = inner.split(",")
+        r = (parts[1] if len(parts) > 1 else parts[0]).strip()
+        r = re.sub(r"\s*\(0x[0-9a-fA-F]+\).*$", "", r)   # drop "(0x2D58) Direct3D11 ..."
+        r = re.sub(r"\s+Direct3D.*$", "", r)
+        r = re.sub(r"\s+vs_\d.*$", "", r).strip()
+    return r or "-"
+
+
+def fingerprint_summary(seed: int, pin: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    p = generate_profile(seed=seed, pin=pin)
+    return {
+        "gpu": _clean_gpu(p.gpu.renderer, p.gpu.vendor),
+        "gpu_vendor": p.gpu.vendor,
+        "gpu_renderer": p.gpu.renderer,
+        "screen": f"{p.screen.width}x{p.screen.height}",
+        "hardware_concurrency": p.hardware.concurrency,
+    }

invisible_firefox-0.2.0/src/invisible_firefox/manager/launcher.py

@@ -0,0 +1,216 @@
+"""Direct-launch orchestration: Profile -> running patched Firefox subprocess."""
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+    import psutil  # cross-platform process tree (Win/Linux/mac)
+except Exception:  # pragma: no cover - psutil is a declared dependency
+    psutil = None  # type: ignore
+
+from invisible_core import build_launch_plan as _core_build_launch_plan, LaunchPlan
+
+from .models import Profile
+from . import paths
+from . import settings as _settings
+from . import sx as _sx
+
+
+def resolve_launch_proxy(proxy: Optional[Dict[str, Any]], base: Optional[Path] = None):
+    """A profile's ``proxy`` is an INTENT. Turn it into a concrete proxy dict:
+    ``None`` -> ``None``; an SX intent (``{"provider":"sx",...}``) -> a live
+    SOCKS5 endpoint via the SX API; an already-concrete ``{"server":...}`` dict
+    -> itself."""
+    if not proxy:
+        return None
+    if proxy.get("provider") == "sx":
+        return _sx.resolve_proxy(proxy, _settings.load_settings(base))
+    return proxy
+
+
+@dataclass
+class LaunchHandle:
+    pid: int              # the REAL browser pid (resolved), NOT the launcher stub on Windows
+    profile_id: str
+    process: Any          # the subprocess.Popen we spawned (the launcher stub on Windows)
+    browser: Any = None   # psutil.Process of the real browser, when resolved (else None)
+
+
+def build_launch_plan(profile: Profile, base: Optional[Path] = None) -> LaunchPlan:
+    """Resolve the profile's proxy intent (SX -> concrete endpoint) and its
+    profile dir, then delegate the whole session setup to
+    ``invisible_core.build_launch_plan``. The manager owns only SX resolution and
+    where the profile lives; the fingerprint, geo, prefs, user.js, env and argv
+    are all invisible_core's job (one shared code path with the wrapper).
+
+    The manager does not choose a Firefox at all. It names no tag and no path,
+    so the engine is whichever one the installed invisible_core is sealed to,
+    and the core verifies that engine before it hands back a binary. The
+    per-profile ``binary_ver`` pin that used to be passed here was retired on
+    2026-07-25: it let one profile run an old engine under the new engine's
+    claimed identity, with nothing on screen to say so."""
+    rproxy = resolve_launch_proxy(profile.proxy, base)  # SX intent -> concrete endpoint
+    pdir = paths.profile_dir(profile.id, base=base)
+    return _core_build_launch_plan(
+        profile.seed,
+        profile_dir=pdir,
+        proxy=rproxy,
+        timezone=profile.timezone,
+        locale=profile.locale,
+        pin=profile.pin,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────
+#  Cross-OS process tracking (Win/Linux/mac)
+# ─────────────────────────────────────────────────────────────────────────
+# The pid we get from Popen is NOT always the browser:
+#   Windows - `firefox.exe` is a "launcher process" that spawns the real
+#             browser as its FIRST CHILD and then EXITS (Mozilla design, see
+#             wiki.mozilla.org/.../Launcher_Process). So Popen's pid dies in
+#             ~1s and the browser lives under a different pid.
+#   Linux   - the `firefox` script `exec`s firefox-bin in place: Popen's pid
+#             IS the browser.
+#   macOS   - the launched binary IS the browser (no launcher process).
+# We resolve the real browser uniformly by the PROFILE DIR in its cmdline
+# (unique per profile, present on every OS) and track THAT via psutil, so
+# running-status and stop work identically everywhere.
+
+
+def _is_main_firefox(p: "psutil.Process", target: str) -> bool:
+    """True iff psutil process ``p`` is a MAIN firefox browser (not a content
+    child) launched with ``-profile <target>``."""
+    try:
+        cmd = p.cmdline()
+        name = (p.name() or "").lower()
+    except Exception:
+        return False
+    if not cmd or "-contentproc" in cmd:
+        return False
+    exe0 = (cmd[0] or "").lower()
+    if not (name.startswith("firefox") or "firefox" in exe0):
+        return False
+    return any(target in (c or "") for c in cmd)
+
+
+def _has_contentproc_child(p: "psutil.Process") -> bool:
+    """True if ``p`` has at least one ``-contentproc`` firefox child. The REAL
+    browser spawns content processes; the Windows launcher stub does not - so
+    this cleanly tells the browser from the stub even while both exist."""
+    try:
+        for c in p.children(recursive=False):
+            try:
+                if "-contentproc" in c.cmdline():
+                    return True
+            except Exception:
+                continue
+    except Exception:
+        pass
+    return False
+
+
+def resolve_browser_process(profile_dir: Path, popen_proc: Any, timeout: float = 8.0) -> Any:
+    """Return the psutil.Process of the REAL browser for this profile, or None.
+
+    The browser is the main firefox process (``-profile <dir>``, not a
+    ``-contentproc`` child) that HAS content-process children. That test is what
+    makes this reliable cross-OS: on Windows the launcher stub also matches the
+    ``-profile`` filter but never spawns content children, so it is never
+    mistaken for the browser; on Linux/macOS the launched process is the browser
+    and has them. Falls back to any alive main-firefox match if content children
+    have not appeared before the timeout."""
+    if psutil is None:
+        return None
+    target = str(profile_dir)
+    launched_pid = getattr(popen_proc, "pid", None)
+    start = time.monotonic()
+    fallback = None
+    while time.monotonic() - start < timeout:
+        candidates: List[Any] = []
+        seen = set()
+        # Prefer the stub's subtree (Windows), then a global scan (Linux/mac +
+        # re-parented Windows child once the stub has exited).
+        if launched_pid is not None:
+            try:
+                for c in psutil.Process(launched_pid).children(recursive=True):
+                    if _is_main_firefox(c, target):
+                        candidates.append(c)
+                        seen.add(c.pid)
+            except Exception:
+                pass
+        try:
+            for p in psutil.process_iter(["name"]):
+                if not (p.info.get("name") or "").lower().startswith("firefox"):
+                    continue
+                if p.pid in seen:
+                    continue
+                if _is_main_firefox(p, target):
+                    candidates.append(p)
+        except Exception:
+            pass
+        for c in candidates:
+            if _has_contentproc_child(c):
+                return c  # unambiguously the real browser
+        alive = [c for c in candidates if c.is_running()]
+        if alive:
+            fallback = alive[0]
+        time.sleep(0.25)
+    return fallback
+
+
+def process_alive(psproc: Any) -> bool:
+    """Cross-OS liveness for a psutil.Process (False if gone or a zombie)."""
+    if psproc is None or psutil is None:
+        return False
+    try:
+        return psproc.is_running() and psproc.status() != psutil.STATUS_ZOMBIE
+    except Exception:
+        return False
+
+
+def terminate_process_tree(psproc: Any, timeout: float = 5.0) -> None:
+    """Terminate a browser and all its child processes, cross-OS. Graceful
+    terminate() first, then kill() any survivors."""
+    if psproc is None or psutil is None:
+        return
+    try:
+        procs = psproc.children(recursive=True)
+    except Exception:
+        procs = []
+    procs.append(psproc)
+    for p in procs:
+        try:
+            p.terminate()
+        except Exception:
+            pass
+    try:
+        _gone, alive = psutil.wait_procs(procs, timeout=timeout)
+    except Exception:
+        alive = procs
+    for p in alive:
+        try:
+            p.kill()
+        except Exception:
+            pass
+
+
+def launch(
+    profile: Profile,
+    base: Optional[Path] = None,
+    spawn: Callable[..., Any] = subprocess.Popen,
+) -> LaunchHandle:
+    plan = build_launch_plan(profile, base=base)
+    proc = spawn(plan.argv, env=plan.env)
+    # Only resolve the real browser on a REAL launch; an injected spawn (tests)
+    # keeps the raw process so its pid/handle stay predictable.
+    browser = None
+    real_pid = proc.pid
+    if spawn is subprocess.Popen:
+        browser = resolve_browser_process(plan.profile_dir, proc)
+        if browser is not None:
+            real_pid = browser.pid
+    return LaunchHandle(pid=real_pid, profile_id=profile.id, process=proc, browser=browser)