From f7f2fce4e3be59e0ef01de33f350a81b363e7b43 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 17:04:30 +0000
Subject: [PATCH 01/10] Load styles.css from disk at runtime instead of
 bundling it at build time

Tauri embeds frontendDist into the compiled binary at build time (confirmed
directly: editing the bundled dist/styles.css post-build and relaunching the
same binary had zero effect on rendering), so any styling change previously
needed a full rebuild to take effect -- painful with a Rust/Tauri build on
constrained hardware, and heavy iteration on the stylesheet expected.

New get_custom_css command (main.rs) reads a real file from the app's data
directory (~/.local/share/FT8AF/styles.css on Linux) fresh on every launch,
seeding it from the compiled-in default (public/styles.css, via
include_str!) on first run so there's something to open and edit
immediately. main.tsx now awaits this and injects the result as a <style>
tag instead of a static Vite-bundled import, so editing that file and
relaunching the app picks up changes with no rebuild at all -- same
"resolved live, not baked in at compile time" idea already used for the
Hamlib rig list.

Verified end-to-end with a real screenshot test: launched the built binary,
edited the on-disk styles.css to a loud, unmistakable color with no rebuild,
relaunched the same binary, and confirmed the new color rendered.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/{src => public}/styles.css |  0
 desktop/src-tauri/src/main.rs      | 41 +++++++++++++++++++++++++++---
 desktop/src/main.tsx               | 28 ++++++++++++++++++--
 3 files changed, 64 insertions(+), 5 deletions(-)
 rename desktop/{src => public}/styles.css (100%)

diff --git a/desktop/src/styles.css b/desktop/public/styles.css
similarity index 100%
rename from desktop/src/styles.css
rename to desktop/public/styles.css
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 118b7e372..30f5eff36 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -2,6 +2,7 @@
 // exposes commands to the web UI, and forwards engine events to the webview.
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
+use std::path::PathBuf;
 use std::sync::Arc;
 
 use serde::Serialize;
@@ -191,6 +192,41 @@ fn set_waterfall_config(state: State<AppState>, config: WfConfig) {
     state.engine.send(EngineCommand::SetWaterfallConfig(config));
 }
 
