@aguacerowx/mapsgl 0.0.52 → 0.0.54

package/src/nexrad/nexradLevel3Products.ts

@@ -1,581 +1,581 @@
-import {
-    clampNexradTiltForVariable,
-    formatTiltForApi,
-    getDefaultRadarTilt,
-    getRadarTilts,
-    isTerminalRadar,
-} from '@aguacerowx/javascript-sdk';
-
-/** API elevation string for Level-III listings (lowest tilt / nominal 0.5°). */
-export const NEXRAD_LEVEL3_ELEV = '0.50';
-
-function nearestTiltInSortedList(tilts: readonly number[], target: number): number {
-    if (!tilts.length) return target;
-    let best = tilts[0]!;
-    let bestD = Math.abs(best - target);
-    for (let i = 1; i < tilts.length; i++) {
-        const t = tilts[i]!;
-        const d = Math.abs(t - target);
-        if (d < bestD || (d === bestD && t < best)) {
-            best = t;
-            bestD = d;
-        }
-    }
-    return best;
-}
-
-export const NEXRAD_LEVEL3_MOTION_PRODUCT = 'N0S';
-
-export type Level3DecodeMode =
-    | 'velocity'
-    | 'dbz'
-    | 'precip'
-    | 'categorical'
-    | 'tops_kft'
-    | 'vil'
-    /** PDB/generic-digital products already in physical units (e.g. KDP °/km); fine texture packing, not dBZ scale. */
-    | 'generic_physical';
-
-export type NexradLevel3MenuEntry = {
-    /** Stored as `layer.radarVariable` and used in time-anchor keys `SITE_${radarKey}_${elev}_level3`. */
-    radarKey: string;
-    /** S3 object-key product mnemonic (e.g. N0B, N1P). */
-    product: string;
-    menuLabel: string;
-    /** DICTIONARIES.fld key for titles / metadata. */
-    fldKey: string;
-    /** layerProperties key (after variable_cmap resolution from fldKey). */
-    cmapPropertyKey: string;
-    /** Omit for velocity (VEL): use the same mph / km/h defaults as Level-2 velocity. */
-    defaultUnit?: string;
-    decodeMode: Level3DecodeMode;
-    /**
-     * When true, this entry uses storm-relative processing (N0G + N0S).
-     * Only the `VEL` radarKey uses this; `N0G` is base velocity from the same grid without N0S.
-     */
-    stormRelativeVelocity?: boolean;
-};
-
-/**
- * Level-III menu: subset aligned with products we decode as radial symbology (packets 0x0010 / 0xAF1F).
- * See product codes vs mnemonics: https://supercell-wx.readthedocs.io/en/stable/features/nexrad-l3.html
- *
- * Intentionally omitted for now: legacy/digital precip variants (OHA/DPA/DSP/DU6/DOD/DSD/DPR) not wired in menu,
- * NET/N0M, and base N0G-only velocity (menu keeps storm-relative VEL = N0G + N0S only).
- *
- * Terminal (TDWR) radars: only storm-relative velocity ({@link nexradStormRelativeVelocityUsesLevel2TiltAndFetch}) is
- * exposed as Level-III in the UI; other Level-III products are WSR-88D-only in this app.
- */
-export const NEXRAD_LEVEL3_MENU: NexradLevel3MenuEntry[] = [
-    {
-        radarKey: 'VEL',
-        product: 'N0G',
-        menuLabel: 'Storm Relative Velocity',
-        fldKey: 'nexrad_vel',
-        cmapPropertyKey: 'nexrad_vel',
-        decodeMode: 'velocity',
-        stormRelativeVelocity: true,
-    },
-    {
-        radarKey: 'KDP',
-        product: 'N0K',
-        menuLabel: 'Specific Differential Phase',
-        fldKey: 'nexrad_l3_n0k',
-        cmapPropertyKey: 'nexrad_kdp',
-        defaultUnit: 'deg/km',
-        decodeMode: 'generic_physical',
-    },
-    {
-        radarKey: 'N0H',
-        product: 'N0H',
-        menuLabel: 'Hydrometeor Classification',
-        fldKey: 'nexrad_l3_n0h',
-        cmapPropertyKey: 'nexrad_l3_n0h',
-        defaultUnit: 'None',
-        decodeMode: 'categorical',
-    },
-    {
-        radarKey: 'HHC',
-        product: 'HHC',
-        menuLabel: 'Hybrid Hydrometeor Classification',
-        fldKey: 'nexrad_l3_hhc',
-        cmapPropertyKey: 'nexrad_l3_hhc',
-        defaultUnit: 'None',
-        decodeMode: 'categorical',
-    },
-    {
-        radarKey: 'EET',
-        product: 'EET',
-        menuLabel: 'Enhanced Echo Tops',
-        fldKey: 'nexrad_l3_eet',
-        cmapPropertyKey: 'nexrad_l3_eet',
-        defaultUnit: 'kft',
-        decodeMode: 'tops_kft',
-    },
-    {
-        radarKey: 'DVL',
-        product: 'DVL',
-        menuLabel: 'Vertically Integrated Liquid',
-        fldKey: 'nexrad_l3_dvl',
-        cmapPropertyKey: 'nexrad_l3_dvl',
-        defaultUnit: 'kg/m²',
-        decodeMode: 'vil',
-    },
-    {
-        radarKey: 'DAA',
-        product: 'DAA',
-        menuLabel: '1-Hour Precipitation',
-        fldKey: 'nexrad_l3_daa',
-        cmapPropertyKey: 'tp_0_1',
-        defaultUnit: 'in',
-        decodeMode: 'precip',
-    },
-    {
-        radarKey: 'DU3',
-        product: 'DU3',
-        menuLabel: '3-Hour Precipitation',
-        fldKey: 'nexrad_l3_du3',
-        cmapPropertyKey: 'tp_0_total',
-        defaultUnit: 'in',
-        decodeMode: 'precip',
-    },
-    {
-        radarKey: 'DTA',
-        product: 'DTA',
-        menuLabel: 'Storm Total Precipitation',
-        fldKey: 'nexrad_l3_dta',
-        cmapPropertyKey: 'tp_0_total',
-        defaultUnit: 'in',
-        decodeMode: 'precip',
-    },
-];
-
-const byRadarKey = new Map<string, NexradLevel3MenuEntry>();
-for (const e of NEXRAD_LEVEL3_MENU) {
-    byRadarKey.set(e.radarKey, e);
-    // Backward compatibility: older saved layers used radarVariable=NVL.
-    if (e.radarKey === 'DVL') byRadarKey.set('NVL', e);
-}
-
-export function getNexradLevel3EntryByRadarKey(radarKey: string): NexradLevel3MenuEntry | undefined {
-    return byRadarKey.get(radarKey);
-}
-
-/** Digital Specific Differential Phase (163): S3 mnemonic per elevation slot (ICD order, low → high). */
-export const NEXRAD_LEVEL3_KDP_PRODUCTS: readonly string[] = [
-    'NXK',
-    'NYK',
-    'NZK',
-    'N0K',
-    'NAK',
-    'N1K',
-    'NBK',
-    'N2K',
-    'N3K',
-];
-
-/** Digital Hydrometeor Classification (165): S3 mnemonic per elevation slot (ICD order, low → high). */
-export const NEXRAD_LEVEL3_DHC_PRODUCTS: readonly string[] = [
-    'NXH',
-    'NYH',
-    'NZH',
-    'N0H',
-    'NAH',
-    'N1H',
-    'NBH',
-    'N2H',
-    'N3H',
-];
-
-/**
- * Level-III KDP/DHC products aligned with {@link getRadarTilts} indices (lowest manifest tilt first).
- * NXK/NYK/NZK (and NXH…) are sub–0.5° cuts; our tilt manifest for KDP/N0H starts at ~0.5° like REF,
- * so index 0 must map to N0K/N0H — matching historical behavior before multi-tilt wiring.
- */
-const NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_KDP_PRODUCTS.slice(3);
-const NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_DHC_PRODUCTS.slice(3);
-
-/** Super-res base radial velocity (154): S3 mnemonic per elevation (ICD order, low → high). */
-export const NEXRAD_LEVEL3_VELOCITY_PRODUCTS: readonly string[] = [
-    'NXG', 'NYG', 'NZG', 'N0G', 'NAG', 'N1G', 'NBG', 'N2G', 'N3G',
-];
-const NEXRAD_LEVEL3_VELOCITY_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_VELOCITY_PRODUCTS.slice(3);
-
-/**
- * Level-III KDP / digital HC (N0H): one S3 mnemonic per manifest slot in
- * {@link NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST} / {@link NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST}.
- * The UI and composite keys use the first this many tilts from {@link getRadarTilts} (site order), not a fixed elevation angle.
- */
-export const NEXRAD_LEVEL3_MANIFEST_TILT_COUNT = NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST.length;
-
-/** Tilts available for Level-III KDP / N0H: same order as Level II, truncated after the Nth tilt ({@link NEXRAD_LEVEL3_MANIFEST_TILT_COUNT}). */
-export function getNexradLevel3RadarTilts(siteId: string, radarVariable: string): number[] {
-    return getRadarTilts(siteId, radarVariable).slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
-}
-
-/** Tilts for super-res L3 velocity (N*G), same manifest cap as KDP/N0H. */
-export function getNexradLevel3RadarTiltsForVelocity(siteId: string): number[] {
-    return getRadarTilts(siteId, 'VEL').slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
-}
-
-/**
- * Map site tilt to L3 super-res base velocity mnemonic (N0G, NAG, …) for Unidata S3 keys / stable GPU layout — aguacero-frontend parity.
- */
-export function nexradLevel3S3VelocityProductForSiteTilt(siteId: string, tilt: number): string {
-    const products = NEXRAD_LEVEL3_VELOCITY_PRODUCTS_FOR_MANIFEST;
-    const tilts = getNexradLevel3RadarTiltsForVelocity(siteId);
-    if (!tilts.length) {
-        return products[0]!;
-    }
-    const clamped = clampNexradTiltForVariable(siteId, 'VEL', tilt);
-    let idx = tilts.indexOf(clamped);
-    if (idx === -1) {
-        idx = tilts.reduce(
-            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
-            0,
-        );
-    }
-    idx = Math.min(idx, products.length - 1);
-    return products[idx]!;
-}
-
-export function nexradLevel3IsTiltIndexedKdpProduct(product: string): boolean {
-    return NEXRAD_LEVEL3_KDP_PRODUCTS.includes(product);
-}
-
-export function nexradLevel3IsTiltIndexedDhcProduct(product: string): boolean {
-    return NEXRAD_LEVEL3_DHC_PRODUCTS.includes(product);
-}
-
-/** Layer variable is KDP or digital HC (N0H); user tilt maps to NXK..N3K / NXH..N3H. */
-export function nexradLevel3UsesTiltIndexedS3Products(radarVariable: string | undefined): boolean {
-    const v = radarVariable || '';
-    return v === 'KDP' || v === 'N0H';
-}
-
-/**
- * Clamp stored tilt for composite keys / fetches when `radarVariable` is KDP or N0H on true Level III.
- */
-export function clampTiltForLevel3CompositeKey(siteId: string, radarVariable: string, tilt: number): number {
-    if (!nexradLevel3UsesTiltIndexedS3Products(radarVariable)) {
-        return clampNexradTiltForVariable(siteId, radarVariable, tilt);
-    }
-    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
-    const c = clampNexradTiltForVariable(siteId, radarVariable, tilt);
-    if (!tilts.length) return c;
-    return nearestTiltInSortedList(tilts, c);
-}
-
-/**
- * Cross section fetches: one S3 product per manifest tilt in {@link getRadarTilts} order (capped by
- * ICD mnemonic count). Uses the full NXK–N3K / NXH–N3H tables; when the lowest tilt is at or above
- * ~0.5°, the first slot is N0K / N0H (skipping NX, NY, NZ sub-half-degree products).
- */
-export function nexradLevel3CrossSectionTiltProductJobs(
-    siteId: string,
-    radarVariable: 'KDP' | 'N0H',
-): { tiltDeg: number; product: string }[] {
-    const products =
-        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS : NEXRAD_LEVEL3_DHC_PRODUCTS;
-    const tilts = getRadarTilts(siteId, radarVariable);
-    if (!tilts.length) return [];
-    const low = tilts[0]!;
-    const startSlot = low >= 0.45 ? 3 : 0;
-    const nSlots = Math.min(tilts.length, products.length - startSlot);
-    const out: { tiltDeg: number; product: string }[] = [];
-    for (let i = 0; i < nSlots; i++) {
-        out.push({ tiltDeg: tilts[i]!, product: products[startSlot + i]! });
-    }
-    return out;
-}
-
-/**
- * Map site tilt to Level-III S3 product (N0K, NAK, … / N0H, …) for map tiles and time keys.
- */
-export function nexradLevel3S3ProductForSiteTilt(
-    siteId: string,
-    radarVariable: 'KDP' | 'N0H',
-    tilt: number,
-): string {
-    const products =
-        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
-    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
-    if (!tilts.length) {
-        return products[0]!;
-    }
-    const clamped = clampTiltForLevel3CompositeKey(siteId, radarVariable, tilt);
-    let idx = tilts.indexOf(clamped);
-    if (idx === -1) {
-        idx = tilts.reduce(
-            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
-            0,
-        );
-    }
-    idx = Math.min(idx, products.length - 1);
-    return products[idx]!;
-}
-
-/** Elevation string for `SITE_VAR_elev_level3` keys / UI — matches manifest slot for this S3 product. */
-export function nexradLevel3DisplayElevForS3Product(
-    siteId: string,
-    radarVariable: 'KDP' | 'N0H',
-    s3Product: string,
-): string {
-    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
-    if (!tilts.length) return NEXRAD_LEVEL3_ELEV;
-
-    const manifestProducts =
-        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
-    let idx = manifestProducts.indexOf(s3Product);
-    if (idx >= 0) {
-        const t = tilts[Math.min(idx, tilts.length - 1)]!;
-        return formatTiltForApi(t);
-    }
-
-    /** NXK/NYK/NZK (or NXH…) from listings: not in manifest-ordered slice — use lowest tilt for keying. */
-    const full = radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS : NEXRAD_LEVEL3_DHC_PRODUCTS;
-    const fullIdx = full.indexOf(s3Product);
-    if (fullIdx >= 0 && fullIdx < 3) {
-        return formatTiltForApi(tilts[0]!);
-    }
-    if (fullIdx >= 3) {
-        const mIdx = fullIdx - 3;
-        const t = tilts[Math.min(mIdx, tilts.length - 1)]!;
-        return formatTiltForApi(t);
-    }
-    return NEXRAD_LEVEL3_ELEV;
-}
-
-/**
- * Level-III products that are not tied to a selectable sweep (precip accumulations, echo tops, VIL,
- * hybrid HC, etc.). Hide tilt controls and ignore tilt stepping for these.
- * Digital HC (N0H) and KDP use {@link nexradLevel3UsesTiltIndexedS3Products}.
- */
-const LEVEL3_DECODE_MODES_WITHOUT_USER_TILT: ReadonlySet<Level3DecodeMode> = new Set([
-    'precip',
-    'tops_kft',
-    'vil',
-    'categorical',
-]);
-
-export function nexradLevel3DisallowsUserTiltChange(radarVariable: string | undefined): boolean {
-    if (nexradLevel3UsesTiltIndexedS3Products(radarVariable)) return false;
-    const entry = getNexradLevel3EntryByRadarKey(radarVariable || '');
-    if (!entry) return false;
-    if (entry.stormRelativeVelocity) return false;
-    return LEVEL3_DECODE_MODES_WITHOUT_USER_TILT.has(entry.decodeMode);
-}
-
-/**
- * Cross sections stack multiple elevation sweeps. True Level-III products that are a single grid
- * (precipitation totals, echo tops, VIL, hybrid HC, etc.) cannot produce a pseudo-RHI — skip fetches.
- */
-export function nexradCrossSectionBlockedReason(layer: {
-    radar?: string | null;
-    radarDataSource?: string;
-    radarVariable?: string;
-    level3StormRelative?: boolean;
-}): string | null {
-    if (!nexradLayerUsesTrueLevel3Listing(layer)) return null;
-    if (!nexradLevel3DisallowsUserTiltChange(layer.radarVariable)) return null;
-    const entry = getNexradLevel3EntryByRadarKey(layer.radarVariable || '');
-    const label = entry?.menuLabel ?? layer.radarVariable ?? 'this product';
-    return `Cross sections are not available for ${label}.`;
-}
-
-/** True Level-III map products (not storm-relative velocity, which uses Level II + motion). */
-export function nexradLayerUsesTrueLevel3Listing(layer: {
-    radar?: string | null;
-    radarDataSource?: string;
-    radarVariable?: string;
-    level3StormRelative?: boolean;
-}): boolean {
-    return (
-        layer.radarDataSource === 'level3' && !nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)
-    );
-}
-
-/** Terminal radars do not support true Level-III map products in this app (SRV only). */
-export function terminalRadarBlocksTrueLevel3(layer: {
-    radar?: string | null;
-    radarDataSource?: string;
-    radarVariable?: string;
-    level3StormRelative?: boolean;
-}): boolean {
-    const site = layer.radar || '';
-    return isTerminalRadar(site) && nexradLayerUsesTrueLevel3Listing(layer);
-}
-
-/** Digital (N0H) and hybrid (HHC) hydrometeor classification — discrete classes, not a continuous field. */
-export function nexradLevel3IsHydrometeorClassification(radarVariable: string | undefined): boolean {
-    const v = radarVariable || '';
-    return v === 'N0H' || v === 'HHC';
-}
-
-export type Level3ExpandTarget = { radarKey: string; attachMotionMap: boolean };
-
-/** Map raw S3 product code to one or more formatted time-anchor variables. */
-export function getLevel3ExpansionTargetsForS3Product(product: string): Level3ExpandTarget[] {
-    if (product === NEXRAD_LEVEL3_MOTION_PRODUCT) {
-        return [];
-    }
-    if (product === 'DVL') {
-        // Emit both keys so old NVL layers and new DVL layers resolve the same time map.
-        return [
-            { radarKey: 'DVL', attachMotionMap: false },
-            { radarKey: 'NVL', attachMotionMap: false },
-        ];
-    }
-    if (product === 'N0G') {
-        return [
-            { radarKey: 'N0G', attachMotionMap: false },
-            { radarKey: 'VEL', attachMotionMap: true },
-        ];
-    }
-    if (nexradLevel3IsTiltIndexedKdpProduct(product)) {
-        return [{ radarKey: 'KDP', attachMotionMap: false }];
-    }
-    if (nexradLevel3IsTiltIndexedDhcProduct(product)) {
-        return [{ radarKey: 'N0H', attachMotionMap: false }];
-    }
-    return [{ radarKey: product, attachMotionMap: false }];
-}
-
-/**
- * Product 135 (EET): MetPy `DigitalEETMapper` uses PDB thr1–thr3 as data mask, scale, and offset:
- * `mapped = ((level & mask) - offset) / scale` (raw signed halfwords — no /10; unlike dBZ min/inc).
- *
- * Output is treated as **kilometers** end-to-end with the rest of `tops_kft` packing.
- */
-export function level3EetHeightKmFromLevel(
-    level: number,
-    dataMaskRaw: number,
-    scaleRaw: number,
-    offsetRaw: number,
-): number | null {
-    if (level < 2) return null;
-    const masked = level & (dataMaskRaw & 0xffff);
-    if (!Number.isFinite(scaleRaw) || scaleRaw === 0) {
-        return level - 2;
-    }
-    const mapped = (masked - offsetRaw) / scaleRaw;
-    if (!Number.isFinite(mapped)) return null;
-    return mapped;
-}
-
-export function level3ValuePacking(decodeMode: Level3DecodeMode): { valueScale: number; valueOffset: number } {
-    switch (decodeMode) {
-        case 'velocity':
-            return { valueScale: 0.01, valueOffset: 0 };
-        case 'dbz':
-            return { valueScale: 0.5, valueOffset: -32 };
-        case 'precip':
-            return { valueScale: 0.001, valueOffset: 0 };
-        case 'categorical':
-            return { valueScale: 1, valueOffset: 0 };
-        case 'tops_kft':
-            // Shader physical = raw * valueScale (km). raw = round(km / valueScale) must stay within int16.
-            // 0.001 implied raw = meters → tops >32.767 km clamped (seen on EET ~48 km). Use 2 m/LSb → max ~65.5 km.
-            return { valueScale: 0.002, valueOffset: 0 };
-        case 'vil':
-            return { valueScale: 0.1, valueOffset: 0 };
-        case 'generic_physical':
-            return { valueScale: 0.01, valueOffset: 0 };
-        default:
-            return { valueScale: 0.5, valueOffset: -32 };
-    }
-}
-
-/**
- * Opt-in storm-relative velocity (super-res VEL + N0S motion). Set in localStorage to trace: DEBUG_NEXRAD_VEL=1
- */
-function nexradVelDebug(label: string, data: Record<string, unknown>) {
-    try {
-        if (typeof localStorage !== 'undefined' && localStorage.getItem('DEBUG_NEXRAD_VEL') === '1') {
-            console.log(`[NEXRAD_VEL] ${label}`, data);
-        }
-    } catch {
-        /* ignore */
-    }
-}
-
-/**
- * Storm-relative velocity is rendered from Level-2 super-res VEL at the user’s tilt plus L3 N0S motion.
- * Layers may still have `radarDataSource: 'level3'` when chosen from the Level-III menu.
- *
- * `level3StormRelative === undefined` must NOT default to “on” for Level-II velocity (that broke base VEL).
- * For legacy layers with L3-menu VEL and no flag, infer SRV only when `radarDataSource === 'level3'`.
- */
-export function nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer: {
-    radar?: string | null;
-    radarVariable?: string;
-    level3StormRelative?: boolean;
-    radarDataSource?: string;
-}): boolean {
-    if ((layer.radarVariable || 'REF') !== 'VEL') {
-        return false;
-    }
-    if (layer.level3StormRelative === true) return true;
-    if (layer.level3StormRelative === false) return false;
-    const inferred = (layer.radarDataSource || 'level2') === 'level3';
-    nexradVelDebug('VEL level3StormRelative missing — infer from radarDataSource', {
-        radar: layer.radar,
-        radarDataSource: layer.radarDataSource,
-        useStormRelativeVelocity: inferred,
-    });
-    return inferred;
-}
-
-/**
- * True when composite time keys and map wiring should use `layer.radarTilt` (like Level II), not a fixed 0.5° token.
- */
-export function nexradLevel3LayerUsesRadarTiltInCompositeKeys(layer: {
-    radar?: string | null;
-    radarVariable?: string;
-    radarDataSource?: string;
-    level3StormRelative?: boolean;
-}): boolean {
-    if (layer.radarDataSource !== 'level3') return false;
-    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) return false;
-    return nexradLevel3UsesTiltIndexedS3Products(layer.radarVariable);
-}
-
-export function nexradEffectiveFetchSource(layer: {
-    radar?: string | null;
-    radarVariable?: string;
-    radarDataSource?: string;
-    level3StormRelative?: boolean;
-}): 'level2' | 'level3' {
-    if (terminalRadarBlocksTrueLevel3(layer)) return 'level2';
-    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) return 'level2';
-    return layer.radarDataSource === 'level3' ? 'level3' : 'level2';
-}
-
-export function nexradTimesFetchOptionsFromLayer(layer: {
-    radar?: string | null;
-    radarVariable?: string;
-    radarDataSource?: string;
-    level3StormRelative?: boolean;
-    radarTilt?: number | null;
-}): { level3Product?: string; level3StormRelative?: boolean } | undefined {
-    if (terminalRadarBlocksTrueLevel3(layer)) return undefined;
-    /** L2 fetch + N0S time alignment for storm-relative velocity (super-res VEL + motion). */
-    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) {
-        return { level3StormRelative: true };
-    }
-    if (layer.radarDataSource !== 'level3') return undefined;
-    const v = layer.radarVariable || 'REF';
-    const entry = getNexradLevel3EntryByRadarKey(v);
-    let product = entry?.product ?? (v === 'VEL' ? 'N0G' : v);
-    const site = layer.radar || '';
-    if (site && nexradLevel3UsesTiltIndexedS3Products(v)) {
-        const tilt = layer.radarTilt ?? getDefaultRadarTilt(site);
-        product = nexradLevel3S3ProductForSiteTilt(site, v as 'KDP' | 'N0H', tilt);
-    }
-    const stormRelative = v === 'VEL' ? nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer) : false;
-    return { level3Product: product, level3StormRelative: stormRelative };
-}
-
-export function formatLevel3TiltForApi(): string {
-    return NEXRAD_LEVEL3_ELEV;
-}
+import {
+    clampNexradTiltForVariable,
+    formatTiltForApi,
+    getDefaultRadarTilt,
+    getRadarTilts,
+    isTerminalRadar,
+} from '@aguacerowx/javascript-sdk';
+
+/** API elevation string for Level-III listings (lowest tilt / nominal 0.5°). */
+export const NEXRAD_LEVEL3_ELEV = '0.50';
+
+function nearestTiltInSortedList(tilts: readonly number[], target: number): number {
+    if (!tilts.length) return target;
+    let best = tilts[0]!;
+    let bestD = Math.abs(best - target);
+    for (let i = 1; i < tilts.length; i++) {
+        const t = tilts[i]!;
+        const d = Math.abs(t - target);
+        if (d < bestD || (d === bestD && t < best)) {
+            best = t;
+            bestD = d;
+        }
+    }
+    return best;
+}
+
+export const NEXRAD_LEVEL3_MOTION_PRODUCT = 'N0S';
+
+export type Level3DecodeMode =
+    | 'velocity'
+    | 'dbz'
+    | 'precip'
+    | 'categorical'
+    | 'tops_kft'
+    | 'vil'
+    /** PDB/generic-digital products already in physical units (e.g. KDP °/km); fine texture packing, not dBZ scale. */
+    | 'generic_physical';
+
+export type NexradLevel3MenuEntry = {
+    /** Stored as `layer.radarVariable` and used in time-anchor keys `SITE_${radarKey}_${elev}_level3`. */
+    radarKey: string;
+    /** S3 object-key product mnemonic (e.g. N0B, N1P). */
+    product: string;
+    menuLabel: string;
+    /** DICTIONARIES.fld key for titles / metadata. */
+    fldKey: string;
+    /** layerProperties key (after variable_cmap resolution from fldKey). */
+    cmapPropertyKey: string;
+    /** Omit for velocity (VEL): use the same mph / km/h defaults as Level-2 velocity. */
+    defaultUnit?: string;
+    decodeMode: Level3DecodeMode;
+    /**
+     * When true, this entry uses storm-relative processing (N0G + N0S).
+     * Only the `VEL` radarKey uses this; `N0G` is base velocity from the same grid without N0S.
+     */
+    stormRelativeVelocity?: boolean;
+};
+
+/**
+ * Level-III menu: subset aligned with products we decode as radial symbology (packets 0x0010 / 0xAF1F).
+ * See product codes vs mnemonics: https://supercell-wx.readthedocs.io/en/stable/features/nexrad-l3.html
+ *
+ * Intentionally omitted for now: legacy/digital precip variants (OHA/DPA/DSP/DU6/DOD/DSD/DPR) not wired in menu,
+ * NET/N0M, and base N0G-only velocity (menu keeps storm-relative VEL = N0G + N0S only).
+ *
+ * Terminal (TDWR) radars: only storm-relative velocity ({@link nexradStormRelativeVelocityUsesLevel2TiltAndFetch}) is
+ * exposed as Level-III in the UI; other Level-III products are WSR-88D-only in this app.
+ */
+export const NEXRAD_LEVEL3_MENU: NexradLevel3MenuEntry[] = [
+    {
+        radarKey: 'VEL',
+        product: 'N0G',
+        menuLabel: 'Storm Relative Velocity',
+        fldKey: 'nexrad_vel',
+        cmapPropertyKey: 'nexrad_vel',
+        decodeMode: 'velocity',
+        stormRelativeVelocity: true,
+    },
+    {
+        radarKey: 'KDP',
+        product: 'N0K',
+        menuLabel: 'Specific Differential Phase',
+        fldKey: 'nexrad_l3_n0k',
+        cmapPropertyKey: 'nexrad_kdp',
+        defaultUnit: 'deg/km',
+        decodeMode: 'generic_physical',
+    },
+    {
+        radarKey: 'N0H',
+        product: 'N0H',
+        menuLabel: 'Hydrometeor Classification',
+        fldKey: 'nexrad_l3_n0h',
+        cmapPropertyKey: 'nexrad_l3_n0h',
+        defaultUnit: 'None',
+        decodeMode: 'categorical',
+    },
+    {
+        radarKey: 'HHC',
+        product: 'HHC',
+        menuLabel: 'Hybrid Hydrometeor Classification',
+        fldKey: 'nexrad_l3_hhc',
+        cmapPropertyKey: 'nexrad_l3_hhc',
+        defaultUnit: 'None',
+        decodeMode: 'categorical',
+    },
+    {
+        radarKey: 'EET',
+        product: 'EET',
+        menuLabel: 'Enhanced Echo Tops',
+        fldKey: 'nexrad_l3_eet',
+        cmapPropertyKey: 'nexrad_l3_eet',
+        defaultUnit: 'kft',
+        decodeMode: 'tops_kft',
+    },
+    {
+        radarKey: 'DVL',
+        product: 'DVL',
+        menuLabel: 'Vertically Integrated Liquid',
+        fldKey: 'nexrad_l3_dvl',
+        cmapPropertyKey: 'nexrad_l3_dvl',
+        defaultUnit: 'kg/m²',
+        decodeMode: 'vil',
+    },
+    {
+        radarKey: 'DAA',
+        product: 'DAA',
+        menuLabel: '1-Hour Precipitation',
+        fldKey: 'nexrad_l3_daa',
+        cmapPropertyKey: 'tp_0_1',
+        defaultUnit: 'in',
+        decodeMode: 'precip',
+    },
+    {
+        radarKey: 'DU3',
+        product: 'DU3',
+        menuLabel: '3-Hour Precipitation',
+        fldKey: 'nexrad_l3_du3',
+        cmapPropertyKey: 'tp_0_total',
+        defaultUnit: 'in',
+        decodeMode: 'precip',
+    },
+    {
+        radarKey: 'DTA',
+        product: 'DTA',
+        menuLabel: 'Storm Total Precipitation',
+        fldKey: 'nexrad_l3_dta',
+        cmapPropertyKey: 'tp_0_total',
+        defaultUnit: 'in',
+        decodeMode: 'precip',
+    },
+];
+
+const byRadarKey = new Map<string, NexradLevel3MenuEntry>();
+for (const e of NEXRAD_LEVEL3_MENU) {
+    byRadarKey.set(e.radarKey, e);
+    // Backward compatibility: older saved layers used radarVariable=NVL.
+    if (e.radarKey === 'DVL') byRadarKey.set('NVL', e);
+}
+
+export function getNexradLevel3EntryByRadarKey(radarKey: string): NexradLevel3MenuEntry | undefined {
+    return byRadarKey.get(radarKey);
+}
+
+/** Digital Specific Differential Phase (163): S3 mnemonic per elevation slot (ICD order, low → high). */
+export const NEXRAD_LEVEL3_KDP_PRODUCTS: readonly string[] = [
+    'NXK',
+    'NYK',
+    'NZK',
+    'N0K',
+    'NAK',
+    'N1K',
+    'NBK',
+    'N2K',
+    'N3K',
+];
+
+/** Digital Hydrometeor Classification (165): S3 mnemonic per elevation slot (ICD order, low → high). */
+export const NEXRAD_LEVEL3_DHC_PRODUCTS: readonly string[] = [
+    'NXH',
+    'NYH',
+    'NZH',
+    'N0H',
+    'NAH',
+    'N1H',
+    'NBH',
+    'N2H',
+    'N3H',
+];
+
+/**
+ * Level-III KDP/DHC products aligned with {@link getRadarTilts} indices (lowest manifest tilt first).
+ * NXK/NYK/NZK (and NXH…) are sub–0.5° cuts; our tilt manifest for KDP/N0H starts at ~0.5° like REF,
+ * so index 0 must map to N0K/N0H — matching historical behavior before multi-tilt wiring.
+ */
+const NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_KDP_PRODUCTS.slice(3);
+const NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_DHC_PRODUCTS.slice(3);
+
+/** Super-res base radial velocity (154): S3 mnemonic per elevation (ICD order, low → high). */
+export const NEXRAD_LEVEL3_VELOCITY_PRODUCTS: readonly string[] = [
+    'NXG', 'NYG', 'NZG', 'N0G', 'NAG', 'N1G', 'NBG', 'N2G', 'N3G',
+];
+const NEXRAD_LEVEL3_VELOCITY_PRODUCTS_FOR_MANIFEST: readonly string[] = NEXRAD_LEVEL3_VELOCITY_PRODUCTS.slice(3);
+
+/**
+ * Level-III KDP / digital HC (N0H): one S3 mnemonic per manifest slot in
+ * {@link NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST} / {@link NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST}.
+ * The UI and composite keys use the first this many tilts from {@link getRadarTilts} (site order), not a fixed elevation angle.
+ */
+export const NEXRAD_LEVEL3_MANIFEST_TILT_COUNT = NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST.length;
+
+/** Tilts available for Level-III KDP / N0H: same order as Level II, truncated after the Nth tilt ({@link NEXRAD_LEVEL3_MANIFEST_TILT_COUNT}). */
+export function getNexradLevel3RadarTilts(siteId: string, radarVariable: string): number[] {
+    return getRadarTilts(siteId, radarVariable).slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
+}
+
+/** Tilts for super-res L3 velocity (N*G), same manifest cap as KDP/N0H. */
+export function getNexradLevel3RadarTiltsForVelocity(siteId: string): number[] {
+    return getRadarTilts(siteId, 'VEL').slice(0, NEXRAD_LEVEL3_MANIFEST_TILT_COUNT);
+}
+
+/**
+ * Map site tilt to L3 super-res base velocity mnemonic (N0G, NAG, …) for Unidata S3 keys / stable GPU layout — aguacero-frontend parity.
+ */
+export function nexradLevel3S3VelocityProductForSiteTilt(siteId: string, tilt: number): string {
+    const products = NEXRAD_LEVEL3_VELOCITY_PRODUCTS_FOR_MANIFEST;
+    const tilts = getNexradLevel3RadarTiltsForVelocity(siteId);
+    if (!tilts.length) {
+        return products[0]!;
+    }
+    const clamped = clampNexradTiltForVariable(siteId, 'VEL', tilt);
+    let idx = tilts.indexOf(clamped);
+    if (idx === -1) {
+        idx = tilts.reduce(
+            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
+            0,
+        );
+    }
+    idx = Math.min(idx, products.length - 1);
+    return products[idx]!;
+}
+
+export function nexradLevel3IsTiltIndexedKdpProduct(product: string): boolean {
+    return NEXRAD_LEVEL3_KDP_PRODUCTS.includes(product);
+}
+
+export function nexradLevel3IsTiltIndexedDhcProduct(product: string): boolean {
+    return NEXRAD_LEVEL3_DHC_PRODUCTS.includes(product);
+}
+
+/** Layer variable is KDP or digital HC (N0H); user tilt maps to NXK..N3K / NXH..N3H. */
+export function nexradLevel3UsesTiltIndexedS3Products(radarVariable: string | undefined): boolean {
+    const v = radarVariable || '';
+    return v === 'KDP' || v === 'N0H';
+}
+
+/**
+ * Clamp stored tilt for composite keys / fetches when `radarVariable` is KDP or N0H on true Level III.
+ */
+export function clampTiltForLevel3CompositeKey(siteId: string, radarVariable: string, tilt: number): number {
+    if (!nexradLevel3UsesTiltIndexedS3Products(radarVariable)) {
+        return clampNexradTiltForVariable(siteId, radarVariable, tilt);
+    }
+    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
+    const c = clampNexradTiltForVariable(siteId, radarVariable, tilt);
+    if (!tilts.length) return c;
+    return nearestTiltInSortedList(tilts, c);
+}
+
+/**
+ * Cross section fetches: one S3 product per manifest tilt in {@link getRadarTilts} order (capped by
+ * ICD mnemonic count). Uses the full NXK–N3K / NXH–N3H tables; when the lowest tilt is at or above
+ * ~0.5°, the first slot is N0K / N0H (skipping NX, NY, NZ sub-half-degree products).
+ */
+export function nexradLevel3CrossSectionTiltProductJobs(
+    siteId: string,
+    radarVariable: 'KDP' | 'N0H',
+): { tiltDeg: number; product: string }[] {
+    const products =
+        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS : NEXRAD_LEVEL3_DHC_PRODUCTS;
+    const tilts = getRadarTilts(siteId, radarVariable);
+    if (!tilts.length) return [];
+    const low = tilts[0]!;
+    const startSlot = low >= 0.45 ? 3 : 0;
+    const nSlots = Math.min(tilts.length, products.length - startSlot);
+    const out: { tiltDeg: number; product: string }[] = [];
+    for (let i = 0; i < nSlots; i++) {
+        out.push({ tiltDeg: tilts[i]!, product: products[startSlot + i]! });
+    }
+    return out;
+}
+
+/**
+ * Map site tilt to Level-III S3 product (N0K, NAK, … / N0H, …) for map tiles and time keys.
+ */
+export function nexradLevel3S3ProductForSiteTilt(
+    siteId: string,
+    radarVariable: 'KDP' | 'N0H',
+    tilt: number,
+): string {
+    const products =
+        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
+    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
+    if (!tilts.length) {
+        return products[0]!;
+    }
+    const clamped = clampTiltForLevel3CompositeKey(siteId, radarVariable, tilt);
+    let idx = tilts.indexOf(clamped);
+    if (idx === -1) {
+        idx = tilts.reduce(
+            (bestI, t, i) => (Math.abs(t - clamped) < Math.abs(tilts[bestI]! - clamped) ? i : bestI),
+            0,
+        );
+    }
+    idx = Math.min(idx, products.length - 1);
+    return products[idx]!;
+}
+
+/** Elevation string for `SITE_VAR_elev_level3` keys / UI — matches manifest slot for this S3 product. */
+export function nexradLevel3DisplayElevForS3Product(
+    siteId: string,
+    radarVariable: 'KDP' | 'N0H',
+    s3Product: string,
+): string {
+    const tilts = getNexradLevel3RadarTilts(siteId, radarVariable);
+    if (!tilts.length) return NEXRAD_LEVEL3_ELEV;
+
+    const manifestProducts =
+        radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS_FOR_MANIFEST : NEXRAD_LEVEL3_DHC_PRODUCTS_FOR_MANIFEST;
+    let idx = manifestProducts.indexOf(s3Product);
+    if (idx >= 0) {
+        const t = tilts[Math.min(idx, tilts.length - 1)]!;
+        return formatTiltForApi(t);
+    }
+
+    /** NXK/NYK/NZK (or NXH…) from listings: not in manifest-ordered slice — use lowest tilt for keying. */
+    const full = radarVariable === 'KDP' ? NEXRAD_LEVEL3_KDP_PRODUCTS : NEXRAD_LEVEL3_DHC_PRODUCTS;
+    const fullIdx = full.indexOf(s3Product);
+    if (fullIdx >= 0 && fullIdx < 3) {
+        return formatTiltForApi(tilts[0]!);
+    }
+    if (fullIdx >= 3) {
+        const mIdx = fullIdx - 3;
+        const t = tilts[Math.min(mIdx, tilts.length - 1)]!;
+        return formatTiltForApi(t);
+    }
+    return NEXRAD_LEVEL3_ELEV;
+}
+
+/**
+ * Level-III products that are not tied to a selectable sweep (precip accumulations, echo tops, VIL,
+ * hybrid HC, etc.). Hide tilt controls and ignore tilt stepping for these.
+ * Digital HC (N0H) and KDP use {@link nexradLevel3UsesTiltIndexedS3Products}.
+ */
+const LEVEL3_DECODE_MODES_WITHOUT_USER_TILT: ReadonlySet<Level3DecodeMode> = new Set([
+    'precip',
+    'tops_kft',
+    'vil',
+    'categorical',
+]);
+
+export function nexradLevel3DisallowsUserTiltChange(radarVariable: string | undefined): boolean {
+    if (nexradLevel3UsesTiltIndexedS3Products(radarVariable)) return false;
+    const entry = getNexradLevel3EntryByRadarKey(radarVariable || '');
+    if (!entry) return false;
+    if (entry.stormRelativeVelocity) return false;
+    return LEVEL3_DECODE_MODES_WITHOUT_USER_TILT.has(entry.decodeMode);
+}
+
+/**
+ * Cross sections stack multiple elevation sweeps. True Level-III products that are a single grid
+ * (precipitation totals, echo tops, VIL, hybrid HC, etc.) cannot produce a pseudo-RHI — skip fetches.
+ */
+export function nexradCrossSectionBlockedReason(layer: {
+    radar?: string | null;
+    radarDataSource?: string;
+    radarVariable?: string;
+    level3StormRelative?: boolean;
+}): string | null {
+    if (!nexradLayerUsesTrueLevel3Listing(layer)) return null;
+    if (!nexradLevel3DisallowsUserTiltChange(layer.radarVariable)) return null;
+    const entry = getNexradLevel3EntryByRadarKey(layer.radarVariable || '');
+    const label = entry?.menuLabel ?? layer.radarVariable ?? 'this product';
+    return `Cross sections are not available for ${label}.`;
+}
+
+/** True Level-III map products (not storm-relative velocity, which uses Level II + motion). */
+export function nexradLayerUsesTrueLevel3Listing(layer: {
+    radar?: string | null;
+    radarDataSource?: string;
+    radarVariable?: string;
+    level3StormRelative?: boolean;
+}): boolean {
+    return (
+        layer.radarDataSource === 'level3' && !nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)
+    );
+}
+
+/** Terminal radars do not support true Level-III map products in this app (SRV only). */
+export function terminalRadarBlocksTrueLevel3(layer: {
+    radar?: string | null;
+    radarDataSource?: string;
+    radarVariable?: string;
+    level3StormRelative?: boolean;
+}): boolean {
+    const site = layer.radar || '';
+    return isTerminalRadar(site) && nexradLayerUsesTrueLevel3Listing(layer);
+}
+
+/** Digital (N0H) and hybrid (HHC) hydrometeor classification — discrete classes, not a continuous field. */
+export function nexradLevel3IsHydrometeorClassification(radarVariable: string | undefined): boolean {
+    const v = radarVariable || '';
+    return v === 'N0H' || v === 'HHC';
+}
+
+export type Level3ExpandTarget = { radarKey: string; attachMotionMap: boolean };
+
+/** Map raw S3 product code to one or more formatted time-anchor variables. */
+export function getLevel3ExpansionTargetsForS3Product(product: string): Level3ExpandTarget[] {
+    if (product === NEXRAD_LEVEL3_MOTION_PRODUCT) {
+        return [];
+    }
+    if (product === 'DVL') {
+        // Emit both keys so old NVL layers and new DVL layers resolve the same time map.
+        return [
+            { radarKey: 'DVL', attachMotionMap: false },
+            { radarKey: 'NVL', attachMotionMap: false },
+        ];
+    }
+    if (product === 'N0G') {
+        return [
+            { radarKey: 'N0G', attachMotionMap: false },
+            { radarKey: 'VEL', attachMotionMap: true },
+        ];
+    }
+    if (nexradLevel3IsTiltIndexedKdpProduct(product)) {
+        return [{ radarKey: 'KDP', attachMotionMap: false }];
+    }
+    if (nexradLevel3IsTiltIndexedDhcProduct(product)) {
+        return [{ radarKey: 'N0H', attachMotionMap: false }];
+    }
+    return [{ radarKey: product, attachMotionMap: false }];
+}
+
+/**
+ * Product 135 (EET): MetPy `DigitalEETMapper` uses PDB thr1–thr3 as data mask, scale, and offset:
+ * `mapped = ((level & mask) - offset) / scale` (raw signed halfwords — no /10; unlike dBZ min/inc).
+ *
+ * Output is treated as **kilometers** end-to-end with the rest of `tops_kft` packing.
+ */
+export function level3EetHeightKmFromLevel(
+    level: number,
+    dataMaskRaw: number,
+    scaleRaw: number,
+    offsetRaw: number,
+): number | null {
+    if (level < 2) return null;
+    const masked = level & (dataMaskRaw & 0xffff);
+    if (!Number.isFinite(scaleRaw) || scaleRaw === 0) {
+        return level - 2;
+    }
+    const mapped = (masked - offsetRaw) / scaleRaw;
+    if (!Number.isFinite(mapped)) return null;
+    return mapped;
+}
+
+export function level3ValuePacking(decodeMode: Level3DecodeMode): { valueScale: number; valueOffset: number } {
+    switch (decodeMode) {
+        case 'velocity':
+            return { valueScale: 0.01, valueOffset: 0 };
+        case 'dbz':
+            return { valueScale: 0.5, valueOffset: -32 };
+        case 'precip':
+            return { valueScale: 0.001, valueOffset: 0 };
+        case 'categorical':
+            return { valueScale: 1, valueOffset: 0 };
+        case 'tops_kft':
+            // Shader physical = raw * valueScale (km). raw = round(km / valueScale) must stay within int16.
+            // 0.001 implied raw = meters → tops >32.767 km clamped (seen on EET ~48 km). Use 2 m/LSb → max ~65.5 km.
+            return { valueScale: 0.002, valueOffset: 0 };
+        case 'vil':
+            return { valueScale: 0.1, valueOffset: 0 };
+        case 'generic_physical':
+            return { valueScale: 0.01, valueOffset: 0 };
+        default:
+            return { valueScale: 0.5, valueOffset: -32 };
+    }
+}
+
+/**
+ * Opt-in storm-relative velocity (super-res VEL + N0S motion). Set in localStorage to trace: DEBUG_NEXRAD_VEL=1
+ */
+function nexradVelDebug(label: string, data: Record<string, unknown>) {
+    try {
+        if (typeof localStorage !== 'undefined' && localStorage.getItem('DEBUG_NEXRAD_VEL') === '1') {
+            console.log(`[NEXRAD_VEL] ${label}`, data);
+        }
+    } catch {
+        /* ignore */
+    }
+}
+
+/**
+ * Storm-relative velocity is rendered from Level-2 super-res VEL at the user’s tilt plus L3 N0S motion.
+ * Layers may still have `radarDataSource: 'level3'` when chosen from the Level-III menu.
+ *
+ * `level3StormRelative === undefined` must NOT default to “on” for Level-II velocity (that broke base VEL).
+ * For legacy layers with L3-menu VEL and no flag, infer SRV only when `radarDataSource === 'level3'`.
+ */
+export function nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer: {
+    radar?: string | null;
+    radarVariable?: string;
+    level3StormRelative?: boolean;
+    radarDataSource?: string;
+}): boolean {
+    if ((layer.radarVariable || 'REF') !== 'VEL') {
+        return false;
+    }
+    if (layer.level3StormRelative === true) return true;
+    if (layer.level3StormRelative === false) return false;
+    const inferred = (layer.radarDataSource || 'level2') === 'level3';
+    nexradVelDebug('VEL level3StormRelative missing — infer from radarDataSource', {
+        radar: layer.radar,
+        radarDataSource: layer.radarDataSource,
+        useStormRelativeVelocity: inferred,
+    });
+    return inferred;
+}
+
+/**
+ * True when composite time keys and map wiring should use `layer.radarTilt` (like Level II), not a fixed 0.5° token.
+ */
+export function nexradLevel3LayerUsesRadarTiltInCompositeKeys(layer: {
+    radar?: string | null;
+    radarVariable?: string;
+    radarDataSource?: string;
+    level3StormRelative?: boolean;
+}): boolean {
+    if (layer.radarDataSource !== 'level3') return false;
+    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) return false;
+    return nexradLevel3UsesTiltIndexedS3Products(layer.radarVariable);
+}
+
+export function nexradEffectiveFetchSource(layer: {
+    radar?: string | null;
+    radarVariable?: string;
+    radarDataSource?: string;
+    level3StormRelative?: boolean;
+}): 'level2' | 'level3' {
+    if (terminalRadarBlocksTrueLevel3(layer)) return 'level2';
+    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) return 'level2';
+    return layer.radarDataSource === 'level3' ? 'level3' : 'level2';
+}
+
+export function nexradTimesFetchOptionsFromLayer(layer: {
+    radar?: string | null;
+    radarVariable?: string;
+    radarDataSource?: string;
+    level3StormRelative?: boolean;
+    radarTilt?: number | null;
+}): { level3Product?: string; level3StormRelative?: boolean } | undefined {
+    if (terminalRadarBlocksTrueLevel3(layer)) return undefined;
+    /** L2 fetch + N0S time alignment for storm-relative velocity (super-res VEL + motion). */
+    if (nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer)) {
+        return { level3StormRelative: true };
+    }
+    if (layer.radarDataSource !== 'level3') return undefined;
+    const v = layer.radarVariable || 'REF';
+    const entry = getNexradLevel3EntryByRadarKey(v);
+    let product = entry?.product ?? (v === 'VEL' ? 'N0G' : v);
+    const site = layer.radar || '';
+    if (site && nexradLevel3UsesTiltIndexedS3Products(v)) {
+        const tilt = layer.radarTilt ?? getDefaultRadarTilt(site);
+        product = nexradLevel3S3ProductForSiteTilt(site, v as 'KDP' | 'N0H', tilt);
+    }
+    const stormRelative = v === 'VEL' ? nexradStormRelativeVelocityUsesLevel2TiltAndFetch(layer) : false;
+    return { level3Product: product, level3StormRelative: stormRelative };
+}
+
+export function formatLevel3TiltForApi(): string {
+    return NEXRAD_LEVEL3_ELEV;
+}