fix(v3/linux): align cross image GTK baseline

[taliesin-ai]

Fixes #5928

Root cause

The canonical cross image used Debian 12, whose GTK 4.8 headers do not provide the GTK APIs used by the default Wails v3 Linux backend.

Change

• move the canonical image to Debian 13/Trixie
• assert the supported GTK 4.14+ baseline during image construction
• retain GTK3/WebKit2GTK 4.1 packages for the legacy -tags gtk3 path
• add embedded-asset regression coverage and update the implementation tracker

Verification

• reproduced the reported CGO errors with the Bookworm package set (GTK 4.8.3)
• compiled ./pkg/application on Trixie (GTK 4.18.6), default GTK4 path
• compiled ./pkg/application on Trixie with -tags gtk3
• CGO_ENABLED=0 go test ./internal/commands -run TestCrossDockerfileMatchesLinuxSupportContract -count=1
• git diff --check
• CodeRabbit invoked; public OSS review quota was exhausted before findings could run

Summary by CodeRabbit

• Bug Fixes

  • Updated the official Linux cross-compilation image to Debian 13.
  • Aligned the image with the GTK 4.14+ and WebKitGTK 6.0 baseline.
  • Preserved GTK 3 and WebKitGTK 4.1 legacy compatibility.
  • Improved iOS linker flags, development connection stability, and ordered event dispatch with backpressure.
  • Added validation for required GTK and WebKit development dependencies.

• Documentation

  • Documented GTK4 as the default build target and GTK3 as the legacy opt-in.
  • Updated cross-compilation guidance, Phase 6 status, and changelog coverage.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 35bd0eb5-901b-48f0-b57a-7fd433270f2b

📥 Commits

Reviewing files that changed from the base of the PR and between e891213 and 9a994ca.

📒 Files selected for processing (1)

• v3/UNRELEASED_CHANGELOG.md

---

Walkthrough

The cross-compilation image now uses Debian 13 and validates GTK 4.14, WebKitGTK 6.0, GTK 3, and WebKitGTK 4.1 development packages. Tests and documentation record these requirements.

Changes

Cross-image GTK baseline

Layer / File(s)	Summary
Image contract and regression validation v3/internal/commands/build_assets/docker/Dockerfile.cross, v3/internal/commands/cross_dockerfile_test.go	The image uses golang:1.26-trixie. The build validates the required GTK and WebKit packages with pkg-config. The test checks the Dockerfile contract.
Build guidance and release notes IMPLEMENTATION.md, v3/UNRELEASED_CHANGELOG.md	Documentation defines GTK4 as the default and GTK3 as the legacy -tags gtk3 path. Changelog entries record the Debian 13 migration, GTK 4.14 baseline, and related fixes.

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

Possibly related PRs

• wailsapp/wails#5071: Addresses GTK4/WebKitGTK build dependencies and cross-compilation guidance.

Suggested reviewers: leaanthony

Poem

A rabbit checks the GTK gate,
Debian hops to thirteen’s state.
WebKit packages line up bright,
Tests guard the build day and night.
The cross-image contract holds tight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	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 GTK baseline fix for the v3 Linux cross-compilation image.
Description check	✅ Passed	The description covers the issue, root cause, changes, motivation, and verification steps, so it is mostly complete.
Linked Issues check	✅ Passed	The Dockerfile update and regression tests address issue #5928 by providing the required GTK4 baseline for successful cross-compilation.
Out of Scope Changes check	✅ Passed	The Dockerfile, contract test, changelog, and implementation documentation changes directly support the linked issue and stated objectives.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/5928-gtk48-cross

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@IMPLEMENTATION.md`:
- Around line 243-246: Update the Phase 6 instructions near the canonical
Dockerfile.cross description so they state GTK4 is the default backend and the
legacy path is selected with -tags gtk3. Remove or clearly mark outdated
GTK3-default and BUILD_TAGS=gtk4 guidance as historical, keeping
IMPLEMENTATION.md consistent with the current GTK4/GTK3 contract.

In `@v3/internal/commands/cross_dockerfile_test.go`:
- Around line 15-25: Extend the Dockerfile content assertions in the cross-image
test to verify the three missing pkg-config checks: webkitgtk-6.0, gtk+-3.0, and
webkit2gtk-4.1, alongside the existing GTK4 assertion. Keep the current
dependency-package assertions unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 18b46200-1f4f-4d78-8906-52f91a719a2e

📥 Commits

Reviewing files that changed from the base of the PR and between 2a462f3 and 06eb197.

📒 Files selected for processing (4)

• IMPLEMENTATION.md
• v3/UNRELEASED_CHANGELOG.md
• v3/internal/commands/build_assets/docker/Dockerfile.cross
• v3/internal/commands/cross_dockerfile_test.go

[taliesin-ai]

Addressed both actionable CodeRabbit findings in dfb9205b8 after merging current origin/master without force:

• corrected Phase 6 to document GTK4/WebKitGTK 6.0 as the default and -tags gtk3 as the legacy opt-in;
• extended the embedded Dockerfile contract test to assert all four GTK/WebKit pkg-config checks.

Verification:

• CGO_ENABLED=0 go test ./internal/commands -run TestCrossDockerfileMatchesLinuxSupportContract -count=1
• CGO_ENABLED=0 go test ./internal/commands -count=1
• built the canonical Trixie cross image with Podman; its build-time package checks passed (GTK 4.18.6, WebKitGTK 6.0 2.52.5, GTK 3.24.49, WebKit2GTK 4.1 2.52.5)
• inside that image, compiled ./pkg/application for default GTK4 and legacy -tags gtk3
• git diff --check

The installed CodeRabbit CLI rejects the legacy --plain flag because plain text is now the default. The supported coderabbit review --uncommitted equivalent was invoked, but the public OSS review quota was exhausted (reported reset wait: 53 minutes). Hosted CodeRabbit and CI are running on the pushed commit.