fix: settings form alignment — grouped form, aligned labels

Add ReturnsList (newest-first, max 8, click-to-Finder, hidden when empty)
and SettingsView (hotkey row, folder Choose… via FolderSettings + AppModel
seam mutators, async updateWatchFolder(url) only).

Sources/Shotdeck/AppModel.swift

@@ -0,0 +1,265 @@
+import AppKit
+import Carbon.HIToolbox
+import Foundation
+import Observation
+import SwiftUI
+import ShotdeckCore
+
+@MainActor
+public protocol SendCapable: AnyObject {
+    func send(anchor: NSView?) async
+}
+
+@MainActor
+public protocol SettingsWindowPresenting: AnyObject {
+    func presentSettingsWindow()
+}
+
+@MainActor
+public protocol ReturnsSectionProviding: AnyObject {
+    @ViewBuilder func returnsSection() -> AnyView
+}
+
+@MainActor
+@Observable
+public final class AppModel {
+    public private(set) var session: CaptureSession
+    public private(set) var region: CaptureRegion?
+    public private(set) var screenRecordingGranted: Bool
+    public private(set) var allReturns: [ReturnedDocument] = []
+    public private(set) var commentedReturns: [ReturnedDocument] = []
+    public private(set) var statusLine: String?
+    public private(set) var isCapturing: Bool = false
+    public private(set) var isSending: Bool = false
+    public private(set) var outboxDisplayName: String
+    public private(set) var watchFolderDisplayName: String
+    /// Live outbox; WP-4b reads this (not `paths.outbox`) so Settings folder changes take effect.
+    public private(set) var outboxURL: URL
+    /// Live watch folder; WP-4c updates this alongside `ReturnWatcher.updateWatchFolder`.
+    public private(set) var watchFolderURL: URL
+
+    let paths: AppSupportPaths
+    let spool: SpoolStore
+    let composer: PDFComposer
+    let capturer: ScreenCapturer
+    let hotkeys: HotkeyCenter
+    let picker: RegionPickerController
+    let ledger: ReturnLedger
+    let watcher: ReturnWatcher
+
+    public init(
+        paths: AppSupportPaths,
+        spool: SpoolStore,
+        composer: PDFComposer,
+        capturer: ScreenCapturer,
+        hotkeys: HotkeyCenter,
+        picker: RegionPickerController,
+        ledger: ReturnLedger,
+        watcher: ReturnWatcher
+    ) {
+        self.paths = paths
+        self.spool = spool
+        self.composer = composer
+        self.capturer = capturer
+        self.hotkeys = hotkeys
+        self.picker = picker
+        self.ledger = ledger
+        self.watcher = watcher
+        self.session = CaptureSession(
+            id: UUID(),
+            createdAt: Date(),
+            state: .open,
+            captures: [],
+            pdfFileName: nil
+        )
+        self.region = nil
+        self.screenRecordingGranted = ScreenCapturer.isScreenRecordingGranted
+        // Seeded from FolderSettings.resolve() via resolvedAppSupportPaths — never .standard().
+        let folders = FolderSettings.resolve()
+        self.outboxURL = folders.outbox
+        self.watchFolderURL = folders.watch
+        self.outboxDisplayName = folders.outbox.lastPathComponent
+        self.watchFolderDisplayName = folders.watch.lastPathComponent
+    }
+
+    // MARK: Seam mutators — the only way a WP-4b/4c extension changes state.
+
+    func setStatus(_ text: String?) { statusLine = text }
+    func setSending(_ value: Bool) { isSending = value }
+    func setCapturing(_ value: Bool) { isCapturing = value }
+    func replaceSession(_ new: CaptureSession) { session = new }
+    func replaceRegion(_ new: CaptureRegion?) { region = new }
+    func setReturns(all: [ReturnedDocument], commented: [ReturnedDocument]) {
+        allReturns = all
+        commentedReturns = commented
+    }
+    func setFolderDisplayNames(outbox: String, watch: String) {
+        outboxDisplayName = outbox
+        watchFolderDisplayName = watch
+    }
+    func setFolderURLs(outbox: URL, watch: URL) {
+        outboxURL = outbox
+        watchFolderURL = watch
+        setFolderDisplayNames(outbox: outbox.lastPathComponent, watch: watch.lastPathComponent)
+    }
+
+    public var iconState: MenuIconState {
+        if !screenRecordingGranted { return .recordingMissing }
+        if isCapturing { return .capturing }
+        if region == nil { return .noRegion }
+        if session.captures.isEmpty { return .regionEmpty }
+        return .hasCaptures(session.captures.count)
+    }
+
+    public func bootstrap() async {
+        if let data = UserDefaults.standard.data(forKey: CaptureRegion.defaultsKey),
+           let decoded = try? JSONDecoder().decode(CaptureRegion.self, from: data),
+           decoded.isStillValid {
+            replaceRegion(decoded)
+        }
+
+        do {
+            let recovered = try await spool.currentSession()
+            replaceSession(recovered)
+        } catch {
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "Could not open the spool.")
+        }
+
+        do {
+            let initial = try await ledger.all()
+            let commented = try await ledger.commented()
+            setReturns(all: initial, commented: commented)
+        } catch {
+            // Empty ledger on first run is not an error.
+        }
+
+        do {
+            try await watcher.start { [weak self] _ in
+                Task { @MainActor in
+                    guard let self else { return }
+                    let all = (try? await self.ledger.all()) ?? []
+                    let commented = (try? await self.ledger.commented()) ?? []
+                    self.setReturns(all: all, commented: commented)
+                }
+            }
+        } catch {
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "Could not watch the return folder.")
+        }
+
+        let registered = hotkeys.register(
+            id: "capture",
+            keyCode: UInt32(kVK_ANSI_2),
+            modifiers: UInt32(optionKey | shiftKey)
+        ) { [weak self] in
+            Task { await self?.captureNow() }
+        }
+        if !registered {
+            setStatus("⌥⇧2 is already used by another app — capture only works from the menu.")
+        }
+    }
+
+    public func captureNow() async {
+        guard !isCapturing else { return }
+        setCapturing(true)
+        defer { setCapturing(false) }
+
+        var target = region
+        if target == nil {
+            target = await withCheckedContinuation { (cont: CheckedContinuation<CaptureRegion?, Never>) in
+                picker.pick { picked in cont.resume(returning: picked) }
+            }
+            guard let picked = target else {
+                setStatus("No region selected.")
+                return
+            }
+            persistRegion(picked)
+        }
+        guard let region = target else { return }
+
+        do {
+            let image = try await capturer.capture(region)
+            let capture = try await spool.append(
+                pngData: image.pngData,
+                pixelWidth: image.pixelWidth,
+                pixelHeight: image.pixelHeight,
+                scale: image.scale,
+                capturedAt: Date()
+            )
+            replaceSession(try await spool.currentSession())
+            setStatus("Captured page \(capture.sequence).")
+        } catch {
+            screenRecordingGranted = ScreenCapturer.isScreenRecordingGranted
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "The screenshot could not be taken.")
+        }
+    }
+
+    public func rePickRegion() async {
+        let picked = await withCheckedContinuation { (cont: CheckedContinuation<CaptureRegion?, Never>) in
+            picker.pick { cont.resume(returning: $0) }
+        }
+        guard let picked else { return }
+        persistRegion(picked)
+        setStatus("Region set: \(Int(picked.rect.width)) × \(Int(picked.rect.height)).")
+    }
+
+    public func removeCapture(id: UUID) async {
+        do {
+            // D-11: SpoolStore.remove MOVES the PNG to <session>/removed/; it is never unlinked.
+            replaceSession(try await spool.remove(captureID: id))
+        } catch {
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "Could not remove that capture.")
+        }
+    }
+
+    public func copyCommentedLinks() async {
+        do {
+            let text = try await ledger.clipboardText()
+            let pasteboard = NSPasteboard.general
+            pasteboard.clearContents()
+            pasteboard.setString(text, forType: .string)
+            let count = commentedReturns.count
+            setStatus("Copied \(count) link\(count == 1 ? "" : "s").")
+        } catch {
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "Nothing to copy.")
+        }
+    }
+
+    public func openSpoolFolder() {
+        NSWorkspace.shared.open(paths.spool)
+    }
+
+    public func openScreenRecordingSettings() {
+        guard let url = URL(string:
+            "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture") else {
+            setStatus("Could not open System Settings.")
+            return
+        }
+        NSWorkspace.shared.open(url)
+    }
+
+    private func persistRegion(_ picked: CaptureRegion) {
+        replaceRegion(picked)
+        if let encoded = try? JSONEncoder().encode(picked) {
+            UserDefaults.standard.set(encoded, forKey: CaptureRegion.defaultsKey)
+        }
+    }
+}
+
+public enum MenuIconState: Equatable {
+    case noRegion, regionEmpty, hasCaptures(Int), capturing, recordingMissing
+
+    public var symbolName: String {
+        switch self {
+        case .noRegion: return "viewfinder"
+        case .regionEmpty: return "viewfinder.rectangular"
+        case .hasCaptures: return "viewfinder.rectangular"
+        case .capturing: return "viewfinder.circle.fill"
+        case .recordingMissing: return "exclamationmark.triangle"
+        }
+    }
+
+    public var countText: String? {
+        if case .hasCaptures(let n) = self { return "\(n)" }
+        return nil
+    }
+}

Sources/Shotdeck/MenuBarView.swift

@@ -0,0 +1,180 @@
+import AppKit
+import SwiftUI
+import ShotdeckCore
+
+struct MenuBarView: View {
+    @Environment(AppModel.self) private var model
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            statusRow
+            SessionStrip()
+            Divider()
+            actionsList
+            if !model.allReturns.isEmpty {
+                Divider()
+                returnsBlock
+            }
+        }
+        .padding(10)
+        .frame(width: 320, alignment: .leading)
+        .controlSize(.small)
+    }
+
+    @ViewBuilder
+    private var statusRow: some View {
+        if !model.screenRecordingGranted {
+            HStack(alignment: .top, spacing: 6) {
+                Image(systemName: "exclamationmark.triangle")
+                    .foregroundStyle(.yellow)
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(
+                        ShotdeckError.screenRecordingNotGranted.errorDescription
+                            ?? "Screen Recording is turned off."
+                    )
+                    .font(.caption)
+                    .fixedSize(horizontal: false, vertical: true)
+                    Button("Open Screen Recording settings") {
+                        model.openScreenRecordingSettings()
+                    }
+                }
+            }
+        } else {
+            Text(model.statusLine ?? defaultStatusText)
+                .font(.caption)
+                .foregroundStyle(.primary)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+    }
+
+    private var defaultStatusText: String {
+        guard let region = model.region else {
+            return "No region yet — press ⌥⇧2 to pick one."
+        }
+        let w = Int(region.rect.width)
+        let h = Int(region.rect.height)
+        let display = displayName(for: region)
+        if model.session.isEmpty {
+            return "Region \(w) × \(h) on \(display) · Nothing captured yet."
+        }
+        let count = model.session.captures.count
+        return "\(count) captures · region \(w) × \(h) on \(display)"
+    }
+
+    private func displayName(for region: CaptureRegion) -> String {
+        for (index, screen) in NSScreen.screens.enumerated() {
+            let id = (screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber)?
+                .uint32Value
+            if id == region.displayID {
+                return "Display \(index + 1)"
+            }
+        }
+        return "Display 1"
+    }
+
+    private var actionsList: some View {
+        VStack(alignment: .leading, spacing: 2) {
+            Button {
+                let anchor = NSApp.keyWindow?.contentView
+                if let sender = model as? SendCapable {
+                    Task { await sender.send(anchor: anchor) }
+                } else {
+                    model.setStatus("Send is not available in this build.")
+                }
+            } label: {
+                actionLabel("Send…")
+            }
+            .disabled(model.session.isEmpty || model.isSending)
+
+            Button {
+                Task { await model.captureNow() }
+            } label: {
+                actionLabel("Capture now", trailing: "⌥⇧2")
+            }
+            .disabled(model.isCapturing)
+
+            Button {
+                Task { await model.rePickRegion() }
+            } label: {
+                actionLabel("Re-select area")
+            }
+
+            Button {
+                Task { await model.copyCommentedLinks() }
+            } label: {
+                actionLabel(
+                    "Copy commented links",
+                    trailing: model.commentedReturns.isEmpty ? nil : "\(model.commentedReturns.count)"
+                )
+            }
+            .disabled(model.commentedReturns.isEmpty)
+
+            Button {
+                model.openSpoolFolder()
+            } label: {
+                actionLabel("Open spool folder")
+            }
+
+            Button {
+                if let presenter = model as? SettingsWindowPresenting {
+                    presenter.presentSettingsWindow()
+                } else {
+                    model.setStatus("Settings is not available in this build.")
+                }
+            } label: {
+                actionLabel("Settings…")
+            }
+
+            Button {
+                NSApp.terminate(nil)
+            } label: {
+                actionLabel("Quit Shotdeck")
+            }
+        }
+        .buttonStyle(.plain)
+    }
+
+    private func actionLabel(_ title: String, trailing: String? = nil) -> some View {
+        HStack(spacing: 8) {
+            Text(title)
+            Spacer(minLength: 8)
+            if let trailing {
+                Text(trailing)
+                    .foregroundStyle(.secondary)
+                    .monospacedDigit()
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .contentShape(Rectangle())
+        .padding(.vertical, 3)
+    }
+
+    @ViewBuilder
+    private var returnsBlock: some View {
+        if let provider = model as? ReturnsSectionProviding {
+            provider.returnsSection()
+        } else {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Came back from your device")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                ForEach(newestReturns.prefix(8)) { doc in
+                    HStack(spacing: 8) {
+                        Text(doc.fileURL.lastPathComponent)
+                            .lineLimit(1)
+                        Spacer(minLength: 8)
+                        Text(doc.isCommented
+                             ? "\(doc.annotatedPages.count) page\(doc.annotatedPages.count == 1 ? "" : "s") marked"
+                             : "not marked")
+                            .font(.caption)
+                            .foregroundStyle(doc.isCommented ? .primary : .secondary)
+                    }
+                }
+            }
+        }
+    }
+
+    private var newestReturns: [ReturnedDocument] {
+        model.allReturns.sorted { $0.detectedAt > $1.detectedAt }
+    }
+}

Sources/Shotdeck/PanelSnapshot.swift

