argent-tv-interact

Name: argent-tv-interact
Author: software-mansion

1.8kstars51forks

How to install argent-tv-interact?

software-mansion/argent/argent-tv-interact

$npx -y skills add software-mansion/argent --skill argent-tv-interact

Installs into the current project.

Summary

Control and inspect TV apps via argent — Apple TV (tvOS), Android TV (leanback), and Amazon Fire TV (Vega). Boot the target, read focus, navigate with the D-pad remote, type, screenshot, and on Vega debug the JS runtime (evaluate, console logs, network inspector). Use when a task

Files · 1

View on GitHub

SKILL.md

1	# Argent TV (Apple TV + Android TV + Fire TV)
2
3	## Critical
4
5	- A TV is focus-driven, not touch-driven. Drive every interaction with `describe` + `tv-remote` + `keyboard`; never use `gesture-*` / coordinate taps — they don't apply on any TV platform.
6	- Always `describe` before navigating to find the live cursor and your target — never guess focus from a screenshot. The cursor is the focused element; on Vega the toolkit often leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor when nothing reports `[focused]`.
7	- Pass the `udid` from `list-devices` — an Apple TV simulator UDID or an Android TV / Vega `serial`. Dispatch is automatic from the id; the same tools drive all three.
8
9	## The navigation loop
10
11	1. `describe` — find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
12	2. `tv-remote` — move focus toward the target. Prefer one call with a path ending in `select`, e.g. `{button:["down","right","select"]}`; count rows/columns from the frames to build the path.
13	3. `describe` again to confirm. On a miss, repeat.
14
15	## Tools
16
17	- `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.
18	- `tv-remote {udid, button}` — D-pad / remote. `button` is one key or a whole path (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
19	- `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
20	- `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}` — `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.
21	- `screenshot {udid, scale?}` — Apple TV via `xcrun simctl io` (downscaled); Android TV / Vega host-side via `adb` / `screencap`.
22
23	## Per-platform
24
25	### Apple TV (tvOS simulator)
26
27	- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds). Give the RN bundle a few seconds to render before the first `describe`.
28	- Media-transport / volume keys are rejected — the sim's HID stack ignores them (they work on Android TV / Vega).
29	- Dev build: `open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}` (`<HOST_IP>` = your Mac's LAN IP, shown on the launcher).
30
31	### Android TV (leanback emulator)
32
33	- Boot the leanback AVD like any emulator — see `argent-android-emulator-setup`.
34	- `describe` may report zero focusables on a screen with visible tiles: many `react-native-tvos` screens use RN's own focus engine, invisible to the OS accessibility tree. `describe` auto-falls-back to the full UI tree (and says so in the hint); `tv-remote` still moves focus, so drive blind + `screenshot` to confirm.
35	- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back — Back exits the app).
36
37	### Fire TV (Vega / VVD)
38
39	- `list-devices` shows a `serial` (use as `udid`) and a `vvdImage`. `boot-device {vvdImage}` (e.g. `"tv"`) starts the single SDK-managed VVD; skip if one already runs.
40	- Stop the VVD with `vega virtual-device stop` in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via `boot-device`; to restart that one use `boot-device {vvdImage, force:true}` (stops then re-boots).
41	- Empty `describe` tree → `restart-app` (the automation toolkit attaches at launch), then retry. Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
42	- Editing `node_modules` has no effect on a Release build — only Debug `.vpkg` builds load patchable JS.
43	- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
44
45	## Common gotchas
46
47	- Empty focus right after `launch-app` / `restart-app` is the splash / loading window — `describe` retries int

People who liked this also viewed

6 picks

Type

argent-tv-interact

1.8kstars51forks

View on GitHub

How to install argent-tv-interact?

software-mansion/argent/argent-tv-interact

$npx -y skills add software-mansion/argent --skill argent-tv-interact

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Argent TV (Apple TV + Android TV + Fire TV)
2
3	## Critical
4
5	- A TV is focus-driven, not touch-driven. Drive every interaction with `describe` + `tv-remote` + `keyboard`; never use `gesture-*` / coordinate taps — they don't apply on any TV platform.
6	- Always `describe` before navigating to find the live cursor and your target — never guess focus from a screenshot. The cursor is the focused element; on Vega the toolkit often leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor when nothing reports `[focused]`.
7	- Pass the `udid` from `list-devices` — an Apple TV simulator UDID or an Android TV / Vega `serial`. Dispatch is automatic from the id; the same tools drive all three.
8
9	## The navigation loop
10
11	1. `describe` — find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
12	2. `tv-remote` — move focus toward the target. Prefer one call with a path ending in `select`, e.g. `{button:["down","right","select"]}`; count rows/columns from the frames to build the path.
13	3. `describe` again to confirm. On a miss, repeat.
14
15	## Tools
16
17	- `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.
18	- `tv-remote {udid, button}` — D-pad / remote. `button` is one key or a whole path (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
19	- `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
20	- `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}` — `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.
21	- `screenshot {udid, scale?}` — Apple TV via `xcrun simctl io` (downscaled); Android TV / Vega host-side via `adb` / `screencap`.
22
23	## Per-platform
24
25	### Apple TV (tvOS simulator)
26
27	- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds). Give the RN bundle a few seconds to render before the first `describe`.
28	- Media-transport / volume keys are rejected — the sim's HID stack ignores them (they work on Android TV / Vega).
29	- Dev build: `open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}` (`<HOST_IP>` = your Mac's LAN IP, shown on the launcher).
30
31	### Android TV (leanback emulator)
32
33	- Boot the leanback AVD like any emulator — see `argent-android-emulator-setup`.
34	- `describe` may report zero focusables on a screen with visible tiles: many `react-native-tvos` screens use RN's own focus engine, invisible to the OS accessibility tree. `describe` auto-falls-back to the full UI tree (and says so in the hint); `tv-remote` still moves focus, so drive blind + `screenshot` to confirm.
35	- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back — Back exits the app).
36
37	### Fire TV (Vega / VVD)
38
39	- `list-devices` shows a `serial` (use as `udid`) and a `vvdImage`. `boot-device {vvdImage}` (e.g. `"tv"`) starts the single SDK-managed VVD; skip if one already runs.
40	- Stop the VVD with `vega virtual-device stop` in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via `boot-device`; to restart that one use `boot-device {vvdImage, force:true}` (stops then re-boots).
41	- Empty `describe` tree → `restart-app` (the automation toolkit attaches at launch), then retry. Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
42	- Editing `node_modules` has no effect on a Release build — only Debug `.vpkg` builds load patchable JS.
43	- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
44
45	## Common gotchas
46
47	- Empty focus right after `launch-app` / `restart-app` is the splash / loading window — `describe` retries int

People who liked this also viewed

6 picks

Type