diff --git a/docs/github-tracking/issue-windows-dual-hotkey-sources.md b/docs/github-tracking/issue-windows-dual-hotkey-sources.md new file mode 100644 index 00000000..82197002 --- /dev/null +++ b/docs/github-tracking/issue-windows-dual-hotkey-sources.md @@ -0,0 +1,77 @@ +## Symptom + +Windows dictation / QA lifecycle previously had two event sources driving the same state machine: + +- OS-level low-level keyboard hook +- renderer / window-local hotkey forwarding + +That design is risky even when the product "seems to work": + +- press/release edges can come from different sources +- focus switches can strand half an edge +- hold mode and toggle mode can drift differently on Windows only + +## Evidence + +- [openless-all/app/src/App.tsx](/D:/Users/cooper/Practice-Project/202604/openless/openless-all/app/src/App.tsx) + - Windows window-local forwarding existed in the frontend path +- [openless-all/app/src-tauri/src/coordinator.rs](/D:/Users/cooper/Practice-Project/202604/openless/openless-all/app/src-tauri/src/coordinator.rs) + - backend also accepted `handle_window_hotkey_event` +- [openless-all/app/src-tauri/src/hotkey.rs](/D:/Users/cooper/Practice-Project/202604/openless/openless-all/app/src-tauri/src/hotkey.rs) + - Windows already owns a `WH_KEYBOARD_LL` low-level hook + +Current convergence from this repair track: + +- QA hotkey / follow-up flow works +- Windows owner source should be the backend low-level hook +- window-local forwarding should not keep driving the same lifecycle + +## Root Cause Convergence + +This was not just "an extra fallback path". + +It was an ownership problem: + +```text +Two independent input sources were allowed to influence one dictation / QA +lifecycle state machine without an explicit precedence contract. +``` + +## 5 Whys + +1. Why is this a lifecycle issue and not just a convenience fallback? + - Because the second path was able to trigger real start/stop edges. +2. Why is that dangerous? + - Because mixed-source ordering can desynchronize phase transitions. +3. Why is it primarily a Windows issue? + - Because Windows carried both the low-level hook and the renderer-forward path. +4. Why does this diverge from original intent? + - Because one user gesture should map to one stable lifecycle transition. +5. Why is this near closure now? + - Because current repair work has already converged on a single owner source: backend low-level hook. + +## Platform Scope + +- Direct symptom scope: Windows implementation risk +- Problem layer: input source ownership, lifecycle precedence, focus-sensitive edge delivery + +## Related Issues + +- #154 main issue anchor +- #147 settings-to-runtime listener refresh contract +- #158 governance issue for helper-window / native-window contract family + +## Impact + +- Without a single owner source, Windows-only lifecycle drift remains hard to reproduce and harder to trust +- With ownership clarified, regression review can focus on evidence instead of guessing which path fired + +## Proposed Acceptance Criteria + +- [ ] Windows lifecycle owner source is explicitly documented as backend low-level hook +- [ ] window-local forwarding no longer drives the main lifecycle unless a future explicit fallback contract is introduced +- [ ] regression review confirms no new mixed-source ordering evidence + +## Status Note + +Current recommendation: treat this issue as near-closure and use it as a regression-review anchor rather than a new large refactor anchor. diff --git a/docs/github-tracking/pr-154-windows-dual-hotkey.md b/docs/github-tracking/pr-154-windows-dual-hotkey.md new file mode 100644 index 00000000..e0a5d12e --- /dev/null +++ b/docs/github-tracking/pr-154-windows-dual-hotkey.md @@ -0,0 +1,52 @@ +## Summary + +Closes #154 + +This draft PR now serves as a near-closure tracking anchor for the Windows dual-hotkey-source problem. + +Current conclusion: + +- Windows dictation / QA lifecycle should be owned by the backend low-level hook +- renderer / window-local forwarding should not keep driving the same lifecycle +- future work here should focus on regression review, not on reopening the architecture without new evidence + +## Current Status + +- keep draft for now +- close to regression review +- not a parked native-strategy problem like #153 + +## Scope + +- source ownership +- lifecycle precedence +- mixed-source risk on Windows + +Out of scope: + +- helper-window drag semantics +- main window / radius / appearance work +- broad hotkey adapter rewrites without new evidence + +## Key Finding + +```text +One lifecycle needs one owner source. +On Windows, that owner source should be the backend low-level hook. +``` + +## Evidence + +- QA hotkey and follow-up flow remain healthy after ownership tightening +- no evidence from this repair track suggests the renderer-forward path should remain a co-owner + +## Next Step + +- use this PR as the place to summarize regression evidence +- only reopen architecture scope if new mixed-source failures appear + +## Validation Plan + +- [x] Manual verification: QA hotkey flow remains functional +- [x] Manual verification: lifecycle tightening did not break follow-up QA +- [ ] Regression review: confirm no new mixed-source phase drift evidence diff --git a/docs/windows-lifecycle-tracking/issue-154-dual-hotkey-sources.md b/docs/windows-lifecycle-tracking/issue-154-dual-hotkey-sources.md new file mode 100644 index 00000000..f4df0348 --- /dev/null +++ b/docs/windows-lifecycle-tracking/issue-154-dual-hotkey-sources.md @@ -0,0 +1,27 @@ +# Issue #154 Tracking + +Scope: Windows dictation lifecycle driven by two hotkey event sources + +Current stage: + +- This branch is a draft PR placeholder. +- No runtime fix is included yet. +- The goal is to lock down source ownership and failure modes before changing behavior. + +Problem statement: + +- Windows currently has both OS-level low-level keyboard hook input and focused-window renderer forwarding. +- macOS/Linux do not have the same dual-source lifecycle driver. +- Shared dedupe exists, but source precedence is not yet a first-class contract. + +Implementation target to converge before coding: + +- Decide whether Windows should have one owner source or an explicit precedence model. +- Define expected behavior for mixed-source press/release ordering. +- Add testable scenarios for hold mode, toggle mode, and focus switching. + +Non-goals in this draft: + +- No hotkey adapter rewrite yet +- No input-stack refactor without agreed target contract +- No unrelated QA hotkey changes