fix(cw): stop the decoder claiming a healthy signal it cannot hear

With tone shift off and the operator tuned outside 400-1200 Hz, the page did not
go quiet - it went confidently wrong. Three measurements, all reproduced against
the real spectrogram path:

estimatedPitch is (32 + loudestBin) * 12.5 - shiftHz with the bin confined to
0..64, so with no shift applied it can only ever report 400-1200 Hz. It cannot
express 1500 Hz, and it does not try: it publishes whichever window edge the
leakage piles against. For a 1500 Hz tone that is 1200 Hz.

That leakage is not faint. The waterfall normalises to the loudest value on
screen, so 50 of 65 bins clear the 0.06 draw threshold and the picture shows a
keyed-looking column pinned to the right edge - the 1200 Hz column runs 25 times
the 400 Hz one.

signalStrength is prominence over the window mean, so the same leakage scores
0.78 and paints the meter to 78% of full width.

So the operator got a strong-signal bar, a plausible 1200 Hz readout, a picture
that looked like a signal, and an empty transcript, with nothing saying why.

The scan that can see past the window now runs whether or not shifting is
enabled - it is the only measurement that can - and publishes through a new
detectedToneHz flow kept separate from estimatedPitch. Overloading the latter is
what let the 1200 Hz claim out in the first place, so the two meanings stay in
two flows. The shift decision still only happens when the setting is on. Cost is
one 121-bin scan every 2 s.

The meter now reads zero when a tone is out of range and not being shifted in: it
is a claim that something decodable is present, and in that state nothing is.

A line under the waterfall says which case the operator is in - the tone was
moved in, or it is out of range and tone shift is off, naming the frequency and
the remedy. Strings in all nine locales; feature:cw only had five, so values-es,
values-ru, values-si and values-uk are new, with the Turkish apostrophe escaped.

CwToneShifterTest pins the premise the hint rests on: that the scan reports tones
the model window excludes, at 120, 250, 1400 and 1500 Hz.

core/data/src/main/java/com/rtbishop/look4sat/core/data/cw/CwDeepDecoder.kt

