layernav-android 0.3.0__py3-none-any.whl

layernav_android/__init__.py

@@ -0,0 +1,29 @@
+from layernav_android._protocol import AdbProtocol
+from layernav_android.base import (
+    BaseLayerModel,
+    DetectResult,
+    KEYCODE_BACK,
+    KEYCODE_HOME,
+    LayerDef,
+    LayerListener,
+    POST_TRANSITION_SLEEP,
+)
+from layernav_android.cold_start import (
+    APP_DEFAULTS,
+    cold_start_app_from_launcher,
+    dock_app_icon_coords,
+)
+
+__all__ = [
+    "AdbProtocol",
+    "APP_DEFAULTS",
+    "BaseLayerModel",
+    "cold_start_app_from_launcher",
+    "DetectResult",
+    "dock_app_icon_coords",
+    "KEYCODE_BACK",
+    "KEYCODE_HOME",
+    "LayerDef",
+    "LayerListener",
+    "POST_TRANSITION_SLEEP",
+]

layernav_android/_protocol.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class AdbProtocol(Protocol):
+    """Minimal ADB interface for layer navigation.
+
+    Users implement or inject their existing ADB client.
+    ``collector_phone_android``'s ``AdbClient`` already satisfies
+    this protocol — no adapter needed.
+    """
+
+    def screencap(self) -> bytes: ...
+    def key_event(self, code: int) -> None: ...
+    def foreground_package(self) -> str: ...
+    def tap(self, x: int, y: int) -> None: ...
+    def _run(self, args: list[str]) -> str: ...

layernav_android/base.py

