Add a kapture CLI so agents can capture windows and screens

kapture capture --app <name> (or --window-id / --screen) writes a PNG and
prints its path; kapture list enumerates on-screen windows. The CLI is a
thin client: requests go to the running menu-bar app over distributed
notifications plus JSON files in Application Support, so captures use the
app's Screen Recording grant and its window/display logic — no second
permission. The app launches automatically when needed, and the bundled
CLI opens its own app bundle rather than a stale installed copy.

Built as `kapture-cli` (Kapture/kapture collide on the case-insensitive
filesystem), signed nested in the app bundle, and installed on PATH as
`kapture` by the Homebrew cask's binary stanza.

Generated with OpenCode

Assisted-by: Kimi:k3

.gitignore

@@ -5,6 +5,9 @@
 # App bundle (build artifact, regenerate with ./build-app.sh)
 Kapture.app/
 
+# Secrets
+*.p8
+
 # macOS
 .DS_Store
 

Package.swift

@@ -4,10 +4,22 @@ import PackageDescription
 let package = Package(
     name: "Kapture",
     platforms: [.macOS(.v13)],
+    products: [
+        .executable(name: "Kapture", targets: ["Kapture"]),
+        // Command-line client for agents and scripts; talks to the running
+        // menu-bar app over distributed notifications (no extra permissions).
+        // Named kapture-cli because "Kapture" and "kapture" collide on the
+        // case-insensitive filesystem; the cask installs it as `kapture`.
+        .executable(name: "kapture-cli", targets: ["KaptureCLI"]),
+    ],
     targets: [
         .executableTarget(
             name: "Kapture",
             path: "Sources/Kapture"
-        )
+        ),
+        .executableTarget(
+            name: "KaptureCLI",
+            path: "Sources/KaptureCLI"
+        ),
     ]
 )

README.md

@@ -25,11 +25,14 @@ No network calls, no API keys — everything runs locally.
 ## Install with Homebrew
 
 ```bash
-brew tap TZGyn/tap
-brew trust TZGyn/tap          # Homebrew 6+ requires trusting third-party taps
+brew tap TZGyn/tap https://gitea.tzgyn.dev/TZGyn/homebrew-tap.git
+brew trust TZGyn/tap
 brew install --cask kapture
 ```
 
+The tap is hosted on Gitea, so the full URL is required. Homebrew may print
+an "Unsupported tap" warning — it's harmless.
+
 Releases are published as zips on GitHub Releases; `release.sh` packages a
 new one (`./release.sh 1.0.1 && git tag v1.0.1 && git push origin v1.0.1`).
 The cask lives in the [TZGyn/homebrew-tap](https://github.com/TZGyn/homebrew-tap)

Sources/Kapture/App.swift

@@ -21,17 +21,55 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
             runOCRSelfTest()
             return
         }
+        // Single instance: stale copies keep their own hotkey + overlays alive
+        // after app updates and eat clicks meant for the new instance.
+        let myPid = ProcessInfo.processInfo.processIdentifier
+        let others = NSRunningApplication.runningApplications(withBundleIdentifier: "dev.tzgyn.kapture")
+            .filter { $0.processIdentifier != myPid }
+        if !others.isEmpty {
+            CaptureController.log("launch: other Kapture instances pids=\(others.map { String($0.processIdentifier) }.joined(separator: ",")) — terminating them")
+            for other in others {
+                other.forceTerminate()
+            }
+        }
         HotkeyManager.shared.onTrigger = { CaptureController.shared.begin() }
+        HotkeyManager.shared.onFrozenTrigger = { CaptureController.shared.begin(frozen: true) }
+        HotkeyManager.shared.onRecordTrigger = {
+            if RecordingController.shared.state.isRecording {
+                RecordingController.shared.stop()
+            } else {
+                CaptureController.shared.begin(recording: true)
+            }
+        }
         HotkeyManager.shared.register()
