fix(build): ensure gtk4-layer-shell loads before libwayland-client

- Update CGO_LDFLAGS in build scripts to include gtk4-layer-shell with the correct load order.
- Add a new layershell_link.go file to maintain the dependency on gtk4-layer-shell.
- Modify overlay_gtk.go to clarify the importance of load order for Layer Shell functionality.
- Enhance run.sh to preload gtk4-layer-shell for proper overlay positioning.

scripts/ci/package-release.sh

@@ -32,11 +32,12 @@ mkdir -p -- \
 
 # The Sherpa Go module embeds an absolute build-machine RPATH. Add a portable
 # build-time fallback; the final paths are normalized after dependency copying.
+# gtk4-layer-shell must precede libwayland-client so its Wayland shim installs.
 # shellcheck disable=SC2016 # $ORIGIN must remain literal for the ELF loader.
-CGO_LDFLAGS='-Wl,-rpath,$ORIGIN/lib' \
+CGO_LDFLAGS='-Wl,--no-as-needed -lgtk4-layer-shell -Wl,-rpath,$ORIGIN/lib' \
   go build -trimpath -o "$package_dir/captioneer" ./src/cmd/captioneer
 # shellcheck disable=SC2016 # $ORIGIN must remain literal for the ELF loader.
-CGO_LDFLAGS='-Wl,-rpath,$ORIGIN/lib' \
+CGO_LDFLAGS='-Wl,--no-as-needed -lgtk4-layer-shell -Wl,-rpath,$ORIGIN/lib' \
   go build -trimpath -tags gtk \
     -o "$package_dir/captioneer-desktop" ./src/cmd/captioneer-desktop
 

scripts/distrobox/build.sh

@@ -19,6 +19,9 @@ build_script='set -Eeuo pipefail
 repo_root=$1
 shift
 cd -- "$repo_root"
+# gtk4-layer-shell must precede libwayland-client in the loader order or the
+# Wayland shim never installs and the overlay cannot be positioned.
+export CGO_LDFLAGS="-Wl,--no-as-needed -lgtk4-layer-shell ${CGO_LDFLAGS:-}"
 go build "$@" -o build/captioneer ./src/cmd/captioneer
 go build "$@" -tags gtk -o build/captioneer-desktop ./src/cmd/captioneer-desktop'
 

scripts/distrobox/run.sh

@@ -15,6 +15,13 @@ cd -- "$repo_root"
 # Avoid host/container DMABUF incompatibilities on mismatched GPU stacks. An
 # explicit GTK renderer choice still takes precedence.
 export GSK_RENDERER="${GSK_RENDERER:-cairo}"
+# gtk4-layer-shell must load before libwayland-client or its Wayland shim is
+# skipped and the overlay sits as an unpositioned normal window.
+layer_shell_lib="$(pkg-config --variable=libdir gtk4-layer-shell-0)/libgtk4-layer-shell.so.0"
+if [[ -f "$layer_shell_lib" ]]; then
+  export LD_PRELOAD="${layer_shell_lib}${LD_PRELOAD:+:$LD_PRELOAD}"
+fi
+export CGO_LDFLAGS="-Wl,--no-as-needed -lgtk4-layer-shell ${CGO_LDFLAGS:-}"
 exec go run -tags gtk ./src/cmd/captioneer-desktop "$@"'
 
 exec distrobox enter --no-workdir --name "$container_name" -- \