Merge remote-tracking branch 'origin/main' into chore/dependabot

Author: DavidHruby1

CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Screamer is a Windows desktop push-to-talk dictation tool. Hold a hotkey, speak, release; audio is recorded at 16 kHz mono, sent to a Whisper-compatible STT endpoint, optionally cleaned up by an LLM rewrite, and typed into the active window via Win32 `SendInput`. It runs as a system-tray app with a settings dialog. Stack: Python 3 + PySide6 (Qt), `sounddevice`, `numpy`, `httpx`. Packaged with PyInstaller.
+
+> Note: `docs/OVERVIEW.md` is a stale pre-fork scouting note (it references PyQt6 and a `transcriber.py` that no longer exists). The authoritative design doc is `docs/IMPLEMENTATION.md` + `docs/PLAN.md`, which match the current code.
+
+## Commands
+
+```powershell
+# Dev setup
+python -m venv .venv; .\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+
+# Run the tray app
+python -m src.main
+
+# Build a Windows .exe (creates .venv, installs deps, runs PyInstaller)
+.\build_windows.ps1   # output: dist\Screamer\Screamer.exe
+
+# Verification (must pass on any OS)
+python -m compileall src/
+python -c "import src; print('OK')"
+```
+
+### Per-module smoke tests
+
+There is **no pytest suite**. Each backend module has a `__main__` block used as its smoke test:
+
+```powershell
+python -m src.icons              # writes 3 test PNGs (32x32)
+python -m src.config             # prints defaults, DPAPI roundtrip, creates APP_DIR
+python -m src.audio              # records 3s -> test.wav, prints duration + RMS
+python -m src.hotkey             # prints pressed/released (Windows only)
+python -m src.injector "hello"   # types into active window (Windows only)
+python -m src.stt test.wav       # transcribes (needs API config)
+python -m src.rewrite "test sentense"   # corrects text (needs API config)
+python -m src.settings_dialog    # launches the 4-tab dialog standalone
+```
+
+CLI scripts resolve credentials in this order: `load_config()` (QSettings + DPAPI) → backfill empty fields from a `.env` at cwd via `import_from_env()` → if still empty, print a setup message to stderr and `exit(1)`. No hardcoded provider defaults.
+
+## Architecture
+
+The codebase is a strict DAG rooted at `main.py` (the composition root). These dependency rules are load-bearing — preserve them when editing:
+
+- **`main.py` imports everything; nothing imports `main.py`.** It owns the tray icon, the `idle → recording → processing → idle` state machine, and the worker thread lifecycle.
+- **The five backend modules (`audio`, `hotkey`, `stt`, `rewrite`, `injector`) must NOT import each other.** They may import only `utils.py`.
+- **`stt.py` and `rewrite.py` receive `AppConfig` as a parameter** — they do not import `config.py`. `audio.py` receives device id / name / RMS threshold from `main.py`.
+- **Qt (PySide6) lives only in `utils.py`, `icons.py`, `settings_dialog.py`, `main.py`.** The backend modules are Qt-free.
+- **`settings_dialog.py` imports only `config.py` and `utils.py`.** It edits a *copy* of the config; the original is untouched until accept.
+
+### Threading model
+
+- The Qt main thread owns all UI. Recording start/stop runs on the main thread.
+- The full pipeline (`transcribe → rewrite → type_text`) runs in `_WorkerThread` (a `QThread`) so it never blocks the UI. It checks a `threading.Event` (`cancel_event`) before each blocking step and emits results back via `finished_signal`.
+- The hotkey listener runs its own daemon thread with a Win32 `GetMessage` pump. It communicates to the Qt main thread through `SignalBridge` (the `QObject`-with-`Signal` bridge in `utils.py`) — this cross-thread signal pattern is how worker/hotkey threads safely touch the UI.
+
+### Error handling
+
+Backend code raises `ScreamerError(AppError.X, detail=...)` — never bare `print()` or swallowed exceptions. `AppError` (in `utils.py`) is an enum whose `.value` is a user-facing message. `main.py` surfaces these as tray balloon notifications. Non-fatal issues (fallback used, rewrite failed) are carried as `PipelineResult.warnings` rather than raised. When adding a new failure mode, add an `AppError` enum member rather than inventing an ad-hoc message.
+
+### Config & secrets
+
+- Plain settings persist via `QSettings` (IniFormat). API-key fields are encrypted with **Windows DPAPI** before being written (see `_SECRET_FIELDS` in `config.py`).
+- All app data lives under `%LOCALAPPDATA%/Screamer/` (`APP_DIR` in `utils.py`). Logs go to a rotating `screamer.log` there.
+- **Never log `api_key` values. Never log transcript text unless `setup_logging(debug=True)`.**
+
+### Platform guards
+
+Windows-first, but every module must **import** cleanly on any OS (agents may run on Linux/macOS). Windows-only runtime paths (`hotkey.py`, `injector.py`, DPAPI in `config.py`) guard Win32 calls behind `platform.system() == "Windows"` and raise `ScreamerError(AppError.UNSUPPORTED_PLATFORM)` at *runtime* rather than crashing at import time. DPAPI roundtrip, `RegisterHotKey`, and `SendInput` can only be fully verified on Windows.
+
+## Conventions
+
+- Public API surface of each module is fixed by the contracts in `docs/IMPLEMENTATION.md`. Phase 2 (`main.py`, `settings_dialog.py`) wires Phase 1 modules using only those exports — if you change a backend signature, update that doc.
+- No new third-party dependencies and no new modules beyond the 10 in `src/` without a strong reason; the project is deliberately small.
+- Hotkeys are `config.Hotkey` value objects (modifiers + one key/mouse trigger), serialized to a canonical string (`ctrl+alt+key:0x20`, `ctrl+mouse:x1`); legacy preset keys auto-migrate via `Hotkey.parse`. Presets live in `HOTKEY_OPTIONS` (`config.py`); the listener uses low-level hooks (`WH_KEYBOARD_LL`/`WH_MOUSE_LL`) and swallows the matched trigger. Add safe-bind-alone keys via `SAFE_STANDALONE_KEYS` in `config.py`.

