fix: compare the feature vector against medians, not poisoned means (#41)

Author: Endika

src/application/use-cases/RecognizeSignsUseCase.ts

@@ -65,6 +65,7 @@ export class RecognizeSignsUseCase {
   private lastRawTop: readonly RawScore[] = [];
   private lastVeto: WindowVeto | null = null;
   private wordsEmitted = 0;
+  private lettersEmitted = 0;
   private lastSignature: SignatureProfile | null = null;
   /** The segmenter outlives a session, so short-window counts are read as a delta. */
   private shortWindowsAtStart = 0;
@@ -205,7 +206,10 @@ export class RecognizeSignsUseCase {
   }
 
   private append(candidate: SignCandidate, atMs: number): void {
-    this.wordsEmitted += 1;
+    // Counted apart: a panel reading "2 words" while the vocabulary was vetoed every time
+    // says the alphabet spoke, and conflating them hid exactly that.
+    if (candidate.source === 'alphabet') this.lettersEmitted += 1;
+    else this.wordsEmitted += 1;
     this.transcript = this.transcript.append({
       text: candidate.gloss.text,
       source: candidate.source,
@@ -255,6 +259,7 @@ export class RecognizeSignsUseCase {
     this.lastRawTop = [];
     this.lastVeto = null;
     this.wordsEmitted = 0;
+    this.lettersEmitted = 0;
     this.lastSignature = null;
     this.shortWindowsAtStart = this.segmenter.discardedShortWindows;
   }
@@ -275,6 +280,7 @@ export class RecognizeSignsUseCase {
       lastRawTop: this.lastRawTop,
       lastVeto: this.lastVeto,
       wordsEmitted: this.wordsEmitted,
+      lettersEmitted: this.lettersEmitted,
       lastSignature: this.lastSignature,
     };
   }

src/domain/recognition/value-objects/RecognitionDiagnostics.ts

@@ -59,7 +59,10 @@ export interface RecognitionDiagnostics {
   /** Unfiltered best guesses for the last window, below the thresholds included. */
   readonly lastRawTop: readonly RawScore[];
   readonly lastVeto: WindowVeto | null;
+  /** Vocabulary words only. Fingerspelled letters are counted separately below. */
   readonly wordsEmitted: number;
+  /** Letters from the alphabet engine, which speaks even while the vocabulary is silent. */
+  readonly lettersEmitted: number;
   /** What the model was actually fed for the last window. Null until one is classified. */
   readonly lastSignature: SignatureProfile | null;
 }
@@ -77,5 +80,6 @@ export const EMPTY_DIAGNOSTICS: RecognitionDiagnostics = {
   lastRawTop: [],
   lastVeto: null,
   wordsEmitted: 0,
+  lettersEmitted: 0,
   lastSignature: null,
 };

src/presentation/components/DiagnosticsPanel.ts

@@ -6,17 +6,24 @@ import {
 } from '@domain/recognition/value-objects/RecognitionDiagnostics';
 
 /**
- * The same statistics measured over SWL-LSE's test split — `tools/train`, 598 recordings.
+ * The same statistics over SWL-LSE's test split — `tools/train`, 598 recordings.
  *
- * Shown beside the live numbers because the model scores near-noise in the browser while
- * measuring 0.741 offline, and feature parity with the trainer is already verified. So the
- * input differs, and the part whose numbers do not match is where.
+ * Medians, not means. The mean of a hand block is 3.37 and its median 0.73: three of the
+ * sixty-nine floats are the wrist relative to the torso, and on the 0.01% of frames where
+ * MediaPipe collapses shoulder width to nearly zero that division reaches six figures. A
+ * mean reference flagged a perfectly healthy vector as broken by a factor of three.
  */
 const EXPECTED: Record<string, { empty: number; magnitude: number }> = {
-  'Mano derecha': { empty: 0.238, magnitude: 3.37 },
-  'Mano izquierda': { empty: 0.377, magnitude: 3.61 },
-  Torso: { empty: 0.0, magnitude: 0.515 },
-  Cara: { empty: 0.002, magnitude: 0.157 },
+  'Mano derecha': { empty: 0.238, magnitude: 0.73 },
+  'Mano izquierda': { empty: 0.377, magnitude: 0.73 },
+  Torso: { empty: 0.0, magnitude: 0.51 },
+  Cara: { empty: 0.002, magnitude: 0.15 },
+};
+
+const VETO_LABELS: Record<WindowVeto, string> = {
+  classifier: 'el modelo: ninguna opción llegó a su mínimo',
+  stabilizer: 'el estabilizador: el modelo respondió pero se quedó corto',
+  duplicate: 'repetido: mismo signo que el anterior',
 };
 
 /**
@@ -26,12 +33,6 @@ const EXPECTED: Record<string, { empty: number; magnitude: number }> = {
  * deployed page, so a dev-only panel would never once be looked at while the bug is
  * reproducing.
  */
-const VETO_LABELS: Record<WindowVeto, string> = {
-  classifier: 'el modelo: ninguna opción llegó a su mínimo',
-  stabilizer: 'el estabilizador: el modelo respondió pero se quedó corto',
-  duplicate: 'repetido: mismo signo que el anterior',
-};
-
 export class DiagnosticsPanel {
   private open = false;
   private latest: RecognitionDiagnostics = EMPTY_DIAGNOSTICS;
@@ -84,7 +85,8 @@ export class DiagnosticsPanel {
       ['Última ventana', d.lastWindowFrames ? `${d.lastWindowFrames} fotogramas` : '—'],
       ['Motor cargado', d.vocabularyReady ? 'sí' : 'no'],
       ['Veces consultado', `${d.vocabularyInvocations}`],
-      ['Palabras escritas', `${d.wordsEmitted}`],
+      ['Palabras del vocabulario', `${d.wordsEmitted}`],
+      ['Letras deletreadas', `${d.lettersEmitted}`],
       ['Bloqueado por', d.lastVeto ? VETO_LABELS[d.lastVeto] : '—'],
     ];