feat: add page-by-page preview in the GUI after building (Closes #18) (#21)

.plans/issue-18-page-preview.md

@@ -0,0 +1,44 @@
+# Issue #18: Add page-by-page preview in the GUI after building
+
+## Summary
+
+Add a PDF preview panel to the GUI that appears after a successful build. It renders PDF pages as images using Apache PDFBox and displays them with previous/next navigation and a page counter. The preview loads pages lazily for performance and updates automatically on new builds.
+
+## AC Verification Checklist
+
+1. After a successful build, a preview panel appears showing generated pages
+2. Users can navigate between pages (previous/next buttons)
+3. Current page number and total count displayed (e.g., "Seite 3 / 42")
+4. Preview renders actual PDF pages as images (PDF-to-image via PDFBox)
+5. Preview panel can be closed/hidden to return to normal view
+6. Preview updates automatically when a new build completes
+7. GUI remains responsive while preview is loading (async rendering)
+
+## Implementation Steps
+
+### Step 1: Add PDFBox dependency to gui module
+
+Add `org.apache.pdfbox:pdfbox:3.0.4` to gui/build.gradle.kts.
+
+### Step 2: Create PdfPreviewState class
+
+A state holder for the preview: current page index, total pages, rendered page images (cached), loading state. Pages are rendered lazily — only the current page is rendered at a time.
+
+### Step 3: Create PdfPreviewPanel composable
+
+A Compose panel with:
+- An Image composable showing the current page
+- Navigation row: "< Prev" button | "Seite X / Y" label | "Next >" button
+- A close/hide button
+- Loading indicator while page is rendering
+
+### Step 4: Integrate preview into App composable
+
+After a successful build:
+- Show a "Vorschau" button in the action buttons row
+- When clicked, show the preview panel (replacing or overlaying the song list area)
+- When a new build succeeds, update the preview automatically
+
+### Step 5: Lazy page rendering
+
+Render pages on demand using coroutines on Dispatchers.IO to keep the UI responsive.