Skip to content
This repository was archived by the owner on Nov 8, 2025. It is now read-only.

cleanup docs #7

Merged
zzfadi merged 1 commit into from
Jul 25, 2025
Merged

cleanup docs #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 59 additions & 20 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,20 @@

## Project Architecture

This is a client-side Next.js 15 app that converts multiple image formats (PNG, JPEG, WebP, GIF, BMP, SVG) to multi-size ICO format in the browser. The app follows a three-component state flow pattern:
This is a client-side Next.js 15 app that converts multiple image formats (PNG, JPEG, WebP, GIF, BMP, SVG) to both ICO and SVG formats with three processing modes:

1. **`page.tsx`**: Central state manager coordinating file upload → preview → conversion
2. **`FileUploader`**: Drag-and-drop with multi-format validation (MIME type detection + size limits)
3. **`Preview`**: Generates multi-size previews and triggers format-specific ICO conversion
**Three Processing Modes:**
1. **Single File**: Traditional one-at-a-time conversion with real-time preview
2. **Batch Processing**: Multi-file upload with parallel processing and ZIP download
3. **Export Presets**: Platform-specific icon packages (iOS, Android, Web, Windows)

**Core Architecture:**
- **`page.tsx`**: Central state manager with complex multi-mode state handling
- **`FileUploader`**: Single-file drag-and-drop with multi-format validation
- **`BatchFileUploader`**: Multi-file uploader with progress tracking
- **`Preview`**: Interactive preview with format switching (ICO/SVG)
- **`ExportPresets`**: Platform preset selection interface
- **`SegmentedControl`**: Mode switching control with accessibility

## Critical Canvas Timeout Pattern

Expand All @@ -33,30 +42,49 @@ Uses "Defined by Jenna" brand colors defined in `globals.css` as CSS variables:

**Styling Convention**: Components use inline `style` props with hex colors instead of Tailwind color classes for brand consistency.

## ICO File Format Implementation

The `imageToIco.ts` utility creates proper multi-size ICO files with binary headers, supporting all image formats with format-specific processing:
## Multi-Format Conversion Implementation

- Maintain the ICO_SIZES array: `[16, 32, 48, 64, 128, 256]`
- The `createIcoFile()` function writes ICO directory headers + PNG data
- Size 256 is encoded as 0 in ICO headers (ICO format limitation)
- **Format-specific processing**: SVG rasterized per-size, raster images use high-quality resampling
**ICO Conversion (`imageToIco.ts`)**:
- Creates proper multi-size ICO files with binary headers for all image formats
- ICO_SIZES array: `[16, 32, 48, 64, 128, 256]` (size 256 encoded as 0 in ICO headers)
- Format-specific processing: SVG rasterized per-size, raster images use high-quality resampling
- **Transparency handling**: Automatic white background for JPEG/BMP formats

**SVG Conversion (`imageToSvg.ts`)**:
- Converts images to scalable SVG format with intelligent sizing
- Preserves transparency for supported formats
- Optimized for different output sizes (32, 64, 128px typically)

**Export Presets (`presetExporter.ts`)**:
- Platform-specific export with predefined size sets and naming conventions
- ZIP packaging with proper folder structures
- Progress tracking for batch operations
- Support for both ICO and PNG formats based on platform requirements

## State Management Pattern

Use the existing unidirectional state flow in `page.tsx`:
- File selection clears previous conversion state
- Error state resets all downstream state (image + ICO)
- Successful conversion prevents re-conversion until new file upload
- **Enhanced metadata**: Format detection, dimensions, and processing hints flow through components
**Complex Multi-Mode State** in `page.tsx`:

**Core Single-File State**: `imageFile`, `imageDataUrl`, `imageMetadata`, `convertedUrl`, `error`
**Mode Management**: `processingMode` ('single' | 'batch' | 'presets'), `currentFormat` ('ico' | 'svg')
**Preset Export State**: `selectedPreset`, `isExportingPreset`, `presetProgress`, `presetExportResult`

**State Flow Patterns**:
- **Single**: FileUploader → Preview → Download
- **Batch**: BatchFileUploader → Progress Tracking → ZIP Download
- **Presets**: PresetSelector → FileUploader → Automated Export → Download

File selection clears previous conversion state across all modes. Error states reset downstream state appropriately for each mode.

## Development Workflow

```bash
npm run dev # Development server (standard Next.js)
npm run build # Production build
npm run lint # ESLint validation
npm run dev # Development server (standard Next.js)
npm run build # Production build
npm run lint # ESLint validation
npm run test:e2e # Run E2E tests (Playwright)
npm run test:e2e:ui # Run E2E tests with UI
npm run test:e2e:debug # Debug E2E tests
```

Local server: http://localhost:3000 (or next available port)
Expand All @@ -70,4 +98,15 @@ Local server: http://localhost:3000 (or next available port)

## Privacy-First Architecture

All processing happens client-side using File API, Canvas API, and Blob URLs. No server endpoints exist for file processing - maintain this architecture for user privacy.
All processing happens client-side using File API, Canvas API, Web Workers, and Blob URLs. No server endpoints exist for file processing - maintain this architecture for user privacy across all three processing modes.

## Testing Framework

**Comprehensive E2E Testing** with Playwright covering all three modes:
- **154 unique test cases** across 10 test files
- **Multi-browser testing**: Chrome, Firefox, Safari, Edge, Mobile Chrome/Safari
- **Key test areas**: Basic functionality, Upload, Conversion, Batch processing, Export presets, UI interactions, Error handling, Performance
- **Test utilities**: Helper functions in `tests/fixtures/helpers/` for common operations
- **CI Integration**: Automated testing with GitHub Actions

See `docs/testing/E2E_TESTING_GUIDE.md` for comprehensive testing documentation.
59 changes: 43 additions & 16 deletions ABOUT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
# About Universal Image to ICO Converter
# About Universal Image Converter

## What is this tool?

Universal Image to ICO Converter is a free, web-based tool that transforms your images into ICO (icon) files right in your browser. Whether you need a favicon for your website, an application icon, or custom desktop icons, our converter handles six major image formats: PNG, JPEG, WebP, GIF, BMP, and SVG.
Universal Image Converter is a free, web-based tool that transforms your images into ICO and SVG formats right in your browser. With three powerful processing modes, it serves everyone from individual developers to teams working on professional applications. The converter handles six major image formats: PNG, JPEG, WebP, GIF, BMP, and SVG.

## Three Processing Modes

**🎯 Single File Mode**: Perfect for quick conversions with real-time preview. Upload one image and get instant feedback with interactive size selection for ICO or scalable SVG output.

**🔥 Batch Processing Mode**: Ideal for bulk operations. Upload multiple images simultaneously, track individual file progress, and download everything in a convenient ZIP package.

**🎨 Export Presets Mode**: Professional icon packages for specific platforms. Choose from iOS, Android, Web, or Windows Desktop presets, and get complete platform-ready icon sets with proper naming conventions and folder structures.

## How it works

Simply drag and drop your image onto our upload area, and the tool automatically detects your file format and creates a multi-size ICO file containing six standard icon sizes (16×16, 32×32, 48×48, 64×64, 128×128, and 256×256 pixels). You can choose which sizes to include and download your ICO file instantly.
The tool adapts to your workflow. In single file mode, drag and drop your image for instant preview and conversion. In batch mode, select multiple files and let the parallel processing handle the heavy lifting. For export presets, simply choose your target platform and upload your image—the tool automatically generates all required sizes and formats.

## Complete Privacy & Security

Expand All @@ -22,38 +30,57 @@ This isn't just a privacy promise—it's technically impossible for us to access

## What makes it special

**Three Processing Modes**: Choose the workflow that fits your needs—single file for quick tasks, batch processing for bulk operations, or export presets for professional platform-specific packages.

**Dual Output Formats**: Generate both ICO files for traditional icon needs and SVG files for modern scalable graphics.

**Smart format handling**: Each image type gets optimized processing. SVG files are rasterized at each icon size for perfect quality, while photos get intelligent scaling with transparency detection.

**Professional quality**: High-quality resampling algorithms ensure your icons look crisp at every size, with automatic white backgrounds added to formats that don't support transparency.
**Professional export presets**: Platform-specific packages with proper naming conventions, folder structures, and size sets optimized for iOS, Android, Web, and Desktop applications.

**User-friendly**: Real-time format detection, dimension display, and helpful tips guide you to the best results without technical knowledge.
**Batch processing**: Upload multiple files simultaneously with parallel processing, individual progress tracking, and organized ZIP downloads.

**Modern & fast**: Built with the latest web technologies for smooth performance on all modern browsers.
**Real-time feedback**: Progress tracking, format detection, dimension display, and helpful tips guide you to the best results without technical knowledge.

**Modern & fast**: Built with the latest web technologies including Web Workers for smooth performance on all modern browsers.

## Technical transparency

This tool uses standard web technologies available in all modern browsers:
- **File API** for reading your selected images
- **Canvas API** for image processing and resizing
- **Blob API** for creating downloadable ICO files
- **File API** for reading your selected images and handling batch uploads
- **Canvas API** for image processing, resizing, and format conversion
- **Web Workers** for background processing and parallel batch operations
- **Blob API** for creating downloadable ICO and SVG files
- **ZIP.js** for client-side ZIP package generation
- **No external services** or third-party image processing APIs

The source code follows defensive programming practices with timeout protection to handle even corrupted or unusual image files gracefully.
The source code follows defensive programming practices with timeout protection to handle even corrupted or unusual image files gracefully. All processing modes maintain the same privacy-first architecture.

## Who is this for?

- **Web developers** creating favicons for websites
- **App developers** needing Windows application icons
- **Designers** converting artwork to ICO format for clients
- **Anyone** who values privacy and wants a reliable, free icon converter
- **Web developers** creating favicons and web app icons
- **Mobile app developers** needing platform-specific icon packages for iOS and Android
- **Desktop application developers** requiring Windows and cross-platform icons
- **Design teams** working on multi-platform applications with consistent icon sets
- **Freelancers and agencies** delivering professional icon packages to clients
- **Anyone** who values privacy and wants a reliable, free image converter with professional features

## Limitations (we're honest about them)

- Maximum file sizes: 50MB for photos, 100MB for SVG files
- Requires a modern browser (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
- For animated GIFs, only the first frame is used for the icon
- For animated GIFs, only the first frame is used for conversion
- Very small source images (under 64×64) may not produce optimal results
- Batch processing is limited by browser memory (typically 50-100 files depending on image sizes)
- Export presets generate platform-specific sizes but may require manual customization for unique requirements

## Our commitment

This tool will always remain free, privacy-respecting, and client-side only. We believe in transparent web tools that put user privacy first without compromising functionality.
This tool will always remain free, privacy-respecting, and client-side only. We believe in transparent web tools that put user privacy first without compromising functionality. As we continue to add new features and processing modes, we maintain our commitment to:

- **Complete privacy**: Your images never leave your browser
- **No data collection**: We don't track or store any user data
- **Free forever**: All features remain completely free
- **Open development**: Transparent about capabilities and limitations
- **Accessibility**: Ensuring the tool works for everyone
- **Performance**: Continuous optimization for the best user experience
Loading
Loading