backend/docs/NEW_FEATURES.md

New Features Guide

This document describes the newly implemented features in Screenshot Studio.

1. Content Preview

Preview AI-generated HTML before creating screenshots to verify formatting and content.

How to Use:

1. Enter your text content
2. Click "Preview HTML" button
3. Review the formatted HTML in the preview modal
4. Copy HTML to clipboard if needed
5. Click "Continue to Generate" to create screenshots

Benefits:

• Verify AI formatting before generating screenshots
• Save API calls by checking output first
• Copy HTML for use in other applications

API Endpoint:

POST /preview
Body: { "text": "your content", "use_cache": true }
Response: { "success": true, "html_content": "..." }

2. Retry Mechanism with Exponential Backoff

Automatically retry failed AI requests with increasing delays between attempts.

Configuration:

• Max retries: 3 attempts
• Base delay: 2 seconds
• Max delay: 30 seconds
• Exponential backoff: delay doubles each retry

How It Works:

1. First attempt fails → wait 2 seconds
2. Second attempt fails → wait 4 seconds
3. Third attempt fails → wait 8 seconds
4. After 3 retries, return error

Benefits:

• Handles temporary network issues
• Reduces failed requests due to rate limiting
• Automatic recovery without user intervention

Implementation:

The retry logic is implemented in src/utils/retry_handler.py and automatically applied to all AI requests.

3. Response Caching

Cache AI responses to save API calls and reduce costs for identical inputs.

How It Works:

• Input text is hashed (SHA-256)
• Response is stored in output/cache/ai_responses.json
• Subsequent identical requests use cached response
• Cache persists across server restarts

Benefits:

• Save API costs for repeated content
• Faster response for cached requests
• Automatic cache management

API Endpoints:

Get Cache Statistics:

GET /cache/stats
Response: {
  "total_entries": 5,
  "cache_file": "output/cache/ai_responses.json",
  "cache_size_kb": 12.5
}

Clear Cache:

POST /cache/clear
Response: { "success": true, "message": "Cache cleared successfully" }

Disable Caching:

Set use_cache: false in the request body to bypass cache.

4. Watermark Support

Add custom text or logo watermarks to screenshots for branding.

Text Watermark:

Settings:

• Watermark Text: Custom text to display
• Position: top-left, top-right, bottom-left, bottom-right, center
• Opacity: 0-255 (default: 128)
• Font Size: Adjustable (default: 20px)
• Color: RGB tuple (default: white)

How to Use:

1. Expand "Advanced Settings"
2. Enter watermark text
3. Select position
4. Generate screenshots

Example:

from utils.watermark import WatermarkManager

wm = WatermarkManager()
wm.add_watermark(
    "screenshot.png",
    text="My Brand",
    position="bottom-right",
    opacity=128
)

Logo Watermark:

Settings:

• Logo Path: Path to logo image file
• Position: Same as text watermark
• Scale: Logo size relative to image (0.0-1.0)
• Opacity: 0-255

Example:

wm.add_logo_watermark(
    "screenshot.png",
    logo_path="logo.png",
    position="bottom-right",
    scale=0.1,
    opacity=128
)

5. Multiple Resolution Presets

Quick access to common device and use-case resolutions.

Available Presets:

Mobile:

• Mobile Portrait (375x667) - iPhone SE/8
• Mobile Portrait Large (414x896) - iPhone 11 Pro Max
• Mobile Landscape (667x375)

Tablet:

• Tablet Portrait (768x1024) - iPad
• Tablet Landscape (1024x768)
• Tablet Pro (1024x1366) - iPad Pro 12.9"

Desktop:

• Desktop HD (1366x768) - Standard laptop
• Desktop Full HD (1920x1080) - Default
• Desktop 2K (2560x1440)
• Desktop 4K (3840x2160)

Social Media:

• Instagram Post (1080x1080) - Square 1:1
• Instagram Story (1080x1920) - Vertical 9:16
• Twitter Post (1200x675) - 16:9
• Facebook Post (1200x630)

Print:

• Print A4 Portrait (2480x3508) - 300 DPI
• Print A4 Landscape (3508x2480) - 300 DPI
• Print Letter (2550x3300) - US Letter 300 DPI

Presentation:

• Presentation 16:9 (1920x1080)
• Presentation 4:3 (1024x768)

How to Use:

1. Select preset from "Resolution Preset" dropdown
2. Dimensions and zoom automatically applied
3. Or use "Custom" and set manual values

API Endpoint:

GET /presets
Response: {
  "presets": {
    "Mobile": [...],
    "Tablet": [...],
    "Desktop": [...],
    ...
  }
}

Programmatic Access:

from utils.resolution_presets import ResolutionPresets

# Get specific preset
preset = ResolutionPresets.get_preset("desktop-4k")
# Returns: {"name": "Desktop 4K", "width": 3840, "height": 2160, "zoom": 2.0, ...}

# Get all presets by category
presets = ResolutionPresets.get_presets_by_category()

# Get preset names
names = ResolutionPresets.get_preset_names()

Usage Examples

Example 1: Generate with Watermark and Preset

const settings = {
    text: "My content",
    watermark_text: "© 2024 My Company",
    watermark_position: "bottom-right",
    resolution_preset: "instagram-post",
    use_cache: true
};

const response = await fetch('/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(settings)
});

Example 2: Preview Before Generating

// Step 1: Preview
const preview = await fetch('/preview', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: "My content" })
});
const previewData = await preview.json();
console.log(previewData.html_content);

// Step 2: Generate if satisfied
const generate = await fetch('/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: "My content" })
});

Example 3: Check Cache Stats

const stats = await fetch('/cache/stats');
const data = await stats.json();
console.log(`Cache has ${data.total_entries} entries`);

Configuration

All features work out of the box with sensible defaults. Advanced users can customize:

Cache Location:

Edit src/utils/cache_manager.py:

cache = CacheManager(cache_dir="custom/path")

Retry Settings:

Edit src/core/ai_client.py:

@retry_with_backoff(max_retries=5, base_delay=1, max_delay=60)

Watermark Defaults:

Edit src/utils/watermark.py:

self.default_text = "Your Brand"
self.default_position = "top-right"
self.default_opacity = 200

Troubleshooting

Preview Not Working:

• Check browser console for errors
• Verify AI API is responding
• Check cache stats to see if response is cached

Watermark Not Appearing:

• Ensure watermark text is not empty
• Check image file permissions
• Verify Pillow is installed: pip install Pillow

Cache Not Saving:

• Check output/cache/ directory exists
• Verify write permissions
• Check disk space

Preset Not Applying:

• Ensure JavaScript is enabled
• Check browser console for errors
• Verify /presets endpoint is accessible

Performance Tips

1. Use Caching: Enable caching for repeated content
2. Preview First: Use preview to verify before generating
3. Choose Appropriate Presets: Use smaller resolutions when possible
4. Watermark Wisely: Add watermarks only when needed
5. Monitor Cache: Clear cache periodically to save disk space

Future Enhancements

Potential improvements for these features:

• Cache expiration policies
• Watermark templates library
• Custom preset creation UI
• Batch watermarking
• Preview with watermark
• Cache compression
• Retry statistics dashboard