# 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-28 - the old single-file Studio preview binary has been replaced with a socket-driven `mangotune-preview` companion under `src/bin/mangotune-preview/`, MangoTune now passes studio defaults through env vars and hot-reloads the preview over a Unix socket instead of only relying on CLI args/restarts, the dashboard/help/docs have been updated to match the new preview contract, MangoHud option help still comes from a verified `docs/MANGOHUD_OPTION_BEHAVIOR.md` reference cross-checked against a local upstream source snapshot plus upstream README/config docs, the schema/validator follow MangoHud semantics more closely (unsigned `offset_x`/`offset_y`, flexible xkb-style keybind validation, legacy warning for `benchmark_percentiles`, upstream `preset` as a list-valued special option, the full documented option surface now represented in the live schema, threshold-color toggles now declare the supporting metric/value/color dependencies they actually need, MangoTune strips the mistaken standalone `gpu_load` / `cpu_load` keys because MangoHud itself rejects them as top-level options, rewrites stale profile aliases like `compact`/`stretch` into modern `hud_compact`/`horizontal_stretch`, default-on MangoHud flags now serialize as explicit `=0` when disabled, and negative legacy offsets are normalized back to unsigned values), Studio preview sessions still calibrate against the actual scaled window size after launch, preview-only right-anchor emulation remains in place because fully native right-side positions regressed horizontal preview visibility, horizontal auto-layout previews still get a bounded width estimate, ordinary Studio config edits now rewrite the temp `MANGOHUD_CONFIGFILE` and rely on MangoHud's file watcher instead of restarting the window, those live preview writes are GTK-debounced to reduce churn, preset/profile/revert-style config replacements now use the same live-apply path where possible, the save menu now includes reset-to-defaults, restore-latest-safety-backup, and a real `Switch Active Config…` action, resetting still rebuilds a sane MangoTune baseline config instead of leaving an effectively empty config, explicit config switching now changes the actual editable target in `state.config.path` with save/discard guarding instead of overloading the layer-stack strip, the unreliable preview-docking preference has been removed from the UI, backup-style helper `.conf` files are filtered out of the detected per-app layer list, the top config strip now refreshes into a read-only layer-stack summary with detected conflict counts instead of a static status label or fake selector, Studio preview now exposes direct renderer controls for scene, FPS cap, particle count, particle size, repeated GPU passes, CPU interaction steps, VRAM pressure, VSync, and pause state instead of the older derived `load + advanced` model, with lower defaults (`Dark` scene, `120 FPS` cap, `1000` particles, `0.03` particle size, `1` pass, `0` VRAM pressure, `0` CPU interaction) so the built-in preview starts safely on faster GPUs and stays visually spread instead of collapsing into a tiny edge-on cluster; the particle renderer now uses standard alpha blending instead of additive bloom so larger particles remain readable against the darker scene, and the scene selector is exposed in the dashboard while also updating the running preview over the socket, app toasts now clear older queued messages and use shorter lifetimes by default, palette-style color fields get swatch controls outside the dedicated colors page too, unset swatches render as neutral placeholders instead of alarming red defaults, comma-separated palette entry fields now live in a fixed editor cluster with stable width instead of collapsing around short values, swatch edits now commit through the same validation/save-state path as text edits, section badges now share a tighter mono sizing system, the dashboard profile picker remembers the last selected profile and mirrors that choice into the save-name field, numeric controls now use compact explicit spin-button fields with typed/pasted junk filtered at the editable layer, the Layer Conflicts page now explains what counts as a true layer collision and gives a concrete repro recipe, the dashboard save menu now offers explicit config-target switching while the top strip stays a read-only layer-stack summary keyed to the actual active file, the new `HUD Order` page under `Tools` reorders currently enabled visible HUD blocks by moving their real config lines up and down with live preview refresh, and the dashboard preset buttons now load the real `Benchmark` / `Competitive` / `Performance` / `Streaming` profile files into the current workspace when those profiles exist, with the older built-in mappings kept only as fallback safety

---

## 🗺️ 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 |
| `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, calmer config-bar language that now frames the strip as a detected read-only layer stack summary instead of an editable target selector, 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, an explicit `Switch Active Config…` flow that lets users move the real editable target between the 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, 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, shared live-preview helper, calmer section naming/order, a debounce-backed temp-config apply path for ordinary Studio edits, explicit restart flow that can still pass the current preview width into preview refreshes, and a saveable-config gate so invalid intermediate edits do not crash the preview |
| `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 and the most common metric/appearance toggles |
| `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
- The dedicated preview renderer is still early and could use even richer scene/load presets plus deeper in-preview UI polish
- The preview renderer still needs more ambitious scene design and richer in-window guidance beyond the current first pass
- UI test coverage is limited; large UX changes currently 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`