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

Sources/Shotdeck/RegionPickerController.swift

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

Sources/Shotdeck/RegionPickerWindow.swift

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

Sources/ShotdeckCore/Capture/CaptureRegion.swift

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

Sources/ShotdeckCore/Capture/HotkeyCenter.swift

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

Sources/ShotdeckCore/Capture/ScreenCapturer.swift

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

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