Project-Kiln/docs/spec/03_PROVIDERS_SESSIONS_AND_INPUT.md

7. Provider strategy

Provider work is incremental. Discovery and parsing, normalization, launch-plan generation, and real execution are separate milestones for each provider. Completing a parser does not authorize beginning execution support, and beginning one provider does not authorize broad parallel implementation of the others.

Each provider adapter must have fixture-based parser tests, normalized-contract tests, isolated integration tests, and explicit real-system acceptance checks. Initial fixtures must include malformed, missing, duplicate, moved, unmounted, and unusual-path cases where relevant. Provider discovery must be read-only unless a separately approved management operation explicitly requires mutation.

Steam. Parse app manifests and library folders; launch by App ID. Preserve Steam's management of Proton and runtime containers. Assume the Steam client is required for ordinary Steamworks/DRM titles and start it silently when needed. Direct executable launch is allowed only for confirmed DRM-free cases and must not silently discard Steamworks, cloud, multiplayer, overlay, or controller behavior. Steam has no supported lightweight service-only client, so unsupported browser-process surgery is not a project dependency.

Lutris. Use its documented --list-games --json discovery output and lutris:rungame/<identifier> or lutris:rungameid/<local-id> launch URIs, validated against the packaged version. Treat Lutris as owner of runner and prefix configuration. Its numeric IDs are machine-local discovery handles, not stable public game identities; store the adapter's persistent installation UUID and re-resolve the current local ID before launch. The optional --output-script path may aid diagnostics but must not become the default because it can bypass client-owned accounting or lifecycle behavior.

Heroic and its providers. Treat Heroic as an optional graphical management interface rather than the mandatory execution backend. Version 1 treats Epic, GOG, and Amazon as separate capability targets, corresponding upstream to Legendary, GOGDL, and Nile respectively. Heroic currently uses its own Legendary fork, so compatibility with standalone upstream Legendary or Heroic-owned state must be demonstrated rather than assumed. Where reliable, provider adapters may call a validated helper without starting Heroic's Electron UI. Each adapter must preserve store-qualified identities, advertise its actual capabilities, and respect ownership of credentials, Wine prefixes, per-game options, cloud saves, and configuration. Sharing Heroic state or reproducing Heroic launch behavior requires prototype validation; direct parsing of unstable Heroic internals remains provisional and isolated. Heroic and helper packaging is resolved through the phase 0 source inventory because Heroic is not an official Arch repository package; release profiles may use only reviewed, pinned, project-built packages or verified upstream artifacts, never an arbitrary live AUR install.

UMU runtime. Provide a first-class Proton execution path outside Steam and for custom Windows games. UMU is a runtime backend, not a provider adapter: it does not supply authoritative library discovery, and its use must not replace the game's store-qualified or custom-manifest identity. Launch plans record the resolved GAMEID, STORE, prefix, Proton selection, executable, and arguments. Because UMU can automatically download its Proton/runtime payloads, packaging must define managed cache locations, authenticated or checksum-verified acquisition where upstream supports it, explicit prefetch/update operations, and an offline failure mode; an ordinary game launch must never disguise a large first-run download as a hung game.

Native. Discover explicitly approved desktop entries and user manifests; do not blindly ingest every Exec= entry on the system. Parse Desktop Entry field codes without a shell, retain provenance, and launch executables with typed arguments.

Vendor launchers — post-v1. After version 1, add Battle.net, EA App, Ubisoft Connect, Rockstar, and similar clients through individually tested Lutris or managed UMU/Wine-prefix integrations. The shared managed-prefix architecture may be designed earlier, but vendor compatibility does not block version 1.

8. Graphics and session model

8.1 Persistent session shell

