fix(export): avoid Pixi WebGPU batch shader mismatch on Linux (_resourceType crash)

[fabri404]

Description

Lightning exports on Linux crashed on the first frame with Cannot read properties of undefined (reading '_resourceType'). When the WebGPU export renderer's batch texture limit differs from WebGL's, the renderer now rejects WebGPU and falls back to WebGL.

Motivation

Root cause: Pixi caches a single module-level batch shader (DefaultBatcher) sized by the first renderer created in the page. The editor preview initializes WebGL first; on Mesa drivers WebGL exposes 32 texture units while WebGPU exposes 16 (maxSampledTexturesPerShaderStage). The WebGPU export renderer then reuses a shader whose bind group layout expects 32 textures while its batch bind group only has 16, so BindGroupSystem._createBindGroup reads undefined resources. On macOS/Windows (ANGLE) both limits are 16, which is why only Linux is affected. Still present in pixi.js 8.20.1.

Captured stack trace: BindGroupSystem._createBindGroup ← GpuBatchAdaptor.execute ← BatcherPipe.execute ← WebGPURenderer.render ← FrameRenderer.renderFrame.

Type of Change

• New Feature
• Bug Fix
• Refactor / Code Cleanup
• Documentation Update
• Other (please specify)

Related Issue(s)

Fixes #644, fixes #948.

Testing Guide

1. On Linux with Mesa (tested: Intel Gen12 / Iris Xe), run a Lightning export.
2. The console logs webgpu export renderer unavailable … WebGPU batch texture limit (16) differs from WebGL (32) and the export completes with WebGL.
3. npx vitest --run src/lib/exporter/pixiBatchTextureLimits.test.ts

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.

---

🤖 Generated with claude-flow

https://claude.ai/code/session_014WWof1pMnhBVJuJzNreUoB

Summary by CodeRabbit

• Bug Fixes
  • Improved export compatibility across WebGPU and WebGL rendering environments.
  • Exporting now detects incompatible texture batch limits and automatically attempts a compatible rendering backend when available.
  • Added clearer diagnostics when rendering limits cannot be reconciled, helping explain why a backend was not selected.

[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: 7e6f5061-08e0-43ee-ac28-17299252b4e4

📥 Commits

Reviewing files that changed from the base of the PR and between 8b9b106 and 388f8b2.

📒 Files selected for processing (3)

• src/lib/exporter/modernFrameRenderer.ts
• src/lib/exporter/pixiBatchTextureLimits.test.ts
• src/lib/exporter/pixiBatchTextureLimits.ts

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

---

📝 Walkthrough

Walkthrough

Changes

Batch texture compatibility

Layer / File(s)	Summary
Batch texture limit utilities src/lib/exporter/pixiBatchTextureLimits.ts, src/lib/exporter/pixiBatchTextureLimits.test.ts	Adds utilities to compare WebGPU and WebGL batchable texture limits. WebGL limit reads return null when unavailable. Tests cover matching, mismatched, and unavailable limits.
WebGPU initialization guard src/lib/exporter/modernFrameRenderer.ts	Checks the WebGPU limit after application creation. A mismatch throws an explanatory error, allowing the backend loop to try the next backend.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant createPixiApplication
  participant assertWebGpuBatchTextureLimitCompatible
  participant readWebGlMaxBatchableTextures
  participant PixiRenderer
  createPixiApplication->>assertWebGpuBatchTextureLimitCompatible: check WebGPU application
  assertWebGpuBatchTextureLimitCompatible->>readWebGlMaxBatchableTextures: read WebGL batch limit
  readWebGlMaxBatchableTextures->>PixiRenderer: call getMaxTexturesPerBatch()
  PixiRenderer-->>readWebGlMaxBatchableTextures: return limit or failure
  assertWebGpuBatchTextureLimitCompatible->>PixiRenderer: read maxBatchableTextures
  PixiRenderer-->>assertWebGpuBatchTextureLimitCompatible: return WebGPU limit
  assertWebGpuBatchTextureLimitCompatible-->>createPixiApplication: return or throw mismatch
  createPixiApplication->>createPixiApplication: retry next backend after mismatch

Loading

Merge Risk: ⚪ Minimal · up to 388f8

The change detects incompatible renderer limits and safely falls back to WebGL, with no unresolved merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 3 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 export fix, the Pixi WebGPU batch shader mismatch, the Linux scope, and the resulting crash.
Description check	✅ Passed	The description is complete. It explains the problem and root cause, identifies the bug-fix type, links related issues, provides testing steps, and includes the checklist.
Linked Issues check	✅ Passed	The change addresses #644 and #948. modernFrameRenderer.ts compares the WebGPU and WebGL batch texture limits before accepting WebGPU. A mismatch throws inside the existing renderer-attempt flow, so…
Out of Scope Changes check	✅ Passed	The changed files implement the renderer compatibility guard and its focused tests. The helper, integration change, and test cases all support the linked Linux Lightning export failure. No unrelated p…

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

[goldstac]

Description

Lightning exports on Linux crashed on the first frame with Cannot read properties of undefined (reading '_resourceType'). When the WebGPU export renderer's batch texture limit differs from WebGL's, the renderer now rejects WebGPU and falls back to WebGL.

Motivation

Root cause: Pixi caches a single module-level batch shader (DefaultBatcher) sized by the first renderer created in the page. The editor preview initializes WebGL first; on Mesa drivers WebGL exposes 32 texture units while WebGPU exposes 16 (maxSampledTexturesPerShaderStage). The WebGPU export renderer then reuses a shader whose bind group layout expects 32 textures while its batch bind group only has 16, so BindGroupSystem._createBindGroup reads undefined resources. On macOS/Windows (ANGLE) both limits are 16, which is why only Linux is affected. Still present in pixi.js 8.20.1.

Captured stack trace: BindGroupSystem._createBindGroup ← GpuBatchAdaptor.execute ← BatcherPipe.execute ← WebGPURenderer.render ← FrameRenderer.renderFrame.

Type of Change

• New Feature
• Bug Fix
• Refactor / Code Cleanup
• Documentation Update
• Other (please specify)

Related Issue(s)

Fixes #644, fixes #948.

Testing Guide

1. On Linux with Mesa (tested: Intel Gen12 / Iris Xe), run a Lightning export.
2. The console logs webgpu export renderer unavailable … WebGPU batch texture limit (16) differs from WebGL (32) and the export completes with WebGL.
3. npx vitest --run src/lib/exporter/pixiBatchTextureLimits.test.ts

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.

🤖 Generated with claude-flow

https://claude.ai/code/session_014WWof1pMnhBVJuJzNreUoB

Summary by CodeRabbit

• Bug Fixes

  • Improved export compatibility across WebGPU and WebGL rendering environments.
  • Exporting now detects incompatible texture batch limits and automatically attempts a compatible rendering backend when available.
  • Added clearer diagnostics when rendering limits cannot be reconciled, helping explain why a backend was not selected.

❤️

[Anit-K-Peter]

Tested PR #951 locally on Fedora 44 KDE Plasma with an AMD Ryzen 7 7730U / integrated Radeon GPU.

Lightning MP4 export at 1920×1080, 30 FPS completed successfully using the PR build.

The _resourceType crash from v1.4.0 is no longer reproducible.

WebGL + WebCodecs export completed successfully.

thank you!

[goldstac]

i'm trying this right now