Release version 1.5.1

.gitignore

@@ -1,38 +1,86 @@
-# Virtual environments
+# ----------------------------
+# Python / virtualenvs
+# ----------------------------
 .venv/
 venv/
+env/
 
-# Python cache
+# Keep verify_venv locally but never track it (works anywhere in the repo)
+verify_venv/
+
+# Python caches
 __pycache__/
-*.pyc
+*.py[cod]
+*$py.class
 
-# Build outputs
-dist/
+# Type checker caches
+.mypy_cache/
+
+# ----------------------------
+# Build / packaging outputs
+# ----------------------------
 build/
+dist/
 *.spec
+*.egg-info/
 faststack.egg-info/
 
+# ----------------------------
 # Logs
+# ----------------------------
 *.log
 
+# ----------------------------
 # OS cruft
+# ----------------------------
 .DS_Store
 Thumbs.db
 
+# ----------------------------
 # IDE
+# ----------------------------
 .vscode/
 .idea/
+*.swp
+*.swo
 
-# Documentation/Generated
+# ----------------------------
+# Project docs we don't track
+# ----------------------------
 prompt.md
 WARP.md
 AGENTS.md
 ARCHITECTURE.md
 docs/COLOR_PROFILE_FIX.md
 
-# Caches
-faststack/.mypy_cache/
-.mypy_cache/
-
-# Runtime/Data
+# ----------------------------
+# Runtime / generated data
+# ----------------------------
 var/
+
+# ----------------------------
+# Local test/debug outputs 
+# ----------------------------
+debug_*.txt
+debug_test.py
+output*.txt
+test_fail*.log
+test_out*.txt
+test_output*.txt
+test_report*.log
+test_results.txt
+smoke_test_output.txt
+verify_result.txt
+
+# Same junk when produced inside the package dir
+faststack/debug_*.txt
+faststack/debug_test.py
+faststack/output*.txt
+faststack/test_fail*.log
+faststack/test_out*.txt
+faststack/test_output*.txt
+faststack/test_report*.log
+faststack/test_results.txt
+faststack/smoke_test_output.txt
+faststack/verify_result.txt
+

ChangeLog.md

@@ -2,6 +2,31 @@
 
 Todo:   Make it work on Linux / Mac.   Create Windows .exe.   Write better documentation / help.   Add splash screen / icon.   
 
+## [1.5.1] - 2026-01-23
+
+### Added
+- Added experimental RAW processing via Rawtherapee
+- Added explicit **JPEG vs RAW editing modes** with UI + signals to keep QML and backend in sync (`editSourceModeChanged`, `saveBehaviorMessage`). RAW mode can develop to a 16-bit working TIFF and optionally write a `*-developed.jpg` output while leaving the original JPEG untouched.
+- Added **RAW development workflow** via RawTherapee **CLI** (`rawtherapee-cli`) with configurable extra args, better error reporting, output validation, and timeout handling.
+- Added editor quality upgrades: **16-bit aware editing pipeline** using float32 working buffers, sRGB↔linear conversions for “true headroom” edits, OpenCV Gaussian blur helpers, and new **Texture** control.
+- Added editor metadata display in the window title (filename + detected bit depth).
+- Added robust undo/restore helper (`_restore_backup_safe`) to better handle locked files and tricky restore scenarios.
+- Added support for indexing and displaying `*-developed.jpg` images and **orphaned RAWs** in the browser list; updated pairing test expectations accordingly.
+
+### Changed
+- Reworked README installation instructions:
+  - macOS recommended flow with **Python 3.12** (Homebrew) + venv + `pip install .`
+  - Simplified run command (`faststack`) and clarified Windows/Linux steps.
+- Switched RawTherapee path detection defaults from GUI executable to **CLI executable** on Windows/macOS/Linux.
+- Improved Prefetcher decode behavior by using TurboJPEG **only for JPEGs**, with a Pillow fallback for non-JPEG formats or decode failures.
+- Centralized navigation state changes (`_set_current_index`) and ensured edit mode resets appropriately on navigation (defaults back to JPEG unless RAW-only).
+
+### Fixed
+- Fixed editor memory usage by clearing large editor buffers when the editor closes and resetting cached preview state.
+- Fixed a QML slider double-click reset edge case where the slider could remain in a pressed/dragging state (force release via a short disable/reenable tick).
+- Fixed histogram scheduling/thread-safety issues by tightening locking around pending/inflight state and improving failure handling when preview data is missing or executor submission fails.
+
+
 
 ## [1.5.0] - 2025-12-01
 

MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include faststack/qml *
+include LICENSE
+include README.md

README.md

@@ -27,17 +27,42 @@ This tool is optimized for speed, using `libjpeg-turbo` for decoding, aggressive
 - **Accurate Colors:** Uses monitor ICC profile to display colors correctly.
 - **RGB Histogram:** Pressing H brings up a RGB histogram which is designed to show even a little bit of highlight clipping and updates as you zoom in.
 
-## Installation & Usage
+## Installation
 
-1.  **Install Dependencies:**
+### macOS (Recommended)
+FastStack performs best on Python 3.12 due to PySide6 compatibility.
+
+1.  **Install Python 3.12 (via Homebrew):**
+    ```bash
+    brew install python@3.12
+    ```
+
+2.  **Create and Activate a Virtual Environment:**
     ```bash
-    pip install -r requirements.txt
+    python3.12 -m venv venv
+    source venv/bin/activate
     ```
 
-2.  **Run the App:**
+3.  **Install FastStack:**
     ```bash
-    python -m faststack.app "C:\path\to\your\images"
+    # From source directory
+    python -m pip install -U pip
+    python -m pip install .
     ```
+    *Note: If you encounter issues with `opencv-python` or `PySide6` on newer Python versions (3.13+), please stick to Python 3.12.*
+
+4.  **Run:**
+    ```bash
+    faststack
+    ```
+
+### Windows / Linux
+```bash
+python -m venv venv
+# Activate venv (Windows: venv\Scripts\activate, Linux: source venv/bin/activate)
+pip install .
+faststack
+```
 
 ## Keyboard Shortcuts