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/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/Spool/SpoolStore.swift

@@ -1,418 +0,0 @@
-import Foundation
-import ImageIO
-import CoreGraphics
-import Darwin
-
-public actor SpoolStore {
-    private let paths: AppSupportPaths
-    private var openSession: CaptureSession
-
-    public init(paths: AppSupportPaths) throws {
-        self.paths = paths
-        let fm = FileManager.default
-        try Self.supersedeSpoolArchiveOverlaps(paths: paths, fileManager: fm)
-        try Self.finishInterruptedArchives(paths: paths, fileManager: fm)
-        let remainingIDs = try Self.listUUIDDirectories(in: paths.spool, fileManager: fm)
-        if remainingIDs.isEmpty {
-            self.openSession = try Self.createFreshSession(paths: paths)
-        } else {
-            var candidates: [CaptureSession] = []
-            for id in remainingIDs {
-                let dir = paths.sessionDirectory(id)
-                candidates.append(
-                    try Self.reconcileSessionDirectory(
-                        at: dir, id: id, assumedStateIfRebuilt: .open, fileManager: fm))
-            }
-            self.openSession = Self.pickNewest(first: candidates[0], rest: Array(candidates.dropFirst()))
-        }
-    }
-
-    /// The session currently accepting captures. Cheap accessor — all reconciliation already
-    /// happened once, inside init.
-    public func currentSession() throws -> CaptureSession {
-        openSession
-    }
-
-    /// Writes `pngData` to disk and fsyncs it BEFORE the manifest is touched, then updates and
-    /// durably writes the manifest. Order is non-negotiable: image durable -> manifest durable
-    /// -> return. Uses AtomicFile.write/writeJSON for both writes — never Data.write(to:).
-    public func append(
-        pngData: Data, pixelWidth: Int, pixelHeight: Int,
-        scale: CGFloat, capturedAt: Date
-    ) throws -> Capture {
-        let captureID = UUID()
-        let sequence = openSession.nextSequence
-        let fileName = "\(String(format: "%03d", sequence))-\(Self.hexSuffix(captureID)).png"
-        let sessionDir = paths.sessionDirectory(openSession.id)
-        let fileURL = sessionDir.appendingPathComponent(fileName)
-        try AtomicFile.write(pngData, to: fileURL)
-        let capture = Capture(
-            id: captureID, sequence: sequence, fileName: fileName,
-            pixelWidth: pixelWidth, pixelHeight: pixelHeight,
-            scale: scale, capturedAt: capturedAt)
-        let updated = openSession.appending(capture)
-        try AtomicFile.writeJSON(updated, to: sessionDir.appendingPathComponent("session.json"))
-        openSession = updated
-        return capture
-    }
-
-    /// D-11: moves the capture's PNG into `<sessionDir>/removed/` (created lazily) and drops
-    /// its manifest entry. NEVER unlinks/deletes a user PNG. Throws (no filesystem change) if
-    /// `captureID` is not present in the open session.
-    public func remove(captureID: UUID) throws -> CaptureSession {
-        guard let capture = openSession.captures.first(where: { $0.id == captureID }) else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: paths.sessionDirectory(openSession.id).path,
-                underlying: "capture \(captureID) is not in the open session")
-        }
-        let sessionDir = paths.sessionDirectory(openSession.id)
-        let removedDir = sessionDir.appendingPathComponent("removed", isDirectory: true)
-        do {
-            try FileManager.default.createDirectory(at: removedDir, withIntermediateDirectories: true)
-        } catch {
-            throw ShotdeckError.spoolWriteFailed(path: removedDir.path, underlying: error.localizedDescription)
-        }
-        let sourceURL = sessionDir.appendingPathComponent(capture.fileName)
-        let destURL = removedDir.appendingPathComponent(capture.fileName)
-        guard rename(sourceURL.path, destURL.path) == 0 else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: destURL.path,
-                underlying: "could not move the capture into removed/: \(String(cString: strerror(errno)))")
-        }
-        try AtomicFile.fsyncDirectory(at: removedDir)
-        let updated = openSession.removing(captureID: captureID)
-        try AtomicFile.writeJSON(updated, to: sessionDir.appendingPathComponent("session.json"))
-        openSession = updated
-        return updated
-    }
-
-    /// Closes the open session (must be non-empty), moves its directory under archive/, records
-    /// pdfFileName, and starts a fresh empty open session. Returns the archived one.
-    public func archiveCurrent(pdfFileName: String) throws -> CaptureSession {
-        guard !openSession.isEmpty else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: paths.sessionDirectory(openSession.id).path,
-                underlying: "cannot archive an empty session")
-        }
-        let archived = openSession.markArchived(pdfFileName: pdfFileName)
-        let sessionDir = paths.sessionDirectory(openSession.id)
-        try AtomicFile.writeJSON(archived, to: sessionDir.appendingPathComponent("session.json"))
-        let archiveDir = paths.archiveDirectory(openSession.id)
-        guard rename(sessionDir.path, archiveDir.path) == 0 else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: sessionDir.path,
-                underlying: "could not move the session into archive/: \(String(cString: strerror(errno)))")
-        }
-        try AtomicFile.fsyncDirectory(at: paths.archive)
-        let fresh = try Self.createFreshSession(paths: paths)
-        openSession = fresh
-        return archived
-    }
-
-    /// Abandons the open session only if it is empty (mints a new id/dir/manifest); throws,
-    /// with no filesystem change, if the open session has captures.
-    public func startNewSession() throws -> CaptureSession {
-        guard openSession.isEmpty else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: paths.sessionDirectory(openSession.id).path,
-                underlying: "cannot start a new session: \(openSession.captures.count) capture(s) present in the open session")
-        }
-        let fresh = try Self.createFreshSession(paths: paths)
-        openSession = fresh
-        return fresh
-    }
-
-    /// Absolute URL of a capture's PNG, in whichever top-level directory its session lives
-    /// (spool/ if session.state == .open, archive/ if .archived).
-    public func imageURL(for capture: Capture, in session: CaptureSession) -> URL {
-        let dir = session.state == .open ? paths.sessionDirectory(session.id) : paths.archiveDirectory(session.id)
-        return dir.appendingPathComponent(capture.fileName)
-    }
-
-    /// Archived sessions, newest createdAt first. Lazily reconciles each archive/ directory
-    /// the same way init reconciles spool/ candidates (orphan recovery, missing-drop, corrupt
-    /// rebuild) — an archived session's manifest can degrade too and must self-heal without
-    /// ever losing a PNG.
-    public func archivedSessions() throws -> [CaptureSession] {
-        let ids = try Self.listUUIDDirectories(in: paths.archive, fileManager: .default)
-        var sessions: [CaptureSession] = []
-        for id in ids {
-            sessions.append(
-                try Self.reconcileSessionDirectory(
-                    at: paths.archiveDirectory(id), id: id, assumedStateIfRebuilt: .archived, fileManager: .default))
-        }
-        return sessions.sorted { ($0.createdAt, $0.id.uuidString) > ($1.createdAt, $1.id.uuidString) }
-    }
-
-    // MARK: - Reconciliation (static so they can run inside init)
-
-    private static func listUUIDDirectories(in parent: URL, fileManager: FileManager) throws -> [UUID] {
-        let entries: [URL]
-        do {
-            entries = try fileManager.contentsOfDirectory(
-                at: parent,
-                includingPropertiesForKeys: [.isDirectoryKey],
-                options: [])
-        } catch {
-            throw ShotdeckError.spoolWriteFailed(path: parent.path, underlying: error.localizedDescription)
-        }
-        var ids: [UUID] = []
-        for url in entries {
-            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
-            guard isDirectory else { continue }
-            if let id = UUID(uuidString: url.lastPathComponent) {
-                ids.append(id)
-            }
-        }
-        return ids
-    }
-
-    private static func supersedeSpoolArchiveOverlaps(paths: AppSupportPaths, fileManager: FileManager) throws {
-        let spoolIDs = Set(try listUUIDDirectories(in: paths.spool, fileManager: fileManager))
-        let archiveIDs = Set(try listUUIDDirectories(in: paths.archive, fileManager: fileManager))
-        for id in spoolIDs.intersection(archiveIDs) {
-            let spoolDir = paths.sessionDirectory(id)
-            let supersededDir = paths.spool.appendingPathComponent(
-                "\(id.uuidString).superseded-\(DubaiTime.fileStamp(Date()))", isDirectory: true)
-            guard rename(spoolDir.path, supersededDir.path) == 0 else {
-                throw ShotdeckError.spoolWriteFailed(
-                    path: spoolDir.path,
-                    underlying: "could not supersede a duplicate spool copy: \(String(cString: strerror(errno)))")
-            }
-            try AtomicFile.fsyncDirectory(at: paths.spool)
-            Log.spool.warning("Found session \(id.uuidString, privacy: .public) in both spool/ and archive/; kept the archive copy and superseded the spool copy — nothing was deleted.")
-        }
-    }
-
-    private static func finishInterruptedArchives(paths: AppSupportPaths, fileManager: FileManager) throws {
-        for id in try listUUIDDirectories(in: paths.spool, fileManager: fileManager) {
-            let spoolDir = paths.sessionDirectory(id)
-            let manifestURL = spoolDir.appendingPathComponent("session.json")
-            guard let data = try? Data(contentsOf: manifestURL),
-                  let decoded = try? decodeSession(from: data),
-                  decoded.id == id, decoded.state == .archived
-            else { continue }
-            let archiveDir = paths.archiveDirectory(id)
-            guard rename(spoolDir.path, archiveDir.path) == 0 else {
-                throw ShotdeckError.spoolWriteFailed(
-                    path: spoolDir.path,
-                    underlying: "could not complete an interrupted archive move: \(String(cString: strerror(errno)))")
-            }
-            try AtomicFile.fsyncDirectory(at: paths.archive)
-            Log.spool.warning("Completed an archive move for \(id.uuidString, privacy: .public) that was interrupted before this launch.")
-        }
-    }
-
-    private static func reconcileSessionDirectory(
-        at dir: URL,
-        id: UUID,
-        assumedStateIfRebuilt: SessionState,
-        fileManager: FileManager
-    ) throws -> CaptureSession {
-        let manifestURL = dir.appendingPathComponent("session.json")
-        let decoded: CaptureSession?
-        if let data = try? Data(contentsOf: manifestURL),
-           let session = try? decodeSession(from: data),
-           session.id == id {
-            decoded = session
-        } else {
-            decoded = nil
-        }
-
-        guard let session = decoded else {
-            return try rebuildManifest(
-                at: dir,
-                id: id,
-                assumedState: assumedStateIfRebuilt,
-                fileManager: fileManager)
-        }
-
-        var present: [Capture] = []
-        var missingCount = 0
-        for capture in session.captures {
-            let fileURL = dir.appendingPathComponent(capture.fileName)
-            if fileManager.fileExists(atPath: fileURL.path) {
-                present.append(capture)
-            } else {
-                missingCount += 1
-            }
-        }
-        let referenced = Set(session.captures.map(\.fileName))
-        let pngs = try listCapturePNGs(in: dir, fileManager: fileManager)
-        var recoveredOrphans: [Capture] = []
-        for pngURL in pngs where !referenced.contains(pngURL.lastPathComponent) {
-            if let recovered = recoverCapture(from: pngURL, fileManager: fileManager) {
-                recoveredOrphans.append(recovered)
-            } else {
-                Log.spool.error("Could not decode orphan PNG at \(pngURL.path, privacy: .public); leaving it on disk.")
-            }
-        }
-        let deletedTmp = deleteStrayTmpFiles(in: dir, fileManager: fileManager)
-        if missingCount == 0 && recoveredOrphans.isEmpty && !deletedTmp {
-            return session
-        }
-        let finalCaptures = (present + recoveredOrphans).sorted { $0.sequence < $1.sequence }
-        let updated = CaptureSession(
-            id: session.id,
-            createdAt: session.createdAt,
-            state: session.state,
-            captures: finalCaptures,
-            pdfFileName: session.pdfFileName)
-        try AtomicFile.writeJSON(updated, to: manifestURL)
-        Log.spool.warning("Reconciled session \(id.uuidString, privacy: .public): dropped \(missingCount) missing PNG(s), recovered \(recoveredOrphans.count) orphan(s).")
-        return updated
-    }
-
-    private static func rebuildManifest(
-        at dir: URL,
-        id: UUID,
-        assumedState: SessionState,
-        fileManager: FileManager
-    ) throws -> CaptureSession {
-        let manifestURL = dir.appendingPathComponent("session.json")
-        if fileManager.fileExists(atPath: manifestURL.path) {
-            let corruptURL = dir.appendingPathComponent(
-                "session.json.corrupt-\(DubaiTime.fileStamp(Date()))")
-            do {
-                try fileManager.moveItem(at: manifestURL, to: corruptURL)
-            } catch {
-                throw ShotdeckError.spoolWriteFailed(
-                    path: manifestURL.path,
-                    underlying: "could not quarantine a corrupt manifest: \(error.localizedDescription)")
-            }
-        }
-
-        var recovered: [Capture] = []
-        for pngURL in try listCapturePNGs(in: dir, fileManager: fileManager) {
-            if let capture = recoverCapture(from: pngURL, fileManager: fileManager) {
-                recovered.append(capture)
-            } else {
-                Log.spool.error("Could not decode PNG at \(pngURL.path, privacy: .public) while rebuilding the manifest; leaving it on disk.")
-            }
-        }
-        _ = deleteStrayTmpFiles(in: dir, fileManager: fileManager)
-        recovered.sort { $0.sequence < $1.sequence }
-
-        let createdAt: Date
-        if let earliest = recovered.map(\.capturedAt).min() {
-            createdAt = earliest
-        } else {
-            createdAt = (try? dir.resourceValues(forKeys: [.creationDateKey]))?.creationDate ?? Date()
-        }
-
-        let rebuilt = CaptureSession(
-            id: id,
-            createdAt: createdAt,
-            state: assumedState,
-            captures: recovered,
-            pdfFileName: nil)
-        try AtomicFile.writeJSON(rebuilt, to: dir.appendingPathComponent("session.json"))
-        Log.spool.warning("Rebuilt manifest for \(id.uuidString, privacy: .public) from \(recovered.count) recovered PNG(s).")
-        if assumedState == .archived {
-            Log.spool.warning("Rebuilt an archived session \(id.uuidString, privacy: .public) from PNGs; pdfFileName could not be recovered.")
-        }
-        return rebuilt
-    }
-
-    private static func recoverCapture(from fileURL: URL, fileManager: FileManager) -> Capture? {
-        guard fileManager.fileExists(atPath: fileURL.path) else { return nil }
-        guard let source = CGImageSourceCreateWithURL(fileURL as CFURL, nil),
-              let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as NSDictionary?,
-              let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,
-              let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue
-        else { return nil }
-        let name = fileURL.lastPathComponent
-        let sequence = Int(name.prefix(3)) ?? 1
-        let capturedAt = (try? fileURL.resourceValues(forKeys: [.creationDateKey]))?.creationDate ?? Date()
-        return Capture(
-            id: UUID(),
-            sequence: sequence,
-            fileName: name,
-            pixelWidth: width,
-            pixelHeight: height,
-            scale: 1.0,
-            capturedAt: capturedAt)
-    }
-
-    private static func pickNewest(first: CaptureSession, rest: [CaptureSession]) -> CaptureSession {
-        rest.reduce(first) { current, candidate in
-            let currentKey = (current.createdAt, current.id.uuidString)
-            let candidateKey = (candidate.createdAt, candidate.id.uuidString)
-            return candidateKey > currentKey ? candidate : current
-        }
-    }
-
-    private static func createFreshSession(paths: AppSupportPaths) throws -> CaptureSession {
-        let id = UUID()
-        let createdAt = Date()
-        let dir = paths.sessionDirectory(id)
-        do {
-            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
-        } catch {
-            throw ShotdeckError.spoolWriteFailed(path: dir.path, underlying: error.localizedDescription)
-        }
-        let session = CaptureSession(id: id, createdAt: createdAt, state: .open, captures: [], pdfFileName: nil)
-        try AtomicFile.writeJSON(session, to: dir.appendingPathComponent("session.json"))
-        return session
-    }
-
-    private static func hexSuffix(_ id: UUID) -> String {
-        String(id.uuidString.replacingOccurrences(of: "-", with: "").prefix(8)).uppercased()
-    }
-
-    private static func decodeSession(from data: Data) throws -> CaptureSession {
-        let decoder = JSONDecoder()
-        decoder.dateDecodingStrategy = .iso8601
-        return try decoder.decode(CaptureSession.self, from: data)
-    }
-
-    private static func isCapturePNGName(_ name: String) -> Bool {
-        guard name.hasSuffix(".png") else { return false }
-        let stem = String(name.dropLast(4))
-        let parts = stem.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
-        guard parts.count == 2,
-              parts[0].count == 3,
-              parts[0].allSatisfy(\.isNumber),
-              parts[1].count == 8,
-              parts[1].allSatisfy(\.isHexDigit)
-        else { return false }
-        return true
-    }
-
-    private static func listCapturePNGs(in dir: URL, fileManager: FileManager) throws -> [URL] {
-        let entries: [URL]
-        do {
-            entries = try fileManager.contentsOfDirectory(
-                at: dir,
-                includingPropertiesForKeys: [.isDirectoryKey],
-                options: [])
-        } catch {
-            throw ShotdeckError.spoolWriteFailed(path: dir.path, underlying: error.localizedDescription)
-        }
-        return entries.filter { url in
-            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
-            guard !isDirectory else { return false }
-            return isCapturePNGName(url.lastPathComponent)
-        }
-    }
-
-    private static func deleteStrayTmpFiles(in dir: URL, fileManager: FileManager) -> Bool {
-        let entries = (try? fileManager.contentsOfDirectory(
-            at: dir,
-            includingPropertiesForKeys: [.isDirectoryKey],
-            options: [])) ?? []
-        var deleted = false
-        for url in entries {
-            guard url.lastPathComponent.hasSuffix(".tmp") else { continue }
-            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
-            guard !isDirectory else { continue }
-            do {
-                try fileManager.removeItem(at: url)
-                deleted = true
-            } catch {
-                Log.spool.error("Could not remove stray temp file at \(url.path, privacy: .public): \(error.localizedDescription, privacy: .public)")
-            }
-        }
-        return deleted
-    }
-}

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/SpoolStoreTests.swift

