44r0n7/mangotune
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7e95b7f95f3114217a01a2538a42c15ddf0ce0df
mangotune/PROJECT_MAP.md
T
44r0n7 08e2910b9d Initial import
2026-03-30 23:06:06 -04:00

37 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink