Assemble complete lightweight feature candidate

.github/workflows/test.yml

@@ -10,6 +10,8 @@ jobs:
     runs-on: macos-14
     steps:
       - uses: actions/checkout@v4
+      - name: Verify generated config defaults
+        run: swift scripts/generate-config-defaults.swift --check
       - name: Run unit tests
         run: swift test
       - name: Build release executable
@@ -29,3 +31,31 @@ jobs:
             echo "sharing archive contains development tests or performance probes" >&2
             exit 1
           fi
+          unzip -Z1 "$archive" | grep -q '/config/defaults.json$'
+          if unzip -Z1 "$archive" | grep -qi 'default-config'; then
+            echo "sharing archive contains a retired config name" >&2
+            exit 1
+          fi
+      - name: Verify app config resource
+        run: |
+          bash scripts/build-app.sh
+          test -f dist/mx3-lite.app/Contents/Resources/defaults.json
+          test ! -e dist/mx3-lite.app/Contents/Resources/default-config.json
+
+  release-archives:
+    runs-on: macos-14
+    strategy:
+      matrix:
+        arch: [arm64, x86_64]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check release scripts
+        run: bash -n scripts/build-release-app.sh scripts/package-release.sh scripts/verify-release.sh
+      - name: Build and verify ${{ matrix.arch }} validation archive
+        run: bash scripts/package-release.sh --arch "${{ matrix.arch }}"
+      - name: Upload validation archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: mx3-lite-${{ matrix.arch }}-validation
+          path: dist/releases/v*/
+          if-no-files-found: error

Sources/MX3AppSupport/AppSettings.swift

