@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/pdfkit/SKILL.md

@@ -1,500 +1,468 @@
 ---
 name: pdfkit
-description: "Display and manipulate PDF documents using PDFKit. Use when embedding PDFView to show PDF files, creating or modifying PDFDocument instances, adding annotations (highlights, notes, signature widgets), extracting text with PDFSelection, navigating pages, generating thumbnails, filling PDF forms, or wrapping PDFView in SwiftUI."
+description: "PDFKit on iOS: PDFView display and SwiftUI wrapping, creating and editing PDFDocument and PDFPage, highlight, note, signature and form annotations, PDFSelection search and text extraction, page navigation, thumbnails, form filling, encrypted saving. Use when an app displays, searches, annotates, fills, builds or saves PDFs."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# PDFKit
 
-Display, navigate, search, annotate, and manipulate PDF documents with `PDFView`, `PDFDocument`, `PDFPage`, `PDFAnnotation`, and `PDFSelection`. Targets Swift 6.3 / iOS 26+.
+# PDFKit
 
-## Contents
+PDFKit renders, searches and edits PDF files. Most work touches five types:
+`PDFView` (the on-screen viewer), `PDFDocument` (the file), `PDFPage` (one
+page), `PDFAnnotation` (marks and form fields on a page) and `PDFSelection`
+(a run of text). Examples target Swift 6.3 and iOS 26.
 
