fix(hud): resolve hover activation and adaptive precision

HUD always showed 0.0000 because it ignored pointsData[index]; read the real value and format up to 32 decimals within the available slot (mobile-safe).

Co-authored-by: Cursor <cursoragent@cursor.com>

.agents/skills/dev-protocol/lessons-learned.md

@@ -246,6 +246,11 @@ Portable findings from VectorLab 3D `v2.1.0` — apply if the older app shares A
 
 **Modules shipped (reference):** `saeFilterBridge.js`, `groupStackLayout.js`, `dimContrastSort.js`; wiring in Compare panel + Instancer layout. Diagnosis: `scripts/diagnose_group_separation.py`. Roadmap: `roadmap/compare-group-contrast-viz.md`.
 
+### 4.12. Bottom HUD hover activation (POINTS / RIBBONS)
+- **Problema**: `ACTIVATION` siempre `0.0000` — `Interaction` pasaba `userData` del mesh (`{ pointsData }`), y el HUD leía `userData.val` / `data.activation` (inexistentes).
+- **Solución Obligatoria**: Resolver vía `resolveHoverTelemetry` → `pointsData[index].activation` (POINTS) o `userData.activations` + face/`index` (RIBBONS / continuity). Formatear con `formatActivationValue` (hasta 32 decimales, shrink + scientific si el slot es angosto; label `ACT:` en mobile). `title` tooltip con valor completo.
+- **Invariante**: telemetría de hover ≠ normalización de color; mostrar valor **crudo** del embedding/activación en ese índice.
+
 ---
 
 ## 5. Protocolo de Mantenimiento de Lecciones Aprendidas

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to VectorLab 3D will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+- **HUD ACTIVATION stuck at 0.0000**: resolve hover from `pointsData[index]` / ribbon `activations`; adaptive precision up to 32 decimals (shrink / scientific / `ACT:` on narrow mobile slots).
+
 ## [2.1.0] - 2026-08-02
 
 ### Added

src/engine/Interaction.js

@@ -60,6 +60,7 @@ export class Interaction {
             object: hit.object,
             index: index,
             point: hit.point,
+            face: hit.face || null,
             userData: hit.object.userData
           });
         }

src/style.css

@@ -790,12 +790,24 @@ canvas {
   display: flex;
   align-items: center;
   gap: 8px;
+  min-width: 0;
+}
+
+.hud-center {
+  flex: 1 1 auto;
+  justify-content: center;
+  overflow: hidden;
+}
+
+.hud-left, .hud-right {
+  flex: 0 1 auto;
 }
 
 .hud-label {
   color: var(--text-muted);
   font-size: 0.7rem;
   font-weight: 700;
+  flex-shrink: 0;
 }
 
 .hud-val { font-family: monospace; font-weight: 600; color: var(--text-main); }
@@ -806,10 +818,30 @@ canvas {
   border-radius: 4px;
   font-size: 0.7rem;
   font-weight: 700;
+  flex-shrink: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 28vw;
 }
 
-.hud-highlight { font-family: monospace; font-weight: 700; }
-.hud-token-text { font-weight: 700; color: var(--accent-gold); }
+.hud-highlight {
+  font-family: monospace;
+  font-weight: 700;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: clip;
+  min-width: 0;
+  max-width: 100%;
+}
+.hud-token-text {
+  font-weight: 700;
+  color: var(--accent-gold);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 22vw;
+}
 
 /* Camera pose overlay (VITE_SHOW_CAM_POSE=true) — readable POS/ROT for default-view capture */
 #camera-pose-debug {
@@ -1654,7 +1686,29 @@ canvas {
     padding: 8px 12px;
     font-size: 0.7rem;
     flex-wrap: wrap;
-    gap: 4px;
+    gap: 4px 8px;
+  }
+
+  .hud-left, .hud-right {
+    flex: 1 1 40%;
+  }
+
+  .hud-center {
+    flex: 1 1 100%;
+    order: 3;
+    justify-content: flex-start;
+  }
+
+  .hud-badge {
+    max-width: 36vw;
+  }
+
+  .hud-token-text {
+    max-width: 40vw;
+  }
+
+  .hud-highlight {
+    font-size: 0.72rem;
   }
 
   #axis-gizmo-container {

