appshot-cli 0.4.0 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 [![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.6.0** - 8 embedded OSS fonts with variants, dry-run mode, verbose debugging, and enhanced CLI UX!
 
 > ⚠️ **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 +55,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** - 8 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 +63,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
 
@@ -524,6 +527,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 +553,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:**
@@ -627,9 +638,65 @@ appshot clean --all --yes
 appshot clean --history
 ```
 
+### `appshot doctor`
+
+Run comprehensive system diagnostics to verify appshot installation and dependencies.
+
+```bash
+appshot doctor [options]
+```
+
+**Options:**
+- `--json` - Output results as JSON for CI/automation
+- `--verbose` - Show detailed diagnostic information
+- `--category <categories>` - Run specific checks (comma-separated: system,dependencies,fonts,filesystem,frames)
+
+**Checks:**
+- **System Requirements** - Node.js version (≥18), npm availability, platform detection
+- **Dependencies** - Sharp module installation, native bindings, image processing test, OpenAI API key
+- **Font System** - Font detection commands, system font loading, common font availability
+- **File System** - Write permissions (current/temp directories), .appshot directory, configuration validity
+- **Frame Assets** - Frame directory presence, Frames.json validation, device frame counts, missing files
+
+**Examples:**
+```bash
+# Run all diagnostics
+appshot doctor
+
+# Check specific categories
+appshot doctor --category system,dependencies
+
+# JSON output for CI
+appshot doctor --json
+
+# Verbose mode for debugging
+appshot doctor --verbose
+```
+
+**Output Example:**
+```
+🏥 Appshot Doctor - System Diagnostics
+
+System Requirements:
+  ✓ Node.js v20.5.0 (minimum: v18.0.0)
+  ✓ npm v9.8.0
+  ✓ darwin (macOS)
+
+Dependencies:
+  ✓ Sharp v0.33.5 installed
+  ✓ libvips v8.15.3 loaded
+  ✓ Sharp image processing test passed
+  ⚠ OpenAI API key not found (translation features disabled)
+
+Summary: 20 passed, 1 warning, 0 errors
+
+Suggestions:
+  • Set OPENAI_API_KEY environment variable to enable translation features
+```
+
 ### `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]
@@ -637,29 +704,47 @@ 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
+- **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
@@ -798,21 +883,50 @@ appshot presets --generate iphone-6-9,ipad-13
 
 ### `appshot specs`
 
-Display device specifications.
+Display complete Apple App Store screenshot specifications.
 
 ```bash
 appshot specs [options]
 ```
 
 **Options:**
-- `--device <name>` - Filter by device
-- `--json` - Output as JSON
+- `--device <name>` - Filter by device type (iphone|ipad|mac|watch|appletv|visionpro)
+- `--json` - Output as JSON (exact Apple specifications for diffing)
+- `--required` - Show only required presets
 
 **Shows:**
-- Supported resolutions
-- Frame availability
-- Orientation support
-- App Store requirements
+- Complete Apple specifications with exact resolutions
+- Display sizes and device compatibility lists
+- Required vs optional indicators
+- Fallback notes and requirements
+
+**JSON Output for Change Tracking:**
+The `--json` flag outputs the complete Apple App Store specifications data, perfect for tracking changes over time:
+
+```bash
+# Save current specifications
+appshot specs --json > apple-specs-2024-08.json
+
+# After Apple updates (typically September)
+appshot specs --json > apple-specs-2024-09.json
+
+# See what changed
+diff apple-specs-2024-08.json apple-specs-2024-09.json
+```
+
+**Data Source:**
+The specifications mirror [Apple's official screenshot requirements](https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications) 
+and are maintained in sync with Apple's updates. The JSON output preserves all metadata including:
+- Exact resolutions (e.g., `1290x2796` for iPhone 6.9")
+- Device groupings (which devices share requirements)
+- Requirement status (mandatory vs optional)
+- Fallback rules and special notes
+
+This is particularly useful for:
+- Tracking when Apple adds new device requirements
+- Validating screenshot compliance before submission
+- Automating screenshot generation pipelines
+- Planning resource allocation for new devices
 
 ### `appshot style`
 
@@ -1369,6 +1483,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**
@@ -1547,7 +1689,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

@@ -6,6 +6,7 @@ import localizeCmd from './commands/localize.js';
 import buildCmd from './commands/build.js';
 import specsCmd from './commands/specs.js';
 import checkCmd from './commands/check.js';
+import doctorCmd from './commands/doctor.js';
 import presetsCmd from './commands/presets.js';
 import validateCmd from './commands/validate.js';
 import styleCmd from './commands/style.js';
@@ -16,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.4.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.6.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());
@@ -27,6 +60,7 @@ program.addCommand(localizeCmd());
 program.addCommand(buildCmd());
 program.addCommand(specsCmd());
 program.addCommand(checkCmd());
+program.addCommand(doctorCmd());
 program.addCommand(presetsCmd());
 program.addCommand(validateCmd());
 program.addCommand(migrateCmd());

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,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,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,9 +19,51 @@ 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 devices = opts.devices.split(',').map((d) => d.trim());
@@ -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));