# PROJECT_MAP.md
# Auto-generated project index. Update this file whenever you add, remove, or significantly change a file or feature.
# Last updated: 2026-03-31 - preview update behavior is now documented and partially centralized around shared live-apply helpers (`docs/PREVIEW_UPDATE_MAP.md`, `src/ui/pages/mod.rs`), the top config strip uses an inline target picker instead of the old switch-config dialog, per-app config creation now supports a searchable bundled game-config database (`data/game_config_db.toml`) with documented maintenance workflow, the `HUD Order` page still reorders real HUD groups with live preview sync but currently uses explicit up/down controls after drag-and-drop proved unstable, MangoTune profiles are now framed as real MangoHud `.conf` files applied into the active target, and the shell/menu/popup surfaces have been tightened and moved onto app-owned compact popover/layout hooks instead of relying on stock roomy menu chrome

---

## 🗺️ Project Overview
MangoTune is a Rust GTK4/libadwaita desktop app for Linux gamers who want to configure MangoHud safely without editing `.conf` files by hand. It combines schema-aware validation, config-layer awareness, quick launch/testing, and desktop integrations in a native Linux GUI.

---

## 🏗️ Architecture Summary
`src/main.rs` starts the libadwaita app in `src/app.rs`, which creates the main window in `src/window.rs`. The window builds page widgets from `src/ui/pages/`, while config parsing/validation/resolution lives under `src/config/`, managed live-preview state now lives in `src/preview/`, system detection under `src/system/`, launcher/test-process logic under `src/launcher/`, and launcher-string/platform helpers under `src/integrations/`.

Representative flow:
startup detection/config load -> `window.rs` builds navigation + shared state -> page/widget edits mutate in-memory `AnnotatedConfig` -> validator updates inline state/save availability -> parser writes MangoHud config to disk when saved.

Dashboard preview flow:
dashboard control change -> in-memory config updates -> `src/preview/mod.rs` writes a temporary preview-only config -> MangoHud Studio preview reparses the temp file in place for ordinary edits, while true preview-window changes still relaunch without touching the user’s saved config.

---

## 📁 File & Folder Map

