WP-2: PDF composer + PageLayout per SPEC-A1b (two-pass, atomic write, zero annotations)

Sources/ShotdeckCore/Model/ShotdeckError.swift

@@ -16,7 +16,7 @@ public enum ShotdeckError: Error, LocalizedError, Sendable {
         case .screenRecordingNotGranted:
             return "Screen Recording is turned off. Grant it in System Settings to capture."
         case .noRegionRemembered:
-            return "No capture region is set. Choose 'Re-select area' from the Shotdeck menu."
+            return "No capture region is set. Press ⌥⇧1 to pick one."
         case .displayNoLongerConnected:
             return "The display used for capture is no longer connected."
         case .captureFailed(let underlying):

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/Support/AtomicFile.swift

@@ -1,104 +0,0 @@
-import Foundation
-import Darwin
-
-public enum AtomicFile {
-    /// Writes `data` to `url` durably: writes to `<url>.tmp` in the SAME directory as `url`,
-    /// fsyncs that file descriptor, closes it, rename()s it onto `url` (atomic same-volume
-    /// rename), then opens `url`'s containing directory and fsyncs THAT too (a rename is only
-    /// durable once its directory entry is flushed). Never uses `Data.write(to:)` — that call
-    /// does not fsync.
-    public static func write(_ data: Data, to url: URL) throws {
-        let finalPath = url.path
-        let directoryURL = url.deletingLastPathComponent()
-        let tmpURL = directoryURL.appendingPathComponent(url.lastPathComponent + ".tmp")
-        let tmpPath = tmpURL.path
-
-        // Clear a stale .tmp left by a previous crash. ENOENT (nothing to clear) is fine.
-        if unlink(tmpPath) != 0 && errno != ENOENT {
-            throw ShotdeckError.spoolWriteFailed(
-                path: finalPath,
-                underlying: "could not clear a stale temp file: \(String(cString: strerror(errno)))")
-        }
-
-        let fd = open(tmpPath, O_WRONLY | O_CREAT | O_TRUNC, 0o644)
-        guard fd >= 0 else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: finalPath, underlying: "open failed: \(String(cString: strerror(errno)))")
-        }
-
-        var writeFailure: String?
-        data.withUnsafeBytes { (raw: UnsafeRawBufferPointer) in
-            var remaining = raw.count
-            var pointer = raw.baseAddress
-            while remaining > 0 {
-                let n = Darwin.write(fd, pointer, remaining)
-                if n < 0 {
-                    if errno == EINTR { continue }
-                    writeFailure = "write failed: \(String(cString: strerror(errno)))"
-                    break
-                }
-                if n == 0 { break }
-                remaining -= n
-                pointer = pointer?.advanced(by: n)
-            }
-        }
-        if let writeFailure {
-            close(fd)
-            _ = unlink(tmpPath)
-            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: writeFailure)
-        }
-        if fsync(fd) != 0 {
-            let message = "fsync failed: \(String(cString: strerror(errno)))"
-            close(fd)
-            _ = unlink(tmpPath)
-            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: message)
-        }
-        if close(fd) != 0 {
-            _ = unlink(tmpPath)
-            throw ShotdeckError.spoolWriteFailed(
-                path: finalPath, underlying: "close failed: \(String(cString: strerror(errno)))")
-        }
-        if rename(tmpPath, finalPath) != 0 {
-            let message = "rename failed: \(String(cString: strerror(errno)))"
-            _ = unlink(tmpPath)
-            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: message)
-        }
-        try fsyncDirectory(at: directoryURL)
-    }
-
-    /// Encodes `value` with `JSONEncoder` (`.sortedKeys, .prettyPrinted`,
-    /// `.dateEncodingStrategy = .iso8601`) and writes it through `write(_:to:)`.
-    public static func writeJSON<T: Encodable>(_ value: T, to url: URL) throws {
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.sortedKeys, .prettyPrinted]
-        encoder.dateEncodingStrategy = .iso8601
-        let data: Data
-        do {
-            data = try encoder.encode(value)
-        } catch {
-            throw ShotdeckError.spoolWriteFailed(
-                path: url.path, underlying: "JSON encoding failed: \(error.localizedDescription)")
-        }
-        try write(data, to: url)
-    }
-
-    /// Opens `url` (must be an existing directory) and fsyncs it. Used after any directory-
-    /// level `rename()` (moving/renaming a whole session directory) — the same durability
-    /// requirement as the internal directory-fsync inside `write(_:to:)`, exposed for callers
-    /// that rename directories themselves (SpoolStore).
-    public static func fsyncDirectory(at url: URL) throws {
-        let fd = open(url.path, O_RDONLY | O_DIRECTORY)
-        guard fd >= 0 else {
-            throw ShotdeckError.spoolWriteFailed(
-                path: url.path,
-                underlying: "could not open directory for fsync: \(String(cString: strerror(errno)))")
-        }
-        let result = fsync(fd)
-        close(fd)
-        if result != 0 {
-            throw ShotdeckError.spoolWriteFailed(
-                path: url.path,
-                underlying: "directory fsync failed: \(String(cString: strerror(errno)))")
-        }
-    }
-}

