feat(pdf-EPUB): add PDF to EPUB/AZW3 conversion functionality via Calibre

[balazs-szucs]

Description of Changes

This PR introduces a new conversion tool allowing users to convert PDF documents into EPUB format. This is particularly useful for reading documents on e-readers (like Kindles or Kobos) where standard PDFs often suffer from fixed formatting and unreadable text sizes.

The implementation leverages the existing Calibre integration (ebook-convert) to produce reflowable e-books with specific optimizations for layout and chapter structure.

Backend Implementation

• Added ConvertPDFToEpubController to handle the conversion workflow.
• Created ConvertPdfToEpubRequest to support new conversion parameters (Device profile and Chapter detection).
• Integrated standard Stirling-PDF temporary file management and process execution patterns.

Frontend & UI

• Added a new view pdf-to-epub.html containing the upload form and configuration options.
• Updated navElements.html and messages.properties to expose the tool in the navigation menu under the "Convert" group.
• Minor cleanup of HTML formatting in the existing ebook-to-pdf template for consistency.

Configuration & Testing

• Registered the pdf-to-epub endpoint in EndpointConfiguration, placing it under the Calibre dependency group.
• Added comprehensive unit tests covering command generation, parameter handling, and temporary file cleanup.

The conversion process utilizes specific calibre, ebook-convert flags to ensure high-quality output:

• Heuristic Processing (--enable-heuristics): Automatically detects and fixes common PDF scanning issues, such as broken lines, hyphens at line ends, and inconsistent paragraph spacing.
• CSS Filtering (--filter-css): Strips hardcoded styling (font families, fixed margins, colors) from the PDF. This ensures the resulting EPUB respects the user's e-reader settings (font size, dark mode, etc.).
• Smart Chapter Detection (--chapter): Optionally uses an XPath expression (//h:*[re:test(., '\\s*Chapter\\s+', 'i')]) to detect headers and insert proper page breaks in the EPUB structure.
• Device Optimization Profiles:
  • Tablet/Phone: Uses the default profile to maintain image resolution and color.
  • Kindle/E-Ink: Uses a specific profile to resize images and optimize contrast for grayscale screens.

---

Checklist

General

• I have read the Contribution Guidelines
• I have read the Stirling-PDF Developer Guide (if applicable)
• I have read the How to add new languages to Stirling-PDF (if applicable)
• I have performed a self-review of my own code
• My changes generate no new warnings

Documentation

• I have updated relevant docs on Stirling-PDF's doc repo (if functionality has heavily changed)
• I have read the section Add New Translation Tags (for new translation tags only)

Translations (if applicable)

• I ran scripts/counter_translation.py

UI Changes (if applicable)

• Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR)

Testing (if applicable)

• I have tested my changes locally. Refer to the Testing Guide for more details.

[stirlingbot]

🚀 Translation Verification Summary

🔄 Reference Branch: pr-branch-messages_en_GB.properties

📃 File Check: messages_en_GB.properties

1. Test Status: ✅ Passed
2. Test Status: ✅ Passed
3. Test Status: ✅ Passed

---

✅ Overall Check Status: Success

Thanks @balazs-szucs for your help in keeping the translations up to date.

[Copilot]

Pull Request Overview

This PR introduces a new PDF to EPUB/AZW3 conversion feature using Calibre, enabling users to convert PDF documents into reflowable e-book formats optimized for e-readers.

Key changes include:

• Backend conversion controller with configurable chapter detection and device-specific optimization profiles
• Request model supporting EPUB/AZW3 output formats and device targeting (tablet/e-ink)
• New UI template with conversion options and comprehensive test coverage

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ConvertPDFToEpubController.java	New controller implementing PDF to EPUB/AZW3 conversion using Calibre with heuristic processing and CSS filtering
ConvertPdfToEpubRequest.java	Request model defining conversion parameters including output format, device profile, and chapter detection
ConverterWebController.java	Added web endpoint for pdf-to-epub form view
EndpointConfiguration.java	Registered pdf-to-epub endpoint in Convert and Calibre groups
pdf-to-epub.html	New UI template with upload form and conversion options
ebook-to-pdf.html	Code formatting cleanup for consistency (removed extra whitespace from attributes)
navElements.html	Added navigation entries for pdf-to-epub tool
messages_en_GB.properties	Added localization strings for pdf-to-epub feature
ConvertPDFToEpubControllerTest.java	Comprehensive unit tests covering command generation, parameter handling, and cleanup
ConverterWebControllerTest.java	Added endpoint enable/disable tests for pdf-to-epub

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.