+        CLIService.shared.start()
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        RecordingController.shared.finalizeForTermination()
     }
 }
 
 struct MenuView: View {
     @State private var granted = PermissionManager.isGranted
+    @ObservedObject private var recordingState = RecordingController.shared.state
 
     var body: some View {
         Button("Capture & OCR") { CaptureController.shared.begin() }
             .keyboardShortcut("s", modifiers: [.command, .shift])
+            .disabled(recordingState.isRecording)
+
+        Button("Capture Frozen Screen") { CaptureController.shared.begin(frozen: true) }
+            .keyboardShortcut("s", modifiers: [.command, .shift, .control])
+            .disabled(recordingState.isRecording)
+
+        if recordingState.isRecording {
+            Button("Stop Recording") { RecordingController.shared.stop() }
+                .keyboardShortcut("r", modifiers: [.command, .shift, .control])
+        } else {
+            Button("Record Screen…") { CaptureController.shared.begin(recording: true) }
+                .keyboardShortcut("r", modifiers: [.command, .shift, .control])
+        }
 
         Button("Extract from Image File…") { ResultWindow.shared.showOpenPanel() }
 
@@ -48,6 +86,13 @@ struct MenuView: View {
 
         Divider()
 
+        Button("Copy Diagnostics") {
+            let diag = CaptureController.shared.diagnostics()
+            let pasteboard = NSPasteboard.general
+            pasteboard.clearContents()
+            pasteboard.setString(diag, forType: .string)
+        }
+
         Button(LoginItem.isEnabled ? "Disable Launch at Login" : "Launch at Login") {
             if !LoginItem.toggle() {
                 let alert = NSAlert()
@@ -72,6 +117,13 @@ enum PermissionManager {
     static func request() {
         CGRequestScreenCaptureAccess()
     }
+
+    static var isAccessibilityGranted: Bool { AXIsProcessTrusted() }
+
+    static func requestAccessibility() {
+        let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary
+        _ = AXIsProcessTrustedWithOptions(opts)
+    }
 }
 
 enum LoginItem {
@@ -94,33 +146,52 @@ enum LoginItem {
     }
 }
 
-func runOCRSelfTest() {
-    let text = "Kapture OCR test 1234, hello world"
-    let size = NSSize(width: 1600, height: 220)
+func renderTestImage(_ text: String, fontSize: CGFloat = 56, width: CGFloat = 1900, height: CGFloat = 220) -> CGImage? {
+    let size = NSSize(width: width, height: height)
     guard let rep = NSBitmapImageRep(
         bitmapDataPlanes: nil, pixelsWide: Int(size.width), pixelsHigh: Int(size.height),
         bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true, isPlanar: false,
         colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0
-    ) else { exit(1) }
-
+    ) else { return nil }
     NSGraphicsContext.saveGraphicsState()
     NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: rep)
     NSColor.white.setFill()
     NSRect(origin: .zero, size: size).fill()
     let attrs: [NSAttributedString.Key: Any] = [
-        .font: NSFont.boldSystemFont(ofSize: 56),
+        .font: NSFont.systemFont(ofSize: fontSize),
         .foregroundColor: NSColor.black,
     ]
-    text.draw(at: NSPoint(x: 60, y: 75), withAttributes: attrs)
+    // Centre the text vertically so tiny canvases still contain it.
+    let textHeight = ("Ag" as NSString).size(withAttributes: attrs).height
+    let y = max(4, (size.height - textHeight) / 2)
+    text.draw(at: NSPoint(x: 20, y: y), withAttributes: attrs)
     NSGraphicsContext.restoreGraphicsState()
+    return rep.cgImage
+}
 
-    guard let cgImage = rep.cgImage else { exit(1) }
-    OCRService.shared.recognize(cgImage) { recognized in
-        print("expected: \(text)")
+func runOCRSelfTest() {
+    let cases: [(expected: String, contains: String, fontSize: CGFloat, width: CGFloat, height: CGFloat)] = [
+        ("Kapture OCR test 1234, hello world", "Kapture OCR test 1234", 56, 1900, 220),
+        ("你好世界，这是一个测试", "你好世界", 56, 1900, 220),
+        // Tiny text: needs the upscale retry to read anything at all.
+        ("会话导出并发冲突报错 export fail", "导出", 7, 320, 40),
+    ]
+    var index = 0
+
+    func runNext() {
+        guard index < cases.count else { exit(0) }
+        let current = cases[index]
+        index += 1
+        guard let image = renderTestImage(current.expected, fontSize: current.fontSize, width: current.width, height: current.height) else { exit(1) }
+        OCRService.shared.recognize(image) { recognized in
+            print("case:     \(current.expected) @\(Int(current.fontSize))pt")
             print("got:      \(recognized)")
-        let ok = recognized == text
+            let ok = recognized.contains(current.contains)
             print(ok ? "PASS" : "FAIL")
-        exit(ok ? 0 : 1)
+            if !ok { exit(1) }
+            runNext()
         }
+    }
+    runNext()
     RunLoop.main.run()
 }

Sources/Kapture/CLIService.swift

@@ -0,0 +1,211 @@
+import AppKit
+import ImageIO
+import UniformTypeIdentifiers
+
+/// Serves `kapture` CLI requests from the running menu-bar app. The CLI
+/// writes a JSON request into `~/Library/Application Support/Kapture/cli`
+/// and posts a distributed notification carrying its id; this service
+/// captures and writes the JSON response alongside it. Captures use the
+/// app's own Screen Recording grant, so the CLI needs no permissions.
+final class CLIService {
+    static let shared = CLIService()
+
+    static let notificationName = "dev.tzgyn.kapture.cli.request"
+    static let requestKey = "id"
+
+    private var observer: NSObjectProtocol?
+
+    private var directory: URL {
+        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("Kapture/cli", isDirectory: true)
+    }
+
+    private func requestURL(_ id: String) -> URL {
+        directory.appendingPathComponent("\(id).request.json")
+    }
+
+    private func responseURL(_ id: String) -> URL {
+        directory.appendingPathComponent("\(id).response.json")
+    }
+
+    func start() {
+        guard observer == nil else { return }
+        try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        observer = DistributedNotificationCenter.default().addObserver(
+            forName: .init(Self.notificationName), object: nil, queue: .main
+        ) { [weak self] note in
+            guard let id = note.userInfo?[Self.requestKey] as? String else { return }
+            self?.handle(id: id)
+        }
+        CaptureController.log("cli: listening")
+    }
+
+    // MARK: - Requests
+
+    private func handle(id: String) {
+        let url = requestURL(id)
+        defer { try? FileManager.default.removeItem(at: url) }
+        guard let data = try? Data(contentsOf: url),
+              let request = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+            respond(id: id, ["ok": false, "error": "Malformed request"])
+            return
+        }
+        switch request["command"] as? String {
+        case "list":
+            respond(id: id, [
+                "ok": true,
+                "windows": windows().map { window in
+                    [
+                        "id": Int(window.id),
+                        "app": window.app,
+                        "title": window.title,
+                        "width": Int(window.bounds.width),
+                        "height": Int(window.bounds.height),
+                    ] as [String: Any]
+                },
+            ])
+        case "capture":
+            handleCapture(id: id, request: request)
+        default:
+            respond(id: id, ["ok": false, "error": "Unknown command"])
+        }
+    }
+
+    private func handleCapture(id: String, request: [String: Any]) {
+        guard CGPreflightScreenCaptureAccess() else {
+            respond(id: id, ["ok": false, "error": "Kapture does not have Screen Recording permission"])
+            return
+        }
+        let outPath = request["out"] as? String
+
+        if request["screen"] as? Bool == true {
+            guard let screen = NSScreen.screens.first else {
+                respond(id: id, ["ok": false, "error": "No screen available"])
+                return
+            }
+            capture(rect: screen.frame, windowID: nil, out: outPath, id: id)
+            return
+        }
+
+        if let number = request["windowID"] as? NSNumber,
+           let window = windows().first(where: { Int($0.id) == number.intValue }) {
+            capture(rect: window.bounds, windowID: window.id, out: outPath, id: id)
+            return
+        }
+
+        guard let window = bestWindow(for: request["app"] as? String) else {
+            let error = (request["app"] as? String).map { "No on-screen window found for app \"\($0)\"" }
+                ?? "No window found"
+            respond(id: id, ["ok": false, "error": error])
+            return
+        }
+        capture(rect: window.bounds, windowID: window.id, out: outPath, id: id)
+    }
+
+    private func capture(rect: NSRect, windowID: CGWindowID?, out: String?, id: String) {
+        ScreenCapture.shared.capture(rect, excludingWindowIDs: [], windowID: windowID) { [weak self] image in
+            DispatchQueue.main.async {
+                guard let self else { return }
+                guard let image else {
+                    self.respond(id: id, ["ok": false, "error": "Capture failed (Screen Recording permission?)"])
+                    return
+                }
+                let url = out.map { URL(fileURLWithPath: $0) }
+                    ?? FileManager.default.temporaryDirectory.appendingPathComponent("kapture-\(Self.timestamp()).png")
+                guard let dest = CGImageDestinationCreateWithURL(url as CFURL, UTType.png.identifier as CFString, 1, nil) else {
+                    self.respond(id: id, ["ok": false, "error": "Could not create \(url.path)"])
+                    return
+                }
+                CGImageDestinationAddImage(dest, image, nil)
+                guard CGImageDestinationFinalize(dest) else {
+                    self.respond(id: id, ["ok": false, "error": "Could not write \(url.path)"])
+                    return
+                }
+                CaptureController.log("cli: captured \(image.width)x\(image.height) -> \(url.path)")
+                self.respond(id: id, ["ok": true, "path": url.path, "width": image.width, "height": image.height])
+            }
+        }
+    }
+
+    private func respond(id: String, _ body: [String: Any]) {
+        guard let data = try? JSONSerialization.data(withJSONObject: body) else { return }
+        try? data.write(to: responseURL(id), options: .atomic)
+    }
+
+    // MARK: - Windows
+
+    private struct WindowInfo {
+        let id: CGWindowID
+        let pid: Int
+        let app: String
+        let title: String
+        let bounds: NSRect
+    }
+
+    /// On-screen layer-0 windows, front to back, own panels excluded.
+    private func windows() -> [WindowInfo] {
+        guard let list = CGWindowListCopyWindowInfo(
+            [.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID
+        ) as? [[String: Any]] else { return [] }
+
+        let ownPid = Int(ProcessInfo.processInfo.processIdentifier)
+        return list.compactMap { info in
+            guard let id = info[kCGWindowNumber as String] as? CGWindowID,
+                  let layer = info[kCGWindowLayer as String] as? Int, layer == 0,
+                  let pid = info[kCGWindowOwnerPID as String] as? Int, pid != ownPid,
+                  let bounds = info[kCGWindowBounds as String] as? [String: CGFloat],
+                  (bounds["Width"] ?? 0) >= 80, (bounds["Height"] ?? 0) >= 60 else { return nil }
+            let cgRect = NSRect(
+                x: bounds["X"] ?? 0, y: bounds["Y"] ?? 0,
+                width: bounds["Width"] ?? 0, height: bounds["Height"] ?? 0
+            )
+            return WindowInfo(
+                id: id,
+                pid: pid,
+                app: info[kCGWindowOwnerName as String] as? String ?? "",
+                title: info[kCGWindowName as String] as? String ?? "",
+                bounds: Self.cgToAppKit(cgRect)
+            )
+        }
+    }
+
+    private func bestWindow(for query: String?) -> WindowInfo? {
+        let candidates = windows()
+        guard let query, !query.isEmpty else {
+            if let front = NSWorkspace.shared.frontmostApplication,
+               let window = candidates.first(where: { $0.pid == front.processIdentifier }) {
+                return window
+            }
+            return candidates.first
+        }
+        let needle = query.lowercased()
+        if let window = candidates.first(where: { $0.app.lowercased().contains(needle) }) {
+            return window
+        }
+        for app in NSWorkspace.shared.runningApplications {
+            let name = (app.localizedName ?? "").lowercased()
+            let bundle = (app.bundleIdentifier ?? "").lowercased()
+            if name.contains(needle) || bundle.contains(needle),
+               let window = candidates.first(where: { $0.pid == app.processIdentifier }) {
+                return window
+            }
+        }
+        return nil
+    }
+
+    private static func cgToAppKit(_ rect: NSRect) -> NSRect {
+        guard let main = NSScreen.screens.first else { return rect }
+        return NSRect(
+            x: rect.origin.x,
+            y: main.frame.height - rect.origin.y - rect.height,
+            width: rect.width,
+            height: rect.height
+        )
+    }
+
+    private static func timestamp() -> String {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyyMMdd-HHmmss"
+        return formatter.string(from: Date())
+    }
+}

Sources/Kapture/CaptureController.swift

@@ -1,46 +1,205 @@
 import AppKit
 import CoreGraphics
 import ScreenCaptureKit
+import ApplicationServices
 
 final class CaptureController: NSObject {
     static let shared = CaptureController()
 
-    private var overlays: [NSWindow] = []
+    private var overlays: [OverlayWindow] = []
     private(set) var isSelecting = false
     private var previousApp: NSRunningApplication?
     private var overlayIDs: [Int] = []
 
-    func begin() {
+    // Selection state (driven by the event tap; AppKit global coordinates)
+    private var marqueeStart: NSPoint?
+    private(set) var marqueeRect: NSRect?
+    private(set) var hoverWindow: (id: CGWindowID, frame: NSRect, pid: Int)?
+    var hoverFrame: NSRect? { hoverWindow?.frame }
+    private var trackedWindows: [(id: CGWindowID, frame: NSRect, pid: Int)] = []
+    private var lastWindowScan = Date.distantPast
+    private var eventTap: CFMachPort?
+
+    /// Session event log for debugging (dumped via Copy Diagnostics).
+    /// Also appended to /tmp/kapture-debug.log so it survives relaunches.
+    static var sessionLog: [String] = []
+    static func log(_ line: String) {
+        let stamped = String(format: "%@ %@", DateFormatter.localizedString(from: Date(), dateStyle: .none, timeStyle: .medium), line)
+        sessionLog.append(stamped)
+        if sessionLog.count > 200 { sessionLog.removeFirst() }
+        NSLog("[Kapture] \(line)")
+        let path = "/tmp/kapture-debug.log"
+        if let handle = FileHandle(forWritingAtPath: path) {
+            handle.seekToEndOfFile()
+            handle.write((stamped + "\n").data(using: .utf8)!)
+            handle.closeFile()
+        } else {
+            FileManager.default.createFile(atPath: path, contents: (stamped + "\n").data(using: .utf8))
+        }
+    }
+
+    /// Diagnostic snapshot for "Copy Diagnostics" menu item.
+    func diagnostics() -> String {
+        var lines: [String] = []
+        lines.append("Kapture diagnostics — version \(Bundle.main.infoDictionary?["CFBundleShortVersionString"] ?? "?")")
+        lines.append("accessibility=\(AXIsProcessTrusted()) eventTap=\(eventTap != nil)")
+        lines.append("--- session log (newest last) ---")
+        lines.append(contentsOf: Self.sessionLog)
+        lines.append("--- screens ---")
+        for (i, s) in NSScreen.screens.enumerated() {
+            let scale = s.backingScaleFactor
+            let cgID = (s.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber)?.uint32Value ?? 0
+            lines.append("screen[\(i)]: frame=\(s.frame) scale=\(scale) backingSize=\(s.frame.width*scale)x\(s.frame.height*scale) cgID=\(cgID)")
+        }
+        if #available(macOS 14.0, *) {
+            Task {
+                if let content = try? await SCShareableContent.current {
+                    for (i, d) in content.displays.enumerated() {
+                        lines.append("SCDisplay[\(i)]: frame=\(d.frame) width=\(d.width)x\(d.height) id=\(d.displayID)")
+                    }
+                } else {
+                    lines.append("SCShareableContent: unavailable (no Screen Recording permission?)")
+                }
+                let text = lines.joined(separator: "\n")
+                let pb = NSPasteboard.general
+                pb.clearContents()
+                pb.setString(text, forType: .string)
+            }
+        } else {
+            let text = lines.joined(separator: "\n")
+            let pb = NSPasteboard.general
+            pb.clearContents()
+            pb.setString(text, forType: .string)
+        }
+        return lines.joined(separator: "\n")
+    }
+
+    // MARK: - Session lifecycle
+
+    /// Frozen mode: the screen is snapshotted at hotkey press, so the pointer
+    /// and any hover state (tooltips, open menus) end up in the capture.
+    private(set) var isFrozenMode = false
+    /// Recording mode: the selection flow ends in a recording, not a still.
+    private(set) var isRecordingMode = false
+    private var frozenSnapshots: [ScreenCapture.DisplaySnapshot] = []
+
+    func begin(frozen: Bool = false, recording: Bool = false) {
         guard !isSelecting else { return }
+        // No new captures while a recording is running (the selection
+        // overlays would end up in the video).
+        guard !RecordingController.shared.state.isRecording else { return }
         guard PermissionManager.isGranted else {
             PermissionManager.request()
             return
         }
         isSelecting = true
+        isFrozenMode = frozen && !recording
+        isRecordingMode = recording
         previousApp = NSWorkspace.shared.frontmostApplication
-        if #available(macOS 14.0, *) {
-            NSApp.activate()
-        } else {
+        // With the event tap driving input we must NOT activate: stealing
+        // focus turns the target app into background mode (dimmed chrome),
+        // and that is what would end up in the screenshot. Activate only on
+        // the fallback path, where panel events are the only input.
+        let usesTap = AXIsProcessTrusted()
+        if !usesTap {
             NSApp.activate(ignoringOtherApps: true)
         }
-        overlays = NSScreen.screens.map { screen in
-            OverlayWindow(
-                screen: screen,
-                onComplete: { [weak self] rect in self?.finishSelection(rect) },
-                onCancel: { [weak self] in self?.cancelSelection() }
+        CaptureController.log("begin: frozen=\(isFrozenMode) recording=\(recording) usesTap=\(usesTap) active=\(NSApp.isActive)")
+
+        if frozen {
+            ScreenCapture.shared.snapshotAllDisplays(includeCursor: true) { [weak self] snapshots in
+                DispatchQueue.main.async {
+                    guard let self, self.isSelecting else { return }
+                    self.frozenSnapshots = snapshots
+                    CaptureController.log("frozen: captured \(snapshots.count) displays")
+                    self.showOverlays()
+                }
+            }
+        } else {
+            showOverlays()
+        }
+    }
+
+    private func showOverlays() {
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) { [weak self] in
+            guard let self, self.isSelecting else { return }
+            self.overlays = NSScreen.screens.map { screen in
+                let panel = OverlayWindow(screen: screen, controller: self)
+                if let view = panel.contentView as? OverlayView {
+                    view.controller = self
+                    view.frozenImage = self.frozenSnapshots.first(where: { $0.frame == screen.frame })?.image
+                }
+                return panel
+            }
+            // orderFrontRegardless: show without taking key/focus.
+            self.overlays.forEach { $0.orderFrontRegardless() }
+            self.overlayIDs = self.overlays.map { $0.windowNumber }
+            CaptureController.log("begin: \(self.overlays.count) overlays, ids=\(self.overlayIDs) — prior app stays focused")
+            self.installEventTap()
+        }
+    }
+
+    /// A window was picked from hover — capture it directly (real rounded
+    /// corners come from the window's own alpha).
+    private func finishWindowPick(_ windowID: CGWindowID, _ rect: NSRect, ownedRisk: Bool) {
+        let ids = overlayIDs
+        let recording = isRecordingMode
+        hideOverlays()
+        isSelecting = false
+        restorePreviousApp()
+        if recording {
+            // Owned-popup risk: record the screen region instead of the
+            // window filter, which could composite the parent into the video.
+            RecordingController.shared.begin(
+                region: rect,
+                windowID: ownedRisk ? nil : windowID,
+                excludingWindowIDs: ids
             )
+            return
+        }
+        DispatchQueue.main.async { [self] in
+            if ownedRisk {
+                capture(rect, excludingWindowIDs: ids, roundedCorners: true)
+            } else {
+                capture(rect, excludingWindowIDs: ids, windowID: windowID)
+            }
         }
-        overlays.forEach { $0.makeKeyAndOrderFront(nil) }
-        overlayIDs = overlays.map { $0.windowNumber }
     }
 
     private func finishSelection(_ rect: NSRect) {
         let ids = overlayIDs
+        let frozen = frozenSnapshots
+        let wasFrozen = isFrozenMode
+        let recording = isRecordingMode
         hideOverlays()
         guard rect.width >= 2, rect.height >= 2 else {
             cancelSelection()
             return
         }
+
+        if wasFrozen {
+            let midpoint = NSPoint(x: rect.midX, y: rect.midY)
+            let snapshot = frozen.first(where: { $0.frame.contains(midpoint) }) ?? frozen.first
+            isSelecting = false
+            restorePreviousApp()
+            DispatchQueue.main.async { [self] in
+                if let snapshot, let image = ScreenCapture.cropFrozen(snapshot, to: rect) {
+                    CaptureController.log("frozen: cropped \(Int(rect.width))x\(Int(rect.height)) -> \(image.width)x\(image.height)")
+                    ResultWindow.shared.show(image: image)
+                } else {
+                    ResultWindow.shared.show(image: ResultWindow.failureImage("Could not crop the frozen screen."))
+                }
+            }
+            return
+        }
+
+        if recording {
+            isSelecting = false
+            restorePreviousApp()
+            RecordingController.shared.begin(region: rect, windowID: nil, excludingWindowIDs: ids)
+            return
+        }
+
         DispatchQueue.main.async { [self] in
             capture(rect, excludingWindowIDs: ids)
         }
@@ -53,8 +212,15 @@ final class CaptureController: NSObject {
     }
 
     private func hideOverlays() {
+        removeEventTap()
         overlays.forEach { $0.orderOut(nil) }
         overlays = []
+        marqueeRect = nil
+        hoverWindow = nil
+        marqueeStart = nil
+        frozenSnapshots = []
+        isFrozenMode = false
+        isRecordingMode = false
     }
 
     private func restorePreviousApp() {
@@ -62,8 +228,226 @@ final class CaptureController: NSObject {
         previousApp = nil
     }
 
-    private func capture(_ rect: NSRect, excludingWindowIDs ids: [Int]) {
-        ScreenCapture.shared.capture(rect, excludingWindowIDs: ids) { [weak self] image in
+    private func renderOverlays() {
+        for overlay in overlays {
+            (overlay.contentView as? OverlayView)?.needsDisplay = true
+        }
+    }
+
+    // MARK: - Event tap
+
+    private func installEventTap() {
+        guard eventTap == nil else { return }
+        guard AXIsProcessTrusted() else {
+            CaptureController.log("tap: accessibility not granted — falling back to panel events")
+            PermissionManager.requestAccessibility()
+            return
+        }
+        let mask: CGEventMask = (1 << CGEventType.mouseMoved.rawValue)
+            | (1 << CGEventType.leftMouseDown.rawValue)
+            | (1 << CGEventType.leftMouseDragged.rawValue)
+            | (1 << CGEventType.leftMouseUp.rawValue)
+            | (1 << CGEventType.keyDown.rawValue)
+        guard let tap = CGEvent.tapCreate(
+            tap: .cghidEventTap,
+            place: .headInsertEventTap,
+            options: .defaultTap,
+            eventsOfInterest: CGEventMask(mask),
+            callback: Self.tapCallback,
+            userInfo: Unmanaged.passUnretained(self).toOpaque()
+        ) else {
+            CaptureController.log("tap: creation FAILED — falling back to panel events")
+            return
+        }
+        eventTap = tap
+        if let source = CFMachPortCreateRunLoopSource(nil, tap, 0) {
+            CFRunLoopAddSource(CFRunLoopGetMain(), source, .commonModes)
+        }
+        CGEvent.tapEnable(tap: tap, enable: true)
+        CaptureController.log("tap: installed")
+    }
+
+    private func removeEventTap() {
+        guard let tap = eventTap else { return }
+        CGEvent.tapEnable(tap: tap, enable: false)
+        if let source = CFMachPortCreateRunLoopSource(nil, tap, 0) {
+            CFRunLoopRemoveSource(CFRunLoopGetMain(), source, .commonModes)
+        }
+        CFMachPortInvalidate(tap)
+        eventTap = nil
+        CaptureController.log("tap: removed")
+    }
+
+    private static let tapCallback: CGEventTapCallBack = { _, type, event, refcon in
+        guard let refcon else { return Unmanaged.passUnretained(event) }
+        let controller = Unmanaged<CaptureController>.fromOpaque(refcon).takeUnretainedValue()
+        if let result = controller.handleTap(type, event) {
+            return Unmanaged.passUnretained(result)
+        }
+        return nil
+    }
+
+    /// Convert a CG global point (top-left origin) to AppKit global.
+    private func cgPointToAppKit(_ p: NSPoint) -> NSPoint {
+        guard let mainScreen = NSScreen.screens.first else { return p }
+        return NSPoint(x: p.x, y: mainScreen.frame.height - p.y)
+    }
+
+    /// Scan on-screen windows (AppKit global frames), front to back.
+    private func refreshTrackedWindows() {
+        guard let list = CGWindowListCopyWindowInfo(
+            [ .optionOnScreenOnly, .excludeDesktopElements ], kCGNullWindowID
+        ) as? [[String: Any]] else { trackedWindows = []; return }
+
+        let ownIDs = Set(overlayIDs)
+        var found: [(id: CGWindowID, frame: NSRect, pid: Int)] = []
+        for info in list {
+            guard let cid = info[kCGWindowNumber as String] as? CGWindowID,
+                  let bounds = info[kCGWindowBounds as String] as? [String: CGFloat],
+                  let layer = info[kCGWindowLayer as String] as? Int,
+                  let pid = info[kCGWindowOwnerPID as String] as? Int,
+                  layer == 0
+            else { continue }
+            if ownIDs.contains(Int(cid)) { continue }
+            let cgRect = NSRect(
+                x: bounds["X"] ?? 0,
+                y: bounds["Y"] ?? 0,
+                width: bounds["Width"] ?? 0,
+                height: bounds["Height"] ?? 0
+            )
+            guard cgRect.width >= 80, cgRect.height >= 60 else { continue }
+            let rect = Self.cgToAppKit(rect: cgRect)
+            found.append((id: cid, frame: rect, pid: pid))
+        }
+        trackedWindows = found
+    }
+
+    /// Convert a CGWindowList (top-left origin) frame into AppKit screen
+    /// coordinates (bottom-left origin).
+    private static func cgToAppKit(rect: NSRect) -> NSRect {
+        guard let mainScreen = NSScreen.screens.first else { return rect }
+        let y = mainScreen.frame.height - rect.origin.y - rect.height
+        return NSRect(x: rect.origin.x, y: y, width: rect.width, height: rect.height)
+    }
+
+    private func topmostWindowContaining(_ appKitPoint: NSPoint) -> (id: CGWindowID, frame: NSRect, pid: Int)? {
+        for entry in trackedWindows {
+            if entry.frame.contains(appKitPoint) {
+                return entry
+            }
+        }
+        return nil
+    }
+
+    /// System dialogs (permission prompts, System Settings) must always
+    /// receive their clicks even while we're selecting.
+    private func isSystemDialogFrontmost() -> Bool {
+        guard let front = NSWorkspace.shared.frontmostApplication else { return false }
+        let id = front.bundleIdentifier ?? ""
+        return id.hasPrefix("com.apple.security") || id.hasPrefix("com.apple.SystemSettings") || id == "com.apple.systempreferences"
+    }
+
+    /// Returns the event to pass through, or nil to consume it.
+    func handleTap(_ type: CGEventType, _ event: CGEvent) -> CGEvent? {
+        guard isSelecting else { return event }
+        if isSystemDialogFrontmost() {
+            CaptureController.log("tap: system dialog frontmost — passing through \(type)")
+            return event
+        }
+
+        switch type {
+        case .tapDisabledByUserInput, .tapDisabledByTimeout:
+            // A timed-out tap must be re-enabled; guard against a torn-down tap.
+            if let tap = eventTap {
+                CGEvent.tapEnable(tap: tap, enable: true)
+                CaptureController.log("tap: re-enabled after \(type)")
+            }
+            return event
+        case .keyDown:
+            if event.getIntegerValueField(.keyboardEventKeycode) == 53 {
+                CaptureController.log("tap: Esc — cancel")
+                cancelSelection()
+                return nil
+            }
+            return event
+        case .mouseMoved, .leftMouseDragged:
+            // Throttle window scans while moving
+            if Date().timeIntervalSince(lastWindowScan) > 0.15 {
+                lastWindowScan = Date()
+                refreshTrackedWindows()
+            }
+            let appKitPoint = cgPointToAppKit(NSPoint(x: event.location.x, y: event.location.y))
+            if type == .mouseMoved {
+                // Frozen mode is marquee-only: no window hover detection.
+                if isFrozenMode { return event }
+                let window = topmostWindowContaining(appKitPoint)
+                if window?.frame != hoverFrame {
+                    hoverWindow = window
+                    if let w = window {
+                        CaptureController.log("hover: picked id=\(w.id) frame=\(w.frame) (tracked=\(trackedWindows.count))")
+                    } else {
+                        CaptureController.log("hover: none (tracked=\(trackedWindows.count))")
+                    }
+                    renderOverlays()
+                }
+                return event
+            }
+            // Drag: grow the marquee — but only after real movement, so a
+            // click's micro-jitter keeps the hovered window eligible.
+            guard let start = marqueeStart else { return nil }
+            let distance = hypot(appKitPoint.x - start.x, appKitPoint.y - start.y)
+            guard distance >= 4 else { return nil }
+            let rect = NSRect(
+                x: min(start.x, appKitPoint.x),
+                y: min(start.y, appKitPoint.y),
+                width: abs(appKitPoint.x - start.x),
+                height: abs(appKitPoint.y - start.y)
+            )
+            marqueeRect = rect
+            hoverWindow = nil
+            renderOverlays()
+            return nil
+        case .leftMouseDown:
+            marqueeStart = cgPointToAppKit(NSPoint(x: event.location.x, y: event.location.y))
+            marqueeRect = nil
+            CaptureController.log("tap: mouseDown at \(marqueeStart.map { "\($0)" } ?? "?")")
+            return nil
+        case .leftMouseUp:
+            defer { marqueeStart = nil; marqueeRect = nil }
+            let appKitPoint = cgPointToAppKit(NSPoint(x: event.location.x, y: event.location.y))
+            let dragDistance = marqueeStart.map { hypot($0.x - appKitPoint.x, $0.y - appKitPoint.y) } ?? 0
+            if let rect = marqueeRect, dragDistance >= 4, rect.width >= 2, rect.height >= 2 {
+                CaptureController.log("tap: marquee complete \(rect)")
+                finishSelection(rect)
+            } else if isFrozenMode {
+                CaptureController.log("tap: frozen click without drag — cancel")
+                cancelSelection()
+            } else if let hover = hoverWindow {
+                // An overlapping window from the same app means this is an
+                // owned popup — desktopIndependentWindow would composite the
+                // parent too, so capture the screen crop instead.
+                // Owned popups composite their parent even when the windows
+                // don't overlap, so ANY other same-app window on screen means
+                // crop (correct region) instead of the group composite.
+                let ownedRisk = trackedWindows.contains {
+                    $0.id != hover.id && $0.pid == hover.pid
+                }
+                CaptureController.log("tap: window pick id=\(hover.id) pid=\(hover.pid) ownedRisk=\(ownedRisk) \(hover.frame)")
+                finishWindowPick(hover.id, hover.frame, ownedRisk: ownedRisk)
+            } else {
+                CaptureController.log("tap: click with no hover/marquee — cancel")
+                cancelSelection()
+            }
+            return nil
+        default:
+            return event
+        }
+    }
+
+    // MARK: - Capture
+
+    private func capture(_ rect: NSRect, excludingWindowIDs ids: [Int], roundedCorners: Bool = false, windowID: CGWindowID? = nil) {
+        ScreenCapture.shared.capture(rect, excludingWindowIDs: ids, roundedCorners: roundedCorners, windowID: windowID) { [weak self] image in
             DispatchQueue.main.async {
                 self?.isSelecting = false
                 self?.restorePreviousApp()
@@ -72,6 +456,7 @@ final class CaptureController: NSObject {
                         ResultWindow.shared.show(image: ResultWindow.failureImage("Capture failed. Check Screen Recording permission."))
                         return
                     }
+                    CaptureController.log("capture done: \(image.width)x\(image.height) — showing result window")
                     ResultWindow.shared.show(image: image)
                 }
             }
@@ -84,31 +469,186 @@ final class ScreenCapture {
 
     private init() {}
 
+    /// Estimate the window's corner radius (in image pixels) by scanning the
+    /// top-left corner: the crop's corner pixels are the desktop background;
+    /// app content starts where the color departs from it.
+    static func detectCornerRadius(of image: CGImage) -> CGFloat? {
+        let w = image.width, h = image.height
+        guard w > 30, h > 30 else { return nil }
+        var px = [UInt8](repeating: 0, count: w * h * 4)
+        guard let c = CGContext(data: &px, width: w, height: h, bitsPerComponent: 8, bytesPerRow: w * 4,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue) else { return nil }
+        c.draw(image, in: CGRect(x: 0, y: 0, width: w, height: h))
+
+        func pixel(x: Int, yTop: Int) -> (r: Int, g: Int, b: Int) {
+            let row = yTop * w * 4 + x * 4
+            return (Int(px[row]), Int(px[row + 1]), Int(px[row + 2]))
+        }
+        let bg = pixel(x: 0, yTop: 0)
+        func diffFromBg(_ p: (r: Int, g: Int, b: Int)) -> Int {
+            abs(p.r - bg.r) + abs(p.g - bg.g) + abs(p.b - bg.b)
+        }
+        var radii: [CGFloat] = []
+        for (limit, axis) in [(h / 3, 0), (w / 3, 1)] {
+            for i in 0..<limit {
+                let p = axis == 0 ? pixel(x: 0, yTop: i) : pixel(x: i, yTop: 0)
+                if diffFromBg(p) > 24 {
+                    radii.append(CGFloat(i))
+                    break
+                }
+            }
+        }
+        guard radii.count == 2 else { return nil }
+        let r = (radii[0] + radii[1]) / 2
+        return (r >= 3 && r <= 40) ? r : nil
+    }
+
     @available(macOS 14.0, *)
-    private func crop(_ image: CGImage, to rect: NSRect, display: SCDisplay) -> CGImage? {
-        let scaleX = CGFloat(display.width) / display.frame.width
-        let scaleY = CGFloat(display.height) / display.frame.height
-        let cgRect = CGRect(
-            x: rect.minX,
-            y: rect.minY,
-            width: rect.width,
-            height: rect.height
-        )
+    private func crop(_ image: CGImage, to cgRect: CGRect, display: SCDisplay, roundedCorners: Bool = false) -> CGImage? {
+        // cgRect is in SCDisplay space (bottom-left origin, Y flipped vs AppKit).
+        // The captured image has a TOP-LEFT origin. So within the display,
+        // we must flip Y: pixelY = displayHeight - (cgY - displayMinY) - cgHeight.
+        let scaleX = CGFloat(image.width) / display.frame.width
+        let scaleY = CGFloat(image.height) / display.frame.height
+        guard scaleX > 0, scaleY > 0 else { return nil }
+        let localMinX = cgRect.minX - display.frame.minX
+        let localMaxY = cgRect.maxY - display.frame.minY
+        let flippedY = display.frame.height - localMaxY
         let pxRect = CGRect(
-            x: (cgRect.minX - display.frame.minX) * scaleX,
-            y: (cgRect.minY - display.frame.minY) * scaleY,
+            x: localMinX * scaleX,
+            y: flippedY * scaleY,
             width: cgRect.width * scaleX,
             height: cgRect.height * scaleY
         )
-        guard let cropCtx = CGContext(
-            data: nil, width: Int(pxRect.width), height: Int(pxRect.height),
+        // Guard against negative offsets when the selection reaches beyond the
+        // display's frame (e.g. secondary monitor coordinate quirks).
+        let safeRect = pxRect.intersection(CGRect(x: 0, y: 0, width: CGFloat(image.width), height: CGFloat(image.height)))
+        guard safeRect.width >= 1, safeRect.height >= 1 else { return nil }
+        // Use a pixel-exact subimage crop instead of redrawing through a
+        // CGContext, which resamples and loses quality on retina captures.
+        let rounded = safeRect.integral
+        guard rounded.width >= 1, rounded.height >= 1 else { return nil }
+        guard var result = image.cropping(to: rounded) else { return nil }
+
+        // Apply a rounded-corner alpha mask for window captures, matching
+        // macOS window chrome (≈10pt radius, scaled to image pixels).
+        if roundedCorners {
+            // The screen crop contains the app's real rounded corners against
+            // the desktop — measure the radius from the corner pixels, then
+            // mask with it (supersampled for smooth edges).
+            let detected = Self.detectCornerRadius(of: result)
+            let radius = min(max((detected.map { $0 * 1.23 + 2.6 }) ?? (10 * scaleX), 4), 40)
+            CaptureController.log("corners: detected=\(detected.map { String(format: "%.1f", $0) } ?? "nil") using=\(Int(radius))px")
+            // Anti-aliased gray mask: supersample 3x, downsample, then draw
+            // the image through it ONCE at 1x (no content resampling blur).
+            let ss = 3
+            let W = result.width * ss, H = result.height * ss
+            guard let hiMask = CGContext(
+                data: nil, width: W, height: H,
+                bitsPerComponent: 8, bytesPerRow: 0,
+                space: CGColorSpaceCreateDeviceGray(),
+                bitmapInfo: CGImageAlphaInfo.none.rawValue
+            ) else { return result }
+            hiMask.setFillColor(CGColor(gray: 1, alpha: 1))
+            hiMask.fill(CGRect(x: 0, y: 0, width: W, height: H))
+            hiMask.setFillColor(CGColor(gray: 0, alpha: 1))
+            let cornerPath = CGMutablePath()
+            cornerPath.addRect(CGRect(x: 0, y: 0, width: W, height: H))
+            cornerPath.addRoundedRect(in: CGRect(x: 0, y: 0, width: W, height: H), cornerWidth: radius * CGFloat(ss), cornerHeight: radius * CGFloat(ss), transform: .identity)
+            hiMask.addPath(cornerPath)
+            hiMask.fillPath(using: .evenOdd)
+            guard let hiMaskImg = hiMask.makeImage(),
+                  let downMask = CGContext(
+                data: nil, width: result.width, height: result.height,
+                bitsPerComponent: 8, bytesPerRow: 0,
+                space: CGColorSpaceCreateDeviceGray(),
+                bitmapInfo: CGImageAlphaInfo.none.rawValue
+            ) else { return result }
+            downMask.interpolationQuality = .high
+            downMask.draw(hiMaskImg, in: CGRect(x: 0, y: 0, width: result.width, height: result.height))
+            guard let mask1x = downMask.makeImage(),
+                  let ctx = CGContext(
+                data: nil, width: result.width, height: result.height,
                 bitsPerComponent: 8, bytesPerRow: 0,
                 space: CGColorSpaceCreateDeviceRGB(),
                 bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
-        ) else { return nil }
-        cropCtx.interpolationQuality = .high
-        cropCtx.draw(image, in: CGRect(x: -pxRect.minX, y: -pxRect.minY, width: CGFloat(image.width), height: CGFloat(image.height)))
-        return cropCtx.makeImage()
+            ) else { return result }
+            ctx.clip(to: CGRect(x: 0, y: 0, width: result.width, height: result.height), mask: mask1x)
+            ctx.draw(result, in: CGRect(x: 0, y: 0, width: result.width, height: result.height))
+            if let masked = ctx.makeImage() {
+                result = masked
+            }
+        }
+        return result
+    }
+
+    /// Screen frame (AppKit global points) + full-resolution image per display.
+    struct DisplaySnapshot {
+        let frame: NSRect
+        let image: CGImage
+    }
+
+    /// Snapshot every display right now. Used by frozen mode: the images are
+    /// taken before the overlay appears, so the pointer and hover states
+    /// (tooltips, menus) are baked in.
+    func snapshotAllDisplays(includeCursor: Bool, completion: @escaping ([DisplaySnapshot]) -> Void) {
+        if #available(macOS 14.0, *) {
+            Task {
+                guard let content = try? await SCShareableContent.current else {
+                    completion([])
+                    return
+                }
+                var out: [DisplaySnapshot] = []
+                for display in content.displays {
+                    guard let screen = NSScreen.screens.first(where: {
+                        (($0.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber)?.uint32Value ?? 0) == display.displayID
+                    }) else { continue }
+                    let config = SCStreamConfiguration()
+                    let scale = screen.backingScaleFactor
+                    config.width = Int(CGFloat(display.width) * scale)
+                    config.height = Int(CGFloat(display.height) * scale)
+                    config.showsCursor = includeCursor
+                    let filter = SCContentFilter(display: display, excludingWindows: [])
+                    if let image = try? await SCScreenshotManager.captureImage(contentFilter: filter, configuration: config) {
+                        out.append(DisplaySnapshot(frame: screen.frame, image: image))
+                    }
+                }
+                completion(out)
+            }
+        } else {
+            var out: [DisplaySnapshot] = []
+            for screen in NSScreen.screens {
+                let cgRect = CGRect(
+                    x: screen.frame.minX,
+                    y: (NSScreen.screens.first(where: { $0.frame.origin == .zero })?.frame.height ?? screen.frame.height) - screen.frame.maxY,
+                    width: screen.frame.width,
+                    height: screen.frame.height
+                )
+                if let image = CGWindowListCreateImage(cgRect, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution, .boundsIgnoreFraming]) {
+                    out.append(DisplaySnapshot(frame: screen.frame, image: image))
+                }
+            }
+            completion(out)
+        }
+    }
+
+    /// Crop a selection out of a frozen snapshot (top-left pixel space).
+    static func cropFrozen(_ snapshot: DisplaySnapshot, to rect: NSRect) -> CGImage? {
+        let scaleX = CGFloat(snapshot.image.width) / snapshot.frame.width
+        let scaleY = CGFloat(snapshot.image.height) / snapshot.frame.height
+        guard scaleX > 0, scaleY > 0 else { return nil }
+        let localX = rect.minX - snapshot.frame.minX
+        let localTopY = snapshot.frame.maxY - rect.maxY
+        let px = CGRect(
+            x: localX * scaleX,
+            y: localTopY * scaleY,
+            width: rect.width * scaleX,
+            height: rect.height * scaleY
+        )
+        let safe = px.intersection(CGRect(x: 0, y: 0, width: CGFloat(snapshot.image.width), height: CGFloat(snapshot.image.height))).integral
+        guard safe.width >= 1, safe.height >= 1 else { return nil }
+        return snapshot.image.cropping(to: safe)
     }
 
     @available(macOS 14.0, *)
@@ -121,7 +661,7 @@ final class ScreenCapture {
         return content.displays.first(where: { $0.displayID == cgID }) ?? content.displays.first
     }
 
-    func capture(_ rect: NSRect, excludingWindowIDs excludedIDs: [Int], completion: @escaping (CGImage?) -> Void) {
+    func capture(_ rect: NSRect, excludingWindowIDs excludedIDs: [Int], roundedCorners: Bool = false, windowID: CGWindowID? = nil, completion: @escaping (CGImage?) -> Void) {
         if #available(macOS 14.0, *) {
             Task {
                 guard let content = try? await SCShareableContent.current,
@@ -133,15 +673,66 @@ final class ScreenCapture {
                 let excluded = content.windows.filter { excludedSet.contains($0.windowID) }
                 let filter = SCContentFilter(display: display, excludingWindows: excluded)
                 let config = SCStreamConfiguration()
-                config.width = Int(display.width)
-                config.height = Int(display.height)
-                config.showsCursor = true
+                // SCDisplay.width/height are in POINTS; SCStreamConfiguration
+                // width/height are output PIXELS. Multiply by the backing scale
+                // of the screen containing the selection so retina displays are
+                // captured at full resolution and 1x displays stay 1x.
+                guard let screen = NSScreen.screens.first(where: { $0.frame.contains(NSPoint(x: rect.midX, y: rect.midY)) }) else {
+                    completion(nil)
+                    return
+                }
+                let backingScale = screen.backingScaleFactor
+                config.width = Int(CGFloat(display.width) * backingScale)
+                config.height = Int(CGFloat(display.height) * backingScale)
+                config.showsCursor = false
+
+                // ScreenCaptureKit uses a different origin than AppKit for
+                // screens stacked around the main display: per-display,
+                // SCDisplay y = appKitY - NSScreen.maxY + SCDisplay.maxY.
+                let scRect = CGRect(
+                    x: rect.minX,
+                    y: rect.minY - screen.frame.maxY + display.frame.maxY,
+                    width: rect.width,
+                    height: rect.height
+                )
+
+                // Window pick: capture the window DIRECTLY — the image comes
+                // with the app's real rounded-corner alpha (no mask guessing).
+                if let windowID,
+                   let scWindow = content.windows.first(where: { $0.windowID == windowID }) {
+                    var windowConfig = SCStreamConfiguration()
+                    windowConfig.width = Int(scWindow.frame.width * backingScale)
+                    windowConfig.height = Int(scWindow.frame.height * backingScale)
+                            windowConfig.showsCursor = false
+                    if let windowImage = try? await SCScreenshotManager.captureImage(
+                        contentFilter: SCContentFilter(desktopIndependentWindow: scWindow),
+                        configuration: windowConfig
+                    ) {
+                        let expectedW = CGFloat(scWindow.frame.width) * backingScale
+                        let expectedH = CGFloat(scWindow.frame.height) * backingScale
+                        let overflow = max(
+                            CGFloat(windowImage.width) / max(expectedW, 1),
+                            CGFloat(windowImage.height) / max(expectedH, 1)
+                        )
+                        if overflow > 1.35 {
+                            // SCKit composited extra windows (owned popups etc.)
+                            // — reject and use the screen crop instead.
+                            CaptureController.log("capture: WINDOW id=\(windowID) overflow=\(overflow) (\(windowImage.width)x\(windowImage.height) vs \(Int(expectedW))x\(Int(expectedH))) — rejecting, using crop+mask")
+                        } else {
+                            CaptureController.log("capture: WINDOW id=\(windowID) image=\(windowImage.width)x\(windowImage.height) (native alpha corners)")
+                            completion(windowImage)
+                            return
+                        }
+                    }
+                    CaptureController.log("capture: window filter failed for id=\(windowID) — falling back to crop+mask")
+                }
 
                 guard let image = try? await SCScreenshotManager.captureImage(contentFilter: filter, configuration: config) else {
                     completion(nil)
                     return
                 }
-                completion(self.crop(image, to: rect, display: display))
+                CaptureController.log("capture: rect=\(rect) screen=\(screen.frame) display=\(display.frame) backing=\(backingScale) image=\(image.width)x\(image.height) scRect=\(scRect)")
+                completion(self.crop(image, to: scRect, display: display, roundedCorners: roundedCorners))
             }
         } else {
             guard let primary = NSScreen.screens.first(where: { $0.frame.origin == .zero }) ?? NSScreen.screens.first else {

Sources/Kapture/HotkeyManager.swift

@@ -4,11 +4,16 @@ import AppKit
 final class HotkeyManager {
     static let shared = HotkeyManager()
 
+    /// ⌘⇧S — live capture (ScreenCaptureKit at capture time).
     var onTrigger: (() -> Void)?
+    /// ⌃⇧⌘S — frozen capture (snapshot at hotkey press).
+    var onFrozenTrigger: (() -> Void)?
+    /// ⌃⇧⌘R — screen recording (region or window); toggles stop.
+    var onRecordTrigger: (() -> Void)?
 
-    private var hotKeyRef: EventHotKeyRef?
+    private var hotKeyRefs: [EventHotKeyRef?] = []
     private var eventHandlerRef: EventHandlerRef?
-    private var hotKeyID = EventHotKeyID(signature: 0x4B505452, id: 1)
+    private let signature: OSType = 0x4B505452
 
     private init() {}
 
@@ -17,18 +22,38 @@ final class HotkeyManager {
             eventClass: OSType(kEventClassKeyboard),
             eventKind: UInt32(kEventHotKeyPressed)
         )
-        InstallEventHandler(GetApplicationEventTarget(), { _, _, _ in
-            HotkeyManager.shared.onTrigger?()
+        InstallEventHandler(GetApplicationEventTarget(), { _, event, _ in
+            var hotKeyID = EventHotKeyID()
+            let status = GetEventParameter(
+                event,
+                EventParamName(kEventParamDirectObject),
+                EventParamType(typeEventHotKeyID),
+                nil,
+                MemoryLayout<EventHotKeyID>.size,
+                nil,
+                &hotKeyID
+            )
+            guard status == noErr else { return noErr }
+            DispatchQueue.main.async {
+                switch hotKeyID.id {
+                case 1: HotkeyManager.shared.onTrigger?()
+                case 2: HotkeyManager.shared.onFrozenTrigger?()
+                case 3: HotkeyManager.shared.onRecordTrigger?()
+                default: break
+                }
+            }
             return noErr
         }, 1, &eventType, nil, &eventHandlerRef)
 
-        RegisterEventHotKey(
-            UInt32(kVK_ANSI_S),
-            UInt32(cmdKey | shiftKey),
-            hotKeyID,
-            GetApplicationEventTarget(),
-            0,
-            &hotKeyRef
-        )
+        registerHotkey(id: 1, keyCode: UInt32(kVK_ANSI_S), modifiers: UInt32(cmdKey | shiftKey))
+        registerHotkey(id: 2, keyCode: UInt32(kVK_ANSI_S), modifiers: UInt32(cmdKey | shiftKey | controlKey))
+        registerHotkey(id: 3, keyCode: UInt32(kVK_ANSI_R), modifiers: UInt32(cmdKey | shiftKey | controlKey))
+    }
+
+    private func registerHotkey(id: UInt32, keyCode: UInt32, modifiers: UInt32) {
+        var ref: EventHotKeyRef?
+        let hotKeyID = EventHotKeyID(signature: signature, id: id)
+        RegisterEventHotKey(keyCode, modifiers, hotKeyID, GetApplicationEventTarget(), 0, &ref)
+        hotKeyRefs.append(ref)
     }
 }

Sources/Kapture/OCRService.swift

@@ -8,17 +8,40 @@ final class OCRService {
 
     func recognize(_ cgImage: CGImage, completion: @escaping (String) -> Void) {
         queue.async {
+            let text = Self.perform(cgImage)
+            // Tiny text (small UI labels) often reads as nothing at native
+            // size; retry upscaled and keep whichever pass read more.
+            guard text.count < 3 else {
+                completion(text)
+                return
+            }
+            var best = text
+            for factor in [CGFloat(2), CGFloat(3)] {
+                guard let upscaled = Self.upscaled(cgImage, factor: factor) else { continue }
+                let candidate = Self.perform(upscaled)
+                if candidate.count > best.count { best = candidate }
+                if best.count >= 3 { break }
+            }
+            completion(best)
+        }
+    }
+
+    private static func perform(_ cgImage: CGImage) -> String {
         let request = VNRecognizeTextRequest()
         request.recognitionLevel = .accurate
         request.usesLanguageCorrection = true
         request.recognitionLanguages = ["en-US", "zh-Hans", "zh-Hant", "ja-JP", "ko-KR"]
+        // Without this, Vision defaults to the first listed language and
+        // renders CJK as Latin garbage (verified: 你好世界 -> "177WR").
+        if #available(macOS 13.0, *) {
+            request.automaticallyDetectsLanguage = true
+        }
 
         let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
         do {
             try handler.perform([request])
         } catch {
-                completion("")
-                return
+            return ""
         }
 
         let observations = request.results ?? []
@@ -30,7 +53,21 @@ final class OCRService {
                 return a.boundingBox.minX < b.boundingBox.minX
             }
             .compactMap { $0.topCandidates(1).first?.string }
-            completion(lines.joined(separator: "\n"))
+        return lines.joined(separator: "\n")
     }
+
+    private static func upscaled(_ cgImage: CGImage, factor: CGFloat) -> CGImage? {
+        let width = Int(CGFloat(cgImage.width) * factor)
+        let height = Int(CGFloat(cgImage.height) * factor)
+        guard width > 0, height > 0, width <= 20000, height <= 20000 else { return nil }
+        guard let ctx = CGContext(
+            data: nil, width: width, height: height,
+            bitsPerComponent: 8, bytesPerRow: 0,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return nil }
+        ctx.interpolationQuality = .high
+        ctx.draw(cgImage, in: CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))
+        return ctx.makeImage()
     }
 }

Sources/Kapture/OverlayView.swift

@@ -1,17 +1,23 @@
 import AppKit
 
+/// Renders the capture overlay. All interaction state lives in
+/// CaptureController (driven by the CGEventTap); this view only draws.
 final class OverlayWindow: NSPanel {
-    init(screen: NSScreen, onComplete: @escaping (NSRect) -> Void, onCancel: @escaping () -> Void) {
-        let content = OverlayView(onComplete: onComplete, onCancel: onCancel)
+    init(screen: NSScreen, controller: CaptureController) {
+        let content = OverlayView()
         super.init(
+            // Non-activating: the overlay must NOT steal focus, so the app
+            // being captured keeps its active appearance (undimmed chrome).
+            // Input comes from the CGEventTap, not panel events.
             contentRect: screen.frame,
             styleMask: [.borderless, .nonactivatingPanel],
             backing: .buffered,
             defer: false
         )
         contentView = content
+        content.controller = controller
         level = .screenSaver
-        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .transient]
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
         backgroundColor = .clear
         isOpaque = false
         hasShadow = false
@@ -23,21 +29,10 @@ final class OverlayWindow: NSPanel {
 }
 
 final class OverlayView: NSView {
-    private let onComplete: (NSRect) -> Void
-    private let onCancel: () -> Void
-
-    private var startPoint: NSPoint?
-    private(set) var selection: NSRect?
-
-    init(onComplete: @escaping (NSRect) -> Void, onCancel: @escaping () -> Void) {
-        self.onComplete = onComplete
-        self.onCancel = onCancel
-        super.init(frame: .zero)
-    }
-
-    required init?(coder: NSCoder) {
-        fatalError("init(coder:) has not been implemented")
-    }
+    weak var controller: CaptureController?
+    /// In frozen mode: the still image to display for this screen (already
+    /// full resolution). Nil = live mode (dim the real screen).
+    var frozenImage: CGImage?
 
     override var acceptsFirstResponder: Bool { true }
 
@@ -47,55 +42,135 @@ final class OverlayView: NSView {
         addCursorRect(bounds, cursor: .crosshair)
     }
 
-    override func mouseDown(with event: NSEvent) {
-        let p = convert(event.locationInWindow, from: nil)
-        startPoint = p
-        selection = NSRect(origin: p, size: .zero)
-        needsDisplay = true
+    /// The screen frame this overlay covers, in AppKit global space.
+    private var screenFrame: NSRect {
+        guard let window else { return .zero }
+        return window.convertToScreen(NSRect(origin: .zero, size: bounds.size))
     }
 
-    override func mouseDragged(with event: NSEvent) {
-        guard let start = startPoint else { return }
-        let p = convert(event.locationInWindow, from: nil)
-        selection = NSRect(
-            x: min(start.x, p.x),
-            y: min(start.y, p.y),
-            width: abs(p.x - start.x),
-            height: abs(p.y - start.y)
+    /// Convert an AppKit-global rect into this view's coordinates.
+    private func viewRect(_ global: NSRect) -> NSRect {
+        let sf = screenFrame
+        return NSRect(
+            x: global.origin.x - sf.origin.x,
+            y: global.origin.y - sf.origin.y,
+            width: global.width,
+            height: global.height
         )
-        needsDisplay = true
     }
 
-    override func mouseUp(with event: NSEvent) {
-        guard let sel = selection else { return }
-        if sel.width >= 2, sel.height >= 2 {
-            onComplete(window!.convertToScreen(sel))
-        } else {
-            onCancel()
-        }
+    /// Draw the frozen snapshot filling the screen, then replace its centre
+    /// hole with the live... no: the image IS the content, drawn opaque.
+    private func drawFrozen(_ image: CGImage) {
+        guard let ctx = NSGraphicsContext.current?.cgContext else { return }
+        ctx.saveGState()
+        ctx.interpolationQuality = .high
+        // Image is in pixels, view in points — draw into the view bounds.
+        ctx.draw(image, in: bounds)
+        ctx.restoreGState()
     }
 
-    override func keyDown(with event: NSEvent) {
-        if event.keyCode == 53 {
-            onCancel()
-        } else {
-            super.keyDown(with: event)
-        }
+    private func drawSizeLabel(for sel: NSRect, in vf: NSRect) {
+        let label = "\(Int(sel.width)) × \(Int(sel.height))"
+        let attrs: [NSAttributedString.Key: Any] = [
+            .font: NSFont.monospacedDigitSystemFont(ofSize: 12, weight: .medium),
+            .foregroundColor: NSColor.white,
+        ]
+        let labelSize = label.size(withAttributes: attrs)
+        let labelRect = NSRect(
+            x: vf.maxX - labelSize.width - 8,
+            y: vf.minY - labelSize.height - 10,
+            width: labelSize.width + 8,
+            height: labelSize.height + 6
+        )
+        NSColor.black.withAlphaComponent(0.6).setFill()
+        NSBezierPath(roundedRect: labelRect, xRadius: 4, yRadius: 4).fill()
+        label.draw(at: NSPoint(x: labelRect.minX + 4, y: labelRect.minY + 3), withAttributes: attrs)
     }
 
     override func draw(_ dirtyRect: NSRect) {
+        if let frozenImage {
+            drawFrozen(frozenImage)
+        } else {
+            NSColor.black.withAlphaComponent(0.35).setFill()
+            NSBezierPath(rect: bounds).fill()
+        }
+
+        // Esc hint — the only way out once clicks are consumed by the tap.
+        let hint: String
+        if controller?.isRecordingMode == true {
+            hint = "Drag to select · hover + click a window to record · Esc to cancel"
+        } else if frozenImage != nil {
+            hint = "Frozen screen · drag to select · Esc to cancel"
+        } else {
+            hint = "Drag to select · hover + click a window to capture it · Esc to cancel"
+        }
+        let hintAttrs: [NSAttributedString.Key: Any] = [
+            .font: NSFont.monospacedSystemFont(ofSize: 12, weight: .medium),
+            .foregroundColor: NSColor.white.withAlphaComponent(0.85),
+        ]
+        let hintSize = hint.size(withAttributes: hintAttrs)
+        let hintRect = NSRect(
+            x: (bounds.width - hintSize.width) / 2 - 10,
+            y: bounds.height - 46,
+            width: hintSize.width + 20,
+            height: hintSize.height + 12
+        )
+        NSColor.black.withAlphaComponent(0.65).setFill()
+        NSBezierPath(roundedRect: hintRect, xRadius: 8, yRadius: 8).fill()
+        hint.draw(at: NSPoint(x: hintRect.minX + 10, y: hintRect.minY + 6), withAttributes: hintAttrs)
+
+        guard let controller else { return }
+
+        // Frozen mode: same look as live mode — a dark veil over everything,
+        // with the selection showing the frozen pixels undimmed.
+        if let frozenImage {
             NSColor.black.withAlphaComponent(0.35).setFill()
             NSBezierPath(rect: bounds).fill()
 
-        guard let sel = selection, sel.width > 0, sel.height > 0 else { return }
+            if let sel = controller.marqueeRect, sel.width > 0, sel.height > 0 {
+                let vf = viewRect(sel)
+                NSGraphicsContext.current?.saveGraphicsState()
+                NSBezierPath(rect: vf).addClip()
+                drawFrozen(frozenImage)
+                NSGraphicsContext.current?.restoreGraphicsState()
+
+                let border = NSBezierPath(rect: vf)
+                border.lineWidth = 1.5
+                NSColor.controlAccentColor.setStroke()
+                border.stroke()
+                drawSizeLabel(for: sel, in: vf)
+            }
+            return
+        }
+
+        // Highlight the hovered window (rounded, like real window corners)
+        if let frame = controller.hoverFrame {
+            let vf = viewRect(frame)
+            NSGraphicsContext.current?.saveGraphicsState()
+            NSGraphicsContext.current?.compositingOperation = .clear
+            NSColor.black.setFill()
+            NSBezierPath(roundedRect: vf, xRadius: 10, yRadius: 10).fill()
+            NSGraphicsContext.current?.restoreGraphicsState()
+
+            let border = NSBezierPath(roundedRect: vf, xRadius: 10, yRadius: 10)
+            border.lineWidth = 2
+            NSColor.controlAccentColor.setStroke()
+            border.stroke()
+            return
+        }
+
+        // Marquee selection
+        guard let sel = controller.marqueeRect, sel.width > 0, sel.height > 0 else { return }
+        let vf = viewRect(sel)
 
         NSGraphicsContext.current?.saveGraphicsState()
         NSGraphicsContext.current?.compositingOperation = .clear
         NSColor.black.setFill()
-        NSBezierPath(rect: sel).fill()
+        NSBezierPath(rect: vf).fill()
         NSGraphicsContext.current?.restoreGraphicsState()
 
-        let border = NSBezierPath(rect: sel)
+        let border = NSBezierPath(rect: vf)
         border.lineWidth = 1.5
         NSColor.controlAccentColor.setStroke()
         border.stroke()
@@ -107,8 +182,8 @@ final class OverlayView: NSView {
         ]
         let labelSize = label.size(withAttributes: attrs)
         let labelRect = NSRect(
-            x: sel.maxX - labelSize.width - 8,
-            y: sel.minY - labelSize.height - 10,
+            x: vf.maxX - labelSize.width - 8,
+            y: vf.minY - labelSize.height - 10,
             width: labelSize.width + 8,
             height: labelSize.height + 6
         )

Sources/Kapture/RecordingController.swift

@@ -0,0 +1,181 @@
+import AppKit
+import SwiftUI
+
+/// Shared recording state, observed by the menu bar menu and control bar.
+final class RecordingState: ObservableObject {
+    @Published var isRecording = false
+    @Published var elapsed: TimeInterval = 0
+}
+
+/// Owns a recording session: the red border around the recorded region and
+/// the floating timer/stop bar. Both chrome windows are excluded from the
+/// video. On stop, the file is auto-saved to ~/Movies and revealed in Finder.
+final class RecordingController {
+    static let shared = RecordingController()
+
+    let state = RecordingState()
+
+    private var recorder: ScreenRecorder?
+    private var chromeWindows: [NSWindow] = []
+    private var timer: Timer?
+
+    /// `region` is in AppKit global points; `windowID` records that window
+    /// instead of the region. Called by CaptureController after the
+    /// selection overlays are hidden.
+    func begin(region: NSRect, windowID: CGWindowID?, excludingWindowIDs: [Int]) {
+        guard !state.isRecording else { return }
+        showChrome(region: region)
+        let excluded = excludingWindowIDs + chromeWindows.map { $0.windowNumber }
+        state.isRecording = true
+
+        let recorder = ScreenRecorder()
+        self.recorder = recorder
+        // Give the window server a beat so the chrome shows up in the
+        // shareable-content snapshot and gets excluded from the video.
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) { [weak self] in
+            guard let self, self.recorder === recorder else { return }
+            recorder.start(region: region, windowID: windowID, excludingWindowIDs: excluded) { [weak self] ok in
+                DispatchQueue.main.async {
+                    guard let self else { return }
+                    if ok {
+                        self.startTimer()
+                    } else {
+                        self.finish(url: nil)
+                        ResultWindow.shared.show(image: ResultWindow.failureImage("Could not start the recording. Check Screen Recording permission."))
+                    }
+                }
+            }
+        }
+    }
+
+    func stop() {
+        guard state.isRecording else { return }
+        state.isRecording = false
+        timer?.invalidate()
+        timer = nil
+        recorder?.stop { [weak self] url in
+            DispatchQueue.main.async { self?.finish(url: url) }
+        }
+    }
+
+    /// Best-effort finalize on quit so the .mov isn't left truncated.
+    /// Blocks briefly — only call from applicationWillTerminate.
+    func finalizeForTermination() {
+        guard let recorder else { return }
+        let semaphore = DispatchSemaphore(value: 0)
+        recorder.stop { _ in semaphore.signal() }
+        _ = semaphore.wait(timeout: .now() + 3)
+    }
+
+    private func finish(url: URL?) {
+        state.isRecording = false
+        hideChrome()
+        recorder = nil
+        state.elapsed = 0
+        if let url {
+            CaptureController.log("rec: saved \(url.path)")
+            NSWorkspace.shared.activateFileViewerSelecting([url])
+        }
+    }
+
+    private func startTimer() {
+        let started = Date()
+        state.elapsed = 0
+        timer = Timer.scheduledTimer(withTimeInterval: 0.5, repeats: true) { [weak self] _ in
+            self?.state.elapsed = Date().timeIntervalSince(started)
+        }
+    }
+
+    // MARK: - Chrome
+
+    private func showChrome(region: NSRect) {
+        // Red border around the recorded region.
+        let border = NSPanel(
+            contentRect: region,
+            styleMask: [.borderless, .nonactivatingPanel],
+            backing: .buffered,
+            defer: false
+        )
+        border.level = .screenSaver
+        border.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        border.backgroundColor = .clear
+        border.isOpaque = false
+        border.hasShadow = false
+        border.ignoresMouseEvents = true
+        border.contentView = RecordingBorderView()
+        border.orderFrontRegardless()
+
+        // Floating timer/stop bar at the bottom centre of the region.
+        let bar = NSPanel(
+            contentRect: .zero,
+            styleMask: [.borderless, .nonactivatingPanel],
+            backing: .buffered,
+            defer: false
+        )
+        bar.level = .screenSaver
+        bar.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        bar.backgroundColor = .clear
+        bar.isOpaque = false
+        bar.hasShadow = false
+        let hosting = NSHostingView(rootView: RecordingBarView(state: state) { [weak self] in
+            self?.stop()
+        })
+        let size = hosting.fittingSize
+        bar.setContentSize(size)
+        bar.setFrameOrigin(NSPoint(x: region.midX - size.width / 2, y: region.minY + 14))
+        bar.contentView = hosting
+        bar.orderFrontRegardless()
+
+        chromeWindows = [border, bar]
+    }
+
+    private func hideChrome() {
+        chromeWindows.forEach { $0.orderOut(nil) }
+        chromeWindows = []
+    }
+}
+
+/// Draws the red rounded border around the recorded region.
+private final class RecordingBorderView: NSView {
+    override func draw(_ dirtyRect: NSRect) {
+        let path = NSBezierPath(roundedRect: bounds.insetBy(dx: 2, dy: 2), xRadius: 8, yRadius: 8)
+        NSColor.systemRed.setStroke()
+        path.lineWidth = 3
+        path.stroke()
+    }
+}
+
+/// The floating capsule bar: red dot, elapsed time, stop button.
+struct RecordingBarView: View {
+    @ObservedObject var state: RecordingState
+    let onStop: () -> Void
+
+    private var timeString: String {
+        let total = Int(state.elapsed)
+        return String(format: "%02d:%02d", total / 60, total % 60)
+    }
+
+    var body: some View {
+        HStack(spacing: 10) {
+            Circle()
+                .fill(Color.red)
+                .frame(width: 8, height: 8)
+            Text(timeString)
+                .font(.system(size: 12, weight: .medium).monospacedDigit())
+                .foregroundStyle(.white)
+            Button(action: onStop) {
+                Image(systemName: "stop.fill")
+                    .font(.system(size: 10, weight: .bold))
+                    .foregroundStyle(.white)
+                    .frame(width: 22, height: 22)
+                    .background(Circle().fill(Color.red))
+                    .contentShape(Circle())
+            }
+            .buttonStyle(.plain)
+            .help("Stop recording (⌃⇧⌘R)")
+        }
+        .padding(.horizontal, 12)
+        .padding(.vertical, 7)
+        .background(Capsule().fill(Color.black.opacity(0.78)))
+    }
+}

Sources/Kapture/ScreenRecorder.swift

@@ -0,0 +1,203 @@
+import AppKit
+import AVFoundation
+import CoreMedia
+import ScreenCaptureKit
+
+/// Records a screen region (or a single window) to an H.264 .mov via
+/// SCStream -> AVAssetWriter. Works on macOS 13+ (no SCScreenshotManager).
+///
+/// Video-only for now: the audio path is wired behind `includeAudio`
+/// (off) — enabling sound later means setting the flag to true, which
+/// turns on `capturesAudio`, adds an AAC track, and starts appending
+/// audio sample buffers. That path is untested until enabled.
+final class ScreenRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
+    /// Future: also record system audio into the .mov.
+    var includeAudio = false
+
+    private let queue = DispatchQueue(label: "dev.tzgyn.kapture.rec")
+    private var stream: SCStream?
+    private var writer: AVAssetWriter?
+    private var videoInput: AVAssetWriterInput?
+    private var audioInput: AVAssetWriterInput?
+    private var sessionStarted = false
+    private var outputURL: URL?
+
+    /// `region` is in AppKit global points. When `windowID` is given the
+    /// stream records that window directly (and follows it if it moves);
+    /// otherwise it records `region` via a display filter + sourceRect.
+    func start(region: NSRect, windowID: CGWindowID?, excludingWindowIDs: [Int], completion: @escaping (Bool) -> Void) {
+        Task {
+            do {
+                try await prepare(region: region, windowID: windowID, excludingWindowIDs: excludingWindowIDs)
+                completion(true)
+            } catch {
+                CaptureController.log("rec: start failed: \(error.localizedDescription)")
+                completion(false)
+            }
+        }
+    }
+
+    private func prepare(region: NSRect, windowID: CGWindowID?, excludingWindowIDs: [Int]) async throws {
+        let content = try await SCShareableContent.current
+
+        let excludedSet = Set(excludingWindowIDs.map { CGWindowID($0) })
+        let excluded = content.windows.filter { excludedSet.contains($0.windowID) }
+
+        let config = SCStreamConfiguration()
+        let filter: SCContentFilter
+        let pixelWidth: Int
+        let pixelHeight: Int
+
+        let regionCentre = NSPoint(x: region.midX, y: region.midY)
+        let screen = NSScreen.screens.first(where: { $0.frame.contains(regionCentre) }) ?? NSScreen.screens.first
+        let scale = screen?.backingScaleFactor ?? 2
+
+        if let windowID, let scWindow = content.windows.first(where: { $0.windowID == windowID }) {
+            filter = SCContentFilter(desktopIndependentWindow: scWindow)
+            pixelWidth = max(2, Int(scWindow.frame.width * scale) / 2 * 2)
+            pixelHeight = max(2, Int(scWindow.frame.height * scale) / 2 * 2)
+            CaptureController.log("rec: window id=\(windowID) \(pixelWidth)x\(pixelHeight)")
+        } else {
+            guard let screen else {
+                throw NSError(domain: "dev.tzgyn.kapture", code: 1, userInfo: [NSLocalizedDescriptionKey: "No screen for region"])
+            }
+            let cgID = (screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber)?.uint32Value ?? 0
+            guard let display = content.displays.first(where: { $0.displayID == cgID }) ?? content.displays.first else {
+                throw NSError(domain: "dev.tzgyn.kapture", code: 2, userInfo: [NSLocalizedDescriptionKey: "No display for region"])
+            }
+            filter = SCContentFilter(display: display, excludingWindows: excluded)
+            // sourceRect is display-local POINTS with a TOP-LEFT origin
+            // (same mapping cropFrozen uses for the frozen snapshots).
+            let local = CGRect(
+                x: region.minX - screen.frame.minX,
+                y: screen.frame.maxY - region.maxY,
+                width: region.width,
+                height: region.height
+            ).intersection(CGRect(x: 0, y: 0, width: display.frame.width, height: display.frame.height))
+            guard local.width >= 2, local.height >= 2 else {
+                throw NSError(domain: "dev.tzgyn.kapture", code: 3, userInfo: [NSLocalizedDescriptionKey: "Region outside display"])
+            }
+            config.sourceRect = local
+            pixelWidth = max(2, Int(local.width * scale) / 2 * 2)
+            pixelHeight = max(2, Int(local.height * scale) / 2 * 2)
+            CaptureController.log("rec: region \(region) sourceRect=\(local) \(pixelWidth)x\(pixelHeight)")
+        }
+
+        config.width = pixelWidth
+        config.height = pixelHeight
+        config.minimumFrameInterval = CMTime(value: 1, timescale: 60)
+        config.pixelFormat = kCVPixelFormatType_32BGRA
+        // Recordings SHOULD include the pointer (unlike stills).
+        config.showsCursor = true
+        config.queueDepth = 6
+        config.capturesAudio = includeAudio
+
+        let movies = FileManager.default.urls(for: .moviesDirectory, in: .userDomainMask).first
+            ?? URL(fileURLWithPath: NSHomeDirectory())
+        let url = movies.appendingPathComponent("Kapture-\(Self.timestamp()).mov")
+        let writer = try AVAssetWriter(url: url, fileType: .mov)
+
+        let videoInput = AVAssetWriterInput(mediaType: .video, outputSettings: [
+            AVVideoCodecKey: AVVideoCodecType.h264,
+            AVVideoWidthKey: pixelWidth,
+            AVVideoHeightKey: pixelHeight,
+        ])
+        videoInput.expectsMediaDataInRealTime = true
+        writer.add(videoInput)
+
+        var audioInput: AVAssetWriterInput?
+        if includeAudio {
+            let input = AVAssetWriterInput(mediaType: .audio, outputSettings: [
+                AVFormatIDKey: kAudioFormatMPEG4AAC,
+                AVSampleRateKey: 48000,
+                AVNumberOfChannelsKey: 2,
+            ])
+            input.expectsMediaDataInRealTime = true
+            writer.add(input)
+            audioInput = input
+        }
+
+        guard writer.startWriting() else {
+            throw writer.error ?? NSError(domain: "dev.tzgyn.kapture", code: 4, userInfo: [NSLocalizedDescriptionKey: "AVAssetWriter failed to start"])
+        }
+
+        let stream = SCStream(filter: filter, configuration: config, delegate: self)
+        try stream.addStreamOutput(self, type: .screen, sampleHandlerQueue: queue)
+        if includeAudio {
+            try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: queue)
+        }
+        try await stream.startCapture()
+
+        self.stream = stream
+        self.writer = writer
+        self.videoInput = videoInput
+        self.audioInput = audioInput
+        self.outputURL = url
+        CaptureController.log("rec: started -> \(url.lastPathComponent)")
+    }
+
+    /// Stops the stream and finalizes the file. Completion gets the URL on
+    /// success (called on an internal queue — hop to main for UI).
+    func stop(completion: @escaping (URL?) -> Void) {
+        Task {
+            try? await stream?.stopCapture()
+            stream = nil
+            queue.async {
+                guard let writer = self.writer else {
+                    completion(nil)
+                    return
+                }
+                self.videoInput?.markAsFinished()
+                self.audioInput?.markAsFinished()
+                let url = self.outputURL
+                self.writer = nil
+                self.videoInput = nil
+                self.audioInput = nil
+                self.sessionStarted = false
+                writer.finishWriting {
+                    CaptureController.log("rec: finished status=\(writer.status.rawValue)")
+                    completion(writer.status == .completed ? url : nil)
+                }
+            }
+        }
+    }
+
+    // MARK: SCStreamOutput (called on `queue`)
+
+    func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {
+        guard CMSampleBufferDataIsReady(sampleBuffer), let writer, let videoInput else { return }
+        switch type {
+        case .screen:
+            // Skip incomplete frames (macOS 13.1+ exposes a frame status).
+            if #available(macOS 13.1, *) {
+                guard let attachments = (CMSampleBufferGetSampleAttachmentsArray(sampleBuffer, createIfNecessary: false) as? [NSDictionary])?.first,
+                      let dict = attachments as? [String: Any],
+                      let statusRaw = dict[SCStreamFrameInfo.status.rawValue] as? Int,
+                      SCFrameStatus(rawValue: statusRaw) == .complete else { return }
+            }
+            guard videoInput.isReadyForMoreMediaData else { return }
+            if !sessionStarted {
+                sessionStarted = true
+                writer.startSession(atSourceTime: CMSampleBufferGetPresentationTimeStamp(sampleBuffer))
+            }
+            videoInput.append(sampleBuffer)
+        case .audio:
+            guard includeAudio, sessionStarted, let audioInput, audioInput.isReadyForMoreMediaData else { return }
+            audioInput.append(sampleBuffer)
+        default:
+            break
+        }
+    }
+
+    // MARK: SCStreamDelegate
+
+    func stream(_ stream: SCStream, didStopWithError error: Error) {
+        CaptureController.log("rec: stream stopped with error: \(error.localizedDescription)")
+    }
+
+    private static func timestamp() -> String {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyyMMdd-HHmmss"
+        return formatter.string(from: Date())
+    }
+}

Sources/KaptureCLI/main.swift

@@ -0,0 +1,254 @@
+import AppKit
+import Foundation
+
+// kapture — command-line client for the Kapture menu-bar app.
+//
+// It does not capture by itself: requests go to the running app, which
+// already holds the Screen Recording permission and owns all window /
+// display capture logic. Requests and responses are JSON files in
+// ~/Library/Application Support/Kapture/cli, signalled by a distributed
+// notification carrying the request id.
+
+let helpText = """
+kapture — screenshot capture for agents and scripts
+
+USAGE
+  kapture capture [options]   Capture a window or the main display to a PNG
+  kapture list [--json]       List on-screen windows (id, app, title, size)
+  kapture --help              Show this help
+
+CAPTURE OPTIONS
+  --app <name|bundle-id>   App whose frontmost window to capture. Matches
+                           localized names and bundle ids, case-insensitive
+                           substring. Default: the frontmost app's window.
+  --window-id <id>         Capture a specific window id from `kapture list`.
+  --screen                 Capture the main display instead of a window.
+  --out <path>             Output PNG path (default: a new file in $TMPDIR).
+  --json                   Print {"ok","path","width","height"} instead of
+                           just the path.
+
+BEHAVIOR
+  Prints the absolute PNG path on stdout (exit 0). Errors go to stderr.
+  Requires the Kapture menu-bar app (Homebrew cask); it is launched
+  automatically if it is not running.
+
+EXAMPLES
+  kapture capture --app Xcode --out /tmp/xcode.png
+  kapture capture --app Safari --json
+  kapture list
+  kapture capture --window-id 1234 --out shot.png
+  kapture capture --screen
+"""
+
+// MARK: - Bridge
+
+enum Bridge {
+    static let notificationName = "dev.tzgyn.kapture.cli.request"
+    static let appBundleID = "dev.tzgyn.kapture"
+
+    static var directory: URL {
+        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("Kapture/cli", isDirectory: true)
+    }
+
+    static func appIsRunning() -> Bool {
+        NSWorkspace.shared.runningApplications.contains {
+            $0.bundleIdentifier == appBundleID || $0.localizedName == "Kapture"
+        }
+    }
+
+    static func launchApp() {
+        // Prefer the bundle this CLI lives inside, so a dev CLI launches its
+        // own app build rather than a stale installed copy with the same id.
+        let executable = URL(fileURLWithPath: CommandLine.arguments[0]).resolvingSymlinksInPath()
+        let appBundle = executable
+            .deletingLastPathComponent()  // Contents/MacOS
+            .deletingLastPathComponent()  // Contents
+            .deletingLastPathComponent()  // Kapture.app
+        let task = Process()
+        task.executableURL = URL(fileURLWithPath: "/usr/bin/open")
+        if appBundle.pathExtension == "app" {
+            task.arguments = [appBundle.path]
+        } else {
+            task.arguments = ["-b", appBundleID]
+        }
+        task.standardOutput = FileHandle.nullDevice
+        task.standardError = FileHandle.nullDevice
+        try? task.run()
+        task.waitUntilExit()
+    }
+
+    /// Send a request to the app and wait for its response. Posts the
+    /// notification repeatedly so a still-starting app can pick it up.
+    static func send(_ request: [String: Any], timeout: TimeInterval = 12) -> [String: Any]? {
+        try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        let id = UUID().uuidString
+        let requestURL = directory.appendingPathComponent("\(id).request.json")
+        let responseURL = directory.appendingPathComponent("\(id).response.json")
+        defer {
+            try? FileManager.default.removeItem(at: requestURL)
+            try? FileManager.default.removeItem(at: responseURL)
+        }
+        guard let data = try? JSONSerialization.data(withJSONObject: request),
+              (try? data.write(to: requestURL, options: .atomic)) != nil else {
+            return nil
+        }
+
+        if !appIsRunning() { launchApp() }
+
+        let deadline = Date().addingTimeInterval(timeout)
+        var lastPost = Date.distantPast
+        while Date() < deadline {
+            if Date().timeIntervalSince(lastPost) > 0.3 {
+                lastPost = Date()
+                DistributedNotificationCenter.default().postNotificationName(
+                    .init(notificationName), object: nil,
+                    userInfo: ["id": id], deliverImmediately: true
+                )
+            }
+            if let responseData = try? Data(contentsOf: responseURL),
+               let object = (try? JSONSerialization.jsonObject(with: responseData)) as? [String: Any] {
+                return object
+            }
+            usleep(50_000)
+        }
+        return nil
+    }
+}
+
+// MARK: - Output helpers
+
+func fail(_ message: String, code: Int32) -> Never {
+    FileHandle.standardError.write(("kapture: " + message + "\n").data(using: .utf8)!)
+    exit(code)
+}
+
+func usageError(_ message: String) -> Never {
+    FileHandle.standardError.write(("kapture: " + message + "\n\n" + helpText + "\n").data(using: .utf8)!)
+    exit(2)
+}
+
+func printJSON(_ object: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: object, options: [.sortedKeys]) else { return }
+    print(String(data: data, encoding: .utf8) ?? "{}")
+}
+
+func timestamp() -> String {
+    let formatter = DateFormatter()
+    formatter.dateFormat = "yyyyMMdd-HHmmss"
+    return formatter.string(from: Date())
+}
+
+// MARK: - Commands
+
+func runCapture(_ args: [String]) {
+    var app: String?
+    var windowID: Int?
+    var screen = false
+    var out: String?
+    var json = false
+
+    var index = 0
+    while index < args.count {
+        switch args[index] {
+        case "--app":
+            index += 1
+            guard index < args.count else { usageError("--app needs a value") }
+            app = args[index]
+        case "--window-id":
+            index += 1
+            guard index < args.count, let id = Int(args[index]) else { usageError("--window-id needs a number") }
+            windowID = id
+        case "--screen":
+            screen = true
+        case "--out":
+            index += 1
+            guard index < args.count else { usageError("--out needs a path") }
+            out = args[index]
+        case "--json":
+            json = true
+        default:
+            usageError("unknown option \"\(args[index])\"")
+        }
+        index += 1
+    }
+
+    let outURL = URL(fileURLWithPath: (out.map { ($0 as NSString).expandingTildeInPath }
+        ?? FileManager.default.temporaryDirectory.appendingPathComponent("kapture-\(timestamp()).png").path))
+
+    var request: [String: Any] = ["command": "capture", "screen": screen, "out": outURL.path]
+    if let app { request["app"] = app }
+    if let windowID { request["windowID"] = windowID }
+
+    guard let response = Bridge.send(request) else {
+        fail("the Kapture app did not respond. Is it installed and running?", code: 3)
+    }
+    guard (response["ok"] as? Bool) == true else {
+        fail(response["error"] as? String ?? "capture failed", code: 1)
+    }
+    if json {
+        printJSON([
+            "ok": true,
+            "path": response["path"] as? String ?? outURL.path,
+            "width": response["width"] as? Int ?? 0,
+            "height": response["height"] as? Int ?? 0,
+        ])
+    } else {
+        print(response["path"] as? String ?? outURL.path)
+    }
+}
+
+func runList(_ args: [String]) {
+    var json = false
+    for arg in args {
+        switch arg {
+        case "--json": json = true
+        default: usageError("unknown option \"\(arg)\"")
+        }
+    }
+    guard let response = Bridge.send(["command": "list"]) else {
+        fail("the Kapture app did not respond. Is it installed and running?", code: 3)
+    }
+    guard (response["ok"] as? Bool) == true else {
+        fail(response["error"] as? String ?? "could not list windows", code: 1)
+    }
+    let windows = response["windows"] as? [[String: Any]] ?? []
+    if json {
+        printJSON(["ok": true, "windows": windows])
+        return
+    }
+    func pad(_ text: String, _ width: Int) -> String {
+        text.count >= width ? String(text.prefix(width - 1)) + "…" : text.padding(toLength: width, withPad: " ", startingAt: 0)
+    }
+    print("\(pad("ID", 8)) \(pad("APP", 20)) \(pad("TITLE", 50)) SIZE")
+    for window in windows {
+        let id = window["id"] as? Int ?? 0
+        let app = window["app"] as? String ?? ""
+        let title = window["title"] as? String ?? ""
+        let width = window["width"] as? Int ?? 0
+        let height = window["height"] as? Int ?? 0
+        print("\(pad(String(id), 8)) \(pad(app, 20)) \(pad(title, 50)) \(width)x\(height)")
+    }
+}
+
+// MARK: - Main
+
+var arguments = Array(CommandLine.arguments.dropFirst())
+guard let command = arguments.first else {
+    print(helpText)
+    exit(2)
+}
+arguments.removeFirst()
+
+switch command {
+case "capture":
+    runCapture(arguments)
+case "list":
+    runList(arguments)
+case "--help", "-h", "help":
+    print(helpText)
+case "--version", "-v":
+    print("kapture (bundled with the Kapture app)")
+default:
+    usageError("unknown command \"\(command)\"")
+}

build-app.sh

@@ -23,8 +23,10 @@ SIGN_KEYCHAIN=""
 if [ -n "$DEV_IDENT" ]; then
     CERT="$DEV_IDENT"
     echo "Using Developer ID identity: $CERT"
-    # Sign from the login keychain where the Dev ID lives.
-    SIGN_KEYCHAIN=""
+    # Ensure the login keychain holding the Dev ID is unlocked & accessible.
+    security unlock-keychain "$HOME/Library/Keychains/login.keychain-db" 2>/dev/null || true
+    security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "" "$HOME/Library/Keychains/login.keychain-db" >/dev/null 2>&1 || true
+    SIGN_KEYCHAIN="$HOME/Library/Keychains/login.keychain-db"
 else
     CERT="kapture-dev"
     echo "Using self-signed identity 'kapture-dev'"
@@ -87,6 +89,9 @@ fi
 rm -rf "$APP"
 mkdir -p "$APP/Contents/MacOS"
 cp "$BIN" "$APP/Contents/MacOS/Kapture"
+# CLI client for agents/scripts; installed on PATH as `kapture` by the
+# Homebrew cask (binary target: kapture).
+cp ".build/release/kapture-cli" "$APP/Contents/MacOS/kapture-cli"
 
 cat > "$APP/Contents/Info.plist" <<'PLIST'
 <?xml version="1.0" encoding="UTF-8"?>
@@ -106,9 +111,9 @@ cat > "$APP/Contents/Info.plist" <<'PLIST'
     <key>CFBundleIconFile</key>
     <string>Icon</string>
     <key>CFBundleShortVersionString</key>
-    <string>1.1.0</string>
+    <string>1.12.0</string>
     <key>CFBundleVersion</key>
-    <string>10</string>
+    <string>120</string>
     <key>LSUIElement</key>
     <true/>
     <key>NSHighResolutionCapable</key>
@@ -122,9 +127,13 @@ PLIST
 chmod +x scripts/make-icon.sh
 ./scripts/make-icon.sh
 
+# Nested executable: sign it explicitly so the bundle seal and notarization
+# see a Developer ID signature rather than SwiftPM's ad-hoc one.
 if [ -n "$SIGN_KEYCHAIN" ]; then
-    codesign --force --sign "$CERT" --keychain "$SIGN_KEYCHAIN" "$APP"
+    codesign --force --options runtime --sign "$CERT" --keychain "$SIGN_KEYCHAIN" "$APP/Contents/MacOS/kapture-cli"
+    codesign --force --options runtime --sign "$CERT" --keychain "$SIGN_KEYCHAIN" "$APP"
 else
+    codesign --force --sign "$CERT" "$APP/Contents/MacOS/kapture-cli"
     codesign --force --sign "$CERT" "$APP"
 fi
 

release.sh

@@ -8,14 +8,83 @@ if [ "$#" -ne 1 ]; then
 fi
 VERSION="$1"
 
+# Notarization credentials. Configure once, e.g. in ~/.zshrc:
+#   export KAPTURE_NOTARY_ASC_PROVIDER="<TeamID>"
+#   export KAPTURE_NOTARY_API_KEY_PATH="$HOME/.config/kapture/AuthKey_XXXX.p8"
+#   export KAPTURE_NOTARY_API_KEY_ID="<KeyID>"
+#   export KAPTURE_NOTARY_API_ISSUER="<IssuerID>"
+# If these are unset (or KAPTURE_SKIP_NOTARY=1), release.sh builds, zips, and stops
+# there — the zip is signed with the Developer ID identity but NOT notarized.
+
 ./build-app.sh
 
 mkdir -p dist
 rm -f dist/Kapture.zip
 ditto -c -k --keepParent Kapture.app dist/Kapture.zip
-shasum -a 256 dist/Kapture.zip
 
+if [ -n "${KAPTURE_SKIP_NOTARY:-}" ]; then
+    echo
+    echo "Skipping notarization (KAPTURE_SKIP_NOTARY set)."
+    shasum -a 256 dist/Kapture.zip
+    echo
+    echo "Tag and release with:"
+    echo "  git tag v$VERSION && git push origin v$VERSION"
+    echo "Attach dist/Kapture.zip to the GitHub release manually."
+    exit 0
+fi
+
+REQUIRED_VARS="KAPTURE_NOTARY_ASC_PROVIDER KAPTURE_NOTARY_API_KEY_PATH KAPTURE_NOTARY_API_KEY_ID KAPTURE_NOTARY_API_ISSUER"
+MISSING=""
+for v in $REQUIRED_VARS; do
+    if [ -z "${!v:-}" ]; then
+        MISSING="$MISSING $v"
+    fi
+done
+if [ -n "$MISSING" ]; then
+    echo "Notarization skipped — missing env var(s):$MISSING (see header comments)." >&2
+    shasum -a 256 dist/Kapture.zip
+    echo
+    echo "The zip above is signed but NOT notarized; Gatekeeper will warn users until it is."
+    echo "Set the KAPTURE_NOTARY_* variables and re-run ./release.sh $VERSION."
+    exit 0
+fi
+
+if ! command -v xcrun >/dev/null 2>&1 || ! xcrun --find notarytool >/dev/null 2>&1; then
+    echo "Notarization skipped — xcrun notarytool not found (requires Xcode 13+)." >&2
+    shasum -a 256 dist/Kapture.zip
+    exit 0
+fi
+
+echo "Submitting to Apple for notarization (first run can take minutes)..."
+xcrun notarytool submit dist/Kapture.zip \
+    --key "$KAPTURE_NOTARY_API_KEY_PATH" \
+    --key-id "$KAPTURE_NOTARY_API_KEY_ID" \
+    --issuer "$KAPTURE_NOTARY_API_ISSUER" \
+    --wait \
+    --output-format json > notary-result.json
+
+STATUS=$(jq -r '.status' notary-result.json 2>/dev/null || echo "unknown")
+if [ "$STATUS" != "Accepted" ]; then
+    echo "Notarization failed with status: $STATUS" >&2
+    if [ -f notary-result.json ]; then
+        cat notary-result.json >&2
+        rm -f notary-result.json
+    fi
+    exit 1
+fi
+rm -f notary-result.json
+
+echo "Notarization accepted — stapling ticket onto the app..."
+xcrun stapler staple Kapture.app
+xcrun stapler validate Kapture.app
+
+rm -f dist/Kapture.zip
+ditto -c -k --keepParent Kapture.app dist/Kapture.zip
+
+echo
+echo "Done — notarized."
+shasum -a 256 dist/Kapture.zip
 echo
 echo "Tag and release with:"
 echo "  git tag v$VERSION && git push origin v$VERSION"
-echo "Attach dist/Kapture.zip to the GitHub release manually."
+echo "Attach dist/Kapture.zip to the GitHub release manually; the Homebrew cask is ready."