falcon_pdf/

mac.rs

//! The PDFKit side: every Objective-C and Core Graphics call in falcon's
//! PDF support is in this file.
//!
//! Most framework methods are `unsafe` in objc2 only because their
//! bindings cannot prove more than the types say. The invariants the calls
//! here rely on are the same throughout, so each block names which apply:
//!
//! - **owned**: every receiver and argument is a live `Retained`/`CFRetained`
//!   (or a reference borrowed from one) of the class the binding expects.
//! - **plain**: arguments are plain values (numbers, points, rects, option
//!   flags, a page index checked against `pageCount`).
//! - **one thread**: the `PDFDocument` and everything taken from it are
//!   only touched from the thread that opened it. `Document` holds
//!   `Retained` Objective-C objects, so it is neither `Send` nor `Sync`,
//!   and the compiler enforces this. PDFKit documents and pages may be
//!   created, searched and drawn off the main thread as long as one thread
//!   uses them at a time (the crate's tests exercise this).
//!
//! Every public method runs inside an autorelease pool, since the viewer
//! calls them on a worker thread that has none of its own.

use std::path::{Path, PathBuf};

use objc2::AnyThread;
use objc2::runtime::AnyObject;
use objc2::rc::{Retained, autoreleasepool};
use objc2_core_foundation::{CGPoint, CGRect, CGSize};
use objc2_core_graphics::{CGBitmapContextCreate, CGColorSpace, CGContext, CGImageAlphaInfo, CGImageByteOrderInfo, CGInterpolationQuality, CGPDFDocument};
use objc2_foundation::{NSArray, NSData, NSDate, NSPoint, NSString, NSStringCompareOptions, NSURL};
use objc2_pdf_kit::{
    PDFActionGoTo, PDFActionURL, PDFDestination, PDFDisplayBox, PDFDocument, PDFDocumentAttribute, PDFDocumentAuthorAttribute,
    PDFDocumentCreationDateAttribute, PDFDocumentCreatorAttribute, PDFDocumentKeywordsAttribute, PDFDocumentModificationDateAttribute,
    PDFDocumentProducerAttribute, PDFDocumentSubjectAttribute, PDFDocumentTitleAttribute, PDFOutline, PDFPage, PDFSelection,
};

use crate::geom::{self, PageGeom};
use crate::ocg::Patcher;
use crate::{Attachment, Bitmap, Error, Hit, Info, Layer, LayerNode, Link, LinkTarget, NEEDS_PASSWORD, OutlineEntry, Rect, Result, SearchOptions, Selection, WRONG_PASSWORD, render_size};

/// Search stops collecting after this many matches.
const MAX_HITS: usize = 10_000;

fn err(msg: impl Into<String>) -> Error {
    Error(msg.into())
}

/// Runs `f` on a document's catalog dictionary and its Core Graphics
/// document, if it has them.
fn catalog_of<T>(doc: &PDFDocument, f: impl FnOnce(catalog::Dict, &CGPDFDocument) -> T) -> Option<T> {
    // SAFETY: owned; one thread. The CGPDFDocument is retained for the
    // whole call, so the catalog and every object reached from it live
    // at least as long.
    let doc = unsafe { doc.documentRef() }?;
    let cat = CGPDFDocument::catalog(Some(&doc));
    (!cat.is_null()).then(|| f(cat, &doc))
}

/// An open PDF file. Usable only on the thread that opened it.
pub struct Document {
    doc: Retained<PDFDocument>,
    count: usize,
    path: PathBuf,
    password: Option<String>,
    /// The copy drawn while the layers differ from the default configuration.
    switched: Option<Retained<PDFDocument>>,
    /// Read on the first switch.
    patcher: Option<Patcher>,
}

impl Document {
    /// Opens a PDF. Fails cleanly for a missing file, a file that is not a
    /// PDF, and a password-protected PDF (with [`NEEDS_PASSWORD`]). Reads
    /// the file synchronously, so callers that must not block (the UI) call
    /// it on a worker thread.
    pub fn open(path: &Path) -> Result<Document> {
        Self::open_with_password(path, None)
    }

    /// Opens a PDF, unlocking it with `password` if it has one. A locked
    /// PDF fails with [`NEEDS_PASSWORD`] without a password and with
    /// [`WRONG_PASSWORD`] when the password doesn't unlock it.
    pub fn open_with_password(path: &Path, password: Option<&str>) -> Result<Document> {
        if !path.is_file() {
            return Err(err(format!("no file at {}", path.display())));
        }
        let path_text = path.to_str().ok_or_else(|| err("the path is not valid UTF-8"))?;
        autoreleasepool(|_| {
            let url = NSURL::fileURLWithPath(&NSString::from_str(path_text));
            // SAFETY: owned; one thread (the result stays in this `Document`).
            let doc = unsafe { PDFDocument::initWithURL(PDFDocument::alloc(), &url) }.ok_or_else(|| err("not a PDF this system can read"))?;
            // SAFETY: owned; one thread.
            if unsafe { doc.isLocked() } {
                let Some(pw) = password else { return Err(err(NEEDS_PASSWORD)) };
                // SAFETY: owned; one thread.
                if !unsafe { doc.unlockWithPassword(&NSString::from_str(pw)) } {
                    return Err(err(WRONG_PASSWORD));
                }
            }
            // SAFETY: owned; one thread.
            let count = unsafe { doc.pageCount() };
            Ok(Document { doc, count, path: path.to_path_buf(), password: password.map(str::to_string), switched: None, patcher: None })
        })
    }

