diff --git a/doc/XFCE-PANEL-BUGS-HANDOFF.md b/doc/XFCE-PANEL-BUGS-HANDOFF.md new file mode 100644 index 00000000..d96baf67 --- /dev/null +++ b/doc/XFCE-PANEL-BUGS-HANDOFF.md @@ -0,0 +1,279 @@ +# XFCE Panel Visual Bugs — Build Verification Handoff + +**From:** Claude Reviewer / XFCE Tweaker (Linux) +**Date:** 24.maj.2026 +**Status:** OPEN — needs FreeBSD build-host diagnostics + +## Deletion Criteria + +- [ ] Whiskermenu Start button icon is visible (not missing/broken). +- [ ] Clock plugin renders date+time in the panel. +- [ ] Clipman loads without "could not be loaded" dialog. +- [ ] Systray icons (NetworkMgr, mixer) and xkb flag icon are visually + uniform in size — no oversized or undersized outliers. +- [ ] All fixes confirmed on real hardware boot (not just image inspection). + +## Operator-Reported Issues + +Six issues from the latest build on real hardware. Ordered by likelihood +of being a config-only fix vs needing build-host investigation. + +### 1. Whiskermenu Start button — missing icon + +- **File:** `live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml:47` +- **Current value:** `button-icon` is `"freebsd"` +- **Problem:** The `"freebsd"` icon name resolves to nothing in the + installed icon themes (Papirus, Adwaita, hicolor). The Papirus theme + does not ship a `freebsd` icon. XFCE falls back to a broken/missing + icon glyph. +- **Diagnosis (build host):** + ```sh + # Check what icon themes actually provide for "freebsd" + find /usr/local/share/icons -iname '*freebsd*' -o -iname '*beastie*' 2>/dev/null + # Check if the freebsd-8k-wallpapers package ships any icons + pkg info -l freebsd-8k-wallpapers | grep -i icon + # Check pixmaps + find /usr/local/share/pixmaps -iname '*freebsd*' 2>/dev/null + ``` +- **Likely fix options:** + - Use `"start-here"` (standard XDG menu icon; Papirus ships it). + - Use `"org.freebsd"` if the OS provides it in hicolor. + - Ship a custom beastie SVG/PNG into the Papirus or hicolor theme as + part of `build.sh`. +- **Scope:** Config-only if `"start-here"` is acceptable. Asset addition + if operator wants the FreeBSD daemon logo specifically. + +### 2. Clock plugin — not rendering + +- **File:** `xfce4-panel.xml` plugin-12 (lines 103-106) +- **Current config:** + ```xml + + + + + ``` +- **Config looks correct.** Clock was working in earlier builds. +- **Possible causes:** + - Noto Sans font not available or not cached at the time the panel + starts. Font config cache may not be regenerated during build. + - Plugin load failure similar to clipman (missing .so dependency). + - Panel background color (#1a1a2e at 85%) blending with clock text + color if the clock inherited a dark text color. +- **Diagnosis (build host):** + ```sh + # Check if clock plugin .so resolves + ldd /usr/local/lib/xfce4/panel/plugins/libxfce4clock.so 2>/dev/null + ldd /usr/local/lib/xfce4/panel/plugins/libdatetime.so 2>/dev/null + # Check Noto Sans availability + fc-list | grep -i 'noto sans' + # Check if the panel XML actually ended up in the image + grep -A5 'plugin-12' /mnt/usr/local/etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml + grep -A5 'plugin-12' /mnt/home/clawdie/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml + # Check for session-level panel errors + cat /mnt/home/clawdie/.cache/xfce4-panel.log 2>/dev/null + ``` +- **If font is present and plugin loads:** the issue may be foreground + color. Consider adding explicit `fg-color` property or switching to + the analog clock mode temporarily to confirm the plugin itself works. + +### 3. Clipman — "could not be loaded" on startup + +- **File:** `xfce4-panel.xml` plugin-13 (line 102) +- **Current config:** `` +- **History:** Clipman was removed in `2fc4ca1` due to this exact error, + restored in `70634ef` after adding an ldd diagnostic gate to TESTING.md. + The ldd check passes at build time but the error still appears at + runtime on real hardware. +- **ldd is necessary but not sufficient.** It catches missing shared + libraries but NOT missing D-Bus services, X11 ICCCM atoms, or + permission issues. +- **Diagnosis (build host — on real hardware after boot):** + ```sh + # Check if the clipman .so has all deps (should pass if build passed) + ldd /usr/local/lib/xfce4/panel/plugins/libxfce4clipman.so + # Check D-Bus activation (clipman registers a D-Bus service) + ls /usr/local/share/dbus-1/services/org.xfce.clipman*.service + dbus-send --session --dest=org.xfce.panel --type=method_call /org/xfce/panel org.xfce.panel.getPluginList 2>&1 || true + # Check session log for the actual error message + grep -ri 'could not be loaded\|clipman' ~/.cache/xfce4-session/*.log 2>/dev/null + grep -ri 'could not be loaded\|clipman' ~/.cache/xfce4-panel.log 2>/dev/null + # Check if xfce4-panel can list the plugin + xfce4-panel --plugin-list 2>&1 | grep -i clipman + ``` +- **Possible root causes:** + - Missing or broken D-Bus service file for clipman. + - The live user `clawdie` lacks a D-Bus session bus at panel start. + - libqrencode or optional dependency missing at runtime. + - Plugin expects Xfconf to have a pre-existing channel that doesn't + exist on first boot. + +### 4. XKB keyboard icon — too large + +- **File:** `xfce4-panel.xml` plugin-10 (lines 97-101) +- **Current config:** + ```xml + + + + + + ``` +- **`display-type=0` means "show flag image".** Flag SVGs in Papirus are + typically 48x48 or scalable with no intrinsic size cap. Other systray + icons render at 22px or 24px because the systray plugin constrains + them. The xkb plugin renders independently and does not inherit the + panel's `icon-size` setting. +- **Diagnosis (build host):** + ```sh + # Check actual flag icon size in Papirus + find /usr/local/share/icons/Papirus -iname '*flag*si*' -o -iname '*flag*us*' 2>/dev/null + identify /usr/local/share/icons/Papirus/48x48/panel/xfpm-keyboard-*.png 2>/dev/null || true + # Check if xkb has a size property + xfconf-query -c xfce4-panel -p /plugins/plugin-10 -l -v 2>/dev/null + ``` +- **Likely fixes:** + - Add `` to show + layout text (e.g., "us" / "si") instead of oversized flag images. + - OR add `` for + the "image + text" mode which may render smaller. + - OR set panel `icon-size` to an explicit value (e.g., `24`) which + may constrain the xkb plugin too. + +### 5. NetworkMgr icon — too small / barely visible + +- **NetworkMgr is a systray icon** (auto-registered in plugin-8 + `systray`). Systray icons respect the icon theme's panel/status + directory sizes, which default to 22px in Papirus. +- **If the panel is 48px tall** and most icons are 22px, they will look + small. This is a Papirus theme default, not a bug in NetworkMgr. +- **Diagnosis (build host):** + ```sh + find /usr/local/share/icons/Papirus/panel/ -name '*network*' 2>/dev/null + find /usr/local/share/icons/Papirus/22x22/status/ -name '*network*' 2>/dev/null + find /usr/local/share/icons/Papirus/24x24/status/ -name '*network*' 2>/dev/null + ``` +- **Possible fix:** Set panel `icon-size` from `0` (auto) to a specific + pixel value. XFCE panel `icon-size` values: `0`=auto, `1`=16px, + `2`=24px, `3`=32px, `4`=48px. Setting to `2` (24px) would force all + panel icons to 24px. However, systray icons may still ignore this — + XFCE's systray plugin is known to not fully respect `icon-size`. + +### 6. Sound (mixer) icon — size mismatch with other icons + +- **File:** `xfce4-panel.xml` plugin-11 (lines 93-96) +- **Mixer plugin has no size property.** It renders at whatever size the + icon theme provides for audio-volume icons. +- **Same underlying issue as #5:** inconsistent icon sizes across panel + plugins because XFCE doesn't enforce a single icon size across all + plugin types. +- **Unified fix approach (covers issues 4, 5, 6):** + - Set panel `icon-size` to an explicit value (suggest `2` = 24px). + - This constrains launchers, whiskermenu, and most plugins. + - For systray: XFCE 4.16+ systray does not fully obey `icon-size`. + If the 24px panel setting doesn't fix systray icons, the remaining + option is to patch the Papirus theme or switch to an icon theme with + larger default status icons. + - For xkb: switch from flag images (`display-type=0`) to text + (`display-type=1`) or set an explicit size property if available. + +## Build-Host Commands to Run + +Codex ISO Builder — please run these on the FreeBSD build host against +the **latest built image** (mounted or live-booted) and report back +exact output: + +```sh +# 1. Confirm all icon themes are installed +pkg info -e papirus-icon-theme adwaita-icon-theme hicolor-icon-theme + +# 2. Find any FreeBSD/OS-branding icons +find /usr/local/share/icons /usr/local/share/pixmaps \ + -iname '*freebsd*' -o -iname '*beastie*' 2>/dev/null + +# 3. Check "start-here" icon availability (potential fix for issue 1) +find /usr/local/share/icons/Papirus -name 'start-here*' 2>/dev/null + +# 4. Check clock plugin shared libs +ldd /usr/local/lib/xfce4/panel/plugins/libxfce4clock.so 2>/dev/null +ldd /usr/local/lib/xfce4/panel/plugins/libdatetime.so 2>/dev/null + +# 5. Check clipman shared libs + D-Bus service +ldd /usr/local/lib/xfce4/panel/plugins/libxfce4clipman.so 2>/dev/null +ls /usr/local/share/dbus-1/services/org.xfce.clipman* 2>/dev/null + +# 6. Check mixer plugin shared libs +ldd /usr/local/lib/xfce4/panel/plugins/libxfce4mixer.so 2>/dev/null + +# 7. Check Noto Sans font availability +fc-list | grep -i 'noto sans' + +# 8. Check flag icon sizes in Papirus +find /usr/local/share/icons/Papirus -name '*flag*' \ + -path '*/panel/*' -o -name '*flag*' -path '*/status/*' 2>/dev/null | head -20 + +# 9. Check network/volume icon sizes +find /usr/local/share/icons/Papirus -name '*network*' -path '*/status/*' 2>/dev/null | head -10 +find /usr/local/share/icons/Papirus -name '*audio-volume*' -path '*/status/*' 2>/dev/null | head -10 + +# 10. Full panel plugin .so audit (from TESTING.md) +for _so in /usr/local/lib/xfce4/panel/plugins/*.so; do + _missing=$(ldd "$_so" 2>&1 | grep 'not found' || true) + if [ -n "$_missing" ]; then echo "FAIL: $_so"; echo "$_missing"; fi +done + +# 11. Verify xfconf XML landed in both XDG and user home +grep -c 'plugin-12' /usr/local/etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml +grep -c 'plugin-12' /home/clawdie/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml +``` + +## Results + +_Codex ISO Builder: paste exact command output here, then mark issues +above with findings._ + +--- + +## Config-Change Candidates + +These are the XML changes that likely address issues 1, 2, 4, 5, 6. +**Do not apply until build-host diagnostics confirm root causes.** + +### xfce4-panel.xml changes + +```xml + + + + + + + + + + + + + + + + + +``` + +### Clock (issue 2) — if font is present but color is wrong + +```xml + + + + + + + + + + + + +```