mangotune/docs/WINDOW_GEOMETRY_INVESTIGATION.md

MangoTune Window Geometry Investigation

This documents the March 28, 2026 investigation into the main-window width drift / off-screen placement issue.

Symptom

• On XFCE/X11, MangoTune can open slightly off-screen on the right and bottom.
• Switching pages such as Live Preview and Debug can make the already-open window grow wider.
• XFCE appears to keep the same top-left corner when that happens, so the right edge drifts farther off-screen.

Environment Observed

• Session type: X11
• Desktop: XFCE
• Monitor/work area observed during testing:
  • screen: 3440x1440
  • _NET_WORKAREA: 3440x1395

Concrete Live Findings

Startup geometry

Observed X11 state from a live MangoTune window:

• WM_NORMAL_HINTS minimum size: 1068 x 650
• actual window geometry at startup:
  • x=2397
  • y=311
  • width=1068
  • height=1109

That puts the window slightly off-screen already:

• right edge: about 25 px off-screen
• bottom edge: about 20 px off-screen

Page-switch growth

Repeated live repro:

1. start from Dashboard
2. switch to Live Preview
3. switch to Debug
4. switch back to Dashboard

After that sequence:

• WM_NORMAL_HINTS minimum size stays 1068 x 650
• actual window width grows from 1068 to 1288
• top-left position stays fixed at the same x/y

Important conclusion:

• page switching is not changing the X11 minimum-size hint
• page switching is causing the actual shown window width to grow

So this is not just a bad startup min-width hint. There is a second issue: post-navigation width growth.

What Was Tested

1. Clamp startup size to monitor geometry

Result:

• helped startup placement
• did not stop the post-navigation width growth

2. Shared page clamp / scroller tightening

Changes tested:

• Adwaita Clamp around page bodies
• ScrolledWindow with:
  • min_content_width = 0
  • propagate_natural_width = false
  • propagate_natural_height = false

Result:

• sensible as a page-system cleanup
• did not stop the post-navigation width growth

3. Tighten likely culprit pages

Pages specifically investigated:

• Live Preview
• Debug

Changes tested included:

• wrapping text views by character
• min_content_width = 0
• narrowing preview controls / button grids

Result:

• reduced some page pressure
• did not stop the actual width growth after navigation

4. Reapply current window size after page refresh

Tried preserving the current window size with set_default_size(...) after swapping the page child.

Result:

• did not stop the width growth in the live XFCE/X11 repro

5. Invalid GTK CSS audit

Found unsupported CSS properties that GTK was ignoring, such as web-style layout rules:

• display
• flex
• gap
• align-items
• overflow
• @media

Result after cleanup:

• real improvement
• startup min width dropped in one rebuilt run from about 1068 to about 848
• startup centering improved
• but the post-navigation width drift still remained

So invalid CSS was a real issue, but not the full root cause.

6. Lazy-page / placeholder experiment

Tried making NavigationView keep placeholder children and attach only the visible real page, to test whether Adwaita was sizing itself to the widest visited page.

Result:

• no improvement
• the same page-switch sequence still produced the same width jump

This experiment was reverted.

7. Temporary startup-width mitigation

A temporary mitigation was added after the investigation:

• MangoTune now starts with a wider baseline window width of about 1300 px
• this is intentionally around the widest observed page width (Debug/post-navigation width was about 1288 px)
• goal: make the width drift much less noticeable in normal use

Important:

• this is not a root-cause fix
• it only reduces how visible the drift is by starting near the eventual grown width
• it should be treated as a stopgap until the actual GTK/Adwaita page-transition sizing cause is understood

Best Current Diagnosis

What is known:

• startup sizing had real app-side issues and was partially improved
• the remaining drift is not explained by the X11 minimum-size hint changing
• the remaining drift is not explained by previously visited NavigationView pages staying alive

Most likely remaining cause:

• a lower-level GTK/Adwaita toplevel layout negotiation behavior on page transitions
• with XFCE preserving the window's top-left position instead of re-centering or clamping it fully back on-screen

In short:

• MangoTune still has a real app-side geometry issue
• but the current remaining one appears deeper than a single page/widget declaring a large min width

Current Recommendation

Do not keep churning speculative layout changes blindly.

If this issue is revisited later, the next investigation should focus on:

1. whether Adwaita NavigationView / NavigationPage transitions are causing the toplevel to renegotiate size after the page becomes visible
2. whether GTK4 exposes a stronger post-show geometry control than set_default_size(...)
3. whether this needs an explicit X11-specific geometry preservation path on page navigation

Status

• startup placement: improved
• page-switch width drift: unresolved
• temporary mitigation: start the window near the widest observed page width so the drift is less visible
• lazy-page workaround: tested and reverted