@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/photos-camera-media/references/camera-capture.md

@@ -1,774 +1,530 @@
-# Camera Capture
+# Capture session recipes
 
-Complete patterns for AVCaptureSession setup, photo capture, video recording, and camera features in SwiftUI. All patterns use a dedicated `@Observable` model that owns the session; the SwiftUI view only displays the preview and triggers actions.
-
----
+Shape used throughout: an `@Observable` model owns the capture session and all
+camera state; the SwiftUI view draws the preview and forwards taps. Session
+work runs on one private serial queue, because `AVCaptureSession` is not
+`Sendable` and its start and stop calls block.
 
 ## Contents
 
-- [1. Complete Camera Manager with Photo Capture](#1-complete-camera-manager-with-photo-capture)
-- [2. Camera Preview (UIViewRepresentable)](#2-camera-preview-uiviewrepresentable)
-- [3. Complete Camera Screen in SwiftUI](#3-complete-camera-screen-in-swiftui)
-- [4. Video Recording](#4-video-recording)
-- [5. Flash and Torch Control](#5-flash-and-torch-control)
-- [6. Focus and Exposure](#6-focus-and-exposure)
-- [7. Barcode and QR Code Scanning](#7-barcode-and-qr-code-scanning)
-- [8. Camera Preview Orientation](#8-camera-preview-orientation)
-- [9. Dual Camera and Device Discovery](#9-dual-camera-and-device-discovery)
-- [10. Restricting Scan Region](#10-restricting-scan-region)
+- [1. A full photo camera](#1-a-full-photo-camera)
+- [2. Preview view](#2-preview-view)
+- [3. Camera screen](#3-camera-screen)
+- [4. Recording video](#4-recording-video)
+- [5. Flash and torch](#5-flash-and-torch)
+- [6. Tap to focus and expose](#6-tap-to-focus-and-expose)
+- [7. Barcodes and QR codes](#7-barcodes-and-qr-codes)
+- [8. Orientation](#8-orientation)
+- [9. Choosing specific cameras](#9-choosing-specific-cameras)
+- [10. Limiting the scan area](#10-limiting-the-scan-area)
 
-## 1. Complete Camera Manager with Photo Capture
+## 1. A full photo camera
 
-A full-featured camera model with photo capture using the delegate pattern.
+The rig owns the session graph and does all session work on its queue. The
+model is main-actor state plus the capture delegate, which is why it inherits
+from `NSObject`.
 
 ```swift
 import AVFoundation
-import UIKit
+import Observation
 
-@available(iOS 17.0, *)
-@Observable
-@MainActor
-final class CameraManager: NSObject {
+final class CameraRig: @unchecked Sendable {
     let session = AVCaptureSession()
+    let stills = AVCapturePhotoOutput()
+    private(set) var activeInput: AVCaptureDeviceInput?
+    private let queue = DispatchQueue(label: "camera.rig")
 
-    private let photoOutput = AVCapturePhotoOutput()
-    private var currentInput: AVCaptureDeviceInput?
-    private var photoContinuation: CheckedContinuation<Data?, Never>?
-
-    var isRunning = false
-    var cameraPosition: AVCaptureDevice.Position = .back
-    var flashMode: AVCaptureDevice.FlashMode = .auto
-    var lastCapturedPhoto: Data?
-    var error: String?
-
-    // MARK: - Configuration
-
-    func configure() async {
-        guard await requestAccess() else {
-            error = "Camera access denied"
-            return
+    func onQueue<T: Sendable>(_ work: @escaping @Sendable () -> T) async -> T {
+        await withCheckedContinuation { done in
+            queue.async { done.resume(returning: work()) }
         }
+    }
 
+    func assemble(facing side: AVCaptureDevice.Position) -> String? {
         session.beginConfiguration()
+        defer { session.commitConfiguration() }
         session.sessionPreset = .photo
+        guard let camera = AVCaptureDevice.default(.builtInWideAngleCamera, for: AVMediaType.video, position: side),
+              let feedIn = try? AVCaptureDeviceInput(device: camera),
+              session.canAddInput(feedIn) else { return "No usable camera" }
+        session.addInput(feedIn)
+        activeInput = feedIn
+        guard session.canAddOutput(stills) else { return "Photo output rejected" }
+        session.addOutput(stills)
+        let largest = camera.activeFormat.supportedMaxPhotoDimensions
+            .max { Int($0.width) * Int($0.height) < Int($1.width) * Int($1.height) }
+        if let largest { stills.maxPhotoDimensions = largest }
+        stills.maxPhotoQualityPrioritization = .quality
+        return nil
+    }
+
+    func swapInput(to side: AVCaptureDevice.Position) -> Bool {
+        guard let camera = AVCaptureDevice.default(.builtInWideAngleCamera, for: AVMediaType.video, position: side),
+              let replacement = try? AVCaptureDeviceInput(device: camera) else { return false }
+        session.beginConfiguration()
+        defer { session.commitConfiguration() }
+        if let activeInput { session.removeInput(activeInput) }
+        guard session.canAddInput(replacement) else { return false }
+        session.addInput(replacement)
+        activeInput = replacement
+        return true
+    }
+}
 
-        // Add camera input
-        guard let device = cameraDevice(for: cameraPosition),
-              let input = try? AVCaptureDeviceInput(device: device),
-              session.canAddInput(input) else {
-            error = "Failed to configure camera input"
-            session.commitConfiguration()
-            return
-        }
-        session.addInput(input)
-        currentInput = input
-
-        // Add photo output
-        guard session.canAddOutput(photoOutput) else {
-            error = "Failed to configure photo output"
-            session.commitConfiguration()
-            return
-        }
-        session.addOutput(photoOutput)
+@available(iOS 17.0, *)
+@Observable @MainActor
+final class StudioCamera: NSObject {
+    private(set) var isRunning = false
+    private(set) var facing: AVCaptureDevice.Position = .back
+    var flash: AVCaptureDevice.FlashMode = .auto
+    private(set) var latestShot: Data?
+    private(set) var problem: String?
 
-        // Enable maximum quality (iOS 16+)
-        if let maxDimensions = photoOutput.maxPhotoDimensions(for: .photo) {
-            photoOutput.maxPhotoDimensions = maxDimensions
-        }
-        photoOutput.maxPhotoQualityPrioritization = .quality
+    @ObservationIgnored let rig = CameraRig()
+    @ObservationIgnored private var pendingShot: CheckedContinuation<Data?, Never>?
 
-        session.commitConfiguration()
+    func configure() async {
+        guard await CameraAccess.isGranted() else { problem = "Camera access denied"; return }
+        let side = facing
+        problem = await rig.onQueue { [rig] in rig.assemble(facing: side) }
     }
 
-    // MARK: - Session Control
-
-    func start() {
-        guard !session.isRunning else { return }
-        Task.detached { [session] in
-            session.startRunning()
-        }
+    func start() async {
+        guard !isRunning else { return }
+        await rig.onQueue { [rig] in rig.session.startRunning() }
         isRunning = true
     }
 
-    func stop() {
-        guard session.isRunning else { return }
-        Task.detached { [session] in
-            session.stopRunning()
-        }
+    func stop() async {
+        guard isRunning else { return }
+        await rig.onQueue { [rig] in rig.session.stopRunning() }
         isRunning = false
     }
 
-    // MARK: - Photo Capture
-
-    func capturePhoto() async -> Data? {
-        let settings = AVCapturePhotoSettings()
-        settings.flashMode = flashMode
-
-        if photoOutput.availablePhotoCodecTypes.contains(.hevc) {
-            settings.photoQualityPrioritization = .quality
-        }
-
-        return await withCheckedContinuation { continuation in
-            photoContinuation = continuation
-            photoOutput.capturePhoto(with: settings, delegate: self)
-        }
+    func flipCamera() async {
+        let target: AVCaptureDevice.Position = facing == .back ? .front : .back
+        if await rig.onQueue({ [rig] in rig.swapInput(to: target) }) { facing = target }
     }
 
-    // MARK: - Camera Switching
-
-    func switchCamera() {
-        let newPosition: AVCaptureDevice.Position = (cameraPosition == .back) ? .front : .back
-
-        guard let device = cameraDevice(for: newPosition),
-              let newInput = try? AVCaptureDeviceInput(device: device) else { return }
-
-        session.beginConfiguration()
-        if let currentInput {
-            session.removeInput(currentInput)
-        }
-        if session.canAddInput(newInput) {
-            session.addInput(newInput)
-            currentInput = newInput
-            cameraPosition = newPosition
-        }
-        session.commitConfiguration()
-    }
-
-    // MARK: - Helpers
-
-    private func cameraDevice(for position: AVCaptureDevice.Position) -> AVCaptureDevice? {
-        AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: position)
-    }
-
-    private func requestAccess() async -> Bool {
-        let status = AVCaptureDevice.authorizationStatus(for: .video)
-        if status == .notDetermined {
-            return await AVCaptureDevice.requestAccess(for: .video)
+    func capturePhoto() async -> Data? {
+        guard pendingShot == nil else { return nil }
+        let mode = flash
+        return await withCheckedContinuation { waiter in
+            pendingShot = waiter
+            let output = rig.stills
+            let settings = AVCapturePhotoSettings()
+            settings.flashMode = mode
+            if output.availablePhotoCodecTypes.contains(.hevc) {
+                settings.photoQualityPrioritization = .quality
+            }
+            output.capturePhoto(with: settings, delegate: self)
         }
-        return status == .authorized
     }
 }
 
-// MARK: - AVCapturePhotoCaptureDelegate
-
 @available(iOS 17.0, *)
-extension CameraManager: AVCapturePhotoCaptureDelegate {
-    nonisolated func photoOutput(
-        _ output: AVCapturePhotoOutput,
-        didFinishProcessingPhoto photo: AVCapturePhoto,
-        error: Error?
-    ) {
-        let data = photo.fileDataRepresentation()
+extension StudioCamera: AVCapturePhotoCaptureDelegate {
+    nonisolated func photoOutput(_ sender: AVCapturePhotoOutput,
+                                 didFinishProcessingPhoto photo: AVCapturePhoto,
+                                 error: Error?) {
+        let encoded = photo.fileDataRepresentation()
         Task { @MainActor in
-            lastCapturedPhoto = data
-            photoContinuation?.resume(returning: data)
-            photoContinuation = nil
+            latestShot = encoded
+            pendingShot?.resume(returning: encoded)
+            pendingShot = nil
         }
     }
 }
 ```
 
-The `capturePhoto()` method bridges the delegate-based API to async/await using `CheckedContinuation`. Store only one continuation at a time -- overlapping captures are not supported.
+Points worth keeping:
 
----
+- If any configuration step fails, record the message and still commit the
+  configuration; the `defer` above does that.
+- `maxPhotoDimensions` (iOS 16+) must be one of the active format's
+  `supportedMaxPhotoDimensions`; the largest gives full-resolution stills.
+  Set `maxPhotoQualityPrioritization` before capturing, since a per-shot
+  prioritization cannot exceed it.
+- Only one shot may be in flight: the model stores a single continuation and
+  refuses a second request until the first resumes.
+- Switching cameras removes the current input and adds the new one inside a
+  single configuration block.
+- The session is never captured by a detached task from the main actor. Swift
+  6 rejects sending a main-actor-owned non-`Sendable` value that way; the rig's
+  queue is the single place the session is touched.
 
-## 2. Camera Preview (UIViewRepresentable)
+## 2. Preview view
 
 ```swift
-import SwiftUI
-import AVFoundation
-
-struct CameraPreview: UIViewRepresentable {
+struct CameraSurface: UIViewRepresentable {
     let session: AVCaptureSession
+    var onFocusTap: ((CGPoint, AVCaptureVideoPreviewLayer) -> Void)?
 
-    func makeUIView(context: Context) -> CameraPreviewView {
-        let view = CameraPreviewView()
-        view.previewLayer.session = session
-        view.previewLayer.videoGravity = .resizeAspectFill
-        return view
+    final class Surface: UIView {
+        override static var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
+        var feed: AVCaptureVideoPreviewLayer { unsafeDowncast(layer, to: AVCaptureVideoPreviewLayer.self) }
     }
 
-    func updateUIView(_ uiView: CameraPreviewView, context: Context) {
-        if uiView.previewLayer.session !== session {
-            uiView.previewLayer.session = session
-        }
+    func makeUIView(context: Context) -> Surface {
+        let surface = Surface()
+        surface.feed.session = session
+        surface.feed.videoGravity = .resizeAspectFill
+        let relay = context.coordinator
+        surface.addGestureRecognizer(UITapGestureRecognizer(target: relay, action: #selector(Coordinator.tapped(_:))))
+        return surface
     }
-}
 
-/// Custom UIView that uses AVCaptureVideoPreviewLayer as its backing layer.
-/// Overriding layerClass ensures the preview layer resizes automatically with the view.
-final class CameraPreviewView: UIView {
-    override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
+    func updateUIView(_ surface: Surface, context: Context) {
+        context.coordinator.onFocusTap = onFocusTap
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+
+    @MainActor
+    final class Coordinator: NSObject {
+        var onFocusTap: ((CGPoint, AVCaptureVideoPreviewLayer) -> Void)?
 
-    var previewLayer: AVCaptureVideoPreviewLayer {
-        layer as! AVCaptureVideoPreviewLayer
+        @objc func tapped(_ gesture: UITapGestureRecognizer) {
+            guard let surface = gesture.view as? Surface else { return }
+            onFocusTap?(gesture.location(in: surface), surface.feed)
+        }
     }
 }
 ```
 
-Never add `AVCaptureVideoPreviewLayer` as a sublayer manually. Using `layerClass` avoids manual frame management in `layoutSubviews`.
-
----
+With `layerClass` returning the preview layer class, the preview is the view's
+own layer and resizes with it. Do not insert an `AVCaptureVideoPreviewLayer`
+as a sublayer and then chase its frame in `layoutSubviews`.
+The coordinator is `@MainActor`: the tap arrives on the main thread, and
+reading `gesture.view` or the surface's layer from a nonisolated class is a
+Swift 6 isolation warning.
 
-## 3. Complete Camera Screen in SwiftUI
+## 3. Camera screen
 
 ```swift
-import SwiftUI
-
 @available(iOS 17.0, *)
-struct CameraScreen: View {
-    @State private var camera = CameraManager()
-    @State private var showCapturedPhoto = false
+struct StudioScreen: View {
+    @State private var camera = StudioCamera()
+    @State private var reviewing = false
 
     var body: some View {
         ZStack {
-            CameraPreview(session: camera.session)
-                .ignoresSafeArea()
-
+            CameraSurface(session: camera.rig.session).ignoresSafeArea()
             VStack {
-                // Top controls
                 HStack {
-                    Button {
-                        camera.switchCamera()
-                    } label: {
-                        Image(systemName: "camera.rotate")
-                            .font(.title2)
-                            .padding()
-                            .background(.ultraThinMaterial, in: Circle())
-                    }
-
+                    roundButton("camera.rotate") { Task { await camera.flipCamera() } }
                     Spacer()
-
-                    // Flash toggle
-                    Button {
-                        camera.flashMode = (camera.flashMode == .off) ? .auto : .off
-                    } label: {
-                        Image(systemName: camera.flashMode == .off
-                              ? "bolt.slash.fill" : "bolt.fill")
-                            .font(.title2)
-                            .padding()
-                            .background(.ultraThinMaterial, in: Circle())
+                    roundButton(camera.flash == .auto ? "bolt.fill" : "bolt.slash.fill") {
+                        camera.flash = camera.flash == .off ? .auto : .off
                     }
                 }
-                .padding(.horizontal)
-
                 Spacer()
-
-                // Bottom controls
                 HStack {
-                    // Thumbnail of last capture
-                    if let data = camera.lastCapturedPhoto,
-                       let uiImage = UIImage(data: data) {
-                        Button { showCapturedPhoto = true } label: {
-                            Image(uiImage: uiImage)
-                                .resizable()
-                                .scaledToFill()
-                                .frame(width: 50, height: 50)
-                                .clipShape(.rect(cornerRadius: 8))
-                        }
-                    } else {
-                        Color.clear.frame(width: 50, height: 50)
-                    }
-
+                    thumbnail.onTapGesture { reviewing = camera.latestShot != nil }
                     Spacer()
-
-                    // Shutter button
-                    Button {
-                        Task { _ = await camera.capturePhoto() }
-                    } label: {
-                        ZStack {
-                            Circle().fill(.white).frame(width: 72, height: 72)
-                            Circle().stroke(.gray, lineWidth: 3).frame(width: 78, height: 78)
-                        }
+                    Button(action: shoot) {
+                        Circle().frame(width: 72, height: 72).foregroundStyle(.white)
+                            .overlay { Circle().strokeBorder(lineWidth: 3).foregroundStyle(.white).frame(width: 78, height: 78) }
                     }
-
                     Spacer()
-
-                    Color.clear.frame(width: 50, height: 50)
+                    Color.clear.frame(width: 50)
                 }
-                .padding(.horizontal)
-                .padding(.bottom)
             }
+            .padding()
         }
         .task {
             await camera.configure()
-            camera.start()
+            await camera.start()
         }
-        .onDisappear {
-            camera.stop()
+        .onDisappear { Task { await camera.stop() } }
+        .sheet(isPresented: $reviewing) {
+            if let shot = camera.latestShot, let image = UIImage(data: shot) {
+                Image(uiImage: image).resizable().scaledToFit()
+            }
         }
-        .sheet(isPresented: $showCapturedPhoto) {
-            if let data = camera.lastCapturedPhoto,
-               let uiImage = UIImage(data: data) {
-                Image(uiImage: uiImage)
-                    .resizable()
-                    .scaledToFit()
+    }
+
+    private func shoot() {
+        Task { _ = await camera.capturePhoto() }
+    }
+
+    private var thumbnail: some View {
+        Group {
+            if let shot = camera.latestShot, let image = UIImage(data: shot) {
+                Image(uiImage: image).resizable().scaledToFill()
+            } else {
+                Color.gray.opacity(0.3)
             }
         }
+        .frame(width: 50, height: 50)
+        .clipShape(.rect(cornerRadius: 8))
+    }
+
+    private func roundButton(_ symbol: String, action: @escaping () -> Void) -> some View {
+        Button(action: action) {
+            Image(systemName: symbol).padding(12).background(.ultraThinMaterial, in: Circle())
+        }
     }
 }
 ```
 
----
+## 4. Recording video
 
-## 4. Video Recording
-
-Add `AVCaptureMovieFileOutput` for video capture. Video recording requires `NSMicrophoneUsageDescription` in Info.plist for audio.
+Movies go through `AVCaptureMovieFileOutput`. Sound needs
+`NSMicrophoneUsageDescription`.
 
 ```swift
-import AVFoundation
-
-@available(iOS 17.0, *)
-@Observable
-@MainActor
-final class VideoRecorder: NSObject {
+final class MovieRig: @unchecked Sendable {
     let session = AVCaptureSession()
+    let movies = AVCaptureMovieFileOutput()
+    private let queue = DispatchQueue(label: "movie.rig")
 
-    private let movieOutput = AVCaptureMovieFileOutput()
-    private var videoContinuation: CheckedContinuation<URL?, Never>?
-
-    var isRecording = false
-    var recordedVideoURL: URL?
-    var error: String?
-
-    func configure() async {
-        guard await requestAccess() else {
-            error = "Camera access denied"
-            return
-        }
+    func onQueue<T: Sendable>(_ work: @escaping @Sendable () -> T) async -> T {
+        await withCheckedContinuation { done in queue.async { done.resume(returning: work()) } }
+    }
 
+    func assemble() -> Bool {
         session.beginConfiguration()
+        defer { session.commitConfiguration() }
         session.sessionPreset = .high
-
-        // Video input
-        guard let videoDevice = AVCaptureDevice.default(.builtInWideAngleCamera,
-                                                         for: .video, position: .back),
-              let videoInput = try? AVCaptureDeviceInput(device: videoDevice),
-              session.canAddInput(videoInput) else {
-            session.commitConfiguration()
-            return
-        }
-        session.addInput(videoInput)
-
-        // Audio input
-        if let audioDevice = AVCaptureDevice.default(for: .audio),
-           let audioInput = try? AVCaptureDeviceInput(device: audioDevice),
-           session.canAddInput(audioInput) {
-            session.addInput(audioInput)
-        }
-
-        // Movie output
-        guard session.canAddOutput(movieOutput) else {
-            session.commitConfiguration()
-            return
-        }
-        session.addOutput(movieOutput)
-
-        session.commitConfiguration()
-    }
-
-    func startRecording() {
-        guard !isRecording else { return }
-
-        let outputURL = FileManager.default.temporaryDirectory
-            .appendingPathComponent(UUID().uuidString)
-            .appendingPathExtension("mov")
-
-        movieOutput.startRecording(to: outputURL, recordingDelegate: self)
-        isRecording = true
+        guard let lens = AVCaptureDevice.default(.builtInWideAngleCamera, for: AVMediaType.video, position: .back),
+              let picture = try? AVCaptureDeviceInput(device: lens),
+              session.canAddInput(picture) else { return false }
+        session.addInput(picture)
+        if let mic = AVCaptureDevice.default(for: .audio),
+           let sound = try? AVCaptureDeviceInput(device: mic),
+           session.canAddInput(sound) {
+            session.addInput(sound)
+        }
+        guard session.canAddOutput(movies) else { return false }
+        session.addOutput(movies)
+        return true
     }
+}
 
-    func stopRecording() async -> URL? {
-        guard isRecording else { return nil }
+@available(iOS 17.0, *)
+@Observable @MainActor
+final class ClipRecorder: NSObject {
+    private(set) var isRecording = false
+    private(set) var hasMicrophone = true
+    @ObservationIgnored let rig = MovieRig()
+    @ObservationIgnored private var finishing: CheckedContinuation<URL?, Never>?
 
-        return await withCheckedContinuation { continuation in
-            videoContinuation = continuation
-            movieOutput.stopRecording()
+    func prepare() async -> Bool {
+        if AVCaptureDevice.authorizationStatus(for: .audio) == .notDetermined {
+            hasMicrophone = await AVCaptureDevice.requestAccess(for: .audio)
         }
+        guard await CameraAccess.isGranted() else { return false }
+        return await rig.onQueue { [rig] in rig.assemble() }
     }
 
-    func start() {
-        Task.detached { [session] in session.startRunning() }
-    }
-
-    func stop() {
-        Task.detached { [session] in session.stopRunning() }
+    func beginRecording() {
+        let target = URL.temporaryDirectory.appending(path: "\(UUID().uuidString).mov")
+        rig.movies.startRecording(to: target, recordingDelegate: self)
+        isRecording = true
     }
 
-    private func requestAccess() async -> Bool {
-        let videoStatus = AVCaptureDevice.authorizationStatus(for: .video)
-        let videoGranted: Bool
-        if videoStatus == .notDetermined {
-            videoGranted = await AVCaptureDevice.requestAccess(for: .video)
-        } else {
-            videoGranted = videoStatus == .authorized
-        }
-
-        // Also request audio for video recording
-        let audioStatus = AVCaptureDevice.authorizationStatus(for: .audio)
-        if audioStatus == .notDetermined {
-            _ = await AVCaptureDevice.requestAccess(for: .audio)
+    func endRecording() async -> URL? {
+        await withCheckedContinuation { waiter in
+            finishing = waiter
+            rig.movies.stopRecording()
         }
-
-        return videoGranted
     }
 }
 
 @available(iOS 17.0, *)
-extension VideoRecorder: AVCaptureFileOutputRecordingDelegate {
-    nonisolated func fileOutput(
-        _ output: AVCaptureFileOutput,
-        didFinishRecordingTo outputFileURL: URL,
-        from connections: [AVCaptureConnection],
-        error: Error?
-    ) {
+extension ClipRecorder: AVCaptureFileOutputRecordingDelegate {
+    nonisolated func fileOutput(_ recorder: AVCaptureFileOutput,
+                                didFinishRecordingTo outputFileURL: URL,
+                                from connections: [AVCaptureConnection],
+                                error: Error?) {
+        let finished = error == nil ? outputFileURL : nil
         Task { @MainActor in
             isRecording = false
-            recordedVideoURL = error == nil ? outputFileURL : nil
-            videoContinuation?.resume(returning: error == nil ? outputFileURL : nil)
-            videoContinuation = nil
+            finishing?.resume(returning: finished)
+            finishing = nil
         }
     }
 }
 ```
 
-Clean up temporary video files when they are no longer needed. Recorded videos can be large and the temporary directory is not automatically cleaned during the app's lifetime.
-
----
+Microphone access is requested alongside the camera, but only the camera answer
+decides whether recording can go ahead. Delete temporary movies as soon as they
+are no longer needed. Movie files are large, and nothing clears that folder
+for you while the app is alive.
 
-## 5. Flash and Torch Control
+## 5. Flash and torch
 
-Flash applies to photo capture settings. Torch provides continuous illumination for video or preview.
+Flash is a per-shot setting on `AVCapturePhotoSettings`. The torch is a steady
+light for video or for the preview.
 
 ```swift
-import AVFoundation
-
-func toggleTorch(on device: AVCaptureDevice, enabled: Bool) throws {
-    guard device.hasTorch, device.isTorchAvailable else { return }
-
+func setLamp(_ on: Bool, on device: AVCaptureDevice) throws {
+    guard device.isTorchAvailable, device.hasTorch else { return }
     try device.lockForConfiguration()
-    device.torchMode = enabled ? .on : .off
-    if enabled {
-        try device.setTorchModeOn(level: AVCaptureDevice.maxAvailableTorchLevel)
+    defer { device.unlockForConfiguration() }
+    if on {
+        let brightest = AVCaptureDevice.maxAvailableTorchLevel
+        try device.setTorchModeOn(level: brightest)
+    } else {
+        device.torchMode = .off
     }
-    device.unlockForConfiguration()
 }
 ```
 
-Always wrap device configuration in `lockForConfiguration()` / `unlockForConfiguration()`. Multiple clients may attempt to configure the device simultaneously.
-
----
+Wrap every device change in `lockForConfiguration()` and
+`unlockForConfiguration()`; other clients can be configuring the same device.
 
-## 6. Focus and Exposure
-
-Implement tap-to-focus by converting a SwiftUI tap location to the camera coordinate system.
+## 6. Tap to focus and expose
 
 ```swift
-import AVFoundation
-
-func setFocusAndExposure(
-    at point: CGPoint,
-    in previewLayer: AVCaptureVideoPreviewLayer,
-    device: AVCaptureDevice
-) throws {
-    let devicePoint = previewLayer.captureDevicePointConverted(fromLayerPoint: point)
-
+func focusAndExpose(at viewPoint: CGPoint, in feed: AVCaptureVideoPreviewLayer, device: AVCaptureDevice) throws {
+    let devicePoint = feed.captureDevicePointConverted(fromLayerPoint: viewPoint)
     try device.lockForConfiguration()
-
+    defer { device.unlockForConfiguration() }
     if device.isFocusPointOfInterestSupported {
         device.focusPointOfInterest = devicePoint
         device.focusMode = .autoFocus
     }
-
     if device.isExposurePointOfInterestSupported {
         device.exposurePointOfInterest = devicePoint
         device.exposureMode = .autoExpose
     }
-
-    device.unlockForConfiguration()
 }
 ```
 
-### Integrating Tap-to-Focus in SwiftUI
-
-```swift
-struct FocusableCameraPreview: UIViewRepresentable {
-    let session: AVCaptureSession
-    var onTapToFocus: ((CGPoint, AVCaptureVideoPreviewLayer) -> Void)?
-
-    func makeUIView(context: Context) -> CameraPreviewView {
-        let view = CameraPreviewView()
-        view.previewLayer.session = session
-        view.previewLayer.videoGravity = .resizeAspectFill
+`CameraSurface` above installs a `UITapGestureRecognizer` whose `@objc`
+handler converts `gesture.location(in:)` and passes it, with the preview layer,
+to the `onFocusTap` closure.
 
-        let tap = UITapGestureRecognizer(
-            target: context.coordinator,
-            action: #selector(Coordinator.handleTap(_:))
-        )
-        view.addGestureRecognizer(tap)
-
-        return view
-    }
-
-    func updateUIView(_ uiView: CameraPreviewView, context: Context) {}
-
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
-
-    final class Coordinator: NSObject {
-        var parent: FocusableCameraPreview
-
-        init(_ parent: FocusableCameraPreview) { self.parent = parent }
-
-        @objc func handleTap(_ gesture: UITapGestureRecognizer) {
-            guard let view = gesture.view as? CameraPreviewView else { return }
-            let point = gesture.location(in: view)
-            parent.onTapToFocus?(point, view.previewLayer)
-        }
-    }
-}
-```
-
----
-
-## 7. Barcode and QR Code Scanning
-
-Use `AVCaptureMetadataOutput` to detect barcodes and QR codes from the camera feed.
+## 7. Barcodes and QR codes
 
 ```swift
-import AVFoundation
-
 @available(iOS 17.0, *)
-@Observable
-@MainActor
-final class QRCodeScanner: NSObject {
-    let session = AVCaptureSession()
-
-    private let metadataOutput = AVCaptureMetadataOutput()
-
-    var scannedCode: String?
-    var isScanning = false
-
-    func configure() async {
-        guard await requestAccess() else { return }
-
+@Observable @MainActor
+final class TicketScanner: NSObject, AVCaptureMetadataOutputObjectsDelegate {
+    private(set) var payload: String?
+    private(set) var isScanning = false
+    @ObservationIgnored let rig = CameraRig()
+    @ObservationIgnored private let codes = AVCaptureMetadataOutput()
+
+    func configure() {
+        let session = rig.session
         session.beginConfiguration()
-
-        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera,
-                                                    for: .video, position: .back),
-              let input = try? AVCaptureDeviceInput(device: device),
-              session.canAddInput(input) else {
-            session.commitConfiguration()
-            return
-        }
+        defer { session.commitConfiguration() }
+        guard let lens = AVCaptureDevice.default(for: .video),
+              let input = try? AVCaptureDeviceInput(device: lens),
+              session.canAddInput(input), session.canAddOutput(codes) else { return }
         session.addInput(input)
-
-        guard session.canAddOutput(metadataOutput) else {
-            session.commitConfiguration()
-            return
-        }
-        session.addOutput(metadataOutput)
-
-        // Set metadata types AFTER adding to session -- available types depend on session config
-        metadataOutput.metadataObjectTypes = [.qr, .ean8, .ean13, .code128, .code39]
-        metadataOutput.setMetadataObjectsDelegate(self, queue: .main)
-
-        session.commitConfiguration()
+        session.addOutput(codes)
+        codes.metadataObjectTypes = [.qr, .ean13, .ean8, .code39, .code128]
+        codes.setMetadataObjectsDelegate(self, queue: .main)
     }
 
-    func start() {
-        scannedCode = nil
+    func start() async {
+        payload = nil
         isScanning = true
-        Task.detached { [session] in session.startRunning() }
+        await rig.onQueue { [rig] in rig.session.startRunning() }
     }
 
-    func stop() {
-        isScanning = false
-        Task.detached { [session] in session.stopRunning() }
-    }
-
-    private func requestAccess() async -> Bool {
-        let status = AVCaptureDevice.authorizationStatus(for: .video)
-        if status == .notDetermined {
-            return await AVCaptureDevice.requestAccess(for: .video)
-        }
-        return status == .authorized
-    }
-}
-
-@available(iOS 17.0, *)
-extension QRCodeScanner: AVCaptureMetadataOutputObjectsDelegate {
-    nonisolated func metadataOutput(
-        _ output: AVCaptureMetadataOutput,
-        didOutput metadataObjects: [AVMetadataObject],
-        from connection: AVCaptureConnection
-    ) {
-        guard let object = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
-              let value = object.stringValue else { return }
-
+    nonisolated func metadataOutput(_ reader: AVCaptureMetadataOutput,
+                                    didOutput metadataObjects: [AVMetadataObject],
+                                    from connection: AVCaptureConnection) {
+        guard let code = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
+              let text = code.stringValue else { return }
         Task { @MainActor in
-            scannedCode = value
-            stop()
-        }
-    }
-}
-```
-
-### Scanner View
-
-```swift
-@available(iOS 17.0, *)
-struct QRScannerView: View {
-    @State private var scanner = QRCodeScanner()
-
-    var body: some View {
-        ZStack {
-            CameraPreview(session: scanner.session)
-                .ignoresSafeArea()
-
-            // Scanning overlay
-            RoundedRectangle(cornerRadius: 12)
-                .stroke(.white, lineWidth: 2)
-                .frame(width: 250, height: 250)
-
-            if let code = scanner.scannedCode {
-                VStack {
-                    Spacer()
-                    Text(code)
-                        .font(.headline)
-                        .padding()
-                        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 12))
-                        .padding(.bottom)
-                }
-            }
-        }
-        .task {
-            await scanner.configure()
-            scanner.start()
-        }
-        .onDisappear {
-            scanner.stop()
+            payload = text
+            isScanning = false
+            await rig.onQueue { [rig] in rig.session.stopRunning() }
         }
     }
 }
 ```
 
-Set `metadataObjectTypes` after adding the output to the session. Setting types before causes a runtime crash because the available types are not yet determined.
-
----
+Building this small graph on the main actor is quick; starting and stopping
+still go through the rig's queue. Set `metadataObjectTypes` only after the
+output is part of the session. Before
+that the output knows no available types and assigning them crashes.
 
-## 8. Camera Preview Orientation
+A scanner screen is the preview with a 250 by 250 rounded rectangle stroked in
+white over the center, plus the decoded text on a material background once
+`payload` is set.
 
-Handle device rotation so the preview and captured photos have correct orientation.
+## 8. Orientation
 
-### Preview Layer Rotation
+On iOS 17 and later, rotation is an angle on the connection. `videoOrientation`
+is deprecated.
 
 ```swift
-import AVFoundation
-import UIKit
-
-func updatePreviewOrientation(
-    _ previewLayer: AVCaptureVideoPreviewLayer,
-    for interfaceOrientation: UIInterfaceOrientation
-) {
-    guard let connection = previewLayer.connection else { return }
-
-    // iOS 17+: use videoRotationAngle
-    if #available(iOS 17.0, *) {
-        let angle: CGFloat
-        switch interfaceOrientation {
-        case .portrait: angle = 90
-        case .portraitUpsideDown: angle = 270
-        case .landscapeLeft: angle = 180
-        case .landscapeRight: angle = 0
-        default: angle = 90
-        }
-        if connection.isVideoRotationAngleSupported(angle) {
-            connection.videoRotationAngle = angle
-        }
-    }
-}
-```
-
-### Photo Output Orientation
-
-Set the rotation angle on the photo output connection before each capture to ensure the captured image matches the device orientation:
-
-```swift
-func capturePhotoWithOrientation() {
-    if let connection = photoOutput.connection(with: .video) {
-        // iOS 17+
-        if #available(iOS 17.0, *) {
-            let angle = currentVideoRotationAngle()
-            if connection.isVideoRotationAngleSupported(angle) {
-                connection.videoRotationAngle = angle
-            }
-        }
+@MainActor
+func currentRotationAngle() -> CGFloat {
+    let scene = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }.first
+    switch scene?.effectiveGeometry.interfaceOrientation {
+    case .landscapeRight: return 0
+    case .landscapeLeft: return 180
+    case .portraitUpsideDown: return 270
+    default: return 90
     }
-
-    let settings = AVCapturePhotoSettings()
-    photoOutput.capturePhoto(with: settings, delegate: self)
 }
 
-private func currentVideoRotationAngle() -> CGFloat {
-    guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
-        return 90
+@MainActor
+func applyRotation(preview: AVCaptureVideoPreviewLayer, stills: AVCapturePhotoOutput) {
+    let angle = currentRotationAngle()
+    if let feed = preview.connection, feed.isVideoRotationAngleSupported(angle) {
+        feed.videoRotationAngle = angle
     }
-    switch scene.interfaceOrientation {
-    case .portrait: return 90
-    case .portraitUpsideDown: return 270
-    case .landscapeLeft: return 180
-    case .landscapeRight: return 0
-    default: return 90
+    if let still = stills.connection(with: .video), still.isVideoRotationAngleSupported(angle) {
+        still.videoRotationAngle = angle
     }
 }
 ```
 
-Use `videoRotationAngle` (iOS 17+) instead of the deprecated `videoOrientation` property. The angle is measured in degrees clockwise from landscape-right (the natural sensor orientation).
+- Read the orientation from `effectiveGeometry.interfaceOrientation` (iOS 16).
+  `UIWindowScene.interfaceOrientation` is deprecated as of iOS 26.
+- The angle is in degrees, clockwise, counted from landscape-right, which is
+  the sensor's native orientation. Only 0, 90, 180 and 270 are accepted.
+- Update the photo output's connection before each shot so the saved image
+  matches how the device was held.
+- `AVCaptureDeviceRotationCoordinator` (iOS 17) can supply the preview and
+  capture angles for a device and preview layer, and tracks changes for you.
 
----
-
-## 9. Dual Camera and Device Discovery
-
-Select specific camera hardware using `AVCaptureDevice.DiscoverySession`.
+## 9. Choosing specific cameras
 
 ```swift
-import AVFoundation
-
-func availableCameras() -> [AVCaptureDevice] {
-    let discoverySession = AVCaptureDevice.DiscoverySession(
-        deviceTypes: [
-            .builtInWideAngleCamera,
-            .builtInUltraWideCamera,
-            .builtInTelephotoCamera,
-            .builtInDualCamera,
-            .builtInTripleCamera
-        ],
+func allCameras() -> [AVCaptureDevice] {
+    AVCaptureDevice.DiscoverySession(
+        deviceTypes: [.builtInWideAngleCamera, .builtInUltraWideCamera, .builtInTelephotoCamera,
+                      .builtInDualCamera, .builtInTripleCamera],
         mediaType: .video,
         position: .unspecified
-    )
-    return discoverySession.devices
+    ).devices
 }
 
-func preferredBackCamera() -> AVCaptureDevice? {
-    // Prefer triple > dual > wide angle
-    let session = AVCaptureDevice.DiscoverySession(
+func bestRearCamera() -> AVCaptureDevice? {
+    AVCaptureDevice.DiscoverySession(
         deviceTypes: [.builtInTripleCamera, .builtInDualCamera, .builtInWideAngleCamera],
         mediaType: .video,
         position: .back
-    )
-    return session.devices.first
+    ).devices.first
 }
 ```
 
----
+`.unspecified` returns cameras on both sides. The order of `deviceTypes` is the
+preference order, so the rear query prefers triple, then dual, then wide.
 
-## 10. Restricting Scan Region
+## 10. Limiting the scan area
 
-Limit the metadata detection area to improve performance and UX:
+`rectOfInterest` on the metadata output shrinks the searched region, which is
+faster and keeps stray codes out. A rectangle with origin (0.2, 0.2) and size
+0.6 by 0.6 covers the middle 60 percent.
 
 ```swift
-// Restrict detection to center 60% of the preview
-metadataOutput.rectOfInterest = CGRect(x: 0.2, y: 0.2, width: 0.6, height: 0.6)
+@MainActor
+func restrictScan(_ codes: AVCaptureMetadataOutput, to box: CGRect, in feed: AVCaptureVideoPreviewLayer) {
+    codes.rectOfInterest = feed.metadataOutputRectConverted(fromLayerRect: box)
+}
 ```
 
-Note that `rectOfInterest` uses the camera coordinate system (landscape, origin top-left). Convert from preview coordinates using `previewLayer.metadataOutputRectConverted(fromLayerRect:)`.
+The rectangle lives in normalized camera coordinates: landscape, origin at the
+top left, values from 0 to 1. Convert from preview coordinates with
+`metadataOutputRectConverted(fromLayerRect:)` rather than guessing.