feat(macos): add software scroll inversion fallback

[zinego]

Summary

Add a per-device macOS software fallback for scroll inversion when a persistent pointer device, such as the Signature M650, does not expose native HID++ 0x2121 inversion support.

The native capability remains authoritative. Devices that support native inversion continue using HID++, while unsupported devices can invert vertical wheel events through the existing macOS event tap without changing trackpad scrolling.

Changes

• hook

  • Add a macOS scroll inversion disposition.
  • Replace captured scroll events with copied events whose vertical line, fixed, and point deltas are inverted.
  • Preserve horizontal deltas and event metadata.
  • Mark replacements as synthetic to prevent event-tap re-entry.

• agent

  • Publish software inversion settings only for persistent pointer devices without native inversion support.
  • Match event sources conservatively by vendor/product ID, with normalized product-name fallback when no product ID is available.
  • Reject ambiguous identities and unsafe shared-receiver attribution.
  • Republish the lookup after inventory, capability, or configuration changes.

• gui

  • Enable scroll inversion for persistent macOS pointer devices that lack native HID++ inversion.
  • Keep the native-support status separate from software fallback availability.
  • Explain that the fallback affects the mouse wheel while leaving trackpad direction unchanged.
  • Add the new explanatory string to all locale files.

• docs

  • Document the fallback design, failure behavior, automated coverage, and hardware acceptance criteria.

Testing

Passed locally:

• cargo fmt --all -- --check
• cargo clippy -p openlogi-hook -p openlogi-agent-core -p openlogi-agent --all-targets -- -D warnings
• cargo test -p openlogi-hook -p openlogi-agent-core -p openlogi-agent
  • 89 unit, wire-format, and documentation tests passed.

Attempted locally but blocked by the host toolchain:

• cargo clippy --workspace --all-targets -- -D warnings
• cargo test --workspace

Both full-workspace commands reached gpui_macos and then stopped because this Mac has Command Line Tools but not Xcode's optional metal compiler. CI remains the authoritative full-workspace and cross-platform check.

Hardware validation:

• Signature M650 L connected directly over Bluetooth on macOS.
• Enabling the fallback was observed to reverse the physical mouse wheel direction.
• Complete acceptance for trackpad isolation, horizontal scrolling, side-button behavior, repeated toggles, and the final GUI availability state has not yet been recorded.

Screenshot: pending final GUI capture.

Fixes: N/A — no matching issue is currently filed.

[greptile-apps]

Greptile Summary

The PR adds a per-device macOS software fallback for mice that lack native HID++ scroll inversion while preserving the native path and leaving unmatched or ambiguous input unchanged.

• Adds macOS scroll-event replacement with vertical delta inversion and synthetic-event tagging.
• Publishes software inversion settings from inventory and configuration using conservative device identity matching.
• Exposes the fallback for persistent macOS pointer devices and adds localized explanatory text.
• Adds focused tests and design/acceptance documentation.

Confidence Score: 5/5

The PR appears safe to merge with no concrete blocking or independently actionable non-blocking issues identified.

The fallback fails open for unknown or ambiguous identities, excludes native-capable devices from software inversion, preserves trackpad and horizontal scrolling paths, and safely replaces matched macOS scroll events.

Important Files Changed

Filename	Overview
crates/openlogi-hook/src/macos.rs	Adds a copy-and-replace scroll transformation that preserves metadata and horizontal deltas while preventing synthetic-event re-entry.
crates/openlogi-agent-core/src/hook_runtime.rs	Adds conservative per-device identity matching and the runtime policy for applying software inversion only to eligible mouse-wheel events.
crates/openlogi-agent-core/src/orchestrator.rs	Publishes software inversion identities for non-native pointer devices and suppresses unsafe shared-receiver attribution.
crates/openlogi-gui/src/state.rs	Enables inversion for persistent macOS pointer devices while retaining separate native-capability reporting.
crates/openlogi-gui/src/app/detail.rs	Selects distinct explanatory text for native inversion, software fallback, and unsupported devices.

Sequence Diagram

sequenceDiagram
    participant Mouse as Physical mouse
    participant Hook as macOS event tap
    participant Map as Software inversion lookup
    participant OS as macOS application
    Mouse->>Hook: Scroll event + sender identity
    Hook->>Map: Match vendor/product or safe name
    alt Matched fallback with inversion enabled
        Map-->>Hook: Invert
        Hook->>Hook: Copy event, negate vertical deltas, mark synthetic
        Hook->>OS: Replacement scroll event
    else Native, disabled, unknown, ambiguous, or trackpad
        Map-->>Hook: Pass through
        Hook->>OS: Original scroll event
    end

Loading

_{Reviews (1): Last reviewed commit: "docs(scroll): document macos inversion f..." | Re-trigger Greptile}

[davidbudnick]

@zinego Can you please rebase and get the tests working on the PR?