feat(ui): field-info tips and retire landscape gate

Add short English tap tips on editable controls for mobile, and remove the false “Better in landscape” overlay so portrait stays the default phone layout.

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

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

@@ -187,10 +187,11 @@ User-editable hex anchors replace the former fixed dual ramp (no product mid-sto
 - **Solución Obligatoria**: `createWideRibbonMesh` (quad strip a lo largo del centerline). Sin Points. Sin montar plano base en Instancer.
 - **Invariante**: RIBBONS ≠ POINTS; no reintroducir base plane bajo ribbons sin opacificar/`depthWrite` conscientes.
 
-### 4.4. Landscape Gate suave (portrait phone) — no lock, no pause
-- **Problema**: Forzar `orientation.lock('landscape')` falla en iOS Safari; un blocker duro atrapa al usuario en portrait.
-- **Solución Obligatoria**: Overlay soft solo en phone portrait (`width ≤ 768` y `height > width`); dismiss escribe `sessionStorage` y no re-spamea en la sesión; tablet = desktop (sin overlay). El render loop **nunca** se pausa por portrait.
-- **Invariante**: landscape-first sugerido, nunca bloqueante.
+### 4.4. Landscape Gate — RETIRED (portrait preferred)
+- **Antes**: Soft overlay en phone portrait (“Better in landscape”).
+- **Decisión**: Retirado — en producto real se ve **mejor en portrait** que de costado; el cartel era mentira UX.
+- **Solución Obligatoria**: `shouldShowLandscapeGate` → siempre `false`; clase no monta copy. No reintroducir nudge landscape sin pedido explícito.
+- **Invariante**: phone = portrait-first; no orientation lock; render loop nunca pausa por orientación.
 
 ---
 
@@ -255,6 +256,13 @@ Portable findings from VHectorLab 3D `v2.1.0` — apply if the older app shares
 
 ---
 
+### 4.13. Field-info tips ("i") — tap, not hover-only
+- **Problema**: Native `title=` tooltips fail on phone (long-press unreliable); editable fields had almost no per-control help.
+- **Solución Obligatoria**: Deep module `fieldInfo.js` — `FIELD_INFO` short EN catalog (≤28 chars), `infoTipMarkup`, `wireFieldInfo` (one tip at a time, outside/Escape closes, viewport-clamped). Wire on Arithmetic / Compare / SAE params / Spatial sliders / Visualization. Touch: `.field-info-btn` / `.field-info-tip` in `isUiTouchTarget`.
+- **Invariante**: help copy = English, short, mobile-first; do not rely on hover-only `title` for field meaning.
+
+---
+
 ## 5. Protocolo de Mantenimiento de Lecciones Aprendidas
 
 1. **Consulta Obligatoria**: El agente **DEBE** leer este archivo al iniciar cualquier tarea de implementación, diseño de shaders, navegación o refactorización.

CHANGELOG.md

@@ -5,10 +5,12 @@ All notable changes to VHectorLab 3D will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **Field-info tips ("i")** on every editable control (Arithmetic, Compare, SAE params, Spatial sliders, Visualization): short English tap tips, mobile-safe popover (not hover-only `title`).
 - **HF Space cpu-basic demo path** (`feat/hf-space-cpu-demo`): Docker torch CPU (`UV_TORCH_BACKEND=cpu`), vocab embeddings NPZ at image build, `/health.device`, navbar `ONLINE (model · device)`, ARITHMETIC `localStorage` persistence (`vl3d.arithmetic.*`), setup option 7 smoke-run + option 8 `hf` create Space (docker / cpu-basic) + push, README Space YAML frontmatter.
 
 ### Changed
 - **Repo / local folder slug**: GitHub + working copy **`vhectorlab`** (was `VHectorLab-3D`). Product name **VHectorLab 3D** unchanged; npm/manifest id stays `vhectorlab-3d`.
+- **Landscape gate retired**: no more “Better in landscape” cartel — phone portrait is preferred.
 
 ### Fixed
 - **`setup.sh` option 8**: defaults from `.env` (`HF_SPACE_ID`, `HF_SPACE_FORCE_PUSH=1`); skip create if Space exists; force-push to Space remote only (not GitHub) so Enter×N publishes over divergent predecessor history.

src/main.js

@@ -48,6 +48,7 @@ import {
   computeActivationMetrics,
   formatSaeTrainProgress,
 } from './ui/saeControlsDefaults.js';
+import { wireFieldInfo } from './ui/fieldInfo.js';
 import {
   loadArithmeticSettings,
   saveArithmeticSettings,
@@ -117,6 +118,9 @@ class VHectorLabApp {
       }
     );
 
+    // Tap/click "i" tips on editable fields (mobile-friendly; one tip at a time).
+    wireFieldInfo(document);
+
     // Left dock hosts Arithmetic OR Compare (shared collapsed state across MODE).
     this.leftDock = new CollapsibleDock({
       parent: this.appContainer,

src/style.css

@@ -280,6 +280,15 @@ canvas {
   flex-shrink: 0;
 }
 
+.compare-dim-sort .field-label-text {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.compare-dim-sort .field-info-btn {
+  margin-left: auto;
+}
+
 /* COMPARE: cosine-vs-anchor list — scroll only inside the list (§4.1 panel invariant) */
 #compare-panel .compare-results {
   flex: 1 1 auto;
@@ -492,11 +501,66 @@ canvas {
 }
 
 .input-group label {
+  display: flex;
+  align-items: center;
+  gap: 4px;
   font-size: 0.75rem;
   font-weight: 600;
   color: var(--text-muted);
 }
 
+.field-label-text {
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.field-info-btn {
+  flex: 0 0 auto;
+  width: 14px;
+  height: 14px;
+  padding: 0;
+  margin: 0;
+  border-radius: 50%;
+  border: 1px solid rgba(255, 255, 255, 0.28);
+  background: rgba(255, 255, 255, 0.08);
+  color: var(--text-muted);
+  font-size: 0.58rem;
+  font-weight: 700;
+  line-height: 1;
+  font-family: inherit;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.field-info-btn:hover,
+.field-info-btn[aria-expanded="true"] {
+  color: var(--accent-cyan);
+  border-color: rgba(0, 204, 255, 0.55);
+  background: rgba(0, 200, 255, 0.12);
+}
+
+.field-info-tip {
+  position: fixed;
+  z-index: 120;
+  max-width: min(200px, calc(100vw - 16px));
+  padding: 6px 8px;
+  border-radius: 6px;
+  border: 1px solid var(--panel-border);
+  background: rgba(12, 16, 24, 0.96);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  color: var(--text-main);
+  font-size: 0.68rem;
+  font-weight: 500;
+  line-height: 1.3;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+  pointer-events: auto;
+  word-break: break-word;
+}
+
 .input-group.positive label .op { color: var(--accent-cyan); }
 .input-group.negative label .op { color: var(--accent-red); }
 
@@ -562,6 +626,17 @@ canvas {
   line-height: 1.2;
 }
 
+.sae-toggle-with-info {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+}
+
+.sae-toggle-with-info .btn-sae-toggle {
+  flex: 1 1 auto;
+}
+
 .btn-sae-toggle {
   background: rgba(255, 255, 255, 0.06);
   color: var(--text-main);
@@ -639,6 +714,13 @@ canvas {
   gap: 2px;
 }
 
+.sae-params-panel .field-label-text {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 1 auto;
+}
+
 .sae-params-panel input {
   background: rgba(0, 0, 0, 0.35);
   border: 1px solid rgba(255, 255, 255, 0.12);
@@ -1227,7 +1309,7 @@ canvas {
 
 #visualization-controls-container .viz-color-row label {
   font-size: 0.72rem;
-  min-width: 1.4rem;
+  min-width: 2.4rem;
 }
 
 #visualization-controls-container .viz-color-hex {
@@ -1278,6 +1360,17 @@ canvas {
   color: var(--text-muted);
 }
 
+.slider-header label {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+}
+
+.slider-header .field-label-text {
+  flex: 0 1 auto;
+}
+
 .slider-val {
   font-family: monospace;
   color: var(--accent-gold);
@@ -1298,11 +1391,18 @@ canvas {
 }
 
 .viz-filter-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
   font-size: 0.8rem;
   font-weight: 600;
   color: var(--text-muted);
 }
 
+.viz-filter-label .field-label-text {
+  flex: 0 1 auto;
+}
+
 .viz-segmented {
   display: flex;
   width: 100%;
@@ -1369,12 +1469,32 @@ canvas {
 }
 
 .viz-color-row label {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
   font-size: 0.78rem;
   font-weight: 700;
   color: var(--accent-gold);
   font-family: monospace;
 }
 
+.viz-color-row label .field-label-text {
+  flex: 0 0 auto;
+}
+
+.viz-labels-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 2px;
+}
+
+.viz-labels-row .viz-labels-toggle {
+  flex: 1 1 auto;
+  margin-top: 0;
+  align-self: auto;
+}
+
 .viz-color-swatch {
   width: 32px;
   height: 24px;
@@ -1961,5 +2081,17 @@ canvas {
   #compare-panel .compare-cosine-list {
     max-height: min(180px, 32dvh);
   }
+
+  .field-info-btn {
+    width: 18px;
+    height: 18px;
+    font-size: 0.65rem;
+  }
+
+  .field-info-tip {
+    max-width: min(180px, calc(100vw - 12px));
+    font-size: 0.64rem;
+    padding: 5px 7px;
+  }
 }
 

src/ui/ComparePanel.js

@@ -1,6 +1,7 @@
 import { reorderCompareItems, sortCompareItemsByCosine } from './compareCosine.js';
 import { parseCompareInput } from './parseCompareGroups.js';
 import { saeControlsMarkup, wireSaeControls } from './SaeControls.js';
+import { FIELD_INFO, infoTipMarkup } from './fieldInfo.js';
 
 /**
  * Typical auto-manual lexicon in English (parts, fluids, systems).
@@ -124,7 +125,7 @@ export class ComparePanel {
 
       <form id="compare-form" class="sidebar-form">
         <div class="input-group">
-          <label for="compare-tokens">Tokens / Words, or GROUP_name = tokens (comma, space, or newline)</label>
+          <label for="compare-tokens"><span class="field-label-text">Tokens / Words, or GROUP_name = tokens (comma, space, or newline)</span>${infoTipMarkup(FIELD_INFO.compareTokens)}</label>
           <textarea id="compare-tokens" rows="6" placeholder="e.g. wheel, engine… or GROUP_1 = car, truck&#10;GROUP_2 = grace, hope" required></textarea>
         </div>
 
@@ -146,7 +147,7 @@ export class ComparePanel {
         <div id="compare-groups-legend" class="compare-groups-legend" hidden></div>
         <label id="compare-dim-sort-row" class="compare-dim-sort" hidden title="Reorder X axis by |mean_G1 − mean_G2| so group differences cluster on the left">
           <input type="checkbox" id="compare-dim-sort-toggle">
-          <span>Sort dims by group contrast</span>
+          <span class="field-label-text">Sort dims by group contrast</span>${infoTipMarkup(FIELD_INFO.dimSort)}
         </label>
 
         <div class="compare-cosine-header">

src/ui/LandscapeGate.js

@@ -1,9 +1,6 @@
 /**
- * Soft portrait overlay for phone viewports (roadmap D13 / Etapa B).
- *
- * Landscape = recommended. Portrait shows a dismissible overlay; after dismiss,
- * sessionStorage prevents re-spam until a new session. Does not lock orientation
- * and does not pause the render loop.
+ * Landscape gate (retired): portrait overlay was removed — phone portrait is the
+ * preferred mobile layout. Helpers remain for tests / TouchControls selectors.
  */
 
 import { MOBILE_MQ, isMobileViewport } from './CollapsibleDock.js';
@@ -42,16 +39,16 @@ export function dismissLandscapeGate(session, key = LANDSCAPE_DISMISS_KEY) {
 }
 
 /**
- * Pure visibility decision for tests / wiring.
- * @param {{ isPortrait: boolean, dismissed: boolean, isMobile: boolean }} state
+ * Always false — landscape nudge overlay retired (portrait is preferred on phone).
+ * @param {{ isPortrait?: boolean, dismissed?: boolean, isMobile?: boolean }} [_state]
  */
-export function shouldShowLandscapeGate(state) {
-  if (!state.isMobile) return false;
-  if (!state.isPortrait) return false;
-  if (state.dismissed) return false;
-  return true;
+export function shouldShowLandscapeGate(_state) {
+  return false;
 }
 
+/**
+ * No-op mount kept so callers/tests stay stable; never shows overlay.
+ */
 export class LandscapeGate {
   /**
    * @param {object} options
@@ -66,80 +63,36 @@ export class LandscapeGate {
       throw new Error('LandscapeGate requires options.parent');
     }
     this._doc = options.doc || document;
-    this._session = options.sessionStorage !== undefined
-      ? options.sessionStorage
-      : (typeof sessionStorage !== 'undefined' ? sessionStorage : null);
-    this._isMobile = typeof options.isMobile === 'function'
-      ? options.isMobile
-      : () => isMobileViewport();
-    this._isPortrait = typeof options.isPortrait === 'function'
-      ? options.isPortrait
-      : () => isPhonePortrait();
-
     this.overlay = this._doc.createElement('div');
     this.overlay.id = 'landscape-gate';
     this.overlay.className = 'landscape-gate hidden';
-    this.overlay.setAttribute('role', 'dialog');
-    this.overlay.setAttribute('aria-modal', 'false');
-    this.overlay.setAttribute('aria-labelledby', 'landscape-gate-title');
-    this.overlay.innerHTML = `
-      <div class="landscape-gate-card">
-        <div class="landscape-gate-icon" aria-hidden="true">↻</div>
-        <h2 id="landscape-gate-title">Better in landscape</h2>
-        <p class="landscape-gate-copy">Rotate your phone for a better experience. You can stay in portrait if you prefer.</p>
-        <button type="button" class="btn-primary landscape-gate-dismiss">Got it</button>
-      </div>
-    `;
-
+    this.overlay.setAttribute('hidden', '');
+    this.overlay.setAttribute('aria-hidden', 'true');
+    // Intentionally empty — no cartel/copy.
+    this.overlay.innerHTML = '';
     options.parent.appendChild(this.overlay);
-
-    this._dismissBtn = this.overlay.querySelector('.landscape-gate-dismiss');
-    this._onDismiss = () => this.dismiss();
-    this._onBackdrop = (e) => {
-      if (e.target === this.overlay) this.dismiss();
-    };
-    this._onResize = () => this.refresh();
-
-    this._dismissBtn.addEventListener('click', this._onDismiss);
-    this.overlay.addEventListener('click', this._onBackdrop);
-    if (typeof window !== 'undefined') {
-      window.addEventListener('resize', this._onResize);
-      window.addEventListener('orientationchange', this._onResize);
-    }
-
-    this.refresh();
+    this._dismissBtn = null;
   }
 
   /** @returns {boolean} */
   get isVisible() {
-    return !this.overlay.classList.contains('hidden');
+    return false;
   }
 
   refresh() {
-    const show = shouldShowLandscapeGate({
-      isMobile: this._isMobile(),
-      isPortrait: this._isPortrait(),
-      dismissed: wasLandscapeGateDismissed(this._session),
-    });
-    this.overlay.classList.toggle('hidden', !show);
+    this.overlay.classList.add('hidden');
+    this.overlay.setAttribute('hidden', '');
   }
 
   dismiss() {
-    dismissLandscapeGate(this._session);
-    this.overlay.classList.add('hidden');
+    this.refresh();
   }
 
   destroy() {
-    this._dismissBtn.removeEventListener('click', this._onDismiss);
-    this.overlay.removeEventListener('click', this._onBackdrop);
-    if (typeof window !== 'undefined') {
-      window.removeEventListener('resize', this._onResize);
-      window.removeEventListener('orientationchange', this._onResize);
-    }
     if (this.overlay.parentNode) {
       this.overlay.parentNode.removeChild(this.overlay);
     }
   }
 }
 
-export { MOBILE_MQ };
+export { MOBILE_MQ, isMobileViewport };

src/ui/SaeControls.js

@@ -7,6 +7,7 @@ import {
   saveSaeSettings,
   resolveSaeSettings,
 } from './saeControlsDefaults.js';
+import { FIELD_INFO, infoTipMarkup } from './fieldInfo.js';
 
 /**
  * @param {string} idPrefix  unique prefix so Arithmetic/Compare don't clash on ids
@@ -20,9 +21,12 @@ export function saeControlsMarkup(idPrefix) {
           <button type="submit" id="${p}-btn-primary" class="btn-primary sae-cta-main">
             PRIMARY
           </button>
-          <button type="button" id="${p}-btn-sae-toggle" class="btn-sae-toggle" aria-pressed="false">
-            Clean/Denoise (SAE)
-          </button>
+          <div class="sae-toggle-with-info">
+            <button type="button" id="${p}-btn-sae-toggle" class="btn-sae-toggle" aria-pressed="false">
+              Clean/Denoise (SAE)
+            </button>
+            ${infoTipMarkup(FIELD_INFO.saeToggle)}
+          </div>
         </div>
 
         <div class="sae-train-row">
@@ -31,11 +35,11 @@ export function saeControlsMarkup(idPrefix) {
         </div>
 
         <div id="${p}-sae-params" class="sae-params-panel hidden" hidden>
-          <label>hidden_dim (cap) <input type="number" id="${p}-sae-hidden" min="32" max="32768" step="1" /></label>
-          <label>k (cap) <input type="number" id="${p}-sae-k" min="1" max="4096" step="1" /></label>
-          <label>epochs <input type="number" id="${p}-sae-epochs" min="1" max="500" step="1" /></label>
-          <label>lr <input type="number" id="${p}-sae-lr" min="0.00001" max="1" step="0.0001" /></label>
-          <label>batch_size <input type="number" id="${p}-sae-batch" min="1" max="2048" step="1" /></label>
+          <label><span class="field-label-text">hidden_dim (cap) ${infoTipMarkup(FIELD_INFO.saeHidden)}</span><input type="number" id="${p}-sae-hidden" min="32" max="32768" step="1" /></label>
+          <label><span class="field-label-text">k (cap) ${infoTipMarkup(FIELD_INFO.saeK)}</span><input type="number" id="${p}-sae-k" min="1" max="4096" step="1" /></label>
+          <label><span class="field-label-text">epochs ${infoTipMarkup(FIELD_INFO.saeEpochs)}</span><input type="number" id="${p}-sae-epochs" min="1" max="500" step="1" /></label>
+          <label><span class="field-label-text">lr ${infoTipMarkup(FIELD_INFO.saeLr)}</span><input type="number" id="${p}-sae-lr" min="0.00001" max="1" step="0.0001" /></label>
+          <label><span class="field-label-text">batch_size ${infoTipMarkup(FIELD_INFO.saeBatch)}</span><input type="number" id="${p}-sae-batch" min="1" max="2048" step="1" /></label>
           <p class="sae-params-hint">Trains on current Visualize scope. Dims/epochs auto-scale for speed (MPS/CUDA when available).</p>
         </div>
 

src/ui/Sidebar.js

@@ -1,3 +1,5 @@
+import { FIELD_INFO, infoTipMarkup } from './fieldInfo.js';
+
 /**
  * Left Sidebar Control Panel component for A - B + C Vector Arithmetic operations.
  */
@@ -21,17 +23,17 @@ export class Sidebar {
 
       <form id="arithmetic-form" class="sidebar-form">
         <div class="input-group positive">
-          <label for="word-a"><span class="op">+</span> Base Word A</label>
+          <label for="word-a"><span class="field-label-text"><span class="op">+</span> Base Word A</span>${infoTipMarkup(FIELD_INFO.wordA)}</label>
           <input type="text" id="word-a" value="king" required autocomplete="off" />
         </div>
 
         <div class="input-group negative">
-          <label for="word-b"><span class="op">-</span> Subtract Word B</label>
+          <label for="word-b"><span class="field-label-text"><span class="op">-</span> Subtract Word B</span>${infoTipMarkup(FIELD_INFO.wordB)}</label>
           <input type="text" id="word-b" value="man" required autocomplete="off" />
         </div>
 
         <div class="input-group positive">
-          <label for="word-c"><span class="op">+</span> Add Word C</label>
+          <label for="word-c"><span class="field-label-text"><span class="op">+</span> Add Word C</span>${infoTipMarkup(FIELD_INFO.wordC)}</label>
           <input type="text" id="word-c" value="woman" required autocomplete="off" />
         </div>
 

src/ui/ThreadSliders.js

@@ -4,6 +4,7 @@ import {
   resolveSpatialDefaults,
   SPATIAL_SLIDER_BINDINGS,
 } from './spatialSliderDefaults.js';
+import { FIELD_INFO, infoTipMarkup } from './fieldInfo.js';
 
 /**
  * Returns HTML markup for the spatial sliders control panel.
@@ -25,7 +26,7 @@ export function threadSlidersMarkup(config = {}) {
   <!-- Slider 1: Spacing X -->
   <div class="slider-group">
     <div class="slider-header">
-      <label for="thread-spacing-slider">Spacing (X):</label>
+      <label for="thread-spacing-slider"><span class="field-label-text">Spacing (X):</span>${infoTipMarkup(FIELD_INFO.spacingX)}</label>
       <span id="thread-spacing-val" class="slider-val">${spacing.toFixed(2)}</span>
     </div>
     <input type="range" id="thread-spacing-slider" min="0.4" max="2.0" step="0.05" value="${spacing}" title="Double-click: restore default">
@@ -34,7 +35,7 @@ export function threadSlidersMarkup(config = {}) {
   <!-- Slider 2: Vector Distance Y -->
   <div class="slider-group">
     <div class="slider-header">
-      <label for="thread-vector-dist-slider">Vector Distance (Y):</label>
+      <label for="thread-vector-dist-slider"><span class="field-label-text">Vector Distance (Y):</span>${infoTipMarkup(FIELD_INFO.vectorDistY)}</label>
       <span id="thread-vector-dist-val" class="slider-val">${vectorDist.toFixed(1)}</span>
     </div>
     <input type="range" id="thread-vector-dist-slider" min="1.0" max="19.0" step="0.1" value="${vectorDist}" title="Double-click: restore default">
@@ -43,7 +44,7 @@ export function threadSlidersMarkup(config = {}) {
   <!-- Slider 3: Amplitude Y -->
   <div class="slider-group">
     <div class="slider-header">
-      <label for="thread-amplitude-y-slider">Amplitude (Y):</label>
+      <label for="thread-amplitude-y-slider"><span class="field-label-text">Amplitude (Y):</span>${infoTipMarkup(FIELD_INFO.amplitudeY)}</label>
       <span id="thread-amplitude-y-val" class="slider-val">${amplitudeY.toFixed(1)}</span>
     </div>
     <input type="range" id="thread-amplitude-y-slider" min="1.0" max="40.0" step="0.1" value="${amplitudeY}" title="Double-click: restore default">
@@ -52,7 +53,7 @@ export function threadSlidersMarkup(config = {}) {
   <!-- Slider 4: Width Z -->
   <div class="slider-group">
     <div class="slider-header">
-      <label for="thread-width-slider">Length (Z):</label>
+      <label for="thread-width-slider"><span class="field-label-text">Length (Z):</span>${infoTipMarkup(FIELD_INFO.lengthZ)}</label>
       <span id="thread-width-val" class="slider-val">${width.toFixed(3)}</span>
     </div>
     <input type="range" id="thread-width-slider" min="0.001" max="0.2" step="0.001" value="${width}" title="Double-click: restore default">
@@ -61,7 +62,7 @@ export function threadSlidersMarkup(config = {}) {
   <!-- Slider 5: Thickness -->
   <div class="slider-group">
     <div class="slider-header">
-      <label for="thread-thickness-slider">Point Thickness:</label>
+      <label for="thread-thickness-slider"><span class="field-label-text">Point Thickness:</span>${infoTipMarkup(FIELD_INFO.thickness)}</label>
       <span id="thread-thickness-val" class="slider-val">${thickness.toFixed(2)}</span>
     </div>
     <input type="range" id="thread-thickness-slider" min="0.01" max="0.09" step="0.01" value="${thickness}" title="Double-click: restore default">

src/ui/TouchControls.js

@@ -16,6 +16,8 @@ const UI_BLOCK_SELECTOR = [
   '#touch-controls',
   '.glass-modal',
   '.modal-overlay',
+  '.field-info-tip',
+  '.field-info-btn',
 ].join(',');
 
 /**

src/ui/VisualizationControls.js

@@ -21,6 +21,7 @@ import {
   writeCollapsedPreference,
   isMobileViewport,
 } from './CollapsibleDock.js';
+import { FIELD_INFO, infoTipMarkup } from './fieldInfo.js';
 
 export const VIZ_PANEL_COLLAPSE_KEY = `${VIZ_STORAGE_PREFIX}panelCollapsed`;
 
@@ -113,7 +114,7 @@ export function visualizationControlsMarkup(config = DEFAULT_VISUALIZATION_SETTI
     <h3 class="sliders-title">Visualization</h3>
 
     <div class="viz-filter-group">
-      <span class="viz-filter-label">Show:</span>
+      <span class="viz-filter-label"><span class="field-label-text">Show:</span>${infoTipMarkup(FIELD_INFO.vizFilter)}</span>
       <div class="viz-segmented" role="radiogroup" aria-label="Sign filter">
         <label class="viz-seg-option">
           <input type="radio" name="viz-filter-mode" value="all" ${checked('all')}>
@@ -133,17 +134,17 @@ export function visualizationControlsMarkup(config = DEFAULT_VISUALIZATION_SETTI
     <div class="viz-colors-section">
       <div class="viz-colors-title">Colors</div>
       <div class="viz-color-row">
-        <label for="viz-color-positive-hex">+1</label>
+        <label for="viz-color-positive-hex"><span class="field-label-text">+1</span>${infoTipMarkup(FIELD_INFO.colorPos)}</label>
         <input type="color" id="viz-color-positive-swatch" class="viz-color-swatch" value="${s.colorPositive}" title="Positive (+1)" aria-label="Positive color swatch">
         <input type="text" id="viz-color-positive-hex" class="viz-color-hex" value="${s.colorPositive}" maxlength="7" spellcheck="false" placeholder="#FFE600" title="Positive (+1) hex">
       </div>
       <div class="viz-color-row">
-        <label for="viz-color-zero-hex">0</label>
+        <label for="viz-color-zero-hex"><span class="field-label-text">0</span>${infoTipMarkup(FIELD_INFO.colorZero)}</label>
         <input type="color" id="viz-color-zero-swatch" class="viz-color-swatch" value="${s.colorZero}" title="Zero (0)" aria-label="Zero color swatch">
         <input type="text" id="viz-color-zero-hex" class="viz-color-hex" value="${s.colorZero}" maxlength="7" spellcheck="false" placeholder="#000000" title="Zero (0) hex">
       </div>
       <div class="viz-color-row">
-        <label for="viz-color-negative-hex">−1</label>
+        <label for="viz-color-negative-hex"><span class="field-label-text">−1</span>${infoTipMarkup(FIELD_INFO.colorNeg)}</label>
         <input type="color" id="viz-color-negative-swatch" class="viz-color-swatch" value="${s.colorNegative}" title="Negative (−1)" aria-label="Negative color swatch">
         <input type="text" id="viz-color-negative-hex" class="viz-color-hex" value="${s.colorNegative}" maxlength="7" spellcheck="false" placeholder="#9900E6" title="Negative (−1) hex">
       </div>
@@ -151,15 +152,18 @@ export function visualizationControlsMarkup(config = DEFAULT_VISUALIZATION_SETTI
 
     <div class="viz-coverage-row slider-group">
       <div class="slider-header">
-        <label for="viz-zero-coverage-slider">Zero coverage:</label>
+        <label for="viz-zero-coverage-slider"><span class="field-label-text">Zero coverage:</span>${infoTipMarkup(FIELD_INFO.zeroCoverage)}</label>
         <span id="viz-zero-coverage-val" class="slider-val">${s.zeroCoverage}%</span>
       </div>
       <input type="range" id="viz-zero-coverage-slider" min="${ZERO_COVERAGE_MIN}" max="${ZERO_COVERAGE_MAX}" step="1" value="${s.zeroCoverage}" title="How much of ± range stays at the zero color before blending to +1/−1">
     </div>
 
-    <button type="button" id="viz-labels-toggle" class="viz-labels-toggle" aria-pressed="${s.labelsVisible ? 'true' : 'false'}" title="Show or hide floating thread labels">
-      ${labelsToggleButtonText(s.labelsVisible)}
-    </button>
+    <div class="viz-labels-row">
+      <button type="button" id="viz-labels-toggle" class="viz-labels-toggle" aria-pressed="${s.labelsVisible ? 'true' : 'false'}" title="Show or hide floating thread labels">
+        ${labelsToggleButtonText(s.labelsVisible)}
+      </button>
+      ${infoTipMarkup(FIELD_INFO.labelsToggle)}
+    </div>
 
     <button type="button" id="viz-reset-btn" class="viz-reset-btn">Reset</button>
   </div>

src/ui/fieldInfo.js

@@ -0,0 +1,193 @@
+/**
+ * Compact field-info tips ("i") for editable controls.
+ * Tap/click opens a short English tip (mobile-friendly; not hover-only title).
+ */
+
+/** Soft cap so tips stay readable on phone panels. */
+export const MAX_FIELD_INFO_LEN = 28;
+
+/**
+ * Short EN help for every user-editable value/field.
+ * Keep copy ≤ MAX_FIELD_INFO_LEN.
+ */
+export const FIELD_INFO = Object.freeze({
+  wordA: 'Base term (+).',
+  wordB: 'Subtract this.',
+  wordC: 'Add this.',
+  compareTokens: 'Words or GROUP_x = list.',
+  dimSort: 'Order X by group Δ.',
+  saeToggle: 'Paint SAE activations.',
+  saeHidden: 'Max latent width.',
+  saeK: 'Keep top-K features.',
+  saeEpochs: 'Train passes.',
+  saeLr: 'Step size.',
+  saeBatch: 'Batch size.',
+  spacingX: 'Gap between threads.',
+  vectorDistY: 'Stack spacing.',
+  amplitudeY: 'Peak height.',
+  lengthZ: 'Thread depth.',
+  thickness: 'Point size.',
+  vizFilter: 'Which signs show.',
+  colorPos: 'Color at +1.',
+  colorZero: 'Color at 0.',
+  colorNeg: 'Color at −1.',
+  zeroCoverage: '% held at zero.',
+  labelsToggle: 'Floating names.',
+});
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtmlAttr(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Inline "i" button markup for a label row.
+ * @param {string} text
+ * @returns {string}
+ */
+export function infoTipMarkup(text) {
+  const t = String(text ?? '').trim();
+  if (!t) return '';
+  return (
+    `<button type="button" class="field-info-btn" aria-label="Info" ` +
+    `aria-expanded="false" data-field-info="${escapeHtmlAttr(t)}">i</button>`
+  );
+}
+
+/**
+ * Pure click resolver for one-tip-at-a-time UX.
+ * @param {unknown} openBtn currently open trigger (or null)
+ * @param {unknown} clickedBtn info button clicked, or null for outside
+ * @returns {{ action: 'open'|'close'|'noop', button?: unknown }}
+ */
+export function resolveFieldInfoClick(openBtn, clickedBtn) {
+  if (clickedBtn) {
+    if (openBtn === clickedBtn) return { action: 'close' };
+    return { action: 'open', button: clickedBtn };
+  }
+  if (openBtn) return { action: 'close' };
+  return { action: 'noop' };
+}
+
+/**
+ * Position tip near the trigger; clamp to viewport (phone-safe).
+ * @param {HTMLElement} btn
+ * @param {HTMLElement} tip
+ */
+function positionTip(btn, tip) {
+  const pad = 8;
+  const r = btn.getBoundingClientRect();
+  tip.style.visibility = 'hidden';
+  tip.style.left = '0px';
+  tip.style.top = '0px';
+  const tw = tip.offsetWidth || 160;
+  const th = tip.offsetHeight || 40;
+  let left = r.left + r.width / 2 - tw / 2;
+  let top = r.bottom + 6;
+  const vw = typeof window !== 'undefined' ? window.innerWidth : 360;
+  const vh = typeof window !== 'undefined' ? window.innerHeight : 640;
+  left = Math.max(pad, Math.min(left, vw - tw - pad));
+  if (top + th > vh - pad) {
+    top = r.top - th - 6;
+  }
+  tip.style.left = `${left}px`;
+  tip.style.top = `${Math.max(pad, top)}px`;
+  tip.style.visibility = 'visible';
+}
+
+/**
+ * Event-delegated tips for all `.field-info-btn` under root.
+ * One tip open at a time; outside click / Escape closes.
+ *
+ * @param {ParentNode} [root=document]
+ * @returns {{ close: () => void, getOpenButton: () => HTMLElement|null }}
+ */
+export function wireFieldInfo(root = document) {
+  /** @type {HTMLElement|null} */
+  let tipEl = null;
+  /** @type {HTMLElement|null} */
+  let openBtn = null;
+
+  const close = () => {
+    if (tipEl && tipEl.parentNode) tipEl.parentNode.removeChild(tipEl);
+    tipEl = null;
+    if (openBtn) openBtn.setAttribute('aria-expanded', 'false');
+    openBtn = null;
+  };
+
+  /**
+   * @param {HTMLElement} btn
+   */
+  const open = (btn) => {
+    close();
+    const text = btn.getAttribute('data-field-info') || '';
+    if (!text) return;
+    tipEl = document.createElement('div');
+    tipEl.className = 'field-info-tip';
+    tipEl.setAttribute('role', 'tooltip');
+    tipEl.textContent = text;
+    document.body.appendChild(tipEl);
+    openBtn = btn;
+    btn.setAttribute('aria-expanded', 'true');
+    positionTip(btn, tipEl);
+  };
+
+  /**
+   * @param {Event} e
+   */
+  const onClick = (e) => {
+    const target = e.target;
+    if (!target || typeof target.closest !== 'function') return;
+    if (target.closest('.field-info-tip')) return;
+
+    const btn = target.closest('.field-info-btn');
+    const inRoot = !!(btn && (root === document || (root.contains && root.contains(btn))));
+    const decision = resolveFieldInfoClick(openBtn, inRoot ? btn : null);
+
+    if (decision.action === 'open') {
+      e.preventDefault();
+      e.stopPropagation();
+      open(/** @type {HTMLElement} */ (decision.button));
+      return;
+    }
+    if (decision.action === 'close') {
+      if (inRoot) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+      close();
+    }
+  };
+
+  /**
+   * @param {KeyboardEvent} e
+   */
+  const onKeydown = (e) => {
+    if (e.key === 'Escape') close();
+  };
+
+  root.addEventListener('click', onClick);
+  if (typeof window !== 'undefined') {
+    window.addEventListener('keydown', onKeydown);
+  }
+
+  return {
+    close,
+    getOpenButton: () => openBtn,
+    /** @internal test/teardown */
+    destroy() {
+      close();
+      root.removeEventListener('click', onClick);
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('keydown', onKeydown);
+      }
+    },
+  };
+}

tests/LandscapeGate.test.js

@@ -116,8 +116,8 @@ describe('isPhonePortrait', () => {
 });
 
 describe('shouldShowLandscapeGate', () => {
-  it('shows only for mobile portrait not yet dismissed', () => {
-    expect(shouldShowLandscapeGate({ isMobile: true, isPortrait: true, dismissed: false })).toBe(true);
+  it('never shows — landscape cartel retired (portrait preferred)', () => {
+    expect(shouldShowLandscapeGate({ isMobile: true, isPortrait: true, dismissed: false })).toBe(false);
     expect(shouldShowLandscapeGate({ isMobile: true, isPortrait: true, dismissed: true })).toBe(false);
     expect(shouldShowLandscapeGate({ isMobile: true, isPortrait: false, dismissed: false })).toBe(false);
     expect(shouldShowLandscapeGate({ isMobile: false, isPortrait: true, dismissed: false })).toBe(false);
@@ -143,7 +143,7 @@ describe('LandscapeGate', () => {
     session = memorySession();
   });
 
-  it('shows overlay in phone portrait and dismisses without trapping', () => {
+  it('never shows overlay even in phone portrait', () => {
     const gate = new LandscapeGate({
       parent,
       doc: mockDoc,
@@ -152,13 +152,10 @@ describe('LandscapeGate', () => {
       isPortrait: () => true,
     });
 
-    expect(gate.isVisible).toBe(true);
-    gate._dismissBtn.click();
     expect(gate.isVisible).toBe(false);
-    expect(wasLandscapeGateDismissed(session)).toBe(true);
-
     gate.refresh();
     expect(gate.isVisible).toBe(false);
+    expect(gate.overlay.classList.contains('hidden')).toBe(true);
   });
 
   it('stays hidden on tablet/desktop and landscape phone', () => {

tests/ThreadSliders.test.js

@@ -82,6 +82,13 @@ describe('threadSlidersMarkup — ranges centered on defaults', () => {
     }
   });
 
+  it('markup includes field-info tips on each slider label', () => {
+    const html = threadSlidersMarkup();
+    expect(html.match(/class="field-info-btn"/g)?.length).toBe(5);
+    expect(html).toContain('data-field-info="Gap between threads."');
+    expect(html).toContain('data-field-info="Peak height."');
+  });
+
   it('places COMPARE|NAVIGATION|POINTS Spacing 0.7 within [0.4, 2.0]', () => {
     const html = threadSlidersMarkup({
       threadSpacing: 0.7,

tests/TouchControls.test.js

@@ -37,6 +37,15 @@ describe('isUiTouchTarget', () => {
     expect(isUiTouchTarget(child)).toBe(true);
   });
 
+  it('treats field-info tip as UI', () => {
+    const tip = {
+      className: 'field-info-tip',
+      tagName: 'DIV',
+      closest: (sel) => (sel.includes('.field-info-tip') ? tip : null),
+    };
+    expect(isUiTouchTarget(tip)).toBe(true);
+  });
+
   it('allows bare canvas', () => {
     const canvas = { tagName: 'CANVAS', closest: () => null };
     expect(isUiTouchTarget(canvas)).toBe(false);

tests/fieldInfo.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import {
+  FIELD_INFO,
+  MAX_FIELD_INFO_LEN,
+  escapeHtmlAttr,
+  infoTipMarkup,
+  resolveFieldInfoClick,
+} from '../src/ui/fieldInfo.js';
+
+describe('FIELD_INFO catalog', () => {
+  it('covers every editable control key with short English copy', () => {
+    const required = [
+      'wordA', 'wordB', 'wordC',
+      'compareTokens', 'dimSort',
+      'saeToggle', 'saeHidden', 'saeK', 'saeEpochs', 'saeLr', 'saeBatch',
+      'spacingX', 'vectorDistY', 'amplitudeY', 'lengthZ', 'thickness',
+      'vizFilter', 'colorPos', 'colorZero', 'colorNeg', 'zeroCoverage', 'labelsToggle',
+    ];
+    for (const key of required) {
+      expect(FIELD_INFO[key], key).toBeTruthy();
+      expect(FIELD_INFO[key].length, key).toBeLessThanOrEqual(MAX_FIELD_INFO_LEN);
+      expect(FIELD_INFO[key]).not.toMatch(/[\n\r\t]/);
+      expect(FIELD_INFO[key]).toMatch(/[A-Za-z]/);
+    }
+  });
+});
+
+describe('escapeHtmlAttr / infoTipMarkup', () => {
+  it('escapes quotes and angle brackets for safe attributes', () => {
+    expect(escapeHtmlAttr('a"b<c>')).toBe('a&quot;b&lt;c&gt;');
+  });
+
+  it('emits a compact i button with data-field-info', () => {
+    const html = infoTipMarkup('Gap between threads.');
+    expect(html).toContain('class="field-info-btn"');
+    expect(html).toContain('data-field-info="Gap between threads."');
+    expect(html).toMatch(/>i</);
+  });
+
+  it('returns empty string for blank text', () => {
+    expect(infoTipMarkup('')).toBe('');
+    expect(infoTipMarkup('   ')).toBe('');
+  });
+});
+
+describe('resolveFieldInfoClick', () => {
+  const btnA = { id: 'a' };
+  const btnB = { id: 'b' };
+
+  it('opens when clicking an info button with none open', () => {
+    expect(resolveFieldInfoClick(null, btnA)).toEqual({ action: 'open', button: btnA });
+  });
+
+  it('closes when clicking the same open info button', () => {
+    expect(resolveFieldInfoClick(btnA, btnA)).toEqual({ action: 'close' });
+  });
+
+  it('switches when clicking a different info button', () => {
+    expect(resolveFieldInfoClick(btnA, btnB)).toEqual({ action: 'open', button: btnB });
+  });
+
+  it('closes on outside click while a tip is open', () => {
+    expect(resolveFieldInfoClick(btnA, null)).toEqual({ action: 'close' });
+  });
+
+  it('no-ops on outside click when nothing is open', () => {
+    expect(resolveFieldInfoClick(null, null)).toEqual({ action: 'noop' });
+  });
+});

tests/visualizationControls.test.js

@@ -152,6 +152,9 @@ describe('Visualization panel collapse tab', () => {
     expect(html).toContain('Zero coverage');
     expect(html).toContain('viz-labels-toggle');
     expect(html).toContain('Hide labels');
+    expect(html).toContain('field-info-btn');
+    expect(html).toContain('data-field-info="Which signs show."');
+    expect(html).toContain('data-field-info="% held at zero."');
   });
 
   it('collapse tab is a sibling of viz-panel-body (outside card chrome)', () => {