@aguacerowx/javascript-sdk 0.0.28 → 0.0.29

package/dist/nexrad_support.js

@@ -0,0 +1,269 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NEXRAD_SWEEP_LAMBDA_URL = exports.NEXRAD_LEVEL3_BASE_URL = void 0;
+exports.fetchLevel3ProductTimesForStation = fetchLevel3ProductTimesForStation;
+exports.fetchNexradTimesListing = fetchNexradTimesListing;
+exports.getAvailableNexradTilts = getAvailableNexradTilts;
+exports.getRawNexradTiltsForCoalesce = getRawNexradTiltsForCoalesce;
+exports.inferNexradDataSourceForProduct = inferNexradDataSourceForProduct;
+exports.nexradBinGroupIdForKey = nexradBinGroupIdForKey;
+exports.nexradColormapFldKey = nexradColormapFldKey;
+exports.variableToNexradGroup = variableToNexradGroup;
+var _nexradTilts = require("./nexradTilts.js");
+var _nexradTiltCoalesce = require("./nexradTiltCoalesce.js");
+var _nexrad_level3_catalog = require("./nexrad_level3_catalog.js");
+/**
+ * NEXRAD Level-II / Level-III time listings (aligned with aguacero-frontend nexradTimes.ts).
+ */
+
+/**
+ * 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'}
+ */
+function inferNexradDataSourceForProduct(nexradProduct) {
+  const p = (nexradProduct || 'REF').toUpperCase();
+  return (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(p) ? 'level3' : 'level2';
+}
+
+/** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
+function nexradColormapFldKey(nexradDataSource, nexradProduct) {
+  const p = (nexradProduct || 'REF').toUpperCase();
+  if (nexradDataSource === 'level3') {
+    const entry = (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(p);
+    return (entry === null || entry === void 0 ? void 0 : 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()}`;
+}
+const NEXRAD_SWEEP_LAMBDA_URL = exports.NEXRAD_SWEEP_LAMBDA_URL = 'https://ddknicwcw2wyov7v5bzxmbqu440tzntf.lambda-url.us-east-2.on.aws/';
+const NEXRAD_LEVEL3_BASE_URL = exports.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'];
+function variableToNexradGroup(variable) {
+  const v = (variable || 'REF').toUpperCase();
+  if (NEXRAD_GROUP_G2.includes(v)) return 'g2';
+  return 'g1';
+}
+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;
+}
+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 === null || tokenMatch === void 0 ? void 0 : 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
+ */
+async function fetchNexradTimesListing(opts) {
+  var _getNexradLevel3Entry;
+  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 = (0, _nexradTilts.getDefaultRadarTilt)(stationId);
+  const elevNormUse = dataSource === 'level3' ? _nexrad_level3_catalog.NEXRAD_LEVEL3_ELEV : (0, _nexradTilts.formatTiltForApi)((0, _nexradTilts.clampNexradTiltForVariable)(stationId, variable, tiltNum));
+  const group = dataSource === 'level3' ? 'l3' : variableToNexradGroup(variable);
+  const l3Product = dataSource === 'level3' ? opts.level3Product ?? ((_getNexradLevel3Entry = (0, _nexrad_level3_catalog.getNexradLevel3EntryByRadarKey)(variable)) === null || _getNexradLevel3Entry === void 0 ? void 0 : _getNexradLevel3Entry.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_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT}_${elevNormUse}` : '';
+  const l2StormMotionListKey = dataSource === 'level2' && fetchL2VelMotion ? `${stationId}_l3_${_nexrad_level3_catalog.NEXRAD_LEVEL3_MOTION_PRODUCT}_${_nexrad_level3_catalog.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_catalog.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 === null || data === void 0 ? void 0 : data.times)) {
+      times = data.times;
+    } else if (data !== null && data !== void 0 && data.body) {
+      const body = typeof data.body === 'string' ? JSON.parse(data.body) : data.body;
+      times = Array.isArray(body === null || body === void 0 ? void 0 : 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_catalog.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[]}
+ */
+function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
+  if (!siteId) return [];
+  const v = (nexradProduct || 'REF').toUpperCase();
+  const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
+  const tilts = (0, _nexradTilts.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[]}
+ */
+function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+  const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
+  if (!raw.length) return [];
+  return (0, _nexradTiltCoalesce.coalesceNexradTiltOptionsForDisplay)(raw);
+}

package/dist/satellite_support.js

@@ -0,0 +1,395 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TIMELINE_DURATION_MAX_HOURS = exports.TIMELINE_DURATION_HOUR_VALUES = exports.SECTOR_CODE_MAP = exports.SATELLITE_FRAMES_URL = exports.SATELLITE_DURATION_CONFIG = exports.GOES_SATELLITE_CHANNEL_LABELS = exports.GOES_SATELLITE_CHANNELS = exports.GOES_EAST_SATELLITE_SECTORS = void 0;
+exports.buildSatelliteTimelineForSelection = buildSatelliteTimelineForSelection;
+exports.calculateUnixTimeFromSatelliteKey = calculateUnixTimeFromSatelliteKey;
+exports.formatTimelineDurationValue = formatTimelineDurationValue;
+exports.getAllGoesEastSatelliteSelections = getAllGoesEastSatelliteSelections;
+exports.getDefaultSatelliteDurationOption = getDefaultSatelliteDurationOption;
+exports.normalizeTimelineDurationValue = normalizeTimelineDurationValue;
+exports.parseTimelineDurationHours = parseTimelineDurationHours;
+exports.resolveSatelliteDurationOption = resolveSatelliteDurationOption;
+exports.resolveSatelliteS3FileName = resolveSatelliteS3FileName;
+exports.resolveSatelliteSectorLabel = resolveSatelliteSectorLabel;
+/**
+ * Satellite listing / timeline helpers aligned with aguacero-frontend (ActiveTimeContext + satelliteAvailability).
+ * Used by AguaceroCore for GOES-East WebGL satellite mode.
+ */
+
+const SATELLITE_FRAMES_URL = exports.SATELLITE_FRAMES_URL = 'https://rhnq3edhcry5n6nljn6my4o3h40zwxze.lambda-url.us-east-2.on.aws/';
+
+/** Same sector labels as production bundle / ActiveTimeContext SECTOR_CODE_MAP (inverse). */
+const GOES_EAST_SATELLITE_SECTORS = exports.GOES_EAST_SATELLITE_SECTORS = ['GOES-EAST CONUS', 'GOES-EAST FULL DISK', 'GOES-EAST MESOSCALE 1', 'GOES-EAST MESOSCALE 2'];
+const SECTOR_SYNONYM_TO_LABEL = {
+  conus: 'GOES-EAST CONUS',
+  full_disk: 'GOES-EAST FULL DISK',
+  fulldisk: 'GOES-EAST FULL DISK',
+  mesoscale_1: 'GOES-EAST MESOSCALE 1',
+  mesoscale1: 'GOES-EAST MESOSCALE 1',
+  m1: 'GOES-EAST MESOSCALE 1',
+  mesoscale_2: 'GOES-EAST MESOSCALE 2',
+  mesoscale2: 'GOES-EAST MESOSCALE 2',
+  m2: 'GOES-EAST MESOSCALE 2'
+};
+
+/**
+ * Normalizes a sector argument to the listing sector label (middle segment; must match archive paths).
+ * Accepts short tokens (<code>conus</code>, <code>full_disk</code>, …), synonyms (<code>m1</code>, <code>fulldisk</code>, …), or full labels (passthrough for West / custom feeds).
+ * @param {string} [sector]
+ * @returns {string}
+ */
+function resolveSatelliteSectorLabel(sector) {
+  if (sector == null || sector === '') return 'GOES-EAST CONUS';
+  const raw = String(sector).trim();
+  const norm = raw.toLowerCase().replace(/[\s-]+/g, '_');
+  if (SECTOR_SYNONYM_TO_LABEL[norm]) return SECTOR_SYNONYM_TO_LABEL[norm];
+  if (GOES_EAST_SATELLITE_SECTORS.includes(raw)) return raw;
+  return raw;
+}
+
+/** Flat channel ids matching CHANNEL_CATEGORIES in frontend dictionaries. */
+const GOES_SATELLITE_CHANNELS = exports.GOES_SATELLITE_CHANNELS = [...['true_color', 'geocolor', 'ntmicro', 'day_cloud_phase', 'day_land_cloud_fire', 'air_mass', 'sandwich', 'simple_water_vapor', 'dust', 'fire_temperature'], 'C01', 'C02', 'C03', 'C04', 'C05', 'C06', 'C07', 'C08', 'C09', 'C10', 'C11', 'C12', 'C13', 'C14', 'C15', 'C16'];
+
+/**
+ * Human-readable labels for {@link GOES_SATELLITE_CHANNELS}, aligned with aguacero-frontend `CHANNEL_LABELS`.
+ */
+const GOES_SATELLITE_CHANNEL_LABELS = exports.GOES_SATELLITE_CHANNEL_LABELS = {
+  true_color: 'True Color',
+  ntmicro: 'Night Microphysics',
+  day_cloud_phase: 'Day Cloud Phase',
+  day_land_cloud_fire: 'Natural Color Fire',
+  air_mass: 'Air Mass',
+  sandwich: 'Sandwich',
+  simple_water_vapor: 'Simple Water Vapor',
+  dust: 'Dust',
+  geocolor: 'Geocolor',
+  fire_temperature: 'Fire Temperature',
+  C01: 'Blue - Visible',
+  C02: 'Red - Visible',
+  C03: 'Veggie - Near IR',
+  C04: 'Cirrus - Near IR',
+  C05: 'Snow/Ice - Near IR',
+  C06: 'Cloud Particle - Near IR',
+  C07: 'Shortwave Window - IR',
+  C08: 'Upper-Level Water Vapor - IR',
+  C09: 'Mid-Level Water Vapor - IR',
+  C10: 'Lower-Level Water Vapor - IR',
+  C11: 'Cloud Top - IR',
+  C12: 'Ozone - IR',
+  C13: 'Clean Longwave Window - IR',
+  C14: 'Longwave Window - IR',
+  C15: 'Dirty Longwave Window - IR',
+  C16: 'CO2 Longwave - IR'
+};
+const SECTOR_CODE_MAP = exports.SECTOR_CODE_MAP = {
+  'GOES-EAST CONUS': 'C',
+  'GOES-EAST FULL DISK': 'F',
+  'GOES-EAST MESOSCALE 1': 'M1',
+  'GOES-EAST MESOSCALE 2': 'M2'
+};
+const LUMPED_MULTIBAND_SATELLITE_SECTORS = new Set(['GOES-EAST CONUS', 'GOES-EAST FULL DISK']);
+
+/** Uppercase RGB channel tokens as in production (CHANNEL_CATEGORIES.RGB). */
+const SATELLITE_RGB_PRODUCT_UPPER = new Set(['TRUE_COLOR', 'GEOCOLOR', 'NTMICRO', 'DAY_CLOUD_PHASE', 'DAY_LAND_CLOUD_FIRE', 'AIR_MASS', 'SANDWICH', 'SIMPLE_WATER_VAPOR', 'DUST', 'FIRE_TEMPERATURE']);
+
+/**
+ * Maximum timeline window length in hours for satellite, MRMS, and NEXRAD. Values are clamped to (0, this].
+ */
+const TIMELINE_DURATION_MAX_HOURS = exports.TIMELINE_DURATION_MAX_HOURS = 12;
+
+/**
+ * Preset hour buttons (UI). Any positive duration ≤ {@link TIMELINE_DURATION_MAX_HOURS} is valid via {@link formatTimelineDurationValue}.
+ */
+const TIMELINE_DURATION_HOUR_VALUES = exports.TIMELINE_DURATION_HOUR_VALUES = ['1', '4', '6', '12'];
+const LEGACY_SATELLITE_DURATION_ALIASES = {
+  '0.5': '1'
+};
+
+/** Tier keys used in SATELLITE_DURATION_CONFIG (frontend dictionaries). */
+const SATELLITE_DURATION_CONFIG = exports.SATELLITE_DURATION_CONFIG = {
+  CONUS: {
+    basic: [{
+      label: '1 Hr',
+      value: '1',
+      interval: 300
+    }, {
+      label: '4 Hr',
+      value: '4',
+      interval: 300
+    }, {
+      label: '6 Hr',
+      value: '6',
+      interval: 300
+    }, {
+      label: '12 Hr',
+      value: '12',
+      interval: 300
+    }]
+  },
+  FULL_DISK: {
+    basic: [{
+      label: '1 Hr',
+      value: '1',
+      interval: 600
+    }, {
+      label: '4 Hr',
+      value: '4',
+      interval: 600
+    }, {
+      label: '6 Hr',
+      value: '6',
+      interval: 600
+    }, {
+      label: '12 Hr',
+      value: '12',
+      interval: 600
+    }]
+  },
+  MESOSCALE: {
+    basic: [{
+      label: '1 Hr',
+      value: '1',
+      interval: 120
+    }, {
+      label: '4 Hr',
+      value: '4',
+      interval: 120
+    }, {
+      label: '6 Hr',
+      value: '6',
+      interval: 120
+    }, {
+      label: '12 Hr',
+      value: '12',
+      interval: 120
+    }]
+  }
+};
+
+/**
+ * Parses a user duration to hours, then clamps to a positive value not exceeding {@link TIMELINE_DURATION_MAX_HOURS}.
+ * @param {string|number} value
+ * @returns {number}
+ */
+function parseTimelineDurationHours(value) {
+  let s = value == null ? '1' : String(value).trim();
+  s = LEGACY_SATELLITE_DURATION_ALIASES[s] || s;
+  const n = Number(s);
+  if (!Number.isFinite(n) || n <= 0) return 1;
+  if (n > TIMELINE_DURATION_MAX_HOURS) return TIMELINE_DURATION_MAX_HOURS;
+  return n;
+}
+
+/**
+ * Canonical string for AguaceroCore state (stable for equality checks). Supports fractional hours (e.g. <code>'2.5'</code>).
+ * @param {string|number} value
+ * @returns {string}
+ */
+function formatTimelineDurationValue(value) {
+  const n = parseTimelineDurationHours(value);
+  if (Math.abs(n - Math.round(n)) < 1e-6) return String(Math.round(n));
+  return String(Math.round(n * 10000) / 10000);
+}
+
+/** @returns {string} Same as {@link formatTimelineDurationValue} (backward-compatible name). */
+function normalizeTimelineDurationValue(value) {
+  return formatTimelineDurationValue(value);
+}
+
+/**
+ * Picks a preset GOES duration option when one matches; otherwise builds a custom option using the same cadence as the 1&nbsp;hr preset for that sector/tier.
+ * @param {string} sectorName - e.g. <code>GOES-EAST CONUS</code>
+ * @param {string} [tier='basic']
+ * @param {string|number} durationValue
+ * @returns {{ label: string, value: string, interval: number }}
+ */
+function resolveSatelliteDurationOption(sectorName, tier, durationValue) {
+  var _SATELLITE_DURATION_C, _tierConfig$find;
+  let sectorType = 'CONUS';
+  if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+  const t = tier || 'basic';
+  const tierConfig = ((_SATELLITE_DURATION_C = SATELLITE_DURATION_CONFIG[sectorType]) === null || _SATELLITE_DURATION_C === void 0 ? void 0 : _SATELLITE_DURATION_C[t]) || SATELLITE_DURATION_CONFIG.CONUS.basic;
+  const key = formatTimelineDurationValue(durationValue);
+  const preset = tierConfig.find(o => String(o.value) === String(key));
+  if (preset) return preset;
+  const interval = ((_tierConfig$find = tierConfig.find(o => o.value === '1')) === null || _tierConfig$find === void 0 ? void 0 : _tierConfig$find.interval) || 300;
+  return {
+    label: `${key} Hr`,
+    value: key,
+    interval
+  };
+}
+function getDefaultSatelliteDurationOption(sectorName, tier = 'basic') {
+  var _SATELLITE_DURATION_C2;
+  let sectorType = 'CONUS';
+  if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+  const tierConfig = ((_SATELLITE_DURATION_C2 = SATELLITE_DURATION_CONFIG[sectorType]) === null || _SATELLITE_DURATION_C2 === void 0 ? void 0 : _SATELLITE_DURATION_C2[tier]) || SATELLITE_DURATION_CONFIG.CONUS.basic;
+  return tierConfig.find(o => o.value === '1') || tierConfig[0];
+}
+function calculateUnixTimeFromSatelliteKey(fileKey) {
+  try {
+    const match = fileKey.match(/_(\d{10})(?:\.ktx2)?$/);
+    if (match) return parseInt(match[1], 10);
+    const oldMatch = fileKey.match(/_s(\d{4})(\d{3})(\d{2})(\d{2})(\d{2})/);
+    if (oldMatch) {
+      const [, year, dayOfYear, hour, minute, second] = oldMatch.map(Number);
+      const date = new Date(Date.UTC(year, 0, 1));
+      date.setUTCDate(dayOfYear);
+      date.setUTCHours(hour, minute, second, 0);
+      return date.getTime() / 1000;
+    }
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * @param {{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }} selection
+ * @param {string[]} allFiles S3 keys from satellite listing API
+ * @param {{ value: string, interval: number }} durationOption
+ */
+function buildSatelliteTimelineForSelection(selection, allFiles, durationOption) {
+  const satelliteName = selection === null || selection === void 0 ? void 0 : selection.satelliteInstrumentId;
+  const categoryName = selection === null || selection === void 0 ? void 0 : selection.satelliteSectorLabel;
+  const channelName = selection === null || selection === void 0 ? void 0 : selection.satelliteChannel;
+  if (!satelliteName || !categoryName || !channelName) {
+    return {
+      unixTimes: [],
+      fileList: [],
+      timeToFileMap: {}
+    };
+  }
+  const SECTOR_CODE_MAP_LOCAL = {
+    'GOES-EAST CONUS': 'C',
+    'GOES-EAST FULL DISK': 'F',
+    'GOES-EAST MESOSCALE 1': 'M1',
+    'GOES-EAST MESOSCALE 2': 'M2'
+  };
+  const satelliteNum = satelliteName.replace('GOES', '').replace('-EAST', '').replace('-WEST', '');
+  const satId = `G${satelliteNum}`;
+  const sectorCode = SECTOR_CODE_MAP_LOCAL[categoryName] || 'C';
+  let sectorType = 'CONUS';
+  if (categoryName.includes('FULL DISK')) sectorType = 'FULL_DISK';else if (categoryName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+  const intervalSeconds = (durationOption === null || durationOption === void 0 ? void 0 : durationOption.interval) || 300;
+  const durationHours = durationOption !== null && durationOption !== void 0 && durationOption.value ? parseFloat(durationOption.value) : 1;
+  const filePrefix = `${sectorCode}_${satId}_`;
+  let searchProduct = channelName.toUpperCase();
+  if (!/^C\d{2}$/.test(searchProduct)) {
+    if (SATELLITE_RGB_PRODUCT_UPPER.has(searchProduct)) {
+      searchProduct = LUMPED_MULTIBAND_SATELLITE_SECTORS.has(categoryName) ? 'MULTI' : searchProduct;
+    } else {
+      searchProduct = 'MULTI';
+    }
+  }
+  const matchString = `${filePrefix}${searchProduct}`;
+  let relevantFiles = allFiles.filter(file => file.startsWith(matchString));
+  if (relevantFiles.length === 0) {
+    return {
+      unixTimes: [],
+      fileList: [],
+      timeToFileMap: {}
+    };
+  }
+  relevantFiles.sort((a, b) => {
+    const timeA = calculateUnixTimeFromSatelliteKey(a);
+    const timeB = calculateUnixTimeFromSatelliteKey(b);
+    return timeA - timeB;
+  });
+  let cutoffTime = 0;
+  if (durationHours > 0) {
+    const latestTime = calculateUnixTimeFromSatelliteKey(relevantFiles[relevantFiles.length - 1]);
+    cutoffTime = latestTime - durationHours * 3600;
+  }
+  let processedFiles = relevantFiles.filter(f => calculateUnixTimeFromSatelliteKey(f) >= cutoffTime);
+  if (intervalSeconds > 0 && processedFiles.length > 0) {
+    const intervalMinutes = intervalSeconds / 60;
+    if (sectorType === 'MESOSCALE') {
+      processedFiles = processedFiles.filter(file => {
+        if (intervalMinutes <= 1.1) return true;
+        const t = calculateUnixTimeFromSatelliteKey(file);
+        const date = new Date(t * 1000);
+        const minutes = date.getUTCMinutes();
+        return minutes % intervalMinutes === 0;
+      });
+    } else {
+      if (intervalSeconds >= 300) {
+        processedFiles = processedFiles.filter(file => {
+          if (Math.abs(intervalMinutes - 5) < 0.1) return true;
+          const t = calculateUnixTimeFromSatelliteKey(file);
+          const minutes = new Date(t * 1000).getUTCMinutes();
+          const remainder = minutes % intervalMinutes;
+          const distToInterval = Math.min(remainder, intervalMinutes - remainder);
+          return distToInterval < 2.5;
+        });
+      } else {
+        processedFiles = processedFiles.filter(file => {
+          const t = calculateUnixTimeFromSatelliteKey(file);
+          const minutes = new Date(t * 1000).getUTCMinutes();
+          return minutes % intervalMinutes === 0;
+        });
+      }
+    }
+    if (processedFiles.length === 0 && relevantFiles.length > 0) {
+      processedFiles = relevantFiles.slice(-1);
+    }
+  }
+  const unixTimes = [];
+  const timeToFileMap = {};
+  processedFiles.forEach(file => {
+    const unixTime = calculateUnixTimeFromSatelliteKey(file);
+    if (unixTime > 0) {
+      unixTimes.push(unixTime);
+      timeToFileMap[unixTime] = file;
+    }
+  });
+
+  // Chronological (oldest → newest): matches standard time sliders (earlier left, later right).
+  unixTimes.sort((a, b) => a - b);
+  return {
+    unixTimes,
+    fileList: processedFiles,
+    timeToFileMap
+  };
+}
+
+/**
+ * All GOES-East spacecraft / sector / channel combinations the SDK knows (same naming as production).
+ * @param {string} [satelliteInstrumentId='GOES19-EAST']
+ * @returns {Array<{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }>}
+ */
+function getAllGoesEastSatelliteSelections(satelliteInstrumentId = 'GOES19-EAST') {
+  const out = [];
+  for (const sector of GOES_EAST_SATELLITE_SECTORS) {
+    for (const ch of GOES_SATELLITE_CHANNELS) {
+      out.push({
+        satelliteInstrumentId,
+        satelliteSectorLabel: sector,
+        satelliteChannel: ch
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} satelliteChannel — band or RGB id (third segment of the archive descriptor)
+ */
+function resolveSatelliteS3FileName(satelliteChannel, timeToFileMap, satelliteTimestamp) {
+  const fileFromMap = timeToFileMap === null || timeToFileMap === void 0 ? void 0 : timeToFileMap[satelliteTimestamp];
+  if (fileFromMap) return fileFromMap;
+  const channelName = satelliteChannel;
+  const channelNameUpper = String(channelName).toUpperCase();
+  let name = fileFromMap || '';
+  if (!name && satelliteTimestamp != null) {
+    const suffix = `_${String(Math.floor(Number(satelliteTimestamp)))}`;
+    const multiName = Object.values(timeToFileMap || {}).find(f => f.includes('MULTI') && f.includes(suffix));
+    if (multiName) {
+      name = multiName.replace('MULTI', channelNameUpper);
+    }
+  }
+  return name;
+}