Files
software-mansion__argent/.github/workflows/build-package-artifact.yml
Mateusz Ścianek b8afbed183 feat(tv): Apple TV (tvOS) and Android TV support (#374)
Adds end-to-end support for driving **Apple TV (tvOS)** and **Android TV
(leanback)** targets through argent, using a focus-driven interaction
model (TVs have no touchscreen — interaction is moving a focus highlight
with the remote).

This PR was reworked after review to **reuse the existing cross-platform
tool surface and the `tv-remote` tool from the Vega/Fire TV work
(#366)** rather than ship a separate family of `tv-*` tools.

## What this delivers

TV targets are driven by the **same cross-platform tools as every other
platform**, routed through the existing `dispatchByPlatform` fork
mechanism — there are no dedicated
`tv-describe`/`tv-navigate`/`tv-type`/`tv-set-focus` tools:

- **`describe`** — on a `runtimeKind: "tv"` target, returns the
focus-driven view (focused + focusable elements) instead of a tap tree.
On Android TV it auto-falls-back to the full `uiautomator` tree when the
RN focus engine exposes nothing.
- **`tv-remote`** — the cross-platform remote/D-pad tool from #366, now
extended with `ios` (Apple TV HID daemon) and `android` (Android TV adb
keyevents) branches alongside the existing `vega` branch. Single button,
a `repeat`, or a whole path (`["up","right","select"]`) in one call.
- **`keyboard`** — types into the focused field on a TV target (named
keys are rejected there — they're navigation, which belongs to
`tv-remote`).
- **`button`** stays hardware-only (phones/tablets); it is not a TV
tool.

**Apple TV** runs two native daemons (in-sim AX service + host-side HID
daemon), shipped via the `argent-private` submodule. **Android TV**
reuses the same tool surface, adb-backed (`input keyevent`, `uiautomator
dump`, `input text`).

## Remote vocabulary parity

`tv-remote` exposes the full 16-button vocabulary
(`up`/`down`/`left`/`right`/`select`/`back`/`home`/`menu`/`playPause`/`rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`):

| | Apple TV | Android TV | Vega |
|---|---|---|---|
| D-pad / select / back / menu / home / playPause | ✅ | ✅ | ✅ |
| media-transport + volume/mute | ❌ rejected | ✅ | ✅ |

Media-transport/volume keys **genuinely work on Android TV** (real
keycodes — verified live: `volumeUp` moved `STREAM_MUSIC`, `mute`
toggled per `dumpsys audio`). On the **Apple TV simulator** they are
**rejected with a clear error**: on-device testing confirmed the tvOS
sim's HID stack silently drops Consumer-Control events, so returning
success would be a lie.

## Key design points
- **tvOS UDIDs are UUID-shaped and indistinguishable from iOS by
shape.** Handled with `runtimeKind` detection (tvOS runtime string for
Apple TV; `pm list features` leanback/television for Android TV — *not*
`ro.build.characteristics`, which lies on TV emulators).
- Converted launch-app / restart-app / screenshot / screenshot-diff /
run-sequence from **eager** to **lazy** service resolution, so a tvOS
target never spins up (and hangs on) the iOS-only simulator-server /
native-devtools blueprints.
- Native injection selects the platform-matched (TVOSSIMULATOR) dylib
slice; daemons recycle across sim reboots and app relaunches so
injection and focus survive.
- SKILL.md footprint minimized per review: the two TV skills were
collapsed into a single lean **`argent-tv-interact`** (~40 lines).

## Verification
- `npm run build`, ESLint, Prettier, and the full tool-server suite
(**1565 tests**) all pass; CI green (incl. the Apple TV / Android TV /
Vega e2e jobs).
- Core flows verified live against real apps on both an Apple TV 4K
simulator and a Google ATV emulator.

## Dependency / merge order
Pins the `argent-private` submodule to the tip of its `feat/tv-support`
branch (software-mansion/argent-private#20). **Merge that PR to `main`
first, then bump the submodule pointer here to the merged SHA before
merging this PR.**

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 14:59:37 +02:00

98 lines
3.8 KiB
YAML

name: Build npm package artifact
on:
workflow_dispatch:
jobs:
build-package:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
ref: main
- uses: actions/setup-node@v6
with:
node-version: "24"
registry-url: "https://registry.npmjs.org"
scope: "@swmansion"
- name: Download signed simulator-server binary
run: bash scripts/download-simulator-server.sh
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Download signed native binaries (dylibs, ax-service, Android helper APK)
run: bash scripts/download-native-binaries.sh
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Download Perfetto trace-processor WASM artifacts
run: bash scripts/download-trace-processor.sh
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: npm ci
- run: npx tsc --build
- run: npm run build -w @swmansion/argent
# Keep the artifact build checks aligned with the publish workflow so the
# uploaded tarball has the same required runtime assets as an npm release.
- name: Verify per-platform simulator-server binaries
env:
ARGENT_REQUIRE_LINUX_BINARY: "0"
run: |
set -e
missing=0
echo "simulator-server inventory:"
for plat in darwin linux linux-arm64; do
p="packages/argent/bin/${plat}/simulator-server"
if [[ -x "$p" ]]; then
size=$(wc -c <"$p")
echo " ok ${plat}: ${p} (${size} bytes; $(file -b "$p"))"
else
echo " missing ${plat}: ${p}"
if [[ "$plat" == "darwin" ]]; then missing=1; fi
if [[ "$plat" == linux* && "${ARGENT_REQUIRE_LINUX_BINARY}" == "1" ]]; then missing=1; fi
fi
done
[[ "$missing" == "0" ]] || { echo "::error::required simulator-server binary missing"; exit 1; }
- run: test -x packages/argent/bin/darwin/ax-service
- run: test -f packages/argent/dylibs/libNativeDevtoolsIos.dylib
- run: test -f packages/argent/dylibs/libKeyboardPatch.dylib
- run: test -f packages/argent/dylibs/libArgentInjectionBootstrap.dylib
# tvOS (Apple TV) binaries — fail the build if any is missing rather
# than silently shipping a package where tv-* tools crash at runtime.
- run: test -x packages/argent/bin/darwin/tvos-ax-service
- run: test -x packages/argent/bin/darwin/tvos-hid-daemon
- run: test -f packages/argent/dylibs/tvos/libNativeDevtoolsIos.dylib
- run: test -f packages/argent/dylibs/tvos/libKeyboardPatch.dylib
- run: test -f packages/argent/dylibs/tvos/libArgentInjectionBootstrap.dylib
- run: test -f packages/argent/assets/argent.tracecfg.pbtxt
- run: test -d packages/argent/assets/queries
- run: test -f packages/argent/assets/manifest.json
- run: test -f packages/argent/assets/trace-processor/trace_processor.wasm
- run: test -f packages/argent/assets/trace-processor/engine_bundle.node.js
- run: test -f packages/argent/assets/trace-processor/engine.mjs
- run: test -f packages/argent/assets/trace-processor/LICENSE
- run: head -c4 packages/argent/assets/trace-processor/trace_processor.wasm | grep -q $'\x00asm'
- run: ls packages/argent/bin/argent-android-devtools-*.apk
- name: Pack npm package
run: |
mkdir -p package-artifact
npm pack -w @swmansion/argent --pack-destination package-artifact
- name: Upload npm package artifact
uses: actions/upload-artifact@v7
with:
name: argent-main-npm-package
path: package-artifact/*.tgz
if-no-files-found: error
retention-days: 14