fix(linux): stop the immersive view flashing and the motion cover failing on webkitgtk 2.54

[InstaZDLL]

Found on Fedora 44 (WebKitGTK 2.54, Wayland, Iris Xe) with the native RPM. The AppImage, which ships an older WebKit, is not affected.

Symptoms

1. Opening the immersive view on a track with a motion cover blacked the whole window out three times.
2. Cannot map External OES textures / failed to map video frame plane 0 was logged four times a second while a motion cover played. Once, the cover stayed on WebKit's ▶ placeholder and never started.

Causes, each isolated with a dedicated debug build on the machine

• (2) On Linux, useLoopFrameHold copies the current frame into a <canvas> at each timeupdate, to hide the blank frame when a looping clip jumps back. WebKitGTK's DMA-BUF video sink hands out GL textures that cannot be mapped back, so every copy failed.
  • Disabling the copy removed the errors, but brought back the flash at each loop.
  • WEBKIT_GST_DMABUF_SINK_DISABLED=1 removed the errors and kept the copy working. There was no loop flash and no visible slowdown.
  • The string is present in /usr/lib64/libwebkit2gtk-4.1.so.0.
• (1) A video mounting inside the full-window layer while its animate-fade-in runs.
  • Removing the fade took it from three blackouts to one short flash.
  • The flash that remains is WebKit creating the video layer. Removing the clip's own 700 ms fade did not change it, and neither did removing the backdrop blur.
  • WEBKIT_DISABLE_DMABUF_RENDERER=1 did remove the flash, but made the whole view lag and stretched the clip. So it is not used.

Change

• render_mode::apply sets WEBKIT_GST_DMABUF_SINK_DISABLED=1 on Linux in every mode, unless the user already set it. This only affects the video sink; the page renderer keeps its DMA-BUF path.
• ImmersiveView drops animate-fade-in on Linux (FADE_IN). The opaque bg-zinc-950 still paints from the first frame. LINUX is exported from usePlayableVideo rather than detected a second time.
• Docs: ui.md, in the Linux video limits and in the transition notes.

Verification

• Final build on the laptop, no variables passed by hand: one short flash on open, no flash at the loop, no lag, and 0 External OES lines (634 before).
• clippy --all-targets on Linux, cargo fmt, typecheck, eslint and prettier pass.

Summary by CodeRabbit

• Améliorations
  • Sous Linux, les transitions d’entrée de la vue immersive s’affichent désormais sans fondu. Un bref flash peut toutefois survenir.
  • La lecture vidéo sous Linux évite un problème de capture d’images vidéo, sans modifier les réglages personnalisés déjà définis.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: InstaZDLL/WaveFlow/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 684514e8-87b7-4376-b3e4-d4a820ead9b6

📥 Commits

Reviewing files that changed from the base of the PR and between b84d80f and bd4bd02.

📒 Files selected for processing (4)

• docs/features/ui.md
• src-tauri/crates/app/src/render_mode.rs
• src/components/player/ImmersiveView.tsx
• src/hooks/usePlayableVideo.ts

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Walkthrough

Sous Linux, la vue immersive s’ouvre sans fondu. render_mode::apply définit une variable GStreamer si l’utilisateur ne l’a pas déjà définie. La documentation décrit ces changements et les limites vidéo de WebKitGTK.

Changes

Lecture vidéo sous Linux

Layer / File(s)	Summary
Désactivation du fondu dans la vue immersive src/hooks/usePlayableVideo.ts, src/components/player/ImmersiveView.tsx, docs/features/ui.md	LINUX est exportée et sert à désactiver l’animation d’apparition de l’arrière-plan et du premier plan sous Linux. La documentation décrit la transition sans fondu.
Configuration du puits DMA-BUF src-tauri/crates/app/src/render_mode.rs, docs/features/ui.md	Sous Linux, render_mode::apply définit WEBKIT_GST_DMABUF_SINK_DISABLED=1 si cette variable n’est pas déjà définie. La documentation décrit le problème de copie d’image et le puits de remplacement.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to bd4bd

No actionable merge-blocking risk remains in the reviewed changes.

Security Architecture Review

Security architecture risk: 🔵 Low · up to bd4bd

The change preserves user-provided settings and does not show a new privilege or access boundary. Risk is limited mainly to compatibility uncertainty from changing the video backend for Linux launches; runtime behavior across supported WebKitGTK versions was not independently verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The configuration change can affect video-sink selection throughout a normally initialized Linux application process, not just the immersive view. The inspected delta does not establish greater file, credential, tenant, or service authority.

Trust Boundaries and Controls

• observed — apply is private and reached through native startup. set_unless_present preserves launch-environment authority instead of overwriting it. A launcher can opt out of the default through that environment, but the inspected change does not expose this operation to media input or a new frontend caller.

Resilience and Maintainability Implications

• inferred — Repeated application preserves the existing value, and normal startup performs the mutation before application threads are initialized. Separate launches have separate environments. The existing PID-owned launch marker, atomic state-file replacement, paint acknowledgement, and next-launch retry flow remain separate from this new setting, limiting its effect on recovery-state ownership.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Le titre décrit clairement les deux changements principaux : la correction du clignotement de la vue immersive et l’échec de lecture vidéo sous WebKitGTK 2.54. Il suit aussi le format Conventional Com…
Description check	✅ Passed	La description fournit un contexte précis, les symptômes, les causes, les changements et les résultats de vérification. Elle ne reprend pas les sections formelles du modèle, la checklist ni un numéro …
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}