phoebus_os/docs/adr/0009-mango-dankmaterialshell-desktop.md
Phoebus bbd3d89d6a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO
- desktop.profile defaults to mango with Flatpak on; explicit none/minimal/dwl/
  full still win. The plan shows the selected session.
- Installed login uses greetd + tuigreet (authentication required, Mango default,
  dwl selectable); live autologin is a separate live-only configuration.
- installer/live/build.sh builds a rootless Debian testing rootfs with Mango
  (pinned source build), DankMaterialShell (pinned SHA-256 release), Quickshell,
  scenefx, Qt Wayland and greetd, then splices it into the base Debian-Live boot
  equipment. Live autologin, an Install Phoebus launcher and a serial/VT
  recovery console are included and the build fails clearly if a desktop
  component is missing. Verified in a graphical seat-providing VM (Mango + DMS +
  Quickshell; DMS panel captured).
- Shared desktop assets emitted by phoebus-installer --emit-asset, a graphical
  VM driver (live-driver.py), and regression tests for defaults/overrides,
  login, live/installed separation and the live ISO guards.
- Docs updated: ADR 0005/0009, STATUS, HANDOFF, CHANGELOG, ROADMAP, DEVELOPMENT
  and VM-BOOT-VERIFICATION.
2026-09-21 06:47:22 -07:00

6.8 KiB

ADR 0009: Mango + DankMaterialShell desktop option

  • Status: Accepted
  • Date: 2026-09-21

Context

Phoebus's flagship desktop is a hand-assembled dwl session (dwl, waybar, wofi, mako, swaybg, swayidle, swaylock, polkit-gnome). It is lightweight and proven, but it requires the user to assemble everyday desktop functions. 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 task is to offer it as an explicit profile, keep dwl as a fallback, and promote Mango to the default only after verification.

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 (the fallback) depends on the wlroots 0.18 slot. The two are different slots, so dwl and mangowm install side by side without a forced wlroots upgrade.
  • 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. A new explicit profile desktop.profile = "mango" installs Mango + DMS and also the dwl session as a fallback. Legacy values (none, minimal, dwl, full) keep their exact meaning.
  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. Two session entry points, one shell each. /usr/share/wayland-sessions gets phoebus-mango.desktop (default when the Mango profile is installed) and phoebus-dwl.desktop (fallback). The Mango session starts only mango, DMS (panel, launcher, notifications, lock, idle), and the shell's polkit agent; it never starts waybar/mako/swaybg/swayidle/swaylock. The dwl session is unchanged.
  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 default desktop (explicit owner decision, 2026-09-21). desktop.profile defaults to mango, Flatpak is on by default, and the default login experience selects the Mango session. Explicit values — including none and dwl — are still respected. This supersedes the earlier "verify before default promotion" policy; the graphical-VM gates below are still tracked honestly, but they no longer gate the default. dwl remains shipped as a fallback and selectable at login.

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".