    pub fn page_count(&self) -> usize {
        self.count
    }

    /// The document's title from its metadata, if it has one.
    pub fn title(&self) -> Option<String> {
        autoreleasepool(|_| {
            // SAFETY: owned; one thread; the attribute key is a framework
            // constant set at load time.
            let attrs = unsafe { self.doc.documentAttributes() }?;
            let key = unsafe { PDFDocumentTitleAttribute };
            let value = attrs.objectForKey(key)?;
            let s = value.downcast::<NSString>().ok()?.to_string();
            let s = s.trim().to_string();
            (!s.is_empty()).then_some(s)
        })
    }

    /// The document's metadata (title, author, dates, version and the like).
    pub fn info(&self) -> Info {
        autoreleasepool(|_| {
            // SAFETY: owned; one thread.
            let attrs = unsafe { self.doc.documentAttributes() };
            let get = |key: &PDFDocumentAttribute| attrs.as_ref().and_then(|a| a.objectForKey(key));
            // SAFETY: the attribute keys are framework constants set at load time.
            let text = |key: &PDFDocumentAttribute| get(key).and_then(|v| text_of(&v));
            let date = |key: &PDFDocumentAttribute| get(key).and_then(|v| v.downcast::<NSDate>().ok()).map(|d| d.timeIntervalSince1970());
            unsafe {
                Info {
                    title: text(PDFDocumentTitleAttribute),
                    author: text(PDFDocumentAuthorAttribute),
                    subject: text(PDFDocumentSubjectAttribute),
                    keywords: text(PDFDocumentKeywordsAttribute),
                    creator: text(PDFDocumentCreatorAttribute),
                    producer: text(PDFDocumentProducerAttribute),
                    created: date(PDFDocumentCreationDateAttribute),
                    modified: date(PDFDocumentModificationDateAttribute),
                    version: (self.doc.majorVersion() as i64, self.doc.minorVersion() as i64),
                    pages: self.count,
                    encrypted: self.doc.isEncrypted(),
                }
            }
        })
    }

    fn page(&self, i: usize) -> Result<Retained<PDFPage>> {
        if i >= self.count {
            return Err(err(format!("no page {}", i + 1)));
        }
        // SAFETY: owned, plain (index checked above); one thread.
        unsafe { self.doc.pageAtIndex(i) }.ok_or_else(|| err(format!("page {} can't be read", i + 1)))
    }

    /// Page `i` of the copy showing the chosen layers, else of the document.
    fn drawn_page(&self, i: usize) -> Result<Retained<PDFPage>> {
        let Some(doc) = &self.switched else { return self.page(i) };
        if i >= self.count {
            return Err(err(format!("no page {}", i + 1)));
        }
        // SAFETY: owned, plain (index checked above; the copy was checked to
        // have the same pages); one thread.
        unsafe { doc.pageAtIndex(i) }.ok_or_else(|| err(format!("page {} can't be read", i + 1)))
    }

    fn geom(page: &PDFPage) -> PageGeom {
        // SAFETY: owned, plain; one thread.
        let (b, rot) = unsafe { (page.boundsForBox(PDFDisplayBox::CropBox), page.rotation()) };
        PageGeom { x0: b.origin.x, y0: b.origin.y, w: b.size.width.abs(), h: b.size.height.abs(), turns: geom::turns(rot as i64) }
    }

    /// Page `i`'s size in points as shown (after its rotation).
    pub fn page_size(&self, i: usize) -> Option<(f64, f64)> {
        autoreleasepool(|_| self.page(i).ok().map(|p| Self::geom(&p).size()))
    }

    /// Every page's size, in order (one call for the viewer's layout).
    pub fn page_sizes(&self) -> Vec<(f64, f64)> {
        (0..self.count).map(|i| self.page_size(i).unwrap_or((612.0, 792.0))).collect()
    }

    /// Draws page `i` at `scale` pixels per point on white, turned as the
    /// page asks, shrunk so neither side exceeds `max_px`.
    pub fn render(&self, i: usize, scale: f64, max_px: usize) -> Result<Bitmap> {
        let size = self.page_size(i).ok_or_else(|| err(format!("no page {}", i + 1)))?;
        let (w, h) = render_size(size, scale, max_px.max(1));
        self.render_part(i, Rect { x: 0.0, y: 0.0, w: size.0, h: size.1 }, w, h)
    }

