feat: complete Phase 3 roadmap + COST 231 + ITM variability modes

CHANGELOG.md

@@ -10,15 +10,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Per-Node Coverage Visualization (P6-1)**: Multi-Site Analysis composite overlay now renders each selected node's coverage as a distinct color instead of one flat cyan mask, so overlapping/redundant sites are visually distinguishable. Simulation node markers and the Sites results table are color-matched to the same coverage patches.
+- **Client-Side Hata & FSPL (P3-1)**: Okumura-Hata is now implemented in JavaScript (`src/utils/math/hata.js`), mirroring the Python engine term-for-term. The Link Analysis tool resolves the `fspl` and `hata` models locally instead of calling `/api/calculate-link`, so both remain usable with no backend -- including offline/PWA use. `bullington` and server-side `itm` still use the backend, which applies clutter height and k-factor to the terrain profile.
+- **COST 231-Hata Extension (P4-2)**: Hata coverage extended from 150-1500 MHz to 150-2000 MHz. Selecting "Hata" automatically dispatches to COST 231 at or above 1500 MHz in both the frontend and `rf-engine`; `cost231` is also accepted as an explicit backend model. COST 231 defines only the 3 dB metropolitan correction, so choosing a suburban or rural environment above the crossover now raises an explicit warning rather than silently reusing the Okumura-Hata corrections.
+- **WASM ITM for Batch Reports (P3-3)**: Batch Processing gained a propagation-model selector. Choosing Longley-Rice ITM runs the same WASM engine as Link Analysis over a 100-point terrain profile (vs 20 for Bullington), honouring Ground Type and Climate Zone, so batch numbers agree with single-link analysis. The engine loads lazily on selection, and a link that fails ITM falls back to Bullington instead of failing the report.
+- **Per-Node Configs in Batch CSV (P3-4)**: Batch CSV import now accepts optional `Antenna_Height`, `Antenna_Gain`, `TX_Power`, `Device` and `Antenna` columns (with aliases such as `Height`/`AGL`/`Gain`/`Power`, and loose preset-name matching so `HELTEC_V3`, `heltec-v3` and `Heltec V3` all resolve). Values are merged over the global A/B config field-by-field; blank cells and existing three-column files behave exactly as before. The sidebar reports how many loaded nodes carry an override.
+- Mesh report CSV now includes `Model`, `PathLoss_dB`, and the per-node TX/RX heights, gains and TX power, plus a progress bar while the report runs.
+- **Probabilistic / Variability Modes (P4-6)**: ITM's time/location/situation variability was hardcoded to 50/50/50; it is now user-selectable via a **Reliability** control in the Environment sidebar -- Best Case (10/10/10), Typical (50/50/50, default) and Reliable (90/90/90). The mode applies to Link Analysis, RF Coverage and batch ITM reports, and batch rows record which mode produced them. On a synthetic ridge profile at 915 MHz this spans roughly 20 dB (193.5 / 203.8 / 213.7 dB).
+  - Required C++ changes: `time_pct`, `loc_pct`, `sit_pct` and `mdvar` added to `LinkParameters`, exposed through Embind, and threaded into `calculate_rf_coverage` (which gained three trailing arguments). All default to the previously hardcoded values, so callers that ignore them are unchanged -- a call that never sets the new fields returns a bit-identical result to an explicit 50/50/50.
+  - `public/meshrf.wasm`, `libmeshrf/js/meshrf.wasm` and `libmeshrf/js/meshrf.js` are regenerated. See ROADMAP.md P4-6 for the rebuild command.
 
 ### Changed
 
 - **Backend**: Refactored `rf-engine/core/viewshed_proc.py` to share a single pixel-projection helper instead of three near-identical copies of the same coordinate-mapping logic.
 - Added `eslint-plugin-react`'s `jsx-uses-vars` rule to `eslint.config.js` -- the previous config had no way to recognize JSX component usage, producing ~100 false-positive "unused import" warnings that were masking real ones.
 - Added a `ci.yml` GitHub Actions workflow that runs frontend lint/test/build and the `rf-engine` pytest suite on every push and PR to `dev`/`main`.
+- `useWasmITM` accepts an `enabled` flag so always-mounted panels can defer loading the WASM module until ITM is actually selected, keeping it off the startup path.
+- Hata validity warnings in the Link Analysis panel are driven by a single `getHataValidity` helper instead of inline thresholds, so they track the active model variant.
+- Mesh report export writes via a Blob instead of a `data:` URI and escapes CSV fields, so node names containing commas or quotes no longer corrupt the report.
 
 ### Fixed
 
+- Bullington diffraction loss was never shown for the Hata model in `LinkLayer`: the check compared against `'Hata'` while the model value is lowercase `'hata'`, so the condition could never be true.
+
 - Dead `elevation` variable, unused caught SSE-parse error, and stale `eslint-disable` directives now flagged/cleaned up now that lint output is trustworthy again.
 - `ROADMAP.md` had a duplicated P5-6/P5-7 section from a copy-paste error.
 - `README.md` linked to `Documentation/pwa-guide.md`, which never existed; the guide has been written.

