@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/pdfkit/references/pdfkit-patterns.md

@@ -1,839 +1,617 @@
-# PDFKit Patterns
+# PDFKit patterns
 
-Extended patterns for PDFKit: form filling, creating PDFs programmatically,
-watermarks, printing, merging documents, custom page overlays, document
-outlines, and custom annotation drawing.
+Longer recipes that build on the main skill. Code targets Swift 6.3 and iOS 26;
+functions that touch views are `@MainActor`.
 
 ## Contents
 
-- [Form Filling](#form-filling)
-- [Creating PDFs Programmatically](#creating-pdfs-programmatically)
+- [Forms](#forms)
+- [Building PDFs in code](#building-pdfs-in-code)
 - [Watermarks](#watermarks)
-- [Merging Documents](#merging-documents)
+- [Merging and splitting](#merging-and-splitting)
 - [Printing](#printing)
-- [Document Outlines](#document-outlines)
-- [Custom Annotation Subclasses](#custom-annotation-subclasses)
-- [Custom Page Subclasses](#custom-page-subclasses)
-- [Page Overlay Lifecycle](#page-overlay-lifecycle)
-- [Rendering Pages to Images](#rendering-pages-to-images)
-- [Page Rotation and Cropping](#page-rotation-and-cropping)
-- [Burning In Annotations](#burning-in-annotations)
-- [Document Permissions](#document-permissions)
-- [Coordinator Pattern for PDFView](#coordinator-pattern-for-pdfview)
+- [Outlines](#outlines)
+- [Custom annotation classes](#custom-annotation-classes)
+- [Custom page classes](#custom-page-classes)
+- [Overlay lifecycle](#overlay-lifecycle)
+- [Rendering a page to an image](#rendering-a-page-to-an-image)
+- [Rotation and cropping](#rotation-and-cropping)
+- [Burning in annotations](#burning-in-annotations)
+- [Permissions](#permissions)
+- [Coordinator-based SwiftUI wrapper](#coordinator-based-swiftui-wrapper)
 
-## Form Filling
+## Forms
 
-PDF forms use widget annotations. Each widget has a `fieldName`, a
-`widgetFieldType`, and a `widgetStringValue`.
+Interactive PDF fields are widget annotations. Each one has a `fieldName`, a
+`widgetFieldType` and, for text fields, a `widgetStringValue`.
 
-### Reading Form Fields
+### Reading and filling
 
 ```swift
-func extractFormFields(from document: PDFDocument) -> [(name: String, value: String)] {
-    var fields: [(String, String)] = []
-    for pageIndex in 0..<document.pageCount {
-        guard let page = document.page(at: pageIndex) else { continue }
-        for annotation in page.annotations {
-            guard annotation.widgetFieldType == .text,
-                  let name = annotation.fieldName else { continue }
-            fields.append((name, annotation.widgetStringValue ?? ""))
+import PDFKit
+
+func textFieldValues(in form: PDFDocument) -> [String: String] {
+    var values: [String: String] = [:]
+    for index in 0..<form.pageCount {
+        guard let page = form.page(at: index) else { continue }
+        for field in page.annotations where field.widgetFieldType == .text {
+            if let name = field.fieldName {
+                values[name] = field.widgetStringValue ?? ""
+            }
         }
     }
-    return fields
+    return values
 }
-```
 
-### Filling Text Fields
+func allFields(in form: PDFDocument) -> [PDFAnnotation] {
+    (0..<form.pageCount).compactMap { form.page(at: $0) }.flatMap(\.annotations)
+}
 
-```swift
-func fillTextField(in document: PDFDocument, fieldName: String, value: String) {
-    for pageIndex in 0..<document.pageCount {
-        guard let page = document.page(at: pageIndex) else { continue }
-        for annotation in page.annotations {
-            if annotation.widgetFieldType == .text,
-               annotation.fieldName == fieldName {
-                annotation.widgetStringValue = value
-                return
-            }
-        }
+func setText(_ value: String, field name: String, in form: PDFDocument) {
+    for field in allFields(in: form) where field.widgetFieldType == .text && field.fieldName == name {
+        field.widgetStringValue = value
     }
 }
-```
-
-### Filling Checkbox Fields
 
-```swift
-func setCheckbox(in document: PDFDocument, fieldName: String, checked: Bool) {
-    for pageIndex in 0..<document.pageCount {
-        guard let page = document.page(at: pageIndex) else { continue }
-        for annotation in page.annotations {
-            if annotation.widgetFieldType == .button,
-               annotation.widgetControlType == .checkBoxControl,
-               annotation.fieldName == fieldName {
-                annotation.buttonWidgetState = checked ? .onState : .offState
-                return
-            }
-        }
+func setCheckbox(_ name: String, checked: Bool, in form: PDFDocument) {
+    for field in allFields(in: form)
+    where field.widgetFieldType == .button
+        && field.widgetControlType == .checkBoxControl
+        && field.fieldName == name {
+        field.buttonWidgetState = checked ? .onState : .offState
     }
 }
 ```
 
-### Creating Widget Annotations
+### Creating fields
 
 ```swift
-// Text field widget
-func createTextField(
-    bounds: CGRect,
-    fieldName: String,
-    placeholder: String = ""
-) -> PDFAnnotation {
-    let widget = PDFAnnotation(bounds: bounds, forType: .widget, withProperties: nil)
-    widget.widgetFieldType = .text
-    widget.fieldName = fieldName
-    widget.widgetStringValue = placeholder
-    widget.font = UIFont.systemFont(ofSize: 12)
-    widget.backgroundColor = UIColor.systemGray6
-    return widget
-}
-
-// Checkbox widget
-func createCheckbox(bounds: CGRect, fieldName: String) -> PDFAnnotation {
-    let widget = PDFAnnotation(bounds: bounds, forType: .widget, withProperties: nil)
-    widget.widgetFieldType = .button
-    widget.widgetControlType = .checkBoxControl
-    widget.fieldName = fieldName
-    widget.buttonWidgetState = .offState
-    return widget
-}
+import PDFKit
+import UIKit
+
+func registrationForm() -> PDFDocument {
+    let sheet = PDFPage()
+    sheet.setBounds(CGRect(x: 0, y: 0, width: 612, height: 792), for: .mediaBox)
+
+    let fullName = PDFAnnotation(bounds: CGRect(x: 72, y: 690, width: 300, height: 24), forType: .widget, withProperties: nil)
+    fullName.widgetFieldType = .text
+    fullName.fieldName = "fullName"
+    fullName.widgetStringValue = ""
+    fullName.font = .systemFont(ofSize: 13)
+    fullName.backgroundColor = UIColor.systemGray6
+    sheet.addAnnotation(fullName)
+
+    let newsletter = PDFAnnotation(bounds: CGRect(x: 72, y: 650, width: 18, height: 18), forType: .widget, withProperties: nil)
+    newsletter.widgetFieldType = .button
+    newsletter.widgetControlType = .checkBoxControl
+    newsletter.fieldName = "newsletter"
+    newsletter.buttonWidgetState = .offState
+    sheet.addAnnotation(newsletter)
+
+    for (offset, size) in ["S", "M", "L"].enumerated() {
+        let option = PDFAnnotation(bounds: CGRect(x: 72 + offset * 40, y: 610, width: 18, height: 18), forType: .widget, withProperties: nil)
+        option.widgetFieldType = .button
+        option.widgetControlType = .radioButtonControl
+        option.fieldName = "shirtSize"
+        option.buttonWidgetStateString = size
+        sheet.addAnnotation(option)
+    }
 
-// Radio button widget
-func createRadioButton(
-    bounds: CGRect,
-    groupName: String,
-    stateString: String
-) -> PDFAnnotation {
-    let widget = PDFAnnotation(bounds: bounds, forType: .widget, withProperties: nil)
-    widget.widgetFieldType = .button
-    widget.widgetControlType = .radioButtonControl
-    widget.fieldName = groupName
-    widget.buttonWidgetStateString = stateString
-    return widget
-}
+    let country = PDFAnnotation(bounds: CGRect(x: 72, y: 560, width: 200, height: 24), forType: .widget, withProperties: nil)
+    country.widgetFieldType = .choice
+    country.fieldName = "country"
+    country.choices = ["Canada", "Chile", "Japan"]
+    country.isListChoice = false
+    sheet.addAnnotation(country)
 
-// Choice widget (dropdown)
-func createDropdown(
-    bounds: CGRect,
-    fieldName: String,
-    options: [String]
-) -> PDFAnnotation {
-    let widget = PDFAnnotation(bounds: bounds, forType: .widget, withProperties: nil)
-    widget.widgetFieldType = .choice
-    widget.fieldName = fieldName
-    widget.choices = options
-    widget.isListChoice = false  // false = dropdown, true = list box
-    return widget
+    let form = PDFDocument()
+    form.insert(sheet, at: 0)
+    return form
 }
 ```
 
-### Building a Simple Form
+| Field | `widgetFieldType` | Extra settings |
+|---|---|---|
+| text box | `.text` | `widgetStringValue`, `font`, `backgroundColor` |
+| checkbox | `.button` | `widgetControlType = .checkBoxControl`, start at `.offState` |
+| radio button | `.button` | `.radioButtonControl`; `fieldName` is the group, `buttonWidgetStateString` the value |
+| dropdown | `.choice` | `choices`, `isListChoice = false` |
+| list box | `.choice` | `choices`, `isListChoice = true` |
 
-```swift
-func buildForm() -> PDFDocument {
-    let document = PDFDocument()
-    let page = PDFPage()
-    let pageBounds = CGRect(x: 0, y: 0, width: 612, height: 792) // Letter size
-    page.setBounds(pageBounds, for: .mediaBox)
-
-    // Name field
-    let nameField = createTextField(
-        bounds: CGRect(x: 100, y: 700, width: 200, height: 24),
-        fieldName: "name",
-        placeholder: ""
-    )
-    page.addAnnotation(nameField)
-
-    // Agree checkbox
-    let checkbox = createCheckbox(
-        bounds: CGRect(x: 100, y: 660, width: 20, height: 20),
-        fieldName: "agree"
-    )
-    page.addAnnotation(checkbox)
-
-    document.insert(page, at: 0)
-    return document
-}
-```
+A US Letter page is 612 by 792 points; set it with `setBounds(_:for: .mediaBox)`.
 
-## Creating PDFs Programmatically
+## Building PDFs in code
 
-### From Images
+### From images
 
 ```swift
-func createPDFFromImages(_ images: [UIImage]) -> PDFDocument {
-    let document = PDFDocument()
-    for (index, image) in images.enumerated() {
-        if let page = PDFPage(image: image) {
-            document.insert(page, at: index)
+import PDFKit
+import UIKit
+
+func album(from photos: [UIImage]) -> PDFDocument {
+    let book = PDFDocument()
+    for (slot, photo) in photos.enumerated() {
+        if let page = PDFPage(image: photo) {
+            book.insert(page, at: slot)
         }
     }
-    return document
+    return book
 }
-```
 
-### From Images with Options
-
-```swift
-func createPDFFromImage(
-    _ image: UIImage,
-    mediaBox: CGRect? = nil,
-    compressionQuality: CGFloat = 0.8
-) -> PDFPage? {
-    var options: [PDFPage.ImageInitializationOption: Any] = [
-        .compressionQuality: compressionQuality
-    ]
-    if let box = mediaBox {
-        options[.mediaBox] = NSValue(cgRect: box)
-    }
-    return PDFPage(image: image, options: options)
+func compactPage(from photo: UIImage) -> PDFPage? {
+    PDFPage(image: photo, options: [
+        .compressionQuality: 0.7,
+        .mediaBox: NSValue(cgRect: CGRect(x: 0, y: 0, width: 595, height: 842))
+    ])
 }
 ```
 
-### Using Core Graphics
+`PDFPage(image:)` is failable. `PDFPage(image:options:)` accepts
+`PDFPage.ImageInitializationOption` keys such as `.compressionQuality` and
+`.mediaBox`.
 
-For full control over PDF layout, use `UIGraphicsPDFRenderer`.
+### With full layout control
 
 ```swift
-func createPDFWithCoreGraphics() -> Data {
-    let pageRect = CGRect(x: 0, y: 0, width: 612, height: 792)
-    let renderer = UIGraphicsPDFRenderer(bounds: pageRect)
-
-    return renderer.pdfData { context in
-        context.beginPage()
-
-        // Draw title
-        let title = "Document Title"
-        let titleAttributes: [NSAttributedString.Key: Any] = [
-            .font: UIFont.boldSystemFont(ofSize: 24),
-            .foregroundColor: UIColor.black
-        ]
-        title.draw(at: CGPoint(x: 50, y: 50), withAttributes: titleAttributes)
-
-        // Draw body text
-        let body = "This is the body text of the PDF document."
-        let bodyAttributes: [NSAttributedString.Key: Any] = [
-            .font: UIFont.systemFont(ofSize: 12),
-            .foregroundColor: UIColor.darkGray
-        ]
-        let bodyRect = CGRect(x: 50, y: 100, width: 512, height: 600)
-        body.draw(in: bodyRect, withAttributes: bodyAttributes)
-
-        // Draw a line
-        context.cgContext.setStrokeColor(UIColor.gray.cgColor)
-        context.cgContext.setLineWidth(1)
-        context.cgContext.move(to: CGPoint(x: 50, y: 90))
-        context.cgContext.addLine(to: CGPoint(x: 562, y: 90))
-        context.cgContext.strokePath()
+import PDFKit
+import UIKit
+
+func receiptPDF(lines: [String]) -> PDFDocument? {
+    let paper = CGRect(x: 0, y: 0, width: 420, height: 595)
+    let bytes = UIGraphicsPDFRenderer(bounds: paper).pdfData { ctx in
+        ctx.beginPage()
+        let style: [NSAttributedString.Key: Any] = [.font: UIFont.monospacedSystemFont(ofSize: 12, weight: .regular)]
+        for (row, text) in lines.enumerated() {
+            text.draw(at: CGPoint(x: 32, y: 40 + CGFloat(row) * 18), withAttributes: style)
+        }
+        let rule = ctx.cgContext
+        rule.move(to: CGPoint(x: 32, y: 30))
+        rule.addLine(to: CGPoint(x: paper.width - 32, y: 30))
+        rule.strokePath()
     }
+    return PDFDocument(data: bytes)
 }
 ```
 
-### Loading Core Graphics PDF into PDFDocument
-
-```swift
-let pdfData = createPDFWithCoreGraphics()
-let document = PDFDocument(data: pdfData)
-```
+`UIGraphicsPDFRenderer(bounds:)` plus `pdfData { $0.beginPage() ... }` gives a
+normal UIKit drawing context; load the `Data` back with `PDFDocument(data:)`.
 
 ## Watermarks
 
-Add watermarks by subclassing `PDFPage` and overriding `draw(with:to:)`.
-
-### Text Watermark
+Subclass `PDFPage`, override `draw(with:to:)`, and call `super` first so the
+original content is underneath.
 
 ```swift
-class WatermarkedPage: PDFPage {
-    var watermarkText: String = "CONFIDENTIAL"
+import PDFKit
+import UIKit
 
+final class ConfidentialPage: PDFPage {
     override func draw(with box: PDFDisplayBox, to context: CGContext) {
         super.draw(with: box, to: context)
-
+        let area = bounds(for: box)
         UIGraphicsPushContext(context)
         context.saveGState()
-
-        let pageBounds = bounds(for: box)
-        let center = CGPoint(x: pageBounds.midX, y: pageBounds.midY)
-
-        // Rotate around center
-        context.translateBy(x: center.x, y: center.y)
-        context.rotate(by: -.pi / 4)  // -45 degrees
-        context.translateBy(x: -center.x, y: -center.y)
-
-        let attributes: [NSAttributedString.Key: Any] = [
-            .font: UIFont.boldSystemFont(ofSize: 72),
-            .foregroundColor: UIColor.red.withAlphaComponent(0.15)
-        ]
-
-        let textSize = watermarkText.size(withAttributes: attributes)
-        let textOrigin = CGPoint(
-            x: center.x - textSize.width / 2,
-            y: center.y - textSize.height / 2
-        )
-        watermarkText.draw(at: textOrigin, withAttributes: attributes)
-
+        context.translateBy(x: area.midX, y: area.midY)
+        context.rotate(by: -.pi / 4)
+        let stamp = NSAttributedString(string: "CONFIDENTIAL", attributes: [
+            .font: UIFont.systemFont(ofSize: 60, weight: .heavy),
+            .foregroundColor: UIColor.systemRed.withAlphaComponent(0.15)
+        ])
+        let size = stamp.size()
+        stamp.draw(at: CGPoint(x: -size.width / 2, y: -size.height / 2))
         context.restoreGState()
         UIGraphicsPopContext()
     }
 }
-```
-
-### Applying Watermarks via Document Delegate
-
-```swift
-class WatermarkDelegate: NSObject, PDFDocumentDelegate {
-    func classForPage() -> AnyClass {
-        WatermarkedPage.self
-    }
-}
-
-// Usage
-let delegate = WatermarkDelegate()
-document.delegate = delegate
-pdfView.document = document
-```
-
-### Image Watermark
 
-```swift
-class ImageWatermarkedPage: PDFPage {
-    var watermarkImage: UIImage?
+final class LogoPage: PDFPage {
+    static let logo = UIImage(systemName: "seal")?.cgImage
 
     override func draw(with box: PDFDisplayBox, to context: CGContext) {
         super.draw(with: box, to: context)
-
-        guard let image = watermarkImage?.cgImage else { return }
-
-        let pageBounds = bounds(for: box)
-        let imageSize = CGSize(width: 200, height: 200)
-        let imageRect = CGRect(
-            x: pageBounds.midX - imageSize.width / 2,
-            y: pageBounds.midY - imageSize.height / 2,
-            width: imageSize.width,
-            height: imageSize.height
-        )
-
+        guard let mark = Self.logo else { return }
+        let area = bounds(for: box)
         context.saveGState()
         context.setAlpha(0.1)
-        context.draw(image, in: imageRect)
+        context.draw(mark, in: CGRect(x: area.midX - 100, y: area.midY - 100, width: 200, height: 200))
         context.restoreGState()
     }
 }
+
+final class WatermarkSource: NSObject, PDFDocumentDelegate {
+    func classForPage() -> AnyClass {
+        ConfidentialPage.self
+    }
+}
 ```
 
-## Merging Documents
+The document asks its delegate which page class to instantiate through
+`classForPage()`. Set `document.delegate` before the document is handed to a
+`PDFView`, and keep the delegate object alive.
 
-### Append All Pages
+## Merging and splitting
 
 ```swift
-func mergeDocuments(_ documents: [PDFDocument]) -> PDFDocument {
+import PDFKit
+
+func combine(_ parts: [PDFDocument]) -> PDFDocument {
     let merged = PDFDocument()
-    var insertIndex = 0
-    for document in documents {
-        for pageIndex in 0..<document.pageCount {
-            guard let page = document.page(at: pageIndex) else { continue }
-            merged.insert(page, at: insertIndex)
-            insertIndex += 1
+    var next = 0
+    for part in parts {
+        for index in 0..<part.pageCount {
+            if let page = part.page(at: index) {
+                merged.insert(page, at: next)
+                next += 1
+            }
         }
     }
     return merged
 }
-```
-
-### Extract Page Range
 
-```swift
-func extractPages(
-    from document: PDFDocument,
-    range: ClosedRange<Int>
-) -> PDFDocument {
-    let extracted = PDFDocument()
-    var insertIndex = 0
-    for pageIndex in range {
-        guard pageIndex >= 0,
-              pageIndex < document.pageCount,
-              let page = document.page(at: pageIndex) else { continue }
-        extracted.insert(page, at: insertIndex)
-        insertIndex += 1
+func excerpt(_ span: ClosedRange<Int>, of source: PDFDocument) -> PDFDocument {
+    let piece = PDFDocument()
+    for index in span where index >= 0 && index < source.pageCount {
+        if let page = source.page(at: index) {
+            piece.insert(page, at: piece.pageCount)
+        }
     }
-    return extracted
+    return piece
 }
-```
 
-### Split Document
-
-```swift
-func splitDocument(_ document: PDFDocument, pagesPerChunk: Int) -> [PDFDocument] {
-    var chunks: [PDFDocument] = []
-    var chunkDoc = PDFDocument()
-    var chunkIndex = 0
-
-    for pageIndex in 0..<document.pageCount {
-        guard let page = document.page(at: pageIndex) else { continue }
-        chunkDoc.insert(page, at: chunkIndex)
-        chunkIndex += 1
-
-        if chunkIndex >= pagesPerChunk {
-            chunks.append(chunkDoc)
-            chunkDoc = PDFDocument()
-            chunkIndex = 0
+func chunks(of source: PDFDocument, size: Int) -> [PDFDocument] {
+    var result: [PDFDocument] = []
+    var current = PDFDocument()
+    for index in 0..<source.pageCount {
+        if let page = source.page(at: index) {
+            current.insert(page, at: current.pageCount)
+        }
+        if current.pageCount == size {
+            result.append(current)
+            current = PDFDocument()
         }
     }
-
-    if chunkDoc.pageCount > 0 {
-        chunks.append(chunkDoc)
-    }
-
-    return chunks
+    if current.pageCount > 0 { result.append(current) }
+    return result
 }
 ```
 
 ## Printing
 
-### Using UIPrintInteractionController
-
 ```swift
-func printPDF(document: PDFDocument, from viewController: UIViewController) {
-    guard let data = document.dataRepresentation() else { return }
-
-    let printController = UIPrintInteractionController.shared
-    let printInfo = UIPrintInfo(dictionary: nil)
-    printInfo.outputType = .general
-    printInfo.jobName = "PDF Document"
-
-    printController.printInfo = printInfo
-    printController.printingItem = data
-    printController.present(animated: true)
-}
-```
-
-### Print a Specific Page Range
+import PDFKit
+import UIKit
 
-```swift
-func printPageRange(
-    document: PDFDocument,
-    range: ClosedRange<Int>,
-    from viewController: UIViewController
-) {
-    let subset = extractPages(from: document, range: range)
-    guard let data = subset.dataRepresentation() else { return }
-
-    let printController = UIPrintInteractionController.shared
-    let printInfo = UIPrintInfo(dictionary: nil)
-    printInfo.outputType = .general
-    printController.printInfo = printInfo
-    printController.printingItem = data
-    printController.present(animated: true)
+@MainActor
+func printDocument(_ file: PDFDocument, title: String) {
+    let job = UIPrintInfo(dictionary: nil)
+    job.outputType = .general
+    job.jobName = title
+    let printer = UIPrintInteractionController.shared
+    printer.printInfo = job
+    printer.printingItem = file.dataRepresentation()
+    printer.present(animated: true)
 }
 ```
 
-## Document Outlines
+To print only some pages, build a smaller document with `excerpt` above and
+print that.
 
-`PDFOutline` represents the table of contents (bookmarks) of a PDF.
+## Outlines
 
-### Reading Outlines
+`PDFOutline` is the table of contents (the bookmarks sidebar in most readers).
 
 ```swift
-func printOutline(_ outline: PDFOutline, level: Int = 0) {
-    let indent = String(repeating: "  ", count: level)
-    if let label = outline.label {
-        print("\(indent)\(label)")
-    }
-    for i in 0..<outline.numberOfChildren {
-        if let child = outline.child(at: i) {
-            printOutline(child, level: level + 1)
-        }
-    }
-}
+import PDFKit
 
-// Usage
-if let root = document.outlineRoot {
-    printOutline(root)
+func titles(under node: PDFOutline, depth: Int = 0) -> [String] {
+    var found: [String] = []
+    for index in 0..<node.numberOfChildren {
+        guard let child = node.child(at: index) else { continue }
+        found.append(String(repeating: "  ", count: depth) + (child.label ?? ""))
+        found += titles(under: child, depth: depth + 1)
+    }
+    return found
 }
-```
 
-### Creating Outlines
-
-```swift
-func buildOutline(for document: PDFDocument) {
+func addChapters(_ names: [String], startPages: [Int], to file: PDFDocument) {
     let root = PDFOutline()
-
-    func destination(for pageIndex: Int) -> PDFDestination? {
-        guard pageIndex >= 0,
-              pageIndex < document.pageCount,
-              let page = document.page(at: pageIndex) else { return nil }
-        return PDFDestination(page: page, at: .zero)
+    for (slot, name) in names.enumerated() {
+        guard slot < startPages.count, let page = file.page(at: startPages[slot]) else { continue }
+        let chapter = PDFOutline()
+        chapter.label = name
+        chapter.destination = PDFDestination(page: page, at: .zero)
+        root.insertChild(chapter, at: slot)
     }
-
-    let chapter1 = PDFOutline()
-    chapter1.label = "Chapter 1"
-    chapter1.destination = destination(for: 0)
-    root.insertChild(chapter1, at: 0)
-
-    let section1_1 = PDFOutline()
-    section1_1.label = "Section 1.1"
-    section1_1.destination = destination(for: 2)
-    chapter1.insertChild(section1_1, at: 0)
-
-    let chapter2 = PDFOutline()
-    chapter2.label = "Chapter 2"
-    chapter2.destination = destination(for: 5)
-    root.insertChild(chapter2, at: 1)
-
-    document.outlineRoot = root
+    file.outlineRoot = root
 }
-```
 
-### Navigating to an Outline Entry
-
-```swift
-func goToOutlineEntry(_ outline: PDFOutline, in pdfView: PDFView) {
-    if let destination = outline.destination {
-        pdfView.go(to: destination)
-    } else if let action = outline.action {
-        pdfView.perform(action)
+@MainActor
+func open(_ entry: PDFOutline, in reader: PDFView) {
+    if let target = entry.destination {
+        reader.go(to: target)
+    } else if let action = entry.action {
+        reader.perform(action)
     }
 }
 ```
 
-## Custom Annotation Subclasses
+Start reading from `document.outlineRoot`.
 
-Override `draw(with:in:)` to render custom annotation graphics.
+## Custom annotation classes
+
+Annotations draw with `draw(with:in:)`; pages use `draw(with:to:)`. Mind the
+different label.
 
 ```swift
-class CircleStampAnnotation: PDFAnnotation {
+import PDFKit
+import UIKit
+
+final class CircledNote: PDFAnnotation {
     override func draw(with box: PDFDisplayBox, in context: CGContext) {
         super.draw(with: box, in: context)
-
         UIGraphicsPushContext(context)
-        context.saveGState()
-
-        let insetBounds = bounds.insetBy(dx: 2, dy: 2)
-        let path = UIBezierPath(ovalIn: insetBounds)
-        path.lineWidth = 3
-
-        UIColor.systemRed.setStroke()
-        path.stroke()
-
-        // Draw centered text
-        let text = "REVIEWED"
-        let attributes: [NSAttributedString.Key: Any] = [
-            .font: UIFont.boldSystemFont(ofSize: 10),
-            .foregroundColor: UIColor.systemRed
-        ]
-        let textSize = text.size(withAttributes: attributes)
-        let textOrigin = CGPoint(
-            x: bounds.midX - textSize.width / 2,
-            y: bounds.midY - textSize.height / 2
-        )
-        text.draw(at: textOrigin, withAttributes: attributes)
-
-        context.restoreGState()
+        let ring = UIBezierPath(ovalIn: bounds.insetBy(dx: 3, dy: 3))
+        ring.lineWidth = 2
+        UIColor.systemPurple.setStroke()
+        ring.stroke()
+        let tag = NSAttributedString(string: contents ?? "", attributes: [.font: UIFont.systemFont(ofSize: 10)])
+        let size = tag.size()
+        tag.draw(at: CGPoint(x: bounds.midX - size.width / 2, y: bounds.midY - size.height / 2))
         UIGraphicsPopContext()
     }
 }
-```
-
-### Registering Custom Annotations via Delegate
 
-```swift
-class AnnotationDelegate: NSObject, PDFDocumentDelegate {
+final class AnnotationFactory: NSObject, PDFDocumentDelegate {
     func `class`(forAnnotationType annotationType: String) -> AnyClass {
-        switch annotationType {
-        case "CircleStamp":
-            return CircleStampAnnotation.self
-        default:
-            return PDFAnnotation.self
-        }
+        annotationType == "Circle" ? CircledNote.self : PDFAnnotation.self
     }
 }
 ```
 
-## Custom Page Subclasses
+A document asks `class(forAnnotationType:)` which class to create for each
+annotation it reads; return `PDFAnnotation.self` for anything you do not
+customise.
+
+## Custom page classes
 
-Override `draw(with:to:)` for page-level custom drawing like headers,
-footers, or decorative borders.
+Headers, footers and borders work the same way as watermarks. Remember that
+y = 0 is the bottom edge.
 
 ```swift
-class HeaderFooterPage: PDFPage {
-    var headerText: String = ""
-    var footerText: String = ""
+import PDFKit
+import UIKit
 
+final class NumberedPage: PDFPage {
     override func draw(with box: PDFDisplayBox, to context: CGContext) {
         super.draw(with: box, to: context)
-
+        let area = bounds(for: box)
+        let small: [NSAttributedString.Key: Any] = [.font: UIFont.systemFont(ofSize: 9)]
         UIGraphicsPushContext(context)
         context.saveGState()
-
-        let pageBounds = bounds(for: box)
-        let attributes: [NSAttributedString.Key: Any] = [
-            .font: UIFont.systemFont(ofSize: 10),
-            .foregroundColor: UIColor.gray
-        ]
-
-        // Header (top of page in PDF coordinates)
-        if !headerText.isEmpty {
-            let headerSize = headerText.size(withAttributes: attributes)
-            let headerOrigin = CGPoint(
-                x: pageBounds.midX - headerSize.width / 2,
-                y: pageBounds.maxY - 30
-            )
-            headerText.draw(at: headerOrigin, withAttributes: attributes)
-        }
-
-        // Footer (bottom of page in PDF coordinates)
-        if !footerText.isEmpty {
-            let footerSize = footerText.size(withAttributes: attributes)
-            let footerOrigin = CGPoint(
-                x: pageBounds.midX - footerSize.width / 2,
-                y: 20
-            )
-            footerText.draw(at: footerOrigin, withAttributes: attributes)
-        }
-
+        context.translateBy(x: 0, y: area.height)
+        context.scaleBy(x: 1, y: -1)
+        ("Quarterly report" as NSString).draw(at: CGPoint(x: 40, y: 18), withAttributes: small)
+        ("Page \(pageRef?.pageNumber ?? 0)" as NSString).draw(at: CGPoint(x: 40, y: area.height - 30), withAttributes: small)
         context.restoreGState()
         UIGraphicsPopContext()
     }
 }
 ```
 
-## Page Overlay Lifecycle
+In unflipped PDF space the header sits near `area.maxY - 30` and the footer
+near y = 20. The example flips the context so UIKit text draws upright, which
+turns those into a small y for the header and `height - 30` for the footer.
 
-`PDFView.pageOverlayViewProvider` is weak. Store the provider on a view
-controller, SwiftUI coordinator, or another object that outlives the `PDFView`.
+## Overlay lifecycle
 
-PDFKit requests overlay views for pages it is preparing or displaying, then
-calls the lifecycle hooks as pages enter and leave the visible range. Keep
-overlay state outside the view so scrolling does not discard edits.
+- Keep the `PDFPageOverlayViewProvider` on something that outlives the
+  `PDFView`: a view controller, a SwiftUI coordinator or a model object.
+- PDFKit asks for overlays as pages are prepared for display and tells the
+  provider when they leave the visible range. Keep editing state outside the
+  views so scrolling away and back does not lose it.
+- `pdfView(_:willEndDisplayingOverlayView:for:)` is where to capture what the
+  user did, for example into a dictionary keyed by `PDFPage`.
+- Overlay views are UIKit (or AppKit) views, not PDF content. `write(to:)` and
+  `dataRepresentation()` ignore them.
+- Before saving, turn overlay content into real PDF annotations, annotations
+  with custom appearance streams, or drawn page content. Add
+  `.burnInAnnotationsOption` when the result must not be editable.
 
 ```swift
-class PageOverlayProvider: NSObject, PDFPageOverlayViewProvider {
-    private var pageNotes: [PDFPage: String] = [:]
+import PDFKit
+import UIKit
+
+@MainActor
+final class SignatureOverlays: NSObject, @preconcurrency PDFPageOverlayViewProvider {
+    private var savedStrokes: [PDFPage: [CGPoint]] = [:]
 
     func pdfView(_ view: PDFView, overlayViewFor page: PDFPage) -> UIView? {
-        let textView = UITextView()
-        textView.text = pageNotes[page] ?? ""
-        textView.backgroundColor = .clear
-        return textView
+        let pad = StrokePad()
+        pad.points = savedStrokes[page] ?? []
+        return pad
     }
 
-    func pdfView(
-        _ view: PDFView,
-        willEndDisplayingOverlayView overlayView: UIView,
-        for page: PDFPage
-    ) {
-        if let textView = overlayView as? UITextView {
-            pageNotes[page] = textView.text
+    func pdfView(_ pdfView: PDFView, willEndDisplayingOverlayView overlayView: UIView, for page: PDFPage) {
+        if let pad = overlayView as? StrokePad {
+            savedStrokes[page] = pad.points
         }
     }
 }
-```
 
-Overlay views are UIKit/AppKit views, not PDF content. Before calling
-`write(to:)` or `dataRepresentation()`, convert overlay data into PDF
-annotations, custom annotation appearance streams, or rendered page content.
-Use `.burnInAnnotationsOption` when saved annotations should become permanent
-page content.
-
-## Rendering Pages to Images
+final class StrokePad: UIView {
+    var points: [CGPoint] = []
+}
+```
 
-### Single Page
+## Rendering a page to an image
 
 ```swift
-func renderPage(_ page: PDFPage, scale: CGFloat = 2.0) -> UIImage? {
-    let pageBounds = page.bounds(for: .mediaBox)
-    let size = CGSize(
-        width: pageBounds.width * scale,
-        height: pageBounds.height * scale
-    )
-
-    let renderer = UIGraphicsImageRenderer(size: size)
-    return renderer.image { ctx in
-        ctx.cgContext.scaleBy(x: scale, y: scale)
-
-        // White background
+import PDFKit
+import UIKit
+
+func snapshot(of page: PDFPage, scale: CGFloat = 2.0) -> UIImage {
+    let box = page.bounds(for: .mediaBox)
+    let size = CGSize(width: box.width * scale, height: box.height * scale)
+    return UIGraphicsImageRenderer(size: size).image { ctx in
         UIColor.white.setFill()
         ctx.fill(CGRect(origin: .zero, size: size))
-
-        // PDFPage draw uses bottom-left origin; flip the context
-        ctx.cgContext.translateBy(x: 0, y: pageBounds.height)
-        ctx.cgContext.scaleBy(x: 1, y: -1)
-
-        page.draw(with: .mediaBox, to: ctx.cgContext)
+        let cg = ctx.cgContext
+        cg.translateBy(x: 0, y: size.height)
+        cg.scaleBy(x: scale, y: -scale)
+        page.draw(with: .mediaBox, to: cg)
     }
 }
 ```
 
-### Thumbnail Shortcut
+`draw(with:to:)` assumes a bottom-left origin, so the context is flipped first.
+`thumbnail(of:for:)` does that flip for you and is the simpler choice when a
+preview-sized image is enough.
 
-The simpler `thumbnail(of:for:)` method handles coordinate flipping
-internally.
+## Rotation and cropping
 
 ```swift
-let thumbnail = page.thumbnail(of: CGSize(width: 200, height: 260), for: .mediaBox)
-```
-
-## Page Rotation and Cropping
-
-### Rotation
+import PDFKit
 
-```swift
-// Rotate a page (must be a multiple of 90)
-page.rotation = 90   // 0, 90, 180, or 270
+func straighten(_ page: PDFPage) {
+    page.rotation = (page.rotation + 90) % 360
+    let media = page.bounds(for: .mediaBox)
+    page.setBounds(media.insetBy(dx: 36, dy: 36), for: .cropBox)
+}
 ```
 
-### Cropping
+`rotation` accepts only 0, 90, 180 or 270. `setBounds(_:for: .cropBox)` trims
+the visible area.
 
-Set the crop box to display only a portion of the page.
+## Burning in annotations
 
 ```swift
-let pageBounds = page.bounds(for: .mediaBox)
-let cropRect = pageBounds.insetBy(dx: 50, dy: 50)
-page.setBounds(cropRect, for: .cropBox)
-```
-
-## Burning In Annotations
-
-Write annotations permanently into the PDF content so they cannot be removed.
+import PDFKit
 
-```swift
-func burnInAnnotations(_ document: PDFDocument, to url: URL) -> Bool {
-    document.write(to: url, withOptions: [
-        .burnInAnnotationsOption: true
-    ])
+func flatten(_ file: PDFDocument, to url: URL) -> Bool {
+    file.write(to: url, withOptions: [.burnInAnnotationsOption: true])
 }
 ```
 
-After burning in, annotations become part of the page content and are no
-longer editable or removable as separate objects.
-
-## Document Permissions
+The option is iOS 16+ and the call returns `Bool`. Afterwards the marks are part of the page drawing and
+can no longer be selected, edited or removed as annotations.
 
-Check what operations the PDF allows.
+## Permissions
 
 ```swift
-func checkPermissions(_ document: PDFDocument) {
-    let status = document.permissionsStatus  // .none, .user, .owner
-
-    let canCopy = document.allowsCopying
-    let canPrint = document.allowsPrinting
-    let canComment = document.allowsCommenting
-    let canFillForms = document.allowsFormFieldEntry
-    let canAssemble = document.allowsDocumentAssembly
-    let canModify = document.allowsDocumentChanges
-    let canAccessibility = document.allowsContentAccessibility
-}
-```
-
-### Writing with Access Permissions
+import PDFKit
 
-```swift
-func saveWithRestrictions(_ document: PDFDocument, to url: URL) {
-    let permissions: PDFAccessPermissions = [
-        .allowsLowQualityPrinting,
-        .allowsContentCopying,
-        .allowsCommenting
-    ]
-    document.write(to: url, withOptions: [
-        .ownerPasswordOption: "ownerSecret",
-        .userPasswordOption: "userPass",
-        .accessPermissionsOption: permissions.rawValue
+func describeAccess(_ file: PDFDocument) -> [String] {
+    var notes: [String] = []
+    switch file.permissionsStatus {
+    case .none: notes.append("opened without a password")
+    case .user: notes.append("opened with the user password")
+    case .owner: notes.append("opened with the owner password")
+    @unknown default: break
+    }
+    if !file.allowsCopying { notes.append("copying blocked") }
+    if !file.allowsPrinting { notes.append("printing blocked") }
+    if !file.allowsCommenting { notes.append("comments blocked") }
+    if !file.allowsFormFieldEntry { notes.append("form entry blocked") }
+    if !file.allowsDocumentAssembly { notes.append("page assembly blocked") }
+    if !file.allowsDocumentChanges { notes.append("edits blocked") }
+    if !file.allowsContentAccessibility { notes.append("accessibility extraction blocked") }
+    return notes
+}
+
+func lockDown(_ file: PDFDocument, to url: URL) -> Bool {
+    let allowed = PDFAccessPermissions.allowsLowQualityPrinting.rawValue
+        | PDFAccessPermissions.allowsCommenting.rawValue
+    return file.write(to: url, withOptions: [
+        .ownerPasswordOption: "archive-owner",
+        .userPasswordOption: "",
+        .accessPermissionsOption: allowed
     ])
 }
 ```
 
-## Coordinator Pattern for PDFView
+`permissionsStatus` is `.none`, `.user` or `.owner`. To restrict a saved file,
+pass `PDFAccessPermissions` flags (for example `.allowsLowQualityPrinting`,
+`.allowsContentCopying`, `.allowsCommenting`) as the value of
+`.accessPermissionsOption` (iOS 15+), together with the password options.
+In Swift `PDFAccessPermissions` imports as a plain enum, not an `OptionSet`,
+so combine flags by OR-ing their `rawValue`s. Some flags imply others:
+content copying includes accessibility extraction, commenting includes form
+entry, and document changes include both.
 
-A reusable coordinator that handles delegate callbacks, notifications, and
-annotation hit detection for a SwiftUI-wrapped PDFView.
+## Coordinator-based SwiftUI wrapper
 
 ```swift
-import SwiftUI
 import PDFKit
+import SwiftUI
+import UIKit
 
-struct ManagedPDFView: UIViewRepresentable {
+struct TrackedPDFView: UIViewRepresentable {
     let document: PDFDocument
-    @Binding var currentPageIndex: Int
-    var onAnnotationTapped: ((PDFAnnotation) -> Void)?
+    @Binding var pageIndex: Int
+    var onAnnotationTap: (PDFAnnotation) -> Void = { _ in }
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(owner: self)
+    }
 
     func makeUIView(context: Context) -> PDFView {
-        let pdfView = PDFView()
-        pdfView.autoScales = true
-        pdfView.displayMode = .singlePageContinuous
-        pdfView.document = document
-        pdfView.delegate = context.coordinator
-        context.coordinator.attach(to: pdfView)
-        return pdfView
+        let reader = PDFView()
+        reader.autoScales = true
+        reader.document = document
+        reader.delegate = context.coordinator
+        context.coordinator.attach(to: reader)
+        return reader
     }
 
-    func updateUIView(_ pdfView: PDFView, context: Context) {
-        if pdfView.document !== document {
-            pdfView.document = document
+    func updateUIView(_ reader: PDFView, context: Context) {
+        context.coordinator.owner = self
+        if reader.document !== document {
+            reader.document = document
         }
-        if currentPageIndex >= 0,
-           currentPageIndex < document.pageCount,
-           let page = document.page(at: currentPageIndex),
-           pdfView.currentPage !== page {
-            pdfView.go(to: page)
+        guard pageIndex >= 0, pageIndex < document.pageCount,
+              let wanted = document.page(at: pageIndex) else { return }
+        if reader.currentPage !== wanted {
+            reader.go(to: wanted)
         }
     }
 
-    static func dismantleUIView(_ uiView: PDFView, coordinator: Coordinator) {
+    static func dismantleUIView(_ reader: PDFView, coordinator: Coordinator) {
         NotificationCenter.default.removeObserver(coordinator)
     }
 
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
+    @MainActor
+    final class Coordinator: NSObject, @preconcurrency PDFViewDelegate {
+        var owner: TrackedPDFView
 
-    class Coordinator: NSObject, PDFViewDelegate {
-        let parent: ManagedPDFView
-
-        init(_ parent: ManagedPDFView) {
-            self.parent = parent
-            super.init()
+        init(owner: TrackedPDFView) {
+            self.owner = owner
         }
 
-        func attach(to pdfView: PDFView) {
+        deinit {
             NotificationCenter.default.removeObserver(self)
-            NotificationCenter.default.addObserver(
-                self,
-                selector: #selector(pageChanged),
-                name: .PDFViewPageChanged,
-                object: pdfView
-            )
-            NotificationCenter.default.addObserver(
-                self,
-                selector: #selector(annotationHit),
-                name: .PDFViewAnnotationHit,
-                object: pdfView
-            )
         }
 
-        deinit {
-            NotificationCenter.default.removeObserver(self)
+        func attach(to reader: PDFView) {
+            let center = NotificationCenter.default
+            center.removeObserver(self)
+            center.addObserver(self, selector: #selector(pageDidChange(_:)), name: .PDFViewPageChanged, object: reader)
+            center.addObserver(self, selector: #selector(annotationWasHit(_:)), name: .PDFViewAnnotationHit, object: reader)
         }
 
-        @objc func pageChanged(_ notification: Notification) {
-            guard let pdfView = notification.object as? PDFView,
-                  let page = pdfView.currentPage,
-                  let doc = pdfView.document else { return }
-            let index = doc.index(for: page)
-            if parent.currentPageIndex != index {
-                parent.currentPageIndex = index
+        @objc private func pageDidChange(_ note: Notification) {
+            guard let reader = note.object as? PDFView,
+                  let page = reader.currentPage,
+                  let file = reader.document else { return }
+            let index = file.index(for: page)
+            if index != owner.pageIndex {
+                owner.pageIndex = index
             }
         }
 
-        @objc func annotationHit(_ notification: Notification) {
-            guard let annotation = notification.userInfo?["PDFAnnotationHit"] as? PDFAnnotation
-            else { return }
-            parent.onAnnotationTapped?(annotation)
+        @objc private func annotationWasHit(_ note: Notification) {
+            if let tapped = note.userInfo?["PDFAnnotationHit"] as? PDFAnnotation {
+                owner.onAnnotationTap(tapped)
+            }
         }
 
         func pdfViewWillClick(onLink sender: PDFView, with url: URL) {
@@ -842,3 +620,14 @@ struct ManagedPDFView: UIViewRepresentable {
     }
 }
 ```
+
+- `updateUIView` swaps the document only when `!==` says it changed, and
+  navigates only when the requested index is valid and differs from
+  `currentPage`.
+- The page handler writes to the binding only on a real change, which avoids
+  an update loop between SwiftUI and the view.
+- `dismantleUIView(_:coordinator:)` and the coordinator's `deinit` both remove
+  the notification observers; `attach` clears old ones before adding.
+- `.PDFViewAnnotationHit` carries the tapped annotation under the
+  `"PDFAnnotationHit"` user-info key.
+- `pdfViewWillClick(onLink:with:)` lets the app decide what a link tap does.