    /// Draws the part `part` of page `i` (display points, so the crop box
    /// and the page's turn are already applied) on white, filling a picture
    /// of `w` x `h` pixels. Memory follows the picture, not the page, so
    /// any zoom can be drawn for the part on screen.
    pub fn render_part(&self, i: usize, part: Rect, w: usize, h: usize) -> Result<Bitmap> {
        autoreleasepool(|_| {
            let page = self.drawn_page(i)?;
            let size = Self::geom(&page).size();
            let (w, h) = (w.max(1), h.max(1));
            let mut rgba = vec![0u8; w * h * 4];
            let space = CGColorSpace::new_device_rgb().ok_or_else(|| err("no RGB colour space"))?;
            let info = CGImageAlphaInfo::PremultipliedLast.0 | CGImageByteOrderInfo::Order32Big.0;
            // SAFETY: `rgba` is `w * h * 4` bytes and outlives the context,
            // which is dropped before `rgba` is moved; 8 bits per component
            // with `w * 4` bytes per row matches that buffer exactly.
            let ctx = unsafe { CGBitmapContextCreate(rgba.as_mut_ptr().cast(), w, h, 8, w * 4, Some(&space), info) }.ok_or_else(|| err("no bitmap context"))?;
            let c = Some(&*ctx);
            CGContext::set_rgb_fill_color(c, 1.0, 1.0, 1.0, 1.0);
            CGContext::fill_rect(c, CGRect::new(CGPoint::new(0.0, 0.0), CGSize::new(w as f64, h as f64)));
            CGContext::set_interpolation_quality(c, CGInterpolationQuality::High);
            if part.w > 0.0 && part.h > 0.0 {
                CGContext::scale_ctm(c, w as f64 / part.w, h as f64 / part.h);
                // The context's origin is at the bottom, display points' at
                // the top: the part's bottom-left corner goes to the origin.
                CGContext::translate_ctm(c, -part.x, part.y + part.h - size.1);
                // drawWithBox:toContext: applies the box's origin and the
                // page's rotation itself, drawing the page as shown into a
                // context of its displayed size (checked by the rotated-page
                // test).
                // SAFETY: owned; one thread; `ctx` is a live bitmap context.
                unsafe { page.drawWithBox_toContext(PDFDisplayBox::CropBox, &ctx) };
            }
            drop(ctx);
            // The background is opaque white, so premultiplied is straight.
            for px in rgba.as_chunks_mut::<4>().0 {
                px[3] = 255;
            }
            Ok(Bitmap { width: w, height: h, rgba })
        })
    }

    /// A small picture of page `i` whose longer side is `max_px`.
    pub fn thumbnail(&self, i: usize, max_px: usize) -> Result<Bitmap> {
        let size = self.page_size(i).ok_or_else(|| err(format!("no page {}", i + 1)))?;
        let longest = size.0.max(size.1).max(1.0);
        self.render(i, max_px as f64 / longest, max_px)
    }

    /// The text of page `i` (empty for a page without a text layer).
    pub fn text(&self, i: usize) -> String {
        autoreleasepool(|_| {
            let Ok(page) = self.page(i) else { return String::new() };
            // SAFETY: owned; one thread.
            unsafe { page.string() }.map(|s| s.to_string()).unwrap_or_default()
        })
    }

    /// Every match of `text` in the document, in reading order, with one
    /// rectangle per line it spans. An empty query finds nothing.
    pub fn search(&self, text: &str, options: SearchOptions) -> Vec<Hit> {
        if text.is_empty() {
            return Vec::new();
        }
        autoreleasepool(|_| {
            let mut flags = NSStringCompareOptions::empty();
            if !options.match_diacritics {
                flags |= NSStringCompareOptions::DiacriticInsensitiveSearch;
            }
            if !options.match_case {
                flags |= NSStringCompareOptions::CaseInsensitiveSearch;
            }
            // Each page's text as PDFKit counts it, for the whole-word test.
            let mut texts: std::collections::HashMap<usize, Vec<u16>> = std::collections::HashMap::new();
            // SAFETY: owned, plain; one thread.
            let found = unsafe { self.doc.findString_withOptions(&NSString::from_str(text), flags) };
            let mut hits = Vec::new();
            for sel in found.iter().take(MAX_HITS) {
                // SAFETY: owned; one thread.
                let pages = unsafe { sel.pages() };
                for page in pages.iter() {
                    // SAFETY: owned; one thread; the page belongs to this document.
                    let index = unsafe { self.doc.indexForPage(&page) };
                    if index >= self.count {
                        continue;
                    }
                    if options.whole_words {
                        // SAFETY: owned, plain; one thread; the page is one of the selection's.
                        let range = unsafe { sel.rangeAtIndex_onPage(0, &page) };
                        let text = texts.entry(index).or_insert_with(|| unsafe { page.string() }.map(|s| s.to_string().encode_utf16().collect()).unwrap_or_default());
                        if !crate::is_whole_word(text, range.location, range.length) {
                            continue;
                        }
                    }
                    hits.push(Hit { page: index, rects: line_rects(&sel, &page) });
                }
            }
            hits
        })
    }

    /// The text between two display points on page `page` (as a drag from
    /// `from` to `to` selects it) and the rectangles to highlight.
    pub fn selection(&self, page: usize, from: (f64, f64), to: (f64, f64)) -> Selection {
        autoreleasepool(|_| {
            let Ok(p) = self.page(page) else { return Selection::default() };
            let g = Self::geom(&p);
            let (a, b) = (g.to_page(from.0, from.1), g.to_page(to.0, to.1));
            // SAFETY: owned, plain; one thread.
            let Some(sel) = (unsafe { p.selectionFromPoint_toPoint(NSPoint::new(a.0, a.1), NSPoint::new(b.0, b.1)) }) else {
                return Selection::default();
            };
            // SAFETY: owned; one thread.
            let text = unsafe { sel.string() }.map(|s| s.to_string()).unwrap_or_default();
            let rects = if text.is_empty() { Vec::new() } else { line_rects(&sel, &p) };
            Selection { text, rects }
        })
    }

