feat(backend): expose wal-qt process env and awww daemon format

Add two per-backend escape hatches instead of a generic CLI-flag string,
which would break on positional-arg setters and resist validation.

wal-qt: backend.wal-qt.env, a list of KEY=VALUE entries merged into the
wal-qt-host process environment at spawn. Stored as a list (not a map)
because Viper lowercases map keys and env var names are case-sensitive.
ValidateConfig rejects malformed entries and daemon-managed keys
(WAYLAND_DISPLAY, XDG_RUNTIME_DIR, DISPLAY, PATH, HOME, LD_PRELOAD,
LD_LIBRARY_PATH). This is the supported way to set
QTWEBENGINE_CHROMIUM_FLAGS and other Qt/Chromium rendering knobs.

awww: backend.awww.daemon_format, passed to `awww-daemon --format`
(argb|abgr|rgb|bgr) at spawn; takes effect on the next daemon restart.

Settings UI gets a key/value env editor for wal-qt (with a client-side
protected-key warning) and a format dropdown for awww. Both fields are
daemon-scoped, so the UI notes they apply after a backend restart.

Also fixes a pre-existing tsc error: blur_nsfw_thumbnails missing from
the hard-coded default Wallhaven config in settingsStore.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: 0bCdian

daemon/API_CONTRACT.md

@@ -1349,12 +1349,15 @@ Returned by `GET /config/backends/awww`. Updated by `PATCH /config/backends/awww
   "resize": "crop",
   "fill_color": "000000",
   "filter_type": "Lanczos3",
-  "invert_y": false
+  "invert_y": false,
+  "daemon_format": ""
 }
 ```
 
 TOML config supports both hyphens and underscores (e.g. `transition-type` and `transition_type` are equivalent).
 
+`daemon_format` is passed to `awww-daemon --format` (`argb` | `abgr` | `rgb` | `bgr`; empty = awww default). It is read only when the daemon spawns `awww-daemon`, so it takes effect on the next awww-daemon restart, and only when waypaper started the daemon itself.
+
 #### mpvpaper Backend Config
 
 Returned by `GET /config/backends/mpvpaper`. Updated by `PATCH /config/backends/mpvpaper`.
@@ -1370,6 +1373,19 @@ Returned by `GET /config/backends/mpvpaper`. Updated by `PATCH /config/backends/
 }
 ```
 
