crabidy/quality/help-modal.md

Quality gates — help modal (cbd-tui)

Checklist for the implement stage. Each gate is pass/fail and verified by reading the code (the automatic tests live in cbd-tui/src/app/{bindings,help,mod}.rs #[cfg(test)] modules and must pass via devenv shell -- cargo test -p cbd-tui).

Single source of truth

• bindings::BINDINGS is the only encoding of key → action → description. help.rs contains no hardcoded key names or binding descriptions other than the usage paragraph; key labels come from bindings::key_label.
• The old match (app.focus, key.modifiers, key.code) in main.rs is fully replaced by bindings::lookup + App::dispatch. No key handling remains in main.rs besides translating KeyEvent → Action and honoring DispatchResult::Quit.
• Behavior parity: every binding that existed before the refactor (main.rs match arms at the pre-change commit) maps to a BINDINGS entry triggering the same underlying call. Cross-check arm by arm.

Modality

• While show_help is true, only Scope::Help entries dispatch; q closes the modal and does not quit the app.
• Scope::Help entries never dispatch while the modal is closed.
• The overlay is drawn last in App::render and uses ratatui's Clear before drawing the popup, so pane content never bleeds through.

No panics on user input (AGENTS.md hard rule)

• All todo!() stubs from api-design are gone from bindings.rs, help.rs, and App::dispatch.
• lookup, key_label, dispatch, and help::render cannot panic for any KeyEvent or any frame size (including 1×1); no unwrap/expect /indexing on user-driven paths. Unknown keys are ignored (None), not errors.
• Channel send failures in dispatch are ignored (let _ =), matching the existing module convention — no unwrap on tx.send.

Robust key matching

• lookup ignores SHIFT when comparing KeyCode::Char chords and requires exact matches for all other modifiers (Ctrl+n ≠ n).
• Key events with kind != KeyEventKind::Press are still filtered out before lookup (existing behavior preserved).

Code quality

• Public items in bindings.rs and help.rs keep doc comments that match the implemented behavior (update them if implementation details shift).
• No new external dependencies in cbd-tui/Cargo.toml.
• devenv shell -- cargo fmt --check, cargo clippy (no new warnings, no dead-code warnings remaining for bindings/help), and cargo test -p cbd-tui all pass.
• The TODO(api-design) marker on the LibraryQueueNext description is resolved: the wording matches what MessageFromUi::QueueTracks actually does server-side.