    /// The table of contents, flattened depth-first; empty if there is none.
    pub fn outline(&self) -> Vec<OutlineEntry> {
        autoreleasepool(|_| {
            let mut out = Vec::new();
            // SAFETY: owned; one thread.
            if let Some(root) = unsafe { self.doc.outlineRoot() } {
                self.walk(&root, 0, &mut out);
            }
            out
        })
    }

    /// The files embedded in the document: the catalog's EmbeddedFiles
    /// name tree, then each page's file attachment annotations. PDFKit has
    /// no API for them, so this reads the document's objects through Core
    /// Graphics (`documentRef`).
    pub fn attachments(&self) -> Vec<Attachment> {
        autoreleasepool(|_| self.with_catalog(|cat, doc| catalog::embedded(cat, doc).into_iter().map(|(a, _)| a).collect()).unwrap_or_default())
    }

    /// The bytes of attachment `i` of [`Document::attachments`].
    pub fn attachment_data(&self, i: usize) -> Result<Vec<u8>> {
        autoreleasepool(|_| {
            self.with_catalog(|cat, doc| catalog::embedded(cat, doc).into_iter().nth(i).and_then(|(_, stream)| catalog::stream_bytes(stream)))
                .flatten()
                .ok_or_else(|| err("the attachment can't be read"))
        })
    }

    /// The optional content groups ("layers") and whether the default
    /// configuration shows each.
    pub fn layers(&self) -> Vec<Layer> {
        autoreleasepool(|_| self.with_catalog(|cat, _| catalog::layers(cat)).unwrap_or_default())
    }

    /// The layers list as a tree, from the default configuration's
    /// `/Order` (see [`crate::layer_tree`]); `None` when it has none, and
    /// the list is then flat. Indices are those of [`Document::layers`].
    pub fn layer_tree(&self) -> Option<Vec<LayerNode>> {
        autoreleasepool(|_| self.with_catalog(|cat, _| catalog::layer_tree(cat)).flatten())
    }

    /// Chooses which layers [`Document::render`] and [`Document::thumbnail`]
    /// show, one flag per entry of [`Document::layers`]. The default choice
    /// draws the document itself; any other draws an in-memory copy with
    /// that configuration (see the `ocg` module). Text, search and links
    /// stay the document's. On failure what's drawn doesn't change.
    pub fn set_layers(&mut self, visible: &[bool]) -> Result<()> {
        let layers = self.layers();
        if visible.len() != layers.len() {
            return Err(err("the list of layers doesn't match the document"));
        }
        if layers.iter().map(|l| l.visible).eq(visible.iter().copied()) {
            self.switched = None;
            return Ok(());
        }
        let mut bytes = std::fs::read(&self.path).map_err(|e| err(e.to_string()))?;
        if self.patcher.is_none() {
            let patcher = Patcher::new(&bytes, self.password.as_deref())?;
            if patcher.groups() != layers.len() {
                return Err(err("the PDF's layers can't be switched"));
            }
            self.patcher = Some(patcher);
        }
        let tail = self.patcher.as_ref().map(|p| p.update(visible, bytes.len())).unwrap_or_default();
        bytes.extend_from_slice(&tail);
        autoreleasepool(|_| {
            let data = NSData::with_bytes(&bytes);
            // SAFETY: owned; one thread (the copy stays in this `Document`).
            let copy = unsafe { PDFDocument::initWithData(PDFDocument::alloc(), &data) }.ok_or_else(|| err("the PDF's layers can't be switched"))?;
            // SAFETY: owned; one thread.
            if unsafe { copy.isLocked() } && !self.password.as_deref().is_some_and(|pw| unsafe { copy.unlockWithPassword(&NSString::from_str(pw)) }) {
                return Err(err("the PDF's layers can't be switched"));
            }
            // SAFETY: owned; one thread.
            let same_pages = unsafe { copy.pageCount() } == self.count;
            // The engine must read back the configuration just written.
            let took = catalog_of(&copy, |cat, _| catalog::layers(cat)).is_some_and(|l| l.iter().map(|l| l.visible).eq(visible.iter().copied()));
            if !same_pages || !took {
                return Err(err("the PDF's layers can't be switched"));
            }
            self.switched = Some(copy);
            Ok(())
        })
    }

    /// Runs `f` on the document's catalog dictionary and its Core Graphics
    /// document, if it has them.
    fn with_catalog<T>(&self, f: impl FnOnce(catalog::Dict, &CGPDFDocument) -> T) -> Option<T> {
        catalog_of(&self.doc, f)
    }