Documentation/batch-processing.md

@@ -20,6 +20,36 @@ The first line can be a header or data. The tool uses a heuristic to identify co
 > [!TIP]
 > Use the **"Download Template"** link in the sidebar to get a perfectly formatted CSV file.
 
+### Per-Node Hardware Overrides
+
+When your CSV has a header row, you can add optional columns to give individual
+nodes their own hardware instead of applying the global A/B configuration to
+every site. Any column you leave out — or leave blank on a given row — falls
+back to the global config, so existing three-column files keep working unchanged.
+
+| Column | Aliases | Meaning |
+| --- | --- | --- |
+| `Antenna_Height` | `Height`, `AGL` | Antenna height above ground, in meters |
+| `Antenna_Gain` | `Gain` | Antenna gain in dBi |
+| `TX_Power` | `Power` | Transmit power in dBm |
+| `Device` | — | Device preset, e.g. `HELTEC_V3`, `RAK_4631`, `Station G2` |
+| `Antenna` | `Antenna_Type` | Antenna preset, e.g. `YAGI`, `OMNI_HIGH`, `Standard Dipole` |
+
+Preset names are matched loosely — `HELTEC_V3`, `heltec-v3` and `Heltec V3` all
+resolve to the same device. Selecting an `Antenna` preset supplies its nominal
+gain automatically; an explicit `Antenna_Gain` on the same row wins.
+
+```csv
+Name,Lat,Lon,Antenna_Height,Antenna_Gain,TX_Power,Device,Antenna
+Site Alpha,45.5152,-122.6784,30,8,22,HELTEC_V3,OMNI_HIGH
+Site Bravo,45.5252,-122.6684,12,,,,DIPOLE
+Site Delta,45.5100,-122.6500,,,,,
+```
+
+Above, Alpha is fully specified, Bravo overrides only its height and antenna
+(taking 3.0 dBi from the dipole preset), and Delta inherits everything from the
+global config. The sidebar shows how many loaded nodes carry an override.
+
 ## 2. Integration with Link Analyzer
 
 The Batch Nodes panel provides a seamless transition into detailed point-to-point analysis:
@@ -32,23 +62,56 @@ By using these buttons, you can quickly verify a link's profile and Fresnel clea
 > [!IMPORTANT]
 > Selecting a different tool from the toolbar (e.g., switching from Link Analysis to Viewshed) will clear the current analysis markers and results from the map. However, your **Batch Nodes** will remain visible until you click **"Clear All Nodes"**.
 
-## 3. Exporting Mesh Reports
+## 3. Choosing a Propagation Model
+
+Once more than one node is loaded, a **Propagation Model** selector appears above
+the export button:
+
+- **Bullington (Fast)** — Free-space path loss plus knife-edge diffraction,
+  computed over a 20-point terrain profile per link. This is the default and is
+  well suited to sweeping a large candidate list quickly.
+- **Longley-Rice ITM (Accurate, Slower)** — The same WASM ITM engine the Link
+  Analysis tool uses, run over a denser 100-point profile and using your
+  **Ground Type**, **Climate Zone** and **Reliability** settings. Batch numbers
+  then agree with what you see when you open the same link in the Link Analyzer.
+
+> [!TIP]
+> The **Reliability** setting in the Environment sidebar applies here too. Running
+> a mesh report at *Reliable (90%)* tells you which links survive poor conditions,
+> not just which ones work on a median day. The `Model` column records the mode
+> used for each row (e.g. `ITM 90/90/90`), so reports run at different confidence
+> levels stay distinguishable after export.
+
+The ITM engine is loaded on demand the first time you select it; the export
+button stays disabled for the moment it takes to initialize. If ITM fails on an
+individual link, that link falls back to Bullington rather than failing the
+whole report — the `Model` column records which model actually produced each row.
+
+## 4. Exporting Mesh Reports
 
 The most powerful feature of Batch Processing is the **"Export Mesh Report"** button.
 
 ### What it does:
 
 1. It iterates through every possible pair of nodes in your imported list.
 2. It performs a terrain profile analysis for every link (Source to Target).
-3. It calculates the Link Budget based on your current **Hardware Settings**.
+3. It calculates the Link Budget from each node's own configuration, falling
+   back to your global **Hardware Settings** where no override is given.
 4. It generates a CSV report containing:
    - **Distance**: In kilometers.
    - **Status**: GOOD, MARGINAL, or OBSTRUCTED.
+   - **Quality**: Fresnel-based link quality rating.
    - **Clearance**: Minimum Fresnel zone clearance in meters.
    - **Margin**: Signal margin in dB.
+   - **Model**: Which propagation model produced the row (`ITM` or `Bullington`).
+   - **PathLoss_dB**: Total path loss used for the budget.
+   - **Per-node params**: TX/RX antenna height, TX/RX gain, and TX power, so the
+     report is self-documenting when nodes differ.
+
+A progress bar tracks completion while the report runs.
 
 > [!WARNING]
