gamewrap/docs/roadmap.md

# gamewrap Roadmap

## Purpose

`gamewrap` is a Steam-first Linux game launcher wrapper that keeps Steam launch options short while moving launch behavior into a readable, persistent config.

The project is designed to make features like MangoHud and GameMode easier to use without requiring users to remember long launch commands, environment variables, or per-game flag combinations.

Core product goals:
- keep Steam launch options simple
- prefer human-friendly configuration over flag-heavy one-off commands
- fail clearly when launch requirements are not met
- keep runtime overhead low
- support both quick default usage and deeper profile-based customization

## Current Direction

The current preferred Steam usage is:

```text
gamewrap %command%
```

The preferred low-maintenance install approach is:
1. install with `cargo install`
2. ensure `~/.cargo/bin` is on PATH in the desktop session

This lets Steam resolve `gamewrap` by name without committing to long-term package maintenance yet.

## Current Feature Set

Implemented features:
- Steam-first launcher flow with `gamewrap %command%`
- Default launch mode with MangoHud and GameMode
- Friendly setting names for all launch options
- Named game-specific profiles (flat two-tier: global defaults + per-game overrides)
- Per-profile environment variable overrides (`profile env set/unset/list/clear`)
- Manual executable-to-profile bindings
- Observed game history with launch count, timestamps, and display names
- Play time tracking per game (when post-launch hook is configured)
- `game rename` for human-readable game names
- `game forget` to remove entries from observed history
- `gamewrap last` to see the most recently played game
- gamescope Wayland compositor integration
- vkBasalt post-processing integration
- FPS cap via MangoHud
- Proton esync/fsync/large-address-aware controls
- Pre-launch and post-launch shell hooks
- `status` command
- `doctor` preflight checks with color-coded output
- `dry-run` launch plan preview
- `config edit` to open config in `$EDITOR`
- Config and profile export/import for sharing
- `notify test` for graphical notification verification
- ANSI color output (respects NO_COLOR, CLICOLOR, CLICOLOR_FORCE)
- Shell completion with live candidates (profiles, games, settings)
- Clear runtime dependency checks and actionable error messages

Friendly settings supported:
- `mangohud`, `gamemode`, `steam-host-libs`, `game-libs`, `verbose`
- `gamescope`, `gamescope-width`, `gamescope-height`, `gamescope-fps`
- `fps-cap`, `vkbasalt`
- `esync`, `fsync`, `large-address-aware`
- `pre-launch`, `post-launch`
- `env-vars` (via `profile env` subcommands)

## v1 Done Criteria

The project can be considered functionally complete for v1 when all of the following are true:

- [x] Steam launch works reliably with the chosen install method
- [x] MangoHud enable/disable works correctly
- [x] GameMode enable/disable works correctly
- [x] `doctor`, `status`, and `dry-run` are trustworthy for normal troubleshooting
- [x] launch failures are visible and understandable
- [x] README and CLI help are clear enough for a new user
- [x] no major known bugs remain in the core launch path
- [x] native Linux games validated in real testing
- [x] Proton / Windows games validated in real testing
- [x] one intentional failure case tested

**v1 complete — 2026-05-31.**

## Validation Still Desired

Real-world validation to finish before calling v1 done:
- test at least one native Linux game
- test at least one Proton / Windows game
- test one intentional failure case
- confirm Steam launch behavior with the preferred install method
- confirm notification behavior for internal launcher failures
- confirm that profile binding works on an actual game executable

## Packaging and Distribution Plan

Long-term packaging direction:
- distro-native packages first
- `cargo install` remains supported but is not the ideal end-user distribution path

Planned packaging targets:
- Arch Linux / AUR
- Debian / Ubuntu
- Fedora / RPM

Packaging goals:
- install `gamewrap` to a system-visible path such as `/usr/bin/gamewrap`
- allow Steam launch options to use `gamewrap %command%`
- avoid requiring absolute paths for normal packaged installs

