@houwert/conductor 0.29.2 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.29.2",
+  "version": "0.30.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor-device-interact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-interact
-description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements (by selector or raw coordinate), typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, granting/denying app permissions, adding media to the gallery, setting GPS location or a travel route, toggling airplane mode, recording a screen video, or verifying an app change in the real running app.
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, Roku device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements (by selector or raw coordinate), typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, granting/denying app permissions, adding media to the gallery, setting GPS location or a travel route, toggling airplane mode, recording a screen video, or verifying an app change in the real running app.
 ---
 
 # Conductor — device interaction
@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
@@ -125,8 +125,9 @@ relaunch without the flag. (See `conductor-device-setup`.)
 
 ## Tips
 
-- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega>` scopes by platform.
+- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega|roku>` scopes by platform.
 - Vega (Amazon Fire TV) is D-pad driven: navigate with `press-key "Remote Dpad …"`; coordinate `tap-on` also works. `open-link`, `set-location`, gestures, and clipboard are unsupported. See `conductor-device-setup`.
+- Roku is D-pad only — there is no touch. `tap-on <selector>` resolves the element but presses `Select`, which activates whatever currently holds **focus**, so navigate focus onto the target with `press-key "Remote Dpad …"` first and use `tap-on` to confirm. `scroll`/`swipe` become repeated D-pad presses in the direction the content moves. `open-link` needs an app id (it becomes a channel launch parameter). Only sideloaded dev-mode channels are inspectable. See `conductor-device-setup`.
 - Add `--json` for machine-readable output; failed assertions exit non-zero.
 - Run a per-session daemon for many commands (see `conductor-device-setup`).
 - `conductor <command> --help` for exact flags.

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -21,7 +21,7 @@ conductor list-apps          # installed app ids / package names (--json adds ap
 
 | Command                                                               | Purpose                                                                    |
 | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `conductor start-device --platform <ios\|android\|tvos\|web\|vega>`   | Boot a simulator/emulator, start the web driver, or attach to a Vega VVD    |
+| `conductor start-device --platform <ios\|android\|tvos\|web\|vega\|roku>` | Boot a simulator/emulator, start the web driver, attach to a Vega VVD, or check a Roku device |
 | `conductor start-device --os-version <n> --device-type <name>`        | Pick OS version + device type (creates if needed)                          |
 | `conductor start-device --platform android --avd <name> --device-type <profile> --memory <mb>` | Create an Android AVD with a RAM floor (default 4096MB; only raises, creation-time only) |
 | `conductor stop-device [<name-or-id>] [--all]`                        | Shut down device(s)                                                        |
@@ -69,6 +69,39 @@ app launch — so launch the app under test via conductor. Navigate with the D-p
 works. Unsupported on Vega: deep links (`open-link`), `set-location`, gestures,
 screen recording, clipboard, `clear-state`/`uninstall-app`.
 
+### Roku
+
+Roku is driven over the network with the **External Control Protocol** (ECP — an
+HTTP REST API on device port 8060). There is no emulator and no driver process:
+physical hardware only, and every command is a stateless ECP call.
+
+Device setup, once per device:
+
+1. Enable developer mode (Home ×3, Up ×2, Right, Left, Right, Left, Right) and
+   set a dev password.
+2. Set **Settings > System > Advanced system settings > Control by mobile apps >
+   Network access** to **Permissive** — recent Roku OS versions answer `403` to
+   every keypress otherwise, while still serving the view hierarchy.
+
+Environment:
+
+```bash
+export CONDUCTOR_ROKU_HOST=192.168.1.100   # pin a device by IP (primary)
+export CONDUCTOR_ROKU_PASSWORD=devpwd      # dev-mode password (screenshots only)
+export CONDUCTOR_ROKU_DISCOVERY=true       # optional: SSDP LAN scan (~1s per listing)
+```
+
+Devices show up in `list-devices` as `roku:<host>`;
+`conductor start-device --platform roku [--name <host>]` checks reachability
+rather than booting anything. The view hierarchy comes from `/query/app-ui`,
+which **only reports sideloaded dev-mode channels** — a store channel inspects as
+empty. A sideloaded channel's app id is `dev`. Screenshots need
+`CONDUCTOR_ROKU_PASSWORD`.
+
+Unsupported on Roku: `install-app`/`uninstall-app` (sideload via the device's dev
+web server at `http://<device-ip>`), `list-apps`, `clear-state`, gestures,
+screen recording, clipboard, `set-location`, memory/CPU profiling, and device logs.
+
 ## App lifecycle
 
 | Command                                               | Purpose                                                                |

package/skills/conductor-profiler/SKILL.md

@@ -18,9 +18,14 @@ Measure a running app's performance and inspect crashes.
 | "Which component re-renders on every input?" | `profile react start` → interact → `profile react stop` |
 | "Memory grows / it stutters periodically" | `profile memory --track 30` |
 
-`profile frames`, `profile cpu` and `profile memory` work on **release builds**
-and on real hardware. `profile js` and `profile react` attach over Metro, so
-they need a dev/profiling build.
+Only `profile frames` and `profile memory` work on a **stock release build**.
+`profile cpu` needs `android:debuggable` or `<profileable android:shell="true"/>`
+in the manifest; `profile js` and `profile react` attach over Metro, and release
+Hermes ships without the inspector so there is no target to attach to.
+
+On TV, run `profile frames --track` with `--repeat 5`. Identical captures of one
+screen have been measured spanning 37.8-72.9% janky — a single window can invent
+a regression or hide one, and cannot support a `--diff`.
 
 ## Frame timing & jank (Android, incl. Fire TV / Android TV)
 
@@ -43,7 +48,7 @@ navigation, prefer asking a human to drive the physical remote during the
 window (the command announces the window on stderr for exactly this), and treat
 a divergence between human-driven and automated numbers as the harness.
 
-Not available on `vega` — but a **physical Fire TV Stick runs Fire OS
+Not available on `roku` (ECP exposes no counters) or `vega` — but a **physical Fire TV Stick runs Fire OS
 (Android)** over adb and works fine.
 
 Attribute jank by comparing each phase's p95 against its p50: `vsyncDelay` means