Merge pull request #382 from Splode/feat/local-shortcuts

Author: Splode

CHANGELOG.md

@@ -4,6 +4,9 @@
 ### Bug Fixes
 
 * **App freeze / crash on launch when "Show in System Tray" is enabled on KDE Plasma 6 / Wayland** — enabling the system tray on a Linux system without `libayatana-appindicator3` or `libappindicator3` installed caused `libappindicator-sys` to panic inside an `extern "C"` function, which aborts the process. Because the setting is persisted before the crash, every subsequent launch would abort before the window could appear. The fix probes for the shared library via `dlopen` before calling `TrayIconBuilder::build()` and returns early with a warning when it is absent. The System Tray section in Settings → System is now hidden entirely on Linux systems where the library is not found, preventing the setting from being enabled in the first place. The required library can be installed on Arch / Manjaro with `sudo pacman -S libayatana-appindicator`.
+### Shortcuts
+
+* **Local keyboard shortcuts** — a set of keyboard shortcuts now activates while the main timer window has focus, with no system-wide registration required. Default bindings: Space (pause/resume), Left Arrow (reset current round), Right Arrow (skip round), Down Arrow (volume down), Up Arrow (volume up), M (mute toggle), F11 (fullscreen toggle). All seven bindings are re-mappable in Settings → Shortcuts under the new Local Shortcuts section, which appears above the existing Global Shortcuts section. Bindings persist across restarts and are restored to defaults when Reset All Settings is used.
 
 ### UI
 

openspec/changes/archive/2026-04-02-local-shortcuts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

openspec/changes/archive/2026-04-02-local-shortcuts/design.md

