UAT: TUI MainScreen missing escape-cascading navigation (escape key not bound) #1335

New issue

Open

opened 2026-04-02 16:53:29 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 16:53:29 +00:00

Owner

Severity Assessment

Impact: Medium. Users cannot use escape to dismiss overlays, close the sidebar, or navigate back to the main screen. This is a core UX principle of the TUI.
Likelihood: 100% reproducible — escape is not registered as a binding.
Priority: Medium

Location

File: src/cleveragents/tui/app.py — BINDINGS class variable (lines 90–93)

Description

The specification defines escape-cascading navigation as a key architectural principle:

"Escape-cascading navigation — escape always moves toward the main screen from any state"

The spec keyboard reference (§Keyboard Reference — Global) states:

escape — Close current overlay / modal / sidebar toward main screen

The spec also defines specific escape behaviors:

In Sidebar Visible: escape → Dismiss sidebar, return focus to prompt
In Sidebar Fullscreen: escape → Return to visible sidebar state
In Conversation/Block Cursor: escape → Clear block cursor, return focus to prompt
In Block Context Menu: escape → Dismiss menu
In Reference Picker Overlay: escape → Dismiss overlay
In Slash Command Overlay: escape → Dismiss overlay

Actual Behavior

The BINDINGS class variable does not include escape:

BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
    ("ctrl+q", "quit", "Quit"),
    ("f1", "help", "Help"),
    ("ctrl+t", "cycle_preset", "Cycle Preset"),
]

There is no action_escape() method or any escape handling logic in app.py.

Expected Behavior (from spec)

The app should register an escape binding that:

If a modal/overlay is open → close it
If sidebar is fullscreen → transition to visible state
If sidebar is visible → dismiss sidebar, return focus to prompt
If block cursor is active → clear cursor, return focus to prompt
If at main screen with prompt focused → no-op (or minimal feedback)

Steps to Reproduce

Run the TUI
Press F1 to open the help panel
Press escape — the help panel does not close (no escape handler)
Press escape again — still no response

#694 (feat(tui): Textual MainScreen with sidebar states and Dracula theme)
#1329 (UAT: TUI MainScreen missing right-side collapsible sidebar)
#1330 (UAT: TUI MainScreen missing keyboard bindings)

References

Spec §TUI Architecture Overview (escape-cascading navigation principle)
Spec §Keyboard Reference — Global
Spec §Sidebar — Visible (Partial) keyboard table
Spec §Sidebar — Fullscreen keyboard table

## Bug Report: [tui] — Escape-cascading navigation is not implemented in MainScreen ### Severity Assessment - **Impact**: Medium. Users cannot use `escape` to dismiss overlays, close the sidebar, or navigate back to the main screen. This is a core UX principle of the TUI. - **Likelihood**: 100% reproducible — `escape` is not registered as a binding. - **Priority**: Medium ### Location - **File**: `src/cleveragents/tui/app.py` — `BINDINGS` class variable (lines 90–93) ### Description The specification defines **escape-cascading navigation** as a key architectural principle: > "**Escape-cascading navigation** — `escape` always moves toward the main screen from any state" The spec keyboard reference (§Keyboard Reference — Global) states: > `escape` — Close current overlay / modal / sidebar toward main screen The spec also defines specific escape behaviors: - In **Sidebar Visible**: `escape` → Dismiss sidebar, return focus to prompt - In **Sidebar Fullscreen**: `escape` → Return to visible sidebar state - In **Conversation/Block Cursor**: `escape` → Clear block cursor, return focus to prompt - In **Block Context Menu**: `escape` → Dismiss menu - In **Reference Picker Overlay**: `escape` → Dismiss overlay - In **Slash Command Overlay**: `escape` → Dismiss overlay ### Actual Behavior The `BINDINGS` class variable does not include `escape`: ```python BINDINGS: ClassVar[list[tuple[str, str, str]]] = [ ("ctrl+q", "quit", "Quit"), ("f1", "help", "Help"), ("ctrl+t", "cycle_preset", "Cycle Preset"), ] ``` There is no `action_escape()` method or any escape handling logic in `app.py`. ### Expected Behavior (from spec) The app should register an `escape` binding that: 1. If a modal/overlay is open → close it 2. If sidebar is fullscreen → transition to visible state 3. If sidebar is visible → dismiss sidebar, return focus to prompt 4. If block cursor is active → clear cursor, return focus to prompt 5. If at main screen with prompt focused → no-op (or minimal feedback) ### Steps to Reproduce 1. Run the TUI 2. Press `F1` to open the help panel 3. Press `escape` — the help panel does not close (no escape handler) 4. Press `escape` again — still no response ### Related Issues - #694 (feat(tui): Textual MainScreen with sidebar states and Dracula theme) - #1329 (UAT: TUI MainScreen missing right-side collapsible sidebar) - #1330 (UAT: TUI MainScreen missing keyboard bindings) ### References - Spec §TUI Architecture Overview (escape-cascading navigation principle) - Spec §Keyboard Reference — Global - Spec §Sidebar — Visible (Partial) keyboard table - Spec §Sidebar — Fullscreen keyboard table

freemo added the

labels

2026-04-02 16:55:44 +00:00

freemo referenced this issue

2026-04-02 16:56:18 +00:00

[Automated] Product Build Session State #1314