blurb/AGENT.md

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:

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

Install pinned dependencies with:

.\.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.