@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/vision-framework/references/visionkit-scanner.md

@@ -1,536 +1,358 @@
-# VisionKit Scanner Patterns
+# VisionKit scanners
 
-Complete implementation patterns for DataScannerViewController and
-VNDocumentCameraViewController covering availability checking, configuration,
-SwiftUI integration, delegate handling, custom overlays, and camera permissions.
-All patterns target iOS 26+ with Swift 6.3 unless noted.
+Camera UI that VisionKit provides on top of Vision: the live
+`DataScannerViewController` and the paper-oriented
+`VNDocumentCameraViewController`. Summary in `../SKILL.md`.
 
 ## Contents
-- Camera Permission Setup
-- DataScannerViewController
-- Delegate Methods
-- SwiftUI Integration
-- Custom Overlay UI
-- VNDocumentCameraViewController
 
-## Camera Permission Setup
+- [Camera permission](#camera-permission)
+- [DataScannerViewController](#datascannerviewcontroller)
+- [Delegate callbacks](#delegate-callbacks)
+- [SwiftUI](#swiftui)
+- [Custom overlay](#custom-overlay)
+- [VNDocumentCameraViewController](#vndocumentcameraviewcontroller)
+- [Performance](#performance)
 
-Add the camera usage description to Info.plist before using any scanner:
+## Camera permission
 
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Camera access is needed to scan text and barcodes.</string>
-```
-
-Request permission before presenting the scanner:
+Both scanners use the camera, so Info.plist needs `NSCameraUsageDescription`
+before either is shown. Ask for access explicitly when you want to control the
+moment of the prompt:
 
 ```swift
 import AVFoundation
 
-func requestCameraAccess() async -> Bool {
+func cameraAllowed() async -> Bool {
     let status = AVCaptureDevice.authorizationStatus(for: .video)
-    switch status {
-    case .authorized:
+    if status == .authorized {
         return true
-    case .notDetermined:
-        return await AVCaptureDevice.requestAccess(for: .video)
-    case .denied, .restricted:
-        return false
-    @unknown default:
-        return false
     }
+    if status == .notDetermined {
+        let granted = await AVCaptureDevice.requestAccess(for: .video)
+        return granted
+    }
+    return false
 }
 ```
 
-## DataScannerViewController
+`.denied`, `.restricted` and any status added in a future release all fall
+through to `false`.
 
-`DataScannerViewController` provides a full-screen live camera scanner for text
-and barcodes with built-in highlighting and interaction. Available on devices
-with an A12 chip or later (iOS 16+).
+## DataScannerViewController
 
-### Availability Checking
+A full-screen live scanner with built-in highlighting and tap handling.
+Available from iOS 16 on devices with an A12 Bionic chip or newer.
 
-Always check both hardware support and runtime availability before presenting.
+Two class properties gate it, and both must be true before presenting:
 
-```swift
-import VisionKit
+- `isSupported`: the hardware can run it.
+- `isAvailable`: supported, plus camera access is granted and not blocked by
+  restrictions such as device management.
 
-func canUseDataScanner() -> Bool {
-    // Hardware check: requires A12 Bionic or later
-    guard DataScannerViewController.isSupported else {
-        return false
-    }
-    // Runtime check: camera authorized and not restricted
-    guard DataScannerViewController.isAvailable else {
-        return false
-    }
-    return true
-}
-```
+### Initializer options
 
-`isSupported` checks hardware capability (A12+). `isAvailable` checks that the
-camera is authorized and not restricted by device management. Both must be true.
+| Parameter | Default | Meaning |
+|---|---|---|
+| `recognizedDataTypes` | required | Set of text and barcode types to find |
+| `qualityLevel` | `.balanced` | Speed versus detail |
+| `recognizesMultipleItems` | `false` | Track many items or only the most prominent |
+| `isHighFrameRateTrackingEnabled` | `true` | Smoother highlight tracking, more power |
+| `isPinchToZoomEnabled` | `true` | Pinch gesture zooms the camera |
+| `isGuidanceEnabled` | `true` | On-screen hints such as "slow down" |
+| `isHighlightingEnabled` | `false` | System highlight boxes around found items |
 
-### Configuration and Initialization
+Three configurations for different jobs:
 
 ```swift
 import VisionKit
 
-func createTextScanner() -> DataScannerViewController {
-    DataScannerViewController(
-        recognizedDataTypes: [
-            .text(languages: ["en"]),
-        ],
-        qualityLevel: .balanced,
-        recognizesMultipleItems: true,
-        isHighFrameRateTrackingEnabled: true,
-        isPinchToZoomEnabled: true,
-        isGuidanceEnabled: true,
-        isHighlightingEnabled: true
-    )
-}
+@MainActor
+enum ScannerPresets {
+    static func signReader() -> DataScannerViewController {
+        DataScannerViewController(
+            recognizedDataTypes: [.text()],
+            qualityLevel: .accurate,
+            recognizesMultipleItems: true,
+            isHighFrameRateTrackingEnabled: false,
+            isPinchToZoomEnabled: true,
+            isGuidanceEnabled: false,
+            isHighlightingEnabled: true
+        )
+    }
 
-func createBarcodeScanner() -> DataScannerViewController {
-    DataScannerViewController(
-        recognizedDataTypes: [
-            .barcode(symbologies: [.qr, .ean13, .code128]),
-        ],
-        qualityLevel: .fast,
-        recognizesMultipleItems: false,
-        isHighFrameRateTrackingEnabled: false,
-        isPinchToZoomEnabled: false,
-        isGuidanceEnabled: true,
-        isHighlightingEnabled: true
-    )
-}
+    static func boardingPassReader() -> DataScannerViewController {
+        DataScannerViewController(
+            recognizedDataTypes: [.barcode(symbologies: [.pdf417, .aztec, .qr])],
+            qualityLevel: .fast,
+            isHighFrameRateTrackingEnabled: false,
+            isPinchToZoomEnabled: false
+        )
+    }
 
-func createMixedScanner() -> DataScannerViewController {
-    DataScannerViewController(
-        recognizedDataTypes: [
-            .text(languages: ["en"]),
-            .barcode(symbologies: [.qr, .ean13]),
-        ],
-        qualityLevel: .balanced,
-        recognizesMultipleItems: true,
-        isHighFrameRateTrackingEnabled: true,
-        isPinchToZoomEnabled: true,
-        isGuidanceEnabled: true,
-        isHighlightingEnabled: true
-    )
+    static func parcelReader() -> DataScannerViewController {
+        DataScannerViewController(
+            recognizedDataTypes: [
+                .text(textContentType: .shipmentTrackingNumber),
+                .barcode(symbologies: [.code128, .qr])
+            ],
+            qualityLevel: .balanced,
+            isHighlightingEnabled: true
+        )
+    }
 }
 ```
 
-### Recognized Data Types
+### Data types
 
-```swift
-// Text with language hints
-let textType: DataScannerViewController.RecognizedDataType =
-    .text(languages: ["en", "fr", "de"])
-
-// Text filtered by content type
-let emailType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .emailAddress)
-let urlType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .URL)
-let phoneType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .telephoneNumber)
-let addressType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .fullAddress)
-let flightType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .flightNumber)
-let trackingType: DataScannerViewController.RecognizedDataType =
-    .text(textContentType: .shipmentTrackingNumber)
-
-// Barcode with specific symbologies
-let qrOnly: DataScannerViewController.RecognizedDataType =
-    .barcode(symbologies: [.qr])
-let retailBarcodes: DataScannerViewController.RecognizedDataType =
-    .barcode(symbologies: [.ean8, .ean13, .upce, .code128])
-```
+`DataScannerViewController.RecognizedDataType` values:
 
-### Quality Levels
+- `.text(languages:textContentType:)`: both arguments are optional, so
+  `.text()`, `.text(languages: ["fr"])` and
+  `.text(textContentType: .flightNumber)` all work.
+- `.barcode(symbologies:)`: takes `VNBarcodeSymbology` values.
 
-| Level | Use Case | Notes |
-|---|---|---|
-| `.fast` | Barcode scanning, quick text grab | Lowest latency |
-| `.balanced` | General purpose text + barcode | Default choice |
-| `.accurate` | Detailed OCR, small text | Higher latency |
+Text content types narrow recognition to one kind of string: `.URL`,
+`.emailAddress`, `.telephoneNumber`, `.fullStreetAddress`, `.flightNumber`,
+`.shipmentTrackingNumber`, `.dateTimeDuration`, and `.currency` (iOS 17).
 
-### Starting and Stopping
+A retail product scanner usually needs `.ean13`, `.ean8`, `.upce` and
+`.code128`.
 
-```swift
-func presentScanner(_ scanner: DataScannerViewController,
-                    from presenter: UIViewController) {
-    scanner.delegate = presenter as? DataScannerViewControllerDelegate
-    presenter.present(scanner, animated: true) {
-        try? scanner.startScanning()
-    }
-}
+### Quality levels
 
-func dismissScanner(_ scanner: DataScannerViewController) {
-    scanner.stopScanning()
-    scanner.dismiss(animated: true)
-}
-```
+- `.fast`: lowest latency; barcodes and large, quick text.
+- `.balanced`: the sensible default for most scanners.
+- `.accurate`: small or dense text; slower to respond.
 
-## Delegate Methods
+### Start and stop
 
-Implement `DataScannerViewControllerDelegate` to handle recognized items and
-scanner lifecycle events.
+Scanning can only start once the controller is on screen. Set the delegate,
+present, and start in the presentation completion. To finish, call
+`stopScanning()` and then dismiss.
 
 ```swift
+import UIKit
 import VisionKit
 
-final class ScannerCoordinator: NSObject, DataScannerViewControllerDelegate {
-
-    var onTextRecognized: ((String) -> Void)?
-    var onBarcodeRecognized: ((String, VNBarcodeSymbology) -> Void)?
-
-    // Called when the user taps on a recognized item
-    func dataScanner(
-        _ scanner: DataScannerViewController,
-        didTapOn item: RecognizedItem
-    ) {
-        switch item {
-        case .text(let text):
-            onTextRecognized?(text.transcript)
-        case .barcode(let barcode):
-            if let payload = barcode.payloadStringValue {
-                onBarcodeRecognized?(payload, barcode.observation.symbology)
-            }
-        @unknown default:
-            break
-        }
-    }
-
-    // Called when new items appear in the camera view
-    func dataScanner(
-        _ scanner: DataScannerViewController,
-        didAdd addedItems: [RecognizedItem],
-        allItems: [RecognizedItem]
-    ) {
-        for item in addedItems {
-            switch item {
-            case .text(let text):
-                print("New text: \(text.transcript)")
-            case .barcode(let barcode):
-                print("New barcode: \(barcode.payloadStringValue ?? "nil")")
-            @unknown default:
-                break
-            }
+@MainActor
+final class ScanCoordinator {
+    private var live: DataScannerViewController?
+
+    func open(from host: UIViewController, delegate: DataScannerViewControllerDelegate) {
+        let passReader = ScannerPresets.boardingPassReader()
+        passReader.delegate = delegate
+        live = passReader
+        host.present(passReader, animated: true) {
+            try? passReader.startScanning()
         }
     }
 
-    // Called when items are updated (position or content changes)
-    func dataScanner(
-        _ scanner: DataScannerViewController,
-        didUpdate updatedItems: [RecognizedItem],
-        allItems: [RecognizedItem]
-    ) {
-        // Handle position or content updates
-    }
-
-    // Called when items leave the camera view
-    func dataScanner(
-        _ scanner: DataScannerViewController,
-        didRemove removedItems: [RecognizedItem],
-        allItems: [RecognizedItem]
-    ) {
-        // Clean up UI for removed items
-    }
-
-    // Called when the scanner becomes unavailable (e.g., camera revoked)
-    func dataScannerDidChangeUnavailabilityReasons(
-        _ scanner: DataScannerViewController
-    ) {
-        // Handle unavailability -- dismiss or show fallback
+    func close() {
+        guard let live else { return }
+        live.stopScanning()
+        live.dismiss(animated: true)
+        self.live = nil
     }
 }
 ```
 
-### Async Sequence for Recognized Items
+## Delegate callbacks
+
+`DataScannerViewControllerDelegate` methods, all main-actor isolated:
+
+| Method | When it fires |
+|---|---|
+| `dataScanner(_:didTapOn:)` | The user tapped a recognized item |
+| `dataScanner(_:didAdd:allItems:)` | New items appeared |
+| `dataScanner(_:didUpdate:allItems:)` | Items moved or their content changed |
+| `dataScanner(_:didRemove:allItems:)` | Items left the frame |
+| `dataScanner(_:becameUnavailableWithError:)` | Scanning stopped being possible, for example camera access was revoked; dismiss or fall back |
+| `dataScannerDidZoom(_:)` | Zoom factor changed |
 
-Use `recognizedItems` for a reactive stream of all currently visible items:
+`RecognizedItem` is an enum. Handle both cases and keep an `@unknown default`:
 
 ```swift
-func observeRecognizedItems(_ scanner: DataScannerViewController) async {
-    for await items in scanner.recognizedItems {
-        let texts = items.compactMap { item -> String? in
-            guard case .text(let text) = item else { return nil }
-            return text.transcript
-        }
-        let barcodes = items.compactMap { item -> String? in
-            guard case .barcode(let barcode) = item else { return nil }
-            return barcode.payloadStringValue
-        }
-        await MainActor.run {
-            // Update UI with current texts and barcodes
-        }
+import VisionKit
+
+func describe(_ item: RecognizedItem) -> String {
+    switch item {
+    case .text(let recognized):
+        return recognized.transcript
+    case .barcode(let code):
+        return "\(code.observation.symbology.rawValue): \(code.payloadStringValue ?? "?")"
+    @unknown default:
+        return ""
     }
 }
 ```
 
-### Capturing a Photo
+### Async stream of items
 
-Capture a still image from the scanner for further processing:
+`recognizedItems` is an `AsyncStream<[RecognizedItem]>`: every element is the
+full set of items currently in view.
 
 ```swift
-func captureAndProcess(_ scanner: DataScannerViewController) async throws {
-    let photo = try await scanner.capturePhoto()
-    // photo is a UIImage -- process with Vision or save
+import VisionKit
+
+@MainActor
+func watch(_ scanner: DataScannerViewController,
+           onText: ([String]) -> Void,
+           onCodes: ([String]) -> Void) async {
+    for await visible in scanner.recognizedItems {
+        var lines: [String] = []
+        var codes: [String] = []
+        for item in visible {
+            switch item {
+            case .text(let recognized): lines.append(recognized.transcript)
+            case .barcode(let code): codes.append(code.payloadStringValue ?? "")
+            @unknown default: break
+            }
+        }
+        onText(lines)
+        onCodes(codes)
+    }
 }
 ```
 
-## SwiftUI Integration
+### Still photo
 
-Wrap `DataScannerViewController` in `UIViewControllerRepresentable` for use
-in SwiftUI views.
+`try await scanner.capturePhoto()` returns a `UIImage` of the current camera
+frame, useful for a high-resolution OCR pass or for attaching to a record.
 
-### Full DataScanner Representable
+## SwiftUI
+
+A representable that reports tapped items through bindings:
 
 ```swift
-import SwiftUI
 import VisionKit
+import SwiftUI
 
-struct DataScannerRepresentable: UIViewControllerRepresentable {
-    let recognizedDataTypes: Set<DataScannerViewController.RecognizedDataType>
-    let qualityLevel: DataScannerViewController.QualityLevel
-    let recognizesMultipleItems: Bool
-    @Binding var recognizedText: [String]
-    @Binding var recognizedBarcodes: [String]
+struct LiveScanner: UIViewControllerRepresentable {
+    let kinds: Set<DataScannerViewController.RecognizedDataType>
+    var quality: DataScannerViewController.QualityLevel = .balanced
+    var many = false
+    @Binding var lines: [String]
+    @Binding var payloads: [String]
 
     func makeUIViewController(context: Context) -> DataScannerViewController {
-        let scanner = DataScannerViewController(
-            recognizedDataTypes: recognizedDataTypes,
-            qualityLevel: qualityLevel,
-            recognizesMultipleItems: recognizesMultipleItems,
-            isHighFrameRateTrackingEnabled: true,
-            isPinchToZoomEnabled: true,
-            isGuidanceEnabled: true,
+        let liveView = DataScannerViewController(
+            recognizedDataTypes: kinds,
+            qualityLevel: quality,
+            recognizesMultipleItems: many,
             isHighlightingEnabled: true
         )
-        scanner.delegate = context.coordinator
-        return scanner
+        liveView.delegate = context.coordinator
+        Task { @MainActor in
+            try? liveView.startScanning()
+        }
+        return liveView
     }
 
-    func updateUIViewController(
-        _ controller: DataScannerViewController,
-        context: Context
-    ) {
-        // No dynamic updates needed
-    }
+    func updateUIViewController(_ scannerController: DataScannerViewController, context: Context) {}
 
-    func makeCoordinator() -> Coordinator {
-        Coordinator(parent: self)
+    func makeCoordinator() -> Tapper {
+        Tapper(owner: self)
     }
 
-    static func dismantleUIViewController(
-        _ controller: DataScannerViewController,
-        coordinator: Coordinator
-    ) {
-        controller.stopScanning()
+    static func dismantleUIViewController(_ scannerController: DataScannerViewController, coordinator: Tapper) {
+        scannerController.stopScanning()
     }
 
     @MainActor
-    final class Coordinator: NSObject, DataScannerViewControllerDelegate {
-        let parent: DataScannerRepresentable
+    final class Tapper: NSObject, DataScannerViewControllerDelegate {
+        private let owner: LiveScanner
 
-        init(parent: DataScannerRepresentable) {
-            self.parent = parent
+        init(owner: LiveScanner) {
+            self.owner = owner
         }
 
-        func dataScanner(
-            _ scanner: DataScannerViewController,
-            didTapOn item: RecognizedItem
-        ) {
+        func dataScanner(_ dataScanner: DataScannerViewController, didTapOn item: RecognizedItem) {
             switch item {
-            case .text(let text):
-                parent.recognizedText.append(text.transcript)
-            case .barcode(let barcode):
-                if let payload = barcode.payloadStringValue {
-                    parent.recognizedBarcodes.append(payload)
+            case .text(let recognized):
+                owner.lines.append(recognized.transcript)
+            case .barcode(let code):
+                if let value = code.payloadStringValue {
+                    owner.payloads.append(value)
                 }
             @unknown default:
                 break
             }
         }
-
-        func dataScanner(
-            _ scanner: DataScannerViewController,
-            didAdd addedItems: [RecognizedItem],
-            allItems: [RecognizedItem]
-        ) {
-            // Handle newly recognized items
-        }
-
-        func dataScanner(
-            _ scanner: DataScannerViewController,
-            didUpdate updatedItems: [RecognizedItem],
-            allItems: [RecognizedItem]
-        ) {
-            // Handle item updates
-        }
-
-        func dataScanner(
-            _ scanner: DataScannerViewController,
-            didRemove removedItems: [RecognizedItem],
-            allItems: [RecognizedItem]
-        ) {
-            // Handle removed items
-        }
     }
 }
 ```
 
-### SwiftUI Scanner View
+`startScanning()` must wait until the controller is presented. The deferred
+`Task` above runs after `makeUIViewController` returns; stopping belongs in
+`dismantleUIViewController`.
+
+A screen that offers the scanner only where it can run:
 
 ```swift
-import SwiftUI
 import VisionKit
+import SwiftUI
 
-struct ScannerView: View {
-    @State private var recognizedText: [String] = []
-    @State private var recognizedBarcodes: [String] = []
-    @State private var isShowingScanner = false
+struct ShelfScanScreen: View {
+    @State private var scanning = false
+    @State private var lines: [String] = []
+    @State private var payloads: [String] = []
 
     var body: some View {
-        VStack {
+        Form {
             if DataScannerViewController.isSupported {
-                Button("Scan") {
-                    isShowingScanner = true
-                }
-                .fullScreenCover(isPresented: $isShowingScanner) {
-                    NavigationStack {
-                        DataScannerRepresentable(
-                            recognizedDataTypes: [
-                                .text(languages: ["en"]),
-                                .barcode(symbologies: [.qr]),
-                            ],
-                            qualityLevel: .balanced,
-                            recognizesMultipleItems: true,
-                            recognizedText: $recognizedText,
-                            recognizedBarcodes: $recognizedBarcodes
-                        )
-                        .ignoresSafeArea()
-                        .toolbar {
-                            ToolbarItem(placement: .cancellationAction) {
-                                Button("Done") {
-                                    isShowingScanner = false
-                                }
-                            }
-                        }
-                    }
-                }
+                Button("Scan labels") { scanning = true }
             } else {
-                ContentUnavailableView(
-                    "Scanner Not Available",
-                    systemImage: "camera.fill",
-                    description: Text("This device does not support scanning.")
-                )
+                ContentUnavailableView("Scanning unavailable",
+                                       systemImage: "camera.fill",
+                                       description: Text("Live scanning needs a newer iPhone or iPad."))
             }
-
-            List {
-                Section("Text") {
-                    ForEach(recognizedText, id: \.self) { text in
-                        Text(text)
-                    }
-                }
-                Section("Barcodes") {
-                    ForEach(recognizedBarcodes, id: \.self) { barcode in
-                        Text(barcode)
+            Section("Text") { ForEach(lines, id: \.self, content: Text.init) }
+            Section("Codes") { ForEach(payloads, id: \.self, content: Text.init) }
+        }
+        .fullScreenCover(isPresented: $scanning) {
+            NavigationStack {
+                LiveScanner(kinds: [.text(), .barcode()], lines: $lines, payloads: $payloads)
+                    .ignoresSafeArea()
+                    .toolbar {
+                        ToolbarItem(placement: .cancellationAction) {
+                            Button("Close") { scanning = false }
+                        }
                     }
-                }
             }
         }
     }
 }
 ```
 
-### Starting the Scanner After Presentation
+## Custom overlay
 
-The scanner must be started after the view controller is fully presented.
-Use `onAppear` with a coordinator flag or start in the completion handler:
+Layer your own guidance on top of the scanner with a `ZStack`:
 
 ```swift
-struct AutoStartScannerRepresentable: UIViewControllerRepresentable {
-    func makeUIViewController(context: Context) -> DataScannerViewController {
-        let scanner = DataScannerViewController(
-            recognizedDataTypes: [.text(languages: ["en"])],
-            qualityLevel: .balanced,
-            recognizesMultipleItems: false,
-            isHighFrameRateTrackingEnabled: true,
-            isHighlightingEnabled: true
-        )
-        scanner.delegate = context.coordinator
-        // Start scanning after a brief delay to ensure presentation is complete
-        Task { @MainActor in
-            try? scanner.startScanning()
-        }
-        return scanner
-    }
-
-    func updateUIViewController(
-        _ controller: DataScannerViewController,
-        context: Context
-    ) {}
-
-    func makeCoordinator() -> ScannerCoordinator {
-        ScannerCoordinator()
-    }
-
-    static func dismantleUIViewController(
-        _ controller: DataScannerViewController,
-        coordinator: ScannerCoordinator
-    ) {
-        controller.stopScanning()
-    }
-}
-```
-
-## Custom Overlay UI
-
-Add custom views on top of the scanner for region-of-interest indicators,
-instructions, or result display.
-
-### Overlay with Region of Interest
+import VisionKit
+import SwiftUI
 
-```swift
-struct ScannerWithOverlay: View {
-    @State private var isShowingScanner = false
-    @State private var lastScannedText = ""
+struct FramedScanner: View {
+    @State private var lines: [String] = []
+    @State private var payloads: [String] = []
 
     var body: some View {
         ZStack {
-            AutoStartScannerRepresentable()
+            LiveScanner(kinds: [.barcode()], lines: $lines, payloads: $payloads)
                 .ignoresSafeArea()
-
-            VStack {
-                // Top instruction bar
-                Text("Point camera at text or barcode")
-                    .font(.subheadline)
-                    .padding(.horizontal)
-                    .padding(.vertical)
+            VStack(spacing: 24) {
+                Text("Fit the code inside the frame")
+                    .padding(.horizontal, 16)
+                    .padding(.vertical, 8)
                     .background(.ultraThinMaterial, in: Capsule())
-                    .padding(.top)
-
-                Spacer()
-
-                // Scan region indicator
-                RoundedRectangle(cornerRadius: 12)
-                    .strokeBorder(.white.opacity(0.6), lineWidth: 2)
-                    .frame(width: 280, height: 180)
-
-                Spacer()
-
-                // Result display
-                if !lastScannedText.isEmpty {
-                    Text(lastScannedText)
-                        .font(.body)
-                        .padding()
-                        .frame(maxWidth: .infinity)
-                        .background(.ultraThinMaterial)
-                        .clipShape(.rect(cornerRadius: 12))
+                RoundedRectangle(cornerRadius: 16)
+                    .stroke(.white.opacity(0.7), lineWidth: 3)
+                    .frame(width: 260, height: 260)
+                if let latest = payloads.last {
+                    Text(latest)
                         .padding()
+                        .background(.thinMaterial, in: .rect(cornerRadius: 12))
                 }
             }
         }
@@ -538,201 +360,203 @@ struct ScannerWithOverlay: View {
 }
 ```
 
+Sizes in these examples are placeholders; take them from the design system.
+
 ## VNDocumentCameraViewController
 
-`VNDocumentCameraViewController` provides a full-screen document camera with
-auto-capture, perspective correction, and multi-page scanning. Available on
-all devices running iOS 13+.
+Presents a camera that fills the screen, snaps pages on its own, straightens
+them, and collects several pages per session. It works on every device that runs iOS 13 or later.
 
-### UIKit Presentation
+A small helper used by both versions below:
 
 ```swift
 import VisionKit
 
-final class DocumentScannerPresenter: NSObject,
-    VNDocumentCameraViewControllerDelegate
-{
-    weak var presenter: UIViewController?
+extension VNDocumentCameraScan {
+    var allPages: [UIImage] {
+        var collected: [UIImage] = []
+        for index in 0..<pageCount {
+            collected.append(imageOfPage(at: index))
+        }
+        return collected
+    }
+}
+```
+
+UIKit:
+
+```swift
+import UIKit
+import VisionKit
 
-    func showDocumentScanner() {
-        let scanner = VNDocumentCameraViewController()
-        scanner.delegate = self
-        presenter?.present(scanner, animated: true)
+@MainActor
+final class PaperScanFlow: NSObject, @MainActor VNDocumentCameraViewControllerDelegate {
+    private weak var host: UIViewController?
+    var onPages: ([UIImage]) -> Void = { _ in }
+    var onFailure: (Error) -> Void = { _ in }
+
+    func start(from host: UIViewController) {
+        self.host = host
+        let camera = VNDocumentCameraViewController()
+        camera.delegate = self
+        host.present(camera, animated: true)
     }
 
-    func documentCameraViewController(
-        _ controller: VNDocumentCameraViewController,
-        didFinishWith scan: VNDocumentCameraScan
-    ) {
-        controller.dismiss(animated: true)
-        for pageIndex in 0..<scan.pageCount {
-            let pageImage = scan.imageOfPage(at: pageIndex)
-            // Process each scanned page image
-        }
+    func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                      didFinishWith scan: VNDocumentCameraScan) {
+        camera.dismiss(animated: true)
+        onPages(scan.allPages)
     }
 
-    func documentCameraViewControllerDidCancel(
-        _ controller: VNDocumentCameraViewController
-    ) {
-        controller.dismiss(animated: true)
+    func documentCameraViewControllerDidCancel(_ camera: VNDocumentCameraViewController) {
+        camera.dismiss(animated: true)
     }
 
-    func documentCameraViewController(
-        _ controller: VNDocumentCameraViewController,
-        didFailWithError error: Error
-    ) {
-        controller.dismiss(animated: true)
-        // Handle scanning error
+    func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                      didFailWithError error: Error) {
+        camera.dismiss(animated: true)
+        onFailure(error)
     }
 }
 ```
 
-### SwiftUI Document Scanner
+`VNDocumentCameraViewControllerDelegate` carries no actor annotation, so the
+conformance is written as `@MainActor VNDocumentCameraViewControllerDelegate`
+(an isolated conformance, Swift 6.2 and later). The presenter is held `weak`
+so the flow object never keeps a dismissed screen alive.
+
+SwiftUI:
 
 ```swift
-import SwiftUI
 import VisionKit
+import SwiftUI
 
-struct DocumentScannerRepresentable: UIViewControllerRepresentable {
-    @Binding var scannedImages: [UIImage]
-    @Environment(\.dismiss) private var dismiss
+struct PaperCamera: UIViewControllerRepresentable {
+    @Binding var pages: [UIImage]
+    @Environment(\.dismiss) private var close
 
     func makeUIViewController(context: Context) -> VNDocumentCameraViewController {
-        let scanner = VNDocumentCameraViewController()
-        scanner.delegate = context.coordinator
-        return scanner
+        let camera = VNDocumentCameraViewController()
+        camera.delegate = context.coordinator
+        return camera
     }
 
-    func updateUIViewController(
-        _ controller: VNDocumentCameraViewController,
-        context: Context
-    ) {}
+    func updateUIViewController(_ camera: VNDocumentCameraViewController, context: Context) {}
 
-    func makeCoordinator() -> Coordinator {
-        Coordinator(parent: self)
+    func makeCoordinator() -> Receiver {
+        Receiver(owner: self)
     }
 
     @MainActor
-    final class Coordinator: NSObject, VNDocumentCameraViewControllerDelegate {
-        let parent: DocumentScannerRepresentable
+    final class Receiver: NSObject, @MainActor VNDocumentCameraViewControllerDelegate {
+        private let owner: PaperCamera
 
-        init(parent: DocumentScannerRepresentable) {
-            self.parent = parent
+        init(owner: PaperCamera) {
+            self.owner = owner
         }
 
-        func documentCameraViewController(
-            _ controller: VNDocumentCameraViewController,
-            didFinishWith scan: VNDocumentCameraScan
-        ) {
-            parent.scannedImages = (0..<scan.pageCount).map { scan.imageOfPage(at: $0) }
-            parent.dismiss()
+        func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                          didFinishWith scan: VNDocumentCameraScan) {
+            owner.pages = scan.allPages
+            owner.close()
         }
 
-        func documentCameraViewControllerDidCancel(
-            _ controller: VNDocumentCameraViewController
-        ) {
-            parent.dismiss()
+        func documentCameraViewControllerDidCancel(_ camera: VNDocumentCameraViewController) {
+            owner.close()
         }
 
-        func documentCameraViewController(
-            _ controller: VNDocumentCameraViewController,
-            didFailWithError error: Error
-        ) {
-            parent.dismiss()
+        func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                          didFailWithError error: Error) {
+            owner.close()
         }
     }
 }
 ```
 
-### Document Scanner with OCR Pipeline
+### Scan then read
 
-Combine document scanning with Vision text recognition for a complete OCR flow:
+A model that runs OCR over every captured page, and a view that drives it:
 
 ```swift
+import Observation
 import SwiftUI
-import VisionKit
 import Vision
+import VisionKit
 
 @MainActor
 @Observable
-final class DocumentOCRModel {
-    var scannedPages: [UIImage] = []
-    var extractedText: [String] = []
-    var isProcessing = false
-
-    func processScannedPages() async {
-        isProcessing = true
-        defer { isProcessing = false }
-
-        extractedText = []
-        for page in scannedPages {
-            guard let cgImage = page.cgImage else { continue }
+final class PaperReader {
+    var pages: [UIImage] = []
+    var transcripts: [String] = []
+    var busy = false
+
+    func transcribe() async {
+        busy = true
+        defer { busy = false }
+        var results: [String] = []
+        for page in pages {
+            guard let bitmap = page.cgImage else {
+                results.append("(page could not be read)")
+                continue
+            }
+            var request = RecognizeTextRequest()
+            request.usesLanguageCorrection = true
+            request.recognitionLanguages = [Locale.Language(identifier: "en-GB")]
+            request.recognitionLevel = .accurate
             do {
-                var request = RecognizeTextRequest()
-                request.recognitionLevel = .accurate
-                request.recognitionLanguages = [Locale.Language(identifier: "en-US")]
-                request.usesLanguageCorrection = true
-
-                let observations = try await request.perform(on: cgImage)
-                let pageText = observations
-                    .compactMap { $0.topCandidates(1).first?.string }
-                    .joined(separator: "\n")
-                extractedText.append(pageText)
+                let found = try await request.perform(on: bitmap)
+                let body = found.compactMap { $0.topCandidates(1).first }.map(\.string)
+                results.append(body.joined(separator: "\n"))
             } catch {
-                extractedText.append("[Recognition failed]")
+                results.append("(recognition failed)")
             }
         }
+        transcripts = results
     }
 }
 
-struct DocumentOCRView: View {
-    @State private var model = DocumentOCRModel()
-    @State private var isShowingScanner = false
+struct PaperReaderScreen: View {
+    @State private var reader = PaperReader()
+    @State private var capturing = false
 
     var body: some View {
-        NavigationStack {
-            List {
-                if model.isProcessing {
-                    ProgressView("Recognizing text...")
-                }
-                ForEach(Array(model.extractedText.enumerated()), id: \.offset) { index, text in
-                    Section("Page \(index + 1)") {
-                        Text(text)
-                            .font(.body)
-                            .textSelection(.enabled)
-                    }
-                }
+        Form {
+            Button("Scan pages") { capturing = true }
+            if reader.busy {
+                ProgressView()
             }
-            .navigationTitle("Document OCR")
-            .toolbar {
-                Button("Scan") {
-                    isShowingScanner = true
+            ForEach(reader.transcripts.indices, id: \.self) { page in
+                Section("Page \(page + 1)") {
+                    Text(reader.transcripts[page]).textSelection(.enabled)
                 }
             }
-            .fullScreenCover(isPresented: $isShowingScanner) {
-                DocumentScannerRepresentable(scannedImages: $model.scannedPages)
-            }
-            .onChange(of: model.scannedPages) {
-                Task { await model.processScannedPages() }
-            }
+        }
+        .sheet(isPresented: $capturing) {
+            PaperCamera(pages: $reader.pages)
+        }
+        .onChange(of: reader.pages) {
+            Task { await reader.transcribe() }
         }
     }
 }
 ```
 
-## Performance Considerations
+User-facing strings here are literals for brevity; ship them as localized keys.
+
+## Performance
 
-### DataScannerViewController
+Live scanner:
 
-- Use `.fast` quality for barcode-only scanning
-- Set `recognizesMultipleItems = false` when only one result is needed
-- Disable `isHighFrameRateTrackingEnabled` for barcode scanning to save power
-- Limit `recognizedDataTypes` to only what you need
-- Stop scanning when processing results to avoid wasted CPU cycles
+- Use `.fast` when only barcodes are scanned.
+- Set `recognizesMultipleItems = false` when one result is enough.
+- Turn off `isHighFrameRateTrackingEnabled` for barcode-only scanners to save
+  power.
+- Ask only for the `recognizedDataTypes` the feature needs.
+- Call `stopScanning()` while you process a result, and resume afterwards.
 
-### VNDocumentCameraViewController
+Document camera:
 
-- Pages are returned as `UIImage` at full resolution -- resize before
-  processing if memory is a concern
-- Process pages sequentially to avoid memory spikes
-- Use `autoreleasepool` when processing many pages in a loop
+- Pages arrive as full-resolution `UIImage` values; downscale them if memory
+  is tight.
+- Process pages one after another rather than all at once, and wrap
+  synchronous per-page loops in `autoreleasepool` when there are many.