Huge Cursor

Huge Cursor 是一个 macOS 交互原型：当用户快速晃动鼠标时，在光标所在位置附近弹出一个轻量输入框。

这个项目的灵感来自 macOS 的“晃动鼠标指针以定位”能力。不同的是，Huge Cursor 不读取系统私有状态，也不依赖系统光标是否被放大，而是直接根据鼠标移动轨迹识别“晃动”手势，并把它转化成一个可复用的交互触发器。

演示

查看演示视频

当前能力

• 支持全方向快速晃动识别：左右、上下、斜向都可以触发。
• 在晃动位置附近弹出自动聚焦的输入框。
• 提供实时调试指标，方便调节手势阈值：
  • confidence
  • current speed
  • peak speed
  • direction turns
  • travel distance

目前没有后端逻辑。输入框只是本地 UI 占位，用于验证“鼠标晃动 -> 光标位置输入/命令入口”这条交互路径。

为什么这样做

macOS 自带一个辅助功能：快速移动鼠标时，系统会临时放大光标，帮助用户定位指针。但第三方开发者没有公开 API 可以直接读取“光标正在被系统放大”这个状态。

Huge Cursor 选择绕开这个限制，直接识别用户的鼠标晃动行为：

1. 监听本地和全局鼠标移动事件。
2. 保存一个很短时间窗口内的光标采样点。
3. 计算移动速度、峰值速度、轨迹距离和方向变化次数。
4. 当这些指标超过阈值时，在光标附近触发浮层输入框。

检测逻辑

核心检测代码在：

Huge cursor/Huge cursor/MouseShakeMonitor.swift

检测器使用一个滚动采样窗口，将快速方向变化视为晃动意图。为了避免只支持横向甩动，它不会只看 deltaX 的正负，而是基于二维移动向量判断方向变化。

当前实现还做了一层“趋势向量”处理：不是直接比较每两个相邻采样点的小位移，而是先把短距离移动累积成一段趋势，再判断趋势是否反向。这样在鼠标事件采样很密时，仍然能保持较好的灵敏度。

输入浮层

光标位置输入框的代码在：

Huge cursor/Huge cursor/ShakeInputOverlay.swift

它使用 NSPanel 承载 SwiftUI View，因此可以像桌面级浮层一样出现在光标附近，并立即聚焦输入框。

环境要求

• macOS
• Xcode 26 或更新版本
• SwiftUI 和 AppKit

本地运行

用 Xcode 打开项目：

open "Huge cursor/Huge cursor.xcodeproj"

或者在终端构建：

xcodebuild -project "Huge cursor/Huge cursor.xcodeproj" \
  -scheme "Huge cursor" \
  -configuration Debug \
  -destination "platform=macOS" \
  build

隐私说明

这个原型只监听鼠标移动，不会录制、上传或处理用户输入内容到本地应用之外。

全局鼠标事件监听可能受到 macOS 隐私和沙盒策略影响。如果要把它做成正式产品，需要认真检查 App Sandbox、Accessibility、Input Monitoring 以及 App Store 分发要求。

后续方向

• 将输入浮层扩展成命令面板。
• 增加可配置的手势灵敏度预设。
• 在输入框出现前增加光标周围的视觉反馈。
• 将 MouseShakeMonitor 抽成可复用 Swift Package。
• 用录制的鼠标轨迹样本为检测算法补测试。
• 支持输入提交后的自定义动作。

License

MIT

---

English

Huge Cursor is a macOS interaction prototype that turns a fast mouse shake into a lightweight input surface at the cursor position.

The idea is inspired by macOS "Shake mouse pointer to locate", but this project does not read private system state or depend on whether the system cursor is visually enlarged. Instead, it detects the gesture directly from mouse movement and uses it as an interaction trigger.

Demo

Watch the demo video

What It Does

• Detects fast cursor shaking in any direction.
• Opens a focused input box near the shake position.
• Shows live debug metrics for tuning the gesture.

There is no backend logic yet. The input box is intentionally a local UI placeholder for experimenting with shake-to-input and shake-to-command interaction paths.

Why This Approach

Third-party macOS apps do not get a public API for reading the system pointer enlargement state. Huge Cursor avoids that dependency by detecting the gesture itself from local and global mouse movement events.

Run Locally

open "Huge cursor/Huge cursor.xcodeproj"

Or build from Terminal:

xcodebuild -project "Huge cursor/Huge cursor.xcodeproj" \
  -scheme "Huge cursor" \
  -configuration Debug \
  -destination "platform=macOS" \
  build