README.md

@@ -34,6 +34,7 @@ That's it.
 - **OpenAI-compatible speech-to-text** - use OpenAI, Groq, or another compatible `/audio/transcriptions` endpoint.
 - **Optional AI cleanup** - fix punctuation, grammar, spelling, and capitalization after transcription.
 - **Fallback providers** - configure backup STT and LLM providers if the primary one fails.
+- **On-screen recording indicator** - a small pulsing pill appears at the bottom-center of the screen while recording and processing.
 - **System tray app** - enable/disable, change hotkey, toggle rewrite, open settings, or exit from the tray.
 - **Microphone selection** - pick your input device and calibrate silence detection.
 - **Post-type key** - optionally press `Enter`, `Tab`, `Space`, or `Backspace` after typing.
@@ -62,7 +63,17 @@ Model: whisper-1
 API key: your_api_key
 ```
 
-For Groq or another provider, use their OpenAI-compatible base URL and model name.
+For Groq, prefer:
+
+```text
+Base URL: https://api.groq.com/openai/v1
+Model: whisper-large-v3-turbo
+Language: en
+```
+
+If accuracy matters more than speed, use `whisper-large-v3` instead.
+
+For another OpenAI-compatible provider, use its base URL and model name.
 
 The LLM rewrite step is optional. Leave it off if you want raw transcription.
 
@@ -97,7 +108,7 @@ The LLM rewrite step is optional. Leave it off if you want raw transcription.
 
 ## Hotkeys
 
-Available hotkey options:
+Quick-pick presets:
 
 ```text
 Ctrl+Alt+Space
@@ -111,6 +122,12 @@ Pause
 
 Default: `Ctrl+Alt+Space`
 
+Or set a **custom hotkey**: in Settings, click **Record** and press any key
+combination, a function key, or a mouse side/middle button. Bare everyday keys
+need a modifier (Ctrl/Alt/Shift); function keys, lock/pause keys, and mouse
+side/middle buttons may be bound on their own. The matched trigger is swallowed
+so it won't reach the app underneath.
+
 ## For developers
 
 Run from source:
@@ -167,7 +184,7 @@ Screamer is built for Windows.
 
 It depends on Windows-specific features including:
 
-- global hotkeys via `RegisterHotKey`
+- global hotkeys (keyboard or mouse) via low-level hooks (`WH_KEYBOARD_LL`/`WH_MOUSE_LL`)
 - text injection via `SendInput`
 - tray integration
 - DPAPI key storage

docs/FEATURES.md

@@ -2,7 +2,22 @@
 
 ## PRIORITY FEATURE**
 
-Async batching of transcriptions after 5 seconds using queue to boost performance significantly.
+Optimization of the STT transcription pipeline speed.
+
+Fix this issue:
+When dictating with Screamer, injected text appears correctly in web browsers but NOT in Windows Notepad. The app reports success - no error is shown.
+Root Cause: Modifier Key Interference
+The default hotkey is Ctrl+Alt+Space. In src/hotkey.py:215-229, the release watcher (_watch_release) only polls for the primary key (Space, VK=0x20). It does not monitor the modifier keys (Ctrl, Alt):
+state = user32.GetAsyncKeyState(vk)  # only checks 0x20 (Space)
+In toggle mode, _finalize_recording() is called directly from the hotkey-pressed handler while Ctrl+Alt+Space is still physically held. The type_text() call via SendInput with KEYEVENTF_UNICODE then runs while Ctrl/Alt are still logically down.
+Notepad uses the classic Win32 EDIT control, which respects the current keyboard modifier state. When Ctrl or Alt is held, characters injected via KEYEVENTF_UNICODE/VK_PACKET can be dropped or misinterpreted as accelerators.
+Browsers work because they use modern text frameworks (TSF, DirectInput, contenteditable) that handle VK_PACKET robustly regardless of modifier state - so the same SendInput call succeeds there.
+Possible Fixes
+Fix	What	Where
+1. Wait for all hotkey keys	Poll GetAsyncKeyState for both the primary key AND modifier keys (Ctrl, Alt) before emitting hotkey_released	src/hotkey.py:_watch_release
+2. Explicitly init KEYBDINPUT	Set wVk = 0, time = 0, dwExtraInfo = 0 explicitly in _send_unicode and _send_vk (currently relies on implicit ctypes zero-init)	src/injector.py:_send_unicode, _send_vk
+3. Log target window	Call GetForegroundWindow + GetClassNameW before SendInput to see which window actually receives the text	src/injector.py:type_text
+Fix #1 is the most important - it prevents the pipeline from injecting text while modifier keys are still physically held. Fixes #2 and #3 are low-risk hygiene improvements that help with debugging.
 
 ---
 

docs/IMPLEMENTATION.md