@@ -0,0 +1,402 @@
+"""Multi-layer Android task-stack navigation framework.
+
+Framework—Task contract:
+    Task subclass overrides:
+        - ``layers`` — list of :class:`LayerDef`
+        - ``detect`` — screenshot-based layer detection
+        - ``_on_Lx`` — per-layer handler (business logic + tap)
+
+Framework provides:
+    Atomic:   ``detect``  ``enter_next``  ``back_one``  ``back_recover``
+    Combined: ``back``    ``advance``     ``restore``
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Protocol
+
+from layernav_android._protocol import AdbProtocol
+
+LOG = logging.getLogger("layernav")
+
+POST_TRANSITION_SLEEP = 1.5
+
+KEYCODE_BACK = 4
+KEYCODE_HOME = 3
+
+# ── Layer definition ──────────────────────────────────────────────────────────
+
+
+@dataclass
+class LayerDef:
+    """Description of one layer in the Android task stack."""
+
+    key: str
+    """Layer key: ``"L0"`` | ``"L1"`` | ``"L2"`` | ``"L3"``."""
+
+    name: str
+    """Machine-readable name."""
+
+    label_cn: str
+    """Human-readable Chinese label."""
+
+    detection: str
+    """How this layer is detected (human-readable)."""
+
+    page_name: str = ""
+    """Optional custom page name. Callers can set this per-layer to
+    distinguish sub-states within a layer (e.g. main_list vs recent_page for L1).
+    Default empty string means no sub-page distinction."""
+
+    detection_extra: str = ""
+    """Optional detail about detection (human-readable, complementary to
+    *detection*). Callers can append custom context strings."""
+
+
+# ── Observer / Listener (inspired by python-statemachine's Listener pattern) ───
+
+
+class LayerListener(Protocol):
+    """Observer interface for layer model lifecycle events.
+
+    All methods are optional — implement only what you need.
+    Inspired by `python-statemachine
+    <https://github.com/fgmacedo/python-statemachine>`_'s Listener pattern.
+    """
+
+    def on_transition(
+        self, from_layer: str, to_layer: str, method: str,
+    ) -> None:
+        """Called after an atomic layer transition completes.
+
+        *method* is one of ``"enter_next"`` or ``"back_one"``.
+        """
+        ...
+
+    def on_timeout(
+        self, from_layer: str, target_layer: str, elapsed_s: float,
+    ) -> None:
+        """Called when :meth:`BaseLayerModel.enter_next` polling times out."""
+        ...
+
+    def on_recovery(self, target_layer: str, ok: bool) -> None:
+        """Called after :meth:`BaseLayerModel.back_recover` completes.
+
+        *ok* indicates whether the recovery succeeded.
+        """
+        ...
+
+
+# ── Layer detection result ──────────────────────────────────────────────────────
+
+
+@dataclass
+class DetectResult:
+    """Result of :meth:`BaseLayerModel.detect_detail`.
+
+    Combines layer key with optional page_name from :class:`LayerDef`.
+    """
+
+    layer_key: str
+    """Layer key: ``"L0"`` | ``"L1"`` | ``"L2"`` | ``"L3"``."""
+
+    page_name: str = ""
+    """Custom page name from :attr:`LayerDef.page_name`, or ``""``."""
+
+
+# ── Abstract base ─────────────────────────────────────────────────────────────
+
+
+class BaseLayerModel:
+    """Abstract Android task-stack layer model.
+
+    Subclass contract:
+        - Override :attr:`layers`.
+        - Override :meth:`detect`.
+        - Override ``_on_L0`` / ``_on_L1`` / ``_on_L2`` / ``_on_L3``.
+        - Optionally override :meth:`_cold_start`.
+    """
+
+    layers: list[LayerDef] = []
+    _ON_METHODS: tuple[str, ...] = ("_on_L0", "_on_L1", "_on_L2", "_on_L3")
+
+    def __init__(self) -> None:
+        self._listeners: list[LayerListener] = []
+
+    def add_listener(self, listener: LayerListener) -> None:
+        """Register a :class:`LayerListener` to observe lifecycle events."""
+        self._listeners.append(listener)
+
+    def _notify_transition(
+        self, from_layer: str, to_layer: str, method: str,
+    ) -> None:
+        for lst in self._listeners:
+            lst.on_transition(from_layer, to_layer, method)
+
+    def _notify_timeout(
+        self, from_layer: str, target_layer: str, elapsed_s: float,
+    ) -> None:
+        for lst in self._listeners:
+            lst.on_timeout(from_layer, target_layer, elapsed_s)
+
+    def _notify_recovery(self, target_layer: str, ok: bool) -> None:
+        for lst in self._listeners:
+            lst.on_recovery(target_layer, ok)
+
+    # ── Subclass overrides ────────────────────────────────────────────────────
+
+    def detect(self, adb: AdbProtocol, scale_w: float) -> str:
+        """Return current layer key.  Task MUST override."""
+        raise NotImplementedError("subclass must override detect()")
+
+    def detect_detail(self, adb: AdbProtocol, scale_w: float) -> DetectResult:
+        """Return current layer key + custom page_name.
+
+        Default implementation calls :meth:`detect` and looks up
+        :attr:`LayerDef.page_name` from :attr:`layers`.  Subclasses
+        may override to set page_name dynamically.
+        """
+        layer_key = self.detect(adb, scale_w)
+        page_name = ""
+        for ld in self.layers:
+            if ld.key == layer_key:
+                page_name = ld.page_name
+                break
+        return DetectResult(layer_key=layer_key, page_name=page_name)
+
+    def _recover_to_page(
+        self,
+        layer: str,
+        page_name: str,
+        adb: AdbProtocol,
+        scale_w: float,
+    ) -> bool:
+        """Navigate to a specific sub-page within *layer* after recovery.
+
+        Called by :meth:`back_recover` (and :meth:`restore` when already
+        on the target layer) after reaching the correct layer.  Override
+        to handle sub-page navigation (e.g. switching tabs within L1).
+
+        Default: verify current page via :meth:`detect_detail` — returns
+        ``True`` if ``detect_detail().page_name == page_name``.
+        """
+        result = self.detect_detail(adb, scale_w)
+        return result.page_name == page_name
+
+    def _on_L0(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L0 handler: home screen → cold-start App."""
+        raise NotImplementedError("subclass must override _on_L0")
+
+    def _on_L1(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L1 handler: App main screen → pick content, tap."""
+        raise NotImplementedError("subclass must override _on_L1")
+
+    def _on_L2(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L2 handler: content page → pick sub-content, tap."""
+        raise NotImplementedError("subclass must override _on_L2")
+
+    def _on_L3(self, adb: AdbProtocol, scale_w: float, *, quick: bool = False) -> str | None:
+        """L3 handler: deepest layer — typically no further advance."""
+        raise NotImplementedError("subclass must override _on_L3")
+
+    def _call_on_layer(
+        self, layer_key: str, adb: AdbProtocol, scale_w: float, *, quick: bool
+    ) -> str | None:
+        i = self._layer_index(layer_key)
+        if i < 0:
+            LOG.error("_call_on_layer: unknown layer %s", layer_key)
+            return None
+        method = getattr(self, self._ON_METHODS[i])
+        return method(adb, scale_w, quick=quick)
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _layer_index(self, layer_key: str) -> int:
+        for i, ld in enumerate(self.layers):
+            if ld.key == layer_key:
+                return i
+        return -1
+
+    def init(self, adb: AdbProtocol) -> None:
+        """One-time initialisation (optional)."""
+        pass
+
+    def _cold_start(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float
+    ) -> None:
+        """Cold-start the target app (override in subclass)."""
+        pass
+
+    # ── Atomic API ────────────────────────────────────────────────────────────
+
+    def enter_next(
+        self,
+        adb: AdbProtocol,
+        scale_w: float,
+        *,
+        quick: bool = False,
+        max_wait_s: float = 8.0,
+    ) -> bool:
+        """Advance ONE layer from current position.
+
+        1. detect current layer  ← **guard** (pre-check)
+        2. call _on_L[cur](quick) — handler does business + tap
+        3. if handler returns None or same layer → stop (success)
+        4. wait POST_TRANSITION_SLEEP, then detect  ← **validator** (post-check)
+        5. if not yet on target, poll with increasing intervals up to max_wait_s
+
+        This handles variable transition times (network loading, animations).
+        """
+        cur = self.detect(adb, scale_w)
+        target = self._call_on_layer(cur, adb, scale_w, quick=quick)
+        if target is None or target == cur:
+            return True
+
+        time.sleep(POST_TRANSITION_SLEEP)
+        next_cur = self.detect(adb, scale_w)
+        if next_cur == target:
+            self._notify_transition(cur, next_cur, "enter_next")
+            return True
+
+        poll_start = time.monotonic()
+        deadline = poll_start + max_wait_s
+        interval = 0.5
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            next_cur = self.detect(adb, scale_w)
+            if next_cur == target:
+                self._notify_transition(cur, next_cur, "enter_next")
+                return True
+            interval = min(interval + 0.5, 2.0)
+
+        elapsed = time.monotonic() - poll_start
+        LOG.warning(
+            "enter_next: %s→%s timeout after %.1fs — still on %s",
+            cur, target, max_wait_s, next_cur,
+        )
+        self._notify_timeout(cur, target, elapsed)
+        return False
+
+    def back_one(self, adb: AdbProtocol, scale_w: float) -> str:
+        """Send KEYCODE_BACK once, return new layer.
+
+        1. detect current layer  ← **guard** (pre-check)
+        2. KEYCODE_BACK
+        3. sleep, detect new layer  ← **validator** (post-check)
+        """
+        cur = self.detect(adb, scale_w)
+        LOG.debug("back_one: from %s", cur)
+        adb.key_event(KEYCODE_BACK)
+        time.sleep(1.0)
+        next_cur = self.detect(adb, scale_w)
+        LOG.debug("back_one: %s → %s", cur, next_cur)
+        self._notify_transition(cur, next_cur, "back_one")
+        return next_cur
+
+    def back_recover(
+        self,
+        adb: AdbProtocol,
+        target_layer: str,
+        scale_w: float,
+        *,
+        target_page: str | None = None,
+    ) -> bool:
+        """Recover after BACK exhaustion: cold-start → fast-forward → page.
+
+        If *target_page* is given, calls :meth:`_recover_to_page` after
+        reaching *target_layer*.
+        """
+        LOG.warning("back_recover: cold-start → fast-forward → %s (page=%s)",
+                     target_layer, target_page)
+        adb.key_event(KEYCODE_HOME)
+        time.sleep(0.8)
+        self._cold_start(adb, "L1", scale_w)
+
+        ok = self.advance(adb, target_layer, scale_w, quick=True)
+        if not ok:
+            self._notify_recovery(target_layer, False)
+            return False
+
+        if target_page is not None:
+            page_ok = self._recover_to_page(
+                target_layer, target_page, adb, scale_w,
+            )
+            if not page_ok:
+                LOG.error(
+                    "back_recover: reached L%s but page=%s recovery failed",
+                    target_layer, target_page,
+                )
+                self._notify_recovery(target_layer, False)
+                return False
+
+        result = self.detect(adb, scale_w) == target_layer
+        self._notify_recovery(target_layer, result)
+        return result
+
+    # ── Combined API ──────────────────────────────────────────────────────────
+
+    def back(
+        self, adb: AdbProtocol, to_layer: str, scale_w: float, *,
+        target_page: str | None = None,
+    ) -> bool:
+        """Retreat to *to_layer* via repeated BACK."""
+        for _ in range(3):
+            cur = self.detect(adb, scale_w)
+            if cur == to_layer:
+                self._call_on_layer(to_layer, adb, scale_w, quick=False)
+                if target_page is not None:
+                    return self._recover_to_page(to_layer, target_page, adb, scale_w)
+                return True
+            if cur == "L0":
+                break
+            self.back_one(adb, scale_w)
+        return self.back_recover(adb, to_layer, scale_w, target_page=target_page)
+
+    def advance(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float, *,
+        quick: bool = False,
+        max_wait_s: float = 8.0,
+    ) -> bool:
+        """Advance layer-by-layer to *target_layer*.
+
+        Uses :meth:`enter_next` for each step.  *quick* is forwarded to
+        intermediate layers' handlers.  At the target layer, handler is
+        always called with ``quick=False``.
+        """
+        while True:
+            cur = self.detect(adb, scale_w)
+            if cur == target_layer:
+                self._call_on_layer(target_layer, adb, scale_w, quick=False)
+                return True
+            ok = self.enter_next(adb, scale_w, quick=quick, max_wait_s=max_wait_s)
+            if not ok:
+                return False
+
+    def restore(
+        self, adb: AdbProtocol, target_layer: str, scale_w: float, *,
+        target_page: str | None = None,
+    ) -> bool:
+        """Restore to *target_layer* (and optionally *target_page*) from any position.
+
+        If already on *target_layer* but page mismatch, calls
+        :meth:`_recover_to_page` without cold-start.
+        """
+        cur = self.detect(adb, scale_w)
+        if cur == target_layer:
+            if target_page is not None:
+                return self._recover_to_page(target_layer, target_page, adb, scale_w)
+            return True
+        ci = self._layer_index(cur)
+        ti = self._layer_index(target_layer)
+        if ci > ti:
+            return self.back(adb, target_layer, scale_w, target_page=target_page)
+        else:
+            ok = self.advance(adb, target_layer, scale_w, quick=True)
+            if not ok:
+                return False
+            if target_page is not None:
+                return self._recover_to_page(target_layer, target_page, adb, scale_w)
+            return True

layernav_android/cold_start.py

@@ -0,0 +1,224 @@
+"""Generic cold-start: launch an Android app from the launcher home screen.
+
+Three paths tried in priority order:
+
+1. **monkey** — ``monkey -p <package> -c LAUNCHER 1`` (primary)
+2. **am start Intent** — ``am start -a MAIN -c LAUNCHER <package>`` (backup
+   for custom ROMs like MIUI / ColorOS that may restrict monkey)
+3. **Dock icon tap** — calculated via ``dock_app_icon_coords`` (last resort,
+   with 0.5 s pre‑wait and up to 2 retries)
+
+After the app enters foreground, optionally taps a session tab to reach the
+app's main content list (e.g. WeChat's bottom "微信" tab).
+
+Screen dimensions are always auto‑detected via ``adb shell wm size``.
+
+.. code-block:: python
+
+    from layernav_android.cold_start import cold_start_app_from_launcher
+
+    ok = cold_start_app_from_launcher(
+        adb, "com.tencent.mm",
+        app_name="wechat", M=4, N=3,
+        session_tab_x=108, session_tab_y=2192,
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+
+from layernav_android._protocol import AdbProtocol
+
+LOG = logging.getLogger("layernav.cold_start")
+
+_SZ_RE = re.compile(r"(\d{3,})\s*x\s*(\d{3,})")
+
+APP_DEFAULTS: dict[str, dict[str, int]] = {
+    "wechat": {"M": 4, "N": 3},
+    "xhs":    {"M": 4, "N": 1},
+}
+
+_DOCK_RETRIES = 2
+_DOCK_PRE_WAIT_S = 0.5
+
+
+def dock_app_icon_coords(
+    screen_w: int,
+    screen_h: int,
+    scale_w: float,
+    *,
+    app_name: str = "wechat",
+    M: int = 4,
+    N: int | None = None,
+) -> tuple[int, int]:
+    """Calculate the centre of the *N*-th Dock slot (1‑indexed) in a Dock with *M* equal-width slots.
+
+    - *M*: total number of Dock slots (default 4).
+    - *N*: 1‑based slot index; defaults from ``APP_DEFAULTS`` (wechat→3, xhs→1).
+    - Formula: ``x = round(W * (N - 0.5) / M)``.
+    """
+    if N is None:
+        defaults = APP_DEFAULTS.get(app_name, {})
+        N = defaults.get("N", 1)
+        M = defaults.get("M", M)
+    N = max(1, min(M, N))
+    pad_x = max(12, screen_w // 8)
+    dx = int(round(screen_w * (N - 0.5) / M))
+    dx = max(pad_x, min(screen_w - pad_x, dx))
+    dy = screen_h - max(48, int(round(52 * max(scale_w, 1e-6))))
+    return dx, dy
+
+
+def cold_start_app_from_launcher(
+    adb: AdbProtocol,
+    package: str,
+    *,
+    app_name: str = "wechat",
+    M: int = 4,
+    N: int | None = None,
+    session_tab_x: int | None = None,
+    session_tab_y: int | None = None,
+    force_stop_before: bool = True,
+    deadline_s: float = 25.0,
+) -> bool:
+    """Cold-start *package* from the Android launcher and optionally tap a session tab.
+
+    Screen dimensions are always auto‑detected via ``adb shell wm size``.
+
+    Args:
+        adb: :class:`AdbProtocol` client.
+        package: Android package name (e.g. ``"com.tencent.mm"``).
+        app_name: key in :data:`APP_DEFAULTS` — drives default *M* / *N*.
+        M: number of Dock slots.
+        N: 1‑based slot index where the app icon lives.
+        session_tab_x, session_tab_y: if both are non-``None``, tap this
+            coordinate after the app enters foreground (e.g. WeChat's
+            「微信」 bottom tab).
+        force_stop_before: issue ``am force-stop`` before cold-start.
+        deadline_s: maximum time budget for the whole cold-start.
+
+    Returns:
+        ``True`` if *package* is the foreground app after cold-start.
+    """
+    screen_w, screen_h = _resolve_screen_size(adb)
+    scale_w = screen_w / 1080.0
+    LOG.info("cold_start: screen %dx%d scale_w=%.3f", screen_w, screen_h, scale_w)
+
+    deadline = time.monotonic() + deadline_s
+
+    if force_stop_before:
+        LOG.info("cold_start: force-stop %s", package)
+        try:
+            adb._run(["shell", "am", "force-stop", package])
+        except Exception:
+            LOG.warning("cold_start: force-stop %s failed (non-fatal)", package)
+        time.sleep(0.65)
+
+    # -- path 1: monkey LAUNCHER --
+    if _try_monkey(adb, package):
+        time.sleep(1.5)
+        _tap_session_tab(adb, session_tab_x, session_tab_y)
+        if time.monotonic() < deadline and _check_foreground(adb, package):
+            return True
+
+    # -- path 2: am start Intent (backup for custom ROMs) --
+    if _try_am_start(adb, package):
+        time.sleep(1.5)
+        _tap_session_tab(adb, session_tab_x, session_tab_y)
+        if time.monotonic() < deadline and _check_foreground(adb, package):
+            return True
+
+    # -- path 3: Dock icon tap (last resort, with pre-wait + retry) --
+    dx, dy = dock_app_icon_coords(
+        screen_w, screen_h, scale_w, app_name=app_name, M=M, N=N,
+    )
+    if _try_dock_tap_with_retry(adb, package, dx, dy, session_tab_x, session_tab_y):
+        if time.monotonic() < deadline and _check_foreground(adb, package):
+            return True
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_screen_size(adb: AdbProtocol) -> tuple[int, int]:
+    out = adb._run(["shell", "wm", "size"])
+    m = _SZ_RE.search(out)
+    if m:
+        return int(m.group(1)), int(m.group(2))
+    return 1080, 1920
+
+
+def _try_monkey(adb: AdbProtocol, package: str) -> bool:
+    LOG.info("cold_start: monkey LAUNCHER for %s", package)
+    try:
+        adb._run(
+            ["shell", "monkey", "-p", package, "-c",
+             "android.intent.category.LAUNCHER", "1"],
+        )
+        return True
+    except Exception as exc:
+        LOG.warning("cold_start: monkey failed (%s)", exc)
+        return False
+
+
+def _try_am_start(adb: AdbProtocol, package: str) -> bool:
+    LOG.info("cold_start: am start LAUNCHER for %s", package)
+    try:
+        adb._run(
+            ["shell", "am", "start",
+             "-a", "android.intent.action.MAIN",
+             "-c", "android.intent.category.LAUNCHER",
+             package],
+        )
+        return True
+    except Exception as exc:
+        LOG.warning("cold_start: am start failed (%s)", exc)
+        return False
+
+
+def _tap_session_tab(
+    adb: AdbProtocol,
+    session_tab_x: int | None,
+    session_tab_y: int | None,
+) -> None:
+    if session_tab_x is not None and session_tab_y is not None:
+        LOG.info("cold_start: tap session tab (%d, %d)", session_tab_x, session_tab_y)
+        adb.tap(session_tab_x, session_tab_y)
+        time.sleep(0.55)
+
+
+def _try_dock_tap_with_retry(
+    adb: AdbProtocol,
+    package: str,
+    dx: int,
+    dy: int,
+    session_tab_x: int | None,
+    session_tab_y: int | None,
+) -> bool:
+    LOG.info("cold_start: Dock tap at (%d, %d) for %s (pre-wait %.1fs, max %d retries)",
+             dx, dy, package, _DOCK_PRE_WAIT_S, _DOCK_RETRIES)
+    for attempt in range(1 + _DOCK_RETRIES):
+        if attempt > 0:
+            time.sleep(_DOCK_PRE_WAIT_S)
+        adb.tap(dx, dy)
+        time.sleep(1.2)
+        _tap_session_tab(adb, session_tab_x, session_tab_y)
+        if _check_foreground(adb, package):
+            LOG.info("cold_start: Dock tap succeeded on attempt %d", attempt + 1)
+            return True
+        LOG.warning("cold_start: Dock tap attempt %d failed", attempt + 1)
+    return False
+
+
+def _check_foreground(adb: AdbProtocol, package: str) -> bool:
+    try:
+        return adb.foreground_package() == package
+    except Exception:
+        return False