Hyper Key Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a Wox-only Hyper Key mode where Caps Lock + key can trigger main, selection, and query hotkeys stored as hyper+key.

Architecture: Keep normal OS-registered hotkeys unchanged. Add a small raw-key based Hyper Key dispatcher in the core hotkey layer, controlled by a boolean setting and used only for Wox-owned hotkeys. Teach Flutter settings, recorder, parsing, and display code to understand hyper+key.

Tech Stack: Go core, native keyboard hooks already exposed through wox.core/util/keyboard, Flutter/Dart settings UI, existing Wox HTTP settings API.

---

Task 1: Settings Contract

Files:

• Modify: wox.core/setting/wox_setting.go

• Modify: wox.core/ui/dto/setting_dto.go

• Modify: wox.core/ui/router.go

• Modify: wox.core/ui/manager.go

• Modify: wox.ui.flutter/wox/lib/entity/wox_setting.dart

• Modify: wox.ui.flutter/wox/lib/controllers/wox_setting_controller.dart

• Modify: wox.ui.flutter/wox/lib/modules/setting/views/wox_setting_general_view.dart

• Modify: wox.core/resource/lang/en_US.json

• Modify: wox.core/resource/lang/zh_CN.json

• Modify: wox.core/resource/lang/pt_BR.json

• Modify: wox.core/resource/lang/ru_RU.json

• Add EnableHyperKey as a default-off Wox setting.

• Include it in settings DTOs and update routing.

• Add a General settings switch with localized text.

Task 2: Core Hyper Hotkey Dispatch

Files:

• Modify: wox.core/util/keyboard/listener.go

• Modify: wox.core/util/keyboard/listener_windows.go

• Modify: wox.core/util/keyboard/listener_windows.c

• Modify: wox.core/util/keyboard/listener_darwin.go

• Modify: wox.core/util/keyboard/listener_darwin.m

• Modify: wox.core/util/keyboard/listener_linux*.go

• Modify: wox.core/util/keyboard/listener_linux.c

• Modify: wox.core/util/hotkey/hotkey.go

• Modify: wox.core/util/hotkey/hotkey_parse.go

• Add Caps Lock to the shared key enum and platform native mappings.

• Parse hyper+key into a Hyper Key hotkey spec.

• Register Hyper Key specs through a raw-key dispatcher that tracks Caps Lock state and invokes only exact registered hyper+key callbacks.

• Keep normal and double-modifier hotkey behavior unchanged.

Task 3: Manager Integration

Files:

• Modify: wox.core/ui/manager.go

• Re-register main, selection, and query hotkeys when EnableHyperKey changes.

• Make Hyper Key callbacks use the same recording, ignored-app, onboarding, and query execution gates as existing hotkeys.

• Update availability comparison so hyper+k conflicts with another Caps Lock based Wox hotkey for the same key.

Task 4: Flutter Recorder And Display

Files:

• Modify: wox.ui.flutter/wox/lib/entity/wox_hotkey.dart

• Modify: wox.ui.flutter/wox/lib/components/wox_hotkey_recorder_view.dart

• Modify: wox.ui.flutter/wox/lib/utils/wox_hotkey_display_util.dart

• Parse hyper+key as a first-class hotkey variant.

• Record Caps Lock plus an allowed key as hyper+key when Hyper Key is enabled, otherwise as capslock+key.

• Display hyper+key as ✦ + key consistently.

Task 5: Verification

Files:

• Format/check modified Go and Dart files.

• Run gofmt on modified Go files.

• Run dart format --line-length 180 on modified Dart files.

• Run a targeted Go build/check for core changes.

• Run Flutter static analysis or syntax check only; do not run Flutter build or smoke tests.