diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index fd0bd8d..5bd65dc 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -5,6 +5,15 @@ this file is the curated, human-readable summary.
## Unreleased — Fast defaults with user-controlled source builds
+- **First-login wallpaper and profile initials (2026-10-02).** Mango now seeds
+ DMS's wallpaper session state with `~/Pictures/Wallpapers/aurora-lagoon.jpg`
+ and opens the wallpaper browser in that folder, including on the live
+ desktop. Existing choices are kept. The installer creates a letter avatar
+ for the installation user before greeter login; the session creates one for
+ later accounts that have no `~/.face`. AccountsService uses a chosen profile
+ image ahead of this fallback. The disposable VM displayed the aurora and a
+ “P” avatar, and session/provisioning tests covered first use and preservation.
+
- **DMS cursor and responsive Settings (2026-10-02).** Phoebus now includes
DMS's managed Mango cursor fragment from the first session, so the Theme &
Colors cursor controls no longer require a manual Add/Setup step. Existing
diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md
index ca48df9..ca5d3f0 100644
--- a/docs/HANDOFF.md
+++ b/docs/HANDOFF.md
@@ -3,6 +3,21 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
+- **Wallpaper and avatar defaults (2026-10-02):** The Mango session sets
+ DMS's `session.json` wallpaper path to the bundled aurora only when unset,
+ and its `cache.json` wallpaper browser folder to
+ `~/Pictures/Wallpapers` only when unset. `jq` is available in both the live
+ package manifest and installed DMS dependencies. AccountsService already
+ falls back to `~/.face`; the installer now creates a first-letter SVG for
+ the installation user before greeter login, and the session creates one
+ for later users if absent. The existing QEMU playground displayed its “P”
+ avatar and aurora wallpaper. Focused tests exercise first use and preserve
+ a chosen wallpaper, folder and avatar; a temporary-home check covered
+ existing DMS state with empty wallpaper fields. The new session launcher
+ was installed in the visible VM. `make check`, release and static builds,
+ and ShellCheck passed. Fresh ISO/install remains unverified while host free
+ space is 10 GiB against the 20 GiB VM gate.
+
- **DMS cursor and Settings sizing (2026-10-02):** The packaged Mango config
sources `./dms/cursor.conf`, and the session creates that fragment before
Mango starts. A one-time marker lets existing user configs gain the include
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 5b65490..5b61695 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -48,6 +48,18 @@ disposable VM; `serial-driver.py recovery` now automates the same check.
## Matrix
+First-login appearance (2026-10-02): the existing disposable VM shows the
+bundled `aurora-lagoon.jpg` and a first-letter profile avatar. The session
+launcher now seeds DMS's wallpaper path and wallpaper browser directory only
+when unset; the installer creates the installation user's avatar before first
+login, and the session creates one for later users without a `~/.face`.
+Functional session and provisioning tests pass, including preservation of
+custom wallpaper, folder and avatar choices. An existing empty DMS state was
+also filled without changing another setting. The running VM has the new
+session launcher; `make check`, release/static builds and ShellCheck passed.
+A fresh ISO/install with these defaults is not verified because the host has
+10 GiB free against the 20 GiB VM gate.
+
Desktop cursor and sizing follow-up (2026-10-02): the default Mango config
now sources DMS's managed cursor fragment, and the session creates it before
Mango starts. Existing profiles gain the include once without overwriting
diff --git a/installer-rs/crates/phoebus-core/src/system.rs b/installer-rs/crates/phoebus-core/src/system.rs
index d622ec5..1f8282c 100644
--- a/installer-rs/crates/phoebus-core/src/system.rs
+++ b/installer-rs/crates/phoebus-core/src/system.rs
@@ -1484,6 +1484,77 @@ if [ -f /usr/share/applications/firefox-bin.desktop ] \
xdg-mime default firefox-bin.desktop text/html 2>/dev/null || true
fi
+# DMS keeps its selected wallpaper and the wallpaper browser's last directory
+# in separate files. Fill only missing values, before the shell starts, so the
+# first desktop uses the bundled aurora and the picker opens its folder.
+wallpaper_dir="$HOME/Pictures/Wallpapers"
+default_wallpaper="$wallpaper_dir/aurora-lagoon.jpg"
+if [ -r "$default_wallpaper" ] && command -v jq >/dev/null 2>&1; then
+ (
+ umask 077
+ dms_state="$HOME/.local/state/DankMaterialShell/session.json"
+ dms_cache="$HOME/.cache/DankMaterialShell/cache.json"
+ if mkdir -p "$(dirname "$dms_state")" "$(dirname "$dms_cache")"; then
+ if [ ! -e "$dms_state" ]; then
+ jq -n --arg path "$default_wallpaper" \
+ '{configVersion:4,wallpaperPath:$path}' > "$dms_state"
+ elif jq -e '(.wallpaperPath // "") == ""' "$dms_state" >/dev/null 2>&1; then
+ if state_tmp="$(mktemp "${dms_state}.XXXXXX")"; then
+ if jq --arg path "$default_wallpaper" '.wallpaperPath = $path' "$dms_state" > "$state_tmp"; then
+ mv "$state_tmp" "$dms_state"
+ else
+ rm -f "$state_tmp"
+ fi
+ fi
+ fi
+ if [ ! -e "$dms_cache" ]; then
+ jq -n --arg dir "$wallpaper_dir" \
+ '{configVersion:3,wallpaperLastPath:$dir,fileBrowserSettings:{wallpaper:{lastPath:$dir}}}' > "$dms_cache"
+ elif jq -e '(.wallpaperLastPath // "") == "" or (.fileBrowserSettings.wallpaper.lastPath // "") == ""' "$dms_cache" >/dev/null 2>&1; then
+ if cache_tmp="$(mktemp "${dms_cache}.XXXXXX")"; then
+ if jq --arg fallback "$wallpaper_dir" '
+ (if (.fileBrowserSettings.wallpaper.lastPath // "") != "" then .fileBrowserSettings.wallpaper.lastPath
+ elif (.wallpaperLastPath // "") != "" then .wallpaperLastPath
+ else $fallback end) as $dir
+ | .wallpaperLastPath |= (if . == null or . == "" then $dir else . end)
+ | .fileBrowserSettings.wallpaper.lastPath |= (if . == null or . == "" then $dir else . end)
+ ' "$dms_cache" > "$cache_tmp"; then
+ mv "$cache_tmp" "$dms_cache"
+ else
+ rm -f "$cache_tmp"
+ fi
+ fi
+ fi
+ fi
+ )
+fi
+
+# AccountsService uses ~/.face only when the user has not chosen an icon. A
+# letter avatar therefore appears in DMS and the greeter, while a chosen
+# profile picture remains authoritative. Never replace an existing .face.
+if [ ! -e "$HOME/.face" ]; then
+ avatar_user="${USER:-$(id -un)}"
+ avatar_name="$(getent passwd "$avatar_user" | cut -d: -f5 | cut -d, -f1)"
+ avatar_name="${avatar_name#"${avatar_name%%[![:space:]]*}"}"
+ avatar_initial="${avatar_name:0:1}"
+ case "$avatar_initial" in [[:alpha:]]) ;; *) avatar_initial="${avatar_user:0:1}" ;; esac
+ case "$avatar_initial" in [[:alpha:]]) ;; *) avatar_initial="U" ;; esac
+ avatar_initial="${avatar_initial^^}"
+ if avatar_tmp="$(mktemp "$HOME/.face.XXXXXX")"; then
+ cat > "$avatar_tmp" <
+SVG
+ chmod 0644 "$avatar_tmp"
+ ln "$avatar_tmp" "$HOME/.face" 2>/dev/null || true
+ rm -f "$avatar_tmp"
+ fi
+fi
+
HELPERS=""
start_helper() {
diff --git a/installer-rs/crates/phoebus-executor/src/desktop.rs b/installer-rs/crates/phoebus-executor/src/desktop.rs
index 2353687..b359752 100644
--- a/installer-rs/crates/phoebus-executor/src/desktop.rs
+++ b/installer-rs/crates/phoebus-executor/src/desktop.rs
@@ -552,7 +552,9 @@ pub fn provision_installed_welcome(exec: &Exec, config: &InstallConfig) -> Resul
/// Seed the installation user's wallpaper folder and the skeleton for future
/// accounts. Existing images are never replaced, including namesakes that a
-/// user has edited after installation.
+/// user has edited after installation. Give the installation user a letter
+/// avatar before the first greeter login; later accounts receive one from the
+/// session launcher.
pub fn provision_wallpapers(exec: &Exec, config: &InstallConfig) -> Result<()> {
use std::os::unix::fs::PermissionsExt;
@@ -619,8 +621,45 @@ pub fn provision_wallpapers(exec: &Exec, config: &InstallConfig) -> Result<()> {
&[&owner, &format!("{home}/Pictures/Wallpapers/{name}")],
)?;
}
+ let avatar_rel = format!("{home_rel}/.face");
+ if !target.exists(&avatar_rel) {
+ let initial = config
+ .user
+ .fullname
+ .trim_start()
+ .chars()
+ .next()
+ .filter(|letter| letter.is_alphabetic())
+ .or_else(|| {
+ username
+ .chars()
+ .next()
+ .filter(|letter| letter.is_alphabetic())
+ })
+ .unwrap_or('U')
+ .to_uppercase()
+ .next()
+ .unwrap_or('U');
+ let avatar = format!(
+ "\n"
+ );
+ let path = target.write(&avatar_rel, &avatar)?;
+ std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644))
+ .map_err(|e| ExecError::io(path, e))?;
+ portage::chroot(
+ exec,
+ target.path(),
+ "chown",
+ &[&owner, &format!("{home}/.face")],
+ )?;
+ }
exec.logger.info(format!(
- "seeded {} wallpapers in {home}/Pictures/Wallpapers",
+ "seeded {} wallpapers and an initial avatar for {username}",
DEFAULT_WALLPAPERS.len()
));
Ok(())
@@ -1011,12 +1050,21 @@ mod tests {
assert_eq!(std::fs::read(current).unwrap(), bytes);
assert_eq!(std::fs::read(future).unwrap(), bytes);
}
+ let avatar = exec.root.join("home/phoebus/.face");
+ assert!(std::fs::read_to_string(&avatar)
+ .unwrap()
+ .contains(">P"));
let custom = exec
.root
.join("home/phoebus/Pictures/Wallpapers/desert-arch.jpg");
std::fs::write(&custom, b"user's edited wallpaper").unwrap();
+ std::fs::write(&avatar, b"user's own profile picture").unwrap();
provision_wallpapers(&exec, &cfg).unwrap();
assert_eq!(std::fs::read(custom).unwrap(), b"user's edited wallpaper");
+ assert_eq!(
+ std::fs::read(avatar).unwrap(),
+ b"user's own profile picture"
+ );
assert!(runner.recorded().iter().any(|spec| {
spec.program == "chroot"
&& spec
diff --git a/installer-rs/crates/phoebus-executor/tests/session_script.rs b/installer-rs/crates/phoebus-executor/tests/session_script.rs
index bd1c438..301985e 100644
--- a/installer-rs/crates/phoebus-executor/tests/session_script.rs
+++ b/installer-rs/crates/phoebus-executor/tests/session_script.rs
@@ -86,6 +86,7 @@ impl Fixture {
.env("DBUS_SESSION_BUS_ADDRESS", "unix:path=/run/test-bus")
.env("SESSION_TEST_DIR", self.dir.path())
.env("HOME", self.dir.path())
+ .env("USER", "phoebus")
.stdout(Stdio::null())
.stderr(Stdio::piped())
.spawn()
@@ -148,3 +149,64 @@ fn failure_to_create_the_socket_is_reported() {
);
assert!(fixture.read("helpers.log").is_empty());
}
+
+#[test]
+fn first_login_seeds_wallpaper_folder_and_letter_avatar_without_replacing_choices() {
+ let fixture = Fixture::new(MANGO_OK);
+ let wallpapers = fixture.dir.path().join("Pictures/Wallpapers");
+ std::fs::create_dir_all(&wallpapers).unwrap();
+ std::fs::write(wallpapers.join("aurora-lagoon.jpg"), b"sample image").unwrap();
+
+ let (status, stderr) = fixture.run();
+ assert!(status.success(), "session failed: {stderr}");
+ let state = fixture
+ .dir
+ .path()
+ .join(".local/state/DankMaterialShell/session.json");
+ let cache = fixture
+ .dir
+ .path()
+ .join(".cache/DankMaterialShell/cache.json");
+ let avatar = fixture.dir.path().join(".face");
+ let state_json: serde_json::Value =
+ serde_json::from_slice(&std::fs::read(&state).unwrap()).unwrap();
+ let cache_json: serde_json::Value =
+ serde_json::from_slice(&std::fs::read(&cache).unwrap()).unwrap();
+ assert_eq!(
+ state_json["wallpaperPath"],
+ wallpapers
+ .join("aurora-lagoon.jpg")
+ .to_string_lossy()
+ .as_ref()
+ );
+ assert_eq!(
+ cache_json["wallpaperLastPath"],
+ wallpapers.to_string_lossy().as_ref()
+ );
+ assert_eq!(
+ cache_json["fileBrowserSettings"]["wallpaper"]["lastPath"],
+ wallpapers.to_string_lossy().as_ref()
+ );
+ assert!(std::fs::read_to_string(&avatar)
+ .unwrap()
+ .contains(">P"));
+
+ std::fs::write(
+ &state,
+ "{\"configVersion\":4,\"wallpaperPath\":\"/chosen/image.jpg\"}",
+ )
+ .unwrap();
+ std::fs::write(&cache, "{\"configVersion\":3,\"wallpaperLastPath\":\"/chosen\",\"fileBrowserSettings\":{\"wallpaper\":{\"lastPath\":\"/chosen\"}}}").unwrap();
+ std::fs::write(&avatar, b"custom avatar").unwrap();
+ std::fs::remove_file(fixture.runtime.join("wayland-0")).unwrap();
+
+ let (status, stderr) = fixture.run();
+ assert!(status.success(), "second session failed: {stderr}");
+ assert!(fixture
+ .read(".local/state/DankMaterialShell/session.json")
+ .contains("/chosen/image.jpg"));
+ assert!(fixture
+ .read(".cache/DankMaterialShell/cache.json")
+ .contains("/chosen"));
+ assert_eq!(std::fs::read(&avatar).unwrap(), b"custom avatar");
+}