feat(android): detect Fire OS devices as Android TV targets and document Fire TV support

Merged
TH
2d ago
+277-71

Summary

Fire TV devices running Fire OS are Android-based and automate over ADB, but the docs framed TV support as Android TV / tvOS / Vega VVD only, and TV detection missed them: detection read only the AOSP leanback/television features, while Fire OS declares amazon.hardware.fire_tv (Amazon, "Identify Fire TV Devices") and may declare no leanback feature. App launch and listing on a TV target queried LEANBACK_LAUNCHER only, while Fire OS apps can register under either launcher category.

  • launcher-categories.ts (new): one shared TV/mobile launcher-category resolver; app-lifecycle.ts and app-helpers.ts both read launch, fallback, and listing categories from it. TV listing is the union of LEANBACK_LAUNCHER and LAUNCHER; launch prefers LEANBACK_LAUNCHER and falls back to LAUNCHER, launching under the category the component resolved under.
  • inventory.ts: amazon.hardware.fire_tv counts as a TV feature signal, so a Fire TV is discovered with target=tv.
  • Docs + versioned help tv: Fire TV (Fire OS) = Android TV backend over ADB (adb connect <ip>:5555, ADB debugging); Vega OS remains a different, VVD-only OS. Docs state only the Android 6.0 (API 23) helper requirement; no per-command enumeration beyond what the Android TV backend runs.
  • Electron/Chromium macOS docs moved to #3932.
adb connect 192.168.1.20:5555
agent-device open com.example.app --platform android --target tv
agent-device tv-remote press down --platform android --target tv

Validation

  • Head df2f9120ce66426d384a228b4cb813f7b68fe67a: rebased onto main after #3933 (coverage timeout fix) and #3932 (Electron docs) merged; conflicts resolved by keeping main's Electron sentences and only adding the Fire OS wording, so no Electron text is re-added or duplicated. The one post-467e134 change is the review's single-spelling note: androidLaunchCategory now returns androidLauncherCategories(target)[0]!. pnpm check:affected --run --head df2f9120ce66426d384a228b4cb813f7b68fe67a: all runnable checks passed, exactCommit=true (receipt .tmp/validation/run-05ZPGb/receipt.json).
  • Head 467e13402ed220e58fdac45d42a53f179a7f1303 adds only the review's naming/dedup/assertion refactor in launcher-categories.ts/app-lifecycle.ts/app-helpers.ts; the emitted adb argv is byte-identical to the bbcc604 runs quoted below (the argv unit tests re-ran green at the new head). pnpm check:affected --run --head 467e13402ed220e58fdac45d42a53f179a7f1303: all runnable checks passed, exactCommit=true (receipt .tmp/validation/run-VsQOlP/receipt.json). Unit tests: Fire OS detection on the pm list features path and the cmd package has-feature path (device that fails ro.build.characteristics, answers no AOSP leanback/television feature, and answers amazon.hardware.fire_tv true — decided tv before the feature-list probe, asserted); TV fallback argv; TV listing queries both categories on the daemon and executor-helper paths. Each new production behavior fails on base for the intended reason.
  • Live, at head bbcc604599, on emulators created for this run: Android TV fireos_docs_tv (android-tv API 34, arm64, emulator-5554) and phone fireos_docs_phone (google_apis API 35, emulator-5556), both removed after. Two purpose-built APKs installed: com.example.fireosdocs (LAUNCHER-only activity) and com.example.fireosdocslb (LEANBACK_LAUNCHER-only). adb argv captured with a forwarding wrapper that logs each invocation, then execs the real platform-tools 37.0.1 adb; CLI built from the head sha.

1. apps --target tv lists the LAUNCHER-only package next to the leanback app:

$ agent-device apps --platform android --target tv --serial emulator-5554 --session head-tv
Fireosdocs (com.example.fireosdocs)
Fireosdocslb (com.example.fireosdocslb)

wrapper log — both category queries ran:

adb -s emulator-5554 shell cmd package query-activities --brief -a android.intent.action.MAIN -c android.intent.category.LEANBACK_LAUNCHER
adb -s emulator-5554 shell cmd package query-activities --brief -a android.intent.action.MAIN -c android.intent.category.LAUNCHER

2. open com.example.fireosdocs --target tv runs the fallback and the app resumes:

$ agent-device open com.example.fireosdocs --platform android --target tv --serial emulator-5554 --session head-tv
Opened: com.example.fireosdocs

wrapper log — primary -c LEANBACK_LAUNCHER -p start (which fails on the device with raw adb's Error: Activity not started, unable to resolve Intent { ... cat=[android.intent.category.LEANBACK_LAUNCHER,android.intent.category.DEFAULT] ... pkg=com.example.fireosdocs }), then resolve-activity for LEANBACK_LAUNCHER (misses), then resolve-activity for LAUNCHER (resolves), then the second am start -n with -c LAUNCHER:

adb -s emulator-5554 shell am start -W -a android.intent.action.MAIN -c android.intent.category.DEFAULT -c android.intent.category.LEANBACK_LAUNCHER -p com.example.fireosdocs
adb -s emulator-5554 shell cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.LEANBACK_LAUNCHER com.example.fireosdocs
adb -s emulator-5554 shell cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.LAUNCHER com.example.fireosdocs
adb -s emulator-5554 shell am start -W -a android.intent.action.MAIN -c android.intent.category.DEFAULT -c android.intent.category.LAUNCHER -n com.example.fireosdocs/.LauncherActivity

$ agent-device appstate --platform android --target tv --serial emulator-5554 --session head-tv
Foreground app: com.example.fireosdocs
Activity: com.example.fireosdocs.LauncherActivity

3. Mobile-target open on the phone emulator still runs one am start -c LAUNCHER (zero LEANBACK occurrences in the whole request log):

$ agent-device open com.example.fireosdocs --platform android --target mobile --serial emulator-5556 --session head-phone
Opened: com.example.fireosdocs

adb -s emulator-5556 shell am start -W -a android.intent.action.MAIN -c android.intent.category.DEFAULT -c android.intent.category.LAUNCHER -p com.example.fireosdocs
  • Earlier live run at e9250ed (pre-amend): devices target=tv, snapshot -i on the helper backend (helperVersion 0.21.32-dev), tv-remote down/select/volume-down/home/back/android-keycode, screenshot 1920x1080, logs, network dump, is visible/is focused selectors, close.
  • Not tested: Fire OS hardware — no Fire TV device available. Detection of amazon.hardware.fire_tv rests on unit tests against the documented feature format plus the live Android TV runs above, not on Fire TV firmware.
  • CI owns coverage, device lanes, and integration.

🤖 Generated with Claude Code