Document UMU Proton backend design

docs/superpowers/specs/2026-05-05-umu-proton-backend-design.md

@@ -0,0 +1,64 @@
+# UMU Proton Backend Design
+
+## Goal
+
+Add a general UMU/Proton backend to audiogame-manager so selected games can install and launch through `umu-run` with AGM-managed Proton prefixes. Shadow Line is the first supported game and should be installable, launchable, translated to English, and speech-capable without changing the existing Wine backend for other games.
+
+## Scope
+
+This change introduces generic UMU helpers and wires Shadow Line to use them. It does not migrate existing Wine games, add proton-voices, or reimplement `umu-launcher`. AGM depends on `umu-run` for Proton/runtime management because UMU handles Proton selection, Steam Runtime setup, prefix creation, protonfixes, and Proton winetricks routing.
+
+## Architecture
+
+Launcher entries gain a new backend value in the first `games.conf` field:
+
+```text
+umu|c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe|Shadow Line|...
+```
+
+The existing Wine values (`win64`, `win32`) continue to behave as they do now. When the backend is `umu`, launch setup uses a dedicated Proton prefix under:
+
+```text
+${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/protonBottles/<game-id>
+```
+
+The game id is supplied by the installer and stored in launcher flags, for example `export umuGameId=shadow-line`. Helpers will centralize backend behavior:
+
+- `install_proton_bottle <game-id> [winetricks verbs...]`: create and select a UMU prefix, initialize it with `umu-run ""`, and install optional Proton winetricks verbs with `umu-run winetricks`.
+- `get_umu_bottle <game-id>`: export `WINEPREFIX`, `GAMEID`, `STORE`, and `DISPLAY`.
+- `run_umu_game <windows-path>`: convert the Windows path to a Unix executable path in the UMU prefix and run it through `umu-run`.
+- `add_umu_launcher <game-id> <windows-path> [flags...]`: append a `umu|...` launcher line.
+
+## Shadow Line
+
+Shadow Line uses the generic UMU backend with `umuGameId=shadow-line`. Its installer will:
+
+1. Require `umu-run`.
+2. Download `shadowrine_fullvoice3.171.exe` and `language_en.dat`.
+3. Create/select the Shadow Line UMU prefix.
+4. Apply `bcryptprimitives=native,builtin`.
+5. Apply per-app `win8` for `play_sr.exe`.
+6. Run the installer silently with UMU.
+7. Stop any leftover Wine/Proton processes for the prefix.
+8. Copy `language_en.dat` into `SystemData`.
+9. Copy AGM's `nvdaControllerClient32.dll` and/or `nvdaControllerClient64.dll` over any matching game DLLs found in the Shadow Line install.
+10. Register the UMU launcher and show the first-run instructions for switching the game language to English.
+
+Clipboard translation will not be used for Shadow Line in this implementation.
+
+## Dependency Checks
+
+`check_requirements` remains focused on core AGM dependencies, but UMU installers call a targeted `require_umu` helper so the error is clear at install time. The `-c` checkup report will also list `umu-run`: missing UMU is reported as required for Proton-backed games, not as a blocker for every Wine game.
+
+## Error Handling
+
+UMU helper functions fail fast with clear messages when `umu-run` is missing, prefix initialization fails, the installer does not produce the expected executable, or the translation file cannot be copied. Shadow Line should not be added to `games.conf` unless the expected executable exists.
+
+## Verification
+
+Verification will include:
+
+- `bash -n` on changed shell scripts.
+- `shellcheck` on changed Bash files.
+- A focused install-path dry run where possible without launching the interactive game.
+- Confirmation that Shadow Line creates a `umu|...|Shadow Line` launcher entry and that the UMU prefix contains `play_sr.exe`, `language_en.dat`, registry settings, and replacement NVDA DLLs when matching DLLs exist.