From 5036e34d3c0b3d121666c10fcf33007f824d4951 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Wed, 16 Sep 2026 08:51:47 -0400
Subject: [PATCH] fix(install): install webkitgtk-6.0 runtime per distro,
 refuse on musl

The release binary dynamically links libwebkitgtk-6.0, which is not preinstalled on most distros and is not shipped in the tarball, so installs failed at first launch with a missing-.so error. Add a step-0 dependency stage to install_linux.sh that maps Arch/Debian-Ubuntu/Fedora/OpenMandriva/Void to their verified runtime package names (ID plus ID_LIKE, so derivatives resolve), requires root/sudo, and stays idempotent. musl systems (Alpine, Void-musl) get a warning plus hard-abort: the glibc-linked binary cannot run there and no package fixes that. Unknown distros get the package table and exit 1. Existing desktop/icons/binary steps untouched. Verified with an 11-case stub harness (all families route correctly; sudo/no-sudo/missing-manager/musl/unknown all behave).
---
 build/install_linux.sh | 94 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/build/install_linux.sh b/build/install_linux.sh
index e192c28..b0d394c 100755
--- a/build/install_linux.sh
+++ b/build/install_linux.sh
@@ -1,4 +1,98 @@
 #!/bin/bash
+set -u
+
+# Step 0: WebKitGTK 6 runtime ...................................................
+# The release binary dynamically links libwebkitgtk-6.0 and libgtk-4, which are
+# not preinstalled on most distros and are not shipped in the tarball. Install
+# them first so the app can start; abort before copying anything otherwise.
+#
+# OS_RELEASE_FILE override exists for testing the distro mapping only.
+
+print_manual_instructions() {
+  cat >&2 <<'EOF'
+Install the WebKitGTK 6 runtime for your distribution, then re-run this script:
+  Arch / Manjaro / EndeavourOS:  sudo pacman -S webkitgtk-6.0
+  Debian / Ubuntu / Mint / Pop:  sudo apt install libwebkitgtk-6.0-4
+  Fedora / Nobara:               sudo dnf install webkitgtk6.0
+  OpenMandriva:                  sudo dnf install lib64webkit2gtk6.0
+  Void (glibc):                  sudo xbps-install -S libwebkitgtk60
+Without it the app fails at launch: error while loading shared libraries: libwebkitgtk-6.0.so.4
+EOF
+}
+
+install_webkit_runtime() {
+  # 0a. musl guard: the prebuilt binary is glibc-linked and cannot run on
+  # musl systems (Alpine, Void-musl). No package fixes that — refuse loudly.
+  if ldd --version 2>&1 | grep -qi musl; then
+    echo "ERROR: AniTrack ships a glibc-linked binary, but this system uses musl libc." >&2
+    echo "The prebuilt release cannot run here. Build from source instead (see README)." >&2
+    return 1
+  fi
+
+  # 0b. Every package manager below needs privilege.
+  local sudo_cmd=""
+  if [ "$(id -u)" -ne 0 ]; then
+    if ! command -v sudo >/dev/null 2>&1; then
+      echo "ERROR: root privileges are required to install system packages," >&2
+      echo "but sudo is not available. Install the WebKitGTK 6 runtime manually:" >&2
+      print_manual_instructions
+      return 1
+    fi
+    sudo_cmd="sudo"
+  fi
+
+  # 0c. Distro mapping. ID_LIKE catches derivatives (Mint/Pop -> ubuntu,
+  # Manjaro/EndeavourOS -> arch, Nobara -> fedora) without enumerating them.
+  local os_release="${OS_RELEASE_FILE:-/etc/os-release}"
+  local dist_id="" dist_like=""
+  if [ -r "$os_release" ]; then
+    # shellcheck disable=SC1090
+    . "$os_release"
+    dist_id="${ID:-}"
+    dist_like="${ID_LIKE:-}"
+  fi
+
+  need_cmd() {
+    command -v "$1" >/dev/null 2>&1
+  }
+
+  local ids=" ${dist_id} ${dist_like} "
+  case "$ids" in
+    *" arch "*|*" manjaro "*|*" endeavouros "*|*" garuda "*|*" cachyos "*)
+      need_cmd pacman || { echo "ERROR: pacman not found on Arch-family system." >&2; return 1; }
+      $sudo_cmd pacman -S --needed --noconfirm webkitgtk-6.0 || return 1
+      ;;
+    *" debian "*|*" ubuntu "*|*" pop "*|*" linuxmint "*)
+      need_cmd apt-get || { echo "ERROR: apt-get not found on Debian-family system." >&2; return 1; }
+      $sudo_cmd apt-get update && $sudo_cmd apt-get install -y libwebkitgtk-6.0-4 || return 1
+      ;;
+    *" fedora "*|*" nobara "*)
+      need_cmd dnf || { echo "ERROR: dnf not found on Fedora-family system." >&2; return 1; }
+      $sudo_cmd dnf install -y webkitgtk6.0 || return 1
+      ;;
+    *" openmandriva "*)
+      need_cmd dnf || { echo "ERROR: dnf not found on OpenMandriva system." >&2; return 1; }
+      $sudo_cmd dnf install -y lib64webkit2gtk6.0 || return 1
+      ;;
+    *" void "*)
+      need_cmd xbps-install || { echo "ERROR: xbps-install not found on Void system." >&2; return 1; }
+      $sudo_cmd xbps-install -Sy libwebkitgtk60 || return 1
+      ;;
+    *" alpine "*)
+      echo "ERROR: Alpine Linux uses musl libc, which the prebuilt glibc-linked binary cannot run on." >&2
+      echo "Build from source instead (see README)." >&2
+      return 1
+      ;;
+    *)
+      echo "ERROR: unsupported or unrecognised distribution (ID='${dist_id}' ID_LIKE='${dist_like}')." >&2
+      print_manual_instructions
+      return 1
+      ;;
+  esac
+  unset -f need_cmd
+}
+
+install_webkit_runtime || exit 1
 
 # copy desktop file
 if [ ! -f "$HOME/.local/share/applications/AniTrack.desktop" ]; then