| Path | Role | Notes |
|------|------|-------|
| `Cargo.toml` | Rust manifest | App metadata, GTK/libadwaita/runtime dependencies |
| `Cargo.lock` | Dependency lockfile | Pinned crate graph |
| `build.rs` | Build helper | Compiles GSettings schema/assets |
| `README.md` | User-facing intro | Install, rationale, launcher/config-layer behavior |
| `LICENSE` | Project license | MIT |
| `THIRD_PARTY_LICENSES.md` | Dependency licensing | Third-party notice bundle |
| `Makefile` | Install/build convenience | Release install helpers for both `mangotune` and `mangotune-preview` |
| `ROADMAP.md` | Tactical roadmap | Tracks current UX direction, near-term milestones, and preview-renderer follow-up |
| `docs/MANGOHUD_OPTION_BEHAVIOR.md` | Verified MangoHud reference | Cross-checked against a local upstream source snapshot plus upstream `README.md` and `data/MangoHud.conf`; covers parsing/defaults/positioning rules, special-case options like `preset`, and the full currently documented option surface MangoTune now represents |
| `docs/MANGOHUD_POSITION_LAB.md` | Direct MangoHud test notes | Documents the native MangoHud position lab, expected semantics, isolated-Xorg workflow on `arch.lan`, and the right-alignment test matrix |
| `docs/PREVIEW_UPDATE_MAP.md` | Preview update contract | Maps which UI paths use debounced live apply, immediate live apply, restart, or preview-runtime-only updates, and records the current consistency rules |
| `data/` | Desktop app assets | Desktop entry, metainfo, schema, icon, CSS |
| `data/com.mangotune.MangoTune.gschema.xml` | GSettings schema | Window/app preferences, launcher defaults, remembered profile selection, and studio renderer tuning defaults such as load/FPS/VSync |
| `data/style.css` | App styling | Global CSS hooks for badges, compact dashboard cards, tool-page shells, custom control-row styling, and the newer sharper redesign-inspired visual treatment across shell chrome, sidebar/search/header controls, split/content surfaces, stock-ish GTK surfaces, custom unsaved-changes dialog chrome, section headers, chips, cards, rows, inputs, and callouts, now with a tighter shared mono badge system plus less rounding and denser spacing across the main shells, darker themed container seams between header/sidebar/content areas, plus a distinct active-conflict tint in the layer-stack strip |
| `docs/plan/` | Planning/spec docs | Architecture, design system, schema, phase plans |
| `src/main.rs` | Binary entry point | Runs `MangoTuneApp` |
| `src/bin/mangotune-preview/` | Companion preview renderer | Socket-driven Studio preview app split into `main.rs`/`renderer.rs`/`scene.rs`/`socket_api.rs`/`workload.rs`, with direct runtime controls for FPS cap, VSync, VRAM pressure, particle count, particle size, repeated surface passes (`gpu_passes`), pause state, and CPU interaction steps; the renderer still uses the heavier volumetric particle path and parallel CPU interaction work, but MangoTune now exposes the real knobs directly instead of deriving them from a synthetic `load` slider |
| `src/bin/preview_probe.rs` | Dev preview harness | Loads a saved profile, launches a controlled preview session, and makes local screenshot-based alignment debugging reproducible |
| `scripts/mangohud-position-lab.sh` | Direct MangoHud launcher | Runs MangoHud directly against `glxgears`/`vkcube`, records logs, captures window geometry, saves both app-window and full-root screenshots, and crops the root capture back to the app bounds when overlays are composited separately |
| `scripts/mangohud-position-matrix.sh` | Direct matrix runner | Generates margin-on/off variants from the standard sparse/full right-alignment profiles and captures them through MangoHud directly |
| `src/lib.rs` | Library root | Re-exports core modules for app/tests |
| `src/debug_log.rs` | In-app diagnostics buffer | Shared recent-log ring buffer used by the app shell and config parser, with copy/clear support for the Debug page |
| `src/app.rs` | Application bootstrap | GTK/libadwaita app setup, CSS load, startup detection |
| `src/window.rs` | Main shell | App state, header/actions, sidebar, accordion-style section navigation, async config-bar layer discovery, visible-page rebuilds with scroll-position preservation, a top config strip that now acts as an inline active-target picker plus read-only layer-stack summary, periodic layer-summary refresh with real detected-conflict counts, narrower default sizing and a slimmer sidebar so the app fits better on typical 16:9 desktops, dashboard-first startup without restoring the last visited page, a clearer header-led save/reload/revert/close flow, reset-to-defaults and restore-latest-safety-backup menu actions alongside safety backups, real target switching between writable global/per-app XDG configs with save/discard guarding, a sane MangoTune baseline for reset instead of an empty config, selective app-preference reset for preview/backup defaults, a save-menu `Auto backup on save` toggle instead of a mostly-empty Preferences screen, explicit shell styling hooks for the header/sidebar/config strip, app-owned compact popovers for the top-bar menus, and an Adwaita in-app unsaved-changes alert sheet instead of a standalone popup window |
| `src/preview/` | Managed live preview | Preview-session state, temp preview config writing, start/reload/restart/stop flow |
| `src/preview/mod.rs` | Preview controller | Uses a temporary preview config and launches the actual preview/test process directly, including persisted studio load/FPS/VSync settings, live socket-driven Studio runtime updates for load/FPS/VSync/VRAM/particle/pause controls, temp-config live-apply for ordinary Studio edits without signaling/restarting the process, safer studio restart behavior for window-size changes, legacy flag normalization before preview writes, explicit `horizontal_stretch=0` serialization for stretch-off sessions, effective HUD-width-based preview sizing, preview-only bounded widths for horizontal auto-layout sessions, per-metric auto-width estimation with separate sparse compact/non-compact tuning, preview-only right-anchor emulation for horizontal right-aligned layouts, and Studio-only post-launch window-size calibration so fractional desktop scaling does not throw off width-sensitive preview placement |
| `src/config/normalize.rs` | Legacy option cleanup | Shared normalization for old flag/bool encodings like `key=0`/`key=1`, normalization of old negative offsets back to unsigned values, plus cleanup for the mistaken standalone `gpu_load` / `cpu_load` keys; reused by save/load/profile/preview flows |
| `src/config/` | MangoHud config domain | Parser, schema, validation, resolver, help/types |
| `src/config/parser.rs` | Config I/O | Comment-preserving parse/write, duplicate-key collapse on parse, whitespace-normalized values, safer stale-backup handling, in-memory mutation, and explicit zero serialization for MangoHud flags that default on upstream (`horizontal_stretch`, `frametime`, `frame_timing`, `fps`, `gpu_stats`, `cpu_stats`, `legacy_layout`, `text_outline`) |
| `src/config/schema.rs` | Schema catalog | Typed definitions for MangoHud options and categories, now aligned more closely with upstream semantics including unsigned edge offsets, list-valued `preset`, and most practical upstream options that were previously missing |
| `src/config/validator.rs` | Validation rules | Value validation, dependency/conflict checks, flexible xkb-style keybind parsing, and warning-level handling for legacy `benchmark_percentiles` |
| `src/config/resolver.rs` | Layer discovery | Finds config sources and effective priority order, with user-facing layer labels tuned for clearer “built-in defaults” vs “saved global config” wording, backup-style helper `.conf` files filtered out of the detected per-app list, and reusable layer-conflict detection used by both the inspector page and the top shell summary |
| `src/config/types.rs` | Shared config types | `AnnotatedConfig`, `ConfigValue`, categories, validation types |
| `src/config/help.rs` | Help text map | UI summaries/default/tooltips plus friendly display titles and polished summaries per key, now loaded from `docs/MANGOHUD_OPTION_BEHAVIOR.md` instead of the older planning doc |
| `src/system/` | Environment detection | MangoHud/tool/display/GPU detection and XDG paths |
| `src/system/detect.rs` | Runtime detection | Checks MangoHud/tools/display server/GPU vendor |
| `src/system/paths.rs` | XDG path logic | Resolves MangoHud config locations |
| `src/launcher/` | Test launch flow | Spawns/stops/reloads MangoHud test processes |
| `src/launcher/runner.rs` | Process management | Launch, stop, reload, and retained X11 window-management helpers from the preview-lab/docking experiments |
| `src/integrations/` | External launchers/tools | Steam/Lutris/Heroic/GameMode helpers |
| `src/profiles/` | Profile storage | Save/list/load/delete real MangoHud `.conf` profile files under MangoTune's XDG config directory, including normalization of legacy values when applying one into the active target |
| `src/ui/` | UI layer | Page builders and reusable widgets |
| `src/ui/toast.rs` | Toast helper | Shared short-lived toast helper that dismisses older queued messages and gives errors/warnings a slightly longer lifetime |
| `src/ui/widgets/tool_page.rs` | Shared page/window scaffolds | Owns the shared page frame/header, section shells, callouts, and now the reusable utility-window shell used by raw editor and small modal-style utility windows so spacing/frame rules stay consistent |
| `src/ui/pages/mod.rs` | Page registry | Sidebar structure, navigation-page factory, current-config snapshots, search-result routing, and the shared preview-update helpers that now define the two main MangoHud config refresh modes: debounced live apply and immediate live apply |
| `src/ui/pages/overview.rs` | Dashboard page | Dashboard now uses the same flat page-header scaffold and outer spacing as the rest of the app, while focusing on quick everyday tuning: `Layout & Position`, `Make It Readable`, `Show These Metrics`, a compact profile utility strip with icon actions, and a single-line status strip at the bottom. Live Preview and Presets now live on their own dedicated pages under `Start`, while the dashboard keeps MangoHud-faithful unsigned offsets, uses live apply for the common metric/appearance toggles, and separates Studio runtime controls from true preview-window restart cases |
| `src/ui/pages/live_preview.rs` | Live Preview page | Dedicated `Start` page for Studio preview launch/apply/restart/stop, preview window size, scene selection, and direct runtime tuning controls without touching the saved MangoHud config, using the same flat page-header scaffold and spacing rules as the rest of the app |
| `src/ui/pages/presets_page.rs` | Presets page | Dedicated `Start` page for loading the practical starter presets/profile-backed overlay shapes without mixing them into the preview workflow, using the same flat page-header scaffold and spacing rules as the rest of the app |
| `src/ui/pages/debug.rs` | Debug page | Tool-page style diagnostics surface with a live recent-log view, current in-memory config snapshot, and clipboard actions for support/debugging |
| `src/ui/pages/conflicts.rs` | Layer conflict view | Inline cascade/conflict inspection with filter toggles, explicit empty states, and a built-in explanation/repro recipe clarifying that this page only shows layer-on-layer overrides, not validator-style logical conflicts inside a single file |
| `src/ui/pages/appearance.rs` | Layout page | Appearance-layout schema rows |
| `src/ui/pages/colors.rs` | Color page | Appearance-color schema rows regrouped into clearer palette sections, plus moved-in FPS/GPU/CPU signal palettes and friendlier color titles/subtitles sourced from schema help |
| `src/ui/pages/typography.rs` | Typography page | Appearance-typography schema rows, including secondary-size controls for supporting text |
| `src/ui/pages/performance.rs` | Display config page | FPS/frametime/general display options, plus runtime/render-stack details and Gamescope/FSR/HDR controls, with styling controls moved out to `Colors and Theme` |
| `src/ui/pages/gpu.rs` | GPU config page | GPU-specific metrics options, with signal/load colors moved out to `Colors and Theme` |
| `src/ui/pages/cpu.rs` | CPU config page | CPU metrics options, with signal/load colors moved out to `Colors and Theme` |
| `src/ui/pages/memory.rs` | Memory config page | RAM/VRAM swap display options |
| `src/ui/pages/io_network.rs` | IO/network page | Disk/network display options |
| `src/ui/pages/media_player.rs` | Media player page | Media integration metrics |
| `src/ui/pages/battery.rs` | Battery page | Battery-related overlay options |
| `src/ui/pages/keybindings.rs` | Keybinding page | Toggle/shortcut options |
| `src/ui/pages/fps_limits.rs` | FPS limits page | MangoHud frame cap/list options |
| `src/ui/pages/logging.rs` | Logging page | Logging and dump options |
| `src/ui/pages/blacklist.rs` | Blacklist page | Injection/config-exclusion options plus an advanced special-directives section for `help` and `inherit` |
| `src/ui/pages/opengl_quirks.rs` | OpenGL page | OpenGL-specific workarounds |
| `src/ui/pages/raw_editor.rs` | Raw editor | Tool-page style raw-config launcher with workspace stats, lighter-use guidance, and a richer editor pop-out now using the shared utility-window shell instead of hand-rolled framing |
| `src/ui/pages/integrations.rs` | Integrations page | Tool-page style Steam/Lutris/Heroic/GameMode helpers with live Steam command generation |
| `src/ui/widgets/toggle_row.rs` | Schema row factory | Builds switch/combo/entry rows plus explicit compact spin-button suffix controls for numeric schema fields, applies verified friendly titles/help text, surfaces inline validation, refreshes live preview after edits, routes palette-style comma-separated color fields to richer swatch controls, treats free-text entries as commit-based preview updates that only fire after an actual edit, and filters typed/pasted junk out of numeric controls at both the key and editable layers instead of only validating later |
| `src/ui/widgets/hotkey_row.rs` | Hotkey row widget | Keybinding editor rows with a modal edit dialog now using the shared utility-window shell instead of a one-off padded box |
| `src/ui/widgets/tool_page.rs` | Tool-page shell builder | Shared custom page hero/section/callout helpers used to move deep pages away from stock preferences layouts, including top-aligned section badges, explicit section-header wrappers, and chip rows that follow the redesign-inspired shell language |
| `src/ui/widgets/color_row.rs` | Color control widget | Hex + color-dialog row with shared live-preview refresh, plus palette-list swatches for comma-separated color fields like `fps_color`, `gpu_load_color`, and `cpu_load_color`; text editing now validates live but only refreshes preview on commit/focus-leave after a real edit, unset swatches now render in a neutral placeholder state, and palette entry fields live in a fixed editor cluster instead of resizing around current content |
| `src/ui/widgets/hotkey_row.rs` | Hotkey widget | Keybinding capture/edit UI with shared live-preview refresh |
| `src/ui/widgets/cascade_view.rs` | Conflict widget | Cascade/layer visualization plus filter-aware visibility helpers |
| `src/ui/widgets/validation_label.rs` | Validation helper | Inline row error presentation |
| `src/ui/widgets/color_utils.rs` | Shared color helpers | Hex/RGBA conversion utilities shared by dashboard and color rows |

