v2.5.0

PDF Craft v2.5.0

PDF Craft 2.5.0 adds incremental content callbacks for PDF extraction, EPUB
translation, and PCEX translation and rendering. Applications can display content
while a task is running, with source locations for highlighting and PDF previews.
Operations still return complete, validated artifacts; a callback is not a partial
PCEX, EPUB, or PDF file.

Incremental PDF extraction

• ExtractionOptions.on_body and on_footnote deliver independent PCEX XML
  snapshots as content closes during cross-page analysis. Body events include
  text, standalone assets, and display formulas; footnote events contain complete
  reference definitions. Source fragment identities, pages, and bounding boxes
  are retained.
• OCR and content analysis can progress together. Closed paragraphs and footnotes
  can be delivered before OCR finishes; unresolved trailing content is flushed
  before successful return. Notifications precede global TOC exclusion, heading
  finalization, and optional footnote refinement, so final structure remains
  authoritative in the completed PCEX.
• ExtractionContext provides page geometry and resource access during extraction.
  read_pages() and read_asset() on both Craft facades provide the corresponding
  access to a completed extraction, without exposing temporary paths.

Shared PCEX translation and rendering

• render_markdown(), render_epub(), and PDF patching can consume translated
  content as it becomes available, without first creating a complete translated
  PCEX. translate_extraction() uses the same content producer to persist a new
  translation layer.
• PCEX translation and Markdown/EPUB rendering expose optional on_body and
  on_footnote callbacks carrying ParagraphContent(text, original, regions).
  Each event covers one whole logical paragraph or heading, including sources
  across pages. Text and optional original are separate Markdown values, even
  when the final output is bilingual. Standalone assets and formulas are not
  emitted as paragraphs.
• SourceRegion pairs each original bbox and source_order_in_page identity with
  a PageGeometry. map_bbox(target_size) maps coordinates using actual page
  dimensions rather than assuming the requested DPI matches the rendered image.
• PDF patching and translation callbacks carry PDFParagraphContent. Its
  PDFSourceRegion values include final Qt font sizes, text runs and baselines,
  inline formula vector data, and sampled erasure masks in source OCR pixels.
  A cross-page paragraph is delivered together after its final layout is known.
  Applications choose their own preview fonts; identical browser glyph shaping
  is not guaranteed.

EPUB translation fragments

• translate_epub(on_body=...) delivers EpubFragmentContent(epubcfi, original, translated): one accepted atomic fragment, with separate plain source and
  translated text. Overlapping LLM context windows do not produce duplicate
  notifications.
• Range CFIs locate content in the input EPUB, preserving text/tail positions and
  UTF-16 offsets across inline markup and formula projection. Precise callbacks
  require XHTML spine documents; text/html remains supported without on_body.
• Chapter reading and CFI package paths normalize relative paths, including
  ../ references from an OPF in a nested directory.

One finalized book metadata callback

• Optional on_metadata receives MetadataContent, with a complete
  DocumentMetadata and a separate original view for translation.
• PDF extraction without LLM metadata extraction notifies after reading native
  PDF metadata, before OCR. When LLM extraction is enabled, notification waits
  for the final merge with native fallback. Empty metadata still produces one
  notification when requested.
• PCEX translation and online translation rendering notify from their shared
  metadata stage. EPUB translation reports OPF book metadata separately from
  body fragments, navigation, and document-head titles.
• In EPUB bilingual modes, callback metadata remains a replacement view with
  the original separate; the final EPUB retains the requested append behavior.
  Repeated and unrecognized OPF fields remain preserved in the file.

Callback behavior and compatibility

• Callbacks are optional, accept synchronous or asynchronous functions, and
  asynchronous callbacks are awaited. Each content channel is ordered; body and
  footnote channels do not imply a shared total order.
• Disk-backed queues separate production from callback delivery. Completed work
  frees execution capacity even when an earlier result is delayed, and queued
  content and detached source contexts do not accumulate as full source DOMs in
  memory. Temporary disk usage can grow with the document.
• Missing callbacks skip their public snapshot/preview conversion; EPUB CFI
  source tracking is enabled only when needed. Callback failures and cancellation
  abort the operation. Final outputs are staged; Markdown text and assets use
  rollback because multiple paths cannot become atomically visible together.
  One-shot conversion publishes an optional extraction_path after extraction;
  later translation or rendering failures do not roll back that source PCEX.
• Existing entry points and PCEX v4 archives remain compatible with v2.4.4.
  EpubTranslation is available as an alias of EpubFragmentContent. Synchronous
  and asynchronous facades expose matching typed callback and translation options;
  internal translation hooks and PDF preview transport are private.

Validation and documentation

The regression suite passes 922 tests, including early delivery, ordered callbacks
under out-of-order completion, cancellation, optional callback costs, complete
multi-file CFI resolution, PDF layout scaling, bilingual metadata separation, and
synchronous callback forwarding and awaiting. Type checks, lint, and package
builds also pass.

See the callback guide, API reference,
and Chinese callback guide for payloads and examples.
Feature work: #514,
#515,
#516, and
#517.

Full Changelog: v2.4.4...v2.5.0