feat(build): optional xvfb-run for Linux GUI builds

Add an --xvfb switch to 'build run' and 'job' that wraps the Linux build
command in 'xvfb-run -a sh -c ...', giving GUI toolkits (GTK4/PyGObject)
a headless $DISPLAY. Exported env vars precede xvfb-run so they
propagate into the virtual-display session. No-op (with a notice) for
Windows guests.

The local-ci-build composite action exposes it as the 'xvfb' input
(default false), forwarded as INPUT_XVFB -> --xvfb, mirroring the
use-shared-cache/skip-artifact wiring.

Docs: WORKFLOW-AUTHORING.md parameter table + Linux example note;
LINUX-TEMPLATE-SETUP.md Step 4a (the template ships python3-gi
gir1.2-gtk-4.0 xvfb). Adds build-run unit tests (wrap, plain, Windows
no-op).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/actions/local-ci-build/action.yml

@@ -20,6 +20,7 @@
 #             build-command: 'python build_plugin.py --final --dist-dir dist'
 #             artifact-source: 'dist'
 #             submodules: 'true'
+#             # xvfb: 'true'   # Linux: run the build under a headless X server
 #
 # Runner label determines the guest OS template:
 #   windows-build  ->  WinBuild2025 (WinRM/HTTPS transport)
@@ -190,6 +191,15 @@ inputs:
     required: false
     default: 'false'
 
+  xvfb:
+    description: >
+      Linux only. Set to "true" to run the build command under xvfb-run, a
+      headless X server providing $DISPLAY for GUI toolkits (e.g. GTK4 /
+      PyGObject). Requires xvfb in the Linux template (installed by
+      Install-CIToolchain-Linux2404.sh). Ignored on Windows guests.
+    required: false
+    default: 'false'
+
 outputs:
   artifact-path:
     description: >
@@ -228,6 +238,7 @@ runs:
         INPUT_EXTRA_GUEST_ENV_JSON:  ${{ inputs.extra-guest-env-json }}
         INPUT_USE_SHARED_CACHE:      ${{ inputs.use-shared-cache }}
         INPUT_SKIP_ARTIFACT:         ${{ inputs.skip-artifact }}
+        INPUT_XVFB:                  ${{ inputs.xvfb }}
         INPUT_GUEST_CPU:             ${{ inputs.guest-cpu }}
         INPUT_GUEST_MEMORY_MB:       ${{ inputs.guest-memory-mb }}
       run: |
@@ -347,6 +358,7 @@ runs:
         else { $pyArgs += '--use-git-clone' }
         if ($env:INPUT_USE_SHARED_CACHE -eq 'true') { $pyArgs += '--use-shared-cache' }
         if ($env:INPUT_SKIP_ARTIFACT    -eq 'true') { $pyArgs += '--skip-artifact' }
+        if ($env:INPUT_XVFB             -eq 'true') { $pyArgs += '--xvfb' }
         # VMX overrides: forward only when > 0 (0 = keep template value).
         if ([int]($env:INPUT_GUEST_CPU)       -gt 0) { $pyArgs += @('--guest-cpu', $env:INPUT_GUEST_CPU) }
         if ([int]($env:INPUT_GUEST_MEMORY_MB) -gt 0) { $pyArgs += @('--guest-memory-mb', $env:INPUT_GUEST_MEMORY_MB) }