+#### wal-qt Backend Config
+
+Returned by `GET /config/backends/wal-qt`. Updated by `PATCH /config/backends/wal-qt`.
+Only the fields relevant to process environment are shown here:
+
+```json
+{
+  "env": ["QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu --ignore-gpu-blocklist", "QSG_RHI_BACKEND=software"]
+}
+```
+
+`env` is a list of `KEY=VALUE` entries merged into the `wal-qt` process environment at spawn — the escape hatch for Qt/Chromium rendering knobs. It is stored as a list (not a map) because Viper lowercases map keys and environment variable names are case-sensitive. `PATCH` rejects entries that are not in `KEY=VALUE` form and entries whose key is daemon-managed: `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR`, `DISPLAY`, `PATH`, `HOME`, `LD_PRELOAD`, `LD_LIBRARY_PATH`. Read only at spawn, so changes take effect on the next wal-qt restart.
+
 #### MonitorsConfig
 
 ```json

daemon/internal/backend/awww/awww.go

@@ -23,6 +23,21 @@ const (
 	daemonBinary = "awww-daemon"
 )
 
+// validDaemonFormats are the wl_shm formats accepted by `awww-daemon --format`.
+var validDaemonFormats = map[string]bool{"argb": true, "abgr": true, "rgb": true, "bgr": true}
+
+// awwwDaemonArgs builds the argv for awww-daemon. --no-cache is always set:
+// waypaper drives wallpaper selection explicitly via `awww img`, so the daemon
+// must not restore its own cache on startup. format, when non-empty, adds
+// `--format <value>`.
+func awwwDaemonArgs(format string) []string {
+	args := []string{"--no-cache"}
+	if format != "" {
+		args = append(args, "--format", format)
+	}
+	return args
+}
+
 type Awww struct {
 	once    sync.Once
 	v       *viper.Viper
@@ -80,8 +95,13 @@ func (a *Awww) Initialize(ctx context.Context) error {
 		return nil
 	}
 
-	slog.Info("starting daemon with --no-cache", "binary", daemonBinary)
-	cmd := exec.Command(daemonBinary, "--no-cache")
+	format := ""
+	if a.v != nil {
+		format = strings.ToLower(strings.TrimSpace(a.v.GetString("backend.awww.daemon_format")))
+	}
+	args := awwwDaemonArgs(format)
+	slog.Info("starting daemon", "binary", daemonBinary, "args", args)
+	cmd := exec.Command(daemonBinary, args...)
 	cmd.SysProcAttr = &syscall.SysProcAttr{Pdeathsig: syscall.SIGTERM}
 	if err := cmd.Start(); err != nil {
 		return fmt.Errorf("awww: start %s: %w", daemonBinary, err)
@@ -239,6 +259,7 @@ func (a *Awww) RegisterDefaults(v *viper.Viper) {
 	v.SetDefault("backend.awww.fill_color", "000000")
 	v.SetDefault("backend.awww.filter_type", string(FilterLanczos3))
 	v.SetDefault("backend.awww.invert_y", false)
+	v.SetDefault("backend.awww.daemon_format", "")
 }
 
 // loadConfigFromViper reads the [backend.awww] section from the TOML config via Viper.
@@ -333,5 +354,8 @@ func (a *Awww) ValidateConfig(raw json.RawMessage) error {
 	if cfg.TransitionDuration < 0 || cfg.TransitionDuration > 120 {
 		return fmt.Errorf("awww: transition_duration must be between 0 and 120 seconds")
 	}
+	if f := strings.ToLower(strings.TrimSpace(cfg.DaemonFormat)); f != "" && !validDaemonFormats[f] {
+		return fmt.Errorf("awww: daemon_format must be one of argb, abgr, rgb, bgr")
+	}
 	return nil
 }

daemon/internal/backend/awww/config.go

@@ -13,6 +13,12 @@ type Config struct {
 	FillColor          string             `mapstructure:"fill_color" json:"fill_color"`
 	FilterType         FilterType         `mapstructure:"filter_type" json:"filter_type"`
 	InvertY            bool               `mapstructure:"invert_y" json:"invert_y"`
+	// DaemonFormat, when non-empty, is passed to `awww-daemon --format`
+	// (argb|abgr|rgb|bgr) — a wl_shm format. Empty leaves awww-daemon on its
+	// own default (argb). Read only at Initialize, so it takes effect on the
+	// next awww-daemon restart, and only when waypaper spawned the daemon
+	// itself (a pre-existing awww-daemon is left untouched).
+	DaemonFormat string `mapstructure:"daemon_format" json:"daemon_format"`
 }
 
 type TransitionType string

daemon/internal/backend/awww/daemon_test.go

@@ -0,0 +1,29 @@
+package awww
+
+import (
+	"slices"
+	"testing"
+)
+
+func TestAwwwDaemonArgs(t *testing.T) {
+	if got := awwwDaemonArgs(""); !slices.Equal(got, []string{"--no-cache"}) {
+		t.Fatalf("awwwDaemonArgs(\"\") = %v, want [--no-cache]", got)
+	}
+	got := awwwDaemonArgs("rgb")
+	want := []string{"--no-cache", "--format", "rgb"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("awwwDaemonArgs(\"rgb\") = %v, want %v", got, want)
+	}
+}
+
+func TestValidateConfigDaemonFormat(t *testing.T) {
+	b := New()
+	for _, f := range []string{"", "argb", "abgr", "rgb", "bgr"} {
+		if err := b.ValidateConfig([]byte(`{"daemon_format":"` + f + `"}`)); err != nil {
+			t.Fatalf("daemon_format %q rejected: %v", f, err)
+		}
+	}
+	if err := b.ValidateConfig([]byte(`{"daemon_format":"xrgb"}`)); err == nil {
+		t.Fatal("invalid daemon_format accepted, want rejection")
+	}
+}

daemon/internal/backend/walqt/config.go

@@ -52,6 +52,14 @@ type Config struct {
 	FillColor              string `mapstructure:"fill_color" json:"fill_color"`
 	VideoAudioDefault      bool   `mapstructure:"video_audio_default" json:"video_audio_default"`
 	AllowNetworkWallpapers bool   `mapstructure:"allow_network_wallpapers" json:"allow_network_wallpapers"`
+	// Env holds extra environment variables ("KEY=VALUE" each) merged into the
+	// wal-qt process environment at spawn — the escape hatch for Qt/Chromium
+	// rendering knobs (QTWEBENGINE_CHROMIUM_FLAGS, QSG_RHI_BACKEND, …) on hosts
+	// without a usable GPU. Protected keys (see protectedEnvKeys) are rejected
+	// by ValidateConfig. Stored as a list, not a map, because Viper lowercases
+	// map keys and env var names are case-sensitive. Takes effect on the next
+	// wal-qt (re)spawn.
+	Env []string `mapstructure:"env" json:"env"`
 }
 
 func defaultSocketPath() string {

daemon/internal/backend/walqt/env.go

@@ -0,0 +1,62 @@
+package walqt
+
+import (
+	"fmt"
+	"strings"
+)
+
+// protectedEnvKeys are environment variables the daemon owns. The user may not
+// override them through backend.wal-qt.env: doing so silently breaks the
+// wal-qt spawn (wrong Wayland socket, missing binary, wrong home dir, injected
+// libraries) with no obvious cause. Everything else is allowed — the env map
+// is an escape hatch, so it stays wide open apart from these.
+var protectedEnvKeys = map[string]bool{
+	"WAYLAND_DISPLAY": true,
+	"XDG_RUNTIME_DIR": true,
+	"DISPLAY":         true,
+	"PATH":            true,
+	"HOME":            true,
+	"LD_PRELOAD":      true,
+	"LD_LIBRARY_PATH": true,
+}
+
+// validateEnvEntries checks that every entry is a well-formed "KEY=VALUE" pair
+// with a non-empty, whitespace-free key that is not in protectedEnvKeys.
+func validateEnvEntries(entries []string) error {
+	for _, e := range entries {
+		key, _, ok := strings.Cut(e, "=")
+		if !ok {
+			return fmt.Errorf("env entry %q must be in KEY=VALUE form", e)
+		}
+		key = strings.TrimSpace(key)
+		if key == "" {
+			return fmt.Errorf("env entry %q has an empty key", e)
+		}
+		if strings.ContainsAny(key, " \t") {
+			return fmt.Errorf("env key %q must not contain whitespace", key)
+		}
+		if protectedEnvKeys[strings.ToUpper(key)] {
+			return fmt.Errorf("%s is managed by waypaper and cannot be overridden", key)
+		}
+	}
+	return nil
+}
+
+// mergeProcessEnv returns base with the extra "KEY=VALUE" entries appended.
+// os/exec deduplicates Cmd.Env keeping the last occurrence of each key, so
+// appending extra after the inherited environment makes extra entries win.
+// Blank entries are skipped.
+func mergeProcessEnv(base, extra []string) []string {
+	if len(extra) == 0 {
+		return base
+	}
+	merged := make([]string, 0, len(base)+len(extra))
+	merged = append(merged, base...)
+	for _, e := range extra {
+		if strings.TrimSpace(e) == "" {
+			continue
+		}
+		merged = append(merged, e)
+	}
+	return merged
+}

daemon/internal/backend/walqt/env_test.go

@@ -0,0 +1,57 @@
+package walqt
+
+import (
+	"slices"
+	"testing"
+)
+
+func TestValidateEnvEntries(t *testing.T) {
+	cases := []struct {
+		name    string
+		entries []string
+		wantErr bool
+	}{
+		{"nil", nil, false},
+		{"valid chromium flags", []string{"QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu --ignore-gpu-blocklist"}, false},
+		{"valid multiple", []string{"QSG_RHI_BACKEND=software", "LIBGL_ALWAYS_SOFTWARE=1"}, false},
+		{"empty value allowed", []string{"FOO="}, false},
+		{"missing equals", []string{"NOEQUALS"}, true},
+		{"empty key", []string{"=value"}, true},
+		{"whitespace in key", []string{"BAD KEY=v"}, true},
+		{"protected WAYLAND_DISPLAY", []string{"WAYLAND_DISPLAY=wayland-9"}, true},
+		{"protected key case-insensitive", []string{"path=/evil"}, true},
+		{"protected LD_PRELOAD", []string{"LD_PRELOAD=/tmp/x.so"}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateEnvEntries(tc.entries)
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("validateEnvEntries(%v) err = %v, wantErr %v", tc.entries, err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestMergeProcessEnv(t *testing.T) {
+	base := []string{"PATH=/usr/bin", "HOME=/home/u"}
+
+	if got := mergeProcessEnv(base, nil); !slices.Equal(got, base) {
+		t.Fatalf("empty extra: got %v, want %v", got, base)
+	}
+
+	got := mergeProcessEnv(base, []string{"FOO=bar", "   ", "BAZ=qux"})
+	want := []string{"PATH=/usr/bin", "HOME=/home/u", "FOO=bar", "BAZ=qux"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("merge: got %v, want %v", got, want)
+	}
+}
+
+func TestValidateConfigRejectsProtectedEnv(t *testing.T) {
+	b := New()
+	if err := b.ValidateConfig([]byte(`{"env":["QT_SCALE_FACTOR=2"]}`)); err != nil {
+		t.Fatalf("valid env rejected: %v", err)
+	}
+	if err := b.ValidateConfig([]byte(`{"env":["PATH=/evil"]}`)); err == nil {
+		t.Fatal("protected env key accepted, want rejection")
+	}
+}

daemon/internal/backend/walqt/walqt.go

@@ -198,6 +198,7 @@ func (w *WalQt) initializeImpl(ctx context.Context) error {
 		"DISPLAY", os.Getenv("DISPLAY"),
 	)
 	cmd := exec.Command(binaryName)
+	cmd.Env = mergeProcessEnv(os.Environ(), cfg.Env)
 	cmd.SysProcAttr = &syscall.SysProcAttr{Pdeathsig: syscall.SIGTERM}
 	// Pipe stdout/stderr through the daemon logger so spawn failures are visible.
 	cmd.Stdout = &slogWriter{prefix: "wal-qt stdout"}
@@ -597,6 +598,7 @@ func (w *WalQt) RegisterDefaults(v *viper.Viper) {
 	v.SetDefault(viperBackendKey+".fill_color", def.FillColor)
 	v.SetDefault(viperBackendKey+".video_audio_default", def.VideoAudioDefault)
 	v.SetDefault(viperBackendKey+".allow_network_wallpapers", def.AllowNetworkWallpapers)
+	v.SetDefault(viperBackendKey+".env", []string{})
 }
 
 func (w *WalQt) ValidateConfig(raw json.RawMessage) error {
@@ -630,6 +632,9 @@ func (w *WalQt) ValidateConfig(raw json.RawMessage) error {
 			return fmt.Errorf("wal-qt: fill_color must be 6- or 8-digit hex (RRGGBB or RRGGBBAA), got %q", cfg.FillColor)
 		}
 	}
+	if err := validateEnvEntries(cfg.Env); err != nil {
+		return fmt.Errorf("wal-qt: %w", err)
+	}
 	return nil
 }
 
@@ -734,6 +739,7 @@ func (w *WalQt) loadConfigFromViper() *Config {
 	}
 	cfg.VideoAudioDefault = getBool("video_audio_default")
 	cfg.AllowNetworkWallpapers = getBool("allow_network_wallpapers")
+	cfg.Env = w.v.GetStringSlice(viperBackendKey + ".env")
 
 	if w.v != nil {
 		cfg.TransitionAngleDeg = normalizeAngleDeg(intFromViperPrefixes(w.v, "transition_angle_deg", cfg.TransitionAngleDeg))

electron/daemon-go-types.ts

@@ -333,6 +333,8 @@ export interface AwwwConfig {
   fill_color: string;
   filter_type: string;
   invert_y: boolean;
+  /** wl_shm format for `awww-daemon --format` (argb|abgr|rgb|bgr). Empty = awww default. Applies on next awww-daemon restart. */
+  daemon_format?: string;
 }
 
 export interface FehConfig {
@@ -399,6 +401,8 @@ export interface WalQtConfig {
   video_audio_default?: boolean;
   /** When true, HTML wallpapers may use fetch/XHR to the network (synced to wal-qt at runtime). */
   allow_network_wallpapers?: boolean;
+  /** Extra environment variables ("KEY=VALUE" each) merged into the wal-qt process at spawn — e.g. QTWEBENGINE_CHROMIUM_FLAGS. Applies on next wal-qt restart. */
+  env?: string[];
 }
 
 export interface MonitorsConfig {