clawdie-iso/doc/XFCE-PANEL-BUGS-HANDOFF.md

# XFCE Panel Visual Bugs — Build Verification Handoff

**From:** Claude Reviewer / XFCE Tweaker (Linux)
**Date:** 24.maj.2026
**Status:** Visual-polish lane COMPLETE (Pass 1 + Pass 2, on `main`, build-ready: panel XML valid, `build.sh` install paths + Whisker icon verified). → **Awaiting ISO rebuild on the FreeBSD build host (osa) + a boot on the AMD/ASUS box** to check the verification items below. No domedog/config work remains.

## Pre-build changes applied (24.may.2026)

The XFCE Tweaker applied the low-risk config fixes directly to the panel-skel
so the next image carries them. The base AMD ASUS hardware collection has since been recorded in `doc/AMD-ASUS-XFCE-LIVE-USB-FINDINGS.md`. This handoff now tracks only the remaining XFCE panel/icon polish. What changed:

- **Issue 1 (Start icon):** replaced `button-icon="freebsd"` with a custom
  branded triangle PNG referenced by **absolute path**
  (`/usr/local/share/clawdie-iso/icons/clawdie-start.png`), so it never depends
  on an icon-theme cache being current at first login. Asset source:
  `live/operator-session/icons/clawdie-start.svg`. **Verify:** the triangle
  renders on the panel (not a broken glyph).
- **Issue 2 (Clock):** added explicit `mode=2` (digital) + white `fg-color`
  defensively. **Verify:** root cause may still be **Noto Sans missing/uncached**
  — run the `fc-list` / plugin `.so` checks below.
- **Issue 3 (Clipman):** **dropped from the default panel** (removed `plugin-13`
  from `plugin-ids` and its definition) so the image boots without the error
  dialog. Re-add once the D-Bus root cause is found (diagnostics below retained).
- **Issue 4 (xkb):** set `display-type=1` (layout text instead of oversized flag).
- **Issues 5+6 (systray/mixer sizes):** set panel `icon-size=2` (24px). **Verify:**
  XFCE systray may still ignore this — confirm NetworkMgr/mixer icon sizes.

Also: the desktop wallpaper now points at `clawdie-operator-bg.png` (brand
gradient + triangle motif); the old `clawdie-dark-grad.svg` was removed. Both
assets ship as PNG to avoid depending on a librsvg gdk-pixbuf loader that is not
in the package lists.

## Pre-build changes applied (25.may.2026) — Pass 2

Follow-up operator polish, **config-only** (no build.sh / hardware changes).
Targets the residual "panel size" + "network/mixer icons too small /
inconsistent" complaints (issues 5+6) that Pass 1's `icon-size=2` did not
resolve, because the XFCE systray renders theme-fixed (~22px) icons and ignores
the panel `icon-size`.

- **Panel size:** reduced `size` from `48` to `40` (`xfce4-panel.xml:8`).
  `icon-size` stays `2` (24px). On a 48px panel, 24px icons left ~12px of
  vertical padding and the fixed ~22px systray icons looked lost; at 40px the
  padding drops to ~8px so launchers, xkb text, and tray icons read as one
  proportionate row. Reversible single value; `36` is the tighter alternative
  if 40 still looks tall on the operator's display.
- **Systray (network/mixer):** added `square-icons=true` to plugin-8
  (`xfce4-panel.xml:88`) so tray icons render at a uniform square footprint
  instead of width-varying. `show-frame` stays `false`.
- **Not re-touched (Pass 1, still pending hardware verify):** Whisker branded
  PNG, xkb `display-type=1` (text, already the compact form requested), clock
  `mode=2`+white. Asset+install paths confirmed in-repo: `clawdie-start.png`
  ships via build.sh:1282-1283 to the absolute path the button references;
  launcher icons use standard XDG names (`firefox`, `system-file-manager`,
  `utilities-terminal`) that Papirus provides.

**Honest config limit:** making the network/mixer icons _absolutely_ larger is
not a config lever — XFCE's systray ignores panel `icon-size`, so absolute
sizing is a theme/build-host concern (Papirus status-icon sizes), left to the
FreeBSD/operator side. Pass 2 only improves _proportion and uniformity_.