@@ -0,0 +1,295 @@
+import AppKit
+import CoreGraphics
+import Darwin
+import Foundation
+import ImageIO
+import PDFKit
+import SwiftUI
+import ShotdeckCore
+
+/// Headless offscreen renderer for `MenuBarView` / `SettingsView`.
+/// Driven by `SHOTDECK_SNAPSHOT_DIR`; never touches the real Application Support spool.
+enum PanelSnapshot {
+    private static let panelWidth: CGFloat = 340
+
+    /// Called from `main.swift` before `ShotdeckApp.main()`. Returns immediately when the
+    /// env var is unset; otherwise writes the six panel PNGs, prints each path, and `exit`s.
+    @MainActor
+    static func runIfRequested() {
+        guard let raw = ProcessInfo.processInfo.environment["SHOTDECK_SNAPSHOT_DIR"],
+              !raw.isEmpty
+        else { return }
+
+        let app = NSApplication.shared
+        app.setActivationPolicy(.prohibited)
+
+        Task { @MainActor in
+            do {
+                try await captureAll(to: URL(fileURLWithPath: raw, isDirectory: true))
+                exit(0)
+            } catch {
+                fputs("PanelSnapshot failed: \(error)\n", stderr)
+                exit(1)
+            }
+        }
+
+        app.run()
+        exit(0)
+    }
+
+    @MainActor
+    private static func captureAll(to directory: URL) async throws {
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+
+        let (model, root) = try makeIsolatedModel()
+        defer { try? FileManager.default.removeItem(at: root) }
+
+        let region = sampleRegion()
+
+        // 01 — Screen Recording missing (no public mutator; snapshot-only seam).
+        model.snapshotSetScreenRecordingGranted(false)
+        model.replaceRegion(nil)
+        try renderMenuBar(model: model, to: directory, name: "01-no-permission")
+
+        // 02 — granted, no region picked.
+        model.snapshotSetScreenRecordingGranted(true)
+        model.replaceRegion(nil)
+        try renderMenuBar(model: model, to: directory, name: "02-no-region")
+
+        // 03 — region set, empty session.
+        model.replaceRegion(region)
+        try renderMenuBar(model: model, to: directory, name: "03-empty-session")
+
+        // 04 — three real PNGs in the temp spool so SessionStrip thumbnails decode.
+        let swatches: [(CGFloat, CGFloat, CGFloat)] = [
+            (0.85, 0.22, 0.18),
+            (0.18, 0.62, 0.32),
+            (0.16, 0.38, 0.82),
+        ]
+        for (red, green, blue) in swatches {
+            let png = try makePNGData(width: 192, height: 108, red: red, green: green, blue: blue)
+            _ = try await model.spool.append(
+                pngData: png,
+                pixelWidth: 192,
+                pixelHeight: 108,
+                scale: 2.0,
+                capturedAt: Date()
+            )
+        }
+        model.replaceSession(try await model.spool.currentSession())
+        try renderMenuBar(model: model, to: directory, name: "04-captures-present")
+
+        // 05 — two inspected PDFs in the temp ledger, one marked / one not.
+        try await seedReturns(model: model)
+        try renderMenuBar(model: model, to: directory, name: "05-returns-present")
+
+        // 06 — SettingsView against the same isolated model.
+        try render(
+            SettingsView().environment(model),
+            to: directory.appendingPathComponent("panel-06-settings.png")
+        )
+    }
+
+    @MainActor
+    private static func renderMenuBar(model: AppModel, to directory: URL, name: String) throws {
+        try render(
+            MenuBarView().environment(model),
+            to: directory.appendingPathComponent("panel-\(name).png")
+        )
+    }
+
+    @MainActor
+    private static func render(_ view: some View, to url: URL) throws {
+        let wrapped = view
+            .frame(width: panelWidth, alignment: .topLeading)
+            .fixedSize(horizontal: false, vertical: true)
+            .background(Color(nsColor: .windowBackgroundColor))
+
+        let hosting = NSHostingView(rootView: wrapped)
+        hosting.wantsLayer = true
+        hosting.appearance = NSAppearance(named: .aqua)
+
+        let window = NSWindow(
+            contentRect: NSRect(x: -10_000, y: -10_000, width: panelWidth, height: 64),
+            styleMask: [.borderless],
+            backing: .buffered,
+            defer: false
+        )
+        window.isReleasedWhenClosed = false
+        window.appearance = NSAppearance(named: .aqua)
+        window.backgroundColor = .windowBackgroundColor
+        window.isOpaque = true
+        window.alphaValue = 0
+        window.contentView = hosting
+        window.orderBack(nil)
+
+        hosting.layoutSubtreeIfNeeded()
+        var size = hosting.fittingSize
+        if size.height < 1 {
+            size.height = hosting.intrinsicContentSize.height
+        }
+        if size.height < 1 { size.height = 240 }
+        size.width = panelWidth
+        size.height = ceil(size.height)
+
+        hosting.setFrameSize(size)
+        window.setContentSize(size)
+        hosting.layoutSubtreeIfNeeded()
+        RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.05))
+
+        let bounds = hosting.bounds
+        guard let rep = hosting.bitmapImageRepForCachingDisplay(in: bounds) else {
+            throw SnapshotError.renderFailed(url.lastPathComponent)
+        }
+        hosting.cacheDisplay(in: bounds, to: rep)
+        guard let png = rep.representation(using: .png, properties: [:]) else {
+            throw SnapshotError.encodeFailed(url.lastPathComponent)
+        }
+        try png.write(to: url)
+        print(url.path)
+        fflush(stdout)
+
+        window.contentView = nil
+        window.close()
+    }
+
+    @MainActor
+    private static func makeIsolatedModel() throws -> (model: AppModel, root: URL) {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("shotdeck-panel-snapshot-\(UUID().uuidString)", isDirectory: true)
+        let paths = try AppSupportPaths(
+            root: root,
+            outbox: root.appendingPathComponent("outbox", isDirectory: true),
+            watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+        )
+        let ledger = try ReturnLedger(paths: paths)
+        let model = AppModel(
+            paths: paths,
+            spool: try SpoolStore(paths: paths),
+            composer: PDFComposer(),
+            capturer: ScreenCapturer(),
+            hotkeys: HotkeyCenter(),
+            picker: RegionPickerController(),
+            ledger: ledger,
+            watcher: ReturnWatcher(paths: paths, ledger: ledger)
+        )
+        model.setFolderURLs(outbox: paths.outbox, watch: paths.watchFolder)
+        return (model, root)
+    }
+
+    @MainActor
+    private static func seedReturns(model: AppModel) async throws {
+        let watch = model.paths.watchFolder
+        let unmarkedURL = watch.appendingPathComponent("Shotdeck-20260901-120000.pdf")
+        let markedURL = watch.appendingPathComponent("Shotdeck-20260901-120100.pdf")
+        try writeShotdeckPDF(to: unmarkedURL, marked: false)
+        try writeShotdeckPDF(to: markedURL, marked: true)
+
+        let unmarked = try AnnotationInspector.inspect(fileURL: unmarkedURL)
+        let marked = try AnnotationInspector.inspect(fileURL: markedURL)
+        try await model.ledger.record(unmarked)
+        try await model.ledger.record(marked)
+        model.setReturns(
+            all: try await model.ledger.all(),
+            commented: try await model.ledger.commented()
+        )
+    }
+
+    private static func sampleRegion() -> CaptureRegion {
+        CaptureRegion(
+            displayID: CGMainDisplayID(),
+            rect: CGRect(x: 120, y: 80, width: 800, height: 600),
+            capturedScale: 2.0
+        )
+    }
+
+    private static func makePNGData(
+        width: Int,
+        height: Int,
+        red: CGFloat,
+        green: CGFloat,
+        blue: CGFloat
+    ) throws -> Data {
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        guard let context = CGContext(
+            data: nil,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: width * 4,
+            space: colorSpace,
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else {
+            throw SnapshotError.pngGenerationFailed
+        }
+        context.setFillColor(red: red, green: green, blue: blue, alpha: 1)
+        context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        guard let image = context.makeImage() else {
+            throw SnapshotError.pngGenerationFailed
+        }
+        let buffer = NSMutableData()
+        guard let destination = CGImageDestinationCreateWithData(
+            buffer,
+            "public.png" as CFString,
+            1,
+            nil
+        ) else {
+            throw SnapshotError.pngGenerationFailed
+        }
+        CGImageDestinationAddImage(destination, image, nil)
+        guard CGImageDestinationFinalize(destination) else {
+            throw SnapshotError.pngGenerationFailed
+        }
+        return buffer as Data
+    }
+
+    private static func writeShotdeckPDF(to url: URL, marked: Bool) throws {
+        let document = PDFDocument()
+        let page = PDFPage()
+        page.setBounds(CGRect(x: 0, y: 0, width: 612, height: 792), for: .mediaBox)
+        document.insert(page, at: 0)
+        document.documentAttributes = [
+            PDFDocumentAttribute.creatorAttribute: "Shotdeck",
+            PDFDocumentAttribute.subjectAttribute: UUID().uuidString,
+        ]
+        if marked {
+            let annotation = PDFAnnotation(
+                bounds: CGRect(x: 72, y: 400, width: 220, height: 36),
+                forType: .highlight,
+                withProperties: nil
+            )
+            page.addAnnotation(annotation)
+        }
+        guard document.write(to: url) else {
+            throw SnapshotError.pdfWriteFailed(url.lastPathComponent)
+        }
+    }
+}
+
+extension AppModel {
+    /// `screenRecordingGranted` is `public private(set)` with no seam mutator.
+    /// Snapshot-only: the KeyPath setter exists at runtime; compile-time access is file-private.
+    func snapshotSetScreenRecordingGranted(_ granted: Bool) {
+        // private(set) types this as KeyPath; the setter still exists on the @Observable storage.
+        let writable: ReferenceWritableKeyPath<AppModel, Bool> = unsafeBitCast(
+            \AppModel.screenRecordingGranted, to: ReferenceWritableKeyPath<AppModel, Bool>.self
+        )
+        self[keyPath: writable] = granted
+    }
+}
+
+private enum SnapshotError: Error, CustomStringConvertible {
+    case renderFailed(String)
+    case encodeFailed(String)
+    case pngGenerationFailed
+    case pdfWriteFailed(String)
+
+    var description: String {
+        switch self {
+        case .renderFailed(let name): return "bitmapImageRepForCachingDisplay failed for \(name)"
+        case .encodeFailed(let name): return "PNG encode failed for \(name)"
+        case .pngGenerationFailed: return "CoreGraphics PNG generation failed"
+        case .pdfWriteFailed(let name): return "could not write \(name)"
+        }
+    }
+}

Sources/Shotdeck/RegionPickerController.swift

@@ -0,0 +1,181 @@
+import AppKit
+import ShotdeckCore
+
+@MainActor
+public final class RegionPickerController {
+    private var windows: [RegionPickerWindow] = []
+    private var monitor: Any?
+    private var completion: (@MainActor (CaptureRegion?) -> Void)?
+    private var dragStart: NSPoint?
+    private var startScreen: NSScreen?
+    private var cursorPushed = false
+
+    public init() {}
+
+    /// Presents one overlay per attached screen. A pick already in progress is cancelled
+    /// (its completion called with nil) before the new one starts — never leaves a caller
+    /// waiting forever on a dropped re-entrant call.
+    public func pick(completion: @escaping @MainActor (CaptureRegion?) -> Void) {
+        if self.completion != nil {
+            finish(region: nil)
+        }
+        self.completion = completion
+        presentOverlays()
+    }
+
+    private func presentOverlays() {
+        let screens = NSScreen.screens
+        guard !screens.isEmpty else {
+            finish(region: nil)
+            return
+        }
+
+        NSCursor.crosshair.push()
+        cursorPushed = true
+
+        windows = screens.map { RegionPickerWindow(screen: $0) }
+        for window in windows {
+            window.orderFrontRegardless()
+        }
+        // Nonactivating panel can become key without activating the app; needed so
+        // Escape reaches the local monitor immediately, before any mouse click.
+        let mouse = NSEvent.mouseLocation
+        let keyWindow = windows.first(where: { $0.coveringScreen.frame.contains(mouse) })
+            ?? windows[0]
+        keyWindow.makeKey()
+
+        monitor = NSEvent.addLocalMonitorForEvents(
+            matching: [.leftMouseDown, .leftMouseDragged, .leftMouseUp, .keyDown]
+        ) { [weak self] event in
+            guard let self else { return event }
+            // NSEvent is not Sendable; lift the two Sendable fields the handler
+            // needs. Mouse geometry is read from NSEvent.mouseLocation on the
+            // main thread inside the isolated methods, per spec.
+            let type = event.type
+            let keyCode = event.keyCode
+            let consume = MainActor.assumeIsolated {
+                self.handle(type: type, keyCode: keyCode)
+            }
+            return consume ? nil : event
+        }
+    }
+
+    /// Returns `true` when the event should be swallowed.
+    private func handle(type: NSEvent.EventType, keyCode: UInt16) -> Bool {
+        switch type {
+        case .keyDown:
+            if keyCode == 53 { // kVK_Escape
+                finish(region: nil)
+                return true
+            }
+            return false
+        case .leftMouseDown:
+            handleMouseDown()
+            return false
+        case .leftMouseDragged:
+            handleMouseDragged()
+            return false
+        case .leftMouseUp:
+            handleMouseUp()
+            return false
+        default:
+            return false
+        }
+    }
+
+    private func handleMouseDown() {
+        let point = NSEvent.mouseLocation
+        dragStart = point
+        startScreen = NSScreen.screens.first(where: { $0.frame.contains(point) })
+            ?? NSScreen.screens.first
+        guard let startScreen else { return }
+        let local = Self.localRect(
+            from: CGRect(origin: point, size: .zero).intersection(startScreen.frame),
+            on: startScreen
+        )
+        window(for: startScreen)?.updateSelection(localRect: local, sizeText: "0 x 0")
+        for window in windows where window.coveringScreen !== startScreen {
+            window.updateSelection(localRect: nil, sizeText: nil)
+        }
+    }
+
+    private func handleMouseDragged() {
+        guard dragStart != nil, startScreen != nil else { return }
+        applyLiveSelection()
+    }
+
+    private func handleMouseUp() {
+        guard let startScreen else {
+            dragStart = nil
+            return
+        }
+        guard let rect = currentClampedRect(), rect.width >= 8, rect.height >= 8 else {
+            // Mis-click: reset drag state, leave every window open and fully dimmed.
+            dragStart = nil
+            self.startScreen = nil
+            for window in windows {
+                window.updateSelection(localRect: nil, sizeText: nil)
+            }
+            return
+        }
+        let region = CaptureRegion.fromAppKit(rect: rect, on: startScreen)
+        finish(region: region)
+    }
+
+    private func applyLiveSelection() {
+        guard let startScreen, let rect = currentClampedRect() else { return }
+        let local = Self.localRect(from: rect, on: startScreen)
+        let text = "\(Int(rect.width)) x \(Int(rect.height))"
+        window(for: startScreen)?.updateSelection(localRect: local, sizeText: text)
+        for window in windows where window.coveringScreen !== startScreen {
+            window.updateSelection(localRect: nil, sizeText: nil)
+        }
+    }
+
+    /// Normalize the drag (so bottom-right → up-left is not misjudged) then clamp
+    /// to the screen the gesture started on — never selects across displays.
+    private func currentClampedRect() -> CGRect? {
+        guard let dragStart, let startScreen else { return nil }
+        let current = NSEvent.mouseLocation
+        let normalized = CGRect(
+            x: min(dragStart.x, current.x),
+            y: min(dragStart.y, current.y),
+            width: abs(current.x - dragStart.x),
+            height: abs(current.y - dragStart.y)
+        )
+        return normalized.intersection(startScreen.frame)
+    }
+
+    private func window(for screen: NSScreen) -> RegionPickerWindow? {
+        windows.first { $0.coveringScreen === screen }
+    }
+
+    private static func localRect(from rect: CGRect, on screen: NSScreen) -> CGRect {
+        CGRect(
+            x: rect.minX - screen.frame.minX,
+            y: rect.minY - screen.frame.minY,
+            width: rect.width,
+            height: rect.height
+        )
+    }
+
+    private func finish(region: CaptureRegion?) {
+        if let monitor {
+            NSEvent.removeMonitor(monitor)
+            self.monitor = nil
+        }
+        if cursorPushed {
+            NSCursor.pop()
+            cursorPushed = false
+        }
+        for window in windows {
+            window.orderOut(nil)
+        }
+        windows.removeAll()
+        dragStart = nil
+        startScreen = nil
+        let done = completion
+        completion = nil
+        done?(region)
+    }
+}

Sources/Shotdeck/RegionPickerWindow.swift

@@ -0,0 +1,110 @@
+import AppKit
+
+/// Full-screen dim overlay for one attached display. Subclasses `NSPanel` with
+/// `.nonactivatingPanel` so it can accept mouse and key events without activating
+/// Shotdeck or stealing the frontmost app beyond those events.
+@MainActor
+final class RegionPickerWindow: NSPanel {
+    let coveringScreen: NSScreen
+    private let pickerView: RegionPickerView
+
+    init(screen: NSScreen) {
+        self.coveringScreen = screen
+        self.pickerView = RegionPickerView(frame: CGRect(origin: .zero, size: screen.frame.size))
+        super.init(
+            contentRect: screen.frame,
+            styleMask: [.borderless, .nonactivatingPanel],
+            backing: .buffered,
+            defer: false
+        )
+        setFrame(screen.frame, display: false)
+        level = .screenSaver
+        isOpaque = false
+        backgroundColor = .clear
+        ignoresMouseEvents = false
+        hasShadow = false
+        isMovable = false
+        hidesOnDeactivate = false
+        isFloatingPanel = true
+        becomesKeyOnlyIfNeeded = false
+        animationBehavior = .none
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        contentView = pickerView
+    }
+
+    override var canBecomeKey: Bool { true }
+    override var canBecomeMain: Bool { false }
+
+    /// `localRect` is in this window's coordinates (screen.frame origin subtracted).
+    /// Pass `nil` to restore the full dim with no punch and no size chip.
+    func updateSelection(localRect: CGRect?, sizeText: String?) {
+        pickerView.selectionLocalRect = localRect
+        pickerView.sizeChipText = sizeText
+        pickerView.needsDisplay = true
+    }
+}
+
+/// Draws ~35% black over the screen with an even-odd punch for the live selection,
+/// a thin light border, and the size-readout chip.
+@MainActor
+private final class RegionPickerView: NSView {
+    var selectionLocalRect: CGRect?
+    var sizeChipText: String?
+
+    override var isOpaque: Bool { false }
+    override var acceptsFirstResponder: Bool { true }
+
+    override func draw(_ dirtyRect: NSRect) {
+        super.draw(dirtyRect)
+
+        let dim = NSColor.black.withAlphaComponent(0.35)
+        let path = NSBezierPath(rect: bounds)
+        if let sel = selectionLocalRect, sel.width > 0, sel.height > 0 {
+            path.append(NSBezierPath(rect: sel))
+            path.windingRule = .evenOdd
+        }
+        dim.setFill()
+        path.fill()
+
+        guard let sel = selectionLocalRect, sel.width > 0, sel.height > 0 else { return }
+
+        NSColor.white.withAlphaComponent(0.85).setStroke()
+        let border = NSBezierPath(rect: sel)
+        border.lineWidth = 1
+        border.stroke()
+
+        if let text = sizeChipText {
+            drawSizeChip(text, above: sel)
+        }
+    }
+
+    private func drawSizeChip(_ text: String, above sel: CGRect) {
+        let attrs: [NSAttributedString.Key: Any] = [
+            .font: NSFont.systemFont(ofSize: NSFont.smallSystemFontSize),
+            .foregroundColor: NSColor.white,
+        ]
+        let nsText = text as NSString
+        let textSize = nsText.size(withAttributes: attrs)
+        let padX: CGFloat = 8
+        let padY: CGFloat = 4
+        let chipSize = CGSize(
+            width: ceil(textSize.width) + padX * 2,
+            height: ceil(textSize.height) + padY * 2
+        )
+
+        var origin = CGPoint(x: sel.minX, y: sel.maxY + 6)
+        if origin.y + chipSize.height > bounds.maxY {
+            origin.y = sel.minY - 6 - chipSize.height
+        }
+        origin.x = min(max(origin.x, bounds.minX + 4), bounds.maxX - chipSize.width - 4)
+        origin.y = min(max(origin.y, bounds.minY + 4), bounds.maxY - chipSize.height - 4)
+
+        let chipRect = CGRect(origin: origin, size: chipSize)
+        NSColor.black.withAlphaComponent(0.75).setFill()
+        NSBezierPath(roundedRect: chipRect, xRadius: 4, yRadius: 4).fill()
+        nsText.draw(
+            at: CGPoint(x: chipRect.minX + padX, y: chipRect.minY + padY),
+            withAttributes: attrs
+        )
+    }
+}

Sources/Shotdeck/ReturnsList.swift

@@ -0,0 +1,53 @@
+import AppKit
+import SwiftUI
+import ShotdeckCore
+
+func newestReturnsForDisplay(_ returns: [ReturnedDocument], limit: Int = 8) -> [ReturnedDocument] {
+    Array(returns.sorted { $0.detectedAt > $1.detectedAt }.prefix(limit))
+}
+
+func returnMarkLabel(_ document: ReturnedDocument) -> String {
+    guard document.isCommented else { return "not marked" }
+    let count = document.annotatedPages.count
+    return "\(count) page\(count == 1 ? "" : "s") marked"
+}
+
+struct ReturnsList: View {
+    let returns: [ReturnedDocument]
+
+    var body: some View {
+        let visible = newestReturnsForDisplay(returns)
+        if visible.isEmpty {
+            EmptyView()
+        } else {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Came back from your device")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                ForEach(visible) { document in
+                    Button {
+                        NSWorkspace.shared.activateFileViewerSelecting([document.fileURL])
+                    } label: {
+                        HStack(spacing: 8) {
+                            Text(document.fileURL.lastPathComponent)
+                                .lineLimit(1)
+                            Spacer(minLength: 8)
+                            Text(returnMarkLabel(document))
+                                .font(.caption)
+                                .foregroundStyle(document.isCommented ? .primary : .secondary)
+                        }
+                    }
+                    .buttonStyle(.plain)
+                    .help(DubaiTime.stamp(document.detectedAt))
+                }
+            }
+        }
+    }
+}
+
+extension AppModel: ReturnsSectionProviding {
+    public func returnsSection() -> AnyView {
+        guard !allReturns.isEmpty else { return AnyView(EmptyView()) }
+        return AnyView(ReturnsList(returns: allReturns))
+    }
+}