• Normal gaming mode starts one persistent minimal stacking compositor with Wayland/Xwayland support; Xorg remains a compatibility fallback.
• The default visible application is a fullscreen terminal, making the system appear and behave CLI-first without repeatedly creating graphical environments.
• The compositor supplies only required window management: focus, maximize/fullscreen, application switching, dialogs, multi-monitor placement, and optional dedicated workspaces.
• A general stacking compositor is preferred for the session shell because Steam, Heroic, dialogs, terminals, frontends, and authentication windows must coexist. Labwc is the leading prototype candidate because it provides lightweight Wayland stacking and Xwayland support without a desktop environment; it remains replaceable until Steam, Heroic, Lutris, NVIDIA, portals, multi-monitor behavior, and nested Gamescope pass prototype testing.
• Gamescope remains available as a per-game or nested optimization layer where it is beneficial; it is not assumed to be the general multi-window desktop shell.
• ChimeraOS gamescope-session is reference material and a possible reusable base for dedicated Steam-like or controller-frontend sessions. It is not the Lean or Ready multi-window shell because arbitrary multi-window clients in embedded Gamescope require Steam-specific window-property behavior.

8.2 Initial application and return behavior

• The session may initially show the fullscreen terminal, Steam Big Picture, another configured frontend, or a user-supplied command. Pegasus becomes the reference configured frontend after version 1.
• When a launcher or frontend exits, configurable behavior may return to the terminal, restart the selected frontend, or end the session.
• Closing a game normally reveals the previous launcher, frontend, or terminal rather than tearing down the graphical foundation.
• Required plumbing may include PipeWire/WirePlumber, D-Bus, XDG portals, Polkit agent, file picker, fonts, controller services, Bluetooth, and Xwayland. Traditional desktop furniture is excluded unless explicitly installed.

8.3 Session ownership and login

• The graphical-session prototype defines logind seat/TTY ownership, user D-Bus startup, compositor environment propagation, and a project systemd user target in the per-user manager. Session services declare PartOf=graphical-session.target; the login/session launcher owns the compositor process and stops the target when that compositor session ends.
• Graphical services stop with the graphical session instead of surviving accidentally in the user manager. Tests cover logout, compositor crash, failed initial shell, repeated restart, and switching to the TTY recovery target.
• Recovery mode bypasses graphical autostart and avoids restart loops when the compositor or initial application fails.
• The exact display manager, greetd/autologin mechanism, or direct-login design remains open, but its contract is resolved during the session proof rather than postponed to ISO construction.

8.4 Runtime profiles

Profile	Default behavior
Lean	Start the graphical foundation and fullscreen terminal; launch provider clients and GUIs only when required. This is the default.
Ready	Start the same foundation and keep user-selected launchers such as Steam or Heroic resident, usually hidden or on dedicated workspaces.
Frontend	Start Steam Big Picture or another selected frontend as the initial shell; retain terminal access through a shortcut or controller action. Pegasus becomes the reference option after version 1.
Custom	Apply individually selected initial application, autostart, residency, hiding, and exit policies.
TTY	Start no graphical session; provide recovery, diagnostics, and deliberate console-only operation.

Profile selection and per-launcher residency are runtime configuration, not installation-only choices. Installer questions and presentation are intentionally deferred for a later design discussion.

8.5 Launcher lifecycle and switching

• kiln provider show <name> starts the launcher when absent. Focusing an existing Wayland window is exposed only when the selected compositor/session-control adapter provides a tested mechanism; Labwc deliberately has no D-Bus or custom IPC, so the command must return a structured focus-unsupported result rather than pretending success. Compositor keybindings remain the baseline switching path.
• Users can switch among the terminal, provider interfaces, configured frontends, and the running game using compositor shortcuts, a controller-accessible session action, supported CLI focus commands, or frontend actions. The session proof must choose and test the controller path; candidates are Steam Input desktop mappings, a narrowly scoped project input service, or InputPlumber if prototype evidence makes it necessary.
• Steam and Heroic may autostart and remain resident in Ready or Custom profiles.
• Lean may start Steam silently on the first Steam launch and retain it afterward. Provider clients are not automatically stopped after play; explicit safe exit or a later optional idle policy may be added only where the provider exposes reliable behavior.
• Heroic-backed games should use supported CLI backends without the Heroic GUI where validated; opening Heroic remains available for browsing, installation, authentication, and configuration.
• Post-v1 vendor launchers stay lazy by default unless required by a running title or explicitly configured as resident.
• Minimizing or hiding a launcher is preferred to risky process manipulation. Game scopes may receive higher CPU and I/O priority, but process-priority and resource-control policies require measurement and compatibility testing.