@@ -93,24 +93,28 @@ public struct AppSettings: Codable, Equatable, Sendable {
     public var scrollTransformMode: AppScrollTransformMode
 
     public static let `default` = AppSettings(
-        threshold: 220,
-        buttons: AppButtonSettings(gesture: 5, back: 3, forward: 4),
+        threshold: ConfigDefaults.threshold,
+        buttons: AppButtonSettings(
+            gesture: ConfigDefaults.gestureButton,
+            back: ConfigDefaults.backButton,
+            forward: ConfigDefaults.forwardButton
+        ),
         downAction: .ctrlDown,
-        invertY: false,
-        invertDesktopGestureDirection: true,
+        invertY: ConfigDefaults.invertY,
+        invertDesktopGestureDirection: ConfigDefaults.invertDesktopGestureDirection,
         actionBackend: .systemEvents,
-        invertVerticalScroll: true,
-        invertHorizontalScroll: false,
-        scrollMultiplier: 1,
-        smoothScroll: true,
+        invertVerticalScroll: ConfigDefaults.invertVerticalScroll,
+        invertHorizontalScroll: ConfigDefaults.invertHorizontalScroll,
+        scrollMultiplier: ConfigDefaults.scrollMultiplier,
+        smoothScroll: ConfigDefaults.smoothScroll,
         smoothScrollMode: .ema,
-        smoothScrollFactor: 0.35,
-        scrollDeadzone: 0,
-        maxScrollStep: 8,
-        scrollAcceleration: 1,
-        freeSpinDamping: 0.75,
-        ratchetStepMultiplier: 1,
-        allowGlobalScrollTransform: false,
+        smoothScrollFactor: ConfigDefaults.smoothScrollFactor,
+        scrollDeadzone: ConfigDefaults.scrollDeadzone,
+        maxScrollStep: ConfigDefaults.maxScrollStep,
+        scrollAcceleration: ConfigDefaults.scrollAcceleration,
+        freeSpinDamping: ConfigDefaults.freeSpinDamping,
+        ratchetStepMultiplier: ConfigDefaults.ratchetStepMultiplier,
+        allowGlobalScrollTransform: ConfigDefaults.allowGlobalScrollTransform,
         scrollTransformMode: .mxMasterOnly
     )
 

Sources/MX3AppSupport/ConfigDefaults.generated.swift

@@ -0,0 +1,23 @@
+enum ConfigDefaults {
+    static let threshold = 220.0
+    static let gestureButton = 5
+    static let backButton = 3
+    static let forwardButton = 4
+    static let downAction = AppDownAction.ctrlDown
+    static let invertY = false
+    static let invertDesktopGestureDirection = true
+    static let actionBackend = AppActionBackend.systemEvents
+    static let invertVerticalScroll = true
+    static let invertHorizontalScroll = false
+    static let scrollMultiplier = 1.0
+    static let smoothScroll = true
+    static let smoothScrollMode = AppSmoothScrollMode.ema
+    static let smoothScrollFactor = 0.35
+    static let scrollDeadzone = 0.0
+    static let maxScrollStep = 8.0
+    static let scrollAcceleration = 1.0
+    static let freeSpinDamping = 0.75
+    static let ratchetStepMultiplier = 1.0
+    static let allowGlobalScrollTransform = false
+    static let scrollTransformMode = AppScrollTransformMode.mxMasterOnly
+}

Sources/MX3Lite/CLI.swift

@@ -314,7 +314,7 @@ struct CLI {
         mxMasterRegistry.start()
 
         let debugger = ScrollDebugger(config: loadedConfig.config, logger: logger, mxMasterRegistry: mxMasterRegistry)
-        let eventTap = try MouseEventTap(mode: .debugScroll(debugger), logger: logger)
+        let eventTap = try MouseEventTap(mode: .debugScroll(debugger))
 
         let signalController = SignalController()
         signalController.start {
@@ -352,10 +352,9 @@ struct CLI {
         let mapper = GestureMapper(config: config, logger: logger, liveEventDebug: debug, mxMasterRegistry: mxMasterRegistry)
         let eventTap = try MouseEventTap(
             mode: .map(mapper),
-            eventTypes: debug ? nil : mapper.primaryEventTypes,
-            logger: logger
+            eventTypes: debug ? nil : mapper.primaryEventTypes
         )
-        let movementEventTap = try makeMovementEventTap(for: mapper, shouldCreate: !debug, logger: logger)
+        let movementEventTap = try makeMovementEventTap(for: mapper, shouldCreate: !debug)
 
         let signalController = SignalController()
         signalController.start {
@@ -399,8 +398,8 @@ struct CLI {
         }
 
         let mapper = GestureMapper(config: config, logger: logger, liveEventDebug: false, mxMasterRegistry: mxMasterRegistry)
-        let eventTap = try MouseEventTap(mode: .map(mapper), eventTypes: mapper.primaryEventTypes, logger: logger)
-        let movementEventTap = try makeMovementEventTap(for: mapper, shouldCreate: true, logger: logger)
+        let eventTap = try MouseEventTap(mode: .map(mapper), eventTypes: mapper.primaryEventTypes)
+        let movementEventTap = try makeMovementEventTap(for: mapper, shouldCreate: true)
 
         let signalController = SignalController()
         signalController.start {
@@ -419,17 +418,15 @@ struct CLI {
 
     private func makeMovementEventTap(
         for mapper: GestureMapper,
-        shouldCreate: Bool,
-        logger: DebugLogger
+        shouldCreate: Bool
     ) throws -> MouseEventTap? {
         guard shouldCreate, !mapper.movementEventTypes.isEmpty else {
             return nil
         }
 
         let movementEventTap = try MouseEventTap(
             mode: .map(mapper),
-            eventTypes: mapper.movementEventTypes,
-            logger: logger
+            eventTypes: mapper.movementEventTypes
         )
         mapper.onGestureActivityChanged = { [weak movementEventTap] isActive in
             movementEventTap?.setEnabled(isActive)

Sources/MX3Lite/Config.swift

@@ -390,24 +390,28 @@ struct AppConfig: Codable {
     var scrollTransformMode: ScrollTransformMode
 
     static let `default` = AppConfig(
-        threshold: 220,
-        buttons: ButtonConfig(gesture: 5, back: 3, forward: 4),
+        threshold: ConfigDefaults.threshold,
+        buttons: ButtonConfig(
+            gesture: ConfigDefaults.gestureButton,
+            back: ConfigDefaults.backButton,
+            forward: ConfigDefaults.forwardButton
+        ),
         downAction: .ctrlDown,
-        invertY: false,
-        invertDesktopGestureDirection: true,
+        invertY: ConfigDefaults.invertY,
+        invertDesktopGestureDirection: ConfigDefaults.invertDesktopGestureDirection,
         actionBackend: .systemEvents,
-        invertVerticalScroll: true,
-        invertHorizontalScroll: false,
-        scrollMultiplier: 1,
-        smoothScroll: true,
+        invertVerticalScroll: ConfigDefaults.invertVerticalScroll,
+        invertHorizontalScroll: ConfigDefaults.invertHorizontalScroll,
+        scrollMultiplier: ConfigDefaults.scrollMultiplier,
+        smoothScroll: ConfigDefaults.smoothScroll,
         smoothScrollMode: .ema,
-        smoothScrollFactor: 0.35,
-        scrollDeadzone: 0,
-        maxScrollStep: 8,
-        scrollAcceleration: 1,
-        freeSpinDamping: 0.75,
-        ratchetStepMultiplier: 1,
-        allowGlobalScrollTransform: false,
+        smoothScrollFactor: ConfigDefaults.smoothScrollFactor,
+        scrollDeadzone: ConfigDefaults.scrollDeadzone,
+        maxScrollStep: ConfigDefaults.maxScrollStep,
+        scrollAcceleration: ConfigDefaults.scrollAcceleration,
+        freeSpinDamping: ConfigDefaults.freeSpinDamping,
+        ratchetStepMultiplier: ConfigDefaults.ratchetStepMultiplier,
+        allowGlobalScrollTransform: ConfigDefaults.allowGlobalScrollTransform,
         scrollTransformMode: .mxMasterOnly
     )
 

Sources/MX3Lite/ConfigDefaults.generated.swift

@@ -0,0 +1,23 @@
+enum ConfigDefaults {
+    static let threshold = 220.0
+    static let gestureButton = 5
+    static let backButton = 3
+    static let forwardButton = 4
+    static let downAction = DownAction.ctrlDown
+    static let invertY = false
+    static let invertDesktopGestureDirection = true
+    static let actionBackend = ActionBackend.systemEvents
+    static let invertVerticalScroll = true
+    static let invertHorizontalScroll = false
+    static let scrollMultiplier = 1.0
+    static let smoothScroll = true
+    static let smoothScrollMode = SmoothScrollMode.ema
+    static let smoothScrollFactor = 0.35
+    static let scrollDeadzone = 0.0
+    static let maxScrollStep = 8.0
+    static let scrollAcceleration = 1.0
+    static let freeSpinDamping = 0.75
+    static let ratchetStepMultiplier = 1.0
+    static let allowGlobalScrollTransform = false
+    static let scrollTransformMode = ScrollTransformMode.mxMasterOnly
+}

Sources/MX3Lite/GestureMapper.swift

@@ -76,12 +76,30 @@ final class GestureMapper {
         return suppressed
     }
 
+    func cancelGestureForEventTapInterruption() {
+        guard gestureState.isActive else {
+            return
+        }
+
+        gestureState.end()
+        onGestureActivityChanged?(false)
+    }
+
+#if DEBUG
+    var gestureStateForTesting: GestureState {
+        gestureState
+    }
+#endif
+
     private func handleButtonDown(event: CGEvent) -> Bool {
         let button = Int(event.getIntegerValueField(.mouseEventButtonNumber))
+        if gestureState.isActive {
+            _ = cancelGestureIfStale(event: event)
+        }
 
         switch GestureState.buttonDownDecision(button: button, buttons: config.buttons, gestureActive: gestureState.isActive) {
         case .beginGesture:
-            gestureState.begin(at: event.location)
+            gestureState.begin(at: event.location, timestamp: event.timestamp)
             onGestureActivityChanged?(true)
             logger.log("gesture start button=\(button) startLocation=\(event.location.compactDescription)")
             return true
@@ -99,11 +117,14 @@ final class GestureMapper {
 
     private func handleButtonUp(event: CGEvent) -> Bool {
         let button = Int(event.getIntegerValueField(.mouseEventButtonNumber))
+        let staleGestureCancelled = gestureState.isActive && cancelGestureIfStale(event: event)
 
         if matches(button, config.buttons.gesture) {
-            logger.log("gesture end button=\(button) final accumulatedDx=\(format(gestureState.accumulatedDx)) accumulatedDy=\(format(gestureState.accumulatedDy)) accumulatedScrollX=\(format(gestureState.accumulatedScrollX)) accumulatedScrollY=\(format(gestureState.accumulatedScrollY))")
-            gestureState.end()
-            onGestureActivityChanged?(false)
+            if !staleGestureCancelled {
+                logger.log("gesture end button=\(button) final accumulatedDx=\(format(gestureState.accumulatedDx)) accumulatedDy=\(format(gestureState.accumulatedDy)) accumulatedScrollX=\(format(gestureState.accumulatedScrollX)) accumulatedScrollY=\(format(gestureState.accumulatedScrollY))")
+                gestureState.end()
+                onGestureActivityChanged?(false)
+            }
             return true
         }
 
@@ -118,6 +139,9 @@ final class GestureMapper {
         guard gestureState.isActive else {
             return false
         }
+        guard !cancelGestureIfStale(event: event) else {
+            return false
+        }
 
         let currentLocation = event.location
         let previousLocation = gestureState.lastLocation ?? currentLocation
@@ -135,14 +159,11 @@ final class GestureMapper {
 
     private func handleScroll(event: CGEvent) -> Bool {
         guard gestureState.isActive else {
-            if let result = scrollTransformer.apply(
-                to: event,
-                config: config,
-                mxMasterRegistry: mxMasterRegistry,
-                captureDebug: liveEventDebug
-            ) {
-                logger.log(result.debugDescription(prefix: "scroll transform"))
-            }
+            transformInactiveScroll(event: event)
+            return false
+        }
+        guard !cancelGestureIfStale(event: event) else {
+            transformInactiveScroll(event: event)
             return false
         }
 
@@ -158,6 +179,28 @@ final class GestureMapper {
         return false
     }
 
+    private func cancelGestureIfStale(event: CGEvent) -> Bool {
+        guard gestureState.isStale(at: event.timestamp) else {
+            return false
+        }
+
+        logger.log("stale gesture cancelled")
+        gestureState.end()
+        onGestureActivityChanged?(false)
+        return true
+    }
+
+    private func transformInactiveScroll(event: CGEvent) {
+        if let result = scrollTransformer.apply(
+            to: event,
+            config: config,
+            mxMasterRegistry: mxMasterRegistry,
+            captureDebug: liveEventDebug
+        ) {
+            logger.log(result.debugDescription(prefix: "scroll transform"))
+        }
+    }
+
     private func evaluateGesture(source: String) {
         guard let action = gestureState.consumeAction(
             threshold: config.threshold,

Sources/MX3Lite/GestureState.swift

@@ -13,9 +13,12 @@ enum ButtonDownDecision: Equatable {
 }
 
 struct GestureState {
+    static let staleHoldTimeout: CGEventTimestamp = 30_000_000_000
+
     private(set) var isActive = false
     private(set) var isConsumed = false
     private(set) var lastLocation: CGPoint?
+    private(set) var startedAt: CGEventTimestamp?
     private(set) var accumulatedDx = 0.0
     private(set) var accumulatedDy = 0.0
     private(set) var accumulatedScrollX = 0.0
@@ -34,10 +37,11 @@ struct GestureState {
         return .passThrough
     }
 
-    mutating func begin(at location: CGPoint) {
+    mutating func begin(at location: CGPoint, timestamp: CGEventTimestamp = 0) {
         isActive = true
         isConsumed = false
         lastLocation = location
+        startedAt = timestamp
         accumulatedDx = 0
         accumulatedDy = 0
         accumulatedScrollX = 0
@@ -48,12 +52,20 @@ struct GestureState {
         isActive = false
         isConsumed = false
         lastLocation = nil
+        startedAt = nil
         accumulatedDx = 0
         accumulatedDy = 0
         accumulatedScrollX = 0
         accumulatedScrollY = 0
     }
 
+    func isStale(at timestamp: CGEventTimestamp, timeout: CGEventTimestamp = staleHoldTimeout) -> Bool {
+        guard isActive, let startedAt, timestamp >= startedAt else {
+            return false
+        }
+        return timestamp - startedAt >= timeout
+    }
+
     mutating func addMovement(to location: CGPoint, invertY: Bool) {
         guard isActive else {
             return