portholejs 0.1.0

package/dist/ui-tree.d.ts

@@ -0,0 +1,47 @@
+export interface UiBounds {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}
+export interface UiNode {
+    class: string;
+    text: string;
+    resourceId: string;
+    contentDesc: string;
+    bounds: UiBounds;
+    focused: boolean;
+    focusable: boolean;
+    clickable: boolean;
+    enabled: boolean;
+    children: UiNode[];
+}
+export interface UiMatch extends UiNode {
+    center: {
+        x: number;
+        y: number;
+    };
+    normalizedCenter: {
+        x: number;
+        y: number;
+    } | null;
+}
+export declare function dumpUi(serial: string, filter?: string): Promise<UiNode[]>;
+export declare function getFocusedNode(serial: string): Promise<UiNode | null>;
+export declare function findElement(serial: string, query: {
+    text?: string;
+    resourceId?: string;
+}): Promise<UiMatch | null>;
+export declare function findInTree(tree: UiNode[], query: {
+    text?: string;
+    resourceId?: string;
+}): UiMatch | null;
+export declare function displaySize(tree: UiNode[]): {
+    width: number;
+    height: number;
+};
+export declare function waitForUiText(serial: string, text: string, timeoutMs: number): Promise<UiNode>;
+export declare function parseUiAutomatorXml(xml: string): UiNode[];
+export declare function findFocused(nodes: UiNode[]): UiNode | null;
+export declare function filterTree(nodes: UiNode[], query: string): UiNode[];
+//# sourceMappingURL=ui-tree.d.ts.map

package/dist/ui-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-tree.d.ts","sourceRoot":"","sources":["../src/ui-tree.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,OAAQ,SAAQ,MAAM;IACrC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAIjC,gBAAgB,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD;AAED,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI/E;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE3E;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAEzB;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,GAAG,IAAI,CAShB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQ7E;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAoCzD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAO1D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnE"}

package/dist/ui-tree.js

@@ -0,0 +1,179 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { adbBin, findAndroidSdk } from "./device-manager.js";
+const execFileAsync = promisify(execFile);
+export async function dumpUi(serial, filter) {
+    const xml = await dumpUiXml(serial);
+    const tree = parseUiAutomatorXml(xml);
+    return filter ? filterTree(tree, filter) : tree;
+}
+export async function getFocusedNode(serial) {
+    return findFocused(parseUiAutomatorXml(await dumpUiXml(serial)));
+}
+export async function findElement(serial, query) {
+    return findInTree(parseUiAutomatorXml(await dumpUiXml(serial)), query);
+}
+export function findInTree(tree, query) {
+    const node = flatten(tree).find((candidate) => {
+        if (query.text && !candidate.text.includes(query.text))
+            return false;
+        if (query.resourceId && !candidate.resourceId.includes(query.resourceId)) {
+            return false;
+        }
+        return true;
+    });
+    return node ? withCenter(node, displaySize(tree)) : null;
+}
+export function displaySize(tree) {
+    let width = 0;
+    let height = 0;
+    for (const node of flatten(tree)) {
+        if (node.bounds.r > width)
+            width = node.bounds.r;
+        if (node.bounds.b > height)
+            height = node.bounds.b;
+    }
+    return { width, height };
+}
+export async function waitForUiText(serial, text, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const tree = parseUiAutomatorXml(await dumpUiXml(serial));
+        const found = flatten(tree).find((node) => node.text.includes(text));
+        if (found)
+            return found;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    throw new Error(`Timed out waiting for text: ${text}`);
+}
+export function parseUiAutomatorXml(xml) {
+    const nodes = [];
+    const stack = [];
+    const tagRe = /<\/node>|<node\b([^>]*?)(\/?)>/g;
+    let match;
+    while ((match = tagRe.exec(xml)) !== null) {
+        if (match[0] === "</node>") {
+            stack.pop();
+            continue;
+        }
+        const attrs = parseAttributes(match[1] ?? "");
+        const node = {
+            class: attrs.get("class") ?? "",
+            text: attrs.get("text") ?? "",
+            resourceId: attrs.get("resource-id") ?? "",
+            contentDesc: attrs.get("content-desc") ?? "",
+            bounds: parseBounds(attrs.get("bounds") ?? ""),
+            focused: attrs.get("focused") === "true",
+            focusable: attrs.get("focusable") === "true",
+            clickable: attrs.get("clickable") === "true",
+            enabled: attrs.get("enabled") !== "false",
+            children: [],
+        };
+        const parent = stack.at(-1);
+        if (parent)
+            parent.children.push(node);
+        else
+            nodes.push(node);
+        if (match[2] !== "/") {
+            stack.push(node);
+        }
+    }
+    return nodes;
+}
+export function findFocused(nodes) {
+    for (const node of nodes) {
+        if (node.focused)
+            return node;
+        const child = findFocused(node.children);
+        if (child)
+            return child;
+    }
+    return null;
+}
+export function filterTree(nodes, query) {
+    const needle = query.toLowerCase();
+    return nodes.flatMap((node) => {
+        const children = filterTree(node.children, query);
+        const selfMatches = node.text.toLowerCase().includes(needle) ||
+            node.resourceId.toLowerCase().includes(needle) ||
+            node.contentDesc.toLowerCase().includes(needle);
+        return selfMatches || children.length > 0 ? [{ ...node, children }] : [];
+    });
+}
+function flatten(nodes) {
+    return nodes.flatMap((node) => [node, ...flatten(node.children)]);
+}
+function withCenter(node, display) {
+    const center = {
+        x: (node.bounds.l + node.bounds.r) / 2,
+        y: (node.bounds.t + node.bounds.b) / 2,
+    };
+    const normalizedCenter = display.width > 0 && display.height > 0
+        ? { x: center.x / display.width, y: center.y / display.height }
+        : null;
+    return { ...node, center, normalizedCenter };
+}
+async function dumpUiXml(serial) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const direct = await tryDumpDirect(serial);
+        if (direct.trim())
+            return direct;
+        await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+    const adb = adbBin(findAndroidSdk());
+    await execFileAsync(adb, [
+        "-s",
+        serial,
+        "shell",
+        "uiautomator",
+        "dump",
+        "/sdcard/window_dump.xml",
+    ]);
+    const { stdout } = await execFileAsync(adb, [
+        "-s",
+        serial,
+        "exec-out",
+        "cat",
+        "/sdcard/window_dump.xml",
+    ]);
+    return stdout;
+}
+async function tryDumpDirect(serial) {
+    try {
+        const { stdout } = await execFileAsync(adbBin(findAndroidSdk()), ["-s", serial, "exec-out", "uiautomator", "dump", "/dev/tty"], { maxBuffer: 10 * 1024 * 1024 });
+        const start = stdout.indexOf("<?xml");
+        return start === -1 ? stdout : stdout.slice(start);
+    }
+    catch {
+        return "";
+    }
+}
+function parseAttributes(input) {
+    const attrs = new Map();
+    const attrRe = /([\w:-]+)="([^"]*)"/g;
+    let match;
+    while ((match = attrRe.exec(input)) !== null) {
+        attrs.set(match[1] ?? "", decodeXml(match[2] ?? ""));
+    }
+    return attrs;
+}
+function parseBounds(value) {
+    const match = /^\[(\d+),(\d+)\]\[(\d+),(\d+)\]$/.exec(value);
+    if (!match)
+        return { l: 0, t: 0, r: 0, b: 0 };
+    return {
+        l: Number(match[1]),
+        t: Number(match[2]),
+        r: Number(match[3]),
+        b: Number(match[4]),
+    };
+}
+function decodeXml(value) {
+    return value
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&amp;", "&");
+}
+//# sourceMappingURL=ui-tree.js.map

package/dist/ui-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-tree.js","sourceRoot":"","sources":["../src/ui-tree.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "portholejs",
+  "version": "0.1.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",
+  "bin": {
+    "porthole": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-package-assets.mjs",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "node scripts/download-scrcpy-server.mjs",
+    "prepublishOnly": "npm run build --prefix ../.."
+  },
+  "keywords": [
+    "android",
+    "emulator",
+    "android-tv",
+    "scrcpy",
+    "adb",
+    "avd",
+    "mcp",
+    "claude"
+  ],
+  "license": "Apache-2.0",
+  "author": "Giovanni Laquidara (https://github.com/giolaq)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giolaq/porthole.git"
+  },
+  "homepage": "https://github.com/giolaq/porthole#readme",
+  "bugs": {
+    "url": "https://github.com/giolaq/porthole/issues"
+  },
+  "files": [
+    "dist/",
+    "!dist/__tests__/",
+    "scripts/download-scrcpy-server.mjs",
+    "client-dist/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@yume-chan/adb": "^2.6.0",
+    "@yume-chan/adb-scrcpy": "^2.3.2",
+    "@yume-chan/adb-server-node-tcp": "^2.5.2",
+    "@yume-chan/scrcpy": "^2.3.0",
+    "@yume-chan/stream-extra": "^2.5.3",
+    "commander": "^14.0.3",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/pngjs": "^6.0.5",
+    "@types/ws": "^8.18.1"
+  }
+}

package/scripts/download-scrcpy-server.mjs

@@ -0,0 +1,67 @@
+// Downloads the pinned scrcpy-server jar from the official Genymobile/scrcpy
+// GitHub release at install time. The jar is NOT committed to the repository
+// or shipped in the npm tarball; this script is the single source of truth
+// for the pinned version and its checksum.
+//
+// Bump process: update SCRCPY_VERSION and SCRCPY_SHA256 together, then verify
+// the engine's AdbScrcpyOptions class in scrcpy-engine.ts matches the new
+// server's protocol version.
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SCRCPY_VERSION = "3.1";
+export const SCRCPY_SHA256 =
+  "958f0944a62f23b1f33a16e9eb14844c1a04b882ca175a738c16d23cb22b86c0";
+export const SCRCPY_URL = `https://github.com/Genymobile/scrcpy/releases/download/v${SCRCPY_VERSION}/scrcpy-server-v${SCRCPY_VERSION}`;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, "..");
+const targetPath = join(packageRoot, "assets", "scrcpy-server");
+
+function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+async function alreadyPresent() {
+  if (!existsSync(targetPath)) return false;
+  return sha256(await readFile(targetPath)) === SCRCPY_SHA256;
+}
+
+async function download() {
+  const response = await fetch(SCRCPY_URL, { redirect: "follow" });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} fetching ${SCRCPY_URL}`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const digest = sha256(bytes);
+  if (digest !== SCRCPY_SHA256) {
+    throw new Error(
+      `Checksum mismatch for scrcpy-server v${SCRCPY_VERSION}: expected ${SCRCPY_SHA256}, got ${digest}`,
+    );
+  }
+  await mkdir(dirname(targetPath), { recursive: true });
+  const tmpPath = `${targetPath}.download-${process.pid}`;
+  await writeFile(tmpPath, bytes);
+  await rename(tmpPath, targetPath);
+}
+
+try {
+  if (await alreadyPresent()) {
+    process.exit(0);
+  }
+  await download();
+  console.log(`porthole: downloaded scrcpy-server v${SCRCPY_VERSION} (sha256 verified)`);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.warn(
+    `porthole: could not download scrcpy-server v${SCRCPY_VERSION}: ${message}\n` +
+      `porthole: streaming will not work until it is fetched. Re-run:\n` +
+      `porthole:   node ${join("scripts", "download-scrcpy-server.mjs")} (from the portholejs package directory)`,
+  );
+  // Do not fail `npm install` on offline machines; the CLI and doctor
+  // report the missing asset with the same fix instructions at runtime.
+  process.exit(0);
+}