Context HUD: Standalone command discovery display

[malpern]

Vision

A standalone, frosted-glass HUD that displays available commands based on the current context (layer, mode, one-shot, etc.). Works independently of the keyboard overlay, giving users flexible options for command discovery.

Trigger

• Appears on any context change: layer activation, mode switches, one-shot activations, or other state changes
• Examples: entering Nav layer, activating Window layer via Leader -> w, enabling a one-shot modifier

Relationship to Overlay

User choice - configurable in Settings:

• Overlay only (current behavior)
• HUD only (for users who prefer minimal UI)
• Both (HUD appears on top of overlay when both enabled)

Content and Layout

Default View

• Vertical list of available commands
• Each item: Large virtual keycap (styled like the keycaps in Rules UI) + short label
• Grouped by category with subtle section headers

Custom Views per Context

Some contexts have custom HUD layouts:

• Window Snapping: Visual grid showing monitor with snap zones (like WindowSnappingView)
• Launcher: App icon grid
• Symbols: Symbol picker layout
• Other contexts: Default vertical list

Position

• Lower 1/3 of screen, horizontally centered
• Floats on top of overlay if overlay is visible

Dismissal

All of these mechanisms:

• Action: Closes when user presses a mapped key
• Timeout: Auto-closes after configurable seconds of inactivity
• Escape: Manual dismiss via Esc key
• Context change: Closes when leaving the current context/layer

Visual Style

• Frosted glass (NSVisualEffectView with vibrancy)
• Semi-transparent with blur, matches macOS design language
• Smooth fade in/out animations

Acceptance Criteria

• HUD appears on context changes (layers, modes, one-shots)
• Default view shows keycaps + labels in categorized vertical list
• Window Snapping context shows visual grid custom view
• Position: lower 1/3 center, on top of overlay
• Dismisses on: action, timeout, Esc, context change
• Frosted glass visual style
• User can enable/disable in Settings
• User can choose: overlay only, HUD only, or both

Out of Scope (Future)

• Keyboard navigation within HUD
• Pinning HUD to stay visible
• Custom positioning per context

References

• Supersedes: MAL-57, MAL-58
• Related: MAL-56 (Overlay Context Integration) - done