references/vega.md
# Fire TV (Vega / VVD)
Everything in the related SKILL.md still applies; this page covers what is Vega-only.
## Device
- Use the `serial` from `list-devices` as `udid`; start a stopped VVD with `boot-device {vvdImage}`.
- **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).
- Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
- Editing `node_modules` has no effect on a Release build; only Debug `.vpkg` builds load patchable JS.
- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
- `keyboard` named `key` presses (e.g. `{key:"enter"}`) work on Vega, unlike Apple TV / Android TV.
- `reinstall-app` takes a `.vpkg` as `appPath`.
## Fast Refresh
Build and install a Debug `.vpkg` (`vega device install-app -p <path>`), `npm start`, `vega device start-port-forwarding --port 8081 --forward false`, then `vega device launch-app -a <appId>`. Confirm `http://localhost:8081/json/list` shows a `Hermes React Native` target; `.tsx` edits then hot-reload.
## Debugging the JS runtime
Once that same Debug build + Metro setup is in place, the JS-runtime tools work on a Vega VVD: `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry` (console logs), `view-network-logs`, and `view-network-request-details`. Verify with `debugger-status`. Vega-specific: on `no_app_connected`, check `vega device start-port-forwarding` **before** relaunching the app: a down device→host forward is the usual cause, and the generic guidance can't know about it. See the `argent-metro-debugger` skill.
Vega's React Native forks RN 0.72 and serves the legacy Hermes inspector, so `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are **not supported**. Component-tree and inspect-element are hard-blocked: they need `Runtime.addBinding`, which this Hermes acknowledges but never installs. The rest are simply unverified on the legacy inspector. Use `describe` for on-screen structure; with both component tools gated off, component `file:line` tracing has no path on Vega. `isNewDebugger: false` and an empty `projectRoot` are expected there.
SKILL.md
---
name: argent-tv-interact
description: 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 targets a TV (runtimeKind "tv", or platform "vega"), or mentions Apple TV / tvOS / Android TV / leanback / Vega / Fire TV / VVD.
---
# Argent TV (Apple TV + Android TV + Fire TV)
## Critical
- 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.
- **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]`.
- 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.
- **E2E tests: Vega only.** Apple TV and Android TV have no e2e support (a `tap:` can pass without doing anything): report that limitation.
- **Fire TV (Vega)** (`platform: "vega"` in `list-devices`): read `references/vega.md` before driving it. It covers booting and stopping the VVD, Fast Refresh, and debugging the JS runtime.
## The navigation loop
1. `describe`: find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
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.
3. `describe` again to confirm. On a miss, repeat.
## Tools
`describe`, `tv-remote` and `keyboard` descriptions cover the TV behaviour (focus view, remote keys and paths, text-only typing). Beyond them:
- `launch-app` / `restart-app` / `reinstall-app` take the `bundleId` from the app manifest.
## Per-platform
### Apple TV (tvOS simulator)
- 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).
- 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).
### Android TV (leanback emulator)
- Boot the leanback AVD like any emulator; see `argent-android-emulator-setup`.
- Dev build: `open-url` `<scheme>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081` (`<scheme>`: the app's URL scheme, or its package name if it sets none), then dismiss the first dev menu with `tv-remote` `select` (not `back`: it exits the app).
## Fast Refresh (dev builds)
Needs a Debug build + Metro running. argent only _connects_ to Metro: start Metro yourself, and forward the port where the app needs it (Android: `argent-metro-debugger` §1; Vega: `references/vega.md`).
- **Apple TV / Android TV:** use the dev-build deep-links above; `npm start` for Metro.
- **Vega:** see `references/vega.md`.