Overlay Context Integration: Show available actions in keyboard overlay

[malpern]

Integrate contextual menu into the existing LiveKeyboardOverlayView to show available actions when a layer is activated via sequence.

User Workflow

Example: Leader → w (Window Management)

1. User presses Space (leader key)
2. User presses 'w' while holding space
3. Sequence completes, activates window-mgmt layer
4. Overlay instantly highlights available keys (H, J, K, L, etc.)
5. Each highlighted key shows action label ("Left Half", "Maximize", etc.)
6. Inactive keys dim to 40% opacity
7. User presses H → window snaps left, context dismisses
8. OR: User waits 5s → context auto-dismisses
9. OR: User presses Esc → context dismisses

Implementation Steps

1. Sequence Support (MAL-45 dependency)

• Enable Leader → w → activate layer capability
• Prerequisite: MAL-45 must be completed first
• Provides foundation for sequence detection

2. Window Management Layer Definition (1 day, ~100 lines)

• Map window actions to home row keys:
  • H: Left half
  • L: Right half
  • K: Maximize
  • J: Center
  • Y: Top-left, U: Top-right
  • B: Bottom-left, N: Bottom-right
  • M: Next display, Z: Undo
• File: RuleCollectionCatalog.swift (+100 lines)

3. Overlay Context Integration (2-3 days, ~230 lines)

LiveKeyboardOverlayView.swift (+150 lines):

• Add context state management
• Handle layer change events for context activation
• Pass context mappings to keycap views
• Auto-dismiss logic (5s timeout)
• Esc key dismissal

OverlayKeycapView.swift (+80 lines):

• Add context highlight rendering (blue glow)
• Add action label display below key
• Add dimming for inactive keys (40% opacity)
• Smooth animations for context enter/exit

4. Wiring & Polish (1 day, ~50 lines)

• TCP layer change events trigger context display
• Context dismisses on key press or timeout
• Smooth animations (spring, 0.3s response)
• Handle Esc to manually dismiss
• Testing all workflows

Visual Design

When window layer activates:

┌─────────────────────────────────────────────────┐
│  [Layer: Window Management]                     │
├─────────────────────────────────────────────────┤
│  Q  W  E  R  T  [Y]  U   I  O  P               │
│                  ↑    ↑                         │
│             Top-Left Top-Right                  │
│                                                 │
│  A  S  D  F  G  [H] [J] [K] [L]  ;             │
│                  ↓   ↓   ↓   ↓                  │
│               Left Ctr Max Right                │
│                                                 │
│  Z  X  C  V  [B]  N  [M]                       │
│              ↑     ↑   ↑                        │
│         Bot-Left Bot-R Display                  │
└─────────────────────────────────────────────────┘

Benefits

• Uses existing, proven overlay system (1,800 lines)
• No new windows to manage
• Users already looking at overlay
• Integrated visual language
• Natural extension of existing functionality

Extensibility

Pattern can be reused for other contexts:

• Leader → a → app launcher (show app icons on keys)
• Leader → s → symbol layer (show available symbols)
• Leader → n → navigation layer (show nav shortcuts)

Effort Estimate

• Total: ~880 lines across 10 files
• Duration: 6-8 days (including MAL-45 dependency)
• Complexity: Medium (building on proven infrastructure)

Dependencies

• Blocks: None (but blocked by MAL-45 for sequence support)
• Blocked by: MAL-45 (Kanata sequences)

Success Criteria

• ✅ Leader → w activates window layer with visual feedback
• ✅ Overlay highlights H, J, K, L, etc. with action labels
• ✅ Inactive keys dimmed
• ✅ Pressing action key works and dismisses context
• ✅ 5s timeout auto-dismisses
• ✅ Esc manually dismisses
• ✅ Smooth animations for enter/exit

References

• Design doc: docs/features/leader-key-overlay-integration.md
• Related: MAL-45 (sequence support dependency)
• Related: MAL-38 (original leader key visual menu request)