src/ui/HUD.js

@@ -3,6 +3,12 @@
  * Displays real-time X, Y, Z coordinates, activation values, and token text.
  * Optional camera pose overlay (VITE_SHOW_CAM_POSE=true).
  */
+import {
+  resolveHoverTelemetry,
+  formatActivationValue,
+  activationDisplayBudget,
+} from './hoverTelemetry.js';
+
 export class HUD {
   /**
    * @param {HTMLElement} [containerElement]
@@ -37,6 +43,19 @@ export class HUD {
     this.segmentEl = this.element.querySelector('#hud-segment');
     this.activationEl = this.element.querySelector('#hud-activation');
     this.tokenEl = this.element.querySelector('#hud-token');
+    this.centerEl = this.element.querySelector('.hud-center');
+
+    this._lastActivation = null;
+    this._resizeObserver = null;
+
+    if (typeof ResizeObserver !== 'undefined' && this.centerEl) {
+      this._resizeObserver = new ResizeObserver(() => {
+        if (this._lastActivation != null) {
+          this._renderActivation(this._lastActivation);
+        }
+      });
+      this._resizeObserver.observe(this.centerEl);
+    }
 
     this.cameraDebugEl = null;
     this.camPosEl = null;
@@ -86,27 +105,64 @@ export class HUD {
   }
 
   updateTelemetry(data) {
-    if (!data) {
+    const t = resolveHoverTelemetry(data);
+    if (!t) {
+      this._lastActivation = null;
       this.coordsEl.textContent = 'X: -- | Y: -- | Z: --';
       this.segmentEl.textContent = 'NEUTRAL SPACE';
-      this.activationEl.textContent = 'ACTIVATION: 0.000';
+      this.activationEl.textContent = 'ACTIVATION: --';
       this.activationEl.style.color = '#888888';
+      this.activationEl.removeAttribute('title');
       this.tokenEl.textContent = 'NONE';
       return;
     }
 
-    const pos = data.point || { x: 0, y: 0, z: 0 };
+    const pos = t.point || { x: 0, y: 0, z: 0 };
     this.coordsEl.textContent = `X: ${Math.round(pos.x)} | Y: ${Math.round(pos.y)} | Z: ${Math.round(pos.z)}`;
 
-    const val = data.userData?.val !== undefined ? data.userData.val : (data.activation || 0);
-    const formattedVal = val.toFixed(4);
-    this.activationEl.textContent = `ACTIVATION: ${formattedVal}`;
-    this.activationEl.style.color = val > 0.3 ? '#ffe600' : '#00ffaa';
+    this._lastActivation = t.activation;
+    this._renderActivation(t.activation);
+
+    this.segmentEl.textContent = t.type;
+    this.tokenEl.textContent = t.token;
+  }
+
+  /**
+   * @param {number} val
+   * @private
+   */
+  _renderActivation(val) {
+    const slotPx = this._activationSlotWidth();
+    const fontSize = this._activationFontSize();
+    const { maxChars, compactLabel } = activationDisplayBudget(slotPx, 'ACTIVATION: ', fontSize);
+    const label = compactLabel ? 'ACT: ' : 'ACTIVATION: ';
+    const formatted = formatActivationValue(val, { maxDecimals: 32, maxChars });
+
+    this.activationEl.textContent = `${label}${formatted}`;
+    this.activationEl.title = `ACTIVATION: ${formatActivationValue(val, { maxDecimals: 32, maxChars: 48 })}`;
+    this.activationEl.style.color = Math.abs(val) > 0.3 ? '#ffe600' : '#00ffaa';
+  }
 
-    const typeStr = (data.userData?.type || 'VECTOR').toUpperCase();
-    this.segmentEl.textContent = typeStr;
+  /** @private */
+  _activationSlotWidth() {
+    if (!this.centerEl) return 160;
+    const centerW = this.centerEl.clientWidth || 160;
+    const labelW = this.centerEl.querySelector('.hud-label')?.offsetWidth || 0;
+    const badgeW = this.segmentEl?.offsetWidth || 0;
+    const gap = 16;
+    const available = centerW - labelW - badgeW - gap;
+    // Mobile wrap: if center is tight, allow activation to use most of the bar
+    if (available < 64 && this.element?.clientWidth) {
+      return Math.max(72, Math.floor(this.element.clientWidth * 0.45));
+    }
+    return Math.max(64, available);
+  }
 
-    const tokenText = data.userData?.word || data.userData?.token || `DIM #${data.index || 0}`;
-    this.tokenEl.textContent = tokenText;
+  /** @private */
+  _activationFontSize() {
+    if (typeof window === 'undefined' || !this.activationEl) return 12;
+    const cs = window.getComputedStyle?.(this.activationEl);
+    const px = cs ? parseFloat(cs.fontSize) : 12;
+    return Number.isFinite(px) && px > 0 ? px : 12;
   }
 }

