link out to selkies layers for references, update docs to reflect zero copy x11 and how it works, stop mentioning x11 as a fallback

Author: thelamer

docs/selkies/components/baseimages.md

@@ -26,7 +26,7 @@ There is deliberately **no `latest` tag** for base images. Downstream images pin
 - **The LSIO foundation**: each tag builds on the corresponding LinuxServer.io distro baseimage, inheriting s6-overlay init, the `abc` user with PUID and PGID remapping, `TZ`, Docker mods, and the `/custom-cont-init.d` and `/custom-services.d` hooks.
 - **Selkies** (pinned commit) installed into the `/lsiopy` virtualenv, with pixelflux 2.x and pcmflux 2.x, plus [Pelorus](pelorus.md) preinstalled.
 - **The web client**: prebuilt dashboards under `/usr/share/selkies/`, selected at runtime by the `DASHBOARD` variable.
-- **Compositors for both stacks**: labwc (built from source with a small IPC patch that adds the window query socket Pelorus uses) for Wayland, and a patched Xvfb (with `-vfbdevice` DRI3 support) plus Openbox for the legacy X11 fallback. A patched wlroots build makes the compositor survive pixman rendering faults instead of crashing.
+- **Display servers for both stacks**: labwc (built from source with a small IPC patch that adds the window query socket Pelorus uses) for Wayland, and an XLibre Xvfb built with glamor and DRI3 plus Openbox for X11. The Xvfb carries a LinuxServer patch that keeps the screen pixmap on the GPU and lets the framebuffer follow RandR resizes, which is what makes zero copy capture possible on X11. Both are prebuilt per distro in [selkies-layers](https://github.com/linuxserver/selkies-layers) and copied into the image. A patched wlroots build makes the compositor survive pixman rendering faults instead of crashing.
 - **[Selkies Desktop](selkies-desktop.md)** at `/usr/bin/selkies-desktop`, activated by env var.
 - **Nginx** with the fancyindex module, serving the client, proxying the WebSocket, handling basic auth, subfolder support, and the `/files` download index.
 - **PulseAudio** with null sinks (`output` and `input`) wired for stream audio and microphone return.
@@ -54,8 +54,10 @@ At startup a chain of one shot init scripts configures everything from environme
 
 ## The two session modes
 
-- **Wayland (default on capable hardware)**: pixelflux hosts the virtual compositor; labwc (single apps) or a full desktop (Webtop flavors) nests on it; zero copy GPU encoding is available. `PIXELFLUX_WAYLAND=true` is baked into current downstream images.
-- **X11 (legacy fallback)**: patched Xvfb with DRI3, Openbox, XSHM capture. Selected with `PIXELFLUX_WAYLAND=false` or on flavors that have not moved to Wayland yet. Deprecated for GPU work.
+- **Wayland**: pixelflux hosts the virtual compositor; labwc (single apps) or a full desktop (Webtop flavors) nests on it. `PIXELFLUX_WAYLAND=true` is baked into images whose application or desktop runs on Wayland.
+- **X11**: XLibre Xvfb with glamor and DRI3 on `:1`, Openbox for single apps or the desktop's own window manager, and pixelflux capturing the GPU resident screen through DRI3. Selected with `PIXELFLUX_WAYLAND=false`, and the stack for applications and desktops that run best on X11.
+
+Both stacks encode with zero copy on a GPU and share the same CPU encoders without one.
 
 ## The downstream contract
 

docs/selkies/components/index.md

@@ -56,7 +56,7 @@ graph TD
 
 To make the layering concrete, here is the life of one frame in a Wayland mode container:
 
-1. The application renders into a buffer belonging to **labwc** (or KWin on KDE), which is itself a client of the headless Smithay compositor that **pixelflux** hosts in process.
+1. The application renders into a buffer belonging to **labwc** (or KWin on KDE), which is itself a client of the headless Smithay compositor that **pixelflux** hosts in process. On X11 the application instead draws into an XLibre Xvfb whose screen pixmap lives on the GPU, and pixelflux blits it out through DRI3 rather than compositing it.
 2. Pixelflux composites the output. If a GPU holds the framebuffer and the encoder lives on the same GPU, the frame is passed as a DMA-BUF straight into NVENC or VA-API, zero copy, for any codec the card carries. Otherwise it is read back and encoded on CPU, in parallel stripes for H.264 and JPEG and full frame for the other codecs.
 3. Only regions that changed get encoded at all; a static screen costs almost nothing, and after motion stops a high quality paint over pass restores perfect detail.
 4. The encoded frame, with a small binary header, is handed to **Selkies**, which broadcasts it over the WebSocket to every connected viewer with backpressure control per client.

docs/selkies/components/pixelflux.md

@@ -10,8 +10,8 @@ Pcmflux is its audio sibling: it captures PulseAudio output and encodes Opus fra
 
 As of the 2.0.0 release, pixelflux is a **Rust** library exposed to Python through PyO3 (earlier versions were C++ with ctypes). One extension module contains:
 
-- An **X11 backend**: XShm screen capture with XFixes cursor tracking, for the legacy X11 stack.
-- A **Wayland backend**: a full headless Wayland compositor built on [Smithay](https://github.com/Smithay/smithay), running in process. This is the key architectural point of the modern stack: **pixelflux does not capture a Wayland compositor, it is the compositor.** It synthesizes the output, seat, and clipboard itself, which is why the framebuffer can live directly on a GPU and why input is injected through its API rather than tools like xdotool.
+- An **X11 backend**: DRI3 capture that blits the GPU resident screen into DMA-BUFs the encoder imports in place, and XShm capture with XFixes cursor tracking where that does not apply.
+- A **Wayland backend**: a full headless Wayland compositor built on [Smithay](https://github.com/Smithay/smithay), running in process. This is the key architectural point of the Wayland stack: **pixelflux does not capture a Wayland compositor, it is the compositor.** It synthesizes the output, seat, and clipboard itself, which is why the framebuffer can live directly on a GPU and why input is injected through its API rather than tools like xdotool.
 - Six codecs across software and hardware encoders, and the damage tracking, paint over, and rate control logic shared between them.
 
 ## Encoders
@@ -37,7 +37,7 @@ Hardware encoders always operate full frame, delivered as a single full height s
 
 ### Damage detection
 
-- **X11:** each stripe's pixels are hashed (xxh3) every frame, a changed hash marks the stripe dirty. Continuously changing regions enter a "damage block" state that skips re hashing for a configured number of frames to save CPU.
+- **X11:** on the DRI3 path the Damage extension reports whether anything was drawn since the last frame, so nothing is hashed. On the XShm path each stripe's pixels are hashed (xxh3) every frame, a changed hash marks the stripe dirty. Continuously changing regions enter a "damage block" state that skips re hashing for a configured number of frames to save CPU.
 - **Wayland:** no hashing needed, the compositor knows exactly which rectangles clients damaged and maps them to stripes.
 - A fully idle screen takes a fast path that skips the encode thread pool entirely.
 
@@ -50,11 +50,11 @@ The signature quality feature. After a region has been static for a configurable
 - **CRF/CQP mode** (default): constant quality, bits go wherever needed.
 - Infinite GOP by default: keyframes are only sent on demand (client join, recovery, or an optional periodic interval). Bitrate, framerate, and quality are all adjustable live without restarting the capture.
 
-## Zero copy on Wayland
+## Zero copy
 
-When the compositor renders on a GPU and the encoder is on the same GPU, frames flow as DMA-BUF handles from the render buffer straight into NVENC or VA-API. The pixels never touch system RAM and the CPU never sees them. If the render and encode devices differ, or a software encoder is selected, pixelflux falls back to a readback path automatically and logs which decision it made. Zero copy is a property of the capture path, not the codec: any codec the GPU carries takes it.
+**Wayland.** When the compositor renders on a GPU and the encoder is on the same GPU, frames flow as DMA-BUF handles from the render buffer straight into NVENC or VA-API. The pixels never touch system RAM and the CPU never sees them. If the render and encode devices differ, or a software encoder is selected, pixelflux falls back to a readback path automatically and logs which decision it made. Zero copy is a property of the capture path, not the codec: any codec the GPU carries takes it.
 
-On X11 there is one zero copy path as well. When the session encodes on NVENC, capture goes through NvFBC, the Nvidia X driver composites the screen into a buffer in video memory, and that buffer is registered with the encoder in place. Every other X11 session copies each frame once into shared memory. Nothing selects this, the driver decides and the log says which path was taken.
+**X11.** On an X server whose screen lives on the GPU, which is what the containers run (XLibre Xvfb started with `-glamor -dri`), pixelflux allocates a small pool of DMA-BUFs through GBM on the render node the server draws with, hands each to the server as a pixmap through DRI3, and captures every frame as one `CopyArea` of the root window into the next buffer, a GPU blit in glamor. The encoder imports that buffer in place through the same path the Wayland capture uses, so no frame crosses to the CPU. The Damage extension gates capture so a static screen costs nothing, and the server composites the cursor and any watermark through Render. Nvidia, Intel, and AMD all take this path. It is declined, with one log line saying why, for software encoding, a codec the GPU has no engine for, a server drawing on a different device than the encoder, or a server without DRI3 1.2, Damage, or Render, and the session then streams through XShm with one copy per frame.
 
 GPU selection is automatic: it walks `/sys/class/drm`, identifies cards by driver (`nvidia` goes to NVENC, `i915` and `amdgpu` to VA-API), and can be pinned by device path, index, or an `auto_gpu` token matching a driver or vendor ID.
 

docs/selkies/developer-guide/architecture.md

@@ -22,14 +22,14 @@ The subtle point people miss: **pixelflux is the display server.** When the Selk
 
 labwc then runs as a *client* of that compositor (using its Wayland backend, the nested pattern) and provides window management, decorations, and XWayland on display `:0` for legacy apps. Applications connect to labwc's `wayland-0` socket. Full desktops swap labwc for a heavier nested compositor: Webtop KDE runs `kwin_wayland` nested on `wayland-1` with plasmashell on top.
 
-In X11 fallback mode the shape is more traditional: a patched Xvfb (with DRI3 device support) provides `:1`, Openbox manages windows, and pixelflux captures via XSHM with per stripe hashing for damage detection.
+In X11 mode the shape is more traditional: an XLibre Xvfb built with glamor and DRI3 provides `:1` with its screen pixmap on the GPU, Openbox manages windows, and pixelflux captures the screen with a DRI3 blit into DMA-BUFs the encoder imports in place. Without a GPU, or when the DRI3 path is declined, it captures via XShm with per stripe hashing for damage detection.
 
 ## The video pipeline
 
 ### Capture and damage
 
 - Wayland: the compositor knows exactly which rectangles changed each frame, damage tracking is free and exact.
-- X11: pixelflux hashes each horizontal stripe of the framebuffer per frame (xxh3) and marks changed stripes dirty, with a "damage block" heuristic that stops re hashing regions that are continuously changing.
+- X11: on the DRI3 path the Damage extension reports whether anything changed since the last frame. On the XShm path pixelflux hashes each horizontal stripe of the framebuffer per frame (xxh3) and marks changed stripes dirty, with a "damage block" heuristic that stops re hashing regions that are continuously changing.
 - Idle screens take a fast path that costs close to zero CPU.
 
 ### Encoding

docs/selkies/developer-guide/baseimage-internals.md

@@ -6,7 +6,7 @@ What actually happens inside a Selkies container, boot order, services, and the
 
 The baseimage Dockerfile is a multi stage build assembling, onto a LinuxServer.io distro base (Debian, Ubuntu, Alpine, Fedora, Arch, or Kali):
 
-- A patched **Xvfb** (adds a `-vfbdevice` flag for DRI3 GPU passthrough) from the LSIO xvfb image
+- An **XLibre Xvfb** built with glamor and DRI3 from [selkies-layers](https://github.com/linuxserver/selkies-layers), patched so the screen pixmap lives on the GPU (`-glamor -dri /dev/dri/renderD###`) and the framebuffer follows RandR resizes
 - The **web frontend**: the Selkies repository pinned to an exact commit, with `selkies-web-core` and the dashboards built and dropped in `/usr/share/selkies/`
 - **labwc 0.9.7** built from source with the IPC patch (adds `labwc -i`, a read only JSON window query socket at `$XDG_RUNTIME_DIR/labwc.sock`, consumed by Pelorus)
 - A rebuilt **wlroots** with a defensive patch that catches SIGSEGV and SIGBUS inside pixman draw calls and skips the frame instead of crashing the compositor
@@ -15,7 +15,7 @@ The baseimage Dockerfile is a multi stage build assembling, onto a LinuxServer.i
 - The **input interposer** (`/usr/lib/selkies_input_interposer.so`) and **fake udev** (`/opt/lib/libudev.so.1.0.0-fake`) compiled from the Selkies addons
 - Nginx with fancyindex, PulseAudio, mesa and VA-API userspace, Vulkan loaders, all system locales, proot-apps, Docker in Docker machinery, and passwordless sudo for `abc`
 
-Baked ENV defaults worth knowing: `HOME=/config`, `DISPLAY=:1`, `TITLE=Selkies`, `SELKIES_ENCODER="h264enc,h265enc,vp8enc,vp9enc,av1enc,jpeg"`, `SELKIES_ENABLE_BASIC_AUTH=false`, `SELKIES_VIDEO_STREAMING_MODE=false`, `SELKIES_ALLOWED_ORIGINS="*"`, `START_DOCKER=true`, `DISABLE_ZINK=false`, `DISABLE_DRI3=false`, `NVIDIA_DRIVER_CAPABILITIES=all`, and the interposer path in `SELKIES_INTERPOSER`.
+Baked ENV defaults worth knowing: `HOME=/config`, `DISPLAY=:1`, `TITLE=Selkies`, `SELKIES_ENCODER="h264enc,h265enc,vp8enc,vp9enc,av1enc,jpeg"`, `SELKIES_ENABLE_BASIC_AUTH=false`, `SELKIES_VIDEO_STREAMING_MODE=false`, `SELKIES_ALLOWED_ORIGINS="*"`, `START_DOCKER=true`, `DISABLE_DRI3=false`, `NVIDIA_DRIVER_CAPABILITIES=all`, and the interposer path in `SELKIES_INTERPOSER`.
 
 ## Boot: the init chain
 
@@ -51,7 +51,7 @@ init-os-end
 | --- | --- |
 | `svc-nginx` | Reaps zombie workers then runs Nginx in the foreground |
 | `svc-pulseaudio` | PulseAudio as `abc`, never idle exits, runtime dir under `/defaults` |
-| `svc-xorg` | X11 mode: Xvfb on `:1` with a max resolution from `MAX_RES` and the DRI3 device flag. Wayland mode: sleeps |
+| `svc-xorg` | X11 mode: picks the render node (`DRINODE`, else the Nvidia node when one exists, else the first) and starts Xvfb on `:1` with `-glamor -dri <node>` so the screen lives on the GPU, unless `DISABLE_DRI3=true` or no node exists. Wayland mode: sleeps |
 | `svc-selkies` | Loads the `output` and `input` null sinks once PulseAudio is up, then runs `selkies --addr=localhost --mode=websockets` as `abc`. In Wayland mode this is what brings up the pixelflux compositor on `wayland-1` |
 | `svc-de` | Waits for the display (the `wayland-1` socket, or `xset q` on X11), then executes `/defaults/startwm_wayland.sh` or `/defaults/startwm.sh` as `abc`, recording the PID for clean teardown. On X11 it also sets the initial 1024x768 mode (or `SELKIES_MANUAL_WIDTH` and `HEIGHT`) via xrandr |
 | `svc-xsettingsd` | X11 only, DPI hinting for legacy toolkits |

docs/selkies/developer-guide/building-images.md

@@ -27,7 +27,7 @@ with a repository layout of:
 root/
 └── defaults/
     ├── autostart_wayland    # what to run in Wayland mode
-    └── autostart            # what to run in X11 fallback mode
+    └── autostart            # what to run in X11 mode
 ```
 
 and `root/defaults/autostart_wayland` containing, in the simplest case, one line:
@@ -46,7 +46,7 @@ The baseimage looks for these files. All are optional, sane defaults exist for e
 | File | Role |
 | --- | --- |
 | `/defaults/autostart_wayland` | Command launched inside labwc (Wayland). Runs as the `abc` user. Copied to `/config/.config/labwc/autostart` on first run only, so users can edit it and their edits persist |
-| `/defaults/autostart` | Same for Openbox (X11 fallback) |
+| `/defaults/autostart` | Same for Openbox (X11) |
 | `/defaults/menu_wayland.xml`, `/defaults/menu.xml` | Right click root menu (Openbox menu XML schema, shared by labwc) |
 | `/defaults/startwm_wayland.sh`, `/defaults/startwm.sh` | Replace the *entire* session startup. This is the full desktop hook, override these and you own the session |
 | `/usr/share/selkies/www/icon.png` | App icon: favicon, PWA icon, and the Selkies Desktop wallpaper mark |
@@ -124,7 +124,7 @@ The other Webtop flavors are lighter: Alpine XFCE's entire session script is ess
 
 ## The window manager layer: labwc and Openbox
 
-Single application containers run [labwc](https://github.com/labwc/labwc) on Wayland, which is a **1:1 replacement for Openbox**: it consumes the same menu XML schema and an rc.xml with the same concepts, so everything below applies to both stacks, with the X11 fallback simply using Openbox itself. Full desktop Webtops (KDE, XFCE, and friends) bring their own window management and ignore this layer entirely.
+Single application containers run [labwc](https://github.com/labwc/labwc) on Wayland, which is a **1:1 replacement for Openbox**: it consumes the same menu XML schema and an rc.xml with the same concepts, so everything below applies to both stacks, with X11 sessions simply using Openbox itself. Full desktop Webtops (KDE, XFCE, and friends) bring their own window management and ignore this layer entirely.
 
 ### The right click menu: menu.xml
 
@@ -186,7 +186,7 @@ Checklist:
 - Kill the app inside the session: can you relaunch from the right click menu? Does `RESTART_APP=true` bring it back?
 - Recreate the container against the same `/config`: settings persist, no first run dialogs
 - Try `SELKIES_DESKTOP=true` and `PELORUS=true` if you intend to support them
-- Run the X11 fallback (`-e PIXELFLUX_WAYLAND=false`) unless you are deliberately Wayland only, in which case ship the explanatory stub `startwm.sh`
+- Run the X11 stack too (`-e PIXELFLUX_WAYLAND=false`) unless you are deliberately Wayland only, in which case ship the explanatory stub `startwm.sh`
 
 ## Multi arch and CI