appshot-cli 0.9.2 → 1.0.0

package/skill/references/templates.md

@@ -0,0 +1,170 @@
+# Template Reference
+
+8 professional templates for App Store screenshots.
+
+## Template Selection Guide
+
+| App Type | Recommended Template |
+|----------|---------------------|
+| Developer tools, CLI, OSS | `nerdy` |
+| Business, productivity | `corporate` |
+| Games, entertainment | `playful` |
+| Lifestyle, premium | `elegant` |
+| Finance, fintech | `bold` |
+| Social, consumer | `modern` |
+| Health, wellness | `minimal` |
+| Custom backgrounds | `showcase` |
+
+---
+
+## modern
+
+**Modern Vibrant** - Eye-catching gradient with floating device and clean captions
+
+- **Category:** modern
+- **Background:** Purple-pink diagonal gradient (`#667eea` → `#764ba2` → `#f093fb`)
+- **Caption:** Above device, SF Pro Display, dark text (`#021d2f`)
+- **Best for:** Consumer apps, social apps, general-purpose
+
+```
+appshot.template with template: "modern"
+```
+
+---
+
+## minimal
+
+**Minimal Clean** - Soft pastel background with elegant typography
+
+- **Category:** minimal
+- **Background:** Warm peach gradient (`#ffecd2` → `#fcb69f`)
+- **Caption:** Above device, Helvetica Neue, dark text (`#1b2a3a`)
+- **Best for:** Health apps, wellness, lifestyle
+
+```
+appshot.template with template: "minimal"
+```
+
+---
+
+## bold
+
+**Bold Impact** - Dark dramatic gradient with large device and overlay captions
+
+- **Category:** bold
+- **Background:** Dark purple diagonal gradient (`#0f0c29` → `#302b63` → `#24243e`)
+- **Caption:** Overlay at bottom, SF Pro Display, white text
+- **Best for:** Finance apps, security, premium features
+
+```
+appshot.template with template: "bold"
+```
+
+---
+
+## nerdy
+
+**Nerdy OSS** - Grid-lined midnight background with JetBrains Mono captions
+
+- **Category:** bold
+- **Background:** Auto-detect (uses background.png if present)
+- **Caption:** Overlay at bottom, JetBrains Mono Bold, mint green (`#7CFFCB`)
+- **Best for:** Developer tools, CLI apps, open source projects
+
+```
+appshot.template with template: "nerdy"
+```
+
+**Note:** Place a grid/terminal background image at `screenshots/iphone/background.png` for best results.
+
+---
+
+## elegant
+
+**Elegant Professional** - Sophisticated monochrome with floating device
+
+- **Category:** elegant
+- **Background:** Silver gradient (`#8e9eab` → `#eef2f3`)
+- **Caption:** Below device, Georgia serif, dark text (`#132235`)
+- **Best for:** Luxury apps, premium services, professional tools
+
+```
+appshot.template with template: "elegant"
+```
+
+---
+
+## showcase
+
+**Showcase** - Feature your app with custom backgrounds
+
+- **Category:** professional
+- **Background:** Auto-detect with cyan fallback (`#4facfe` → `#00f2fe`)
+- **Caption:** Above device, SF Pro Display, white text
+- **Best for:** Apps with strong visual branding, custom marketing assets
+
+```
+appshot.template with template: "showcase"
+```
+
+**Tip:** Add your branded background to `screenshots/iphone/background.png`
+
+---
+
+## playful
+
+**Playful Energy** - Bright, fun gradients perfect for games and entertainment apps
+
+- **Category:** playful
+- **Background:** Pink-yellow diagonal gradient (`#fa709a` → `#fee140` → `#fa709a`)
+- **Caption:** Above device, SF Pro Display, white text
+- **Best for:** Games, kids apps, entertainment, social
+
+```
+appshot.template with template: "playful"
+```
+
+---
+
+## corporate
+
+**Corporate Professional** - Clean, professional look for business and productivity apps
+
+- **Category:** professional
+- **Background:** Blue-teal gradient (`#0077BE` → `#33CCCC`)
+- **Caption:** Above device, Helvetica, dark text (`#0f1e2d`)
+- **Best for:** Business apps, B2B, enterprise, productivity
+
+```
+appshot.template with template: "corporate"
+```
+
+---
+
+## Applying Templates
+
+```
+# Apply a template
+appshot.template with template: "nerdy"
+
+# Preview without applying
+appshot.template with preview: "modern"
+
+# List all templates
+appshot.template with list: true
+```
+
+## Customizing After Template
+
+Templates set a starting point. Customize further with:
+
+```
+# Change gradient
+appshot.gradients with action: "apply", preset: "sunset"
+
+# Adjust device positioning
+appshot.config with device: "iphone", frameScale: 0.85, framePosition: 30
+
+# Change caption position
+appshot.config with device: "iphone", captionPosition: "below"
+```

package/skill/references/troubleshooting.md

@@ -0,0 +1,228 @@
+# Troubleshooting Guide
+
+Common issues and solutions when using appshot.
+
+---
+
+## Project Setup Issues
+
+### "Configuration not found"
+
+**Cause:** No `.appshot/config.json` exists in the project.
+
+**Solution:**
+```
+appshot.init with force: true
+```
+
+### "Input directory not found"
+
+**Cause:** Screenshot folder doesn't exist or is empty.
+
+**Solution:**
+1. Create the directory: `screenshots/iphone/`
+2. Add PNG/JPG screenshots to the folder
+3. Run build again
+
+---
+
+## Caption Issues
+
+### Captions not appearing
+
+**Causes:**
+1. No captions set for the screenshots
+2. Caption file is empty
+3. Wrong language specified
+
+**Solutions:**
+```
+# Check current captions
+appshot.captions with device: "iphone", action: "list"
+
+# Auto-generate from filenames
+appshot.captions with device: "iphone", action: "auto"
+
+# Set manually
+appshot.captions with device: "iphone", action: "set", filename: "screen.png", caption: "My Caption"
+```
+
+### Caption text cut off
+
+**Cause:** Caption too long for the available space.
+
+**Solutions:**
+1. Use shorter text (2-3 words ideal)
+2. Adjust caption box settings:
+```
+appshot.config with device: "iphone", captionPosition: "above"
+```
+
+### Wrong font displaying
+
+**Cause:** Font not available on system.
+
+**Solution:**
+```
+# Check font availability
+appshot.fonts with action: "validate", font: "SF Pro Display"
+
+# List embedded fonts (always available)
+appshot.fonts with action: "embedded"
+```
+
+**Embedded fonts:** Inter, Poppins, Montserrat, DM Sans, Roboto, Open Sans, Lato, Work Sans, JetBrains Mono, Fira Code
+
+---
+
+## Frame Issues
+
+### "No matching frame found"
+
+**Cause:** Screenshot dimensions don't match any known device.
+
+**Solutions:**
+1. Use standard device resolutions
+2. Check screenshot dimensions match config
+
+**Common iPhone resolutions:**
+- 1290x2796 (iPhone 15 Pro Max, 16 Plus)
+- 1179x2556 (iPhone 15 Pro, 16)
+- 1206x2622 (iPhone 16 Pro)
+
+### Frame looks wrong / misaligned
+
+**Cause:** Screenshot orientation doesn't match frame.
+
+**Solution:** Ensure portrait screenshots are taller than wide, landscape wider than tall.
+
+---
+
+## Build Issues
+
+### Build produces blank/black images
+
+**Causes:**
+1. Screenshot files are corrupted
+2. Sharp module issue
+
+**Solutions:**
+```
+# Run diagnostics
+appshot.doctor
+```
+
+### "Failed to load screenshot"
+
+**Cause:** File is not a valid image or is corrupted.
+
+**Solution:**
+1. Verify the file opens in an image viewer
+2. Re-export from the source
+3. Ensure file extension matches actual format
+
+### Build is slow
+
+**Solutions:**
+```
+# Reduce concurrency on low-memory systems
+appshot.build with concurrency: 2
+
+# Build specific devices only
+appshot.build with devices: ["iphone"]
+
+# Use preview mode for testing
+appshot.build with preview: true
+```
+
+---
+
+## Background Issues
+
+### Background image not appearing
+
+**Causes:**
+1. Image path incorrect
+2. Mode set to gradient instead of image/auto
+
+**Solutions:**
+```
+# Set background explicitly
+appshot.backgrounds with action: "set", image: "./bg.png", fit: "cover"
+
+# Or use auto-detect (looks for background.png in device folders)
+appshot.build with autoBackground: true
+```
+
+### Background looks stretched/cropped
+
+**Solution:** Change fit mode:
+```
+appshot.backgrounds with action: "set", image: "./bg.png", fit: "contain"
+```
+
+Fit modes:
+- `cover` - Fill entire area, may crop (default)
+- `contain` - Show entire image, may letterbox
+- `fill` - Stretch to fill (may distort)
+- `scale-down` - Like contain but never upscale
+
+---
+
+## Validation Issues
+
+### "Resolution mismatch"
+
+**Cause:** Screenshot doesn't match App Store requirements.
+
+**Solution:**
+```
+# Check required specs
+appshot.specs with device: "iphone", required: true
+
+# Use presets for correct sizing
+appshot.build with presets: ["iphone-6-9", "ipad-13"]
+```
+
+### Missing required sizes
+
+**Required for App Store:**
+- iPhone 6.9": 1320x2868 or 1290x2796
+- iPad 13": 2064x2752 or 2048x2732
+
+---
+
+## System Issues
+
+### Sharp module errors
+
+**Solution:**
+```
+# Run doctor to check system
+appshot.doctor
+
+# Reinstall if needed (in terminal)
+npm rebuild sharp
+```
+
+### Permission denied errors
+
+**Cause:** Cannot write to output directory.
+
+**Solution:** Check file permissions on `final/` directory.
+
+---
+
+## Quick Diagnostics
+
+Run the doctor command to check all systems:
+```
+appshot.doctor
+```
+
+This checks:
+- Node.js version (requires 18+)
+- Sharp module installation
+- Font detection capability
+- File system permissions
+- Frame asset availability