@@ -0,0 +1,88 @@
+## Context
+
+Pomotroid has an existing global shortcuts system that registers OS-level hotkeys via `tauri-plugin-global-shortcut`. Those shortcuts are stored in SQLite, exposed through the `Settings` struct, and editable in the Settings → Shortcuts section (`ShortcutsSection.svelte`).
+
+Local shortcuts are a different, complementary mechanism: they fire only while the app window has focus, need no OS-level registration, and are handled entirely in the frontend via standard `keydown` event listeners. The actions they invoke (timer toggle, skip, reset, volume change, mute, fullscreen) are already available through existing IPC commands.
+
+## Goals / Non-Goals
+
+**Goals:**
+- 7 default local shortcuts active whenever any Pomotroid window has focus
+- All 7 bindings are user-configurable via Settings → Shortcuts
+- Bindings persist in SQLite alongside global shortcut bindings
+- "Reset All Settings" resets local bindings to defaults
+- Shortcut bindings update live: changing a binding takes effect without restart
+- No separate enable/disable toggle (local shortcuts are always active while focused)
+
+**Non-Goals:**
+- Modifier-key chording for local shortcuts (single keys only, consistent with defaults like Space, Arrow keys, M, F11)
+- Per-window shortcut overrides (same bindings apply to both main and settings windows)
+- Local shortcut conflict detection with global shortcuts
+- Disabling individual shortcuts (user can leave a binding blank/unbound to effectively disable)
+
+## Decisions
+
+### 1. Pure frontend keydown listeners — no Rust involvement for dispatch
+
+**Decision**: Handle keydown in Svelte via `document.addEventListener('keydown', ...)`. When a matching key is pressed, call the existing IPC functions (`timerToggle()`, `timerSkip()`, `timerReset()`, `volumeSet()`, `settingsSet()`, etc.) directly from the listener.
+
+**Why over Rust-side handling**: The Tauri `tauri-plugin-global-shortcut` plugin is the right tool for OS-level shortcuts, but for focus-scoped shortcuts the browser's own keyboard event model is simpler and sufficient. There is no IPC round-trip needed just to dispatch — the frontend already has all the IPC wrappers it needs.
+
+**Alternative**: Register shortcuts in Rust using `Window::on_window_event` focus guards. Rejected: adds complexity, introduces a Rust→frontend callback path for no benefit.
+
+### 2. Store bindings in Settings struct as plain key strings
+
+**Decision**: Add 7 new fields to the `Settings` struct (e.g. `local_shortcut_toggle: String`) with DB keys like `local_shortcut_toggle`. Each value is a key string (e.g. `" "`, `"ArrowLeft"`, `"F11"`, `"m"`) matching the browser `KeyboardEvent.key` property.
+
+**Why `KeyboardEvent.key` over `KeyboardEvent.code`**: `key` is layout-aware and maps to what the user expects ("Space", not "Space" vs "KeySpace"). Single-character keys like `m` are unambiguous. Arrow keys and function keys have stable `key` names across platforms.
+
+**Why not a JSON blob**: The existing settings pattern stores flat key/value strings. Keeping the same shape makes settings reset, migration, and the `settings_set` IPC flow consistent with the rest of the codebase.
+
+### 3. Key capture UI reuses global shortcut recorder pattern
+
+**Decision**: The local shortcuts section in `ShortcutsSection.svelte` uses the same single-key recorder input pattern already used for global shortcuts — click to focus, press a key, the binding is saved. Difference: local shortcuts record the raw `KeyboardEvent.key` value rather than a Tauri accelerator string.
+
+**Why**: The UX is already proven and familiar. Minor adaptation needed: global shortcut recording listens for a Tauri accelerator format; local shortcut recording listens for `KeyboardEvent.key` directly.
+
+### 4. Listener mounted on `document` in `+page.svelte` (main window) and `settings/+page.svelte`
+
+**Decision**: The keydown handler lives in both page root components, added in `onMount` and removed in `onDestroy`. It reads the current local shortcut settings from the reactive settings store.
+
+**Why both pages**: Both windows can be focused. The settings window should also respond to shortcuts (e.g., user adjusts volume while in settings).
+
+**Guard**: The handler should skip if the focused element is an `<input>` or `<textarea>` to avoid interfering with typing in shortcut capture fields.
+
+### 5. Fullscreen via Tauri `appWindow.setFullscreen()` toggle
+
+**Decision**: F11 calls `getCurrentWindow().setFullscreen(!isFullscreen)`, reading current fullscreen state from a local reactive variable updated via `Window.onResized` or `Window.isFullscreen()`.
+
+**Why**: Tauri exposes `setFullscreen` on the `WebviewWindow` API. This is the correct cross-platform way; native OS F11 handling is bypassed in Tauri's decoration-free window mode anyway.
+
+### 6. Volume up/down as fixed increments (±5%)
+
+**Decision**: Each Up/Down Arrow press adjusts volume by 0.05 (5%) clamped to [0.0, 1.0]. Volume is then saved with `settingsSet('volume', ...)`.
+
+**Why 5%**: Consistent with typical media application increments. Larger steps feel coarse; smaller steps require too many presses.
+
+## Risks / Trade-offs
+
+- **Key conflicts with browser defaults** → Arrow keys may scroll the page in some contexts. Calling `event.preventDefault()` in the handler mitigates this. Must be careful not to swallow keys when an input is focused.
+- **Settings window shortcut duplication** → Both windows mount listeners, so both will fire if both have focus simultaneously (impossible in practice; OS enforces single focus). Low risk.
+- **KeyboardEvent.key normalization** → On some platforms/locales, single-character keys may differ in case. Storing and comparing in lowercase for letter keys avoids mismatches.
+- **Binding an already-used key** → No conflict detection in v1. A key bound to both a local and global shortcut will fire both if the app is focused. Acceptable for now; conflict UI is explicitly a non-goal.
+
+## Migration Plan
+
+1. Add DB migration (increment schema version, insert 7 new key/value rows with defaults)
+2. Add 7 fields to `Settings` struct and `defaults.rs`
+3. Update `types.ts` to match
+4. Wire keydown listeners in both page components, reading from settings store
+5. Expand `ShortcutsSection.svelte` with local shortcut capture rows
+6. Verify "Reset All Settings" path resets the 7 new keys to defaults (handled by existing `settings_reset` command which re-runs `defaults.rs`)
+
+Rollback: remove migration (or let it be — extra DB rows are harmless), revert frontend changes. No data loss risk.
+
+## Open Questions
+
+- Should the Space bar shortcut be suppressed on the settings page to avoid accidental timer toggle while a user types? Likely yes — the `input`/`textarea` focus guard handles this.
+- Should we display the current key binding next to each action in the main timer window as a tooltip? Out of scope for v1 but worth noting.

