Initial commit

This commit is contained in:
Xuc Pan committed 2026-09-05 13:04:29 +08:00
commit 611383544b
91 files changed
+12958

No files matched your search

+76
View File
@@ -0,0 +1,76 @@
# Architecture
`uur` is a compatibility layer, not a repackaged Windows application. The
official client remains in an isolated per-user Wine prefix. A small PE hook
adapts stable Windows APIs at runtime; the Rust host owns policy, desktop
integration, and process lifetime.
```text
UU Remote / Wine
└─ PE ABI adapter (SendInput, GDI/DXGI capture entry points)
└─ authenticated loopback protocol + private frame transport
└─ Rust session supervisor
├─ capture source: xdg ScreenCast → PipeWire
├─ input sink (capability-selected)
├─ xdg RemoteDesktop
├─ Linux uinput
└─ X11 XTest
└─ native services
├─ authenticated terminal proxy → Linux PTY
├─ authenticated Quick Launch proxy → XDG applications
├─ wallpaper metadata synchronizer
└─ desktop suspend/idle inhibitor
```
## Capability negotiation
No runtime branch checks a desktop or distribution name. The order is based on
available interfaces:
1. On Wayland, try a combined RemoteDesktop + ScreenCast portal session. This
is the preferred unprivileged path and uses one consent session for video
and input.
2. If the compositor exposes ScreenCast but not RemoteDesktop, keep portal
capture and inject through `/dev/uinput`. This covers compositors whose
portal currently implements capture only.
3. On X11, use XTest. Wine already sees the real X11 desktop, so an additional
portal capture is unnecessary.
4. XTest remains a final partial fallback for XWayland windows.
Portal implementations are selected by `xdg-desktop-portal`, not by uur. This
keeps compositor-specific policy in the component designed to own it.
## Adapter boundary
The PE DLL is intentionally small C code because it must obey the Windows ABI.
It intercepts API imports and dynamic `GetProcAddress` resolution; it does not
search for product-version-specific instruction bytes or patch official
binaries. Everything above that ABI boundary is Rust.
Capture follows the same pattern as `wemeet-wayland-screenshare`: intercept a
stable capture boundary, obtain real compositor frames through PipeWire, and
substitute those frames before the proprietary application consumes them.
The implementation supports GDI today and keeps DXGI behind the same adapter
surface.
## Lifetime and isolation
`uur run` is the only supervisor. It creates each native helper in a dedicated
process group and records the supervisor PID plus Linux process start time.
When the UU UI exits, or when `uur stop` sends SIGTERM to that exact supervisor,
RAII cleanup terminates only those helper groups and the one managed Wine
prefix. There are no permanent daemons, global `pkill` calls, or required
systemd units.
Frame data lives in `$XDG_RUNTIME_DIR/uur/frames.v1` with mode 0600. The path is
passed through the adapter configuration, so users and concurrent sessions do
not share a global `/dev/shm` object.
## Extension seams
- `InputBackend`: portal, uinput, XTest, and future libei transports.
- capture helper protocol: producer-independent triple-buffer transport.
- PE adapter: API-level UU integration isolated from Linux backends.
- session supervisor: process lifetime independent of init system.
- packaging stage: one filesystem layout consumed by AUR, deb, rpm, Arch, and
portable tarball builders.
+49
View File
@@ -0,0 +1,49 @@
# Capture frame protocol
How frames travel from the compositor (via PipeWire) into the client's
capture calls. Two producers/consumers, one shared file, no locks.
```text
xdg-desktop-portal ScreenCast
│ (portal-consented session; per-monitor)
▼
uur-pw-capture (C) ── PipeWire stream, BGRx, SHM buffers
│ writes slots, seqlock per slot
▼
$XDG_RUNTIME_DIR/uur/frames.v1 (mode 0600, 64-byte header + 3 slots)
│ mapped read-only by the PE hook through its configured Wine Z: path
▼
uur-hook.dll ── intercepts static/dynamic gdi32!BitBlt/StretchBlt calls;
scales the newest stable snapshot into the destination DIB
```
## Shared file layout
All integers little-endian. Total size = 64 + 3 × (8 + stride × height).
| offset | type | field |
| --- | --- | --- |
| 0 | u32 | magic `0x46525555` ("UURF") |
| 4 | u32 | protocol version = 1 |
| 8 | u32 | frame width (px) |
| 12 | u32 | frame height (px) |
| 16 | u32 | stride (bytes per row) |
| 20 | u32 | format: 1 = BGRx (32 bits per pixel) |
| 24 | u64 | total frames written (monotonic counter) |
| 32..64 | — | reserved, zero |
Slot *i* (i = 0, 1, 2) at offset `64 + i × (8 + stride × height)`:
| offset | type | field |
| --- | --- | --- |
| 0 | u64 | sequence: `2×n − 1` while slot n is being written, `2×n` when slot n is stable |
| 8 | bytes | frame, `stride × height`, rows top-to-bottom, pixels BGRx |
Writer picks slots round-robin (`n mod 3`), bumps the counter, publishes
the odd sequence (release), copies the frame, then publishes the even
sequence (release). The reader is a classic seqlock read: load the
sequence, copy, re-load; retry while the value changed or is odd. No
mutexes; a torn read is detected, never observed.
The transport path is created per user and passed to the Wine adapter through
the managed prefix configuration. It is never a global shared-memory name.
+113
View File
@@ -0,0 +1,113 @@
# Package installation
Choose the package format native to the system. Every format installs the same
Rust supervisor, Wine adapters, PipeWire helper, desktop entry, icon, and
uinput integration files. `sudo`, `doas`, or another privilege frontend may be
needed for system-wide package installation.
## Arch Linux
```bash
# AUR
paru -S uur
# Downloaded release package
sudo pacman -U ./uur-0.1.0-1-x86_64.pkg.tar.zst
```
## Debian, Ubuntu, and derivatives
```bash
sudo apt install ./uur_0.1.0_amd64.deb
```
The same release artifact covers Debian, Ubuntu, Linux Mint, Pop!_OS, KDE neon,
Zorin OS, elementary OS, Kali Linux, MX Linux, TUXEDO OS, and compatible
derivatives.
## Fedora, RHEL, and openSUSE families
```bash
sudo dnf install ./uur-0.1.0-1.x86_64.rpm
# openSUSE
sudo zypper install ./uur-0.1.0-1.x86_64.rpm
```
This format also covers Fedora derivatives and RPM systems whose repositories
provide the declared Wine, GLib, PipeWire, and portal dependencies.
## Portable archive
The portable archive targets conventional glibc/FHS systems:
```bash
sudo tar --zstd -C / -xf ./uur-0.1.0-linux-x86_64.tar.zst
```
## Nix and NixOS
```bash
nix build
nix run . -- doctor
```
The flake includes a package, application, development shell, lock file, and
NixOS module. See [Nix and NixOS](nix.md).
## Alpine Linux and musl
`packaging/alpine/APKBUILD` builds an x86_64 musl package from a tagged source
archive. The container recipe runs the same Rust, MinGW, and PipeWire builds:
```bash
docker build -f packaging/alpine/Dockerfile .
```
Alpine edge provides native x86_64 Wine, PulseAudio/ALSA Wine drivers,
PipeWire, desktop portals, Rust, and the MinGW-w64 toolchain.
```bash
cd packaging/alpine
abuild checksum
abuild -r
sudo apk add ~/packages/*/x86_64/uur-*.apk
```
## Other package ecosystems
Gentoo, Funtoo, Void Linux, Slackware, Solus, Clear Linux, ALT Linux, Exherbo,
Mageia, OpenMandriva, PCLinuxOS, Venom Linux, and other FHS/glibc systems can
install the portable release archive or build from source. Their native recipe
can call `packaging/stage.sh` after the three standard builds; the staged tree
is shared with pacman, deb, rpm, APK, and the portable archive.
GNU Guix can wrap the same source build and staged tree. Flatpak and Snap need
manifests granting Wine execution, session D-Bus, PipeWire, and input access.
## Source installation for one user
```bash
cargo build --release --locked
./hook/build.sh
./capture/build.sh
./scripts/install-user.sh
```
This installs under `~/.local` by default. It requires Rust, a native C
compiler, PipeWire development files, `pkg-config`, and the MinGW-w64 x86_64
toolchain.
## Required first run
Package installation does not implicitly accept NetEase's EULA or download the
official client. Complete the setup explicitly:
```bash
uur doctor
uur setup --accept-eula
uur run
```
See [Platform support and usage](platform-support.md) for desktop-session and
portal requirements.
+35
View File
@@ -0,0 +1,35 @@
# Feature parity
| Capability | Status | Linux route |
| --- | --- | --- |
| 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 |
| 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 |
| Wayland virtual source | available when advertised | `uur display source virtual` → ScreenCast Virtual source |
| Independent Wayland multi-screen switching | in progress | Multiple PipeWire streams → UU display topology adapter |
| 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 |
| 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 |
| Prevent suspend/idle | available | Inhibit portal, scoped to `uur run` |
| System proxy | available | Standard proxy environment → Wine WinINet settings |
| Login autostart | available | User-controlled XDG autostart entry |
| Wake-on-LAN host setup | available | Physical-interface discovery → ethtool/NetworkManager configuration |
| Wake button in UU cloud UI | planned | Stable server capability API integration |
| VA-API capability | detected | DRM render nodes + `vainfo` |
| Vulkan Video capability | detected | Vulkan device and `VK_KHR_video_queue` |
| NVENC/NVDEC capability | detected | NVIDIA encode/decode driver libraries |
| Native hardware encode/decode data path | in progress | A common frame/codec interface feeds VA-API, Vulkan Video, and NVENC/NVDEC |
| Gamepad | Wine baseline | Wine HID/XInput for the controller UI; native host injection is planned |
| Resolution, orientation, HiDPI, zoom | partial | Portal stream geometry and Wine display settings |
| Privacy screen | planned | Compositor output policy and virtual display routing |
| Lock, reboot, shutdown, task manager | planned | logind/Polkit and desktop-native actions |
| Unattended login screen | compositor-dependent | Display-manager or compositor remote-desktop session |
| Upstream update detection | available | Official feed + API-contract CI probe |
+159
View File
@@ -0,0 +1,159 @@
# Native service adapters
UU Remote exposes features beyond screen control. On Linux, those features
must operate on the host user account and network namespace, not on Wine's
emulated Windows environment.
## Design boundary
```text
UU feature protocol under Wine
│
▼
small Win64 ABI proxy
│ authenticated loopback, bounded frames
▼
Rust native service owned by `uur run`
│
├─ PTY and login shell
├─ XDG user directories and file portals
└─ host TCP/UDP sockets
```
Proxies translate only the Windows process or stdio boundary expected by UU.
They do not implement Linux policy. Native services are children of the uur
supervisor and cannot outlive the managed session.
## Terminal
Status: implemented.
UU's server uses `conpty_bridge.exe`, `uuyc-mux.exe`, and WTS session queries.
At session startup, uur installs narrow Win64 adapters at those documented
process and API boundaries. The ConPTY adapter forwards stdio and resize
frames; the mux adapter preserves UU's named-session lifecycle; the WTS shim
supplies an active unlocked Wine session. UU's private visible-attach IPC is
delegated to the retained original helper while shell I/O remains native.
The Rust service:
- binds an ephemeral IPv4 loopback port;
- generates a new 256-bit token for every `uur run`;
- accepts at most four concurrent terminal sessions;
- validates a fixed-size handshake and caps frames at 64 KiB;
- opens a real PTY and starts `$SHELL -l` in `$HOME`;
- forwards terminal resize events with `TIOCSWINSZ`;
- sends a hangup and reaps the shell when the UU terminal closes;
- never logs commands, input, output, or environment contents.
The mode-0600 runtime configuration is removed during session shutdown. The
listener, proxy configuration, PTYs, and shells share the main uur lifecycle.
Implementation files:
- `src/terminal.rs`
- `hook/terminal-proxy.c`
- `hook/terminal-protocol.h`
- `tests/terminal-smoke.sh`
The smoke test starts the Rust service, runs the Win64 proxy under Wine, sends a
command through it, and requires a marker emitted by the native Linux shell.
## Quick Launch
Status: implemented.
UU discovers launchable Windows applications through the standard Uninstall
registry. Before starting the server, uur exports the current XDG desktop
application catalog into a private registry namespace. Each item targets a
small Win64 launcher stored in the managed prefix.
The launcher cannot execute an arbitrary command. It reads its immutable
desktop ID, authenticates to a per-run loopback endpoint, and asks the Rust
service to launch that ID only if it is still present in the freshly scanned
catalog. The host uses `gio launch` with `gtk-launch` as a fallback, so normal
desktop activation also covers applications installed through integration
layers that publish `.desktop` entries.
The runtime token is mode 0600 and removed with the main session. A bounded
catalog prevents an untrusted application directory from causing unbounded
registry or prefix growth.
## Desktop integration services
The same lifecycle owns wallpaper synchronization and suspend/idle inhibition.
Proxy settings are imported before Wine starts. Login autostart is explicitly
controlled with `uur autostart`; no permanent root daemon is used.
## File transfer
Status: UU's existing Wine-visible filesystem remains available; native path
integration is not implemented yet.
This means transfers can use paths under the managed prefix or Wine's `Z:`
mapping. A future native adapter should preserve UU's existing transfer
protocol while changing only filesystem access:
### Receiving
1. Receive into a mode-0700 staging directory under the user's XDG data or
runtime directory.
2. Reject absolute paths, parent traversal, device names, symlinks, sparse-file
amplification, and declared-size mismatches.
3. Keep partial files hidden and enforce per-file and per-session quotas.
4. After the final size and digest are known, atomically publish into the XDG
Downloads directory with collision-safe names.
5. Optionally notify the desktop through the standard notification portal.
### Sending
1. Obtain files from an explicit CLI argument, drag-and-drop request, or the
FileChooser portal.
2. Open and retain file descriptors before acknowledging the request, avoiding
path replacement races.
3. Expose only selected files through a private staging view; never expose the
entire home directory by default.
4. Stream from descriptors with bounded memory and cancellation support.
The native adapter should not attempt to translate every Windows path into a
POSIX path. Explicitly selected files and well-defined staging directories are
safer and work in sandboxed environments.
## Port mapping
Status: design complete; protocol attachment to UU is not implemented yet.
The data plane should use host sockets directly so mapped services refer to the
Linux network namespace. The native broker will:
- support TCP first, then UDP after session and timeout semantics are proven;
- bind loopback by default;
- require explicit configuration before binding a LAN or wildcard address;
- reject privileged ports unless a separately configured capability permits
them;
- enforce destination allowlists, connection limits, idle timeouts, and byte
quotas;
- resolve names through the host resolver without exposing arbitrary proxy
environment variables to Wine;
- close every listener and connection when `uur run` ends.
The remaining reverse-engineering task is the stable control-plane boundary
between UU's `PortMappingModule` and its tunnel implementation. The adapter
attaches at an API or helper-process boundary.
## Clipboard and phone text
Clipboard access belongs to the active desktop session. The preferred Wayland
route is the Clipboard interface attached to the existing RemoteDesktop portal
session. X11 uses normal selection ownership. Text payloads require strict size
limits and must not be written to logs.
## Security invariants
- Every service authenticates its Wine-side proxy with a per-run random token.
- Runtime endpoints bind only to loopback or use private Unix descriptors.
- Payload lengths and concurrent sessions are bounded before allocation.
- Native services run as the logged-in user; no root daemon handles content.
- User content is absent from diagnostics.
- Session shutdown revokes tokens, removes runtime files, closes listeners, and
reaps child processes.
+49
View File
@@ -0,0 +1,49 @@
# Nix and NixOS
The repository exports an x86_64 Linux package, an app, a development shell,
and a NixOS module. The lock file pins NixOS/nixpkgs 26.05.
## Build or run from a checkout
```bash
nix build
nix run . -- doctor
nix run . -- setup --accept-eula
nix run . -- run
```
The derivation builds the Rust supervisor, the musl/glibc-independent source
components, the PipeWire helper, and all MinGW Win64 adapters. Runtime tools
are wrapped into `PATH`; the UU client and Wine prefix remain in the user's XDG
data directory.
## NixOS module
Add this repository as a flake input and import its module:
```nix
{
inputs.uur.url = "github:panxuc/uur";
outputs = { self, nixpkgs, uur, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
uur.nixosModules.default
({ ... }: {
programs.uur.enable = true;
})
];
};
};
}
```
The module installs the package, loads `uinput`, and registers uur's udev rule.
The selected desktop still supplies its matching xdg-desktop-portal backend.
Override the package when following a fork or local build:
```nix
programs.uur.package = inputs.uur.packages.x86_64-linux.uur;
```
+278
View File
@@ -0,0 +1,278 @@
# Platform support and usage
`uur` selects Linux integrations by observable capability. Distribution and
desktop names below help users install the right dependencies. `uur doctor`
reports the active login session.
The current release target is Linux x86_64. Wine must be able to run the
official 64-bit UU Remote client.
## Runtime dependency axes
| Capability | Preferred route | Alternatives |
| --- | --- | --- |
| Wayland video | ScreenCast portal + PipeWire | Portal virtual/window sources |
| X11 video | Wine X11 capture | ScreenCast portal when explicitly selected |
| Wayland input | RemoteDesktop portal | uinput; XTest for XWayland windows |
| X11 input | XTest | uinput |
| Audio | PulseAudio protocol | pipewire-pulse; ALSA |
| Wine windows | X11/XWayland | Wine Wayland driver |
| Application launch | `gio launch` | `gtk-launch` |
| Suspend inhibition | Inhibit portal | Session continues without an inhibitor |
| WOL persistence | NetworkManager + ethtool | ethtool runtime state |
| Hardware inventory | DRM + VA-API/Vulkan Video | NVENC/NVDEC; software codec |
Common portal packages include `xdg-desktop-portal-gnome`,
`xdg-desktop-portal-kde`, `xdg-desktop-portal-hyprland`,
`xdg-desktop-portal-wlr`, `xdg-desktop-portal-lxqt`,
`xdg-desktop-portal-xapp`, `xdg-desktop-portal-gtk`, and compositor-specific
implementations. The active interfaces determine the selected path.
## Install by distribution family
### Arch package family
This includes Arch Linux and distributions that consume Arch packages or the
AUR, such as EndeavourOS, CachyOS, Manjaro, Garuda Linux, Artix Linux, and
Arch-based development systems. Init-system choice does not affect uur; it
does not require a persistent systemd service.
From AUR:
```bash
paru -S uur
```
From a downloaded Arch package:
```bash
sudo pacman -U ./uur-0.1.0-1-x86_64.pkg.tar.zst
```
Install the portal backend supplied or recommended by the selected desktop.
On a capture-only Wayland portal, ensure the active user can open
`/dev/uinput`; the package installs a udev rule and a module-load entry.
### Debian package family
The deb artifact is intended for current Debian, Ubuntu, Linux Mint, Pop!_OS,
Zorin OS, elementary OS, KDE neon, TUXEDO OS, Kali Linux, MX Linux, and other
compatible derivatives:
```bash
sudo apt install ./uur_0.1.0_amd64.deb
```
The package manager resolves Wine, PipeWire, and the portal frontend. Install
the session's portal backend separately when the distribution does not pull it
in with the desktop environment.
### RPM package family
The rpm artifact targets current Fedora and distributions with compatible RPM
dependency names. Install it with the native frontend:
```bash
# Fedora and compatible systems
sudo dnf install ./uur-0.1.0-1.x86_64.rpm
# openSUSE family
sudo zypper install ./uur-0.1.0-1.x86_64.rpm
```
RHEL, CentOS Stream, Rocky Linux, AlmaLinux, Oracle Linux, Nobara, Ultramarine,
openSUSE Tumbleweed, and openSUSE Leap can use the RPM when its dependency names
resolve, with the portable or source build covering other package layouts.
### Other conventional distributions
Gentoo, Funtoo, Void Linux, Slackware, Solus, Clear Linux, Mageia, OpenMandriva,
PCLinuxOS, and similar mutable/FHS systems can use the portable archive when
they provide compatible glibc, Wine, PipeWire, and portal libraries:
```bash
sudo tar --zstd -C / -xf ./uur-0.1.0-linux-x86_64.tar.zst
```
Alternatively, build and install for one user:
```bash
cargo build --release --locked
./hook/build.sh
./capture/build.sh
./scripts/install-user.sh
```
The source build needs Rust, a native C compiler, PipeWire development files,
`pkg-config`, and the MinGW-w64 x86_64 compiler and binutils. Package names are
distribution-specific; uur does not invoke a package manager itself.
### Immutable, declarative, and musl systems
NixOS uses the repository flake and NixOS module described in [Nix and
NixOS](nix.md). The module installs the package, udev integration, and `uinput`
kernel module declaratively.
Alpine edge uses `packaging/alpine/APKBUILD` or the included musl container
build. GNU Guix can package the same staged layout. Flatpak and Snap require
host input, Wine, and portal permissions that are best expressed as dedicated
manifests.
## Select the desktop integration path
### X11 session
Requirements: `DISPLAY`, Wine's X11 driver, and the XTest extension.
This path applies to full desktops and standalone window managers alike. Common
examples include Xorg sessions of GNOME, Plasma, Cinnamon, MATE, Xfce, LXQt,
LXDE, Budgie, Deepin, Pantheon, Trinity, and UKUI, plus i3, bspwm, awesome,
Openbox, Fluxbox, IceWM, dwm, qtile, herbstluftwm, spectrwm, and FVWM.
Wine captures the X11 desktop directly and uur injects input with XTest. A
ScreenCast portal is not required for this path.
### Wayland session with ScreenCast and RemoteDesktop portals
Requirements: a working session D-Bus, PipeWire, the xdg-desktop-portal
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
advertises both interfaces. Interface availability—not the desktop name—makes
the final decision.
### Wayland session with a capture-only portal
Requirements: ScreenCast/PipeWire plus writable `/dev/uinput` for full desktop
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
installation is incomplete or whose selected backend omits RemoteDesktop.
Install the compositor's ScreenCast portal and enable uinput access. A
`portals.conf` selects the backend when several are installed.
### Wine window backend
The UU user interface still needs a Wine display driver:
- Existing X11 and most Wayland desktop sessions normally use Wine through
X11 or XWayland.
- Compositors without built-in XWayland can use an external XWayland manager;
niri, for example, integrates xwayland-satellite in current releases.
- Wine builds with a usable native Wayland driver may run without XWayland,
but that combination must still pass UU WebView2 and window-management tests.
This choice is independent from desktop capture. A client window can use
XWayland while the controlled desktop is captured through the Wayland portal.
### Audio servers
Wine's PulseAudio driver is selected for both a native PulseAudio daemon and
the `pipewire-pulse` compatibility server. A native PipeWire session without
PulseAudio compatibility uses Wine's ALSA driver. `uur doctor` prints the live
choice; this is independent from PipeWire's Wayland video role.
### Displays and virtual sources
```bash
uur display status
uur display source monitor
uur display source window
uur display source virtual
```
The command clears the old restore token so the next Portal session can create
or select the requested source. X11 exposes its XRandR topology to Wine.
Wayland currently carries one selected stream; independent multi-stream
switching is the next display-topology adapter.
## First run and normal use
After installing any package format:
```bash
uur doctor
uur setup --accept-eula
uur run
```
Optional host integration is managed explicitly:
```bash
uur autostart enable
uur autostart status
uur wol status
sudo uur wol enable --interface enp3s0
```
The WOL command configures the real Linux adapter; it requires `ethtool`, and
persists the setting through an active NetworkManager wired profile when one
exists. The adapter name above is only an example—omit it for automatic
physical-interface selection.
The package installs `uur.desktop` as the canonical application-menu entry.
During setup, an existing Wine-generated Linux desktop entry for the official
client is converted into a hidden compatibility alias whose command is also
`uur run`. This keeps already pinned Dock, panel, or launcher favorites working
without showing a duplicate application in new searches.
The `.lnk` file inside the Wine prefix remains available for diagnosis. Normal
desktop integration launches `uur.desktop` or `uur run` so all helpers share
the same lifetime.
The first Wayland run may show a portal chooser. Select the monitor to expose
to remote controllers. A successful persistent portal grant is reused where
the backend supports restore tokens.
UU Quick Launch is populated from visible XDG desktop entries every time
`uur run` starts. This includes conventional packages and any containerized or
portable application that publishes a valid `.desktop` entry. Application
activation uses the desktop entry itself, so uur does not maintain a command
translation table.
Stop only the managed session and its Wine prefix with:
```bash
uur stop
```
Useful input-backend overrides for diagnosis are:
```bash
UUR_INPUT_BACKEND=portal uur run
UUR_INPUT_BACKEND=uinput uur run
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.
## Reading `uur doctor`
- `portal ScreenCast`: required to capture a Wayland desktop.
- `portal RemoteDesktop`: preferred unprivileged Wayland input route.
- `uinput (/dev/uinput)`: full-desktop fallback when RemoteDesktop is absent.
- `DISPLAY`: required for Wine/X11 or Wine/XWayland and for XTest fallback.
- `WAYLAND_DISPLAY`: identifies the active Wayland session.
- `PipeWire`: required for the Wayland frame transport.
If both Wayland input routes are unavailable, XTest controls XWayland windows.
## Session model
Portal sessions operate in the logged-in desktop seat. Display-manager access
uses a display-manager remote session, while headless operation uses a portal
virtual source or a provisioned virtual display. `uur doctor` reports the
active backend capabilities.
Relevant upstream documentation:
- [xdg-desktop-portal backend selection](https://flatpak.github.io/xdg-desktop-portal/docs/portals.conf.html)
- [RemoteDesktop portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.RemoteDesktop.html)
- [ScreenCast portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.ScreenCast.html)
+43
View File
@@ -0,0 +1,43 @@
# Upstream adaptation
UU Remote and uur have independent release lifecycles. The AUR package
contains only uur, so a new proprietary client does not automatically require
a package rebuild.
## Compatibility contract
The adapter depends on named operating-system APIs, not a table of UU versions,
hashes, RVAs, or instruction patches:
- `wevtapi!EvtOpenPublisherMetadata` loads the compatibility shim;
- `USER32!SendInput` is routed to the native input bridge;
- GDI or DXGI desktop-capture entry points are routed to the frame adapter;
- dynamic `GetProcAddress` resolution is intercepted as well as static imports.
`scripts/probe-upstream.sh` verifies those contracts across every PE file in
an installed client tree. If an installer cannot be extracted directly, the
probe installs it in a disposable Wine prefix and examines the result.
## Automation
The daily `upstream-watch` workflow:
1. resolves NetEase's official HTTPS release URL;
2. verifies the Authenticode signature;
3. extracts or installs the client in an ephemeral environment;
4. runs the static API-contract probe;
5. opens or updates a tracking issue with the result.
Static success means the generic adapter still has a viable attachment point;
it is not presented as full runtime proof. A release candidate must also pass
the Wine input round-trip and changing-frame canary before it is promoted.
Project releases build all package formats from the same source and publish
immutable artifacts and checksums. A new proprietary client version alone does
not cause a meaningless uur package rebuild.
## When a contract changes
Compatibility changes add a stable API adapter or transport behind the existing
Rust traits. Capability probes select the route whose prerequisite API is
available.
+31
View File
@@ -0,0 +1,31 @@
# Video and display backends
## Frame sources
- X11 sessions expose the XRandR monitor topology directly to Wine.
- Wayland monitor and window sources use ScreenCast/PipeWire.
- `uur display source virtual` requests the portal's Virtual source type and
stores its restore token.
- A multi-stream compositor will combine or expose several PipeWire nodes to
UU's display topology for independent Wayland screen switching.
## Codec capabilities
`uur doctor` inventories the native acceleration APIs independently:
- DRM render nodes are the common device boundary;
- VA-API covers Intel, AMD, and supported third-party drivers;
- Vulkan Video is recognized through `VK_KHR_video_queue`;
- NVENC and NVDEC are recognized through NVIDIA's encode/decode libraries;
- software H.264 remains available through UU's current Windows path.
The native codec data path will consume the same BGRx frame transport used by
the current capture adapter. A backend receives frame descriptors, negotiated
color metadata, dimensions, and target latency; it returns encoded access units
through one common interface. Codec selection can then prefer a verified
hardware route and fall back to software without changing capture, display, or
UU protocol code.
HDR requires a 10-bit frame format, color primaries, transfer function, and
mastering metadata across the portal, PipeWire, encoder, and UU transport. The
current BGRx transport is SDR.
+30
View File
@@ -0,0 +1,30 @@
# UU Windows feature map
The current UU server advertises these capability families. The Linux route is
organized by host subsystem so each backend can evolve independently.
| UU capability family | Linux integration |
| --- | --- |
| Desktop, window, and emulator capture | X11/Wine or portal/PipeWire frame source |
| Monitor, second screen, virtual display | XRandR topology or portal monitor/window/virtual sources |
| Resolution, orientation, HiDPI, zoom | Display topology and stream geometry adapters |
| 90/144 fps, true color, chroma, HDR | Frame format and encoder capability negotiation |
| Keyboard, mouse, smart/virtual mouse | RemoteDesktop portal, uinput, XTest |
| Touch, pen, gamepad | uinput tablet and future multitouch/gamepad devices |
| Speaker, microphone, remote mute | Wine WASAPI over PulseAudio, pipewire-pulse, or ALSA |
| Clipboard and phone text input | Portal clipboard and X11 selections |
| File transfer v1-v4 | Wine-visible paths now; native XDG staging next |
| Terminal and multiple sessions | Native PTY with ConPTY and mux ABI adapters |
| Port mapping | Native host socket broker |
| Quick Launch and remote application list | XDG desktop catalog and authenticated launcher |
| Wallpaper and privacy wallpaper | Desktop wallpaper providers and capture routing |
| Privacy screen | Compositor output policy or a dedicated virtual output |
| Wake-on-LAN | Physical NIC configuration and UU capability reporting |
| Lock, reboot, shutdown, task manager | logind/Polkit and desktop-native actions |
| Auto unlock and login-screen access | Display-manager remote session integration |
| Controlled update | Official release feed and compatibility probes |
The [App Store release history](https://apps.apple.com/hk/app/uu%E8%BF%9C%E7%A8%8B-%E8%BF%9C%E7%A8%8B%E5%8A%9E%E5%85%AC-%E6%B8%B8%E6%88%8F%E4%B8%B2%E6%B5%81/id1642306791?platform=mac)
also confirms multi-session terminal support, view-only mode, automatic unlock,
and remote terminal access on current Apple clients. The server capability
table is broader and is the implementation map used by uur.