src/ui/hoverTelemetry.js

@@ -0,0 +1,183 @@
+/**
+ * Resolve hover raycast payload → HUD telemetry fields.
+ * Points meshes store per-vertex data in userData.pointsData[index].
+ */
+
+export const MAX_ACTIVATION_DECIMALS = 32;
+
+/**
+ * Map a Three.js intersect payload to display fields.
+ * @param {object|null|undefined} data
+ * @returns {{
+ *   point: { x: number, y: number, z: number } | null,
+ *   index: number | null,
+ *   activation: number,
+ *   type: string,
+ *   token: string,
+ *   dim: number | null,
+ * } | null}
+ */
+export function resolveHoverTelemetry(data) {
+  if (!data) return null;
+
+  const index = data.index != null ? data.index : null;
+  const ud = data.userData || {};
+  const pointsData = ud.pointsData;
+
+  let activation = null;
+  /** @type {Record<string, unknown>} */
+  let meta = {};
+
+  if (Array.isArray(pointsData) && index != null && pointsData[index]) {
+    const pt = pointsData[index];
+    activation = typeof pt.activation === 'number' ? pt.activation : pt.meta?.val;
+    meta = pt.meta && typeof pt.meta === 'object' ? pt.meta : {};
+  } else if (Array.isArray(ud.activations)) {
+    const actIdx = resolveActivationIndex(data, ud);
+    if (actIdx != null && actIdx >= 0 && actIdx < ud.activations.length) {
+      activation = ud.activations[actIdx];
+      meta = {
+        dim: actIdx,
+        token: ud.token,
+        type: ud.type,
+        val: activation,
+      };
+    }
+  } else if (typeof data.activation === 'number') {
+    activation = data.activation;
+  } else if (typeof ud.val === 'number') {
+    activation = ud.val;
+  }
+
+  if (typeof activation !== 'number' || !Number.isFinite(activation)) {
+    activation = 0;
+  }
+
+  const dim = meta.dim != null ? Number(meta.dim) : index;
+  const token =
+    (typeof meta.token === 'string' && meta.token)
+    || (typeof meta.word === 'string' && meta.word)
+    || (typeof ud.token === 'string' && ud.token)
+    || (typeof ud.word === 'string' && ud.word)
+    || (dim != null ? `DIM #${dim}` : '—');
+
+  const typeRaw = meta.type || ud.type || 'VECTOR';
+
+  return {
+    point: data.point || null,
+    index,
+    activation,
+    type: String(typeRaw).toUpperCase(),
+    token: String(token),
+    dim: dim != null && Number.isFinite(dim) ? dim : null,
+  };
+}
+
+/**
+ * @param {object} data
+ * @param {object} ud
+ * @returns {number|null}
+ */
+function resolveActivationIndex(data, ud) {
+  if (ud.kind === 'wideRibbon' && data.face) {
+    const a = data.face.a;
+    if (typeof a === 'number') return Math.floor(a / 2);
+  }
+  if (data.index != null && Number.isFinite(data.index)) {
+    return data.index;
+  }
+  return null;
+}
+
+/**
+ * Format an activation for the bottom HUD.
+ * Uses enough decimals to show significance (cap 32), then shrinks to fit maxChars.
+ * Tiny values that still overflow fall back to scientific notation.
+ *
+ * @param {number} value
+ * @param {{ maxDecimals?: number, maxChars?: number }} [options]
+ * @returns {string}
+ */
+export function formatActivationValue(value, options = {}) {
+  const maxDecimals = Math.min(
+    Math.max(0, options.maxDecimals ?? MAX_ACTIVATION_DECIMALS),
+    MAX_ACTIVATION_DECIMALS
+  );
+  const maxChars = Math.max(3, options.maxChars ?? 20);
+
+  if (!Number.isFinite(value)) return '--';
+  if (value === 0) return '0';
+
+  const abs = Math.abs(value);
+  let idealDecimals;
+  if (abs >= 1) {
+    idealDecimals = Math.min(maxDecimals, 6);
+  } else {
+    // Digits after decimal until first significant + a few more for nuance
+    const firstSig = Math.ceil(-Math.log10(abs));
+    idealDecimals = Math.min(maxDecimals, Math.max(4, firstSig + 4));
+  }
+
+  for (let d = idealDecimals; d >= 0; d--) {
+    const candidate = trimFixed(value, d);
+    if (candidate.length <= maxChars) {
+      // Avoid collapsing tiny non-zero to "0" — try scientific instead
+      if (Number(candidate) === 0 && value !== 0) break;
+      return candidate;
+    }
+  }
+
+  return formatScientific(value, maxChars);
+}
+
+/**
+ * Estimate how many monospace characters fit in a pixel budget.
+ * @param {number} widthPx
+ * @param {number} [fontSizePx=12]
+ * @returns {number}
+ */
+export function estimateMonospaceChars(widthPx, fontSizePx = 12) {
+  if (!(widthPx > 0) || !(fontSizePx > 0)) return 8;
+  // Typical monospace advance ≈ 0.6em
+  return Math.max(3, Math.floor(widthPx / (fontSizePx * 0.6)));
+}
+
+/**
+ * Char budget for the numeric part given total activation slot width and label.
+ * @param {number} slotWidthPx
+ * @param {string} label - e.g. "ACTIVATION: " or "ACT: "
+ * @param {number} [fontSizePx]
+ * @returns {{ maxChars: number, compactLabel: boolean }}
+ */
+export function activationDisplayBudget(slotWidthPx, label = 'ACTIVATION: ', fontSizePx = 12) {
+  const totalChars = estimateMonospaceChars(slotWidthPx, fontSizePx);
+  const labelLen = label.length;
+  let maxChars = totalChars - labelLen;
+  let compactLabel = false;
+
+  if (maxChars < 8) {
+    compactLabel = true;
+    maxChars = totalChars - 'ACT: '.length;
+  }
+  return {
+    maxChars: Math.max(4, maxChars),
+    compactLabel,
+  };
+}
+
+function trimFixed(value, decimals) {
+  if (decimals <= 0) {
+    return String(Math.round(value));
+  }
+  const fixed = value.toFixed(decimals);
+  // Keep at least one digit after decimal when present; strip trailing zeros
+  return fixed.replace(/(\.\d*?[1-9])0+$/, '$1').replace(/\.0+$/, '');
+}
+
+function formatScientific(value, maxChars) {
+  for (let p = 6; p >= 0; p--) {
+    const s = value.toExponential(p);
+    if (s.length <= maxChars) return s;
+  }
+  return value.toExponential(0);
+}