---

## 🧭 Hot Paths
- Add or change a major window/workflow: `src/window.rs`, `src/ui/pages/mod.rs`, affected page module(s), `data/style.css`
- Change a MangoHud option’s validation/type/category: `src/config/schema.rs`, `src/config/help.rs`, `src/config/validator.rs`, affected page in `src/ui/pages/`
- Change config parsing or write behavior: `src/config/parser.rs`, `src/config/types.rs`, parser tests
- Change launcher/test-preview behavior: `src/preview/mod.rs`, `src/bin/mangotune-preview.rs`, `src/launcher/runner.rs`, `src/ui/pages/overview.rs`, `data/com.mangotune.MangoTune.gschema.xml`, `Makefile`
- Change direct MangoHud validation flow: `scripts/mangohud-position-lab.sh`, `scripts/mangohud-position-matrix.sh`, `docs/MANGOHUD_POSITION_LAB.md`
- Change profile behavior: `src/profiles/mod.rs`, `src/ui/pages/overview.rs`
- Change config-layer/conflict behavior: `src/config/resolver.rs`, `src/ui/pages/conflicts.rs`, `src/window.rs`
- Change desktop app settings/preferences: `data/com.mangotune.MangoTune.gschema.xml`, `build.rs`, `src/window.rs`
- Change integration strings/behavior: `src/integrations/*.rs`, `src/ui/pages/integrations.rs`

