fix: repair Wine setup and niri capture, input and tray (#22)

* fix(setup): verify provisioning and runtime readiness

* feat: add explicit per-user uninstall and purge

* fix: restore niri input and provide native capture and tray

* fix(build): declare Wayland scanner and release dependencies
This commit is contained in:
Xuc Pan authored and GitHub committed 2026-10-13 15:26:06 +08:00
1 parent d349e6ff6a
commit 8c0589021f
38 files changed
+2409 -185

No files matched your search

+59 -1
View File
@@ -95,7 +95,7 @@ cargo build --release --locked
```
This installs under `~/.local` by default. It requires Rust, a native C
compiler, PipeWire development files, `pkg-config`, and the MinGW-w64 x86_64
compiler, PipeWire and Wayland development files (including `wayland-scanner`), `pkg-config`, and the MinGW-w64 x86_64
toolchain.
## Required first run
@@ -111,3 +111,61 @@ uur run
See [Platform support and usage](platform-support.md) for desktop-session and
portal requirements.
## Package removal, repair, and per-user state
Package removal leaves the managed Wine prefix, downloaded installer cache,
configuration and logs in the user's XDG directories. This preserves login
and client data across package upgrades and reinstalls. Reinstalling the
package therefore does not create a new Wine prefix. Start with
`uur stop` followed by `uur setup --repair` for an interrupted setup.
For a fresh prefix, stop uur and move the old prefix aside before setup:
```bash
uur stop
uur_prefix="${XDG_DATA_HOME:-$HOME/.local/share}/uur/wine"
mv -- "$uur_prefix" "$uur_prefix.backup-$(date +%Y%m%d-%H%M%S)"
uur setup --accept-eula
```
The fresh prefix needs the official client installed and logged in again.
The backup retains the previous client and account data.
`uur uninstall` stops the managed session and Wine server, removes this user's
autostart entry and recognized UU launchers/icons, and removes a source
installation identified by its installer receipt. It keeps the managed client,
account data, configuration and logs by default. Use `--purge` for a fresh
start or complete removal:
```bash
# Preview only: no processes stopped, no files changed
uur uninstall --purge --dry-run
# Run as the desktop user, NOT with sudo; review the paths and confirm
uur uninstall --purge
# Remove system package files afterwards (Arch Linux)
sudo pacman -Rns uur
```
Purge permanently deletes the dedicated Wine prefix (including Wine Mono,
WebView2 and the official client), login/account data, installer cache, all uur
configuration and logs, and private runtime files. Back up the `uur` XDG
directories first if those data are needed. For unattended removal, explicitly
confirm with `uur uninstall --purge --yes`. The command honors the current
`XDG_DATA_HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_RUNTIME_DIR`; use
the same values used for setup. A custom source install can be selected with
`UUR_INSTALL_PREFIX=/path/to/prefix uur uninstall --purge`.
On Debian/Ubuntu, use `sudo apt purge uur` after the user cleanup; on Fedora,
use `sudo dnf remove uur`. Package-manager removal alone leaves per-user data
intact, including when run with `purge`: package scripts run as root and do not
erase other users' home directories. Each user should run the cleanup command
before the system package is removed. If the package was already removed,
reinstall it to get the cleanup command, run `uur uninstall --purge`, then
remove the package again; running setup is not required. Shared Wine/Mono, PipeWire and portal
packages remain the package manager's responsibility. Kernel/device settings
and compositor-granted portal permissions are not reset by user-data cleanup.
Unpin any old launcher from the desktop panel afterwards if the panel retains
its own pinned copy.
+2 -2
View File
@@ -5,7 +5,7 @@
| Control other devices | available | Official UU UI and decoder under Wine |
| Receive remote video | available | Official UU UI under Wine |
| Share X11 desktop | available | Wine X11 capture |
| Share Wayland desktop | available | ScreenCast portal → PipeWire → GDI adapter |
| Share Wayland desktop | available | ScreenCast/PipeWire or explicitly enabled native screencopy → GDI adapter |
| Mouse and keyboard | implemented | RemoteDesktop portal → uinput → XTest capability order |
| X11 multi-monitor | Wine integration | Native Wine/XRandR display topology |
| Wayland monitor/window selection | available | Persistent portal source selection |
@@ -14,7 +14,7 @@
| Clipboard and phone IME text | planned | RemoteDesktop Clipboard portal, then X11 fallback |
| Speaker and microphone audio | available through Wine | PulseAudio, pipewire-pulse, or ALSA selected from live capabilities |
| System-audio loopback and remote mute | Wine integration | WASAPI → winepulse/winealsa |
| Native tray | Wine baseline | Official tray, with StatusNotifierItem as the native route |
| Native tray | implemented | StatusNotifierItem + DBusMenu, supervised with the session; no Wine XEmbed dependency |
| Terminal | available | ConPTY/mux ABI adapters → authenticated native Rust PTY/login shell |
| Quick Launch | implemented | Windows app inventory adapter → XDG desktop catalog → `gio launch` |
| Desktop wallpaper | available | Capability providers → Wine desktop metadata |
+100 -3
View File
@@ -139,8 +139,7 @@ frontend, and a backend exposing both `ScreenCast` and `RemoteDesktop`.
Where those interfaces are available, uur creates one combined session for
capture and input. This is the preferred unprivileged route. Examples can
include current GNOME Shell, KDE Plasma, niri with its recommended portal
configuration, COSMIC, and other sessions whose selected portal backend
include current GNOME Shell, KDE Plasma, COSMIC, and other sessions whose selected portal backend
advertises both interfaces. Interface availability—not the desktop name—makes
the final decision.
@@ -151,7 +150,9 @@ input. XTest remains only a partial fallback for XWayland surfaces.
This route commonly applies to compositors using Hyprland or wlroots-oriented
portal backends, including Hyprland, Sway, Wayfire, river, labwc, dwl, Waybox,
and other wlroots-based sessions. It may also apply to a desktop whose portal
and other wlroots-based sessions. niri uses its recommended
`xdg-desktop-portal-gnome` ScreenCast integration and requires uinput when a
working RemoteDesktop session is unavailable. It may also apply to a desktop whose portal
installation is incomplete or whose selected backend omits RemoteDesktop.
Install the compositor's ScreenCast portal and enable uinput access. A
@@ -253,6 +254,102 @@ UUR_INPUT_BACKEND=xtest uur run
An override is a diagnostic tool, not a desktop-specific configuration. The
default `auto` mode should be used after troubleshooting.
## Interrupted setup and Wine components
Retry an interrupted installation without deleting the managed prefix:
```bash
uur stop
uur setup --repair
uur doctor
uur run
```
The repair option runs `wineboot --update` for the managed prefix. This retries
Wine's component initialization, including its Wine Mono offer where needed.
It keeps the installed client's data, checks both the client and service
executables and the Windows service registration, and reruns the official
installer if that installation is incomplete. Failed initialization or a
failed/cancelled installer returns an error instead of reporting completion.
The **Wine Mono Installer** is Wine's .NET runtime installer. It is separate
from **WebView2**, which uur uses for the official client's management UI.
Cancelling Mono does not establish the cause of a Wayland black screen or
failed desktop input. Those paths depend on the native capture helper,
ScreenCast/PipeWire and an authorized RemoteDesktop session or uinput.
On Arch/CachyOS, installing the matching `wine-mono` package can avoid the
Wine dialog's network download; use the package supplied for the installed
Wine version. For the existing 0.1.4 release, the equivalent manual retry is:
```bash
uur stop
WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}/uur/wine" \
WINEDLLOVERRIDES="wevtapi=b,wtsapi32=b" wineboot --update
uur setup
```
To open the Wine program/component manager for this prefix:
```bash
WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}/uur/wine" \
WINEDLLOVERRIDES="wevtapi=b,wtsapi32=b" wine uninstaller
```
## niri: black video or missing desktop input
Use the niri session entry (or `niri-session`), its recommended
`xdg-desktop-portal-gnome` backend, and a running PipeWire service. A visible
Wine window only verifies its XWayland display path. Remote video still needs
the separate ScreenCast stream, and native Wayland input needs a working
RemoteDesktop session or writable `/dev/uinput`.
Start with an actual monitor selection:
```bash
uur display source monitor
uur doctor
test -w /dev/uinput && echo 'uinput is writable'
uur run
```
If the portal chooser offers **niri Dynamic Cast Target**, that stream remains
empty until a target is assigned through niri. Select a real monitor when
diagnosing black video. See [niri's screencasting documentation](https://github.com/niri-wm/niri/wiki/Screencasting).
If RemoteDesktop creation fails, the automatic policy tries uinput. When both
are unavailable it reports an error; explicitly selected XTEST can only reach
XWayland windows. The packaged udev rule and uinput module must be active for
the logged-in user; restart the graphical session after changing that setup.
`uur run` verifies a real Wayland frame and a running GameViewerService before
announcing readiness. Startup/helper failures are reported in the terminal;
details are in `${XDG_STATE_HOME:-$HOME/.local/state}/uur/session.log` and
`${XDG_DATA_HOME:-$HOME/.local/share}/uur/hook.log`. A missing tray icon alone
does not determine whether capture or input works.
For niri and other compositors exposing `wlr-screencopy`, uur also offers
direct, shared-memory monitor capture. This path avoids portal/PipeWire/GBM
dependencies for video and is useful when a portal cannot produce frames:
```bash
uur display outputs
uur display backend wayland --output DP-1 # Use the name printed above
uur run
```
Selecting `wayland` explicitly authorizes direct monitor capture for later
runs. It does not show a system screen-sharing dialog and does not activate
automatically after portal cancellation or failure. With one output, `--output`
can be omitted; multiple outputs require an explicit name. Automatic input
selection uses uinput in this mode. Run `uur display backend portal` to return
to portal-consented capture. Direct mode captures a monitor, not individual
windows or virtual portal sources; changes to its size require restarting
the session.
The supervised native StatusNotifierItem supplies its own icon pixels and
DBusMenu to Noctalia, Plasma and other compatible panels. Right-click it for
Open UU Remote and Quit. It re-registers when the panel's watcher restarts;
it does not depend on Wine's legacy tray being visible.
## Reading `uur doctor`
- `portal ScreenCast`: required to capture a Wayland desktop.