SubMiner/backlog/tasks/task-220 - Restore-YouTube-overlay-mpv-keybindings-after-picker-routing.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, references, documentation, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	references	documentation	priority	ordinal
TASK-220	Restore YouTube overlay mpv keybindings after picker routing	Done	codex	2026-03-22 00:00	2026-03-22 23:49	bug overlay youtube keyboard		src/renderer/handlers/keyboard.ts src/renderer/modals/youtube-track-picker.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/youtube-track-picker.test.ts	docs/workflow/verification.md	high	118800

Description

Regression: after adding the YouTube subtitle picker modal path, visible-overlay keydown handling can stop before reaching the shared mpv keybinding dispatch path. Result: default overlay mpv bindings like Space pause/play and q quit stop working while the overlay owns focus during YouTube playback.

Acceptance Criteria

• #1 Unhandled keys while the YouTube track picker state is active still fall through to the shared overlay mpv keybinding dispatcher.
• #2 The YouTube picker continues to consume Enter and Escape for its own actions.
• #3 Renderer regression tests cover both the picker modal key contract and the shared keyboard dispatch fallback.

Implementation Plan

1. Add a failing renderer keyboard regression test covering YouTube picker state plus shared mpv keybinding fallback.
2. Update the global keyboard handler to return early only when the YouTube picker actually handles the key event.
3. Update the picker modal handler to return false for unhandled keys while preserving Enter/Escape.
4. Run the cheap renderer verification lane and record results.

Implementation Notes

Fixed the regression by making the global renderer keyboard handler stop early for the YouTube picker only when the picker actually consumes the key. The picker modal now returns false for unrelated keys, so shared overlay mpv bindings like Space and KeyQ still dispatch while the visible overlay has focus.

Added regression coverage in the keyboard handler suite for mpv keybinding fallback during YouTube picker state, plus a picker-modal contract test that keeps Escape handled but leaves unrelated keys unclaimed.

Verification:

• bun test src/renderer/handlers/keyboard.test.ts src/renderer/modals/youtube-track-picker.test.ts
• bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/renderer/handlers/keyboard.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/youtube-track-picker.ts src/renderer/modals/youtube-track-picker.test.ts
• bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/renderer/handlers/keyboard.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/youtube-track-picker.ts src/renderer/modals/youtube-track-picker.test.ts
• verifier artifact: .tmp/skill-verification/subminer-verify-20260322-234831-b2m6nJ

Final Summary

Restored YouTube-session overlay mpv keybindings by removing an unconditional early return added to the renderer keyboard path for the YouTube subtitle picker modal. Unhandled keys now fall through to the shared mpv keybinding dispatcher, while handled picker keys (Enter, Escape) still stay local to the picker. Added renderer regression tests for both the keyboard fallback path and the picker modal key-consumption contract.