blurb/AGENT.md

Agent Guide

Project purpose

Maintain a Windows desktop photo-book editor that imports a photo folder, arranges one photo per interior page, edits photo crops, and exports Blurb interior and optional ImageWrap cover PDFs.

Project map

• main.py launches the app.
• blurb_editor.py implements the PySide6 UI, page and cover lists/canvases, and the background import/export workers.
• blurb_book.py defines PhotoPage, CoverLayout, 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.
• Rescanning a selected folder adds only paths not already in the project, preserves existing page edits and relative order, inserts new pages chronologically, and reports the number added.
• 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, print settings, cover-spine text styles and vertical positions, and front-cover text settings and positions.
• 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.
• Cover photos live in BookProject.cover, outside BookProject.pages. The Cover Photos list is informational; cover photos are not interior pages, page-count entries, or reorderable page rows. Removing a cover returns its PhotoPage to BookProject.pages by capture date.
• Front-cover title and subtitle text use one saved font family, separate sizes and movable normalized positions. Each uses the corresponding spine text color and a 7 px black outline radius; cover export rasterizes the lettering into the spread image.
• Spine title and subtitle vertical positions are saved in inches from the bottom of the face. The title moves within the full spine; the subtitle stays in the bottom subtitle area. Resetting spine text clears custom positions and restores the centered defaults.
• 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, project loading, and thumbnail preparation run in background workers. 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 progress dialogs and worker lifetime/error handling in sync.
• The default trim area is 9.5 × 8 inches per individual interior page. Final PDF dimensions and trim insets are set separately for the chosen Blurb configuration. Interior export renders at 300 PPI and verifies PDF page dimensions and page count. Configured covers export as a separate one-page full spread with editable face/spine dimensions and 0.125-inch starting values for the wrap/bleed margins; users must verify exact values for their selected Blurb configuration.
• 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.