portholejs 0.1.1 → 0.2.0

package/README.md

@@ -65,6 +65,7 @@ in sync (see `src/engine/scrcpy-engine.ts`).
 
 ```sh
 npx portholejs start Pixel_8_Pro_API_34
+npx portholejs start Pixel_8_Pro_API_34 Television_1080p_API_34
 ```
 
 For a headless agent workflow:
@@ -76,54 +77,82 @@ npx portholejs screenshot -q
 npx portholejs kill -q
 ```
 
+## Things to try
+
+Test a TV app **without touching a remote**: `porthole focus-on "Library"
+--select` walks the D-pad focus to any element by its text and presses OK —
+then `porthole focused -q` tells you exactly where leanback focus landed, as
+JSON. Record a bug repro as a real video with
+`porthole record repro.mp4 --duration 30s` while you swipe, scroll, and
+long-press the phone from the CLI (`porthole scroll down`,
+`porthole swipe 0.5 0.05 0.5 0.7` opens the notification shade). Catch visual
+regressions in one line: save a baseline with `porthole screenshot -o good.png`,
+then `porthole assert-screen good.png --threshold 0.02` exits non-zero and
+writes a diff image the moment the screen drifts. Stream a **phone and a TV
+side by side** from one command — `porthole start Pixel_8 Tv_1080p` puts both
+in the same browser tab with a device picker. And the whole loop works with no
+human at all: add the MCP server to Claude Code (below) and ask it to _"open
+my app on the TV emulator, navigate to Settings, and check nothing crashed"_ —
+it will drive the D-pad, read the UI as JSON (`dump_ui`), and pull
+`get_crashes` on its own. If anything misbehaves, `porthole doctor` diagnoses
+your setup in seconds.
+
 ## CLI Reference
 
-| Command                             | Purpose                                             |
-| ----------------------------------- | --------------------------------------------------- |
-| `porthole start [avd]`              | Boot or attach and serve the browser preview        |
-| `porthole list`                     | List AVDs, running emulators, and known sessions    |
-| `porthole kill [avd]`               | Stop emulators Porthole booted and detached servers |
-| `porthole tap <x> <y>`              | Touch normalized phone coordinates from `0..1`      |
-| `porthole key <keycode>`            | Send an Android keycode down/up pair                |
-| `porthole remote <button>`          | Press a TV D-pad/media button                       |
-| `porthole text "<string>"`          | Type text into the active session                   |
-| `porthole screenshot [-o file.png]` | Save a PNG screenshot                               |
-| `porthole focused`                  | Print the currently focused UI node                 |
-| `porthole dump-ui [--filter text]`  | Dump the Android UI hierarchy                       |
-| `porthole wait-for <text>`          | Wait until UI text appears                          |
-| `porthole open-url <url>`           | Open a URL or Android deep link                     |
-| `porthole stop-app <package>`       | Force-stop an app                                   |
-| `porthole clear-app <package>`      | Clear app data                                      |
-| `porthole rotate <orientation>`     | Rotate a phone emulator                             |
-| `porthole emu <args...>`            | Pass through to `adb emu`                           |
-| `porthole doctor`                   | Diagnose Node/SDK/adb/AVD/session problems          |
-| `porthole mcp`                      | Run the MCP server over stdio                       |
+| Command                              | Purpose                                             |
+| ------------------------------------ | --------------------------------------------------- |
+| `porthole start [avd...]`            | Boot or attach one or more emulators and serve them |
+| `porthole list`                      | List AVDs, running emulators, and known sessions    |
+| `porthole kill [avd]`                | Stop emulators Porthole booted and detached servers |
+| `porthole tap <x> <y>`               | Touch normalized phone coordinates from `0..1`      |
+| `porthole swipe <x1> <y1> <x2> <y2>` | Swipe between normalized phone coordinates          |
+| `porthole longpress <x> <y>`         | Long-press normalized phone coordinates             |
+| `porthole scroll <direction>`        | Scroll phone content up, down, left, or right       |
+| `porthole key <keycode>`             | Send an Android keycode down/up pair                |
+| `porthole remote <button>`           | Press a TV D-pad/media button                       |
+| `porthole text "<string>"`           | Type text into the active session                   |
+| `porthole screenshot [-o file.png]`  | Save a PNG screenshot                               |
+| `porthole assert-screen <png>`       | Compare the current screen with a PNG baseline      |
+| `porthole record <out.mp4>`          | Record the current H.264 stream to MP4              |
+| `porthole focused`                   | Print the currently focused UI node                 |
+| `porthole focus-on <text>`           | Move TV D-pad focus to matching text                |
+| `porthole dump-ui [--filter text]`   | Dump the Android UI hierarchy                       |
+| `porthole wait-for <text>`           | Wait until UI text appears                          |
+| `porthole open-url <url>`            | Open a URL or Android deep link                     |
+| `porthole stop-app <package>`        | Force-stop an app                                   |
+| `porthole clear-app <package>`       | Clear app data                                      |
+| `porthole rotate <orientation>`      | Rotate a phone emulator                             |
+| `porthole emu <args...>`             | Pass through to `adb emu`                           |
+| `porthole doctor`                    | Diagnose Node/SDK/adb/AVD/session problems          |
+| `porthole mcp`                       | Run the MCP server over stdio                       |
 
 Common options:
 
-| Option                  | Meaning                                          |
-| ----------------------- | ------------------------------------------------ |
-| `-p, --port <port>`     | Preview/control port, default `3200`             |
-| `-d, --device <serial>` | Attach to a running emulator serial              |
-| `--host <host>`         | Bind address, default `127.0.0.1`                |
-| `--no-preview`          | Do not open the browser automatically            |
-| `--detach`              | Start the preview server in the background       |
-| `--mjpeg`               | Force MJPEG screenshot polling                   |
-| `-q, --quiet`           | Emit one JSON object/array on stdout             |
-| `--max-size <px>`       | Maximum scrcpy stream dimension                  |
-| `--max-fps <fps>`       | Maximum scrcpy FPS                               |
-| `--bitrate <bps>`       | Scrcpy video bitrate                             |
-| `--wipe-data`           | Wipe emulator data before boot                   |
-| `--no-snapshot`         | Disable loading/saving emulator snapshots        |
-| `--cold-boot`           | Alias for `--no-snapshot`                        |
-| `--gpu <mode>`          | Pass emulator GPU mode                           |
-| `--keep-alive`          | Leave a Porthole-booted emulator running on exit |
+| Option                  | Meaning                                                 |
+| ----------------------- | ------------------------------------------------------- |
+| `-p, --port <port>`     | Preview/control port, default `3200`                    |
+| `-d, --device <serial>` | Target a running emulator serial; comma-list on `start` |
+| `--host <host>`         | Bind address, default `127.0.0.1`                       |
+| `--no-preview`          | Do not open the browser automatically                   |
+| `--detach`              | Start the preview server in the background              |
+| `--mjpeg`               | Force MJPEG screenshot polling                          |
+| `-q, --quiet`           | Emit one JSON object/array on stdout                    |
+| `--max-size <px>`       | Maximum scrcpy stream dimension                         |
+| `--max-fps <fps>`       | Maximum scrcpy FPS                                      |
+| `--bitrate <bps>`       | Scrcpy video bitrate                                    |
+| `--wipe-data`           | Wipe emulator data before boot                          |
+| `--no-snapshot`         | Disable loading/saving emulator snapshots               |
+| `--cold-boot`           | Alias for `--no-snapshot`                               |
+| `--gpu <mode>`          | Pass emulator GPU mode                                  |
+| `--keep-alive`          | Leave a Porthole-booted emulator running on exit        |
 
 Quiet schemas are intentionally simple: `list -q` returns
-`{ "devices": [...], "sessions": [...] }`; `start --detach -q` returns the
-session record with `url`, `pid`, `serial`, `avdName`, `port`, and `profile`;
-input commands return `{ "ok": true, "session": ... }`; `screenshot -q` returns
-`{ "ok": true, "path": "...", "session": ... }`.
+`{ "devices": [...], "sessions": [...] }`; single-device `start --detach -q`
+returns the session record with `url`, `pid`, `serial`, `avdName`, `port`, and
+`profile`; multi-device detached starts return `{ "sessions": [...] }`; input
+commands return `{ "ok": true, "session": ... }`; `screenshot -q` returns
+`{ "ok": true, "path": "...", "session": ... }`. Pass `-d <serial>` to
+port-scoped commands when a server is streaming more than one emulator.
 
 ## MCP Setup
 
@@ -147,15 +176,70 @@ claude mcp add porthole -- npx portholejs mcp
 ```
 
 Useful MCP tools: `list_devices`, `boot_device`, `wait_for_boot`,
