-
Notifications
You must be signed in to change notification settings - Fork 129
docs(windows): 跟踪双热键事件源生命周期 #155
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
appergb
merged 2 commits into
Open-Less:main
from
Cooper-X-Oak:codex/issue-154-windows-dual-hotkey-pr
May 2, 2026
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
27 changes: 27 additions & 0 deletions
27
docs/windows-lifecycle-tracking/issue-154-dual-hotkey-sources.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The evidence section links to
/D:/...filesystem paths, which only exist on one Windows workstation and are not resolvable in GitHub or by other contributors. This breaks traceability for the core claim in this tracking doc because reviewers cannot open the referenced source files from the repository context. Use repository-relative links (or commit permalinks) so the documentation remains portable and verifiable.Useful? React with 👍 / 👎.