v2.0.0: Modular architecture, CLI mode, presets, and full test suite

- Restructured from monolithic main.py into pixieswitch/ package
- Fixed critical thread safety bug (Qt widgets modified from worker threads)
- Fixed animated image resize (now applies to all frames, not just first)
- Fixed strip_metadata silently destroying animation frames
- Fixed preset filename injection (path traversal via user input)
- Added CLI mode: python -m pixieswitch convert --help
- Added settings persistence (QSettings, restored on startup)
- Added folder drag-and-drop (recursive image discovery)
- Added keyboard shortcuts (Ctrl+O, Delete, Ctrl+Enter, Escape, etc.)
- Added conversion presets (Web Optimized, Archive, Social Media, custom)
- Added image preview with dimensions and file size
- Added conversion stats (success/fail count, elapsed time, bytes written)
- Added cancel button with Escape shortcut
- Added "Open Output Folder" button
- Added overwrite and close-during-conversion warnings
- Added dark/light theme auto-detection (Qt 6.5+)
- Added APNG output support for animated sources
- Added progress bar text overlay (12/50) and title bar progress
- Added file count display in status bar
- Added drag reordering in file list
- Added proper .ico for Windows builds
- Added CI pipeline (GitHub Actions, ruff, mypy, pytest)
- Added pyproject.toml for unified tool configuration
- 32 tests covering converter, formats, presets, and settings
- ruff and mypy clean

Author: HackingPain

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest pytest-cov ruff mypy
+      - name: Lint
+        run: ruff check pixieswitch/ tests/
+      - name: Type check
+        run: mypy pixieswitch/ --ignore-missing-imports
+      - name: Test
+        run: pytest --cov=pixieswitch --cov-report=term-missing -v

.gitignore

@@ -2,6 +2,11 @@ __pycache__/
 *.pyc
 dist/
 build/
-*.spec
 .venv/
 venv/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.claude/
+tests/fixtures/

CLAUDE.md

@@ -0,0 +1,54 @@
+# Project Guide - PixieSwitch
+
+## Project overview
+PixieSwitch is a batch image converter with a PySide6 GUI and CLI mode. It supports JPG, PNG, GIF, WebP, TIFF, BMP, JPEG2000, HEIF/HEIC/AVIF formats with animation preservation, metadata control, and resizing.
+
+## Build & run
+```bash
+pip install -r requirements.txt          # runtime deps
+pip install pytest pytest-cov ruff mypy  # dev deps
+python -m pixieswitch                    # GUI
+python -m pixieswitch convert --help     # CLI
+python main.py                           # legacy shim
+```
+
+## Test, lint, type-check
+```bash
+pytest --cov=pixieswitch -v
+ruff check pixieswitch/ tests/
+mypy pixieswitch/ --ignore-missing-imports
+```
+
+## Architecture
+```
+pixieswitch/
+    __init__.py        - APP_NAME, __version__
+    __main__.py        - entry point (CLI args -> cli.py, else -> GUI)
+    converter.py       - core conversion (ConvertTask -> ConvertResult, no GUI deps)
+    formats.py         - format constants, human_size(), safe_filename()
+    settings.py        - QSettings wrapper with typed properties
+    cli.py             - argparse CLI mode
+    gui/
+        main_window.py - ConverterWindow (main widget)
+        drop_list.py   - DropListWidget (file list with drag/drop/dedup)
+        style.py       - dark/light theme detection
+        presets.py     - preset management (JSON in user config dir)
+```
+
+## Key design decisions
+- **Thread safety**: Worker threads emit a Qt signal; all widget updates happen in the GUI thread slot. Callbacks use `weakref` to the window to prevent use-after-free on close.
+- **Converter has zero GUI deps**: `converter.py` and `formats.py` are testable without Qt installed. GUI tests are skipped via `pytest.importorskip("PySide6")`.
+- **Animation handling**: Frames are extracted and processed (resize, strip metadata) individually before saving. This avoids the historical bugs where resize/strip only affected the first frame.
+- **Presets stored as JSON**: One file per preset in `QStandardPaths.AppConfigLocation/presets/`. Names are sanitized via `safe_filename()` with path-traversal checks.
+
+## Conventions
+- Line length: 100 (configured in pyproject.toml)
+- Linter: ruff (E, F, W, I, UP, B, SIM rules)
+- Type checker: mypy (ignore-missing-imports for optional deps like PySide6, pillow-heif, imageio)
+- Tests: pytest, fixtures auto-generate small test images in `tests/fixtures/` (gitignored)
+- No GUI tests (low ROI); test the converter and format logic directly
+
+## Watch out for
+- Pillow type stubs are incomplete. `Image.open()` returns `ImageFile` but operations return `Image.Image`. Use `type: ignore[assignment]` on the open call.
+- `QSettings` serializes bools differently per platform. The `AppSettings` properties handle this with `in (True, "true")` checks.
+- The `_running` flag + button disable + shortcut guard are all needed to prevent double-convert. Shortcuts bypass `QPushButton.setEnabled(False)`.

PixieSwitch.spec

@@ -0,0 +1,45 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+
+a = Analysis(
+    ['main.py'],
+    pathex=[],
+    binaries=[],
+    datas=[],
+    hiddenimports=['pixieswitch', 'pixieswitch.gui', 'pixieswitch.gui.main_window'],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='PixieSwitch',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=False,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+    icon=['pixieswitch.ico'],
+)
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='PixieSwitch',
+)

