# MangoHud Position Lab

This is a direct MangoHud test harness for debugging positioning behavior outside MangoTune's
preview pipeline.

## Why

When right-aligned horizontal preview behavior looks wrong, the first question is whether the
problem is in MangoTune's preview math or MangoHud itself. This lab runs MangoHud directly
against a simple test app so the behavior can be compared without preview-only overrides.

## Script

Use:

```bash
scripts/mangohud-position-lab.sh <config> [glxgears|vkcube] [output_dir]
```

Examples:

```bash
scripts/mangohud-position-lab.sh ~/.config/mangotune/profiles/zz_test_right_sparse_top.conf glxgears
scripts/mangohud-position-lab.sh ~/.config/mangotune/profiles/zz_test_right_full_top.conf vkcube /tmp/mh-lab/full-top
```

The script:
- launches MangoHud directly
- records stdout/stderr to `run.log`
- tries to dump the X window tree to `xwininfo.tree`
- tries to capture window geometry and a screenshot when `xdotool`/`import` are available
- honors `DISPLAY`, `XAUTHORITY`, `WAIT_SECS`, `WIDTH`, and `HEIGHT` from the environment

## Matrix runner

For the standard right-alignment repro set, use:

```bash
scripts/mangohud-position-matrix.sh [vkcube|glxgears] [output_dir] [profile_dir]
```

Examples:

```bash
scripts/mangohud-position-matrix.sh vkcube /tmp/mh-matrix
DISPLAY=:1 XAUTHORITY=/root/.Xauthority scripts/mangohud-position-matrix.sh vkcube /tmp/mh-matrix /home/aaron/mangotune-test-profiles
```

This generates both margin-on and margin-off variants for the standard right-alignment test
profiles and captures each case directly through MangoHud.

## Suggested Test Matrix

Run at least these profile families:

1. `zz_test_right_full_top.conf`
2. `zz_test_right_sparse_top.conf`
3. `zz_test_right_sparse_middle.conf`
4. `zz_test_right_sparse_compact_top.conf`
5. `zz_test_right_sparse_compact_middle.conf`

Then compare:
- `hud_no_margin` on vs off
- `hud_compact` on vs off
- sparse vs fuller layouts
- `top-right` vs `middle-right`

Recommended validation order:

1. `full` top-right, margin on
2. `full` top-right, margin off
3. `sparse` top-right, margin on
4. `sparse` top-right, margin off
5. `sparse_compact` top-right, margin off
6. `sparse` middle-right, margin off
7. `sparse_compact` middle-right, margin off

## Isolated Xorg on arch.lan

When local testing would interrupt the user desktop, `arch.lan` can run a separate Xorg on
another VT and use that for direct MangoHud captures:

```bash
ssh aaron@arch.lan
sudo -n xinit /bin/bash -lc 'xsetroot -solid black; while :; do sleep 3600; done' \
  -- /usr/bin/Xorg :1 vt8 -nolisten tcp -noreset
```

Then from another shell:

```bash
ssh aaron@arch.lan '
  DISPLAY=:1 XAUTHORITY=/root/.Xauthority \
  /path/to/mangotune/scripts/mangohud-position-matrix.sh \
    vkcube /tmp/mh-matrix /home/aaron/mangotune-test-profiles
'
```

That keeps the direct MangoHud investigation isolated from the main desktop session.

## Expected MangoHud Semantics

From MangoHud's upstream README:
- `position=` supports `top-right`, `middle-right`, and `bottom-right` directly
- `horizontal` enables horizontal layout
- `horizontal_stretch` stretches the background to the screen width in horizontal mode
- `hud_no_margin` removes margins around MangoHud
- `offset_x` and `offset_y` are generic HUD position offsets
- `width=` overrides the automatically computed HUD width

That means MangoTune should be conservative about inventing extra right-anchor behavior. If
MangoHud itself has a quirk here, MangoTune should document or surface it rather than baking in
fragile compensations unless absolutely necessary.

## Upstream source findings

From MangoHud upstream `src/overlay.cpp` and `src/overlay_params.cpp`:

- Default edge margin is `10.0f`.
- The margin is forced to `0.0f` whenever **any** of these are true:
  - `offset_x > 0`
  - `offset_y > 0`
  - `hud_no_margin` is enabled
- For right-side anchors, MangoHud positions the HUD with:

```cpp
x = display_width - window_size.x - margin + offset_x
```

That means:
- right anchors are native in MangoHud
- positive `offset_x` pushes a right-anchored HUD farther right, not inward
- because `offset_x` is parsed as unsigned, MangoHud cannot use a negative right-anchor offset
  to nudge the HUD left from `top-right` / `middle-right` / `bottom-right`

Also note:

- `horizontal_stretch` defaults to `true` upstream, so `horizontal_stretch=0` must be written
  explicitly when the user disables it
- `offset_x` / `offset_y` are parsed as unsigned values upstream

These semantics should be treated as source-of-truth before adding any MangoTune-side
compensation.

## Capture caveat

On the isolated remote Xorg lab, direct screenshot methods can still miss MangoHud's overlay
entirely while capturing the app window correctly. This includes:

- ImageMagick `import` against the app window
- ImageMagick `import -window root` against the full desktop
- `ffmpeg -f x11grab` style X11 captures

So:

- direct launch/log/geometry capture is reliable there
- direct pixel capture of the overlay is not yet a trustworthy automated oracle
- if visual confirmation matters, a manual screenshot on a real desktop session is still the
  most reliable check