device-shots 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,180 @@
+# device-shots
+
+A CLI tool that captures screenshots from running iOS simulators and Android emulators, then optionally frames iOS screenshots with device bezels. Built for developers who need store-ready screenshots without manual work.
+
+## What it does
+
+1. **Discovers devices** — Finds all running iOS simulators and Android emulators that have your app installed
+2. **Cleans up status bars** — Sets a uniform status bar (9:41, full battery, full signal) on all devices before capturing
+3. **Captures screenshots** — Takes screenshots from every discovered device in one go
+4. **Transparent Android status bar** — Automatically makes the Android status bar area transparent using ImageMagick
+5. **Frames iOS screenshots** — Wraps iOS screenshots in device bezels (iPhone/iPad frames) using [device-frames-core](https://pypi.org/project/device-frames-core/)
+6. **Organizes by screen size** — Saves screenshots into store-aligned size buckets (e.g. `6.9`, `6.7`, `phone`) instead of device names
+
+## Use cases
+
+- Generating App Store and Play Store screenshots across multiple device sizes at once
+- Keeping consistent, reproducible screenshot sets for your app listing
+- Automating screenshot capture in CI/CD pipelines
+- Quickly re-capturing screenshots after UI changes
+
+## Prerequisites
+
+### Required
+
+- **Node.js 18+**
+- **Xcode Command Line Tools** (for iOS) — provides `xcrun simctl`
+- **Android SDK** (for Android) — provides `adb`. The tool looks for it at `$ANDROID_HOME/platform-tools/adb` or `~/Library/Android/sdk/platform-tools/adb`
+
+### Optional
+
+- **ImageMagick** — needed to make Android status bars transparent. Install with `brew install imagemagick`
+- **Python 3** — needed for iOS screenshot framing. The tool auto-creates a virtual environment at `~/.device-shots/.venv` and installs `device-frames-core` and `Pillow` automatically on first use
+
+## Install
+
+```bash
+npm install -g device-shots
+```
+
+Or run directly with `npx`:
+
+```bash
+npx device-shots capture --bundle-id com.example.myapp
+```
+
+## Usage
+
+### Capture screenshots
+
+```bash
+# Interactive — prompts for screenshot name
+device-shots capture --bundle-id com.example.myapp
+
+# Non-interactive — provide name directly
+device-shots capture dashboard --bundle-id com.example.myapp
+
+# iOS only, custom output directory
+device-shots capture home -b com.example.myapp -p ios -o ./.store-assets
+
+# Skip framing
+device-shots capture login -b com.example.myapp --no-frame
+
+# Custom status bar time
+device-shots capture checkout -b com.example.myapp --time "10:30"
+```
+
+### Frame existing screenshots
+
+```bash
+# Frame all unframed iOS screenshots in ./.screenshots
+device-shots frame
+
+# Frame from a specific directory
+device-shots frame ./.my-screenshots
+
+# Re-frame everything (overwrite existing framed images)
+device-shots frame --force
+```
+
+### Initialize config
+
+```bash
+device-shots init
+```
+
+Creates a `.device-shotsrc.json` in the current directory so you don't have to pass `--bundle-id` every time:
+
+```json
+{
+  "bundleId": "com.example.myapp",
+  "output": "./.screenshots",
+  "platform": "both",
+  "time": "9:41",
+  "frame": true
+}
+```
+
+## Config file
+
+The tool uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig), so you can configure it in any of these ways:
+
+- `.device-shotsrc.json`
+- `.device-shotsrc.yaml`
+- `.device-shotsrc.js`
+- `device-shots.config.js`
+- `"device-shots"` key in `package.json`
+
+## Output structure
+
+Screenshots are organized by platform and screen size bucket, matching App Store and Play Store requirements:
+
+```
+.screenshots/
+├── ios/
+│   ├── 6.9/                          # iPhone 16 Pro Max
+│   │   ├── dashboard.png
+│   │   ├── dashboard_framed.png
+│   │   ├── settings.png
+│   │   └── settings_framed.png
+│   ├── 6.5/                          # iPhone 14 Plus, 13 Pro Max
+│   │   ├── dashboard.png
+│   │   └── dashboard_framed.png
+│   └── 6.3/                          # iPhone 16 Pro, 16, 15 Pro, 15
+│       └── ...
+├── android/
+│   └── phone/                        # Pixel 9 Pro, etc.
+│       ├── dashboard.png
+│       └── settings.png
+└── metadata.json
+```
+
+### Screen size buckets
+
+**iOS** — Maps to App Store Connect display size categories:
+
+| Bucket | Devices |
+|--------|---------|
+| `6.9` | iPhone 16 Pro Max, 16 Plus, 15 Pro Max, 15 Plus, 14 Pro Max |
+| `6.5` | iPhone 14 Plus, 13 Pro Max, 12 Pro Max, 11 Pro Max, XS Max |
+| `6.3` | iPhone 16 Pro, 16, 15 Pro, 15, 14 Pro |
+| `6.1` | iPhone 14, 13, 12, X, XS, 12 mini, 13 mini |
+| `5.5` | iPhone 8 Plus, 7 Plus |
+| `4.7` | iPhone SE (3rd/2nd), iPhone 8 |
+| `13` | iPad Pro 13", iPad Air 13" |
+| `11` | iPad Pro 11", iPad Air 11", iPad mini 6th gen |
+
+**Android** — Categorized by form factor:
+
+| Bucket | Criteria |
+|--------|----------|
+| `phone` | Shorter screen dimension < 1200px |
+| `tablet-7` | Shorter dimension 1200–1799px |
+| `tablet-10` | Shorter dimension 1800px+ |
+
+### metadata.json
+
+Tracks which physical device was used for each size bucket:
+
+```json
+{
+  "ios": {
+    "6.9": {
+      "device": "iPhone 16 Pro Max",
+      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+      "resolution": "1320x2868"
+    }
+  },
+  "android": {
+    "phone": {
+      "device": "Pixel 9 Pro",
+      "id": "emulator-5554",
+      "resolution": "1080x2340"
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -2,12 +2,19 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { writeFileSync, existsSync as existsSync5 } from "fs";
+import { writeFileSync as writeFileSync2, existsSync as existsSync5 } from "fs";
 import pc3 from "picocolors";
 import prompts2 from "prompts";
 
 // src/commands/capture.ts
-import { existsSync as existsSync4, mkdirSync, readdirSync as readdirSync2, renameSync } from "fs";
+import {
+  existsSync as existsSync4,
+  mkdirSync,
+  readdirSync as readdirSync2,
+  renameSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
 import { join as join4 } from "path";
 import { tmpdir } from "os";
 import { mkdtempSync } from "fs";
@@ -20,7 +27,7 @@ import { cosmiconfig } from "cosmiconfig";
 var MODULE_NAME = "device-shots";
 var DEFAULTS = {
   bundleId: "",
-  output: "./screenshots",
+  output: "./.screenshots",
   platform: "both",
   time: "9:41",
   frame: true
@@ -40,7 +47,7 @@ function createDefaultConfig(bundleId) {
   return JSON.stringify(
     {
       bundleId,
-      output: "./screenshots",
+      output: "./.screenshots",
       platform: "both",
       time: "9:41",
       frame: true
@@ -87,6 +94,55 @@ async function runOrFail(cmd, args, options) {
   return result.stdout ?? "";
 }
 
+// src/devices/screen-sizes.ts
+var IOS_RESOLUTION_MAP = {
+  // 6.9" — iPhone 16 Pro Max, 16 Plus, 15 Pro Max, 15 Plus, 14 Pro Max
+  "1320x2868": "6.9",
+  "1290x2796": "6.9",
+  "1260x2736": "6.9",
+  // 6.5" — iPhone 14 Plus, 13 Pro Max, 12 Pro Max, 11 Pro Max, XS Max, XR
+  "1284x2778": "6.5",
+  "1242x2688": "6.5",
+  // 6.3" — iPhone 16 Pro, 16, 15 Pro, 15, 14 Pro
+  "1206x2622": "6.3",
+  "1179x2556": "6.3",
+  // 6.1" — iPhone 14, 13, 13 Pro, 12, 12 Pro, X, XS, 11 Pro, 12 mini, 13 mini
+  "1170x2532": "6.1",
+  "1125x2436": "6.1",
+  "1080x2340": "6.1",
+  // 5.5" — iPhone 8 Plus, 7 Plus, 6s Plus
+  "1242x2208": "5.5",
+  // 4.7" — iPhone SE (3rd/2nd), iPhone 8, 7, 6s
+  "750x1334": "4.7",
+  // 4.0" — iPhone SE (1st), iPhone 5/5s/5c
+  "640x1136": "4.0",
+  "640x1096": "4.0",
+  // iPad 13" — iPad Pro 13" (M4/M3/M2/M1), iPad Air 13", iPad Pro 12.9" (older)
+  "2064x2752": "13",
+  "2048x2732": "13",
+  // iPad 11" — iPad Pro 11", iPad Air 11", iPad 10th gen, iPad mini 6th gen
+  "1488x2266": "11",
+  "1668x2420": "11",
+  "1668x2388": "11",
+  "1640x2360": "11",
+  // iPad 10.5" — iPad Pro 10.5", iPad Air 3rd gen, iPad 7th-9th gen
+  "1668x2224": "10.5",
+  // iPad 9.7" — iPad Pro 9.7", iPad Air 1-2, older iPad mini
+  "1536x2048": "9.7",
+  "1536x2008": "9.7"
+};
+function getIosScreenSize(width, height) {
+  const w = Math.min(width, height);
+  const h = Math.max(width, height);
+  return IOS_RESOLUTION_MAP[`${w}x${h}`] ?? `${w}x${h}`;
+}
+function getAndroidScreenSize(width, height) {
+  const shorter = Math.min(width, height);
+  if (shorter >= 1800) return "tablet-10";
+  if (shorter >= 1200) return "tablet-7";
+  return "phone";
+}
+
 // src/devices/ios.ts
 function sanitizeName(name) {
   return name.replace(/[ (),]/g, "_").replace(/[^A-Za-z0-9_-]/g, "");
@@ -115,17 +171,63 @@ async function discoverIosDevices(bundleId) {
         bundleId
       ]);
       if (container) {
+        const resolution = await getResolutionViaTestCapture(d.udid);
+        const screenSize = resolution ? getIosScreenSize(resolution.width, resolution.height) : sanitizeName(d.name);
         devices.push({
           platform: "ios",
           safeName: sanitizeName(d.name),
           captureId: d.udid,
-          displayName: d.name
+          displayName: d.name,
+          screenSize,
+          resolution: resolution ?? { width: 0, height: 0 }
         });
       }
     }
   }
   return devices;
 }
+async function getResolutionViaTestCapture(udid) {
+  try {
+    const tmpPath = `/tmp/device-shots-probe-${udid}.png`;
+    await runOrFail("xcrun", ["simctl", "io", udid, "screenshot", tmpPath]);
+    if (await commandExists("magick")) {
+      const { stdout } = await run("magick", [
+        "identify",
+        "-format",
+        "%wx%h",
+        tmpPath
+      ]);
+      const match = stdout.match(/(\d+)x(\d+)/);
+      await run("rm", ["-f", tmpPath]);
+      if (match) {
+        return {
+          width: parseInt(match[1], 10),
+          height: parseInt(match[2], 10)
+        };
+      }
+    } else {
+      const { stdout } = await run("sips", [
+        "-g",
+        "pixelWidth",
+        "-g",
+        "pixelHeight",
+        tmpPath
+      ]);
+      await run("rm", ["-f", tmpPath]);
+      const wMatch = stdout.match(/pixelWidth:\s*(\d+)/);
+      const hMatch = stdout.match(/pixelHeight:\s*(\d+)/);
+      if (wMatch && hMatch) {
+        return {
+          width: parseInt(wMatch[1], 10),
+          height: parseInt(hMatch[1], 10)
+        };
+      }
+    }
+    await run("rm", ["-f", tmpPath]);
+  } catch {
+  }
+  return null;
+}
 async function setIosStatusBar(time) {
   if (!await commandExists("xcrun")) return;
   await run("xcrun", [
@@ -164,6 +266,16 @@ async function captureIosScreenshot(udid, outputPath) {
 function sanitizeName2(name) {
   return name.replace(/[ (),]/g, "_").replace(/[^A-Za-z0-9_-]/g, "");
 }
+async function getAndroidResolution(serial) {
+  const adb = getAdbPath();
+  const { stdout } = await run(adb, ["-s", serial, "shell", "wm", "size"]);
+  const match = stdout.match(/(\d+)x(\d+)/);
+  if (!match) return null;
+  return {
+    width: parseInt(match[1], 10),
+    height: parseInt(match[2], 10)
+  };
+}
 async function discoverAndroidDevices(bundleId) {
   const adb = getAdbPath();
   const { stdout } = await run(adb, ["devices"]);
@@ -203,11 +315,15 @@ async function discoverAndroidDevices(bundleId) {
       avdName = model.trim();
     }
     const safeName = sanitizeName2(avdName) || serial;
+    const resolution = await getAndroidResolution(serial);
+    const screenSize = resolution ? getAndroidScreenSize(resolution.width, resolution.height) : "phone";
     devices.push({
       platform: "android",
       safeName,
       captureId: serial,
-      displayName: avdName || serial
+      displayName: avdName || serial,
+      screenSize,
+      resolution: resolution ?? { width: 0, height: 0 }
     });
   }
   return devices;
@@ -358,11 +474,11 @@ function getFramePyPath() {
     "Could not find vendored frame.py. Ensure the vendor/ directory is present."
   );
 }
-async function frameScreenshots(rawDir, framedDir, force = false) {
+async function frameScreenshots(inputDir, outputDir, force = false) {
   await ensureVenv();
   const framePy = getFramePyPath();
   const python = getVenvPython();
-  const args = [framePy, rawDir, framedDir];
+  const args = [framePy, inputDir, outputDir];
   if (force) {
     args.push("--force");
   }
@@ -370,22 +486,24 @@ async function frameScreenshots(rawDir, framedDir, force = false) {
   if (output) {
     process.stdout.write(output + "\n");
   }
-  const framedFiles = existsSync3(framedDir) ? readdirSync(framedDir).filter((f) => f.endsWith(".png")).length : 0;
-  const rawFiles = existsSync3(rawDir) ? readdirSync(rawDir).filter((f) => f.endsWith(".png")).length : 0;
+  const framedFiles = existsSync3(outputDir) ? readdirSync(outputDir).filter((f) => f.endsWith(".png")).length : 0;
+  const rawFiles = existsSync3(inputDir) ? readdirSync(inputDir).filter((f) => f.endsWith(".png")).length : 0;
   return { framed: framedFiles, skipped: rawFiles - framedFiles };
 }
 async function frameAllIosScreenshots(screenshotsDir, force = false) {
   const iosDir = join3(screenshotsDir, "ios");
   if (!existsSync3(iosDir)) return 0;
   let totalFramed = 0;
-  const deviceDirs = readdirSync(iosDir, { withFileTypes: true }).filter((d) => d.isDirectory());
-  for (const deviceDir of deviceDirs) {
-    const rawDir = join3(iosDir, deviceDir.name, "raw");
-    if (!existsSync3(rawDir)) continue;
-    const pngFiles = readdirSync(rawDir).filter((f) => f.endsWith(".png"));
+  const sizeDirs = readdirSync(iosDir, { withFileTypes: true }).filter(
+    (d) => d.isDirectory()
+  );
+  for (const sizeDir of sizeDirs) {
+    const dirPath = join3(iosDir, sizeDir.name);
+    const pngFiles = readdirSync(dirPath).filter(
+      (f) => f.endsWith(".png") && !f.includes("_framed")
+    );
     if (pngFiles.length === 0) continue;
-    const framedDir = join3(iosDir, deviceDir.name, "framed");
-    const { framed } = await frameScreenshots(rawDir, framedDir, force);
+    const { framed } = await frameScreenshots(dirPath, dirPath, force);
     totalFramed += framed;
   }
   return totalFramed;
@@ -418,18 +536,17 @@ async function captureCommand(options) {
 Detected ${devices.length} device(s) with ${bundleId}:`)
   );
   for (const device of devices) {
-    const deviceDir = join4(outputDir, device.platform, device.safeName);
-    const rawDir = join4(deviceDir, "raw");
-    if (existsSync4(rawDir)) {
-      const count = readdirSync2(rawDir).filter(
-        (f) => f.endsWith(".png")
+    const sizeDir = join4(outputDir, device.platform, device.screenSize);
+    if (existsSync4(sizeDir)) {
+      const count = readdirSync2(sizeDir).filter(
+        (f) => f.endsWith(".png") && !f.includes("_framed")
       ).length;
       console.log(
-        `  ${pc.dim(device.platform + "/")}${device.safeName} (${device.displayName}) - ${count} screenshot(s)`
+        `  ${pc.dim(device.platform + "/")}${device.screenSize} ${pc.dim("(" + device.displayName + ")")} - ${count} screenshot(s)`
       );
     } else {
       console.log(
-        `  ${pc.dim(device.platform + "/")}${device.safeName} (${device.displayName}) - ${pc.green("new")}`
+        `  ${pc.dim(device.platform + "/")}${device.screenSize} ${pc.dim("(" + device.displayName + ")")} - ${pc.green("new")}`
       );
     }
   }
@@ -458,9 +575,8 @@ Detected ${devices.length} device(s) with ${bundleId}:`)
   const existingFile = join4(
     outputDir,
     firstDevice.platform,
-    firstDevice.safeName,
-    "raw",
-    `${screenshotName}_${firstDevice.safeName}.png`
+    firstDevice.screenSize,
+    `${screenshotName}.png`
   );
   if (existsSync4(existingFile)) {
     const response = await prompts({
@@ -492,10 +608,12 @@ Detected ${devices.length} device(s) with ${bundleId}:`)
   console.log("");
   const captured = [];
   for (const device of devices) {
-    const filename = `${screenshotName}_${device.safeName}.png`;
-    const tmpPath = join4(tmpDir, filename);
+    const filename = `${screenshotName}.png`;
+    const tmpPath = join4(tmpDir, `${device.platform}_${device.screenSize}_${filename}`);
     const icon = device.platform === "ios" ? "iOS" : "Android";
-    const s = ora(`${icon}: Capturing from ${device.displayName}...`).start();
+    const s = ora(
+      `${icon}: Capturing from ${device.displayName}...`
+    ).start();
     let success = false;
     if (device.platform === "ios") {
       success = await captureIosScreenshot(device.captureId, tmpPath);
@@ -514,25 +632,21 @@ Detected ${devices.length} device(s) with ${bundleId}:`)
     if (success) {
       captured.push({
         platform: device.platform,
-        safeName: device.safeName,
+        screenSize: device.screenSize,
         filename,
         tmpPath
       });
-      s.succeed(`${icon}: ${device.displayName}`);
+      s.succeed(`${icon}: ${device.screenSize} (${device.displayName})`);
     } else {
       s.fail(`${icon}: Failed to capture from ${device.displayName}`);
     }
   }
   for (const file of captured) {
-    const destDir = join4(outputDir, file.platform, file.safeName, "raw");
+    const destDir = join4(outputDir, file.platform, file.screenSize);
     mkdirSync(destDir, { recursive: true });
-    if (file.platform === "ios") {
-      mkdirSync(join4(outputDir, file.platform, file.safeName, "framed"), {
-        recursive: true
-      });
-    }
     renameSync(file.tmpPath, join4(destDir, file.filename));
   }
+  updateMetadata(outputDir, devices);
   if (iosDevices.length > 0) {
     await clearIosStatusBar();
   }
@@ -561,19 +675,35 @@ Captured ${captured.length} screenshot(s) as '${screenshotName}'.`
 function getExistingScreenshotNames(outputDir, devices) {
   const names = /* @__PURE__ */ new Set();
   for (const device of devices) {
-    const rawDir = join4(outputDir, device.platform, device.safeName, "raw");
-    if (!existsSync4(rawDir)) continue;
-    for (const file of readdirSync2(rawDir)) {
-      if (!file.endsWith(".png")) continue;
-      const base = file.replace(".png", "");
-      const suffix = `_${device.safeName}`;
-      if (base.endsWith(suffix)) {
-        names.add(base.slice(0, -suffix.length));
-      }
+    const sizeDir = join4(outputDir, device.platform, device.screenSize);
+    if (!existsSync4(sizeDir)) continue;
+    for (const file of readdirSync2(sizeDir)) {
+      if (!file.endsWith(".png") || file.includes("_framed")) continue;
+      names.add(file.replace(".png", ""));
     }
   }
   return [...names].sort();
 }
+function updateMetadata(outputDir, devices) {
+  const metaPath = join4(outputDir, "metadata.json");
+  let metadata = { ios: {}, android: {} };
+  if (existsSync4(metaPath)) {
+    try {
+      metadata = JSON.parse(readFileSync(metaPath, "utf-8"));
+    } catch {
+    }
+  }
+  for (const device of devices) {
+    const entry = {
+      device: device.displayName,
+      id: device.captureId,
+      resolution: `${device.resolution.width}x${device.resolution.height}`
+    };
+    metadata[device.platform][device.screenSize] = entry;
+  }
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(metaPath, JSON.stringify(metadata, null, 2) + "\n");
+}
 
 // src/commands/frame.ts
 import ora2 from "ora";
@@ -605,7 +735,7 @@ async function frameCommand(dir, options) {
 var program = new Command();
 program.name("device-shots").description(
   "Capture and frame mobile app screenshots from iOS simulators and Android emulators"
-).version("0.1.0");
+).version("0.2.1");
 program.command("capture").description("Capture screenshots from running devices").argument("[name]", "Screenshot name").option("-b, --bundle-id <id>", "App bundle ID").option("-o, --output <dir>", "Output directory").option("-p, --platform <platform>", "ios, android, or both").option("--no-frame", "Skip framing after capture").option("--time <time>", "Status bar time", "9:41").action(async (name, opts) => {
   await captureCommand({ name, ...opts });
 });
@@ -628,7 +758,7 @@ program.command("init").description("Create a .device-shotsrc.json config file")
     return;
   }
   const config = createDefaultConfig(response.bundleId);
-  writeFileSync(configPath, config + "\n");
+  writeFileSync2(configPath, config + "\n");
   console.log(pc3.green(`Created ${configPath}`));
 });
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "device-shots",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Capture and frame mobile app screenshots from iOS simulators and Android emulators",
   "type": "module",
   "bin": {