Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions docs/github-tracking/issue-windows-dual-hotkey-sources.md
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)
Comment on lines +16 to +20
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Replace machine-local evidence links with repo-relative paths

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 👍 / 👎.

- 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.
52 changes: 52 additions & 0 deletions docs/github-tracking/pr-154-windows-dual-hotkey.md
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 docs/windows-lifecycle-tracking/issue-154-dual-hotkey-sources.md
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
Loading