src/visualizer/Instancer.js

@@ -326,6 +326,8 @@ export class Instancer {
       }
       if (ribbonMesh) {
         ribbonMesh.userData.threadId = threadId;
+        ribbonMesh.userData.token = item.text;
+        ribbonMesh.userData.type = 'compare';
         this.activeGroup.add(ribbonMesh);
       }
 

src/visualizer/MeshFactory.js

@@ -105,6 +105,7 @@ export class MeshFactory {
     lineMesh.userData = {
       kind: 'continuityLine',
       pointCount: points.length,
+      activations: activations ? Array.from(activations) : null,
     };
 
     return lineMesh;
@@ -207,7 +208,12 @@ export class MeshFactory {
 
     const mesh = new THREE.Mesh(geometry, material);
     mesh.frustumCulled = false;
-    mesh.userData = { kind: 'wideRibbon', pointCount: n, width };
+    mesh.userData = {
+      kind: 'wideRibbon',
+      pointCount: n,
+      width,
+      activations: Array.from(acts),
+    };
     return mesh;
   }
 

tests/HUD.test.js

@@ -78,3 +78,70 @@ describe('HUD camera pose overlay', () => {
     expect(hud.camRotEl.textContent).toBe('ROT: -5.4, -51.5, 0.0');
   });
 });
+
+describe('HUD activation telemetry', () => {
+  let root;
+
+  beforeEach(() => {
+    root = document.createElement('div');
+  });
+
+  it('shows real activation from pointsData instead of 0.0000', () => {
+    const hud = new HUD(root);
+    // Node mock lacks innerHTML parsing — attach real-ish readout nodes
+    const center = document.createElement('div');
+    center.className = 'hud-center';
+    Object.defineProperty(center, 'clientWidth', { get: () => 360 });
+
+    const label = document.createElement('span');
+    label.className = 'hud-label';
+    Object.defineProperty(label, 'offsetWidth', { get: () => 100 });
+
+    const segment = document.createElement('span');
+    Object.defineProperty(segment, 'offsetWidth', { get: () => 70 });
+
+    const activation = document.createElement('span');
+    const coords = document.createElement('span');
+    const token = document.createElement('span');
+
+    center.appendChild(label);
+    center.appendChild(segment);
+    center.appendChild(activation);
+
+    hud.centerEl = center;
+    hud.segmentEl = segment;
+    hud.activationEl = activation;
+    hud.coordsEl = coords;
+    hud.tokenEl = token;
+
+    hud.updateTelemetry({
+      index: 0,
+      point: { x: 5, y: 1, z: 0 },
+      userData: {
+        pointsData: [{
+          activation: 0.0000421,
+          meta: { type: 'compare', token: 'alpha', dim: 3, val: 0.0000421 },
+        }],
+      },
+    });
+
+    expect(activation.textContent).not.toMatch(/0\.0000$/);
+    expect(activation.textContent).toMatch(/0\.0000421|4\.21e-/i);
+    expect(token.textContent).toBe('alpha');
+    expect(segment.textContent).toBe('COMPARE');
+  });
+
+  it('clears to -- when hover leaves', () => {
+    const hud = new HUD(root);
+    hud.activationEl = document.createElement('span');
+    hud.coordsEl = document.createElement('span');
+    hud.segmentEl = document.createElement('span');
+    hud.tokenEl = document.createElement('span');
+    hud.activationEl.style = {};
+    hud.activationEl.removeAttribute = () => {};
+
+    hud.updateTelemetry(null);
+    expect(hud.activationEl.textContent).toBe('ACTIVATION: --');
+    expect(hud.segmentEl.textContent).toBe('NEUTRAL SPACE');
+  });
+});

