WP-3b: ScreenCaptureKit capturer + region picker overlay per SPEC-A2a

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/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/Returns/AnnotationInspector.swift

@@ -1,110 +0,0 @@
-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

@@ -1,60 +0,0 @@
-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

@@ -1,154 +0,0 @@
-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

@@ -1,412 +0,0 @@
-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/ReturnLedgerTests.swift

@@ -1,200 +0,0 @@
-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

@@ -1,173 +0,0 @@
-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()
-    }
-}