-`attach_device`, `tap`, `key`, `remote`, `type_text`, `screenshot`,
-`dump_ui`, `get_focused`, `find_element`, `wait_for`, `open_url`, `stop_app`,
-`clear_app`, `get_crashes`, `read_logcat`, and `install_apk`.
+`attach_device`, `tap`, `swipe`, `long_press`, `scroll`, `key`, `remote`,
+`type_text`, `screenshot`, `assert_screen`, `start_recording`, `stop_recording`,
+`dump_ui`, `get_focused`, `focus_on`, `find_element`, `wait_for`, `open_url`,
+`stop_app`, `clear_app`, `get_crashes`, `read_logcat`, and `install_apk`.
+
+## Agent Skill
+
+Porthole ships an agent skill (`skills/porthole/`) that teaches agents the full workflow: doctor triage,
+boot/attach, semantic UI assertions, TV navigation, and cleanup.
+
+Install it by copying the skill directory into your skills folder — for the
+current project:
+
+```sh
+mkdir -p .claude/skills
+cp -r node_modules/portholejs/skills/porthole .claude/skills/
+```
+
+or for all your projects:
+
+```sh
+mkdir -p ~/.claude/skills
+cp -r node_modules/portholejs/skills/porthole ~/.claude/skills/
+```
+
+From a clone of this repository, copy `skills/porthole` instead. Claude Code
+picks the skill up automatically; ask it to "test my app on the Android
+emulator" and it will follow the Porthole workflow.
+
+## GitHub Action
+
+Porthole ships an in-repo GitHub Action for CI smoke tests. It wraps
+`reactivecircus/android-emulator-runner`, starts `npx --yes portholejs` against
+the booted emulator, and runs your script while the emulator is alive.
+
+```yaml
+jobs:
+  tv-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: porthole
+        uses: giolaq/porthole@main
+        with:
+          avd-name: porthole-tv
+          api-level: "35"
+          profile: tv
+          script: |
+            mkdir -p artifacts
+            "$PORTHOLE_CLI" focus-on "Library" --select -q -p "$PORTHOLE_PORT"
+            "$PORTHOLE_CLI" screenshot -o artifacts/library.png -q -p "$PORTHOLE_PORT"
+```
+
+The action exposes `url`, `serial`, and `port` outputs, and also sets
+`PORTHOLE_URL`, `PORTHOLE_SERIAL`, `PORTHOLE_PORT`, and `PORTHOLE_CLI` for the
+smoke script. See `docs/github-action-example.yml` for a fuller `focus-on` /
+`assert-screen` workflow that uploads screenshot artifacts on failure.
 
 ## Browser UI
 
-The preview shows the active device, stream status, screenshots, copy-to-clipboard,
+The preview shows device tabs, stream status, screenshots, copy-to-clipboard,
 stream stats, logcat, drag-and-drop APK install/file push, phone hardware keys,
-and a TV D-pad remote. TV sessions reject touch input server-side.
+and a TV D-pad remote. Switching tabs re-subscribes to that device's stream
+without reloading the page. TV sessions reject touch input server-side.
 
 Video uses WebCodecs by default. Browsers without `VideoDecoder` automatically
 fall back to `/stream.mjpeg`, and `--mjpeg` or `?video=mjpeg` forces that mode.