feat(viz): sign filter and color anchors panel (v1.7.0)

Add Visualization controls under Spatial Controls: All/+ Only/− Only on
normalized activations, three hex anchors replacing the mid-stop ramp,
localStorage persistence, and POINTS shader uniforms.

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

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

@@ -66,15 +66,18 @@ Este archivo registra las lecciones aprendidas, invariantes de arquitectura y pa
   }
   ```
 
-### 2.2. Rampas Cromáticas Divergentes Simplificadas (Dual Color Ramps)
-Para lecturas de alta visibilidad y ligera carga computacional, implementar la paleta divergente simplificada (sin transiciones intermedias a rojo o verde):
-- **Rango Positivo ($0 \rightarrow +1$)**: Negro ($0.0$) $\rightarrow$ Naranja ($+0.50$, `#FF8000`) $\rightarrow$ Amarillo Incandescente ($+1.00$, `#FFE600`).
-- **Rango Negativo ($0 \rightarrow -1$)**: Negro ($0.0$) $\rightarrow$ Azul Eléctrico ($-0.50$, `#0040FF`) $\rightarrow$ Violeta Neón ($-1.00$, `#9900E6`).
+### 2.2. Rampas Cromáticas Divergentes (Color Anchors)
+User-editable hex anchors replace the former fixed dual ramp (no product mid-stops at ±0.5 orange/blue):
+- **+1** default `#FFE600`, **0** `#000000`, **−1** `#9900E6`.
+- Interpolation: lerp(`zero`, `positive`, t) for t≥0; lerp(`zero`, `negative`, −t) for t<0.
+- POINTS shader: uniforms `uColorPos` / `uColorNeg` / `uColorZero` (never hardcode ramp in GLSL).
+- Sign filter + colors are **global** (`vl3d.viz.*` in localStorage); filter runs on **normalized t** (ε=0.01), not raw dims.
+- Continuity lines use `LineSegments` + index pairs; wide ribbons omit quad indices for filtered pairs (keeps full vertex buffers for compare reorder).
 
 ### 2.3. Continuidad de hilo según RENDER mode (mutuamente excluyentes)
 - **POINTS**: puntos + línea fina `createRibbonMesh` (continuidad 1px).
 - **RIBBONS**: la continuidad **es** la cinta ancha (`createWideRibbonMesh`); sin plano base (el quad oscuro se veía a través de cintas transparentes). No usar `LineBasicMaterial.linewidth` (§1.4).
-- Colormap RIBBONS: rampa **divergente** VectorLab para consistencia de marca.
+- Colormap RIBBONS: rampa **divergente** VectorLab (anchors) para consistencia de marca.
 - **Retired**: `RENDER: MESH` (surface heightfield) removed in v1.6.0 — `normalizeRenderMode('MESH')` → POINTS. Do not reintroduce without an explicit product decision.
 
 ### 2.4. Optimización de Fragment Shader para Cero Activación ($|t| < 0.01$)

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to VectorLab 3D will be documented in this file.
 
+## [1.7.0] - 2026-08-02
+
+### Added
+- **Visualization Controls** (`feat/visualization-sign-color-controls`): right-dock panel under 3D Spatial Controls.
+  - Sign filter: `All | + Only | − Only` on **normalized** activations (ε=0.01); hides opposite sign and near-zero for ± only.
+  - Applies to POINTS (shader discard) and RIBBONS / continuity lines (index omission) in ARITHMETIC + COMPARE.
+  - Three hex color anchors (+1 / 0 / −1) replace the fixed mid-stop divergent ramp; defaults `#FFE600` / `#000000` / `#9900E6`.
+  - POINTS shader uniforms `uColorPos` / `uColorNeg` / `uColorZero`; live update + `localStorage` (`vl3d.viz.*`) + Reset.
+
 ## [Unreleased]
 
 ### Changed

CONTEXT.md

@@ -38,5 +38,14 @@ _Avoid_: treating Sidebar/ComparePanel as independent minimize targets; unmounti
 Soft, dismissible portrait-phone overlay that suggests rotating to landscape without locking orientation or pausing the 3D render loop.
 
 ### Wide Ribbon
-Quad-strip mesh with real lateral width following a thread centerline, colored by activation; used by `RENDER: RIBBONS` together with a translucent Base Plane. Distinct from 1px WebGL lines.
+Quad-strip mesh with real lateral width following a thread centerline, colored by activation; used by `RENDER: RIBBONS`. Distinct from 1px WebGL lines.
+
+### Visualization Controls
+Right-dock glass panel for global sign filter and divergent color anchors (below 3D Spatial Controls).
+
+### Sign Filter
+Global show mode `all | positive | negative` over **normalized** activations (post z-score/tanh); near-zero `|t| < 0.01` is treated as neutral and hidden by +/− only.
+
+### Color Anchor
+User-editable hex for normalized activations at +1, 0, and −1; replaces the former fixed dual mid-stop ramp via linear RGB lerp.
 

manifest.json

