## What
Adds `docs/linux-rendering-troubleshooting.md` — the user-facing
troubleshooting page for Linux rendering failures.
## What's in the doc
**Crash: `colrv1_configure_skpaint` assertion abort (AppImage, Fedora
40+)**
Root cause: the AppImage bundles WebKitGTK compiled against FreeType
2.11.1, but `libfreetype.so.6` is not bundled — WebKit loads the host's
FreeType at runtime. FreeType 2.13.0 added a field to
`FT_ColorStopIterator` (16 → 20 bytes); on hosts with FreeType ≥ 2.13
the struct-layout mismatch corrupts Skia's COLRv1 color-stop arithmetic,
causing the assertion abort. Fix: upgrade to v0.5.2+ (build container
bumped to `ubuntu:24.04` in
[#3602](https://github.com/block/buzz/pull/3602)). Includes the glibc
floor table (2.35 → 2.39) and `.deb`/`.rpm` guidance for Ubuntu 22.04 /
Debian 12 users. A manual fontconfig workaround is preserved for users
stuck on older AppImages.
**Blank window / dmabuf renderer (NVIDIA, AppImage)**
Covers the auto-fix shipped in v0.5.1
([#3271](https://github.com/block/buzz/pull/3271)) and the
`--safe-rendering` flag for cases where auto-detection misses.
**AMD RDNA4 / transparent window
([#2643](https://github.com/block/buzz/issues/2643))**
Documents the three-variable workaround verified by the reporter
(`GDK_BACKEND=x11`, `WEBKIT_DISABLE_DMABUF_RENDERER=1`,
`WEBKIT_SKIA_ENABLE_CPU_RENDERING=1`).
Also includes a crash-log capture recipe and issue-filing checklist.
Context: [#2548](https://github.com/block/buzz/issues/2548),
[#2982](https://github.com/block/buzz/issues/2982),
[#2643](https://github.com/block/buzz/issues/2643),
[#2338](https://github.com/block/buzz/issues/2338).
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
