device-shots 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+A CLI tool that captures screenshots from running iOS simulators and Android emulators, then frames them for store-ready use. iOS screenshots get real device bezels, Android screenshots get a clean black border with rounded corners. Built for developers who need store-ready screenshots without manual work.
 
 ## What it does
 
@@ -9,7 +9,8 @@ A CLI tool that captures screenshots from running iOS simulators and Android emu
 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
+6. **Frames Android screenshots** — Adds a black border with rounded corners for a clean device-like look (requires ImageMagick)
+7. **Organizes by screen size** — Saves screenshots into store-aligned size buckets (e.g. `6.9`, `6.3`, `phone`) instead of device names
 
 ## Use cases
 
@@ -28,8 +29,8 @@ A CLI tool that captures screenshots from running iOS simulators and Android emu
 
 ### 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
+- **ImageMagick** — needed for Android status bar transparency and Android framing (black border + rounded corners). Install with `brew install imagemagick`
+- **Python 3** — needed for iOS screenshot framing with device bezels. The tool auto-creates a virtual environment at `~/.device-shots/.venv` and installs `device-frames-core` and `Pillow` automatically on first use
 
 ## Install
 
@@ -67,7 +68,7 @@ device-shots capture checkout -b com.example.myapp --time "10:30"
 ### Frame existing screenshots
 
 ```bash
-# Frame all unframed iOS screenshots in ./.screenshots
+# Frame all unframed screenshots (iOS + Android) in ./.screenshots
 device-shots frame
 
 # Frame from a specific directory
@@ -83,11 +84,11 @@ device-shots frame --force
 device-shots init
 ```
 
-Creates a `.device-shotsrc.json` in the current directory so you don't have to pass `--bundle-id` every time:
+Creates a `.device-shotsrc.json` in the current directory so you don't have to pass `--bundle-id` every time. It will ask for both production and dev bundle IDs:
 
 ```json
 {
-  "bundleId": "com.example.myapp",
+  "bundleId": ["com.example.myapp", "com.example.myapp.dev"],
   "output": "./.screenshots",
   "platform": "both",
   "time": "9:41",
@@ -95,6 +96,14 @@ Creates a `.device-shotsrc.json` in the current directory so you don't have to p
 }
 ```
 
+A single string also works if you only have one bundle ID:
+
+```json
+{
+  "bundleId": "com.example.myapp"
+}
+```
+
 ## Config file
 
 The tool uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig), so you can configure it in any of these ways:
@@ -105,6 +114,20 @@ The tool uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig), so you
 - `device-shots.config.js`
 - `"device-shots"` key in `package.json`
 
+## Multiple bundle IDs
+
+Most apps have separate bundle IDs for production and development builds. You can pass an array to `bundleId` in the config:
+
+```json
+{
+  "bundleId": ["com.example.myapp", "com.example.myapp.dev"]
+}
+```
+
+During discovery, the tool tries each bundle ID on every running device and captures from whichever build is installed. This means it works regardless of whether you have the dev or production build running.
+
+The CLI `--bundle-id` flag accepts a single ID for quick one-off captures.
+
 ## Output structure
 
 Screenshots are organized by platform and screen size bucket, matching App Store and Play Store requirements:
@@ -125,7 +148,9 @@ Screenshots are organized by platform and screen size bucket, matching App Store
 ├── android/
 │   └── phone/                        # Pixel 9 Pro, etc.
 │       ├── dashboard.png
-│       └── settings.png
+│       ├── dashboard_framed.png
+│       ├── settings.png
+│       └── settings_framed.png
 └── metadata.json
 ```
 
@@ -175,6 +200,26 @@ Tracks which physical device was used for each size bucket:
 }
 ```
 
