feat: QoL improvements

Author: radioactiveorange

.github/workflows/release.yml

@@ -191,14 +191,14 @@ jobs:
           Get-ChildItem dist -Force
           echo ""
           if (Test-Path "dist\glimpse.exe") {
-            $newName = "glimpse-${{ needs.semantic-release.outputs.new-release-version }}-windows-${{ steps.arch-windows.outputs.arch }}.exe"
+            $newName = "glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-windows-${{ steps.arch-windows.outputs.arch }}.exe"
             Copy-Item "dist\glimpse.exe" $newName
             echo "Successfully created $newName"
             echo "File created:"
             Get-ChildItem $newName -Force
           } elseif (Test-Path "dist\glimpse") {
             echo "Found 'glimpse' without .exe extension - renaming it"
-            $newName = "glimpse-${{ needs.semantic-release.outputs.new-release-version }}-windows-${{ steps.arch-windows.outputs.arch }}.exe"
+            $newName = "glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-windows-${{ steps.arch-windows.outputs.arch }}.exe"
             Copy-Item "dist\glimpse" $newName  
             echo "Successfully created $newName from 'glimpse'"
             echo "File created:"
@@ -233,11 +233,11 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: |
           # Create renamed binary
-          cp dist/glimpse glimpse-${{ needs.semantic-release.outputs.new-release-version }}-linux-${{ steps.arch-linux.outputs.arch }}
+          cp dist/glimpse glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-linux-${{ steps.arch-linux.outputs.arch }}
           
           # Create tar.gz archive
           cd dist
-          tar -czf ../glimpse-${{ needs.semantic-release.outputs.new-release-version }}-linux-${{ steps.arch-linux.outputs.arch }}.tar.gz glimpse
+          tar -czf ../glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-linux-${{ steps.arch-linux.outputs.arch }}.tar.gz glimpse
           cd ..
           
       - name: Create .deb package (Linux)
@@ -333,7 +333,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: |
           # Create renamed binary
-          cp dist/glimpse glimpse-${{ needs.semantic-release.outputs.new-release-version }}-macos-${{ steps.arch-macos.outputs.arch }}
+          cp dist/glimpse glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-macos-${{ steps.arch-macos.outputs.arch }}
           
           # Create a temporary directory for the DMG contents
           mkdir -p dmg-contents
@@ -344,13 +344,13 @@ jobs:
                          -srcfolder dmg-contents \
                          -ov \
                          -format UDZO \
-                         glimpse-${{ needs.semantic-release.outputs.new-release-version }}-macos-${{ steps.arch-macos.outputs.arch }}.dmg
+                         glimpse-viewer-${{ needs.semantic-release.outputs.new-release-version }}-macos-${{ steps.arch-macos.outputs.arch }}.dmg
 
       - name: Verify artifacts before upload (Windows)
         if: matrix.os == 'windows-latest'
         run: |
           echo "=== FILES AVAILABLE FOR UPLOAD ==="
-          Get-ChildItem . -Filter "glimpse-*" -Force | Select-Object Name, Length, LastWriteTime
+          Get-ChildItem . -Filter "glimpse-viewer-*" -Force | Select-Object Name, Length, LastWriteTime
           echo ""
           echo "=== ALL FILES IN CURRENT DIRECTORY ==="
           Get-ChildItem . -Force
@@ -360,15 +360,15 @@ jobs:
         if: matrix.os != 'windows-latest'
         run: |
           echo "=== FILES AVAILABLE FOR UPLOAD ==="
-          ls -la glimpse-* 2>/dev/null || echo "No glimpse-* files found with ls"
+          ls -la glimpse-viewer-* 2>/dev/null || echo "No glimpse-viewer-* files found with ls"
           echo "=== ALL FILES IN CURRENT DIRECTORY ==="
           ls -la
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: glimpse-${{ matrix.name }}
-          path: glimpse-*
+          name: glimpse-viewer-${{ matrix.name }}
+          path: glimpse-viewer-*
           if-no-files-found: error
 
   # Create the actual release with binaries
@@ -409,7 +409,7 @@ jobs:
       - name: Prepare release assets
         run: |
           mkdir -p release-assets
-          find ./artifacts -name "*.exe" -o -name "*.tar.gz" -o -name "*.deb" -o -name "*.dmg" | xargs -I {} cp {} release-assets/
+          find ./artifacts -name "glimpse-viewer-*.exe" -o -name "glimpse-viewer-*.tar.gz" -o -name "glimpse-viewer-*.deb" -o -name "glimpse-viewer-*.dmg" | xargs -I {} cp {} release-assets/
           ls -la release-assets/
 
       - name: Create version file for semantic-release

README.md

@@ -8,6 +8,24 @@
 
 A cross-platform desktop application for viewing random images from folders or collections. Useful for reference studies, browsing large image libraries, and rediscovering artwork.
 
+[![Latest Release](https://img.shields.io/github/v/release/radioactiveorange/glimpse)](https://github.com/radioactiveorange/glimpse/releases/latest)
+[![Downloads](https://img.shields.io/github/downloads/radioactiveorange/glimpse/total)](https://github.com/radioactiveorange/glimpse/releases)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+## 📋 Table of Contents
+
+- [✨ Features](#-features)
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [🎯 Use Cases](#-use-cases)
+- [⌨️ Keyboard Shortcuts](#️-keyboard-shortcuts)
+- [🖱️ Mouse Controls](#️-mouse-controls)
+- [🛠️ Advanced Features](#️-advanced-features)
+- [🏗️ Technical Details](#️-technical-details)
+- [🎨 Screenshots](#-screenshots)
+- [🤝 Contributing](#-contributing)
+- [📝 License](#-license)
+
 ## ✨ Features
 
 ### 🎲 **Collections & Random Viewing**
@@ -31,64 +49,60 @@ A cross-platform desktop application for viewing random images from folders or c
 - Minimal UI design
 
 ### 💾 **Collection Management**
-- Multi-folder collections
+- Multi-folder collections with professional startup dialog
 - Persistent storage between sessions
+- Collection editing, deletion, and organization
+- Quick folder location access
 - Cross-platform support (Windows, macOS, Linux)
 
 ---
 
-## 🚀 Quick Start
+## 📦 Installation
 
-### Installation
+### 🎯 Recommended: Download Pre-built Binaries
 
-**Prerequisites:**
-- Python 3.13+
-- [uv](https://docs.astral.sh/uv/) (fast Python package manager) - Install with: `pip install uv`
+**[📥 Download Latest Release](https://github.com/radioactiveorange/glimpse/releases/latest)**
 
-**Option 1: Run from Source**
-```bash
-# Clone the repository
-git clone https://github.com/radioactiveorange/glimpse.git
-cd glimpse
+| Platform | File | Installation |
+|----------|------|--------------|
+| **Windows** | `glimpse-viewer-*.exe` | Download and run directly |
+| **macOS** | `glimpse-viewer-*.dmg` | Download, mount, and drag to Applications |
+| **Linux** | `glimpse-viewer-*.deb` | `sudo dpkg -i glimpse-viewer-*.deb` |
+| **Linux** | `glimpse-viewer-*.tar.gz` | Extract and run `./glimpse` |
 
-# Create and activate virtual environment with uv (recommended)
-uv venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+### 🛠️ Development Installation
 
-# Install dependencies
-uv pip install -e .
-
-# Run the application
-uv run main.py
-```
+**Prerequisites:**
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) (fast Python package manager) - Install with: `pip install uv`
 
-**Alternative with uv (no manual venv activation needed):**
+**Run from Source:**
 ```bash
 # Clone the repository
 git clone https://github.com/radioactiveorange/glimpse.git
 cd glimpse
 
-# Install dependencies (uv handles venv automatically)
-uv pip install -e .
+# Install dependencies and run (uv handles venv automatically)
+uv pip install pyside6
 
 # Run the application
 uv run main.py
 ```
 
-**Option 2: Build Executable**
+**Build Your Own Executable:**
 ```bash
 # Install build dependencies
-uv pip install -e ".[build]"
+uv pip install pyinstaller pyside6
 
-# Build standalone executable
-pyinstaller --noconfirm --onefile --windowed --icon=app_icon.ico --name=glimpse main.py
+# Build standalone executable using the spec file
+pyinstaller glimpse.spec
 
 # Find your executable in the dist/ folder
 ```
 
 ---
 
-### First Launch
+## 🚀 Quick Start
 
 1. Create a collection by clicking "New Collection" and selecting folders
 2. Configure timer settings (or disable for manual browsing)
@@ -112,9 +126,15 @@ Alternatively, use "Quick Shuffle Folder" to browse any folder immediately.
 | Shortcut | Action |
 |----------|--------|
 | `←` `→` | Navigate previous/next image |
+| `Space` | Play/pause timer |
 | `Ctrl` `+` | Zoom in |
 | `Ctrl` `-` | Zoom out |
-| `Ctrl` `0` | Reset zoom to 100% |
+| `Ctrl` `0` | Reset zoom and center image |
+| `F` | Flip image horizontally |
+| `G` | Toggle grayscale mode |
+| `B` | Cycle background modes (black/gray/adaptive) |
+| `H` | Toggle history panel |
+| `Esc` | Switch collection/folder |
 | `Right-click` | Open context menu |
 
 ## 🖱️ Mouse Controls
@@ -128,27 +148,50 @@ Alternatively, use "Quick Shuffle Folder" to browse any folder immediately.
 ## 🛠️ Advanced Features
 
 ### Collection Management
-- Edit collections (rename, manage folders)
-- Delete collections
+- Professional startup dialog with ShuffleBird-inspired design
+- Edit collections (rename, manage folders) 
+- Delete collections with confirmation
 - Auto-sorted by recent usage
+- Quick folder location access button
+- Async loading for large collections (72K+ images tested)
 
 ### Image Processing  
 - Supported formats: JPG, JPEG, PNG, BMP, GIF
 - Recursive search in subfolders
-- Grayscale mode and flip controls
+- Image transformations: flip horizontal/vertical, grayscale
+- Smart image caching for performance
 
 ### Customization
-- Background modes: Black, Gray, Adaptive Color
-- Timer intervals: 30s, 1min, 2min, 5min, or custom
-- Configurable history panel
+- Background modes: Black, Gray, Smart Adaptive Color
+- Timer intervals: 30s, 1min, 2min, 5min, 10min, 30min, or custom
+- Configurable history panel with thumbnails
+- Professional button styling with SVG icons
 
 ## 🏗️ Technical Details
 
-- Framework: PySide6 (Qt for Python)
-- Modular architecture
-- JSON-based collection storage
-- Cross-platform settings and data directories
-- Image caching for smooth performance
+- **Framework**: PySide6 (Qt for Python) 
+- **Architecture**: Clean modular structure with UI/core separation
+- **Collection Storage**: JSON files in platform-appropriate directories:
+  - Linux: `~/.local/share/glimpse/collections/`
+  - Windows: `%LOCALAPPDATA%/glimpse/collections/`
+  - macOS: `~/Library/Application Support/glimpse/collections/`
+- **Image Processing**: Optimized pixmap caching and async loading
+- **UI Components**: Custom widgets with professional dark theme
+- **Icons**: SVG-based with coded fallbacks for consistency
+- **Settings**: QSettings with cross-platform persistence
+- **Threading**: Worker threads for large collection operations
+- **Build System**: PyInstaller with optimized spec file for all platforms
+- **Package Management**: Debian (.deb), DMG (macOS), and portable binaries
+
+### System Requirements
+
+| Platform | Minimum | Recommended |
+|----------|---------|-------------|
+| **Windows** | Windows 10 | Windows 11 |
+| **macOS** | macOS 10.15 | macOS 12+ |
+| **Linux** | Ubuntu 20.04 / equivalent | Ubuntu 22.04+ |
+| **RAM** | 2GB | 4GB+ |
+| **Storage** | 50MB | 100MB+ |
 
 ## 🎨 Screenshots
 
@@ -168,7 +211,30 @@ Alternatively, use "Quick Shuffle Folder" to browse any folder immediately.
 
 ## 🤝 Contributing
 
-This project was built collaboratively with Claude Code. Contributions, bug reports, and feature requests are welcome!
+This project was built collaboratively with Claude Code. We welcome:
+
+- 🐛 **Bug reports** - [Open an issue](https://github.com/radioactiveorange/glimpse/issues)
+- 💡 **Feature requests** - [Suggest improvements](https://github.com/radioactiveorange/glimpse/issues)
+- 🔧 **Pull requests** - Fork and contribute code
+- 📖 **Documentation** - Help improve docs and examples
+- 🧪 **Testing** - Try on different platforms and report findings
+
+### Development Setup
+
+1. Fork the repository
+2. Follow the [Development Installation](#🛠️-development-installation) steps
+3. Make your changes
+4. Test on your platform
+5. Submit a pull request
+
+### Reporting Issues
+
+When reporting bugs, please include:
+- Operating system and version
+- Python version 
+- Steps to reproduce
+- Expected vs actual behavior
+- Screenshots if relevant
 
 ---
 

icons/folder.svg

@@ -430,6 +430,25 @@ def _create_coded_icon(icon_type, size=24, color="#ffffff"):
         painter.drawLine(margin + 2, size - margin - 2, margin + 2 + head_size//2, size - margin - 2 - head_size)
         painter.drawLine(margin + 2, size - margin - 2, margin + size//3, size - margin - 2)
         painter.drawLine(margin + size//3, size - margin - 2, margin + size//3 - head_size, size - margin - 2 - head_size//2)
+        
+    elif icon_type == "folder":
+        # Folder icon
+        painter.setBrush(Qt.NoBrush)
+        painter.setPen(pen)
+        
+        # Folder body
+        folder_width = size - 2 * margin
+        folder_height = (size - 2 * margin) * 2 // 3
+        folder_y = margin + size // 6
+        
+        # Draw folder outline
+        painter.drawRoundedRect(margin, folder_y, folder_width, folder_height, 2, 2)
+        
+        # Folder tab (top part)
+        tab_width = folder_width // 3
+        tab_height = size // 8
+        tab_y = folder_y - tab_height // 2
+        painter.drawRoundedRect(margin, tab_y, tab_width, tab_height, 1, 1)
 
     painter.end()
     return QIcon(pixmap)