Crate kael_pdf 

kael_pdf

Bounded PDF document primitives for native applications built with Kael or with a custom UI.

The crate provides in-process PDF parsing, metadata and outline discovery, per-page text extraction and search, link discovery, atomic document saves, and a validated sidecar annotation model. It has no dependency on kael_ui and no native system-library requirement.

Native and wasm32-unknown-unknown builds share the bounded byte parser. Use PdfDocument::from_bytes (or async open_from_memory) for browser file-picker, drop, IndexedDB, and download workflows. to_bytes, annotations_to_bytes, and load_annotations_from_bytes keep PDF and sidecar persistence byte-oriented. Native-only open, save, and save_annotations return a typed PdfPlatformError in browsers rather than treating a browser origin as a filesystem.

Quick start

use kael_pdf::{PdfDocument, Result};

smol::block_on(async {
    let document = PdfDocument::open("manual.pdf").await?;
    println!("{} pages", document.page_count());

    let first_page = document.page(0)?;
    let text = first_page.text()?;
    let matches = first_page.search("installation")?;
    let links = first_page.links()?;

    // A lightweight layout placeholder, not a rendering of PDF graphics.
    let preview = first_page.schematic_preview(1.0).await?;
    assert_eq!(preview.pixels().len(), preview.width() as usize * preview.height() as usize * 4);
    println!("{} text bytes, {} matches, {} links", text.len(), matches.len(), links.len());
    Ok(())
})

Deliberate scope

schematic_preview draws extracted-text bars and Kael sidecar annotations into an RGBA placeholder. It does not rasterize the PDF content stream, fonts, images, or vector graphics. Use a platform PDF API or a dedicated optional renderer in the application when pixel-faithful pages are required. The naming is intentional so a placeholder can never be mistaken for a rendered legal, financial, or design document.

Kael annotations live in <document>.annotations.json; they are not embedded into the PDF and are not visible to other PDF readers. The model supports highlights, notes, free text, ink, and stamps. has_unsaved_annotations reports dirty state. Use save_annotations to update only the sidecar without rewriting the PDF, or PdfDocument::save to write both to a new destination. The sidecar-only path verifies that the PDF has not changed on disk. The crate is not a form editor, digital-signature engine, collaborative review service, or PDF/A validator.

Persistence and recovery

Document and sidecar writes use a temporary sibling, flush and sync it, then atomically replace the destination. Existing PDF permissions are preserved. Existing symbolic-link destinations are resolved to their target instead of replacing the link. Sidecars reject symbolic links and non-regular files; newly created sidecars use owner-only permissions on Unix.

A stale, malformed, oversized, or unsafe sidecar never prevents a valid PDF from opening. Its annotations are ignored and annotation_load_warning describes the problem. If the primary PDF save succeeds but sidecar persistence fails, the returned error states that the PDF itself was saved.

Resource bounds

• input and saved PDFs: 256 MiB;
• parsed objects: 1,000,000; pages: 100,000;
• extracted text per page: 16 MiB;
• cached text: 64 MiB and 1,024 pages;
• schematic previews: aspect-preserving output of at most 4,096 × 4,096 RGBA pixels and 16 million drawing operations;
• cached previews: 128 MiB and 256 entries;
• annotation sidecar and in-memory model: 16 MiB and 100,000 annotations;
• search query: 4 KiB; results per page: 10,000; and
• links per page and outline entries: 10,000 each.

Text extraction, search, links, annotation mutations, and from_bytes are synchronous and may do CPU work while holding the document’s internal lock. Native page preview generation and document open/save use the blocking worker pool; browser byte work runs in the calling context. Keep these operations away from latency-sensitive render or audio callbacks, and use a web worker for large browser documents.

PDFs are complex, attacker-controlled containers. These limits constrain Kael-owned allocations and traversal, but the parser still runs in process. Applications accepting hostile documents should use operating-system sandboxing or a dedicated worker process as an additional trust boundary.

Treat every PdfLinkDestination::Uri as untrusted input. Kael bounds it and rejects control characters, but the application must allowlist schemes and request user intent before opening an external destination.

API documentation is generated from this README and the public item documentation on docs.rs. The broader framework guide lives in the Kael repository.

License

Licensed under the Apache License, Version 2.0. See LICENSE-APACHE.

Re-exports

pub use annotation::Annotation;

pub use annotation::AnnotationId;

pub use annotation::PageAnnotation;

pub use annotation::PdfColor;

pub use annotation::PdfPoint;

pub use annotation::PdfRect;

pub use annotation::StampKind;

pub use document::OutlineItem;

pub use document::PdfDocument;

pub use document::PdfMetadata;

pub use document::PdfPlatformError;

pub use page::PdfLink;

pub use page::PdfLinkDestination;

pub use page::PdfPage;

pub use page::PdfPageSize;

pub use renderer::PagePreview;

pub use text::TextMatch;

Modules

annotation

PDF annotation types. PDF annotation types.

document

PDF document loading and persistence. PDF document loading and persistence.

page

PDF page access. PDF page access.

platform

Platform metadata for PDF services. Platform metadata for PDF services.

renderer

Schematic page preview generation. Schematic raster page preview generation.

text

Text extraction and search helpers. Text extraction and search helpers.

Type Aliases

Result

Result<T, Error>