Feature: Play media and render HTML in the preview pane on Wayland

[MemerGamer]

Resolved / Related Issues

• Related to Roadmap: in development, to do, backlog, done #161 (roadmap) and Fix: Fixed an issue where HTML and media previews were blank on Wayland #192, which added the Wayland fallbacks this PR replaces for media and HTML.

What changed

Audio/video and HTML previews now render in the preview pane on the native Wayland host, and on X11 as well. Neither depends on native window embedding. Note that X11 never had these previews: LinuxFiles doesn't reference Uno's MediaPlayer or WebView X11 add-ins, so on X11 media showed only metadata and HTML showed its source.

• Media (libmpv, optional): frames come from the libmpv software render API and are drawn into a XAML WriteableBitmap, with play/pause, seek, and volume controls (volume is persisted). Ctrl+Space also toggles playback. Nothing is decoded until the user presses Play. The file is opened through PreviewFile (regular files only, inode pinned) and passed to mpv as /proc/self/fd/N. mpv runs with config, scripts, ytdl, and auto-loading disabled, the lavf demuxer only, protocol_whitelist=[file], and a container whitelist. Playlist expansion and path changes are rejected. Playback stops as soon as the selection changes.
• HTML (WebKitGTK 4.1 + bubblewrap, optional): the app starts a copy of itself as a short-lived helper (--linuxfiles-html-snapshot). The helper renders the file in an offscreen WebKitGTK view and returns a PNG, which is shown in a scroll viewer. The web process runs in WebKit's bwrap sandbox. If bwrap or xdg-dbus-proxy is missing, or in Snap or Flatpak environments where WebKit would skip the sandbox, it refuses to render. JavaScript is off, and navigation, downloads, and network access are blocked: a CSP is injected, and the preconnect and prefetch features, which bypass CSP, are disabled. The snapshot covers only the bounded visible region. When rendering is unavailable, the existing source-text fallback is shown.
• Release notes: not changed. Wayland still opens the page in the browser. The reasons and options are in the design note.
• Design note: docs/linux-port/wayland-previews.md covers the media and HTML design, why I didn't use wl_subsurface native hosting, and what interactive HTML would cost (WPE WebKit is the recommended follow-up).
• Packaging: AUR optdepends gain mpv and webkit2gtk-4.1. The Nix flake doesn't include either library yet, so both previews fall back there (see the note).

Steps used to test these changes

1. dotnet build src/Files.App -f net10.0-desktop and dotnet build tests/Files.Platform.Tests -warnaserror both build clean.
2. Files.Platform.Tests on a private virtual KWin: 1450/1450 passed. The new tests cover mpv rendering, resize, dispose races, disguised playlists, FIFO rejection, the helper's argument and process handling, JS disabled, zero connections to a loopback listener (including preconnect), the height crop, background trimming, sandbox refusal, and cancellation.
3. Native Wayland host on a private kwin_wayland --virtual: mp4, webm, and mp3 play; a disguised .mp4 playlist shows "could not be played"; a selection change stops the player threads; the HTML preview renders; the Markdown preview is unchanged. During rendering I saw WebKitWebProcess running under /usr/bin/bwrap.
4. X11 host on private Xvfb (scripts/linux/headless-run.sh): mp4 plays and the HTML preview renders.
5. Codex reviewed the change twice. It found no blockers, and all of its should-fix findings are addressed (bounded snapshot, playback stop, pinned media fd, sandbox environment gaps, footer trimming, debounce).

Not verified: NativeAOT publish, a real desktop session with audio output, HiDPI in the full app (the helper's 2x output is covered by tests).

🤖 Generated with Claude Code

https://claude.ai/code/session_01BTZhMsNyJ6k4VC68CNb5WU