Improve Linux package app store integration

Disable Linux in-app global hotkeys and switch to desktop custom-shortcut command

.github/workflows/build-linux.yml

@@ -33,17 +33,28 @@ jobs:
             libgtk-3-dev \
             libwebkit2gtk-4.1-dev \
             libasound2-dev \
-            libayatana-appindicator3-dev
+            libayatana-appindicator3-dev \
+            dpkg-dev \
+            rpm
 
       - name: Install frontend dependencies
-        run: npm ci
+        run: npm install
         working-directory: frontend
 
       - name: Build app
         run: bash scripts/build-linux.sh --no-install
 
-      - name: Upload binary
+      - name: Package .deb and .rpm
+        run: bash scripts/package-linux.sh
+
+      - name: Upload .deb package
         uses: actions/upload-artifact@v4
         with:
-          name: wis-free-v3-linux-amd64
+          name: wis-free-v3-linux-deb
-          path: build/bin/wis-free-v3
+          path: dist/packages/*.deb
+
+      - name: Upload .rpm package
+        uses: actions/upload-artifact@v4
+        with:
+          name: wis-free-v3-linux-rpm
+          path: dist/packages/*.rpm

README.md

@@ -31,7 +31,9 @@ Install the RPM with the distribution package manager:
 sudo dnf install ./wis-free-v3-<version>-1.x86_64.rpm
 ```
 
-For openSUSE, use `sudo zypper install ./wis-free-v3-<version>.x86_64.rpm`.
+Uninstall it from a terminal with `sudo dnf remove wis-free-v3`. The RPM also ships desktop and AppStream metadata so graphical software centers such as GNOME Software can show the package as an app and offer install/uninstall actions for the local RPM.
+
+For openSUSE, use `sudo zypper install ./wis-free-v3-<version>.x86_64.rpm` and `sudo zypper remove wis-free-v3`.
 
 After installing, launch **WIS Free V3** from the application launcher or run `wis-free-v3` in a terminal. A reboot is not required.
 
@@ -39,17 +41,13 @@ After installing, launch **WIS Free V3** from the application launcher or run `w
 
 ### Global shortcut
 
-On current GNOME, KDE Plasma, and other desktops that implement the XDG GlobalShortcuts portal, set the shortcut in WIS Free V3 Settings. The desktop may ask you to approve or change the shortcut.
+Linux uses your desktop environment's custom shortcut feature as the primary global shortcut method. Copy the **Linux System Shortcut** command shown in Settings and bind it to your preferred key combination:
-
-If the portal is unavailable on your desktop, use the **Fallback System Shortcut** command shown in Settings:
 
 - GNOME: **Settings -> Keyboard -> Custom Shortcuts**
 - KDE Plasma: **System Settings -> Shortcuts -> Command/URL**
 
 That command toggles recording: one press starts and the next press stops. It is shell-quoted automatically, including when the app is installed in a path containing spaces. It also works from a cold start because it uses `--action=toggle`.
 
-Set `WISFREE_USE_PORTAL_HOTKEY=0` before launching the app only to deliberately disable portal shortcuts and use the fallback command instead.
-
 ### Direct typing with ydotool
 
 WIS Free V3 uses `ydotool` to type transcriptions into the active application. This works on both Wayland and X11, but it needs the persistent `ydotoold` service.
@@ -156,7 +154,7 @@ With no flag, the script builds both formats and therefore requires both `dpkg-d
 | Symptom | What to check |
 | --- | --- |
 | The package installed but the app will not launch | Install it with `apt install ./file.deb` or `dnf install ./file.rpm` so runtime libraries are resolved. Launch `wis-free-v3` from a terminal once to see any loader error. |
-| The shortcut does nothing | Configure the portal shortcut in Settings. If your desktop rejects it, use the fallback command displayed there. |
+| The shortcut does nothing | Copy the Linux System Shortcut command from Settings and bind it in your desktop's custom shortcut settings. |
 | Transcription completes but text is not inserted | Open Settings and complete the ydotool setup. Check `systemctl --user status ydotool.service`. |
 | `ydotoold socket not found` | Enable the user service, then log out/in once only if the service still cannot access `/dev/uinput`. |
 | The app runs but no tray icon appears on GNOME | Install and enable the AppIndicator extension. |

app.go

@@ -25,19 +25,19 @@ import (
 
 // App struct
 type App struct {
-	ctx              context.Context
+	ctx             context.Context
-	audioRecorder    *recorder.AudioRecorder
+	audioRecorder   *recorder.AudioRecorder
-	hotkeyListener   *hotkey.Listener
+	hotkeyListener  *hotkey.Listener
-	transcriber      *transcriber.Client
+	transcriber     *transcriber.Client
-	config           *config.Config
+	config          *config.Config
-	overlay          platform.Overlay
+	overlay         platform.Overlay
-	recordingPath    string
+	recordingPath   string
-	recording        int32
+	recording       int32
-	isQuitting       bool
+	isQuitting      bool
-	wasMediaPlaying  bool
+	wasMediaPlaying bool
-	whisperManager   *whisper.Manager
+	whisperManager  *whisper.Manager
-	tempDir          string
+	tempDir         string
-	transcribing     int32 // atomic: 1 = transcription in progress, prevents concurrent
+	transcribing    int32 // atomic: 1 = transcription in progress, prevents concurrent
 }
 
 // NewApp creates a new App application struct
@@ -468,29 +468,25 @@ func (a *App) SaveSettings(settings map[string]interface{}) string {
 		}
 	}
 	if val, ok := settings["shortcut"].(string); ok {
-		_, _, modOnly, ok := hotkey.ParseShortcut(val)
+		if runtime.GOOS == "linux" {
-		if !ok {
+			logger.Info("Ignoring in-app shortcut recording on Linux; use the desktop custom-shortcut command shown in Settings")
-			logger.Error("Invalid shortcut: %s (rejected)", val)
-			return "Invalid shortcut - use modifiers plus a key (e.g. ctrl+k), or modifier-only on Windows (e.g. ctrl+win)"
-		}
-		if modOnly && runtime.GOOS != "windows" {
-			return "Modifier-only shortcuts (like ctrl+win) are only supported on Windows"
-		}
-
-		a.config.Shortcut = val
-		// Hot-swap the listener on every platform. Linux uses the XDG
-		// GlobalShortcuts portal when the desktop implements it and otherwise
-		// exposes the custom-command fallback in Settings.
-		if a.hotkeyListener != nil {
-			a.hotkeyListener.UpdateShortcut(val)
 		} else {
-			a.hotkeyListener = hotkey.NewListener(val, a.StartRecording, a.StopRecording)
+			_, _, modOnly, ok := hotkey.ParseShortcut(val)
-			if runtime.GOOS != "windows" {
+			if !ok {
-				a.hotkeyListener.SetRegistrationErrorCallback(func(err error) {
+				logger.Error("Invalid shortcut: %s (rejected)", val)
-					logger.Error("Linux hotkey registration failed: %v", err)
+				return "Invalid shortcut - use modifiers plus a key (e.g. ctrl+k), or modifier-only on Windows (e.g. ctrl+win)"
-				})
+			}
+			if modOnly && runtime.GOOS != "windows" {
+				return "Modifier-only shortcuts (like ctrl+win) are only supported on Windows"
+			}
+
+			a.config.Shortcut = val
+			if a.hotkeyListener != nil {
+				a.hotkeyListener.UpdateShortcut(val)
+			} else {
+				a.hotkeyListener = hotkey.NewListener(val, a.StartRecording, a.StopRecording)
+				a.hotkeyListener.Start()
 			}
-			a.hotkeyListener.Start()
 		}
 	}
 	if val, ok := settings["whisper_model"].(string); ok {
@@ -644,28 +640,19 @@ func (a *App) startupHeadless() {
 		}
 	}
 
-	// Ensure desktop integration for Wayland portals
+	// Ensure desktop integration for Linux custom shortcuts and tray metadata.
 	if err := platform.EnsureDesktopFile(tray.DefaultIconBytes()); err != nil {
 		logger.Error("Failed to ensure desktop file: %v", err)
 	}
 
-	// Initialize Hotkey Listener
+	// Linux uses the desktop custom-shortcut command shown in Settings instead
-	if shouldStartBuiltInHotkeyListener() {
+	// of an in-app global hotkey backend. Other platforms keep their native
+	// listeners.
+	if runtime.GOOS != "linux" {
 		a.hotkeyListener = hotkey.NewListener(a.config.Shortcut, a.StartRecording, a.StopRecording)
-		if runtime.GOOS != "windows" {
-			a.hotkeyListener.SetRegistrationErrorCallback(func(err error) {
-				logger.Error("Linux hotkey registration failed: %v", err)
-				go func() {
-					time.Sleep(2 * time.Second)
-					if a.overlay != nil {
-						a.overlay.Show("Shortcut registration failed. Add a custom system shortcut with the command shown in Settings.")
-					}
-				}()
-			})
-		}
 		a.hotkeyListener.Start()
 	} else {
-		logger.Info("Linux portal hotkey disabled; use the command shown in Settings for a desktop shortcut")
+		logger.Info("Linux shortcut setup uses the command shown in Settings; configure it in GNOME/KDE custom shortcuts")
 	}
 
 	logger.Info("Components initialized successfully!")
@@ -673,16 +660,6 @@ func (a *App) startupHeadless() {
 	logger.Info("Basic app components loaded, continuing startup...")
 }
 
-func shouldStartBuiltInHotkeyListener() bool {
-	if runtime.GOOS != "linux" {
-		return true
-	}
-	// The portal is the safest cross-desktop implementation on modern Linux.
-	// WISFREE_USE_PORTAL_HOTKEY=0 remains an escape hatch for desktops with a
-	// broken portal; Settings always provides a custom-shortcut fallback.
-	return os.Getenv("WISFREE_USE_PORTAL_HOTKEY") != "0"
-}
-
 // Shutdown cleans up resources
 func (a *App) Shutdown(ctx context.Context) {
 	if a.hotkeyListener != nil {

frontend/index.html

@@ -39,7 +39,7 @@
                 <p class="hint">Get your free key at <a href="#" onclick="window.runtime.BrowserOpenURL('https://console.groq.com/keys'); return false;" style="color: var(--accent);">console.groq.com/keys</a></p>
             </div>
 
-            <!-- Global Hotkey -->
+            <!-- Global Hotkey (hidden on Linux because Linux uses the system shortcut command below) -->
             <div class="section" id="shortcutSection">
                 <label>Global Hotkey</label>
                 <div class="form-control">
@@ -50,26 +50,33 @@
                         <button id="recordBtn" onclick="recordShortcut()">Record</button>
                     </div>
                 </div>
-                <p class="hint">Uses the desktop GlobalShortcuts portal when available. Press the key combination you want to use to start/stop recording (e.g. alt+z, ctrl+shift+space). Modifier-only combos like ctrl+alt are supported only on Windows.</p>
+                <p class="hint">Windows and macOS can listen for this shortcut directly. Modifier-only combos like ctrl+alt are supported only on Windows.</p>
             </div>
 
             <div class="section-group-label">Input</div>
 
-            <!-- Linux fallback shortcut command -->
+            <!-- Linux ydotool status / Direct typing setup -->
-            <div class="section" id="linuxPressSection" style="display: none;">
+            <div class="section" id="linuxYdotoolSection" style="display: none;">
-                <label>Fallback System Shortcut (Linux)</label>
+                <label>Direct Typing (ydotool)</label>
-                <div class="form-control">
+                <div id="linuxYdotoolStatus"></div>
-                    <div class="flex-row">
+            </div>
-                        <div class="input-wrapper">
+
-                            <input type="text" id="linuxPressCommand" readonly>
+            <!-- Linux system shortcut command (collapsible) -->
+            <div class="section" id="linuxFallbackSection" style="display: none;">
+                <details class="fallback-details">
+                    <summary class="fallback-summary">Linux System Shortcut</summary>
+                    <p class="hint" style="margin-top: 12px;">This is the main Linux shortcut method. Copy this command into your desktop's custom shortcut settings. One press starts recording, and the next press stops.</p>
+                    <div class="form-control" style="margin-top: 12px;">
+                        <div class="flex-row">
+                            <div class="input-wrapper">
+                                <input type="text" id="linuxPressCommand" readonly>
+                            </div>
+                            <button onclick="copyLinuxPressCommand()">Copy</button>
                         </div>
-                        <button onclick="copyLinuxPressCommand()">Copy</button>
                     </div>
-                </div>
+                    <p class="hint" style="margin-top: 10px;">GNOME: Settings → Keyboard → Custom Shortcuts → Add a shortcut with the copied command.</p>
-                <p class="hint">Use this if your desktop does not support the GlobalShortcuts portal. The command toggles recording: one press starts, the next stops.</p>
+                    <p class="hint">KDE: System Settings → Shortcuts → Command/URL → Add a shortcut with the copied command.</p>
-                <p class="hint">GNOME: Settings -> Keyboard -> Custom Shortcuts -> Add a shortcut with the copied command.</p>
+                </details>
-                <p class="hint">KDE: System Settings -> Shortcuts -> Command/URL -> Add a shortcut with the copied command.</p>
-                <div id="linuxYdotoolStatus" style="display: none; margin-top: 12px; padding: 10px 12px; border-radius: 7px; font-size: 12px; line-height: 1.45;"></div>
             </div>
 
             <!-- Microphone -->
@@ -202,6 +209,7 @@
 
     <script type="module">
         let apiKeyVisible = false;
+        let linuxShortcutMode = false;
 
         // Toggle API key visibility
         window.toggleApiKey = function () {
@@ -214,6 +222,10 @@
 
         // Record shortcut
         window.recordShortcut = function () {
+            if (linuxShortcutMode) {
+                return;
+            }
+
             const btn = document.getElementById('recordBtn');
             const input = document.getElementById('shortcutInput');
 
@@ -390,11 +402,26 @@
                 if (shortcutInput) {
                     shortcutInput.value = settings.shortcut || 'alt+z';
                 }
+                linuxShortcutMode = !!settings.linux_press_mode;
                 if (settings.linux_press_mode) {
-                    const section = document.getElementById('linuxPressSection');
+                    const shortcutSection = document.getElementById('shortcutSection');
+                    const ydotoolSection = document.getElementById('linuxYdotoolSection');
+                    const fallbackSection = document.getElementById('linuxFallbackSection');
                     const cmdInput = document.getElementById('linuxPressCommand');
-                    if (section) section.style.display = 'block';
+
-                    if (cmdInput) cmdInput.value = settings.linux_press_command || '';
+                    if (shortcutSection) shortcutSection.style.display = 'none';
+                    if (ydotoolSection) ydotoolSection.style.display = 'block';
+                    if (fallbackSection) fallbackSection.style.display = 'block';
+
+                    if (cmdInput) {
+                        // Show just the executable name with quotes and the toggle flag
+                        const fullCommand = settings.linux_press_command || '';
+                        const match = fullCommand.match(/^'[^']*' (--action=toggle)$/);
+                        const togglePart = match ? "'wisp-open' " + match[1] : "'wisp-open' --action=toggle";
+                        cmdInput.value = togglePart;
+                        window._linuxFullCommand = togglePart;
+                    }
+
                     renderLinuxYdotoolStatus(settings.linux_ydotool_status);
                 }
                 document.getElementById('whisperModel').value = settings.whisper_model || 'whisper-large-v3-turbo';
@@ -474,7 +501,8 @@
             const cmdInput = document.getElementById('linuxPressCommand');
             if (!cmdInput) return;
 
-            const command = cmdInput.value || '';
+            // Reconstruct the full command from the backend settings
+            const command = window._linuxFullCommand || cmdInput.value || '';
             try {
                 if (navigator.clipboard && navigator.clipboard.writeText) {
                     await navigator.clipboard.writeText(command);

frontend/src/main.js

@@ -3,6 +3,7 @@
 // Global state
 let currentSettings = {};
 let apiKeyVisible = true;
+let linuxShortcutMode = false;
 
 // Initialize
 document.addEventListener('DOMContentLoaded', async () => {
@@ -29,9 +30,12 @@ async function loadSettings() {
         document.getElementById('aiPrompt').value = settings.ai_prompt || '';
         document.getElementById('startupToggle').checked = settings.startup || false;
 
+        linuxShortcutMode = !!settings.linux_press_mode;
         if (settings.linux_press_mode) {
-            const section = document.getElementById('linuxPressSection');
+            const shortcutSection = document.getElementById('shortcutSection');
+            const section = document.getElementById('linuxPressSection') || document.getElementById('linuxFallbackSection');
             const cmdInput = document.getElementById('linuxPressCommand');
+            if (shortcutSection) shortcutSection.style.display = 'none';
             if (section) section.style.display = 'block';
             if (cmdInput) cmdInput.value = settings.linux_press_command || '';
         }

frontend/src/style.css

@@ -342,6 +342,44 @@ button:active {
 
 
 
+/* ── Collapsible fallback details ── */
+.fallback-details {
+    color: var(--text);
+}
+
+.fallback-summary {
+    cursor: pointer;
+    font-weight: 500;
+    font-size: 13px;
+    color: var(--text-2);
+    padding: 2px 0;
+    user-select: none;
+    list-style: none;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+}
+
+.fallback-summary::-webkit-details-marker {
+    display: none;
+}
+
+.fallback-summary::before {
+    content: '▶';
+    font-size: 10px;
+    color: var(--text-3);
+    transition: transform 0.15s ease;
+    display: inline-block;
+}
+
+.fallback-details[open] > .fallback-summary::before {
+    transform: rotate(90deg);
+}
+
+.fallback-summary:hover {
+    color: var(--text);
+}
+
 /* ── Section group header divider ── */
 .section-group-label {
     font-size: 11px;

go.mod

@@ -6,7 +6,6 @@ require (
 	github.com/gen2brain/malgo v0.11.24
 	github.com/getlantern/systray v1.2.2
 	github.com/go-vgo/robotgo v0.110.8
-	github.com/godbus/dbus/v5 v5.1.0
 	github.com/wailsapp/wails/v2 v2.11.0
 	golang.design/x/mainthread v0.3.0
 	golang.org/x/sys v0.33.0

go.sum

@@ -34,8 +34,6 @@ github.com/go-stack/stack v1.8.0 h1:5SgMzNM5HxrEjV0ww2lTmX6E2Izsfxas4+YHWRs3Lsk=
 github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
 github.com/go-vgo/robotgo v0.110.8 h1:tWoUyqlZgDJ61bQju3WGSb/NIIfNV4TkYL3GFeWcHio=
 github.com/go-vgo/robotgo v0.110.8/go.mod h1:45w33PzprtFncpw4cAt9SzMtSY9XnVfotu+RrCVN8JE=
-github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
-github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=

internal/xhotkey/hotkey_linux.go

@@ -5,16 +5,15 @@ package hotkey
 import "errors"
 
 func (hk *Hotkey) register() error {
-	return hk.registerPortal()
+	return errors.New("Linux in-app global hotkeys are disabled; use the desktop custom-shortcut command shown in Settings")
 }
 
 func (hk *Hotkey) unregister() error {
 	hk.mu.Lock()
+	defer hk.mu.Unlock()
 	if !hk.registered {
-		hk.mu.Unlock()
 		return errors.New("hotkey is not registered.")
 	}
 	hk.registered = false
-	hk.mu.Unlock()
+	return nil
-	return hk.cleanupPortal()
 }

internal/xhotkey/hotkey_linux_platform.go

@@ -2,25 +2,9 @@
 
 package hotkey
 
-import (
+import "sync"
-	"sync"
-
-	"github.com/godbus/dbus/v5"
-)
-
-const (
-	linuxHKNone = iota
-	linuxHKPortal
-)
 
 type platformHotkey struct {
 	mu         sync.Mutex
 	registered bool
-	backend    int
-
-	// Wayland / XDG portal global shortcuts
-	portalStop  chan struct{}
-	portalDone  chan struct{}
-	portalConn  *dbus.Conn
-	sessionPath dbus.ObjectPath
 }

internal/xhotkey/hotkey_linux_portal.go

@@ -1,471 +0,0 @@
-//go:build linux
-
-// ============================================================
-// LINUX-ONLY FILE — Portal-based global hotkey implementation
-// for Linux using the org.freedesktop.portal.GlobalShortcuts
-// D-Bus API (Wayland/desktop-agnostic).
-// The Windows equivalent is in hotkey_windows.go
-// ============================================================
-
-package hotkey
-
-import (
-	"crypto/rand"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"os"
-	"strings"
-	"time"
-
-	"github.com/godbus/dbus/v5"
-	"wis-free-v3/internal/logger"
-)
-
-func unwrapVariant(val interface{}) interface{} {
-	for {
-		if v, ok := val.(dbus.Variant); ok {
-			val = v.Value()
-		} else {
-			break
-		}
-	}
-	return val
-}
-
-const (
-	portalBusName                    = "org.freedesktop.portal.Desktop"
-	portalObjectPath                 = "/org/freedesktop/portal/desktop"
-	ifaceGlobalShortcuts             = "org.freedesktop.portal.GlobalShortcuts"
-	ifaceRequest                     = "org.freedesktop.portal.Request"
-	ifaceSession                     = "org.freedesktop.portal.Session"
-	wisfreeGlobalShortcutID          = "com.wisfree.push-to-record"
-	envForcePortal                   = "WISFREE_USE_PORTAL_HOTKEY"
-)
-
-func usePortalBackend() bool {
-	if os.Getenv(envForcePortal) == "0" {
-		return false
-	}
-	return true
-}
-
-func randomPortalToken() string {
-	b := make([]byte, 8)
-	if _, err := rand.Read(b); err != nil {
-		return "tok" + fmt.Sprintf("%d", time.Now().UnixNano())
-	}
-	return hex.EncodeToString(b)
-}
-
-func triggerForPortalSpec(mods []Modifier, key Key) string {
-	var ctrl, shift, alt, super bool
-	for _, m := range mods {
-		switch m {
-		case ModCtrl:
-			ctrl = true
-		case ModShift:
-			shift = true
-		case Mod1:
-			alt = true
-		case Mod4:
-			super = true
-		}
-	}
-	keyName := portalKeySpecName(key)
-	if keyName == "" {
-		return ""
-	}
-	var parts []string
-	if ctrl {
-		parts = append(parts, "Control")
-	}
-	if alt {
-		parts = append(parts, "Alt")
-	}
-	if shift {
-		parts = append(parts, "Shift")
-	}
-	if super {
-		parts = append(parts, "Super")
-	}
-	if len(parts) == 0 {
-		return keyName
-	}
-	return strings.Join(parts, "+") + "+" + keyName
-}
-
-func portalKeySpecName(key Key) string {
-	if key >= KeyA && key <= KeyZ {
-		return string(rune(key))
-	}
-	if key >= Key0 && key <= Key9 {
-		return string(rune(key))
-	}
-	switch key {
-	case KeySpace:
-		return "Space"
-	case KeyReturn:
-		return "Return"
-	case KeyEscape:
-		return "Escape"
-	case KeyDelete:
-		return "Delete"
-	case KeyTab:
-		return "Tab"
-	case KeyLeft:
-		return "Left"
-	case KeyRight:
-		return "Right"
-	case KeyUp:
-		return "Up"
-	case KeyDown:
-		return "Down"
-	case KeyF1:
-		return "F1"
-	case KeyF2:
-		return "F2"
-	case KeyF3:
-		return "F3"
-	case KeyF4:
-		return "F4"
-	case KeyF5:
-		return "F5"
-	case KeyF6:
-		return "F6"
-	case KeyF7:
-		return "F7"
-	case KeyF8:
-		return "F8"
-	case KeyF9:
-		return "F9"
-	case KeyF10:
-		return "F10"
-	case KeyF11:
-		return "F11"
-	case KeyF12:
-		return "F12"
-	default:
-		return ""
-	}
-}
-
-func portalWaitRequest(conn *dbus.Conn, reqPath dbus.ObjectPath) (uint32, map[string]dbus.Variant, error) {
-	ch := make(chan *dbus.Signal, 8)
-	conn.Signal(ch)
-	defer conn.RemoveSignal(ch)
-	rule := fmt.Sprintf(
-		"type='signal',path='%s',interface='%s',member='Response'",
-		string(reqPath), ifaceRequest,
-	)
-	if err := conn.BusObject().Call("org.freedesktop.DBus.AddMatch", 0, rule).Store(); err != nil {
-		return 0, nil, err
-	}
-	defer func() {
-		_ = conn.BusObject().Call("org.freedesktop.DBus.RemoveMatch", 0, rule).Store()
-	}()
-
-	timeout := time.NewTimer(45 * time.Second)
-	defer timeout.Stop()
-
-	for {
-		select {
-		case sig := <-ch:
-			if sig == nil || sig.Path != reqPath {
-				continue
-			}
-			if !strings.HasSuffix(sig.Name, ".Response") {
-				continue
-			}
-			if len(sig.Body) < 2 {
-				continue
-			}
-			rawCode := unwrapVariant(sig.Body[0])
-			var code uint32
-			switch x := rawCode.(type) {
-			case uint32:
-				code = x
-			case int:
-				code = uint32(x)
-			case int32:
-				code = uint32(x)
-			case uint8:
-				code = uint32(x)
-			default:
-				continue
-			}
-			rawResults := unwrapVariant(sig.Body[1])
-			var results map[string]dbus.Variant
-			switch resMap := rawResults.(type) {
-			case map[string]dbus.Variant:
-				results = resMap
-			case map[string]interface{}:
-				results = make(map[string]dbus.Variant)
-				for k, val := range resMap {
-					results[k] = dbus.MakeVariant(val)
-				}
-			}
-			return code, results, nil
-		case <-timeout.C:
-			return 0, nil, fmt.Errorf("portal request timed out")
-		}
-	}
-}
-
-func variantToObjectPath(v dbus.Variant) (dbus.ObjectPath, bool) {
-	val := unwrapVariant(v)
-	switch x := val.(type) {
-	case dbus.ObjectPath:
-		return x, true
-	case string:
-		return dbus.ObjectPath(x), true
-	default:
-		return "", false
-	}
-}
-
-// registerPortal binds a global shortcut via org.freedesktop.portal.GlobalShortcuts (Wayland / desktop-agnostic).
-func (hk *Hotkey) registerPortal() error {
-	trigger := triggerForPortalSpec(hk.mods, hk.key)
-	if trigger == "" {
-		return fmt.Errorf("unsupported key for portal global shortcuts")
-	}
-
-	conn, err := dbus.SessionBus()
-	if err != nil {
-		return fmt.Errorf("dbus session: %w", err)
-	}
-
-	portal := conn.Object(portalBusName, portalObjectPath)
-
-	createOpts := map[string]dbus.Variant{
-		"handle_token":         dbus.MakeVariant(randomPortalToken()),
-		"session_handle_token": dbus.MakeVariant(randomPortalToken()),
-		// Required by xdg-desktop-portal on some desktops (e.g. Fedora/GNOME).
-		// This should match the app's .desktop file id when possible.
-		"app_id": dbus.MakeVariant("wis-free-v3"),
-	}
-
-	var createReqPath dbus.ObjectPath
-	if err := portal.Call(ifaceGlobalShortcuts+".CreateSession", 0, createOpts).Store(&createReqPath); err != nil {
-		_ = conn.Close()
-		return fmt.Errorf("CreateSession: %w", err)
-	}
-
-	code, results, err := portalWaitRequest(conn, createReqPath)
-	if err != nil {
-		_ = conn.Close()
-		return fmt.Errorf("CreateSession wait: %w", err)
-	}
-	if code != 0 {
-		_ = conn.Close()
-		return fmt.Errorf("CreateSession rejected (code %d)", code)
-	}
-	v, ok := results["session_handle"]
-	if !ok {
-		_ = conn.Close()
-		return errors.New("CreateSession: missing session_handle")
-	}
-	sessPath, okp := variantToObjectPath(v)
-	if !okp || sessPath == "" {
-		_ = conn.Close()
-		return errors.New("CreateSession: invalid session_handle")
-	}
-
-	type portalShortcut struct {
-		ID      string
-		Details map[string]dbus.Variant
-	}
-	shortcutsArg := []portalShortcut{
-		{
-			ID: wisfreeGlobalShortcutID,
-			Details: map[string]dbus.Variant{
-				"description":       dbus.MakeVariant("Hold to dictate; release to transcribe (WIS Free)"),
-				"preferred_trigger": dbus.MakeVariant(trigger),
-			},
-		},
-	}
-
-	bindOpts := map[string]dbus.Variant{
-		"handle_token": dbus.MakeVariant(randomPortalToken()),
-	}
-
-	var bindReqPath dbus.ObjectPath
-	if err := portal.Call(ifaceGlobalShortcuts+".BindShortcuts", 0, sessPath, shortcutsArg, "", bindOpts).Store(&bindReqPath); err != nil {
-		_ = conn.Object(portalBusName, sessPath).Call(ifaceSession+".Close", 0).Store()
-		_ = conn.Close()
-		return fmt.Errorf("BindShortcuts: %w", err)
-	}
-
-	code, results, err = portalWaitRequest(conn, bindReqPath)
-	if err != nil {
-		_ = conn.Object(portalBusName, sessPath).Call(ifaceSession+".Close", 0).Store()
-		_ = conn.Close()
-		return err
-	}
-	if code != 0 {
-		_ = conn.Object(portalBusName, sessPath).Call(ifaceSession+".Close", 0).Store()
-		_ = conn.Close()
-		return fmt.Errorf("BindShortcuts rejected (code %d); install a desktop with GlobalShortcuts portal support (e.g. recent KDE Plasma or GNOME)", code)
-	}
-	if sc, ok := results["shortcuts"]; ok {
-		val := sc.Value()
-		isEmpty := false
-		switch v := val.(type) {
-		case []interface{}:
-			isEmpty = len(v) == 0
-		case [][]interface{}:
-			isEmpty = len(v) == 0
-		case []map[string]interface{}:
-			isEmpty = len(v) == 0
-		}
-		if isEmpty {
-			_ = conn.Object(portalBusName, sessPath).Call(ifaceSession+".Close", 0).Store()
-			_ = conn.Close()
-			return fmt.Errorf("BindShortcuts returned empty shortcut list (desktop declined the binding)")
-		}
-	}
-
-	hk.mu.Lock()
-	if hk.registered {
-		hk.mu.Unlock()
-		_ = conn.Object(portalBusName, sessPath).Call(ifaceSession+".Close", 0).Store()
-		_ = conn.Close()
-		return errors.New("hotkey already registered.")
-	}
-	hk.backend = linuxHKPortal
-	hk.registered = true
-	hk.portalConn = conn
-	hk.sessionPath = sessPath
-	hk.portalStop = make(chan struct{})
-	hk.portalDone = make(chan struct{})
-	hk.mu.Unlock()
-
-	go hk.portalSignalLoop()
-	return nil
-}
-
-func (hk *Hotkey) sendPortalEvent(name string, ch chan<- Event) {
-	hk.mu.Lock()
-	stopCh := hk.portalStop
-	registered := hk.registered
-	hk.mu.Unlock()
-	if !registered || stopCh == nil {
-		return
-	}
-
-	defer func() {
-		if r := recover(); r != nil {
-			logger.Debug("sendPortalEvent(%s): recovered from panic: %v", name, r)
-		}
-	}()
-
-	select {
-	case ch <- Event{}:
-	case <-stopCh:
-	case <-time.After(2 * time.Second):
-		logger.Error("Timed out delivering Linux portal hotkey %s event", name)
-	}
-}
-
-// safeSendKeydown sends a keydown event to the hotkey channel.
-func (hk *Hotkey) safeSendKeydown() {
-	hk.sendPortalEvent("keydown", hk.keydownIn)
-}
-
-// safeSendKeyup sends a keyup event to the hotkey channel.
-func (hk *Hotkey) safeSendKeyup() {
-	hk.sendPortalEvent("keyup", hk.keyupIn)
-}
-
-func (hk *Hotkey) portalSignalLoop() {
-	defer close(hk.portalDone)
-
-	hk.mu.Lock()
-	conn := hk.portalConn
-	hk.mu.Unlock()
-	if conn == nil {
-		return
-	}
-
-	ch := make(chan *dbus.Signal, 32)
-	conn.Signal(ch)
-	defer conn.RemoveSignal(ch)
-	
-	rule := fmt.Sprintf(
-		"type='signal',sender='%s',interface='%s'",
-		portalBusName, ifaceGlobalShortcuts,
-	)
-	if err := conn.BusObject().Call("org.freedesktop.DBus.AddMatch", 0, rule).Store(); err != nil {
-		logger.Error("wis-free-v3 hotkey: AddMatch GlobalShortcuts: %v", err)
-		return
-	}
-	defer func() { _ = conn.BusObject().Call("org.freedesktop.DBus.RemoveMatch", 0, rule).Store() }()
-
-	logger.Info("Listening for global shortcut signals (sender=%s, interface=%s)", portalBusName, ifaceGlobalShortcuts)
-
-	for {
-		select {
-		case <-hk.portalStop:
-			return
-		case sig, ok := <-ch:
-			if !ok || sig == nil {
-				return
-			}
-			if len(sig.Body) < 2 {
-				continue
-			}
-
-			// Bypass strict session path checking to avoid mismatch bugs.
-			// The shortcut ID is unique to our application.
-			rawID := unwrapVariant(sig.Body[1])
-			id, ok := rawID.(string)
-			if !ok || id != wisfreeGlobalShortcutID {
-				continue
-			}
-
-			logger.Info("Matched global shortcut signal: name=%s", sig.Name)
-
-			switch sig.Name {
-			case ifaceGlobalShortcuts + ".Activated":
-				hk.safeSendKeydown()
-			case ifaceGlobalShortcuts + ".Deactivated":
-				hk.safeSendKeyup()
-			default:
-				// Fallback for different bus routing names just in case
-				if strings.HasSuffix(sig.Name, ".Activated") {
-					hk.safeSendKeydown()
-				} else if strings.HasSuffix(sig.Name, ".Deactivated") {
-					hk.safeSendKeyup()
-				}
-			}
-		}
-	}
-}
-
-// cleanupPortal stops the portal listener and closes the session (unlock before call).
-func (hk *Hotkey) cleanupPortal() error {
-	hk.mu.Lock()
-	stopCh := hk.portalStop
-	doneCh := hk.portalDone
-	conn := hk.portalConn
-	sess := hk.sessionPath
-	hk.portalStop = nil
-	hk.portalDone = nil
-	hk.portalConn = nil
-	hk.sessionPath = ""
-	hk.backend = linuxHKNone
-	hk.mu.Unlock()
-
-	if stopCh != nil {
-		close(stopCh)
-	}
-	if doneCh != nil {
-		<-doneCh
-	}
-	if conn != nil && sess != "" {
-		_ = conn.Object(portalBusName, sess).Call(ifaceSession+".Close", 0).Store()
-		_ = conn.Close()
-	}
-	return nil
-}

internal/xhotkey/hotkey_linux_test.go

@@ -1,41 +1,21 @@
-// Copyright 2021 The golang.design Initiative Authors.
-// All rights reserved. Use of this source code is governed
-// by a MIT license that can be found in the LICENSE file.
-//
-// Written by Changkun Ou <changkun.de>
-
 //go:build linux && cgo
 
 package hotkey_test
 
 import (
-	"context"
+	"strings"
-	"fmt"
 	"testing"
-	"time"
 
 	"wis-free-v3/internal/xhotkey"
 )
 
-// TestHotkey should always run success.
+func TestHotkeyLinuxUsesDesktopShortcutFallback(t *testing.T) {
-// This is a test to run and for manually testing, registered combination:
+	hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.Mod2, hotkey.Mod4}, hotkey.KeyA)
-// Ctrl+Alt+A (Ctrl+Mod2+Mod4+A on Linux)
+	err := hk.Register()
-func TestHotkey(t *testing.T) {
+	if err == nil {
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		t.Fatal("expected Linux in-app hotkey registration to be disabled")
-	defer cancel()
-
-	hk := hotkey.New([]hotkey.Modifier{
-		hotkey.ModCtrl, hotkey.Mod2, hotkey.Mod4}, hotkey.KeyA)
-	if err := hk.Register(); err != nil {
-		t.Errorf("failed to register hotkey: %v", err)
-		return
 	}
-	for {
+	if !strings.Contains(err.Error(), "desktop custom-shortcut command") {
-		select {
+		t.Fatalf("expected desktop shortcut fallback error, got %v", err)
-		case <-ctx.Done():
-			return
-		case <-hk.Keydown():
-			fmt.Println("triggered")
-		}
 	}
 }

internal/xhotkey/hotkey_linux_types.go

@@ -2,7 +2,7 @@
 
 package hotkey
 
-// Modifier represents a modifier (X11 bitmask; also used when mapping to portal shortcut spec).
+// Modifier represents a modifier (X11 bitmask value used by non-Linux native backends and shortcut parsing).
 type Modifier uint32
 
 // See /usr/include/X11/X.h

internal/xhotkey/hotkey_nocgo_test.go

@@ -14,7 +14,7 @@ import (
 	"wis-free-v3/internal/xhotkey"
 )
 
-// Without CGO on Darwin, registration is unsupported (panic). Linux without CGO uses the portal backend instead.
+// Without CGO on Darwin, registration is unsupported (panic). Linux without CGO returns the Linux unsupported-backend error.
 func TestHotkey(t *testing.T) {
 	defer func() {
 		if r := recover(); r != nil {

scripts/build-linux.sh

@@ -351,8 +351,8 @@ if [ $MISSING_DEPS -eq 1 ]; then
     echo ""
     echo "It looks like you are missing some required libraries."
     echo ""
-    echo "Wayland note: global hotkeys use the XDG GlobalShortcuts portal (xdg-desktop-portal"
+    echo "Wayland note: Linux global shortcuts use your desktop's custom shortcut settings"
-    echo "with a supporting compositor, e.g. KDE Plasma or GNOME)."
+    echo "with the command shown in the app Settings window."
     echo ""
     
     DEBIAN_DEPS="build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev libasound2-dev libayatana-appindicator3-dev"
@@ -363,7 +363,7 @@ if [ $MISSING_DEPS -eq 1 ]; then
     FEDORA_DEPS="gcc gcc-c++ make pkgconf-pkg-config gtk3-devel webkit2gtk4.1-devel alsa-lib-devel libayatana-appindicator-gtk3-devel"
     # Same as FEDORA_DEPS but classic libappindicator (some spins/repos lack Ayatana -devel)
     FEDORA_DEPS_ALT="gcc gcc-c++ make pkgconf-pkg-config gtk3-devel webkit2gtk4.1-devel alsa-lib-devel libappindicator-gtk3-devel"
-    FEDORA_RUNTIME_OPT="playerctl xdg-desktop-portal ydotool"
+    FEDORA_RUNTIME_OPT="playerctl ydotool"
     ARCH_DEPS="base-devel pkgconf gtk3 webkit2gtk alsa-lib libayatana-appindicator"
     ARCH_RUNTIME_OPT="playerctl ydotool"
     

scripts/package-linux.sh

@@ -196,6 +196,7 @@ rm -rf "$WORK_DIR"
 mkdir -p "$WORK_DIR/root/usr/bin"
 mkdir -p "$WORK_DIR/root/usr/share/applications"
 mkdir -p "$WORK_DIR/root/usr/share/pixmaps"
+mkdir -p "$WORK_DIR/root/usr/share/metainfo"
 mkdir -p "$WORK_DIR/root/usr/share/doc/$APP_NAME"
 mkdir -p "$DIST_DIR"
 
@@ -221,6 +222,32 @@ Icon=$APP_NAME
 StartupWMClass=$APP_NAME
 Terminal=false
 Categories=Utility;Audio;
+Keywords=dictation;speech;voice;transcription;whisper;
+EOF
+
+cat > "$WORK_DIR/root/usr/share/metainfo/$APP_NAME.metainfo.xml" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>$APP_NAME.desktop</id>
+  <metadata_license>MIT</metadata_license>
+  <project_license>$LICENSE</project_license>
+  <name>$DISPLAY_NAME</name>
+  <summary>$COMMENT</summary>
+  <description>
+    <p>WIS Free V3 is a desktop voice dictation app built with Go and Wails.</p>
+    <p>It records audio from a global shortcut, transcribes it, optionally refines the text, and types the result into the focused application.</p>
+  </description>
+  <launchable type="desktop-id">$APP_NAME.desktop</launchable>
+  <provides>
+    <binary>$APP_NAME</binary>
+  </provides>
+  <categories>
+    <category>Utility</category>
+    <category>Audio</category>
+  </categories>
+  <content_rating type="oars-1.1" />
+  <url type="homepage">https://github.com/Daishir0/wisp-open</url>
+</component>
 EOF
 
 if [ -f README.md ]; then
@@ -250,6 +277,30 @@ Description: $COMMENT
  On Wayland, install ydotool for direct keyboard injection.
 EOF
 
+cat > "$DEB_ROOT/DEBIAN/postinst" <<'EOF'
+#!/usr/bin/env sh
+set -e
+if command -v update-desktop-database >/dev/null 2>&1; then
+    update-desktop-database /usr/share/applications >/dev/null 2>&1 || true
+fi
+if command -v appstreamcli >/dev/null 2>&1; then
+    appstreamcli refresh-cache --force >/dev/null 2>&1 || true
+fi
+exit 0
+EOF
+cat > "$DEB_ROOT/DEBIAN/postrm" <<'EOF'
+#!/usr/bin/env sh
+set -e
+if command -v update-desktop-database >/dev/null 2>&1; then
+    update-desktop-database /usr/share/applications >/dev/null 2>&1 || true
+fi
+if command -v appstreamcli >/dev/null 2>&1; then
+    appstreamcli refresh-cache --force >/dev/null 2>&1 || true
+fi
+exit 0
+EOF
+chmod 0755 "$DEB_ROOT/DEBIAN/postinst" "$DEB_ROOT/DEBIAN/postrm"
+
 dpkg-deb --build "$DEB_ROOT" "$DIST_DIR/${APP_NAME}_${PKG_VERSION}-${PKG_RELEASE}_${ARCH_DEB}.deb"
 fi
 
@@ -269,7 +320,10 @@ Summary:        $COMMENT
 License:        $LICENSE
 Requires:       gtk3
 Requires:       alsa-lib
+Requires:       webkit2gtk4.1
+Requires:       libayatana-appindicator-gtk3
 Recommends:     ydotool
+Provides:       application() application($APP_NAME.desktop)
 
 %description
 WIS Free V3 is a desktop voice dictation app built with Go and Wails.
@@ -280,10 +334,27 @@ rm -rf %{buildroot}
 mkdir -p %{buildroot}
 cp -a "$RPM_PAYLOAD"/. %{buildroot}/
 
+%post
+if command -v update-desktop-database >/dev/null 2>&1; then
+    update-desktop-database /usr/share/applications >/dev/null 2>&1 || :
+fi
+if command -v appstreamcli >/dev/null 2>&1; then
+    appstreamcli refresh-cache --force >/dev/null 2>&1 || :
+fi
+
+%postun
+if command -v update-desktop-database >/dev/null 2>&1; then
+    update-desktop-database /usr/share/applications >/dev/null 2>&1 || :
+fi
+if command -v appstreamcli >/dev/null 2>&1; then
+    appstreamcli refresh-cache --force >/dev/null 2>&1 || :
+fi
+
 %files
 %attr(0755,root,root) /usr/bin/$APP_NAME
 /usr/share/applications/$APP_NAME.desktop
 /usr/share/pixmaps/$APP_NAME.png
+/usr/share/metainfo/$APP_NAME.metainfo.xml
 /usr/share/doc/$APP_NAME/README.md
 EOF