@lanternajs/android 0.0.1

package/dist/collector.d.ts

@@ -0,0 +1,10 @@
+import type { CommandRunner, Device, MeasurementSession } from "@lanternajs/core";
+/**
+ * Collect Android performance metrics for a given device and package.
+ *
+ * Runs adb commands to gather CPU (via top), memory (via dumpsys meminfo),
+ * and frame metrics (via dumpsys gfxinfo), then merges all samples into
+ * a single MeasurementSession.
+ */
+export declare function collectAndroidMetrics(runner: CommandRunner, device: Device, packageName: string, duration: number): Promise<MeasurementSession>;
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,EAAgB,MAAM,kBAAkB,CAAC;AAMhG;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAC1C,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC,CA4D7B"}

package/dist/collector.js

@@ -0,0 +1,64 @@
+import { parseGfxinfoOutput } from "./parsers/gfxinfo";
+import { parseMeminfoOutput } from "./parsers/meminfo";
+import { parseTopOutput } from "./parsers/top";
+import { findAndroidPid } from "./process";
+/**
+ * Collect Android performance metrics for a given device and package.
+ *
+ * Runs adb commands to gather CPU (via top), memory (via dumpsys meminfo),
+ * and frame metrics (via dumpsys gfxinfo), then merges all samples into
+ * a single MeasurementSession.
+ */
+export async function collectAndroidMetrics(runner, device, packageName, duration) {
+    const pid = await findAndroidPid(runner, device.id, packageName);
+    if (pid === null) {
+        throw new Error(`Process not found: "${packageName}" is not running on device "${device.name}" (${device.id}). ` +
+            "Make sure the app is launched before profiling.");
+    }
+    const startedAt = Date.now();
+    const samples = [];
+    // Run all data collection in parallel
+    const [topResult, meminfoResult, gfxinfoResult] = await Promise.all([
+        runner("adb", [
+            "-s",
+            device.id,
+            "shell",
+            "top",
+            "-H",
+            "-d",
+            "1",
+            "-n",
+            String(duration),
+            "-p",
+            String(pid),
+        ]),
+        runner("adb", ["-s", device.id, "shell", "dumpsys", "meminfo", packageName]),
+        runner("adb", ["-s", device.id, "shell", "dumpsys", "gfxinfo", packageName]),
+    ]);
+    // Parse top output — may contain multiple snapshots separated by blank lines
+    if (topResult.exitCode === 0 && topResult.stdout) {
+        const snapshots = topResult.stdout.split(/\n\n+/);
+        for (let i = 0; i < snapshots.length; i++) {
+            const snapshotTimestamp = startedAt + i * 1000;
+            const parsed = parseTopOutput(snapshots[i], snapshotTimestamp);
+            samples.push(...parsed);
+        }
+    }
+    // Parse meminfo
+    if (meminfoResult.exitCode === 0 && meminfoResult.stdout) {
+        const parsed = parseMeminfoOutput(meminfoResult.stdout, startedAt);
+        samples.push(...parsed);
+    }
+    // Parse gfxinfo
+    if (gfxinfoResult.exitCode === 0 && gfxinfoResult.stdout) {
+        const parsed = parseGfxinfoOutput(gfxinfoResult.stdout, startedAt);
+        samples.push(...parsed);
+    }
+    return {
+        device,
+        platform: "android",
+        samples,
+        duration,
+        startedAt,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { collectAndroidMetrics } from "./collector";
+export { parseGfxinfoOutput } from "./parsers/gfxinfo";
+export { parseMeminfoOutput } from "./parsers/meminfo";
+export { parseTopOutput } from "./parsers/top";
+export { findAndroidPid } from "./process";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { collectAndroidMetrics } from "./collector";
+export { parseGfxinfoOutput } from "./parsers/gfxinfo";
+export { parseMeminfoOutput } from "./parsers/meminfo";
+export { parseTopOutput } from "./parsers/top";
+export { findAndroidPid } from "./process";

package/dist/parsers/gfxinfo.d.ts

@@ -0,0 +1,8 @@
+import { type MetricSample } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell dumpsys gfxinfo <package>`.
+ * Extracts janky frame percentage to calculate effective UI FPS and frame drop rate.
+ * Never throws — returns empty array on malformed input.
+ */
+export declare function parseGfxinfoOutput(output: string, timestamp: number): MetricSample[];
+//# sourceMappingURL=gfxinfo.d.ts.map

package/dist/parsers/gfxinfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gfxinfo.d.ts","sourceRoot":"","sources":["../../src/parsers/gfxinfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,kBAAkB,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAiDpF"}

package/dist/parsers/gfxinfo.js

@@ -0,0 +1,49 @@
+import { MetricType } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell dumpsys gfxinfo <package>`.
+ * Extracts janky frame percentage to calculate effective UI FPS and frame drop rate.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseGfxinfoOutput(output, timestamp) {
+    if (!output || typeof output !== "string") {
+        return [];
+    }
+    const lines = output.split("\n");
+    let totalFrames = null;
+    let jankyFrames = null;
+    let jankyPercent = null;
+    for (const line of lines) {
+        const totalMatch = line.match(/Total frames rendered:\s*([\d]+)/);
+        if (totalMatch) {
+            totalFrames = Number.parseInt(totalMatch[1], 10);
+        }
+        // "Janky frames: 75 (5.00%)"
+        const jankyMatch = line.match(/Janky frames:\s*([\d]+)\s*\(([\d.]+)%\)/);
+        if (jankyMatch) {
+            jankyFrames = Number.parseInt(jankyMatch[1], 10);
+            jankyPercent = Number.parseFloat(jankyMatch[2]);
+        }
+    }
+    if (totalFrames === null || jankyFrames === null || jankyPercent === null) {
+        return [];
+    }
+    if (Number.isNaN(totalFrames) || Number.isNaN(jankyPercent)) {
+        return [];
+    }
+    // Calculate effective FPS: 60 * (1 - jankyPercent/100)
+    const actualFps = 60 * (1 - jankyPercent / 100);
+    return [
+        {
+            type: MetricType.UI_FPS,
+            value: Math.round(actualFps * 100) / 100,
+            timestamp,
+            unit: "fps",
+        },
+        {
+            type: MetricType.FRAME_DROPS,
+            value: jankyPercent,
+            timestamp,
+            unit: "%",
+        },
+    ];
+}

package/dist/parsers/meminfo.d.ts

@@ -0,0 +1,8 @@
+import { type MetricSample } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell dumpsys meminfo <package>`.
+ * Extracts TOTAL Pss Total and converts KB to MB.
+ * Never throws — returns empty array on malformed input.
+ */
+export declare function parseMeminfoOutput(output: string, timestamp: number): MetricSample[];
+//# sourceMappingURL=meminfo.d.ts.map

package/dist/parsers/meminfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meminfo.d.ts","sourceRoot":"","sources":["../../src/parsers/meminfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,kBAAkB,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CA8BpF"}

package/dist/parsers/meminfo.js

@@ -0,0 +1,32 @@
+import { MetricType } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell dumpsys meminfo <package>`.
+ * Extracts TOTAL Pss Total and converts KB to MB.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseMeminfoOutput(output, timestamp) {
+    if (!output || typeof output !== "string") {
+        return [];
+    }
+    const lines = output.split("\n");
+    for (const line of lines) {
+        // Look for the TOTAL line — format: "  TOTAL   120000   100000  ..."
+        const match = line.match(/^\s*TOTAL\s+([\d]+)/);
+        if (match) {
+            const pssKb = Number.parseInt(match[1], 10);
+            if (Number.isNaN(pssKb)) {
+                return [];
+            }
+            const pssMb = pssKb / 1024;
+            return [
+                {
+                    type: MetricType.MEMORY,
+                    value: Math.round(pssMb * 100) / 100,
+                    timestamp,
+                    unit: "MB",
+                },
+            ];
+        }
+    }
+    return [];
+}

package/dist/parsers/top.d.ts

@@ -0,0 +1,8 @@
+import { type MetricSample } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell top -H -d 1 -p <pid>`.
+ * Sums all thread CPU percentages to produce a single CPU sample.
+ * Never throws — returns empty array on malformed input.
+ */
+export declare function parseTopOutput(output: string, timestamp: number): MetricSample[];
+//# sourceMappingURL=top.d.ts.map

package/dist/parsers/top.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"top.d.ts","sourceRoot":"","sources":["../../src/parsers/top.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,kBAAkB,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CA2ChF"}

package/dist/parsers/top.js

@@ -0,0 +1,43 @@
+import { MetricType } from "@lanternajs/core";
+/**
+ * Parse output from `adb shell top -H -d 1 -p <pid>`.
+ * Sums all thread CPU percentages to produce a single CPU sample.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseTopOutput(output, timestamp) {
+    if (!output || typeof output !== "string") {
+        return [];
+    }
+    const lines = output.split("\n");
+    let totalCpu = 0;
+    let foundAny = false;
+    for (const line of lines) {
+        // Match data lines: PID TID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ THREAD
+        // The CPU column contains a value like "25.0" and is preceded by a single-char state (S/R/D/Z/T)
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("Tasks:") || trimmed.startsWith("PID")) {
+            continue;
+        }
+        // Try to extract CPU percentage from process lines
+        // Format: PID TID USER PR NI VIRT RES SHR S[%CPU] %MEM TIME+ THREAD
+        const match = trimmed.match(/^\s*\d+\s+\d+\s+\S+\s+\d+\s+[-\d]+\s+\S+\s+\S+\s+\S+\s+[SRDZT]\s+([\d.]+)/);
+        if (match) {
+            const cpu = Number.parseFloat(match[1]);
+            if (!Number.isNaN(cpu)) {
+                totalCpu += cpu;
+                foundAny = true;
+            }
+        }
+    }
+    if (!foundAny) {
+        return [];
+    }
+    return [
+        {
+            type: MetricType.CPU,
+            value: totalCpu,
+            timestamp,
+            unit: "%",
+        },
+    ];
+}

package/dist/process.d.ts

@@ -0,0 +1,7 @@
+import type { CommandRunner } from "@lanternajs/core";
+/**
+ * Find the PID of a running Android app by package name.
+ * Returns null if the process is not found or on error.
+ */
+export declare function findAndroidPid(runner: CommandRunner, deviceId: string, packageName: string): Promise<number | null>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;GAGG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB"}

package/dist/process.js

@@ -0,0 +1,20 @@
+/**
+ * Find the PID of a running Android app by package name.
+ * Returns null if the process is not found or on error.
+ */
+export async function findAndroidPid(runner, deviceId, packageName) {
+    try {
+        const result = await runner("adb", ["-s", deviceId, "shell", "pidof", packageName]);
+        if (result.exitCode !== 0 || !result.stdout.trim()) {
+            return null;
+        }
+        const pid = Number.parseInt(result.stdout.trim(), 10);
+        if (Number.isNaN(pid)) {
+            return null;
+        }
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lanternajs/android",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src"],
+  "license": "Apache-2.0",
+  "description": "Android performance data collection via adb and perfetto for Lanterna",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicepkg/lanterna.git",
+    "directory": "packages/android"
+  },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@lanternajs/core": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "bun test"
+  }
+}

package/src/__tests__/parsers.test.ts

@@ -0,0 +1,355 @@
+import { describe, expect, test } from "bun:test";
+import { type CommandRunner, type Device, MetricType } from "@lanternajs/core";
+import { collectAndroidMetrics } from "../collector";
+import { parseGfxinfoOutput } from "../parsers/gfxinfo";
+import { parseMeminfoOutput } from "../parsers/meminfo";
+import { parseTopOutput } from "../parsers/top";
+import { findAndroidPid } from "../process";
+
+// ── Fixtures ────────────────────────────────────────────────────────────────────
+
+const TOP_OUTPUT = `Tasks: 1 total,   0 running,   1 sleeping,   0 stopped,   0 zombie
+  PID   TID USER         PR  NI VIRT  RES  SHR S[%CPU] %MEM     TIME+ THREAD
+12345 12345 u0_a123      20   0 4.2G 180M  95M S  25.0  4.5   0:12.34 main
+12345 12350 u0_a123      20   0 4.2G 180M  95M S  15.3  4.5   0:08.21 mqt_js
+12345 12351 u0_a123      20   0 4.2G 180M  95M S   8.7  4.5   0:05.10 RenderThread`;
+
+const MEMINFO_OUTPUT = `Applications Memory Usage (in Kilobytes):
+Uptime: 123456 Realtime: 654321
+
+** MEMINFO in pid 12345 [com.example.app] **
+                   Pss  Private  Private  SwapPss     Rss  Heap  Heap  Heap
+                 Total    Dirty    Clean    Dirty   Total  Size Alloc  Free
+                ------   ------   ------   ------  ------  ----  ----  ----
+  Native Heap    45678    45000      200      100   50000 65536 50000 15536
+  Dalvik Heap    12345    12000      100       50   15000 20480 12345  8135
+        TOTAL   120000   100000     5000     1000  150000`;
+
+const GFXINFO_OUTPUT = `Applications Graphics Acceleration Info:
+com.example.app/com.example.app.MainActivity:
+
+Total frames rendered: 1500
+Janky frames: 75 (5.00%)
+Number of missed Vsync: 30
+Number of High input latency: 10
+Number of Slow UI thread: 25
+Number of Slow bitmap uploads: 5
+Number of Slow issue draw commands: 5`;
+
+const MOCK_DEVICE: Device = {
+	id: "emulator-5554",
+	name: "Pixel 6 API 33",
+	platform: "android",
+	type: "emulator",
+};
+
+// ── parseTopOutput ──────────────────────────────────────────────────────────────
+
+describe("parseTopOutput", () => {
+	test("sums all thread CPU values into one sample", () => {
+		const samples = parseTopOutput(TOP_OUTPUT, 1000);
+
+		expect(samples).toHaveLength(1);
+		expect(samples[0].type).toBe(MetricType.CPU);
+		expect(samples[0].value).toBeCloseTo(49.0, 1); // 25.0 + 15.3 + 8.7
+		expect(samples[0].timestamp).toBe(1000);
+		expect(samples[0].unit).toBe("%");
+	});
+
+	test("returns empty array for empty input", () => {
+		expect(parseTopOutput("", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for malformed input", () => {
+		expect(parseTopOutput("some random text\nwith no data", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for null/undefined-like input", () => {
+		expect(parseTopOutput(null as unknown as string, 1000)).toEqual([]);
+		expect(parseTopOutput(undefined as unknown as string, 1000)).toEqual([]);
+	});
+
+	test("handles single thread output", () => {
+		const singleThread = `Tasks: 1 total,   0 running,   1 sleeping,   0 stopped,   0 zombie
+  PID   TID USER         PR  NI VIRT  RES  SHR S[%CPU] %MEM     TIME+ THREAD
+12345 12345 u0_a123      20   0 4.2G 180M  95M S  42.5  4.5   0:12.34 main`;
+
+		const samples = parseTopOutput(singleThread, 2000);
+		expect(samples).toHaveLength(1);
+		expect(samples[0].value).toBeCloseTo(42.5, 1);
+	});
+});
+
+// ── parseMeminfoOutput ──────────────────────────────────────────────────────────
+
+describe("parseMeminfoOutput", () => {
+	test("extracts TOTAL Pss and converts KB to MB", () => {
+		const samples = parseMeminfoOutput(MEMINFO_OUTPUT, 1000);
+
+		expect(samples).toHaveLength(1);
+		expect(samples[0].type).toBe(MetricType.MEMORY);
+		expect(samples[0].value).toBeCloseTo(120000 / 1024, 2); // ~117.19 MB
+		expect(samples[0].timestamp).toBe(1000);
+		expect(samples[0].unit).toBe("MB");
+	});
+
+	test("returns empty array for empty input", () => {
+		expect(parseMeminfoOutput("", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for malformed input", () => {
+		expect(parseMeminfoOutput("no total line here\njust garbage", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for null/undefined-like input", () => {
+		expect(parseMeminfoOutput(null as unknown as string, 1000)).toEqual([]);
+		expect(parseMeminfoOutput(undefined as unknown as string, 1000)).toEqual([]);
+	});
+
+	test("handles TOTAL line with different spacing", () => {
+		const output = "  TOTAL     98765   50000   2000   500  100000";
+		const samples = parseMeminfoOutput(output, 3000);
+
+		expect(samples).toHaveLength(1);
+		expect(samples[0].value).toBeCloseTo(98765 / 1024, 2);
+	});
+});
+
+// ── parseGfxinfoOutput ──────────────────────────────────────────────────────────
+
+describe("parseGfxinfoOutput", () => {
+	test("calculates FPS and frame drop rate", () => {
+		const samples = parseGfxinfoOutput(GFXINFO_OUTPUT, 1000);
+
+		expect(samples).toHaveLength(2);
+
+		const fpsSample = samples.find((s) => s.type === MetricType.UI_FPS);
+		const dropSample = samples.find((s) => s.type === MetricType.FRAME_DROPS);
+
+		expect(fpsSample).toBeDefined();
+		expect(fpsSample?.value).toBeCloseTo(57.0, 1); // 60 * (1 - 5/100) = 57
+		expect(fpsSample?.unit).toBe("fps");
+		expect(fpsSample?.timestamp).toBe(1000);
+
+		expect(dropSample).toBeDefined();
+		expect(dropSample?.value).toBe(5.0);
+		expect(dropSample?.unit).toBe("%");
+	});
+
+	test("returns empty array for empty input", () => {
+		expect(parseGfxinfoOutput("", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for malformed input", () => {
+		expect(parseGfxinfoOutput("no gfx data here", 1000)).toEqual([]);
+	});
+
+	test("returns empty array for null/undefined-like input", () => {
+		expect(parseGfxinfoOutput(null as unknown as string, 1000)).toEqual([]);
+		expect(parseGfxinfoOutput(undefined as unknown as string, 1000)).toEqual([]);
+	});
+
+	test("returns empty array when only total frames present but no janky", () => {
+		const partial = "Total frames rendered: 1000\n";
+		expect(parseGfxinfoOutput(partial, 1000)).toEqual([]);
+	});
+
+	test("handles 0% janky frames", () => {
+		const output = `Total frames rendered: 500
+Janky frames: 0 (0.00%)`;
+		const samples = parseGfxinfoOutput(output, 1000);
+
+		expect(samples).toHaveLength(2);
+		const fpsSample = samples.find((s) => s.type === MetricType.UI_FPS);
+		expect(fpsSample?.value).toBeCloseTo(60.0, 1);
+	});
+});
+
+// ── findAndroidPid ──────────────────────────────────────────────────────────────
+
+describe("findAndroidPid", () => {
+	test("returns PID when process is found", async () => {
+		const runner: CommandRunner = async () => ({
+			stdout: "12345\n",
+			stderr: "",
+			exitCode: 0,
+		});
+
+		const pid = await findAndroidPid(runner, "emulator-5554", "com.example.app");
+		expect(pid).toBe(12345);
+	});
+
+	test("returns null when process is not found", async () => {
+		const runner: CommandRunner = async () => ({
+			stdout: "",
+			stderr: "",
+			exitCode: 1,
+		});
+
+		const pid = await findAndroidPid(runner, "emulator-5554", "com.example.app");
+		expect(pid).toBeNull();
+	});
+
+	test("returns null on empty stdout", async () => {
+		const runner: CommandRunner = async () => ({
+			stdout: "   \n",
+			stderr: "",
+			exitCode: 0,
+		});
+
+		const pid = await findAndroidPid(runner, "emulator-5554", "com.example.app");
+		expect(pid).toBeNull();
+	});
+
+	test("returns null when runner throws", async () => {
+		const runner: CommandRunner = async () => {
+			throw new Error("adb not found");
+		};
+
+		const pid = await findAndroidPid(runner, "emulator-5554", "com.example.app");
+		expect(pid).toBeNull();
+	});
+
+	test("passes correct arguments to runner", async () => {
+		let capturedCmd = "";
+		let capturedArgs: string[] = [];
+
+		const runner: CommandRunner = async (cmd, args) => {
+			capturedCmd = cmd;
+			capturedArgs = args;
+			return { stdout: "99999\n", stderr: "", exitCode: 0 };
+		};
+
+		await findAndroidPid(runner, "device-123", "com.test.pkg");
+		expect(capturedCmd).toBe("adb");
+		expect(capturedArgs).toEqual(["-s", "device-123", "shell", "pidof", "com.test.pkg"]);
+	});
+});
+
+// ── collectAndroidMetrics ───────────────────────────────────────────────────────
+
+describe("collectAndroidMetrics", () => {
+	test("collects and merges all metric samples", async () => {
+		const runner: CommandRunner = async (_cmd, args) => {
+			const fullCommand = args.join(" ");
+
+			if (fullCommand.includes("pidof")) {
+				return { stdout: "12345\n", stderr: "", exitCode: 0 };
+			}
+			if (fullCommand.includes("top")) {
+				return { stdout: TOP_OUTPUT, stderr: "", exitCode: 0 };
+			}
+			if (fullCommand.includes("meminfo")) {
+				return { stdout: MEMINFO_OUTPUT, stderr: "", exitCode: 0 };
+			}
+			if (fullCommand.includes("gfxinfo")) {
+				return { stdout: GFXINFO_OUTPUT, stderr: "", exitCode: 0 };
+			}
+
+			return { stdout: "", stderr: "", exitCode: 1 };
+		};
+
+		const session = await collectAndroidMetrics(runner, MOCK_DEVICE, "com.example.app", 5);
+
+		expect(session.device).toBe(MOCK_DEVICE);
+		expect(session.platform).toBe("android");
+		expect(session.duration).toBe(5);
+		expect(typeof session.startedAt).toBe("number");
+
+		// Should have: 1 CPU sample (from top), 1 MEMORY (from meminfo), 1 UI_FPS + 1 FRAME_DROPS (from gfxinfo)
+		const cpuSamples = session.samples.filter((s) => s.type === MetricType.CPU);
+		const memorySamples = session.samples.filter((s) => s.type === MetricType.MEMORY);
+		const fpsSamples = session.samples.filter((s) => s.type === MetricType.UI_FPS);
+		const dropSamples = session.samples.filter((s) => s.type === MetricType.FRAME_DROPS);
+
+		expect(cpuSamples.length).toBeGreaterThanOrEqual(1);
+		expect(memorySamples).toHaveLength(1);
+		expect(fpsSamples).toHaveLength(1);
+		expect(dropSamples).toHaveLength(1);
+	});
+
+	test("throws when PID is not found", async () => {
+		const runner: CommandRunner = async () => ({
+			stdout: "",
+			stderr: "",
+			exitCode: 1,
+		});
+
+		expect(collectAndroidMetrics(runner, MOCK_DEVICE, "com.nonexistent.app", 5)).rejects.toThrow(
+			/Process not found/,
+		);
+	});
+
+	test("returns session with empty samples when commands fail", async () => {
+		const runner: CommandRunner = async (_cmd, args) => {
+			const fullCommand = args.join(" ");
+
+			if (fullCommand.includes("pidof")) {
+				return { stdout: "12345\n", stderr: "", exitCode: 0 };
+			}
+
+			// All other commands fail
+			return { stdout: "", stderr: "error", exitCode: 1 };
+		};
+
+		const session = await collectAndroidMetrics(runner, MOCK_DEVICE, "com.example.app", 5);
+		expect(session.samples).toEqual([]);
+		expect(session.platform).toBe("android");
+	});
+
+	test("passes correct adb arguments for each command", async () => {
+		const capturedCalls: { cmd: string; args: string[] }[] = [];
+
+		const runner: CommandRunner = async (cmd, args) => {
+			capturedCalls.push({ cmd, args: [...args] });
+			const fullCommand = args.join(" ");
+
+			if (fullCommand.includes("pidof")) {
+				return { stdout: "12345\n", stderr: "", exitCode: 0 };
+			}
+			return { stdout: "", stderr: "", exitCode: 1 };
+		};
+
+		await collectAndroidMetrics(runner, MOCK_DEVICE, "com.example.app", 10);
+
+		// First call is pidof
+		const pidCall = capturedCalls[0];
+		expect(pidCall.cmd).toBe("adb");
+		expect(pidCall.args).toContain("-s");
+		expect(pidCall.args).toContain("emulator-5554");
+
+		// Should have top, meminfo, gfxinfo calls
+		const topCall = capturedCalls.find((c) => c.args.includes("top"));
+		expect(topCall).toBeDefined();
+		expect(topCall?.args).toContain("-p");
+		expect(topCall?.args).toContain("12345");
+		expect(topCall?.args).toContain("-n");
+		expect(topCall?.args).toContain("10");
+
+		const meminfoCall = capturedCalls.find((c) => c.args.includes("meminfo"));
+		expect(meminfoCall).toBeDefined();
+		expect(meminfoCall?.args).toContain("com.example.app");
+
+		const gfxinfoCall = capturedCalls.find((c) => c.args.includes("gfxinfo"));
+		expect(gfxinfoCall).toBeDefined();
+		expect(gfxinfoCall?.args).toContain("com.example.app");
+	});
+
+	test("includes descriptive error message when process not found", async () => {
+		const runner: CommandRunner = async () => ({
+			stdout: "",
+			stderr: "",
+			exitCode: 1,
+		});
+
+		try {
+			await collectAndroidMetrics(runner, MOCK_DEVICE, "com.example.app", 5);
+			expect(true).toBe(false); // Should not reach here
+		} catch (err) {
+			const msg = (err as Error).message;
+			expect(msg).toContain("com.example.app");
+			expect(msg).toContain("Pixel 6 API 33");
+			expect(msg).toContain("emulator-5554");
+		}
+	});
+});

package/src/collector.ts

@@ -0,0 +1,79 @@
+import type { CommandRunner, Device, MeasurementSession, MetricSample } from "@lanternajs/core";
+import { parseGfxinfoOutput } from "./parsers/gfxinfo";
+import { parseMeminfoOutput } from "./parsers/meminfo";
+import { parseTopOutput } from "./parsers/top";
+import { findAndroidPid } from "./process";
+
+/**
+ * Collect Android performance metrics for a given device and package.
+ *
+ * Runs adb commands to gather CPU (via top), memory (via dumpsys meminfo),
+ * and frame metrics (via dumpsys gfxinfo), then merges all samples into
+ * a single MeasurementSession.
+ */
+export async function collectAndroidMetrics(
+	runner: CommandRunner,
+	device: Device,
+	packageName: string,
+	duration: number,
+): Promise<MeasurementSession> {
+	const pid = await findAndroidPid(runner, device.id, packageName);
+	if (pid === null) {
+		throw new Error(
+			`Process not found: "${packageName}" is not running on device "${device.name}" (${device.id}). ` +
+				"Make sure the app is launched before profiling.",
+		);
+	}
+
+	const startedAt = Date.now();
+	const samples: MetricSample[] = [];
+
+	// Run all data collection in parallel
+	const [topResult, meminfoResult, gfxinfoResult] = await Promise.all([
+		runner("adb", [
+			"-s",
+			device.id,
+			"shell",
+			"top",
+			"-H",
+			"-d",
+			"1",
+			"-n",
+			String(duration),
+			"-p",
+			String(pid),
+		]),
+		runner("adb", ["-s", device.id, "shell", "dumpsys", "meminfo", packageName]),
+		runner("adb", ["-s", device.id, "shell", "dumpsys", "gfxinfo", packageName]),
+	]);
+
+	// Parse top output — may contain multiple snapshots separated by blank lines
+	if (topResult.exitCode === 0 && topResult.stdout) {
+		const snapshots = topResult.stdout.split(/\n\n+/);
+		for (let i = 0; i < snapshots.length; i++) {
+			const snapshotTimestamp = startedAt + i * 1000;
+			const parsed = parseTopOutput(snapshots[i], snapshotTimestamp);
+			samples.push(...parsed);
+		}
+	}
+
+	// Parse meminfo
+	if (meminfoResult.exitCode === 0 && meminfoResult.stdout) {
+		const parsed = parseMeminfoOutput(meminfoResult.stdout, startedAt);
+		samples.push(...parsed);
+	}
+
+	// Parse gfxinfo
+	if (gfxinfoResult.exitCode === 0 && gfxinfoResult.stdout) {
+		const parsed = parseGfxinfoOutput(gfxinfoResult.stdout, startedAt);
+		samples.push(...parsed);
+	}
+
+	return {
+		device,
+		platform: "android",
+		samples,
+		duration,
+		startedAt,
+	};
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { collectAndroidMetrics } from "./collector";
+export { parseGfxinfoOutput } from "./parsers/gfxinfo";
+export { parseMeminfoOutput } from "./parsers/meminfo";
+export { parseTopOutput } from "./parsers/top";
+export { findAndroidPid } from "./process";

package/src/parsers/gfxinfo.ts

@@ -0,0 +1,57 @@
+import { type MetricSample, MetricType } from "@lanternajs/core";
+
+/**
+ * Parse output from `adb shell dumpsys gfxinfo <package>`.
+ * Extracts janky frame percentage to calculate effective UI FPS and frame drop rate.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseGfxinfoOutput(output: string, timestamp: number): MetricSample[] {
+	if (!output || typeof output !== "string") {
+		return [];
+	}
+
+	const lines = output.split("\n");
+	let totalFrames: number | null = null;
+	let jankyFrames: number | null = null;
+	let jankyPercent: number | null = null;
+
+	for (const line of lines) {
+		const totalMatch = line.match(/Total frames rendered:\s*([\d]+)/);
+		if (totalMatch) {
+			totalFrames = Number.parseInt(totalMatch[1], 10);
+		}
+
+		// "Janky frames: 75 (5.00%)"
+		const jankyMatch = line.match(/Janky frames:\s*([\d]+)\s*\(([\d.]+)%\)/);
+		if (jankyMatch) {
+			jankyFrames = Number.parseInt(jankyMatch[1], 10);
+			jankyPercent = Number.parseFloat(jankyMatch[2]);
+		}
+	}
+
+	if (totalFrames === null || jankyFrames === null || jankyPercent === null) {
+		return [];
+	}
+
+	if (Number.isNaN(totalFrames) || Number.isNaN(jankyPercent)) {
+		return [];
+	}
+
+	// Calculate effective FPS: 60 * (1 - jankyPercent/100)
+	const actualFps = 60 * (1 - jankyPercent / 100);
+
+	return [
+		{
+			type: MetricType.UI_FPS,
+			value: Math.round(actualFps * 100) / 100,
+			timestamp,
+			unit: "fps",
+		},
+		{
+			type: MetricType.FRAME_DROPS,
+			value: jankyPercent,
+			timestamp,
+			unit: "%",
+		},
+	];
+}

package/src/parsers/meminfo.ts

@@ -0,0 +1,38 @@
+import { type MetricSample, MetricType } from "@lanternajs/core";
+
+/**
+ * Parse output from `adb shell dumpsys meminfo <package>`.
+ * Extracts TOTAL Pss Total and converts KB to MB.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseMeminfoOutput(output: string, timestamp: number): MetricSample[] {
+	if (!output || typeof output !== "string") {
+		return [];
+	}
+
+	const lines = output.split("\n");
+
+	for (const line of lines) {
+		// Look for the TOTAL line — format: "  TOTAL   120000   100000  ..."
+		const match = line.match(/^\s*TOTAL\s+([\d]+)/);
+		if (match) {
+			const pssKb = Number.parseInt(match[1], 10);
+			if (Number.isNaN(pssKb)) {
+				return [];
+			}
+
+			const pssMb = pssKb / 1024;
+
+			return [
+				{
+					type: MetricType.MEMORY,
+					value: Math.round(pssMb * 100) / 100,
+					timestamp,
+					unit: "MB",
+				},
+			];
+		}
+	}
+
+	return [];
+}

package/src/parsers/top.ts

@@ -0,0 +1,51 @@
+import { type MetricSample, MetricType } from "@lanternajs/core";
+
+/**
+ * Parse output from `adb shell top -H -d 1 -p <pid>`.
+ * Sums all thread CPU percentages to produce a single CPU sample.
+ * Never throws — returns empty array on malformed input.
+ */
+export function parseTopOutput(output: string, timestamp: number): MetricSample[] {
+	if (!output || typeof output !== "string") {
+		return [];
+	}
+
+	const lines = output.split("\n");
+	let totalCpu = 0;
+	let foundAny = false;
+
+	for (const line of lines) {
+		// Match data lines: PID TID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ THREAD
+		// The CPU column contains a value like "25.0" and is preceded by a single-char state (S/R/D/Z/T)
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("Tasks:") || trimmed.startsWith("PID")) {
+			continue;
+		}
+
+		// Try to extract CPU percentage from process lines
+		// Format: PID TID USER PR NI VIRT RES SHR S[%CPU] %MEM TIME+ THREAD
+		const match = trimmed.match(
+			/^\s*\d+\s+\d+\s+\S+\s+\d+\s+[-\d]+\s+\S+\s+\S+\s+\S+\s+[SRDZT]\s+([\d.]+)/,
+		);
+		if (match) {
+			const cpu = Number.parseFloat(match[1]);
+			if (!Number.isNaN(cpu)) {
+				totalCpu += cpu;
+				foundAny = true;
+			}
+		}
+	}
+
+	if (!foundAny) {
+		return [];
+	}
+
+	return [
+		{
+			type: MetricType.CPU,
+			value: totalCpu,
+			timestamp,
+			unit: "%",
+		},
+	];
+}

package/src/process.ts

@@ -0,0 +1,28 @@
+import type { CommandRunner } from "@lanternajs/core";
+
+/**
+ * Find the PID of a running Android app by package name.
+ * Returns null if the process is not found or on error.
+ */
+export async function findAndroidPid(
+	runner: CommandRunner,
+	deviceId: string,
+	packageName: string,
+): Promise<number | null> {
+	try {
+		const result = await runner("adb", ["-s", deviceId, "shell", "pidof", packageName]);
+
+		if (result.exitCode !== 0 || !result.stdout.trim()) {
+			return null;
+		}
+
+		const pid = Number.parseInt(result.stdout.trim(), 10);
+		if (Number.isNaN(pid)) {
+			return null;
+		}
+
+		return pid;
+	} catch {
+		return null;
+	}
+}