wayland-screenshare-diag

Diagnostic tool for Wayland screen sharing failures on KDE Plasma / Bazzite.

Checks all seven known failure modes in the portal stack and outputs:

• Colour-coded terminal report
• Structured JSON at /tmp/screenshare-diag-<epoch>.json (for the GUI Phase 2)

The seven failure modes it checks

#	Layer	Failure	Symptom
F1	L3	Startup race: portal activated before KWin registers zkde_screencast_unstable_v1	Silent "denied by user"
F2	L2	Wrong backend wins the ScreenCast interface (portal conflict)	Black frames or no dialog
F3	L2	WAYLAND_DISPLAY / XDG_CURRENT_DESKTOP missing from systemd user env	No dialog, silent fail
F4	L5	Stale "deny" in Flatpak permission store	Silent instant rejection
F5	L0	NVIDIA DMA-BUF modifier mismatch or explicit sync fence violation	Chooser appears → black frames
F6	L1	Zombie D-Bus portal session from previous unclean exit	Chooser hangs or no frames
F7	L7	KWin screencast plugin disabled in kwinrc	Same symptom as F1

Installation

# Copy the script
mkdir -p ~/.local/bin
cp wayland-screenshare-diag.sh ~/.local/bin/
chmod +x ~/.local/bin/wayland-screenshare-diag.sh

# Install the ujust recipe (Bazzite only)
mkdir -p ~/.config/ublue-os/just
cp screenshare-diag.just ~/.config/ublue-os/just/

Usage

# Via ujust (Bazzite)
ujust diagnose-screenshare

# Direct
bash ~/.local/bin/wayland-screenshare-diag.sh

# JSON only (for piping / Tauri GUI)
bash ~/.local/bin/wayland-screenshare-diag.sh --json-only

# Quick fixes also available via ujust
ujust restart-portals
ujust reset-screenshare-permissions

JSON report schema

{
  "schema_version": "1",
  "system": {
    "generated_at": "...", "hostname": "...", "kernel": "...",
    "nvidia_driver": "...", "bazzite_image": "...", ...
  },
  "results": [
    {
      "layer":      "L3",
      "check":      "zkde_screencast_protocol",
      "status":     "FAIL",
      "detail":     "zkde_screencast_unstable_v1 absent from Wayland registry",
      "fix":        "systemctl --user restart plasma-xdg-desktop-portal-kde xdg-desktop-portal",
      "confidence": "HIGH"
    },
    ...
  ],
  "summary": { "pass": 8, "warn": 1, "fail": 1 }
}

The fix field in each result directly drives the "Fix it" buttons in the Phase 2 Tauri/Svelte GUI.

Dependencies

All checks use tools that are either present in a standard Bazzite install or degrade gracefully if absent:

Tool	Package	Used for
qdbus6 / qdbus	qt6-tools	L7 KWin plugin check
wayland-info	wayland-utils	L3 protocol registry
systemctl --user	systemd	L2 service health
busctl	systemd	L1 D-Bus interface
pw-dump	pipewire-utils	L4 PipeWire nodes
nvidia-smi	nvidia-driver	L0 NVIDIA checks
flatpak	flatpak	L5 permission store
python3	python3	JSON encoding (always present on Fedora)

Phase 2

The JSON output from this script is the input contract for the Phase 2 Tauri/Svelte GUI (wayland-spectre). The GUI will:

• Display the layered pipeline visually (green / amber / red per layer)
• Offer one-click "Fix it" buttons wired to each fix field
• Run a live end-to-end capture test via PipeWire
• Bundle the JSON + relevant journal excerpts for upstream bug reports