Sources/ShotdeckCore/Support/FolderSettings.swift

@@ -1,111 +0,0 @@
-import Foundation
-
-/// User-configurable overrides for the outbox (PDF send destination) and watch folder
-/// (AirDrop return), backed by UserDefaults. Shotdeck is NOT App-Sandboxed (no
-/// `com.apple.security.app-sandbox` entitlement in this build — it is a plain, unsandboxed
-/// SwiftPM executable). Security-scoped bookmarks exist to let a SANDBOXED app retain access
-/// to a user-picked file/folder outside its container across relaunches; an unsandboxed
-/// process already has the invoking user's own filesystem permissions on every launch, so a
-/// plain absolute path stored in UserDefaults is sufficient — including for a mounted network
-/// share, which resolves by path the same as any local folder for as long as it is mounted.
-public enum FolderSettings {
-    public static let outboxDefaultsKey = "ai.flowmaster.shotdeck.outbox"
-    public static let watchFolderDefaultsKey = "ai.flowmaster.shotdeck.watchFolder"
-
-    /// Raw stored path (or nil if never set / cleared). For display in Settings — does NOT
-    /// validate that the path still exists.
-    public static func storedOutboxPath(defaults: UserDefaults = .standard) -> String? {
-        defaults.string(forKey: outboxDefaultsKey)
-    }
-
-    public static func storedWatchFolderPath(defaults: UserDefaults = .standard) -> String? {
-        defaults.string(forKey: watchFolderDefaultsKey)
-    }
-
-    /// Persists a user-chosen folder as its absolute POSIX path.
-    public static func setOutbox(_ url: URL, defaults: UserDefaults = .standard) {
-        defaults.set(url.path, forKey: outboxDefaultsKey)
-    }
-
-    public static func setWatchFolder(_ url: URL, defaults: UserDefaults = .standard) {
-        defaults.set(url.path, forKey: watchFolderDefaultsKey)
-    }
-
-    /// Removes the override; resolve() falls back to the default again.
-    public static func resetOutbox(defaults: UserDefaults = .standard) {
-        defaults.removeObject(forKey: outboxDefaultsKey)
-    }
-
-    public static func resetWatchFolder(defaults: UserDefaults = .standard) {
-        defaults.removeObject(forKey: watchFolderDefaultsKey)
-    }
-
-    /// Resolves both folders. A stored override wins only if it is set AND the directory it
-    /// names still exists; otherwise falls back to the default (Desktop / Downloads). Never
-    /// throws — a missing/bad override is logged via `Log.ui` and silently replaced.
-    public static func resolve(
-        defaults: UserDefaults = .standard,
-        fileManager: FileManager = .default
-    ) -> (outbox: URL, watch: URL) {
-        let outbox = resolveOne(
-            storedPath: storedOutboxPath(defaults: defaults),
-            fallback: defaultOutbox(fileManager: fileManager),
-            label: "outbox", fileManager: fileManager)
-        let watch = resolveOne(
-            storedPath: storedWatchFolderPath(defaults: defaults),
-            fallback: defaultWatchFolder(fileManager: fileManager),
-            label: "watch", fileManager: fileManager)
-        return (outbox, watch)
-    }
-
-    /// Builds an `AppSupportPaths` using `root` (defaults to the standard
-    /// `~/Library/Application Support/Shotdeck`, computed the same way
-    /// `AppSupportPaths.standard()` does, when `root` is nil) plus whatever `resolve()`
-    /// returns for outbox/watch. This is the ONLY place that combines FolderSettings with
-    /// AppSupportPaths — call this everywhere in the app instead of `AppSupportPaths.standard()`.
-    /// `root` is exposed purely so tests can point it at a temporary directory instead of the
-    /// user's real Application Support folder.
-    public static func resolvedAppSupportPaths(
-        root: URL? = nil,
-        defaults: UserDefaults = .standard,
-        fileManager: FileManager = .default
-    ) throws -> AppSupportPaths {
-        let resolvedRoot: URL
-        if let root {
-            resolvedRoot = root
-        } else {
-            let appSupportParent = try fileManager.url(
-                for: .applicationSupportDirectory, in: .userDomainMask,
-                appropriateFor: nil, create: true)
-            resolvedRoot = appSupportParent.appendingPathComponent("Shotdeck", isDirectory: true)
-        }
-        let folders = resolve(defaults: defaults, fileManager: fileManager)
-        return try AppSupportPaths(root: resolvedRoot, outbox: folders.outbox, watchFolder: folders.watch)
-    }
-
-    private static func defaultOutbox(fileManager: FileManager) -> URL {
-        fileManager.urls(for: .desktopDirectory, in: .userDomainMask).first
-            ?? fileManager.homeDirectoryForCurrentUser.appendingPathComponent("Desktop", isDirectory: true)
-    }
-
-    private static func defaultWatchFolder(fileManager: FileManager) -> URL {
-        fileManager.urls(for: .downloadsDirectory, in: .userDomainMask).first
-            ?? fileManager.homeDirectoryForCurrentUser.appendingPathComponent("Downloads", isDirectory: true)
-    }
-
-    private static func resolveOne(
-        storedPath: String?,
-        fallback: URL,
-        label: String,
-        fileManager: FileManager
-    ) -> URL {
-        guard let storedPath else { return fallback }
-        var isDirectory: ObjCBool = false
-        let exists = fileManager.fileExists(atPath: storedPath, isDirectory: &isDirectory)
-        guard exists, isDirectory.boolValue else {
-            Log.ui.warning("Configured \(label, privacy: .public) folder \(storedPath, privacy: .public) no longer exists; falling back to the default.")
-            return fallback
-        }
-        return URL(fileURLWithPath: storedPath, isDirectory: true)
-    }
-}