tests/hoverTelemetry.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveHoverTelemetry,
+  formatActivationValue,
+  estimateMonospaceChars,
+  activationDisplayBudget,
+  MAX_ACTIVATION_DECIMALS,
+} from '../src/ui/hoverTelemetry.js';
+
+describe('resolveHoverTelemetry', () => {
+  it('returns null for empty hover', () => {
+    expect(resolveHoverTelemetry(null)).toBeNull();
+    expect(resolveHoverTelemetry(undefined)).toBeNull();
+  });
+
+  it('reads activation from pointsData[index] (POINTS mesh)', () => {
+    const data = {
+      index: 1,
+      point: { x: 10, y: 2, z: 0 },
+      userData: {
+        pointsData: [
+          { activation: 0.01, meta: { type: 'compare', token: 'cat', dim: 0, val: 0.01 } },
+          { activation: -0.0421, meta: { type: 'compare', token: 'cat', dim: 1, val: -0.0421 } },
+        ],
+      },
+    };
+    const t = resolveHoverTelemetry(data);
+    expect(t.activation).toBe(-0.0421);
+    expect(t.token).toBe('cat');
+    expect(t.type).toBe('COMPARE');
+    expect(t.dim).toBe(1);
+    expect(t.point).toEqual({ x: 10, y: 2, z: 0 });
+  });
+
+  it('does not fall back to 0 when pointsData has a real value (regression)', () => {
+    // Legacy HUD read userData.val / data.activation — both missing on Points meshes
+    const data = {
+      index: 0,
+      point: { x: 1, y: 0, z: 0 },
+      userData: {
+        pointsData: [{ activation: 1.23e-7, meta: { dim: 0, val: 1.23e-7, type: 'res' } }],
+      },
+    };
+    expect(resolveHoverTelemetry(data).activation).toBe(1.23e-7);
+  });
+
+  it('reads activations[] on wideRibbon via face vertex index', () => {
+    const data = {
+      index: 4,
+      face: { a: 6, b: 7, c: 8 },
+      userData: {
+        kind: 'wideRibbon',
+        activations: [0.1, 0.2, 0.3, 0.4, 0.5],
+        token: 'dog',
+        type: 'compare',
+      },
+    };
+    const t = resolveHoverTelemetry(data);
+    expect(t.activation).toBe(0.4); // floor(6/2) = 3
+    expect(t.token).toBe('dog');
+  });
+
+  it('falls back to DIM #n when no token meta', () => {
+    const t = resolveHoverTelemetry({
+      index: 12,
+      userData: {
+        pointsData: [{ activation: 0.5, meta: { dim: 12, val: 0.5 } }],
+      },
+    });
+    expect(t.token).toBe('DIM #12');
+  });
+});
+
+describe('formatActivationValue', () => {
+  it('caps decimals at 32', () => {
+    expect(MAX_ACTIVATION_DECIMALS).toBe(32);
+    const tiny = 1e-30;
+    const s = formatActivationValue(tiny, { maxDecimals: 32, maxChars: 40 });
+    expect(s.includes('e') || s.length <= 40).toBe(true);
+    // Must not be the old HUD "0.0000"
+    expect(s).not.toBe('0.0000');
+    expect(Number(s)).not.toBe(0);
+  });
+
+  it('shows small magnitudes that toFixed(4) would hide', () => {
+    const s = formatActivationValue(0.00001234, { maxDecimals: 32, maxChars: 20 });
+    expect(s).not.toMatch(/^0\.0+$/);
+    expect(Math.abs(Number(s) - 0.00001234)).toBeLessThan(1e-8);
+  });
+
+  it('shrinks to fit maxChars without overflowing', () => {
+    const s = formatActivationValue(0.123456789012345, { maxDecimals: 32, maxChars: 8 });
+    expect(s.length).toBeLessThanOrEqual(8);
+    expect(s).not.toBe('0');
+  });
+
+  it('uses scientific when fixed form cannot fit', () => {
+    const s = formatActivationValue(1.23456789e-20, { maxDecimals: 32, maxChars: 10 });
+    expect(s.length).toBeLessThanOrEqual(10);
+    expect(s).toMatch(/e/i);
+  });
+
+  it('formats zero as 0', () => {
+    expect(formatActivationValue(0, { maxChars: 10 })).toBe('0');
+  });
+});
+
+describe('activationDisplayBudget', () => {
+  it('estimates monospace capacity', () => {
+    expect(estimateMonospaceChars(120, 12)).toBeGreaterThan(10);
+  });
+
+  it('switches to compact ACT: label when slot is narrow (mobile)', () => {
+    const wide = activationDisplayBudget(400, 'ACTIVATION: ', 12);
+    expect(wide.compactLabel).toBe(false);
+
+    const narrow = activationDisplayBudget(90, 'ACTIVATION: ', 11);
+    expect(narrow.compactLabel).toBe(true);
+    expect(narrow.maxChars).toBeGreaterThanOrEqual(4);
+  });
+});