pythonnative 0.49.0__tar.gz → 0.50.0__tar.gz

{pythonnative-0.49.0 → pythonnative-0.50.0}/.github/workflows/release.yml

@@ -113,3 +113,83 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           skip-existing: true
+
+  # PythonNative Go, the prebuilt dev client, ships as release assets that
+  # `pn go` downloads for the matching version (RFC 0006). Its builds run
+  # after PyPI publishing so a toolchain hiccup never blocks the package.
+  go:
+    name: Build PythonNative Go (${{ matrix.name }})
+    needs: [release, publish]
+    if: needs.release.outputs.tag != '' && needs.release.outputs.commit != ''
+    strategy:
+      fail-fast: false
+      matrix:
+        # The simulator app's Python runtime is staged for one architecture,
+        # so each Mac architecture gets its own asset, built on a runner of
+        # that architecture (`pn go` downloads the one matching the Mac).
+        include:
+          - name: ios-arm64
+            platform: ios
+            runner: macos-15
+          - name: ios-x86_64
+            platform: ios
+            runner: macos-15-intel
+          - name: android
+            platform: android
+            runner: ubuntu-24.04
+    runs-on: ${{ matrix.runner }}
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_26.3.app/Contents/Developer
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.commit }}
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: '3.13'
+      - name: Set up Java 17
+        if: matrix.platform == 'android'
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - name: Set up Gradle
+        if: matrix.platform == 'android'
+        uses: gradle/actions/setup-gradle@v4
+      - name: Install PythonNative
+        run: uv sync --locked
+      - name: Build and package
+        run: uv run python scripts/build-go.py --platform ${{ matrix.platform }} --out go-dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: go-${{ matrix.name }}
+          path: go-dist/
+          if-no-files-found: error
+
+  go-assets:
+    name: Attach PythonNative Go to the release
+    needs: [release, go]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.commit }}
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: go-*
+          path: go-dist
+          merge-multiple: true
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: '3.13'
+      - name: Write checksums
+        run: uv run python scripts/build-go.py --checksums go-dist
+      - name: Upload
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ needs.release.outputs.tag }}
+        run: gh release upload "$RELEASE_TAG" go-dist/* --clobber

{pythonnative-0.49.0/src/pythonnative.egg-info → pythonnative-0.50.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.49.0
+Version: 0.50.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -40,6 +40,7 @@ Classifier: Topic :: Software Development :: User Interfaces
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: debugpy>=1.8
 Provides-Extra: build
 Requires-Dist: Pillow>=10.0; extra == "build"
 Dynamic: license-file
@@ -88,7 +89,9 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Device APIs:** Python facades expose camera, location, notifications, storage, permissions, keyboard, dimensions and pixel ratio, device info, localization, accessibility settings, and other native services, with a Python fallback for headless tests. Test permissions and platform behavior on your deployment targets.
 - **Native extension SDK:** Python dataclasses and protocols define contracts; `define_component` returns a typed element factory and `pn codegen` generates props and module adapters for Swift and Kotlin. Plugins package native sources and resources, and builds verify matching contracts at startup.
 - **Testing library:** `pythonnative.testing` renders components headlessly with Testing Library-style queries (`get_by_role`, `get_by_placeholder_text`, `within`, `find_by_*`), a virtual clock for timers, and a pytest plugin that resets the runtime between tests.
-- **Development tools:** `pn start` serves the browser preview and connected mobile dev clients. Fast Refresh preserves compatible component state, while diagnostics report errors and invalid hook usage. Changes to native inputs trigger a rebuild.
+- **PythonNative Go:** a prebuilt dev client, published with each release, runs any project without native code, so the project itself is never compiled. `i` / `a` in `pn start` open it on the iOS Simulator (which still needs Xcode installed) or an Android emulator, and a phone with Go installed opens the project by scanning the QR code `pn start` prints. Go isn't in the app stores: Android phones install the APK, and iPhones need Go built and signed with your Apple team. Projects that add native code run in their own debug build, which `pn run` rebuilds only when something native changes.
+- **DevTools and debugging:** `pn start` serves DevTools, with a component tree showing props and hooks (and editable state), a console with a REPL inside the running app, problems with component stacks and source excerpts, network requests, and live performance with trace capture. VS Code attaches `debugpy` breakpoints to Python on the preview, a simulator, or a phone. On device, a dev menu (shake or Cmd+D) offers reload, an element inspector, and a performance monitor, and errors show a screen with the component stack and your source.
+- **Development tools:** Fast Refresh preserves compatible component state, `pn lint` checks the rules of hooks, and `pn init` scaffolds tests, type checking, debugger settings, and CI.
 - **Browser preview:** `pn preview` runs your Python application against a browser renderer with DOM widgets, Yoga WebAssembly layout, and JavaScript animation graphs. It supports iteration on application logic and UI; fonts, platform controls, and device APIs require mobile testing.
 - **App packaging and dependency locks:** `pn run` and `pn build` stage bundled app templates, native libraries, and Python sources. Target-specific wheel locks record dependency versions and hashes for mobile builds. Binary dependencies need compatible mobile wheels; `pn deps` reports target resolution.
 
@@ -125,9 +128,8 @@ def App() -> pn.Node:
 
 ```bash
 pn init my-app && cd my-app
-pn preview          # dev server + browser preview with Fast Refresh
-pn run ios          # in another terminal: debug build that connects to the same server
-pn run android
+pn start            # dev server: scan the QR code, or press i (iOS), a (Android), w (browser), j (DevTools)
+pn run ios          # the project's own debug build, for projects that add native code
 pn build ios        # standalone release artifacts
 ```
 

{pythonnative-0.49.0 → pythonnative-0.50.0}/README.md

@@ -42,7 +42,9 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Device APIs:** Python facades expose camera, location, notifications, storage, permissions, keyboard, dimensions and pixel ratio, device info, localization, accessibility settings, and other native services, with a Python fallback for headless tests. Test permissions and platform behavior on your deployment targets.
 - **Native extension SDK:** Python dataclasses and protocols define contracts; `define_component` returns a typed element factory and `pn codegen` generates props and module adapters for Swift and Kotlin. Plugins package native sources and resources, and builds verify matching contracts at startup.
 - **Testing library:** `pythonnative.testing` renders components headlessly with Testing Library-style queries (`get_by_role`, `get_by_placeholder_text`, `within`, `find_by_*`), a virtual clock for timers, and a pytest plugin that resets the runtime between tests.
-- **Development tools:** `pn start` serves the browser preview and connected mobile dev clients. Fast Refresh preserves compatible component state, while diagnostics report errors and invalid hook usage. Changes to native inputs trigger a rebuild.
+- **PythonNative Go:** a prebuilt dev client, published with each release, runs any project without native code, so the project itself is never compiled. `i` / `a` in `pn start` open it on the iOS Simulator (which still needs Xcode installed) or an Android emulator, and a phone with Go installed opens the project by scanning the QR code `pn start` prints. Go isn't in the app stores: Android phones install the APK, and iPhones need Go built and signed with your Apple team. Projects that add native code run in their own debug build, which `pn run` rebuilds only when something native changes.
+- **DevTools and debugging:** `pn start` serves DevTools, with a component tree showing props and hooks (and editable state), a console with a REPL inside the running app, problems with component stacks and source excerpts, network requests, and live performance with trace capture. VS Code attaches `debugpy` breakpoints to Python on the preview, a simulator, or a phone. On device, a dev menu (shake or Cmd+D) offers reload, an element inspector, and a performance monitor, and errors show a screen with the component stack and your source.
+- **Development tools:** Fast Refresh preserves compatible component state, `pn lint` checks the rules of hooks, and `pn init` scaffolds tests, type checking, debugger settings, and CI.
 - **Browser preview:** `pn preview` runs your Python application against a browser renderer with DOM widgets, Yoga WebAssembly layout, and JavaScript animation graphs. It supports iteration on application logic and UI; fonts, platform controls, and device APIs require mobile testing.
 - **App packaging and dependency locks:** `pn run` and `pn build` stage bundled app templates, native libraries, and Python sources. Target-specific wheel locks record dependency versions and hashes for mobile builds. Binary dependencies need compatible mobile wheels; `pn deps` reports target resolution.
 
@@ -79,9 +81,8 @@ def App() -> pn.Node:
 
 ```bash
 pn init my-app && cd my-app
-pn preview          # dev server + browser preview with Fast Refresh
-pn run ios          # in another terminal: debug build that connects to the same server
-pn run android
+pn start            # dev server: scan the QR code, or press i (iOS), a (Android), w (browser), j (DevTools)
+pn run ios          # the project's own debug build, for projects that add native code
 pn build ios        # standalone release artifacts
 ```
 

{pythonnative-0.49.0 → pythonnative-0.50.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.49.0"
+version = "0.50.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -26,7 +26,11 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: User Interfaces",
 ]
-dependencies = []
+# debugpy is development tooling: `pn start` syncs its sources to dev
+# clients for breakpoint debugging (RFC 0006). App bundles never include it.
+dependencies = [
+  "debugpy>=1.8",
+]
 
 [project.optional-dependencies]
 build = [

{pythonnative-0.49.0 → pythonnative-0.50.0}/src/pythonnative/__init__.py

@@ -66,7 +66,7 @@ Example:
     ```
 """
 
-__version__ = "0.49.0"
+__version__ = "0.50.0"
 
 import importlib
 from typing import TYPE_CHECKING, Any

{pythonnative-0.49.0 → pythonnative-0.50.0}/src/pythonnative/bootstrap.py

@@ -88,6 +88,11 @@ def start(dev: bool = False, strict: bool = False, entry: Optional[str] = None)
 
             client = devclient.start_if_configured()
             status_["dev_server"] = client.server_label if client is not None else None
+            if client is None:
+                # No server yet: the dev menu, inspector, and performance
+                # monitor still work locally; a connection replaces this
+                # agent with one that reports to DevTools.
+                devclient.install_local_agent()
             # An overlay from the last session may already hold assets the
             # bundle doesn't; point the native resolver at it right away.
             from .assets import configure_native

{pythonnative-0.49.0 → pythonnative-0.50.0}/src/pythonnative/bridge/commits.py

@@ -21,7 +21,7 @@ from typing import Any, Callable
 from ..profiling import count, profiled
 from .list_store import ListStore
 
-PROTOCOL_VERSION = 5
+PROTOCOL_VERSION = 6
 """The bridge protocol every runtime speaks; generated native contracts carry it."""
 
 

{pythonnative-0.49.0 → pythonnative-0.50.0}/src/pythonnative/bridge/web.py

@@ -24,6 +24,7 @@ __all__ = ["BROWSER_MODULES", "WebTransport"]
 
 BROWSER_MODULES = frozenset(
     {
+        "DevSupport",
         "Host",
         "Layout",
         "Alert",

pythonnative-0.50.0/src/pythonnative/cli/keys.py

@@ -0,0 +1,178 @@
+"""Single-key commands for ``pn start``, like Metro's terminal UI.
+
+When stdin is a terminal, ``pn start`` reads keys without waiting for
+Enter. [`KeyCommands.handle`][pythonnative.cli.keys.KeyCommands.handle]
+maps each key to an action; it's separate from the terminal handling so it
+can be tested without one.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import threading
+import webbrowser
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+__all__ = ["HELP", "KeyCommands", "read_keys"]
+
+Logger = Callable[[str], None]
+
+HELP: List[Tuple[str, str]] = [
+    ("i", "open on the iOS Simulator (in PythonNative Go when the project can run there)"),
+    ("a", "open on an Android emulator or device (in PythonNative Go when possible)"),
+    ("I / A", "build and run the project's own development app"),
+    ("w", "open the browser preview"),
+    ("j", "open DevTools"),
+    ("r", "reload every connected app"),
+    ("m", "open the dev menu on every connected device"),
+    ("d", "show how to attach a debugger"),
+    ("c", "clear the terminal"),
+    ("?", "show these commands"),
+    ("q", "quit"),
+]
+
+LAUNCH_CONFIG = """{
+  "name": "PythonNative: Attach",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": {"host": "127.0.0.1", "port": %d},
+  "justMyCode": true
+}"""
+
+
+class KeyCommands:
+    """Turn keys into dev-server actions.
+
+    Args:
+        session: The running ``PreviewSession``.
+        port: The dev server's port (passed to ``pn go`` and ``pn run``).
+        log: Terminal logger.
+        stop: Called by ``q``.
+        spawn: Runs a ``pn`` subcommand in the background (tests replace it).
+    """
+
+    def __init__(
+        self,
+        session: Any,
+        port: int,
+        log: Logger,
+        stop: Callable[[], None],
+        spawn: Optional[Callable[[List[str]], None]] = None,
+    ) -> None:
+        self.session = session
+        self.port = port
+        self.log = log
+        self.stop = stop
+        self.spawn = spawn or self._spawn
+        self._running: Dict[str, subprocess.Popen[bytes]] = {}
+
+    def help_lines(self) -> List[str]:
+        """The command list, aligned."""
+        return [f"  {key:<6} {text}" for key, text in HELP]
+
+    def handle(self, key: str) -> bool:
+        """Run the action for ``key``; returns ``False`` once the server should stop."""
+        server = self.session.server
+        if key in ("i", "a", "I", "A"):
+            platform = "ios" if key.lower() == "i" else "android"
+            use_go = key.islower() and self._go_compatible()
+            command = ["go" if use_go else "run", platform, "--port", str(self.port)]
+            if not use_go:
+                command.append("--no-logs")
+            what = "PythonNative Go" if use_go else "the project's development app"
+            self.log(f"[pn] opening {what} on {'iOS' if platform == 'ios' else 'Android'}...")
+            self.spawn(command)
+        elif key == "w":
+            webbrowser.open(server.info.preview_url("localhost"))
+        elif key == "j":
+            webbrowser.open(server.info.devtools_url("localhost"))
+        elif key == "r":
+            self.log("[pn] reloading every connected app")
+            server.broadcast_command("reload")
+        elif key == "m":
+            self.log("[pn] opening the dev menu on connected devices")
+            server.broadcast_command("menu")
+        elif key == "d":
+            self._debug_help()
+        elif key == "c":
+            sys.stdout.write("\033[2J\033[H")
+            sys.stdout.flush()
+        elif key in ("?", "h"):
+            for line in ["", "  Commands:", *self.help_lines(), ""]:
+                self.log(line)
+        elif key in ("q", "\x03", "\x04"):
+            self.stop()
+            return False
+        return True
+
+    def _go_compatible(self) -> bool:
+        try:
+            runtime = self.session.server.project_runtime
+        except Exception:
+            return True
+        if not runtime.go_compatible:
+            reasons = runtime.plugins + runtime.native_packages
+            self.log(
+                f"[pn] this project needs native code PythonNative Go doesn't have ({', '.join(reasons)}); "
+                "building its development app instead"
+            )
+            return False
+        return True
+
+    def _debug_help(self) -> None:
+        server = self.session.server
+        if not server.debug_port:
+            self.log("[pn] the debugger proxy is off (start with --debug-port 5678)")
+            return
+        target = server.hub.default_target()
+        where = target.label() if target is not None else "the next app that connects"
+        self.log(f"[pn] debugger: attach a Debug Adapter Protocol client to 127.0.0.1:{server.debug_port}")
+        self.log(f"[pn] it debugs {where}; pick another in DevTools or with the device's dev menu")
+        self.log("[pn] VS Code launch configuration (pn init writes it to .vscode/launch.json):")
+        for line in (LAUNCH_CONFIG % server.debug_port).split("\n"):
+            self.log("    " + line)
+
+    def _spawn(self, args: List[str]) -> None:
+        """Run ``pn <args>`` in the background, outside the preview's web environment."""
+        name = " ".join(args[:2])
+        previous = self._running.get(name)
+        if previous is not None and previous.poll() is None:
+            self.log(f"[pn] `pn {name}` is still running")
+            return
+        env = {key: value for key, value in os.environ.items() if key != "PN_PLATFORM"}
+        process = subprocess.Popen(
+            [sys.executable, "-m", "pythonnative.cli.pn", *args], env=env, stdin=subprocess.DEVNULL
+        )
+        self._running[name] = process
+
+
+def read_keys(handle: Callable[[str], bool], stopped: threading.Event) -> None:
+    """Read single keys from the terminal until ``handle`` returns ``False`` or ``stopped`` is set.
+
+    The terminal is put in cbreak mode (keys arrive without Enter, and
+    Ctrl+C still interrupts) and restored on exit.
+    """
+    try:
+        import select
+        import termios
+        import tty
+    except ImportError:  # Windows: no key commands.
+        return
+    fd = sys.stdin.fileno()
+    try:
+        saved = termios.tcgetattr(fd)
+    except termios.error:
+        return
+    try:
+        tty.setcbreak(fd)
+        while not stopped.is_set():
+            ready, _, _ = select.select([fd], [], [], 0.25)
+            if not ready:
+                continue
+            key = os.read(fd, 1).decode("utf-8", errors="ignore")
+            if key and not handle(key):
+                break
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)

pythonnative-0.50.0/src/pythonnative/cli/launch.py

@@ -0,0 +1,261 @@
+"""Device-facing steps shared by ``pn run``, ``pn go``, and ``pn start``'s keys.
+
+These shell out to ``xcrun simctl``, ``xcrun devicectl``, ``adb``, and the
+Android emulator, so they're exercised on real toolchains rather than in
+unit tests (which cover the pure helpers: links and URLs).
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from ..project import devices as devices_mod
+
+Logger = Callable[[str], None]
+
+__all__ = [
+    "boot_android_emulator",
+    "booted_ios_udid",
+    "ensure_android_device",
+    "install_android",
+    "install_ios_simulator",
+    "open_link_android",
+    "launch_ios_device",
+    "launch_ios_simulator",
+    "select_ios_simulator",
+    "server_connect_url",
+]
+
+
+# ======================================================================
+# URLs
+# ======================================================================
+
+
+def server_connect_url(platform: str, device: Optional[devices_mod.Device], port: int, token: str) -> str:
+    """The server URL a launched dev client should use to reach ``pn start``.
+
+    Simulators share the host's loopback. Android emulators and USB
+    devices reach it through ``adb reverse`` (set up by the caller), so
+    ``localhost`` works for every Android target. A physical iOS device is
+    on the LAN, so it gets the first LAN address. The URL carries the dev
+    ``token`` the server requires.
+    """
+    from ..devserver.auth import with_token
+
+    host = "localhost"
+    if platform == "ios" and device is not None and device.kind == "device":
+        from ..devserver import lan_addresses
+
+        host = next(iter(lan_addresses()), host)
+    return with_token(f"http://{host}:{port}/", token)
+
+
+# ======================================================================
+# iOS
+# ======================================================================
+
+
+def booted_ios_udid() -> Optional[str]:
+    """A booted iOS Simulator's UDID, or ``None``."""
+    try:
+        result = subprocess.run(
+            ["xcrun", "simctl", "list", "devices", "booted", "--json"], check=False, capture_output=True, text=True
+        )
+    except FileNotFoundError:
+        return None
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return None
+    for devices in (data.get("devices") or {}).values():
+        for device in devices or []:
+            if device.get("state") == "Booted" and device.get("udid"):
+                return str(device["udid"])
+    return None
+
+
+def select_ios_simulator() -> Optional[str]:
+    """A simulator UDID to target: the booted one, else an iPhone 15, else the first available iPhone.
+
+    The fallback order is deliberate: a full-size iPhone keeps layouts (and
+    the E2E suite's taps) the same from run to run, where picking by name
+    could land on a compact model such as the iPhone SE.
+    """
+    booted = booted_ios_udid()
+    if booted:
+        return booted
+    try:
+        result = subprocess.run(
+            ["xcrun", "simctl", "list", "devices", "available", "--json"], check=False, capture_output=True, text=True
+        )
+    except FileNotFoundError:
+        return None
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return None
+    devices: List[Dict[str, Any]] = [d for entries in (data.get("devices") or {}).values() for d in (entries or [])]
+    for device in devices:
+        if "iphone 15" in str(device.get("name") or "").lower() and device.get("isAvailable"):
+            return str(device.get("udid"))
+    for device in devices:
+        if device.get("isAvailable") and str(device.get("name") or "").lower().startswith("iphone"):
+            return str(device.get("udid"))
+    return None
+
+
+def boot_ios_simulator(udid: str) -> None:
+    """Boot ``udid`` (a no-op when it's booted) and bring Simulator.app forward."""
+    subprocess.run(["xcrun", "simctl", "boot", udid], check=False, capture_output=True)
+    subprocess.run(["open", "-a", "Simulator"], check=False, capture_output=True)
+    subprocess.run(["xcrun", "simctl", "bootstatus", udid, "-b"], check=False, capture_output=True)
+
+
+def install_ios_simulator(udid: str, app: Path) -> bool:
+    """Install an ``.app`` on a simulator."""
+    return subprocess.run(["xcrun", "simctl", "install", udid, str(app)], check=False).returncode == 0
+
+
+def launch_ios_simulator(
+    udid: str, bundle_id: str, link: Optional[str], *, console: bool = False
+) -> "subprocess.Popen[bytes]":
+    """Relaunch an app on a simulator, handing it a connect link.
+
+    The link travels in the launch environment (``PN_CONNECT_LINK``)
+    rather than through ``simctl openurl``, which makes iOS ask the user to
+    confirm opening the app. With ``console``, the app's stdout and stderr
+    stream to this terminal and the returned process runs until the app
+    exits.
+    """
+    import os
+
+    from ..devclient import LINK_ENV
+
+    env = {**os.environ, "SIMCTL_CHILD_PYTHONUNBUFFERED": "1"}
+    if link:
+        env["SIMCTL_CHILD_" + LINK_ENV] = link
+    command = ["xcrun", "simctl", "launch", "--terminate-running-process"]
+    if console:
+        command.append("--console-pty")
+    return subprocess.Popen([*command, udid, bundle_id], env=env)
+
+
+def launch_ios_device(identifier: str, bundle_id: str, link: Optional[str]) -> bool:
+    """Relaunch an app on a physical device, handing it a connect link."""
+    from ..devclient import LINK_ENV
+
+    command = ["xcrun", "devicectl", "device", "process", "launch", "--terminate-existing"]
+    if link:
+        command += ["--environment-variables", json.dumps({LINK_ENV: link})]
+    command += ["--device", identifier, bundle_id]
+    return subprocess.run(command, check=False).returncode == 0
+
+
+# ======================================================================
+# Android
+# ======================================================================
+
+
+def _emulator_binary() -> Optional[Path]:
+    from ..project.android import sdk_dir
+
+    candidate = sdk_dir() / "emulator" / "emulator"
+    return candidate if candidate.exists() else None
+
+
+def list_avds() -> List[str]:
+    """The Android Virtual Devices this machine has."""
+    emulator = _emulator_binary()
+    if emulator is None:
+        return []
+    result = subprocess.run([str(emulator), "-list-avds"], check=False, capture_output=True, text=True)
+    return [line.strip() for line in (result.stdout or "").splitlines() if line.strip() and " " not in line.strip()]
+
+
+def boot_android_emulator(log: Logger, avd: Optional[str] = None, timeout: float = 240.0) -> Optional[str]:
+    """Boot an emulator and wait until Android finished booting; returns its serial."""
+    emulator = _emulator_binary()
+    avds = list_avds()
+    name = avd or (avds[0] if avds else None)
+    if emulator is None or name is None:
+        log("No Android emulator to boot: create one in Android Studio's Device Manager.")
+        return None
+    log(f"Booting the Android emulator {name}...")
+    subprocess.Popen(
+        [str(emulator), "-avd", name, "-netdelay", "none", "-netspeed", "full"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        for device in devices_mod.list_android_devices():
+            if device.kind == "emulator" and device.is_ready:
+                booted = subprocess.run(
+                    ["adb", "-s", device.identifier, "shell", "getprop", "sys.boot_completed"],
+                    check=False,
+                    capture_output=True,
+                    text=True,
+                )
+                if booted.stdout.strip() == "1":
+                    return device.identifier
+        time.sleep(2.0)
+    log("The emulator didn't finish booting in time.")
+    return None
+
+
+def ensure_android_device(device: Optional[devices_mod.Device], log: Logger) -> Optional[str]:
+    """A ready Android serial: ``device``'s, the first connected one, or a freshly booted emulator."""
+    if device is not None:
+        return device.identifier
+    ready = [d for d in devices_mod.list_android_devices() if d.is_ready]
+    if ready:
+        return ready[0].identifier
+    return boot_android_emulator(log)
+
+
+def _adb(serial: Optional[str], *args: str, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    command = ["adb", *(["-s", serial] if serial else []), *args]
+    return subprocess.run(command, check=False, capture_output=capture, text=True)
+
+
+def install_android(serial: Optional[str], apk: Path, package: str, log: Logger) -> bool:
+    """Install an APK, replacing an installed copy signed with a different key."""
+    result = _adb(serial, "install", "-r", str(apk), capture=True)
+    if result.returncode == 0:
+        return True
+    output = (result.stdout or "") + (result.stderr or "")
+    if "INSTALL_FAILED_UPDATE_INCOMPATIBLE" in output or "signatures do not match" in output:
+        log(f"Replacing the installed {package}, which was signed with a different key.")
+        _adb(serial, "uninstall", package, capture=True)
+        return _adb(serial, "install", str(apk)).returncode == 0
+    log(output.strip())
+    return False
+
+
+def reverse_port(serial: Optional[str], port: int) -> None:
+    """Let the device reach ``localhost:port`` on this machine (``adb reverse``)."""
+    _adb(serial, "reverse", f"tcp:{port}", f"tcp:{port}", capture=True)
+
+
+def open_link_android(serial: Optional[str], link: str, package: str) -> bool:
+    """Open a deep link in ``package`` (launching it when needed)."""
+    # `adb shell` runs its arguments through the device's shell.
+    command = f"am start -a android.intent.action.VIEW -d {shlex.quote(link)} {shlex.quote(package)}"
+    return _adb(serial, "shell", command).returncode == 0
+
+
+def stop_android_app(serial: Optional[str], package: str) -> None:
+    """Force-stop ``package`` so the next link cold-starts it."""
+    _adb(serial, "shell", "am", "force-stop", package, capture=True)
+
+
+def describe(device: Optional[devices_mod.Device]) -> Dict[str, Any]:
+    """A loggable description of a target device."""
+    return device.to_dict() if device is not None else {}