openspec/changes/archive/2026-04-02-local-shortcuts/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+Pomotroid already supports global shortcuts that work system-wide, but lacks any keyboard shortcuts that activate while the app window is focused. Users who keep the app visible on screen have no way to control the timer, volume, or round state with the keyboard — they must reach for the mouse even for common actions like pause/resume or volume adjustment.
+
+## What Changes
+
+- Introduce a new local shortcuts system: a set of keyboard shortcuts active only while a Pomotroid window has focus
+- Default bindings: Space (pause/resume), Left Arrow (reset current round), Right Arrow (skip round), Down Arrow (volume down), Up Arrow (volume up), M (mute toggle), F11 (fullscreen toggle)
+- All local shortcuts are re-mappable in Settings → Shortcuts alongside global shortcuts
+- "Reset All Settings" resets local shortcut bindings to defaults along with all other settings
+- Local shortcuts are always active when the app is focused (no separate enable/disable toggle — unlike global shortcuts)
+
+## Capabilities
+
+### New Capabilities
+- `local-shortcuts`: Keyboard shortcuts active while the application window is focused, covering pause/resume, round reset, round skip, volume up/down, mute, and fullscreen toggle — all re-mappable via Settings
+
+### Modified Capabilities
+- `shortcuts`: The existing global shortcuts spec must be extended: Settings → Shortcuts section now displays both global and local shortcut bindings; "Reset All Settings" must also reset local shortcut bindings to defaults
+
+## Impact
+
+- **Frontend**: `ShortcutsSection.svelte` expanded to show local shortcut bindings below global ones; keydown event listeners added on main and settings window roots; IPC wrappers for new local-shortcut commands
+- **Backend**: New `Settings` fields for local shortcut key bindings; DB migration adds keys (e.g. `local_shortcut_toggle`, `local_shortcut_reset`, etc.); `settings/defaults.rs` updated; `commands.rs` wires up shortcut actions; `settings_reset` handler also resets local shortcut defaults
+- **Types**: `src/lib/types.ts` updated to mirror new `Settings` fields
+- **Capabilities file**: No new Tauri plugin permissions required (keydown handling is pure frontend via Svelte)

openspec/changes/archive/2026-04-02-local-shortcuts/specs/local-shortcuts/spec.md

