appshot-cli 0.8.5 → 0.8.7

package/README.md

@@ -8,9 +8,9 @@
 [![Node.js Version](https://img.shields.io/node/v/appshot-cli.svg)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-🆕 **Version 0.8.5** - **Watch Mode & Device Capture** - File system monitoring with auto-processing and direct iOS simulator capture!
+🆕 **Version 0.8.6** - **Background Images** - Replace gradients with custom static images, auto-detection, and dimension validation!
 
-> ⚠️ **NEW in v0.8.5**: `appshot watch` for automatic screenshot processing and `appshot device` for iOS simulator capture (macOS only). Includes duplicate detection and background service management.
+> ⚠️ **NEW in v0.8.6**: Use custom background images instead of gradients! Auto-detects `background.png` in device folders, supports multiple fit modes, and validates dimensions against App Store specs.
 
 > ⚠️ **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/`.
@@ -170,7 +170,7 @@ final/
 
 ### Project Structure
 
-Appshot uses a simple, predictable directory structure:
+Appshot creates and manages the following directory structure in your project:
 
 ```
 your-project/
@@ -178,16 +178,38 @@ your-project/
 │   ├── config.json          # Main configuration
 │   ├── captions/            # Device-specific captions
 │   │   ├── iphone.json
-│   │   └── ipad.json
-│   └── caption-history.json # Autocomplete history
-├── screenshots/             # Original screenshots
+│   │   ├── ipad.json
+│   │   ├── mac.json
+│   │   └── watch.json
+│   ├── caption-history.json # Autocomplete history (created on use)
+│   ├── ai-config.json       # AI translation settings (optional)
+│   ├── processed/           # Watch mode tracking (macOS only)
+│   └── watch.pid            # Watch service PID (macOS only)
+├── screenshots/             # Your original screenshots
 │   ├── iphone/
+│   │   └── background.png  # Optional device background
 │   ├── ipad/
-│   └── mac/
-├── frames/                  # Device frames (auto-downloaded)
+│   ├── mac/
+│   └── watch/
 └── final/                   # Generated output
+    ├── iphone/
+    │   ├── en/              # Language subdirectory (always created)
+    │   ├── es/              # Additional languages as needed
+    │   └── fr/
+    └── ipad/
+        └── en/
 ```
 
+**Created by `appshot init`:**
+- `.appshot/` directory with config.json
+- `.appshot/captions/` with device JSON files
+- `screenshots/` directories for each device type
+
+**Created during usage:**
+- `final/` - Created when you run `appshot build`
+- `.appshot/caption-history.json` - Created when using captions
+- `.appshot/processed/` - Created by watch mode (macOS)
+
 ### Configuration Overview
 
 All settings are stored in `.appshot/config.json`:
@@ -207,7 +229,7 @@ All settings are stored in `.appshot/config.json`:
   },
   "devices": {
     "iphone": {
-      "resolution": "1284x2778",
+      "resolution": "1290x2796",
       "autoFrame": true
     }
   }
@@ -267,6 +289,129 @@ appshot gradients --sample
 }
 ```
 
+### Background System (NEW in v0.8.6)
+
+Replace gradients with custom static background images for a unique, branded look. Appshot supports automatic detection, multiple formats, and intelligent scaling.
+
+#### Background Locations
+
+Backgrounds are searched in priority order:
+
+1. **Device-specific**: `screenshots/<device>/background.png`
+2. **Global**: `screenshots/background.png`  
+3. **Custom**: Path specified via config or CLI
+
+#### Background Commands
+
+```bash
+# Set background for a device
+appshot backgrounds set iphone ./backgrounds/sunset.jpg
+
+# Set global background for all devices
+appshot backgrounds set --global ./backgrounds/brand-bg.png
+
+# Validate dimensions against App Store specs
+appshot backgrounds validate
+
+# List all configured backgrounds
+appshot backgrounds list
+
+# Clear background configuration
+appshot backgrounds clear iphone
+```
+
+#### Build Options
+
+```bash
+# Auto-detect background.png in device folders
+appshot build --auto-background
+
+# Use specific background image
+appshot build --background ./assets/custom-bg.png
+
+# Set background fit mode
+appshot build --background-fit cover
+
+# Disable backgrounds (transparent)
+appshot build --no-background
+```
+
+#### Fit Modes
+
+- **`cover`** - Scale to cover entire area (may crop)
+- **`contain`** - Scale to fit within area (may add letterbox bars)
+- **`fill`** - Stretch to exact dimensions (may distort)
+- **`scale-down`** - Only scale down if larger, never scale up
+
+#### Creating Backgrounds with ImageMagick
+
+ImageMagick is a powerful CLI tool for creating custom backgrounds:
+
+```bash
+# Solid color background
+magick -size 1290x2796 canvas:navy background.png
+
+# Gradient background
+magick -size 1290x2796 gradient:blue-purple background.png
+
+# Radial gradient
+magick -size 1290x2796 radial-gradient:white-darkblue background.png
+
+# Plasma fractal pattern
+magick -size 1290x2796 plasma:fractal background.png
+
+# Blurred noise texture
+magick -size 1290x2796 xc: +noise Random -blur 0x10 background.png
+
+# Tiled pattern
+magick -size 100x100 pattern:checkerboard -scale 1290x2796 background.png
+
+# Multi-point color interpolation
+magick -size 1290x2796 xc: -sparse-color barycentric \
+  '0,0 skyblue 1290,0 white 645,2796 lightblue' background.png
+```
+
+#### Configuration
+
+```json
+{
+  "background": {
+    "mode": "image",
+    "image": "./backgrounds/global.png",
+    "fit": "cover"
+  },
+  "devices": {
+    "iphone": {
+      "background": {
+        "image": "./backgrounds/iphone.png",
+        "fit": "contain"
+      }
+    }
+  }
+}
+```
+
+#### Mixed Configurations
+
+You can mix backgrounds and gradients across devices:
+
+- iPhone uses a custom background image
+- iPad falls back to gradient
+- Mac uses a different background
+- Watch uses the global background
+
+This flexibility allows you to optimize each device's appearance independently.
+
+#### Dimension Validation
+
+Appshot validates background dimensions and warns about:
+
+- Images smaller than target resolution (will be upscaled)
+- Aspect ratio mismatches (may cause cropping/distortion)
+- Large file sizes (>10MB triggers optimization suggestion)
+
+Use `appshot backgrounds validate` to check all backgrounds before building.
+
 ### Font System
 
 Version 0.4.0 introduces comprehensive font management with intelligent fallbacks.
@@ -1345,7 +1490,7 @@ appshot validate [options]
   "devices": {
     "iphone": {
       "input": "./screenshots/iphone",
-      "resolution": "1284x2778",
+      "resolution": "1290x2796",
       "autoFrame": true,
       "preferredFrame": "frame-name",
       "partialFrame": false,
@@ -1375,7 +1520,7 @@ Each device can override global settings:
     "iphone": {
       // Required
       "input": "./screenshots/iphone",
-      "resolution": "1284x2778",
+      "resolution": "1290x2796",
       
       // Frame options
       "autoFrame": true,
@@ -1531,7 +1676,7 @@ cat > .appshot/config.json << EOF
 {
   "gradient": {"colors": ["#FF5733", "#FFC300"]},
   "devices": {
-    "iphone": {"resolution": "1284x2778"}
+    "iphone": {"resolution": "1290x2796"}
   }
 }
 EOF
@@ -1569,7 +1714,7 @@ def generate_screenshots(device, captions):
     config = {
         "gradient": {"colors": ["#0077BE", "#33CCCC"]},
         "devices": {
-            device: {"resolution": "1284x2778"}
+            device: {"resolution": "1290x2796"}
         }
     }
     
@@ -1679,7 +1824,7 @@ For identical device positioning across all screenshots:
 {
   "devices": {
     "iphone": {
-      "resolution": "1284x2778",
+      "resolution": "1290x2796",
       "autoFrame": false,
       "preferredFrame": "iphone-16-pro-max-portrait",
       "frameScale": 0.85,
@@ -1927,12 +2072,25 @@ appshot/
 ├── src/
 │   ├── cli.ts              # Entry point
 │   ├── commands/           # Command implementations
-│   ├── core/              # Core functionality
-│   ├── services/          # Services (fonts, translation)
-│   └── types.ts           # TypeScript definitions
-├── tests/                 # Test files
-├── frames/               # Device frame images
-└── examples/            # Example projects
+│   ├── core/               # Core functionality
+│   ├── services/           # Services (fonts, translation, etc)
+│   ├── types/              # TypeScript type definitions
+│   ├── utils/              # Utility functions
+│   └── types.ts            # Main type definitions
+├── tests/                  # Test files
+│   ├── integration/        # Integration tests
+│   └── visual/             # Visual regression tests
+├── fonts/                  # Embedded font files
+│   ├── Inter/
+│   ├── Poppins/
+│   ├── Montserrat/
+│   └── ...                 # 10+ font families
+├── frames/                 # Device frame images
+├── assets/                 # Static assets
+│   ├── specs/              # App Store specifications
+│   └── frames/             # Frame metadata
+└── examples/               # Example projects
+    └── minimal-project/    # Basic example setup
 ```
 
 ### Testing
@@ -2044,7 +2202,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.8.5
+- 🔄 Latest version: 0.8.6
 
 ---
 

package/dist/cli.js

@@ -12,6 +12,7 @@ import presetsCmd from './commands/presets.js';
 import validateCmd from './commands/validate.js';
 import styleCmd from './commands/style.js';
 import gradientsCmd from './commands/gradients.js';
+import backgroundsCmd from './commands/backgrounds.js';
 import fontsCmd from './commands/fonts.js';
 import migrateCmd from './commands/migrate.js';
 import { createCleanCommand } from './commands/clean.js';
@@ -23,12 +24,12 @@ import watchStatusCmd from './commands/watch-status.js';
 const program = new Command();
 program
     .name('appshot')
-    .description(`Generate App Store–ready screenshots with frames, gradients, and captions.
+    .description(`Generate App Store–ready screenshots with frames, backgrounds, and captions.
 
 ${pc.bold('Features:')}
   • Auto-detects portrait/landscape orientation
   • 8 embedded font families with italic & bold variants  
-  • 24+ gradient presets with visual preview
+  • Custom background images or 24+ gradient presets
   • AI-powered translation to 25+ languages
   • Smart caption wrapping and positioning
   • All official App Store resolutions
@@ -44,6 +45,7 @@ ${pc.bold('Quick Start:')}
 ${pc.bold('Common Workflows:')}
   $ appshot fonts --set "Poppins Italic"     # Set italic font
   $ appshot gradients select                  # Pick gradient
+  $ appshot backgrounds set iphone bg.jpg     # Set background image
   $ appshot frame ./screenshots --recursive   # Batch frame images
   $ appshot build --preset iphone-6-9,ipad-13 # App Store presets
   $ appshot localize --langs es,fr,de        # Batch translate${platform() === 'darwin' ? `
@@ -51,7 +53,7 @@ ${pc.bold('Common Workflows:')}
   $ appshot watch start --process             # Auto-process new screenshots` : ''}
 
 ${pc.dim('Docs: https://github.com/chrisvanbuskirk/appshot')}`)
-    .version('0.8.5')
+    .version('0.8.7')
     .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)
@@ -66,6 +68,7 @@ program.addCommand(initCmd());
 program.addCommand(captionCmd());
 program.addCommand(styleCmd());
 program.addCommand(gradientsCmd());
+program.addCommand(backgroundsCmd());
 program.addCommand(fontsCmd());
 program.addCommand(localizeCmd());
 program.addCommand(buildCmd());

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/backgrounds.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export default function backgroundsCommand(): Command;
+//# sourceMappingURL=backgrounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backgrounds.d.ts","sourceRoot":"","sources":["../../src/commands/backgrounds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,MAAM,CAAC,OAAO,UAAU,kBAAkB,IAAI,OAAO,CAmWpD"}

package/dist/commands/backgrounds.js

@@ -0,0 +1,323 @@
+import { Command } from 'commander';
+import { promises as fs } from 'fs';
+import path from 'path';
+import pc from 'picocolors';
+import { select, input } from '@inquirer/prompts';
+import { validateBackgroundDimensions, detectBestFit } from '../core/background.js';
+import { loadConfig, saveConfig } from '../core/files.js';
+export default function backgroundsCommand() {
+    const cmd = new Command('backgrounds')
+        .description('Manage background images for screenshots')
+        .addHelpText('after', `
+${pc.bold('Examples:')}
+  $ appshot backgrounds set iphone ./backgrounds/sunset.jpg
+  $ appshot backgrounds validate
+  $ appshot backgrounds preview
+  $ appshot backgrounds clear iphone
+  $ appshot backgrounds list
+
+${pc.bold('Background Locations:')}
+  Device-specific:  screenshots/<device>/background.png
+  Global:          screenshots/background.png
+  Custom:          Specified via config or command
+
+${pc.bold('Fit Modes:')}
+  cover      Scale to cover entire area (may crop)
+  contain    Scale to fit within area (may add bars)
+  fill       Stretch to exact dimensions (may distort)
+  scale-down Only scale down if larger, never scale up
+`);
+    // Set background for a device
+    cmd
+        .command('set')
+        .description('Set background image for a device')
+        .argument('[device]', 'Device type (iphone, ipad, mac, watch)')
+        .argument('[image]', 'Path to background image')
+        .option('-f, --fit <mode>', 'Fit mode: cover, contain, fill, scale-down', 'cover')
+        .option('--global', 'Set as global background for all devices')
+        .action(async (device, image, options) => {
+        try {
+            // Interactive mode if arguments not provided
+            if (!device && !options.global) {
+                device = await select({
+                    message: 'Select device type:',
+                    choices: [
+                        { name: 'iPhone', value: 'iphone' },
+                        { name: 'iPad', value: 'ipad' },
+                        { name: 'Mac', value: 'mac' },
+                        { name: 'Watch', value: 'watch' },
+                        { name: 'All Devices (Global)', value: 'global' }
+                    ]
+                });
+                if (device === 'global') {
+                    options.global = true;
+                    device = undefined;
+                }
+            }
+            if (!image) {
+                image = await input({
+                    message: 'Enter path to background image:',
+                    validate: async (value) => {
+                        try {
+                            await fs.access(value);
+                            return true;
+                        }
+                        catch {
+                            return 'File not found';
+                        }
+                    }
+                });
+            }
+            // Validate image exists
+            try {
+                await fs.access(image);
+            }
+            catch {
+                console.error(pc.red(`❌ Background image not found: ${image}`));
+                process.exit(1);
+            }
+            // Load config
+            const config = await loadConfig();
+            // Initialize background config if not exists
+            if (!config.background) {
+                config.background = {
+                    mode: 'image',
+                    warnOnMismatch: true
+                };
+            }
+            // Set background
+            if (options.global) {
+                config.background.image = image;
+                config.background.fit = options.fit;
+                console.log(pc.green(`✅ Set global background: ${image}`));
+            }
+            else {
+                // Device-specific background
+                if (!config.devices[device]) {
+                    console.error(pc.red(`❌ Device '${device}' not found in config`));
+                    console.log(pc.dim(`Available devices: ${Object.keys(config.devices).join(', ')}`));
+                    process.exit(1);
+                }
+                if (!config.devices[device].background) {
+                    config.devices[device].background = {};
+                }
+                config.devices[device].background.image = image;
+                config.devices[device].background.fit = options.fit;
+                console.log(pc.green(`✅ Set ${device} background: ${image}`));
+            }
+            // Save config
+            await saveConfig(config);
+            console.log(pc.dim('Configuration saved'));
+        }
+        catch (error) {
+            console.error(pc.red('Error setting background:'), error);
+            process.exit(1);
+        }
+    });
+    // Validate backgrounds
+    cmd
+        .command('validate')
+        .description('Validate background dimensions against App Store specs')
+        .option('-d, --device <type>', 'Validate specific device only')
+        .action(async (options) => {
+        try {
+            const config = await loadConfig();
+            let hasWarnings = false;
+            // Get devices to validate
+            const devices = options.device
+                ? [options.device]
+                : Object.keys(config.devices);
+            console.log(pc.bold('\n📐 Validating background dimensions...\n'));
+            for (const device of devices) {
+                const deviceConfig = config.devices[device];
+                if (!deviceConfig)
+                    continue;
+                // Find background image
+                let backgroundPath = null;
+                if (deviceConfig.background?.image) {
+                    backgroundPath = deviceConfig.background.image;
+                }
+                else if (config.background?.image) {
+                    backgroundPath = config.background.image;
+                }
+                else {
+                    // Check for auto-detected background
+                    const candidates = [
+                        path.join(deviceConfig.input, 'background.png'),
+                        path.join(deviceConfig.input, 'background.jpg'),
+                        path.join('screenshots', 'background.png'),
+                        path.join('screenshots', 'background.jpg')
+                    ];
+                    for (const candidate of candidates) {
+                        try {
+                            await fs.access(candidate);
+                            backgroundPath = candidate;
+                            break;
+                        }
+                        catch {
+                            // Continue checking
+                        }
+                    }
+                }
+                if (!backgroundPath) {
+                    console.log(pc.dim(`${device}: No background image found`));
+                    continue;
+                }
+                // Get target dimensions
+                const [width, height] = deviceConfig.resolution.split('x').map(Number);
+                // Validate
+                const validation = await validateBackgroundDimensions(backgroundPath, width, height);
+                // Display results
+                console.log(pc.cyan(`${device}:`));
+                console.log(pc.dim(`  Background: ${backgroundPath}`));
+                console.log(pc.dim(`  Source: ${validation.dimensions.source.width}x${validation.dimensions.source.height}`));
+                console.log(pc.dim(`  Target: ${validation.dimensions.target.width}x${validation.dimensions.target.height}`));
+                if (validation.warnings.length > 0) {
+                    hasWarnings = true;
+                    validation.warnings.forEach(warning => {
+                        console.log(pc.yellow(`  ⚠️  ${warning}`));
+                    });
+                    // Suggest best fit mode
+                    const bestFit = detectBestFit(validation.dimensions.source.width, validation.dimensions.source.height, validation.dimensions.target.width, validation.dimensions.target.height);
+                    console.log(pc.cyan(`  💡 Suggested fit mode: ${bestFit}`));
+                }
+                else {
+                    console.log(pc.green('  ✅ Dimensions OK'));
+                }
+                console.log();
+            }
+            if (hasWarnings) {
+                console.log(pc.yellow('⚠️  Some backgrounds have dimension warnings'));
+                console.log(pc.dim('Run "appshot backgrounds set" to adjust fit modes'));
+            }
+            else {
+                console.log(pc.green('✅ All backgrounds validated successfully'));
+            }
+        }
+        catch (error) {
+            console.error(pc.red('Error validating backgrounds:'), error);
+            process.exit(1);
+        }
+    });
+    // Preview backgrounds
+    cmd
+        .command('preview')
+        .description('Generate preview of screenshots with backgrounds')
+        .option('-d, --device <type>', 'Preview specific device only')
+        .option('-o, --output <dir>', 'Output directory', './preview')
+        .action(async (options) => {
+        try {
+            const config = await loadConfig();
+            const outputDir = options.output;
+            // Create output directory
+            await fs.mkdir(outputDir, { recursive: true });
+            console.log(pc.bold('\n🎨 Generating background previews...\n'));
+            // This would integrate with the compose system
+            // For now, just show what would be generated
+            const devices = options.device
+                ? [options.device]
+                : Object.keys(config.devices);
+            for (const device of devices) {
+                console.log(pc.cyan(`${device}:`));
+                console.log(pc.dim(`  Would generate preview in ${outputDir}/${device}/`));
+            }
+            console.log(pc.dim('\nNote: Full preview generation requires running "appshot build --preview"'));
+        }
+        catch (error) {
+            console.error(pc.red('Error generating preview:'), error);
+            process.exit(1);
+        }
+    });
+    // Clear background
+    cmd
+        .command('clear')
+        .description('Remove background configuration')
+        .argument('[device]', 'Device type to clear (or "all" for global)')
+        .action(async (device) => {
+        try {
+            if (!device) {
+                device = await select({
+                    message: 'Clear background for:',
+                    choices: [
+                        { name: 'iPhone', value: 'iphone' },
+                        { name: 'iPad', value: 'ipad' },
+                        { name: 'Mac', value: 'mac' },
+                        { name: 'Watch', value: 'watch' },
+                        { name: 'All Devices (Global)', value: 'all' }
+                    ]
+                });
+            }
+            const config = await loadConfig();
+            if (device === 'all') {
+                // Clear global background
+                if (config.background) {
+                    delete config.background.image;
+                    console.log(pc.green('✅ Cleared global background'));
+                }
+            }
+            else {
+                // Clear device-specific background
+                if (config.devices[device]?.background) {
+                    delete config.devices[device].background.image;
+                    console.log(pc.green(`✅ Cleared ${device} background`));
+                }
+            }
+            await saveConfig(config);
+            console.log(pc.dim('Configuration saved'));
+        }
+        catch (error) {
+            console.error(pc.red('Error clearing background:'), error);
+            process.exit(1);
+        }
+    });
+    // List backgrounds
+    cmd
+        .command('list')
+        .description('List configured backgrounds')
+        .action(async () => {
+        try {
+            const config = await loadConfig();
+            console.log(pc.bold('\n📋 Configured Backgrounds:\n'));
+            // Global background
+            if (config.background?.image) {
+                console.log(pc.cyan('Global:'));
+                console.log(pc.dim(`  Image: ${config.background.image}`));
+                console.log(pc.dim(`  Fit: ${config.background.fit || 'cover'}`));
+                console.log();
+            }
+            // Device-specific backgrounds
+            for (const [device, deviceConfig] of Object.entries(config.devices)) {
+                if (deviceConfig.background?.image) {
+                    console.log(pc.cyan(`${device}:`));
+                    console.log(pc.dim(`  Image: ${deviceConfig.background.image}`));
+                    console.log(pc.dim(`  Fit: ${deviceConfig.background.fit || 'cover'}`));
+                    console.log();
+                }
+            }
+            // Auto-detected backgrounds
+            console.log(pc.bold('Auto-detected backgrounds:'));
+            for (const [device, deviceConfig] of Object.entries(config.devices)) {
+                const candidates = [
+                    path.join(deviceConfig.input, 'background.png'),
+                    path.join(deviceConfig.input, 'background.jpg')
+                ];
+                for (const candidate of candidates) {
+                    try {
+                        await fs.access(candidate);
+                        console.log(pc.dim(`  ${device}: ${candidate}`));
+                        break;
+                    }
+                    catch {
+                        // Not found
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error(pc.red('Error listing backgrounds:'), error);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=backgrounds.js.map