appshot-cli 0.5.0 → 0.7.0

package/README.md

@@ -6,7 +6,9 @@
 [![npm version](https://badge.fury.io/js/appshot-cli.svg)](https://www.npmjs.com/package/appshot-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-🆕 **Version 0.4.0** - Language-aware output directories, comprehensive font system, and system locale detection!
+🆕 **Version 0.7.0** - **Enhanced caption styling**, flexible positioning (above/below/overlay), customizable backgrounds and borders for professional App Store screenshots!
+
+> ⚠️ **NEW in v0.7.0**: Complete caption styling system with backgrounds, borders, and flexible positioning. Create professional captions with customizable colors, opacity, padding, and rounded corners.
 
 > ⚠️ **BREAKING CHANGE in v0.4.0**: Output structure now always uses language subdirectories.
 > Single language builds now output to `final/device/lang/` instead of `final/device/`.
@@ -55,6 +57,7 @@ Appshot is the only **agent-first CLI tool** designed for automated App Store sc
 - 🖼️ **Smart Frames** - Automatically detects portrait/landscape and selects appropriate device frame
 - 🎨 **Gradient Presets** - 24+ beautiful gradients with visual preview and easy application
 - 🔤 **Font System** - 50+ font mappings, direct font setting, interactive selection, and system detection
+- 📦 **Embedded Fonts** - 10 high-quality open source fonts bundled for consistent rendering everywhere
 - ✏️ **Dynamic Captions** - Smart text wrapping, auto-sizing, and multi-line support
 - 🌍 **AI Translation** - Real-time and batch translation using OpenAI's latest models
 - 📱 **Multi-Device** - iPhone, iPad, Mac, Apple TV, Vision Pro, and Apple Watch support
@@ -62,6 +65,8 @@ Appshot is the only **agent-first CLI tool** designed for automated App Store sc
 - 🔄 **Orientation Detection** - Intelligently handles both portrait and landscape
 - ⚡ **Parallel Processing** - Configurable concurrency for large batches
 - 🔍 **Caption Autocomplete** - Intelligent suggestions with fuzzy search and learning
+- 🔬 **Dry-Run Mode** - Preview what would be built without generating images
+- 🐛 **Verbose Debugging** - Detailed rendering metrics for troubleshooting
 
 ## 🚀 Quick Start
 
@@ -342,7 +347,7 @@ Intelligent caption rendering that adapts to content:
 ```json
 {
   "caption": {
-    "position": "above",      // above or overlay
+    "position": "above",      // above, below, or overlay
     "box": {
       "autoSize": true,       // Dynamic height
       "maxLines": 3,          // Line limit
@@ -354,6 +359,97 @@ Intelligent caption rendering that adapts to content:
 }
 ```
 
+#### Caption Positioning Options
+
+- **`above`** (default): Caption appears above the device frame
+- **`below`** (new in v0.7.0): Caption appears below the device frame  
+- **`overlay`**: Caption overlays on the gradient background
+
+```bash
+# Configure caption below device
+appshot style --device iphone
+# → Select "Below device frame" option
+
+# Or set directly in config
+{
+  "devices": {
+    "iphone": {
+      "captionPosition": "below"
+    }
+  }
+}
+```
+
+#### Caption Styling (New in v0.7.0)
+
+Create professional captions with customizable backgrounds and borders:
+
+```json
+{
+  "caption": {
+    "color": "#FFFFFF",           // Text color (hex)
+    "background": {
+      "color": "#000000",         // Background color (hex)
+      "opacity": 0.8,             // Transparency (0-1)
+      "padding": 20               // Padding around text
+    },
+    "border": {
+      "color": "#FFFFFF",         // Border color (hex)
+      "width": 2,                 // Border thickness (1-10)
+      "radius": 12                // Rounded corners (0-30)
+    }
+  }
+}
+```
+
+**Key Features:**
+- **Full-width styling** - Backgrounds and borders span device width for uniformity
+- **Flexible positioning** - Works with above, below, and overlay positions
+- **Device-specific overrides** - Customize styling per device type
+- **Professional appearance** - Rounded corners and padding for polished look
+
+**Interactive Configuration:**
+```bash
+# Configure caption styling interactively
+appshot style --device iphone
+# → Choose caption position (above/below/overlay)
+# → Configure background color and opacity
+# → Set border color, width, and radius
+```
+
+**Examples:**
+
+```json
+// Dark background with white border
+{
+  "caption": {
+    "color": "#FFFFFF",
+    "background": {
+      "color": "#000000",
+      "opacity": 0.9,
+      "padding": 30
+    },
+    "border": {
+      "color": "#FFFFFF",
+      "width": 3,
+      "radius": 16
+    }
+  }
+}
+
+// Subtle gradient-matched styling
+{
+  "caption": {
+    "color": "#FFFFFF",
+    "background": {
+      "color": "#FF5733",
+      "opacity": 0.6,
+      "padding": 25
+    }
+  }
+}
+```
+
 #### Caption Autocomplete
 
 The caption command includes intelligent autocomplete:
@@ -524,6 +620,8 @@ appshot build [options]
 - `--langs <list>` - Build for specific languages (if not specified, auto-detects)
 - `--preview` - Generate low-res previews
 - `--concurrency <n>` - Parallel processing limit (default: 5)
+- `--dry-run` - Show what would be rendered without generating images
+- `--verbose` - Show detailed rendering information
 - `--no-frame` - Skip device frames
 - `--no-gradient` - Skip gradient backgrounds
 - `--no-caption` - Skip captions
@@ -548,6 +646,12 @@ appshot build --preset iphone-6-9-portrait,ipad-13-landscape
 
 # Preview mode
 appshot build --preview --devices iphone
+
+# Dry-run to see what would be built
+appshot build --dry-run
+
+# Verbose mode for debugging
+appshot build --verbose --devices iphone
 ```
 
 **Exit Codes:**
@@ -685,7 +789,7 @@ Suggestions:
 
 ### `appshot fonts`
 
-Browse, validate, and set fonts for captions.
+Browse, validate, and set fonts for captions. Includes 8 high-quality embedded fonts for consistent rendering across all platforms.
 
 ```bash
 appshot fonts [options]
@@ -693,29 +797,48 @@ appshot fonts [options]
 
 **Options:**
 - `--all` - List all system fonts
+- `--embedded` - Show embedded fonts bundled with appshot
 - `--recommended` - Show recommended fonts only (default)
-- `--validate <name>` - Check if font is available
+- `--validate <name>` - Check if font is available (embedded or system)
 - `--set <name>` - Set the caption font
 - `--select` - Interactive font selection
 - `--device <name>` - Target specific device (with --set or --select)
 - `--json` - Output as JSON
 
+**Embedded Fonts (Always Available):**
+- **Modern UI**: Inter, Poppins, Montserrat, DM Sans
+- **Popular Web**: Roboto, Open Sans, Lato, Work Sans
+- **Monospace**: JetBrains Mono, Fira Code
+- **Variants**: Regular, Italic, Bold, and Bold Italic styles
+
+All embedded fonts use open source licenses (OFL or Apache 2.0) and provide consistent rendering without requiring system installation. Font variants are automatically detected and properly rendered with correct styles.
+
 **Examples:**
 ```bash
 # Browse recommended fonts
 appshot fonts
 
-# Set global font directly
-appshot fonts --set "Montserrat"
+# Show embedded fonts
+appshot fonts --embedded
+
+# Set global font directly (embedded font)
+appshot fonts --set "Inter"
+
+# Set font variant (italic style)
+appshot fonts --set "Poppins Italic"
+
+# Set bold variant
+appshot fonts --set "Montserrat Bold"
 
 # Interactive font selection
 appshot fonts --select
 
-# Set device-specific font
-appshot fonts --set "SF Pro" --device iphone
+# Set device-specific font variant
+appshot fonts --set "Poppins Bold Italic" --device iphone
 
-# Validate before setting
-appshot fonts --validate "My Font" && appshot fonts --set "My Font"
+# Validate font availability
+appshot fonts --validate "Inter"  # Shows: embedded
+appshot fonts --validate "Arial"  # Shows: system installed
 
 # List all system fonts
 appshot fonts --all
@@ -962,11 +1085,21 @@ appshot validate [options]
   "caption": {
     "font": "Font Name",
     "fontsize": 64,              // Pixels
-    "color": "#FFFFFF",
+    "color": "#FFFFFF",         // Text color (hex)
     "align": "center",           // left, center, right
-    "position": "above",         // above, overlay
+    "position": "above",         // above, below, overlay
     "paddingTop": 100,
     "paddingBottom": 60,
+    "background": {              // Optional background styling
+      "color": "#000000",        // Background color (hex)
+      "opacity": 0.8,            // Transparency (0-1)
+      "padding": 20              // Padding around text
+    },
+    "border": {                  // Optional border styling
+      "color": "#FFFFFF",        // Border color (hex)
+      "width": 2,                // Border thickness (1-10)
+      "radius": 12               // Rounded corners (0-30)
+    },
     "box": {
       "autoSize": true,          // Dynamic height
       "maxLines": 3,
@@ -1022,6 +1155,16 @@ Each device can override global settings:
       "captionFont": "SF Pro",
       "captionSize": 64,
       "captionPosition": "above",
+      "captionBackground": {     // Device-specific background
+        "color": "#FF5733",
+        "opacity": 0.7,
+        "padding": 25
+      },
+      "captionBorder": {         // Device-specific border
+        "color": "#FFFFFF",
+        "width": 3,
+        "radius": 16
+      },
       "captionBox": {
         "autoSize": false,
         "minHeight": 320,
@@ -1454,6 +1597,34 @@ appshot build --devices iphone
 appshot build --devices ipad
 ```
 
+### Debugging with Verbose Mode
+
+Use `--verbose` flag to diagnose rendering issues:
+
+```bash
+# See detailed caption metrics
+appshot build --verbose --devices iphone
+
+# Output includes:
+# - Caption wrap width and line count
+# - Font stack with fallbacks
+# - Device frame scaling factors
+# - Position calculations
+```
+
+Use `--dry-run` to validate configuration without processing:
+
+```bash
+# Check what would be generated
+appshot build --dry-run
+
+# Verify frame selection
+appshot build --dry-run --devices iphone
+
+# Check multi-language output
+appshot build --dry-run --langs en,es,fr
+```
+
 ### Performance Tips
 
 1. **Use appropriate concurrency**
@@ -1590,7 +1761,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ### Completed ✅
 - [x] Official App Store specifications
-- [x] Caption positioning (above/overlay)
+- [x] Caption positioning (above/below/overlay)
 - [x] Partial frame support
 - [x] Intelligent caption autocomplete
 - [x] Apple Watch optimizations
@@ -1632,7 +1803,7 @@ For security vulnerabilities, please see [SECURITY.md](SECURITY.md).
 ### NPM Package
 
 - 📦 [appshot-cli on NPM](https://www.npmjs.com/package/appshot-cli)
-- 🔄 Latest version: 0.4.0
+- 🔄 Latest version: 0.6.0
 - ⬇️ Weekly downloads: ![npm](https://img.shields.io/npm/dw/appshot-cli)
 
 ---

package/dist/cli.js

@@ -17,8 +17,40 @@ import { createCleanCommand } from './commands/clean.js';
 const program = new Command();
 program
     .name('appshot')
-    .description('Generate App Store–ready screenshots with frames, gradients, and captions.')
-    .version('0.5.0');
+    .description(`Generate App Store–ready screenshots with frames, gradients, and captions.
+
+${pc.bold('Features:')}
+  • Auto-detects portrait/landscape orientation
+  • 8 embedded font families with italic & bold variants  
+  • 24+ gradient presets with visual preview
+  • AI-powered translation to 25+ languages
+  • Smart caption wrapping and positioning
+  • All official App Store resolutions
+  • Parallel processing for large batches
+
+${pc.bold('Quick Start:')}
+  $ appshot init                    # Initialize project
+  $ appshot caption --device iphone  # Add captions
+  $ appshot build                    # Generate screenshots
+
+${pc.bold('Common Workflows:')}
+  $ appshot fonts --set "Poppins Italic"     # Set italic font
+  $ appshot gradients select                  # Pick gradient
+  $ appshot build --preset iphone-6-9,ipad-13 # App Store presets
+  $ appshot localize --langs es,fr,de        # Batch translate
+
+${pc.dim('Docs: https://github.com/chrisvanbuskirk/appshot')}`)
+    .version('0.7.0')
+    .addHelpText('after', `\n${pc.bold('Environment Variables:')}
+  OPENAI_API_KEY              API key for translation features
+  APPSHOT_DISABLE_FONT_SCAN   Skip system font detection (CI optimization)
+
+${pc.bold('Configuration Files:')}
+  .appshot/config.json        Main configuration
+  .appshot/captions/*.json    Per-device captions
+  .appshot/caption-history.json  Autocomplete history
+
+${pc.dim('Run \'appshot <command> --help\' for command details.')}`);
 program.addCommand(initCmd());
 program.addCommand(captionCmd());
 program.addCommand(styleCmd());

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,OAAO,MAAM,oBAAoB,CAAC;AACzC,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,SAAS,MAAM,sBAAsB,CAAC;AAC7C,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,YAAY,MAAM,yBAAyB,CAAC;AACnD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,4EAA4E,CAAC;KACzF,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAEzC,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,CAAC;AAE9D,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,OAAO,MAAM,oBAAoB,CAAC;AACzC,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,SAAS,MAAM,sBAAsB,CAAC;AAC7C,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,YAAY,MAAM,yBAAyB,CAAC;AACnD,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC;;EAEb,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC;;;;;;;;;EASpB,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC;;;;;EAKvB,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC;;;;;;EAM5B,EAAE,CAAC,GAAG,CAAC,kDAAkD,CAAC,EAAE,CAAC;KAC5D,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,wBAAwB,CAAC;;;;EAI5D,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC;;;;;EAK/B,EAAE,CAAC,GAAG,CAAC,uDAAuD,CAAC,EAAE,CAAC,CAAC;AAErE,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAEzC,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,CAAC;AAE9D,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,CAAC,OAAO,UAAU,QAAQ,YAuO/B"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,CAAC,OAAO,UAAU,QAAQ,YA4T/B"}

package/dist/commands/build.js

@@ -9,7 +9,7 @@ import { composeAppStoreScreenshot } from '../core/compose.js';
 import { resolveLanguages, normalizeLanguageCode } from '../utils/language.js';
 export default function buildCmd() {
     const cmd = new Command('build')
-        .description('Render screenshots using frames, gradients, and captions')
+        .description('Generate final screenshots with frames, gradients, and captions')
         .option('--devices <list>', 'comma-separated device list (e.g., iphone,ipad)', 'iphone,ipad,mac,watch')
         .option('--preset <ids>', 'use specific App Store presets (e.g., iphone-6-9,ipad-13)')
         .option('--config <file>', 'use specific config file', 'appshot.json')
@@ -19,11 +19,53 @@ export default function buildCmd() {
         .option('--no-frame', 'skip device frames')
         .option('--no-gradient', 'skip gradient backgrounds')
         .option('--no-caption', 'skip captions')
+        .option('--dry-run', 'show what would be rendered without generating images')
+        .option('--verbose', 'show detailed rendering information')
+        .addHelpText('after', `
+${pc.bold('Examples:')}
+  ${pc.dim('# Build all devices')}
+  $ appshot build
+  
+  ${pc.dim('# Build specific devices')}
+  $ appshot build --devices iphone,ipad
+  
+  ${pc.dim('# Build for multiple languages')}
+  $ appshot build --langs en,es,fr,de
+  
+  ${pc.dim('# Use App Store presets')}
+  $ appshot build --preset iphone-6-9,ipad-13
+  
+  ${pc.dim('# Fast preview mode')}
+  $ appshot build --preview --concurrency 8
+  
+  ${pc.dim('# Frames only (no gradient/caption)')}
+  $ appshot build --no-gradient --no-caption
+  
+  ${pc.dim('# Preview what would be built')}
+  $ appshot build --dry-run
+  
+  ${pc.dim('# Show detailed rendering info')}
+  $ appshot build --verbose
+
+${pc.bold('Output:')}
+  Screenshots are saved to: ${pc.cyan('final/[device]/[language]/')}
+  
+${pc.bold('Language Detection:')}
+  1. --langs parameter (if provided)
+  2. Languages in caption files
+  3. defaultLanguage in config.json
+  4. System locale
+  5. Fallback to 'en'`)
         .action(async (opts) => {
         try {
-            console.log(pc.bold('Building screenshots...'));
+            if (opts.dryRun) {
+                console.log(pc.bold('Dry run mode - no images will be generated\n'));
+            }
+            else {
+                console.log(pc.bold('Building screenshots...'));
+            }
             // Load configuration
-            const config = await loadConfig();
+            const config = await loadConfig(opts.config);
             const devices = opts.devices.split(',').map((d) => d.trim());
             const concurrency = parseInt(opts.concurrency, 10);
             // Initialize frame registry from Frames.json if available
@@ -65,7 +107,7 @@ export default function buildCmd() {
                 // Resolve languages for this device
                 const cliLangs = opts.langs ? opts.langs.split(',').map((l) => normalizeLanguageCode(l.trim())) : undefined;
                 const { languages, source } = resolveLanguages(cliLangs, captions, config);
-                console.log(pc.cyan(`\n${device}:`), `Processing ${screenshots.length} screenshots`);
+                console.log(pc.cyan(`\n${device}:`), `${opts.dryRun ? 'Would process' : 'Processing'} ${screenshots.length} screenshots`);
                 if (!cliLangs) {
                     console.log(pc.dim(`  Using language: ${languages.join(', ')} (from ${source})`));
                 }
@@ -73,7 +115,9 @@ export default function buildCmd() {
                 for (const lang of languages) {
                     // Always use language subdirectory
                     const langDir = path.join(outputDir, lang);
-                    await fs.mkdir(langDir, { recursive: true });
+                    if (!opts.dryRun) {
+                        await fs.mkdir(langDir, { recursive: true });
+                    }
                     // Process screenshots in batches
                     for (let i = 0; i < screenshots.length; i += concurrency) {
                         const batch = screenshots.slice(i, i + concurrency);
@@ -91,20 +135,22 @@ export default function buildCmd() {
                                     captionText = captionData[lang] || '';
                                 }
                                 // Get screenshot dimensions and orientation
-                                const { orientation } = await getImageDimensions(inputPath);
-                                // Load screenshot
+                                const { width: srcWidth, height: srcHeight, orientation } = await getImageDimensions(inputPath);
+                                // In dry-run mode, skip loading the screenshot buffer
                                 let screenshotBuffer;
-                                try {
-                                    // First verify the file exists and is readable
-                                    await fs.access(inputPath, fs.constants.R_OK);
-                                    // Load the screenshot into a buffer
-                                    screenshotBuffer = await sharp(inputPath)
-                                        .png() // Ensure output is PNG
-                                        .toBuffer();
-                                }
-                                catch (error) {
-                                    console.error(pc.red(`  ✗ ${path.basename(inputPath)}`), `Failed to load screenshot: ${error instanceof Error ? error.message : String(error)}`);
-                                    return;
+                                if (!opts.dryRun) {
+                                    try {
+                                        // First verify the file exists and is readable
+                                        await fs.access(inputPath, fs.constants.R_OK);
+                                        // Load the screenshot into a buffer
+                                        screenshotBuffer = await sharp(inputPath)
+                                            .png() // Ensure output is PNG
+                                            .toBuffer();
+                                    }
+                                    catch (error) {
+                                        console.error(pc.red(`  ✗ ${path.basename(inputPath)}`), `Failed to load screenshot: ${error instanceof Error ? error.message : String(error)}`);
+                                        return;
+                                    }
                                 }
                                 // Parse resolution for output dimensions
                                 const [configWidth, configHeight] = deviceConfig.resolution.split('x').map(Number);
@@ -134,54 +180,85 @@ export default function buildCmd() {
                                 if (opts.frame !== false) {
                                     // If autoFrame is disabled but preferredFrame is set, use the preferred frame
                                     // Otherwise, auto-select a frame
-                                    const result = await autoSelectFrame(inputPath, path.resolve(config.frames), device, deviceConfig.preferredFrame);
+                                    const result = await autoSelectFrame(inputPath, path.resolve(config.frames), device, deviceConfig.preferredFrame, opts.dryRun // Pass dry-run flag
+                                    );
                                     frame = result.frame;
                                     frameMetadata = result.metadata;
-                                    if (frame && frameMetadata) {
+                                    if (frameMetadata) {
                                         frameUsed = true;
-                                        console.log(pc.dim(`    Using ${frameMetadata.displayName} ${orientation} frame`));
+                                        if (opts.verbose || opts.dryRun) {
+                                            console.log(pc.dim(`    ${opts.dryRun ? 'Would use' : 'Using'} ${frameMetadata.displayName} ${orientation} frame`));
+                                        }
                                     }
-                                    else if (frameMetadata && !frame) {
+                                    else if (!opts.dryRun && frameMetadata && !frame) {
                                         console.error(pc.red('    ERROR: Frame metadata found but image failed to load!'));
                                     }
                                 }
-                                // Use the new compose function
-                                let image;
-                                try {
-                                    image = await composeAppStoreScreenshot({
-                                        screenshot: screenshotBuffer,
-                                        frame: frame,
-                                        frameMetadata: frameMetadata ? {
-                                            frameWidth: frameMetadata.frameWidth,
-                                            frameHeight: frameMetadata.frameHeight,
-                                            screenRect: frameMetadata.screenRect,
-                                            maskPath: frameMetadata.maskPath,
-                                            deviceType: frameMetadata.deviceType,
-                                            displayName: frameMetadata.displayName,
-                                            name: frameMetadata.name
-                                        } : undefined,
-                                        caption: opts.caption !== false ? captionText : undefined,
-                                        captionConfig: config.caption,
-                                        gradientConfig: config.gradient,
-                                        deviceConfig: deviceConfig,
-                                        outputWidth: outWidth,
-                                        outputHeight: outHeight
-                                    });
+                                // Handle dry-run vs actual rendering
+                                if (opts.dryRun) {
+                                    // Dry-run output
+                                    console.log(pc.cyan(`  ${screenshot}`) + pc.dim(` → ${lang}`));
+                                    // Show source dimensions
+                                    console.log(pc.dim(`    Source: ${srcWidth}x${srcHeight} (${orientation})`));
+                                    // Show frame info
+                                    if (frameMetadata) {
+                                        console.log(pc.dim(`    Frame: ${frameMetadata.displayName} (${frameMetadata.frameWidth}x${frameMetadata.frameHeight})`));
+                                    }
+                                    else if (opts.frame !== false) {
+                                        console.log(pc.dim('    Frame: No matching frame found'));
+                                    }
+                                    // Show caption info
+                                    if (captionText && opts.caption !== false) {
+                                        const lines = captionText.split('\n').length;
+                                        console.log(pc.dim(`    Caption: "${captionText.substring(0, 50)}${captionText.length > 50 ? '...' : ''}" (${captionText.length} chars, ${lines} line${lines > 1 ? 's' : ''})`));
+                                        // Show font info
+                                        const fontName = deviceConfig.captionFont || config.caption.font;
+                                        console.log(pc.dim(`    Font: ${fontName}`));
+                                    }
+                                    // Show output info
+                                    console.log(pc.dim(`    Output: ${outWidth}x${outHeight} → ${outputPath}`));
+                                    totalProcessed++;
                                 }
-                                catch (error) {
-                                    console.error(pc.red(`  ✗ ${path.basename(inputPath)}`), error instanceof Error ? error.message : String(error));
-                                    return;
+                                else {
+                                    // Actual rendering
+                                    let image;
+                                    try {
+                                        image = await composeAppStoreScreenshot({
+                                            screenshot: screenshotBuffer,
+                                            frame: frame,
+                                            frameMetadata: frameMetadata ? {
+                                                frameWidth: frameMetadata.frameWidth,
+                                                frameHeight: frameMetadata.frameHeight,
+                                                screenRect: frameMetadata.screenRect,
+                                                maskPath: frameMetadata.maskPath,
+                                                deviceType: frameMetadata.deviceType,
+                                                displayName: frameMetadata.displayName,
+                                                name: frameMetadata.name
+                                            } : undefined,
+                                            caption: opts.caption !== false ? captionText : undefined,
+                                            captionConfig: config.caption,
+                                            gradientConfig: config.gradient,
+                                            deviceConfig: deviceConfig,
+                                            outputWidth: outWidth,
+                                            outputHeight: outHeight,
+                                            verbose: opts.verbose
+                                        });
+                                    }
+                                    catch (error) {
+                                        console.error(pc.red(`  ✗ ${path.basename(inputPath)}`), error instanceof Error ? error.message : String(error));
+                                        return;
+                                    }
+                                    // Save final image
+                                    await sharp(image)
+                                        .resize(opts.preview ? 800 : undefined, undefined, {
+                                        fit: 'inside',
+                                        withoutEnlargement: true
+                                    })
+                                        .png() // Ensure output is PNG
+                                        .toFile(outputPath);
+                                    console.log(pc.green('  ✓'), path.basename(outputPath), pc.dim(`[${orientation}${frameUsed ? ', framed' : ''}${captionText ? ', captioned' : ''}]`));
+                                    totalProcessed++;
                                 }
-                                // Save final image
-                                await sharp(image)
-                                    .resize(opts.preview ? 800 : undefined, undefined, {
-                                    fit: 'inside',
-                                    withoutEnlargement: true
-                                })
-                                    .png() // Ensure output is PNG
-                                    .toFile(outputPath);
-                                console.log(pc.green('  ✓'), path.basename(outputPath), pc.dim(`[${orientation}${frameUsed ? ', framed' : ''}${captionText ? ', captioned' : ''}]`));
-                                totalProcessed++;
                             }
                             catch (error) {
                                 console.log(pc.red('  ✗'), screenshot, pc.dim(error instanceof Error ? error.message : String(error)));
@@ -193,12 +270,18 @@ export default function buildCmd() {
                 }
             }
             // Summary
-            console.log('\n' + pc.bold('Build complete!'));
-            console.log(pc.green(`✓ ${totalProcessed} screenshots processed`));
-            if (totalErrors > 0) {
-                console.log(pc.red(`✗ ${totalErrors} errors`));
+            if (opts.dryRun) {
+                console.log('\n' + pc.bold('Dry run complete!'));
+                console.log(pc.cyan(`→ ${totalProcessed} screenshots would be generated`));
+            }
+            else {
+                console.log('\n' + pc.bold('Build complete!'));
+                console.log(pc.green(`✓ ${totalProcessed} screenshots processed`));
+                if (totalErrors > 0) {
+                    console.log(pc.red(`✗ ${totalErrors} errors`));
+                }
+                console.log(pc.dim(`Output directory: ${config.output}`));
             }
-            console.log(pc.dim(`Output directory: ${config.output}`));
         }
         catch (error) {
             console.error(pc.red('Error:'), error instanceof Error ? error.message : String(error));