# Android foreground-app automation condition — implementation notes

> Status: implemented on `feature/android-foreground-app-automation`. Last updated 2026-06-02.

## What & why

The desktop build has an **Application** automation rule (`ApplicationRule`): activate a scene
when given apps are running / foreground / fullscreen. It was already wired end-to-end on
Android (engine, storage, API, editor) but **silently never fired**, because the two
Windows-only ctypes paths return empty off-Windows:

1. **Detection** — `PlatformDetector._get_topmost_process_sync()` (and the running/fullscreen
   variants) returned `(None, False)` / `set()` on Android.
2. **The app picker** — populated from `GET /api/v1/system/processes` →
   `get_running_processes()`, also empty on Android, so users couldn't even choose an app.

This feature fills both holes using in-platform Android APIs and the established Kotlin↔Python
bridge pattern. **Zero new Python or Gradle dependencies.**

## Design decision: one implicit "foreground" mode on Android

Android exposes exactly one obtainable signal — the **current foreground app package**. The
desktop rule's four match types (`running` / `topmost` / `fullscreen` / `topmost_fullscreen`)
are either unobtainable (`running` — `getRunningTasks` is restricted) or identical (a foreground
TV app effectively *is* fullscreen). So on Android:

- The editor **hides the match-type selector** and the collector forces `match_type="topmost"`.
- `_get_topmost_process_sync()` returns `(package, True)`; the running/fullscreen detectors
  return the foreground app as a best-effort single-element set so legacy rules still behave.

This avoided touching the existing plain `<select>` (forbidden for new UI) and removed a
misleading 4-way choice — a simplification surfaced by the pre-implementation plan review.

## Detection — `ForegroundAppBridge` (Kotlin) ↔ `platform_detector.py`

`android/app/src/main/java/com/ledgrab/android/ForegroundAppBridge.kt` (an `object` singleton,
mirroring `CameraBridge`, context bound in `LedGrabApp.onCreate`):

- `getForegroundPackage()` — `UsageStatsManager.queryEvents(now - 10s, now)`, returns the package
  of the most recent `MOVE_TO_FOREGROUND` / `ACTIVITY_RESUMED` event (the two constants share a
  value; the ~10s window absorbs event lag against the ~1s automation tick). `queryEvents` is the
  right call — `queryUsageStats` gives aggregate durations, not "current app".
- `hasUsageAccess()` — `AppOpsManager` `OPSTR_GET_USAGE_STATS` check (`unsafeCheckOpNoThrow` on
  API 29+, `checkOpNoThrow` below).
- `listLaunchableApps()` — `LauncherApps.getActivityList` → JSON `[{package,label}]` for the
  picker. The sanctioned launchable-app API; **no `QUERY_ALL_PACKAGES`**.

`server/src/ledgrab/core/automations/platform_detector.py`:

- Module-level guarded wrappers `get_foreground_package()` / `has_usage_access()` /
  `list_installed_apps()` resolve `jclass("com.ledgrab.android.ForegroundAppBridge").INSTANCE`
  lazily (never at import — the module loads on desktop CI). These are the **test monkeypatch
  surface**, mirroring `android_camera_engine`.
- The `is_android()` branch is placed **ahead of** the import-time `if not _IS_WINDOWS:`
  early-return in each detector — the critical fix from plan review (a naive wiring would no-op
  behind the Windows guard yet still pass tests). The Windows ctypes path is unchanged
  (regression-tested).
- A one-time `logger.warning` fires when Usage Access is missing.

## App picker — `/system/installed-apps` + platform signal

- `GET /api/v1/system/installed-apps` → `{apps:[{package,label}], count}` (empty off-Android).
- `GET /api/v1/system/info` → `{is_android, app_match_kind, usage_access_granted}` — the editor
  reads it to pick the app source + matching semantics and to show the Usage-Access banner.
- Frontend: the command-palette picker (`core/process-picker.ts`) gained label→value support; a
  new `AppPalette` shows the human label and inserts the package name. On Android the app-rule
  editor uses it (`attachAppPicker`) instead of the process picker, plus a package-name hint and
  the Usage-Access banner.

## Value semantics (no migration)

`ApplicationRule.apps` are **package names** on Android (`com.netflix.mediaclient`) vs **process
names** on Windows (`chrome.exe`). Same field, same matching code — **no storage migration** —
but rules are **not portable across platforms**. Documented in the model/schema docstrings and a
user-facing editor hint.

## Permission UX

`PACKAGE_USAGE_STATS` is a special access (can't be granted at runtime):

- Manifest declares it with `tools:ignore="ProtectedPermissions"`.
- MainActivity shows a passive **"Grant usage access"** button (opens
  `ACTION_USAGE_ACCESS_SETTINGS`, with a generic-Settings fallback) only while access is missing.
  **No blanket prompt at capture start** — most users have no foreground-app rule.
- The web-UI rule editor shows a banner when an Android Application rule lacks access.

## Limitations

- Foreground-app only; no full window-title or arbitrary process enumeration on Android.
- Detection rides the existing ~1s automation poll; `queryEvents` can lag a few seconds.
- Rules authored on desktop don't match on Android and vice-versa (package vs process names).
- The on-device "Grant usage access" button currently shows whenever access is missing (not
  gated on whether an Android Application rule exists), to avoid Activity↔server coupling; the
  web-UI banner provides the contextual guidance.