Sources/Shotdeck/SendController.swift

@@ -0,0 +1,71 @@
+import AppKit
+import Darwin
+import Foundation
+import ShotdeckCore
+
+extension AppModel: SendCapable {
+    public func send(anchor: NSView?) async {
+        guard !session.isEmpty, !isSending else { return }
+        setSending(true)
+        defer { setSending(false) }
+
+        let workingSession = session
+        let composer = self.composer
+        // Live outbox (FolderSettings), not `paths.outbox` — Settings changes take effect.
+        let outboxDir = outboxURL
+        let sourceDir = paths.sessionDirectory(workingSession.id)
+        let fileName = PDFComposer.fileName(for: workingSession)
+        let finalURL = outboxDir.appendingPathComponent(fileName)
+        // Same directory as the final target so the rename below is same-volume (atomic).
+        let tempURL = outboxDir.appendingPathComponent(".shotdeck-\(UUID().uuidString).pdf")
+        let title = "Shotdeck – \(DubaiTime.stamp(workingSession.createdAt))"
+
+        do {
+            // D-13: build off the main actor. Only Sendable values cross into the
+            // detached task — never `anchor` (NSView is not Sendable).
+            try await Task.detached(priority: .userInitiated) {
+                _ = try composer.compose(
+                    session: workingSession,
+                    imageURL: { capture in sourceDir.appendingPathComponent(capture.fileName) },
+                    title: title,
+                    to: tempURL
+                )
+                // POSIX rename onto `finalURL` replaces any same-name file in one
+                // directory operation; there is never a window where the PDF is gone.
+                if Darwin.rename(tempURL.path, finalURL.path) != 0 {
+                    throw ShotdeckError.pdfCompositionFailed(
+                        reason: "could not publish the PDF: \(String(cString: strerror(errno)))"
+                    )
+                }
+                try AtomicFile.fsyncDirectory(at: outboxDir)
+            }.value
+
+            // File exists on disk now — archive only after that (D-13). A later AirDrop
+            // failure never deletes this file.
+            guard FileManager.default.fileExists(atPath: finalURL.path) else {
+                throw ShotdeckError.pdfCompositionFailed(reason: "the PDF was not written to disk")
+            }
+            _ = try await spool.archiveCurrent(pdfFileName: fileName)
+            replaceSession(try await spool.currentSession())
+
+            let pageWord = workingSession.captures.count == 1 ? "page" : "pages"
+            setStatus("Sent — \(workingSession.captures.count) \(pageWord).")
+
+            guard let anchor else {
+                setStatus("PDF saved to \(outboxDisplayName). Open the panel to AirDrop it.")
+                return
+            }
+            do {
+                try Sharing.airDrop(fileURL: finalURL, from: anchor)
+            } catch {
+                setStatus(
+                    "AirDrop is not available right now — the PDF is on your \(outboxDisplayName)."
+                )
+            }
+        } catch {
+            // Never unlink the published PDF, and never unlink `tempURL` either:
+            // a rename failure would leave the complete document at the temp name.
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "The PDF could not be built.")
+        }
+    }
+}

Sources/Shotdeck/SessionStrip.swift