Sources/ShotdeckCore/Support/Log.swift

@@ -1,9 +0,0 @@
-import os
-
-public enum Log {
-    public static let spool = Logger(subsystem: "ai.flowmaster.shotdeck", category: "spool")
-    public static let pdf = Logger(subsystem: "ai.flowmaster.shotdeck", category: "pdf")
-    public static let capture = Logger(subsystem: "ai.flowmaster.shotdeck", category: "capture")
-    public static let returns = Logger(subsystem: "ai.flowmaster.shotdeck", category: "returns")
-    public static let ui = Logger(subsystem: "ai.flowmaster.shotdeck", category: "ui")
-}

Tests/ShotdeckCoreTests/AtomicFileTests.swift

@@ -1,178 +0,0 @@
-import Foundation
-import Testing
-import ShotdeckCore
-
-@Test
-func atomicWriteProducesByteIdenticalFileAndLeavesNoTmp() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-write")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    let url = directory.appendingPathComponent("payload.bin")
-    let data = Data("shotdeck-durable-bytes".utf8)
-
-    try AtomicFile.write(data, to: url)
-
-    let onDisk = try Data(contentsOf: url)
-    #expect(onDisk == data)
-    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
-}
-
-@Test
-func atomicWriteToTheSameURLTwiceKeepsTheSecondPayload() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-rewrite")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    let url = directory.appendingPathComponent("payload.bin")
-    let first = Data("first-pass".utf8)
-    let second = Data("second-pass-wins".utf8)
-
-    try AtomicFile.write(first, to: url)
-    try AtomicFile.write(second, to: url)
-
-    let onDisk = try Data(contentsOf: url)
-    #expect(onDisk == second)
-    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
-}
-
-@Test
-func atomicWriteThrowsWhenParentDirectoryDoesNotExist() throws {
-    let missingParent = FileManager.default.temporaryDirectory
-        .appendingPathComponent("shotdeck-atomic-missing-\(UUID().uuidString)", isDirectory: true)
-    let url = missingParent.appendingPathComponent("payload.bin")
-    let data = Data("never-written".utf8)
-
-    let error = try #require(throws: ShotdeckError.self) {
-        try AtomicFile.write(data, to: url)
-    }
-    guard case .spoolWriteFailed(let path, _) = error else {
-        Issue.record("expected spoolWriteFailed, got \(error)")
-        return
-    }
-    #expect(path == url.path)
-    #expect(!FileManager.default.fileExists(atPath: url.path))
-}
-
-@Test
-func atomicWriteClearsAStaleTmpAndWritesTheNewPayload() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-stale-tmp")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    let url = directory.appendingPathComponent("payload.bin")
-    let tmpURL = directory.appendingPathComponent(url.lastPathComponent + ".tmp")
-    let garbage = Data("stale-crash-garbage".utf8)
-    let newData = Data("recovered-payload".utf8)
-
-    try garbage.write(to: tmpURL)
-    #expect(FileManager.default.fileExists(atPath: tmpURL.path))
-
-    try AtomicFile.write(newData, to: url)
-
-    let onDisk = try Data(contentsOf: url)
-    #expect(onDisk == newData)
-    #expect(!FileManager.default.fileExists(atPath: tmpURL.path))
-}
-
-@Test
-func writeJSONSortsKeysPrettyPrintsAndEncodesDatesAsISO8601() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-json-format")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    let url = directory.appendingPathComponent("session.json")
-    let date = try iso8601Date(year: 2026, month: 8, day: 30, hour: 9, minute: 42, second: 5)
-    let value = JSONProbe(zebra: "last", apple: 7, capturedAt: date)
-
-    try AtomicFile.writeJSON(value, to: url)
-
-    let raw = try Data(contentsOf: url)
-    let text = try #require(String(data: raw, encoding: .utf8))
-
-    let apple = try #require(text.range(of: "\"apple\""))
-    let capturedAt = try #require(text.range(of: "\"capturedAt\""))
-    let zebra = try #require(text.range(of: "\"zebra\""))
-    #expect(apple.lowerBound < capturedAt.lowerBound)
-    #expect(capturedAt.lowerBound < zebra.lowerBound)
-    #expect(text.contains("\n"))
-    #expect(text.contains("  \"apple\""))
-    #expect(text.contains("2026-08-30T09:42:05Z"))
-    #expect(!text.contains("\(date.timeIntervalSinceReferenceDate)"))
-    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
-}
-
-@Test
-func writeJSONRoundTripsThroughISO8601Decoder() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-json-roundtrip")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    let url = directory.appendingPathComponent("session.json")
-    let date = try iso8601Date(year: 2026, month: 8, day: 31, hour: 13, minute: 5, second: 9)
-    let original = JSONProbe(zebra: "keep", apple: 42, capturedAt: date)
-
-    try AtomicFile.writeJSON(original, to: url)
-
-    let decoder = JSONDecoder()
-    decoder.dateDecodingStrategy = .iso8601
-    let decoded = try decoder.decode(JSONProbe.self, from: Data(contentsOf: url))
-    #expect(decoded == original)
-}
-
-@Test
-func fsyncDirectorySucceedsOnADirectoryAndThrowsOnMissingOrFilePaths() throws {
-    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-fsync-dir")
-    defer { try? FileManager.default.removeItem(at: directory) }
-
-    try AtomicFile.fsyncDirectory(at: directory)
-
-    let missing = directory.appendingPathComponent("does-not-exist", isDirectory: true)
-    let missingError = try #require(throws: ShotdeckError.self) {
-        try AtomicFile.fsyncDirectory(at: missing)
-    }
-    guard case .spoolWriteFailed = missingError else {
-        Issue.record("expected spoolWriteFailed for a missing path, got \(missingError)")
-        return
-    }
-
-    let fileURL = directory.appendingPathComponent("not-a-directory.bin")
-    try AtomicFile.write(Data("file".utf8), to: fileURL)
-    let fileError = try #require(throws: ShotdeckError.self) {
-        try AtomicFile.fsyncDirectory(at: fileURL)
-    }
-    guard case .spoolWriteFailed = fileError else {
-        Issue.record("expected spoolWriteFailed for a file path, got \(fileError)")
-        return
-    }
-}
-
-private struct JSONProbe: Codable, Equatable {
-    var zebra: String
-    var apple: Int
-    var capturedAt: Date
-}
-
-private func makeTemporaryDirectory(prefix: String) throws -> URL {
-    let url = FileManager.default.temporaryDirectory
-        .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
-    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
-    return url
-}
-
-private func iso8601Date(
-    year: Int,
-    month: Int,
-    day: Int,
-    hour: Int,
-    minute: Int,
-    second: Int
-) throws -> Date {
-    var calendar = Calendar(identifier: .gregorian)
-    calendar.timeZone = try #require(TimeZone(secondsFromGMT: 0))
-    return try #require(
-        calendar.date(from: DateComponents(
-            year: year,
-            month: month,
-            day: day,
-            hour: hour,
-            minute: minute,
-            second: second
-        ))
-    )
-}

Tests/ShotdeckCoreTests/FolderSettingsTests.swift

@@ -1,168 +0,0 @@
-import Foundation
-import Testing
-import ShotdeckCore
-
-@Test
-func resolveWithoutStoredKeysReturnsDesktopAndDownloads() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-
-    let resolved = FolderSettings.resolve(defaults: suite.defaults)
-    let expectedOutbox = try #require(
-        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
-    )
-    let expectedWatch = try #require(
-        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
-    )
-
-    #expect(resolved.outbox.path == expectedOutbox.path)
-    #expect(resolved.watch.path == expectedWatch.path)
-}
-
-@Test
-func setOutboxToAnExistingDirectoryIsReturnedByResolve() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-set")
-    defer { try? FileManager.default.removeItem(at: outbox) }
-
-    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
-    let resolved = FolderSettings.resolve(defaults: suite.defaults)
-    let expectedWatch = try #require(
-        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
-    )
-
-    #expect(resolved.outbox.path == outbox.path)
-    #expect(resolved.watch.path == expectedWatch.path)
-    #expect(FolderSettings.storedOutboxPath(defaults: suite.defaults) == outbox.path)
-}
-
-@Test
-func resolveFallsBackWhenTheStoredOutboxDirectoryIsGone() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-gone")
-
-    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
-    try FileManager.default.removeItem(at: outbox)
-
-    let resolved = FolderSettings.resolve(defaults: suite.defaults)
-    let expectedOutbox = try #require(
-        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
-    )
-    #expect(resolved.outbox.path == expectedOutbox.path)
-}
-
-@Test
-func setWatchFolderMirrorsOutboxOverrideAndFallbackIndependently() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-    let watch = try makeTemporaryDirectory(prefix: "shotdeck-watch-set")
-    let expectedOutbox = try #require(
-        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
-    )
-
-    FolderSettings.setWatchFolder(watch, defaults: suite.defaults)
-    let withOverride = FolderSettings.resolve(defaults: suite.defaults)
-    #expect(withOverride.watch.path == watch.path)
-    #expect(withOverride.outbox.path == expectedOutbox.path)
-
-    try FileManager.default.removeItem(at: watch)
-    let afterDelete = FolderSettings.resolve(defaults: suite.defaults)
-    let expectedWatch = try #require(
-        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
-    )
-    #expect(afterDelete.watch.path == expectedWatch.path)
-    #expect(afterDelete.outbox.path == expectedOutbox.path)
-}
-
-@Test
-func resetOutboxClearsTheOverride() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-reset")
-    defer { try? FileManager.default.removeItem(at: outbox) }
-
-    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
-    FolderSettings.resetOutbox(defaults: suite.defaults)
-
-    let resolved = FolderSettings.resolve(defaults: suite.defaults)
-    let expectedOutbox = try #require(
-        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
-    )
-    #expect(resolved.outbox.path == expectedOutbox.path)
-    #expect(FolderSettings.storedOutboxPath(defaults: suite.defaults) == nil)
-}
-
-@Test
-func resolvedAppSupportPathsUsesTheOutboxOverrideAndCreatesSpoolArchive() throws {
-    let suite = try makeDefaultsSuite()
-    defer { tearDown(suite) }
-    let root = try makeTemporaryDirectory(prefix: "shotdeck-paths-root")
-    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-paths-outbox")
-    defer {
-        try? FileManager.default.removeItem(at: root)
-        try? FileManager.default.removeItem(at: outbox)
-    }
-
-    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
-    let paths = try FolderSettings.resolvedAppSupportPaths(root: root, defaults: suite.defaults)
-
-    #expect(paths.outbox.path == outbox.path)
-    #expect(directoryExists(paths.spool))
-    #expect(directoryExists(paths.archive))
-    #expect(paths.spool.deletingLastPathComponent().path == root.path)
-    #expect(paths.archive.deletingLastPathComponent().path == root.path)
-}
-
-@Test
-func userDefaultsSuitesDoNotLeakFolderOverrides() throws {
-    let suiteA = try makeDefaultsSuite()
-    let suiteB = try makeDefaultsSuite()
-    defer {
-        tearDown(suiteA)
-        tearDown(suiteB)
-    }
-    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-suite-a-outbox")
-    defer { try? FileManager.default.removeItem(at: outbox) }
-
-    FolderSettings.setOutbox(outbox, defaults: suiteA.defaults)
-
-    let resolvedA = FolderSettings.resolve(defaults: suiteA.defaults)
-    let resolvedB = FolderSettings.resolve(defaults: suiteB.defaults)
-    let expectedOutbox = try #require(
-        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
-    )
-
-    #expect(resolvedA.outbox.path == outbox.path)
-    #expect(resolvedB.outbox.path == expectedOutbox.path)
-}
-
-private struct DefaultsSuite {
-    let name: String
-    let defaults: UserDefaults
-}
-
-private func makeDefaultsSuite() throws -> DefaultsSuite {
-    let name = "shotdeck-test-\(UUID().uuidString)"
-    let defaults = try #require(UserDefaults(suiteName: name))
-    defaults.removePersistentDomain(forName: name)
-    return DefaultsSuite(name: name, defaults: defaults)
-}
-
-private func tearDown(_ suite: DefaultsSuite) {
-    suite.defaults.removePersistentDomain(forName: suite.name)
-}
-
-private func makeTemporaryDirectory(prefix: String) throws -> URL {
-    let url = FileManager.default.temporaryDirectory
-        .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
-    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
-    return url
-}
-
-private func directoryExists(_ url: URL) -> Bool {
-    var isDirectory: ObjCBool = false
-    let exists = FileManager.default.fileExists(atPath: url.path, isDirectory: &isDirectory)
-    return exists && isDirectory.boolValue
-}

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)
+}