mangotune/PROJECT_MAP.md

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