Skip to content

Eliminate fake key layer notifications via native Kanata LayerChange #198

@malpern

Description

@malpern

Summary

Make Kanata's layer-while-held emit native LayerChange TCP broadcasts on activation and deactivation. This single upstream change enables eliminating the entire fake key layer notification system, the OneShotLayerOverrideState reconciliation mechanism, the dual notification paths, and the 500ms polling safety net.

Problem

Kanata's layer-while-held does not emit LayerChange broadcasts. KeyPath works around this with deffakekeys entries that fire push-msg on press and release. This creates:

  • Dual notification paths (push-msg vs native LayerChange) requiring complex reconciliation
  • OneShotLayerOverrideState mechanism to arbitrate between the two paths
  • 500ms polling (RequestCurrentLayerName) as a safety net for missed events
  • Layer state desynchronization bugs (e.g., MAL-61: one-shot layers fire enter but no exit fake key, leaving UI stuck)

Phased Plan

Phase 1: Upstream Kanata Change (High priority)

  • Make layer-while-held emit LayerChange on activation and deactivation
  • Extend to one-shot-press layer deactivation
  • File as PR against jtroo/kanata or implement in fork
  • Add capability flag: layer_while_held_change

Phase 2: Simplify KeyPath (After Phase 1)

  • Remove renderFakeKeysBlock(), on-press-fakekey/on-release-fakekey from aliases
  • Delete OneShotLayerOverrideState from LiveKeyboardOverlayController and ContextHUDController
  • Remove source parameter from .kanataLayerChanged notification
  • Reduce polling from 500ms to 5s health check

Phase 3: Consolidate State (After Phase 2)

  • Unify three layer state holders into single reactive source
  • Remove redundant ActionDispatcher.onLayerAction path

Key Insight

push-msg remains correct and permanent for application actions (launch:, open:, system:, window:) and UI hints (icon:, emphasis:). Only layer state notifications are candidates for elimination.

Documentation

  • ADR-029: docs/adr/adr-029-eliminate-fake-key-layer-notifications.md
  • Architecture roadmap: docs/architecture/layer-coordination-roadmap.md

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions