From 6b59f8c7a7a2d8959282d2c8d6f8c285aed875b2 Mon Sep 17 00:00:00 2001
From: Giovanni Trujillo Silvas <gtrujill0@outlook.com>
Date: Sat, 12 Sep 2026 17:05:31 -0600
Subject: [PATCH] FIX:default to WebGL over WebGPU on Linux

---
 src/lib/exporter/backendPolicy.test.ts  | 8 ++++++++
 src/lib/exporter/backendPolicy.ts       | 9 +++++++++
 src/lib/exporter/modernFrameRenderer.ts | 9 ++++++++-
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/lib/exporter/backendPolicy.test.ts b/src/lib/exporter/backendPolicy.test.ts
index 69ae5b8f5..81fe6b58c 100644
--- a/src/lib/exporter/backendPolicy.test.ts
+++ b/src/lib/exporter/backendPolicy.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
 	getDefaultLightningRenderBackend,
+	getDefaultLightningRenderBackendOrder,
 	normalizeLightningRuntimePlatform,
 	planLightningExportRoutes,
 	shouldPreferNativeAutoBackend,
@@ -27,6 +28,13 @@ describe("backendPolicy", () => {
 		expect(getDefaultLightningRenderBackend()).toBe("webgl");
 	});
 
+	it("defaults Linux to WebGL first to avoid the WebGPU/Dawn resource-import crash", () => {
+		expect(getDefaultLightningRenderBackendOrder("linux")).toEqual(["webgl", "webgpu"]);
+		expect(getDefaultLightningRenderBackendOrder("win32")).toEqual(["webgpu", "webgl"]);
+		expect(getDefaultLightningRenderBackendOrder("darwin")).toEqual(["webgpu", "webgl"]);
+		expect(getDefaultLightningRenderBackendOrder("unknown")).toEqual(["webgpu", "webgl"]);
+	});
+	
 	it("keeps Windows auto exports on the streaming route by default", () => {
 		expect(shouldPreferNativeStaticLayoutBeforeBreeze("win32", "auto")).toBe(false);
 		expect(shouldPreferNativeStaticLayoutBeforeBreeze("darwin", "auto")).toBe(false);
diff --git a/src/lib/exporter/backendPolicy.ts b/src/lib/exporter/backendPolicy.ts
index 3c7f98479..0cac7485e 100644
--- a/src/lib/exporter/backendPolicy.ts
+++ b/src/lib/exporter/backendPolicy.ts
@@ -149,3 +149,12 @@ export function planLightningExportRoutes(options: {
 export function getDefaultLightningRenderBackend(): ExportRenderBackend {
 	return "webgl";
 }
+
+// WebGPU-on-Linux (Dawn/Vulkan) can corrupt GPU resource imports for VideoFrame-backed
+// textures mid-export, crashing PixiJS's WebGPU bind group system well after init
+// succeeds. Default Linux to WebGL until that upstream instability is resolved.
+export function getDefaultLightningRenderBackendOrder(
+	platform: LightningRuntimePlatform,
+): ExportRenderBackend[] {
+	return platform === "linux" ? ["webgl", "webgpu"] : ["webgpu", "webgl"];
+}
diff --git a/src/lib/exporter/modernFrameRenderer.ts b/src/lib/exporter/modernFrameRenderer.ts
index 25dc33c39..482346e70 100644
--- a/src/lib/exporter/modernFrameRenderer.ts
+++ b/src/lib/exporter/modernFrameRenderer.ts
@@ -86,6 +86,10 @@ import {
 	renderAnnotations,
 	renderAnnotationToCanvas,
 } from "./annotationRenderer";
+import {
+	getDefaultLightningRenderBackendOrder,
+	normalizeLightningRuntimePlatform,
+} from "./backendPolicy";
 import { ForwardFrameSource } from "./forwardFrameSource";
 import { resolveMediaElementSource } from "./localMediaSource";
 import {
@@ -638,13 +642,16 @@ export class FrameRenderer {
 		};
 
 		const preferredRenderBackend = this.config.preferredRenderBackend;
+		const runtimePlatform = normalizeLightningRuntimePlatform(
+			typeof navigator !== "undefined" ? navigator.platform || navigator.userAgent || "" : "",
+		);
 		const backendOrder: ExportRenderBackend[] =
 			preferredRenderBackend === "webgl"
 				? ["webgl", "webgpu"]
 				: preferredRenderBackend === "webgpu"
 					? ["webgpu", "webgl"]
 					: typeof navigator !== "undefined" && "gpu" in navigator
-						? ["webgpu", "webgl"]
+						? getDefaultLightningRenderBackendOrder(runtimePlatform)
 						: ["webgl"];
 		const failures: PixiRendererAttempt[] = [];