Serialize overlapping accessibility captures

Guard collector captures so timer and app-activation snapshots cannot overlap, reduce repeated AX child sorting lookups, and add coverage for the capture gate.

Author: ComputelessComputer

Sources/OpenbirdKit/Capture/AccessibilitySnapshotter.swift

@@ -178,29 +178,30 @@ public struct AccessibilitySnapshotter: Sendable {
     }
 
     private func prioritizedChildren(for element: AXUIElement) -> [AXUIElement] {
-        copyChildren(for: element).sorted { lhs, rhs in
-            let lhsRole = stringAttribute(kAXRoleAttribute, on: lhs) ?? ""
-            let rhsRole = stringAttribute(kAXRoleAttribute, on: rhs) ?? ""
-            let lhsPriority = childPriority(for: lhsRole)
-            let rhsPriority = childPriority(for: rhsRole)
-            if lhsPriority != rhsPriority {
-                return lhsPriority > rhsPriority
+        copyChildren(for: element)
+            .map { child in
+                let role = stringAttribute(kAXRoleAttribute, on: child) ?? ""
+                return PrioritizedChild(
+                    element: child,
+                    role: role,
+                    priority: childPriority(for: role),
+                    area: elementArea(for: child),
+                    originX: elementOriginX(for: child)
+                )
             }
-
-            let lhsArea = elementArea(for: lhs)
-            let rhsArea = elementArea(for: rhs)
-            if lhsArea != rhsArea {
-                return lhsArea > rhsArea
-            }
-
-            let lhsX = elementOriginX(for: lhs)
-            let rhsX = elementOriginX(for: rhs)
-            if lhsX != rhsX {
-                return lhsX > rhsX
+            .sorted { lhs, rhs in
+                if lhs.priority != rhs.priority {
+                    return lhs.priority > rhs.priority
+                }
+                if lhs.area != rhs.area {
+                    return lhs.area > rhs.area
+                }
+                if lhs.originX != rhs.originX {
+                    return lhs.originX > rhs.originX
+                }
+                return lhs.role < rhs.role
             }
-
-            return lhsRole < rhsRole
-        }
+            .map(\.element)
     }
 
     private func stringAttribute(_ attribute: String, on element: AXUIElement) -> String? {
@@ -296,6 +297,14 @@ public struct AccessibilitySnapshotter: Sendable {
     }
 }
 
+private struct PrioritizedChild {
+    let element: AXUIElement
+    let role: String
+    let priority: Int
+    let area: CGFloat
+    let originX: CGFloat
+}
+
 private extension Array where Element: Hashable {
     func removingDuplicates() -> [Element] {
         var seen = Set<Element>()

Sources/OpenbirdKit/Capture/CollectorRuntime.swift

@@ -8,6 +8,7 @@ public final class CollectorRuntime: NSObject, @unchecked Sendable {
     private let snapshotter = AccessibilitySnapshotter()
     private let browserURLResolver = BrowserURLResolver()
     private let exclusionEngine = ExclusionEngine()
+    private let captureGate = CaptureGate()
     private let captureInterval: TimeInterval
     private let ownerID: String
     private let ownerName: String
@@ -73,6 +74,12 @@ public final class CollectorRuntime: NSObject, @unchecked Sendable {
     }
 
     public func captureNow() async {
+        await captureGate.runIfIdle {
+            await performCaptureNow()
+        }
+    }
+
+    private func performCaptureNow() async {
         do {
             let now = Date()
             let claimedLease = try await store.claimCollectorLease(
@@ -134,3 +141,14 @@ public final class CollectorRuntime: NSObject, @unchecked Sendable {
         }
     }
 }
+
+actor CaptureGate {
+    private var isRunning = false
+
+    func runIfIdle(_ operation: @Sendable () async -> Void) async {
+        guard isRunning == false else { return }
+        isRunning = true
+        defer { isRunning = false }
+        await operation()
+    }
+}

Tests/OpenbirdKitTests/CaptureGateTests.swift

@@ -0,0 +1,72 @@
+import Foundation
+import Testing
+@testable import OpenbirdKit
+
+struct CaptureGateTests {
+    @Test func dropsOverlappingWork() async throws {
+        let gate = CaptureGate()
+        let recorder = ConcurrencyRecorder()
+
+        let first = Task {
+            await gate.runIfIdle {
+                await recorder.started()
+                try? await Task.sleep(for: .milliseconds(100))
+                await recorder.finished()
+            }
+        }
+
+        try await Task.sleep(for: .milliseconds(20))
+
+        let second = Task {
+            await gate.runIfIdle {
+                await recorder.started()
+                await recorder.finished()
+            }
+        }
+
+        await first.value
+        await second.value
+
+        let snapshot = await recorder.snapshot()
+        #expect(snapshot.completed == 1)
+        #expect(snapshot.maxConcurrent == 1)
+    }
+
+    @Test func acceptsNewWorkAfterCompletion() async {
+        let gate = CaptureGate()
+        let recorder = ConcurrencyRecorder()
+
+        await gate.runIfIdle {
+            await recorder.started()
+            await recorder.finished()
+        }
+
+        await gate.runIfIdle {
+            await recorder.started()
+            await recorder.finished()
+        }
+
+        let snapshot = await recorder.snapshot()
+        #expect(snapshot.completed == 2)
+    }
+}
+
+private actor ConcurrencyRecorder {
+    private var concurrentCount = 0
+    private var maxConcurrentCount = 0
+    private var completedCount = 0
+
+    func started() {
+        concurrentCount += 1
+        maxConcurrentCount = max(maxConcurrentCount, concurrentCount)
+    }
+
+    func finished() {
+        concurrentCount -= 1
+        completedCount += 1
+    }
+
+    func snapshot() -> (completed: Int, maxConcurrent: Int) {
+        (completedCount, maxConcurrentCount)
+    }
+}