@@ -1,590 +0,0 @@
-import CoreGraphics
-import Foundation
-import ImageIO
-import Testing
-import ShotdeckCore
-
-// MARK: - 1. append writes a real, decodable PNG
-
-@Test
-func appendWritesARealDecodablePNGMatchingSourceDimensions() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let width = 12
-    let height = 7
-    let png = try makePNGData(width: width, height: height, red: 0.9, green: 0.1, blue: 0.2)
-    let store = try SpoolStore(paths: paths)
-    let capturedAt = Date(timeIntervalSince1970: 1_700_000_000)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: width, pixelHeight: height, scale: 2.0, capturedAt: capturedAt)
-    let session = try await store.currentSession()
-
-    #expect(capture.pixelWidth == width)
-    #expect(capture.pixelHeight == height)
-
-    let url = await store.imageURL(for: capture, in: session)
-    let expected = paths.sessionDirectory(session.id).appendingPathComponent(capture.fileName)
-    #expect(url.path == expected.path)
-    #expect(FileManager.default.fileExists(atPath: url.path))
-
-    let onDisk = try Data(contentsOf: url)
-    #expect(onDisk == png)
-    let decoded = try #require(pngDimensions(at: url))
-    #expect(decoded.width == width)
-    #expect(decoded.height == height)
-}
-
-// MARK: - 2. remaining-manifest sequence rule (coordinator correction)
-
-@Test
-func sequencesFollowRemainingManifestMaxAndAreNotRenumbered() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let c1 = try await store.append(
-        pngData: try makePNGData(width: 4, height: 4, red: 1, green: 0, blue: 0),
-        pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    let c2 = try await store.append(
-        pngData: try makePNGData(width: 6, height: 4, red: 0, green: 1, blue: 0),
-        pixelWidth: 6, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    let c3 = try await store.append(
-        pngData: try makePNGData(width: 8, height: 4, red: 0, green: 0, blue: 1),
-        pixelWidth: 8, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    #expect(c1.sequence == 1)
-    #expect(c2.sequence == 2)
-    #expect(c3.sequence == 3)
-
-    _ = try await store.remove(captureID: c2.id)
-    let afterMiddle = try await store.currentSession()
-    #expect(afterMiddle.captures.map(\.sequence) == [1, 3])
-    #expect(afterMiddle.captures.map(\.id) == [c1.id, c3.id])
-
-    let c4 = try await store.append(
-        pngData: try makePNGData(width: 10, height: 4, red: 1, green: 1, blue: 0),
-        pixelWidth: 10, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    #expect(c4.sequence == 4)
-
-    _ = try await store.remove(captureID: c4.id)
-    let afterLast = try await store.currentSession()
-    #expect(afterLast.captures.map(\.sequence) == [1, 3])
-
-    let c4b = try await store.append(
-        pngData: try makePNGData(width: 12, height: 4, red: 1, green: 0, blue: 1),
-        pixelWidth: 12, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    #expect(c4b.sequence == 4)
-    #expect(c4b.fileName != c4.fileName)
-    #expect(c4b.id != c4.id)
-
-    let sessionDir = paths.sessionDirectory(afterLast.id)
-    #expect(FileManager.default.fileExists(atPath: sessionDir.appendingPathComponent(c4b.fileName).path))
-    #expect(FileManager.default.fileExists(
-        atPath: sessionDir.appendingPathComponent("removed", isDirectory: true)
-            .appendingPathComponent(c4.fileName).path))
-    #expect(!FileManager.default.fileExists(atPath: sessionDir.appendingPathComponent(c4.fileName).path))
-}
-
-// MARK: - 3. remove moves PNG into removed/
-
-@Test
-func removeMovesThePNGUnchangedIntoRemovedAndLeavesTheOriginalPathEmpty() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let png = try makePNGData(width: 8, height: 5, red: 0.2, green: 0.5, blue: 0.8)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: 8, pixelHeight: 5, scale: 2.0, capturedAt: Date())
-    let session = try await store.currentSession()
-    let sessionDir = paths.sessionDirectory(session.id)
-    let originalURL = sessionDir.appendingPathComponent(capture.fileName)
-    let removedURL = sessionDir.appendingPathComponent("removed", isDirectory: true)
-        .appendingPathComponent(capture.fileName)
-
-    let updated = try await store.remove(captureID: capture.id)
-
-    #expect(updated.captures.contains(where: { $0.id == capture.id }) == false)
-    #expect(!FileManager.default.fileExists(atPath: originalURL.path))
-    #expect(FileManager.default.fileExists(atPath: removedURL.path))
-    let moved = try Data(contentsOf: removedURL)
-    #expect(moved == png)
-}
-
-// MARK: - 4. remove of unknown id throws with zero filesystem change
-
-@Test
-func removeOfUnknownIDThrowsAndLeavesDiskByteIdentical() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    _ = try await store.append(
-        pngData: try makePNGData(width: 4, height: 4, red: 0.1, green: 0.2, blue: 0.3),
-        pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
-    let beforeSession = try await store.currentSession()
-    let beforeFiles = try snapshotFiles(under: root)
-
-    do {
-        _ = try await store.remove(captureID: UUID())
-        Issue.record("expected remove of an unknown id to throw")
-    } catch let error as ShotdeckError {
-        guard case .spoolWriteFailed = error else {
-            Issue.record("expected spoolWriteFailed, got \(error)")
-            return
-        }
-    } catch {
-        Issue.record("expected ShotdeckError, got \(error)")
-        return
-    }
-
-    let afterSession = try await store.currentSession()
-    #expect(afterSession == beforeSession)
-    let afterFiles = try snapshotFiles(under: root)
-    #expect(afterFiles == beforeFiles)
-}
-
-// MARK: - 5. orphan recovery
-
-@Test
-func orphanPNGWrittenBehindTheStoreIsRecoveredOnReopen() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let session = try await store.currentSession()
-    let width = 11
-    let height = 9
-    let png = try makePNGData(width: width, height: height, red: 0.4, green: 0.7, blue: 0.1)
-    let orphanName = "007-ABCD1234.png"
-    let dest = paths.sessionDirectory(session.id).appendingPathComponent(orphanName)
-    try AtomicFile.write(png, to: dest)
-
-    let reopened = try SpoolStore(paths: paths)
-    let recovered = try await reopened.currentSession()
-    let match = try #require(recovered.captures.first { $0.fileName == orphanName })
-    #expect(match.pixelWidth == width)
-    #expect(match.pixelHeight == height)
-    #expect(match.sequence == 7)
-    #expect(match.scale == 1.0)
-}
-
-// MARK: - 6. removed/ files are not resurrected
-
-@Test
-func orphanRecoveryDoesNotResurrectFilesInRemoved() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let session = try await store.currentSession()
-    let sessionDir = paths.sessionDirectory(session.id)
-    let removedDir = sessionDir.appendingPathComponent("removed", isDirectory: true)
-    try FileManager.default.createDirectory(at: removedDir, withIntermediateDirectories: true)
-    let hiddenName = "009-FEEDFACE.png"
-    try AtomicFile.write(
-        try makePNGData(width: 5, height: 5, red: 0.9, green: 0.9, blue: 0.1),
-        to: removedDir.appendingPathComponent(hiddenName))
-
-    let reopened = try SpoolStore(paths: paths)
-    let reconciled = try await reopened.currentSession()
-    #expect(reconciled.captures.contains(where: { $0.fileName == hiddenName }) == false)
-    #expect(FileManager.default.fileExists(atPath: removedDir.appendingPathComponent(hiddenName).path))
-}
-
-// MARK: - 7. missing-image drop
-
-@Test
-func missingPNGReferencedByManifestIsDroppedAndOthersSurvive() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let keep = try await store.append(
-        pngData: try makePNGData(width: 6, height: 6, red: 0.1, green: 0.8, blue: 0.2),
-        pixelWidth: 6, pixelHeight: 6, scale: 1.0, capturedAt: Date())
-    let drop = try await store.append(
-        pngData: try makePNGData(width: 7, height: 7, red: 0.8, green: 0.1, blue: 0.2),
-        pixelWidth: 7, pixelHeight: 7, scale: 1.0, capturedAt: Date())
-    let session = try await store.currentSession()
-    try FileManager.default.removeItem(
-        at: paths.sessionDirectory(session.id).appendingPathComponent(drop.fileName))
-
-    let reopened = try SpoolStore(paths: paths)
-    let reconciled = try await reopened.currentSession()
-    #expect(reconciled.captures.map(\.id) == [keep.id])
-    #expect(reconciled.captures.contains(where: { $0.id == drop.id }) == false)
-}
-
-// MARK: - 8. corrupt manifest rebuild
-
-@Test
-func corruptManifestIsQuarantinedAndPNGsAreRebuiltIntoANewManifest() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let first = try await store.append(
-        pngData: try makePNGData(width: 8, height: 6, red: 0.3, green: 0.3, blue: 0.9),
-        pixelWidth: 8, pixelHeight: 6, scale: 2.0, capturedAt: Date())
-    let second = try await store.append(
-        pngData: try makePNGData(width: 9, height: 6, red: 0.9, green: 0.3, blue: 0.3),
-        pixelWidth: 9, pixelHeight: 6, scale: 2.0, capturedAt: Date())
-    let session = try await store.currentSession()
-    let sessionDir = paths.sessionDirectory(session.id)
-    let manifestURL = sessionDir.appendingPathComponent("session.json")
-    let garbage = Data("{ not json".utf8)
-    try AtomicFile.write(garbage, to: manifestURL)
-
-    let reopened = try SpoolStore(paths: paths)
-    let rebuilt = try await reopened.currentSession()
-    #expect(rebuilt.id == session.id)
-
-    let contents = try FileManager.default.contentsOfDirectory(at: sessionDir, includingPropertiesForKeys: nil)
-    let corruptFiles = contents.filter { $0.lastPathComponent.hasPrefix("session.json.corrupt-") }
-    #expect(corruptFiles.count == 1)
-    let quarantined = try Data(contentsOf: try #require(corruptFiles.first))
-    #expect(quarantined == garbage)
-
-    let names = Set(rebuilt.captures.map(\.fileName))
-    #expect(names.contains(first.fileName))
-    #expect(names.contains(second.fileName))
-    let recoveredFirst = try #require(rebuilt.captures.first { $0.fileName == first.fileName })
-    #expect(recoveredFirst.pixelWidth == 8)
-    #expect(recoveredFirst.pixelHeight == 6)
-}
-
-// MARK: - 9. archiveCurrent moves the directory
-
-@Test
-func archiveCurrentMovesTheSessionUnderArchiveAndOpensAFreshEmptySession() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let png = try makePNGData(width: 10, height: 8, red: 0.5, green: 0.1, blue: 0.6)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: 10, pixelHeight: 8, scale: 1.0, capturedAt: Date())
-    let open = try await store.currentSession()
-    let archived = try await store.archiveCurrent(pdfFileName: "shotdeck-review.pdf")
-
-    #expect(archived.state == .archived)
-    #expect(archived.pdfFileName == "shotdeck-review.pdf")
-    #expect(archived.id == open.id)
-    #expect(!FileManager.default.fileExists(atPath: paths.sessionDirectory(open.id).path))
-
-    let archivedPNG = paths.archiveDirectory(open.id).appendingPathComponent(capture.fileName)
-    #expect(FileManager.default.fileExists(atPath: archivedPNG.path))
-    #expect(try Data(contentsOf: archivedPNG) == png)
-
-    let current = try await store.currentSession()
-    #expect(current.id != open.id)
-    #expect(current.isEmpty)
-    #expect(current.state == .open)
-    #expect(FileManager.default.fileExists(
-        atPath: paths.sessionDirectory(current.id).appendingPathComponent("session.json").path))
-}
-
-// MARK: - 10. archiveCurrent on empty throws
-
-@Test
-func archiveCurrentOnEmptySessionThrowsAndDoesNotMoveTheDirectory() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let session = try await store.currentSession()
-    let before = try snapshotFiles(under: root)
-
-    do {
-        _ = try await store.archiveCurrent(pdfFileName: "never.pdf")
-        Issue.record("expected archiveCurrent on an empty session to throw")
-    } catch let error as ShotdeckError {
-        guard case .spoolWriteFailed = error else {
-            Issue.record("expected spoolWriteFailed, got \(error)")
-            return
-        }
-    } catch {
-        Issue.record("expected ShotdeckError, got \(error)")
-        return
-    }
-
-    #expect(FileManager.default.fileExists(atPath: paths.sessionDirectory(session.id).path))
-    #expect(try snapshotFiles(under: root) == before)
-}
-
-// MARK: - 11. interrupted-archive, both exist
-
-@Test
-func interruptedArchiveBothExistSupersedesTheSpoolCopyAndKeepsArchive() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let png = try makePNGData(width: 8, height: 8, red: 0.2, green: 0.2, blue: 0.8)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: 8, pixelHeight: 8, scale: 1.0, capturedAt: Date())
-    let archived = try await store.archiveCurrent(pdfFileName: "sent.pdf")
-    let archiveDir = paths.archiveDirectory(archived.id)
-    let spoolCopy = paths.sessionDirectory(archived.id)
-    try FileManager.default.copyItem(at: archiveDir, to: spoolCopy)
-    let archivePNGBefore = try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName))
-
-    let reopened = try SpoolStore(paths: paths)
-    _ = try await reopened.currentSession()
-
-    #expect(FileManager.default.fileExists(atPath: archiveDir.path))
-    #expect(!FileManager.default.fileExists(atPath: spoolCopy.path))
-    #expect(try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName)) == archivePNGBefore)
-
-    let spoolEntries = try FileManager.default.contentsOfDirectory(
-        at: paths.spool, includingPropertiesForKeys: [.isDirectoryKey])
-    let superseded = spoolEntries.filter {
-        $0.lastPathComponent.hasPrefix("\(archived.id.uuidString).superseded-")
-    }
-    #expect(superseded.count == 1)
-    let supersededPNG = try #require(superseded.first).appendingPathComponent(capture.fileName)
-    #expect(FileManager.default.fileExists(atPath: supersededPNG.path))
-    #expect(try Data(contentsOf: supersededPNG) == png)
-}
-
-// MARK: - 12. interrupted-archive, manifest-only
-
-@Test
-func interruptedArchiveManifestOnlyCompletesTheMoveIntoArchive() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let png = try makePNGData(width: 6, height: 8, red: 0.7, green: 0.4, blue: 0.1)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: 6, pixelHeight: 8, scale: 1.0, capturedAt: Date())
-    let session = try await store.currentSession()
-    let marked = session.markArchived(pdfFileName: "partial.pdf")
-    try AtomicFile.writeJSON(
-        marked, to: paths.sessionDirectory(session.id).appendingPathComponent("session.json"))
-
-    let reopened = try SpoolStore(paths: paths)
-    let current = try await reopened.currentSession()
-    #expect(current.id != session.id)
-    #expect(!FileManager.default.fileExists(atPath: paths.sessionDirectory(session.id).path))
-    let archiveDir = paths.archiveDirectory(session.id)
-    #expect(FileManager.default.fileExists(atPath: archiveDir.path))
-    #expect(FileManager.default.fileExists(atPath: archiveDir.appendingPathComponent(capture.fileName).path))
-    #expect(try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName)) == png)
-
-    let archived = try await reopened.archivedSessions()
-    #expect(archived.contains(where: { $0.id == session.id }))
-}
-
-// MARK: - 13. archivedSessions newest createdAt first
-
-@Test
-func archivedSessionsReturnsNewestCreatedAtFirst() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let newest = UUID(uuidString: "00000000-0000-4000-8000-000000000003")!
-    let oldest = UUID(uuidString: "00000000-0000-4000-8000-000000000001")!
-    let middle = UUID(uuidString: "00000000-0000-4000-8000-000000000002")!
-    let tNewest = Date(timeIntervalSince1970: 1_700_000_200)
-    let tOldest = Date(timeIntervalSince1970: 1_700_000_000)
-    let tMiddle = Date(timeIntervalSince1970: 1_700_000_100)
-
-    try seedSession(id: newest, createdAt: tNewest, state: .archived, directory: paths.archiveDirectory(newest))
-    try seedSession(id: oldest, createdAt: tOldest, state: .archived, directory: paths.archiveDirectory(oldest))
-    try seedSession(id: middle, createdAt: tMiddle, state: .archived, directory: paths.archiveDirectory(middle))
-
-    let store = try SpoolStore(paths: paths)
-    let listed = try await store.archivedSessions()
-    #expect(listed.map(\.id) == [newest, middle, oldest])
-}
-
-// MARK: - 14. newest-session tie-break by greater UUID string
-
-@Test
-func newestSessionTieBreakPicksTheLexicographicallyGreaterUUID() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let smaller = UUID(uuidString: "AAAAAAAA-AAAA-4AAA-8AAA-AAAAAAAAAAAA")!
-    let greater = UUID(uuidString: "BBBBBBBB-BBBB-4BBB-8BBB-BBBBBBBBBBBB")!
-    let createdAt = Date(timeIntervalSince1970: 1_700_000_500)
-    try seedSession(id: smaller, createdAt: createdAt, state: .open, directory: paths.sessionDirectory(smaller))
-    try seedSession(id: greater, createdAt: createdAt, state: .open, directory: paths.sessionDirectory(greater))
-
-    let first = try SpoolStore(paths: paths)
-    let firstID = try await first.currentSession().id
-    let second = try SpoolStore(paths: paths)
-    let secondID = try await second.currentSession().id
-    #expect(firstID == greater)
-    #expect(secondID == greater)
-}
-
-// MARK: - 15. filename shape
-
-@Test
-func appendFilenameMatchesSequenceDashEightHexSuffix() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let capture = try await store.append(
-        pngData: try makePNGData(width: 4, height: 3, red: 0.1, green: 0.1, blue: 0.1),
-        pixelWidth: 4, pixelHeight: 3, scale: 1.0, capturedAt: Date())
-    let hex = String(capture.id.uuidString.replacingOccurrences(of: "-", with: "").prefix(8)).uppercased()
-    #expect(capture.fileName == "001-\(hex).png")
-    let session = try await store.currentSession()
-    let url = await store.imageURL(for: capture, in: session)
-    #expect(url.lastPathComponent == capture.fileName)
-    #expect(FileManager.default.fileExists(atPath: url.path))
-}
-
-// MARK: - 16. startNewSession
-
-@Test
-func startNewSessionThrowsWhenNonEmptyAndMintsANewIdWhenEmpty() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    _ = try await store.append(
-        pngData: try makePNGData(width: 5, height: 5, red: 0.4, green: 0.2, blue: 0.6),
-        pixelWidth: 5, pixelHeight: 5, scale: 1.0, capturedAt: Date())
-    let before = try snapshotFiles(under: root)
-    let occupied = try await store.currentSession()
-
-    do {
-        _ = try await store.startNewSession()
-        Issue.record("expected startNewSession to throw while captures are present")
-    } catch let error as ShotdeckError {
-        guard case .spoolWriteFailed = error else {
-            Issue.record("expected spoolWriteFailed, got \(error)")
-            return
-        }
-    } catch {
-        Issue.record("expected ShotdeckError, got \(error)")
-        return
-    }
-    #expect(try snapshotFiles(under: root) == before)
-    #expect(try await store.currentSession().id == occupied.id)
-
-    _ = try await store.remove(captureID: occupied.captures[0].id)
-    let emptyID = try await store.currentSession().id
-    let fresh = try await store.startNewSession()
-    #expect(fresh.id != emptyID)
-    #expect(fresh.isEmpty)
-    #expect(FileManager.default.fileExists(
-        atPath: paths.sessionDirectory(emptyID).appendingPathComponent("session.json").path))
-}
-
-// MARK: - 17. durability-ordering smoke test
-
-@Test
-func appendReturnsOnlyAfterThePNGBytesAreAlreadyOnDisk() async throws {
-    let (root, paths) = try makeIsolatedPaths()
-    defer { try? FileManager.default.removeItem(at: root) }
-
-    let store = try SpoolStore(paths: paths)
-    let png = try makePNGData(width: 13, height: 11, red: 0.15, green: 0.55, blue: 0.95)
-    let capture = try await store.append(
-        pngData: png, pixelWidth: 13, pixelHeight: 11, scale: 2.0, capturedAt: Date())
-    let session = try await store.currentSession()
-    let url = paths.sessionDirectory(session.id).appendingPathComponent(capture.fileName)
-    let onDisk = try Data(contentsOf: url)
-    #expect(onDisk == png)
-}
-
-// MARK: - Fixtures
-
-private func makeIsolatedPaths() throws -> (root: URL, paths: AppSupportPaths) {
-    let root = FileManager.default.temporaryDirectory
-        .appendingPathComponent("shotdeck-spool-\(UUID().uuidString)", isDirectory: true)
-    let paths = try AppSupportPaths(
-        root: root,
-        outbox: root.appendingPathComponent("outbox", isDirectory: true),
-        watchFolder: root.appendingPathComponent("watch", isDirectory: true)
-    )
-    return (root, paths)
-}
-
-private 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 FixtureError.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 FixtureError.pngGenerationFailed
-    }
-    let buffer = NSMutableData()
-    guard let destination = CGImageDestinationCreateWithData(buffer, "public.png" as CFString, 1, nil) else {
-        throw FixtureError.pngGenerationFailed
-    }
-    CGImageDestinationAddImage(destination, image, nil)
-    guard CGImageDestinationFinalize(destination) else {
-        throw FixtureError.pngGenerationFailed
-    }
-    return buffer as Data
-}
-
-private func pngDimensions(at url: URL) -> (width: Int, height: Int)? {
-    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
-          let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as NSDictionary?,
-          let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,
-          let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue
-    else { return nil }
-    return (width, height)
-}
-
-private func seedSession(
-    id: UUID,
-    createdAt: Date,
-    state: SessionState,
-    directory: URL
-) throws {
-    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-    let session = CaptureSession(id: id, createdAt: createdAt, state: state, captures: [], pdfFileName: nil)
-    try AtomicFile.writeJSON(session, to: directory.appendingPathComponent("session.json"))
-}
-
-private func snapshotFiles(under root: URL) throws -> [String: Data] {
-    let fm = FileManager.default
-    var files: [String: Data] = [:]
-    guard let enumerator = fm.enumerator(
-        at: root,
-        includingPropertiesForKeys: [.isRegularFileKey],
-        options: [.skipsHiddenFiles]
-    ) else { return files }
-    let rootPath = root.standardizedFileURL.path
-    for case let url as URL in enumerator {
-        let values = try url.resourceValues(forKeys: [.isRegularFileKey])
-        guard values.isRegularFile == true else { continue }
-        var relative = url.standardizedFileURL.path
-        if relative.hasPrefix(rootPath) {
-            relative = String(relative.dropFirst(rootPath.count))
-            if relative.hasPrefix("/") { relative = String(relative.dropFirst()) }
-        }
-        files[relative] = try Data(contentsOf: url)
-    }
-    return files
-}
-
-private enum FixtureError: Error {
-    case pngGenerationFailed
-}