@@ -1,6 +1,6 @@
 {
   "project": "vectorlab-3d",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "bootstrap_run": false,
   "state_schema": {
     "model_name": "all-mpnet-base-v2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorlab-3d",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

roadmap/PROMPT-visualization-controls.md

@@ -0,0 +1,66 @@
+# Prompt — agente Visualization Controls (Sign filter + color anchors)
+
+Copiá y pegá el bloque siguiente en una sesión nueva. **Todas las decisiones de producto ya están cerradas** en `roadmap/visualization-sign-filters-colors.md` (2026-08-02).
+
+---
+
+```text
+Usando dev-protocol, ejecutá el roadmap Visualization Filters & Color Anchors.
+
+## Contexto
+Repo: VectorLab 3D (Python/uv + Vite/Three.js).
+Base: `main` actualizado (pull first).
+Roadmap canónico (leelo COMPLETO antes de codear):
+  `roadmap/visualization-sign-filters-colors.md`
+Lecciones: `.agents/skills/dev-protocol/lessons-learned.md`
+  (§4.5 sliders/dock derecho, §2.2 rampa divergente, §7 SemVer, §1 WebGL).
+
+## Decisiones YA CERRADAS (no re-preguntar)
+- V1: Panel nuevo debajo de “3D Spatial Controls” en right dock (mismo glass).
+- V2: Efectivo en ARITHMETIC + COMPARE.
+- V3: POINTS + RIBBONS only.
+- F1: + = >0, − = <0, near-zero |t|<0.01 (ε alineado a DivergentShading).
+- F2: “+ only” oculta − y near-zero; “− only” oculta + y near-zero.
+- F3: Radio segmentado All | + Only | − Only (default All).
+- F4: Filtrar TODA la geometría (points + continuity lines + wide ribbons).
+- C1: Tres hex anclas REEMPLAZAN la rampa fija (lerp 0↔+1 y 0↔−1; sin midstops de producto).
+- C2: Hex libre; C3 defaults #FFE600 / #000000 / #9900E6; C4 localStorage.
+- D1: Global (no per MODE|VIEW|RENDER); D2: Reset a defaults + All.
+- X1: Sin backend; X2: sin presets con nombre / export.
+- Filtrar sobre activación NORMALIZADA (post z-score/tanh), no raw suelto — documentalo.
+- POINTS shader: uniforms para colores (no hardcode GLSL ramp).
+
+## Objetivo
+UI + pipeline de color/filtro según roadmap §0–§7. TDD en helpers puros. MINOR version bump (§7).
+
+## Fuera de alcance
+- roadmap/archivo/**, backend, MESH, named palettes, per-context viz overrides.
+
+## Flujo
+1. Branch `feat/visualization-sign-color-controls` (or staged A/B/C as in roadmap §9).
+2. Implement defaults/persistence + pure filter/color tests (RED→GREEN).
+3. UI panel + wire into main.js right dock below ThreadSliders.
+4. Instancer/MeshFactory/DivergentShading: apply filter + anchors on POINTS and RIBBONS.
+5. CHANGELOG + CONTEXT terms + short lessons note; bump version (check current manifest).
+6. Vitest green + smoke checklist in roadmap §6–§7.
+7. APPROVAL GATE — report how to test; wait for explicit OK before push/merge.
+
+## Criterios de aceptación
+Ver checklist §7 del roadmap (todos los ítems).
+
+## Cómo probar
+1. `npm run dev` (+ backend).
+2. Right dock → Visualization: toggle All / + Only / − Only on POINTS then RIBBONS (Arithmetic + Compare).
+3. Edit +1/0/−1 hex; confirm live recolor; reload → persisted; Reset → defaults.
+4. Confirm lines/ribbons also lose filtered-sign geometry (not points-only).
+
+## Estilo
+No-fluff; deep modules; don’t expand scope; don’t re-ask closed IDs.
+```
+
+---
+
+## Notas para el humano
+
+- Decisiones V/F/C/D/X ya cerradas — pegá el prompt directo.
+- Si `feat/compare-group-labels` u otros no están en `main`, mergeá antes o pedile al agente que parta de `main` limpio.

roadmap/README.md

@@ -6,6 +6,8 @@ Documentos de planificación **activos** viven en esta carpeta. Históricos en *
 |---|---|---|
 | [`english-ui-i18n.md`](./english-ui-i18n.md) | English-only UI / product strings (audit → glossary gate → apply) | **Activo** |
 | [`PROMPT-english-ui.md`](./PROMPT-english-ui.md) | Prompt para agente que ejecuta el epic EN | **Activo** |
+| [`visualization-sign-filters-colors.md`](./visualization-sign-filters-colors.md) | Filtro All/+/− + anclas de color +1/0/−1 (panel Visualization) | **Activo** |
+| [`PROMPT-visualization-controls.md`](./PROMPT-visualization-controls.md) | Prompt para agente que ejecuta viz filters/colors | **Activo** |
 | [`archivo/`](./archivo/) | Epic A→E mobile/MESH/RIBBONS, specs legacy, release 1.0 | Archivado 2026-08-02 |
 
 Fuente de verdad del código: `CHANGELOG.md`, `CONTEXT.md`, `main`.

roadmap/visualization-sign-filters-colors.md

@@ -0,0 +1,222 @@
+# Roadmap — Visualization Filters & Color Anchors (Sign / Polarity Controls)
+
+**Status:** Ready for implementation handoff  
+**Date:** 2026-08-02  
+**Product:** VectorLab 3D (`lsv2`)  
+**Prompt companion:** [`PROMPT-visualization-controls.md`](./PROMPT-visualization-controls.md)
+
+> **Do not re-ask closed decisions** below. If something truly new appears, list once and ask; otherwise implement.
+
+---
+
+## 0. Goal (one sentence)
+
+Add a second glass panel under **3D Spatial Controls** (right dock) that lets the user (1) filter the 3D viz to **All / positives only / negatives only**, and (2) **replace** the divergent colormap with three user-editable hex anchors for **+1**, **−1**, and **0**, globally, with persistence and reset.
+
+---
+
+## 0.1. Closed decisions (authoritative)
+
+| ID | Topic | Decision |
+| :--- | :--- | :--- |
+| **V1** | Placement | New panel **below** existing “3D Spatial Controls” in the **right dock**, same glass / section-card style. |
+| **V2** | Modes | Visible and effective in **ARITHMETIC and COMPARE** (all workspace modes). |
+| **V3** | Render modes | Applies to **POINTS and RIBBONS** only (MESH already retired). |
+| **F1** | Sign / zero | Positive: raw or display activation `> 0`. Negative: `< 0`. Near-zero: `abs(v) < ε` with **ε = 0.01** (align with existing `|t| < 0.01` short-circuit in `DivergentShading`). Treat near-zero as **neutral / zero** for filter + color anchor `0`. |
+| **F2** | What “only + / only −” hides | **+ only:** hide negative **and** near-zero. **− only:** hide positive **and** near-zero. |
+| **F3** | Filter UI | **Radio / segmented control:** `All` \| `+ only` \| `− only`. Exactly one active. Default: `All`. |
+| **F4** | Geometry filtered | **Filter all drawn geometry** for POINTS and RIBBONS: point cloud **and** continuity lines / wide ribbons (omit vertices or break strips so filtered signs disappear). Not “points-only”. |
+| **C1** | Colormap | User colors **replace** the built-in dual ramp (no fixed mid Orange/Blue stops as product truth). Interpolation: **lerp between 0↔+1 and 0↔−1** using the three anchors. Alpha/opacity curve may stay similar to today (pow on \|t\|) unless tests force a tweak — document if changed. |
+| **C2** | Color inputs | **Free hex** (`#RRGGBB`), with validation; invalid → ignore / revert to last good. Optional native `<input type="color">` synced to hex text is OK if it stays deep/simple. |
+| **C3** | Default colors | Match **current** palette endpoints / zero: see §0.2. |
+| **C4** | Persistence | Persist filter mode + three hex colors in **`localStorage`**. |
+| **D1** | Context | **Global** — not per MODE\|VIEW\|RENDER. Same values everywhere. |
+| **D2** | Reset | Yes — explicit **Reset** control (and/or dblclick on a control restoring that field’s default, consistent with spatial sliders lesson §4.5). Reset restores filter=`All` + default hex trio. |
+| **X1** | Backend | **No API/backend changes** unless a later discovery forces it (should not). |
+| **X2** | Named presets / export | **Out of scope** for v1. |
+
+### 0.2. Default color anchors (from current ramp)
+
+Documented in `src/visualizer/DivergentShading.js` / lessons §2.2:
+
+| Anchor | Meaning | Default hex (approx from current ramp) | Notes |
+| :--- | :--- | :--- | :--- |
+| **+1** | Strong positive | `#FFE600` | Incandescent yellow at +1.00 |
+| **−1** | Strong negative | `#9900E6` | Neon violet at −1.00 |
+| **0** | Near-zero / neutral | `#000000` | Black at 0 (today also very low alpha ~0.05) |
+
+Mid stops (+0.5 orange `#FF8000`, −0.5 electric blue `#0040FF`) are **not** user controls in v1; they disappear as fixed brand stops once anchors replace the ramp (C1). Intermediate t values = linear RGB lerp in normalized t-space after z-score/tanh (same normalization pipeline as today).
+
+---
+
+## 1. Product copy (English-only UI — §4.7)
+
+Suggested labels (adjust only if glossary conflicts; keep EN):
+
+| UI | Copy |
+| :--- | :--- |
+| Panel title | `Visualization` or `Sign & Color` (pick one; prefer **`Visualization`**) |
+| Filter group | `Show:` |
+| Radio | `All` / `+ Only` / `− Only` |
+| Color section | `Colors` |
+| Fields | `+1` / `0` / `−1` (or `Positive (+1)` / `Zero (0)` / `Negative (−1)`) |
+| Reset | `Reset` |
+| Hex placeholders | `#FFE600`, `#000000`, `#9900E6` |
+
+Internal keys (examples — agent may rename for clarity but keep stable once chosen):
+
+- `vizFilterMode`: `'all' | 'positive' | 'negative'`
+- `colorPositive`, `colorZero`, `colorNegative` (hex strings)
+- `localStorage` key prefix e.g. `vl3d.viz.` (`vl3d.viz.filter`, `vl3d.viz.colorPositive`, …)
+
+---
+
+## 2. UX / layout
+
+```
+Right dock body (top → bottom):
+  [ 3D Spatial Controls ]     ← existing ThreadSliders
+  [ Visualization ]           ← NEW section-card
+      Show:  ( All | + Only | − Only )
+      Colors:
+        +1  [#______] [swatch/color]
+         0  [#______] [swatch/color]
+        −1  [#______] [swatch/color]
+      [ Reset ]
+  [ AxisGizmo ]
+```
+
+- Same CSS patterns as `#thread-sliders-container` / `.section-card` / `.slider-group`.
+- Mobile: lives in right dock (already collapses); no extra landscape rules.
+- Changing filter or color → **live update** of 3D (reuse current `refreshRender` / in-situ buffer update patterns; prefer mutating colors/visibility without full scene teardown when possible).
+
+---
+
+## 3. Technical design (recommended seams)
+
+### 3.1. Deep modules (preferred)
+
+| Module | Responsibility |
+| :--- | :--- |
+| `src/ui/visualizationControlsDefaults.js` | Defaults, `localStorage` read/write, validate hex, `resolveVisualizationSettings()` |
+| `src/ui/VisualizationControls.js` | Markup + wire events → mutate settings + `onChange` callback |
+| `src/visualizer/DivergentShading.js` (extend) | Accept optional color anchors; `getDivergentColor(val, absMax, anchors?)`; shader uniforms for POINTS material if colors are GPU-side |
+| Filter helper (pure) | `shouldShowActivation(v, mode, eps=0.01)` + `filterPointsData` / ribbon vertex mask — **unit-tested** |
+
+### 3.2. Data flow
+
+1. App loads → read `localStorage` → merge with defaults → hold `vizConfig` on `VectorLabApp` (or small store beside `sliderConfig`).
+2. Mount `VisualizationControls` under sliders in right dock (`main.js` / same place as `mountThreadSlidersUI`).
+3. On change → persist → `refreshRender()` (and/or update materials/geometries in place).
+4. `Instancer` / `MeshFactory` / `ThreadFactory` receive `vizConfig` (or read from a single getter) when building POINTS lines/points and RIBBONS.
+
+### 3.3. Filter semantics (F4A)
+
+- **POINTS:** Drop points that fail the filter from the Points cloud; rebuild or rewrite buffers. Continuity `Line` (`createRibbonMesh`): only include consecutive segments where endpoints pass (or drop vertices that fail — avoid leaving misleading bridges across hidden signs). Prefer **omit failing vertices** and break the line into multiple `Line` segments / or use discontinuous indices — pick simplest robust approach; document in lessons.
+- **RIBBONS (`createWideRibbonMesh`):** Same activation array — skip or split strips so hidden signs are not drawn. Do **not** leave full ribbon colored only on one side while filter says “+ only”.
+- **Filter input value:** Use the **same activation** used for coloring after the project’s normalization choice. Clarify in impl: filter on **raw embedding dim value** vs **z-score/tanh normalized t**.  
+  **Recommendation (lock unless blocked):** filter on **normalized t** (post `calculateZScoreNormalized`), so ε=0.01 matches the shader short-circuit and “zero color” band. State this explicitly in code comments + tests.
+
+### 3.4. Color replacement (C1)
+
+- `getDivergentColor` / GLSL fragment path must use anchors:
+  - `t >= 0`: lerp(`colorZero`, `colorPositive`, t)  (with near-zero short-circuit → `colorZero` + low alpha)
+  - `t < 0`: lerp(`colorZero`, `colorNegative`, -t)
+- Remove dependency on hard-coded orange/blue mid stops when custom anchors are active (always, in v1 — anchors always drive the ramp).
+- POINTS `ShaderMaterial`: today embeds ramp in GLSL — **must** gain uniforms (or CPU attribute colors) so live hex edits update without shader string rebuild every frame. Prefer **uniforms** `uColorPos`, `uColorNeg`, `uColorZero`.
+- CPU paths (`getDivergentColor` for lines/ribbons vertex colors) must share the **same** math as GPU (pure function + tests).
+
+### 3.5. Persistence
+
+- On load: invalid hex → fallback to default for that key.
+- On Reset: write defaults back to `localStorage`.
+- Do not key by MODE/VIEW/RENDER (D1).
+
+### 3.6. Versioning
+
+- Capability add → **MINOR** bump per lessons-learned **§7** (e.g. `1.7.0` → `1.8.0` if `1.7.0` already shipped with groups; check `manifest.json` / Navbar at start of work).
+- Sync `manifest.json`, `package.json`, Navbar `version-tag`, `CHANGELOG` section.
+- No build numbers as product version (§7.3).
+
+---
+
+## 4. Files likely touched
+
+| Area | Paths |
+| :--- | :--- |
+| UI | `src/ui/VisualizationControls.js` (new), `src/ui/visualizationControlsDefaults.js` (new), `src/style.css`, `src/main.js` |
+| Shading | `src/visualizer/DivergentShading.js`, `src/visualizer/MeshFactory.js`, possibly `ThreadFactory.js` |
+| Render | `src/visualizer/Instancer.js` (pass vizConfig into mount paths) |
+| State (optional) | `src/core/State.js` only if you want viz settings in AppState — **not required**; local app field + localStorage is enough |
+| Tests | `tests/visualizationControls*.test.js`, extend `tests/DivergentShading.test.js`, ribbon/points filter tests |
+| Docs | `CHANGELOG.md`, `CONTEXT.md` (new terms), `lessons-learned.md` short § |
+
+**Do not touch:** `roadmap/archivo/**`, backend (X1), unrelated roadmaps.
+
+---
+
+## 5. CONTEXT glossary terms to add
+
+- **Visualization Controls:** Right-dock panel for sign filter + divergent color anchors.
+- **Sign Filter:** Global show mode `all | positive | negative` over normalized activations.
+- **Color Anchor:** User hex for normalized activations at +1, 0, −1 replacing the fixed dual ramp.
+
+---
+
+## 6. Test plan (TDD where harness exists)
+
+### Unit
+- [ ] `shouldShowActivation` / filter helper: all / + / − × values `{1, 0.5, 0.005, -0.5, -1}`.
+- [ ] Hex validate + persist round-trip (mock `localStorage`).
+- [ ] `getDivergentColor` with custom anchors: t=1 → +1 hex; t=0 → 0 hex; t=-1 → −1 hex; t=0.5 → midpoint lerp.
+- [ ] Defaults match §0.2.
+- [ ] Reset restores defaults and `all`.
+
+### Integration / visual smoke (manual)
+- [ ] ARITHMETIC + COMPARE; POINTS + RIBBONS.
+- [ ] `+ Only` / `− Only` visibly removes opposite and near-zero geometry on both render modes.
+- [ ] Change +1 hex → peaks update live; reload page → hex + filter restored.
+- [ ] Reset → back to yellow/black/violet + All.
+- [ ] Spatial sliders + viz panel both usable in right dock; gizmo still below.
+
+---
+
+## 7. Acceptance criteria
+
+- [ ] New panel under Spatial Controls; EN copy; global; POINTS+RIBBONS; Arithmetic+Compare.
+- [ ] Segmented **All | + Only | − Only**; + hides − and |t|&lt;ε; − hides + and |t|&lt;ε.
+- [ ] Filter affects points **and** lines/ribbons (F4A).
+- [ ] Three hex anchors replace old mid-stop ramp; defaults §0.2; live update.
+- [ ] `localStorage` persistence; Reset works.
+- [ ] No backend changes; Vitest green; CHANGELOG + version MINOR; lesson note for filter-on-normalized-t + shader uniforms.
+- [ ] Approval gate before push/merge (`dev-protocol`).
+
+---
+
+## 8. Out of scope / non-goals
+
+- Per-context (MODE|VIEW|RENDER) viz presets.
+- Named palettes / export / import.
+- Filtering NAVIGATION vs ANALYSIS differently.
+- Reintroducing MESH.
+- Changing z-score/tanh pipeline itself (only consume its output).
+- i18n framework.
+
+---
+
+## 9. Implementation stages (suggested)
+
+| Stage | Branch sketch | Deliverable |
+| :--- | :--- | :--- |
+| **A** | `feat/viz-controls-settings` | Defaults module + localStorage + pure filter/color helpers + Vitest (no UI yet or stub UI). |
+| **B** | same or `feat/viz-controls-ui` | Panel UI under sliders; wire onChange → refreshRender with CPU color path working. |
+| **C** | same | Shader uniforms for POINTS; ribbon/line filter completeness; polish Reset; docs/version. |
+| **Gate** | — | Human smoke → OK → merge to `main`. |
+
+Agent may combine A–C in one branch if the diff stays reviewable.
+
+---
+
+## 10. Open residual (only if blocked)
+
+None expected. If shader uniform vs CPU attribute tradeoff is ambiguous for POINTS, prefer **uniforms** and ask only if WebGL constraints break the approach.

src/main.js

@@ -13,6 +13,11 @@ import { CustomModal } from './ui/CustomModal.js';
 import { ThreadLabels } from './ui/ThreadLabels.js';
 import { threadSlidersMarkup, wireThreadSliders, syncThreadSlidersFromConfig } from './ui/ThreadSliders.js';
 import { resolveSpatialDefaults } from './ui/spatialSliderDefaults.js';
+import {
+  visualizationControlsMarkup,
+  wireVisualizationControls,
+} from './ui/VisualizationControls.js';
+import { loadVisualizationSettings } from './ui/visualizationControlsDefaults.js';
 
 import { ComparePanel, COMPARE_AUTO_PRESETS } from './ui/ComparePanel.js';
 import { CollapsibleDock } from './ui/CollapsibleDock.js';
@@ -113,6 +118,7 @@ class VectorLabApp {
     });
 
     this.mountThreadSlidersUI();
+    this.mountVisualizationControlsUI();
 
     // 6. Interaction Callbacks
     this.interaction.onHoverCallback = (hoverData) => {
@@ -145,6 +151,23 @@ class VectorLabApp {
     });
   }
 