-- [Setup](#setup)
-- [Displaying PDFs](#displaying-pdfs)
-- [Loading Documents](#loading-documents)
-- [Page Navigation](#page-navigation)
-- [Text Search and Selection](#text-search-and-selection)
-- [Annotations](#annotations)
-- [Thumbnails](#thumbnails)
-- [SwiftUI Integration](#swiftui-integration)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Freehand drawing tools are not PDFKit work: use PencilKit or PaperKit.
 
 ## Setup
 
-PDFKit requires no entitlements or Info.plist entries.
+No entitlement and no Info.plist key is needed.
 
 ```swift
 import PDFKit
 ```
 
-**Platform availability:** iOS 11+, iPadOS 11+, Mac Catalyst 13.1+, macOS 10.4+, tvOS 11+, visionOS 1.0+.
+| Platform | Minimum |
+|---|---|
+| iOS, iPadOS | 11 |
+| Mac Catalyst | 13.1 |
+| macOS | 10.4 |
+| tvOS | 11 |
+| visionOS | 1.0 |
 
-## Displaying PDFs
+## Showing a PDF
 
-`PDFView` is a `UIView` subclass that renders PDF content, handles zoom,
-scroll, text selection, and page navigation out of the box.
+`PDFView` is a `UIView` subclass. Out of the box it zooms, scrolls, selects text
+and pages through the document.
 
 ```swift
 import PDFKit
 import UIKit
 
-class PDFViewController: UIViewController {
-    let pdfView = PDFView()
+final class ManualViewController: UIViewController {
+    private let reader = PDFView()
 
     override func viewDidLoad() {
         super.viewDidLoad()
-        pdfView.frame = view.bounds
-        pdfView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        view.addSubview(pdfView)
-
-        pdfView.autoScales = true
-        pdfView.displayMode = .singlePageContinuous
-        pdfView.displayDirection = .vertical
-
-        if let url = Bundle.main.url(forResource: "sample", withExtension: "pdf") {
-            pdfView.document = PDFDocument(url: url)
+        reader.frame = view.bounds
+        reader.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        reader.autoScales = true
+        reader.displayMode = .singlePageContinuous
+        reader.displayDirection = .vertical
+        view.addSubview(reader)
+
+        if let url = Bundle.main.url(forResource: "assembly-guide", withExtension: "pdf"),
+           let file = PDFDocument(url: url) {
+            reader.document = file
         }
     }
 }
 ```
 
-### Display Modes
+### Display modes
 
-| Mode | Behavior |
+| Mode | Layout |
 |---|---|
-| `.singlePage` | One page at a time |
-| `.singlePageContinuous` | Pages stacked vertically, scrollable |
-| `.twoUp` | Two pages side by side |
-| `.twoUpContinuous` | Two-up with continuous scrolling |
+| `.singlePage` | one page on screen at a time |
+| `.singlePageContinuous` | one column of pages, scrolling |
+| `.twoUp` | facing pages side by side |
+| `.twoUpContinuous` | facing pages, scrolling |
 
-### Scaling and Appearance
+### Scale and look
 
 ```swift
-pdfView.autoScales = true
-pdfView.minScaleFactor = pdfView.scaleFactorForSizeToFit
-pdfView.maxScaleFactor = 4.0
+import PDFKit
 
-pdfView.displaysPageBreaks = true
-pdfView.pageShadowsEnabled = true
-pdfView.interpolationQuality = .high
+@MainActor
+func tune(_ reader: PDFView) {
+    reader.autoScales = true
+    reader.minScaleFactor = reader.scaleFactorForSizeToFit
+    reader.maxScaleFactor = 5.0
+    reader.displaysPageBreaks = true
+    reader.pageShadowsEnabled = false
+    reader.interpolationQuality = .high
+}
 ```
 
-## Loading Documents
+## Loading documents
 
-`PDFDocument` loads from a URL, `Data`, or can be created empty.
+There are three initializers: `PDFDocument(url:)`, `PDFDocument(data:)` and
+the empty `PDFDocument()`. The first two are failable.
 
-```swift
-let fileDoc = PDFDocument(url: fileURL)
-let dataDoc = PDFDocument(data: pdfData)
-let emptyDoc = PDFDocument()
-```
-
-### Password-Protected PDFs
+### Locked files
 
 ```swift
-guard let document = PDFDocument(url: url) else { return }
-if document.isLocked {
-    if !document.unlock(withPassword: userPassword) {
-        // Show password prompt
-    }
+import PDFKit
+
+func open(_ file: PDFDocument, passcode: String) -> Bool {
+    guard file.isLocked else { return true }
+    return file.unlock(withPassword: passcode)
 }
 ```
 
-### Saving and Page Manipulation
+If `unlock(withPassword:)` returns `false`, ask the user for the password again.
+
+### Saving and rearranging pages
 
 ```swift
-document.write(to: outputURL)
-document.write(to: outputURL, withOptions: [
-    .ownerPasswordOption: "ownerPass", .userPasswordOption: "userPass"
-])
-let data = document.dataRepresentation()
-
-// Pages are zero-based. Validate indices; out-of-range calls raise exceptions.
-let count = document.pageCount
-document.insert(PDFPage(), at: count)
-if document.pageCount > 2 {
-    document.removePage(at: 2)
+import PDFKit
+
+func export(_ file: PDFDocument, to url: URL, ownerKey: String, readerKey: String) -> Bool {
+    file.write(to: url, withOptions: [
+        .ownerPasswordOption: ownerKey,
+        .userPasswordOption: readerKey
+    ])
 }
-if document.pageCount > 3 {
-    document.exchangePage(at: 0, withPageAt: 3)
+
+func reorder(_ file: PDFDocument) {
+    let blank = PDFPage()
+    file.insert(blank, at: file.pageCount)
+    if file.pageCount > 2 {
+        file.exchangePage(at: 0, withPageAt: 2)
+    }
+    if file.pageCount > 1 {
+        file.removePage(at: 1)
+    }
 }
 ```
 
-## Page Navigation
-
-`PDFView` provides built-in navigation with history tracking.
-
-```swift
-// Go to a specific page
-let pageIndex = 5
-if let document = pdfView.document,
-   pageIndex >= 0,
-   pageIndex < document.pageCount,
-   let page = document.page(at: pageIndex) {
-    pdfView.go(to: page)
-}
+- `write(to:)` saves as is; `write(to:withOptions:)` with
+  `.ownerPasswordOption` and `.userPasswordOption` encrypts.
+- `dataRepresentation()` returns `Data?` for upload or sharing.
+- Page indices start at 0. Inserting at `pageCount` appends.
+- An index outside `0..<pageCount` raises an Objective-C exception rather than
+  returning `nil`, so check it before `page(at:)`, `insert(_:at:)`,
+  `removePage(at:)` or `exchangePage(at:withPageAt:)`.
 
-// Sequential navigation
-pdfView.goToNextPage(nil)
-pdfView.goToPreviousPage(nil)
-pdfView.goToFirstPage(nil)
-pdfView.goToLastPage(nil)
+## Navigating
 
-// Check navigation state
-if pdfView.canGoToNextPage { /* ... */ }
+`PDFView` keeps its own history of where the user has been.
 
-// History navigation
-if pdfView.canGoBack { pdfView.goBack(nil) }
+```swift
+import PDFKit
 
-// Go to a specific point on the current page
-if let page = pdfView.currentPage {
-    let destination = PDFDestination(page: page, at: CGPoint(x: 0, y: 500))
-    pdfView.go(to: destination)
+@MainActor
+func show(pageNumber index: Int, in reader: PDFView) {
+    guard let file = reader.document, index >= 0, index < file.pageCount,
+          let target = file.page(at: index) else { return }
+    reader.go(to: target)
 }
-```
 
-### Observing Page Changes
+@MainActor
+func stepThrough(_ reader: PDFView) {
+    if reader.canGoToNextPage { reader.goToNextPage(nil) }
+    reader.goToPreviousPage(nil)
+    reader.goToFirstPage(nil)
+    reader.goToLastPage(nil)
+    if reader.canGoBack { reader.goBack(nil) }
+}
 
-```swift
-NotificationCenter.default.addObserver(
-    self, selector: #selector(pageChanged),
-    name: .PDFViewPageChanged, object: pdfView
-)
-
-@objc func pageChanged(_ notification: Notification) {
-    guard let page = pdfView.currentPage,
-          let doc = pdfView.document else { return }
-    let index = doc.index(for: page)
-    pageLabel.text = "Page \(index + 1) of \(doc.pageCount)"
+@MainActor
+func jump(to point: CGPoint, on page: PDFPage, in reader: PDFView) {
+    reader.go(to: PDFDestination(page: page, at: point))
+    _ = reader.currentPage
 }
 ```
 
-## Text Search and Selection
-
-### Synchronous Search
+### Tracking the current page
 
 ```swift
-let results: [PDFSelection] = document.findString(
-    "search term", withOptions: [.caseInsensitive]
-)
+import PDFKit
+
+@MainActor
+func watchPages(of reader: PDFView, update: @escaping @MainActor @Sendable (String) -> Void) -> NSObjectProtocol {
+    NotificationCenter.default.addObserver(forName: .PDFViewPageChanged, object: reader, queue: .main) { _ in
+        MainActor.assumeIsolated {
+            guard let file = reader.document, let page = reader.currentPage else { return }
+            update("\(file.index(for: page) + 1) / \(file.pageCount)")
+        }
+    }
+}
 ```
 
-### Asynchronous Search
+## Search and text
 
-Use `PDFDocumentDelegate` for background searches on large documents.
-Implement `didMatchString(_:)` to receive each match and
-`documentDidEndDocumentFind(_:)` for completion.
+### Synchronous
 
-### Incremental Search and Find Interaction
+`findString(_:withOptions:)` returns every match as `[PDFSelection]`:
 
 ```swift
-// Find next match from current selection
-let next = document.findString("term", fromSelection: current, withOptions: [.caseInsensitive])
+import PDFKit
 
-// System find bar (iOS 16+)
-pdfView.isFindInteractionEnabled = true
+func matches(of term: String, in file: PDFDocument) -> [PDFSelection] {
+    file.findString(term, withOptions: [.caseInsensitive])
+}
 ```
 
-### Text Extraction
+### Asynchronous
+
+For long documents, search in the background with `beginFindString(_:withOptions:)`
+and a `PDFDocumentDelegate`. `didMatchString(_:)` is called per hit and
+`documentDidEndDocumentFind(_:)` when the pass finishes.
 
 ```swift
-let fullText = document.string                          // Entire document
-let firstPage = document.pageCount > 0 ? document.page(at: 0) : nil
-let pageText = firstPage?.string                        // Single page
-let attributed = firstPage?.attributedString            // With formatting
-
-// Region-based extraction
-if let page = firstPage {
-    let selection = page.selection(for: CGRect(x: 50, y: 50, width: 400, height: 200))
-    let text = selection?.string
-}
-```
+import PDFKit
 
-### Highlighting Search Results
+final class ContractSearch: NSObject, PDFDocumentDelegate {
+    private(set) var hits: [PDFSelection] = []
+    var onFinish: (([PDFSelection]) -> Void)?
 
-```swift
-let results = document.findString("important", withOptions: [.caseInsensitive])
-for selection in results { selection.color = .yellow }
-pdfView.highlightedSelections = results
+    func run(_ term: String, in file: PDFDocument) {
+        hits.removeAll()
+        file.delegate = self
+        file.beginFindString(term, withOptions: [.caseInsensitive])
+    }
 
-if let first = results.first {
-    pdfView.setCurrentSelection(first, animate: true)
-    pdfView.go(to: first)
+    func didMatchString(_ instance: PDFSelection) {
+        hits.append(instance)
+    }
+
+    func documentDidEndDocumentFind(_ notification: Notification) {
+        onFinish?(hits)
+    }
 }
 ```
 
-## Annotations
+### Next match and the system find bar
 
-Annotations are created with `PDFAnnotation(bounds:forType:withProperties:)`
-and added to a `PDFPage`.
+- `findString(_:fromSelection:withOptions:)` returns the first hit after a
+  given selection, which is how "Find next" works.
+- `reader.isFindInteractionEnabled = true` turns on the system find bar
+  (iOS 16+).
 
-### Highlight Annotation
+### Extracting text
 
 ```swift
-func addHighlight(to page: PDFPage, selection: PDFSelection) {
-    let highlight = PDFAnnotation(
-        bounds: selection.bounds(for: page),
-        forType: .highlight, withProperties: nil
-    )
-    highlight.color = UIColor.yellow.withAlphaComponent(0.5)
-    page.addAnnotation(highlight)
+import PDFKit
+
+func textSamples(from file: PDFDocument) -> (all: String?, first: String?, box: String?) {
+    let all = file.string
+    guard file.pageCount > 0, let first = file.page(at: 0) else { return (all, nil, nil) }
+    _ = first.attributedString
+    let box = first.selection(for: CGRect(x: 36, y: 700, width: 300, height: 60))?.string
+    return (all, first.string, box)
 }
 ```
 
-### Text Note Annotation
-
-```swift
-let note = PDFAnnotation(
-    bounds: CGRect(x: 100, y: 700, width: 30, height: 30),
-    forType: .text, withProperties: nil
-)
-note.contents = "This is a sticky note."
-note.color = .systemYellow
-note.iconType = .comment
-page.addAnnotation(note)
-```
+`document.string` is the whole document, `page.string` one page,
+`page.attributedString` keeps fonts and styles, and `page.selection(for:)`
+limits extraction to a rectangle. Check `pageCount > 0` before asking for
+page 0.
 
-### Free Text Annotation
+### Highlighting hits
 
 ```swift
-let freeText = PDFAnnotation(
-    bounds: CGRect(x: 50, y: 600, width: 300, height: 40),
-    forType: .freeText, withProperties: nil
-)
-freeText.contents = "Added commentary"
-freeText.font = UIFont.systemFont(ofSize: 14)
-freeText.fontColor = .darkGray
-page.addAnnotation(freeText)
+import PDFKit
+
+@MainActor
+func mark(_ hits: [PDFSelection], in reader: PDFView) {
+    for hit in hits { hit.color = .systemOrange }
+    reader.highlightedSelections = hits
+    if let firstHit = hits.first {
+        reader.setCurrentSelection(firstHit, animate: true)
+        reader.go(to: firstHit)
+    }
+}
 ```
 
-### Link Annotation
+## Annotations
+
+Create an annotation with `PDFAnnotation(bounds:forType:withProperties:)` and
+attach it with `page.addAnnotation(_:)`.
 
 ```swift
-let link = PDFAnnotation(
-    bounds: CGRect(x: 50, y: 500, width: 200, height: 20),
-    forType: .link, withProperties: nil
-)
-link.url = URL(string: "https://example.com")
-page.addAnnotation(link)
-
-// Internal page link
-link.destination = PDFDestination(page: targetPage, at: .zero)
-```
+import PDFKit
+import UIKit
 
-### Removing Annotations
+func annotate(_ page: PDFPage, hit: PDFSelection, target: PDFPage) {
+    let marker = PDFAnnotation(bounds: hit.bounds(for: page), forType: .highlight, withProperties: nil)
+    marker.color = UIColor.systemGreen.withAlphaComponent(0.5)
+    page.addAnnotation(marker)
+
+    let note = PDFAnnotation(bounds: CGRect(x: 40, y: 40, width: 24, height: 24), forType: .text, withProperties: nil)
+    note.contents = "Check this total"
+    note.color = .systemBlue
+    note.iconType = .comment
+    page.addAnnotation(note)
+
+    let label = PDFAnnotation(bounds: CGRect(x: 72, y: 120, width: 220, height: 30), forType: .freeText, withProperties: nil)
+    label.contents = "Approved"
+    label.font = .boldSystemFont(ofSize: 16)
+    label.fontColor = .systemRed
+    page.addAnnotation(label)
+
+    let web = PDFAnnotation(bounds: CGRect(x: 72, y: 170, width: 160, height: 20), forType: .link, withProperties: nil)
+    web.url = URL(string: "https://example.org/terms")
+    page.addAnnotation(web)
+
+    let internalJump = PDFAnnotation(bounds: CGRect(x: 72, y: 200, width: 160, height: 20), forType: .link, withProperties: nil)
+    internalJump.destination = PDFDestination(page: target, at: CGPoint(x: 0, y: 792))
+    page.addAnnotation(internalJump)
+}
 
-```swift
-for annotation in page.annotations {
-    page.removeAnnotation(annotation)
+func stripMarkup(from page: PDFPage) {
+    for item in page.annotations {
+        page.removeAnnotation(item)
+    }
 }
 ```
 
-Common subtypes include `.highlight`, `.underline`, `.strikeOut`, `.text`,
-`.freeText`, `.ink`, `.link`, `.line`, `.square`, `.circle`, `.stamp`, and
+Commonly used subtypes: `.highlight`, `.underline`, `.strikeOut`, `.text`,
+`.freeText`, `.ink`, `.link`, `.line`, `.square`, `.circle`, `.stamp`,
 `.widget`.
 
 ## Thumbnails
 
 ### PDFThumbnailView
 
-`PDFThumbnailView` shows a strip of page thumbnails linked to a `PDFView`.
+`PDFThumbnailView` shows a strip of page previews. Point its `pdfView` at the
+main viewer so taps navigate and the current page is highlighted.
 
 ```swift
-let thumbnailView = PDFThumbnailView()
-thumbnailView.pdfView = pdfView
-thumbnailView.thumbnailSize = CGSize(width: 60, height: 80)
-thumbnailView.layoutMode = .vertical
-thumbnailView.translatesAutoresizingMaskIntoConstraints = false
-view.addSubview(thumbnailView)
+import PDFKit
+
+@MainActor
+func makeStrip(for reader: PDFView) -> PDFThumbnailView {
+    let strip = PDFThumbnailView()
+    strip.pdfView = reader
+    strip.thumbnailSize = CGSize(width: 48, height: 64)
+    strip.layoutMode = .vertical
+    return strip
+}
 ```
 
-### Generating Thumbnails Programmatically
+### Generating images
 
 ```swift
-let thumbnail = page.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)
+import PDFKit
+import UIKit
 
-// All pages
-let thumbnails = (0..<document.pageCount).compactMap {
-    document.page(at: $0)?.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)
+func previews(of file: PDFDocument) -> [UIImage] {
+    let size = CGSize(width: 120, height: 160)
+    let cover = file.page(at: 0)?.thumbnail(of: size, for: .mediaBox)
+    _ = cover
+    return (0..<file.pageCount).compactMap { file.page(at: $0)?.thumbnail(of: size, for: .mediaBox) }
 }
 ```
 
-## SwiftUI Integration
+## SwiftUI
 
-Wrap `PDFView` in a `UIViewRepresentable` for SwiftUI. PDF-specific wrappers
-that configure `PDFView`, pages, annotations, search, thumbnails, or overlays
-belong in this skill; route only generic representable lifecycle, layout, or SwiftUI state architecture questions to SwiftUI/UIKit interop guidance.
+Wrap `PDFView` in a `UIViewRepresentable`. Wrappers that configure the viewer,
+move between pages, manage annotations, search, show thumbnails or install
+overlays belong to this skill. Only generic representable questions (lifecycle,
+sizing, state architecture) go to `swiftui-uikit-interop`.
 
 ```swift
-import SwiftUI
 import PDFKit
+import SwiftUI
 
-struct PDFKitView: UIViewRepresentable {
+struct PDFReader: UIViewRepresentable {
     let document: PDFDocument
 
     func makeUIView(context: Context) -> PDFView {
-        let pdfView = PDFView()
-        pdfView.autoScales = true
-        pdfView.displayMode = .singlePageContinuous
-        pdfView.document = document
-        return pdfView
+        let reader = PDFView()
+        reader.autoScales = true
+        reader.displayMode = .singlePageContinuous
+        reader.document = document
+        return reader
     }
 
-    func updateUIView(_ pdfView: PDFView, context: Context) {
-        if pdfView.document !== document {
-            pdfView.document = document
+    func updateUIView(_ reader: PDFView, context: Context) {
+        if reader.document !== document {
+            reader.document = document
         }
     }
 }
-```
-
-### Usage
 
-```swift
-struct DocumentScreen: View {
-    let url: URL
+struct InvoiceScreen: View {
+    let fileURL: URL
 
     var body: some View {
-        if let document = PDFDocument(url: url) {
-            PDFKitView(document: document)
+        if let file = PDFDocument(url: fileURL) {
+            PDFReader(document: file)
                 .ignoresSafeArea()
         } else {
-            ContentUnavailableView("Unable to load PDF", systemImage: "doc.questionmark")
+            ContentUnavailableView("Cannot open invoice", systemImage: "doc.questionmark")
         }
     }
 }
 ```
 
-For interactive wrappers with page tracking, annotation hit detection, and
-coordinator patterns, see [references/pdfkit-patterns.md](references/pdfkit-patterns.md).
+A version that binds the current page, reports annotation taps and uses a
+coordinator is in [the patterns reference](references/pdfkit-patterns.md#coordinator-based-swiftui-wrapper).
 
-### Page Overlays (iOS 16+)
+### Page overlays (iOS 16+)
 
-`PDFPageOverlayViewProvider` places UIKit views on top of individual pages
-for interactive controls or custom rendering beyond standard annotations.
+`PDFPageOverlayViewProvider` places a UIKit view above each page, for
+interactive controls or custom drawing. Implement
+`pdfView(_:overlayViewFor:) -> UIView?` and assign the provider to
+`pdfView.pageOverlayViewProvider`. That property is weak, so something else
+must keep the provider alive.
 
 ```swift
-class OverlayProvider: NSObject, PDFPageOverlayViewProvider {
+import PDFKit
+import UIKit
+
+@MainActor
+final class StampOverlays: NSObject, @preconcurrency PDFPageOverlayViewProvider {
     func pdfView(_ view: PDFView, overlayViewFor page: PDFPage) -> UIView? {
-        let overlay = UIView()
-        // Add custom subviews
-        return overlay
+        let badge = UILabel()
+        badge.text = "DRAFT"
+        badge.textColor = .systemRed
+        badge.sizeToFit()
+        return badge
     }
 }
 
-class PDFOverlayController: UIViewController {
-    let pdfView = PDFView()
-    private let overlayProvider = OverlayProvider()
+final class DraftViewer: UIViewController {
+    private let reader = PDFView()
+    private let overlays = StampOverlays()
 
     override func viewDidLoad() {
         super.viewDidLoad()
-        pdfView.pageOverlayViewProvider = overlayProvider
-    }
-}
-```
-
-`pageOverlayViewProvider` is weak, so keep the provider strongly owned. For overlay lifecycle and save handling, read [references/pdfkit-patterns.md](references/pdfkit-patterns.md).
-
-## Common Mistakes
-
-### DON'T: Force-unwrap PDFDocument init
-
-`PDFDocument(url:)` and `PDFDocument(data:)` are failable initializers.
-
-```swift
-// WRONG
-let document = PDFDocument(url: url)!
-
-// CORRECT
-guard let document = PDFDocument(url: url) else { return }
-```
-
-### DON'T: Forget autoScales on PDFView
-
-Without `autoScales`, the PDF renders at its native resolution.
-
-```swift
-// WRONG
-pdfView.document = document
-
-// CORRECT
-pdfView.autoScales = true
-pdfView.document = document
-```
-
-### DON'T: Ignore PDF coordinate system in annotations
-
-PDF page coordinates have origin at the bottom-left with Y increasing
-upward -- opposite of UIKit.
-
-```swift
-// WRONG: UIKit coordinates
-let bounds = CGRect(x: 50, y: 50, width: 200, height: 30)
-
-// CORRECT: PDF coordinates (origin bottom-left)
-let pageBounds = page.bounds(for: .mediaBox)
-let pdfY = pageBounds.height - 50 - 30
-let bounds = CGRect(x: 50, y: pdfY, width: 200, height: 30)
-```
-
-### DON'T: Modify annotations on a background thread
-
-PDFKit classes are not thread-safe.
-
-```swift
-// WRONG
-DispatchQueue.global().async { page.addAnnotation(annotation) }
-
-// CORRECT
-DispatchQueue.main.async { page.addAnnotation(annotation) }
-```
-
-### DON'T: Compare PDFDocument with == in UIViewRepresentable
-
-`PDFDocument` is a reference type. Use identity (`!==`).
-
-```swift
-// WRONG: Always replaces document
-func updateUIView(_ pdfView: PDFView, context: Context) {
-    pdfView.document = document
-}
-
-// CORRECT
-func updateUIView(_ pdfView: PDFView, context: Context) {
-    if pdfView.document !== document {
-        pdfView.document = document
+        reader.pageOverlayViewProvider = overlays
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] `PDFDocument` init uses optional binding, not force-unwrap
-- [ ] `pdfView.autoScales = true` set for proper initial display
-- [ ] Page indices checked against `pageCount` before access
-- [ ] `displayMode` and `displayDirection` configured to match design
-- [ ] Annotations use PDF coordinate space (origin bottom-left, Y up)
-- [ ] All PDFKit mutations happen on the main thread
-- [ ] Password-protected PDFs handled with `isLocked` / `unlock(withPassword:)`
-- [ ] SwiftUI wrapper uses `!==` identity check in `updateUIView`
-- [ ] `PDFViewPageChanged` notification observed for page tracking
-- [ ] `PDFThumbnailView.pdfView` linked to the main `PDFView`
-- [ ] Large-document search uses async `beginFindString` with delegate
-- [ ] Saved documents use `write(to:withOptions:)` when encryption needed
+## Common mistakes
+
+- **Force-unwrapping the initializers.** `PDFDocument(url:)` and
+  `PDFDocument(data:)` return `nil` for a bad file. Use `guard let`.
+- **Forgetting `autoScales`.** Without it, pages appear at their native size.
+- **Using UIKit coordinates on a page.** PDF space starts at the bottom-left and
+  y grows upward. To place something at a UIKit-style top offset, compute
+  `page.bounds(for: .mediaBox).height - topOffset - itemHeight`.
+- **Mutating from a background queue.** PDFKit classes are not thread-safe.
+  Add or change annotations on the main thread.
+- **Reassigning the document in `updateUIView`.** `PDFDocument` is a class;
+  compare with `!==` first, otherwise every SwiftUI update reloads the file.
+
+## Review checklist
+
+- [ ] `PDFDocument` is created with optional binding
+- [ ] `autoScales = true` is set
+- [ ] Every page index is checked against `pageCount`
+- [ ] `displayMode` and `displayDirection` match the design
+- [ ] Annotation rectangles are in PDF coordinate space
+- [ ] All PDFKit mutation happens on the main thread
+- [ ] Locked files go through `isLocked` and `unlock(withPassword:)`
+- [ ] The SwiftUI wrapper compares documents with `!==` in `updateUIView`
+- [ ] `PDFViewPageChanged` drives any page indicator
+- [ ] `PDFThumbnailView.pdfView` points at the main `PDFView`
+- [ ] Long documents are searched with `beginFindString` and the delegate
+- [ ] `write(to:withOptions:)` is used when the file must be encrypted
 
 ## References
 
-- Extended patterns (forms, watermarks, merging, printing, overlays, outlines, custom drawing): [references/pdfkit-patterns.md](references/pdfkit-patterns.md)
-- [PDFKit framework](https://sosumi.ai/documentation/pdfkit)
-- [PDFView](https://sosumi.ai/documentation/pdfkit/pdfview)
-- [PDFDocument](https://sosumi.ai/documentation/pdfkit/pdfdocument)
-- [PDFPage](https://sosumi.ai/documentation/pdfkit/pdfpage)
-- [PDFAnnotation](https://sosumi.ai/documentation/pdfkit/pdfannotation)
-- [PDFSelection](https://sosumi.ai/documentation/pdfkit/pdfselection)
-- [PDFThumbnailView](https://sosumi.ai/documentation/pdfkit/pdfthumbnailview)
-- [PDFPageOverlayViewProvider](https://sosumi.ai/documentation/pdfkit/pdfpageoverlayviewprovider)
-- [Adding Widgets to a PDF Document](https://sosumi.ai/documentation/pdfkit/adding-widgets-to-a-pdf-document)
-- [Adding Custom Graphics to a PDF](https://sosumi.ai/documentation/pdfkit/adding-custom-graphics-to-a-pdf)
+- [PDFKit patterns](references/pdfkit-patterns.md) - forms, building PDFs, watermarks, merging and splitting, printing, outlines, custom annotation and page classes, overlay lifecycle, rendering, rotation and crop, burn-in, permissions, coordinator wrapper
+- [PDFKit](https://developer.apple.com/documentation/pdfkit)
+- [PDFView](https://developer.apple.com/documentation/pdfkit/pdfview)
+- [PDFDocument](https://developer.apple.com/documentation/pdfkit/pdfdocument)
+- [PDFPage](https://developer.apple.com/documentation/pdfkit/pdfpage)
+- [PDFAnnotation](https://developer.apple.com/documentation/pdfkit/pdfannotation)
+- [PDFSelection](https://developer.apple.com/documentation/pdfkit/pdfselection)
+- [PDFThumbnailView](https://developer.apple.com/documentation/pdfkit/pdfthumbnailview)
+- [PDFPageOverlayViewProvider](https://developer.apple.com/documentation/pdfkit/pdfpageoverlayviewprovider)
+- [Adding widgets to a PDF document](https://developer.apple.com/documentation/pdfkit/adding-widgets-to-a-pdf-document)
+- [Adding custom graphics to a PDF](https://developer.apple.com/documentation/pdfkit/adding-custom-graphics-to-a-pdf)