@@ -0,0 +1,102 @@
+## ADDED Requirements
+
+### Requirement: Local shortcuts are active while any app window has focus
+The system SHALL handle a configurable set of keyboard shortcuts that fire when the user presses a bound key while any Pomotroid window (main or settings) has OS focus. Local shortcuts SHALL NOT fire when the focus is inside a text input element.
+
+#### Scenario: Shortcut fires in main window
+- **WHEN** the main timer window has OS focus
+- **AND** the user presses the key bound to pause/resume
+- **THEN** the timer SHALL toggle between running and paused
+
+#### Scenario: Shortcut fires in settings window
+- **WHEN** the settings window has OS focus
+- **AND** the user presses the key bound to volume up
+- **THEN** the volume SHALL increase by 5%
+
+#### Scenario: Shortcut does not fire when input is focused
+- **WHEN** a text input or shortcut capture field has keyboard focus
+- **AND** the user presses a key that is bound to a local shortcut
+- **THEN** the shortcut action SHALL NOT execute and the keypress SHALL be handled normally by the input
+
+---
+
+### Requirement: Default local shortcut bindings
+The system SHALL provide the following default local shortcut bindings on all platforms:
+- Pause/Resume: Space
+- Reset current round: ArrowLeft
+- Skip round: ArrowRight
+- Volume down: ArrowDown
+- Volume up: ArrowUp
+- Mute toggle: m
+- Fullscreen toggle: F11
+
+#### Scenario: First launch defaults
+- **WHEN** the application is launched for the first time with no existing settings
+- **THEN** all seven local shortcut bindings SHALL match the defaults listed above
+
+#### Scenario: Existing bindings preserved across launches
+- **WHEN** the user has customized one or more local shortcut bindings and restarts the app
+- **THEN** the customized bindings SHALL be restored from the database
+
+---
+
+### Requirement: Local shortcut actions
+Each local shortcut SHALL invoke a specific action:
+
+- **Pause/Resume**: toggles the timer between running and paused (same as `timer_toggle` IPC command)
+- **Reset current round**: resets the current timer round to its full duration without advancing sequence (same as `timer_reset` IPC command)
+- **Skip round**: ends the current round and advances to the next in sequence (same as `timer_skip` IPC command)
+- **Volume down**: decreases volume by 5 percentage points, clamped to 0.0
+- **Volume up**: increases volume by 5 percentage points, clamped to 1.0
+- **Mute toggle**: toggles the volume between 0.0 and the last non-zero volume level
+- **Fullscreen toggle**: toggles the main window between fullscreen and its previous size/position
+
+#### Scenario: Volume up at maximum
+- **WHEN** the volume is at 1.0 (100%)
+- **AND** the user presses the volume up shortcut
+- **THEN** the volume SHALL remain at 1.0 (no overflow)
+
+#### Scenario: Volume down at minimum
+- **WHEN** the volume is at 0.0 (0%)
+- **AND** the user presses the volume down shortcut
+- **THEN** the volume SHALL remain at 0.0 (no underflow)
+
+#### Scenario: Mute restores previous volume
+- **WHEN** the volume is at 0.6 (60%)
+- **AND** the user presses the mute shortcut
+- **THEN** the volume SHALL be set to 0.0
+- **WHEN** the user presses the mute shortcut again
+- **THEN** the volume SHALL be restored to 0.6
+
+#### Scenario: Fullscreen toggle
+- **WHEN** the main window is in windowed mode
+- **AND** the user presses the fullscreen shortcut
+- **THEN** the main window SHALL enter fullscreen mode
+- **WHEN** the user presses the fullscreen shortcut again
+- **THEN** the main window SHALL exit fullscreen and return to windowed mode
+
+---
+
+### Requirement: Local shortcuts are re-mappable in Settings
+The system SHALL allow users to change any local shortcut binding via Settings → Shortcuts. Each binding field SHALL record the next keypress (excluding modifier-only keys) as the new binding. The new binding SHALL be saved immediately and take effect without restart.
+
+#### Scenario: User rebinds pause/resume
+- **WHEN** the user clicks the pause/resume local shortcut field in Settings → Shortcuts
+- **AND** presses the P key
+- **THEN** the binding SHALL be updated to "p" in the database
+- **AND** pressing P while the main window is focused SHALL toggle the timer
+
+#### Scenario: Binding takes effect immediately
+- **WHEN** the user saves a new local shortcut binding
+- **AND** the settings window remains open
+- **THEN** pressing the newly bound key SHALL immediately trigger the corresponding action (no restart required)
+
+---
+
+### Requirement: Reset All Settings restores local shortcut defaults
+When the user resets all settings to defaults, all local shortcut bindings SHALL be reverted to their default values.
+
+#### Scenario: Reset restores default bindings
+- **WHEN** the user triggers "Reset All Settings" via the Settings menu
+- **THEN** all seven local shortcut bindings SHALL revert to their defaults (Space, ArrowLeft, ArrowRight, ArrowDown, ArrowUp, m, F11)
+- **AND** any custom bindings the user had configured SHALL be discarded

openspec/changes/archive/2026-04-02-local-shortcuts/specs/shortcuts/spec.md

@@ -0,0 +1,9 @@
+## MODIFIED Requirements
+
+### Requirement: Reset All Settings disables global shortcuts
+When the user resets all settings to defaults, `global_shortcuts_enabled` SHALL be `false`, any previously registered global shortcuts SHALL be unregistered, and all local shortcut bindings SHALL be reverted to their default values (Space, ArrowLeft, ArrowRight, ArrowDown, ArrowUp, m, F11).
+
+#### Scenario: Reset All Settings disables global shortcuts and restores local defaults
+- **WHEN** the user resets all settings to defaults
+- **THEN** `global_shortcuts_enabled` SHALL be `false` and any previously registered shortcuts SHALL be unregistered
+- **AND** all seven local shortcut bindings SHALL revert to their defaults