+  /**
+   * Visualization panel (sign filter + color anchors) below Spatial Controls.
+   */
+  mountVisualizationControlsUI() {
+    this.vizConfig = loadVisualizationSettings();
+    const wrapper = document.createElement('div');
+    wrapper.innerHTML = visualizationControlsMarkup(this.vizConfig);
+    const vizEl = wrapper.firstElementChild;
+    this.vizEl = vizEl;
+    // Below sliders, above AxisGizmo (V1).
+    this.rightDock.body.insertBefore(vizEl, this.axisGizmo.container);
+
+    wireVisualizationControls(vizEl, this.vizConfig, () => {
+      this.refreshRender();
+    });
+  }
+
   /**
    * Apply camera + spatial defaults for current MODE/VIEW/RENDER and sync slider UI.
    * Called when context changes so each combo can keep its own sweet spot.
@@ -202,7 +225,8 @@ class VectorLabApp {
           state.compareData,
           state.renderMode,
           this.sliderConfig,
-          this.viewMode
+          this.viewMode,
+          this.vizConfig
         );
         this.threadLabels.setLabels(labels);
       }
@@ -212,7 +236,8 @@ class VectorLabApp {
           state.arithmeticData,
           state.renderMode,
           this.sliderConfig,
-          this.viewMode
+          this.viewMode,
+          this.vizConfig
         );
         this.threadLabels.setLabels(labels);
       }
@@ -257,7 +282,8 @@ class VectorLabApp {
         data,
         state.renderMode,
         this.sliderConfig,
-        this.viewMode
+        this.viewMode,
+        this.vizConfig
       );
       this.threadLabels.setLabels(labels);
 
@@ -277,7 +303,8 @@ class VectorLabApp {
         data,
         state.renderMode,
         this.sliderConfig,
-        this.viewMode
+        this.viewMode,
+        this.vizConfig
       );
       this.threadLabels.setLabels(labels);
       this.comparePanel.updateCompareResults(data);

src/style.css

@@ -689,7 +689,8 @@ canvas {
 /* =============================================================================
    Thread Geometry Spatial Sliders 3D Styling (inside #right-dock)
    ============================================================================= */
-#thread-sliders-container {
+#thread-sliders-container,
+#visualization-controls-container {
   position: relative;
   top: auto;
   right: auto;
@@ -753,6 +754,131 @@ canvas {
   cursor: pointer;
 }
 
