Auv Wayland Rendering Agent Skill

AUV Wayland Rendering

Build a reproducible Linux desktop session in which AUV can observe a Wayland

display and persist capture artifacts. Treat environment validation as evidence,

not as a change to AUV's public support claim.

Keep ownership explicit: the compositor renders application clients; AUV

requests frames through the portal and records them. Do not imply that AUV

ships the compositor or a Linux overlay renderer.

Read the relevant references

• Read setup.md before installing packages, creating a

compositor session, or configuring remote viewing.

• Read troubleshooting.md when a probe or

capture fails, the image is blank, or hardware rendering is uncertain.

• Check AUV's current support matrix before

describing a result as supported. A successful live probe is

live-validated evidence for the named environment only.

Follow the workflow

1. Inspect before changing the host

Run the read-only probe in the target shell:

.agents/skills/auv-wayland-rendering/scripts/probe-wayland.sh

Add --require-gpu to make missing GPU prerequisites fatal when hardware

rendering is required. The flag does not replace compositor-log evidence.

Record:

• distribution and package manager;
• existing compositor and whether the session is local, nested, or headless;
• WAYLAND_DISPLAY, XDG_RUNTIME_DIR, and the session D-Bus;
• accessible /dev/dri/renderD* nodes and the renderer reported by compositor

logs or eglinfo/vulkaninfo;

• ScreenCast portal and PipeWire readiness.

Do not infer GPU rendering from the presence of a GPU or render node. Require a

renderer log or renderer-tool result. Label pixman, llvmpipe, and similar

paths as software rendering.

2. Choose the session shape

Prefer the existing logged-in Wayland compositor when one is available. It

already owns the seat, GPU, D-Bus activation environment, and user consent UI.

Use headless Sway when the host has no desktop session or the test must be

isolated. Start with wlroots renderer auto-selection. Force pixman only as an

explicit software fallback; doing so gives deterministic rendering but does

not validate the GPU path.

Use a nested compositor when isolation is needed inside an existing Wayland

desktop and an extra window is acceptable. Do not point AUV at one compositor

while its portal backend is attached to another.

3. Install the smallest capability set

Install or verify:

• a Wayland compositor such as Sway;
• xdg-desktop-portal and the backend for that compositor;
• PipeWire and WirePlumber;
• wayland-info and grim for independent diagnostics;
• WayVNC only when a human needs to view the wlroots session remotely.

Request authorization before changing system packages, user services, group

membership, login linger, or firewall state. Prefer distribution packages.

Use a source build or patch only after reproducing a version-specific defect

and recording the exact upstream revision and reason.

4. Keep one coherent user session

Run the compositor, portal backend, PipeWire, and AUV as the same unprivileged

user. They must agree on XDG_RUNTIME_DIR, WAYLAND_DISPLAY, and the session

bus. For a compositor started by a user service, import its generated variables

into the systemd user manager and retrieve them in SSH shells.

Use the helper to run a command with either the current environment or the

variables published by the user manager:

.agents/skills/auv-wayland-rendering/scripts/with-wayland-session.sh \
  auv invoke display.list --json

Do not run the compositor or AUV as root to work around device permissions.

Fix seat, logind, container-device, or render-node access instead.

5. Validate from dependencies to AUV artifacts

Validate in this order so each failure has one clear owner:

• Confirm the Wayland socket and compositor output with wayland-info or the

compositor IPC.

• Confirm PipeWire and the org.freedesktop.portal.ScreenCast interface.
• Run the AUV Linux driver probe:

   cargo run -p auv-driver-linux --example validate -- permissions displays

• Run repeated product-surface captures:

   .agents/skills/auv-wayland-rendering/scripts/verify-auv-capture.sh \
     --auv target/debug/auv --repeat 3

• Open at least one emitted PNG. Verify that it contains the expected client,

has the expected dimensions, and is not a blank or stale frame.

Repeated captures establish startup and first-frame reliability. To test

freshness, visibly change a client between two capture passes and compare their

artifacts; identical static frames do not prove that updates propagate.

The verification script checks AUV's JSON result, artifact purpose, PNG

signature, and file existence. It does not prove semantic correctness of the

rendered application; visual inspection or an app-specific assertion remains

separate.

6. Report the boundary precisely

Report all of the following:

• OS, compositor, portal backend, output name and dimensions;
• renderer and whether it is hardware or software;
• portal frame transport when known (dma-buf, shared memory, or fallback);
• AUV revision and exact validation commands;
• successful run IDs and artifact paths;
• whether remote viewing was enabled and how it was secured;
• known warnings, fallbacks, and missing capabilities.

Do not turn compilation, a portal introspection result, or a single screenshot

into a blanket Linux support claim.

Keep GPU compositor rendering, GPU-buffer transport, and correct AUV artifact

output as three separate claims. None implies the other two.

Apply safety rules

• Bind WayVNC to loopback and use an SSH tunnel unless authenticated transport

was explicitly configured.

• Do not expose an unauthenticated VNC port on 0.0.0.0.
• Do not overwrite an existing desktop's portal selection without checking its

current backend and other consumers.

• Do not persist services or enable login linger unless the user requested a

durable session.

• Keep capture and input evidence separate. A rendered frame does not prove

that input was delivered or that an application completed an operation.