README.md

@@ -1,26 +1,41 @@
-# PixieSwitch — Batch Image Converter (GUI)
+# PixieSwitch - Batch Image Converter (GUI + CLI)
 
-**PixieSwitch** is a fun, simple GUI to convert images between popular formats. Drop in files, pick an output format, tweak a few options, and go. It handles batch conversion, optional metadata preservation/stripping, basic resizing, and animations (GIF/WebP).
+**PixieSwitch** is a fun, simple GUI to convert images between popular formats. Drop in files, pick an output format, tweak a few options, and go. It handles batch conversion, optional metadata preservation/stripping, basic resizing, and animations (GIF/WebP/APNG).
 
 ## Features
 
-- Drag & Drop multiple images
+- Drag & Drop files **and folders** (recursively adds images)
 - Output formats: JPG/JPEG, PNG, GIF, WebP, TIFF, BMP, JPEG2000 (JP2/J2K), and optional HEIF/HEIC/AVIF (with pillow-heif)
-- Animation-aware: Keep animation for GIF/WebP (when source is animated)
+- Animation-aware: Keep animation for GIF/WebP/APNG (when source is animated)
 - Metadata: preserve EXIF (JPEG) or strip all metadata
 - Resize: constrain longest edge (px)
 - Quality: set lossy compression quality for JPEG/WebP/AVIF/etc.
-- PNG compression level: 0 (fast/big) … 9 (slow/small)
+- PNG compression level: 0 (fast/big) ... 9 (slow/small)
 - Suffix & Output folder controls
 - Multithreaded conversion
+- **Settings persistence** - your options are remembered between sessions
+- **Keyboard shortcuts** - Ctrl+O (add), Delete (remove), Ctrl+Enter (convert), etc.
+- **Presets** - built-in (Web Optimized, Archive, Social Media) and custom
+- **Image preview** - select a file to see thumbnail, dimensions, and size
+- **Conversion stats** - success/fail count, elapsed time, bytes written
+- **Dark/light theme** - auto-detected from system settings
+- **CLI mode** - `python -m pixieswitch convert --help`
 
 ## Install
 
-Python 3.9+ recommended (tested on 3.13). Windows, macOS, Linux.
+Python 3.10+ recommended (tested on 3.13). Windows, macOS, Linux.
 
 1. Create & activate a virtual env (recommended)
 2. `pip install -r requirements.txt`
-3. `python main.py`
+3. `python -m pixieswitch` (GUI) or `python main.py`
+
+### CLI usage
+
+```
+python -m pixieswitch convert --input *.png --format webp --quality 85 --output ./out/
+python -m pixieswitch convert --input ./photos/ --format jpg --resize 1920
+python -m pixieswitch convert --help
+```
 
 ### Optional extras
 
@@ -29,39 +44,58 @@ Python 3.9+ recommended (tested on 3.13). Windows, macOS, Linux.
 
 ## Build a standalone app
 
-### Windows (EXE)
-
 ```
 pip install pyinstaller
-pyinstaller --noconfirm --windowed --name PixieSwitch --icon NONE main.py
+pyinstaller PixieSwitch.spec
 # Output in dist/PixieSwitch/
 ```
 
-### macOS (App bundle/DMG)
+## Development
 
 ```
-pip install pyinstaller
-pyinstaller --noconfirm --windowed --name PixieSwitch --icon NONE main.py
-# Optional: codesign/notarize per Apple docs
+pip install -r requirements.txt
+pip install pytest pytest-cov ruff mypy
+pytest --cov=pixieswitch -v
+ruff check pixieswitch/ tests/
+mypy pixieswitch/ --ignore-missing-imports
 ```
 
-### Linux (AppImage)
+## Keyboard shortcuts
 
-Use pyinstaller for a folder build, then package with tools like appimagetool if desired.
+| Action | Shortcut |
+|---|---|
+| Add Files | Ctrl+O |
+| Remove Selected | Delete |
+| Clear List | Ctrl+Shift+Delete |
+| Convert | Ctrl+Enter |
+| Cancel | Escape |
+| Browse Output | Ctrl+Shift+O |
 
 ## Usage tips
 
-- Transparency → JPEG: JPEG has no alpha; we composite on white by default.
+- Transparency -> JPEG: JPEG has no alpha; we composite on white by default.
 - EXIF vs Strip: "Strip ALL metadata" overrides "Preserve EXIF."
-- Animated output: Only GIF & WebP are guaranteed here. Other targets will use the first frame.
+- Animated output: GIF, WebP, and APNG are supported. Other targets will use the first frame.
 - JPEG2000: Quality handling varies by Pillow build. If unsupported, you'll see an error per file.
 
-## Roadmap
+## Project structure
 
-- APNG output (where Pillow supports it)
-- Color profile controls, ICC copy
-- Presets & CLI runner
-- Bulk folder watch mode
+```
+pixieswitch/
+    __init__.py          # APP_NAME, __version__
+    __main__.py          # Entry point
+    converter.py         # Core conversion logic (no GUI deps)
+    formats.py           # Format constants
+    settings.py          # QSettings wrapper
+    cli.py               # CLI mode
+    gui/
+        main_window.py   # Main window
+        drop_list.py     # Drag-and-drop list widget
+        style.py         # Theme detection and stylesheets
+        presets.py       # Preset management
+main.py                  # Thin shim -> pixieswitch.__main__
+tests/                   # pytest test suite
+```
 
 ## License