@@ -0,0 +1,78 @@
+import AppKit
+import SwiftUI
+import ShotdeckCore
+
+struct SessionStrip: View {
+    @Environment(AppModel.self) private var model
+
+    var body: some View {
+        if model.session.captures.isEmpty {
+            Text("Nothing captured yet.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .frame(maxWidth: .infinity, minHeight: 64, alignment: .leading)
+        } else {
+            ScrollView(.horizontal, showsIndicators: false) {
+                HStack(alignment: .top, spacing: 6) {
+                    ForEach(model.session.captures) { capture in
+                        SessionThumb(capture: capture)
+                    }
+                }
+            }
+            .frame(height: 64)
+        }
+    }
+}
+
+private struct SessionThumb: View {
+    @Environment(AppModel.self) private var model
+    let capture: Capture
+    @State private var hovering = false
+
+    var body: some View {
+        ZStack(alignment: .topLeading) {
+            thumbnail
+            Text("\(capture.sequence)")
+                .font(.system(size: 9, weight: .bold))
+                .foregroundStyle(.white)
+                .padding(.horizontal, 4)
+                .padding(.vertical, 1)
+                .background(.black.opacity(0.65))
+                .clipShape(RoundedRectangle(cornerRadius: 2, style: .continuous))
+                .padding(3)
+            if hovering {
+                VStack {
+                    Spacer()
+                    Button("Remove") {
+                        Task { await model.removeCapture(id: capture.id) }
+                    }
+                    .font(.system(size: 10, weight: .semibold))
+                    .buttonStyle(.plain)
+                    .foregroundStyle(.white)
+                    .frame(maxWidth: .infinity)
+                    .padding(.vertical, 3)
+                    .background(.black.opacity(0.7))
+                }
+            }
+        }
+        .frame(height: 64)
+        .clipped()
+        .onHover { hovering = $0 }
+        .help(DubaiTime.stamp(capture.capturedAt))
+    }
+
+    @ViewBuilder
+    private var thumbnail: some View {
+        let url = model.paths.sessionDirectory(model.session.id).appendingPathComponent(capture.fileName)
+        if let image = NSImage(contentsOf: url) {
+            Image(nsImage: image)
+                .resizable()
+                .aspectRatio(contentMode: .fit)
+                .frame(height: 64)
+        } else {
+            Rectangle()
+                .fill(Color.secondary.opacity(0.2))
+                .frame(width: 64, height: 64)
+        }
+    }
+}

Sources/Shotdeck/SettingsView.swift

@@ -0,0 +1,138 @@
+import AppKit
+import SwiftUI
+import ShotdeckCore
+
+struct SettingsView: View {
+    @Environment(AppModel.self) private var model
+
+    private let labelWidth: CGFloat = 104
+
+    var body: some View {
+        Grid(alignment: .leading, horizontalSpacing: 12, verticalSpacing: 10) {
+            GridRow {
+                Text("Hotkey")
+                    .font(.headline)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .gridCellColumns(2)
+            }
+
+            GridRow(alignment: .firstTextBaseline) {
+                fieldLabel("Capture")
+                Text("⌥⇧2 — fixed in this version")
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .frame(minHeight: 22, alignment: .leading)
+            }
+
+            GridRow {
+                Text("Folders")
+                    .font(.headline)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .gridCellColumns(2)
+                    .padding(.top, 6)
+            }
+
+            GridRow(alignment: .center) {
+                fieldLabel("Watch folder")
+                folderValue(path: model.watchFolderURL.path) {
+                    model.chooseWatchFolder()
+                }
+            }
+
+            GridRow(alignment: .center) {
+                fieldLabel("Output folder")
+                folderValue(path: model.outboxURL.path) {
+                    model.chooseOutboxFolder()
+                }
+            }
+
+            GridRow {
+                Button("Reveal spool folder") { model.openSpoolFolder() }
+                    .gridCellColumns(2)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .padding(.top, 4)
+            }
+        }
+        .padding(16)
+        .frame(minWidth: 320, idealWidth: 360, maxWidth: 360, alignment: .leading)
+        .controlSize(.small)
+    }
+
+    private func fieldLabel(_ title: String) -> some View {
+        Text(title)
+            .lineLimit(1)
+            .frame(width: labelWidth, alignment: .trailing)
+            .gridColumnAlignment(.trailing)
+            .frame(minHeight: 22, alignment: .trailing)
+    }
+
+    private func folderValue(path: String, choose: @escaping () -> Void) -> some View {
+        HStack(spacing: 8) {
+            Text(path)
+                .lineLimit(1)
+                .truncationMode(.middle)
+                .foregroundStyle(.secondary)
+                .frame(maxWidth: .infinity, alignment: .leading)
+            Button("Choose…") { choose() }
+        }
+        .frame(minHeight: 22)
+    }
+}
+
+extension AppModel: SettingsWindowPresenting {
+    private static var settingsWindowController: NSWindowController?
+
+    public func presentSettingsWindow() {
+        if let existing = Self.settingsWindowController {
+            existing.window?.makeKeyAndOrderFront(nil)
+            NSApp.activate()
+            return
+        }
+        let hosting = NSHostingController(rootView: SettingsView().environment(self))
+        let window = NSWindow(contentViewController: hosting)
+        window.title = "Shotdeck Settings"
+        window.styleMask = [.titled, .closable]
+        window.isReleasedWhenClosed = false
+        window.center()
+        let controller = NSWindowController(window: window)
+        Self.settingsWindowController = controller
+        controller.showWindow(nil)
+        NSApp.activate()
+    }
+
+    func chooseOutboxFolder() {
+        guard let url = chooseDirectory(startingAt: outboxURL) else { return }
+        FolderSettings.setOutbox(url)
+        setFolderURLs(outbox: url, watch: watchFolderURL)
+        setStatus("Output folder set to \(url.lastPathComponent).")
+    }
+
+    func chooseWatchFolder() {
+        guard let url = chooseDirectory(startingAt: watchFolderURL) else { return }
+        FolderSettings.setWatchFolder(url)
+        setFolderURLs(outbox: outboxURL, watch: url)
+        Task {
+            do {
+                try await watcher.updateWatchFolder(url)
+                setStatus("Watch folder set to \(url.lastPathComponent).")
+            } catch {
+                setStatus(
+                    (error as? ShotdeckError)?.errorDescription ?? "Could not switch the watch folder."
+                )
+            }
+        }
+    }
+
+    private func chooseDirectory(startingAt directory: URL) -> URL? {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        panel.canCreateDirectories = true
+        panel.prompt = "Choose"
+        panel.directoryURL = directory
+        guard panel.runModal() == .OK else { return nil }
+        return panel.url
+    }
+}

Sources/Shotdeck/Sharing.swift

@@ -0,0 +1,83 @@
+import AppKit
+import ShotdeckCore
+
+@MainActor
+enum Sharing {
+    /// Presents the AirDrop picker for `fileURL`, anchored to `view`.
+    /// Throws `ShotdeckError.airDropUnavailable` when the service cannot be created,
+    /// `canPerform` is false, or `view` is not in a visible window (a detached view
+    /// never produces an on-screen sheet).
+    static func airDrop(fileURL: URL, from view: NSView) throws {
+        guard let service = NSSharingService(named: .sendViaAirDrop),
+              service.canPerform(withItems: [fileURL]) else {
+            throw ShotdeckError.airDropUnavailable
+        }
+        // Presenting from a detached NSView (no window) yields a sheet that never appears.
+        guard let window = view.window, window.isVisible else {
+            throw ShotdeckError.airDropUnavailable
+        }
+
+        NSApp.activate()
+        window.makeKeyAndOrderFront(nil)
+
+        service.subject = fileURL.lastPathComponent
+        let session = AirDropSession(service: service, window: window, view: view)
+        AirDropSession.keepAlive(session)
+        service.delegate = session
+        service.perform(withItems: [fileURL])
+    }
+}
+
+/// Retains the sharing service for the life of the picker and supplies the real
+/// on-screen window as the sheet parent. `NSSharingService.delegate` is weak.
+@MainActor
+private final class AirDropSession: NSObject, NSSharingServiceDelegate {
+    static var live: [AirDropSession] = []
+
+    let service: NSSharingService
+    let window: NSWindow
+    let view: NSView
+
+    init(service: NSSharingService, window: NSWindow, view: NSView) {
+        self.service = service
+        self.window = window
+        self.view = view
+    }
+
+    static func keepAlive(_ session: AirDropSession) {
+        live.append(session)
+    }
+
+    private func drop() {
+        Self.live.removeAll { $0 === self }
+    }
+
+    func sharingService(
+        _ sharingService: NSSharingService,
+        sourceWindowForShareItems items: [Any],
+        sharingContentScope: UnsafeMutablePointer<NSSharingService.SharingContentScope>
+    ) -> NSWindow? {
+        sharingContentScope.pointee = .item
+        return window
+    }
+
+    func sharingService(
+        _ sharingService: NSSharingService,
+        sourceFrameOnScreenForShareItem item: Any
+    ) -> NSRect {
+        let inWindow = view.convert(view.bounds, to: nil)
+        return window.convertToScreen(inWindow)
+    }
+
+    func sharingService(_ sharingService: NSSharingService, didShareItems items: [Any]) {
+        drop()
+    }
+
+    func sharingService(
+        _ sharingService: NSSharingService,
+        didFailToShareItems items: [Any],
+        error: any Error
+    ) {
+        drop()
+    }
+}

Sources/Shotdeck/main.swift

@@ -1,6 +1,78 @@
 import AppKit
+import SwiftUI
+import ShotdeckCore
 
-// WP-4 replaces this body with the real menu-bar UI.
-let application = NSApplication.shared
-application.setActivationPolicy(.accessory)
-application.run()
+// SwiftPM treats a file named main.swift as top-level code, which forbids `@main`.
+// App.main() is the equivalent entry point.
+if ProcessInfo.processInfo.environment["SHOTDECK_SNAPSHOT_DIR"] != nil {
+    MainActor.assumeIsolated { PanelSnapshot.runIfRequested() }
+}
+ShotdeckApp.main()
+
+struct ShotdeckApp: App {
+    @NSApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
+
+    var body: some Scene {
+        MenuBarExtra {
+            MenuBarView()
+                .environment(appDelegate.model)
+        } label: {
+            let state = appDelegate.model.iconState
+            HStack(spacing: 4) {
+                Image(systemName: state.symbolName)
+                if let count = state.countText {
+                    Text(count).font(.system(size: 11, weight: .semibold))
+                }
+            }
+            .accessibilityLabel("Shotdeck")
+        }
+        .menuBarExtraStyle(.window)
+    }
+}
+
+@MainActor
+final class AppDelegate: NSObject, NSApplicationDelegate {
+    let model: AppModel
+
+    override init() {
+        NSApplication.shared.setActivationPolicy(.accessory)
+        model = AppDelegate.makeLaunchModel()
+        super.init()
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        Task { await model.bootstrap() }
+    }
+
+    private static func makeLaunchModel() -> AppModel {
+        do {
+            let paths = try FolderSettings.resolvedAppSupportPaths()
+            return try makeModel(paths: paths)
+        } catch {
+            Log.ui.critical(
+                "AppModel init failed: \(String(describing: error), privacy: .public)"
+            )
+            let tmp = FileManager.default.temporaryDirectory
+            let fallbackRoot = tmp.appendingPathComponent("Shotdeck-fallback", isDirectory: true)
+            // Safe: temp-dir creation for a path this process controls cannot legitimately fail.
+            let fallback = try! AppSupportPaths(root: fallbackRoot, outbox: tmp, watchFolder: tmp)
+            let model = try! makeModel(paths: fallback)
+            model.setStatus("Shotdeck could not access its storage folder. Captures will not persist.")
+            return model
+        }
+    }
+
+    private static func makeModel(paths: AppSupportPaths) throws -> AppModel {
+        let ledger = try ReturnLedger(paths: paths)
+        return AppModel(
+            paths: paths,
+            spool: try SpoolStore(paths: paths),
+            composer: PDFComposer(),
+            capturer: ScreenCapturer(),
+            hotkeys: HotkeyCenter(),
+            picker: RegionPickerController(),
+            ledger: ledger,
+            watcher: ReturnWatcher(paths: paths, ledger: ledger)
+        )
+    }
+}

Sources/ShotdeckCore/Capture/CaptureRegion.swift

@@ -0,0 +1,58 @@
+import Foundation
+import AppKit  // NSScreen, NSDeviceDescriptionKey — macOS-only target, no portability concern
+
+/// A remembered rectangle, in CoreGraphics global display coordinates (origin top-left,
+/// y increasing downward — see the conversion note below).
+public struct CaptureRegion: Codable, Sendable, Equatable {
+    public let displayID: CGDirectDisplayID
+    public let rect: CGRect
+    public let capturedScale: CGFloat
+
+    public init(displayID: CGDirectDisplayID, rect: CGRect, capturedScale: CGFloat) {
+        self.displayID = displayID
+        self.rect = rect
+        self.capturedScale = capturedScale
+    }
+
+    /// Converts an AppKit rect in GLOBAL AppKit coordinates (bottom-left origin, y increasing
+    /// upward, anchored at the bottom-left of the PRIMARY screen — exactly what
+    /// `NSWindow.frame`, `NSEvent.mouseLocation` and `NSScreen.frame` already report; no
+    /// screen-local conversion is needed here) into global CoreGraphics coordinates
+    /// (top-left origin, y increasing downward, same primary-screen anchor). Both coordinate
+    /// systems share the SAME horizontal origin and the SAME anchor rectangle (the primary
+    /// screen's bounds) — only the vertical axis is mirrored around the primary's height.
+    /// That is why the flip below is correct for every attached screen, including one with a
+    /// negative AppKit x (to the left of primary) or a y that places it above the primary
+    /// (whose CG y then comes out negative): x is untouched, and the primary height is the
+    /// one fixed reference both systems agree on regardless of which physical screen the
+    /// rect is actually on.
+    public static func fromAppKit(rect: CGRect, on screen: NSScreen) -> CaptureRegion {
+        let displayID = (screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")]
+            as? NSNumber)?.uint32Value ?? CGMainDisplayID()
+        let primaryHeight = NSScreen.screens.first?.frame.height ?? screen.frame.height
+        return fromAppKit(rect: rect, displayID: displayID,
+                           capturedScale: screen.backingScaleFactor, primaryHeight: primaryHeight)
+    }
+
+    /// Injectable overload for deterministic geometry tests — no dependency on real attached
+    /// displays. The public overload above is a thin adapter over this.
+    static func fromAppKit(rect: CGRect, displayID: CGDirectDisplayID,
+                            capturedScale: CGFloat, primaryHeight: CGFloat) -> CaptureRegion {
+        let cgY = primaryHeight - rect.origin.y - rect.height
+        let cgRect = CGRect(x: rect.origin.x, y: cgY, width: rect.width, height: rect.height)
+        return CaptureRegion(displayID: displayID, rect: cgRect, capturedScale: capturedScale)
+    }
+
+    /// True when `displayID` is still attached AND `rect` still lies inside its current
+    /// bounds. Uses `CGDisplayIsActive` (returns 0 safely for an unknown id, never traps) and
+    /// `CGDisplayBounds` — both real CoreGraphics calls, no injection needed since this is a
+    /// live-state check by design.
+    public var isStillValid: Bool {
+        guard CGDisplayIsActive(displayID) != 0 else { return false }
+        let bounds = CGDisplayBounds(displayID)
+        return bounds.contains(rect)
+    }
+
+    /// Persisted in UserDefaults under this key BY THE APP (WP-4a), never by this type.
+    public static let defaultsKey = "ai.flowmaster.shotdeck.region"
+}

Sources/ShotdeckCore/Capture/HotkeyCenter.swift

@@ -0,0 +1,115 @@
+import Carbon.HIToolbox
+import Foundation
+
+/// Carbon's C event handler cannot capture Swift closures, so live handlers are kept in one
+/// process-wide table keyed by the numeric EventHotKeyID Carbon hands back on fire. Safe
+/// because InstallEventHandler on GetApplicationEventTarget() always delivers on the main
+/// thread, and every access here happens either from a @MainActor HotkeyCenter method or from
+/// the C callback below, which this process only ever invokes on the main run loop.
+private final class HotkeyDispatchTable: @unchecked Sendable {
+    static let shared = HotkeyDispatchTable()
+    private var handlers: [UInt32: @MainActor () -> Void] = [:]
+    private init() {}
+    func set(_ numericID: UInt32, _ handler: @escaping @MainActor () -> Void) {
+        handlers[numericID] = handler
+    }
+    func remove(_ numericID: UInt32) { handlers.removeValue(forKey: numericID) }
+    func fire(_ numericID: UInt32) { MainActor.assumeIsolated { handlers[numericID]?() } }
+}
+
+private func shotdeckCarbonHotkeyHandler(
+    _ nextHandler: EventHandlerCallRef?, _ event: EventRef?, _ userData: UnsafeMutableRawPointer?
+) -> OSStatus {
+    guard let event else { return OSStatus(eventNotHandledErr) }
+    var hotKeyID = EventHotKeyID()
+    let status = GetEventParameter(event, EventParamName(kEventParamDirectObject),
+        EventParamType(typeEventHotKeyID), nil, MemoryLayout<EventHotKeyID>.size, nil, &hotKeyID)
+    guard status == noErr else { return status }
+    HotkeyDispatchTable.shared.fire(hotKeyID.id)
+    return noErr
+}
+
+/// Four-character creator code used for every `EventHotKeyID` this process registers.
+private let shotdeckHotKeySignature: OSType = 0x53484F54 // "SHOT"
+
+@MainActor
+public final class HotkeyCenter {
+    private var bindings: [String: (ref: EventHotKeyRef, numericID: UInt32)] = [:]
+    private var nextNumericID: UInt32 = 1
+
+    private static var didInstallGlobalCarbonHandler = false
+    private static var carbonHandlerRef: EventHandlerRef?
+
+    public init() { HotkeyCenter.installGlobalCarbonHandlerIfNeeded() }
+
+    /// Registers a hotkey. `id` is a caller-chosen stable identifier. Re-registering the same
+    /// `id` first unregisters its previous binding, then attempts the new one (idempotent).
+    /// Returns false when Carbon's `RegisterEventHotKey` reports a non-`noErr` status — the
+    /// most common cause is the same keyCode+modifiers combination already being claimed
+    /// system-wide by this or another process.
+    @discardableResult
+    public func register(
+        id: String,
+        keyCode: UInt32,
+        modifiers: UInt32,
+        handler: @escaping @MainActor () -> Void
+    ) -> Bool {
+        unregister(id: id)
+
+        let hotKeyID = EventHotKeyID(signature: shotdeckHotKeySignature, id: nextNumericID)
+        var ref: EventHotKeyRef?
+        let status = RegisterEventHotKey(
+            keyCode,
+            modifiers,
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        guard status == noErr, let ref else {
+            return false
+        }
+        bindings[id] = (ref: ref, numericID: nextNumericID)
+        HotkeyDispatchTable.shared.set(nextNumericID, handler)
+        nextNumericID += 1
+        return true
+    }
+
+    public func unregister(id: String) {
+        guard let binding = bindings.removeValue(forKey: id) else { return }
+        _ = UnregisterEventHotKey(binding.ref)
+        HotkeyDispatchTable.shared.remove(binding.numericID)
+    }
+
+    public func unregisterAll() {
+        let ids = Array(bindings.keys)
+        for id in ids {
+            unregister(id: id)
+        }
+    }
+
+    /// Installs the process-wide Carbon hot-key pressed handler exactly once.
+    private static func installGlobalCarbonHandlerIfNeeded() {
+        guard !didInstallGlobalCarbonHandler else { return }
+        didInstallGlobalCarbonHandler = true
+
+        var handlerRef: EventHandlerRef?
+        var eventTypes = [
+            EventTypeSpec(
+                eventClass: OSType(kEventClassKeyboard),
+                eventKind: OSType(kEventHotKeyPressed)
+            )
+        ]
+        let status = InstallEventHandler(
+            GetApplicationEventTarget(),
+            shotdeckCarbonHotkeyHandler,
+            1,
+            &eventTypes,
+            nil,
+            &handlerRef
+        )
+        if status == noErr {
+            carbonHandlerRef = handlerRef
+        }
+    }
+}

Sources/ShotdeckCore/Capture/ScreenCapturer.swift

@@ -0,0 +1,118 @@
+import ScreenCaptureKit
+import CoreGraphics
+import ImageIO
+import UniformTypeIdentifiers
+import AppKit  // NSScreen only, to read backingScaleFactor as a fallback
+import Foundation
+
+public struct CapturedImage: Sendable {
+    public let pngData: Data
+    public let pixelWidth: Int
+    public let pixelHeight: Int
+    public let scale: CGFloat
+}
+
+public struct ScreenCapturer: Sendable {
+    public init() {}
+
+    /// Does NOT prompt. Reports the current Screen Recording grant.
+    public static var isScreenRecordingGranted: Bool { CGPreflightScreenCaptureAccess() }
+
+    /// Captures `region` at the display's true backing scale. Throws
+    /// `.screenRecordingNotGranted` when the grant is absent — never requests it.
+    public func capture(_ region: CaptureRegion) async throws -> CapturedImage {
+        guard Self.isScreenRecordingGranted else {
+            throw ShotdeckError.screenRecordingNotGranted
+        }
+
+        let content: SCShareableContent
+        do {
+            content = try await SCShareableContent.excludingDesktopWindows(
+                false,
+                onScreenWindowsOnly: true
+            )
+        } catch {
+            throw ShotdeckError.captureFailed(underlying: error.localizedDescription)
+        }
+
+        guard let display = content.displays.first(where: { $0.displayID == region.displayID }) else {
+            throw ShotdeckError.displayNoLongerConnected(displayID: region.displayID)
+        }
+
+        // Bounds/clamp: a resolution change often shrinks the display bounds by a few
+        // points without the region Ben picked being meaningfully wrong; 80% keeps a real
+        // recapture usable while a smaller overlap (e.g. a genuinely different display
+        // swapped in) still throws.
+        let rect: CGRect
+        if display.frame.contains(region.rect) {
+            rect = region.rect
+        } else {
+            let overlap = display.frame.intersection(region.rect)
+            let originalArea = region.rect.width * region.rect.height
+            let overlapArea = overlap.width * overlap.height
+            if originalArea > 0 && overlapArea / originalArea >= 0.8 {
+                rect = overlap
+            } else {
+                throw ShotdeckError.displayNoLongerConnected(displayID: region.displayID)
+            }
+        }
+
+        let localRect = CGRect(
+            x: rect.minX - display.frame.minX,
+            y: rect.minY - display.frame.minY,
+            width: rect.width,
+            height: rect.height
+        )
+
+        guard let mode = CGDisplayCopyDisplayMode(region.displayID) else {
+            throw ShotdeckError.captureFailed(
+                underlying: "no display mode for displayID \(region.displayID)"
+            )
+        }
+        guard mode.width > 0 else {
+            throw ShotdeckError.captureFailed(
+                underlying: "display mode width is 0 for displayID \(region.displayID)"
+            )
+        }
+        let scale = CGFloat(mode.pixelWidth) / CGFloat(mode.width)
+
+        let filter = SCContentFilter(display: display, excludingWindows: [])
+        let configuration = SCStreamConfiguration()
+        configuration.sourceRect = localRect
+        configuration.width = Int((localRect.width * scale).rounded())
+        configuration.height = Int((localRect.height * scale).rounded())
+        configuration.scalesToFit = false
+        configuration.showsCursor = false
+
+        let cgImage: CGImage
+        do {
+            cgImage = try await SCScreenshotManager.captureImage(
+                contentFilter: filter,
+                configuration: configuration
+            )
+        } catch {
+            throw ShotdeckError.captureFailed(underlying: error.localizedDescription)
+        }
+
+        let data = NSMutableData()
+        guard let dest = CGImageDestinationCreateWithData(
+            data,
+            UTType.png.identifier as CFString,
+            1,
+            nil
+        ) else {
+            throw ShotdeckError.captureFailed(underlying: "could not create PNG image destination")
+        }
+        CGImageDestinationAddImage(dest, cgImage, nil)
+        guard CGImageDestinationFinalize(dest) else {
+            throw ShotdeckError.captureFailed(underlying: "PNG encoding failed to finalize")
+        }
+
+        return CapturedImage(
+            pngData: data as Data,
+            pixelWidth: cgImage.width,
+            pixelHeight: cgImage.height,
+            scale: scale
+        )
+    }
+}

Sources/ShotdeckCore/PDF/PDFComposer.swift

@@ -0,0 +1,209 @@
+import AppKit
+import CoreGraphics
+import CoreText
+import Foundation
+import ImageIO
+import os
+
+private let pdfLog = Logger(subsystem: "ai.flowmaster.shotdeck", category: "PDF")
+
+public struct PDFComposer: Sendable {
+    public init() {}
+
+    @discardableResult
+    public func compose(
+        session: CaptureSession,
+        imageURL: (Capture) -> URL,
+        title: String,
+        to outputURL: URL
+    ) throws -> Int {
+        if session.isEmpty {
+            throw ShotdeckError.pdfCompositionFailed(reason: "session has no captures")
+        }
+
+        var loaded: [(Capture, CGImage)] = []
+        loaded.reserveCapacity(session.captures.count)
+        for capture in session.captures {
+            let url = imageURL(capture)
+            if let image = Self.loadCGImage(from: url) {
+                loaded.append((capture, image))
+            } else {
+                pdfLog.error(
+                    "skipping capture \(capture.id.uuidString, privacy: .public) seq \(capture.sequence, privacy: .public): image unreadable at \(url.path, privacy: .public)"
+                )
+            }
+        }
+
+        guard !loaded.isEmpty else {
+            throw ShotdeckError.pdfCompositionFailed(reason: "no readable images in session")
+        }
+
+        let pageCount = loaded.count
+        let tmpURL = outputURL
+            .deletingLastPathComponent()
+            .appendingPathComponent(".tmp-\(UUID().uuidString)-\(outputURL.lastPathComponent)")
+
+        do {
+            try Self.writePDF(
+                loaded: loaded,
+                pageCount: pageCount,
+                title: title,
+                sessionID: session.id,
+                to: tmpURL
+            )
+
+            let handle = try FileHandle(forWritingTo: tmpURL)
+            try handle.synchronize()
+            try handle.close()
+
+            if FileManager.default.fileExists(atPath: outputURL.path) {
+                try FileManager.default.removeItem(at: outputURL)
+            }
+            try FileManager.default.moveItem(at: tmpURL, to: outputURL)
+            return pageCount
+        } catch {
+            try? FileManager.default.removeItem(at: tmpURL)
+            if let shotdeck = error as? ShotdeckError {
+                throw shotdeck
+            }
+            throw ShotdeckError.pdfCompositionFailed(reason: error.localizedDescription)
+        }
+    }
+
+    public static func fileName(for session: CaptureSession) -> String {
+        "Shotdeck-\(DubaiTime.fileStamp(session.createdAt)).pdf"
+    }
+
+    private static func writePDF(
+        loaded: [(Capture, CGImage)],
+        pageCount: Int,
+        title: String,
+        sessionID: UUID,
+        to tmpURL: URL
+    ) throws {
+        guard let consumer = CGDataConsumer(url: tmpURL as CFURL) else {
+            throw ShotdeckError.pdfCompositionFailed(reason: "cannot open output location")
+        }
+
+        let auxiliaryInfo: [String: Any] = [
+            kCGPDFContextCreator as String: "Shotdeck",
+            kCGPDFContextTitle as String: title,
+            kCGPDFContextSubject as String: sessionID.uuidString.lowercased(),
+        ]
+
+        guard let context = CGContext(
+            consumer: consumer,
+            mediaBox: nil,
+            auxiliaryInfo as CFDictionary
+        ) else {
+            throw ShotdeckError.pdfCompositionFailed(reason: "cannot open output location")
+        }
+
+        let lightGrey = CGColor(gray: 0.75, alpha: 1)
+        let black = CGColor(gray: 0, alpha: 1)
+        let timestampColor = CGColor(gray: 0.45, alpha: 1)
+
+        for pageIndex in 1...pageCount {
+            let (capture, cgImage) = loaded[pageIndex - 1]
+            let layout = PageLayout(capture: capture, pageIndex: pageIndex, pageCount: pageCount)
+
+            context.beginPDFPage(Self.pageInfo(mediaBox: layout.pageRect))
+
+            context.draw(cgImage, in: layout.imageRect)
+
+            context.setStrokeColor(lightGrey)
+            context.setLineWidth(0.5)
+            context.move(to: CGPoint(x: layout.headerRect.minX, y: layout.headerRect.minY))
+            context.addLine(to: CGPoint(x: layout.headerRect.maxX, y: layout.headerRect.minY))
+            context.strokePath()
+
+            drawText(
+                layout.pageNumberText,
+                font: layout.pageNumberFont,
+                color: black,
+                at: layout.pageNumberOrigin,
+                in: context
+            )
+            drawText(
+                layout.timestampText,
+                font: layout.timestampFont,
+                color: timestampColor,
+                at: layout.timestampOrigin,
+                in: context
+            )
+            drawText(
+                "PASS",
+                font: layout.tickLabelFont,
+                color: black,
+                at: layout.passLabelOrigin,
+                in: context
+            )
+            drawText(
+                "FAIL",
+                font: layout.tickLabelFont,
+                color: black,
+                at: layout.failLabelOrigin,
+                in: context
+            )
+
+            strokeTickBox(layout.passTickBox, in: context, color: black)
+            strokeTickBox(layout.failTickBox, in: context, color: black)
+
+            context.endPDFPage()
+        }
+
+        context.closePDF()
+    }
+
+    private static func pageInfo(mediaBox: CGRect) -> CFDictionary {
+        var box = mediaBox
+        let data = Data(bytes: &box, count: MemoryLayout<CGRect>.size)
+        return [kCGPDFContextMediaBox as String: data] as CFDictionary
+    }
+
+    private static func drawText(
+        _ string: String,
+        font: NSFont,
+        color: CGColor,
+        at origin: CGPoint,
+        in context: CGContext
+    ) {
+        let attributes: [CFString: Any] = [
+            kCTFontAttributeName: font,
+            kCTForegroundColorAttributeName: color,
+        ]
+        guard let attributed = CFAttributedStringCreate(
+            nil,
+            string as CFString,
+            attributes as CFDictionary
+        ) else {
+            return
+        }
+        let line = CTLineCreateWithAttributedString(attributed)
+        context.textMatrix = .identity
+        context.textPosition = origin
+        CTLineDraw(line, context)
+    }
+
+    private static func strokeTickBox(_ box: CGRect, in context: CGContext, color: CGColor) {
+        let path = CGPath(
+            roundedRect: box,
+            cornerWidth: 2,
+            cornerHeight: 2,
+            transform: nil
+        )
+        context.addPath(path)
+        context.setStrokeColor(color)
+        context.setLineWidth(1.0)
+        context.strokePath()
+    }
+
+    private static func loadCGImage(from url: URL) -> CGImage? {
+        guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+              CGImageSourceGetCount(source) > 0
+        else {
+            return nil
+        }
+        return CGImageSourceCreateImageAtIndex(source, 0, nil)
+    }
+}

Sources/ShotdeckCore/PDF/PageLayout.swift

@@ -0,0 +1,149 @@
+import AppKit
+import CoreGraphics
+import CoreText
+import Foundation
+
+public struct PageLayout: Sendable, Equatable {
+    public let isLandscape: Bool
+    public let pageRect: CGRect
+    public let headerRect: CGRect
+    public let imageBoxRect: CGRect
+    public let imageRect: CGRect
+
+    public let pageNumberText: String
+    public let pageNumberOrigin: CGPoint
+    public let timestampText: String
+    public let timestampOrigin: CGPoint
+
+    public let passLabelOrigin: CGPoint
+    public let failLabelOrigin: CGPoint
+    public let passTickBox: CGRect
+    public let failTickBox: CGRect
+
+    /// Constructed at access time so `PageLayout` stays Sendable under Swift 6
+    /// (`NSFont` is not Sendable). Same `NSFont.systemFont` values used for measurement.
+    public var pageNumberFont: NSFont { NSFont.systemFont(ofSize: 9, weight: .semibold) }
+    public var timestampFont: NSFont { NSFont.systemFont(ofSize: 9, weight: .regular) }
+    public var tickLabelFont: NSFont { NSFont.systemFont(ofSize: 8, weight: .semibold) }
+
+    private static let marginAll: CGFloat = 18
+    private static let headerHeight: CGFloat = 26
+    private static let headerImageGap: CGFloat = 10
+    private static let tickBoxSize: CGFloat = 13
+    private static let tickGroupGap: CGFloat = 8
+    private static let portraitPage = CGSize(width: 595, height: 842)
+    private static let landscapePage = CGSize(width: 842, height: 595)
+
+    /// `pageIndex` and `pageCount` are 1-based / total, over ACTUALLY-WRITTEN pages
+    /// (see SPEC decision D-D), not `capture.sequence` / `session.captures.count`.
+    public init(capture: Capture, pageIndex: Int, pageCount: Int) {
+        let pageNumberFont = NSFont.systemFont(ofSize: 9, weight: .semibold)
+        let timestampFont = NSFont.systemFont(ofSize: 9, weight: .regular)
+        let tickLabelFont = NSFont.systemFont(ofSize: 8, weight: .semibold)
+
+        isLandscape = capture.isLandscape
+        pageRect = CGRect(origin: .zero, size: isLandscape ? Self.landscapePage : Self.portraitPage)
+        let W = pageRect.width
+        let H = pageRect.height
+
+        let contentMinX = Self.marginAll
+        let contentMaxX = W - Self.marginAll
+        let contentMinY = Self.marginAll
+        let contentMaxY = H - Self.marginAll
+        let contentWidth = contentMaxX - contentMinX
+
+        headerRect = CGRect(
+            x: contentMinX,
+            y: contentMaxY - Self.headerHeight,
+            width: contentWidth,
+            height: Self.headerHeight
+        )
+
+        imageBoxRect = CGRect(
+            x: contentMinX,
+            y: contentMinY,
+            width: contentWidth,
+            height: headerRect.minY - Self.headerImageGap - contentMinY
+        )
+
+        let pointSize = CGSize(
+            width: CGFloat(capture.pixelWidth) / capture.scale,
+            height: CGFloat(capture.pixelHeight) / capture.scale
+        )
+        let fitScale = min(
+            imageBoxRect.width / pointSize.width,
+            imageBoxRect.height / pointSize.height,
+            1.0
+        )
+        let drawnSize = CGSize(
+            width: pointSize.width * fitScale,
+            height: pointSize.height * fitScale
+        )
+        imageRect = CGRect(
+            x: imageBoxRect.midX - drawnSize.width / 2,
+            y: imageBoxRect.midY - drawnSize.height / 2,
+            width: drawnSize.width,
+            height: drawnSize.height
+        )
+
+        let metricsFont = timestampFont as CTFont
+        let ascent = CTFontGetAscent(metricsFont)
+        let descent = CTFontGetDescent(metricsFont)
+        let baselineY = headerRect.minY + (headerRect.height - (ascent + descent)) / 2 + descent
+
+        pageNumberText = "\(pageIndex) / \(pageCount)"
+        pageNumberOrigin = CGPoint(x: headerRect.minX, y: baselineY)
+
+        timestampText = DubaiTime.stamp(capture.capturedAt)
+        let pageNumberWidth = Self.measuredWidth(pageNumberText, font: pageNumberFont)
+        timestampOrigin = CGPoint(x: headerRect.minX + pageNumberWidth + 10, y: baselineY)
+
+        let groupRightX = headerRect.maxX
+        let failBoxMinX = groupRightX - Self.tickBoxSize
+        let tickBoxY = headerRect.midY - Self.tickBoxSize / 2
+        failTickBox = CGRect(
+            x: failBoxMinX,
+            y: tickBoxY,
+            width: Self.tickBoxSize,
+            height: Self.tickBoxSize
+        )
+
+        let failLabelWidth = Self.measuredWidth("FAIL", font: tickLabelFont)
+        let failLabelMaxX = failTickBox.minX - Self.tickGroupGap
+        failLabelOrigin = CGPoint(x: failLabelMaxX - failLabelWidth, y: baselineY)
+
+        let passBoxMaxX = failLabelOrigin.x - Self.tickGroupGap
+        passTickBox = CGRect(
+            x: passBoxMaxX - Self.tickBoxSize,
+            y: tickBoxY,
+            width: Self.tickBoxSize,
+            height: Self.tickBoxSize
+        )
+
+        let passLabelWidth = Self.measuredWidth("PASS", font: tickLabelFont)
+        let passLabelMaxX = passTickBox.minX - Self.tickGroupGap
+        passLabelOrigin = CGPoint(x: passLabelMaxX - passLabelWidth, y: baselineY)
+    }
+
+    public static func == (lhs: PageLayout, rhs: PageLayout) -> Bool {
+        lhs.isLandscape == rhs.isLandscape
+            && lhs.pageRect == rhs.pageRect
+            && lhs.headerRect == rhs.headerRect
+            && lhs.imageBoxRect == rhs.imageBoxRect
+            && lhs.imageRect == rhs.imageRect
+            && lhs.pageNumberText == rhs.pageNumberText
+            && lhs.pageNumberOrigin == rhs.pageNumberOrigin
+            && lhs.timestampText == rhs.timestampText
+            && lhs.timestampOrigin == rhs.timestampOrigin
+            && lhs.passLabelOrigin == rhs.passLabelOrigin
+            && lhs.failLabelOrigin == rhs.failLabelOrigin
+            && lhs.passTickBox == rhs.passTickBox
+            && lhs.failTickBox == rhs.failTickBox
+    }
+
+    private static func measuredWidth(_ text: String, font: NSFont) -> CGFloat {
+        let attributed = NSAttributedString(string: text, attributes: [.font: font])
+        let line = CTLineCreateWithAttributedString(attributed)
+        return CGFloat(CTLineGetTypographicBounds(line, nil, nil, nil))
+    }
+}

Sources/ShotdeckCore/Returns/AnnotationInspector.swift

@@ -0,0 +1,110 @@
+import Foundation
+import PDFKit
+
+public struct ReturnedDocument: Codable, Sendable, Identifiable, Equatable {
+    public var id: URL { fileURL }
+    public let fileURL: URL
+    /// Session UUID recovered from the PDF's subject attribute, when present and valid.
+    public let sessionID: UUID?
+    public let pageCount: Int
+    /// 1-based page numbers that carry at least one human mark, ascending, no duplicates.
+    public let annotatedPages: [Int]
+    public let detectedAt: Date
+    public var isCommented: Bool { !annotatedPages.isEmpty }
+
+    public init(
+        fileURL: URL,
+        sessionID: UUID?,
+        pageCount: Int,
+        annotatedPages: [Int],
+        detectedAt: Date
+    ) {
+        self.fileURL = fileURL
+        self.sessionID = sessionID
+        self.pageCount = pageCount
+        self.annotatedPages = annotatedPages
+        self.detectedAt = detectedAt
+    }
+}
+
+public enum AnnotationInspector {
+    private static let humanMarkTypes: Set<String> = [
+        PDFAnnotationSubtype.ink.rawValue,
+        PDFAnnotationSubtype.highlight.rawValue,
+        PDFAnnotationSubtype.underline.rawValue,
+        PDFAnnotationSubtype.strikeOut.rawValue,
+        // PDFKit has no PDFAnnotationSubtype.squiggly member (unsupported renderer),
+        // but Apple Markup still writes Adobe /Squiggly objects that we must count.
+        PDFAnnotationSubtype(rawValue: "/Squiggly").rawValue,
+        PDFAnnotationSubtype.freeText.rawValue,
+        PDFAnnotationSubtype.square.rawValue,
+        PDFAnnotationSubtype.circle.rawValue,
+        PDFAnnotationSubtype.line.rawValue,
+        PDFAnnotationSubtype.stamp.rawValue,
+        PDFAnnotationSubtype.text.rawValue,
+    ]
+
+    // .link ignored: a PDF hyperlink is structural, not a human mark.
+    // .popup ignored: it is always the companion of another annotation; counting it
+    //   would double-count a single human mark as two.
+    // .widget ignored: a form field. Shotdeck's own PASS/FAIL boxes are page content
+    //   (drawn by WP-2), never PDFAnnotation objects — a widget seen here can only be
+    //   introduced by a third-party tool flattening/reopening the file, and is not a
+    //   human mark either way.
+
+    /// PDFKit's `PDFAnnotation.type` may omit the leading slash that
+    /// `PDFAnnotationSubtype.rawValue` includes; compare against the slash form.
+    private static func pdfTypeName(_ type: String) -> String {
+        type.hasPrefix("/") ? type : "/" + type
+    }
+
+    private static func isHumanMark(_ annotation: PDFAnnotation) -> Bool {
+        guard let raw = annotation.type else { return false }
+        let type = pdfTypeName(raw)
+        guard humanMarkTypes.contains(type) else { return false }
+        if type == PDFAnnotationSubtype.ink.rawValue {
+            let b = annotation.bounds
+            return b.width > 0 && b.height > 0   // zero-area ink = an undone stroke, not a mark
+        }
+        return true
+    }
+
+    /// Opens the PDF at fileURL and reports which pages carry a genuine human mark.
+    /// Throws ShotdeckError.manifestCorrupt(path: fileURL.path) if PDFDocument cannot open it.
+    /// File modification date is never consulted; only persisted PDFAnnotation objects count.
+    public static func inspect(fileURL: URL) throws -> ReturnedDocument {
+        guard let document = PDFDocument(url: fileURL) else {
+            throw ShotdeckError.manifestCorrupt(path: fileURL.path)
+        }
+        var annotatedPages: [Int] = []
+        for index in 0..<document.pageCount {
+            guard let page = document.page(at: index) else { continue }
+            if page.annotations.contains(where: isHumanMark) {
+                annotatedPages.append(index + 1)   // 1-based
+            }
+        }
+        var sessionID: UUID?
+        if let subject = document.documentAttributes?[PDFDocumentAttribute.subjectAttribute] as? String {
+            sessionID = UUID(uuidString: subject)   // nil (not thrown) if it doesn't parse
+        }
+        return ReturnedDocument(
+            fileURL: fileURL, sessionID: sessionID, pageCount: document.pageCount,
+            annotatedPages: annotatedPages, detectedAt: Date()
+        )
+    }
+
+    /// True when this PDF was produced by Shotdeck. Creator attribute is authoritative;
+    /// the filename fallback applies ONLY when the creator attribute is absent.
+    public static func isShotdeckDocument(_ document: PDFDocument) -> Bool {
+        if let creator = document.documentAttributes?[PDFDocumentAttribute.creatorAttribute] as? String {
+            return creator == "Shotdeck"          // present creator is authoritative, full stop
+        }
+        // Creator ABSENT (some apps rewrite metadata on save) -> filename fallback only here.
+        guard let name = document.documentURL?.lastPathComponent else { return false }
+        // .lastPathComponent on a file URL is already percent-decoded; do not use .absoluteString.
+        return name.wholeMatch(of: /^Shotdeck-\d{8}-\d{6}( \d+)?\.pdf$/) != nil
+        // Case-sensitive by construction (Swift Regex literals are case-sensitive by default).
+        // The optional "( \d+)?" is macOS's duplicate-name suffix AirDrop adds when a file of
+        // the same name already exists in the watch folder — the normal case for a return.
+    }
+}

Sources/ShotdeckCore/Returns/ReturnLedger.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+public actor ReturnLedger {
+    private let fileURL: URL
+    private var entries: [URL: ReturnedDocument]
+
+    /// Loads `returns.json` under paths.root if it exists; starts empty otherwise.
+    /// A file that cannot be decoded is renamed (never deleted) and the ledger starts empty.
+    public init(paths: AppSupportPaths) throws {
+        self.fileURL = paths.root.appendingPathComponent("returns.json")
+        if FileManager.default.fileExists(atPath: fileURL.path) {
+            let data = try Data(contentsOf: fileURL)
+            do {
+                let decoded = try JSONDecoder().decode([ReturnedDocument].self, from: data)
+                entries = Dictionary(decoded.map { ($0.fileURL, $0) }, uniquingKeysWith: { _, new in new })
+            } catch {
+                let stamp = DubaiTime.fileStamp(Date())
+                let corruptURL = fileURL.deletingLastPathComponent()
+                    .appendingPathComponent("returns.json.corrupt-\(stamp)")
+                try FileManager.default.moveItem(at: fileURL, to: corruptURL)
+                Log.returns.error(
+                    "returns.json could not be decoded; moved to \(corruptURL.path, privacy: .public): \(error.localizedDescription, privacy: .public)"
+                )
+                entries = [:]
+            }
+        } else {
+            entries = [:]
+        }
+    }
+
+    /// Upserts by fileURL — recording the same URL again replaces the prior entry
+    /// (the most recently recorded call wins, regardless of its detectedAt value).
+    public func record(_ document: ReturnedDocument) throws {
+        entries[document.fileURL] = document
+        try persist()
+    }
+
+    /// Every recorded return, newest detectedAt first.
+    public func all() throws -> [ReturnedDocument] {
+        entries.values.sorted { $0.detectedAt > $1.detectedAt }
+    }
+
+    /// Commented returns (isCommented == true), newest detectedAt first.
+    public func commented() throws -> [ReturnedDocument] {
+        try all().filter(\.isCommented)
+    }
+
+    /// Absolute POSIX paths of commented returns, newest first, one per line, no
+    /// trailing newline. Throws ShotdeckError.noCommentedReturns when commented() is empty.
+    public func clipboardText() throws -> String {
+        let paths = try commented().map { $0.fileURL.path }
+        guard !paths.isEmpty else { throw ShotdeckError.noCommentedReturns }
+        return paths.joined(separator: "\n")
+    }
+
+    private func persist() throws {
+        let data = try JSONEncoder().encode(Array(entries.values))
+        try AtomicFile.write(data, to: fileURL)
+    }
+}

Sources/ShotdeckCore/Returns/ReturnWatcher.swift

@@ -0,0 +1,154 @@
+import Foundation
+import PDFKit
+import CoreServices   // FSEventStream* APIs; system framework, no Package.swift change needed
+
+public actor ReturnWatcher {
+    private let ledger: ReturnLedger
+    private var watchFolder: URL
+    private var onChange: (@Sendable ([ReturnedDocument]) -> Void)?
+    private var stream: FSEventStreamRef?
+    private var bridge: FSEventBridge?
+    private var pendingScanTask: Task<Void, Never>?
+    private let eventQueue = DispatchQueue(label: "ai.flowmaster.shotdeck.returns.fsevents")
+
+    /// Watch folder is `paths.watchFolder`, which production constructs from
+    /// `FolderSettings.resolve().watch`. This type never calls FolderSettings;
+    /// `updateWatchFolder` is invoked by the UI layer only.
+    public init(paths: AppSupportPaths, ledger: ReturnLedger) {
+        self.ledger = ledger
+        self.watchFolder = paths.watchFolder   // never a literal "~/Downloads" here
+    }
+
+    /// Starts watching paths.watchFolder for returned PDFs. Performs one immediate
+    /// scanNow() before returning, then calls onChange after every subsequent debounced
+    /// batch (even if that batch's result is empty — the caller decides what to do).
+    public func start(onChange: @escaping @Sendable ([ReturnedDocument]) -> Void) async throws {
+        self.onChange = onChange
+        try startStream(on: watchFolder)
+        let found = try await scanNow()
+        onChange(found)
+    }
+
+    /// Idempotent. Stops and releases the FSEventStream if one is running; safe to call
+    /// when never started or already stopped. Cancels any pending debounced scan.
+    public func stop() {
+        // Idempotent: nil stream / already-stopped is a no-op; never started is the same.
+        pendingScanTask?.cancel()
+        pendingScanTask = nil
+        if let stream {
+            FSEventStreamStop(stream)
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+        }
+        stream = nil
+        bridge = nil
+    }
+
+    /// Called by whoever owns the Settings "Choose..." folder action (WP-4c) after the user
+    /// picks a new watch folder. If the watcher was running, stops the old FSEventStream,
+    /// switches to the new folder, restarts, and performs one immediate scanNow (reporting
+    /// through the same onChange callback given to start()). If the watcher was never
+    /// started, only updates the stored folder for the next start() call.
+    public func updateWatchFolder(_ url: URL) async throws {
+        let wasRunning = stream != nil
+        stop()
+        watchFolder = url
+        guard wasRunning else { return }
+        try startStream(on: url)
+        let found = try await scanNow()
+        onChange?(found)
+    }
+
+    /// Scans the watch folder once, immediately, without waiting for an event. Every
+    /// recognized, stable, openable Shotdeck PDF present is (re-)inspected and (re-)recorded
+    /// into the ledger; returns exactly the documents processed in this call.
+    @discardableResult
+    public func scanNow() async throws -> [ReturnedDocument] {
+        let fm = FileManager.default
+        let candidates = (try? fm.contentsOfDirectory(
+            at: watchFolder, includingPropertiesForKeys: nil
+        )) ?? []
+        var results: [ReturnedDocument] = []
+        for url in candidates.sorted(by: { $0.lastPathComponent < $1.lastPathComponent }) {
+            let name = url.lastPathComponent
+            // ".pdf.inprogress" already fails hasSuffix(".pdf") -> naturally skipped.
+            guard name.hasSuffix(".pdf"), !name.hasPrefix(".") else { continue }
+            guard await isStableAndReadable(url) else { continue }   // leave for next event
+            guard let document = PDFDocument(url: url),
+                  AnnotationInspector.isShotdeckDocument(document) else { continue }
+            guard let inspected = try? AnnotationInspector.inspect(fileURL: url) else { continue }
+            try await ledger.record(inspected)
+            results.append(inspected)
+        }
+        return results
+    }
+
+    /// Size-stable: two equal byte counts 250 ms apart AND PDFDocument opens;
+    /// otherwise leave the file for the next event.
+    private func isStableAndReadable(_ url: URL) async -> Bool {
+        let fm = FileManager.default
+        guard let size1 = try? fm.attributesOfItem(atPath: url.path)[.size] as? Int else { return false }
+        try? await Task.sleep(for: .milliseconds(250))
+        guard let size2 = try? fm.attributesOfItem(atPath: url.path)[.size] as? Int else { return false }
+        guard size1 == size2, size1 > 0 else { return false }
+        return PDFDocument(url: url) != nil
+    }
+
+    private func startStream(on folder: URL) throws {
+        let bridge = FSEventBridge { [weak self] in
+            guard let self else { return }
+            Task { await self.scheduleDebouncedScan() }
+        }
+        self.bridge = bridge
+        var context = FSEventStreamContext()
+        context.version = 0
+        context.info = Unmanaged.passUnretained(bridge).toOpaque()
+        context.retain = nil
+        context.release = nil
+        context.copyDescription = nil
+        guard let stream = FSEventStreamCreate(
+            kCFAllocatorDefault, shotdeckFSEventsCallback, &context,
+            [folder.path] as CFArray, FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.0,
+            FSEventStreamCreateFlags(kFSEventStreamCreateFlagFileEvents | kFSEventStreamCreateFlagNoDefer)
+        ) else {
+            throw ShotdeckError.captureFailed(underlying: "could not create FSEventStream for \(folder.path)")
+        }
+        // Dispatch queue, not a run loop: this actor has no run loop of its own, and
+        // FSEventStreamSetDispatchQueue is the modern replacement for
+        // FSEventStreamScheduleWithRunLoop. One dedicated serial queue per watcher.
+        FSEventStreamSetDispatchQueue(stream, eventQueue)
+        guard FSEventStreamStart(stream) else {
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+            throw ShotdeckError.captureFailed(underlying: "FSEventStreamStart failed for \(folder.path)")
+        }
+        self.stream = stream
+    }
+
+    private func scheduleDebouncedScan() async {
+        pendingScanTask?.cancel()
+        pendingScanTask = Task {
+            try? await Task.sleep(for: .milliseconds(400))   // coalesce AirDrop's write+rename burst
+            guard !Task.isCancelled else { return }
+            guard let found = try? await self.scanNow() else { return }
+            // One in-flight debounced callback may land after stop(); it is a
+            // harmless read-only rescan (ledger upsert, no watch-folder mutation).
+            self.onChange?(found)
+        }
+    }
+}
+
+/// Non-actor bridge because FSEventStreamCallback is a @convention(c) function pointer and
+/// cannot capture actor-isolated state directly; it hops back onto the actor via Task.
+private final class FSEventBridge: @unchecked Sendable {
+    // @unchecked is safe: `notify` is a let, set once at init, never mutated after — the
+    // type is immutable for its entire lifetime.
+    let notify: @Sendable () -> Void
+    init(notify: @escaping @Sendable () -> Void) { self.notify = notify }
+}
+
+private let shotdeckFSEventsCallback: FSEventStreamCallback = { _, info, _, _, _, _ in
+    guard let info else { return }
+    Unmanaged<FSEventBridge>.fromOpaque(info).takeUnretainedValue().notify()
+}

Tests/ShotdeckCoreTests/AnnotationInspectorTests.swift

@@ -0,0 +1,412 @@
+import AppKit
+import Foundation
+import PDFKit
+import Testing
+import ShotdeckCore
+
+private let pageBounds = CGRect(x: 0, y: 0, width: 600, height: 800)
+
+private func makeAnnotation(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect = CGRect(x: 100, y: 100, width: 80, height: 40),
+    contents: String? = nil
+) -> PDFAnnotation {
+    let annotation = PDFAnnotation(
+        bounds: bounds,
+        forType: subtype,
+        withProperties: nil
+    )
+    annotation.contents = contents
+    return annotation
+}
+
+private func makePDF(
+    at url: URL,
+    pageCount: Int,
+    creator: String? = "Shotdeck",
+    subject: String? = nil,
+    annotations: [(page: Int, annotation: PDFAnnotation)] = []
+) throws {
+    let document = PDFDocument()
+    for index in 0..<pageCount {
+        let page = PDFPage()
+        page.setBounds(pageBounds, for: .mediaBox)
+        document.insert(page, at: index)
+    }
+
+    var attributes = [PDFDocumentAttribute: Any]()
+    if let creator { attributes[.creatorAttribute] = creator }
+    if let subject { attributes[.subjectAttribute] = subject }
+    document.documentAttributes = attributes
+
+    for item in annotations {
+        guard let page = document.page(at: item.page) else {
+            throw NSError(domain: "WP5Test", code: 1)
+        }
+        page.addAnnotation(item.annotation)
+    }
+
+    guard document.write(to: url) else {
+        throw NSError(domain: "WP5Test", code: 2)
+    }
+}
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5a-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+@Test("I-1 Untouched PDF is clean")
+func i1_untouchedPDFIsClean() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134200.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        creator: "Shotdeck",
+        subject: "11111111-1111-1111-1111-111111111111"
+    )
+
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.timeZone = try #require(TimeZone(identifier: "Asia/Dubai"))
+    let firstMTime = try #require(calendar.date(from: DateComponents(
+        year: 2026, month: 8, day: 30, hour: 13, minute: 42, second: 0
+    )))
+    let secondMTime = try #require(calendar.date(from: DateComponents(
+        year: 2026, month: 8, day: 30, hour: 13, minute: 43, second: 0
+    )))
+    try FileManager.default.setAttributes([.modificationDate: firstMTime], ofItemAtPath: pdfURL.path)
+    try FileManager.default.setAttributes([.modificationDate: secondMTime], ofItemAtPath: pdfURL.path)
+
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.fileURL == pdfURL)
+    #expect(inspected.sessionID == UUID(uuidString: "11111111-1111-1111-1111-111111111111"))
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(inspected)
+    let all = try await ledger.all()
+    #expect(all.count == 1)
+    #expect(all[0].fileURL == pdfURL)
+    #expect(try await ledger.commented() == [])
+    let clipboardError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = clipboardError else {
+        Issue.record("expected noCommentedReturns, got \(clipboardError)")
+        return
+    }
+}
+
+@Test("I-2 Ink is a mark")
+func i2_inkIsAMark() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134201.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [(page: 1, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 120, y: 240, width: 140, height: 60)
+        ))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [2])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-3 Highlight is a mark")
+func i3_highlightIsAMark() throws {
+    try expectSinglePageMark(
+        .highlight,
+        bounds: CGRect(x: 80, y: 500, width: 300, height: 24),
+        fileName: "Shotdeck-20260830-134202.pdf"
+    )
+}
+
+@Test("I-4 Underline is a mark")
+func i4_underlineIsAMark() throws {
+    try expectSinglePageMark(
+        .underline,
+        bounds: CGRect(x: 90, y: 460, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134203.pdf"
+    )
+}
+
+@Test("I-5 Strike-out is a mark")
+func i5_strikeOutIsAMark() throws {
+    try expectSinglePageMark(
+        .strikeOut,
+        bounds: CGRect(x: 90, y: 430, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134204.pdf"
+    )
+}
+
+@Test("I-6 Squiggly is a mark")
+func i6_squigglyIsAMark() throws {
+    try expectSinglePageMark(
+        PDFAnnotationSubtype(rawValue: "/Squiggly"),
+        bounds: CGRect(x: 90, y: 400, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134205.pdf"
+    )
+}
+
+@Test("I-7 Free-text is a mark")
+func i7_freeTextIsAMark() throws {
+    try expectSinglePageMark(
+        .freeText,
+        bounds: CGRect(x: 140, y: 300, width: 220, height: 80),
+        contents: "Typed review note",
+        fileName: "Shotdeck-20260830-134206.pdf"
+    )
+}
+
+@Test("I-8 Square is a mark")
+func i8_squareIsAMark() throws {
+    try expectSinglePageMark(
+        .square,
+        bounds: CGRect(x: 160, y: 250, width: 100, height: 100),
+        fileName: "Shotdeck-20260830-134207.pdf"
+    )
+}
+
+@Test("I-9 Circle is a mark")
+func i9_circleIsAMark() throws {
+    try expectSinglePageMark(
+        .circle,
+        bounds: CGRect(x: 280, y: 250, width: 100, height: 100),
+        fileName: "Shotdeck-20260830-134208.pdf"
+    )
+}
+
+@Test("I-10 Line is a mark")
+func i10_lineIsAMark() throws {
+    try expectSinglePageMark(
+        .line,
+        bounds: CGRect(x: 100, y: 180, width: 320, height: 8),
+        fileName: "Shotdeck-20260830-134209.pdf"
+    )
+}
+
+@Test("I-11 Stamp is a mark")
+func i11_stampIsAMark() throws {
+    try expectSinglePageMark(
+        .stamp,
+        bounds: CGRect(x: 180, y: 500, width: 120, height: 60),
+        contents: "Approved",
+        fileName: "Shotdeck-20260830-134210.pdf"
+    )
+}
+
+@Test("I-12 Sticky text is a mark")
+func i12_stickyTextIsAMark() throws {
+    try expectSinglePageMark(
+        .text,
+        bounds: CGRect(x: 420, y: 620, width: 28, height: 28),
+        contents: "Look here",
+        fileName: "Shotdeck-20260830-134211.pdf"
+    )
+}
+
+@Test("I-13 Link alone is not a mark")
+func i13_linkAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .link,
+        bounds: CGRect(x: 80, y: 700, width: 160, height: 20),
+        fileName: "Shotdeck-20260830-134212.pdf"
+    )
+}
+
+@Test("I-14 Popup alone is not a mark")
+func i14_popupAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .popup,
+        bounds: CGRect(x: 450, y: 600, width: 100, height: 60),
+        fileName: "Shotdeck-20260830-134213.pdf"
+    )
+}
+
+@Test("I-15 Widget alone is not a mark")
+func i15_widgetAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .widget,
+        bounds: CGRect(x: 100, y: 100, width: 140, height: 32),
+        fileName: "Shotdeck-20260830-134214.pdf"
+    )
+}
+
+@Test("I-16 Zero-area ink is not a mark")
+func i16_zeroAreaInkIsNotAMark() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134215.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 240, y: 240, width: 0, height: 0)
+        ))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+}
+
+@Test("I-17 Ignored objects plus one real mark count once")
+func i17_ignoredObjectsPlusOneRealMarkCountOnce() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134216.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [
+            (page: 1, annotation: makeAnnotation(.link, bounds: CGRect(x: 20, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.popup, bounds: CGRect(x: 70, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.widget, bounds: CGRect(x: 120, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.ink, bounds: CGRect(x: 200, y: 200, width: 120, height: 50))),
+        ]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [2])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-18 Page numbers are 1-based and ascending")
+func i18_pageNumbersAre1BasedAndAscending() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134217.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [
+            (page: 0, annotation: makeAnnotation(.circle, bounds: CGRect(x: 260, y: 200, width: 70, height: 70))),
+            (page: 1, annotation: makeAnnotation(.link, bounds: CGRect(x: 80, y: 700, width: 160, height: 20))),
+            (page: 2, annotation: makeAnnotation(.ink, bounds: CGRect(x: 100, y: 100, width: 90, height: 40))),
+        ]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [1, 3])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-19 Session UUID recovery and invalid-subject tolerance")
+func i19_sessionUUIDRecoveryAndInvalidSubjectTolerance() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let validURL = paths.watchFolder.appendingPathComponent("valid-subject.pdf")
+    let invalidURL = paths.watchFolder.appendingPathComponent("invalid-subject.pdf")
+    let missingURL = paths.watchFolder.appendingPathComponent("missing-subject.pdf")
+
+    try makePDF(
+        at: validURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: "22222222-2222-2222-2222-222222222222"
+    )
+    try makePDF(
+        at: invalidURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: "not-a-uuid"
+    )
+    try makePDF(
+        at: missingURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: nil
+    )
+
+    let valid = try AnnotationInspector.inspect(fileURL: validURL)
+    #expect(valid.sessionID == UUID(uuidString: "22222222-2222-2222-2222-222222222222"))
+    #expect(valid.pageCount == 1)
+    #expect(valid.annotatedPages == [])
+    #expect(valid.isCommented == false)
+
+    let invalid = try AnnotationInspector.inspect(fileURL: invalidURL)
+    #expect(invalid.sessionID == nil)
+    #expect(invalid.annotatedPages == [])
+    #expect(invalid.isCommented == false)
+
+    let missing = try AnnotationInspector.inspect(fileURL: missingURL)
+    #expect(missing.sessionID == nil)
+    #expect(missing.annotatedPages == [])
+    #expect(missing.isCommented == false)
+}
+
+@Test("I-19b Present non-Shotdeck creator beats a matching filename")
+func i19b_presentNonShotdeckCreatorBeatsMatchingFilename() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134218.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: "Preview",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+    let reopened = try #require(PDFDocument(url: pdfURL))
+    #expect(AnnotationInspector.isShotdeckDocument(reopened) == false)
+}
+
+private func expectSinglePageMark(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect,
+    contents: String? = nil,
+    fileName: String
+) throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent(fileName)
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(subtype, bounds: bounds, contents: contents))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 1)
+    #expect(inspected.annotatedPages == [1])
+    #expect(inspected.isCommented == true)
+}
+
+private func expectSinglePageIgnored(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect,
+    fileName: String
+) throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent(fileName)
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(subtype, bounds: bounds))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+}

