argent-tv-interact

Argent TV（Apple TV + Android TV + Fire TV）

重要

• テレビはタッチ操作ではなく、フォーカス操作が中心です。 すべての操作で describe + tv-remote + keyboard を使用してください。gesture-* や座標を指定したタップは使用しないでください。どのテレビプラットフォームでも使えません。
• 移動する前に必ず describe を実行し、現在のカーソルと目的の項目を確認してください。スクリーンショットからフォーカスを推測してはいけません。カーソルはフォーカス中の要素です。Vega では、ツールが focused を false のままにし、ハイライトされた項目に [selected] を付けることがよくあります。そのため、[focused] が報告されない場合は [selected] をカーソルとして扱ってください。
• list-devices の udid を渡してください。これは Apple TV シミュレーターの UDID、または Android TV / Vega の serial です。ID に応じて自動的に振り分けられるため、同じツールで3つすべてを操作できます。

ナビゲーションのループ

1. describe：カーソルと目的の項目を確認します（フォーカス中の要素と、タップツリーではなく、フォーカス可能な要素をすべて返します）。
2. tv-remote：目的の項目へ向けてフォーカスを移動します。select で終わるパスを指定した1回の呼び出しを優先してください。例：{button:["down","right","select"]}。フレームから行数／列数を数えてパスを作成します。
3. 再度 describe を実行して確認します。目的の項目に移動できなかった場合は、繰り返します。

ツール

• describe {udid}：フォーカス表示。フォーカス中／[selected] の要素と、ラベルおよび正規化されたフレームを含むフォーカス可能な要素を返します。移動の前後に呼び出してください。ツリーが空の場合は、プラットフォームごとの注意事項を確認してください。
• tv-remote {udid, button}：十字キー／リモコン。button には1つのキー、またはパス全体を指定します（1回の呼び出しで実行）。キー：up／down／left／right、select、back、menu、home、playPause、およびメディアキー rewind／fastForward／next／previous／volumeUp／volumeDown／mute。単一キー：{button:"down"}、繰り返し：{button:"down", repeat:3}、パス：{button:["up","right","select"]}。
• keyboard {udid, text}：フォーカス中のフィールドに入力します（先に tv-remote でフォーカスしてください）。1回の呼び出しでは text または key のどちらか一方だけを指定します。入力後にキーを押すには、1つの run-sequence で keyboard を2ステップ送信してください。名前付きの key によるキー入力（例：{key:"enter"}）は Vega で機能します。Apple TV / Android TV では、代わりに tv-remote でフォーカスを移動してください。
• launch-app / restart-app / reinstall-app {udid, bundleId}：アプリのマニフェストに記載された bundleId を指定します。Vega の reinstall-app では appPath に .vpkg を指定します。
• screenshot {udid, scale?}：Apple TV では xcrun simctl io 経由で取得します（縮小されます）。Android TV / Vega ではホスト側から adb / screencap 経由で取得します。

プラットフォームごとの注意事項

Apple TV（tvOS シミュレーター）

• ほかの iOS シミュレーターと同様に起動します（boot-device）。AX + HID デーモンは、最初の describe / tv-remote で自動的に起動します（初回の呼び出しには数秒かかる場合があります）。最初の describe を実行する前に、RN バンドルの描画が完了するまで数秒待ってください。
• メディア操作／音量キーは拒否されます。シミュレーターの HID スタックがこれらのキーを無視するためです（Android TV / Vega では機能します）。
• 開発ビルド：open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}（<HOST_IP> は Mac の LAN IP で、ランチャーに表示されます）。

Android TV（leanback エミュレーター）

• leanback AVD は通常のエミュレーターと同様に起動します。argent-android-emulator-setup を参照してください。
• タイルが表示されている画面でも、describe がフォーカス可能な要素を0個と報告することがあります。多くの react-native-tvos 画面では、OS のアクセシビリティツリーから見えない RN 独自のフォーカスエンジンを使用しています。describe は自動的に UI ツリー全体へフォールバックし、その旨をヒントに表示します。tv-remote でフォーカスは引き続き移動できるため、画面を見ずに操作し、screenshot で確認してください。
• 開発ビルド：adb -s <serial> reverse tcp:8081 tcp:8081 を実行し、<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081 にディープリンクします。最初の開発メニューは adb shell input keyevent KEYCODE_DPAD_CENTER で閉じてください（Back を押すとアプリが終了します）。

