device-shots 0.1.0

package/dist/index.js

@@ -0,0 +1,634 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import { writeFileSync, 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 { join as join4 } from "path";
+import { tmpdir } from "os";
+import { mkdtempSync } from "fs";
+import ora from "ora";
+import pc from "picocolors";
+import prompts from "prompts";
+
+// src/config.ts
+import { cosmiconfig } from "cosmiconfig";
+var MODULE_NAME = "device-shots";
+var DEFAULTS = {
+  bundleId: "",
+  output: "./screenshots",
+  platform: "both",
+  time: "9:41",
+  frame: true
+};
+async function loadConfig() {
+  const explorer = cosmiconfig(MODULE_NAME);
+  try {
+    const result = await explorer.search();
+    if (result && result.config) {
+      return { ...DEFAULTS, ...result.config };
+    }
+  } catch {
+  }
+  return DEFAULTS;
+}
+function createDefaultConfig(bundleId) {
+  return JSON.stringify(
+    {
+      bundleId,
+      output: "./screenshots",
+      platform: "both",
+      time: "9:41",
+      frame: true
+    },
+    null,
+    2
+  );
+}
+
+// src/exec.ts
+import { execa } from "execa";
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var cachedAdbPath = null;
+function getAdbPath() {
+  if (cachedAdbPath) return cachedAdbPath;
+  const androidHome = process.env.ANDROID_HOME || join(homedir(), "Library", "Android", "sdk");
+  const adbPath = join(androidHome, "platform-tools", "adb");
+  if (existsSync(adbPath)) {
+    cachedAdbPath = adbPath;
+    return adbPath;
+  }
+  cachedAdbPath = "adb";
+  return "adb";
+}
+async function commandExists(cmd) {
+  try {
+    await execa("which", [cmd]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function run(cmd, args, options) {
+  const result = await execa(cmd, args, {
+    reject: false,
+    ...options
+  });
+  return { stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+async function runOrFail(cmd, args, options) {
+  const result = await execa(cmd, args, options);
+  return result.stdout ?? "";
+}
+
+// src/devices/ios.ts
+function sanitizeName(name) {
+  return name.replace(/[ (),]/g, "_").replace(/[^A-Za-z0-9_-]/g, "");
+}
+async function discoverIosDevices(bundleId) {
+  if (!await commandExists("xcrun")) return [];
+  const { stdout } = await run("xcrun", [
+    "simctl",
+    "list",
+    "devices",
+    "booted",
+    "-j"
+  ]);
+  if (!stdout) return [];
+  const data = JSON.parse(stdout);
+  const devices = [];
+  for (const [, deviceList] of Object.entries(
+    data.devices
+  )) {
+    for (const d of deviceList) {
+      if (d.state !== "Booted") continue;
+      const { stdout: container } = await run("xcrun", [
+        "simctl",
+        "get_app_container",
+        d.udid,
+        bundleId
+      ]);
+      if (container) {
+        devices.push({
+          platform: "ios",
+          safeName: sanitizeName(d.name),
+          captureId: d.udid,
+          displayName: d.name
+        });
+      }
+    }
+  }
+  return devices;
+}
+async function setIosStatusBar(time) {
+  if (!await commandExists("xcrun")) return;
+  await run("xcrun", [
+    "simctl",
+    "status_bar",
+    "booted",
+    "override",
+    "--time",
+    time,
+    "--batteryState",
+    "charged",
+    "--batteryLevel",
+    "100",
+    "--wifiBars",
+    "3",
+    "--cellularBars",
+    "4",
+    "--operatorName",
+    ""
+  ]);
+}
+async function clearIosStatusBar() {
+  if (!await commandExists("xcrun")) return;
+  await run("xcrun", ["simctl", "status_bar", "booted", "clear"]);
+}
+async function captureIosScreenshot(udid, outputPath) {
+  try {
+    await runOrFail("xcrun", ["simctl", "io", udid, "screenshot", outputPath]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/devices/android.ts
+function sanitizeName2(name) {
+  return name.replace(/[ (),]/g, "_").replace(/[^A-Za-z0-9_-]/g, "");
+}
+async function discoverAndroidDevices(bundleId) {
+  const adb = getAdbPath();
+  const { stdout } = await run(adb, ["devices"]);
+  if (!stdout) return [];
+  const devices = [];
+  const lines = stdout.split("\n").slice(1);
+  for (const line of lines) {
+    const match = line.match(/^(\S+)\s+device$/);
+    if (!match) continue;
+    const serial = match[1];
+    const { stdout: pmPath } = await run(adb, [
+      "-s",
+      serial,
+      "shell",
+      "pm",
+      "path",
+      bundleId
+    ]);
+    if (!pmPath) continue;
+    let avdName = "";
+    const { stdout: emuName } = await run(adb, [
+      "-s",
+      serial,
+      "emu",
+      "avd",
+      "name"
+    ]);
+    avdName = emuName.split("\n")[0].trim();
+    if (!avdName) {
+      const { stdout: model } = await run(adb, [
+        "-s",
+        serial,
+        "shell",
+        "getprop",
+        "ro.product.model"
+      ]);
+      avdName = model.trim();
+    }
+    const safeName = sanitizeName2(avdName) || serial;
+    devices.push({
+      platform: "android",
+      safeName,
+      captureId: serial,
+      displayName: avdName || serial
+    });
+  }
+  return devices;
+}
+async function setAndroidDemoMode(serial, time) {
+  const adb = getAdbPath();
+  const hhmm = time.replace(":", "");
+  const commands = [
+    ["settings", "put", "global", "sysui_demo_allowed", "1"],
+    ["am", "broadcast", "-a", "com.android.systemui.demo", "-e", "command", "enter"],
+    ["am", "broadcast", "-a", "com.android.systemui.demo", "-e", "command", "clock", "-e", "hhmm", hhmm],
+    ["am", "broadcast", "-a", "com.android.systemui.demo", "-e", "command", "wifi", "-e", "fully", "true"],
+    ["am", "broadcast", "-a", "com.android.systemui.demo", "-e", "command", "battery", "-e", "level", "100", "-e", "plugged", "false"],
+    ["am", "broadcast", "-a", "com.android.systemui.demo", "-e", "command", "notifications", "-e", "visible", "false"]
+  ];
+  for (const cmd of commands) {
+    await run(adb, ["-s", serial, "shell", ...cmd]);
+  }
+}
+async function clearAndroidDemoMode(serial) {
+  const adb = getAdbPath();
+  await run(adb, [
+    "-s",
+    serial,
+    "shell",
+    "am",
+    "broadcast",
+    "-a",
+    "com.android.systemui.demo",
+    "-e",
+    "command",
+    "exit"
+  ]);
+}
+async function captureAndroidScreenshot(serial, outputPath) {
+  const adb = getAdbPath();
+  const deviceTmp = "/sdcard/screenshot_tmp.png";
+  try {
+    await runOrFail(adb, ["-s", serial, "shell", "screencap", deviceTmp]);
+    await runOrFail(adb, ["-s", serial, "pull", deviceTmp, outputPath]);
+    await run(adb, ["-s", serial, "shell", "rm", deviceTmp]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function makeStatusBarTransparent(serial, imagePath) {
+  if (!await commandExists("magick")) return false;
+  const adb = getAdbPath();
+  const STATUS_BAR_HEIGHT_DP = 24;
+  const { stdout: densityOutput } = await run(adb, [
+    "-s",
+    serial,
+    "shell",
+    "wm",
+    "density"
+  ]);
+  const densityMatch = densityOutput.match(/(\d+)\s*$/m);
+  if (!densityMatch) return false;
+  const density = parseInt(densityMatch[1], 10);
+  const statusBarPx = Math.ceil(STATUS_BAR_HEIGHT_DP * density / 160);
+  const { stdout: identify } = await run("magick", [
+    "identify",
+    "-format",
+    "%w",
+    imagePath
+  ]);
+  const imgWidth = identify.trim();
+  if (!imgWidth) return false;
+  try {
+    await runOrFail("magick", [
+      imagePath,
+      "-region",
+      `${imgWidth}x${statusBarPx}+0+0`,
+      "-alpha",
+      "set",
+      "-channel",
+      "A",
+      "-evaluate",
+      "set",
+      "0",
+      "+channel",
+      imagePath
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/devices/discover.ts
+async function discoverDevices(bundleId, platform = "both") {
+  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);
+  }
+  return results;
+}
+
+// src/framing/frame.ts
+import { existsSync as existsSync3, readdirSync } from "fs";
+import { join as join3, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// src/framing/setup.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+var VENV_DIR = join2(homedir2(), ".device-shots", ".venv");
+var PYTHON_BIN = join2(VENV_DIR, "bin", "python3");
+var PIP_BIN = join2(VENV_DIR, "bin", "pip");
+function getVenvPython() {
+  return PYTHON_BIN;
+}
+function isVenvReady() {
+  return existsSync2(PYTHON_BIN);
+}
+async function ensureVenv() {
+  if (isVenvReady()) return;
+  if (!await commandExists("python3")) {
+    throw new Error("python3 is required for framing. Please install Python 3.");
+  }
+  await runOrFail("python3", ["-m", "venv", VENV_DIR]);
+  await runOrFail(PIP_BIN, [
+    "install",
+    "--quiet",
+    "device-frames-core",
+    "Pillow"
+  ]);
+}
+
+// src/framing/frame.ts
+function getFramePyPath() {
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join3(thisDir, "..", "vendor", "frame.py"),
+    join3(thisDir, "..", "..", "vendor", "frame.py")
+  ];
+  for (const c of candidates) {
+    if (existsSync3(c)) return c;
+  }
+  throw new Error(
+    "Could not find vendored frame.py. Ensure the vendor/ directory is present."
+  );
+}
+async function frameScreenshots(rawDir, framedDir, force = false) {
+  await ensureVenv();
+  const framePy = getFramePyPath();
+  const python = getVenvPython();
+  const args = [framePy, rawDir, framedDir];
+  if (force) {
+    args.push("--force");
+  }
+  const output = await runOrFail(python, args);
+  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;
+  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"));
+    if (pngFiles.length === 0) continue;
+    const framedDir = join3(iosDir, deviceDir.name, "framed");
+    const { framed } = await frameScreenshots(rawDir, framedDir, force);
+    totalFramed += framed;
+  }
+  return totalFramed;
+}
+
+// src/commands/capture.ts
+async function captureCommand(options) {
+  const config = await loadConfig();
+  const bundleId = options.bundleId || config.bundleId;
+  if (!bundleId) {
+    console.error(
+      pc.red("Bundle ID is required. Use --bundle-id or set it in config.")
+    );
+    process.exit(1);
+  }
+  const outputDir = options.output || config.output;
+  const platform = options.platform || config.platform;
+  const time = options.time || config.time;
+  const shouldFrame = !options.noFrame && config.frame;
+  const spinner = ora("Discovering devices...").start();
+  const devices = await discoverDevices(bundleId, platform);
+  spinner.stop();
+  if (devices.length === 0) {
+    console.error(pc.red(`No devices found with ${bundleId} 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}:`)
+  );
+  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")
+      ).length;
+      console.log(
+        `  ${pc.dim(device.platform + "/")}${device.safeName} (${device.displayName}) - ${count} screenshot(s)`
+      );
+    } else {
+      console.log(
+        `  ${pc.dim(device.platform + "/")}${device.safeName} (${device.displayName}) - ${pc.green("new")}`
+      );
+    }
+  }
+  const existingNames = getExistingScreenshotNames(outputDir, devices);
+  if (existingNames.length > 0) {
+    console.log(pc.dim("\nExisting screenshots:"));
+    for (const name of existingNames) {
+      console.log(pc.dim(`  - ${name}`));
+    }
+  }
+  let screenshotName = options.name;
+  if (!screenshotName) {
+    const response = await prompts({
+      type: "text",
+      name: "name",
+      message: "Screenshot name (e.g. dashboard, sales-report)"
+    });
+    if (!response.name) {
+      console.log("No name provided. Aborting.");
+      process.exit(1);
+    }
+    screenshotName = response.name;
+  }
+  screenshotName = screenshotName.replace(/ /g, "-").replace(/[^A-Za-z0-9_-]/g, "");
+  const firstDevice = devices[0];
+  const existingFile = join4(
+    outputDir,
+    firstDevice.platform,
+    firstDevice.safeName,
+    "raw",
+    `${screenshotName}_${firstDevice.safeName}.png`
+  );
+  if (existsSync4(existingFile)) {
+    const response = await prompts({
+      type: "confirm",
+      name: "overwrite",
+      message: `Screenshot '${screenshotName}' already exists. Overwrite?`,
+      initial: false
+    });
+    if (!response.overwrite) {
+      console.log("Aborting.");
+      process.exit(0);
+    }
+  }
+  const tmpDir = mkdtempSync(join4(tmpdir(), "device-shots-"));
+  const iosDevices = devices.filter((d) => d.platform === "ios");
+  const androidDevices = devices.filter((d) => d.platform === "android");
+  if (iosDevices.length > 0) {
+    const s = ora("Setting clean iOS status bar...").start();
+    await setIosStatusBar(time);
+    s.succeed("iOS status bar set");
+  }
+  if (androidDevices.length > 0) {
+    const s = ora("Setting clean Android status bar...").start();
+    for (const device of androidDevices) {
+      await setAndroidDemoMode(device.captureId, time);
+    }
+    s.succeed("Android demo mode set");
+  }
+  console.log("");
+  const captured = [];
+  for (const device of devices) {
+    const filename = `${screenshotName}_${device.safeName}.png`;
+    const tmpPath = join4(tmpDir, filename);
+    const icon = device.platform === "ios" ? "iOS" : "Android";
+    const s = ora(`${icon}: Capturing from ${device.displayName}...`).start();
+    let success = false;
+    if (device.platform === "ios") {
+      success = await captureIosScreenshot(device.captureId, tmpPath);
+    } else {
+      success = await captureAndroidScreenshot(device.captureId, tmpPath);
+      if (success) {
+        const transparent = await makeStatusBarTransparent(
+          device.captureId,
+          tmpPath
+        );
+        if (transparent) {
+          s.text = `${icon}: Captured from ${device.displayName} (status bar transparent)`;
+        }
+      }
+    }
+    if (success) {
+      captured.push({
+        platform: device.platform,
+        safeName: device.safeName,
+        filename,
+        tmpPath
+      });
+      s.succeed(`${icon}: ${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");
+    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));
+  }
+  if (iosDevices.length > 0) {
+    await clearIosStatusBar();
+  }
+  for (const device of androidDevices) {
+    await clearAndroidDemoMode(device.captureId);
+  }
+  console.log(
+    pc.green(
+      `
+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}`
+      );
+    }
+  }
+}
+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));
+      }
+    }
+  }
+  return [...names].sort();
+}
+
+// src/commands/frame.ts
+import ora2 from "ora";
+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();
+  try {
+    const framed = await frameAllIosScreenshots(
+      screenshotsDir,
+      options.force
+    );
+    if (framed > 0) {
+      spinner.succeed(`Framed ${framed} screenshot(s)`);
+    } else {
+      spinner.info("No new screenshots to frame");
+    }
+  } catch (error) {
+    spinner.fail(
+      `Framing failed: ${error instanceof Error ? error.message : error}`
+    );
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+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");
+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) => {
+  await frameCommand(dir, opts);
+});
+program.command("init").description("Create a .device-shotsrc.json config file").action(async () => {
+  const configPath = ".device-shotsrc.json";
+  if (existsSync5(configPath)) {
+    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)"
+  });
+  if (!response.bundleId) {
+    console.log("Aborting.");
+    return;
+  }
+  const config = createDefaultConfig(response.bundleId);
+  writeFileSync(configPath, config + "\n");
+  console.log(pc3.green(`Created ${configPath}`));
+});
+program.parse();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "device-shots",
+  "version": "0.1.0",
+  "description": "Capture and frame mobile app screenshots from iOS simulators and Android emulators",
+  "type": "module",
+  "bin": {
+    "device-shots": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "vendor"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "screenshot",
+    "mobile",
+    "ios",
+    "android",
+    "simulator",
+    "emulator",
+    "device-frame"
+  ],
+  "author": "mjcarnaje",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "cosmiconfig": "^9.0.0",
+    "execa": "^9.5.2",
+    "ora": "^8.2.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/vendor/frame.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Frame iOS screenshots with device bezels.
+
+Auto-detects the device model from screenshot resolution and applies
+the matching Apple frame using device-frames-core.
+
+Android screenshots are used raw (per Google Play Store guidelines).
+
+Requirements:
+    pip install device-frames-core Pillow
+"""
+
+import sys
+from pathlib import Path
+
+from device_frames_core import apply_frame, list_devices
+
+VARIATION_PREFERENCE = ["space-black", "black", "space-grey", "silver"]
+IOS_CATEGORIES = {"apple-iphone", "apple-ipad"}
+
+
+def build_resolution_map():
+    """Map (width, height) -> best matching iOS device info."""
+    res_map = {}
+    for d in list_devices():
+        if d["category"] not in IOS_CATEGORIES:
+            continue
+
+        key = (d["screen"]["width"], d["screen"]["height"])
+        existing = res_map.get(key)
+        if existing is None:
+            res_map[key] = d
+        else:
+            for pref in VARIATION_PREFERENCE:
+                if pref in d["variation"] and pref not in existing["variation"]:
+                    res_map[key] = d
+                    break
+    return res_map
+
+
+def get_image_size(path):
+    """Return (width, height) of an image."""
+    from PIL import Image
+
+    with Image.open(path) as img:
+        return img.size
+
+
+def frame_screenshot(input_path, output_path, res_map):
+    """Frame a single screenshot, auto-detecting the device."""
+    width, height = get_image_size(input_path)
+    device_info = res_map.get((width, height))
+
+    if device_info is None:
+        print(f"  No matching device frame for {width}x{height}, skipping: {input_path}")
+        return False
+
+    category = device_info["category"]
+    device = device_info["device"]
+    variation = device_info["variation"]
+
+    print(f"  {Path(input_path).name} -> {device} ({variation})")
+    apply_frame(
+        screenshot_path=Path(input_path),
+        device=device,
+        variation=variation,
+        output_path=Path(output_path),
+        category=category,
+    )
+    return True
+
+
+def main():
+    force = "--force" in sys.argv
+    args = [a for a in sys.argv[1:] if a != "--force"]
+
+    if len(args) < 2:
+        print("Usage: frame.py <raw_dir> <framed_dir> [--force]")
+        sys.exit(1)
+
+    raw_dir = Path(args[0])
+    framed_dir = Path(args[1])
+    framed_dir.mkdir(parents=True, exist_ok=True)
+
+    res_map = build_resolution_map()
+
+    screenshots = sorted(raw_dir.glob("*.png"))
+    if not screenshots:
+        print("No screenshots found.")
+        sys.exit(1)
+
+    skipped = 0
+    to_frame = []
+
+    for f in screenshots:
+        framed_name = f"{f.stem}_framed.png"
+        if not force and (framed_dir / framed_name).exists():
+            skipped += 1
+        else:
+            to_frame.append(f)
+
+    if not to_frame:
+        print(f"All {skipped} screenshots already framed. Nothing to do.")
+        return
+
+    if skipped:
+        print(f"Skipping {skipped} already framed.")
+    print(f"Framing {len(to_frame)} screenshots...")
+
+    success = 0
+    for f in to_frame:
+        output = framed_dir / f"{f.stem}_framed.png"
+        if frame_screenshot(str(f), str(output), res_map):
+            success += 1
+
+    print(f"Done! Framed {success}/{len(to_frame)} screenshots.")
+
+
+if __name__ == "__main__":
+    main()