portholejs 0.1.0 → 0.2.0

package/dist/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAsB,SAAS,CAAC,IAAI,SAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAY1E;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,EACpB,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACvD,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/E"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAsB,SAAS,CAAC,IAAI,SAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAY1E;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,EACpB,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACvD,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/E"}

package/dist/state.js

@@ -26,9 +26,7 @@ export async function writeState(state, path = statePath()) {
 }
 export async function upsertSession(record, path = statePath()) {
     const state = await readState(path);
-    const sessions = state.sessions.filter((session) => session.serial !== record.serial &&
-        session.port !== record.port &&
-        session.pid !== record.pid);
+    const sessions = state.sessions.filter((session) => session.serial !== record.serial);
     sessions.push(record);
     await writeState({ sessions }, path);
 }

package/dist/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoB1C,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAI,GAAG,SAAS,EAAE;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QACzD,OAAO;YACL,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;gBACtC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC;gBACzC,CAAC,CAAC,EAAE;SACP,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAoB,EACpB,IAAI,GAAG,SAAS,EAAE;IAElB,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC7C,MAAM,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChE,MAAM,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA6B,EAC7B,IAAI,GAAG,SAAS,EAAE;IAElB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;IACtF,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,MAAM,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAuD,EACvD,IAAI,GAAG,SAAS,EAAE;IAElB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;QACjD,IAAI,KAAK,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QAC1E,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,MAAc;IAC3D,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CACxB,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,UAAU,CAC7D,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,CACL,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAClC,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;QACvD,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;QAC9B,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;QAC9B,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;QACpC,OAAO,MAAM,CAAC,UAAU,KAAK,SAAS,CACvC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "portholejs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A window into your Android emulator — stream and control AVDs from the browser",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "porthole": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc && node scripts/copy-package-assets.mjs",
+    "build": "npm run build:ts && npm run copy-package-assets",
+    "build:ts": "tsc",
+    "copy-package-assets": "node scripts/copy-package-assets.mjs",
     "typecheck": "tsc --noEmit",
     "postinstall": "node scripts/download-scrcpy-server.mjs",
     "prepublishOnly": "npm run build --prefix ../.."
@@ -38,7 +51,8 @@
     "dist/",
     "!dist/__tests__/",
     "scripts/download-scrcpy-server.mjs",
-    "client-dist/"
+    "client-dist/",
+    "skills/"
   ],
   "engines": {
     "node": ">=20"
@@ -52,6 +66,7 @@
     "@yume-chan/stream-extra": "^2.5.3",
     "commander": "^14.0.3",
     "jpeg-js": "^0.4.4",
+    "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "ws": "^8.21.0"
   },

package/skills/porthole/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: porthole
+description: Boot, stream, and control Android phone/TV emulators headlessly with the porthole CLI or MCP tools — screenshots, touch/D-pad input, semantic UI dumps, logcat, and APK install. Use when asked to run, test, drive, or inspect an Android emulator or AVD, navigate an Android TV app, or verify Android UI state from an agent workflow.
+---
+
+# Porthole Agent Skill
+
+Use Porthole when you need to inspect or control an Android emulator from an
+agent workflow. Porthole supports Android emulator AVDs only; do not use it for
+iOS, physical Android devices, or audio.
+
+## Workflow
+
+1. List devices:
+
+   ```sh
+   porthole list -q
+   ```
+
+   If anything fails at any step (SDK missing, port busy, offline adb,
+   missing scrcpy-server), diagnose first:
+
+   ```sh
+   porthole doctor -q
+   ```
+
+2. Start a session. Prefer detached JSON mode for automation:
+
+   ```sh
+   porthole start <AVD_NAME> --detach -q
+   porthole start <PHONE_AVD> <TV_AVD> --detach -q
+   ```
+
+   In GitHub Actions, prefer the bundled repository action so the emulator,
+   Porthole server, and smoke script share one lifecycle:
+
+   ```yaml
+   - uses: giolaq/porthole@main
+     with:
+       profile: tv
+       script: |
+         "$PORTHOLE_CLI" focus-on "Library" --select -q -p "$PORTHOLE_PORT"
+   ```
+
+3. Verify the screen:
+
+   ```sh
+   porthole screenshot -q
+   porthole assert-screen baseline.png --threshold 0.02 -q
+   porthole record run.mp4 --duration 10s -q
+   ```
+
+4. Drive input:
+
+   ```sh
+   porthole tap 0.5 0.9
+   porthole scroll down
+   porthole swipe 0.5 0.85 0.5 0.2
+   porthole longpress 0.5 0.5
+   porthole key 4
+   porthole text "hello"
+   ```
+
+   When one Porthole server is streaming multiple emulators, pass
+   `-d <serial>` to target the right device:
+
+   ```sh
+   porthole tap 0.5 0.9 -d emulator-5554
+   porthole remote dpad_down -d emulator-5556
+   ```
+
+5. For Android TV, use remote buttons instead of touch:
+
+   ```sh
+   porthole remote dpad_down
+   porthole focus-on "Library" --select
+   porthole remote select
+   porthole remote back
+   ```
+
+6. Read logs when behavior is unclear:
+
+   ```sh
+   curl "http://127.0.0.1:3200/api/logcat?lines=200"
+   ```
+
+7. Clean up:
+
+   ```sh
+   porthole kill -q
+   ```
+
+## Semantic UI
+
+Prefer semantic checks before screenshot interpretation when possible:
+
+```sh
+porthole focused -q
+porthole dump-ui --filter "Settings" -q
+porthole wait-for "Continue" --timeout 10000 -q
+porthole open-url "example://deep/link"
+```
+
+For TV AVDs, prefer `focus-on` / `focus_on` for named destinations. Use
+`remote`, then `focused`, then assert the focused node's `text`, `resourceId`,
+or `contentDesc` for manual focus work. For phones, `find_element` is exposed
+through MCP and can tap the center of a matching node.
+
+Note: `focused` is a D-pad/leanback concept. On phone profiles it usually
+returns `null` — that is expected, not an error; use `dump-ui` or
+`find_element` on phones instead.
+
+## MCP Loop
+
+When MCP is configured, use:
+
+- `list_devices` to pick an AVD
+- `boot_device` and `wait_for_boot` for cold starts
+- `attach_device` before input and screenshots
+- `screenshot` after each meaningful input step
+- `assert_screen` when a baseline image is available
+- `start_recording` and `stop_recording` when an MP4 artifact is useful
+- `dump_ui`, `get_focused`, and `wait_for` for semantic assertions
+- `get_crashes` after risky actions
+- `focus_on` or `remote` for TV navigation
+- `tap`, `swipe`, `scroll`, and `long_press` only for phone profiles
+- `read_logcat` to diagnose crashes or focus issues
+- `install_apk` to load a freshly built APK
+
+Keep the loop tight: input, screenshot, compare, adjust.