fix: Add dispatch context & refactor scroll posting

Introduce ScrollDispatchContext to capture event/proxy snapshots, enqueue async posts and guard frames by generation/TTL. Refactor ScrollPoster to use the dispatch context and an unfair lock (remove direct ref tuple), mark/skip synthetic smooth events, and centralize phase/posting logic into new post(...) APIs. Add diagnostics and debug counters, improve lifecycle handling (advance/invalidate generation on stop/reset) and ensure tracking end is posted correctly. Also: ignore /build in .gitignore, add synthetic event marker helpers in ScrollUtils, import os where needed, and call ScrollPoster.stop(.TrackingEnd) on Interceptor.restart.

- #868
- #826
- #699
- #687
- #665
- #510
- #512
- #499
- #368
- #597
- #859

Author: Caldis

.gitignore

@@ -17,3 +17,4 @@ sparkle_private_key.txt
 
 # build
 build/*.zip
+/build

Mos/ScrollCore/ScrollCore.swift

@@ -48,6 +48,22 @@ class ScrollCore {
 
     // MARK: - 滚动事件处理
     let scrollEventCallBack: CGEventTapCallBack = { (proxy, type, event, refcon) in
+        _ = refcon
+        // Tap 被系统禁用或重启边界时，强制清理 poster 上下文并失效历史异步帧
+        if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
+            ScrollPoster.shared.stop(.TrackingEnd)
+            return Unmanaged.passUnretained(event)
+        }
+        if type != .scrollWheel {
+            return Unmanaged.passUnretained(event)
+        }
+        // 跳过 Mos 自己合成的平滑事件，避免重复进入平滑管线
+        if ScrollUtils.shared.isSyntheticSmoothEvent(event) {
+#if DEBUG
+            ScrollPoster.shared.recordSkippedSyntheticEvent()
+#endif
+            return Unmanaged.passUnretained(event)
+        }
         // 不处理触控板
         // 无法区分黑苹果, 因为黑苹果的触控板驱动直接模拟鼠标输入
         // 无法区分 Magic Mouse, 因为其滚动特征与内置的 Trackpad 一致

Mos/ScrollCore/ScrollDispatchContext.swift

@@ -0,0 +1,145 @@
+//
+//  ScrollDispatchContext.swift
+//  Mos
+//
+//  Created by Codex on 2026/3/5.
+//
+
+import Cocoa
+import os
+
+final class ScrollDispatchContext {
+
+    static let shared = ScrollDispatchContext()
+
+    struct PostingSnapshot {
+        let event: CGEvent
+        let proxy: CGEventTapProxy
+        let generation: UInt64
+        let capturedAt: CFTimeInterval
+    }
+
+    private struct SnapshotState {
+        var eventTemplate: CGEvent?
+        var proxy: CGEventTapProxy?
+        var generation: UInt64 = 0
+        var updatedAt: CFTimeInterval = 0.0
+    }
+
+    private var state = SnapshotState()
+    private var lock = os_unfair_lock_s()
+    private let postQueue = DispatchQueue(label: "me.caldis.mos.scrollposter.proxy-post", qos: .userInteractive)
+    // TTL 仅作为 enqueue 投递时的兜底安全网, 不用于快照创建门控
+    // 需覆盖最长惯性减速阶段 (通常 1-3s, 极端 ~5s)
+    private let proxyTTL: CFTimeInterval = 5.0
+
+#if DEBUG
+    private var postedFrames: UInt64 = 0
+    private var droppedFramesByGeneration: UInt64 = 0
+    private var droppedFramesByTTL: UInt64 = 0
+    private var skippedSyntheticEvents: UInt64 = 0
+    private var updateSnapshotFailures: UInt64 = 0
+#endif
+
+    private init() {}
+
+    @discardableResult
+    func capture(event: CGEvent, proxy: CGEventTapProxy) -> Bool {
+        guard let template = event.copy() else {
+#if DEBUG
+            os_unfair_lock_lock(&lock)
+            updateSnapshotFailures &+= 1
+            os_unfair_lock_unlock(&lock)
+#endif
+            return false
+        }
+        os_unfair_lock_lock(&lock)
+        state.eventTemplate = template
+        state.proxy = proxy
+        state.updatedAt = CFAbsoluteTimeGetCurrent()
+        os_unfair_lock_unlock(&lock)
+        return true
+    }
+
+    func advanceGeneration() {
+        os_unfair_lock_lock(&lock)
+        state.generation &+= 1
+        os_unfair_lock_unlock(&lock)
+    }
+
+    func clearContext() {
+        os_unfair_lock_lock(&lock)
+        state.eventTemplate = nil
+        state.proxy = nil
+        state.updatedAt = 0.0
+        os_unfair_lock_unlock(&lock)
+    }
+
+    func invalidateAll() {
+        os_unfair_lock_lock(&lock)
+        state.generation &+= 1
+        state.eventTemplate = nil
+        state.proxy = nil
+        state.updatedAt = 0.0
+        os_unfair_lock_unlock(&lock)
+    }
+
+    func preparePostingSnapshot() -> PostingSnapshot? {
+        os_unfair_lock_lock(&lock)
+        guard let proxy = state.proxy,
+              let eventClone = state.eventTemplate?.copy() else {
+            os_unfair_lock_unlock(&lock)
+            return nil
+        }
+        let snapshot = PostingSnapshot(event: eventClone, proxy: proxy, generation: state.generation, capturedAt: state.updatedAt)
+        os_unfair_lock_unlock(&lock)
+        return snapshot
+    }
+
+    func enqueue(_ snapshot: PostingSnapshot) {
+        postQueue.async { [self] in
+            os_unfair_lock_lock(&self.lock)
+            let now = CFAbsoluteTimeGetCurrent()
+            let validGeneration = snapshot.generation == self.state.generation
+            let validTTL = now - snapshot.capturedAt <= self.proxyTTL
+            if !validGeneration {
+#if DEBUG
+                self.droppedFramesByGeneration &+= 1
+#endif
+            } else if !validTTL {
+#if DEBUG
+                self.droppedFramesByTTL &+= 1
+#endif
+            }
+            os_unfair_lock_unlock(&self.lock)
+            guard validGeneration && validTTL else { return }
+            snapshot.event.tapPostEvent(snapshot.proxy)
+#if DEBUG
+            os_unfair_lock_lock(&self.lock)
+            self.postedFrames &+= 1
+            os_unfair_lock_unlock(&self.lock)
+#endif
+        }
+    }
+
+#if DEBUG
+    func recordSkippedSyntheticEvent() {
+        os_unfair_lock_lock(&lock)
+        skippedSyntheticEvents &+= 1
+        os_unfair_lock_unlock(&lock)
+    }
+
+    func diagnosticsSnapshot() -> (postedFrames: UInt64, droppedFramesByGeneration: UInt64, droppedFramesByTTL: UInt64, skippedSyntheticEvents: UInt64, updateSnapshotFailures: UInt64) {
+        os_unfair_lock_lock(&lock)
+        let snapshot = (
+            postedFrames: postedFrames,
+            droppedFramesByGeneration: droppedFramesByGeneration,
+            droppedFramesByTTL: droppedFramesByTTL,
+            skippedSyntheticEvents: skippedSyntheticEvents,
+            updateSnapshotFailures: updateSnapshotFailures
+        )
+        os_unfair_lock_unlock(&lock)
+        return snapshot
+    }
+#endif
+}