fix(linux): retry Lightning export with WebGL fallback when WebGPU render fails

[AlexSilva-dev]

Problem

Lightning (Beta) MP4 export fails on Linux with:

Lightning (Beta) export failed.
Reason: Cannot read properties of undefined (reading '_resourceType')
Renderer: webgpu
Encoder path: WebCodecs (avc1.640033/prefer-software/realtime)

Reproduced on the official v1.4.0-beta.1 AppImage (Arch Linux, Hyprland/Wayland, Electron 43.1.0, AMD RADV). The string _resourceType only exists in pixi.js's WebGPU renderer (gpu/BindGroupSystem): the crash happens inside the WebGPU render stage, before any frame is encoded (frameCount: 0). The WebCodecs software encoder path works — confirmed with a minimal repro (clean Electron + pixi WebGPURenderer + per-frame texture swap) where canvas/WebGL pipelines encode successfully.

Solution

• WebGPU remains the default render backend on Linux (design unchanged).
• On Linux, when a render-stage failure occurs with WebGPU, the export retries once from scratch with the WebGL renderer (state fully cleaned between attempts, max 1 retry). renderFallbackUsed is reported in export metrics/report.
• RECORDLY_LINUX_RENDER_BACKEND=webgl|webgpu env override for debugging/validation; a forced value disables the automatic fallback.
• Smoke-export diagnostics now survive packaged builds (terser drop_console) via keepLog/keepError wrappers, and scripts/verify-smoke-build.mjs guards against stale packaging.

Testing

• New unit tests: backend policy defaults/overrides (unset→webgpu, forced values honored, non-linux→undefined) and fallback behavior (crash→retry→success with renderBackend: webgl + renderFallbackUsed: true; forced env→no retry; max 1 retry). Full suite: 1103 tests passing, biome and tsc clean.
• End-to-end on Linux (Hyprland/Wayland), via the built-in smoke export: WebGPU attempt fails with the known pixi crash → automatic WebGL retry → success: true, 327 frames, valid playable MP4 (1080p30). Forcing webgl exports directly with no WebGPU attempt.
• macOS/Windows unchanged: the policy returns undefined outside Linux, the fallback is gated to the linux runtime platform, and the new IPC (get-linux-render-backend-env) is additive and returns null elsewhere.

Notes

• Relates to fix: avoid Linux WebGPU export failures #901 (alternative take on Linux WebGPU export failures) — happy to coordinate.
• The underlying pixi.js WebGPU crash (BindGroupSystem._resourceType on first render) is an upstream issue; this PR makes the app resilient to it while it gets fixed upstream.

Summary by CodeRabbit

• New Features

  • Linux video exports now default to WebGPU and can use WebGL when explicitly configured.
  • If WebGPU fails during export, the app automatically retries once with WebGL when available.
  • Export metrics indicate when a fallback was used.
  • Export and smoke-run diagnostics remain visible in production builds.

• Bug Fixes

  • Improved resilience for Linux exports affected by mid-export rendering failures.

• Tests

  • Added coverage for backend selection, fallback behavior, texture replacement, diagnostics, and packaged-build verification.

[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: 649deb8f-2715-4e3d-91ac-a0480c02b082

📥 Commits

Reviewing files that changed from the base of the PR and between 4b20a1a and 5f79407.

📒 Files selected for processing (16)

• electron/electron-env.d.ts
• electron/ipc/register/settings.ts
• electron/preload.ts
• scripts/verify-smoke-build.mjs
• scripts/verify-smoke-build.test.mjs
• src/components/video-editor/export/useExportRunner.ts
• src/components/video-editor/export/useSmokeExportAutomation.ts
• src/lib/exporter/backendPolicy.test.ts
• src/lib/exporter/backendPolicy.ts
• src/lib/exporter/modernFrameRenderer.test.ts
• src/lib/exporter/modernVideoExporter.linuxWebgpuFallback.test.ts
• src/lib/exporter/modernVideoExporter.ts
• src/lib/exporter/types.ts
• src/lib/keepConsole.test.ts
• src/lib/keepConsole.ts
• vitest.config.ts

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

---

📝 Walkthrough

Walkthrough

The PR adds Linux render-backend selection and WebGPU-to-WebGL export fallback. It preserves smoke-export diagnostics in production builds and adds a packaged-build marker verification script with Vitest coverage.

Changes

Linux export and smoke verification

Layer / File(s)	Summary
Backend selection bridge electron/electron-env.d.ts, electron/ipc/register/settings.ts, electron/preload.ts, src/lib/exporter/backendPolicy.ts, src/lib/exporter/backendPolicy.test.ts	The Electron bridge exposes RECORDLY_LINUX_RENDER_BACKEND. Linux backend policy honors webgl and webgpu, and defaults to webgpu.
Linux export fallback flow src/lib/exporter/modernVideoExporter.ts, src/lib/exporter/types.ts, src/lib/exporter/modernVideoExporter.linuxWebgpuFallback.test.ts, src/lib/exporter/modernFrameRenderer.test.ts	The exporter detects render-stage failures, retries Linux WebGPU exports once with WebGL when allowed, records renderFallbackUsed, and tests forced-backend and retry-failure behavior.
Persistent export diagnostics src/lib/keepConsole.ts, src/lib/keepConsole.test.ts, src/components/video-editor/export/useExportRunner.ts, src/components/video-editor/export/useSmokeExportAutomation.ts	Smoke-export and backend messages use keepLog and keepError wrappers that avoid removal by production drop_console processing.
Packaged smoke-build verification scripts/verify-smoke-build.mjs, scripts/verify-smoke-build.test.mjs, vitest.config.ts	The new script checks expected markers in an asar payload using latin1 reads. Tests cover argument parsing, marker detection, binary-safe reads, and script test discovery.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 5f794

No actionable merge-blocking risk remains in the reviewed Linux fallback, diagnostics, and smoke-build verification changes.

Sequence Diagram(s)

sequenceDiagram
  participant ModernVideoExporter
  participant electronAPI
  participant ModernFrameRenderer
  ModernVideoExporter->>electronAPI: Read Linux backend environment
  electronAPI-->>ModernVideoExporter: Return backend value or null
  ModernVideoExporter->>ModernFrameRenderer: Initialize with resolved backend
  ModernFrameRenderer-->>ModernVideoExporter: Report render failure
  ModernVideoExporter->>ModernFrameRenderer: Retry once with WebGL
  ModernFrameRenderer-->>ModernVideoExporter: Return export result and fallback metrics

Loading

Suggested reviewers: webadderall, meiiie

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 16 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 and concisely describes the primary change: retrying Linux Lightning export with a WebGL fallback after a WebGPU render failure.
Description check	✅ Passed	The description is detailed and relevant. It explains the problem, solution, motivation, testing results, platform scope, environment override, and related issue. It does not use the template headings…
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.

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