    /// Page `i`'s link annotations: their areas and where they go (a page
    /// of this document or a URL). Links to other files are left out.
    pub fn links(&self, i: usize) -> Vec<Link> {
        autoreleasepool(|_| {
            let Ok(page) = self.page(i) else { return Vec::new() };
            let g = Self::geom(&page);
            let mut out = Vec::new();
            // SAFETY: owned; one thread.
            let annotations = unsafe { page.annotations() };
            for a in annotations.iter() {
                // SAFETY: owned; one thread.
                let (kind, b) = unsafe { (a.r#type(), a.bounds()) };
                if kind.is_none_or(|k| k.to_string() != "Link") || b.size.width <= 0.0 || b.size.height <= 0.0 {
                    continue;
                }
                // The annotation's own URL or destination, else its action's.
                // SAFETY: owned; one thread.
                let (url, dest, action) = unsafe { (a.URL(), a.destination(), a.action()) };
                let url = url.or_else(|| action.clone().and_then(|act| act.downcast::<PDFActionURL>().ok()).and_then(|u| unsafe { u.URL() }));
                // SAFETY: owned; one thread.
                let dest = dest.or_else(|| action.and_then(|act| act.downcast::<PDFActionGoTo>().ok()).map(|go| unsafe { go.destination() }));
                let target = if let Some(text) = url.and_then(|u| u.absoluteString()).map(|s| s.to_string()) {
                    Some(LinkTarget::Url(text))
                } else {
                    dest.and_then(|d| self.destination(&d))
                };
                if let Some(target) = target {
                    out.push(Link { rect: g.rect_to_display(b.origin.x, b.origin.y, b.size.width, b.size.height), target });
                }
            }
            out
        })
    }

    /// A destination in this document as a page and display point.
    fn destination(&self, d: &PDFDestination) -> Option<LinkTarget> {
        // SAFETY: owned; one thread; the page belongs to this document.
        let (page, point) = unsafe { (d.page()?, d.point()) };
        let index = unsafe { self.doc.indexForPage(&page) };
        if index >= self.count {
            return None;
        }
        // PDFKit marks an unspecified coordinate with a huge value.
        let known = |v: f64| v.is_finite() && v.abs() < 1e7;
        let point = (known(point.x) && known(point.y)).then(|| Self::geom(&page).to_display(point.x, point.y));
        Some(LinkTarget::Page { page: index, point })
    }

    fn walk(&self, node: &PDFOutline, depth: usize, out: &mut Vec<OutlineEntry>) {
        // Deep or huge outlines are cut off rather than walked forever.
        if depth > 16 || out.len() > 5000 {
            return;
        }
        // SAFETY: owned, plain (child index below numberOfChildren); one thread.
        unsafe {
            for n in 0..node.numberOfChildren() {
                let Some(child) = node.childAtIndex(n) else { continue };
                let title = child.label().map(|s| s.to_string()).unwrap_or_default();
                let page = child.destination().and_then(|d| d.page()).map(|p| self.doc.indexForPage(&p)).filter(|&i| i < self.count);
                out.push(OutlineEntry { title, depth, page });
                self.walk(&child, depth + 1, out);
            }
        }
    }
}

/// Opens the PDF at `path` as [`print`] prints it: showing `layers` (one
/// flag per entry of [`Document::layers`]) when given. The file on disk is
/// not changed.
pub fn open_for_print(path: &Path, password: Option<&str>, layers: Option<&[bool]>) -> Result<Document> {
    let mut doc = Document::open_with_password(path, password)?;
    if let Some(visible) = layers {
        doc.set_layers(visible)?;
    }
    Ok(doc)
}

/// Prints the PDF at `path` (unlocked with `password` if it has one)
/// through PDFKit's print operation: the system print panel, then the job
/// named `title`. `layers` is the reader's choice of layers, if it differs
/// from the document's default; the job prints what that shows. Must run
/// on the main thread, which it blocks while the panel is up, and opens the
/// file again there, since a [`Document`] stays on the thread that opened
/// it. Returns whether it printed (false if cancelled). Fails off the main
/// thread, for an unreadable file, when the layers can't be switched, or
/// when the PDF forbids printing.
pub fn print(path: &Path, password: Option<&str>, title: &str, layers: Option<&[bool]>) -> Result<bool> {
    let mtm = objc2::MainThreadMarker::new().ok_or_else(|| err("printing needs the main thread"))?;
    let doc = open_for_print(path, password, layers)?;
    autoreleasepool(|_| {
        // SAFETY: owned; this (main) thread opened the document just now.
        if !unsafe { doc.doc.allowsPrinting() } {
            return Err(err("this PDF does not allow printing"));
        }
        let info = objc2_app_kit::NSPrintInfo::sharedPrintInfo();
        // SAFETY: owned, plain; main thread (`mtm`).
        let op = unsafe { doc.switched.as_ref().unwrap_or(&doc.doc).printOperationForPrintInfo_scalingMode_autoRotate(Some(&info), objc2_pdf_kit::PDFPrintScalingMode::PageScaleDownToFit, true, mtm) }
            .ok_or_else(|| err("PDFKit made no print job"))?;
        op.setJobTitle(Some(&NSString::from_str(title)));
        op.setShowsPrintPanel(true);
        op.setShowsProgressPanel(true);
        Ok(op.runOperation())
    })
}

/// A metadata value as text: a string, or a list of strings (keywords)
/// joined by commas; blank values count as none.
fn text_of(v: &AnyObject) -> Option<String> {
    let s = if let Some(s) = v.downcast_ref::<NSString>() {
        s.to_string()
    } else {
        let list = v.downcast_ref::<NSArray>()?;
        list.iter().filter_map(|x| x.downcast_ref::<NSString>().map(|s| s.to_string())).collect::<Vec<_>>().join(", ")
    };
    let s = s.trim().to_string();
    (!s.is_empty()).then_some(s)
}

/// One display rectangle per line of `sel` on `page`.
fn line_rects(sel: &PDFSelection, page: &PDFPage) -> Vec<Rect> {
    let g = Document::geom(page);
    // SAFETY: owned; one thread (called from `Document` methods).
    let lines = unsafe { sel.selectionsByLine() };
    let mut rects = Vec::new();
    for line in lines.iter() {
        // SAFETY: owned; one thread.
        let b = unsafe { line.boundsForPage(page) };
        if b.size.width > 0.0 && b.size.height > 0.0 {
            rects.push(g.rect_to_display(b.origin.x, b.origin.y, b.size.width, b.size.height));
        }
    }
    rects
}

#[cfg(test)]
mod tests {
    use objc2_foundation::NSDictionary;
    use objc2_pdf_kit::{PDFDocumentOwnerPasswordOption, PDFDocumentUserPasswordOption};

    use super::*;

    /// A one-page PDF with a title, written by hand.
    fn plain_pdf(path: &Path) {
        let objs = [
            "<< /Type /Catalog /Pages 2 0 R >>",
            "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>",
            "<< /Title (Locked Book) /Author (Falcon) /Keywords (one two) >>",
        ];
        let mut out = b"%PDF-1.4\n".to_vec();
        let mut offsets = Vec::new();
        for (k, body) in objs.iter().enumerate() {
            offsets.push(out.len());
            out.extend_from_slice(format!("{} 0 obj\n{body}\nendobj\n", k + 1).as_bytes());
        }
        let xref = out.len();
        out.extend_from_slice(format!("xref\n0 {}\n0000000000 65535 f \n", objs.len() + 1).as_bytes());
        for o in offsets {
            out.extend_from_slice(format!("{o:010} 00000 n \n").as_bytes());
        }
        out.extend_from_slice(format!("trailer\n<< /Size {} /Root 1 0 R /Info 4 0 R >>\nstartxref\n{xref}\n%%EOF\n", objs.len() + 1).as_bytes());
        std::fs::write(path, out).unwrap();
    }

    #[test]
    fn passwords_unlock_and_metadata_reads() {
        let dir = tempfile::tempdir().unwrap();
        let (plain, locked) = (dir.path().join("plain.pdf"), dir.path().join("locked.pdf"));
        plain_pdf(&plain);
        let info = Document::open(&plain).unwrap().info();
        assert_eq!(info.title.as_deref(), Some("Locked Book"));
        assert_eq!(info.author.as_deref(), Some("Falcon"));
        assert_eq!((info.pages, info.encrypted), (1, false));
        assert!(info.version.0 >= 1);
        // PDFKit writes an encrypted copy with a user password.
        autoreleasepool(|_| {
            let url = NSURL::fileURLWithPath(&NSString::from_str(plain.to_str().unwrap()));
            // SAFETY: owned, plain; this test's thread only; the option keys
            // are framework constants.
            unsafe {
                let doc = PDFDocument::initWithURL(PDFDocument::alloc(), &url).unwrap();
                let (user, owner) = (NSString::from_str("secret"), NSString::from_str("owner"));
                let keys = [PDFDocumentUserPasswordOption, PDFDocumentOwnerPasswordOption];
                let options = NSDictionary::from_slices(&keys, &[user.as_ref(), owner.as_ref()]);
                let out = NSURL::fileURLWithPath(&NSString::from_str(locked.to_str().unwrap()));
                assert!(doc.writeToURL_withOptions(&out, Some(&options)));
            }
        });
        let e = Document::open(&locked).err().unwrap();
        assert_eq!(e.0, NEEDS_PASSWORD);
        assert!(e.needs_password());
        let e = Document::open_with_password(&locked, Some("nope")).err().unwrap();
        assert_eq!(e.0, WRONG_PASSWORD);
        assert!(e.needs_password());
        let doc = Document::open_with_password(&locked, Some("secret")).unwrap();
        assert_eq!(doc.page_count(), 1);
        assert!(doc.info().encrypted);
        assert!(!Error("no file".into()).needs_password());
    }

    #[test]
    fn printing_needs_the_main_thread() {
        // The test harness runs tests on other threads.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("plain.pdf");
        plain_pdf(&path);
        let e = print(&path, None, "x", None).err().unwrap();
        assert!(e.0.contains("main thread"), "{e}");
    }
}

/// Reading the document's own objects through Core Graphics' CGPDF
/// functions: the embedded files and the optional content groups, which
/// PDFKit doesn't expose.
///
/// Every pointer here is borrowed from a `CGPDFDocument` the caller keeps
/// retained for the whole walk (`Document::with_catalog`), and is checked
/// for null before use. Walks are capped in depth and count, so a
/// malformed or cyclic tree ends.
mod catalog {
    use std::ffi::CStr;
    use std::ptr::{self, NonNull};

    use objc2_core_graphics::{
        CGPDFArray, CGPDFArrayRef, CGPDFDataFormat, CGPDFDictionary, CGPDFDictionaryRef, CGPDFDocument, CGPDFInteger, CGPDFPage, CGPDFStream,
        CGPDFStreamRef, CGPDFString, CGPDFStringRef,
    };

    use crate::{Attachment, Layer, LayerNode, OrderItem, layer_tree as build_tree};

    pub type Dict = CGPDFDictionaryRef;

    const MAX_DEPTH: usize = 32;
    const MAX_ITEMS: usize = 10_000;

    fn key(k: &CStr) -> NonNull<std::ffi::c_char> {
        NonNull::new(k.as_ptr().cast_mut()).expect("a C string literal is never null")
    }

    fn dict(d: Dict, k: &CStr) -> Option<Dict> {
        let mut out: Dict = ptr::null_mut();
        // SAFETY: `d` is a live dictionary (see the module notes); `out` is
        // a local the call writes.
        (unsafe { CGPDFDictionary::dictionary(d, key(k), &mut out) } && !out.is_null()).then_some(out)
    }

    fn array(d: Dict, k: &CStr) -> Option<CGPDFArrayRef> {
        let mut out: CGPDFArrayRef = ptr::null_mut();
        // SAFETY: as `dict`.
        (unsafe { CGPDFDictionary::array(d, key(k), &mut out) } && !out.is_null()).then_some(out)
    }

    fn stream(d: Dict, k: &CStr) -> Option<CGPDFStreamRef> {
        let mut out: CGPDFStreamRef = ptr::null_mut();
        // SAFETY: as `dict`.
        (unsafe { CGPDFDictionary::stream(d, key(k), &mut out) } && !out.is_null()).then_some(out)
    }

    fn integer(d: Dict, k: &CStr) -> Option<i64> {
        let mut out: CGPDFInteger = 0;
        // SAFETY: as `dict`.
        unsafe { CGPDFDictionary::integer(d, key(k), &mut out) }.then_some(out as i64)
    }

    fn name(d: Dict, k: &CStr) -> Option<String> {
        let mut out: *const std::ffi::c_char = ptr::null();
        // SAFETY: as `dict`; a name is a NUL-terminated string owned by the
        // document.
        (unsafe { CGPDFDictionary::name(d, key(k), &mut out) } && !out.is_null()).then(|| unsafe { CStr::from_ptr(out) }.to_string_lossy().into_owned())
    }

    fn text(s: CGPDFStringRef) -> Option<String> {
        // SAFETY: `s` is a live string object of the document, or null.
        (!s.is_null()).then(|| unsafe { CGPDFString::text_string(s) }).flatten().map(|cf| cf.to_string())
    }

    fn string(d: Dict, k: &CStr) -> Option<String> {
        let mut out: CGPDFStringRef = ptr::null_mut();
        // SAFETY: as `dict`.
        if unsafe { CGPDFDictionary::string(d, key(k), &mut out) } { text(out) } else { None }
    }

    fn len(a: CGPDFArrayRef) -> usize {
        // SAFETY: `a` is a live array of the document.
        unsafe { CGPDFArray::count(a) }.min(MAX_ITEMS)
    }

    fn array_dict(a: CGPDFArrayRef, i: usize) -> Option<Dict> {
        let mut out: Dict = ptr::null_mut();
        // SAFETY: `a` is live and `i` is below its count.
        (unsafe { CGPDFArray::dictionary(a, i, &mut out) } && !out.is_null()).then_some(out)
    }

    fn array_string(a: CGPDFArrayRef, i: usize) -> Option<String> {
        let mut out: CGPDFStringRef = ptr::null_mut();
        // SAFETY: as `array_dict`.
        if unsafe { CGPDFArray::string(a, i, &mut out) } { text(out) } else { None }
    }

    /// A file specification's attachment: its name, size and description,
    /// and the stream holding its bytes.
    fn file_spec(spec: Dict, fallback: Option<String>) -> Option<(Attachment, CGPDFStreamRef)> {
        let ef = dict(spec, c"EF")?;
        let data = stream(ef, c"UF").or_else(|| stream(ef, c"F"))?;
        let name = string(spec, c"UF").or_else(|| string(spec, c"F")).or(fallback).unwrap_or_else(|| "attachment".into());
        // SAFETY: `data` is a live stream of the document.
        let params = dict(unsafe { CGPDFStream::dictionary(data) }, c"Params");
        let size = params.and_then(|p| integer(p, c"Size")).and_then(|n| u64::try_from(n).ok());
        Some((Attachment { name, size, description: string(spec, c"Desc") }, data))
    }

    /// One node of the EmbeddedFiles name tree and its kids.
    fn name_tree(node: Dict, depth: usize, out: &mut Vec<(Attachment, CGPDFStreamRef)>) {
        if depth > MAX_DEPTH || out.len() >= MAX_ITEMS {
            return;
        }
        if let Some(names) = array(node, c"Names") {
            for i in (0..len(names)).step_by(2) {
                if let Some(spec) = array_dict(names, i + 1)
                    && let Some(a) = file_spec(spec, array_string(names, i))
                {
                    out.push(a);
                }
            }
        }
        if let Some(kids) = array(node, c"Kids") {
            for i in 0..len(kids) {
                if let Some(kid) = array_dict(kids, i) {
                    name_tree(kid, depth + 1, out);
                }
            }
        }
    }

    /// Every embedded file, in pdf.js's order: the name tree, then the
    /// pages' file attachment annotations.
    pub fn embedded(cat: Dict, doc: &CGPDFDocument) -> Vec<(Attachment, CGPDFStreamRef)> {
        let mut out = Vec::new();
        if let Some(tree) = dict(cat, c"Names").and_then(|n| dict(n, c"EmbeddedFiles")) {
            name_tree(tree, 0, &mut out);
        }
        for n in 1..=CGPDFDocument::number_of_pages(Some(doc)) {
            let Some(page) = CGPDFDocument::page(Some(doc), n) else { continue };
            let pd = CGPDFPage::dictionary(Some(&page));
            if pd.is_null() {
                continue;
            }
            let Some(annots) = array(pd, c"Annots") else { continue };
            for i in 0..len(annots) {
                if out.len() >= MAX_ITEMS {
                    return out;
                }
                if let Some(a) = array_dict(annots, i)
                    && name(a, c"Subtype").as_deref() == Some("FileAttachment")
                    && let Some(spec) = dict(a, c"FS")
                    && let Some(f) = file_spec(spec, string(a, c"Contents"))
                {
                    out.push(f);
                }
            }
        }
        out
    }

    /// The bytes of an embedded file's stream, decoded.
    pub fn stream_bytes(s: CGPDFStreamRef) -> Option<Vec<u8>> {
        let mut format = CGPDFDataFormat::Raw;
        // SAFETY: `s` is a live stream of the document; `format` is a local.
        unsafe { CGPDFStream::data(s, &mut format) }.map(|d| d.to_vec())
    }

    fn array_array(a: CGPDFArrayRef, i: usize) -> Option<CGPDFArrayRef> {
        let mut out: CGPDFArrayRef = ptr::null_mut();
        // SAFETY: as `array_dict`.
        (unsafe { CGPDFArray::array(a, i, &mut out) } && !out.is_null()).then_some(out)
    }

    /// `/Order` as items. The walk is capped in depth and in count, since
    /// an array may reach itself through an indirect object.
    fn order_items(a: CGPDFArrayRef, groups: &[Dict], depth: usize, budget: &mut usize) -> Vec<OrderItem> {
        let mut out = Vec::new();
        if depth > MAX_DEPTH {
            return out;
        }
        for i in 0..len(a) {
            if *budget == 0 {
                break;
            }
            *budget -= 1;
            out.push(if let Some(g) = array_dict(a, i) {
                groups.iter().position(|&x| x == g).map_or(OrderItem::Other, OrderItem::Group)
            } else if let Some(inner) = array_array(a, i) {
                OrderItem::Array(order_items(inner, groups, depth + 1, budget))
            } else if let Some(t) = array_string(a, i) {
                OrderItem::Text(t)
            } else {
                OrderItem::Other
            });
        }
        out
    }

    /// The layers tree from the default configuration's `/Order`, if it
    /// has one. Labels are read as text strings, so PDFDocEncoding,
    /// UTF-16 and an encrypted document's strings come out as they do for
    /// the groups' names.
    pub fn layer_tree(cat: Dict) -> Option<Vec<LayerNode>> {
        let props = dict(cat, c"OCProperties")?;
        let groups_array = array(props, c"OCGs")?;
        let groups: Vec<Dict> = (0..len(groups_array)).filter_map(|i| array_dict(groups_array, i)).collect();
        let order = array(dict(props, c"D")?, c"Order")?;
        let mut budget = MAX_ITEMS;
        Some(build_tree(&order_items(order, &groups, 0, &mut budget), groups.len()))
    }

    /// The optional content groups, in the document's order, each visible
    /// unless the default configuration turns it off (its base state, then
    /// its ON and OFF lists). Groups are matched by object identity: Core
    /// Graphics hands out one dictionary per indirect object.
    pub fn layers(cat: Dict) -> Vec<Layer> {
        let Some(props) = dict(cat, c"OCProperties") else { return Vec::new() };
        let Some(groups) = array(props, c"OCGs") else { return Vec::new() };
        let config = dict(props, c"D");
        let base_on = config.and_then(|d| name(d, c"BaseState")).is_none_or(|s| s != "OFF");
        let listed = |k: &CStr| -> Vec<Dict> { config.and_then(|d| array(d, k)).map(|a| (0..len(a)).filter_map(|i| array_dict(a, i)).collect()).unwrap_or_default() };
        let (on, off) = (listed(c"ON"), listed(c"OFF"));
        (0..len(groups))
            .filter_map(|i| array_dict(groups, i))
            .map(|g| {
                let visible = if base_on { !off.contains(&g) } else { on.contains(&g) };
                Layer { name: string(g, c"Name").unwrap_or_default(), visible }
            })
            .collect()
    }
}