fix(linux): stabilize Wayland HUD and Lightning export

[yashovardhanpareek]

Summary

On Linux, the recording HUD fallback window is only 860x160. Radix menus and popovers render inside that window, so controls near the bottom are clipped by the BrowserWindow boundary. The existing HUD expansion path is disabled on Linux, while dynamically resizing/repositioning a transparent always-on-top window is unreliable on Wayland and can oscillate.

This change detects a Wayland session and starts the Linux fallback HUD at the already-established expanded size (860x540). X11 remains at the compact fallback size, and Windows/macOS behavior is unchanged.

The patch also extracts the geometry decision into a small pure helper and adds coverage for Wayland, X11, Windows, and macOS behavior.

It also fixes Lightning exports failing before the first rendered frame with Cannot read properties of undefined (reading '_resourceType'). Although the backend policy declares WebGL as Lightning's stable default, ModernVideoExporter discarded the configured/default preference and allowed Pixi to select WebGPU automatically. The exporter now applies the existing stable WebGL default while continuing to honor an explicit WebGPU override.

Verification

• npx vitest --run electron/hudOverlayBounds.test.ts electron/hudOverlaySession.test.ts — 20 tests passed
• Renderer routing regression tests cover both the WebGL default and explicit WebGPU override
• npm test — 134 test files and 1,193 tests passed
• npx tsc --noEmit — passed
• Biome check — passed
• Linux AppImage production build — passed
• Packaged Electron main-process smoke test — passed
• Fedora 44, native Wayland packaged launch — passed
• Packaged HUD geometry inspected via Chromium DevTools Protocol: viewport 860x540; webcam popover top 311, bottom 436, fully within the viewport

Camera capture itself was not exercised in the sandbox; the regression being verified here is window/popover geometry.

The export regression is verified at the renderer-routing boundary and by the full suite; a complete real-media export was not run in the sandbox.

Scope and tradeoff

This is intentionally Wayland-only. Linux transparent-window mouse passthrough remains limited (see #861), so the larger transparent surface can intercept clicks in its bounds. The change prioritizes usable, unclipped controls and avoids the resize/position feedback behavior reported for Wayland. X11 keeps the existing compact behavior.

Related work

• [Bug]: Recording HUD bar oscillates/vanishes on mouse hover on Arch Linux (Hyprland / Wayland) #891
• Fix Linux Wayland HUD oscillation on hover and popover menu clipping #876
• fix(linux): stop HUD menus being clipped, and show Deutsch instead of "de" #896
• fix(hud): Wayland — fit dropdown menus, working hide button, safe tray restore #919
• fix(linux): fix screen recording, HUD expansion, and video export on Linux (X11) #925

Those proposals explore dynamic resizing or broader Linux changes. This PR is a minimal current-main fix that applies static expanded geometry only where Wayland needs it, preserving existing behavior elsewhere.

Summary by CodeRabbit

• Bug Fixes

  • Improved HUD overlay sizing on Wayland when mouse passthrough is unavailable.
  • Prevented unreliable dynamic resizing by maintaining expanded overlay bounds.
  • Preserved compact sizing on Linux X11 and other supported platforms.
  • Ensured overlay bounds remain within small display work areas.
  • Ensured video exports honor the configured rendering backend, with a reliable default when none is selected.

• Tests

  • Added coverage for Wayland detection, platform-specific sizing, fallback bounds, display-area clamping, and rendering backend selection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 14d6ad94-597e-4807-9787-88da1b75ff39

📥 Commits

Reviewing files that changed from the base of the PR and between 956b43c and dfa8feb.

📒 Files selected for processing (2)

• src/lib/exporter/modernVideoExporter.fallback.test.ts
• src/lib/exporter/modernVideoExporter.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The HUD overlay now detects Wayland sessions and uses expanded static bounds when mouse passthrough is unavailable. The video exporter now forwards the configured render backend or its default.

HUD overlay Wayland handling

Layer / File(s)	Summary
Session detection and static bounds electron/hudOverlaySession.ts, electron/hudOverlaySession.test.ts, electron/hudOverlayBounds.ts, electron/hudOverlayBounds.test.ts	Adds injectable Wayland detection and static bounds calculation. Tests cover session parsing, platform-specific bounds, passthrough bounds, and small work areas.
Window bounds integration electron/windows.ts	Uses static expanded bounds for unsupported Wayland sessions. Other paths retain dynamic bounds behavior.

Video renderer backend routing

Layer / File(s)	Summary
Renderer backend forwarding src/lib/exporter/modernVideoExporter.ts, src/lib/exporter/modernVideoExporter.fallback.test.ts	Passes the configured render backend to ModernFrameRenderer and uses the default backend when no backend is configured. Tests verify both backend selections.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: webadderall

Merge Risk: ⚪ Minimal · up to dfa8f

The Wayland HUD sizing and renderer-backend forwarding changes have focused coverage, with no remaining concrete merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly identifies both primary fixes: Wayland HUD stabilization and Lightning export correction.
Description check	✅ Passed	The description provides a detailed purpose, motivation, scope, testing results, tradeoffs, and related issues. It does not use every template heading or include a completed checklist, but the require…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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