-> Processing many links (e.g., 20+ nodes result in 190+ links) can take several minutes as the tool fetches terrain data for each path.
+> Processing many links (e.g., 20+ nodes result in 190+ links) can take several minutes as the tool fetches terrain data for each path. The ITM model is noticeably slower than Bullington, since it fetches a 5x denser terrain profile per link.
 
 ## Workflow Example
 

Documentation/link-analyzer.md

@@ -7,7 +7,7 @@ The **Link Analyzer** is designed for detailed point-to-point analysis between t
 - **Profile Verification**: Real-time terrain profile between Site A and Site B.
 - **Fresnel Zone Analysis**: Visualizes the first Fresnel zone and calculates minimum clearance.
 - **Link Budget Calculation**: Predicts RSSI and link margin based on hardware and environment settings.
-- **Propagation Models**: Choose between Free Space Path Loss (Ideal) and Okumura-Hata (Realistic).
+- **Propagation Models**: Choose between Free Space Path Loss (Ideal), Okumura-Hata / COST 231 (Realistic, 150-2000 MHz), Bullington, and ITM. FSPL and the Hata family are computed in the browser and need no backend connection.
 
 ## How to Use
 

README.md

@@ -14,7 +14,7 @@ meshRF is designed for **mission-critical availability**. It operates with **zer
 - **Advanced Models**:
   - **ITM (Longley-Rice)**: High-precision WASM physical modeling.
   - **Bullington**: Terrain-aware diffraction (Backend).
-  - **Okumura-Hata**: Empirical model for urban zones.
+  - **Okumura-Hata / COST 231**: Empirical model for urban zones, covering 150-2000 MHz.
   - **Free Space**: Baseline physics comparison.
 - **Model Selector**: Comparison tool to instantly switch between models for A/B testing.
 - **Asymmetric Links**: Configure unique hardware (power, gain, height) for **Node A** and **Node B** independently.
@@ -32,11 +32,14 @@ meshRF is designed for **mission-critical availability**. It operates with **zer
 - **RF Coverage Simulator**: Optimized Wasm-powered ITM propagation modeling for wide-area coverage visualization.
 - **Viewshed Analysis**: Desktop-grade viewshed calculations with "Shadow Mode" visualization.
 - **Environment Tuning**: Fine-tune simulations with **Ground Type** ($\epsilon$, $\sigma$) and **Climate Zone** parameters for regional accuracy. Supports Sea Water, City/Industrial, Farmland, and more.
+- **Reliability Modes**: Select the ITM statistical confidence level — Best Case (10%), Typical (50%, default) or Reliable (90%) — to plan against median or worst-case conditions instead of a single fixed forecast.
 
 ### 3. ⚡ Batch Operations & reporting
 
 - **Bulk Link Matrix**: Import CSVs (`Name, Lat, Lon`) to instantly compute link budgets for entire networks.
-- **Automated Reporting**: Export detailed CSV reports containing RSSI, Signal Margin, and Clearance values.
+- **Per-Node Hardware**: Optional CSV columns (antenna height, gain, TX power, device, antenna) let individual sites override the global config for realistic mixed-device meshes.
+- **Selectable Batch Model**: Run mesh reports with fast Bullington diffraction or full WASM ITM for terrain-accurate results that match Link Analysis.
+- **Automated Reporting**: Export detailed CSV reports containing RSSI, Signal Margin, Clearance, path loss, and the per-node parameters used.
 - **Context-Aware Guidance**: Every tool features built-in, interactive help banners that update based on your current mode, guiding you through workflows step-by-step.
 
 ### 4. 📚 Documentation
@@ -67,11 +70,17 @@ meshRF supports multiple propagation models to suit different environments:
 
 | Model                  | Best For          | Characteristics                                                                |
 | :--------------------- | :---------------- | :----------------------------------------------------------------------------- |
-| **Free Space (FSPL)**  | Ideal LOS, Orbit  | Baseline physics, no terrain or environment effects.                           |
-| **Okumura-Hata**       | Flat/Suburban     | Empirical model for urban/suburban. Assumes flat terrain.                      |
+| **Free Space (FSPL)**  | Ideal LOS, Orbit  | Baseline physics, no terrain or environment effects. Runs client-side.         |
+| **Okumura-Hata**       | Flat/Suburban     | Empirical model for urban/suburban, 150-1500 MHz. Assumes flat terrain. Runs client-side. |
+| **COST 231-Hata**      | 1.5-2 GHz ISM     | Hata extended to 1500-2000 MHz. Selected automatically above 1500 MHz.         |
 | **Bullington**         | Terrain/Mesh      | Efficient terrain-aware diffraction. Fast & reliable for terrestrial links.    |
 | **ITM (Longley-Rice)** | Irregular Terrain | **Gold Standard**. High-fidelity WASM-powered physical modeling. Ground-aware. |
 
+> [!NOTE]
+> FSPL and the Hata family are computed in the browser, so they remain available
+> when the Python backend is unreachable (including offline/PWA use). Bullington
+> and server-side ITM require the RF Engine.
+
 > [!TIP]
 > Use **ITM (Longley-Rice)** for mission-critical link analysis. It accounts for irregular terrain, diffraction, troposcatter, and specific ground/climate parameters. Use **Bullington** for rapid terrain-aware estimates.