docs/bugs/002_gradio_ui_investigation.md

# Bug Investigation: Gradio UI Header Cutoff & Layout Ordering

**Date:** November 26, 2025
**Investigator:** Gemini (Supreme Gradio/HF Expert)
**Status:** Resolved
**Target Bugs:**
1.  **Header Cutoff:** Top content (Title/Markdown) hidden under HuggingFace Spaces banner.
2.  **Layout Ordering:** Configuration inputs appearing in unexpected locations or fighting for space.

## 1. The Problem
The Gradio application deployed on HuggingFace Spaces displayed a persistent layout failure where the top-most content (Title) was obscured. Attempts to use `fill_height=True` resulted in aggressive flexbox behavior that, combined with the HF Spaces iframe, pushed the header off-canvas.

**Context:**
- **SDK:** Gradio `6.0.1`
- **Environment:** HuggingFace Spaces
- **Critical Component:** `gr.ChatInterface` inside `gr.Blocks(fill_height=True)`.

## 2. Root Cause Analysis
The issue was a "perfect storm" of three factors:
1.  **`fill_height=True` on Root Blocks:** This forces the entire application to fit within `100vh`.
2.  **`gr.ChatInterface` Dominance:** This component is designed to expand to fill available space. When placed in a `fill_height` container, it aggressively consumes vertical space.
3.  **Markdown Layout:** `gr.Markdown` does not have inherent height/scale properties. In a flex column layout dominated by the ChatInterface, the Markdown header was either squashed or, due to iframe viewport miscalculations, pushed upwards behind the overlay banner.

## 3. Solution Implemented
**Strategy:** Return to Standard Document Flow.

We removed `fill_height=True` from the root `gr.Blocks()` container.
-   **Why:** This disables the single-page flex constraint. The application now flows naturally (Title -> Description -> Chat).
-   **Benefit:** The browser handles the scrolling. If the content exceeds the viewport, the page scrolls naturally, ensuring the Title is always reachable at the top.

**Layout Restructuring:**
1.  **Title/Description:** Moved explicitly *outside* `gr.ChatInterface` to the top of the `gr.Blocks` layout.
2.  **Configuration Inputs:** Kept within `additional_inputs` of `ChatInterface`. While this places them in an accordion (standard Gradio behavior), it ensures functional stability and proper state management without fragile custom layout hacks.
3.  **CSS:** Retained a safety `padding-top` in `launch(css=...)` to handle any residual banner overlaps, though the removal of `fill_height` does the heavy lifting.

## 4. Alternative Solutions Discarded
-   **Moving Title into `ChatInterface`:** Caused `additional_inputs` to render *above* the title in some layout modes, violating desired visual hierarchy.
-   **Custom CSS Hacks on `fill_height`:** Proved brittle against different screen sizes and HF banner updates.
-   **Complex Custom Chat Loop:** Too high risk for a UI bug fix; `ChatInterface` provides significant functionality (streaming, history) that is expensive to reimplement.

## 5. Verification
-   **Local Test:** `make check` passed (101 tests).
-   **Visual Check:** Title should now be the first element in the document flow. Page will scroll if chat is long, which is standard web behavior.

## 6. Future Recommendations
-   If a "fixed app-like" experience is strictly required (no page scroll, only chat scroll), we must wrap `ChatInterface` in a `gr.Column(height=...)` or use specific CSS flex properties on the `gradio-container`, but this requires careful cross-browser testing in the HF iframe.