@8bitbish/screenshot-service 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# @8bitbish/screenshot-service
+
+Take screenshots and fetch screen recordings from a connected iPhone or Android device, straight to your Mac as a `Buffer`. Works over USB or WiFi. No cloud, no Shortcuts, no tapping the phone.
+
+---
+
+## Install
+
+```bash
+npm install @8bitbish/screenshot-service
+```
+
+---
+
+## One-time machine setup
+
+Each computer needs Python + pymobiledevice3 (for iOS) and/or ADB (for Android). Run the relevant setup once per machine:
+
+```bash
+npx @8bitbish/screenshot-service setup-ios      # iOS
+npx @8bitbish/screenshot-service setup-android  # Android
+```
+
+These walk you through everything: Homebrew installs, device trust/pairing, and (for iOS) an optional passwordless-sudo grant for the tunnel daemon. **Installing the npm package itself is silent and side-effect-free** — no prompts on `npm install`.
+
+Test it:
+
+```bash
+npx @8bitbish/screenshot-service test-ios
+npx @8bitbish/screenshot-service test-android
+```
+
+---
+
+## Usage
+
+```typescript
+import {
+  triggerPhoneScreenshot,
+  triggerAndroidScreenshot,
+  fetchLatestPhoneRecording,
+  fetchLatestAndroidRecording,
+  startTunnel,
+} from '@8bitbish/screenshot-service'
+import * as fs from 'fs'
+
+// iOS — start tunnel once at app launch (no-op if already running)
+await startTunnel()
+
+const ios = await triggerPhoneScreenshot({ includeLocation: true })
+fs.writeFileSync('iphone.png', ios.image)
+// ios.device.{model, name, iosVersion}
+// ios.foregroundApp.{bundleId, name, version}  // null if undetected
+// ios.location.{city, country, latitude, longitude}  // null unless includeLocation
+
+// Android — no tunnel needed
+const android = await triggerAndroidScreenshot({ includeLocation: true })
+fs.writeFileSync('android.png', android.image)
+// android.device.{model, name, androidVersion, softwareVersion}
+// same foregroundApp + location shape as iOS
+
+// Fetch the latest video recording (user records on device, then call this)
+const rec = await fetchLatestPhoneRecording({ waitForNew: true, waitTimeout: 120_000 })
+fs.writeFileSync('recording.mov', rec.video)
+```
+
+---
+
+## API
+
+```typescript
+triggerPhoneScreenshot(opts?: {
+  timeout?: number          // default 30000
+  includeLocation?: boolean // default false
+}): Promise<ScreenshotResult>
+
+triggerAndroidScreenshot(opts?: {
+  timeout?: number
+  includeLocation?: boolean
+}): Promise<AndroidScreenshotResult>
+
+fetchLatestPhoneRecording(opts?: {
+  waitForNew?: boolean      // poll until a new video appears (user records then stops)
+  waitTimeout?: number      // default 300000 (5 min)
+  timeout?: number
+  includeLocation?: boolean
+}): Promise<PhoneRecordingResult>
+
+fetchLatestAndroidRecording(opts?: {
+  waitForNew?: boolean
+  waitTimeout?: number
+  timeout?: number
+  includeLocation?: boolean
+}): Promise<AndroidRecordingResult>
+
+// iOS tunnel control (Android needs no tunnel — ADB handles it)
+startTunnel(): Promise<void>     // requires sudo; no-op if already running
+isTunnelRunning(): boolean
+stopTunnel(): void
+```
+
+All result objects share the shape:
+
+```typescript
+{
+  image?: Buffer    // present on screenshot results
+  video?: Buffer    // present on recording results
+  device: { ...platform-specific fields }
+  foregroundApp: { bundleId, name, version } | null
+  capturedAt: Date
+  location: { city, country, latitude, longitude, source } | null
+}
+```
+
+---
+
+## How it works
+
+**iOS** — A background tunnel (`pymobiledevice3 remote tunneld`) connects Mac ↔ iPhone over Apple's RemoteXPC/RSD protocol (iOS 17+). The tunnel needs root; setup-ios offers a passwordless-sudo rule for just this command so you're not prompted every session. Screenshots use the DVT screenshot service; recordings are pulled directly from the Camera Roll via AFC.
+
+**Android** — Uses ADB. Screenshots via `adb exec-out screencap -p`. Recordings are pulled from MediaStore via `adb pull`. Wireless connections auto-reconnect to the last known IP, so a Mac reboot doesn't break things (as long as Wireless Debugging is still toggled ON on the phone).
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Python 3.11+ with pymobiledevice3 not found` | `npx @8bitbish/screenshot-service setup-ios` |
+| `adb not found` | `npx @8bitbish/screenshot-service setup-android` |
+| `No Android device found` after Mac reboot | The package auto-reconnects to the last wireless IP. If it still fails, check Settings → Developer Options → Wireless Debugging is ON on the phone. |
+| iOS screenshot fails repeatedly | Make sure the iPhone is unlocked and trusted with this Mac |
+| Tunnel dies after Mac sleeps | Next `triggerPhoneScreenshot()` call restarts it automatically |
+
+---
+
+## Requirements
+
+- macOS (uses Homebrew, AFC, ADB)
+- Node.js 18+
+- iOS 17+ for iPhone support
+- Android 10+ for Android support (Wireless Debugging requires Android 11+)

package/bin/setup.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execSync, execFileSync, spawnSync } = require('child_process');
+const { writeFileSync, unlinkSync, existsSync } = require('fs');
+const { tmpdir, homedir } = require('os');
+const path = require('path');
+const readline = require('readline');
+
+// ── ANSI colours ──────────────────────────────────────────────────────────────
+const C = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+};
+
+function log(s)   { console.log(s); }
+function ok(s)    { console.log(C.green  + '✓ ' + s + C.reset); }
+function warn(s)  { console.log(C.yellow + '⚠  ' + s + C.reset); }
+function fail(s)  { console.log(C.red    + '✗ ' + s + C.reset); }
+function step(n, t) { console.log('\n' + C.bold + C.cyan + 'Step ' + n + ':' + C.reset + ' ' + t + '\n'); }
+function divider() { console.log(C.dim + '──────────────────────────────────────────────────────────────────' + C.reset); }
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(C.bold + question + C.reset + ' ', a => { rl.close(); resolve(a.trim()); }));
+}
+
+// ── Shared helpers ────────────────────────────────────────────────────────────
+function which(bin) {
+  try { return execSync(`command -v ${bin}`, { encoding: 'utf8' }).trim(); } catch { return ''; }
+}
+
+function findPython() {
+  const candidates = [
+    '/opt/homebrew/bin/python3.14', '/opt/homebrew/bin/python3.13',
+    '/opt/homebrew/bin/python3.12', '/opt/homebrew/bin/python3.11',
+    '/usr/local/bin/python3.14',    '/usr/local/bin/python3.13',
+    '/usr/local/bin/python3.12',    '/usr/local/bin/python3.11',
+    'python3',
+  ];
+  const probe = 'import sys, pymobiledevice3; sys.exit(0 if sys.version_info >= (3, 11) else 1)';
+  for (const p of candidates) {
+    try { execFileSync(p, ['-c', probe], { stdio: 'ignore' }); return p; } catch {}
+  }
+  return null;
+}
+
+function findAdb() {
+  for (const p of ['/opt/homebrew/bin/adb', '/usr/local/bin/adb', 'adb']) {
+    try { execFileSync(p, ['version'], { stdio: 'ignore' }); return p; } catch {}
+  }
+  return null;
+}
+
+function findBrewPython() {
+  // Find any Homebrew-installed python3.x (x ≥ 11), preferring newer
+  for (const v of ['3.14', '3.13', '3.12', '3.11']) {
+    for (const dir of ['/opt/homebrew/bin', '/usr/local/bin']) {
+      const p = path.join(dir, 'python' + v);
+      try { execFileSync(p, ['--version'], { stdio: 'ignore' }); return p; } catch {}
+    }
+  }
+  return null;
+}
+
+// ── iOS setup ─────────────────────────────────────────────────────────────────
+async function runSetupIos() {
+  console.log('');
+  console.log(C.bold + '📱 screenshot-service — iOS setup' + C.reset);
+  divider();
+
+  // Homebrew
+  step(1, 'Homebrew');
+  if (!which('brew')) {
+    fail('Homebrew not found. Install from https://brew.sh and run this again.');
+    process.exit(1);
+  }
+  ok('Homebrew found');
+
+  // Python 3.11+
+  step(2, 'Python 3.11+ with pymobiledevice3');
+  let python = findPython();
+  if (python) {
+    ok('Found ' + python);
+  } else {
+    let py = findBrewPython();
+    if (!py) {
+      log('Installing python@3.13 via Homebrew...');
+      execSync('brew install python@3.13', { stdio: 'inherit' });
+      py = findBrewPython();
+    }
+    if (!py) { fail('Python install failed.'); process.exit(1); }
+    log('Installing pymobiledevice3 into ' + py + '...');
+    // pip3.x ships alongside python3.x in Homebrew
+    const pip = py.replace(/python(3\.\d+)$/, 'pip$1');
+    execSync(`"${pip}" install --break-system-packages pymobiledevice3`, { stdio: 'inherit' });
+    python = findPython();
+    if (!python) { fail('pymobiledevice3 install failed.'); process.exit(1); }
+    ok('Installed: ' + python);
+  }
+
+  // Sudoers (opt-in)
+  step(3, 'Passwordless tunnel (optional)');
+  console.log('  The iPhone screenshot tunnel runs under sudo. You can either:');
+  console.log('  • ' + C.bold + 'Grant passwordless sudo' + C.reset + ' for this specific command (recommended for convenience)');
+  console.log('  • Skip — you will be prompted for your password once per terminal session');
+  console.log('');
+  const ans = await prompt('Grant passwordless sudo for the tunnel daemon only? [y/N]');
+  if (/^[yY]/.test(ans)) {
+    const username = execSync('whoami').toString().trim();
+    const rule = `${username} ALL=(ALL) NOPASSWD: ${python} -m pymobiledevice3 remote tunneld`;
+    const sudoersFile = '/etc/sudoers.d/screenshot-service';
+    const scriptPath = path.join(tmpdir(), 'screenshot-service-setup.sh');
+    writeFileSync(scriptPath, [
+      '#!/bin/bash',
+      `printf '%s\\n' '${rule}' > '${sudoersFile}'`,
+      `chmod 440 '${sudoersFile}'`,
+    ].join('\n'), { mode: 0o755 });
+    try {
+      execSync(`osascript -e 'do shell script "${scriptPath}" with administrator privileges'`, { stdio: 'pipe' });
+      ok('Passwordless tunnel configured');
+    } catch {
+      warn('Sudoers setup cancelled — you will be prompted for your password each session.');
+    } finally {
+      try { unlinkSync(scriptPath); } catch {}
+    }
+  } else {
+    log(C.dim + '  Skipped. You will be prompted for your Mac password the first time per session.' + C.reset);
+  }
+
+  // Device instructions
+  step(4, 'On your iPhone (one-time setup)');
+  console.log('  1. Settings → search ' + C.yellow + '"Developer Mode"' + C.reset + ' → toggle ON → iPhone restarts → confirm');
+  console.log('  2. Plug iPhone in via USB → tap ' + C.yellow + 'Trust' + C.reset + ' when prompted');
+  console.log('  3. (Optional, for wireless) Finder → select iPhone → tick ' + C.yellow + '"Show this iPhone when on Wi-Fi"' + C.reset);
+  console.log('');
+  await prompt('Press Enter when done...');
+
+  divider();
+  console.log('');
+  console.log(C.bold + C.green + 'Done!' + C.reset + ' Test it with: ' + C.cyan + 'npx @8bitbish/screenshot-service test-ios' + C.reset);
+  console.log('');
+}
+
+// ── Android setup ─────────────────────────────────────────────────────────────
+async function runSetupAndroid() {
+  console.log('');
+  console.log(C.bold + '📱 screenshot-service — Android setup' + C.reset);
+  divider();
+
+  // ADB
+  step(1, 'ADB (Android Debug Bridge)');
+  let adb = findAdb();
+  if (adb) {
+    const ver = execFileSync(adb, ['version']).toString().split('\n')[0];
+    ok('Found ' + adb + ' — ' + ver);
+  } else {
+    if (!which('brew')) {
+      fail('Homebrew not found. Install from https://brew.sh and run this again.');
+      process.exit(1);
+    }
+    log('Installing android-platform-tools via Homebrew...');
+    execSync('brew install android-platform-tools', { stdio: 'inherit' });
+    adb = findAdb();
+    if (!adb) { fail('adb install failed.'); process.exit(1); }
+    ok('Installed: ' + adb);
+  }
+
+  // Developer Options
+  step(2, 'Enable Developer Options on your Android phone');
+  console.log('  1. Open ' + C.bold + 'Settings' + C.reset);
+  console.log('  2. Scroll to ' + C.bold + 'About Phone' + C.reset);
+  console.log('  3. Tap ' + C.bold + 'Build Number' + C.reset + ' seven times');
+  console.log('  4. You should see ' + C.cyan + '"You are now a developer!"' + C.reset);
+  console.log('');
+  await prompt('Press Enter when done (skip if already enabled)...');
+
+  // Connection
+  step(3, 'Connection type');
+  console.log('  ' + C.bold + 'A) USB cable' + C.reset + '    — plug in once, works every time');
+  console.log('  ' + C.bold + 'B) Wireless' + C.reset + '     — one-time pairing, then no cable needed (Android 11+)');
+  console.log('');
+  const choice = await prompt('Choose [A/B]:');
+
+  if (/^[Aa]/.test(choice)) {
+    console.log('');
+    console.log('  Settings → Developer Options → turn on ' + C.bold + 'USB Debugging' + C.reset);
+    console.log('  Plug your phone into the Mac via USB. Tap ' + C.bold + 'Allow' + C.reset + ' on the phone.');
+    console.log('');
+    await prompt('Press Enter once connected...');
+  } else {
+    console.log('');
+    console.log('  Settings → Developer Options → turn on ' + C.bold + 'Wireless Debugging' + C.reset);
+    console.log('  Tap ' + C.bold + 'Pair device with pairing code' + C.reset + ' (note IP, port, and 6-digit code).');
+    console.log('');
+    const pairIp   = await prompt('  IP address shown on phone (e.g. 192.168.1.50):');
+    const pairPort = await prompt('  Port shown on pairing screen (e.g. 39847):');
+    console.log('');
+    console.log('  Running: ' + C.cyan + `adb pair ${pairIp}:${pairPort}` + C.reset);
+    console.log('  ' + C.dim + '(enter the 6-digit code when prompted)' + C.reset);
+    console.log('');
+    spawnSync(adb, ['pair', `${pairIp}:${pairPort}`], { stdio: 'inherit' });
+
+    console.log('');
+    console.log('  Now go back to the main ' + C.bold + 'Wireless Debugging' + C.reset + ' screen (different port).');
+    const connIp = await prompt('  IP address (same as before, e.g. 192.168.1.50):');
+    console.log('');
+    log('Connecting...');
+    spawnSync(adb, ['connect', `${connIp}:5555`], { stdio: 'inherit' });
+  }
+
+  // Verify
+  console.log('');
+  const out = execFileSync(adb, ['devices']).toString();
+  if (!/\tdevice/.test(out)) {
+    fail('No authorised device found. Check the connection and try again.');
+    process.exit(1);
+  }
+  ok('Device connected');
+  out.split('\n').slice(1).filter(l => l.includes('\tdevice')).forEach(l => log('  ' + l));
+
+  divider();
+  console.log('');
+  console.log(C.bold + C.green + 'Done!' + C.reset + ' Test it with: ' + C.cyan + 'npx @8bitbish/screenshot-service test-android' + C.reset);
+  console.log('');
+}
+
+// ── Test commands ─────────────────────────────────────────────────────────────
+async function runTestIos() {
+  const { triggerPhoneScreenshot } = require('..');
+  const fs = require('fs');
+  const out = path.join(homedir(), 'Desktop', 'iphone-screenshot.png');
+  console.log('Taking iPhone screenshot...');
+  try {
+    const r = await triggerPhoneScreenshot({ includeLocation: true });
+    fs.writeFileSync(out, r.image);
+    ok('Saved → Desktop/iphone-screenshot.png');
+    log('  Device : ' + r.device.name + ' (' + r.device.model + ')');
+    log('  iOS    : ' + r.device.iosVersion);
+    if (r.foregroundApp) {
+      const v = r.foregroundApp.version ? ' v' + r.foregroundApp.version : '';
+      log('  App    : ' + r.foregroundApp.name + v + ' (' + r.foregroundApp.bundleId + ')');
+    }
+    if (r.location) log('  Place  : ' + r.location.city + ', ' + r.location.country);
+    spawnSync('open', [out]);
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+}
+
+async function runTestAndroid() {
+  const { triggerAndroidScreenshot } = require('..');
+  const fs = require('fs');
+  const out = path.join(homedir(), 'Desktop', 'android-screenshot.png');
+  console.log('Taking Android screenshot...');
+  try {
+    const r = await triggerAndroidScreenshot({ includeLocation: true });
+    fs.writeFileSync(out, r.image);
+    ok('Saved → Desktop/android-screenshot.png');
+    log('  Device   : ' + r.device.name + ' (' + r.device.model + ')');
+    log('  Software : ' + r.device.softwareVersion);
+    if (r.foregroundApp) {
+      const v = r.foregroundApp.version ? ' v' + r.foregroundApp.version : '';
+      log('  App      : ' + r.foregroundApp.name + v + ' (' + r.foregroundApp.bundleId + ')');
+    }
+    if (r.location) log('  Place    : ' + r.location.city + ', ' + r.location.country);
+    spawnSync('open', [out]);
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log('');
+  console.log(C.bold + '@8bitbish/screenshot-service' + C.reset);
+  console.log('');
+  console.log('Usage: ' + C.cyan + 'npx @8bitbish/screenshot-service <command>' + C.reset);
+  console.log('');
+  console.log('Commands:');
+  console.log('  ' + C.bold + 'setup-ios' + C.reset + '       Install iOS deps (Python + pymobiledevice3) and guide device trust');
+  console.log('  ' + C.bold + 'setup-android' + C.reset + '   Install ADB and guide device pairing');
+  console.log('  ' + C.bold + 'test-ios' + C.reset + '        Take a test iPhone screenshot (saved to Desktop)');
+  console.log('  ' + C.bold + 'test-android' + C.reset + '    Take a test Android screenshot (saved to Desktop)');
+  console.log('');
+}
+
+(async () => {
+  const cmd = process.argv[2];
+  switch (cmd) {
+    case 'setup-ios':     return runSetupIos();
+    case 'setup-android': return runSetupAndroid();
+    case 'test-ios':      return runTestIos();
+    case 'test-android':  return runTestAndroid();
+    default:              printHelp();
+  }
+})().catch(err => {
+  fail(err.message || String(err));
+  process.exit(1);
+});

package/dist/android-device.d.ts

@@ -0,0 +1,10 @@
+import type { ForegroundApp } from "./device";
+export interface AndroidDeviceInfo {
+    model: string;
+    name: string;
+    androidVersion: string;
+    softwareVersion: string;
+}
+export declare function getAndroidDeviceInfo(adb: string): Promise<AndroidDeviceInfo>;
+export declare function getAndroidForegroundApp(adb: string): Promise<ForegroundApp | null>;
+//# sourceMappingURL=android-device.d.ts.map

package/dist/android-device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"android-device.d.ts","sourceRoot":"","sources":["../android-device.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;CACxB;AA4DD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwBlF;AAuDD,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA0BxF"}

package/dist/android-device.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAndroidDeviceInfo = getAndroidDeviceInfo;
+exports.getAndroidForegroundApp = getAndroidForegroundApp;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+// Samsung model number prefix → marketing name
+// Strip regional suffix (e.g. SM-S918B → SM-S918) then look up
+const SAMSUNG_MODELS = {
+    // S25
+    "SM-S938": "Galaxy S25 Ultra", "SM-S936": "Galaxy S25+", "SM-S931": "Galaxy S25",
+    // S24
+    "SM-S928": "Galaxy S24 Ultra", "SM-S926": "Galaxy S24+", "SM-S921": "Galaxy S24",
+    "SM-S721": "Galaxy S24 FE",
+    // S23
+    "SM-S918": "Galaxy S23 Ultra", "SM-S916": "Galaxy S23+", "SM-S911": "Galaxy S23",
+    "SM-S711": "Galaxy S23 FE",
+    // S22
+    "SM-S908": "Galaxy S22 Ultra", "SM-S906": "Galaxy S22+", "SM-S901": "Galaxy S22",
+    // S21
+    "SM-G998": "Galaxy S21 Ultra", "SM-G996": "Galaxy S21+", "SM-G991": "Galaxy S21",
+    "SM-G990": "Galaxy S21 FE",
+    // S20
+    "SM-G988": "Galaxy S20 Ultra", "SM-G986": "Galaxy S20+", "SM-G981": "Galaxy S20",
+    "SM-G780": "Galaxy S20 FE",
+    // S10
+    "SM-G977": "Galaxy S10 5G", "SM-G975": "Galaxy S10+",
+    "SM-G973": "Galaxy S10", "SM-G970": "Galaxy S10e",
+    // Note
+    "SM-N986": "Galaxy Note 20 Ultra", "SM-N981": "Galaxy Note 20",
+    "SM-N976": "Galaxy Note 10+", "SM-N970": "Galaxy Note 10",
+    // Z Fold
+    "SM-F956": "Galaxy Z Fold 6", "SM-F946": "Galaxy Z Fold 5",
+    "SM-F936": "Galaxy Z Fold 4", "SM-F926": "Galaxy Z Fold 3",
+    // Z Flip
+    "SM-F741": "Galaxy Z Flip 6", "SM-F731": "Galaxy Z Flip 5",
+    "SM-F721": "Galaxy Z Flip 4", "SM-F711": "Galaxy Z Flip 3",
+    // A series
+    "SM-A556": "Galaxy A55 5G", "SM-A546": "Galaxy A54 5G",
+    "SM-A536": "Galaxy A53 5G", "SM-A526": "Galaxy A52 5G",
+    "SM-A346": "Galaxy A34 5G", "SM-A336": "Galaxy A33 5G",
+    "SM-A256": "Galaxy A25 5G", "SM-A156": "Galaxy A15 5G",
+};
+function samsungModelName(modelNumber) {
+    const base = modelNumber.match(/^(SM-[A-Z]\d{3})/)?.[1];
+    return base ? (SAMSUNG_MODELS[base] ?? null) : null;
+}
+function prop(adb, key) {
+    return execFileAsync(adb, ["shell", "getprop", key], { timeout: 5000 })
+        .then(r => r.stdout.trim())
+        .catch(() => "");
+}
+function formatOneUi(raw) {
+    const n = parseInt(raw, 10);
+    if (!n)
+        return null;
+    const major = Math.floor(n / 10000);
+    const minor = Math.floor((n % 10000) / 100);
+    const patch = n % 100;
+    return patch > 0 ? `One UI ${major}.${minor}.${patch}` : `One UI ${major}.${minor}`;
+}
+async function getAndroidDeviceInfo(adb) {
+    const [n1, n2, n3, n4, modelNumber, androidVersion, oneui, miui, emui] = await Promise.all([
+        prop(adb, "ro.product.marketname"), // Samsung (most firmware)
+        prop(adb, "ro.vendor.oem.model"), // Samsung alternative
+        prop(adb, "ro.product.vendor.marketname"), // Samsung alternative
+        prop(adb, "ro.config.marketing_name"), // Samsung alternative
+        prop(adb, "ro.product.model"), // raw model number fallback
+        prop(adb, "ro.build.version.release"),
+        prop(adb, "ro.build.version.oneui"), // Samsung: "80000" → One UI 8.0
+        prop(adb, "ro.miui.ui.version.name"), // Xiaomi: "MIUI 14"
+        prop(adb, "ro.build.version.emui"), // Huawei: "EmotionUI 12"
+    ]);
+    const name = n1 || n2 || n3 || n4 || samsungModelName(modelNumber) || modelNumber;
+    const model = modelNumber;
+    let softwareVersion;
+    if (oneui)
+        softwareVersion = formatOneUi(oneui) ?? `Android ${androidVersion}`;
+    else if (miui)
+        softwareVersion = miui;
+    else if (emui)
+        softwareVersion = emui;
+    else
+        softwareVersion = `Android ${androidVersion}`;
+    return { model, name, androidVersion, softwareVersion };
+}
+// Android 12+ doesn't expose app labels via ADB — use lookup for common apps,
+// then fall back to formatting the package name into something readable
+const KNOWN_APPS = {
+    "com.google.android.gm": "Gmail",
+    "com.google.android.apps.maps": "Google Maps",
+    "com.google.android.youtube": "YouTube",
+    "com.google.android.googlequicksearchbox": "Google",
+    "com.google.android.apps.photos": "Google Photos",
+    "com.google.android.keep": "Google Keep",
+    "com.google.android.apps.translate": "Google Translate",
+    "com.google.android.apps.messaging": "Messages",
+    "com.google.android.calendar": "Google Calendar",
+    "com.google.android.apps.chromecast.app": "Google Home",
+    "com.android.chrome": "Chrome",
+    "com.instagram.android": "Instagram",
+    "com.instagram.barcelona": "Threads",
+    "com.facebook.katana": "Facebook",
+    "com.facebook.orca": "Messenger",
+    "com.whatsapp": "WhatsApp",
+    "com.twitter.android": "X (Twitter)",
+    "com.snapchat.android": "Snapchat",
+    "com.tiktok.android": "TikTok",
+    "com.linkedin.android": "LinkedIn",
+    "com.Slack": "Slack",
+    "com.microsoft.teams": "Teams",
+    "com.microsoft.office.outlook": "Outlook",
+    "com.microsoft.office.word": "Word",
+    "com.microsoft.office.excel": "Excel",
+    "com.spotify.music": "Spotify",
+    "com.netflix.mediaclient": "Netflix",
+    "com.openai.chatgpt": "ChatGPT",
+    "com.amazon.mShop.android.shopping": "Amazon",
+    "com.ebay.mobile": "eBay",
+    "com.paypal.android.p2pmobile": "PayPal",
+    "com.ubercab": "Uber",
+    "com.ubercab.eats": "Uber Eats",
+    "com.deliveroo.orderapp": "Deliveroo",
+    "com.sec.android.app.camera": "Camera",
+    "com.sec.android.app.launcher": "Samsung Home",
+    "com.samsung.android.messaging": "Messages (Samsung)",
+    "com.samsung.android.calendar": "Calendar (Samsung)",
+};
+function resolveAppName(packageId) {
+    if (KNOWN_APPS[packageId])
+        return KNOWN_APPS[packageId];
+    // Heuristic: strip vendor prefix, skip generic segments, capitalise
+    const parts = packageId.split(".");
+    const skip = new Set(["android", "app", "mobile", "client", "com", "org", "net", "io"]);
+    const meaningful = parts.filter(p => !skip.has(p) && p.length > 2);
+    const segment = meaningful[meaningful.length - 1] ?? parts[parts.length - 1];
+    return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+async function getAndroidForegroundApp(adb) {
+    try {
+        // "dumpsys window windows" omits focus data on Android 12+ — use base "dumpsys window"
+        const { stdout } = await execFileAsync(adb, ["shell", "dumpsys", "window"], { timeout: 8000, maxBuffer: 20 * 1024 * 1024 });
+        // mFocusedWindow gives the cleanest format; mCurrentFocus is the fallback
+        const packageId = stdout.match(/mFocusedWindow=([^\s/]+)\//)?.[1] ??
+            stdout.match(/mCurrentFocus=Window\{[^}]+\s+([^\s/}]+)\//)?.[1];
+        if (!packageId || packageId === "null")
+            return null;
+        const { stdout: pkgOut } = await execFileAsync(adb, ["shell", "dumpsys", "package", packageId], { timeout: 8000, maxBuffer: 50 * 1024 * 1024 });
+        const versionName = pkgOut.match(/versionName=(\S+)/)?.[1] ?? null;
+        const versionCode = pkgOut.match(/versionCode=(\d+)/)?.[1] ?? null;
+        const version = versionName && versionCode ? `${versionName} (${versionCode})`
+            : versionName ?? versionCode ?? null;
+        const name = resolveAppName(packageId);
+        return { bundleId: packageId, name, version };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=android-device.js.map

package/dist/android-device.js.map

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

package/dist/device.d.ts

@@ -0,0 +1,18 @@
+export interface DeviceInfo {
+    model: string;
+    name: string;
+    iosVersion: string;
+}
+export interface ForegroundApp {
+    bundleId: string;
+    name: string;
+    version: string | null;
+}
+export declare function getDeviceInfo(python: string): Promise<DeviceInfo>;
+/**
+ * Returns the foreground app at time of call.
+ * Uses foregroundRunning flag from proclist; cross-references applist for version.
+ * Returns null if detection fails — this is best-effort.
+ */
+export declare function getForegroundApp(python: string): Promise<ForegroundApp | null>;
+//# sourceMappingURL=device.d.ts.map

package/dist/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../device.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AA+BD,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBvE;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAyBpF"}