Floating HUD for Layer Command Discovery

[malpern]

Problem

When users activate layers via sequences (e.g., Space → W for Window Management), they need to discover what commands are available. The current approach of showing labels on keycaps is limited by space constraints - labels get truncated ("M...", "Ya...", "Re...") and are illegible when overlapping.

Proposed Solution

Implement a floating HUD (heads-up display) that appears when entering a layer via sequence, showing available commands in a readable format with sufficient space.

Design Considerations

1. Positioning: Float above the overlay keyboard, or in a corner of the screen
2. Content: List of available commands with full labels and descriptions
   • Key: H → Action: Snap Left Half
   • Key: J → Action: Move Window Down
   • Key: K → Action: Move Window Up
   • Key: L → Action: Snap Right Half
   • Key: M → Action: Maximize Window
3. Interaction:
   • Auto-appear when entering layer via sequence
   • Auto-dismiss after timeout (5s) or after first command execution
   • Dismissible via Escape or clicking outside
4. Visual Design:
   • Semi-transparent background
   • Clean typography with sufficient spacing
   • SF Symbol icons for visual recognition
   • Grouped by category (edges, corners, movement, etc.)

Alternative: Compact Mode

Instead of a full list, could show a compact "cheat sheet" style HUD:

Window Layer
H/L: Snap Left/Right   J/K: Move Down/Up   M: Maximize
Q/E/A/D: Corners       ←/→: Next/Prev Display

Technical Notes

• Can leverage existing LayerKeyMapper for mapping data
• Use RuleCollectionsManager to query available mappings
• Listen to layer change notifications from KanataEventListener
• Implement as SwiftUI overlay separate from keyboard visualization

Related Work

• Removed contextual help overlay (keycap highlighting + labels) due to space constraints
• Layer filtering fix in augmentWithPushMsgActions() ensures collections only apply to target layers

Acceptance Criteria

• HUD appears when user enters layer via sequence
• Shows all available commands with full, readable labels
• Auto-dismisses after timeout or command execution
• Does not interfere with overlay keyboard or inspector
• Works with all layers (window, navigation, vim, numpad, symbols)
• Includes custom rules in command list

Design Assets Needed

• Mockups of HUD positioning and layout
• Typography and spacing specs
• Grouping/categorization strategy for commands