+## Framing
+
+Both platforms get framed automatically after capture (disable with `--no-frame`).
+
+### iOS — Device bezels
+
+Uses [device-frames-core](https://pypi.org/project/device-frames-core/) to wrap screenshots in realistic Apple device frames (iPhone, iPad). The device model is auto-detected from the screenshot resolution. Requires Python 3 (venv is managed automatically).
+
+### Android — Black border with rounded corners
+
+Uses ImageMagick to add a black bezel-like border with rounded corners. Dimensions scale proportionally to the screenshot:
+
+| Property | Value |
+|----------|-------|
+| Border width | ~1.8% of image width |
+| Inner corner radius | ~4.5% of image width |
+| Outer corner radius | inner radius + border width |
+
+For a 1080px wide screenshot, this produces a ~19px border with ~49px rounded corners.
+
 ## License
 
 MIT

package/dist/index.js

@@ -416,14 +416,28 @@ async function makeStatusBarTransparent(serial, imagePath) {
 
 // src/devices/discover.ts
 async function discoverDevices(bundleId, platform = "both") {
+  const ids = Array.isArray(bundleId) ? bundleId : [bundleId];
   const results = [];
-  if (platform === "ios" || platform === "both") {
-    const iosDevices = await discoverIosDevices(bundleId);
-    results.push(...iosDevices);
-  }
-  if (platform === "android" || platform === "both") {
-    const androidDevices = await discoverAndroidDevices(bundleId);
-    results.push(...androidDevices);
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (platform === "ios" || platform === "both") {
+      const iosDevices = await discoverIosDevices(id);
+      for (const d of iosDevices) {
+        if (!seen.has(d.captureId)) {
+          seen.add(d.captureId);
+          results.push(d);
+        }
+      }
+    }
+    if (platform === "android" || platform === "both") {
+      const androidDevices = await discoverAndroidDevices(id);
+      for (const d of androidDevices) {
+        if (!seen.has(d.captureId)) {
+          seen.add(d.captureId);
+          results.push(d);
+        }
+      }
+    }
   }
   return results;
 }
@@ -490,6 +504,64 @@ async function frameScreenshots(inputDir, outputDir, force = false) {
   const rawFiles = existsSync3(inputDir) ? readdirSync(inputDir).filter((f) => f.endsWith(".png")).length : 0;
   return { framed: framedFiles, skipped: rawFiles - framedFiles };
 }
+async function frameAndroidScreenshot(inputPath, outputPath) {
+  if (!await commandExists("magick")) {
+    throw new Error("ImageMagick is required for Android framing. Install with: brew install imagemagick");
+  }
+  const { stdout: identify } = await run("magick", [
+    "identify",
+    "-format",
+    "%wx%h",
+    inputPath
+  ]);
+  const match = identify.match(/(\d+)x(\d+)/);
+  if (!match) return false;
+  const width = parseInt(match[1], 10);
+  const height = parseInt(match[2], 10);
+  const borderWidth = Math.round(width * 0.018);
+  const innerRadius = Math.round(width * 0.045);
+  const outerRadius = innerRadius + borderWidth;
+  const totalW = width + borderWidth * 2;
+  const totalH = height + borderWidth * 2;
+  try {
+    await runOrFail("magick", [
+      // Create black rounded rectangle background
+      "-size",
+      `${totalW}x${totalH}`,
+      "xc:none",
+      "-draw",
+      `fill black roundrectangle 0,0 ${totalW - 1},${totalH - 1} ${outerRadius},${outerRadius}`,
+      // Load screenshot and round its corners
+      "(",
+      inputPath,
+      "-alpha",
+      "set",
+      "(",
+      "+clone",
+      "-alpha",
+      "extract",
+      "-draw",
+      `fill black color 0,0 reset`,
+      "-draw",
+      `fill white roundrectangle 0,0 ${width - 1},${height - 1} ${innerRadius},${innerRadius}`,
+      ")",
+      "-compose",
+      "DstIn",
+      "-composite",
+      ")",
+      // Composite screenshot centered on black background
+      "-gravity",
+      "center",
+      "-compose",
+      "Over",
+      "-composite",
+      outputPath
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function frameAllIosScreenshots(screenshotsDir, force = false) {
   const iosDir = join3(screenshotsDir, "ios");
   if (!existsSync3(iosDir)) return 0;
@@ -508,17 +580,41 @@ async function frameAllIosScreenshots(screenshotsDir, force = false) {
   }
   return totalFramed;
 }
+async function frameAllAndroidScreenshots(screenshotsDir, force = false) {
+  if (!await commandExists("magick")) return 0;
+  const androidDir = join3(screenshotsDir, "android");
+  if (!existsSync3(androidDir)) return 0;
+  let totalFramed = 0;
+  const sizeDirs = readdirSync(androidDir, { withFileTypes: true }).filter(
+    (d) => d.isDirectory()
+  );
+  for (const sizeDir of sizeDirs) {
+    const dirPath = join3(androidDir, sizeDir.name);
+    const rawFiles = readdirSync(dirPath).filter(
+      (f) => f.endsWith(".png") && !f.includes("_framed")
+    );
+    for (const file of rawFiles) {
+      const inputPath = join3(dirPath, file);
+      const outputPath = join3(dirPath, file.replace(".png", "_framed.png"));
+      if (!force && existsSync3(outputPath)) continue;
+      const success = await frameAndroidScreenshot(inputPath, outputPath);
+      if (success) totalFramed++;
+    }
+  }
+  return totalFramed;
+}
 
 // src/commands/capture.ts
 async function captureCommand(options) {
   const config = await loadConfig();
   const bundleId = options.bundleId || config.bundleId;
-  if (!bundleId) {
+  if (!bundleId || Array.isArray(bundleId) && bundleId.length === 0) {
     console.error(
       pc.red("Bundle ID is required. Use --bundle-id or set it in config.")
     );
     process.exit(1);
   }
+  const bundleIdDisplay = Array.isArray(bundleId) ? bundleId.join(", ") : bundleId;
   const outputDir = options.output || config.output;
   const platform = options.platform || config.platform;
   const time = options.time || config.time;
@@ -527,13 +623,13 @@ async function captureCommand(options) {
   const devices = await discoverDevices(bundleId, platform);
   spinner.stop();
   if (devices.length === 0) {
-    console.error(pc.red(`No devices found with ${bundleId} installed.`));
+    console.error(pc.red(`No devices found with ${bundleIdDisplay} installed.`));
     console.error("Start a simulator/emulator and install the app first.");
     process.exit(1);
   }
   console.log(
     pc.bold(`
-Detected ${devices.length} device(s) with ${bundleId}:`)
+Detected ${devices.length} device(s) with ${bundleIdDisplay}:`)
   );
   for (const device of devices) {
     const sizeDir = join4(outputDir, device.platform, device.screenSize);
@@ -659,16 +755,33 @@ Detected ${devices.length} device(s) with ${bundleId}:`)
 Captured ${captured.length} screenshot(s) as '${screenshotName}'.`
     )
   );
-  if (shouldFrame && iosDevices.length > 0) {
-    console.log("");
-    const s = ora("Framing iOS screenshots...").start();
-    try {
-      const framed = await frameAllIosScreenshots(outputDir);
-      s.succeed(`Framed ${framed} screenshot(s)`);
-    } catch (error) {
-      s.fail(
-        `Framing failed: ${error instanceof Error ? error.message : error}`
-      );
+  if (shouldFrame) {
+    if (iosDevices.length > 0) {
+      console.log("");
+      const s = ora("Framing iOS screenshots...").start();
+      try {
+        const framed = await frameAllIosScreenshots(outputDir);
+        s.succeed(`Framed ${framed} iOS screenshot(s)`);
+      } catch (error) {
+        s.fail(
+          `iOS framing failed: ${error instanceof Error ? error.message : error}`
+        );
+      }
+    }
+    if (androidDevices.length > 0) {
+      const s = ora("Framing Android screenshots...").start();
+      try {
+        const framed = await frameAllAndroidScreenshots(outputDir);
+        if (framed > 0) {
+          s.succeed(`Framed ${framed} Android screenshot(s)`);
+        } else {
+          s.info("Android framing skipped (ImageMagick not found)");
+        }
+      } catch (error) {
+        s.fail(
+          `Android framing failed: ${error instanceof Error ? error.message : error}`
+        );
+      }
     }
   }
 }
@@ -711,23 +824,32 @@ import pc2 from "picocolors";
 async function frameCommand(dir, options) {
   const config = await loadConfig();
   const screenshotsDir = dir || options.input || config.output;
-  console.log(pc2.bold(`Framing iOS screenshots in ${screenshotsDir}...`));
-  const spinner = ora2("Setting up Python environment...").start();
+  console.log(pc2.bold(`Framing screenshots in ${screenshotsDir}...`));
+  const iosSpinner = ora2("Framing iOS screenshots (device bezels)...").start();
   try {
-    const framed = await frameAllIosScreenshots(
-      screenshotsDir,
-      options.force
+    const framed = await frameAllIosScreenshots(screenshotsDir, options.force);
+    if (framed > 0) {
+      iosSpinner.succeed(`Framed ${framed} iOS screenshot(s)`);
+    } else {
+      iosSpinner.info("No new iOS screenshots to frame");
+    }
+  } catch (error) {
+    iosSpinner.fail(
+      `iOS framing failed: ${error instanceof Error ? error.message : error}`
     );
+  }
+  const androidSpinner = ora2("Framing Android screenshots (black border)...").start();
+  try {
+    const framed = await frameAllAndroidScreenshots(screenshotsDir, options.force);
     if (framed > 0) {
-      spinner.succeed(`Framed ${framed} screenshot(s)`);
+      androidSpinner.succeed(`Framed ${framed} Android screenshot(s)`);
     } else {
-      spinner.info("No new screenshots to frame");
+      androidSpinner.info("No new Android screenshots to frame");
     }
   } catch (error) {
-    spinner.fail(
-      `Framing failed: ${error instanceof Error ? error.message : error}`
+    androidSpinner.fail(
+      `Android framing failed: ${error instanceof Error ? error.message : error}`
     );
-    process.exit(1);
   }
 }
 
@@ -735,11 +857,11 @@ 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.2.1");
+).version("0.4.0");
 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 });
 });
-program.command("frame").description("Frame existing iOS screenshots with device bezels").argument("[dir]", "Screenshots directory").option("-i, --input <dir>", "Screenshots directory").option("-f, --force", "Re-frame existing screenshots").action(async (dir, opts) => {
+program.command("frame").description("Frame existing screenshots with device bezels or borders").argument("[dir]", "Screenshots directory").option("-i, --input <dir>", "Screenshots directory").option("-f, --force", "Re-frame existing screenshots").action(async (dir, opts) => {
   await frameCommand(dir, opts);
 });
 program.command("init").description("Create a .device-shotsrc.json config file").action(async () => {
@@ -748,16 +870,24 @@ program.command("init").description("Create a .device-shotsrc.json config file")
     console.log(pc3.yellow(`${configPath} already exists.`));
     return;
   }
-  const response = await prompts2({
-    type: "text",
-    name: "bundleId",
-    message: "App bundle ID (e.g. com.example.myapp)"
-  });
+  const response = await prompts2([
+    {
+      type: "text",
+      name: "bundleId",
+      message: "Production bundle ID (e.g. com.example.myapp)"
+    },
+    {
+      type: "text",
+      name: "devBundleId",
+      message: "Dev bundle ID (leave empty to skip)"
+    }
+  ]);
   if (!response.bundleId) {
     console.log("Aborting.");
     return;
   }
-  const config = createDefaultConfig(response.bundleId);
+  const bundleId = response.devBundleId ? [response.bundleId, response.devBundleId] : response.bundleId;
+  const config = createDefaultConfig(bundleId);
   writeFileSync2(configPath, config + "\n");
   console.log(pc3.green(`Created ${configPath}`));
 });

package/package.json

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