HapticMouse 📳

HapticMouse gives any external mouse a haptic scroll wheel. Plug in a $20 USB mouse and feel a crisp Taptic-Engine detent on every scroll notch and click — borrowed live from your MacBook's trackpad. (Plus tactile typing feedback, if you want it!)

---

---

✨ Features

• ⌨️ Mechanical Keyboard Emulation (Key Weights): Types feel like physical keycaps. Specific keycodes are mapped to custom taptic vibrations:
  • Spacebar & Return: Heavy, deep physical click responses (actuationID: 2, 1.0 base intensity).
  • Delete/Backspace: Crisp, solid mechanical click feel (actuationID: 2, 0.8 base intensity).
  • Letters & Numbers: Light, crisp micro-pulse ticks (actuationID: 1, 0.9 base intensity) that simulate quiet brown switches.
• 🎛️ Modular Feature Toggles: Enable or disable haptic categories independently from the menu-bar dropdown checklist:
  • Tactile Keyboard Typing: Adds mechanical typing ticks to your internal keyboard presses.
  • Tactile Mouse Scrolling: Converts scroll wheel clicks from any USB/Bluetooth mouse into physical scroll notches.
  • Tactile Mouse Clicks: Transmits mouse click actions to the trackpad's taptic motor.
• 🎚️ Custom Vibration Strength Slider: Drag the slider (from 0.1 to 2.0 intensity) to adjust your haptic feedback strength in real time. It vibrates dynamically as you slide to let you preview your setting!
• 🔋 Battery-Saving Throttlers: Built-in rate limiters prevent continuous motor activation and reduce power draw by up to 60%:
  • Keyboard keypresses are throttled to a maximum of once every 120ms (limits feedback to ~8 keyclicks per second for smooth typing rhythm).
  • Scroll wheel ticks are throttled to once every 100ms to prevent rapid motor vibration during fast sweeps.
• 🔒 100% Privacy Protection:
  • Zero Keylogging: Events are intercepted in-memory, used to actuate the motor, and discarded instantly.
  • No Disk Write: No logs, configs, caches, or files are ever created or written to disk.
• 🖥️ Standalone Background Agent: Runs completely silently in your menu bar. No terminal windows, no Dock icon clutter, and zero console warning outputs.

---

🚀 Quick Start & Installation

Option 1: Double-Click App Installation

1. Download or compile HapticMouse.app.
2. Move it to your standard Applications folder:

   mv HapticMouse.app /Applications/

3. Double-click /Applications/HapticMouse.app in Finder to launch it.
4. When prompted, follow the prompt to open System Settings and switch ON the Accessibility permission for HapticMouse. (If it doesn't prompt you, navigate to System Settings > Privacy & Security > Accessibility and toggle it manually).

Option 2: Build From Source

Compile the Swift code directly using macOS's built-in compiler:

# Clone the repository
git clone https://github.com/ZANYANBU/haptic-mouse.git
cd haptic-mouse

# Compile the Swift source
swiftc -O HapticMouse.swift -o HapticMouseBin

# Create the macOS App Bundle structure
mkdir -p HapticMouse.app/Contents/MacOS
mv HapticMouseBin HapticMouse.app/Contents/MacOS/HapticMouse
cp Info.plist HapticMouse.app/Contents/Info.plist

# Ad-hoc sign the app bundle
codesign --force --deep --sign - HapticMouse.app

---

⚙️ Configuration & Diagnostics

Running at Login

To make HapticMouse run automatically whenever your Mac boots up:

1. Open System Settings > General > Login Items.
2. Click the + (Plus) button under the "Open at Login" list.
3. Select HapticMouse.app from /Applications.

Testing Haptic Motor Directly

Verify your trackpad's haptic motor is functional directly, independent of Accessibility permission states:

swiftc -O TestHaptic.swift -o test-haptic
./test-haptic

---

📄 License

Distributed under the MIT License. See LICENSE for more details.