Tests/ShotdeckCoreTests/CaptureRegionTests.swift

@@ -0,0 +1,171 @@
+import Carbon.HIToolbox
+import Foundation
+import Testing
+@testable import ShotdeckCore
+
+@Test("GEO-1 primary-only 1080-tall screen, AppKit rect (100,100,400,300)")
+func geo1_primaryOnlyAppKitRectConvertsToExpectedCGRect() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 100, y: 100, width: 400, height: 300),
+        displayID: 1,
+        capturedScale: 2,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: 100, y: 680, width: 400, height: 300))
+}
+
+@Test("GEO-2 rect flush to AppKit bottom (y=0), h=300, primaryHeight=1080")
+func geo2_flushToAppKitBottomYieldsCGY780() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 50, y: 0, width: 200, height: 300),
+        displayID: 1,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect.origin.y == 780)
+}
+
+@Test("GEO-3 rect flush to AppKit top (y+h=primaryHeight), primaryHeight=1080, h=300")
+func geo3_flushToAppKitTopYieldsCGY0() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 50, y: 780, width: 200, height: 300),
+        displayID: 1,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect.origin.y == 0)
+}
+
+@Test("GEO-4 round-trip AppKit→CG via injectable overload, then invert recovers original")
+func geo4_invertRecoverOriginalAppKitRect() {
+    let original = CGRect(x: 100, y: 100, width: 400, height: 300)
+    let primaryHeight: CGFloat = 1080
+    let region = CaptureRegion.fromAppKit(
+        rect: original,
+        displayID: 1,
+        capturedScale: 2,
+        primaryHeight: primaryHeight
+    )
+    let appKitY = primaryHeight - region.rect.origin.y - region.rect.height
+    let recovered = CGRect(
+        x: region.rect.origin.x,
+        y: appKitY,
+        width: region.rect.width,
+        height: region.rect.height
+    )
+    #expect(recovered == original)
+}
+
+@Test("GEO-5 isStillValid for displayID 999_999 is false and does not trap")
+func geo5_unknownDisplayIsNotStillValid() {
+    let region = CaptureRegion(
+        displayID: 999_999,
+        rect: CGRect(x: 0, y: 0, width: 100, height: 100),
+        capturedScale: 1
+    )
+    #expect(region.isStillValid == false)
+}
+
+@Test("GEO-6 CaptureRegion JSONEncoder→JSONDecoder round-trip equals original")
+func geo6_codableRoundTripEqualsOriginal() throws {
+    let original = CaptureRegion(
+        displayID: 42,
+        rect: CGRect(x: 10, y: 20, width: 300, height: 400),
+        capturedScale: 2
+    )
+    let data = try JSONEncoder().encode(original)
+    let decoded = try JSONDecoder().decode(CaptureRegion.self, from: data)
+    #expect(decoded == original)
+}
+
+@Test("GEO-7 secondary screen negative x: AppKit (−1800,200,500,400) → CG (−1800,480,500,400)")
+func geo7_secondaryNegativeXLeavesXUnchanged() {
+    // Secondary AppKit frame (−1920, 0, 1920, 1080); primaryHeight=1080.
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: -1800, y: 200, width: 500, height: 400),
+        displayID: 2,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: -1800, y: 480, width: 500, height: 400))
+}
+
+@Test("GEO-8 secondary screen stacked above primary: AppKit (300,1300,600,350) → CG (300,−570,600,350)")
+func geo8_secondaryPositiveYProducesNegativeCGY() {
+    // Secondary AppKit frame (0, 1080, 1920, 1080); primaryHeight=1080.
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 300, y: 1300, width: 600, height: 350),
+        displayID: 2,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: 300, y: -570, width: 600, height: 350))
+}
+
+/// Carbon registrations are process-wide, so these cases must not run in parallel.
+@Suite(.serialized)
+@MainActor
+struct HotkeyCenterCarbonTests {
+    /// kVK_ANSI_2. The app registers this combo once (WP-4a); tests only exercise the registrar.
+    private let captureKeyCode: UInt32 = 19
+    private let captureModifiers = UInt32(optionKey) | UInt32(shiftKey)
+
+    @Test("HK-1 register id a with Option-Shift-2 returns true")
+    func hk1_registerReturnsTrue() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let ok = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !ok {
+            Issue.record("HK-1: RegisterEventHotKey returned non-noErr inside swift test (no NSApplication). Carbon registration did not function headlessly.")
+            return
+        }
+        #expect(ok)
+    }
+
+    @Test("HK-2 register same combo under a different id returns false")
+    func hk2_duplicateComboRejected() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !first {
+            Issue.record("HK-2: first RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate duplicate-combo rejection.")
+            return
+        }
+        let second = center.register(id: "b", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(second == false)
+    }
+
+    @Test("HK-3 unregister frees the combination so a later register succeeds")
+    func hk3_unregisterFreesCombination() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !first {
+            Issue.record("HK-3: first RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate unregister.")
+            return
+        }
+        center.unregister(id: "a")
+        let again = center.register(id: "c", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(again)
+    }
+
+    @Test("HK-4 unregisterAll frees combinations so a later register succeeds")
+    func hk4_unregisterAllFreesCombinations() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        let other = center.register(
+            id: "other",
+            keyCode: UInt32(kVK_ANSI_3),
+            modifiers: captureModifiers
+        ) {}
+        if !first {
+            Issue.record("HK-4: RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate unregisterAll.")
+            return
+        }
+        _ = other
+        center.unregisterAll()
+        let again = center.register(id: "c", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(again)
+    }
+}

