docs(github-tracking): add dual-hotkey tracking docs
This commit is contained in:
1 parent
93cbd03305
commit
229b871d27
2 files changed
+129
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
Reference in new issue
Block a user