⚠️ Potential issue | 🟠 Major | ⚡ Quick win

#!/bin/bash
set -euo pipefail

echo "== XDG Desktop Portal Settings docs =="
curl -fsSL https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html \
  | rg -n "SettingChanged|org\.freedesktop\.appearance|color-scheme|implementation details"

echo
echo "== Current Wails Linux theme-monitor code paths =="
fd 'application_linux.*\.go$' v3/pkg/application -t f \
  | xargs rg -n -C2 'org\.freedesktop\.appearance|org\.gnome\.desktop\.interface|SystemThemeChanged|color-scheme'

#!/bin/bash
set -euo pipefail

echo "=== Build tags on relevant files ==="
head -1 v3/pkg/application/application_linux*.go

echo
echo "=== File list with build tags ==="
ls -la v3/pkg/application/application_linux*.go

echo
echo "=== Check if both files are included in same build ==="
grep -r "monitorThemeChanges\|monitorPowerEvents" v3/pkg/application/*.go | head -20

#!/bin/bash
set -euo unpipefail

echo "=== Full context: where monitorThemeChanges is called ==="
rg -n "monitorThemeChanges\|monitorPowerEvents" v3/pkg/application -A2 -B2

echo
echo "=== Check the linuxApp type and its definition ==="
rg -n "type linuxApp struct" v3/pkg/application -A20

#!/bin/bash
set -euo pipefail

echo "=== Context: where monitorThemeChanges is called and how linuxApp is initialized ==="
rg -n "monitorThemeChanges\|monitorPowerEvents" v3/pkg/application -B5 -A1 | head -40

echo
echo "=== linuxApp struct definition and init ==="
rg -n "type linuxApp struct" v3/pkg/application -A15 | head -25

#!/bin/bash
set -euo pipefail

echo "=== Check if monitorThemeChanges subscribes to portal or dbus directly ==="
sed -n '10,70p' v3/pkg/application/application_linux_dbus.go

echo
echo "=== Check what namespace the subscription is listening to ==="
rg -n "MatchRule|AddMatch" v3/pkg/application/application_linux_dbus.go -B2 -A2

#!/bin/bash
set -euo pipefail

echo "=== Check portal documentation for color-scheme type and signal structure ==="
curl -fsSL https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html \
  | rg -n "color-scheme|SettingChanged" -A8 -B2 | grep -A8 "SettingChanged"

echo
echo "=== Check if application_linux.go shows how it parses the portal value ==="
sed -n '180,195p' v3/pkg/application/application_linux.go

echo
echo "=== Check the isDarkMode logic to see what value types are expected ==="
rg -n "isDarkMode" v3/pkg/application -A5 | head -30

#!/bin/bash
set -euo pipefail

echo "=== Get full portal Settings spec for color-scheme including the value type ==="
curl -fsSL https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html \
  | rg -n "org\.freedesktop\.appearance.*color-scheme" -B2 -A5

echo
echo "=== Check if there's any fallback or secondary theme detection path ==="
rg -n "color-scheme\|monitorTheme" v3/pkg/application/application_linux.go -B3 -A3

Fix the portal namespace and value type in the theme signal parser.

The parser on lines 32–50 hard-codes org.gnome.desktop.interface and expects a string value, but the XDG Desktop Portal Settings spec standardizes org.freedesktop.appearance/color-scheme with an unsigned integer type (u, where 0=no preference, 1=light, 2=dark). In GTK4 builds, both application_linux.go and application_linux_dbus.go register theme monitors, so signals from the portal (which uses the standardized namespace) are silently rejected by this parser. While xdg-desktop-portal-gtk mirrors the GNOME key as well, non-GNOME portal backends only guarantee the standardized namespace, causing missed theme changes.

Accept the standardized payload namespace and parse the unsigned integer value correctly, or support both shapes for backwards compatibility with GNOME-specific backends.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@v3/pkg/application/application_linux_dbus.go` around lines 32 - 50, The
getTheme parser currently only accepts the GNOME-specific
"org.gnome.desktop.interface" + "color-scheme" and expects a string; update
getTheme to also accept the standardized portal namespace
"org.freedesktop.appearance" with key "color-scheme" and to handle the D-Bus
unsigned integer payload (dbus.Variant containing a uint32 for 'u'). Keep
backward compatibility by still accepting the GNOME form and string variants: if
variant.Value() is a uint32 map 0->"" (no preference), 1->"light", 2->"dark"
(returning the corresponding string), and if variant.Value() is a string return
it as before; return false for any other shapes/types. Reference: the getTheme
closure defined in application_linux_dbus.go that inspects
body[0]/body[1]/body[2].

Skipping in this PR — this is pre-existing behaviour that I just moved (the parser was already in application_linux_gtk3.go before the file rename in #5463). It targets the GNOME-mirrored portal payload; on the GTK4 default path, the canonical portal listener (listenForSystemThemeChanges in application_linux.go) already uses the standardized org.freedesktop.appearance namespace, so the regression in #5474 isn't this. Worth doing as a separate change — happy to file a follow-up if you want it tracked.

@leaanthony, that makes sense — since listenForSystemThemeChanges in application_linux.go already handles the standardized org.freedesktop.appearance namespace on the GTK4 path, this parser's GNOME-specific behavior is redundant rather than a regression blocker. The concern is still worth tracking for non-GNOME portal backends (KDE, COSMIC, etc.) where the GNOME mirror isn't guaranteed.

Would you like me to open a follow-up GitHub issue to track adding org.freedesktop.appearance + uint32 support to getTheme in application_linux_dbus.go? I can file it now and link back to this PR.

Learnt from: symball
Repo: wailsapp/wails PR: 4853
File: v2/internal/system/system.go:128-152
Timestamp: 2026-01-04T08:01:00.038Z
Learning: In v2/internal/system/system.go, shared functions like checkLibrary are defined without build tags but are only invoked from platform-specific files (system_linux.go, system_windows.go, system_darwin.go) that have build constraints. Reviewers should ensure there are no runtime OS checks in system.go and that platform-specific behavior is controlled via build tags. If runtime switches exist, remove them in favor of compile-time platform constraints to reduce overhead and improve correctness.

Learnt from: leaanthony
Repo: wailsapp/wails PR: 4906
File: v3/internal/setupwizard/wizard_windows.go:93-94
Timestamp: 2026-01-26T01:56:49.314Z
Learning: Ensure the Go toolchain minimum version for Wails v3 is 1.25+. Update go.mod to reflect 1.25+ and validate that setup wizard checks enforce Go 1.25+ at release time. Align any CI/go-version checks, documentation, and release notes with this requirement; this guideline applies to all Go files under the v3 module, not just the wizard.

Fixed in 9114d91 — replaced panic(err) with the same warning-and-return pattern used by the surrounding session-bus setup, so a session-bus policy or portal error now disables theme monitoring instead of taking down the app via handlePanic.

Addressed in 9114d91 by dropping a.monitorThemeChanges() from the GTK4 run() so listenForSystemThemeChanges remains the sole GTK4 theme listener — same change CodeRabbit flagged. I left listenForSystemThemeChanges in place because it uses the portal-standard org.freedesktop.appearance namespace and the cross-stack helper in application_linux_dbus.go is still needed for GTK3. Consolidating the two implementations entirely (porting listenForSystemThemeChanges's portal-namespace approach back into the shared helper, then deleting it from application_linux.go) is worth doing, but is broader than this regression fix and I'd rather land that as a follow-up.

Partially addressed in 9114d91: I tightened the variant assertion in isDarkMode (innerVariant, ok := result.Value().(dbus.Variant) instead of an unchecked type assertion) so an unexpected portal payload shape now returns false rather than panicking.

Note: with the same commit, monitorThemeChanges is no longer called on the GTK4 path (it duplicated the existing listenForSystemThemeChanges), so the original cross-file panic-chain you flagged no longer applies here on the default path — isDarkMode is still callable but no longer the trigger point.