screenhand 0.1.1 → 0.3.0

package/native/macos-bridge/Sources/VisionBridge.swift

@@ -1,13 +1,102 @@
 import Foundation
 import Vision
 import AppKit
+import CoreML
 
 class VisionBridge {
 
+    // MARK: - YOLO Element Detection
+
+    private var yoloModel: VNCoreMLModel?
+    private let yoloClassNames = ["button", "field", "heading", "iframe", "image", "label", "link", "text"]
+
+    /// Load the YOLO CoreML model for UI element detection.
+    /// Called lazily on first detectElements call.
+    private func ensureYoloModel() throws {
+        if yoloModel != nil { return }
+
+        // Look for model relative to the binary or via known paths
+        let execPath = URL(fileURLWithPath: CommandLine.arguments[0]).resolvingSymlinksInPath()
+        let execDir = execPath.deletingLastPathComponent()
+        let possiblePaths = [
+            execDir.appendingPathComponent("../Resources/ui-elements.mlpackage"),
+            execDir.appendingPathComponent("../../Resources/ui-elements.mlpackage"),
+            execDir.appendingPathComponent("Resources/ui-elements.mlpackage"),
+            URL(fileURLWithPath: "/tmp/vins-yolo/web-ui-8cls.mlpackage"), // Development fallback
+        ]
+
+        for modelURL in possiblePaths {
+            if FileManager.default.fileExists(atPath: modelURL.path) {
+                let config = MLModelConfiguration()
+                config.computeUnits = .all // Use ANE when available
+                let coreMLModel = try MLModel(contentsOf: modelURL, configuration: config)
+                yoloModel = try VNCoreMLModel(for: coreMLModel)
+                return
+            }
+        }
+
+        throw BridgeError.general("YOLO model not found")
+    }
+
+    /// Detect UI elements in an image using the YOLO CoreML model.
+    /// Returns bounding boxes with class labels and confidence scores.
+    func detectElements(imagePath: String, confidence: Double = 0.25) throws -> [[String: Any]] {
+        try ensureYoloModel()
+        guard let model = yoloModel else {
+            throw BridgeError.general("YOLO model not loaded")
+        }
+
+        let url = URL(fileURLWithPath: imagePath)
+        guard let image = NSImage(contentsOf: url),
+              let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+            throw BridgeError.general("Failed to load image at \(imagePath)")
+        }
+
+        let imageWidth = CGFloat(cgImage.width)
+        let imageHeight = CGFloat(cgImage.height)
+
+        let request = VNCoreMLRequest(model: model)
+        request.imageCropAndScaleOption = .scaleFit
+
+        let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+        try handler.perform([request])
+
+        guard let observations = request.results as? [VNRecognizedObjectObservation] else {
+            return []
+        }
+
+        var results: [[String: Any]] = []
+        for obs in observations {
+            guard obs.confidence >= Float(confidence) else { continue }
+
+            let bbox = obs.boundingBox
+            // Convert from Vision normalized coords (origin bottom-left) to screen coords
+            let x = bbox.origin.x * imageWidth
+            let y = (1 - bbox.origin.y - bbox.height) * imageHeight
+            let width = bbox.width * imageWidth
+            let height = bbox.height * imageHeight
+
+            let className = obs.labels.first?.identifier ?? "unknown"
+
+            results.append([
+                "class": className,
+                "confidence": Double(obs.confidence),
+                "bounds": [
+                    "x": Double(x),
+                    "y": Double(y),
+                    "width": Double(width),
+                    "height": Double(height),
+                ] as [String: Any],
+            ] as [String: Any])
+        }
+
+        return results
+    }
+
     /// Perform OCR on an image, optionally searching for specific text.
     /// Returns all recognized text with bounding boxes.