@@ -79,13 +79,24 @@ DEFAULT_LLM_SYSTEM_PROMPT: str = (
 DEFAULT_RMS_THRESHOLD: float = 5.0
 
 ```python
-@dataclass(frozen=True)
-class HotkeyBinding:
-    modifiers: int
-    vk: int
+MOUSE_X1 = 1; MOUSE_X2 = 2; MOUSE_MIDDLE = 3   # mouse trigger ids
+
+HOTKEY_OPTIONS: list[tuple[str, str]]  # (canonical_string, display_label) preset pairs
+SAFE_STANDALONE_KEYS: frozenset[int]   # VKs bindable without a modifier (F-keys, locks, etc.)
+MODIFIER_VK_TO_NAME: dict[int, str]    # LL-hook modifier VK → "ctrl"/"alt"/"shift"/"win"
 
-HOTKEY_OPTIONS: list[tuple[str, str]]  # (key, display_label) pairs for combo hotkeys
-HOTKEY_BINDINGS: dict[str, HotkeyBinding]  # maps hotkey name → HotkeyBinding
+@dataclass(frozen=True)
+class Hotkey:
+    """Modifiers + a single key/mouse trigger. Serialized to one canonical string."""
+    mods: frozenset   # subset of {"ctrl","alt","shift","win"}
+    kind: str         # "key" | "mouse"
+    code: int         # Win32 VK (kind="key") or a MOUSE_* id (kind="mouse")
+
+    def to_canonical(self) -> str: ...   # "ctrl+alt+key:0x20", "ctrl+mouse:x1", "key:0x91"
+    def to_label(self) -> str: ...       # "Ctrl+Alt+Space", "Mouse Back"
+    def validate(self) -> str | None: ...  # error message if unsafe, else None
+    @classmethod
+    def parse(cls, value: str) -> "Hotkey | None": ...  # canonical OR legacy preset key
 
 @dataclass(frozen=True)
 class ProviderConfig:
@@ -106,7 +117,7 @@ class ConfigValidationIssue:
 
 @dataclass
 class AppConfig:
-    hotkey: str = "ctrl_alt_space"
+    hotkey: str = "ctrl+alt+key:0x20"     # canonical Hotkey string (see Hotkey.parse)
     recording_mode: str = "hold"          # "hold" | "toggle"
     post_type_key: str = "none"           # "none" | "enter" | "tab" | "space" | "backspace"
     start_with_windows: bool = False
@@ -198,13 +209,17 @@ class HotkeyMode(Enum):
     HOLD = "hold"; TOGGLE = "toggle"
 
 class HotkeyListener:
-    def __init__(self, key: str, mode: HotkeyMode, bridge: SignalBridge): ...
+    def __init__(self, hotkey: Hotkey, mode: HotkeyMode, bridge: SignalBridge): ...
     def start(self) -> None: ...
-        """Create message-only window, RegisterHotKey, GetMessage pump in daemon thread.
-        Emits bridge.hotkey_pressed / bridge.hotkey_released."""
+        """Install WH_KEYBOARD_LL + WH_MOUSE_LL global hooks + GetMessage pump in a daemon thread.
+        Matches modifiers + trigger, swallows the matched trigger event (returns 1 from the hook).
+        Emits bridge.hotkey_pressed / bridge.hotkey_released; SetWindowsHookEx failure →
+        bridge.error_occurred(AppError.HOTKEY_HOOK_FAILED)."""
     def stop(self) -> None: ...
-        """Post WM_QUIT, join thread, unregister hotkey."""
+        """PostThreadMessage WM_QUIT, join thread, unhook both hooks."""
     def set_mode(self, mode: HotkeyMode) -> None: ...
+    # Pure, OS-independent matching core (unit-tested without Win32):
+    #   _on_kb_event(wparam, vk) -> bool ; _on_mouse_event(wparam, mouse_data) -> bool
 ```
 
 ### stt.py
@@ -246,6 +261,23 @@ def get_icon_bytes(state: TrayState) -> bytes: ...
     """Raw PNG bytes for testing without Qt."""
 ```
 
+### snackbar.py
+
+```python
+def snackbar_content_for(state_value: str) -> tuple[str, tuple[int, int, int]] | None: ...
+    """Map a TrayState value to (label, dot_rgb); None for idle/unknown (hidden)."""
+
+def bottom_center_xy(available: QRect, size: QSize, margin: int = 48) -> QPoint: ...
+    """Top-left point centering *size* horizontally in *available*, *margin* above bottom."""
+
+class RecordingSnackbar(QWidget):
+    """Frameless, always-on-top, translucent, click-through status pill at the
+    bottom-center of the primary screen. Pulsing dot + label.
+    Never takes focus or appears in the taskbar."""
+    def show_state(self, label: str, dot_rgb: tuple[int, int, int]) -> None: ...
+    def hide_state(self) -> None: ...
+```
+
 ### settings_dialog.py
 
 ```python

docs/OVERVIEW.md

@@ -53,7 +53,7 @@ This repo is a small but useful prototype for a Groq-based push-to-talk dictatio
 
 ## Best fork direction
 
-- Default STT model: `whisper-large-v3-turbo`.
+- Preferred Groq STT model: `whisper-large-v3-turbo`.
 - Quality fallback: `whisper-large-v3`.
 - Add persistent config, device selection, logging, and packaging first.
 - Then add VAD, better UX, and optional always-listening / streaming behavior.

docs/SUMMARY.md

@@ -457,14 +457,14 @@ Primary STT configuration:
 
 - `STT_API_KEY`, default empty.
 - `STT_BASE_URL`, default `https://api.groq.com/openai/v1`.
-- `STT_MODEL`, default `whisper-large-v3`.
+- `STT_MODEL`, typically `whisper-large-v3-turbo` for Groq.
 - `STT_HEADERS`, default empty.
 
 Fallback STT configuration:
 
 - `STT_FALLBACK_API_KEY`, default empty.
 - `STT_FALLBACK_BASE_URL`, default `https://api.groq.com/openai/v1`.
-- `STT_FALLBACK_MODEL`, default `whisper-large-v3`.
+- `STT_FALLBACK_MODEL`, typically `whisper-large-v3` for quality fallback.
 - `STT_FALLBACK_HEADERS`, default empty.
 
 Language configuration:
@@ -478,7 +478,7 @@ The fork overview recommends changing the preferred model defaults to:
 - Default primary: `whisper-large-v3-turbo`
 - Quality fallback: `whisper-large-v3`
 
-The current code still defaults to `whisper-large-v3` for both primary and fallback.
+The current code leaves STT model choice to the user.
 
 ### LLM Rewrite Configuration