**Verify (Pass 2):**

- [ ] 40px panel: launchers, xkb text, clock, and tray icons look like one
      proportionate row (no oversized/undersized outliers).
- [ ] `square-icons` took effect on the systray (network/mixer icons square and
      uniform) — confirm the installed `systray` plugin honors the property.

## Pre-build changes applied (01.jun.2026) — Pass 3

Follow-up from the AMD live report and direct `xfconf-query` checks:

- **Start icon:** the live image had only `/usr/local/share/clawdie-iso/icons/*`;
  no `clawdie-start` entries existed under `/usr/local/share/icons`. The build
  now stages `clawdie-start.png` into `hicolor/48x48/apps` and
  `hicolor/64x64/apps`, stages the SVG into `hicolor/scalable/apps`, updates the
  `hicolor` cache at build time, and uses the themed icon name
  `button-icon="clawdie-start"`.
- **Mixer:** `xfce4-mixer` auto-selected `ATIR6xxHDMI`/`Vol` on AMD hardware even
  when FreeBSD's default sound unit was the internal Realtek speaker. The default
  panel now omits the mixer plugin instead of shipping a visible control pinned
  to HDMI. Re-add only after a reliable backend/default-device strategy exists.

## Deletion Criteria

- [ ] Whiskermenu Start button icon is visible (not missing/broken).
- [ ] Clock plugin renders date+time in the panel.
- [ ] Clipman re-added and loads without "could not be loaded" dialog (dropped
      from this build pending D-Bus root-cause).
- [ ] Systray icons (NetworkMgr) and xkb flag/text display 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
  <property name="plugin-12" type="string" value="clock">
    <property name="digital-format" type="string" value="%H:%M %d.%b.%Y"/>
    <property name="font" type="string" value="Noto Sans 14"/>
  </property>
  ```
- **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:** `<property name="plugin-13" type="string" value="clipman"/>`
- **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
  <property name="plugin-10" type="string" value="xkb">
    <property name="display-type" type="uint" value="0"/>
    <property name="display-name" type="uint" value="0"/>
    <property name="group-policy" type="uint" value="0"/>
  </property>
  ```
- **`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 `<property name="display-type" type="uint" value="1"/>` to show
    layout text (e.g., "us" / "si") instead of oversized flag images.
  - OR add `<property name="display-type" type="uint" value="2"/>` 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 address issues 1, 2, 4, 5, 6.
**Applied to the panel-skel on 24.may.2026** (see "Pre-build changes applied"
above). Retained here as the record of what changed and the fallback options if
build-host verification shows a fix did not take.

### xfce4-panel.xml changes

```xml
<!-- Issue 1: fix whiskermenu icon -->
<!-- BEFORE -->
<property name="button-icon" type="string" value="freebsd"/>
<!-- AFTER (if "start-here" is confirmed available in Papirus on FreeBSD) -->
<property name="button-icon" type="string" value="start-here"/>

<!-- Issues 4+5+6: unify icon sizes -->
<!-- BEFORE (panel-1) -->
<property name="icon-size" type="uint" value="0"/>
<!-- AFTER -->
<property name="icon-size" type="uint" value="2"/>

<!-- Issue 4: shrink xkb flag to text -->
<!-- BEFORE -->
<property name="display-type" type="uint" value="0"/>
<!-- AFTER -->
<property name="display-type" type="uint" value="1"/>
```

### Clock (issue 2) — if font is present but color is wrong

```xml
<!-- Add explicit foreground color (white on dark panel) -->
<property name="plugin-12" type="string" value="clock">
  <property name="digital-format" type="string" value="%H:%M %d.%b.%Y"/>
  <property name="font" type="string" value="Noto Sans 14"/>
  <property name="mode" type="uint" value="2"/>
  <property name="fg-color" type="array">
    <value type="uint" value="65535"/>
    <value type="uint" value="65535"/>
    <value type="uint" value="65535"/>
    <value type="uint" value="65535"/>
  </property>
</property>
```