@@ -106,6 +106,9 @@ class CwDeepDecoder(
     private val _estimatedPitch = MutableStateFlow<Float?>(null)
     override val estimatedPitch: StateFlow<Float?> = _estimatedPitch.asStateFlow()
 
+    private val _detectedToneHz = MutableStateFlow<Float?>(null)
+    override val detectedToneHz: StateFlow<Float?> = _detectedToneHz.asStateFlow()
+
     private val _activeShiftHz = MutableStateFlow(0f)
     override val activeShiftHz: StateFlow<Float> = _activeShiftHz.asStateFlow()
 
@@ -324,23 +327,30 @@ class CwDeepDecoder(
             Log.i(TAG, "toneShift: setting changed to $enabled, dropping buffered audio")
             dropBufferedAudio()
             _activeShiftHz.value = 0f
+            _detectedToneHz.value = null
             shiftDecider.reset()
             lastDetectAtMs = 0L
             detectionPool.clear()
             streamingShifter.reset()
         }
 
-        if (!enabled) return resampled
-
+        // Detection runs whether or not shifting is enabled. It is the only measurement
+        // that can see past the model's window, so with it skipped an out-of-window tone
+        // left the UI with nothing truthful to show: the spectrogram's own pitch readout
+        // is arithmetically confined to the window and reports the leakage piled against
+        // the nearest edge, so a 1500 Hz tone published "1200 Hz" and a healthy signal
+        // level while decoding nothing at all.
         detectionPool.add(resampled)
 
         val now = System.currentTimeMillis()
         val elapsed = now - lastDetectAtMs
         if (detectionPool.isReady && elapsed >= DETECT_INTERVAL_MS) {
             lastDetectAtMs = now
-            runDetection(detectionPool.drain())
+            runDetection(detectionPool.drain(), shiftEnabled = enabled)
         }
 
+        if (!enabled) return resampled
+
         // Streaming keeps the Hilbert filter history and mixer phase across chunks;
         // shifting each chunk in isolation distorted the 62 samples at its edges.
         return streamingShifter.process(resampled, _activeShiftHz.value, CwDeepSpectrogram.SAMPLE_RATE)
@@ -365,8 +375,16 @@ class CwDeepDecoder(
      * meant tests could only restate it, and a restated rule cannot fail when the real
      * one is wrong - four injected defects once left the whole suite green.
      */
-    private fun runDetection(sample: FloatArray) {
+    private fun runDetection(sample: FloatArray, shiftEnabled: Boolean) {
         val analysis = CwToneShifter.analyse(sample, CwDeepSpectrogram.SAMPLE_RATE)
+
+        // Published either way: the UI needs the real pitch to say why nothing decodes
+        // when shifting is off and the tone is out of range. Held through silences for
+        // the same reason the shift is - CW is gaps, and a gap is not a retune.
+        analysis.toneHz?.let { _detectedToneHz.value = it.toFloat() }
+
+        if (!shiftEnabled) return
+
         val decision = shiftDecider.accept(analysis)
         _activeShiftHz.value = decision.shiftHz
 
@@ -496,7 +514,16 @@ class CwDeepDecoder(
         _estimatedPitch.value = (absoluteBin * binHz - _activeShiftHz.value).toFloat()
 
         val mean = total / count
-        _signalStrength.value = ((bestValue - mean) / bestValue).coerceIn(0f, 1f)
+        val prominence = ((bestValue - mean) / bestValue).coerceIn(0f, 1f)
+
+        // Zero when the tone is out of range and not being shifted in. The spectrogram
+        // normalises within the window, so a tone outside it still scores well on the
+        // leakage banked up against the nearest edge - measured at 0.78 for a 1500 Hz
+        // tone, a near-full meter next to an empty transcript. The meter is a claim that
+        // something decodable is present, and in that state nothing is.
+        val outOfRange = _activeShiftHz.value == 0f &&
+            _detectedToneHz.value?.let { !CwToneShifter.isInsideWindow(it) } == true
+        _signalStrength.value = if (outOfRange) 0f else prominence
     }
 
     override fun reset() {
@@ -505,6 +532,7 @@ class CwDeepDecoder(
         _historyText.value = ""
         archiveSize = 0
         _estimatedPitch.value = null
+        _detectedToneHz.value = null
         _signalStrength.value = 0f
         _lastInferenceMs.value = 0
         // Re-detect from scratch: the operator may have retuned before resetting.

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/cw/ICwDecoder.kt

@@ -43,9 +43,25 @@ interface ICwDecoder {
      */
     val historyText: StateFlow<String>
 
-    /** Detected tone frequency in Hz, or null before a tone is found. */
+    /**
+     * Pitch of the tone the model is decoding, in Hz, or null before one is found.
+     *
+     * Derived from the spectrogram, so it can only ever report a frequency inside the
+     * model's analysis window. For the pitch of a tone the model cannot see, use
+     * [detectedToneHz].
+     */
     val estimatedPitch: StateFlow<Float?>
 
+    /**
+     * Pitch of the loudest tone in the raw audio, in Hz, or null when none stands out.
+     *
+     * Unlike [estimatedPitch] this is measured before any shifting and over the full
+     * audio bandwidth, so it can report a tone the model's window excludes — which is
+     * the only way to tell the operator that nothing is being decoded because their tone
+     * is out of range.
+     */
+    val detectedToneHz: StateFlow<Float?>
+
     /** Current shift applied to bring the tone into the model's window, 0f when idle. */
     val activeShiftHz: StateFlow<Float>
 

core/domain/src/test/java/com/rtbishop/look4sat/core/domain/cw/CwToneShifterTest.kt

@@ -94,6 +94,26 @@ class CwToneShifterTest {
         }
     }
 
+    /**
+     * The decoder runs this scan even with shifting switched off, purely to tell the
+     * operator why nothing is decoding. That only works if the scan reaches past the
+     * model's window: the spectrogram's own pitch readout cannot, being confined to the
+     * window by construction, and it reports edge leakage as though it were the tone.
+     */
+    @Test
+    fun `the scan reports tones the model window excludes`() {
+        for (tone in listOf(120.0, 250.0, 1400.0, 1500.0)) {
+            val analysis = CwToneShifter.analyse(cwTone(tone), sampleRate)
+            val reported = analysis.toneHz
+            assertNotNull("$tone Hz went undetected, so the UI has nothing to report", reported)
+            assertEquals("$tone Hz was misreported", tone, reported!!.toDouble(), 30.0)
+            assertFalse(
+                "$tone Hz must read as outside the window",
+                CwToneShifter.isInsideWindow(reported)
+            )
+        }
+    }
+
     /**
      * The waterfall draws a marker at [CwToneShifter.TARGET_HZ] to show the operator where
      * a shifted tone is being delivered. Moving the target outside the model's window, or

feature/cw/src/main/java/com/rtbishop/look4sat/feature/cw/CwDecodeScreen.kt

@@ -63,7 +63,9 @@ import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import androidx.core.content.ContextCompat
+import com.rtbishop.look4sat.core.domain.cw.CwToneShifter
 import com.rtbishop.look4sat.core.domain.repository.IContainerProvider
+import kotlin.math.roundToInt
 import com.rtbishop.look4sat.core.presentation.R as CoreR
 
 /**
@@ -97,6 +99,7 @@ fun CwDecodeScreen() {
     val historyText by decoder.historyText.collectAsState()
     val signalStrength by decoder.signalStrength.collectAsState()
     val estimatedPitch by decoder.estimatedPitch.collectAsState()
+    val detectedToneHz by decoder.detectedToneHz.collectAsState()
     val activeShiftHz by decoder.activeShiftHz.collectAsState()
     val errorMessage by decoder.errorMessage.collectAsState()
 
@@ -179,6 +182,28 @@ fun CwDecodeScreen() {
             )
         }
 
+        // What the markers cannot say on their own. The waterfall covers only the model's
+        // 400-1200 Hz window, so a tone outside it is missing from the picture entirely -
+        // and with tone shift off there is nothing to mark either. One line of text is
+        // what turns "nothing is happening" into a reason and a remedy.
+        val toneHz = detectedToneHz
+        val hint = when {
+            toneHz == null -> null
+            activeShiftHz != 0f -> stringResource(R.string.cw_tone_shifted_hint, toneHz.roundToInt())
+            CwToneShifter.isInsideWindow(toneHz) -> null
+            else -> stringResource(R.string.cw_tone_outside_hint, toneHz.roundToInt())
+        }
+        if (hint != null) {
+            Text(
+                text = hint,
+                fontSize = 11.sp,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(start = 12.dp, top = 4.dp, end = 12.dp)
+            )
+        }
+
         Text(
             text = decodedText.takeLast(64).ifEmpty { "…" },
             fontSize = 20.sp,

feature/cw/src/main/res/values-es/app_values.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="cw_tone_shifted_hint">Tono de %1$d Hz trasladado a la ventana de decodificación de 400-1200 Hz</string>
+    <string name="cw_tone_outside_hint">El tono de %1$d Hz está fuera de la ventana de decodificación de 400-1200 Hz. Active el desplazamiento de tono en Ajustes.</string>
+</resources>

feature/cw/src/main/res/values-id/app_values.xml

@@ -6,4 +6,6 @@
     <string name="cw_mic_permission">Izin mikrofon diperlukan untuk pendekodean CW</string>
     <string name="cw_grant_permission">Berikan izin</string>
     <string name="cw_open_settings">Buka pengaturan aplikasi</string>
+    <string name="cw_tone_shifted_hint">Nada %1$d Hz dipindahkan ke rentang dekode 400-1200 Hz</string>
+    <string name="cw_tone_outside_hint">Nada %1$d Hz di luar rentang dekode 400-1200 Hz. Aktifkan geser nada di Pengaturan.</string>
 </resources>

feature/cw/src/main/res/values-in/app_values.xml

@@ -6,4 +6,6 @@
     <string name="cw_mic_permission">Izin mikrofon diperlukan untuk pendekodean CW</string>
     <string name="cw_grant_permission">Berikan izin</string>
     <string name="cw_open_settings">Buka pengaturan aplikasi</string>
+    <string name="cw_tone_shifted_hint">Nada %1$d Hz dipindahkan ke rentang dekode 400-1200 Hz</string>
+    <string name="cw_tone_outside_hint">Nada %1$d Hz di luar rentang dekode 400-1200 Hz. Aktifkan geser nada di Pengaturan.</string>
 </resources>

feature/cw/src/main/res/values-ru/app_values.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="cw_tone_shifted_hint">Тон %1$d Гц перенесён в окно декодирования 400-1200 Гц</string>
+    <string name="cw_tone_outside_hint">Тон %1$d Гц находится вне окна декодирования 400-1200 Гц. Включите сдвиг тона в настройках.</string>
+</resources>

feature/cw/src/main/res/values-si/app_values.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="cw_tone_shifted_hint">%1$d Hz ස්වරය 400-1200 Hz විකේතන කවුළුවට ගෙන ගියා</string>
+    <string name="cw_tone_outside_hint">%1$d Hz ස්වරය 400-1200 Hz විකේතන කවුළුවෙන් පිටත. සැකසුම් තුළ ස්වර මාරුව සක්‍රිය කරන්න.</string>
+</resources>

feature/cw/src/main/res/values-tr/app_values.xml

@@ -6,4 +6,6 @@
     <string name="cw_mic_permission">CW çözümü için mikrofon izni gerekli</string>
     <string name="cw_grant_permission">İzin ver</string>
     <string name="cw_open_settings">Uygulama ayarlarını aç</string>
+    <string name="cw_tone_shifted_hint">%1$d Hz tonu 400-1200 Hz kod çözme aralığına taşındı</string>
+    <string name="cw_tone_outside_hint">%1$d Hz tonu 400-1200 Hz kod çözme aralığının dışında. Ayarlar\'dan ton kaydırmayı açın.</string>
 </resources>

feature/cw/src/main/res/values-uk/app_values.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="cw_tone_shifted_hint">Тон %1$d Гц перенесено у вікно декодування 400-1200 Гц</string>
+    <string name="cw_tone_outside_hint">Тон %1$d Гц перебуває поза вікном декодування 400-1200 Гц. Увімкніть зсув тону в налаштуваннях.</string>
+</resources>

feature/cw/src/main/res/values-zh/app_values.xml

@@ -6,4 +6,6 @@
     <string name="cw_mic_permission">CW 解码需要麦克风权限</string>
     <string name="cw_grant_permission">授予权限</string>
     <string name="cw_open_settings">打开应用设置</string>
+    <string name="cw_tone_shifted_hint">已将 %1$d Hz 音调搬入 400-1200 Hz 解码范围</string>
+    <string name="cw_tone_outside_hint">%1$d Hz 音调在 400-1200 Hz 解码范围外，请在设置中开启音调搬移。</string>
 </resources>

feature/cw/src/main/res/values/app_values.xml

@@ -6,4 +6,6 @@
     <string name="cw_mic_permission">Microphone permission is required for CW decoding</string>
     <string name="cw_grant_permission">Grant permission</string>
     <string name="cw_open_settings">Open app settings</string>
+    <string name="cw_tone_shifted_hint">Tone %1$d Hz moved into the 400-1200 Hz decoder window</string>
+    <string name="cw_tone_outside_hint">Tone %1$d Hz is outside the 400-1200 Hz decoder window. Enable tone shift in Settings.</string>
 </resources>