Tests/ShotdeckCoreTests/PDFComposerTests.swift

@@ -0,0 +1,579 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+import PDFKit
+import ShotdeckCore
+import Testing
+import UniformTypeIdentifiers
+
+enum TestFixtureError: Error { case cannotCreateBitmap, cannotCreatePNG, cannotFinalizePNG }
+
+func writeSolidPNG(
+    pixelWidth: Int,
+    pixelHeight: Int,
+    red: UInt8,
+    green: UInt8,
+    blue: UInt8,
+    to url: URL
+) throws {
+    let colorSpace = CGColorSpaceCreateDeviceRGB()
+    guard let context = CGContext(
+        data: nil,
+        width: pixelWidth,
+        height: pixelHeight,
+        bitsPerComponent: 8,
+        bytesPerRow: pixelWidth * 4,
+        space: colorSpace,
+        bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+    ) else { throw TestFixtureError.cannotCreateBitmap }
+    context.setFillColor(CGColor(
+        red: CGFloat(red) / 255,
+        green: CGFloat(green) / 255,
+        blue: CGFloat(blue) / 255,
+        alpha: 1
+    ))
+    context.fill(CGRect(x: 0, y: 0, width: pixelWidth, height: pixelHeight))
+    guard let image = context.makeImage(),
+          let destination = CGImageDestinationCreateWithURL(
+              url as CFURL,
+              UTType.png.identifier as CFString,
+              1,
+              nil
+          )
+    else { throw TestFixtureError.cannotCreatePNG }
+    CGImageDestinationAddImage(destination, image, nil)
+    guard CGImageDestinationFinalize(destination) else { throw TestFixtureError.cannotFinalizePNG }
+}
+
+private let fixtureDate = Date(timeIntervalSince1970: 1_777_482_180)
+
+private func makeCapture(
+    sequence: Int,
+    pixelWidth: Int,
+    pixelHeight: Int,
+    scale: CGFloat = 1,
+    capturedAt: Date = fixtureDate,
+    id: UUID = UUID(),
+    fileName: String? = nil
+) -> Capture {
+    Capture(
+        id: id,
+        sequence: sequence,
+        fileName: fileName ?? String(format: "%03d.png", sequence),
+        pixelWidth: pixelWidth,
+        pixelHeight: pixelHeight,
+        scale: scale,
+        capturedAt: capturedAt
+    )
+}
+
+private func makeSession(
+    captures: [Capture],
+    id: UUID = UUID(),
+    createdAt: Date = fixtureDate
+) -> CaptureSession {
+    CaptureSession(
+        id: id,
+        createdAt: createdAt,
+        state: .open,
+        captures: captures,
+        pdfFileName: nil
+    )
+}
+
+private func makeScratchDirectory() throws -> URL {
+    let url = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-pdf-\(UUID().uuidString)", isDirectory: true)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+    return url
+}
+
+private func writePNG(
+    for capture: Capture,
+    red: UInt8,
+    green: UInt8,
+    blue: UInt8,
+    in directory: URL
+) throws -> URL {
+    let url = directory.appendingPathComponent(capture.fileName)
+    try writeSolidPNG(
+        pixelWidth: capture.pixelWidth,
+        pixelHeight: capture.pixelHeight,
+        red: red,
+        green: green,
+        blue: blue,
+        to: url
+    )
+    return url
+}
+
+private func imageURLMap(_ urls: [UUID: URL]) -> (Capture) -> URL {
+    { capture in
+        urls[capture.id] ?? URL(fileURLWithPath: "/nonexistent/\(capture.id.uuidString).png")
+    }
+}
+
+private func openDocument(_ url: URL) throws -> PDFDocument {
+    let document = try #require(PDFDocument(url: url))
+    return document
+}
+
+private func pdftoppm(pdf: URL, prefix: URL) throws {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: "/opt/homebrew/bin/pdftoppm")
+    process.arguments = ["-png", "-r", "110", pdf.path, prefix.path]
+    let err = Pipe()
+    process.standardError = err
+    try process.run()
+    process.waitUntilExit()
+    guard process.terminationStatus == 0 else {
+        let message = String(data: err.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+        throw ShotdeckError.pdfCompositionFailed(reason: "pdftoppm failed: \(message)")
+    }
+}
+
+private struct RGBABitmap {
+    let width: Int
+    let height: Int
+    let bytesPerRow: Int
+    let data: Data
+
+    func pixel(x: Int, y: Int) -> (UInt8, UInt8, UInt8)? {
+        guard x >= 0, y >= 0, x < width, y < height else { return nil }
+        let offset = y * bytesPerRow + x * 4
+        guard offset + 2 < data.count else { return nil }
+        return (data[offset], data[offset + 1], data[offset + 2])
+    }
+
+    func containsNonWhite(x0: Int, y0: Int, x1: Int, y1: Int) -> Bool {
+        let xStart = max(0, x0)
+        let yStart = max(0, y0)
+        let xEnd = min(width, x1)
+        let yEnd = min(height, y1)
+        guard xStart < xEnd, yStart < yEnd else { return false }
+        for y in yStart..<yEnd {
+            for x in xStart..<xEnd {
+                if let (r, g, b) = pixel(x: x, y: y), r != 255 || g != 255 || b != 255 {
+                    return true
+                }
+            }
+        }
+        return false
+    }
+
+    static func loadPNG(at url: URL) throws -> RGBABitmap {
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        let source = try #require(CGImageSourceCreateWithURL(url as CFURL, nil))
+        let image = try #require(CGImageSourceCreateImageAtIndex(source, 0, nil))
+        let width = image.width
+        let height = image.height
+        let bytesPerRow = width * 4
+        var data = Data(count: bytesPerRow * height)
+        try data.withUnsafeMutableBytes { raw in
+            guard let base = raw.baseAddress else {
+                throw TestFixtureError.cannotCreateBitmap
+            }
+            guard let context = CGContext(
+                data: base,
+                width: width,
+                height: height,
+                bitsPerComponent: 8,
+                bytesPerRow: bytesPerRow,
+                space: colorSpace,
+                bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+            ) else {
+                throw TestFixtureError.cannotCreateBitmap
+            }
+            context.interpolationQuality = .none
+            context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+        }
+        return RGBABitmap(width: width, height: height, bytesPerRow: bytesPerRow, data: data)
+    }
+}
+
+private func pixelWindow(
+    for rect: CGRect,
+    pageHeightPt: CGFloat,
+    scale k: CGFloat
+) -> (x0: Int, y0: Int, x1: Int, y1: Int) {
+    let pixelX0 = Int(floor(rect.minX * k))
+    let pixelX1 = Int(ceil(rect.maxX * k))
+    let pixelY0 = Int(floor((pageHeightPt - rect.maxY) * k))
+    let pixelY1 = Int(ceil((pageHeightPt - rect.minY) * k))
+    return (pixelX0, pixelY0, pixelX1, pixelY1)
+}
+
+@Test("Three-page basic compose")
+func threePageBasicCompose() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let c1 = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let c2 = makeCapture(sequence: 2, pixelWidth: 900, pixelHeight: 1600)
+    let c3 = makeCapture(sequence: 3, pixelWidth: 1200, pixelHeight: 800)
+    let urls: [UUID: URL] = [
+        c1.id: try writePNG(for: c1, red: 200, green: 20, blue: 20, in: directory),
+        c2.id: try writePNG(for: c2, red: 20, green: 200, blue: 20, in: directory),
+        c3.id: try writePNG(for: c3, red: 20, green: 20, blue: 200, in: directory),
+    ]
+    let session = makeSession(captures: [c1, c2, c3])
+    let output = directory.appendingPathComponent("three.pdf")
+    let pageCount = try PDFComposer().compose(
+        session: session,
+        imageURL: imageURLMap(urls),
+        title: "Three page",
+        to: output
+    )
+    #expect(pageCount == 3)
+    let document = try openDocument(output)
+    #expect(document.pageCount == 3)
+    let p0 = try #require(document.page(at: 0))
+    let p1 = try #require(document.page(at: 1))
+    let p2 = try #require(document.page(at: 2))
+    #expect(p0.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 842, height: 595))
+    #expect(p1.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+    #expect(p2.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 842, height: 595))
+}
+
+@Test("Wide/tall page geometry exact")
+func wideTallPageGeometryExact() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let wide = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let tall = makeCapture(sequence: 1, pixelWidth: 900, pixelHeight: 1600)
+    let wideURL = try writePNG(for: wide, red: 10, green: 10, blue: 10, in: directory)
+    let tallURL = try writePNG(for: tall, red: 10, green: 10, blue: 10, in: directory)
+
+    let wideOut = directory.appendingPathComponent("wide.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [wide]),
+        imageURL: { _ in wideURL },
+        title: "Wide",
+        to: wideOut
+    )
+    let tallOut = directory.appendingPathComponent("tall.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [tall]),
+        imageURL: { _ in tallURL },
+        title: "Tall",
+        to: tallOut
+    )
+
+    let widePage = try #require(openDocument(wideOut).page(at: 0))
+    let tallPage = try #require(openDocument(tallOut).page(at: 0))
+    #expect(widePage.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 842, height: 595))
+    #expect(tallPage.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+}
+
+@Test("Square resolves to portrait (Capture.swift:39-42 isLandscape strict >)")
+func squareResolvesToPortrait() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let square = makeCapture(sequence: 1, pixelWidth: 1000, pixelHeight: 1000)
+    let png = try writePNG(for: square, red: 80, green: 80, blue: 80, in: directory)
+    let output = directory.appendingPathComponent("square.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [square]),
+        imageURL: { _ in png },
+        title: "Square",
+        to: output
+    )
+    let page = try #require(openDocument(output).page(at: 0))
+    #expect(page.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+}
+
+@Test("Retina capture uses point size, not pixel size")
+func retinaCaptureUsesPointSize() throws {
+    let capture = makeCapture(sequence: 1, pixelWidth: 2880, pixelHeight: 1620, scale: 2.0)
+    let layout = PageLayout(capture: capture, pageIndex: 1, pageCount: 1)
+    let expectedScale = min(806.0 / 1440.0, 523.0 / 810.0, 1.0)
+    let expected = CGSize(width: 1440.0 * expectedScale, height: 810.0 * expectedScale)
+    #expect(abs(layout.imageRect.width - expected.width) < 0.01)
+    #expect(abs(layout.imageRect.height - expected.height) < 0.01)
+    #expect(layout.imageRect.width < 2000)
+    #expect(layout.isLandscape)
+}
+
+@Test("Zero PDFAnnotation objects on every page")
+func zeroPDFAnnotationObjects() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let c1 = makeCapture(sequence: 1, pixelWidth: 800, pixelHeight: 600)
+    let c2 = makeCapture(sequence: 2, pixelWidth: 600, pixelHeight: 800)
+    let c3 = makeCapture(sequence: 3, pixelWidth: 1000, pixelHeight: 1000)
+    let urls: [UUID: URL] = [
+        c1.id: try writePNG(for: c1, red: 30, green: 30, blue: 30, in: directory),
+        c2.id: try writePNG(for: c2, red: 40, green: 40, blue: 40, in: directory),
+        c3.id: try writePNG(for: c3, red: 50, green: 50, blue: 50, in: directory),
+    ]
+    let output = directory.appendingPathComponent("no-annots.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [c1, c2, c3]),
+        imageURL: imageURLMap(urls),
+        title: "No annotations",
+        to: output
+    )
+    let document = try openDocument(output)
+    #expect(document.pageCount == 3)
+    for index in 0..<document.pageCount {
+        let page = try #require(document.page(at: index))
+        #expect(page.annotations.isEmpty)
+    }
+}
+
+@Test("Mixed orientations coexist, unnormalised")
+func mixedOrientationsCoexist() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let wide = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let tall = makeCapture(sequence: 2, pixelWidth: 900, pixelHeight: 1600)
+    let square = makeCapture(sequence: 3, pixelWidth: 1000, pixelHeight: 1000)
+    let urls: [UUID: URL] = [
+        wide.id: try writePNG(for: wide, red: 90, green: 10, blue: 10, in: directory),
+        tall.id: try writePNG(for: tall, red: 10, green: 90, blue: 10, in: directory),
+        square.id: try writePNG(for: square, red: 10, green: 10, blue: 90, in: directory),
+    ]
+    let output = directory.appendingPathComponent("mixed.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [wide, tall, square]),
+        imageURL: imageURLMap(urls),
+        title: "Mixed",
+        to: output
+    )
+    let document = try openDocument(output)
+    #expect(document.pageCount == 3)
+    let p0 = try #require(document.page(at: 0))
+    let p1 = try #require(document.page(at: 1))
+    let p2 = try #require(document.page(at: 2))
+    #expect(p0.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 842, height: 595))
+    #expect(p1.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+    #expect(p2.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+}
+
+@Test("No cover page, no before/after, exactly one page per capture")
+func noCoverPageExactlyOnePagePerCapture() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let c1 = makeCapture(sequence: 1, pixelWidth: 800, pixelHeight: 500)
+    let c2 = makeCapture(sequence: 2, pixelWidth: 500, pixelHeight: 800)
+    let urls: [UUID: URL] = [
+        c1.id: try writePNG(for: c1, red: 12, green: 12, blue: 12, in: directory),
+        c2.id: try writePNG(for: c2, red: 22, green: 22, blue: 22, in: directory),
+    ]
+    let output = directory.appendingPathComponent("two.pdf")
+    let pageCount = try PDFComposer().compose(
+        session: makeSession(captures: [c1, c2]),
+        imageURL: imageURLMap(urls),
+        title: "Two",
+        to: output
+    )
+    #expect(pageCount == 2)
+    #expect(try openDocument(output).pageCount == 2)
+}
+
+@Test("Small image is never upscaled")
+func smallImageIsNeverUpscaled() throws {
+    let capture = makeCapture(sequence: 1, pixelWidth: 200, pixelHeight: 150)
+    let layout = PageLayout(capture: capture, pageIndex: 1, pageCount: 1)
+    #expect(layout.imageRect.size == CGSize(width: 200, height: 150))
+}
+
+@Test("Empty session throws, produces nothing on disk")
+func emptySessionThrowsProducesNothing() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let output = directory.appendingPathComponent("empty.pdf")
+    var threwCompositionFailed = false
+    do {
+        _ = try PDFComposer().compose(
+            session: makeSession(captures: []),
+            imageURL: { _ in directory.appendingPathComponent("missing.png") },
+            title: "Empty",
+            to: output
+        )
+    } catch ShotdeckError.pdfCompositionFailed {
+        threwCompositionFailed = true
+    }
+    #expect(threwCompositionFailed)
+    #expect(!FileManager.default.fileExists(atPath: output.path))
+    let leftover = try FileManager.default.contentsOfDirectory(atPath: directory.path)
+    #expect(leftover.isEmpty)
+}
+
+@Test("A missing PNG is skipped, page count drops, document still opens")
+func missingPNGIsSkipped() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let first = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let missing = makeCapture(sequence: 2, pixelWidth: 800, pixelHeight: 600)
+    let third = makeCapture(sequence: 3, pixelWidth: 900, pixelHeight: 1600)
+    let firstURL = try writePNG(for: first, red: 220, green: 10, blue: 10, in: directory)
+    let thirdURL = try writePNG(for: third, red: 10, green: 10, blue: 220, in: directory)
+    let missingURL = directory.appendingPathComponent("does-not-exist.png")
+    let urls: [UUID: URL] = [
+        first.id: firstURL,
+        missing.id: missingURL,
+        third.id: thirdURL,
+    ]
+    let output = directory.appendingPathComponent("skip-missing.pdf")
+    let pageCount = try PDFComposer().compose(
+        session: makeSession(captures: [first, missing, third]),
+        imageURL: imageURLMap(urls),
+        title: "Skip missing",
+        to: output
+    )
+    #expect(pageCount == 2)
+    let document = try openDocument(output)
+    #expect(document.pageCount == 2)
+    let p0 = try #require(document.page(at: 0))
+    let p1 = try #require(document.page(at: 1))
+    #expect(p0.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 842, height: 595))
+    #expect(p1.bounds(for: .mediaBox) == CGRect(x: 0, y: 0, width: 595, height: 842))
+
+    // Distinct fill colors sampled from pdftoppm at each imageRect center.
+    let prefix = directory.appendingPathComponent("skip-missing")
+    try pdftoppm(pdf: output, prefix: prefix)
+    let page1PNG = directory.appendingPathComponent("skip-missing-1.png")
+    let page2PNG = directory.appendingPathComponent("skip-missing-2.png")
+    let bitmap1 = try RGBABitmap.loadPNG(at: page1PNG)
+    let bitmap2 = try RGBABitmap.loadPNG(at: page2PNG)
+    let k = 110.0 / 72.0
+    let layout1 = PageLayout(capture: first, pageIndex: 1, pageCount: 2)
+    let layout2 = PageLayout(capture: third, pageIndex: 2, pageCount: 2)
+    let c1 = try #require(bitmap1.pixel(
+        x: Int((layout1.imageRect.midX * k).rounded()),
+        y: Int(((layout1.pageRect.height - layout1.imageRect.midY) * k).rounded())
+    ))
+    let c2 = try #require(bitmap2.pixel(
+        x: Int((layout2.imageRect.midX * k).rounded()),
+        y: Int(((layout2.pageRect.height - layout2.imageRect.midY) * k).rounded())
+    ))
+    #expect(c1.0 > 150 && c1.1 < 80 && c1.2 < 80)
+    #expect(c2.2 > 150 && c2.0 < 80 && c2.1 < 80)
+}
+
+@Test("An unreadable (corrupt) PNG is treated exactly like a missing one (D-A)")
+func unreadablePNGIsSkippedLikeMissing() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let good = makeCapture(sequence: 1, pixelWidth: 800, pixelHeight: 500)
+    let bad = makeCapture(sequence: 2, pixelWidth: 800, pixelHeight: 500)
+    let goodURL = try writePNG(for: good, red: 30, green: 140, blue: 30, in: directory)
+    let badURL = directory.appendingPathComponent("corrupt.png")
+    try Data([0x00, 0x01, 0x02, 0xFF, 0xD8, 0x00]).write(to: badURL)
+    let urls: [UUID: URL] = [good.id: goodURL, bad.id: badURL]
+    let output = directory.appendingPathComponent("skip-corrupt.pdf")
+    let pageCount = try PDFComposer().compose(
+        session: makeSession(captures: [good, bad]),
+        imageURL: imageURLMap(urls),
+        title: "Skip corrupt",
+        to: output
+    )
+    #expect(pageCount == 1)
+    let document = try openDocument(output)
+    #expect(document.pageCount == 1)
+}
+
+@Test("Document attributes round-trip exactly")
+func documentAttributesRoundTrip() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let sessionID = try #require(UUID(uuidString: "deadbeef-dead-4eef-8ead-deadbeef0001"))
+    let capture = makeCapture(sequence: 1, pixelWidth: 640, pixelHeight: 480)
+    let png = try writePNG(for: capture, red: 40, green: 40, blue: 40, in: directory)
+    let output = directory.appendingPathComponent("attrs.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [capture], id: sessionID),
+        imageURL: { _ in png },
+        title: "Ben review — 2026-08-30",
+        to: output
+    )
+    let document = try openDocument(output)
+    let attributes = try #require(document.documentAttributes)
+    #expect(attributes[PDFDocumentAttribute.creatorAttribute] as? String == "Shotdeck")
+    #expect(attributes[PDFDocumentAttribute.titleAttribute] as? String == "Ben review — 2026-08-30")
+    #expect(attributes[PDFDocumentAttribute.subjectAttribute] as? String == "deadbeef-dead-4eef-8ead-deadbeef0001")
+    #expect(document.pageCount == 1)
+    #expect(try #require(document.page(at: 0)).annotations.isEmpty)
+}
+
+@Test("Rendered page is not blank (pdftoppm, pinned renderer + rounding)")
+func renderedPageIsNotBlank() throws {
+    let directory = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let capture = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let png = try writePNG(for: capture, red: 128, green: 128, blue: 128, in: directory)
+    let output = directory.appendingPathComponent("not-blank.pdf")
+    _ = try PDFComposer().compose(
+        session: makeSession(captures: [capture]),
+        imageURL: { _ in png },
+        title: "Not blank",
+        to: output
+    )
+    let prefix = directory.appendingPathComponent("not-blank")
+    try pdftoppm(pdf: output, prefix: prefix)
+    let rendered = directory.appendingPathComponent("not-blank-1.png")
+    let bitmap = try RGBABitmap.loadPNG(at: rendered)
+    let layout = PageLayout(capture: capture, pageIndex: 1, pageCount: 1)
+    let k: CGFloat = 110.0 / 72.0
+    let imageWin = pixelWindow(for: layout.imageRect, pageHeightPt: layout.pageRect.height, scale: k)
+    let headerWin = pixelWindow(for: layout.headerRect, pageHeightPt: layout.pageRect.height, scale: k)
+    #expect(bitmap.containsNonWhite(x0: imageWin.x0, y0: imageWin.y0, x1: imageWin.x1, y1: imageWin.y1))
+    #expect(bitmap.containsNonWhite(x0: headerWin.x0, y0: headerWin.y0, x1: headerWin.x1, y1: headerWin.y1))
+}
+
+@Test("Right-edge tick group geometry matches D-12 exactly, both orientations")
+func rightEdgeTickGroupGeometry() throws {
+    let landscape = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let portrait = makeCapture(sequence: 1, pixelWidth: 900, pixelHeight: 1600)
+    let landscapeLayout = PageLayout(capture: landscape, pageIndex: 1, pageCount: 1)
+    let portraitLayout = PageLayout(capture: portrait, pageIndex: 1, pageCount: 1)
+
+    #expect(landscapeLayout.failTickBox.maxX == 824)
+    #expect(landscapeLayout.headerRect.maxX == 824)
+    #expect(portraitLayout.failTickBox.maxX == 577)
+    #expect(portraitLayout.headerRect.maxX == 577)
+    #expect(landscapeLayout.failTickBox.width == 13)
+    #expect(landscapeLayout.failTickBox.height == 13)
+    #expect(portraitLayout.failTickBox.width == 13)
+    #expect(portraitLayout.failTickBox.height == 13)
+    #expect(landscapeLayout.passTickBox.maxX == landscapeLayout.failLabelOrigin.x - 8)
+    #expect(portraitLayout.passTickBox.maxX == portraitLayout.failLabelOrigin.x - 8)
+}
+
+@Test("Writes visual sample for review")
+func writesVisualSampleForReview() throws {
+    let verifyDir = URL(fileURLWithPath: "/Users/benjaminhippler/mmd-projects/multi-agent-runs/shotdeck-20260830/verify")
+    try FileManager.default.createDirectory(at: verifyDir, withIntermediateDirectories: true)
+    let scratch = try makeScratchDirectory()
+    defer { try? FileManager.default.removeItem(at: scratch) }
+
+    let wide = makeCapture(sequence: 1, pixelWidth: 1600, pixelHeight: 900)
+    let tall = makeCapture(sequence: 2, pixelWidth: 900, pixelHeight: 1600)
+    let retina = makeCapture(sequence: 3, pixelWidth: 2880, pixelHeight: 1620, scale: 2.0)
+    let urls: [UUID: URL] = [
+        wide.id: try writePNG(for: wide, red: 196, green: 42, blue: 42, in: scratch),
+        tall.id: try writePNG(for: tall, red: 32, green: 96, blue: 176, in: scratch),
+        retina.id: try writePNG(for: retina, red: 36, green: 148, blue: 84, in: scratch),
+    ]
+    let output = verifyDir.appendingPathComponent("wp2-sample.pdf")
+    let pageCount = try PDFComposer().compose(
+        session: makeSession(captures: [wide, tall, retina]),
+        imageURL: imageURLMap(urls),
+        title: "WP-2 visual sample",
+        to: output
+    )
+    #expect(pageCount == 3)
+    let prefix = verifyDir.appendingPathComponent("wp2-sample")
+    try pdftoppm(pdf: output, prefix: prefix)
+}

