### **User Story: Robust Cross-Platform Game Detection**

**Title:**  
As a user, I want the Electron app to accurately detect which game I am currently playing, so that I can enjoy automatic features (rich presence, overlays, stats tracking, screenshots, etc.) without manual intervention and with minimal false positives.

---

### **Description**

The application must reliably detect the currently active game on the user's PC with high accuracy on both **Windows** and **Linux**. Detection should focus on the game the user is actually playing (foreground window) while strongly minimizing false positives such as:
- Processes with numeric-only names (e.g., “123456.exe”)
- Non-game applications containing words like “Spotify”, “Discord”, “Chrome”, etc.
- Generic or suspicious short names
- Background launchers, browsers, or system processes

The solution should combine multiple signals and smart heuristics to achieve robust detection.

---

### **Acceptance Criteria**

#### **Functional Requirements**
- The app automatically detects the currently focused (foreground) game every 2–5 seconds.
- Detection returns at minimum:
  - Game title (window title)
  - Process name (executable name)
  - Full executable path (when available)
  - PID
  - Confidence score or `isGame: boolean`
- When a game is confidently detected, the app triggers downstream features (e.g., Discord Rich Presence, overlay, auto-screenshot, etc.).
- When no game (or low confidence) is detected, the app remains silent / shows “No game detected”.

#### **Accuracy & False Positive Prevention**
- **Must ignore**:
  - Common non-game applications (Spotify, Discord, browsers, IDEs, Electron apps, SteamWebHelper, etc.)
  - Processes with only numbers or very short/generic names
  - Window titles containing “Spotify”, “Discord”, “Chrome”, etc.
- **Must favor**:
  - Processes whose window title contains letters and has reasonable length (> 5 characters)
  - Games launched via Steam, Epic, GOG, itch.io, or Proton (on Linux)
  - Fullscreen or near-fullscreen windows when possible
  - Processes with high CPU/GPU usage (optional but recommended)
- False positive rate should be **very low** (< 5% in normal usage).

#### **Platform Support**
- **Windows**: Full support with high accuracy (preferred method: native or semi-native)
- **Linux**: Solid support for both **X11** and **Wayland** (Hyprland, GNOME, KDE, Sway)
  - Must handle Proton/Wine games gracefully (prefer window title when process name is `wine` or `proton`)
- Graceful degradation when native access is limited.

#### **Technical Requirements**
- Detection logic runs in the **main Electron process** (higher privileges).
- Solution must be maintainable and extensible.
- Provide clear separation between raw detection and game validation heuristics.
- Easy to add new blacklisted processes or game-specific signatures.

---

### **Suggestions & Enhancements (Non-functional + Future Ideas)**

#### **Core Detection Strategy (Recommended)**
- Primary signal: **Active/Foreground window** + its owning process
- Secondary signals:
  - Executable path analysis (avoid temp folders, browser caches, etc.)
  - Game engine signatures (UnityPlayer.dll, UE4/UE5 modules, Godot, etc.)
  - Window properties (size, fullscreen state, borderless)
  - Process resource usage (CPU > 15–20% for several seconds)
- Smart name/title filtering + allowlist/blacklist system

#### **Advanced Features (Nice-to-Haves)**
1. **Local Game Database**  
   - Store previously confirmed games by executable hash + path
   - First-time detection: Ask user “Are you playing *Game Name*?” → remember choice

2. **Launcher Integration** (High Value)
   - Steam: Detect running AppID and fetch accurate name + metadata via Steamworks or local VDF parsing
   - Epic Games Launcher, GOG Galaxy, Battle.net, etc.

3. **Heuristic Engine**
   - Score-based detection (0–100 confidence)
   - Bonus points for: known game folders, large window, high GPU usage, engine DLLs

4. **Wayland Support**
   - Hyprland: `hyprctl activewindow`
   - Sway: `swaymsg`
   - GNOME/KDE: DBus or compositor-specific APIs

5. **Native Module (Strongly Recommended for best accuracy)**
   - Build a small Rust + NAPI module for:
     - Windows: `GetForegroundWindow`, `QueryFullProcessImageName`, module enumeration
     - Linux: X11 (`XGetInputFocus`, `_NET_WM_PID`) + Wayland support

6. **User Controls**
   - Manual “Ignore this process” / “This is a game” buttons
   - Configurable blacklist & custom game folders
   - Toggle for aggressive vs conservative detection mode

---

### **Out of Scope (for MVP)**
- Real-time GPU usage monitoring
- Automatic game library scanning
- Cloud-based game database
- macOS support (unless later requested)

---

### **Definition of Done**
- Works reliably on Windows 10/11 and common Linux distributions (Ubuntu, Pop!_OS, Arch with Hyprland)
- False positives are rare in real usage (tested with Spotify + Discord + browsers + Steam + 10 popular games)
- Code is well documented and heuristics are easily configurable
- Unit + integration tests for core detection logic
- Settings page allows users to manage ignored processes

---

### **Open Questions / Decisions**
1. Do we want to ship a native Rust module from day one, or start with JS-only (`active-win` + `ps-list`) and optimize later?
2. How aggressive should the initial heuristic be? (Balance between missing obscure games vs false positives)
3. Should we store user confirmations locally using Electron Store / SQLite?
4. What metadata do we want to expose to the renderer process? (`gameName`, `processPath`, `confidence`, `source`: "steam" | "window" | "manual")

---

**Would you like me to also create:**
- A more technical **Technical Specification** / ADR version?
- Detailed **sub-tasks** (breakdown into tickets)?
- The actual folder structure + code skeleton for this feature?

Just tell me which direction you want to go deeper.