Packaging status:
- deferred for now in favor of low maintenance
- still an explicit project direction, not abandoned

Repository:
- Gitea: https://git.44r0n.cc/44r0n7/gamewrap.git (canonical for now)
- Issue tracker: https://git.44r0n.cc/44r0n7/gamewrap/issues

Still undecided:
- homepage URL
- release hosting / distribution channels
- whether to mirror to GitHub

## Deferred Feature Expansion

Features that were deferred from the initial scope and are now implemented:
- ✓ `gamescope` integration
- ✓ `vkBasalt` integration
- ✓ Custom environment presets (per-profile env var overrides)
- ✓ Proton and Wine compatibility toggles (esync, fsync, large-address-aware)

Features still deferred:
- Benchmark and recording profile presets (named templates that bundle several settings)
- Additional launcher helpers beyond the current set
- **Profile description field for community sharing** — add `description: Option<String>` to `ProfileConfig` and `SharedProfileFile`, shown at the top of exported `.gamewrap-profile.toml` files so ProtonDB/forum posts are self-documenting. CLI: `gamewrap profile describe <name> <text>` and `profile clear-describe <name>`. Preserved through import and shown in `profile show`/`profile list`. No tags, AppIDs, or author fields — those belong on the posting platform, not in the file.

## Recommended Expansion Order

Items 1–3 are now implemented. Remaining if development continues:

4. Benchmark / recording profile presets — named templates that bundle several settings into a shareable starting point
5. Graphics API detection (advisory only — see separate section)
6. Additional launcher helpers only if they clearly improve the main use case

## Future Proton and Compatibility Controls

One planned expansion area is support for common Steam/Proton launch adjustments that users often copy from compatibility guides, community comments, or ProtonDB reports.

Examples of future controls that may be worth supporting:
- DXVK-related toggles
- VKD3D-related toggles
- esync/fsync toggles
- Wine debug environment controls
- fullscreen and compositor-related tweaks
- launch-time environment overrides for specific games
- Proton-specific compatibility presets that bundle several known-good settings

This should not become a free-form dump of obscure environment variables by default. The intended direction is:
- expose the most common useful adjustments with friendly names
- keep raw environment overrides available only as an advanced escape hatch if ever added
- prefer reusable presets and profiles over forcing users to remember low-level variables
- use `doctor` and help text to explain what a toggle actually changes

Potential sources of future ideas:
- recurring compatibility patterns seen in ProtonDB reports
- common launch command snippets shared in Linux gaming communities
- settings that repeatedly solve real issues in actual testing

Guardrails for this work:
- do not blindly mirror every ProtonDB workaround
- avoid adding toggles that are highly game-specific unless they can be grouped into a sensible preset model
- keep the main UX readable and non-intimidating
- require a clear explanation in help text for every added compatibility control

## Graphics API Detection (Maybe)

A potential future addition: detect a game's graphics API at launch time and use that to surface
warnings or skip inapplicable settings. Not on the roadmap yet, but worth revisiting.

Specific cases where it would help:

- **vkBasalt safety** — vkBasalt only works with Vulkan. For OpenGL or WineD3D games, `ENABLE_VKBASALT=1`
  silently does nothing. Detection could skip the env var or warn in `doctor`.
- **Gamescope compatibility** — Gamescope is Vulkan-only. If `gamescope = on` is set but the game uses
  OpenGL, it will fail or fall back unexpectedly. A preflight warning would catch this.
- **DXVK vs VKD3D-Proton env hints** — Per-profile overrides like `DXVK_ASYNC 1` only matter for D3D9/10/11
  games (DXVK). D3D12 games use VKD3D-Proton with a different set of vars. Detection could surface
  a mismatch warning when running `doctor`.
- **MangoHud invocation method** — MangoHud works as both a command prefix and an env var injection. The
  env var path works better for some Vulkan games. Detection could pick the right method.

