# Agent Guide

## Project purpose

Maintain a Windows desktop photo-book editor that imports a photo folder, arranges one photo per page, edits photo crops, and exports an interior PDF for Blurb.

## Project map

- `main.py` launches the app.
- `blurb_editor.py` implements the PySide6 UI, page list and canvas, and the background import/export workers.
- `blurb_book.py` defines `PhotoPage`, `BookProject`, and `PrintProfile`; it also handles photo sorting, crop rendering, and PDF export.
- `requirements.txt` pins runtime dependencies.
- `README.md` is the user-facing setup and feature guide.

## Product behavior and constraints

- Folder import is top-level only. Supported formats are JPEG, PNG, TIFF, WebP, and BMP. HEIC and camera RAW formats are reported as unsupported.
- Photos sort by recognized filename timestamp first, then EXIF capture time, then filesystem creation time.
- New photo pages start with centered cover placement (`zoom=1`, `pan_x=0`, `pan_y=0`). Keep preview and export rendering aligned through `render_photo` and the shared crop geometry helpers.
- Photo sources are read-only. Projects store absolute paths, page order, crop transforms, tags, and print settings.
- `PhotoPage.tagged` is optional in older project files; missing values must continue to load as untagged.
- The page list is canonical in `BookProject.pages`. In **View Tagged**, list rows are only a filtered subset. Never treat a visible row number as the project page index; use the page object and the `_page_at_row` / `_project_index_for_page` helpers. Preserve full-book page numbering while filtering.
- **View Tagged** includes tagged photo pages and is disabled when there are no tagged photos. Page insertion and drag reordering are available in **View All** only.
- Folder import scanning and thumbnail preparation run in `FolderImportWorker`. Keep image decoding and preview work off the UI thread. Create or modify `QPixmap` objects only on the GUI thread; worker results should use thread-safe image data such as `QImage`. Keep the progress dialog and worker lifetime/error handling in sync.
- The default trim area is 9.5 × 8 inches per individual page. Final PDF dimensions and trim insets are set separately for the chosen Blurb configuration. Export contains interior pages only, renders at 300 PPI, and verifies PDF page dimensions and page count.
- Do not assume trim dimensions equal final PDF dimensions. Blurb requirements vary by format and paper; consult the current official specifications when changing export guidance.

## Development

Launch from PowerShell with the project environment:

```powershell
.\.venv\Scripts\python.exe main.py
```

Install pinned dependencies with:

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Keep dependency pins current with intentional changes to `requirements.txt`. The PDF path uses Pillow for image processing, ReportLab for assembly, and PyMuPDF for output checks.

There is no documented automated test suite. Do not add or run tests unless explicitly requested; when verification is requested, report exactly what was run.