docs: refresh preview update guidance and repo map
This documents the current preview apply contract, updates the project map to match the live code paths, and adds the local scratchpad issue tracking reminder to the workspace instructions.
This commit is contained in:
+8
-7
@@ -1,6 +1,6 @@
|
||||
# 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
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
@@ -34,6 +34,7 @@ dashboard control change -> in-memory config updates -> `src/preview/mod.rs` wri
|
||||
| `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 |
|
||||
@@ -46,7 +47,7 @@ dashboard control change -> in-memory config updates -> `src/preview/mod.rs` wri
|
||||
| `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/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 |
|
||||
@@ -67,8 +68,8 @@ dashboard control change -> in-memory config updates -> `src/preview/mod.rs` wri
|
||||
| `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/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 |
|
||||
@@ -178,9 +179,9 @@ dashboard control change -> in-memory config updates -> `src/preview/mod.rs` wri
|
||||
---
|
||||
|
||||
## ⚠️ 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
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user