68 lines
6.1 KiB
Markdown
68 lines
6.1 KiB
Markdown
## 13. Graphical session policies and frontends
|
|
|
|
A minimal graphical session is the normal runtime foundation, while its default visible interface remains the fullscreen terminal. Graphical frontends are optional clients of the same unified backend. Users must be able to select the initial shell, profile, autostart behavior, and launcher residency after installation through simple CLI commands and eventually through graphical settings.
|
|
|
|
Here, "frontend" means a project-integrated catalogue client such as Pegasus or a future first-party UI. Steam Big Picture, Heroic, and Lutris are provider-native interfaces: users may open them and use their native launch behavior, but they are not allowed to become the authoritative implementation behind `kiln` or other project frontends.
|
|
|
|
Likely session policies are:
|
|
|
|
| **Policy** | **Behavior** |
|
|
|------------|--------------|
|
|
| Terminal | Start the minimal graphical session and show the fullscreen terminal. |
|
|
| Manual | Start the terminal shell and open the selected frontend only when requested. |
|
|
| Automatic | Start the selected graphical frontend as the initial application through a systemd user target. |
|
|
| Last used | Optional later policy that restores the previous session choice. |
|
|
| TTY | Start no graphical session; use the real console recovery path. |
|
|
|
|
These policies should be implemented with ordinary systemd user services or targets rather than a second project-specific startup system.
|
|
|
|
### 13.1 Pegasus reference integration
|
|
|
|
> **Release scope:** This integration is the first planned frontend milestone after version 1 and does not block the version 1 release.
|
|
|
|
Pegasus Frontend is the preferred first reference frontend because it is FOSS, controller-aware, themeable, cross-platform, and already supports metadata-defined launch commands. Initial integration should use unmodified upstream Pegasus:
|
|
|
|
```text
|
|
Pegasus -> kiln launch <stable-id> -> unified core -> provider adapter
|
|
CLI -> kiln launch <stable-id> -> unified core -> provider adapter
|
|
```
|
|
|
|
`kiln frontend configure pegasus` should create the necessary integration, while `kiln frontend sync pegasus` should export normalized library metadata and artwork references. Generated Pegasus entries must call `kiln launch <stable-id>` rather than embedding provider-specific Steam, Heroic, Lutris, Wine, or emulator commands.
|
|
|
|
Because Pegasus expects launchable file entries, the adapter generates inert per-installation descriptor files. Pegasus passes the selected descriptor to a dedicated `kiln frontend launch-descriptor` operation, which validates and resolves it to the stable installation identity. Titles and provider metadata are never interpolated into `sh -c`. Sync behavior must define whether Pegasus reloads metadata safely or requires a controlled frontend restart.
|
|
|
|
Pegasus may continue to support direct launch commands for advanced use and diagnostics, but bypassing the backend is not the project default.
|
|
|
|
### 13.2 OpenGamepadUI evaluation
|
|
|
|
After version 1, evaluate OpenGamepadUI as an additional controller-native frontend and overlay candidate alongside Pegasus. Its active development, plugin architecture, multiple game sources, and InputPlumber integration are relevant, but its upstream early-development warning prevents making it a version 1 dependency or replacing Pegasus before prototype evidence exists.
|
|
|
|
An OpenGamepadUI integration must consume the same stable backend identities and launch behavior as other clients. Its internal catalog, provider plugins, input daemon, or artwork state must not become authoritative for discovery, configuration ownership, or launch policy. Evaluation should determine whether its plugin or D-Bus boundaries can call the backend cleanly and whether its overlay/input features justify optional InputPlumber integration.
|
|
|
|
### 13.3 Fork and custom-frontend policy
|
|
|
|
Do not fork Pegasus or build a first-party graphical frontend during the initial implementation. Use the upstream application to expose concrete integration limitations before accepting either maintenance burden.
|
|
|
|
The preferred escalation order is:
|
|
|
|
1. External adapter using upstream Pegasus behavior.
|
|
2. Propose a generic data-source, plugin, or structured-launch integration upstream.
|
|
3. Contribute broadly useful changes to Pegasus upstream.
|
|
4. Maintain a small downstream patch set if the required changes are narrow and project-specific.
|
|
5. Fork Pegasus only when deep necessary changes cannot reasonably be accepted or isolated.
|
|
6. Build a first-party frontend when the project needs a native OS control surface rather than only a game-library browser.
|
|
|
|
A future first-party frontend may be justified for live provider state, install/update controls, launch progress, structured errors, OS settings, compatibility profiles, Gamescope/GameMode/MangoHud/MangoApp controls, and seamless desktop/controller layouts. It must remain another client of the shared backend.
|
|
|
|
### 13.4 Provider-interface behavior
|
|
|
|
- Steam may be optionally resident for faster launches and gamepad UI integration; Ready and Custom profiles support autostarting it hidden or visible.
|
|
- When explicitly opened for a controller-oriented session, Steam should start in Big Picture Mode; desktop sessions should use the normal Steam interface.
|
|
- Do not infer controller mode merely because Pegasus is running; the caller or selected session profile should state the intended mode.
|
|
- Heroic and Lutris default to lazy startup in Lean but may remain resident in Ready or Custom.
|
|
- Post-v1 vendor launchers should not remain resident by default.
|
|
- The unified library should remain usable without any provider GUI open.
|
|
- Window-focus requests are capability-based. Session-wide compositor keybindings are the v1 baseline; a frontend or CLI must not assume Labwc exposes programmatic focus control, because upstream intentionally provides no D-Bus or custom IPC.
|
|
|
|
> **Deferred decision:** The final compositor selection, display-manager/login mechanism, installer questions and presets, Pegasus theme, downstream patch set, OpenGamepadUI integration method, and any first-party frontend toolkit remain unselected. Labwc is the leading compositor prototype, not yet a locked dependency.
|