fix(linux): prefer WebGL renderer for Lightning exports with WebGPU f…

[Hashim-Bhagad]

Description

Lightning exports on Linux default to the WebGL renderer instead of WebGPU, and retry once with WebGL if a Pixi WebGPU _resourceType render failure occurs. Explicit backend overrides are still respected.

Motivation

Fixes #644: Lightning (Beta) export fails immediately on Linux with Cannot read properties of undefined (reading '_resourceType') while Legacy works. WebGPU initializes successfully on Linux Mesa/Intel but produces invalid GPU resources on first frame render. Legacy and the preview already render WebGL-first, which is why they were unaffected.

Type of Change

• Bug Fix

Related Issue(s)

Fixes #644

Testing Guide

• npx vitest --run — 133 files / 1190 tests pass, including new regression tests for Linux renderer preference/ordering and the _resourceType → WebGL retry
• npx tsc --noEmit — clean
• npx vite build — succeeds
• Not verified: packaged AppImage manual export on Linux GPU hardware (no display environment available); reviewer with a Linux machine should test a 16:9 export plus one with zoom/cursor effects

Checklist

• I have performed a self-review of my code.
• I have added any necessary screenshots or videos.
• I have linked related issue(s) and updated the changelog if applicable. (No CHANGELOG file in repo; fixes [Bug]: Lightning (Beta) export fails on Linux — "Cannot read properties of undefined (reading '_resourceType')" (WebCodecs avc1.640033, 1080x1350@60); Legacy works #644 for auto-close.)

Summary by CodeRabbit

• Bug Fixes
  • Improved video export reliability on Linux by preferring the WebGL renderer by default.
  • Preserved explicit WebGL or WebGPU renderer selections across supported platforms.
  • Added an automatic one-time fallback to WebGL when WebGPU rendering fails during export.
  • Improved renderer selection so WebGPU remains preferred on macOS and Windows when available, with WebGL used when necessary.

[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: 0006a10c-3d0a-44f6-830f-d271c31f9e8d

📥 Commits

Reviewing files that changed from the base of the PR and between b3ea775 and de3411a.

📒 Files selected for processing (5)

• src/lib/exporter/backendPolicy.test.ts
• src/lib/exporter/backendPolicy.ts
• src/lib/exporter/modernFrameRenderer.ts
• 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; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

Lightning backend fallback

Layer / File(s)	Summary
Backend policy and validation src/lib/exporter/backendPolicy.ts, src/lib/exporter/backendPolicy.test.ts	Adds platform-aware backend preference and ordering helpers. Adds detection for Pixi _resourceType renderer failures and tests for the new behavior.
Renderer backend ordering src/lib/exporter/modernFrameRenderer.ts	Normalizes the runtime platform and delegates Pixi backend ordering to the backend policy.
Exporter preference and retry src/lib/exporter/modernVideoExporter.ts, src/lib/exporter/modernVideoExporter.fallback.test.ts	Applies the resolved backend preference. Retries once with WebGL after a qualifying WebGPU renderer failure. Tests Linux preference and WebGL retry behavior.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant ModernVideoExporter
  participant backendPolicy
  participant ModernFrameRenderer
  participant WebCodecs
  ModernVideoExporter->>backendPolicy: Resolve platform backend preference
  ModernVideoExporter->>ModernFrameRenderer: Construct renderer
  ModernFrameRenderer->>backendPolicy: Resolve backend order
  ModernFrameRenderer->>WebCodecs: Render with selected backend
  WebCodecs-->>ModernVideoExporter: Return _resourceType failure
  ModernVideoExporter->>ModernFrameRenderer: Retry with WebGL

Loading

Suggested reviewers: webadderall

Merge Risk: ⚪ Minimal · up to de341

No concrete merge-blocking defect remains in the platform-aware WebGL fallback.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: Linux Lightning exports now prefer the WebGL renderer when WebGPU fallback behavior is involved.
Description check	✅ Passed	The description covers the purpose, motivation, bug fix type, related issue, testing results, known verification limits, and checklist status. Screenshots and video are not necessary for this renderer…
Linked Issues check	✅ Passed	Issue #644 requires Lightning exports on Linux to avoid the Pixi WebGPU _resourceType failure and to use WebGL or another supported path. The change selects webgl by default on Linux, retries once…
Out of Scope Changes check	✅ Passed	The changed files implement backend policy, renderer backend selection, exporter retry handling, and automated tests for issue #644. These changes directly support the linked Linux Lightning export fi…

• 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.}