screenhand 0.1.1 → 0.3.0

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

@@ -10,12 +10,64 @@ class AccessibilityBridge {
 
     // MARK: - Element Tree
 
-    func getElementTree(pid: pid_t, maxDepth: Int) throws -> [String: Any] {
+    /// Max total nodes to emit in a single tree build to prevent runaway traversal on heavy DOMs (Canva, Figma)
+    private static let treeBuildNodeBudget = 3000
+    /// Max siblings to include per parent during tree build
+    private static let treeBuildSiblingCap = 80
+
+    func getElementTree(pid: pid_t, maxDepth: Int, windowId: Int? = nil) throws -> [String: Any] {
         let appElement = AXUIElementCreateApplication(pid)
-        return try buildTree(element: appElement, depth: 0, maxDepth: maxDepth)
+        var nodesEmitted = 0
+
+        // If windowId specified, scope to that window instead of full app tree
+        if let wid = windowId, wid > 0 {
+            if let windowsRef = getAttribute(appElement, kAXWindowsAttribute) as? [AXUIElement] {
+                // Match by CGWindowID via position/size comparison with CG window list
+                let cgWindows = CGWindowListCopyWindowInfo([.optionOnScreenOnly], kCGNullWindowID) as? [[String: Any]] ?? []
+                let appCGWindows = cgWindows.filter { ($0[kCGWindowOwnerPID as String] as? Int) == Int(pid) }
+
+                for win in windowsRef {
+                    // Get AX window position and size
+                    var axPos = CGPoint.zero
+                    var axSize = CGSize.zero
+                    if let posValue = getAttribute(win, kAXPositionAttribute) {
+                        AXValueGetValue(posValue as! AXValue, .cgPoint, &axPos)
+                    }
+                    if let sizeValue = getAttribute(win, kAXSizeAttribute) {
+                        AXValueGetValue(sizeValue as! AXValue, .cgSize, &axSize)
+                    }
+
+                    // Match against CG window with target windowId
+                    for cgWin in appCGWindows {
+                        guard let cgId = cgWin[kCGWindowNumber as String] as? Int, cgId == wid else { continue }
+                        if let bounds = cgWin[kCGWindowBounds as String] as? [String: Any],
+                           let cgX = bounds["X"] as? Double,
+                           let cgY = bounds["Y"] as? Double {
+                            // Match by position (within tolerance for rounding)
+                            if abs(Double(axPos.x) - cgX) < 2 && abs(Double(axPos.y) - cgY) < 2 {
+                                var tree = try buildTree(element: win, depth: 0, maxDepth: maxDepth, nodesEmitted: &nodesEmitted, isAppRoot: false)
+                                tree["_nodeCount"] = nodesEmitted
+                                return tree
+                            }
+                        }
+                    }
+                }
+            }
+            // Fallback: if window not found by ID, use app root
+        }
+
+        var tree = try buildTree(element: appElement, depth: 0, maxDepth: maxDepth, nodesEmitted: &nodesEmitted, isAppRoot: true)
+        tree["_nodeCount"] = nodesEmitted
+        return tree
     }
 
-    private func buildTree(element: AXUIElement, depth: Int, maxDepth: Int) throws -> [String: Any] {
+    private func buildTree(element: AXUIElement, depth: Int, maxDepth: Int, nodesEmitted: inout Int, isAppRoot: Bool = false) throws -> [String: Any] {
+        // Global node budget — stop adding nodes once exceeded
+        nodesEmitted += 1
+        if nodesEmitted > AccessibilityBridge.treeBuildNodeBudget {
+            return ["role": "BudgetExceeded", "_truncated": true]
+        }
+
         var node: [String: Any] = [:]
 
         node["role"] = getAttribute(element, kAXRoleAttribute) as? String ?? "Unknown"
@@ -52,13 +104,99 @@ class AccessibilityBridge {
             }
         }
 
+        // Children (if not at max depth and within global budget)
+        if depth < maxDepth && nodesEmitted < AccessibilityBridge.treeBuildNodeBudget {
+            if let children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement] {
+                var childNodes: [[String: Any]] = []
+                for (index, child) in children.enumerated() {
+                    if index >= AccessibilityBridge.treeBuildSiblingCap { break }
+                    if nodesEmitted >= AccessibilityBridge.treeBuildNodeBudget { break }
+                    // Skip self-referential AXApplication children at the app root level.
+                    // Some apps (Notes, Safari) list AXApplication elements as children
+                    // of themselves, causing infinite recursion. Only check at depth 0
+                    // (the app root) to avoid affecting legitimate nested elements.
+                    if isAppRoot {
+                        let childRole = getAttribute(child, kAXRoleAttribute) as? String ?? ""
+                        if childRole == "AXApplication" { continue }
+                    }
+                    if let childNode = try? buildTree(element: child, depth: depth + 1, maxDepth: maxDepth, nodesEmitted: &nodesEmitted) {
+                        childNodes.append(childNode)
+                    }
+                }
+                if !childNodes.isEmpty {
+                    node["children"] = childNodes
+                }
+            }
+        }
+
+        return node
+    }
+
+    // MARK: - Menu Bar Tree
+
+    func getMenuBarTree(pid: pid_t, maxDepth: Int) throws -> [String: Any] {
+        let appElement = AXUIElementCreateApplication(pid)
+        guard let menuBar = getAttribute(appElement, kAXMenuBarAttribute) as AnyObject? else {
+            throw BridgeError.notFound("Menu bar not found for pid \(pid)")
+        }
+        let menuBarElement = menuBar as! AXUIElement
+        return try buildMenuTree(element: menuBarElement, depth: 0, maxDepth: maxDepth, expandMenus: true)
+    }
+
+    private func buildMenuTree(element: AXUIElement, depth: Int, maxDepth: Int, expandMenus: Bool = false) throws -> [String: Any] {
+        var node: [String: Any] = [:]
+
+        let role = getAttribute(element, kAXRoleAttribute) as? String ?? "Unknown"
+        node["role"] = role
+        if let title = getAttribute(element, kAXTitleAttribute) as? String, !title.isEmpty {
+            node["title"] = title
+        }
+        if let desc = getAttribute(element, kAXDescriptionAttribute) as? String, !desc.isEmpty {
+            node["description"] = desc
+        }
+        if let enabled = getAttribute(element, kAXEnabledAttribute) as? Bool {
+            node["enabled"] = enabled
+        }
+
+        // Menu-specific attributes
+        if let cmdChar = getAttribute(element, "AXMenuItemCmdChar") as? String, !cmdChar.isEmpty {
+            node["AXMenuItemCmdChar"] = cmdChar
+        }
+        if let cmdMods = getAttribute(element, "AXMenuItemCmdModifiers") {
+            node["AXMenuItemCmdModifiers"] = cmdMods
+        }
+        if let markChar = getAttribute(element, "AXMenuItemMarkChar") as? String, !markChar.isEmpty {
+            node["AXMenuItemMarkChar"] = markChar
+        }
+
         // Children (if not at max depth)
         if depth < maxDepth {
-            if let children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement] {
+            var children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement]
+
+            // macOS AXMenuBarItem has a child AXMenu, but the AXMenu's children
+            // (actual AXMenuItems) are empty until the menu is opened via AXPress.
+            // Always press AXMenuBarItem to populate its submenu items.
+            let shouldExpand = expandMenus && role == "AXMenuBarItem"
+            if shouldExpand {
+                AXUIElementPerformAction(element, kAXPressAction as CFString)
+                // Poll for the AXMenu child's children to appear (max 200ms)
+                let deadline = Date().addingTimeInterval(0.2)
+                while Date() < deadline {
+                    // Re-read children — the AXMenu inside should now have items
+                    children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement]
+                    if let menu = children?.first {
+                        let menuChildren = getAttribute(menu, kAXChildrenAttribute) as? [AXUIElement]
+                        if menuChildren != nil && !menuChildren!.isEmpty { break }
+                    }
+                    Thread.sleep(forTimeInterval: 0.02)
+                }
+            }
+
+            if let children = children {
                 var childNodes: [[String: Any]] = []
                 for (index, child) in children.enumerated() {
                     if index > 100 { break } // Safety limit
-                    if let childNode = try? buildTree(element: child, depth: depth + 1, maxDepth: maxDepth) {
+                    if let childNode = try? buildMenuTree(element: child, depth: depth + 1, maxDepth: maxDepth, expandMenus: expandMenus) {
                         childNodes.append(childNode)
                     }
                 }
@@ -66,6 +204,12 @@ class AccessibilityBridge {
                     node["children"] = childNodes
                 }
             }
+
+            // Close the menu we opened
+            if shouldExpand {
+                AXUIElementPerformAction(element, kAXCancelAction as CFString)
+                Thread.sleep(forTimeInterval: 0.03)
+            }
         }
 
         return node
@@ -74,32 +218,58 @@ class AccessibilityBridge {
     // MARK: - Find Element
 
     func findElement(pid: pid_t, role: String?, title: String?, value: String?,
-                     identifier: String?, exact: Bool) throws -> [String: Any] {
+                     identifier: String?, exact: Bool, maxDepth: Int = 30) throws -> [String: Any] {
         let appElement = AXUIElementCreateApplication(pid)
+        var visited = 0
         guard let result = searchElement(
-            element: appElement, path: [], role: role, title: title,
-            value: value, identifier: identifier, exact: exact
+            element: appElement, path: [], depth: 0, maxDepth: maxDepth,
+            nodesVisited: &visited,
+            role: role, title: title,
+            value: value, identifier: identifier, exact: exact,
+            isAppRoot: true
         ) else {
             throw BridgeError.notFound("Element not found matching criteria")
         }
         return result
     }
 
-    private func searchElement(element: AXUIElement, path: [Int], role: String?,
+    /// Max total nodes to visit in a single search to prevent runaway traversal on heavy DOMs
+    private static let searchNodeBudget = 2000
+    /// Max siblings to check per parent during search
+    private static let searchSiblingCap = 100
+
+    private func searchElement(element: AXUIElement, path: [Int], depth: Int, maxDepth: Int,
+                               nodesVisited: inout Int,
+                               role: String?,
                                title: String?, value: String?, identifier: String?,
-                               exact: Bool) -> [String: Any]? {
+                               exact: Bool, isAppRoot: Bool = false) -> [String: Any]? {
+        // Bail if we've exceeded the node budget or depth limit
+        nodesVisited += 1
+        if nodesVisited > AccessibilityBridge.searchNodeBudget { return nil }
+        if depth > maxDepth { return nil }
+
         // Check if this element matches
         let elementRole = getAttribute(element, kAXRoleAttribute) as? String ?? ""
+        let elementSubrole = getAttribute(element, kAXSubroleAttribute) as? String ?? ""
         let elementTitle = getAttribute(element, kAXTitleAttribute) as? String ?? ""
         let elementValue = getAttribute(element, kAXValueAttribute).flatMap { "\($0)" } ?? ""
         let elementId = getAttribute(element, kAXIdentifierAttribute) as? String ?? ""
+        let elementDesc = getAttribute(element, kAXDescriptionAttribute) as? String ?? ""
 
         var matches = true
         if let role = role {
-            matches = matches && matchString(elementRole, role, exact: exact)
+            // Match role OR subrole — allows searching by "AXCloseButton" subrole
+            let roleMatch = matchString(elementRole, role, exact: exact)
+            let subroleMatch = !elementSubrole.isEmpty && matchString(elementSubrole, role, exact: exact)
+            matches = matches && (roleMatch || subroleMatch)
         }
         if let title = title {
-            matches = matches && matchString(elementTitle, title, exact: exact)
+            // Match title, description, OR subrole — many elements have no title but do
+            // have AXDescription or a meaningful subrole (e.g. AXCloseButton, AXMinimizeButton).
+            let titleMatch = matchString(elementTitle, title, exact: exact)
+            let descMatch = !elementDesc.isEmpty && matchString(elementDesc, title, exact: exact)
+            let subroleMatch = !elementSubrole.isEmpty && matchString(elementSubrole, title, exact: exact)
+            matches = matches && (titleMatch || descMatch || subroleMatch)
         }
         if let value = value {
             matches = matches && matchString(elementValue, value, exact: exact)
@@ -117,6 +287,8 @@ class AccessibilityBridge {
             ]
             if !elementValue.isEmpty { result["value"] = elementValue }
             if !elementId.isEmpty { result["identifier"] = elementId }
+            if !elementDesc.isEmpty { result["description"] = elementDesc }
+            if !elementSubrole.isEmpty { result["subrole"] = elementSubrole }
 
             // Get position for coordinates
             if let posValue = getAttribute(element, kAXPositionAttribute) {
@@ -137,16 +309,27 @@ class AccessibilityBridge {
             return result
         }
 
-        // Search children
-        if let children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement] {
-            for (index, child) in children.enumerated() {
-                var childPath = path
-                childPath.append(index)
-                if let found = searchElement(
-                    element: child, path: childPath, role: role, title: title,
-                    value: value, identifier: identifier, exact: exact
-                ) {
-                    return found
+        // Search children (with breadth + depth + budget limits)
+        if depth < maxDepth {
+            if let children = getAttribute(element, kAXChildrenAttribute) as? [AXUIElement] {
+                for (index, child) in children.enumerated() {
+                    if index >= AccessibilityBridge.searchSiblingCap { break }
+                    if nodesVisited > AccessibilityBridge.searchNodeBudget { break }
+                    // Skip self-referential AXApplication children at app root
+                    if isAppRoot {
+                        let childRole = getAttribute(child, kAXRoleAttribute) as? String ?? ""
+                        if childRole == "AXApplication" { continue }
+                    }
+                    var childPath = path
+                    childPath.append(index)
+                    if let found = searchElement(
+                        element: child, path: childPath, depth: depth + 1, maxDepth: maxDepth,
+                        nodesVisited: &nodesVisited,
+                        role: role, title: title,
+                        value: value, identifier: identifier, exact: exact
+                    ) {
+                        return found
+                    }
                 }
             }
         }
@@ -156,8 +339,8 @@ class AccessibilityBridge {
 
     // MARK: - Actions
 
-    func performAction(pid: pid_t, elementPath: [Int], action: String) throws {
-        let element = try resolveElement(pid: pid, path: elementPath)
+    func performAction(pid: pid_t, elementPath: [Int], action: String, expectedTitle: String? = nil) throws {
+        let element = try resolveElement(pid: pid, path: elementPath, expectedTitle: expectedTitle)
         let result = AXUIElementPerformAction(element, action as CFString)
         if result != .success {
             throw BridgeError.general("AX action '\(action)' failed with code \(result.rawValue)")
@@ -173,8 +356,14 @@ class AccessibilityBridge {
             if focusResult != .success {
                 throw BridgeError.general("Cannot focus element for value set, code \(focusResult.rawValue)")
             }
-            // Use CG to type the value
-            CoreGraphicsBridge().typeText(text: value)
+            // Use CG to type the value — PID-targeted to the correct process
+            CoreGraphicsBridge().typeText(text: value, targetPid: pid)
+        }
+        // Verify the value was actually set — some apps (Notes, etc.) silently ignore AXSetValue
+        usleep(50_000) // 50ms settle time
+        let readBack = getAttribute(element, kAXValueAttribute).flatMap { "\($0)" } ?? ""
+        if !readBack.contains(value.prefix(20)) && readBack != value {
+            throw BridgeError.general("Value set reported success but verification failed — element still shows \"\(String(readBack.prefix(60)))\" instead of \"\(String(value.prefix(60)))\". This element may not support programmatic value changes.")
         }
     }
 
@@ -205,18 +394,42 @@ class AccessibilityBridge {
             }
 
             var found = false
+            // Strip invisible Unicode direction marks (LTR U+200E, RTL U+200F, etc.)
+            // that apps like WhatsApp prepend to menu titles.
+            let cleanItem = menuItem.filter { !$0.unicodeScalars.allSatisfy { s in
+                (0x200B...0x200F).contains(s.value) || (0x2028...0x202F).contains(s.value) ||
+                (0xFEFF...0xFEFF).contains(s.value)
+            }}
             for child in children {
-                let title = getAttribute(child, kAXTitleAttribute) as? String ?? ""
-                if title == menuItem {
+                let rawTitle = getAttribute(child, kAXTitleAttribute) as? String ?? ""
+                let title = rawTitle.filter { !$0.unicodeScalars.allSatisfy { s in
+                    (0x200B...0x200F).contains(s.value) || (0x2028...0x202F).contains(s.value) ||
+                    (0xFEFF...0xFEFF).contains(s.value)
+                }}
+                if title == cleanItem || rawTitle == menuItem {
                     // Press this menu item to open it (for submenus) or activate it
                     AXUIElementPerformAction(child, kAXPressAction as CFString)
-                    // Small delay for menu to open
-                    Thread.sleep(forTimeInterval: 0.1)
 
-                    // If there are more items in the path, navigate into the submenu
-                    if let submenu = getAttribute(child, kAXChildrenAttribute) as? [AXUIElement],
-                       let firstChild = submenu.first {
-                        currentElement = firstChild
+                    // Poll for children to appear (max 500ms, 50ms intervals)
+                    // instead of a fixed 100ms sleep
+                    let pollDeadline = Date().addingTimeInterval(0.5)
+                    var submenuResolved = false
+                    while Date() < pollDeadline {
+                        if let submenu = getAttribute(child, kAXChildrenAttribute) as? [AXUIElement],
+                           let firstChild = submenu.first {
+                            currentElement = firstChild
+                            submenuResolved = true
+                            break
+                        }
+                        Thread.sleep(forTimeInterval: 0.05)
+                    }
+
+                    // If no submenu appeared after polling, still check once more
+                    if !submenuResolved {
+                        if let submenu = getAttribute(child, kAXChildrenAttribute) as? [AXUIElement],
+                           let firstChild = submenu.first {
+                            currentElement = firstChild
+                        }
                     }
 
                     found = true
@@ -232,7 +445,7 @@ class AccessibilityBridge {
 
     // MARK: - Helpers
 
-    private func resolveElement(pid: pid_t, path: [Int]) throws -> AXUIElement {
+    private func resolveElement(pid: pid_t, path: [Int], expectedTitle: String? = nil) throws -> AXUIElement {
         var current = AXUIElementCreateApplication(pid) as AXUIElement
         for index in path {
             guard let children = getAttribute(current, kAXChildrenAttribute) as? [AXUIElement] else {
@@ -243,10 +456,18 @@ class AccessibilityBridge {
             }
             current = children[index]
         }
+        // Verify the resolved element still matches the expected identity
+        if let expected = expectedTitle {
+            let actualTitle = getAttribute(current, kAXTitleAttribute) as? String ?? ""
+            let actualDesc = getAttribute(current, kAXDescriptionAttribute) as? String ?? ""
+            if actualTitle != expected && actualDesc != expected {
+                throw BridgeError.general("Element at path has changed: expected '\(expected)' but found '\(actualTitle.isEmpty ? actualDesc : actualTitle)'")
+            }
+        }
         return current
     }
 
-    private func getAttribute(_ element: AXUIElement, _ attribute: String) -> AnyObject? {
+    func getAttribute(_ element: AXUIElement, _ attribute: String) -> AnyObject? {
         var value: AnyObject?
         let result = AXUIElementCopyAttributeValue(element, attribute as CFString, &value)
         return result == .success ? value : nil

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

@@ -3,6 +3,12 @@ import Foundation
 
 class AppManagement {
 
+    private let ax: AccessibilityBridge
+
+    init(ax: AccessibilityBridge) {
+        self.ax = ax
+    }
+
     func launchApp(bundleId: String) throws -> [String: Any] {
         let workspace = NSWorkspace.shared
 
@@ -51,7 +57,98 @@ class AppManagement {
         guard let app = NSRunningApplication.runningApplications(withBundleIdentifier: bundleId).first else {
             throw BridgeError.notFound("No running application with bundle ID '\(bundleId)'")
         }
-        app.activate()
+
+        // Attempt 1: activateIgnoringOtherApps (strongest NSRunningApplication API)
+        app.activate(options: .activateIgnoringOtherApps)
+
+        // Poll up to 400ms for focus to switch
+        let pollEnd = Date().addingTimeInterval(0.4)
+        while Date() < pollEnd {
+            if NSWorkspace.shared.frontmostApplication?.bundleIdentifier == bundleId {
+                return
+            }
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+
+        // Attempt 2: AppleScript activation via bundle ID — goes through Apple Events,
+        // often succeeds when NSRunningApplication.activate fails (e.g. VS Code holding focus).
+        // Uses "id bundleId" form to avoid issues with Unicode chars in app names (WhatsApp).
+        let script = NSAppleScript(source: "tell application id \"\(bundleId)\" to activate")
+        script?.executeAndReturnError(nil)
+
+        // Poll up to 400ms more
+        let asEnd = Date().addingTimeInterval(0.4)
+        while Date() < asEnd {
+            if NSWorkspace.shared.frontmostApplication?.bundleIdentifier == bundleId {
+                return
+            }
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+
+        // Attempt 3: Raise the main window via AX API
+        let pid = app.processIdentifier
+        let appElement = AXUIElementCreateApplication(pid)
+        if let axWindows = self.ax.getAttribute(appElement, kAXWindowsAttribute) as? [AXUIElement],
+           let mainWindow = axWindows.first {
+            AXUIElementPerformAction(mainWindow, kAXRaiseAction as CFString)
+            // One more activate after raising — the combo often works when neither alone does
+            app.activate(options: .activateIgnoringOtherApps)
+        }
+
+        // Final poll — 300ms
+        let finalEnd = Date().addingTimeInterval(0.3)
+        while Date() < finalEnd {
+            if NSWorkspace.shared.frontmostApplication?.bundleIdentifier == bundleId {
+                return
+            }
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+
+        // Focus never changed — report honestly
+        let actual = NSWorkspace.shared.frontmostApplication?.bundleIdentifier ?? "unknown"
+        throw BridgeError.general("Focus failed: \(actual) is frontmost instead of \(bundleId)")
+    }
+
+    /// Focus a specific window by its CG windowId.
+    /// Activates the owning app and raises the target window via AX.
+    func focusWindow(windowId: Int) throws {
+        // Find the window's owner PID from CG
+        guard let windowList = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else {
+            throw BridgeError.notFound("Cannot enumerate windows")
+        }
+        guard let target = windowList.first(where: { ($0[kCGWindowNumber as String] as? Int) == windowId }),
+              let ownerPid = target[kCGWindowOwnerPID as String] as? Int else {
+            throw BridgeError.notFound("Window \(windowId) not found")
+        }
+
+        // Activate the owning app
+        if let app = NSRunningApplication(processIdentifier: pid_t(ownerPid)) {
+            app.activate(options: .activateIgnoringOtherApps)
+        }
+
+        // Raise the specific window via AX
+        let appElement = AXUIElementCreateApplication(pid_t(ownerPid))
+        guard let axWindows = self.ax.getAttribute(appElement, kAXWindowsAttribute) as? [AXUIElement] else {
+            return // App activated, but can't raise specific window
+        }
+
+        // Match AX window to CG window by position
+        var targetPos = CGPoint.zero
+        if let bounds = target[kCGWindowBounds as String] as? [String: Any] {
+            targetPos.x = CGFloat((bounds["X"] as? NSNumber)?.doubleValue ?? 0)
+            targetPos.y = CGFloat((bounds["Y"] as? NSNumber)?.doubleValue ?? 0)
+        }
+
+        for axWin in axWindows {
+            var axPos = CGPoint.zero
+            if let posValue = self.ax.getAttribute(axWin, kAXPositionAttribute) {
+                AXValueGetValue(posValue as! AXValue, .cgPoint, &axPos)
+            }
+            if abs(axPos.x - targetPos.x) < 2 && abs(axPos.y - targetPos.y) < 2 {
+                AXUIElementPerformAction(axWin, kAXRaiseAction as CFString)
+                return
+            }
+        }
     }
 
     func listRunningApps() -> [[String: Any]] {
@@ -69,7 +166,9 @@ class AppManagement {
     }
 
     func listWindows() -> [[String: Any]] {
-        guard let windowList = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else {
+        // Use .optionAll to include minimized/off-screen windows (e.g. Safari minimized to dock).
+        // layer == 0 filter below already excludes desktop elements and system overlays.
+        guard let windowList = CGWindowListCopyWindowInfo([.optionAll, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else {
             return []
         }
 
@@ -96,6 +195,9 @@ class AppManagement {
             let ownerName = window[kCGWindowOwnerName as String] as? String ?? ""
             let isOnScreen = window[kCGWindowIsOnscreen as String] as? Bool ?? true
 
+            // Skip zero-size windows (system placeholders, UI services)
+            if rect.width < 10 && rect.height < 10 { return nil }
+
             // Look up bundle ID from PID
             let bundleId = NSRunningApplication(processIdentifier: pid_t(ownerPid))?.bundleIdentifier ?? ""
 
@@ -116,6 +218,114 @@ class AppManagement {
         }
     }
 
+    /// List windows with AX-enriched metadata (focused, isMain) merged onto CG window data.
+    /// This is the preferred method for window resolution — it tells callers which window
+    /// is actually focused/main, avoiding wrong-window attachment.
+    ///
+    /// Matching uses a multi-signal join: position + title + size to avoid mis-annotation
+    /// when windows share geometry or move during polling.
+    func listWindowsWithAX() -> [[String: Any]] {
+        var cgWindows = listWindows()
+
+        // Group by PID so we only query AX for apps that have windows
+        var pidSet = Set<Int>()
+        for win in cgWindows {
+            if let pid = win["pid"] as? Int { pidSet.insert(pid) }
+        }
+
+        // For each PID, get AX windows and extract focused/isMain
+        struct AXWindowInfo {
+            let posX: Double
+            let posY: Double
+            let width: Double
+            let height: Double
+            let title: String
+            let focused: Bool
+            let isMain: Bool
+            let subrole: String
+        }
+
+        var axInfoByPid: [Int: [AXWindowInfo]] = [:]
+
+        for pid in pidSet {
+            let appElement = AXUIElementCreateApplication(pid_t(pid))
+            guard let axWindows = self.ax.getAttribute(appElement, kAXWindowsAttribute) as? [AXUIElement] else {
+                continue
+            }
+
+            var infos: [AXWindowInfo] = []
+            for axWin in axWindows {
+                var pos = CGPoint.zero
+                var size = CGSize.zero
+                if let posValue = self.ax.getAttribute(axWin, kAXPositionAttribute) {
+                    AXValueGetValue(posValue as! AXValue, .cgPoint, &pos)
+                }
+                if let sizeValue = self.ax.getAttribute(axWin, kAXSizeAttribute) {
+                    AXValueGetValue(sizeValue as! AXValue, .cgSize, &size)
+                }
+                let title = self.ax.getAttribute(axWin, kAXTitleAttribute) as? String ?? ""
+                let focused = self.ax.getAttribute(axWin, kAXFocusedAttribute) as? Bool ?? false
+                let isMain = self.ax.getAttribute(axWin, kAXMainAttribute) as? Bool ?? false
+                let subrole = self.ax.getAttribute(axWin, kAXSubroleAttribute) as? String ?? ""
+                infos.append(AXWindowInfo(
+                    posX: Double(pos.x), posY: Double(pos.y),
+                    width: Double(size.width), height: Double(size.height),
+                    title: title,
+                    focused: focused, isMain: isMain, subrole: subrole
+                ))
+            }
+            axInfoByPid[pid] = infos
+        }
+
+        // Merge AX info into CG windows using multi-signal matching
+        for i in 0..<cgWindows.count {
+            guard let pid = cgWindows[i]["pid"] as? Int,
+                  let bounds = cgWindows[i]["bounds"] as? [String: Double],
+                  let bx = bounds["x"], let by = bounds["y"],
+                  let bw = bounds["width"], let bh = bounds["height"],
+                  let infos = axInfoByPid[pid] else {
+                continue
+            }
+
+            let cgTitle = cgWindows[i]["title"] as? String ?? ""
+
+            // Score each AX window — higher score = better match
+            var bestScore = 0
+            var bestInfo: AXWindowInfo? = nil
+
+            for info in infos {
+                var score = 0
+                // Position match (within 2px) — required baseline
+                let posMatch = abs(info.posX - bx) < 2 && abs(info.posY - by) < 2
+                if !posMatch { continue }
+                score += 10
+
+                // Size match (within 5px)
+                if abs(info.width - bw) < 5 && abs(info.height - bh) < 5 {
+                    score += 5
+                }
+
+                // Title match — strongest signal for disambiguation
+                if !cgTitle.isEmpty && !info.title.isEmpty && cgTitle == info.title {
+                    score += 20
+                }
+
+                if score > bestScore {
+                    bestScore = score
+                    bestInfo = info
+                }
+            }
+
+            if let info = bestInfo {
+                cgWindows[i]["focused"] = info.focused
+                cgWindows[i]["isMain"] = info.isMain
+                cgWindows[i]["subrole"] = info.subrole
+            }
+        }
+
+        return cgWindows
+    }
+
     func frontmostApp() -> [String: Any] {
         guard let app = NSWorkspace.shared.frontmostApplication else {
             return ["error": "No frontmost application"]