phoebus_os/docs/adr/0009-mango-dankmaterialshell-desktop.md
Phoebus fe8de3904b
Some checks are pending
ci / test (push) Waiting to run
refactor(desktop): unify desktop stack on Mango + DarkMaterial and excise standalone dwl
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock
- Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop
- Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations
- PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback
- Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango
- Live ISO emitted assets reduced from 24 to 17 and verified clean
2026-09-24 15:49:15 -07:00

117 lines
6.5 KiB
Markdown

# ADR 0009: Mango + DankMaterialShell desktop option
- **Status:** Accepted
- **Date:** 2026-09-21
## Context
Phoebus's original desktop was a hand-assembled dwl session (dwl, waybar, wofi,
mako, swaybg, swayidle, swaylock, polkit-gnome). It was lightweight, but
required manual assembly and duplicated effort. Mango (`gui-wm/mangowm`, a
wlroots dwl derivative) plus DankMaterialShell (DMS, a Quickshell shell
providing panel, launcher, notifications, network/Bluetooth/audio controls,
locking, idle and display management) is a complete, coherent desktop that fits
the Wayland/systemd/PipeWire architecture.
The decision was made to make Mango + DarkMaterial the sole, canonical desktop
experience for Phoebus OS, completely retiring standalone dwl and eliminating
any secondary or fallback desktop paths.
## Upstream and packaging facts (verified 2026-09-21)
| Component | Package | Version | Source | License | Keyword |
|-----------|---------|---------|--------|---------|---------|
| Compositor | `gui-wm/mangowm` | 0.17.2 | GURU (community) | CC0-1.0 / GPL-3+ / MIT | `~amd64` |
| Shell | `gui-apps/dankmaterialshell` | 1.5.3 | GURU (community) | MIT | `~amd64` |
| Framework | `gui-apps/quickshell` | 0.3.1 | GURU (community) | LGPL-3 | `~amd64` |
| Search | `gui-apps/danksearch` | 0.3.2 | GURU (community) | MIT | `~amd64` |
| Effects lib | `gui-libs/scenefx` | 0.5 | GURU (community) | MIT | `~amd64` |
- `mangowm` depends on the **wlroots 0.20 slot** and `scenefx:0.5`.
- `gui-wm/dwl` (wlroots 0.18) and standalone dwl helpers (`waybar`, `wofi`, `mako`,
`swaybg`, `swayidle`, `swaylock`) are completely removed from the desktop
package set and session configurations.
- DMS is installed from DMS's **released** tarballs (its ebuild `SRC_URI`
points at GitHub release assets); no live/git package is used.
- GURU is git-only, so `dev-vcs/git` is installed from the main tree before the
overlay is synced.
- Upstream (Quickshell/DMS) requires Qt 6.6+, which the selected
`default/linux/amd64/23.0/desktop/systemd` profile provides.
## Decision
1. **One canonical desktop profile**: `desktop.profile = "mango"` installs Mango + DMS.
Standalone dwl has been excised; `none` remains for headless installations.
2. **Portage owns the stack.** The installer writes `repos.conf` for GURU
(git), installs `dev-vcs/git`, syncs GURU with `emaint sync -r guru`, and
installs the packages with `emerge`. There is no `curl | sh`, no Nix, and no
live package.
3. **Testing keywords are scoped.** `package.accept_keywords/phoebus` lists only
`gui-wm/mangowm`, `gui-apps/dankmaterialshell`, `gui-apps/danksearch`,
`gui-apps/quickshell` and `gui-libs/scenefx`. `~amd64` is never enabled
globally, and Portage is not silently auto-unmasked: additional `~amd64`
dependencies must be reviewed and added deliberately.
4. **Single canonical session entry point.** `/usr/share/wayland-sessions`
ships `phoebus-mango.desktop`. The session starts *only* mango, DMS (panel,
launcher, notifications, lock, idle), and Quickshell's polkit agent. No
competing standalone dwl session entry or helpers are shipped.
5. **User configuration is separate from packaged defaults.** The session seeds
`~/.config/mango/config.conf` from `/etc/xdg/mango/config.conf` only when
absent, and DMS manages `~/.config/mango/dms/*.conf`. Portage upgrades never
overwrite user files.
6. **Administration stays behind `sys`.** DMS's system-update controls are not
wired up; updates continue through `sys`/Portage. The assistant is reachable
from a launcher (`phoebus-assistant`) that simply runs `sys ask`, keeping the
typed-action and approval boundary.
7. **Mango + DankMaterialShell is the canonical Phoebus desktop.** `desktop.profile`
defaults to `mango`, Flatpak is on by default, and `greetd` launches the Mango
session upon authentication. Silent fallback to dwl is prohibited: any failure
fails visibly and diagnostically. Recovery consoles (serial and TTY) remain available.
## Live medium
The installer ISO boots into the same Mango + DankMaterialShell desktop. The
live image is a Debian testing rootfs (wlroots 0.20, scenefx 0.5, quickshell)
plus a pinned Mango source build and a pinned DMS release; it autologins as an
unprivileged `phoebus` user, exposes a serial/VT recovery console, and provides
an "Install Phoebus" launcher that opens the uninstrumented installer UI. The
installed target is Gentoo and never receives Debian packages. See
`installer/live/README.md`. The live and installed login configurations are
generated from the same assets but differ in one property: the live config has
`[initial_session]` (autologin) and the installed config never does.
## Update procedure
GURU is synced by `emaint sync -r guru` on every Portage sync. To move to a new
upstream release, bump the reviewed versions in the keyword list only after
`emerge --pretend` confirms the dependency set, then rebuild the profile's
packages. The overlay is community-maintained; its ebuilds are attributed to
their maintainers (see each `metadata.xml`).
## Consequences and risks
- The Mango install pulls Qt, Quickshell and scenefx, so it is much heavier to
build than the dwl session; a matching signed binhost does not exist for these
GURU packages, so they compile.
- GURU is a community overlay: provenance is documented but it is not the main
Gentoo tree. The keyword scope keeps the risk limited to the listed packages.
- DMS is a fast-moving project; the integration pins a reviewed release and
documents the update path rather than tracking `9999`.
- If DMS's polkit integration does not cover every prompt, a fallback
`PHOEBUS_POLKIT_AGENT` hook is available but defaults off to avoid two agents.
## Verification status
Unit and source-level tests cover the default configuration and explicit
overrides, the profile and package set, keyword scope, generated session
scripts, config seeding, the two session entries, the greetd configuration, the
live/installed login separation, and the live ISO's desktop-payload guards. The
ISO is built by `installer/live/build.sh` (see the evidence recorded in
`docs/VM-BOOT-VERIFICATION.md`).
Graphical-VM acceptance gates (real seat, panel/launcher/notifications/polkit,
lock/unlock, shell restart, logout cleanup, suspend/resume, Flatpak portals,
idle/memory under load) are tracked in `docs/VM-BOOT-VERIFICATION.md` and are
**not all passed**. The default is set by explicit owner decision, not because
those gates passed; `docs/STATUS.md` distinguishes "default in configuration",
"successfully built" and "graphically verified".