+fn app_data_dir() -> PathBuf {
+    dirs::data_dir()
+        .unwrap_or_else(std::env::temp_dir)
+        .join("FT8AF")
+}
+
+// The compiled-in baseline -- only this constant needs a rebuild to change;
+// everything a user actually edits lives at styles_path() on disk instead.
+const DEFAULT_STYLES_CSS: &str = include_str!("../../public/styles.css");
+
+fn styles_path() -> PathBuf {
+    app_data_dir().join("styles.css")
+}
+
+#[tauri::command]
+fn get_custom_css() -> String {
+    // Read from disk on every call, not from the Vite/Tauri-bundled frontend
+    // -- Tauri embeds frontendDist into the compiled binary at build time
+    // (confirmed directly: editing the bundled dist/styles.css after a build
+    // and relaunching the same binary had zero effect), so anything served
+    // from there needs a full rebuild for every change. This file lives
+    // outside that embed entirely, so editing it just needs an app relaunch
+    // -- the whole point, since this stylesheet is expected to change often.
+    let path = styles_path();
+    match std::fs::read_to_string(&path) {
+        Ok(css) => css,
+        Err(_) => {
+            // First run: seed the file so there's something to open and edit.
+            let _ = std::fs::create_dir_all(app_data_dir());
+            let _ = std::fs::write(&path, DEFAULT_STYLES_CSS);
+            DEFAULT_STYLES_CSS.to_string()
+        }
+    }
+}
+
 fn main() {
     // Debug helper: `ft8af --list-rigs` prints the Hamlib-enumerated rig count
     // and exits — verifies the bundled Hamlib library loads without the GUI.
@@ -203,9 +239,7 @@ fn main() {
         return;
     }
 
-    let data_dir = dirs::data_dir()
-        .unwrap_or_else(std::env::temp_dir)
-        .join("FT8AF");
+    let data_dir = app_data_dir();
     let _ = std::fs::create_dir_all(&data_dir);
     let db = Arc::new(
         Db::open(data_dir.join("ft8af.sqlite")).expect("failed to open database"),
@@ -268,6 +302,7 @@ fn main() {
             set_config,
             all_config,
             set_waterfall_config,
+            get_custom_css,
         ])
         .run(tauri::generate_context!())
         .expect("error running FT8AF");
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 6c2e2f307..485c8937c 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -1,7 +1,31 @@
 import ReactDOM from "react-dom/client";
+import { invoke } from "@tauri-apps/api/core";
 import App from "./App";
-import "./styles.css";
 
 // Note: no React.StrictMode. Its dev-only double mount/unmount double-registers
 // the async Tauri event listener, which duplicated every decode batch.
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(<App />);
+
+// Styles come from a real file on disk (get_custom_css, main.rs), read fresh
+// on every launch -- not a Vite-bundled import. Tauri embeds frontendDist
+// into the compiled binary at build time (confirmed directly: editing
+// dist/styles.css after a build and relaunching the unchanged binary had no
+// effect), so a bundled stylesheet -- even at a stable, unhashed path --
+// would still need a full rebuild for every change. Injecting the fetched
+// CSS as a <style> tag instead means edits to the on-disk file just need an
+// app relaunch, matching how the rig list is resolved live via hamlib rather
+// than baked in. Render waits on this so there's no unstyled flash.
+async function loadCustomStyles() {
+  try {
+    const css = await invoke<string>("get_custom_css");
+    const style = document.createElement("style");
+    style.id = "ft8af-custom-styles";
+    style.textContent = css;
+    document.head.appendChild(style);
+  } catch (e) {
+    console.error("failed to load custom styles:", e);
+  }
+}
+
+loadCustomStyles().finally(() => {
+  ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(<App />);
+});

From 7bb85aab903163484f644496c4070d08cd54a0f8 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 17:08:11 +0000
Subject: [PATCH 02/10] Add Linux launcher wrapper working around a real
 Hamlib/QMX version conflict

rig.rs's load_hamlib() does a bare dlopen("libhamlib.so.4") -- resolved
against whatever the dynamic linker finds first. On this machine that's the
distro-packaged libhamlib.so.4 (Hamlib 4.5.4), which has no QMX support at
all (confirmed: 0/283 rigs listed included QMX, and rig_init failed for
model 2057). A separately-built Hamlib 4.7.1 already exists at
/usr/local/lib/libhamlib.so.4 with QMX support (RIG_MODEL_QRPLABS_QMX
present) -- same soname as the system package, so whichever the linker
resolves first wins for any process that doesn't override the search path.

Not fixed by upgrading the system package: other software on this machine
(CQRLOG) depends on the distro Hamlib specifically. desktop/linux/run-ft8af.sh
instead sets LD_LIBRARY_PATH just for FT8AF's own process, so it
preferentially finds the newer build without touching anything system-wide.
Falls back to the system Hamlib (previous behavior) if no /usr/local build
exists.

Verified end-to-end through the wrapper: rig list jumps from 283 to 321
entries (QRPLabs QMX now included), and the app made a real, live CAT
connection to a physical QMX (kenwood_transaction traffic, frequency set,
54ms round-trip) -- confirmed via screenshot showing "rig: qmx" instead of
"no rig".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/linux/run-ft8af.sh | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100755 desktop/linux/run-ft8af.sh

diff --git a/desktop/linux/run-ft8af.sh b/desktop/linux/run-ft8af.sh
new file mode 100755
index 000000000..87ffe6b1f
--- /dev/null
+++ b/desktop/linux/run-ft8af.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Launcher for FT8AF on Linux, working around a real Hamlib version conflict
+# (see rig.rs's load_hamlib(): a bare dlopen("libhamlib.so.4"), resolved
+# against whatever the dynamic linker finds first).
+#
+# QMX (and other newer rigs) need a newer Hamlib than the distro package
+# usually ships -- confirmed on this machine: the system's
+# libhamlib.so.4 is Hamlib 4.5.4 (no QMX support at all), while
+# /usr/local/lib/libhamlib.so.4 is a separately-built Hamlib 4.7.1 that does
+# have it. Both share the same soname, so whichever the linker resolves
+# first wins for any process that doesn't override the search path.
+#
+# We deliberately do NOT upgrade or replace the system Hamlib package --
+# other software on this machine (CQRLOG) depends on it, and installing a
+# newer one over it would break that. Instead this script sets
+# LD_LIBRARY_PATH just for FT8AF's own process, so it preferentially finds
+# the newer build at /usr/local/lib without touching anything system-wide.
+# If no such build exists, this is a no-op and FT8AF falls back to whatever
+# the system provides (same behavior as running the binary directly).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BIN="$SCRIPT_DIR/../src-tauri/target/release/ft8af"
+
+if [ ! -x "$BIN" ]; then
+	echo "error: $BIN not found or not executable -- build it first (npm run tauri build)" >&2
+	exit 1
+fi
+
+if [ -f /usr/local/lib/libhamlib.so.4 ]; then
+	export LD_LIBRARY_PATH="/usr/local/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+fi
+
+exec "$BIN" "$@"

From fb86646cad2a469c2f8b9c227af69d26039ff483 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 17:24:58 +0000
Subject: [PATCH 03/10] Fix unreadable input/select text: light --text color on
 a light native widget background

select and input elements set background: var(--panel) (dark), but
WebKitGTK's native rendering doesn't fully respect that for <select> --
confirmed live, the rig/band dropdown and text fields render with a light
background regardless, so the existing color: var(--text) (light,
#d7e0e8 -- meant for dark panels) made every text box's contents nearly
unreadable. Verified live via the new runtime styles.css: edited the
on-disk file, relaunched with no rebuild, confirmed all Settings-tab
inputs (Callsign, Grid, Display name, Radio) and both dropdowns
(rig/band picker, Backend, Input/Output device) now render crisp black
text.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/public/styles.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index 230eb2cce..bdbac541e 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -41,7 +41,7 @@ button:disabled { opacity: 0.5; cursor: default; }
 
 select, input {
   background: var(--panel);
-  color: var(--text);
+  color: #000;
   border: 1px solid var(--border);
   border-radius: 6px;
   padding: 6px 8px;

From d42c4a8b9a95fc6a2d7258822ddda7369acc63f6 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 18:10:49 +0000
Subject: [PATCH 04/10] Fix invisible text caret in input/select fields

Same root cause as the earlier unreadable-text fix (light --text color on
a light native widget background), but a separate CSS property: caret-color
was never set, so the blinking text cursor was effectively invisible.

This explains a real, confusing user-facing symptom: with no visible caret,
retyping a value without first clearing the field silently inserts new
characters at the actual (but invisible) cursor position instead of
replacing anything -- confirmed live, a garbled "AI5IIAI5IIAI555" ended up
saved after a few real attempts to enter a callsign, matching exactly what
duplicate-insertion-without-clearing produces. Root-caused by resetting the
field to empty and typing a single character with the caret-color fix
applied: cursor now renders as a clear, visible black line, confirmed both
in a screenshot and by the user directly on the live display.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/public/styles.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index bdbac541e..0680b78e4 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -42,6 +42,7 @@ button:disabled { opacity: 0.5; cursor: default; }
 select, input {
   background: var(--panel);
   color: #000;
+  caret-color: #000;
   border: 1px solid var(--border);
   border-radius: 6px;
   padding: 6px 8px;

From 1adc1b656567da7a0f47015814a40e9d852bb224 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 19:06:35 +0000
Subject: [PATCH 05/10] Revert "Fix invisible text caret in input/select
 fields"

This reverts commit d42c4a8b9a95fc6a2d7258822ddda7369acc63f6.
---
 desktop/public/styles.css | 1 -
 1 file changed, 1 deletion(-)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index 0680b78e4..bdbac541e 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -42,7 +42,6 @@ button:disabled { opacity: 0.5; cursor: default; }
 select, input {
   background: var(--panel);
   color: #000;
-  caret-color: #000;
   border: 1px solid var(--border);
   border-radius: 6px;
   padding: 6px 8px;

From 28463d264f18f37bcb46fb8e5f44a1ae8fda0b23 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 19:06:35 +0000
Subject: [PATCH 06/10] Revert "Fix unreadable input/select text: light --text
 color on a light native widget background"

This reverts commit fb86646cad2a469c2f8b9c227af69d26039ff483.
---
 desktop/public/styles.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index bdbac541e..230eb2cce 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -41,7 +41,7 @@ button:disabled { opacity: 0.5; cursor: default; }
 
 select, input {
   background: var(--panel);
-  color: #000;
+  color: var(--text);
   border: 1px solid var(--border);
   border-radius: 6px;
   padding: 6px 8px;

From 9680d65316b7228db4fe0bbb8c26271d01b50666 Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 19:13:16 +0000
Subject: [PATCH 07/10] Scoped, verified-safe fix: white text on the Rig
 control Display name field

The earlier global select/input color override broke real keyboard input
entirely (reverted in fb86646/28463d2 -- see project memory:
project_ft8af_webkitgtk_input_bug.md). This is narrower and confirmed
different: targets only the one Display name <input> via its placeholder
text as a CSS attribute selector (no JSX change, no rebuild needed), not
the shared select/input rule that also matches every native <select>
dropdown.

Verified live, twice, with a real keyboard: text renders white and
readable, and typing into the field still works normally -- unlike every
variant of the global rule change, which broke input every time it was
tried. Callsign/Grid and the <select> dropdowns are untouched by this
commit and still use native-default text color.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/public/styles.css | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index 230eb2cce..9dfd4a48a 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -48,6 +48,16 @@ select, input {
   font-size: 13px;
 }
 
+/* Scoped fix: only the Rig control "Display name" field, targeted by its
+   placeholder text -- NOT a change to the global select/input rule above.
+   Overriding color there broke real keyboard input entirely (confirmed via
+   repeated A/B testing with a real keyboard + xev, not just synthetic
+   input) -- see project memory. This narrower, single-field override was
+   verified safe: readable white text, typing still works normally. */
+input[placeholder="e.g. Flex 6400"] {
+  color: #fff;
+}
+
 .topbar {
   display: flex;
   align-items: center;

From bff5992b8503fbc6aee1b864de98b4e44d19644e Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Fri, 4 Sep 2026 19:50:30 +0000
Subject: [PATCH 08/10] Scoped black-text fix for select fields; add
 --list-audio debug helper

Extends the single-field-scoping approach validated in 9680d65 (Display
name input) to every select that was unreadable against its native light
background: Band, Rig control (Backend/Radio/Connection/Serial port/Baud),
Audio (Input/Output device), and Developer waterfall FFT
(Window function/FFT size/Averaging). Each gets its own id and a CSS rule
targeting just that id -- the shared select/input rule stays untouched,
since overriding color there is what broke real keyboard input earlier
(see project_ft8af_webkitgtk_input_bug.md).

Verified live with a real keyboard across two rebuild/retest cycles:
closed-select display text and open dropdown-list text both render black
and readable, Callsign/Grid typing still works normally, and none of the
scoped selects show any of the input-blocking behavior the global rule
change caused.

Also commits main.rs's `--list-audio` debug helper (used earlier tonight
to diagnose the audio device list, analogous to the existing --list-rigs)
-- prints cpal's enumerated input/output devices and exits.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/public/styles.css     | 25 +++++++++++++++++++------
 desktop/src-tauri/src/main.rs | 31 +++++++++++++++++++++++++++++++
 desktop/src/App.tsx           | 16 +++++++++++++---
 3 files changed, 63 insertions(+), 9 deletions(-)

diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index 9dfd4a48a..7189b9b3f 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -48,16 +48,29 @@ select, input {
   font-size: 13px;
 }
 
-/* Scoped fix: only the Rig control "Display name" field, targeted by its
-   placeholder text -- NOT a change to the global select/input rule above.
-   Overriding color there broke real keyboard input entirely (confirmed via
-   repeated A/B testing with a real keyboard + xev, not just synthetic
-   input) -- see project memory. This narrower, single-field override was
-   verified safe: readable white text, typing still works normally. */
+/* Scoped test: only the Rig control "Display name" field, targeted by its
+   placeholder text (no JSX/rebuild needed) -- not touching the global
+   select/input rule, which broke real keyboard input when modified. */
 input[placeholder="e.g. Flex 6400"] {
   color: #fff;
 }
 
+/* Scoped: Radio/Backend/Connection/Serial port/Baud/Band selects, each
+   targeted by its own id -- not the shared select/input rule. */
+#band-select,
+#rig-backend-select,
+#rig-radio-select,
+#rig-connection-select,
+#rig-serial-port-select,
+#rig-baud-select,
+#audio-input-select,
+#audio-output-select,
+#wf-window-select,
+#wf-fft-size-select,
+#wf-avg-select {
+  color: #000;
+}
+
 .topbar {
   display: flex;
   align-items: center;
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 30f5eff36..28acc2c64 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -239,6 +239,37 @@ fn main() {
         return;
     }
 
+    // Debug helper: `ft8af --list-audio` prints cpal's enumerated input/output
+    // devices and exits -- same idea as --list-rigs, verifies device
+    // enumeration without needing to click through the GUI (native <select>
+    // popups render as a separate top-level X window on Linux, so they don't
+    // show up in a window-scoped screenshot either).
+    if std::env::args().any(|a| a == "--list-audio") {
+        let inputs = audio::list_input_devices();
+        println!("Input devices ({}):", inputs.len());
+        for d in inputs.iter() {
+            println!(
+                "  {}{} -- {} Hz, {} ch",
+                if d.is_default { "* " } else { "  " },
+                d.name,
+                d.default_sample_rate,
+                d.channels
+            );
+        }
+        let outputs = audio::list_output_devices();
+        println!("Output devices ({}):", outputs.len());
+        for d in outputs.iter() {
+            println!(
+                "  {}{} -- {} Hz, {} ch",
+                if d.is_default { "* " } else { "  " },
+                d.name,
+                d.default_sample_rate,
+                d.channels
+            );
+        }
+        return;
+    }
+
     let data_dir = app_data_dir();
     let _ = std::fs::create_dir_all(&data_dir);
     let db = Arc::new(
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index e1a520419..84c52c6df 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -292,7 +292,7 @@ function TopBar(props: {
           {txGain}%
         </span>
       </span>
-      <select value={dialHz} onChange={(e) => onBand(parseInt(e.target.value, 10))}>
+      <select id="band-select" value={dialHz} onChange={(e) => onBand(parseInt(e.target.value, 10))}>
         {bands.map((b) => (
           <option key={b.name} value={b.dial_hz}>
             {b.name} · {(b.dial_hz / 1e6).toFixed(3)}
@@ -772,6 +772,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>Input device (RX)</label>
             <select
+              id="audio-input-select"
               value={input}
               onChange={(e) => {
                 setInput(e.target.value);
@@ -789,6 +790,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>Output device (TX)</label>
             <select
+              id="audio-output-select"
               value={output}
               onChange={(e) => {
                 setOutput(e.target.value);
@@ -843,6 +845,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>Backend</label>
             <select
+              id="rig-backend-select"
               value={rigCfg.backend}
               onChange={(e) => setRigCfg({ ...rigCfg, backend: e.target.value as RigConfig["backend"] })}
             >
@@ -859,6 +862,7 @@ function SettingsScreen(props: {
                 <label>Radio {hamlibRigs.length > 0 ? `(${hamlibRigs.length} supported)` : ""}</label>
                 {hamlibRigs.length > 0 ? (
                   <select
+                    id="rig-radio-select"
                     value={rigCfg.hamlib_model}
                     onChange={(e) =>
                       setRigCfg({ ...rigCfg, hamlib_model: parseInt(e.target.value, 10) })
@@ -884,6 +888,7 @@ function SettingsScreen(props: {
               <div className="field">
                 <label>Connection</label>
                 <select
+                  id="rig-connection-select"
                   value={rigCfg.hamlib_network ? "network" : "serial"}
                   onChange={(e) => setRigCfg({ ...rigCfg, hamlib_network: e.target.value === "network" })}
                 >
@@ -913,7 +918,7 @@ function SettingsScreen(props: {
                   <div className="field">
                     <label>Serial port</label>
                     <div className="row">
-                      <select value={rigCfg.port} onChange={(e) => setRigCfg({ ...rigCfg, port: e.target.value })}>
+                      <select id="rig-serial-port-select" value={rigCfg.port} onChange={(e) => setRigCfg({ ...rigCfg, port: e.target.value })}>
                         <option value="">(none — e.g. Dummy)</option>
                         {ports.map((p) => (
                           <option key={p.name} value={p.name}>
@@ -929,6 +934,7 @@ function SettingsScreen(props: {
                   <div className="field">
                     <label>Baud</label>
                     <select
+                      id="rig-baud-select"
                       value={rigCfg.baud}
                       onChange={(e) => setRigCfg({ ...rigCfg, baud: parseInt(e.target.value, 10) })}
                     >
@@ -988,7 +994,7 @@ function SettingsScreen(props: {
               <div className="field">
                 <label>Serial port</label>
                 <div className="row">
-                  <select value={rigCfg.port} onChange={(e) => setRigCfg({ ...rigCfg, port: e.target.value })}>
+                  <select id="rig-serial-port-select" value={rigCfg.port} onChange={(e) => setRigCfg({ ...rigCfg, port: e.target.value })}>
                     <option value="">— select —</option>
                     {ports.map((p) => (
                       <option key={p.name} value={p.name}>
@@ -1005,6 +1011,7 @@ function SettingsScreen(props: {
                 <div className="field">
                   <label>Baud</label>
                   <select
+                    id="rig-baud-select"
                     value={rigCfg.baud}
                     onChange={(e) => setRigCfg({ ...rigCfg, baud: parseInt(e.target.value, 10) })}
                   >
@@ -1081,6 +1088,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>Window function</label>
             <select
+              id="wf-window-select"
               value={wfCfg.window}
               onChange={(e) => applyWfCfg({ ...wfCfg, window: e.target.value as WfWindow })}
             >
@@ -1094,6 +1102,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>FFT size</label>
             <select
+              id="wf-fft-size-select"
               value={wfCfg.fft_size}
               onChange={(e) => applyWfCfg({ ...wfCfg, fft_size: parseInt(e.target.value, 10) })}
             >
@@ -1107,6 +1116,7 @@ function SettingsScreen(props: {
           <div className="field">
             <label>Averaging (Welch segments per row)</label>
             <select
+              id="wf-avg-select"
               value={wfCfg.avg}
               onChange={(e) => applyWfCfg({ ...wfCfg, avg: parseInt(e.target.value, 10) })}
             >

From f389894dcbb958d74e466d7b25fa295eb5d66e2f Mon Sep 17 00:00:00 2001
From: quadra <leomaniolone@gmail.com>
Date: Sat, 5 Sep 2026 03:31:53 +0000
Subject: [PATCH 09/10] Add live RX input gain control, placed next to the
 decode filter chips

New RX gain slider (0-100%, default 100%/unity) mirrors the existing TX
gain pattern end to end: a lock-free atomic in the audio capture callback
(AudioInput::set_gain(), read fresh per sample on the realtime thread, no
locking), an EngineCommand::SetRxGain handler that persists to config and
applies live without restarting capture, a set_rx_gain Tauri command, and
an ipc.ts wrapper.

Placement: next to the All/CQ/To me filter chips on the Decode screen, not
buried in Settings -- real feedback was that this needs adjusting per-band
(noise floor varies a lot band to band) while actively watching decodes,
the same reasoning that will apply to relocating TX gain next to a future
Tune button.

Range settled at 0-100% (matching TX gain) after live testing: temporarily
widened to 0-800% to confirm the control had real effect (confirmed: mute
at 0%, a genuine clip warning near 800%, proportional movement of the raw
dBFS meter in between), but adjustment past 100% wasn't practically useful
-- the QMX's USB audio codec has no analog preamp stage (confirmed via
amixer: only a capture on/off switch, no volume control), so there's no
real gain headroom on the input side to exploit past unity. Settled on
0-100% for finer control resolution across the range that matters.

Both TX and RX gain sliders now debounce their backend IPC call (~120ms
after the last onChange) while keeping the displayed value instant --
dragging fires far more onChange events than needed, and that load
stacking on the waterfall's own frequent canvas redraws correlates with a
real WebKitGTK renderer crash observed live (the WebKitWebProcess child
disappeared entirely, leaving a blank window, while the Rust backend kept
running) -- not proven as the sole cause, but a safe mitigation regardless.

Also clarified: the waterfall's lack of visible change across the gain
range is by design (its own noise-floor-relative auto-leveling, stated in
its own code comment), and the raw "audio dB" meter reading "silent" at
low gain while decodes keep working is expected too -- it measures
broadband RMS while the decoder/waterfall work in narrow FFT bins, and FT8
is designed to decode at very low SNR.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 desktop/src-tauri/src/audio/input.rs | 85 ++++++++++++++++++++--------
 desktop/src-tauri/src/engine.rs      | 36 +++++++++++-
 desktop/src-tauri/src/main.rs        |  6 ++
 desktop/src/App.tsx                  | 61 +++++++++++++++++++-
 desktop/src/ipc.ts                   |  1 +
 5 files changed, 161 insertions(+), 28 deletions(-)

diff --git a/desktop/src-tauri/src/audio/input.rs b/desktop/src-tauri/src/audio/input.rs
index 550e600c8..dd2c6f780 100644
--- a/desktop/src-tauri/src/audio/input.rs
+++ b/desktop/src-tauri/src/audio/input.rs
@@ -1,7 +1,7 @@
 //! Continuous audio capture: open an input device, downmix to mono, resample to
 //! 12 kHz on a worker thread, and feed a `SlotAccumulator`.
 
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
 use std::sync::Arc;
 use std::thread::JoinHandle;
 
@@ -22,12 +22,23 @@ pub struct AudioInput {
     worker: Option<JoinHandle<()>>,
     pub device_name: String,
     pub device_rate: u32,
+    gain: Arc<AtomicU32>, // f32 bits, read/written lock-free from the realtime callback
 }
 
 impl AudioInput {
+    /// Live-adjustable RX gain (a linear multiplier applied to each downmixed
+    /// sample, e.g. 1.0 = unity, 2.0 = +6 dB) -- some bands are noisier than
+    /// others, so this is expected to change often while decoding, not just
+    /// at startup. Lock-free: the realtime audio callback only ever loads
+    /// this, never blocks on it.
+    pub fn set_gain(&self, g: f32) {
+        self.gain.store(g.to_bits(), Ordering::Relaxed);
+    }
+
     pub fn start(
         device_name: Option<&str>,
         accum: Arc<SlotAccumulator>,
+        initial_gain: f32,
     ) -> anyhow::Result<AudioInput> {
         let device = find_input_device(device_name)
             .ok_or_else(|| anyhow::anyhow!("no input audio device available"))?;
@@ -42,29 +53,43 @@ impl AudioInput {
         let rb = HeapRb::<f32>::new(device_rate as usize * 2); // ~2 s headroom
         let (mut prod, mut cons) = rb.split();
 
+        let gain = Arc::new(AtomicU32::new(initial_gain.to_bits()));
+
         let err_fn = |e| log::error!("audio input stream error: {e}");
 
-        // Build a callback that downmixes interleaved frames to mono f32 and
-        // pushes into the ring. One arm per supported sample format.
+        // Build a callback that downmixes interleaved frames to mono f32,
+        // applies the live RX gain, and pushes into the ring. One arm per
+        // supported sample format. Each arm clones `gain` independently --
+        // disjoint match arms may each move their own capture of a variable
+        // without conflicting (only one arm's closure is ever actually built).
         let stream = match sample_format {
-            SampleFormat::F32 => device.build_input_stream(
-                &config,
-                move |data: &[f32], _| push_mono(data, channels, &mut prod),
-                err_fn,
-                None,
-            )?,
-            SampleFormat::I16 => device.build_input_stream(
-                &config,
-                move |data: &[i16], _| push_mono(data, channels, &mut prod),
-                err_fn,
-                None,
-            )?,
-            SampleFormat::U16 => device.build_input_stream(
-                &config,
-                move |data: &[u16], _| push_mono(data, channels, &mut prod),
-                err_fn,
-                None,
-            )?,
+            SampleFormat::F32 => {
+                let gain = gain.clone();
+                device.build_input_stream(
+                    &config,
+                    move |data: &[f32], _| push_mono(data, channels, &mut prod, &gain),
+                    err_fn,
+                    None,
+                )?
+            }
+            SampleFormat::I16 => {
+                let gain = gain.clone();
+                device.build_input_stream(
+                    &config,
+                    move |data: &[i16], _| push_mono(data, channels, &mut prod, &gain),
+                    err_fn,
+                    None,
+                )?
+            }
+            SampleFormat::U16 => {
+                let gain = gain.clone();
+                device.build_input_stream(
+                    &config,
+                    move |data: &[u16], _| push_mono(data, channels, &mut prod, &gain),
+                    err_fn,
+                    None,
+                )?
+            }
             other => anyhow::bail!("unsupported input sample format: {other:?}"),
         };
         stream.play()?;
@@ -96,6 +121,7 @@ impl AudioInput {
             worker: Some(worker),
             device_name: dev_name,
             device_rate,
+            gain,
         })
     }
 }
@@ -109,8 +135,12 @@ impl Drop for AudioInput {
     }
 }
 
-/// Downmix interleaved `T` frames to mono f32 and push into the ring producer.
-fn push_mono<T, P>(data: &[T], channels: usize, prod: &mut P)
+/// Downmix interleaved `T` frames to mono f32, apply the live RX gain, and
+/// push into the ring producer. `gain` is read fresh per sample (a relaxed
+/// atomic load is cheap, and this runs on the realtime audio thread, so no
+/// locking) -- lets the gain slider feel immediate rather than only taking
+/// effect on the next buffer.
+fn push_mono<T, P>(data: &[T], channels: usize, prod: &mut P, gain: &AtomicU32)
 where
     T: Sample,
     f32: FromSample<T>,
@@ -119,9 +149,14 @@ where
     if channels == 0 {
         return;
     }
+    let g = f32::from_bits(gain.load(Ordering::Relaxed));
+    // Clamp to full scale, same as the TX gain path (audio/output.rs) -- gain
+    // can go well past unity (see clamp_rx_gain), and hard-clipping here
+    // mirrors what a real ADC does when overdriven, rather than passing
+    // arbitrarily large sample values into the resampler/decoder.
     if channels == 1 {
         for &s in data {
-            let _ = prod.try_push(f32::from_sample(s));
+            let _ = prod.try_push((f32::from_sample(s) * g).clamp(-1.0, 1.0));
         }
         return;
     }
@@ -130,6 +165,6 @@ where
         for &s in frame {
             acc += f32::from_sample(s);
         }
-        let _ = prod.try_push(acc / channels as f32);
+        let _ = prod.try_push(((acc / channels as f32) * g).clamp(-1.0, 1.0));
     }
 }
diff --git a/desktop/src-tauri/src/engine.rs b/desktop/src-tauri/src/engine.rs
index 756358db6..7e7387397 100644
--- a/desktop/src-tauri/src/engine.rs
+++ b/desktop/src-tauri/src/engine.rs
@@ -43,6 +43,19 @@ const DEFAULT_TX_GAIN: f32 = 0.9;
 fn clamp_tx_gain(g: f32) -> f32 {
     g.clamp(0.0, 1.0)
 }
+
+// Default RX input gain: unity (no change) -- a fresh install shouldn't
+// alter whatever level the operator's soundcard/interface already provides.
+const DEFAULT_RX_GAIN: f32 = 1.0;
+
+/// Clamp a requested RX gain into 0.0–1.0, same range as TX gain. Widened to
+/// 0.0-8.0 during testing to check the control had real effect (confirmed:
+/// a clip warning at 800%, silence at 0%) -- but adjustment past 100% wasn't
+/// doing anything practically useful, so finalized at 0-100% for finer
+/// control resolution across the range that actually matters.
+fn clamp_rx_gain(g: f32) -> f32 {
+    g.clamp(0.0, 1.0)
+}
 // Live-waterfall FFT parameters (window/size/averaging + display constants)
 // live in `crate::wf` and are runtime-configurable via SetWaterfallConfig.
 // Input RMS at/below this (dBFS) counts as silence — no audio reaching the app.
@@ -97,6 +110,9 @@ pub enum EngineCommand {
     SetBaseFreq(i32),
     /// TX output level, 0.0–1.0 (drive into the soundcard/USB audio path).
     SetTxGain(f32),
+    /// RX input gain, 0.0–2.0 (post-ADC software trim, applied live without
+    /// restarting capture -- some bands are noisier than others).
+    SetRxGain(f32),
     SetInputDevice(Option<String>),
     SetOutputDevice(Option<String>),
     SelectRig(RigConfig),
@@ -265,6 +281,8 @@ struct Engine {
     tx_audio_hz: i32,
     /// TX output level (0.0–1.0) applied to the waveform before playback.
     tx_gain: f32,
+    /// RX input gain (0.0–2.0), applied live inside the capture callback.
+    rx_gain: f32,
     /// Slot id (rx-corrected clock) most recently handed to the decode worker.
     /// Guards the once-per-slot early decode trigger in the run loop.
     last_decoded_slot: i64,
@@ -310,6 +328,11 @@ impl Engine {
             .and_then(|s| s.parse::<f32>().ok())
             .map(clamp_tx_gain)
             .unwrap_or(DEFAULT_TX_GAIN);
+        let rx_gain = db
+            .get_config("rx_gain")
+            .and_then(|s| s.parse::<f32>().ok())
+            .map(clamp_rx_gain)
+            .unwrap_or(DEFAULT_RX_GAIN);
         // Restore the last NTP offset so DT is roughly right immediately, before
         // the first fresh sync of this session lands. Treated as already-synced.
         let saved_offset: Option<i64> = db.get_config("clock_offset_ms").and_then(|s| s.parse().ok());
@@ -375,6 +398,7 @@ impl Engine {
             dial_hz,
             tx_audio_hz,
             tx_gain,
+            rx_gain,
             last_decoded_slot: -1,
             rx_offset_ms,
             last_tick_ms: 0,
@@ -753,6 +777,16 @@ impl Engine {
                 self.tx_gain = clamp_tx_gain(g);
                 let _ = self.db.set_config("tx_gain", &self.tx_gain.to_string());
             }
+            EngineCommand::SetRxGain(g) => {
+                self.rx_gain = clamp_rx_gain(g);
+                let _ = self.db.set_config("rx_gain", &self.rx_gain.to_string());
+                // Applied live -- no capture restart, unlike changing the
+                // device itself. Some bands are noisier than others, so this
+                // is expected to be adjusted often while decoding.
+                if let Some(input) = &self.input {
+                    input.set_gain(self.rx_gain);
+                }
+            }
             EngineCommand::SetWaterfallConfig(cfg) => {
                 let cfg = cfg.sanitize();
                 let _ = self.db.set_config("wf_window", cfg.window.as_str());
@@ -866,7 +900,7 @@ impl Engine {
     }
 
     fn start_decode(&mut self) {
-        match AudioInput::start(self.input_device.as_deref(), self.accum.clone()) {
+        match AudioInput::start(self.input_device.as_deref(), self.accum.clone(), self.rx_gain) {
             Ok(input) => {
                 self.emit(EngineEvent::Info(format!(
                     "capturing from '{}' @ {} Hz",
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 28acc2c64..5ccaa2a07 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -88,6 +88,11 @@ fn set_tx_gain(state: State<AppState>, gain: f32) {
     state.engine.send(EngineCommand::SetTxGain(gain));
 }
 
+#[tauri::command]
+fn set_rx_gain(state: State<AppState>, gain: f32) {
+    state.engine.send(EngineCommand::SetRxGain(gain));
+}
+
 #[tauri::command]
 fn set_input_device(state: State<AppState>, name: Option<String>) {
     state.engine.send(EngineCommand::SetInputDevice(name));
@@ -313,6 +318,7 @@ fn main() {
             set_band,
             set_base_freq,
             set_tx_gain,
+            set_rx_gain,
             set_input_device,
             set_output_device,
             select_rig,
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 84c52c6df..7077bc169 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -76,6 +76,7 @@ export default function App() {
   const [filter, setFilter] = useState<Filter>("all");
   const [txFreq, setTxFreq] = useState(1500);
   const [txGain, setTxGain] = useState(90); // TX level as a percentage (0–100)
+  const [inputGain, setInputGain] = useState(100); // RX input gain as a percentage (0–100)
   const [rigLabel, setRigLabel] = useState(""); // optional display-name override
   const [bands, setBands] = useState<BandInfo[]>([]);
   const [dialHz, setDialHz] = useState<number>(14074000);
@@ -84,6 +85,30 @@ export default function App() {
   const decodingRef = useRef(decoding);
   decodingRef.current = decoding;
 
+  // Debounce IPC calls from the TX/RX gain sliders: a drag gesture can fire
+  // dozens of onChange events (confirmed live -- "the slider is really
+  // touchy"), each one a full round-trip to the Rust backend stacking on top
+  // of the waterfall's own already-frequent canvas redraws. That combined
+  // load correlates with a real WebKitGTK renderer crash seen live (the
+  // WebKitWebProcess disappeared entirely, leaving a blank window, while the
+  // Rust backend kept running fine) -- not proven as the sole cause, but a
+  // clear, safe mitigation regardless. The slider's own displayed value
+  // updates immediately (setTxGain/setInputGain, not debounced) for smooth
+  // visual feedback; only the backend call waits for a short pause in
+  // dragging. Safe to delay for both: TX gain is only read when the *next*
+  // transmission starts (never applied to audio already playing), and RX
+  // gain landing ~120ms late has no practical effect either.
+  const txGainTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const rxGainTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  function debouncedSetTxGain(pct: number) {
+    if (txGainTimer.current) clearTimeout(txGainTimer.current);
+    txGainTimer.current = setTimeout(() => api.setTxGain(pct / 100), 120);
+  }
+  function debouncedSetRxGain(pct: number) {
+    if (rxGainTimer.current) clearTimeout(rxGainTimer.current);
+    rxGainTimer.current = setTimeout(() => api.setRxGain(pct / 100), 120);
+  }
+
   useEffect(() => {
     // Register the event listener with cancellation-safe cleanup. Without this,
     // React StrictMode's mount/unmount/mount in dev leaks the first listener
@@ -112,6 +137,11 @@ export default function App() {
       const pct = Math.round(parseFloat(v) * 100);
       if (!Number.isNaN(pct)) setTxGain(pct); // keep a persisted 0% (not just falsy-skip)
     });
+    api.getConfig("rx_gain").then((v) => {
+      if (v == null || v === "") return;
+      const pct = Math.round(parseFloat(v) * 100);
+      if (!Number.isNaN(pct)) setInputGain(pct);
+    });
     api.getConfig("rig_label").then((v) => {
       if (v) setRigLabel(v);
     });
@@ -201,7 +231,7 @@ export default function App() {
         txGain={txGain}
         onTxGain={(v) => {
           setTxGain(v);
-          api.setTxGain(v / 100);
+          debouncedSetTxGain(v);
         }}
       />
       <div className="tabs">
@@ -223,6 +253,11 @@ export default function App() {
               api.setBaseFreq(hz);
             }}
             onAnswer={(m) => api.answer({ call_from: m.call_from, grid: m.grid, snr: m.snr })}
+            inputGain={inputGain}
+            onInputGain={(v) => {
+              setInputGain(v);
+              debouncedSetRxGain(v);
+            }}
           />
         )}
         {tab === "log" && <LogScreen />}
@@ -456,8 +491,10 @@ function DecodeScreen(props: {
   txFreq: number;
   onSelectFreq: (hz: number) => void;
   onAnswer: (m: UiMessage) => void;
+  inputGain: number;
+  onInputGain: (v: number) => void;
 }) {
-  const { messages, filter, setFilter, txFreq, onSelectFreq, onAnswer } = props;
+  const { messages, filter, setFilter, txFreq, onSelectFreq, onAnswer, inputGain, onInputGain } = props;
   return (
     <>
       <WaterfallView txFreq={txFreq} onSelectFreq={onSelectFreq} />
@@ -467,6 +504,26 @@ function DecodeScreen(props: {
             {f === "all" ? "All" : f === "cq" ? "CQ" : "To me"}
           </div>
         ))}
+        {/* Next to the filter chips, not buried in Settings -- RX gain is
+            expected to be nudged per-band (noise floor varies a lot band to
+            band), so it needs to be at hand while actually watching decodes,
+            not a few clicks away. */}
+        <span className="tx-level" title="RX input gain — some bands are noisier than others" style={{ marginLeft: "auto" }}>
+          <span className="muted">RX</span>
+          <input
+            type="range"
+            aria-label="RX input gain, percent"
+            min={0}
+            max={100}
+            step={1}
+            value={inputGain}
+            onChange={(e) => onInputGain(parseInt(e.target.value, 10))}
+            style={{ width: 90 }}
+          />
+          <span className="muted" style={{ fontVariantNumeric: "tabular-nums", minWidth: 34, textAlign: "right" }}>
+            {inputGain}%
+          </span>
+        </span>
       </div>
       <div className="decode-list">
       <table>
diff --git a/desktop/src/ipc.ts b/desktop/src/ipc.ts
index d1544e6ac..9ed07f7ce 100644
--- a/desktop/src/ipc.ts
+++ b/desktop/src/ipc.ts
@@ -159,6 +159,7 @@ export const api = {
   setBand: (dialHz: number) => invoke("set_band", { dialHz }),
   setBaseFreq: (hz: number) => invoke("set_base_freq", { hz }),
   setTxGain: (gain: number) => invoke("set_tx_gain", { gain }),
+  setRxGain: (gain: number) => invoke("set_rx_gain", { gain }),
   setInputDevice: (name: string | null) => invoke("set_input_device", { name }),
   setOutputDevice: (name: string | null) => invoke("set_output_device", { name }),
   selectRig: (config: RigConfig) => invoke("select_rig", { config }),

From 74b47355410f96e167e58f810977bf6ee5c73c2c Mon Sep 17 00:00:00 2001
From: Patrick Burns <burnsoft@gmail.com>
Date: Tue, 8 Sep 2026 09:01:55 -0500
Subject: [PATCH 10/10] Address code review on the runtime-CSS / RX-gain PR

Select readability (styles.css): the per-id `color: #000` fixed the Linux
symptom but broke the other two platforms. WebKitGTK draws <select> as a
native GTK widget and ignores the author background, so --text sat on a
light control; WebView2 and WKWebView *do* honor the dark --panel
background, so black text there was black-on-#1a2129 -- and CI ships all
three. Opt selects out of native rendering with `appearance: none` so the
theme actually paints everywhere, redraw the arrow as a background image,
and pin both colors on the option list, which the platform draws outside
the page. Drops the dead #rig-radio-select selector along the way.

Stale on-disk stylesheet (main.rs): the seeded copy was frozen after the
first launch, so a later release that ships new markup would render it
unstyled with no in-app reset, and an interrupted first write left a
0-byte file that read back Ok("") and injected an empty <style> forever.
Stamp the seed with an FNV-1a hash of its own body: a file whose stamp
still matches is an untouched seed and is taken back when the compiled
default changes; an edited file, an unstamped one, or one we never wrote
is left alone. Empty or whitespace-only now re-seeds.

Unstyled fallback (main.tsx): with the bundled CSS import removed and
index.html linking nothing, the IPC read was the only source of styling
and the catch rendered anyway -- `npm run dev` in a plain browser, where
invoke rejects, came up as bare HTML. Fall back to the compiled-in copy.

RX gain: docs on SetRxGain, the engine field and set_gain still claimed
0.0-2.0 after the range was finalized at 0.0-1.0. Non-finite input now
falls back to the default instead of being clamped -- f32::clamp
propagates NaN, and the result is persisted where "NaN" parses back
cleanly, so one NaN would kill RX across restarts. The new full-scale
clamp in push_mono applies only above unity: at or below it, it could
only ever clip samples the device already delivered out of range, which
hard-clips the slightly-over-scale samples F32 backends (CoreAudio,
JACK/PipeWire) hand out on an otherwise-default install.

Linux launcher: LD_PRELOAD the one Hamlib rather than prepending
/usr/local/lib to LD_LIBRARY_PATH, which redirected every library FT8AF
resolves; and fall back to an installed ft8af on PATH so the script works
outside a source checkout, which is where its own docs send it.

Debounce: extracted to src/debounce.ts so it is testable, and cancelled
on unmount so a drag in flight cannot fire IPC after teardown.

Tests: resolve_styles/stamp round-trip and recovery cases, clamp_rx_gain
and the non-finite fallback for both gains, push_mono gain/clip/downmix
behavior, and the debounce module.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D7Z6xhcHB3XspStFrQ5puU
---
 desktop/linux/run-ft8af.sh           |  35 ++++--
 desktop/public/styles.css            |  40 ++++--
 desktop/src-tauri/src/audio/input.rs |  87 +++++++++++--
 desktop/src-tauri/src/engine.rs      |  46 ++++++-
 desktop/src-tauri/src/main.rs        | 181 ++++++++++++++++++++++++++-
 desktop/src/App.tsx                  |  37 ++++--
 desktop/src/debounce.test.ts         |  70 +++++++++++
 desktop/src/debounce.ts              |  35 ++++++
 desktop/src/main.tsx                 |  24 +++-
 desktop/src/vite-env.d.ts            |   1 +
 10 files changed, 499 insertions(+), 57 deletions(-)
 create mode 100644 desktop/src/debounce.test.ts
 create mode 100644 desktop/src/debounce.ts
 create mode 100644 desktop/src/vite-env.d.ts

diff --git a/desktop/linux/run-ft8af.sh b/desktop/linux/run-ft8af.sh
index 87ffe6b1f..c983ccd13 100755
--- a/desktop/linux/run-ft8af.sh
+++ b/desktop/linux/run-ft8af.sh
@@ -12,23 +12,38 @@
 #
 # We deliberately do NOT upgrade or replace the system Hamlib package --
 # other software on this machine (CQRLOG) depends on it, and installing a
-# newer one over it would break that. Instead this script sets
-# LD_LIBRARY_PATH just for FT8AF's own process, so it preferentially finds
-# the newer build at /usr/local/lib without touching anything system-wide.
-# If no such build exists, this is a no-op and FT8AF falls back to whatever
-# the system provides (same behavior as running the binary directly).
+# newer one over it would break that. Instead this script LD_PRELOADs that
+# one library into FT8AF's own process: rig.rs's dlopen("libhamlib.so.4")
+# then resolves to the already-loaded object, since the soname matches.
+#
+# LD_PRELOAD rather than prepending /usr/local/lib to LD_LIBRARY_PATH: the
+# latter redirects *every* library FT8AF resolves, so a machine that also has
+# a locally built libssl/libcurl/libstdc++ under /usr/local/lib would load
+# those instead of the distro copies the binary was linked against -- version
+# symbol errors or a crash at startup, from a script whose only job is to
+# pick a Hamlib. If no newer build exists, this is a no-op and FT8AF falls
+# back to whatever the system provides (same as running the binary directly).
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-BIN="$SCRIPT_DIR/../src-tauri/target/release/ft8af"
+DEV_BIN="$SCRIPT_DIR/../src-tauri/target/release/ft8af"
 
-if [ ! -x "$BIN" ]; then
-	echo "error: $BIN not found or not executable -- build it first (npm run tauri build)" >&2
+# Prefer the dev tree's build when this is run from a checkout, but fall back
+# to an installed ft8af on PATH -- the .deb/AppImage CI produces puts it at
+# /usr/bin/ft8af, and this script is meant to be copied out of the repo.
+if [ -x "$DEV_BIN" ]; then
+	BIN="$DEV_BIN"
+elif BIN="$(command -v ft8af)"; then
+	:
+else
+	echo "error: no ft8af binary found -- looked at $DEV_BIN and on PATH." >&2
+	echo "       Build it with 'npm run tauri build' or install the package." >&2
 	exit 1
 fi
 
-if [ -f /usr/local/lib/libhamlib.so.4 ]; then
-	export LD_LIBRARY_PATH="/usr/local/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+HAMLIB=/usr/local/lib/libhamlib.so.4
+if [ -f "$HAMLIB" ]; then
+	export LD_PRELOAD="$HAMLIB${LD_PRELOAD:+:$LD_PRELOAD}"
 fi
 
 exec "$BIN" "$@"
diff --git a/desktop/public/styles.css b/desktop/public/styles.css
index 789dfb2eb..412b33b44 100644
--- a/desktop/public/styles.css
+++ b/desktop/public/styles.css
@@ -55,19 +55,33 @@ input[placeholder="e.g. Flex 6400"] {
   color: #fff;
 }
 
-/* Scoped: Radio/Backend/Connection/Serial port/Baud/Band selects, each
-   targeted by its own id -- not the shared select/input rule. */
-#band-select,
-#rig-backend-select,
-#rig-radio-select,
-#rig-connection-select,
-#rig-serial-port-select,
-#rig-baud-select,
-#audio-input-select,
-#audio-output-select,
-#wf-window-select,
-#wf-fft-size-select,
-#wf-avg-select {
+/* Select readability, fixed at the cause rather than per-id.
+   The original symptom is Linux-only: WebKitGTK draws <select> as a *native*
+   GTK widget, which ignores the author `background` from the shared
+   select/input rule above but still honors `color`, so the light --text sat
+   on a light GTK control and was unreadable. Forcing `color: #000` per id
+   papered over that, but WebView2 (Windows) and WKWebView (macOS) *do* honor
+   the dark --panel background, so the same rule turned every dropdown on
+   those platforms into black-on-#1a2129 -- and CI ships all three.
+   `appearance: none` opts the control out of native rendering everywhere, so
+   the panel background and --text color actually paint on every platform;
+   the arrow the native widget provided is redrawn as a background image. */
+select {
+  -webkit-appearance: none;
+  appearance: none;
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 8'%3E%3Cpath fill='%238a99a8' d='M1 1.5 6 6.5l5-5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 8px center;
+  background-size: 10px 7px;
+  padding-right: 26px;
+}
+
+/* The open dropdown's popup is drawn by the platform, outside the page, so
+   `appearance` does not reach it. Pin both properties on the options so the
+   popup is self-consistent no matter which of the two an engine honors --
+   light ground, dark text, readable against every platform's default popup. */
+select option {
+  background: #fff;
   color: #000;
 }
 
diff --git a/desktop/src-tauri/src/audio/input.rs b/desktop/src-tauri/src/audio/input.rs
index dd2c6f780..f52dda378 100644
--- a/desktop/src-tauri/src/audio/input.rs
+++ b/desktop/src-tauri/src/audio/input.rs
@@ -27,7 +27,7 @@ pub struct AudioInput {
 
 impl AudioInput {
     /// Live-adjustable RX gain (a linear multiplier applied to each downmixed
-    /// sample, e.g. 1.0 = unity, 2.0 = +6 dB) -- some bands are noisier than
+    /// sample, e.g. 1.0 = unity, 0.5 = -6 dB) -- some bands are noisier than
     /// others, so this is expected to change often while decoding, not just
     /// at startup. Lock-free: the realtime audio callback only ever loads
     /// this, never blocks on it.
@@ -150,13 +150,24 @@ where
         return;
     }
     let g = f32::from_bits(gain.load(Ordering::Relaxed));
-    // Clamp to full scale, same as the TX gain path (audio/output.rs) -- gain
-    // can go well past unity (see clamp_rx_gain), and hard-clipping here
-    // mirrors what a real ADC does when overdriven, rather than passing
-    // arbitrarily large sample values into the resampler/decoder.
+    // Clamp to full scale, same as the TX gain path (audio/output.rs) --
+    // hard-clipping mirrors what a real ADC does when overdriven, rather than
+    // passing arbitrarily large sample values into the resampler/decoder.
+    //
+    // Only *above* unity though. A gain of 1.0 or less cannot push a sample
+    // past full scale that was not already there, so clamping unconditionally
+    // would only ever change the samples a device delivered out of range in
+    // the first place -- and F32 devices (CoreAudio, JACK/PipeWire) do hand
+    // out the occasional sample a hair over 1.0. Clipping those on a default,
+    // unity-gain install adds harmonics to RX audio that the capture path
+    // never introduced before the gain control existed. clamp_rx_gain caps at
+    // 1.0 today, so this is dormant; it keeps the guard correct if the range
+    // is ever widened.
+    let clip = g > 1.0;
+    let limit = |x: f32| if clip { x.clamp(-1.0, 1.0) } else { x };
     if channels == 1 {
         for &s in data {
-            let _ = prod.try_push((f32::from_sample(s) * g).clamp(-1.0, 1.0));
+            let _ = prod.try_push(limit(f32::from_sample(s) * g));
         }
         return;
     }
@@ -165,6 +176,68 @@ where
         for &s in frame {
             acc += f32::from_sample(s);
         }
-        let _ = prod.try_push(((acc / channels as f32) * g).clamp(-1.0, 1.0));
+        let _ = prod.try_push(limit((acc / channels as f32) * g));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::push_mono;
+    use ringbuf::traits::{Consumer, Split};
+    use ringbuf::HeapRb;
+    use std::sync::atomic::AtomicU32;
+
+    /// Run `push_mono` over `data` at the given gain and collect what landed.
+    fn pushed(data: &[f32], channels: usize, gain: f32) -> Vec<f32> {
+        let rb = HeapRb::<f32>::new(data.len().max(1) + 1);
+        let (mut prod, mut cons) = rb.split();
+        push_mono(data, channels, &mut prod, &AtomicU32::new(gain.to_bits()));
+        cons.pop_iter().collect()
+    }
+
+    #[test]
+    fn unity_gain_is_a_pure_pass_through() {
+        // The regression this guards: an unconditional clamp would hard-clip
+        // the over-full-scale samples F32 devices (CoreAudio, JACK/PipeWire)
+        // occasionally deliver, changing RX audio on a default install where
+        // the gain control was never touched.
+        let hot = [0.5, -0.5, 1.02, -1.04];
+        assert_eq!(pushed(&hot, 1, 1.0), hot.to_vec());
+    }
+
+    #[test]
+    fn gain_below_unity_scales_without_clipping() {
+        assert_eq!(pushed(&[0.5, -0.25], 1, 0.5), vec![0.25, -0.125]);
+        // Still no clamp: halving an over-scale sample leaves it over-scale,
+        // exactly as the pre-gain path delivered it.
+        assert_eq!(pushed(&[1.6], 1, 0.5), vec![0.8]);
+        assert_eq!(pushed(&[2.4], 1, 1.0), vec![2.4]);
+    }
+
+    #[test]
+    fn gain_above_unity_clips_to_full_scale() {
+        // Dormant while clamp_rx_gain caps at 1.0, but the guard has to be
+        // correct if that range is ever widened.
+        assert_eq!(pushed(&[0.8, -0.8, 0.1], 1, 2.0), vec![1.0, -1.0, 0.2]);
+    }
+
+    #[test]
+    fn multichannel_frames_are_averaged_then_gained() {
+        // Two stereo frames: (0.4, 0.8) -> 0.6, (-1.0, 0.0) -> -0.5.
+        assert_eq!(pushed(&[0.4, 0.8, -1.0, 0.0], 2, 1.0), vec![0.6, -0.5]);
+        assert_eq!(pushed(&[0.4, 0.8, -1.0, 0.0], 2, 0.5), vec![0.3, -0.25]);
+    }
+
+    #[test]
+    fn zero_channels_pushes_nothing() {
+        assert!(pushed(&[0.5, 0.5], 0, 1.0).is_empty());
+    }
+
+    #[test]
+    fn a_trailing_partial_frame_is_dropped() {
+        // chunks_exact: three samples on a stereo stream yield one frame.
+        let got = pushed(&[0.2, 0.4, 0.9], 2, 1.0);
+        assert_eq!(got.len(), 1);
+        assert!((got[0] - 0.3).abs() < 1e-6, "got {got:?}");
     }
 }
diff --git a/desktop/src-tauri/src/engine.rs b/desktop/src-tauri/src/engine.rs
index f3f69f229..0a62946d6 100644
--- a/desktop/src-tauri/src/engine.rs
+++ b/desktop/src-tauri/src/engine.rs
@@ -45,7 +45,16 @@ const MAX_TX_AUDIO_HZ: i32 = 3_000;
 const DEFAULT_TX_GAIN: f32 = 0.9;
 
 /// Clamp a requested TX gain into the valid 0.0–1.0 range (full scale).
+///
+/// Non-finite input falls back to the default rather than being clamped:
+/// `f32::clamp` propagates NaN, and the result is both stored in the engine
+/// and persisted to config, where `"NaN".parse::<f32>()` succeeds — so a
+/// single NaN would poison the gain across restarts with no way back short
+/// of editing the database.
 fn clamp_tx_gain(g: f32) -> f32 {
+    if !g.is_finite() {
+        return DEFAULT_TX_GAIN;
+    }
     g.clamp(0.0, 1.0)
 }
 
@@ -58,7 +67,13 @@ const DEFAULT_RX_GAIN: f32 = 1.0;
 /// a clip warning at 800%, silence at 0%) -- but adjustment past 100% wasn't
 /// doing anything practically useful, so finalized at 0-100% for finer
 /// control resolution across the range that actually matters.
+/// Non-finite input falls back to the default, for the same reason as
+/// `clamp_tx_gain` — and worse here, since a NaN gain multiplies every
+/// captured sample into NaN and silently kills RX entirely.
 fn clamp_rx_gain(g: f32) -> f32 {
+    if !g.is_finite() {
+        return DEFAULT_RX_GAIN;
+    }
     g.clamp(0.0, 1.0)
 }
 
@@ -215,8 +230,9 @@ pub enum EngineCommand {
     SetBaseFreq(i32),
     /// TX output level, 0.0–1.0 (drive into the soundcard/USB audio path).
     SetTxGain(f32),
-    /// RX input gain, 0.0–2.0 (post-ADC software trim, applied live without
-    /// restarting capture -- some bands are noisier than others).
+    /// RX input gain, 0.0–1.0 (post-ADC software trim, applied live without
+    /// restarting capture -- some bands are noisier than others). See
+    /// `clamp_rx_gain` for why the range stops at unity.
     SetRxGain(f32),
     SetInputDevice(Option<String>),
     SetOutputDevice(Option<String>),
@@ -391,7 +407,7 @@ struct Engine {
     tx_audio_hz: i32,
     /// TX output level (0.0–1.0) applied to the waveform before playback.
     tx_gain: f32,
-    /// RX input gain (0.0–2.0), applied live inside the capture callback.
+    /// RX input gain (0.0–1.0), applied live inside the capture callback.
     rx_gain: f32,
     /// Slot id (rx-corrected clock) most recently handed to the decode worker.
     /// Guards the once-per-slot early decode trigger in the run loop.
@@ -1299,8 +1315,9 @@ impl Engine {
 #[cfg(test)]
 mod tests {
     use super::{
-        clamp_tx_gain, reply_tx_audio_hz, rms_dbfs, wf_boundary_row, Engine, CYCLE_MS,
-        MAX_TX_AUDIO_HZ, MIN_TX_AUDIO_HZ, SILENCE_DBFS,
+        clamp_rx_gain, clamp_tx_gain, reply_tx_audio_hz, rms_dbfs, wf_boundary_row, Engine,
+        CYCLE_MS, DEFAULT_RX_GAIN, DEFAULT_TX_GAIN, MAX_TX_AUDIO_HZ, MIN_TX_AUDIO_HZ,
+        SILENCE_DBFS,
     };
     use crate::db::Db;
     use std::sync::Arc;
@@ -1375,6 +1392,25 @@ mod tests {
         assert_eq!(clamp_tx_gain(-0.2), 0.0); // never negative (phase flip / garbage)
     }
 
+    #[test]
+    fn rx_gain_clamps_to_unit_range() {
+        assert_eq!(clamp_rx_gain(0.5), 0.5); // in range, untouched
+        assert_eq!(clamp_rx_gain(1.4), 1.0); // attenuate-only, never past unity
+        assert_eq!(clamp_rx_gain(-0.2), 0.0); // never negative (phase flip / garbage)
+        assert_eq!(clamp_rx_gain(0.0), 0.0); // a deliberate mute is honored
+    }
+
+    #[test]
+    fn non_finite_gain_falls_back_to_the_default() {
+        // f32::clamp propagates NaN, and the clamped value is persisted --
+        // "NaN" parses back cleanly on the next launch, so an unguarded NaN
+        // would stick permanently (and zero RX, since NaN * sample is NaN).
+        for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {
+            assert_eq!(clamp_tx_gain(bad), DEFAULT_TX_GAIN);
+            assert_eq!(clamp_rx_gain(bad), DEFAULT_RX_GAIN);
+        }
+    }
+
     #[test]
     fn wf_boundary_fires_once_per_cycle() {
         let mut last = -1;
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
index 90758068c..3dfeddc5c 100644
--- a/desktop/src-tauri/src/main.rs
+++ b/desktop/src-tauri/src/main.rs
@@ -294,6 +294,88 @@ fn styles_path() -> PathBuf {
     app_data_dir().join("styles.css")
 }
 
+/// Marker line prefixed to the seeded copy of `DEFAULT_STYLES_CSS`. The value
+/// is the hash of the body written underneath it, which does double duty: it
+/// identifies *which* build's stylesheet the copy came from, and comparing it
+/// against a re-hash of the body tells us whether the user has since edited
+/// the file. A CSS comment, so a stale reader just treats it as one.
+const STYLES_STAMP_PREFIX: &str = "/* ft8af-seeded: ";
+
+/// FNV-1a (64-bit). Inlined rather than pulled in as a dependency, and chosen
+/// over `DefaultHasher` because the value is written to disk and compared
+/// across builds -- `DefaultHasher`'s output is explicitly not stable between
+/// Rust releases, which would make every toolchain bump look like a new
+/// stylesheet version.
+fn fnv1a64(s: &str) -> u64 {
+    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
+    for b in s.as_bytes() {
+        h ^= u64::from(*b);
+        h = h.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    h
+}
+
+fn stamped_default_css(default_css: &str) -> String {
+    format!("{STYLES_STAMP_PREFIX}{:016x} */\n{default_css}", fnv1a64(default_css))
+}
+
+/// Split a stamped file into `(recorded hash, body)`, or `None` if it carries
+/// no stamp (a hand-written file, or one seeded before stamping existed).
+fn split_styles_stamp(content: &str) -> Option<(u64, &str)> {
+    let rest = content.strip_prefix(STYLES_STAMP_PREFIX)?;
+    let (hex, after) = rest.split_once(" */")?;
+    let hash = u64::from_str_radix(hex.trim(), 16).ok()?;
+    Some((hash, after.strip_prefix('\n').unwrap_or(after)))
+}
+
+/// What to do with whatever `styles_path()` currently holds. Pure so it can be
+/// unit-tested without touching the filesystem.
+#[derive(Debug, PartialEq, Eq)]
+enum StylesAction {
+    /// Serve this content as-is; leave the file alone.
+    Use(String),
+    /// (Re-)write the file from the compiled default and serve that.
+    Seed,
+}
+
+/// Decide between the on-disk stylesheet and the compiled-in default.
+///
+/// The point of the on-disk copy is that editing it only needs an app
+/// relaunch, not a rebuild -- so a file the user has actually edited always
+/// wins, and an unstamped file is left alone too (we did not verifiably write
+/// it, so we must not clobber it). The two cases we *do* take back are the
+/// ones where the file is worse than useless:
+///
+///  * missing, empty, or whitespace-only -- an interrupted or truncated first
+///    write leaves a 0-byte file that reads back `Ok("")`, which would inject
+///    an empty `<style>` and render the whole app unstyled forever, with no
+///    in-app way out;
+///  * an untouched seed from an older build -- its stamp still matches its own
+///    body, so we know the user never edited it, and serving it would freeze
+///    the UI at that build's CSS while newer releases add markup it has no
+///    rules for.
+fn resolve_styles(on_disk: Option<&str>, default_css: &str) -> StylesAction {
+    let Some(content) = on_disk else {
+        return StylesAction::Seed;
+    };
+    if content.trim().is_empty() {
+        return StylesAction::Seed;
+    }
+    match split_styles_stamp(content) {
+        // Stamp matches the body: an untouched seed. Take it back if it came
+        // from a different build than the one running now.
+        Some((stamp, body)) if stamp == fnv1a64(body) => {
+            if stamp == fnv1a64(default_css) {
+                StylesAction::Use(body.to_string())
+            } else {
+                StylesAction::Seed
+            }
+        }
+        // Stamped but edited, or not stamped at all -- the user's file.
+        _ => StylesAction::Use(content.to_string()),
+    }
+}
+
 #[tauri::command]
 fn get_custom_css() -> String {
     // Read from disk on every call, not from the Vite/Tauri-bundled frontend
@@ -304,12 +386,12 @@ fn get_custom_css() -> String {
     // outside that embed entirely, so editing it just needs an app relaunch
     // -- the whole point, since this stylesheet is expected to change often.
     let path = styles_path();
-    match std::fs::read_to_string(&path) {
-        Ok(css) => css,
-        Err(_) => {
-            // First run: seed the file so there's something to open and edit.
+    let on_disk = std::fs::read_to_string(&path).ok();
+    match resolve_styles(on_disk.as_deref(), DEFAULT_STYLES_CSS) {
+        StylesAction::Use(css) => css,
+        StylesAction::Seed => {
             let _ = std::fs::create_dir_all(app_data_dir());
-            let _ = std::fs::write(&path, DEFAULT_STYLES_CSS);
+            let _ = std::fs::write(&path, stamped_default_css(DEFAULT_STYLES_CSS));
             DEFAULT_STYLES_CSS.to_string()
         }
     }
@@ -441,3 +523,92 @@ fn main() {
         .run(tauri::generate_context!())
         .expect("error running FT8AF");
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        fnv1a64, resolve_styles, split_styles_stamp, stamped_default_css, StylesAction,
+        DEFAULT_STYLES_CSS,
+    };
+
+    const OLD: &str = "body { color: red; }\n";
+    const NEW: &str = "body { color: blue; }\n";
+
+    #[test]
+    fn stamp_round_trips() {
+        let seeded = stamped_default_css(OLD);
+        assert_eq!(split_styles_stamp(&seeded), Some((fnv1a64(OLD), OLD)));
+    }
+
+    #[test]
+    fn unstamped_content_has_no_stamp() {
+        assert_eq!(split_styles_stamp(OLD), None);
+        // A truncated or malformed marker must not be mistaken for a stamp.
+        assert_eq!(split_styles_stamp("/* ft8af-seeded: zzzz */\nx"), None);
+        assert_eq!(split_styles_stamp("/* ft8af-seeded: 00ff"), None);
+    }
+
+    #[test]
+    fn missing_or_blank_file_is_seeded() {
+        // No file at all: first run.
+        assert_eq!(resolve_styles(None, NEW), StylesAction::Seed);
+        // A 0-byte file from an interrupted first write reads back Ok("") --
+        // serving that would inject an empty <style> and render nothing.
+        assert_eq!(resolve_styles(Some(""), NEW), StylesAction::Seed);
+        assert_eq!(resolve_styles(Some("  \n\t "), NEW), StylesAction::Seed);
+    }
+
+    #[test]
+    fn untouched_seed_from_this_build_is_served_without_its_stamp() {
+        let seeded = stamped_default_css(NEW);
+        assert_eq!(
+            resolve_styles(Some(&seeded), NEW),
+            StylesAction::Use(NEW.to_string())
+        );
+    }
+
+    #[test]
+    fn untouched_seed_from_an_older_build_is_reseeded() {
+        // The staleness case: the app shipped new CSS, the on-disk copy is
+        // still the previous build's and the user never touched it.
+        let seeded = stamped_default_css(OLD);
+        assert_eq!(resolve_styles(Some(&seeded), NEW), StylesAction::Seed);
+    }
+
+    #[test]
+    fn user_edits_survive_a_default_change() {
+        let edited = format!("{}body {{ color: green; }}\n", stamped_default_css(OLD));
+        assert_eq!(
+            resolve_styles(Some(&edited), NEW),
+            StylesAction::Use(edited.clone())
+        );
+    }
+
+    #[test]
+    fn unstamped_file_is_never_clobbered() {
+        // Hand-written, or seeded by a build from before stamping existed.
+        assert_eq!(
+            resolve_styles(Some(OLD), NEW),
+            StylesAction::Use(OLD.to_string())
+        );
+    }
+
+    #[test]
+    fn shipped_default_seeds_and_round_trips() {
+        // Guards the real constant, not just fixtures: seeding then resolving
+        // must hand back the compiled stylesheet byte-for-byte.
+        let seeded = stamped_default_css(DEFAULT_STYLES_CSS);
+        assert_eq!(
+            resolve_styles(Some(&seeded), DEFAULT_STYLES_CSS),
+            StylesAction::Use(DEFAULT_STYLES_CSS.to_string())
+        );
+    }
+
+    #[test]
+    fn fnv1a64_matches_reference_vectors() {
+        // Pinned so a refactor can't silently change the on-disk stamp format.
+        assert_eq!(fnv1a64(""), 0xcbf2_9ce4_8422_2325);
+        assert_eq!(fnv1a64("a"), 0xaf63_dc4c_8601_ec8c);
+        assert_eq!(fnv1a64("foobar"), 0x8594_4171_f739_67e8);
+    }
+}
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index c1e548d74..3d6d3d866 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -30,11 +30,17 @@ import {
   type QsoEditForm,
 } from "./logbook";
 import { applySelection, configToSelection, rigName, rigOptions } from "./rig";
+import { debounce } from "./debounce";
 
 type Tab = "decode" | "log" | "settings";
 type Filter = "all" | "cq" | "tome";
 const MAX_MESSAGES = 800;
 
+// Quiet period a gain slider must see before its value is sent to the
+// backend. Long enough to collapse a drag gesture, short enough that a
+// deliberate single adjustment still feels immediate.
+const GAIN_DEBOUNCE_MS = 120;
+
 // The live waterfall draws imperatively to a canvas (registered by WaterfallView)
 // so per-row spectrum events never go through React state.
 const WF_HEIGHT = 160;
@@ -109,17 +115,26 @@ export default function App() {
   // visual feedback; only the backend call waits for a short pause in
   // dragging. Safe to delay for both: TX gain is only read when the *next*
   // transmission starts (never applied to audio already playing), and RX
-  // gain landing ~120ms late has no practical effect either.
-  const txGainTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const rxGainTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  function debouncedSetTxGain(pct: number) {
-    if (txGainTimer.current) clearTimeout(txGainTimer.current);
-    txGainTimer.current = setTimeout(() => api.setTxGain(pct / 100), 120);
-  }
-  function debouncedSetRxGain(pct: number) {
-    if (rxGainTimer.current) clearTimeout(rxGainTimer.current);
-    rxGainTimer.current = setTimeout(() => api.setRxGain(pct / 100), 120);
-  }
+  // gain landing ~120ms late has no practical effect either. This does change
+  // TX gain from "applied on the spot" to "applied after the drag settles" --
+  // deliberate, and invisible unless a slot boundary lands inside that window,
+  // in which case the previous level is used for one transmission.
+  // Held in refs so the debouncers survive re-renders (a fresh one per render
+  // would never accumulate a burst), and cancelled on unmount so a drag still
+  // in flight cannot fire IPC after teardown. See src/debounce.ts.
+  const debouncedSetTxGain = useRef(
+    debounce((pct: number) => api.setTxGain(pct / 100), GAIN_DEBOUNCE_MS)
+  ).current;
+  const debouncedSetRxGain = useRef(
+    debounce((pct: number) => api.setRxGain(pct / 100), GAIN_DEBOUNCE_MS)
+  ).current;
+  useEffect(
+    () => () => {
+      debouncedSetTxGain.cancel();
+      debouncedSetRxGain.cancel();
+    },
+    [debouncedSetTxGain, debouncedSetRxGain]
+  );
 
   useEffect(() => {
     // Register the event listener with cancellation-safe cleanup. Without this,
diff --git a/desktop/src/debounce.test.ts b/desktop/src/debounce.test.ts
new file mode 100644
index 000000000..c6e16adb3
--- /dev/null
+++ b/desktop/src/debounce.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { debounce } from "./debounce";
+
+describe("debounce", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("defers the call until the delay elapses", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    d(50);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(119);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledExactlyOnceWith(50);
+  });
+
+  it("collapses a burst into one call with the last value", () => {
+    // The slider-drag case: dozens of onChange events, one IPC round-trip.
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    for (const v of [10, 20, 30, 40]) {
+      d(v);
+      vi.advanceTimersByTime(30); // each below the threshold
+    }
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(120);
+    expect(fn).toHaveBeenCalledExactlyOnceWith(40);
+  });
+
+  it("fires again once the burst has settled", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    d(1);
+    vi.advanceTimersByTime(120);
+    d(2);
+    vi.advanceTimersByTime(120);
+    expect(fn.mock.calls).toEqual([[1], [2]]);
+  });
+
+  it("cancel drops a pending call", () => {
+    // Unmount with a drag still in flight: the IPC must not fire afterwards.
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    d(7);
+    d.cancel();
+    vi.advanceTimersByTime(1000);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("cancel is safe with nothing pending, and does not disable the debouncer", () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    d.cancel();
+    d.cancel();
+    d(3);
+    vi.advanceTimersByTime(120);
+    expect(fn).toHaveBeenCalledExactlyOnceWith(3);
+  });
+
+  it("passes a falsy value through rather than skipping it", () => {
+    // 0% is a deliberate setting (mute), not an absent one.
+    const fn = vi.fn();
+    const d = debounce(fn, 120);
+    d(0);
+    vi.advanceTimersByTime(120);
+    expect(fn).toHaveBeenCalledExactlyOnceWith(0);
+  });
+});
diff --git a/desktop/src/debounce.ts b/desktop/src/debounce.ts
new file mode 100644
index 000000000..82ec8aac4
--- /dev/null
+++ b/desktop/src/debounce.ts
@@ -0,0 +1,35 @@
+// Trailing-edge debounce, extracted from App so it can be unit-tested (the
+// timer bookkeeping inside a component body is not reachable from vitest).
+
+/** A debounced callback, plus the `cancel` a React cleanup needs. */
+export type Debounced<T> = {
+  (value: T): void;
+  /** Drop any pending call. Idempotent; safe to call when nothing is pending. */
+  cancel: () => void;
+};
+
+/**
+ * Call `fn` with the most recent argument once `ms` have passed with no
+ * further calls. Trailing edge only: rapid calls collapse into one, which is
+ * the point here — a gain-slider drag fires dozens of onChange events and each
+ * one would otherwise be a full IPC round-trip to the Rust backend.
+ *
+ * `cancel` exists because a pending timer outlives unmount: without it the
+ * callback still fires after teardown, invoking IPC against a component that
+ * no longer exists.
+ */
+export function debounce<T>(fn: (value: T) => void, ms: number): Debounced<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const debounced = (value: T) => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn(value);
+    }, ms);
+  };
+  debounced.cancel = () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  };
+  return debounced;
+}
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 485c8937c..91abcaf54 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -1,6 +1,10 @@
 import ReactDOM from "react-dom/client";
 import { invoke } from "@tauri-apps/api/core";
 import App from "./App";
+// The compiled-in copy of the same stylesheet, as a string rather than a
+// side-effecting CSS import -- injected only when the IPC read below fails,
+// so the on-disk file stays the single source of styling in the normal case.
+import bundledCss from "../public/styles.css?raw";
 
 // Note: no React.StrictMode. Its dev-only double mount/unmount double-registers
 // the async Tauri event listener, which duplicated every decode batch.
@@ -14,15 +18,23 @@ import App from "./App";
 // CSS as a <style> tag instead means edits to the on-disk file just need an
 // app relaunch, matching how the rig list is resolved live via hamlib rather
 // than baked in. Render waits on this so there's no unstyled flash.
+function injectStyles(css: string) {
+  const style = document.createElement("style");
+  style.id = "ft8af-custom-styles";
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
 async function loadCustomStyles() {
   try {
-    const css = await invoke<string>("get_custom_css");
-    const style = document.createElement("style");
-    style.id = "ft8af-custom-styles";
-    style.textContent = css;
-    document.head.appendChild(style);
+    injectStyles(await invoke<string>("get_custom_css"));
   } catch (e) {
-    console.error("failed to load custom styles:", e);
+    // No Tauri IPC to answer the call -- most often `npm run dev` opened in a
+    // plain browser, where `invoke` rejects outright. Since index.html links
+    // no stylesheet, rendering past this without a fallback would put up the
+    // app as bare unstyled HTML, so fall back to the compiled-in copy.
+    console.error("failed to load custom styles, using the bundled copy:", e);
+    injectStyles(bundledCss);
   }
 }
 
diff --git a/desktop/src/vite-env.d.ts b/desktop/src/vite-env.d.ts
new file mode 100644
index 000000000..11f02fe2a
--- /dev/null
+++ b/desktop/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />