# 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