+/* Visualization Controls (sign filter + color anchors) */
+.viz-filter-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.viz-filter-label {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text-muted);
+}
+
+.viz-segmented {
+  display: flex;
+  width: 100%;
+  border: 1px solid var(--panel-border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.viz-seg-option {
+  flex: 1;
+  position: relative;
+  text-align: center;
+  cursor: pointer;
+  margin: 0;
+}
+
+.viz-seg-option input {
+  position: absolute;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.viz-seg-option span {
+  display: block;
+  padding: 6px 4px;
+  font-size: 0.72rem;
+  font-weight: 700;
+  color: var(--text-muted);
+  background: transparent;
+  border-right: 1px solid var(--panel-border);
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.viz-seg-option:last-child span {
+  border-right: none;
+}
+
+.viz-seg-option input:checked + span {
+  background: rgba(0, 229, 255, 0.18);
+  color: var(--accent-cyan);
+}
+
+.viz-seg-option:hover span {
+  color: var(--text-main, #e8eef7);
+}
+
+.viz-colors-section {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.viz-colors-title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text-muted);
+}
+
+.viz-color-row {
+  display: grid;
+  grid-template-columns: 28px 36px 1fr;
+  align-items: center;
+  gap: 8px;
+}
+
+.viz-color-row label {
+  font-size: 0.78rem;
+  font-weight: 700;
+  color: var(--accent-gold);
+  font-family: monospace;
+}
+
+.viz-color-swatch {
+  width: 32px;
+  height: 24px;
+  padding: 0;
+  border: 1px solid var(--panel-border);
+  border-radius: 4px;
+  background: transparent;
+  cursor: pointer;
+}
+
+.viz-color-hex {
+  width: 100%;
+  font-family: monospace;
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--accent-gold);
+  background: rgba(0, 0, 0, 0.35);
+  border: 1px solid var(--panel-border);
+  border-radius: 4px;
+  padding: 4px 6px;
+}
+
+.viz-reset-btn {
+  align-self: flex-start;
+  margin-top: 2px;
+  padding: 6px 12px;
+  font-size: 0.75rem;
+  font-weight: 700;
+  color: var(--accent-cyan);
+  background: transparent;
+  border: 1px solid var(--panel-border);
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.viz-reset-btn:hover {
+  border-color: var(--accent-cyan);
+  background: rgba(0, 229, 255, 0.1);
+}
+
 /* =============================================================================
    Floating Thread Labels Overlay (Glassmorphic Badges)
    ============================================================================= */
@@ -1075,7 +1201,8 @@ canvas {
     padding: 8px 6px;
   }
 
-  #thread-sliders-container {
+  #thread-sliders-container,
+  #visualization-controls-container {
     width: min(260px, calc(100vw - 64px));
     padding: 12px;
     gap: 10px;

src/ui/Navbar.js

@@ -16,7 +16,7 @@ export class Navbar {
         <div class="logo-icon">🌐</div>
         <div class="title-group">
           <h1>VECTORLAB <span class="accent-3d">3D</span></h1>
-          <span class="version-tag">v1.6.0</span>
+          <span class="version-tag">v1.7.0</span>
         </div>
       </div>
 

src/ui/VisualizationControls.js

@@ -0,0 +1,168 @@
+/**
+ * Visualization panel: sign filter + divergent color anchors (right dock).
+ */
+
+import {
+  DEFAULT_VISUALIZATION_SETTINGS,
+  normalizeHex,
+  normalizeFilterMode,
+  resolveVisualizationSettings,
+  saveVisualizationSettings,
+  resetVisualizationSettings,
+} from './visualizationControlsDefaults.js';
+
+/**
+ * @param {import('./visualizationControlsDefaults.js').VisualizationSettings} [config]
+ * @returns {string}
+ */
+export function visualizationControlsMarkup(config = DEFAULT_VISUALIZATION_SETTINGS) {
+  const s = resolveVisualizationSettings(config);
+  const checked = (mode) => (s.vizFilterMode === mode ? 'checked' : '');
+
+  return `
+<div id="visualization-controls-container" class="section-card">
+  <h3 class="sliders-title">Visualization</h3>
+
+  <div class="viz-filter-group">
+    <span class="viz-filter-label">Show:</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')}>
+        <span>All</span>
+      </label>
+      <label class="viz-seg-option">
+        <input type="radio" name="viz-filter-mode" value="positive" ${checked('positive')}>
+        <span>+ Only</span>
+      </label>
+      <label class="viz-seg-option">
+        <input type="radio" name="viz-filter-mode" value="negative" ${checked('negative')}>
+        <span>− Only</span>
+      </label>
+    </div>
+  </div>
+
+  <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>
+      <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>
+      <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>
+      <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>
+  </div>
+
+  <button type="button" id="viz-reset-btn" class="viz-reset-btn">Reset</button>
+</div>
+`;
+}
+
+/**
+ * Sync form controls from config object.
+ * @param {HTMLElement} container
+ * @param {import('./visualizationControlsDefaults.js').VisualizationSettings} config
+ */
+export function syncVisualizationControlsFromConfig(container, config) {
+  if (!container || !config) return;
+  const s = resolveVisualizationSettings(config);
+  for (const radio of container.querySelectorAll('input[name="viz-filter-mode"]')) {
+    radio.checked = radio.value === s.vizFilterMode;
+  }
+  const pairs = [
+    ['positive', s.colorPositive],
+    ['zero', s.colorZero],
+    ['negative', s.colorNegative],
+  ];
+  for (const [key, hex] of pairs) {
+    const swatch = container.querySelector(`#viz-color-${key}-swatch`);
+    const text = container.querySelector(`#viz-color-${key}-hex`);
+    if (swatch) swatch.value = hex;
+    if (text) text.value = hex;
+  }
+}
+
+/**
+ * Wire filter radios, hex/swatch inputs, and Reset.
+ * Mutates `config` in place; persists to localStorage; calls onChange.
+ *
+ * @param {HTMLElement} container
+ * @param {import('./visualizationControlsDefaults.js').VisualizationSettings} config
+ * @param {Function} [onChangeCallback]
+ * @param {{ storage?: Storage|null }} [options]
+ */
+export function wireVisualizationControls(container, config, onChangeCallback = null, options = {}) {
+  if (!container || !config) return;
+
+  const storage = options.storage !== undefined
+    ? options.storage
+    : (typeof localStorage !== 'undefined' ? localStorage : null);
+
+  const emit = () => {
+    saveVisualizationSettings(config, storage);
+    if (typeof onChangeCallback === 'function') onChangeCallback(config);
+  };
+
+  for (const radio of container.querySelectorAll('input[name="viz-filter-mode"]')) {
+    radio.addEventListener('change', () => {
+      if (!radio.checked) return;
+      config.vizFilterMode = normalizeFilterMode(radio.value);
+      emit();
+    });
+  }
+
+  const bindColor = (key, configKey) => {
+    const swatch = container.querySelector(`#viz-color-${key}-swatch`);
+    const text = container.querySelector(`#viz-color-${key}-hex`);
+    if (!swatch || !text) return;
+
+    swatch.addEventListener('input', () => {
+      const hex = normalizeHex(swatch.value);
+      if (!hex) return;
+      config[configKey] = hex;
+      text.value = hex;
+      emit();
+    });
+
+    const commitHex = () => {
+      const hex = normalizeHex(text.value);
+      if (!hex) {
+        text.value = config[configKey];
+        return;
+      }
+      config[configKey] = hex;
+      swatch.value = hex;
+      text.value = hex;
+      emit();
+    };
+
+    text.addEventListener('change', commitHex);
+    text.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        commitHex();
+      }
+    });
+  };
+
+  bindColor('positive', 'colorPositive');
+  bindColor('zero', 'colorZero');
+  bindColor('negative', 'colorNegative');
+
+  const resetBtn = container.querySelector('#viz-reset-btn');
+  if (resetBtn) {
+    resetBtn.addEventListener('click', () => {
+      const defaults = resetVisualizationSettings(storage);
+      Object.assign(config, defaults);
+      syncVisualizationControlsFromConfig(container, config);
+      if (typeof onChangeCallback === 'function') onChangeCallback(config);
+    });
+  }
+}

src/ui/visualizationControlsDefaults.js

@@ -0,0 +1,158 @@
+/**
+ * Visualization Controls defaults, hex validation, and localStorage persistence.
+ * Global (not per MODE|VIEW|RENDER). Filter applies to normalized activations (post z-score/tanh).
+ */
+
+/** @typedef {'all' | 'positive' | 'negative'} VizFilterMode */
+
+/** @typedef {{
+ *   vizFilterMode: VizFilterMode,
+ *   colorPositive: string,
+ *   colorZero: string,
+ *   colorNegative: string,
+ * }} VisualizationSettings */
+
+export const VIZ_STORAGE_PREFIX = 'vl3d.viz.';
+
+export const VIZ_STORAGE_KEYS = Object.freeze({
+  filter: `${VIZ_STORAGE_PREFIX}filter`,
+  colorPositive: `${VIZ_STORAGE_PREFIX}colorPositive`,
+  colorZero: `${VIZ_STORAGE_PREFIX}colorZero`,
+  colorNegative: `${VIZ_STORAGE_PREFIX}colorNegative`,
+});
+
+/** Default anchors match former ramp endpoints (§0.2). */
+export const DEFAULT_VIZ_COLORS = Object.freeze({
+  colorPositive: '#FFE600',
+  colorZero: '#000000',
+  colorNegative: '#9900E6',
+});
+
+export const DEFAULT_VIZ_FILTER = /** @type {VizFilterMode} */ ('all');
+
+/** @type {VisualizationSettings} */
+export const DEFAULT_VISUALIZATION_SETTINGS = Object.freeze({
+  vizFilterMode: DEFAULT_VIZ_FILTER,
+  ...DEFAULT_VIZ_COLORS,
+});
+
+const HEX_RE = /^#([0-9A-Fa-f]{6})$/;
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidHex(value) {
+  return typeof value === 'string' && HEX_RE.test(value);
+}
+
+/**
+ * Normalize hex to uppercase #RRGGBB, or null if invalid.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function normalizeHex(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  const withHash = trimmed.startsWith('#') ? trimmed : `#${trimmed}`;
+  if (!isValidHex(withHash)) return null;
+  return withHash.toUpperCase();
+}
+
+/**
+ * Parse #RRGGBB → RGB in [0, 1].
+ * @param {string} hex
+ * @returns {{ r: number, g: number, b: number }|null}
+ */
+export function hexToRgb01(hex) {
+  const normalized = normalizeHex(hex);
+  if (!normalized) return null;
+  const n = parseInt(normalized.slice(1), 16);
+  return {
+    r: ((n >> 16) & 0xff) / 255,
+    g: ((n >> 8) & 0xff) / 255,
+    b: (n & 0xff) / 255,
+  };
+}
+
+/**
+ * @param {unknown} mode
+ * @returns {VizFilterMode}
+ */
+export function normalizeFilterMode(mode) {
+  if (mode === 'positive' || mode === 'negative' || mode === 'all') return mode;
+  return DEFAULT_VIZ_FILTER;
+}
+
+/**
+ * @param {Partial<VisualizationSettings>|null|undefined} partial
+ * @returns {VisualizationSettings}
+ */
+export function resolveVisualizationSettings(partial = null) {
+  const src = partial && typeof partial === 'object' ? partial : {};
+  return {
+    vizFilterMode: normalizeFilterMode(src.vizFilterMode),
+    colorPositive: normalizeHex(src.colorPositive) || DEFAULT_VIZ_COLORS.colorPositive,
+    colorZero: normalizeHex(src.colorZero) || DEFAULT_VIZ_COLORS.colorZero,
+    colorNegative: normalizeHex(src.colorNegative) || DEFAULT_VIZ_COLORS.colorNegative,
+  };
+}
+
+/**
+ * @param {Storage|null|undefined} storage
+ * @returns {VisualizationSettings}
+ */
+export function loadVisualizationSettings(storage = typeof localStorage !== 'undefined' ? localStorage : null) {
+  if (!storage) return { ...DEFAULT_VISUALIZATION_SETTINGS };
+  try {
+    return resolveVisualizationSettings({
+      vizFilterMode: storage.getItem(VIZ_STORAGE_KEYS.filter),
+      colorPositive: storage.getItem(VIZ_STORAGE_KEYS.colorPositive),
+      colorZero: storage.getItem(VIZ_STORAGE_KEYS.colorZero),
+      colorNegative: storage.getItem(VIZ_STORAGE_KEYS.colorNegative),
+    });
+  } catch {
+    return { ...DEFAULT_VISUALIZATION_SETTINGS };
+  }
+}
+
+/**
+ * @param {VisualizationSettings} settings
+ * @param {Storage|null|undefined} storage
+ */
+export function saveVisualizationSettings(settings, storage = typeof localStorage !== 'undefined' ? localStorage : null) {
+  if (!storage) return;
+  const resolved = resolveVisualizationSettings(settings);
+  try {
+    storage.setItem(VIZ_STORAGE_KEYS.filter, resolved.vizFilterMode);
+    storage.setItem(VIZ_STORAGE_KEYS.colorPositive, resolved.colorPositive);
+    storage.setItem(VIZ_STORAGE_KEYS.colorZero, resolved.colorZero);
+    storage.setItem(VIZ_STORAGE_KEYS.colorNegative, resolved.colorNegative);
+  } catch {
+    // Quota / private mode — ignore
+  }
+}
+
+/**
+ * @param {Storage|null|undefined} storage
+ * @returns {VisualizationSettings}
+ */
+export function resetVisualizationSettings(storage = typeof localStorage !== 'undefined' ? localStorage : null) {
+  const defaults = { ...DEFAULT_VISUALIZATION_SETTINGS };
+  saveVisualizationSettings(defaults, storage);
+  return defaults;
+}
+
+/**
+ * RGB01 anchors for DivergentShading from settings hex trio.
+ * @param {VisualizationSettings} settings
+ * @returns {{ positive: {r:number,g:number,b:number}, zero: {r:number,g:number,b:number}, negative: {r:number,g:number,b:number} }}
+ */
+export function anchorsFromSettings(settings) {
+  const resolved = resolveVisualizationSettings(settings);
+  return {
+    positive: hexToRgb01(resolved.colorPositive),
+    zero: hexToRgb01(resolved.colorZero),
+    negative: hexToRgb01(resolved.colorNegative),
+  };
+}

src/visualizer/DivergentShading.js

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import { DEFAULT_VISUALIZATION_SETTINGS, anchorsFromSettings, hexToRgb01 } from '../ui/visualizationControlsDefaults.js';
+import { NEAR_ZERO_EPS } from './activationFilter.js';
 
 /**
  * Calculates Z-score standardized and Tanh normalized activations across a dataset.
@@ -31,60 +33,70 @@ export function calculateZScoreNormalized(values, scaleFactor = 1.2) {
 }
 
 /**
- * Calculates CPU color and dynamic opacity based on activation value.
- *
- * Color Ramps:
- * Positive (0 to +1): Black (0.0) -> Orange (+0.50) -> Yellow (+1.00)
- * Negative (0 to -1): Black (0.0) -> Electric Blue (-0.50) -> Violet (-1.00)
+ * Default RGB01 anchors (product defaults). Mid-stop orange/blue ramps are retired (C1).
+ */
+export const DEFAULT_COLOR_ANCHORS = anchorsFromSettings(DEFAULT_VISUALIZATION_SETTINGS);
+
+/**
+ * Linear RGB lerp.
+ * @param {{r:number,g:number,b:number}} a
+ * @param {{r:number,g:number,b:number}} b
+ * @param {number} k
+ */
+function lerpRgb(a, b, k) {
+  return {
+    r: a.r + (b.r - a.r) * k,
+    g: a.g + (b.g - a.g) * k,
+    b: a.b + (b.b - a.b) * k,
+  };
+}
+
+/**
+ * Resolve anchors object from optional override (RGB01 or settings-like).
+ * @param {object|null|undefined} anchors
+ */
+export function resolveColorAnchors(anchors) {
+  if (!anchors) return DEFAULT_COLOR_ANCHORS;
+  if (anchors.positive && anchors.zero && anchors.negative) {
+    return {
+      positive: anchors.positive,
+      zero: anchors.zero,
+      negative: anchors.negative,
+    };
+  }
+  // Hex settings shape
+  if (anchors.colorPositive || anchors.colorZero || anchors.colorNegative) {
+    return anchorsFromSettings(anchors);
+  }
+  return DEFAULT_COLOR_ANCHORS;
+}
+
+/**
+ * CPU color and dynamic opacity from normalized-ish activation.
+ * Interpolation: lerp(zero, positive, t) for t≥0; lerp(zero, negative, −t) for t<0.
+ * Near-zero |t| < 0.01 → zero anchor + alpha ≈ 0.05.
  *
  * @param {number} val - Activation value (v)
  * @param {number} [absMax=1.0] - Maximum absolute value for normalization
- * @returns {{r: number, g: number, b: number, alpha: number}} Color components in [0, 1] range
+ * @param {object|null} [anchors] - RGB01 trio or hex settings; defaults to product anchors
+ * @returns {{r: number, g: number, b: number, alpha: number}}
  */
-export function getDivergentColor(val, absMax = 1.0) {
+export function getDivergentColor(val, absMax = 1.0, anchors = null) {
   const denom = absMax > 1e-9 ? absMax : 1.0;
   let t = Math.max(-1.0, Math.min(1.0, val / denom));
   const absT = Math.abs(t);
+  const A = resolveColorAnchors(anchors);
 
-  // Computational short-circuit for |t| < 0.01
-  if (absT < 0.01) {
-    return { r: 0.0, g: 0.0, b: 0.0, alpha: 0.05 };
+  if (absT < NEAR_ZERO_EPS) {
+    return { r: A.zero.r, g: A.zero.g, b: A.zero.b, alpha: 0.05 };
   }
 
   const alpha = Math.min(Math.max(Math.pow(absT, 1.2), 0.05), 1.0);
+  const rgb = t >= 0
+    ? lerpRgb(A.zero, A.positive, t)
+    : lerpRgb(A.zero, A.negative, -t);
 
-  let r = 0.0, g = 0.0, b = 0.0;
-
-  if (t > 0) {
-    // Positive (0 to +1): Black (0.0) -> Orange (+0.50) -> Incandescent Yellow (+1.00)
-    if (t < 0.50) {
-      const k = t / 0.50;
-      r = 1.0 * k;
-      g = 0.5 * k;
-      b = 0.0;
-    } else {
-      const k = (t - 0.50) / 0.50;
-      r = 1.0;
-      g = 0.5 + 0.45 * k;
-      b = 0.0;
-    }
-  } else {
-    // Negative (0 to -1): Black (0.0) -> Electric Blue (-0.50) -> Neon Violet (-1.00)
-    const f = -t;
-    if (f < 0.50) {
-      const k = f / 0.50;
-      r = 0.0;
-      g = 0.25 * k;
-      b = 1.0 * k;
-    } else {
-      const k = (f - 0.50) / 0.50;
-      r = 0.6 * k;
-      g = 0.25 * (1.0 - k);
-      b = 1.0 * (1.0 - k) + 0.9 * k;
-    }
-  }
-
-  return { r, g, b, alpha };
+  return { r: rgb.r, g: rgb.g, b: rgb.b, alpha };
 }
 
 /**
@@ -105,13 +117,17 @@ void main() {
 `;
 
 /**
- * GLSL Fragment Shader for Dual Divergent Color Ramps (Solid Circular Points):
- * Positive (0 to +1): Black (0.0) -> Orange (+0.50) -> Incandescent Yellow (+1.00)
- * Negative (0 to -1): Black (0.0) -> Electric Blue (-0.50) -> Neon Violet (-1.00)
+ * GLSL Fragment Shader: three color anchors via uniforms + optional sign filter.
+ * Filter modes: 0=all, 1=positive only, 2=negative only (ε = uNearZeroEps).
  */
 export const divergentFragmentShader = `
 varying float vIntensity;
 uniform float baseOpacity;
+uniform vec3 uColorPos;
+uniform vec3 uColorNeg;
+uniform vec3 uColorZero;
+uniform int uFilterMode;
+uniform float uNearZeroEps;
 
 void main() {
     vec2 coord = abs(gl_PointCoord - vec2(0.5));
@@ -123,36 +139,24 @@ void main() {
     float t = clamp(vIntensity, -1.0, 1.0);
     float absT = abs(t);
 
-    // Computational short-circuit for |t| < 0.01: early return without interpolation
-    if (absT < 0.01) {
-        gl_FragColor = vec4(vec3(0.0), 0.05 * baseOpacity * solidEdge);
+    // Sign filter on normalized t (same semantics as activationFilter.js)
+    if (uFilterMode == 1) {
+        if (absT < uNearZeroEps || t <= 0.0) discard;
+    } else if (uFilterMode == 2) {
+        if (absT < uNearZeroEps || t >= 0.0) discard;
+    }
+
+    // Near-zero short-circuit → zero anchor + low alpha
+    if (absT < uNearZeroEps) {
+        gl_FragColor = vec4(uColorZero, 0.05 * baseOpacity * solidEdge);
         return;
     }
 
     float dynamicAlpha = clamp(pow(absT, 1.1), 0.05, 1.0) * baseOpacity;
 
-    vec3 color = vec3(0.0);
-
-    if (t > 0.0) {
-        // Positive (0 to +1): Black -> Orange (#FF8000) -> Yellow (#FFE600)
-        if (t < 0.50) {
-            float k = t / 0.50;
-            color = mix(vec3(0.0), vec3(1.0, 0.5, 0.0), k);
-        } else {
-            float k = (t - 0.50) / 0.50;
-            color = mix(vec3(1.0, 0.5, 0.0), vec3(1.0, 0.95, 0.0), k);
-        }
-    } else {
-        // Negative (0 to -1): Black -> Electric Blue (#0040FF) -> Neon Violet (#9900E6)
-        float f = -t;
-        if (f < 0.50) {
-            float k = f / 0.50;
-            color = mix(vec3(0.0), vec3(0.0, 0.25, 1.0), k);
-        } else {
-            float k = (f - 0.50) / 0.50;
-            color = mix(vec3(0.0, 0.25, 1.0), vec3(0.6, 0.0, 0.9), k);
-        }
-    }
+    vec3 color = t > 0.0
+        ? mix(uColorZero, uColorPos, t)
+        : mix(uColorZero, uColorNeg, -t);
 
     vec3 finalColor = color * solidEdge;
     float alpha = dynamicAlpha * solidEdge;
@@ -161,23 +165,64 @@ void main() {
 }
 `;
 
+/**
+ * Map viz filter mode → shader int.
+ * @param {'all'|'positive'|'negative'|undefined} mode
+ * @returns {number}
+ */
+export function filterModeToUniform(mode) {
+  if (mode === 'positive') return 1;
+  if (mode === 'negative') return 2;
+  return 0;
+}
+
 /**
  * Factory function creating a customized THREE.ShaderMaterial for GPU divergent shading.
  *
  * @param {number} [pointSize=10.0] - Base size of points
  * @param {number} [baseOpacity=0.7] - Overall opacity scalar
+ * @param {{
+ *   anchors?: object,
+ *   filterMode?: 'all'|'positive'|'negative',
+ * }} [options]
  * @returns {THREE.ShaderMaterial}
  */
-export function createDivergentMaterial(pointSize = 10.0, baseOpacity = 0.7) {
+export function createDivergentMaterial(pointSize = 10.0, baseOpacity = 0.7, options = {}) {
+  const A = resolveColorAnchors(options.anchors ?? null);
   return new THREE.ShaderMaterial({
     uniforms: {
       pointSize: { value: pointSize },
-      baseOpacity: { value: baseOpacity }
+      baseOpacity: { value: baseOpacity },
+      uColorPos: { value: new THREE.Vector3(A.positive.r, A.positive.g, A.positive.b) },
+      uColorNeg: { value: new THREE.Vector3(A.negative.r, A.negative.g, A.negative.b) },
+      uColorZero: { value: new THREE.Vector3(A.zero.r, A.zero.g, A.zero.b) },
+      uFilterMode: { value: filterModeToUniform(options.filterMode) },
+      uNearZeroEps: { value: NEAR_ZERO_EPS },
     },
     vertexShader: divergentVertexShader,
     fragmentShader: divergentFragmentShader,
     transparent: true,
     depthWrite: false,
-    blending: THREE.NormalBlending
+    blending: THREE.NormalBlending,
   });
 }
+
+/**
+ * Update live color/filter uniforms without rebuilding the shader string.
+ * @param {THREE.ShaderMaterial} material
+ * @param {{ anchors?: object, filterMode?: string }} options
+ */
+export function updateDivergentMaterialUniforms(material, options = {}) {
+  if (!material?.uniforms) return;
+  if (options.anchors) {
+    const A = resolveColorAnchors(options.anchors);
+    material.uniforms.uColorPos.value.set(A.positive.r, A.positive.g, A.positive.b);
+    material.uniforms.uColorNeg.value.set(A.negative.r, A.negative.g, A.negative.b);
+    material.uniforms.uColorZero.value.set(A.zero.r, A.zero.g, A.zero.b);
+  }
+  if (options.filterMode !== undefined) {
+    material.uniforms.uFilterMode.value = filterModeToUniform(options.filterMode);
+  }
+}
+
+export { hexToRgb01 };

src/visualizer/Instancer.js

@@ -56,9 +56,10 @@ export class Instancer {
    * @param {string} renderMode - "POINTS" | "RIBBONS" (unknown/retired modes → POINTS)
    * @param {Object} [spatialConfig] - Real-time spatial slider configuration { threadSpacing, threadWidth, threadThickness }
    * @param {string} [viewMode="NAVIGATION"] - "NAVIGATION" | "ANALYSIS"
+   * @param {Object} [vizConfig] - Global sign filter + color anchors
    * @returns {Array<{ id: string, text: string, type: string, origin3D: THREE.Vector3 }>} Label metadata for origins
    */
-  renderArithmeticData(arithmeticResponse, renderMode = "POINTS", spatialConfig = null, viewMode = "NAVIGATION") {
+  renderArithmeticData(arithmeticResponse, renderMode = "POINTS", spatialConfig = null, viewMode = "NAVIGATION", vizConfig = null) {
     this.clear();
     renderMode = normalizeRenderMode(renderMode);
     this.renderMode = renderMode;
@@ -147,7 +148,7 @@ export class Instancer {
       if (baselineMesh) this.activeGroup.add(baselineMesh);
     }
 
-    this._mountRenderModeGeometry(renderMode, surfaceRows, pointsData, thicknessFactor);
+    this._mountRenderModeGeometry(renderMode, surfaceRows, pointsData, thicknessFactor, vizConfig);
     return threadLabelItems;
   }
 
@@ -155,12 +156,16 @@ export class Instancer {
    * Mount POINTS | RIBBONS geometry (mutually exclusive).
    * @private
    */
-  _mountRenderModeGeometry(renderMode, surfaceRows, pointsData, thicknessFactor) {
+  _mountRenderModeGeometry(renderMode, surfaceRows, pointsData, thicknessFactor, vizConfig = null) {
+    const vizOpts = vizConfig ? { vizConfig } : {};
     if (renderMode === "RIBBONS") {
       // No base plane: translucent dark quad showed through ribbons as a hard dark rectangle.
       const ribbonWidth = Math.max(2.0, 14.0 * (thicknessFactor || 0.3));
       surfaceRows.forEach((row) => {
-        const wide = MeshFactory.createWideRibbonMesh(row.points, row.activations, { width: ribbonWidth });
+        const wide = MeshFactory.createWideRibbonMesh(row.points, row.activations, {
+          width: ribbonWidth,
+          ...vizOpts,
+        });
         if (wide) this.activeGroup.add(wide);
       });
       return;
@@ -168,11 +173,14 @@ export class Instancer {
 
     // POINTS: thin continuity lines + point cloud
     surfaceRows.forEach((row) => {
-      const ribbon = MeshFactory.createRibbonMesh(row.points, row.activations);
+      const ribbon = MeshFactory.createRibbonMesh(row.points, row.activations, vizOpts);
       this.activeGroup.add(ribbon);
     });
     if (pointsData.length) {
-      const pointsMesh = MeshFactory.createPointsMesh(pointsData, { pointSize: 15.0 * thicknessFactor });
+      const pointsMesh = MeshFactory.createPointsMesh(pointsData, {
+        pointSize: 15.0 * thicknessFactor,
+        ...vizOpts,
+      });
       pointsMesh.userData = { pointsData };
       this.activeGroup.add(pointsMesh);
     }
@@ -184,9 +192,10 @@ export class Instancer {
    * @param {string} renderMode - "POINTS" | "RIBBONS" (unknown/retired modes → POINTS)
    * @param {Object} [spatialConfig] - Real-time spatial slider configuration
    * @param {string} [viewMode="NAVIGATION"] - "NAVIGATION" | "ANALYSIS"
+   * @param {Object} [vizConfig] - Global sign filter + color anchors
    * @returns {Array<{ id: string, text: string, type: string, origin3D: THREE.Vector3 }>} Label metadata
    */
-  renderCompareData(compareResponse, renderMode = "POINTS", spatialConfig = null, viewMode = "NAVIGATION") {
+  renderCompareData(compareResponse, renderMode = "POINTS", spatialConfig = null, viewMode = "NAVIGATION", vizConfig = null) {
     this.clear();
     renderMode = normalizeRenderMode(renderMode);
     this.renderMode = renderMode;
@@ -244,12 +253,16 @@ export class Instancer {
 
       surfaceRows.push({ points: vec3D, activations });
 
+      const vizOpts = vizConfig ? { vizConfig } : {};
       let ribbonMesh = null;
       if (renderMode === "RIBBONS") {
         const ribbonWidth = Math.max(2.0, 14.0 * thicknessFactor);
-        ribbonMesh = MeshFactory.createWideRibbonMesh(vec3D, activations, { width: ribbonWidth });
+        ribbonMesh = MeshFactory.createWideRibbonMesh(vec3D, activations, {
+          width: ribbonWidth,
+          ...vizOpts,
+        });
       } else {
-        ribbonMesh = MeshFactory.createRibbonMesh(vec3D, activations);
+        ribbonMesh = MeshFactory.createRibbonMesh(vec3D, activations, vizOpts);
       }
       if (ribbonMesh) {
         ribbonMesh.userData.threadId = threadId;
@@ -290,7 +303,10 @@ export class Instancer {
     let pointsMesh = null;
     if (renderMode === "POINTS" && pointsData.length) {
       // RIBBONS must not mount the POINTS cloud (square Chebyshev dots on top of strips).
-      pointsMesh = MeshFactory.createPointsMesh(pointsData, { pointSize: 15.0 * thicknessFactor });
+      pointsMesh = MeshFactory.createPointsMesh(pointsData, {
+        pointSize: 15.0 * thicknessFactor,
+        ...(vizConfig ? { vizConfig } : {}),
+      });
       pointsMesh.userData = { pointsData };
       this.activeGroup.add(pointsMesh);
     }

src/visualizer/MeshFactory.js

@@ -1,5 +1,22 @@
 import * as THREE from 'three';
 import { createDivergentMaterial, getDivergentColor, calculateZScoreNormalized } from './DivergentShading.js';
+import { anchorsFromSettings, resolveVisualizationSettings } from '../ui/visualizationControlsDefaults.js';
+import { lineSegmentIndices, wideRibbonQuadIndices } from './activationFilter.js';
+
+/**
+ * Resolve optional vizConfig from MeshFactory options into filter mode + RGB anchors.
+ * @param {object} [options]
+ */
+function resolveVizOptions(options = {}) {
+  const viz = options.vizConfig
+    ? resolveVisualizationSettings(options.vizConfig)
+    : resolveVisualizationSettings(null);
+  return {
+    filterMode: viz.vizFilterMode,
+    anchors: anchorsFromSettings(viz),
+    viz,
+  };
+}
 
 /**
  * Factory for creating 3D Vector Point Cloud Geometries and Ribbon Lines using Divergent Activation Shading.
@@ -7,12 +24,14 @@ import { createDivergentMaterial, getDivergentColor, calculateZScoreNormalized }
 export class MeshFactory {
   /**
    * Creates a Points Cloud Mesh with GPU Divergent Activation GLSL Shader.
+   * Sign filter is applied in the fragment shader (keeps full buffers for compare reorder).
    * Enforces frustumCulled = false.
    */
   static createPointsMesh(pointsData, options = {}) {
     const geometry = new THREE.BufferGeometry();
     const positions = [];
     const rawActivations = [];
+    const { filterMode, anchors } = resolveVizOptions(options);
 
     pointsData.forEach((item) => {
       const pos = item.position;
@@ -26,7 +45,10 @@ export class MeshFactory {
     geometry.setAttribute('intensity', new THREE.Float32BufferAttribute(normIntensities, 1));
 
     const pointSize = options.pointSize || 14.0;
-    const material = createDivergentMaterial(pointSize, 1.0);
+    const material = createDivergentMaterial(pointSize, 1.0, {
+      anchors,
+      filterMode,
+    });
 
     const pointsMesh = new THREE.Points(geometry, material);
 
@@ -37,23 +59,37 @@ export class MeshFactory {
   }
 
   /**
-   * Creates a Ribbon Line connecting a sequence of 3D vector points with vertex activation colors.
+   * Continuity line for POINTS mode.
+   * Uses LineSegments + index pairs so filtered signs break continuity (F4).
+   * Full vertex buffer retained for in-situ compare reorder position updates.
    */
-  static createRibbonMesh(points, activations = null) {
+  static createRibbonMesh(points, activations = null, options = {}) {
+    const { filterMode, anchors } = resolveVizOptions(options);
     const geometry = new THREE.BufferGeometry().setFromPoints(points);
 
+    let normActivations = null;
     if (activations && activations.length === points.length) {
-      const normActivations = calculateZScoreNormalized(activations, 0.85);
+      normActivations = calculateZScoreNormalized(activations, 0.85);
       const colors = new Float32Array(points.length * 3);
-      normActivations.forEach((val, idx) => {
-        const col = getDivergentColor(val, 1.0);
+      for (let idx = 0; idx < normActivations.length; idx++) {
+        const col = getDivergentColor(normActivations[idx], 1.0, anchors);
         colors[idx * 3 + 0] = col.r;
         colors[idx * 3 + 1] = col.g;
         colors[idx * 3 + 2] = col.b;
-      });
+      }
       geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
     }
 
+    if (normActivations) {
+      const indices = lineSegmentIndices(normActivations, filterMode);
+      if (indices.length) {
+        geometry.setIndex(indices);
+      } else {
+        // No visible segments — empty draw (keep vertices for reorder).
+        geometry.setIndex([]);
+      }
+    }
+
     const material = new THREE.LineBasicMaterial({
       vertexColors: !!activations,
       color: activations ? 0xffffff : 0x00ffaa,
@@ -62,10 +98,12 @@ export class MeshFactory {
       opacity: 0.85
     });
 
-    const lineMesh = new THREE.Line(geometry, material);
-
-    // CRITICAL INVARIANT: frustumCulled = false
+    const lineMesh = new THREE.LineSegments(geometry, material);
     lineMesh.frustumCulled = false;
+    lineMesh.userData = {
+      kind: 'continuityLine',
+      pointCount: points.length,
+    };
 
     return lineMesh;
   }
@@ -96,14 +134,16 @@ export class MeshFactory {
   }
 
   /**
-   * Wide ribbon strip mesh (Etapa E / RIBBONS) — real width via quads, not Line linewidth.
+   * Wide ribbon strip mesh (RIBBONS) — real width via quads, not Line linewidth.
+   * Quad indices omit strips whose endpoints fail the sign filter (F4).
    * @param {THREE.Vector3[]} points
    * @param {number[]|null} activations
-   * @param {{ width?: number }} [options]
+   * @param {{ width?: number, vizConfig?: object }} [options]
    * @returns {THREE.Mesh|null}
    */
   static createWideRibbonMesh(points, activations = null, options = {}) {
     if (!points || points.length < 2) return null;
+    const { filterMode, anchors } = resolveVizOptions(options);
     const width = options.width ?? 3.0;
     const half = width * 0.5;
     const n = points.length;
@@ -139,7 +179,7 @@ export class MeshFactory {
       positions[iR * 3 + 1] = p.y + side.y;
       positions[iR * 3 + 2] = p.z + side.z;
 
-      const col = getDivergentColor(norm[i], 1.0);
+      const col = getDivergentColor(norm[i], 1.0, anchors);
       for (const vi of [iL, iR]) {
         colors[vi * 3] = col.r;
         colors[vi * 3 + 1] = col.g;
@@ -147,15 +187,7 @@ export class MeshFactory {
       }
     }
 
-    const indices = [];
-    for (let i = 0; i < n - 1; i++) {
-      const a = i * 2;
-      const b = a + 1;
-      const c = a + 2;
-      const d = a + 3;
-      indices.push(a, c, b);
-      indices.push(b, c, d);
-    }
+    const indices = wideRibbonQuadIndices(norm, filterMode);
 
     const geometry = new THREE.BufferGeometry();
     geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
@@ -215,7 +247,7 @@ export class MeshFactory {
   }
 
   /**
-   * Semi-transparent ground plane under ribbons (Etapa E).
+   * Semi-transparent ground plane under ribbons (legacy helper; Instancer does not mount it).
    * @param {{ width?: number, depth?: number, y?: number, color?: number, opacity?: number }} [options]
    * @returns {THREE.Mesh}
    */
@@ -264,7 +296,4 @@ export class MeshFactory {
     plane.position.z = center.z;
     return plane;
   }
-
 }
-
-

src/visualizer/activationFilter.js

@@ -0,0 +1,117 @@
+/**
+ * Sign filter over **normalized** activations (post z-score/tanh), not raw embedding dims.
+ * ε aligns with DivergentShading near-zero short-circuit (|t| < 0.01).
+ */
+
+/** @typedef {'all' | 'positive' | 'negative'} VizFilterMode */
+
+export const NEAR_ZERO_EPS = 0.01;
+
+/**
+ * Whether a normalized activation t should be drawn for the given filter mode.
+ * + only: hide negatives and near-zero. − only: hide positives and near-zero.
+ *
+ * @param {number} t - Normalized activation in roughly [-1, 1]
+ * @param {VizFilterMode} mode
+ * @param {number} [eps=NEAR_ZERO_EPS]
+ * @returns {boolean}
+ */
+export function shouldShowActivation(t, mode = 'all', eps = NEAR_ZERO_EPS) {
+  if (mode === 'all') return true;
+  const absT = Math.abs(t);
+  if (absT < eps) return false;
+  if (mode === 'positive') return t > 0;
+  if (mode === 'negative') return t < 0;
+  return true;
+}
+
+/**
+ * Boolean mask parallel to `normalized`.
+ * @param {ArrayLike<number>} normalized
+ * @param {VizFilterMode} mode
+ * @param {number} [eps]
+ * @returns {boolean[]}
+ */
+export function activationVisibilityMask(normalized, mode = 'all', eps = NEAR_ZERO_EPS) {
+  const n = normalized.length;
+  const mask = new Array(n);
+  for (let i = 0; i < n; i++) {
+    mask[i] = shouldShowActivation(normalized[i], mode, eps);
+  }
+  return mask;
+}
+
+/**
+ * Flat index pairs for THREE.LineSegments: only consecutive endpoints that both pass.
+ * Keeps full vertex buffer intact for in-situ position updates.
+ *
+ * @param {ArrayLike<number>} normalized
+ * @param {VizFilterMode} mode
+ * @param {number} [eps]
+ * @returns {number[]}
+ */
+export function lineSegmentIndices(normalized, mode = 'all', eps = NEAR_ZERO_EPS) {
+  const n = normalized.length;
+  if (n < 2) return [];
+  const indices = [];
+  for (let i = 0; i < n - 1; i++) {
+    if (
+      shouldShowActivation(normalized[i], mode, eps)
+      && shouldShowActivation(normalized[i + 1], mode, eps)
+    ) {
+      indices.push(i, i + 1);
+    }
+  }
+  return indices;
+}
+
+/**
+ * Quad strip triangle indices (same winding as MeshFactory wide ribbon) for
+ * consecutive centerline samples that both pass the filter.
+ *
+ * @param {ArrayLike<number>} normalized - one value per centerline sample
+ * @param {VizFilterMode} mode
+ * @param {number} [eps]
+ * @returns {number[]}
+ */
+export function wideRibbonQuadIndices(normalized, mode = 'all', eps = NEAR_ZERO_EPS) {
+  const n = normalized.length;
+  if (n < 2) return [];
+  const indices = [];
+  for (let i = 0; i < n - 1; i++) {
+    if (
+      !shouldShowActivation(normalized[i], mode, eps)
+      || !shouldShowActivation(normalized[i + 1], mode, eps)
+    ) {
+      continue;
+    }
+    const a = i * 2;
+    const b = a + 1;
+    const c = a + 2;
+    const d = a + 3;
+    indices.push(a, c, b);
+    indices.push(b, c, d);
+  }
+  return indices;
+}
+
+/**
+ * Filter pointsData entries by normalized activations of the whole set.
+ * Caller must pass already-normalized values aligned 1:1 with pointsData.
+ *
+ * @template T
+ * @param {T[]} pointsData
+ * @param {ArrayLike<number>} normalized
+ * @param {VizFilterMode} mode
+ * @param {number} [eps]
+ * @returns {T[]}
+ */
+export function filterPointsData(pointsData, normalized, mode = 'all', eps = NEAR_ZERO_EPS) {
+  if (!pointsData?.length) return [];
+  if (mode === 'all') return pointsData.slice();
+  const out = [];
+  for (let i = 0; i < pointsData.length; i++) {
+    if (shouldShowActivation(normalized[i], mode, eps)) out.push(pointsData[i]);
+  }
+  return out;
+}

tests/DivergentShading.test.js

@@ -1,50 +1,65 @@
 import { describe, it, expect } from 'vitest';
-import { getDivergentColor } from '../src/visualizer/DivergentShading.js';
+import { getDivergentColor, DEFAULT_COLOR_ANCHORS } from '../src/visualizer/DivergentShading.js';
 
-describe('Divergent Shading CPU Algorithm', () => {
-  it('maps peak positive (+1.0) to incandescent yellow', () => {
+describe('Divergent Shading CPU Algorithm (anchor lerp)', () => {
+  const A = DEFAULT_COLOR_ANCHORS;
+
+  it('maps peak positive (+1.0) to +1 anchor', () => {
     const { r, g, b, alpha } = getDivergentColor(1.0, 1.0);
-    expect(r).toBeCloseTo(1.0, 5);
-    expect(g).toBeCloseTo(0.95, 5);
-    expect(b).toBe(0.0);
+    expect(r).toBeCloseTo(A.positive.r, 5);
+    expect(g).toBeCloseTo(A.positive.g, 5);
+    expect(b).toBeCloseTo(A.positive.b, 5);
     expect(alpha).toBeCloseTo(1.0, 5);
   });
 
-  it('maps mid positive (+0.5) to orange', () => {
+  it('maps mid positive (+0.5) to midpoint lerp 0↔+1', () => {
     const { r, g, b } = getDivergentColor(0.5, 1.0);
-    expect(r).toBeCloseTo(1.0, 5);
-    expect(g).toBeCloseTo(0.5, 5);
-    expect(b).toBe(0.0);
+    expect(r).toBeCloseTo((A.zero.r + A.positive.r) / 2, 5);
+    expect(g).toBeCloseTo((A.zero.g + A.positive.g) / 2, 5);
+    expect(b).toBeCloseTo((A.zero.b + A.positive.b) / 2, 5);
   });
 
-  it('maps zero to black with minimum opacity (~0.05)', () => {
+  it('maps zero to zero anchor with minimum opacity (~0.05)', () => {
     const { r, g, b, alpha } = getDivergentColor(0.0, 1.0);
-    expect(r).toBe(0.0);
-    expect(g).toBe(0.0);
-    expect(b).toBe(0.0);
+    expect(r).toBeCloseTo(A.zero.r, 5);
+    expect(g).toBeCloseTo(A.zero.g, 5);
+    expect(b).toBeCloseTo(A.zero.b, 5);
     expect(alpha).toBeCloseTo(0.05, 5);
   });
 
-  it('short-circuits |t| < 0.01 to black with minimum opacity (~0.05)', () => {
+  it('short-circuits |t| < 0.01 to zero anchor with minimum opacity (~0.05)', () => {
     const { r, g, b, alpha } = getDivergentColor(0.005, 1.0);
-    expect(r).toBe(0.0);
-    expect(g).toBe(0.0);
-    expect(b).toBe(0.0);
+    expect(r).toBeCloseTo(A.zero.r, 5);
+    expect(g).toBeCloseTo(A.zero.g, 5);
+    expect(b).toBeCloseTo(A.zero.b, 5);
     expect(alpha).toBeCloseTo(0.05, 5);
   });
 
-  it('maps mid negative (-0.5) to electric blue', () => {
+  it('maps mid negative (−0.5) to midpoint lerp 0↔−1', () => {
     const { r, g, b } = getDivergentColor(-0.5, 1.0);
-    expect(r).toBeCloseTo(0.0, 5);
-    expect(g).toBeCloseTo(0.25, 5);
-    expect(b).toBeCloseTo(1.0, 5);
+    expect(r).toBeCloseTo((A.zero.r + A.negative.r) / 2, 5);
+    expect(g).toBeCloseTo((A.zero.g + A.negative.g) / 2, 5);
+    expect(b).toBeCloseTo((A.zero.b + A.negative.b) / 2, 5);
   });
 
-  it('maps peak negative (-1.0) to neon violet', () => {
+  it('maps peak negative (−1.0) to −1 anchor', () => {
     const { r, g, b, alpha } = getDivergentColor(-1.0, 1.0);
-    expect(r).toBeCloseTo(0.6, 5);
-    expect(g).toBeCloseTo(0.0, 5);
-    expect(b).toBeCloseTo(0.9, 5);
+    expect(r).toBeCloseTo(A.negative.r, 5);
+    expect(g).toBeCloseTo(A.negative.g, 5);
+    expect(b).toBeCloseTo(A.negative.b, 5);
     expect(alpha).toBeCloseTo(1.0, 5);
   });
+
+  it('accepts custom anchors', () => {
+    const custom = {
+      positive: { r: 1, g: 0, b: 0 },
+      zero: { r: 0, g: 1, b: 0 },
+      negative: { r: 0, g: 0, b: 1 },
+    };
+    const pos = getDivergentColor(1, 1, custom);
+    expect(pos.r).toBeCloseTo(1, 5);
+    expect(pos.g).toBeCloseTo(0, 5);
+    const neg = getDivergentColor(-1, 1, custom);
+    expect(neg.b).toBeCloseTo(1, 5);
+  });
 });

tests/visualizationControls.test.js

@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  DEFAULT_VISUALIZATION_SETTINGS,
+  DEFAULT_VIZ_COLORS,
+  DEFAULT_VIZ_FILTER,
+  VIZ_STORAGE_KEYS,
+  isValidHex,
+  normalizeHex,
+  hexToRgb01,
+  resolveVisualizationSettings,
+  loadVisualizationSettings,
+  saveVisualizationSettings,
+  resetVisualizationSettings,
+  anchorsFromSettings,
+} from '../src/ui/visualizationControlsDefaults.js';
+import {
+  NEAR_ZERO_EPS,
+  shouldShowActivation,
+  filterPointsData,
+  lineSegmentIndices,
+  wideRibbonQuadIndices,
+} from '../src/visualizer/activationFilter.js';
+import { getDivergentColor } from '../src/visualizer/DivergentShading.js';
+
+function mockStorage(initial = {}) {
+  const map = new Map(Object.entries(initial));
+  return {
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    setItem: (k, v) => { map.set(k, String(v)); },
+    removeItem: (k) => { map.delete(k); },
+    _map: map,
+  };
+}
+
+describe('visualizationControlsDefaults', () => {
+  it('defaults match §0.2 anchors and filter All', () => {
+    expect(DEFAULT_VIZ_FILTER).toBe('all');
+    expect(DEFAULT_VIZ_COLORS.colorPositive).toBe('#FFE600');
+    expect(DEFAULT_VIZ_COLORS.colorZero).toBe('#000000');
+    expect(DEFAULT_VIZ_COLORS.colorNegative).toBe('#9900E6');
+    expect(DEFAULT_VISUALIZATION_SETTINGS).toEqual({
+      vizFilterMode: 'all',
+      colorPositive: '#FFE600',
+      colorZero: '#000000',
+      colorNegative: '#9900E6',
+    });
+  });
+
+  it('validates and normalizes hex', () => {
+    expect(isValidHex('#FFE600')).toBe(true);
+    expect(isValidHex('#ff00')).toBe(false);
+    expect(isValidHex('not-a-color')).toBe(false);
+    expect(normalizeHex('ffe600')).toBe('#FFE600');
+    expect(normalizeHex('#abc')).toBeNull();
+  });
+
+  it('hexToRgb01 parses endpoints', () => {
+    expect(hexToRgb01('#FFE600')).toEqual({
+      r: 1,
+      g: 230 / 255,
+      b: 0,
+    });
+    expect(hexToRgb01('#000000')).toEqual({ r: 0, g: 0, b: 0 });
+    expect(hexToRgb01('#9900E6')).toEqual({
+      r: 153 / 255,
+      g: 0,
+      b: 230 / 255,
+    });
+  });
+
+  it('resolveVisualizationSettings falls back invalid hex and mode', () => {
+    const resolved = resolveVisualizationSettings({
+      vizFilterMode: 'nope',
+      colorPositive: 'bad',
+      colorZero: '#112233',
+      colorNegative: '#9900E6',
+    });
+    expect(resolved.vizFilterMode).toBe('all');
+    expect(resolved.colorPositive).toBe('#FFE600');
+    expect(resolved.colorZero).toBe('#112233');
+    expect(resolved.colorNegative).toBe('#9900E6');
+  });
+
+  it('persist round-trip via mock localStorage', () => {
+    const storage = mockStorage();
+    const settings = resolveVisualizationSettings({
+      vizFilterMode: 'positive',
+      colorPositive: '#FF0000',
+      colorZero: '#111111',
+      colorNegative: '#0000FF',
+    });
+    saveVisualizationSettings(settings, storage);
+    expect(storage.getItem(VIZ_STORAGE_KEYS.filter)).toBe('positive');
+    expect(loadVisualizationSettings(storage)).toEqual(settings);
+  });
+
+  it('reset restores defaults and All', () => {
+    const storage = mockStorage({
+      [VIZ_STORAGE_KEYS.filter]: 'negative',
+      [VIZ_STORAGE_KEYS.colorPositive]: '#FF0000',
+    });
+    const reset = resetVisualizationSettings(storage);
+    expect(reset).toEqual(DEFAULT_VISUALIZATION_SETTINGS);
+    expect(loadVisualizationSettings(storage)).toEqual(DEFAULT_VISUALIZATION_SETTINGS);
+  });
+
+  it('anchorsFromSettings yields RGB01 trio', () => {
+    const a = anchorsFromSettings(DEFAULT_VISUALIZATION_SETTINGS);
+    expect(a.positive.r).toBeCloseTo(1, 5);
+    expect(a.zero).toEqual({ r: 0, g: 0, b: 0 });
+    expect(a.negative.b).toBeCloseTo(230 / 255, 5);
+  });
+});
+
+describe('shouldShowActivation / filter helpers', () => {
+  const samples = [1, 0.5, 0.005, -0.5, -1];
+
+  it('all mode shows every sample', () => {
+    for (const v of samples) {
+      expect(shouldShowActivation(v, 'all')).toBe(true);
+    }
+  });
+
+  it('+ only hides negatives and near-zero', () => {
+    expect(shouldShowActivation(1, 'positive')).toBe(true);
+    expect(shouldShowActivation(0.5, 'positive')).toBe(true);
+    expect(shouldShowActivation(0.005, 'positive')).toBe(false);
+    expect(shouldShowActivation(-0.5, 'positive')).toBe(false);
+    expect(shouldShowActivation(-1, 'positive')).toBe(false);
+  });
+
+  it('− only hides positives and near-zero', () => {
+    expect(shouldShowActivation(1, 'negative')).toBe(false);
+    expect(shouldShowActivation(0.5, 'negative')).toBe(false);
+    expect(shouldShowActivation(0.005, 'negative')).toBe(false);
+    expect(shouldShowActivation(-0.5, 'negative')).toBe(true);
+    expect(shouldShowActivation(-1, 'negative')).toBe(true);
+  });
+
+  it('uses ε = 0.01 by default', () => {
+    expect(NEAR_ZERO_EPS).toBe(0.01);
+    expect(shouldShowActivation(0.009, 'positive')).toBe(false);
+    expect(shouldShowActivation(0.01, 'positive')).toBe(true);
+  });
+
+  it('filterPointsData keeps aligned entries', () => {
+    const points = samples.map((activation, i) => ({ i, activation }));
+    const kept = filterPointsData(points, samples, 'positive');
+    expect(kept.map((p) => p.i)).toEqual([0, 1]);
+  });
+
+  it('lineSegmentIndices breaks across hidden signs', () => {
+    // visible, visible, near-zero, visible-neg → only first segment
+    const norm = [0.5, 0.8, 0.0, -0.5];
+    expect(lineSegmentIndices(norm, 'positive')).toEqual([0, 1]);
+    expect(lineSegmentIndices(norm, 'all')).toEqual([0, 1, 1, 2, 2, 3]);
+  });
+
+  it('wideRibbonQuadIndices omits quads for filtered pairs', () => {
+    const norm = [0.5, 0.8, -0.5];
+    expect(wideRibbonQuadIndices(norm, 'positive')).toEqual([0, 2, 1, 1, 2, 3]);
+    expect(wideRibbonQuadIndices(norm, 'negative')).toEqual([]);
+  });
+});
+
+describe('getDivergentColor with color anchors', () => {
+  const anchors = anchorsFromSettings(DEFAULT_VISUALIZATION_SETTINGS);
+
+  it('t=1 → +1 hex', () => {
+    const c = getDivergentColor(1, 1, anchors);
+    expect(c.r).toBeCloseTo(anchors.positive.r, 5);
+    expect(c.g).toBeCloseTo(anchors.positive.g, 5);
+    expect(c.b).toBeCloseTo(anchors.positive.b, 5);
+  });
+
+  it('t=0 → 0 hex with low alpha', () => {
+    const c = getDivergentColor(0, 1, anchors);
+    expect(c.r).toBeCloseTo(anchors.zero.r, 5);
+    expect(c.g).toBeCloseTo(anchors.zero.g, 5);
+    expect(c.b).toBeCloseTo(anchors.zero.b, 5);
+    expect(c.alpha).toBeCloseTo(0.05, 5);
+  });
+
+  it('t=-1 → −1 hex', () => {
+    const c = getDivergentColor(-1, 1, anchors);
+    expect(c.r).toBeCloseTo(anchors.negative.r, 5);
+    expect(c.g).toBeCloseTo(anchors.negative.g, 5);
+    expect(c.b).toBeCloseTo(anchors.negative.b, 5);
+  });
+
+  it('t=0.5 → midpoint lerp 0↔+1', () => {
+    const c = getDivergentColor(0.5, 1, anchors);
+    expect(c.r).toBeCloseTo((anchors.zero.r + anchors.positive.r) / 2, 5);
+    expect(c.g).toBeCloseTo((anchors.zero.g + anchors.positive.g) / 2, 5);
+    expect(c.b).toBeCloseTo((anchors.zero.b + anchors.positive.b) / 2, 5);
+  });
+});