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.