How detection would likely work in practice:
- Check for `d3d9.dll`/`d3d11.dll`/`dxgi.dll` in the game directory → DXVK (D3D9/10/11 via Vulkan)
- Check for `d3d12.dll` → VKD3D-Proton (D3D12 via Vulkan)
- Check for `.dxvk-cache` / `.d3d12.cache` files → reliable secondary signals
- Native Linux ELFs: inspect imported libs with `ldd` or `file` — harder, lower priority

Guardrails if this is ever added:
- Detection should be advisory only — never silently override user config
- Emit warnings in `doctor` and `dry-run`, not at actual launch time
- Degrade gracefully when detection is inconclusive (most common case)
- Do not make profile selection automatic based on detection results

The "avoid" note in Product Boundaries refers to _automatic profile selection_ based on detection,
not to using detection for diagnostics and warnings. Those are meaningfully different.

## Product Boundaries

Things `gamewrap` should continue to optimize for:
- simple Steam usage
- low system impact
- minimal always-on behavior
- understandable configuration
- useful diagnostics

Things to avoid unless clearly justified:
- automatic profile selection based on graphics API or runtime detection (advisory warnings are fine)
- heavy background services
- large dependency trees just to support optional extras
- turning the project into a general desktop/session manager

## Installation Strategy for Now

Short-term recommended install strategy:
- `cargo install --path . --force` — installs to `~/.cargo/bin/gamewrap`
- Ensure `~/.cargo/bin` is on PATH in your desktop session so Steam can find it by name

Reason:
- low maintenance
- easy updates
- Steam can resolve `gamewrap` by name if `~/.cargo/bin` is on session PATH
- no distro package maintenance burden yet

## Dependency Maintenance (post-1.0)

Checked 2026-05-31. Most crates are on current patch versions via `cargo update`. Two deferred upgrades:

- **toml 0.8 → 1.x**: top-level `from_str`/`to_string_pretty` likely unchanged but the 1.x release has low-level Deserializer/Serializer API changes. Verify against 1.x docs before upgrading. Low urgency — 0.8 is still maintained.
- **owo-colors 1.x → 4.x**: major version jump. Our usage (`.green()`, `.bold()`, `.dimmed()`, `.cyan()`, `OwoColorize`) is fundamental and unlikely to have changed, but read the changelog before upgrading. Low urgency — 1.x works fine.
- **clap_complete `unstable-dynamic` feature**: may have been renamed to `unstable-command` in 4.6.x. Run `cargo update && cargo test` — if it fails, rename the feature flag in `Cargo.toml`. Low risk, one-line fix if needed.

## Notes for Future Work

Before starting packaging or deferred features, re-check:
- whether the install story should remain PATH-based for personal use
- whether the project is going public
- whether package maintenance is worth the overhead
- whether v1 behavior is stable enough to freeze the main CLI/config model

---

## Post-v1 Backlog

Logged 2026-06-06. Priority order reflects dependencies — B1 sets naming used by B5, and JSON output (B6 Phase 1) is prerequisite for any GUI work.

### B1 + B4 — Settings grouping, tool-prefixed names, help system overhaul

**Problem:**
- `gamewrap help settings` outputs 36 settings in a flat, ungrouped list with no visual separation by tool
- `overlay` (MangoHud) and `performance` (GameMode) have no tool prefix while every gamescope/vkbasalt/mangohud-log setting already does
- A gamescope configuration note currently sits orphaned between log options and the gamescope settings block in help output