---

## 🔑 Key Concepts & Domain Terms
- `AnnotatedConfig`: in-memory MangoHud config preserving file lines plus indexed option state
- Config layer/cascade: MangoHud config priority stack (env > app-local > per-app > global > defaults)
- `SchemaEntry`: typed definition for one MangoHud option, including category/dependencies/conflicts
- Validation state: per-key result map used to block invalid saves and surface inline errors
- Managed live preview: a preview-only MangoHud config generated from unsaved in-memory edits and applied to a real preview process
- Companion renderer: `mangotune-preview`, a dedicated animated preview executable for MangoHud tuning
- Test launcher: helper flow that launches a real process with MangoHud enabled for verification
- Profile: a saved real MangoHud `.conf` file stored under MangoTune’s XDG config dir and applied into the active config target on demand

---

## 🔗 Persistence / Data Contracts
- MangoHud global config default: `~/.config/MangoHud/MangoHud.conf` (resolved via `src/system/paths.rs`)
- Profile storage: `~/.config/mangotune/profiles/*.conf` unless `MANGOTUNE_PROFILES_DIR` overrides it
- GSettings schema: `com.mangotune.MangoTune`
- Preferred preview scene setting: GSettings key `preview-scene` now defaults to `studio`
- Studio preview tuning settings: GSettings keys `preview-studio-scene`, `preview-fps-cap`, `preview-vsync`, `preview-vram-pressure`, `preview-particle-count`, `preview-particle-size`, `preview-gpu-passes`, and `preview-interaction-steps` (`preview-load` remains only as a legacy compatibility key)
- Companion renderer binary: `mangotune-preview` is discovered via env override, sibling binary, or `PATH`
- Launcher environment contract: MangoTune sets `MANGOHUD=1` and `MANGOHUD_CONFIGFILE=<config path>` for launched preview/test processes
- Preview temp config contract: live preview writes a temporary MangoHud config under the system temp dir instead of modifying the user’s saved config, and forces `no_display` off for preview visibility
- Config file format contract: MangoHud `.conf` syntax with comment preservation and “last duplicate wins” behavior
- Game config hint DB: bundled at `data/game_config_db.toml`, generated/maintained via `scripts/build_game_config_db.py`, documented in `docs/GAME_CONFIG_DB.md`, and used by the per-app config creation flow to search games and suggest likely executable/config names