Tests/ShotdeckCoreTests/ReturnLedgerTests.swift

@@ -0,0 +1,200 @@
+import Foundation
+import Testing
+import ShotdeckCore
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5a-ledger-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+private func document(
+    path: String,
+    annotatedPages: [Int],
+    detectedAt: Date,
+    sessionID: UUID? = nil,
+    pageCount: Int = 1
+) -> ReturnedDocument {
+    ReturnedDocument(
+        fileURL: URL(fileURLWithPath: path),
+        sessionID: sessionID,
+        pageCount: pageCount,
+        annotatedPages: annotatedPages,
+        detectedAt: detectedAt
+    )
+}
+
+@Test("L-1 commented() returns only commented entries, newest first")
+func l1_commentedReturnsOnlyCommentedNewestFirst() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let newer = document(
+        path: "/tmp/shotdeck-returns/newer.pdf",
+        annotatedPages: [1, 2],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_200)
+    )
+    let older = document(
+        path: "/tmp/shotdeck-returns/older.pdf",
+        annotatedPages: [3],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+    let clean = document(
+        path: "/tmp/shotdeck-returns/clean.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_300)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(older)
+    try await ledger.record(newer)
+    try await ledger.record(clean)
+
+    let commented = try await ledger.commented()
+    #expect(commented.map(\.fileURL) == [newer.fileURL, older.fileURL])
+    #expect(commented.map(\.annotatedPages) == [[1, 2], [3]])
+}
+
+@Test("L-2 clipboardText() exact format")
+func l2_clipboardTextExactFormat() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let newer = document(
+        path: "/tmp/shotdeck-returns/newer.pdf",
+        annotatedPages: [1, 2],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_200)
+    )
+    let older = document(
+        path: "/tmp/shotdeck-returns/older.pdf",
+        annotatedPages: [3],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+    let clean = document(
+        path: "/tmp/shotdeck-returns/clean.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_300)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(older)
+    try await ledger.record(newer)
+    try await ledger.record(clean)
+
+    let text = try await ledger.clipboardText()
+    #expect(text == newer.fileURL.path + "\n" + older.fileURL.path)
+    #expect(text.hasSuffix("\n") == false)
+}
+
+@Test("L-3 Re-recording the same URL upserts")
+func l3_rerecordingTheSameURLUpserts() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let url = URL(fileURLWithPath: "/tmp/shotdeck-returns/same.pdf")
+    let first = ReturnedDocument(
+        fileURL: url,
+        sessionID: nil,
+        pageCount: 1,
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_400)
+    )
+    let second = ReturnedDocument(
+        fileURL: url,
+        sessionID: UUID(uuidString: "11111111-1111-1111-1111-111111111111"),
+        pageCount: 1,
+        annotatedPages: [1],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(first)
+    try await ledger.record(second)
+
+    let all = try await ledger.all()
+    #expect(all.count == 1)
+    #expect(all[0].fileURL == url)
+    #expect(all[0].annotatedPages == [1])
+    #expect(all[0].isCommented == true)
+    #expect(all[0].sessionID == UUID(uuidString: "11111111-1111-1111-1111-111111111111"))
+}
+
+@Test("L-4 clipboardText() throws when nothing is commented")
+func l4_clipboardTextThrowsWhenNothingIsCommented() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let emptyError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = emptyError else {
+        Issue.record("expected noCommentedReturns on an empty ledger, got \(emptyError)")
+        return
+    }
+
+    try await ledger.record(document(
+        path: "/tmp/shotdeck-returns/clean-only.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_500)
+    ))
+    let cleanError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = cleanError else {
+        Issue.record("expected noCommentedReturns with only clean returns, got \(cleanError)")
+        return
+    }
+}
+
+@Test("L-5 Ledger survives reopening from disk")
+func l5_ledgerSurvivesReopeningFromDisk() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let first = document(
+        path: "/tmp/shotdeck-returns/a.pdf",
+        annotatedPages: [1],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_700),
+        sessionID: UUID(uuidString: "11111111-1111-1111-1111-111111111111")
+    )
+    let second = document(
+        path: "/tmp/shotdeck-returns/b.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_600)
+    )
+
+    do {
+        let ledger = try ReturnLedger(paths: paths)
+        try await ledger.record(first)
+        try await ledger.record(second)
+    }
+
+    let reopened = try ReturnLedger(paths: paths)
+    let all = try await reopened.all()
+    #expect(all == [first, second])
+}
+
+@Test("L-6 Corrupt returns.json is renamed and the ledger starts empty")
+func l6_corruptReturnsJSONIsRenamedAndStartsEmpty() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let returnsURL = paths.root.appendingPathComponent("returns.json")
+    try Data("{not-json".utf8).write(to: returnsURL)
+    #expect(FileManager.default.fileExists(atPath: returnsURL.path))
+
+    let ledger = try ReturnLedger(paths: paths)
+    #expect(try await ledger.all() == [])
+    #expect(FileManager.default.fileExists(atPath: returnsURL.path) == false)
+
+    let names = try FileManager.default.contentsOfDirectory(atPath: paths.root.path)
+    let corrupt = names.filter { $0.hasPrefix("returns.json.corrupt-") }
+    #expect(corrupt.count == 1)
+    #expect(corrupt[0].contains(DubaiTime.fileStamp(Date()).prefix(8)))
+}

Tests/ShotdeckCoreTests/ReturnWatcherTests.swift

@@ -0,0 +1,173 @@
+import AppKit
+import Foundation
+import PDFKit
+import Testing
+import ShotdeckCore
+
+private let pageBounds = CGRect(x: 0, y: 0, width: 600, height: 800)
+
+private func makeAnnotation(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect = CGRect(x: 100, y: 100, width: 80, height: 40),
+    contents: String? = nil
+) -> PDFAnnotation {
+    let annotation = PDFAnnotation(
+        bounds: bounds,
+        forType: subtype,
+        withProperties: nil
+    )
+    annotation.contents = contents
+    return annotation
+}
+
+private func makePDF(
+    at url: URL,
+    pageCount: Int,
+    creator: String? = "Shotdeck",
+    subject: String? = nil,
+    annotations: [(page: Int, annotation: PDFAnnotation)] = []
+) throws {
+    let document = PDFDocument()
+    for index in 0..<pageCount {
+        let page = PDFPage()
+        page.setBounds(pageBounds, for: .mediaBox)
+        document.insert(page, at: index)
+    }
+
+    var attributes = [PDFDocumentAttribute: Any]()
+    if let creator { attributes[.creatorAttribute] = creator }
+    if let subject { attributes[.subjectAttribute] = subject }
+    document.documentAttributes = attributes
+
+    for item in annotations {
+        guard let page = document.page(at: item.page) else {
+            throw NSError(domain: "WP5Test", code: 1)
+        }
+        page.addAnnotation(item.annotation)
+    }
+
+    guard document.write(to: url) else {
+        throw NSError(domain: "WP5Test", code: 2)
+    }
+}
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5b-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+/// Guards `confirmation(expectedCount: 1)` against a create+rename double-event.
+private final class ConfirmOnce: @unchecked Sendable {
+    private let lock = NSLock()
+    private var fired = false
+    func run(_ body: () -> Void) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !fired else { return }
+        fired = true
+        body()
+    }
+}
+
+@Test("W-25 Duplicate-name suffix is the normal AirDrop return (scanNow)")
+func w25_duplicateNameSuffixIsRecognizedByScanNow() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134205 2.pdf")
+
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: nil,
+        subject: "33333333-3333-3333-3333-333333333333",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+
+    let found = try await watcher.scanNow()
+    #expect(found.count == 1)
+    let doc = try #require(found.first)
+    #expect(doc.fileURL.lastPathComponent == "Shotdeck-20260830-134205 2.pdf")
+    #expect(doc.fileURL.resolvingSymlinksInPath().path == pdfURL.resolvingSymlinksInPath().path)
+    #expect(doc.pageCount == 1)
+    #expect(doc.annotatedPages == [1])
+    #expect(doc.isCommented == true)
+
+    let commented = try await ledger.commented()
+    #expect(commented.count == 1)
+    #expect(commented[0].fileURL.lastPathComponent == pdfURL.lastPathComponent)
+    #expect(commented[0].fileURL.resolvingSymlinksInPath().path == pdfURL.resolvingSymlinksInPath().path)
+}
+
+@Test("W-26 Creator provenance negative at the scan level")
+func w26_presentNonShotdeckCreatorIsIgnoredByScanNow() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134218.pdf")
+
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: "Preview",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+
+    let found = try await watcher.scanNow()
+    #expect(found.isEmpty)
+    let all = try await ledger.all()
+    #expect(all.isEmpty)
+}
+
+@Test("W-27 FSEvents live callback fires on a real file arrival")
+func w27_fsEventsCallbackFiresOnRealArrival() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-140000.pdf")
+    let once = ConfirmOnce()
+
+    try await confirmation("watcher reports the arrived PDF", expectedCount: 1) { confirm in
+        do {
+            try await watcher.start { docs in
+                if docs.contains(where: { $0.fileURL.lastPathComponent == pdfURL.lastPathComponent }) {
+                    once.run { confirm() }
+                }
+            }
+            // Simulate AirDrop's own write-then-rename so the watcher must survive that pattern.
+            let tmpURL = pdfURL.appendingPathExtension("inprogress")
+            try makePDF(
+                at: tmpURL, pageCount: 1, creator: "Shotdeck",
+                annotations: [(page: 0, annotation: makeAnnotation(
+                    .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+                ))]
+            )
+            try FileManager.default.moveItem(at: tmpURL, to: pdfURL)
+        } catch {
+            print("fsEventsCallbackFiresOnRealArrival error: \(error)")
+            await watcher.stop()
+            throw error
+        }
+        // Budget: 400ms debounce + FS latency + the 250ms stability re-read + PDFKit open.
+        // 5s is a generous, fixed ceiling — never a "some time" wait.
+        try await Task.sleep(for: .seconds(5))
+        await watcher.stop()
+        await watcher.stop()
+    }
+}

scripts/make-dmg.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+APP_BUNDLE="${ROOT}/.build/Shotdeck.app"
+STAGING="${ROOT}/.build/dmg-staging"
+DMG="${ROOT}/.build/Shotdeck.dmg"
+MOUNT_POINT="${ROOT}/.build/dmg-mnt"
+
+SKIP_SIGN=0
+for arg in "$@"; do
+    case "${arg}" in
+        --skip-sign)
+            SKIP_SIGN=1
+            ;;
+        *)
+            echo "Unknown argument: ${arg}" >&2
+            echo "Usage: $0 [--skip-sign]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+echo "==> Building Shotdeck.app"
+if [[ "${SKIP_SIGN}" -eq 1 ]]; then
+    ./scripts/build-app.sh --skip-sign
+else
+    ./scripts/build-app.sh
+fi
+
+if [[ ! -d "${APP_BUNDLE}" ]]; then
+    echo "App bundle not found at ${APP_BUNDLE}" >&2
+    exit 1
+fi
+
+echo "==> Staging DMG contents"
+rm -rf "${STAGING}"
+mkdir -p "${STAGING}"
+ditto "${APP_BUNDLE}" "${STAGING}/Shotdeck.app"
+ln -s /Applications "${STAGING}/Applications"
+
+echo "==> Creating ${DMG}"
+mkdir -p "$(dirname "${DMG}")"
+hdiutil create -volname "Shotdeck" -srcfolder "${STAGING}" -ov -format UDZO "${DMG}"
+
+MOUNTED=0
+detach_dmg() {
+    if [[ "${MOUNTED}" -eq 1 ]]; then
+        hdiutil detach "${MOUNT_POINT}" || hdiutil detach "${MOUNT_POINT}" -force || true
+        MOUNTED=0
+    fi
+}
+trap detach_dmg EXIT
+
+if [[ -d "${MOUNT_POINT}" ]] && /sbin/mount | grep -F -q "${MOUNT_POINT}"; then
+    hdiutil detach "${MOUNT_POINT}" || hdiutil detach "${MOUNT_POINT}" -force
+fi
+rm -rf "${MOUNT_POINT}"
+mkdir -p "${MOUNT_POINT}"
+
+echo "==> Verifying ${DMG}"
+hdiutil attach "${DMG}" -nobrowse -readonly -mountpoint "${MOUNT_POINT}"
+MOUNTED=1
+
+echo "==> Mount contents"
+ls -la "${MOUNT_POINT}"
+
+if [[ ! -d "${MOUNT_POINT}/Shotdeck.app" ]]; then
+    echo "Verification failed: Shotdeck.app missing from mounted DMG" >&2
+    exit 1
+fi
+if [[ ! -L "${MOUNT_POINT}/Applications" ]]; then
+    echo "Verification failed: Applications symlink missing from mounted DMG" >&2
+    exit 1
+fi
+if [[ "$(readlink "${MOUNT_POINT}/Applications")" != "/Applications" ]]; then
+    echo "Verification failed: Applications does not point at /Applications" >&2
+    exit 1
+fi
+
+echo "==> codesign --verify --deep"
+codesign --verify --deep --verbose=2 "${MOUNT_POINT}/Shotdeck.app"
+
+echo "==> Detaching ${MOUNT_POINT}"
+hdiutil detach "${MOUNT_POINT}"
+MOUNTED=0
+trap - EXIT
+
+SHA256="$(shasum -a 256 "${DMG}" | awk '{print $1}')"
+
+echo
+echo "DMG path: ${DMG}"
+echo "SHA256: ${SHA256}"