**Proposed changes:**
- Rename `overlay` → `mangohud` (the MangoHud enable/disable toggle), consistent with `mangohud-log`
- Rename `performance` → `gamemode` (the GameMode enable/disable toggle)
- Group `gamewrap help settings` into tool-based sections: **Core**, **MangoHud**, **GameMode**, **Gamescope**, **vkBasalt**, **Proton/Wine**, **Hooks & Logging**
- Move the gamescope configuration note into the Gamescope section header (fixes B4)
- Enhance `topic_text()` in `src/help.rs` to accept an optional tool filter: `gamewrap help settings gamescope`
- Propagate renames everywhere: `Settings` struct fields, CLI parser, `config/keys.rs`, TOML serialization, shell completion, tests, README, docs
- Add a migration path for existing configs using the old names (clear error pointing to new name, or silent rename on load)

**Note:** Breaking change — existing config files and profiles using `overlay` or `performance` will need migration. Sets the naming foundation for B5.

**Key files:** `src/help.rs`, `src/config/schema.rs`, `src/config/keys.rs`, `src/config/mod.rs`, `src/cli.rs`, `src/completion.rs`, `tests/`, `README.md`

---

### B2 — Large game list management

**Problem:**
- After using gamewrap on many games (demos, uninstalled games, one-offs), `game list` grows without bound
- The only removal option is `game forget` (hard deletion); no way to soft-hide entries

**Proposed changes:**
- Add `game archive <name-or-exe>` / `game unarchive <name-or-exe>` — sets an `archived` flag on the state entry, excluded from default `game list`
- `game list --all` shows archived entries alongside active ones (visually marked)
- `game forget` remains for permanent removal
- `game list` shows an entry count and a hint if the list exceeds a threshold (e.g. 20 entries)

**Key files:** `src/cli.rs`, state file handling in `src/config/mod.rs`, `src/detect.rs`, tests

---

### B3 — Profile export semantics

**Question:** When a profile is exported to share:
- **Option A — sparse:** Export only what was explicitly set in the profile. Recipient's globals fill the rest at their end. Simple and portable; behavior depends on recipient's global config.
- **Option B — effective:** Export fully resolved settings (profile + globals baked in). Recipient gets a "known good" snapshot but must manually strip their own preferences.
- **Option C — sparse + informational context:** Export sparse profile, plus a `# context:` comment block showing what the exporter's globals were at export time. Informational only — not interpreted by import.

**Current behavior:** Option A (sparse).

**Resolved:** Sparse export implemented. Profiles are now flat (no inheritance). Export produces only explicitly set settings.

---

### B5 — Grouped, cleaner `config show` / `profile show` display

**Problem:**
- `config show` output (especially `--effective`) has no visual grouping — 30+ settings appear in struct field order
- No section headers separating e.g. gamescope settings from MangoHud settings

**Proposed changes:**
- Refactor `render_resolved_settings()` and `render_profile_settings_with_indent()` to emit settings under dimmed section headers using the same tool groups as B1
- Configured mode (default): only show a section header if that section has at least one configured value
- Effective mode (`--effective`): always show section headers; show `(nothing configured)` per-section if empty

**Dependency:** Best done after B1, which defines the canonical section groupings. Can be scoped independently by hardcoding groups if B1 is deferred.

**Key files:** `src/config/mod.rs`, tests

---

### B6 — JSON output flag + GUI (discussion needed)

**Phase 1 — JSON flag (independent):**
- Add `--json` flag to read commands: `config show`, `profile show`, `game list`, `status`, `dry-run`
- Write/mutating commands return `{"ok": true}` or the updated state on success
- Useful for scripting independently of any GUI

**Phase 2 — GUI (dependent on Phase 1):**
- Build a GUI that invokes `gamewrap` as a subprocess and renders the JSON output
- CLI remains the authoritative source of truth; GUI is a frontend only

**Discussion points before Phase 2:**
- Framework: egui (Rust, self-contained), iced (Rust async), Tauri (web frontend, heavier), GTK4 (gtk-rs)?
- Scope: full settings editor, profile manager, game list browser, or read-only status overlay?
- Packaging: GUI as an optional Cargo feature flag to keep the base CLI install slim?

**Recommended starting point:** Phase 1 JSON flag only.