---

## 🖥️ User-Facing Command / Feature Surface
- Main dashboard with live preview, workspace status, visual position picking, smarter edge-gap controls, quick appearance controls, starter presets, common metrics, profile save/restore/delete, page-jump shortcuts, preview window size controls, and a denser compact layout that uses less vertical space
- Header-led save flow with `Save Config` as the single primary save surface, plus secondary actions for saving a copy, discarding unsaved changes, and creating a safety backup
- Sidebar navigation with search plus accordion-style section expansion, calmer section naming/order, and a less heavy “config layer” top bar
- Startup now always opens on the dashboard instead of restoring the last visited page
- Deep settings pages with a custom control-deck shell instead of plain stock preferences groups for the main appearance/display/behavior surfaces
- Config layer selector + conflict visibility
- Appearance controls: layout, colors, typography
- Metrics controls: performance, GPU, CPU, memory, I/O/network, media, battery
- Behavior controls: keybindings, FPS limits, logging, blacklist
- Advanced tools: OpenGL quirks, raw editor
- Live preview/testing: managed Studio-only preview from unsaved edits using `mangotune-preview`, with dashboard-level defaults, auto-refreshing status, dashboard window-size controls, preview-only `no_display` override, explicit `horizontal_stretch=0` writes when stretch is disabled, effective-HUD-width window sizing for horizontal auto-layout, preview-only right-offset compensation for right-aligned horizontal layouts, Studio-specific post-launch width calibration for scaled desktops, temp-config live-apply for ordinary Studio config edits, debounced live preview writes for high-frequency controls, safer studio restart behavior for true window-size changes, wheel-safe dashboard controls, live runtime updates for Studio load/FPS/VSync, advanced Studio runtime controls for particle density/VRAM pressure/pause, and an in-window control strip plus visible key hints for the studio renderer
- Integrations: Steam, Lutris, Heroic, GameMode
- Profiles: save the active config target as a profile, then apply a profile back into the active target

---

## 🧪 Test Coverage Map
- Unit tests live inline in Rust modules such as `src/config/parser.rs`, `src/launcher/runner.rs`, `src/profiles/mod.rs`, `src/integrations/steam.rs`, and `src/ui/pages/overview.rs`
- Parser/schema/validator/resolver changes should get module tests updated where the logic lives
- Launcher/preview behavior changes usually require tests in `src/launcher/runner.rs`, `src/preview/mod.rs`, `src/bin/mangotune-preview.rs` when practical, and any overview helpers that drive preview state
- UI shell/page layout currently has light automated coverage; visual/interaction changes need manual GTK testing in addition to `cargo test`

---

## 🧩 Feature Areas & Ownership Map
- **App shell and navigation**: `src/app.rs`, `src/window.rs`, `src/ui/pages/mod.rs`, `data/style.css`
- **MangoHud config engine**: `src/config/`
- **Runtime/system detection**: `src/system/`
- **Preview/test launching**: `src/preview/`, `src/bin/mangotune-preview.rs`, `src/launcher/`, `src/ui/pages/overview.rs`
- **Profiles**: `src/profiles/`, `src/ui/pages/overview.rs`
- **Desktop integrations**: `src/integrations/`, `src/ui/pages/integrations.rs`
- **Page-specific UI**: `src/ui/pages/`
- **Reusable controls**: `src/ui/widgets/`

