UAT: Help panel is an inline Static widget, not a modal overlay as required by spec #1361

New issue

Open

opened 2026-04-02 16:58:41 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 16:58:41 +00:00

Owner

Severity Assessment

Impact: High. The spec requires the help panel to be a modal dialog that overlays the current view with a dark semi-transparent backdrop. The current implementation is an inline Static widget embedded in the main layout, which does not overlay content and does not provide the required visual separation.
Likelihood: 100% reproducible — the widget type is hardcoded.
Priority: High

Location

File: src/cleveragents/tui/widgets/help_panel_overlay.py — HelpPanelOverlay class
File: src/cleveragents/tui/app.py — compose() method

Description

The spec (§10.2 Help Panel) states:

Appearance: The panel will be a modal dialog that overlays the current view with a dark, semi-transparent backdrop (rgba(0, 0, 0, 0.8)).

The current implementation:

HelpPanelOverlay extends Static (a plain inline widget), not ModalScreen or a layered overlay
It is composed directly into the main layout via compose() between the conversation area and the prompt input
It does not overlay the current view — it pushes other widgets up/down when shown
There is no backdrop, no modal behavior, and no visual separation from the rest of the UI

Evidence

HelpPanelOverlay class definition (help_panel_overlay.py, lines 80–82):

class HelpPanelOverlay(_StaticBase):
    """Simple static overlay that toggles contextual help text."""

_StaticBase resolves to textual.widgets.Static — a plain inline widget.

compose() in app.py (lines 113–124):

def compose(self) -> Any:
    yield _Header(show_clock=True)
    with _Vertical(id="main-column"):
        yield _Static("CleverAgents TUI", id="conversation")
        yield HelpPanelOverlay(id="help-panel")   # ← inline, not modal
        yield ReferencePickerOverlay(id="reference-picker")
        yield SlashCommandOverlay(id="slash-overlay")
        yield PromptInput(...)
        yield PersonaBar(id="persona-bar")
    yield _Footer()

The help panel is sandwiched between the conversation area and the reference picker — it is not a modal overlay.

Expected Behavior (from spec §10.2)

The help panel should be implemented as a Textual ModalScreen (or equivalent layer-based overlay) that:

Overlays the entire current view when shown
Has a dark semi-transparent backdrop (rgba(0, 0, 0, 0.8))
Renders on top of all other content
Can be dismissed by pressing Esc or F1 again

In Textual, this is typically achieved with:

class HelpScreen(ModalScreen):
    BINDINGS = [("escape", "dismiss", "Close"), ("f1", "dismiss", "Close")]
    ...

Actual Behavior

The help panel is an inline Static widget that:

Appears between the conversation area and the reference picker in the layout
Does not overlay any content
Has no backdrop
Does not block interaction with other widgets

#1356 (UAT: Help panel title is wrong and missing required shortcut categories)
#1335 (UAT: TUI MainScreen missing escape-cascading navigation)

References

Spec §10.2 Help Panel (F1) — "Appearance" subsection
src/cleveragents/tui/widgets/help_panel_overlay.py lines 80–82 (class definition)
src/cleveragents/tui/app.py lines 113–124 (compose())
Textual docs: ModalScreen for modal overlay implementation

## Bug Report: [tui/help-panel] — Help panel is not a modal overlay ### Severity Assessment - **Impact**: High. The spec requires the help panel to be a modal dialog that overlays the current view with a dark semi-transparent backdrop. The current implementation is an inline `Static` widget embedded in the main layout, which does not overlay content and does not provide the required visual separation. - **Likelihood**: 100% reproducible — the widget type is hardcoded. - **Priority**: High ### Location - **File**: `src/cleveragents/tui/widgets/help_panel_overlay.py` — `HelpPanelOverlay` class - **File**: `src/cleveragents/tui/app.py` — `compose()` method ### Description The spec (§10.2 Help Panel) states: > **Appearance**: The panel will be a **modal dialog** that **overlays the current view** with a dark, semi-transparent backdrop (`rgba(0, 0, 0, 0.8)`). The current implementation: 1. `HelpPanelOverlay` extends `Static` (a plain inline widget), not `ModalScreen` or a layered overlay 2. It is composed directly into the main layout via `compose()` between the conversation area and the prompt input 3. It does not overlay the current view — it pushes other widgets up/down when shown 4. There is no backdrop, no modal behavior, and no visual separation from the rest of the UI ### Evidence **`HelpPanelOverlay` class definition** (`help_panel_overlay.py`, lines 80–82): ```python class HelpPanelOverlay(_StaticBase): """Simple static overlay that toggles contextual help text.""" ``` `_StaticBase` resolves to `textual.widgets.Static` — a plain inline widget. **`compose()` in `app.py` (lines 113–124)**: ```python def compose(self) -> Any: yield _Header(show_clock=True) with _Vertical(id="main-column"): yield _Static("CleverAgents TUI", id="conversation") yield HelpPanelOverlay(id="help-panel") # ← inline, not modal yield ReferencePickerOverlay(id="reference-picker") yield SlashCommandOverlay(id="slash-overlay") yield PromptInput(...) yield PersonaBar(id="persona-bar") yield _Footer() ``` The help panel is sandwiched between the conversation area and the reference picker — it is not a modal overlay. ### Expected Behavior (from spec §10.2) The help panel should be implemented as a Textual `ModalScreen` (or equivalent layer-based overlay) that: 1. Overlays the entire current view when shown 2. Has a dark semi-transparent backdrop (`rgba(0, 0, 0, 0.8)`) 3. Renders on top of all other content 4. Can be dismissed by pressing `Esc` or `F1` again In Textual, this is typically achieved with: ```python class HelpScreen(ModalScreen): BINDINGS = [("escape", "dismiss", "Close"), ("f1", "dismiss", "Close")] ... ``` ### Actual Behavior The help panel is an inline `Static` widget that: - Appears between the conversation area and the reference picker in the layout - Does not overlay any content - Has no backdrop - Does not block interaction with other widgets ### Related Issues - #1356 (UAT: Help panel title is wrong and missing required shortcut categories) - #1335 (UAT: TUI MainScreen missing escape-cascading navigation) ### References - Spec §10.2 Help Panel (F1) — "Appearance" subsection - `src/cleveragents/tui/widgets/help_panel_overlay.py` lines 80–82 (class definition) - `src/cleveragents/tui/app.py` lines 113–124 (`compose()`) - Textual docs: `ModalScreen` for modal overlay implementation

freemo referenced this issue

2026-04-02 16:59:00 +00:00

UAT: Help panel styling does not match spec (missing #FFFFFF background, drop shadow, and semi-transparent backdrop) #1364

freemo added the

labels

2026-04-02 18:01:26 +00:00