WP-3a: CaptureRegion geometry + Carbon HotkeyCenter per SPEC-A2a

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/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/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/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/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
-}