---

## ⚠️ Known Issues / Tech Debt
- Right-side horizontal HUD placement still needs one more deliberate real-user validation pass for the remaining edge cases
- Main-window geometry drift on XFCE/X11 is only mitigated, not root-caused yet; see `docs/WINDOW_GEOMETRY_INVESTIGATION.md`
- UI test coverage is still light, so larger GTK interaction changes continue to rely heavily on manual validation

---

## 🔄 Update Triggers
Update this file when:
- a command, route, page, or feature area is added/removed/renamed
- a meaningful source file/module is added/removed/renamed
- a persistence format, config location rule, or launcher contract changes
- architecture changes materially
- a major known issue is discovered or resolved

Do not update this file for:
- tiny wording tweaks
- purely local refactors with no ownership/structure impact
- dependency bumps with no workflow impact

---

## 📝 Change Log (agent session)
- 2026-03-22 Initial map created
- 2026-03-22 Added `src/preview/mod.rs`, replaced Overview with a dashboard-first live-preview workflow, and removed the old launch-bar widget
- 2026-03-22 Added `ROADMAP.md`, persisted the preferred preview scene, and expanded the dashboard with common metric toggles
- 2026-03-22 Added searchable sidebar navigation, dashboard page-jump actions, and the `mangotune-preview` companion renderer
- 2026-03-22 Added dashboard-level controls for the studio preview renderer's scene, load factor, and FPS cap
- 2026-03-22 Switched preview launching to direct-process tracking and added in-window studio controls with more distinct scene rendering
- 2026-03-22 Added automatic preview-state refresh in the dashboard plus safer reload fallback behavior
- 2026-03-22 Added one-click starter presets to the dashboard for common overlay setups
- 2026-03-22 Collapsed deeper sidebar sections by default while keeping search fully discoverable
- 2026-03-22 Added a dashboard workspace-status card with validation summary, save state, runtime details, and quick actions
- 2026-03-22 Made studio preview reload restart safely and changed the sidebar to auto-collapse other sections when opening a new one
- 2026-03-22 Forced preview visibility when saved configs use `no_display` and stopped pinning the scene selector after previews stop
- 2026-03-22 Added screen-clamped preview docking, dashboard controls for preview window size, and a shared custom shell for the main deep settings pages
- 2026-03-22 Fixed the validation-save deadlock, moved layer conflicts inline, added profile deletion, and made dashboard preview controls safer to scroll/use
- 2026-03-22 Moved raw editor and integrations onto the custom shell and fixed Steam launch-option generation to follow the selected method
- 2026-03-23 Gave right-aligned previews extra width and stopped side-docking them to reduce off-screen HUD placement failures
- 2026-03-23 Added explicit empty states for filtered conflicts/integration detection and surfaced profile-folder open failures instead of failing silently
- 2026-03-23 Extracted shared color conversion helpers and deduplicated the saved-snapshot restore path in window actions
- 2026-03-23 Moved config-layer discovery off the synchronous shell path and hardened parser round-trips against duplicate keys and accidental value whitespace
- 2026-03-23 Rebuilt visible pages from shared state on navigation, refreshed live preview from non-dashboard editors, widened right-aligned horizontal preview safety margins, narrowed default shell sizing, and made stale `.mangotune.bak` paths non-fatal during save
- 2026-03-23 Normalized legacy flag values across preview/profile/reload paths and refreshed the visible page + preview after revert/reload/profile restore so stale `horizontal_stretch=0`-style states don’t linger
- 2026-03-23 Added a preview-only bounded width fallback for horizontal auto-layout previews, renamed/moved the sidebar layer viewer section, softened config-bar labels, narrowed the default shell width again, and simplified raw-editor guidance
- 2026-03-23 Preserved scroll position during visible-page rebuilds, removed the extra dashboard guidance card, tightened dashboard spacing, and narrowed sidebar/window defaults further
- 2026-03-23 Fixed disabled `horizontal_stretch` serialization, made preview reload use the current computed width, reset `horizontal_stretch` in dashboard presets, and stopped dashboard polling timers from leaking across page rebuilds
- 2026-03-24 Corrected the MangoHud behavior references against the deep-research report and local upstream source, including `preset`, `benchmark_percentiles`, `inherit`, and keybind/default caveats
- 2026-03-24 Aligned MangoTune's live schema and validation with the corrected MangoHud reference by making offsets unsigned, broadening keybind parsing, warning on legacy `benchmark_percentiles`, treating `preset` as a list-valued upstream option, and adding the missing practical upstream options that belong in the GUI
- 2026-03-24 Surfaced the last documented upstream options in the UI too, including runtime/Gamescope sections on the Performance page, secondary typography sizing, and an advanced Blacklist subsection for special directives like `help` and `inherit`
- 2026-03-24 Stopped text-entry fields from reloading the preview on every keystroke, added a saveable-config gate before preview reloads, and tightened threshold-color dependencies so incomplete threshold setups do not immediately destabilize the preview
- 2026-03-23 Added preview-only right-offset compensation for horizontal right-aligned layouts after stretch-off was confirmed fixed but right alignment still failed
- 2026-03-23 Added Studio-only post-launch preview-size calibration so right-aligned horizontal HUD placement can use the actual scaled Studio window width instead of only the requested logical width
- 2026-03-24 Expanded the MangoHud source-truth docs with explicit `full` exclusions, offset parsing quirks, and isolated-X capture limitations after direct-lab verification on `arch.lan`
- 2026-03-24 Switched shared control rows, colors, and keybindings to friendly display titles sourced from the verified MangoHud reference instead of raw key-shaped labels
- 2026-03-24 Added polished UI-facing summaries for common MangoHud options so shared rows and keybinding descriptions read like product copy instead of schema text
- 2026-03-24 Simplified the shell save flow by making the header the single primary save surface, softening layer-bar wording, and always starting the app on the dashboard
- 2026-03-24 Moved FPS/GPU/CPU color editors out of the telemetry pages and consolidated them under `Colors and Theme` so metric pages focus on what is shown while appearance pages own styling
- 2026-03-24 Regrouped `Colors and Theme` into clearer sections for core palette, hardware labels, signal thresholds, and extra integrations/status colors
- 2026-03-25 Replaced the placeholder hotkey toggler with a real modal keybind editor, guarded color-entry/swatch synchronization to avoid recursive GTK edit loops, and corrected GPU/CPU threshold-color dependencies to point at `gpu_stats` / `cpu_stats`
- 2026-03-25 Switched ordinary Studio preview edits from restart-driven reloads to debounced temp-config rewrites so MangoHud can reparse changes in place without relaunching the window
- 2026-03-25 Changed dashboard profile restore and presets to use the same Studio live-apply path instead of forcing a preview restart, removed the redundant preview-renderer label from the dashboard card, and added save-menu actions for reset-to-defaults and restore-latest-safety-backup
- 2026-03-26 Removed the unreliable preview-docking preference from the UI, switched dashboard offset controls back to MangoHud’s real unsigned offset semantics, normalized legacy negative offsets on load, and started writing explicit `=0` for upstream default-on flags like `frametime` and `frame_timing`
- 2026-03-24 Simplified preview-only right-anchor emulation by dropping fake vertical offsets and adding a small no-margin right-edge safety for horizontal right-aligned layouts
- 2026-03-24 Tried preserving native MangoHud right-side positions directly, but reverted that change after it made horizontal previews disappear again; preview-side right-anchor emulation remains the last usable path while MangoHud-native behavior is being investigated separately
- 2026-03-24 Added a direct MangoHud position lab and matrix runner so margin/compact/right-anchor behavior can be validated outside MangoTune on a real X11 session, including an isolated-Xorg workflow for `arch.lan`