Screenshot Toolkit

A high-performance cross-platform screenshot tool with interactive region selection and multi-monitor support.

🤖 AI-Generated Project: This entire codebase is generated and driven by AI, demonstrating the power of AI-assisted development workflows.

中文文档 README.zh-CN.md

✨ Features

🤖 AI-Driven Development

This project showcases the capabilities of AI-assisted software development:

• Complete Code Generation: All Rust code, architecture, and implementation generated by AI
• AI-Guided Workflow: Development process entirely driven by AI planning and execution
• Intelligent Problem Solving: Complex technical challenges solved through AI reasoning
• Automated Documentation: Technical docs, PRD, and TODO management handled by AI

🎯 Core Capabilities (v0.1 - Current)

• 🖱️ Interactive Region Selection: Custom GUI overlay with mouse drag selection
• 🖥️ Multi-Monitor Support: Full cross-monitor area selection with virtual desktop coordinates
• ⚡ Metal GPU Acceleration: Native macOS Metal rendering with 60 FPS performance
• 📸 Smart Screenshot Strategy: Optimized single-monitor cropping vs cross-monitor composition
• 💾 High-Quality Export: PNG output with system clipboard integration
• 🏷️ Smart Naming: Time-based templates with sequence numbering
• 🛡️ Robust Error Handling: User-friendly permission and error messages

🚀 Coming Soon (v0.2)

• ✏️ Annotation Tools: Rectangle, arrow, and freehand drawing tools
• 🎨 Real-time Editing: Live preview with undo/redo support
• 🎛️ Toolbar UI: Intuitive editing interface
• 🎨 Style Customization: Color picker and stroke width controls

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/SoloJiang/vibe-coding-screenshot-toolkit.git
cd screenshot

# Build the project
cargo build --workspace

# Run tests
cargo test --workspace

Basic Usage

Interactive Screenshot (Primary feature):

# Basic interactive screenshot
cargo run -p api_cli -- capture-interactive

# Specify output directory
cargo run -p api_cli -- capture-interactive -d ~/Screenshots

# Copy to clipboard simultaneously
cargo run -p api_cli -- capture-interactive --clipboard

# Custom filename template
cargo run -p api_cli -- capture-interactive -t "MyShot-{date:yyyyMMdd-HHmmss}"

Command Line Options:

cargo run -p api_cli -- capture-interactive --help

Multi-Monitor Environment

• Auto-Detection: Automatically detects all connected monitors
• Cross-Monitor Selection: Select areas spanning multiple displays
• Virtual Desktop Coordinates: Unified coordinate mapping system
• Smart Rendering: Optimized performance for single vs multi-monitor scenarios

🏗️ Architecture

crates/
├── core/           # Core data models, error types, naming templates
├── platform_mac/   # macOS implementation (xcap + Metal GPU)
├── platform_win/   # Windows implementation (framework ready)
├── ui_overlay/     # Interactive region selector with Metal rendering
├── services/       # Business logic: capture, export, annotation services
├── renderer/       # CPU rendering engine (fallback)
├── api_cli/        # Command-line interface
└── infra/          # Infrastructure: metrics, caching, utilities

🎮 User Guide

Interactive Screenshot Workflow

1. Launch: Run capture-interactive command
2. Select Area:
   • Left-click and drag to select rectangular region
   • Supports cross-monitor area selection
   • Use Shift for square selection, Alt for center-stretch
3. Adjust: Drag borders to fine-tune selection
4. Confirm: Press Enter or Space to capture
5. Cancel: Press Esc to abort
6. Export: Automatically saves to file and optionally copies to clipboard

File Naming Templates

Supported variables:

• {date:format} - Date/time formatting
  • {date:yyyyMMdd} → 20240922
  • {date:yyyyMMdd-HHmmss} → 20240922-143022
• {seq} - Daily sequence number (resets daily)

Example: Screenshot-{date:yyyyMMdd-HHmmss}-{seq} → Screenshot-20240922-143022-001.png

macOS Permissions

First-time usage requires screen recording permission:

1. Open "System Preferences" → "Security & Privacy" → "Privacy"
2. Select "Screen Recording"
3. Click lock icon to unlock, check this application
4. Restart the application

🔧 Technical Features

High-Performance Rendering

• Metal GPU Acceleration: Native macOS Metal rendering for 60 FPS
• CPU Fallback: Software rendering for compatibility
• Smart Caching: Background caching and image reuse
• Memory Optimization: Arc sharing to avoid pixel data copying

Multi-Monitor Architecture

• Virtual Desktop System: Unified coordinate mapping across displays
• Smart Capture Strategy:
  • Single monitor selection → Direct crop (optimal performance)
  • Cross-monitor selection → Virtual desktop composition
• Real-time Preview: Live selection feedback during interaction

Cross-Platform Design

• macOS: Complete implementation with Metal GPU acceleration
• Windows: Framework ready, implementation in progress
• Modular Architecture: Platform-specific code isolated in platform modules

📋 Development Roadmap

v0.1 - Interactive Screenshot Core ✅

• Interactive region selection with custom GUI
• Multi-monitor support and cross-monitor selection
• Metal GPU rendering with 60 FPS performance
• PNG export and clipboard integration
• Smart file naming with time templates
• Robust error handling and user guidance

v0.2 - Annotation Editing System 🚧

• Toolbar UI with annotation tools
• Rectangle and arrow drawing tools
• Freehand drawing support
• Color picker and stroke customization
• Undo/redo functionality
• Real-time preview during editing

v0.3 - Advanced Annotation Features 📋

• Text annotation with font selection
• Mosaic and highlight tools
• Advanced editing features
• Annotation templates and presets

v1.0 - Complete Product 🎯

• Windows platform full support
• Global hotkey support
• Plugin system for custom tools
• History management interface
• Cloud sync capabilities

🧪 Testing

# Run all tests
cargo test --workspace

# Run specific module tests
cargo test -p api_cli
cargo test -p platform_mac

# Build release version
cargo build --release

📊 Performance

• Startup Time: < 500ms
• UI Response: < 50ms
• Screenshot Processing: < 1s (4K resolution)
• Memory Usage: < 100MB (without annotation editing)
• Rendering: 60 FPS with Metal GPU acceleration

🤖 AI Development Showcase

This project demonstrates the potential of AI-driven software development:

AI-Generated Components

• Complete Rust Codebase: All 15+ crates and modules generated by AI
• Architecture Design: Modular, cross-platform architecture designed by AI
• Performance Optimization: Metal GPU rendering and 60 FPS optimization implemented by AI
• Error Handling: Comprehensive error handling and user guidance written by AI
• Documentation: Technical docs, PRD, and development tasks managed by AI

AI Development Workflow

• Planning: AI analyzes requirements and creates detailed development plans
• Implementation: AI generates code, tests, and documentation
• Problem Solving: AI identifies and resolves complex technical challenges
• Iteration: AI continuously improves code quality and performance
• Maintenance: AI manages ongoing development and feature additions

🤝 Contributing

This project welcomes contributions that explore AI-assisted development:

1. Follow the existing modular architecture and boundaries
2. All changes must pass the test suite
3. Update documentation for significant features
4. Follow Rust coding standards
5. Consider how AI can enhance the development process

📄 License

MIT License - See LICENSE file for details

🔗 Documentation

• Technical Design
• Product Requirements
• Development Tasks

---

Note: This project currently focuses on the interactive screenshot core functionality. Annotation editing and advanced features are planned for future versions.