8.6 Game lifecycle tracking

• Track the game rather than assuming the provider-launch command remains attached to it.
• Prefer an owned process or systemd scope; otherwise use provider-reported state or conservative process correlation.
• Report lifecycle confidence as tracked, provider-reported, probable, or unknown.
• Use lifecycle state for sleep inhibition, optional background-work suppression, running status, logging, and restoration of temporary settings. GameMode activation is related but separate: the request must be held by a real GameMode client or injected wrapper for the lifetime of the game, not inferred solely from tracker confidence. Direct launches may use gamemoderun; Steam/provider launches require tested provider launch options, native integration, or an explicit backend-held client registration.
• When exact tracking is unavailable, degrade safely without leaving permanent performance overrides active.
• A force-stop command is not a version 1 requirement. It may be added later when the existing tracking mechanism makes it safe and simple.

8.7 Fallbacks

• Xorg fallback for games, launchers, or driver combinations that fail under the preferred Wayland compositor or Gamescope.
• Safe mode that disables optional overlays, tuning, and nonessential environment overrides.
• Direct provider launch for diagnosing failures in the unified backend.
• TTY-only target for recovery when the graphical shell cannot start.

9. Controller and input requirements

USB and Bluetooth controllers are release-blocking functionality. The input design must cover kernel recognition, user permissions, SDL visibility, Steam Input, hotplugging, reconnection, and device-specific features where supported.

9.1 Required device classes

• Xbox and XInput-compatible controllers
• DualShock and DualSense controllers
• Nintendo/Switch-compatible controllers
• Generic USB HID gamepads
• Steam Input–managed devices

9.2 Controller tooling

kiln controller list
kiln controller scan
kiln controller pair
kiln controller connect
kiln controller forget
kiln controller test
kiln controller battery
kiln controller manage

• kiln controller manage opens Bluetui as the standard interactive BlueZ TUI for discovery, pairing, trust, connection, and removal. Project-owned commands remain responsible for stable machine-readable output, automation, controller-specific tests, battery reporting, and diagnostics rather than duplicating Bluetui's interactive interface.
• Blueman is the optional desktop-neutral GTK Bluetooth manager for a future or user-installed desktop experience. GNOME and KDE Bluetooth panels may be supplied by their respective desktop profiles but are not base dependencies.
• InputPlumber is a post-v1-leaning optional prototype for controller-driven shell control, advanced remapping, virtual-device presentation, and overlay input. It is not a version 1 baseline dependency unless testing proves a release-blocking need. Evaluation must specifically test duplicate physical/virtual devices and interaction with Steam Input.
• Bluetui is an interactive manager, not a stable automation API. Automated pairing diagnostics and state changes use BlueZ D-Bus interfaces through project-owned typed code; bluetoothctl may remain a recovery/diagnostic fallback.

9.3 Acceptance checks

• A paired Bluetooth controller reconnects after reboot without opening a desktop settings panel.
• A USB controller can be connected before or during a game session.
• A controller can invoke the documented recovery/session-switch action without depending on a running game or a provider overlay; the keyboard equivalent remains available.
• SDL and Steam recognize expected buttons and axes under both Gamescope and fallback sessions.
• Controller permissions do not require running games or launchers as root.
• Battery level, rumble, gyro, touchpad, LEDs, and advanced functions are reported or supported when the relevant driver exposes them.

Controller diagnostics distinguish supported, unsupported, unavailable, permission-denied, managed-by-steam-input, and unknown. Pairing design covers Bluetooth agents and passkey/PIN prompts without a desktop settings panel, multiple-controller assignment, duplicate raw/virtual devices, and a keyboard/controller recovery action when a frontend captures input.