-    func findText(imagePath: String, searchText: String?) throws -> [[String: Any]] {
-        let results = try performOCR(imagePath: imagePath)
+    func findText(imagePath: String, searchText: String?, mode: String = "accurate") throws -> [[String: Any]] {
+        let results = try performOCR(imagePath: imagePath, mode: mode)
 
         guard let search = searchText?.lowercased() else {
             return results
@@ -20,8 +109,9 @@ class VisionBridge {
     }
 
     /// Full OCR of an image — returns all recognized text.
-    func ocr(imagePath: String) throws -> [String: Any] {
-        let results = try performOCR(imagePath: imagePath)
+    /// mode: "fast" (perception loop, 10x faster) or "accurate" (tool actions, default)
+    func ocr(imagePath: String, mode: String = "accurate") throws -> [String: Any] {
+        let results = try performOCR(imagePath: imagePath, mode: mode)
         let fullText = results.compactMap { $0["text"] as? String }.joined(separator: "\n")
         return [
             "text": fullText,
@@ -29,7 +119,52 @@ class VisionBridge {
         ]
     }
 
-    private func performOCR(imagePath: String) throws -> [[String: Any]] {
+    /// OCR a specific region of a window — captures the window, crops to the ROI,
+    /// and runs text recognition on just that region. Returns bounds in window coordinates.
+    func ocrRegion(windowId: Int, region: [String: Double], mode: String = "accurate") throws -> [String: Any] {
+        let roiX = region["x"] ?? 0
+        let roiY = region["y"] ?? 0
+        let roiW = region["width"] ?? 0
+        let roiH = region["height"] ?? 0
+
+        // Capture the full window
+        guard let fullImage = CGWindowListCreateImage(
+            .null, .optionIncludingWindow, CGWindowID(windowId), [.bestResolution, .boundsIgnoreFraming]
+        ) else {
+            throw BridgeError.general("CGWindowListCreateImage returned nil for window \(windowId)")
+        }
+
+        // Crop to the ROI (CGImage coordinates have origin top-left, same as our ROI)
+        let cropRect = CGRect(x: roiX, y: roiY, width: roiW, height: roiH)
+            .intersection(CGRect(x: 0, y: 0, width: fullImage.width, height: fullImage.height))
+
+        guard !cropRect.isEmpty,
+              let cropped = fullImage.cropping(to: cropRect) else {
+            return ["text": "", "regions": [] as [Any]]
+        }
+
+        // Run OCR on cropped image
+        let results = try performOCROnImage(cropped, mode: mode)
+
+        // Translate bounds from cropped-image coordinates back to window coordinates
+        let adjustedResults: [[String: Any]] = results.map { entry in
+            var adjusted = entry
+            if var bounds = entry["bounds"] as? [String: Double] {
+                bounds["x"] = (bounds["x"] ?? 0) + roiX
+                bounds["y"] = (bounds["y"] ?? 0) + roiY
+                adjusted["bounds"] = bounds
+            }
+            return adjusted
+        }
+
+        let fullText = adjustedResults.compactMap { $0["text"] as? String }.joined(separator: "\n")
+        return [
+            "text": fullText,
+            "regions": adjustedResults,
+        ]
+    }
+
+    private func performOCR(imagePath: String, mode: String = "accurate") throws -> [[String: Any]] {
         let url = URL(fileURLWithPath: imagePath)
 
         guard let image = NSImage(contentsOf: url),
@@ -37,12 +172,35 @@ class VisionBridge {
             throw BridgeError.general("Failed to load image at \(imagePath)")
         }
 
+        return try performOCROnImage(cgImage, mode: mode)
+    }
+
+    private func performOCROnImage(_ cgImage: CGImage, mode: String = "accurate") throws -> [[String: Any]] {
         let imageWidth = CGFloat(cgImage.width)
         let imageHeight = CGFloat(cgImage.height)
 
         let request = VNRecognizeTextRequest()
-        request.recognitionLevel = .accurate
-        request.usesLanguageCorrection = true
+
+        if mode == "fast" {
+            // FAST mode: 10x faster (~60ms vs ~631ms), used for perception loop
+            // Trades ~20% text coverage for speed — acceptable for frame diffing
+            request.recognitionLevel = .fast
+            request.usesLanguageCorrection = false
+            request.recognitionLanguages = ["en-US"]
+        } else {
+            // ACCURATE mode: full precision, used for tool actions (ocr, click_text)
+            request.recognitionLevel = .accurate
+            request.usesLanguageCorrection = true
+            if #available(macOS 13.0, *) {
+                request.automaticallyDetectsLanguage = true
+            }
+            let supportedLangs = try? request.supportedRecognitionLanguages()
+            if let supported = supportedLangs {
+                request.recognitionLanguages = supported
+            } else {
+                request.recognitionLanguages = ["en-US", "zh-Hans", "zh-Hant", "ja", "ko", "hi", "ar", "de", "fr", "es", "pt", "it", "ru"]
+            }
+        }
 
         let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
         try handler.perform([request])

package/native/macos-bridge/Sources/main.swift

@@ -4,6 +4,40 @@ import Foundation
 /// Reads JSON requests from stdin (one per line), dispatches to the appropriate bridge,
 /// and writes JSON responses to stdout (one per line).
 
+// MARK: - Signal Handlers
+// Catch fatal signals (SIGSEGV, SIGBUS, SIGABRT) that CGWindowListCreateImage
+// can trigger on GPU-heavy windows. Write an error to stderr so the Node.js
+// bridge client can detect the crash, then exit cleanly.
+func installSignalHandlers() {
+    // Fatal signals — crash reporting
+    let fatalSignals: [Int32] = [SIGSEGV, SIGBUS, SIGABRT]
+    for sig in fatalSignals {
+        signal(sig) { signum in
+            let msg = "Bridge fatal signal \(signum) — restarting\n"
+            msg.withCString { ptr in
+                _ = Darwin.write(STDERR_FILENO, ptr, Int(strlen(ptr)))
+            }
+            _exit(128 + signum)
+        }
+    }
+
+    // Graceful shutdown signals — notify Node.js BridgeClient before exit
+    let gracefulSignals: [Int32] = [SIGTERM, SIGINT]
+    for sig in gracefulSignals {
+        signal(sig) { signum in
+            let reason = signum == SIGTERM ? "SIGTERM" : "SIGINT"
+            let notification = "{\"jsonrpc\":\"2.0\",\"method\":\"bridge.shutdown\",\"params\":{\"reason\":\"\(reason)\"}}\n"
+            notification.withCString { ptr in
+                _ = Darwin.write(STDOUT_FILENO, ptr, Int(strlen(ptr)))
+            }
+            // Flush stdout
+            fflush(stdout)
+            _exit(0)
+        }
+    }
+}
+installSignalHandlers()
+
 struct JsonRpcRequest: Codable {
     let id: Int
     let method: String
@@ -117,7 +151,8 @@ let accessibilityBridge = AccessibilityBridge()
 let observerBridge = ObserverBridge()
 let coreGraphicsBridge = CoreGraphicsBridge()
 let visionBridge = VisionBridge()
-let appManagement = AppManagement()
+let appManagement = AppManagement(ax: accessibilityBridge)
+let streamCapture = StreamCapture()
 
 // MARK: - Method Dispatch
 
@@ -149,6 +184,15 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
     case "app.frontmost":
         return appManagement.frontmostApp()
 
+    // Window management (AX-enriched)
+    case "window.list":
+        return appManagement.listWindowsWithAX()
+
+    case "window.focus":
+        let windowId: Int = try requiredParam(params, "windowId")
+        try appManagement.focusWindow(windowId: windowId)
+        return ["ok": true]
+
     // Accessibility
     case "ax.findElement":
         let pid: Int = try requiredParam(params, "pid")
@@ -157,21 +201,29 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
         let value: String? = param(params, "value")
         let identifier: String? = param(params, "identifier")
         let exact: Bool = param(params, "exact") ?? true
+        let maxDepth: Int = param(params, "maxDepth") ?? 30
         return try accessibilityBridge.findElement(
             pid: pid_t(pid), role: role, title: title, value: value,
-            identifier: identifier, exact: exact
+            identifier: identifier, exact: exact, maxDepth: maxDepth
         )
 
     case "ax.getElementTree":
         let pid: Int = try requiredParam(params, "pid")
         let maxDepth: Int = param(params, "maxDepth") ?? 5
-        return try accessibilityBridge.getElementTree(pid: pid_t(pid), maxDepth: maxDepth)
+        let windowId: Int? = param(params, "windowId")
+        return try accessibilityBridge.getElementTree(pid: pid_t(pid), maxDepth: maxDepth, windowId: windowId)
+
+    case "ax.getMenuBar":
+        let pid: Int = try requiredParam(params, "pid")
+        let maxDepth: Int = param(params, "maxDepth") ?? 10
+        return try accessibilityBridge.getMenuBarTree(pid: pid_t(pid), maxDepth: maxDepth)
 
     case "ax.performAction":
         let pid: Int = try requiredParam(params, "pid")
         let elementPath: [Int] = try requiredParam(params, "elementPath")
         let action: String = param(params, "action") ?? "AXPress"
-        try accessibilityBridge.performAction(pid: pid_t(pid), elementPath: elementPath, action: action)
+        let expectedTitle: String? = param(params, "expectedTitle")
+        try accessibilityBridge.performAction(pid: pid_t(pid), elementPath: elementPath, action: action, expectedTitle: expectedTitle)
         return ["ok": true]
 
     case "ax.setElementValue":
@@ -210,13 +262,16 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
         let y: Double = try requiredParam(params, "y")
         let button: String = param(params, "button") ?? "left"
         let clickCount: Int = param(params, "clickCount") ?? 1
-        coreGraphicsBridge.mouseClick(x: x, y: y, button: button, clickCount: clickCount)
+        let modifiers: [String] = param(params, "modifiers") ?? []
+        let mcTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.mouseClick(x: x, y: y, button: button, clickCount: clickCount, modifiers: modifiers, targetPid: mcTargetPid)
         return ["ok": true]
 
     case "cg.mouseMove":
         let x: Double = try requiredParam(params, "x")
         let y: Double = try requiredParam(params, "y")
-        coreGraphicsBridge.mouseMove(x: x, y: y)
+        let mmTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.mouseMove(x: x, y: y, targetPid: mmTargetPid)
         return ["ok": true]
 
     case "cg.mouseDrag":
@@ -224,7 +279,24 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
         let fromY: Double = try requiredParam(params, "fromY")
         let toX: Double = try requiredParam(params, "toX")
         let toY: Double = try requiredParam(params, "toY")
-        coreGraphicsBridge.mouseDrag(fromX: fromX, fromY: fromY, toX: toX, toY: toY)
+        let dragModifiers: [String] = param(params, "modifiers") ?? []
+        let mdTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.mouseDrag(fromX: fromX, fromY: fromY, toX: toX, toY: toY, modifiers: dragModifiers, targetPid: mdTargetPid)
+        return ["ok": true]
+
+    case "cg.mousePressAndHold":
+        let phX: Double = try requiredParam(params, "x")
+        let phY: Double = try requiredParam(params, "y")
+        let phDuration: Int = param(params, "durationMs") ?? 500
+        let phTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.mousePressAndHold(x: phX, y: phY, durationMs: phDuration, targetPid: phTargetPid)
+        return ["ok": true]
+
+    case "cg.keyPressAndHold":
+        let kphKey: String = try requiredParam(params, "key")
+        let kphDuration: Int = param(params, "durationMs") ?? 500
+        let kphTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.keyPressAndHold(key: kphKey, durationMs: kphDuration, targetPid: kphTargetPid)
         return ["ok": true]
 
     case "cg.mouseFlick":
@@ -232,17 +304,20 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
         let fyF: Double = try requiredParam(params, "fromY")
         let txF: Double = try requiredParam(params, "toX")
         let tyF: Double = try requiredParam(params, "toY")
-        coreGraphicsBridge.mouseFlick(fromX: fxF, fromY: fyF, toX: txF, toY: tyF)
+        let mfTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.mouseFlick(fromX: fxF, fromY: fyF, toX: txF, toY: tyF, targetPid: mfTargetPid)
         return ["ok": true]
 
     case "cg.keyCombo":
         let keys: [String] = try requiredParam(params, "keys")
-        coreGraphicsBridge.keyCombo(keys: keys)
+        let kcTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.keyCombo(keys: keys, targetPid: kcTargetPid)
         return ["ok": true]
 
     case "cg.typeText":
         let text: String = try requiredParam(params, "text")
-        coreGraphicsBridge.typeText(text: text)
+        let ttTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.typeText(text: text, targetPid: ttTargetPid)
         return ["ok": true]
 
     case "cg.captureScreen":
@@ -251,25 +326,89 @@ func dispatch(method: String, params: [String: AnyCodable]?) throws -> Any {
 
     case "cg.captureWindow":
         let windowId: Int = try requiredParam(params, "windowId")
-        return try coreGraphicsBridge.captureWindow(windowId: windowId)
+        let safeCLI: Bool = param(params, "safeCLI") ?? false
+        return try coreGraphicsBridge.captureWindow(windowId: windowId, safeCLI: safeCLI)
+
+    case "cg.captureWindowBuffer":
+        let windowId: Int = try requiredParam(params, "windowId")
+        let safeCLI: Bool = param(params, "safeCLI") ?? false
+        return try coreGraphicsBridge.captureWindowBuffer(windowId: windowId, safeCLI: safeCLI)
 
     case "cg.scroll":
         let x: Double = try requiredParam(params, "x")
         let y: Double = try requiredParam(params, "y")
         let deltaX: Int = param(params, "deltaX") ?? 0
         let deltaY: Int = param(params, "deltaY") ?? 0
-        coreGraphicsBridge.scroll(x: x, y: y, deltaX: deltaX, deltaY: deltaY)
+        let scTargetPid: pid_t? = (param(params, "targetPid") as Int?).map { pid_t($0) }
+        coreGraphicsBridge.scroll(x: x, y: y, deltaX: deltaX, deltaY: deltaY, targetPid: scTargetPid)
         return ["ok": true]
 
     // Vision
     case "vision.findText":
         let imagePath: String = try requiredParam(params, "imagePath")
         let searchText: String? = param(params, "searchText")
-        return try visionBridge.findText(imagePath: imagePath, searchText: searchText)
+        let ftMode: String = param(params, "mode") ?? "accurate"
+        return try visionBridge.findText(imagePath: imagePath, searchText: searchText, mode: ftMode)
 
     case "vision.ocr":
         let imagePath: String = try requiredParam(params, "imagePath")
-        return try visionBridge.ocr(imagePath: imagePath)
+        let ocrMode: String = param(params, "mode") ?? "accurate"
+        return try visionBridge.ocr(imagePath: imagePath, mode: ocrMode)
+
+    case "vision.ocrRegion":
+        let windowId: Int = try requiredParam(params, "windowId")
+        let region: [String: Double] = try requiredParam(params, "region")
+        let ocrRegionMode: String = param(params, "mode") ?? "accurate"
+        return try visionBridge.ocrRegion(windowId: windowId, region: region, mode: ocrRegionMode)
+
+    case "vision.detectElements":
+        let imagePath: String = try requiredParam(params, "imagePath")
+        let confidence: Double = param(params, "confidence") ?? 0.25
+        let elements = try visionBridge.detectElements(imagePath: imagePath, confidence: confidence)
+        return ["elements": elements, "count": elements.count]
+
+    // Stream capture — continuous SCStream for fast perception
+    case "vision.startStream":
+        let windowId: Int = try requiredParam(params, "windowId")
+        let fps: Int = param(params, "fps") ?? 30
+        let sem = DispatchSemaphore(value: 0)
+        var streamError: Error?
+        Task {
+            do {
+                try await streamCapture.start(windowId: windowId, fps: fps)
+            } catch {
+                streamError = error
+            }
+            sem.signal()
+        }
+        sem.wait()
+        if let err = streamError { throw err }
+        return ["ok": true, "fps": fps]
+
+    case "vision.stopStream":
+        let sem = DispatchSemaphore(value: 0)
+        Task {
+            await streamCapture.stop()
+            sem.signal()
+        }
+        sem.wait()
+        return ["ok": true]
+
+    case "vision.streamStatus":
+        let running = streamCapture.isRunning
+        if running, let info = streamCapture.getLatestInfo() {
+            return ["running": true, "path": info["path"]!, "width": info["width"]!, "height": info["height"]!, "ageMs": info["ageMs"]!, "frameCount": info["frameCount"]!]
+        }
+        return ["running": running]
+
+    case "vision.latestFrame":
+        guard streamCapture.isRunning else {
+            throw BridgeError.general("Stream not running")
+        }
+        guard let info = streamCapture.getLatestInfo() else {
+            throw BridgeError.general("No frame captured yet")
+        }
+        return info
 
     default:
         throw BridgeError.general("Unknown method: \(method)")
@@ -334,9 +473,23 @@ while let line = readLine() {
             writeResponse(response)
         }
     } catch {
-        // Malformed JSON — write error with id=0
+        // Malformed JSON — try to extract id from raw string
+        var extractedId = 0
+        if let idRange = line.range(of: "\"id\"\\s*:\\s*(\\d+)", options: .regularExpression) {
+            let match = line[idRange]
+            if let digitRange = match.range(of: "\\d+$", options: .regularExpression) {
+                extractedId = Int(match[digitRange]) ?? 0
+            }
+        }
+        if extractedId == 0 {
+            // No id could be extracted — log to stderr so Node.js BridgeClient can detect it
+            let stderrMsg = "Bridge parse error (no id): \(error.localizedDescription)\n"
+            stderrMsg.withCString { ptr in
+                _ = Darwin.write(STDERR_FILENO, ptr, Int(strlen(ptr)))
+            }
+        }
         let response = JsonRpcResponse(
-            id: 0,
+            id: extractedId,
             result: nil,
             error: JsonRpcError(code: -32700, message: "Parse error: \(error.localizedDescription)")
         )

package/native/windows-bridge/Program.cs

@@ -156,6 +156,8 @@ class Program
                 Param<Dictionary<string, double>>(p, "region")),
             "cg.captureWindow" => _screenCapture.CaptureWindow(
                 RequiredParam<int>(p, "windowId")),
+            "cg.captureWindowBuffer" => _screenCapture.CaptureWindowBuffer(
+                RequiredParam<int>(p, "windowId")),
 
             // Vision (OCR)
             "vision.findText" => _screenCapture.FindText(
@@ -163,6 +165,9 @@ class Program
                 Param<string>(p, "searchText")),
             "vision.ocr" => _screenCapture.Ocr(
                 RequiredParam<string>(p, "imagePath")),
+            "vision.ocrRegion" => _screenCapture.OcrRegion(
+                RequiredParam<int>(p, "windowId"),
+                RequiredParam<Dictionary<string, double>>(p, "region")),
 
             _ => throw new BridgeException($"Unknown method: {method}"),
         };

package/native/windows-bridge/ScreenCapture.cs

@@ -157,6 +157,130 @@ class ScreenCapture
         };
     }
 
+    /// <summary>
+    /// Capture a specific window in-memory, return base64 PNG (no disk I/O).
+    /// Equivalent to macOS captureWindowBuffer.
+    /// </summary>
+    public Dictionary<string, object> CaptureWindowBuffer(int windowId)
+    {
+        var hWnd = new IntPtr(windowId);
+        GetWindowRect(hWnd, out RECT rect);
+
+        int width = rect.Right - rect.Left;
+        int height = rect.Bottom - rect.Top;
+
+        if (width <= 0 || height <= 0)
+            throw new BridgeException($"Window {windowId} has invalid dimensions");
+
+        using var bitmap = new Bitmap(width, height, PixelFormat.Format32bppArgb);
+        using var graphics = Graphics.FromImage(bitmap);
+
+        var hdc = graphics.GetHdc();
+        bool success = PrintWindow(hWnd, hdc, PW_RENDERFULLCONTENT);
+        graphics.ReleaseHdc(hdc);
+
+        if (!success)
+        {
+            graphics.CopyFromScreen(rect.Left, rect.Top, 0, 0,
+                new Size(width, height), CopyPixelOperation.SourceCopy);
+        }
+
+        using var ms = new MemoryStream();
+        bitmap.Save(ms, ImageFormat.Png);
+        var base64 = Convert.ToBase64String(ms.ToArray());
+
+        return new Dictionary<string, object>
+        {
+            ["base64"] = base64,
+            ["width"] = width,
+            ["height"] = height,
+        };
+    }
+
+    /// <summary>
+    /// OCR a specific region of a window. Captures window, crops to ROI, runs OCR,
+    /// then translates bounds back to window coordinates.
+    /// Equivalent to macOS vision.ocrRegion.
+    /// </summary>
+    public Dictionary<string, object> OcrRegion(int windowId, Dictionary<string, double> region)
+    {
+        var hWnd = new IntPtr(windowId);
+        GetWindowRect(hWnd, out RECT rect);
+
+        int winWidth = rect.Right - rect.Left;
+        int winHeight = rect.Bottom - rect.Top;
+
+        if (winWidth <= 0 || winHeight <= 0)
+            throw new BridgeException($"Window {windowId} has invalid dimensions");
+
+        int roiX = (int)region.GetValueOrDefault("x", 0);
+        int roiY = (int)region.GetValueOrDefault("y", 0);
+        int roiW = (int)region.GetValueOrDefault("width", winWidth);
+        int roiH = (int)region.GetValueOrDefault("height", winHeight);
+
+        // Clamp ROI to window bounds
+        roiX = Math.Max(0, Math.Min(roiX, winWidth));
+        roiY = Math.Max(0, Math.Min(roiY, winHeight));
+        roiW = Math.Min(roiW, winWidth - roiX);
+        roiH = Math.Min(roiH, winHeight - roiY);
+
+        if (roiW <= 0 || roiH <= 0)
+            throw new BridgeException("ROI has zero or negative area after clamping");
+
+        // Capture full window
+        using var fullBitmap = new Bitmap(winWidth, winHeight, PixelFormat.Format32bppArgb);
+        using (var graphics = Graphics.FromImage(fullBitmap))
+        {
+            var hdc = graphics.GetHdc();
+            bool success = PrintWindow(hWnd, hdc, PW_RENDERFULLCONTENT);
+            graphics.ReleaseHdc(hdc);
+
+            if (!success)
+            {
+                graphics.CopyFromScreen(rect.Left, rect.Top, 0, 0,
+                    new Size(winWidth, winHeight), CopyPixelOperation.SourceCopy);
+            }
+        }
+
+        // Crop to ROI
+        using var cropped = fullBitmap.Clone(
+            new Rectangle(roiX, roiY, roiW, roiH), fullBitmap.PixelFormat);
+
+        // Save cropped to temp file for OCR
+        var tempPath = Path.Combine(_tempDir, $"ocr_region_{DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()}.png");
+        cropped.Save(tempPath, ImageFormat.Png);
+
+        try
+        {
+            var ocrResult = Ocr(tempPath);
+
+            // Translate bounds back to window coordinates
+            if (ocrResult["regions"] is List<object> regions)
+            {
+                foreach (var regionObj in regions)
+                {
+                    if (regionObj is Dictionary<string, object> entry &&
+                        entry["bounds"] is Dictionary<string, object> bounds)
+                    {
+                        bounds["x"] = (double)bounds["x"] + roiX;
+                        bounds["y"] = (double)bounds["y"] + roiY;
+                    }
+                }
+            }
+
+            ocrResult["roiX"] = roiX;
+            ocrResult["roiY"] = roiY;
+            ocrResult["roiWidth"] = roiW;
+            ocrResult["roiHeight"] = roiH;
+
+            return ocrResult;
+        }
+        finally
+        {
+            try { File.Delete(tempPath); } catch { /* best-effort cleanup */ }
+        }
+    }
+
     /// <summary>
     /// OCR an image file. Uses Windows.Media.Ocr when available, falls back to basic implementation.
     /// </summary>