Fire TV（Vega / VVD）

• list-devices には serial（udid として使用）と vvdImage が表示されます。boot-device {vvdImage}（例："tv"）を実行すると、SDK 管理の VVD が 1 台起動します。すでに起動している場合はスキップしてください。
• シェルで vega virtual-device stop を実行して、VVD を停止します。CLI が追跡するのはフォアグラウンドで起動した VVD のみのため、boot-device で起動した VVD に対して「not running」と報告することがあります。その VVD を再起動するには、boot-device {vvdImage, force:true} を使用します（停止後に再起動します）。
• describe のツリーが空の場合は、restart-app を実行してから再試行してください（自動化ツールキットは起動時にアタッチされます）。入力が無視される場合は、VVD で開発者モードを有効にします：vsm developer-mode enable。
• node_modules を編集しても Release ビルドには反映されません。パッチ可能な JS を読み込むのは Debug .vpkg ビルドのみです。
• プロファイリング／クラッシュには、amazon-devices-buildertools-mcp サーバー（analyze_perfetto_traces、get_app_hot_functions、symbolicate_acr）を使用します。ドキュメントはその search_documentation ツールで確認できます。

よくある注意点

• launch-app／restart-app の直後にフォーカスが空になる場合は、スプラッシュ画面／読み込みウィンドウが表示されています。describe は内部で再試行します。コールドスタート時は約 2～3 秒待ってから再試行してください。
• スマートフォン／タブレット（runtimeKind: "mobile"）の udid を tv-remote に渡すと、「tvOS-only」／「Android-TV-only」という明確なエラーが発生します。list-devices から TV のターゲットを選択してください。

Fast Refresh（開発ビルド）

Debug ビルドと Metro の実行が必要です。argent は Metro に_接続するだけ_なので、Metro の起動とポートフォワーディングはご自身で行ってください（プラットフォームは問いません）。Metro のポートは :8081 に固定されています。

• Apple TV / Android TV： 上記の開発ビルド用ディープリンクを使用し、Metro を起動するには npm start を実行します。
• Vega： Debug .vpkg をビルド／インストールし（vega device install-app -p <path>）、npm start を実行します。続けて vega device start-port-forwarding --port 8081 --forward false を実行し、その後 vega device launch-app -a <appId> を実行します。http://localhost:8081/json/list に Hermes React Native ターゲットが表示されることを確認してください。その後、.tsx の編集がホットリロードされます。

JS ランタイムのデバッグ（Vega）

同じ Debug ビルドと Metro のセットアップが整っていれば、Vega VVD で JS ランタイムツール（debugger-connect、debugger-status、debugger-evaluate、debugger-log-registry（コンソールログ）、view-network-logs、view-network-request-details）を使用できます。debugger-status で確認してください。未接続でもエラーではなくステータス結果が返ります。status: "connected" はセットアップが機能していることを意味し、status: "not_connected" には reason と guidance が含まれます（例：metro_not_running → Metro 自体が起動していません）。Vega 固有の注意点：no_app_connected の場合は、アプリを再起動する前に vega device start-port-forwarding を確認してください。デバイスからホストへの転送が停止していることが通常の原因ですが、一般的なガイダンスではこの問題を把握できません。argent-metro-debugger スキルを参照してください。

Vega の React Native は RN 0.72 をフォークしており、レガシー Hermes インスペクターを提供するため、iOS／Android とは次の 3 点が異なります。

• debugger-component-tree、debugger-inspect-element、debugger-reload-metro、および react-profiler-*／profiler-* ツールはサポートされていません。コンポーネントツリーと要素検査はハードブロックされています。これらには Runtime.addBinding が必要ですが、この Hermes はその存在を認識するものの、インストールしません。残りのツールはレガシーインスペクターで検証されていないだけです。画面上の構造を確認するには describe を使用してください。両方のコンポーネントツールが無効になっているため、Vega ではコンポーネントの file:line をたどる方法はありません。
• debugger-status は isNewDebugger: false を報告します。
• projectRoot は空です（RN 0.72 の Metro はプロジェクトルートのヘッダーを送信しません）。そのため、プロジェクトルートを基準にパスを解決する検索では場所が返されません。