@aguacerowx/javascript-sdk 0.0.23 → 0.0.24

package/src/nexrad_support.js

@@ -1,306 +1,306 @@
-/**
- * NEXRAD Level-II / Level-III time listings (aligned with aguacero-frontend nexradTimes.ts).
- */
-
-import {
-    formatTiltForApi,
-    clampNexradTiltForVariable,
-    getDefaultRadarTilt,
-    getRadarTilts,
-} from './nexradTilts.js';
-import { coalesceNexradTiltOptionsForDisplay } from './nexradTiltCoalesce.js';
-import {
-    NEXRAD_LEVEL3_ELEV,
-    NEXRAD_LEVEL3_MOTION_PRODUCT,
-    getNexradLevel3EntryByRadarKey,
-} from './nexrad_level3_catalog.js';
-
-/**
- * Whether listings and archive fetches for this product use Level-II sweep lambda vs Level-III S3 products.
- * AguaceroCore derives this from the product key only (not user-configurable).
- * @param {string} [nexradProduct] - Radar variable key (e.g. REF, KDP, VEL).
- * @returns {'level2'|'level3'}
- */
-export function inferNexradDataSourceForProduct(nexradProduct) {
-    const p = (nexradProduct || 'REF').toUpperCase();
-    return getNexradLevel3EntryByRadarKey(p) ? 'level3' : 'level2';
-}
-
-/** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
-export function nexradColormapFldKey(nexradDataSource, nexradProduct) {
-    const p = (nexradProduct || 'REF').toUpperCase();
-    if (nexradDataSource === 'level3') {
-        const entry = getNexradLevel3EntryByRadarKey(p);
-        return entry?.fldKey ?? `nexrad_l3_${p.toLowerCase()}`;
-    }
-    const map = {
-        REF: 'nexrad_ref',
-        PHI: 'nexrad_phi',
-        ZDR: 'nexrad_zdr',
-        RHO: 'nexrad_rho',
-        KDP: 'nexrad_kdp',
-        VEL: 'nexrad_vel',
-        SW: 'nexrad_sw',
-    };
-    return map[p] ?? `nexrad_${p.toLowerCase()}`;
-}
-
-export const NEXRAD_SWEEP_LAMBDA_URL = 'https://ddknicwcw2wyov7v5bzxmbqu440tzntf.lambda-url.us-east-2.on.aws/';
-export const NEXRAD_LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
-
-const NEXRAD_GROUP_G1 = ['REF', 'PHI', 'ZDR', 'RHO'];
-const NEXRAD_GROUP_G2 = ['VEL', 'SW'];
-
-export function variableToNexradGroup(variable) {
-    const v = (variable || 'REF').toUpperCase();
-    if (NEXRAD_GROUP_G2.includes(v)) return 'g2';
-    return 'g1';
-}
-
-export function nexradBinGroupIdForKey(cacheGroup) {
-    return cacheGroup === 'g1' ? 1 : 2;
-}
-
-function getLevel3StationPrefix(stationId) {
-    const upper = (stationId || '').toUpperCase();
-    if (upper.startsWith('K') && upper.length === 4) return upper.slice(1);
-    return upper.slice(-3);
-}
-
-function parseS3KeyTimeToUnix(key) {
-    const m = key.match(/_(\d{4})_(\d{2})_(\d{2})_(\d{2})_(\d{2})_(\d{2})$/);
-    if (!m) return null;
-    const [, y, mo, d, h, mi, s] = m;
-    const unix = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) / 1000;
-    return Number.isFinite(unix) ? unix : null;
-}
-
-export async function fetchLevel3ProductTimesForStation(stationId, productCode, listWindowHours) {
-    const stationPrefix = getLevel3StationPrefix(stationId);
-    const nowMs = Date.now();
-    const nowSec = Math.floor(nowMs / 1000);
-    const hourSec = 3600;
-    const windowSec = Math.max(hourSec, Math.ceil(listWindowHours) * hourSec);
-
-    const dayPrefixForOffset = (dayOff) => {
-        const dt = new Date(nowMs - dayOff * 86400000);
-        const y = dt.getUTCFullYear();
-        const mo = String(dt.getUTCMonth() + 1).padStart(2, '0');
-        const day = String(dt.getUTCDate()).padStart(2, '0');
-        return `${stationPrefix}_${productCode}_${y}_${mo}_${day}_`;
-    };
-
-    const dayPrefixes = [dayPrefixForOffset(0), dayPrefixForOffset(1)];
-    const byUnix = new Map();
-
-    const listKeysForPrefix = async (prefix) => {
-        let continuationToken = null;
-        for (let page = 0; page < 8; page++) {
-            const params = new URLSearchParams({
-                'list-type': '2',
-                prefix,
-                'max-keys': '1000',
-            });
-            if (continuationToken) params.set('continuation-token', continuationToken);
-            const res = await fetch(`${NEXRAD_LEVEL3_BASE_URL}/?${params.toString()}`);
-            if (!res.ok) throw new Error(`Level3 list HTTP ${res.status}`);
-            const xml = await res.text();
-            const keyMatches = [...xml.matchAll(/<Key>([^<]+)<\/Key>/g)];
-            keyMatches.forEach((match) => {
-                const objectKey = match[1];
-                const unix = parseS3KeyTimeToUnix(objectKey);
-                if (unix == null) return;
-                byUnix.set(unix, objectKey);
-            });
-            const tokenMatch = xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/);
-            continuationToken = tokenMatch?.[1] || null;
-            if (!continuationToken) break;
-        }
-    };
-
-    for (const prefix of dayPrefixes) {
-        await listKeysForPrefix(prefix);
-    }
-
-    const sorted = [...byUnix.keys()].sort((a, b) => a - b);
-    const windowStart = nowSec - windowSec;
-    let inWindow = sorted.filter((t) => t >= windowStart);
-    if (inWindow.length === 0 && sorted.length > 0) {
-        inWindow = sorted.filter((t) => t >= nowSec - Math.max(6 * hourSec, windowSec));
-    }
-    if (inWindow.length === 0 && sorted.length > 0) {
-        inWindow = sorted.slice(-48);
-    }
-
-    const timeToKeyMap = {};
-    inWindow.forEach((t) => {
-        const k = byUnix.get(t);
-        if (k) timeToKeyMap[String(t)] = k;
-    });
-
-    return { unixTimes: inWindow, timeToKeyMap };
-}
-
-/**
- * @param {object} opts
- * @param {string} opts.stationId
- * @param {string} [opts.variable]
- * @param {string} [opts.elev]
- * @param {'level2'|'level3'} [opts.source]
- * @param {boolean} [opts.level3StormRelative]
- * @param {number} opts.listingWindowHours
- */
-export async function fetchNexradTimesListing(opts) {
-    const {
-        stationId,
-        variable = 'REF',
-        elev,
-        source = 'level2',
-        level3StormRelative,
-        listingWindowHours,
-    } = opts;
-    if (!stationId) {
-        return { unixTimes: [], timeToKeyMap: {}, level3MotionUnixTimes: [], level3MotionTimeToKeyMap: {} };
-    }
-
-    const dataSource = source === 'level3' ? 'level3' : 'level2';
-    let tiltNum = Number(elev);
-    if (!Number.isFinite(tiltNum)) tiltNum = getDefaultRadarTilt(stationId);
-    const elevNormUse =
-        dataSource === 'level3'
-            ? NEXRAD_LEVEL3_ELEV
-            : formatTiltForApi(clampNexradTiltForVariable(stationId, variable, tiltNum));
-    const group = dataSource === 'level3' ? 'l3' : variableToNexradGroup(variable);
-    const l3Product =
-        dataSource === 'level3'
-            ? opts.level3Product ??
-              getNexradLevel3EntryByRadarKey(variable)?.product ??
-              (variable === 'VEL' ? 'N0G' : variable)
-            : '';
-    const fetchL3Motion =
-        dataSource === 'level3' &&
-        l3Product === 'N0G' &&
-        variable === 'VEL' &&
-        level3StormRelative === true;
-    const fetchL2VelMotion =
-        dataSource === 'level2' && variable === 'VEL' && level3StormRelative === true;
-
-    const key =
-        dataSource === 'level3'
-            ? `${stationId}_l3_${l3Product}_${elevNormUse}`
-            : `${stationId}_${group}_${elevNormUse}`;
-    const level3MotionKey =
-        dataSource === 'level3' && fetchL3Motion
-            ? `${stationId}_l3_${NEXRAD_LEVEL3_MOTION_PRODUCT}_${elevNormUse}`
-            : '';
-    const l2StormMotionListKey =
-        dataSource === 'level2' && fetchL2VelMotion
-            ? `${stationId}_l3_${NEXRAD_LEVEL3_MOTION_PRODUCT}_${NEXRAD_LEVEL3_ELEV}`
-            : '';
-
-    let times = [];
-    let timeToKeyMap = {};
-    let l3MotionUnixTimes = [];
-    let l3MotionTimeToKeyMap = {};
-
-    if (dataSource === 'level3') {
-        const l3Primary = await fetchLevel3ProductTimesForStation(stationId, l3Product, listingWindowHours);
-        times = l3Primary.unixTimes;
-        timeToKeyMap = l3Primary.timeToKeyMap;
-        if (fetchL3Motion) {
-            const l3Motion = await fetchLevel3ProductTimesForStation(
-                stationId,
-                NEXRAD_LEVEL3_MOTION_PRODUCT,
-                listingWindowHours,
-            );
-            l3MotionUnixTimes = l3Motion.unixTimes;
-            l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
-        }
-    } else {
-        const params = new URLSearchParams({
-            station: stationId,
-            field: group,
-            elev: elevNormUse,
-            hours: String(listingWindowHours),
-        });
-        const url = `${NEXRAD_SWEEP_LAMBDA_URL}?${params.toString()}`;
-        const res = await fetch(url);
-        if (!res.ok) throw new Error(`NEXRAD lambda HTTP ${res.status}`);
-        const data = await res.json();
-        if (Array.isArray(data?.times)) {
-            times = data.times;
-        } else if (data?.body) {
-            const body = typeof data.body === 'string' ? JSON.parse(data.body) : data.body;
-            times = Array.isArray(body?.times) ? body.times : [];
-        }
-        const groupId = nexradBinGroupIdForKey(group);
-        const elevNorm = elevNormUse;
-        times.forEach((t) => {
-            timeToKeyMap[String(t)] = `${stationId}_${elevNorm}_${t}_g${groupId}.bin`;
-        });
-        if (fetchL2VelMotion) {
-            const l3Motion = await fetchLevel3ProductTimesForStation(
-                stationId,
-                NEXRAD_LEVEL3_MOTION_PRODUCT,
-                listingWindowHours,
-            );
-            l3MotionUnixTimes = l3Motion.unixTimes;
-            l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
-        }
-    }
-
-    const out = {
-        cacheKey: key,
-        unixTimes: times,
-        timeToKeyMap,
-        level3MotionKey: level3MotionKey || null,
-        level3MotionUnixTimes: l3MotionUnixTimes,
-        level3MotionTimeToKeyMap: l3MotionTimeToKeyMap,
-        l2StormMotionListKey: l2StormMotionListKey || null,
-    };
-    return out;
-}
-
-const L3_TILT_INDEX_MANIFEST_SLOTS = 6;
-
-/**
- * Raw manifest tilt list before coalescing (same rules as aguacero-frontend `radarTiltOptionsRaw`).
- * Use {@link coalesceNexradTiltOptionsForDisplay} or {@link getAvailableNexradTilts} for UI controls.
- *
- * @param {string} siteId
- * @param {'level2'|'level3'} nexradDataSource
- * @param {string} [nexradProduct]
- * @returns {number[]}
- */
-export function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
-    if (!siteId) return [];
-    const v = (nexradProduct || 'REF').toUpperCase();
-    const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
-    const tilts = getRadarTilts(siteId, v);
-    /** L3 super-res VEL (N*G) uses the same first-N manifest slots as KDP/N0H — not the full L2 g2-only list. */
-    if (v === 'VEL') {
-        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
-    }
-    if (ds === 'level2') {
-        return [...tilts];
-    }
-    if (v === 'KDP' || v === 'N0H') {
-        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
-    }
-    return [];
-}
-
-/**
- * Tilt angles for the UI: manifest tilts with adjacent 0.1° steps merged like aguacero-frontend
- * ({@link coalesceNexradTiltOptionsForDisplay}).
- *
- * @param {string} siteId
- * @param {'level2'|'level3'} nexradDataSource
- * @param {string} [nexradProduct]
- * @returns {number[]}
- */
-export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
-    const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
-    if (!raw.length) return [];
-    return coalesceNexradTiltOptionsForDisplay(raw);
-}
+/**
+ * NEXRAD Level-II / Level-III time listings (aligned with aguacero-frontend nexradTimes.ts).
+ */
+
+import {
+    formatTiltForApi,
+    clampNexradTiltForVariable,
+    getDefaultRadarTilt,
+    getRadarTilts,
+} from './nexradTilts.js';
+import { coalesceNexradTiltOptionsForDisplay } from './nexradTiltCoalesce.js';
+import {
+    NEXRAD_LEVEL3_ELEV,
+    NEXRAD_LEVEL3_MOTION_PRODUCT,
+    getNexradLevel3EntryByRadarKey,
+} from './nexrad_level3_catalog.js';
+
+/**
+ * Whether listings and archive fetches for this product use Level-II sweep lambda vs Level-III S3 products.
+ * AguaceroCore derives this from the product key only (not user-configurable).
+ * @param {string} [nexradProduct] - Radar variable key (e.g. REF, KDP, VEL).
+ * @returns {'level2'|'level3'}
+ */
+export function inferNexradDataSourceForProduct(nexradProduct) {
+    const p = (nexradProduct || 'REF').toUpperCase();
+    return getNexradLevel3EntryByRadarKey(p) ? 'level3' : 'level2';
+}
+
+/** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
+export function nexradColormapFldKey(nexradDataSource, nexradProduct) {
+    const p = (nexradProduct || 'REF').toUpperCase();
+    if (nexradDataSource === 'level3') {
+        const entry = getNexradLevel3EntryByRadarKey(p);
+        return entry?.fldKey ?? `nexrad_l3_${p.toLowerCase()}`;
+    }
+    const map = {
+        REF: 'nexrad_ref',
+        PHI: 'nexrad_phi',
+        ZDR: 'nexrad_zdr',
+        RHO: 'nexrad_rho',
+        KDP: 'nexrad_kdp',
+        VEL: 'nexrad_vel',
+        SW: 'nexrad_sw',
+    };
+    return map[p] ?? `nexrad_${p.toLowerCase()}`;
+}
+
+export const NEXRAD_SWEEP_LAMBDA_URL = 'https://ddknicwcw2wyov7v5bzxmbqu440tzntf.lambda-url.us-east-2.on.aws/';
+export const NEXRAD_LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
+
+const NEXRAD_GROUP_G1 = ['REF', 'PHI', 'ZDR', 'RHO'];
+const NEXRAD_GROUP_G2 = ['VEL', 'SW'];
+
+export function variableToNexradGroup(variable) {
+    const v = (variable || 'REF').toUpperCase();
+    if (NEXRAD_GROUP_G2.includes(v)) return 'g2';
+    return 'g1';
+}
+
+export function nexradBinGroupIdForKey(cacheGroup) {
+    return cacheGroup === 'g1' ? 1 : 2;
+}
+
+function getLevel3StationPrefix(stationId) {
+    const upper = (stationId || '').toUpperCase();
+    if (upper.startsWith('K') && upper.length === 4) return upper.slice(1);
+    return upper.slice(-3);
+}
+
+function parseS3KeyTimeToUnix(key) {
+    const m = key.match(/_(\d{4})_(\d{2})_(\d{2})_(\d{2})_(\d{2})_(\d{2})$/);
+    if (!m) return null;
+    const [, y, mo, d, h, mi, s] = m;
+    const unix = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) / 1000;
+    return Number.isFinite(unix) ? unix : null;
+}
+
+export async function fetchLevel3ProductTimesForStation(stationId, productCode, listWindowHours) {
+    const stationPrefix = getLevel3StationPrefix(stationId);
+    const nowMs = Date.now();
+    const nowSec = Math.floor(nowMs / 1000);
+    const hourSec = 3600;
+    const windowSec = Math.max(hourSec, Math.ceil(listWindowHours) * hourSec);
+
+    const dayPrefixForOffset = (dayOff) => {
+        const dt = new Date(nowMs - dayOff * 86400000);
+        const y = dt.getUTCFullYear();
+        const mo = String(dt.getUTCMonth() + 1).padStart(2, '0');
+        const day = String(dt.getUTCDate()).padStart(2, '0');
+        return `${stationPrefix}_${productCode}_${y}_${mo}_${day}_`;
+    };
+
+    const dayPrefixes = [dayPrefixForOffset(0), dayPrefixForOffset(1)];
+    const byUnix = new Map();
+
+    const listKeysForPrefix = async (prefix) => {
+        let continuationToken = null;
+        for (let page = 0; page < 8; page++) {
+            const params = new URLSearchParams({
+                'list-type': '2',
+                prefix,
+                'max-keys': '1000',
+            });
+            if (continuationToken) params.set('continuation-token', continuationToken);
+            const res = await fetch(`${NEXRAD_LEVEL3_BASE_URL}/?${params.toString()}`);
+            if (!res.ok) throw new Error(`Level3 list HTTP ${res.status}`);
+            const xml = await res.text();
+            const keyMatches = [...xml.matchAll(/<Key>([^<]+)<\/Key>/g)];
+            keyMatches.forEach((match) => {
+                const objectKey = match[1];
+                const unix = parseS3KeyTimeToUnix(objectKey);
+                if (unix == null) return;
+                byUnix.set(unix, objectKey);
+            });
+            const tokenMatch = xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/);
+            continuationToken = tokenMatch?.[1] || null;
+            if (!continuationToken) break;
+        }
+    };
+
+    for (const prefix of dayPrefixes) {
+        await listKeysForPrefix(prefix);
+    }
+
+    const sorted = [...byUnix.keys()].sort((a, b) => a - b);
+    const windowStart = nowSec - windowSec;
+    let inWindow = sorted.filter((t) => t >= windowStart);
+    if (inWindow.length === 0 && sorted.length > 0) {
+        inWindow = sorted.filter((t) => t >= nowSec - Math.max(6 * hourSec, windowSec));
+    }
+    if (inWindow.length === 0 && sorted.length > 0) {
+        inWindow = sorted.slice(-48);
+    }
+
+    const timeToKeyMap = {};
+    inWindow.forEach((t) => {
+        const k = byUnix.get(t);
+        if (k) timeToKeyMap[String(t)] = k;
+    });
+
+    return { unixTimes: inWindow, timeToKeyMap };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.stationId
+ * @param {string} [opts.variable]
+ * @param {string} [opts.elev]
+ * @param {'level2'|'level3'} [opts.source]
+ * @param {boolean} [opts.level3StormRelative]
+ * @param {number} opts.listingWindowHours
+ */
+export async function fetchNexradTimesListing(opts) {
+    const {
+        stationId,
+        variable = 'REF',
+        elev,
+        source = 'level2',
+        level3StormRelative,
+        listingWindowHours,
+    } = opts;
+    if (!stationId) {
+        return { unixTimes: [], timeToKeyMap: {}, level3MotionUnixTimes: [], level3MotionTimeToKeyMap: {} };
+    }
+
+    const dataSource = source === 'level3' ? 'level3' : 'level2';
+    let tiltNum = Number(elev);
+    if (!Number.isFinite(tiltNum)) tiltNum = getDefaultRadarTilt(stationId);
+    const elevNormUse =
+        dataSource === 'level3'
+            ? NEXRAD_LEVEL3_ELEV
+            : formatTiltForApi(clampNexradTiltForVariable(stationId, variable, tiltNum));
+    const group = dataSource === 'level3' ? 'l3' : variableToNexradGroup(variable);
+    const l3Product =
+        dataSource === 'level3'
+            ? opts.level3Product ??
+              getNexradLevel3EntryByRadarKey(variable)?.product ??
+              (variable === 'VEL' ? 'N0G' : variable)
+            : '';
+    const fetchL3Motion =
+        dataSource === 'level3' &&
+        l3Product === 'N0G' &&
+        variable === 'VEL' &&
+        level3StormRelative === true;
+    const fetchL2VelMotion =
+        dataSource === 'level2' && variable === 'VEL' && level3StormRelative === true;
+
+    const key =
+        dataSource === 'level3'
+            ? `${stationId}_l3_${l3Product}_${elevNormUse}`
+            : `${stationId}_${group}_${elevNormUse}`;
+    const level3MotionKey =
+        dataSource === 'level3' && fetchL3Motion
+            ? `${stationId}_l3_${NEXRAD_LEVEL3_MOTION_PRODUCT}_${elevNormUse}`
+            : '';
+    const l2StormMotionListKey =
+        dataSource === 'level2' && fetchL2VelMotion
+            ? `${stationId}_l3_${NEXRAD_LEVEL3_MOTION_PRODUCT}_${NEXRAD_LEVEL3_ELEV}`
+            : '';
+
+    let times = [];
+    let timeToKeyMap = {};
+    let l3MotionUnixTimes = [];
+    let l3MotionTimeToKeyMap = {};
+
+    if (dataSource === 'level3') {
+        const l3Primary = await fetchLevel3ProductTimesForStation(stationId, l3Product, listingWindowHours);
+        times = l3Primary.unixTimes;
+        timeToKeyMap = l3Primary.timeToKeyMap;
+        if (fetchL3Motion) {
+            const l3Motion = await fetchLevel3ProductTimesForStation(
+                stationId,
+                NEXRAD_LEVEL3_MOTION_PRODUCT,
+                listingWindowHours,
+            );
+            l3MotionUnixTimes = l3Motion.unixTimes;
+            l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
+        }
+    } else {
+        const params = new URLSearchParams({
+            station: stationId,
+            field: group,
+            elev: elevNormUse,
+            hours: String(listingWindowHours),
+        });
+        const url = `${NEXRAD_SWEEP_LAMBDA_URL}?${params.toString()}`;
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`NEXRAD lambda HTTP ${res.status}`);
+        const data = await res.json();
+        if (Array.isArray(data?.times)) {
+            times = data.times;
+        } else if (data?.body) {
+            const body = typeof data.body === 'string' ? JSON.parse(data.body) : data.body;
+            times = Array.isArray(body?.times) ? body.times : [];
+        }
+        const groupId = nexradBinGroupIdForKey(group);
+        const elevNorm = elevNormUse;
+        times.forEach((t) => {
+            timeToKeyMap[String(t)] = `${stationId}_${elevNorm}_${t}_g${groupId}.bin`;
+        });
+        if (fetchL2VelMotion) {
+            const l3Motion = await fetchLevel3ProductTimesForStation(
+                stationId,
+                NEXRAD_LEVEL3_MOTION_PRODUCT,
+                listingWindowHours,
+            );
+            l3MotionUnixTimes = l3Motion.unixTimes;
+            l3MotionTimeToKeyMap = l3Motion.timeToKeyMap;
+        }
+    }
+
+    const out = {
+        cacheKey: key,
+        unixTimes: times,
+        timeToKeyMap,
+        level3MotionKey: level3MotionKey || null,
+        level3MotionUnixTimes: l3MotionUnixTimes,
+        level3MotionTimeToKeyMap: l3MotionTimeToKeyMap,
+        l2StormMotionListKey: l2StormMotionListKey || null,
+    };
+    return out;
+}
+
+const L3_TILT_INDEX_MANIFEST_SLOTS = 6;
+
+/**
+ * Raw manifest tilt list before coalescing (same rules as aguacero-frontend `radarTiltOptionsRaw`).
+ * Use {@link coalesceNexradTiltOptionsForDisplay} or {@link getAvailableNexradTilts} for UI controls.
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+export function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
+    if (!siteId) return [];
+    const v = (nexradProduct || 'REF').toUpperCase();
+    const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
+    const tilts = getRadarTilts(siteId, v);
+    /** L3 super-res VEL (N*G) uses the same first-N manifest slots as KDP/N0H — not the full L2 g2-only list. */
+    if (v === 'VEL') {
+        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+    }
+    if (ds === 'level2') {
+        return [...tilts];
+    }
+    if (v === 'KDP' || v === 'N0H') {
+        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+    }
+    return [];
+}
+
+/**
+ * Tilt angles for the UI: manifest tilts with adjacent 0.1° steps merged like aguacero-frontend
+ * ({@link coalesceNexradTiltOptionsForDisplay}).
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+    const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
+    if (!raw.length) return [];
+    return coalesceNexradTiltOptionsForDisplay(raw);
+}