@aguacerowx/mapsgl 0.0.41 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/mapsgl",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -8,7 +8,8 @@
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "bundle-nexrad": "esbuild src/nexrad/radarDecode.worker.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/radarDecode.worker.bundled.js && esbuild src/nexrad/radarArchiveCore.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/radarArchiveCore.bundled.js --external:@aguacerowx/javascript-sdk && esbuild src/nexrad/MapboxRadarLayer.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/MapboxRadarLayer.bundled.js --external:mapbox-gl --external:@aguacerowx/javascript-sdk",
+    "prepublishOnly": "npm run bundle-nexrad",
+    "bundle-nexrad": "esbuild src/nexrad/radarDecode.worker.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/radarDecode.worker.bundled.js && esbuild src/nexrad/radarArchiveCore.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/radarArchiveCore.bundled.js --external:@aguacerowx/javascript-sdk && esbuild src/nexrad/MapboxRadarLayer.ts --bundle --format=esm --platform=browser --outfile=src/nexrad/MapboxRadarLayer.bundled.js --external:mapbox-gl --external:@aguacerowx/javascript-sdk && esbuild src/nexrad/nexradCrossSectionSampleAtLatLon.ts --format=esm --platform=browser --outfile=src/nexrad/nexradCrossSectionSampleAtLatLon.bundled.js && esbuild src/nexrad/radarFrameGpuMatch.ts --format=esm --platform=browser --outfile=src/nexrad/radarFrameGpuMatch.bundled.js",
     "gen:nws-key": "esbuild ../../../aguacero-frontend/src/components/WarningsMenu/nwsWarningCustomizationKey.ts --bundle --format=esm --platform=neutral --outfile=src/nwsWarningCustomizationKey.gen.js"
   },
   "files": [

package/src/NexradWeatherController.js

@@ -6,8 +6,8 @@ import { getUnitConversionFunction, getDefaultRadarTilt } from '@aguacerowx/java
 import { fetchAndParseArchive, objectKeyToUrl, setNexradArchiveApiKey } from './nexrad/radarArchiveCore.bundled.js';
 import { MapboxRadarLayer } from './nexrad/MapboxRadarLayer.bundled.js';
 import { nexradBinGroupIdForKey, variableToNexradGroup } from '@aguacerowx/javascript-sdk';
-import { sampleNexradFrameAtLatLon } from './nexrad/nexradCrossSectionSampleAtLatLon.ts';
-import { prepareRadarFrameForGpuReadout } from './nexrad/radarFrameGpuMatch.ts';
+import { sampleNexradFrameAtLatLon } from './nexrad/nexradCrossSectionSampleAtLatLon.bundled.js';
+import { prepareRadarFrameForGpuReadout } from './nexrad/radarFrameGpuMatch.bundled.js';
 import { mapboxFrameUploadOptionsForNexradState } from './nexrad/nexradMapboxFrameOpts.js';
 
 function pickNearestLevel3ObjectKey(unixTime, timeToKeyMap, maxDeltaSec = 600) {

package/src/WeatherLayerManager.js

@@ -8,6 +8,48 @@ import { NexradSitesOverlay } from './NexradSitesOverlay.js';
 import { NwsWatchesWarningsOverlay } from './NwsWatchesWarningsOverlay.js';
 import WorkerPool from './WorkerPool.js';
 
+const DEBUG_NS = '[WeatherLayerManager:debug]';
+
+/**
+ * Redact secrets for console output.
+ * @param {object} options
+ */
+function _debugSanitizeOptions(options) {
+    if (!options || typeof options !== 'object') return options;
+    const o = { ...options };
+    if (typeof o.apiKey === 'string' && o.apiKey.length > 0) {
+        o.apiKey = `${o.apiKey.slice(0, 4)}…(${o.apiKey.length} chars)`;
+    }
+    return o;
+}
+
+/**
+ * Compact summary of timestamp / hour arrays (MRMS timeline debugging).
+ * @param {unknown[]} arr
+ */
+function _debugSummarizeNumericSeries(arr) {
+    if (!Array.isArray(arr) || arr.length === 0) {
+        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
+    }
+    const nums = arr.map((x) => Number(x)).filter((n) => !Number.isNaN(n));
+    if (nums.length === 0) {
+        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
+    }
+    const sorted = [...nums].sort((a, b) => a - b);
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const head = sorted.slice(0, Math.min(8, sorted.length));
+    const tail = sorted.length > 16 ? sorted.slice(-8) : [];
+    return {
+        length: sorted.length,
+        min,
+        max,
+        spanSec: max != null && min != null ? max - min : null,
+        head,
+        tail: tail.length ? tail : undefined,
+    };
+}
+
 function findLatestModelRun(modelsData, modelName) {
     const model = modelsData?.[modelName];
     if (!model) return null;
@@ -33,12 +75,17 @@ function findLatestModelRun(modelsData, modelName) {
  * @param {string} [options.belowID] - Style layer id to insert Aguacero weather layers **below** (default `AML_-_terrain` when present). Alias of `weatherBeforeLayerId`.
  * @param {string} [options.weatherBeforeLayerId] - Same as `belowID`.
  * @param {string} [options.nexradLayerId] - Override Mapbox id for the NEXRAD custom layer (default: derived from `layerId`).
+ * @param {boolean} [options.debug] - When `true`, logs detailed diagnostics to the console (prefix `[WeatherLayerManager:debug]`). Off by default.
  */
 export class WeatherLayerManager extends EventEmitter {
     constructor(map, options = {}) {
         super();
         if (!map) throw new Error('A Mapbox GL map instance is required.');
         this.map = map;
+        /** @private When true, emit verbose `[WeatherLayerManager:debug]` logs. */
+        this._debug = options.debug === true;
+        /** @private Monotonic counter for correlating state:change logs. */
+        this._debugStateSeq = 0;
         this.layerId =
             options.layerId ||
             options.id ||
@@ -109,6 +156,29 @@ export class WeatherLayerManager extends EventEmitter {
         // 1. CREATE an instance of the core engine
         this.core = new AguaceroCore(options);
 
+        if (this._debug) {
+            const layerOpts = options.layerOptions || {};
+            console.log(DEBUG_NS, 'constructor', {
+                layerId: this.layerId,
+                nexradLayerId: this._nexradLayerId,
+                mapLoaded: typeof this.map?.loaded === 'function' ? this.map.loaded() : undefined,
+                styleLoaded: this.map?.isStyleLoaded?.() ?? undefined,
+                weatherBeforeLayerId: this._weatherBeforeLayerId,
+                options: _debugSanitizeOptions(options),
+                layerOptions: layerOpts,
+                coreStateSnapshot: {
+                    isMRMS: this.core.state?.isMRMS,
+                    isSatellite: this.core.state?.isSatellite,
+                    isNexrad: this.core.state?.isNexrad,
+                    model: this.core.state?.model,
+                    variable: this.core.state?.variable,
+                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
+                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                    satelliteDurationValue: this.core.state?.satelliteDurationValue,
+                },
+            });
+        }
+
         // 2. LISTEN for events from the core engine
         this.core.on('state:change', (newState) => {
             this._lastEmittedState = newState;
@@ -128,6 +198,20 @@ export class WeatherLayerManager extends EventEmitter {
         this.map.on('mousemove', this._handleMouseMove);
     }
 
+    /**
+     * Structured debug log (no-op unless `options.debug === true` on construction).
+     * @param {string} scope
+     * @param {object} [data]
+     */
+    _debugLog(scope, data) {
+        if (!this._debug) return;
+        if (data !== undefined) {
+            console.log(DEBUG_NS, scope, data);
+        } else {
+            console.log(DEBUG_NS, scope);
+        }
+    }
+
     /**
      * Resolves which style layer id to pass as Mapbox `addLayer(..., beforeId)` for satellite / grid / NEXRAD.
      * Prefers an explicit id (custom styles), then the default Aguacero `AML_-_terrain` anchor when present.
@@ -174,9 +258,39 @@ export class WeatherLayerManager extends EventEmitter {
      * @private
      */
     _handleStateChange(state) {
+        const seq = this._debug ? ++this._debugStateSeq : 0;
         /** NEXRAD setup is async (`sites.show`, frame fetch). `finally` would run before the radar layer exists, so NWS fill stacks above terrain instead of under the custom layer — defer sync until the handler settles. */
         let deferNwsSyncUntilNexradReady = false;
         try {
+            if (this._debug) {
+                const tsSummary = state.isMRMS
+                    ? _debugSummarizeNumericSeries(state.availableTimestamps || [])
+                    : null;
+                this._debugLog('state:change', {
+                    seq,
+                    mode: state.isSatellite
+                        ? 'satellite'
+                        : state.isNexrad
+                          ? 'nexrad'
+                          : state.isMRMS
+                            ? 'mrms'
+                            : 'model',
+                    model: state.model,
+                    variable: state.variable,
+                    runKey: `${state.model}-${state.date}-${state.run}-${state.variable}`,
+                    timeKey: state.isMRMS
+                        ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+                        : Number(state.forecastHour),
+                    mrmsDurationValue: state.mrmsDurationValue,
+                    availableTimestampsSummary: tsSummary,
+                    availableHoursLen: Array.isArray(state.availableHours) ? state.availableHours.length : 0,
+                    shaderLayerRunKey: this.shaderLayer?.runKey ?? null,
+                    currentLoadedTimeKey: this.currentLoadedTimeKey,
+                    rebuildId: this.currentRebuildId,
+                    initialGridLoadPending: this._initialGridLoadPending,
+                });
+            }
+
             if (state.isSatellite) {
                 this._handleSatelliteStateChange(state);
                 return;
@@ -206,6 +320,21 @@ export class WeatherLayerManager extends EventEmitter {
                 : Number(state.forecastHour);
             const runKey = `${state.model}-${state.date}-${state.run}-${state.variable}`;
 
+            if (this._debug && state.isMRMS) {
+                this._debugLog('grid path (mrms/model)', {
+                    seq,
+                    prevMrmsDurationValue: prevMrmsDur,
+                    mrmsDurationChanged,
+                    willRebuild: !this.shaderLayer || this.shaderLayer.runKey !== runKey,
+                    willUpdateData:
+                        this.shaderLayer &&
+                        this.shaderLayer.runKey === runKey &&
+                        this.currentLoadedTimeKey !== timeKey,
+                    shaderRunKey: this.shaderLayer?.runKey,
+                    targetRunKey: runKey,
+                });
+            }
+
             if (!this.shaderLayer || this.shaderLayer.runKey !== runKey) {
                 this._rebuildLayerAndPreload(state);
             } else if (this.currentLoadedTimeKey !== timeKey) {
@@ -215,6 +344,12 @@ export class WeatherLayerManager extends EventEmitter {
                     timeKey === this._rebuildTargetTimeKey;
                 if (!duplicateBeforeFirstPaint) {
                     this._updateLayerData(state);
+                } else if (this._debug) {
+                    this._debugLog('skip _updateLayerData (duplicate before first paint)', {
+                        seq,
+                        timeKey,
+                        _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
+                    });
                 }
             }
 
@@ -225,6 +360,13 @@ export class WeatherLayerManager extends EventEmitter {
             }
 
             if (state.isMRMS && this.shaderLayer && mrmsDurationChanged) {
+                if (this._debug) {
+                    this._debugLog('_preloadAllTimeSteps (mrms duration changed)', {
+                        seq,
+                        from: prevMrmsDur,
+                        to: state.mrmsDurationValue,
+                    });
+                }
                 this._preloadAllTimeSteps(state);
             }
         } finally {
@@ -638,10 +780,68 @@ export class WeatherLayerManager extends EventEmitter {
     // to the core engine. This keeps the API consistent for your users.
 
     async initialize(options) {
+        const t0 =
+            typeof performance !== 'undefined' && typeof performance.now === 'function'
+                ? performance.now()
+                : Date.now();
+        this._debugLog('initialize:start', {
+            autoRefreshEnabled: this.autoRefreshEnabled,
+            autoRefreshIntervalSeconds: this.autoRefreshIntervalSeconds,
+            passedOptions: options && typeof options === 'object' ? { ...options } : options,
+            coreStateBefore: {
+                isMRMS: this.core.state?.isMRMS,
+                variable: this.core.state?.variable,
+                mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                mrmsDurationValue: this.core.state?.mrmsDurationValue,
+            },
+            mrmsStatusVariableLen: this.core.state?.variable
+                ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 'n/a')
+                : 'n/a',
+        });
         if (this.autoRefreshEnabled) {
             this.setAutoRefresh(true, this.autoRefreshIntervalSeconds);
         }
-        return this.core.initialize({ ...options, autoRefresh: false }); // <-- add spread + autoRefresh: false
+        try {
+            const result = await this.core.initialize({ ...options, autoRefresh: false });
+            const t1 =
+                typeof performance !== 'undefined' && typeof performance.now === 'function'
+                    ? performance.now()
+                    : Date.now();
+            this._debugLog('initialize:done', {
+                elapsedMs: Math.round(t1 - t0),
+                coreStateAfter: {
+                    isMRMS: this.core.state?.isMRMS,
+                    variable: this.core.state?.variable,
+                    model: this.core.state?.model,
+                    date: this.core.state?.date,
+                    run: this.core.state?.run,
+                    forecastHour: this.core.state?.forecastHour,
+                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
+                },
+                availableTimestampsSummary: _debugSummarizeNumericSeries(
+                    this._lastEmittedState?.availableTimestamps || [],
+                ),
+                availableHoursLen: Array.isArray(this._lastEmittedState?.availableHours)
+                    ? this._lastEmittedState.availableHours.length
+                    : 0,
+                modelStatusLoaded: this.core.modelStatus != null,
+                mrmsStatusKeys:
+                    this.core.mrmsStatus && typeof this.core.mrmsStatus === 'object'
+                        ? Object.keys(this.core.mrmsStatus).length
+                        : 0,
+                mrmsStatusVariableLen: this.core.state?.variable
+                    ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 0)
+                    : 0,
+            });
+            return result;
+        } catch (err) {
+            this._debugLog('initialize:error', {
+                message: err?.message || String(err),
+                stack: err?.stack,
+            });
+            throw err;
+        }
     }
     async setState(newState) { return this.core.setState(newState); }
     play() { this.core.play(); }
@@ -722,7 +922,211 @@ export class WeatherLayerManager extends EventEmitter {
         // the active time.
     }
 
-    async _rebuildLayerAndPreload(state) {
+    /**
+     * MRMS timestamps or model forecast hours for the active timeline (ordering preserved from source lists).
+     * @returns {number[]}
+     */
+    _collectNormalizedTimelineSteps(state) {
+        let fromCore = [];
+        try {
+            if (!state.isMRMS && typeof this.core.getAvailableForecastHours === 'function') {
+                fromCore = this.core.getAvailableForecastHours();
+            }
+        } catch (err) {
+            // ignore
+        }
+
+        const fromState = state.isMRMS
+            ? (state.availableTimestamps || [])
+            : (state.availableHours || []);
+
+        let timeSteps;
+        let mrmsTimelineSource = '';
+        if (state.isMRMS) {
+            if (fromState.length) {
+                timeSteps = fromState;
+                mrmsTimelineSource = 'state.availableTimestamps';
+            } else if (
+                state.variable &&
+                typeof this.core._getFilteredMrmsTimestampsForVariable === 'function'
+            ) {
+                /**
+                 * Same list {@link AguaceroCore} puts on `state:change` as `availableTimestamps`.
+                 * When that array is missing or empty on this snapshot (ordering / first paint),
+                 * derive from core so rebuild preload is not stuck with only `currentFrameTime`.
+                 */
+                try {
+                    timeSteps = this.core._getFilteredMrmsTimestampsForVariable(state.variable);
+                    mrmsTimelineSource = 'core._getFilteredMrmsTimestampsForVariable';
+                } catch {
+                    timeSteps = fromCore;
+                    mrmsTimelineSource = 'core forecast hours fallback (error)';
+                }
+            } else {
+                timeSteps = fromCore;
+                mrmsTimelineSource = 'empty';
+            }
+        } else {
+            timeSteps = fromCore.length > 0 ? fromCore : fromState;
+        }
+
+        const out = (timeSteps || [])
+            .map(t => Number(t))
+            .filter(t => !Number.isNaN(t));
+        if (this._debug && state.isMRMS) {
+            this._debugLog('_collectNormalizedTimelineSteps', {
+                variable: state.variable,
+                mrmsDurationValue: state.mrmsDurationValue,
+                fromStateLen: fromState.length,
+                fromCoreLen: fromCore.length,
+                chosenSource: mrmsTimelineSource || (state.isMRMS ? 'n/a' : 'model'),
+                normalizedLen: out.length,
+                summary: _debugSummarizeNumericSeries(out),
+            });
+        }
+        return out;
+    }
+
+    /**
+     * @param {object} state
+     * @param {number[]} times
+     * @param {{ rebuildId: number, mode: 'rebuild' | 'append' }} options
+     */
+    _runParallelGridFrameLoads(state, times, options) {
+        const { rebuildId, mode } = options;
+        if (!times.length || !this.shaderLayer) {
+            if (mode === 'rebuild') {
+                this._initialGridLoadPending = false;
+            }
+            this._debugLog('_runParallelGridFrameLoads:skip', {
+                reason: !times.length ? 'no times' : 'no shaderLayer',
+                mode,
+                rebuildId,
+                timesLen: times.length,
+            });
+            return;
+        }
+
+        const currentFrameTime = Number(state.isMRMS ? state.mrmsTimestamp : state.forecastHour);
+        /** When the active timestep is unset/NaN, paint the first timeline step (legacy single-fetch behavior). */
+        let primaryTimeForRebuild = Number.NaN;
+        if (mode === 'rebuild') {
+            primaryTimeForRebuild = Number.isFinite(currentFrameTime)
+                ? currentFrameTime
+                : times[0];
+        }
+        const tsKey = state.isMRMS ? 'mrmsTimestamp' : 'forecastHour';
+        const gridModel = state.isMRMS ? 'mrms' : state.model;
+        const { gridDef } = this.core._getGridCornersAndDef(gridModel);
+
+        this._debugLog('_runParallelGridFrameLoads', {
+            mode,
+            rebuildId,
+            gridModel,
+            timesLen: times.length,
+            timesSummary: _debugSummarizeNumericSeries(times),
+            currentFrameTime,
+            primaryTimeForRebuild:
+                mode === 'rebuild'
+                    ? Number.isFinite(currentFrameTime)
+                        ? currentFrameTime
+                        : times[0]
+                    : undefined,
+            tsKey,
+            gridNxNy: gridDef?.grid_params
+                ? { nx: gridDef.grid_params.nx, ny: gridDef.grid_params.ny }
+                : null,
+        });
+
+        times.forEach((time) => {
+            const stateForTime = { ...state, [tsKey]: time };
+            this.core._loadGridData(stateForTime)
+                .then((grid) => {
+                    if (rebuildId !== this.currentRebuildId || !this.shaderLayer) {
+                        return;
+                    }
+
+                    const isPrimaryFrame =
+                        mode === 'rebuild' &&
+                        Number.isFinite(primaryTimeForRebuild) &&
+                        time === primaryTimeForRebuild;
+
+                    if (isPrimaryFrame) {
+                        const coreTimeKey = state.isMRMS
+                            ? (this.core.state.mrmsTimestamp == null
+                                ? null
+                                : Number(this.core.state.mrmsTimestamp))
+                            : Number(this.core.state.forecastHour);
+                        if (coreTimeKey !== this._rebuildTargetTimeKey) {
+                            this._debugLog('_loadGridData:skip primary (core time drifted vs rebuild target)', {
+                                time,
+                                coreTimeKey,
+                                _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
+                                rebuildId,
+                            });
+                            return;
+                        }
+                        if (!grid?.data) {
+                            this._debugLog('_loadGridData:primary frame missing grid.data', {
+                                time,
+                                rebuildId,
+                                mode,
+                            });
+                            this._initialGridLoadPending = false;
+                            return;
+                        }
+                        this.shaderLayer.updateDataTexture(
+                            grid.data,
+                            grid.encoding,
+                            gridDef.grid_params.nx,
+                            gridDef.grid_params.ny,
+                        );
+                        this.currentLoadedTimeKey = time;
+                        this.shaderLayer.registerCurrentDataTextureAsPreloaded(time);
+                        this._initialGridLoadPending = false;
+                        this.map.triggerRepaint();
+                        return;
+                    }
+
+                    if (grid?.data) {
+                        this.shaderLayer.storePreloadedTexture(
+                            time,
+                            grid.data,
+                            grid.encoding,
+                            gridDef.grid_params.nx,
+                            gridDef.grid_params.ny,
+                        );
+                        const s = this.core.state;
+                        const activeTime = s.isMRMS
+                            ? (s.mrmsTimestamp == null ? null : Number(s.mrmsTimestamp))
+                            : Number(s.forecastHour);
+                        if (time === activeTime && this.shaderLayer.switchToPreloadedTexture(time)) {
+                            this.currentLoadedTimeKey = time;
+                            this.map.triggerRepaint();
+                        }
+                    } else if (this._debug && mode === 'append') {
+                        this._debugLog('_loadGridData:empty grid (append)', { time, mode, rebuildId });
+                    }
+                })
+                .catch((err) => {
+                    this._debugLog('_loadGridData:error', {
+                        time,
+                        mode,
+                        rebuildId,
+                        message: err?.message || String(err),
+                    });
+                    if (
+                        mode === 'rebuild' &&
+                        Number.isFinite(primaryTimeForRebuild) &&
+                        time === primaryTimeForRebuild
+                    ) {
+                        this._initialGridLoadPending = false;
+                    }
+                });
+        });
+    }
+
+    _rebuildLayerAndPreload(state) {
         if (state.isSatellite) {
             return;
         }
@@ -775,119 +1179,69 @@ export class WeatherLayerManager extends EventEmitter {
             : Number(state.forecastHour);
         this._initialGridLoadPending = true;
 
-        let grid;
-        try {
-            grid = await this.core._loadGridData(state);
-        } catch (e) {
-            this._initialGridLoadPending = false;
-            throw e;
-        }
-
-        if (rebuildId !== this.currentRebuildId) {
-            this._initialGridLoadPending = false;
-            return;
-        }
-
-        const coreTimeKey = state.isMRMS
-            ? (this.core.state.mrmsTimestamp == null ? null : Number(this.core.state.mrmsTimestamp))
-            : Number(this.core.state.forecastHour);
-        if (coreTimeKey !== this._rebuildTargetTimeKey) {
+        const normalized = this._collectNormalizedTimelineSteps(state);
+        const currentFrameTime = Number(state.isMRMS ? state.mrmsTimestamp : state.forecastHour);
+        const timesSet = new Set(normalized);
+        if (!Number.isNaN(currentFrameTime)) {
+            timesSet.add(currentFrameTime);
+        }
+        let timesToLoad = [...timesSet];
+        if (timesToLoad.length === 0 && !Number.isNaN(currentFrameTime)) {
+            timesToLoad = [currentFrameTime];
+        }
+        this._debugLog('_rebuildLayerAndPreload:timeline', {
+            rebuildId,
+            isMRMS: state.isMRMS,
+            variable: state.variable,
+            normalizedLen: normalized.length,
+            normalizedSummary: _debugSummarizeNumericSeries(normalized),
+            currentFrameTime,
+            timesToLoadLen: timesToLoad.length,
+            timesToLoadSummary: _debugSummarizeNumericSeries(timesToLoad),
+            insertBeforeId: beforeId ?? '(stack top)',
+        });
+        if (timesToLoad.length === 0) {
             this._initialGridLoadPending = false;
+            this._debugLog('_rebuildLayerAndPreload:no times to load — check availableTimestamps / duration window', {
+                rebuildId,
+                availableTimestampsLen: Array.isArray(state.availableTimestamps)
+                    ? state.availableTimestamps.length
+                    : 0,
+                mrmsDurationValue: state.mrmsDurationValue,
+            });
             return;
         }
 
-        if (grid && grid.data) {
-            const gridModel = state.isMRMS ? 'mrms' : state.model;
-            const { gridDef } = this.core._getGridCornersAndDef(gridModel);
-
-            this.shaderLayer.updateDataTexture(
-                grid.data, grid.encoding,
-                gridDef.grid_params.nx, gridDef.grid_params.ny
-            );
-
-            this.currentLoadedTimeKey = state.isMRMS
-                ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
-                : Number(state.forecastHour);
-            this.shaderLayer.registerCurrentDataTextureAsPreloaded(this.currentLoadedTimeKey);
-            this.map.triggerRepaint();
-        }
-
-        this._initialGridLoadPending = false;
-
         if (rebuildId === this.currentRebuildId) {
-            this._preloadAllTimeSteps(state);
+            this._runParallelGridFrameLoads(state, timesToLoad, { rebuildId, mode: 'rebuild' });
         }
     }
-    
-    _preloadAllTimeSteps(state) {
-        let fromCore = [];
-        try {
-            if (!state.isMRMS && typeof this.core.getAvailableForecastHours === 'function') {
-                fromCore = this.core.getAvailableForecastHours();
-            }
-        } catch (err) {
-            // ignore
-        }
-
-        const fromState = state.isMRMS
-            ? (state.availableTimestamps || [])
-            : (state.availableHours || []);
-
-        let timeSteps;
-        if (state.isMRMS) {
-            timeSteps = fromState.length ? fromState : fromCore;
-        } else {
-            timeSteps = fromCore.length > 0 ? fromCore : fromState;
-        }
-
-        const normalized = (timeSteps || [])
-            .map(t => Number(t))
-            .filter(t => !Number.isNaN(t));
 
+    _preloadAllTimeSteps(state) {
+        const normalized = this._collectNormalizedTimelineSteps(state);
         const currentFrameTime = Number(state.isMRMS ? state.mrmsTimestamp : state.forecastHour);
         const stepsToPreload = normalized.filter(t => t !== currentFrameTime);
 
+        this._debugLog('_preloadAllTimeSteps', {
+            normalizedLen: normalized.length,
+            currentFrameTime,
+            stepsToPreloadLen: stepsToPreload.length,
+            stepsSummary: _debugSummarizeNumericSeries(stepsToPreload),
+        });
+
         if (normalized.length === 0) {
             return;
         }
 
         if (stepsToPreload.length === 0) {
+            this._debugLog('_preloadAllTimeSteps:skip (nothing to preload besides current)', {
+                currentFrameTime,
+            });
             return;
         }
 
         const capturedRebuildId = this.currentRebuildId;
-
-        const gridModel = state.isMRMS ? 'mrms' : state.model;
-        const { gridDef } = this.core._getGridCornersAndDef(gridModel);
-
-        stepsToPreload.forEach(time => {
-            const stateForTime = {
-                ...state,
-                [state.isMRMS ? 'mrmsTimestamp' : 'forecastHour']: time
-            };
-
-            this.core._loadGridData(stateForTime)
-                .then(grid => {
-                    if (capturedRebuildId !== this.currentRebuildId) {
-                        return;
-                    }
-                    if (grid?.data && this.shaderLayer) {
-                        this.shaderLayer.storePreloadedTexture(
-                            time, grid.data, grid.encoding,
-                            gridDef.grid_params.nx, gridDef.grid_params.ny
-                        );
-                        const s = this.core.state;
-                        const activeTime = s.isMRMS
-                            ? (s.mrmsTimestamp == null ? null : Number(s.mrmsTimestamp))
-                            : Number(s.forecastHour);
-                        if (time === activeTime && this.shaderLayer.switchToPreloadedTexture(time)) {
-                            this.currentLoadedTimeKey = time;
-                            this.map.triggerRepaint();
-                        }
-                    }
-                })
-                .catch(() => {});
-        });
+        this._runParallelGridFrameLoads(state, stepsToPreload, { rebuildId: capturedRebuildId, mode: 'append' });
     }
 
     _updateLayerData(state) {
@@ -1124,6 +1478,7 @@ export class WeatherLayerManager extends EventEmitter {
      * Cleans up all resources.
      */
     destroy() {
+        this._debugLog('destroy');
         this.setAutoRefresh(false);
         
         // 1. Unbind the map's mousemove event listener

package/src/nexrad/nexradCrossSectionSampleAtLatLon.bundled.js

@@ -0,0 +1,91 @@
+function wrapAzimuthDeltaDeg(azDeg, azimuthBaseDeg) {
+  let da = azDeg - azimuthBaseDeg;
+  da -= Math.floor(da / 360) * 360;
+  if (da < 0) da += 360;
+  return da;
+}
+function snapGateCoord(t, nCells) {
+  if (nCells <= 1) return 0;
+  const idx = Math.floor(t * (nCells - 1) + 0.5);
+  return idx / (nCells - 1);
+}
+function readGateRawSigned(frame, rayIdx, gateIdx) {
+  if (rayIdx < 0 || gateIdx < 0 || rayIdx >= frame.nRays || gateIdx >= frame.nGates) return null;
+  const byteOffset = (rayIdx * frame.nGates + gateIdx) * 2;
+  const hi = frame.gateData[byteOffset];
+  const lo = frame.gateData[byteOffset + 1];
+  const raw = lo + hi * 256;
+  const rawSigned = raw >= 32768 ? raw - 65536 : raw;
+  if (rawSigned <= -32768) return null;
+  return rawSigned;
+}
+function sampleGateRawBilinearDecoded(frame, gateX, gateY) {
+  const w = frame.nGates;
+  const h = frame.nRays;
+  if (w < 1 || h < 1) return null;
+  const gx = Math.min(1, Math.max(0, gateX));
+  const gy = Math.min(1, Math.max(0, gateY));
+  const sx = gx * Math.max(w - 1, 1);
+  const sy = gy * Math.max(h - 1, 1);
+  const i0 = Math.floor(sx);
+  const j0 = Math.floor(sy);
+  const i1 = Math.min(i0 + 1, w - 1);
+  const j1 = Math.min(j0 + 1, h - 1);
+  const fx = sx - i0;
+  const fy = sy - j0;
+  const w00 = (1 - fx) * (1 - fy);
+  const w10 = fx * (1 - fy);
+  const w01 = (1 - fx) * fy;
+  const w11 = fx * fy;
+  let acc = 0;
+  let wsum = 0;
+  const add = (r, wt) => {
+    if (r !== null) {
+      acc += r * wt;
+      wsum += wt;
+    }
+  };
+  add(readGateRawSigned(frame, j0, i0), w00);
+  add(readGateRawSigned(frame, j0, i1), w10);
+  add(readGateRawSigned(frame, j1, i0), w01);
+  add(readGateRawSigned(frame, j1, i1), w11);
+  if (wsum < 1e-6) return null;
+  return acc / wsum;
+}
+function sampleNexradFrameAtLatLon(frame, lat, lon, options) {
+  const DEG_TO_RAD = Math.PI / 180;
+  const EARTH_RADIUS_M = 6378137;
+  const dLatDeg = lat - frame.stationLat;
+  const dLonDeg = lon - frame.stationLon;
+  const cosLat = Math.max(Math.cos(lat * DEG_TO_RAD), 1e-6);
+  const xM = dLonDeg * DEG_TO_RAD * EARTH_RADIUS_M * cosLat;
+  const yM = dLatDeg * DEG_TO_RAD * EARTH_RADIUS_M;
+  const rangeM = Math.hypot(xM, yM);
+  const rangeKm = rangeM / 1e3;
+  if (rangeKm < frame.firstGateKm) return null;
+  const spanKm = frame.nGates * frame.gateWidthKm;
+  if (!(spanKm > 0)) return null;
+  const maxRangeKm = frame.firstGateKm + spanKm;
+  if (rangeKm >= maxRangeKm) return null;
+  let azDeg = Math.atan2(xM, yM) * (180 / Math.PI);
+  if (azDeg < 0) azDeg += 360;
+  const boundaries = frame.rayBoundariesDeg;
+  const azimuthBaseDeg = boundaries.length > 0 ? Number(boundaries[0]) : 0;
+  const da = wrapAzimuthDeltaDeg(azDeg, azimuthBaseDeg);
+  let gateY = da / 360;
+  gateY = Math.min(1, Math.max(0, gateY));
+  let gateX = (rangeKm - frame.firstGateKm) / spanKm;
+  gateX = Math.min(1, Math.max(0, gateX));
+  const smoothPolar = options?.smoothPolar === true;
+  if (!smoothPolar) {
+    gateX = snapGateCoord(gateX, frame.nGates);
+    gateY = snapGateCoord(gateY, frame.nRays);
+  }
+  const rawSigned = sampleGateRawBilinearDecoded(frame, gateX, gateY);
+  if (rawSigned === null) return null;
+  const physical = rawSigned * frame.valueScale + frame.valueOffset;
+  return { value: physical, groundRangeKm: rangeKm };
+}
+export {
+  sampleNexradFrameAtLatLon
+};

package/src/nexrad/radarFrameGpuMatch.bundled.js

@@ -0,0 +1,79 @@
+function angularDistanceDeg(a, b) {
+  let d = Math.abs(a - b) % 360;
+  if (d > 180) d = 360 - d;
+  return d;
+}
+function canonicalBinsRadarFrame(frame) {
+  const nRays = frame.nRays;
+  const nGates = frame.nGates;
+  if (nRays <= 0 || nGates <= 0) return frame;
+  if (frame.rayBoundariesDeg.length < nRays + 1) return frame;
+  const degPerBin = 360 / nRays;
+  const bytesPerRay = nGates * 2;
+  const centers = new Float32Array(nRays);
+  for (let r = 0; r < nRays; r++) {
+    const lower = frame.rayBoundariesDeg[r];
+    const upper = frame.rayBoundariesDeg[r + 1];
+    const center = (lower + upper) * 0.5;
+    centers[r] = (center % 360 + 360) % 360;
+  }
+  const canonicalGateData = new Uint8Array(nRays * bytesPerRay);
+  for (let i = 0; i < canonicalGateData.length; i += 2) {
+    canonicalGateData[i] = 128;
+  }
+  const used = new Array(nRays).fill(false);
+  for (let bin = 0; bin < nRays; bin++) {
+    const targetDeg = ((bin + 0.5) * degPerBin % 360 + 360) % 360;
+    let bestR = -1;
+    let bestDist = Infinity;
+    for (let r = 0; r < nRays; r++) {
+      if (used[r]) continue;
+      const dist = angularDistanceDeg(centers[r], targetDeg);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestR = r;
+      }
+    }
+    if (bestR >= 0) {
+      used[bestR] = true;
+      canonicalGateData.set(
+        frame.gateData.subarray(bestR * bytesPerRay, (bestR + 1) * bytesPerRay),
+        bin * bytesPerRay
+      );
+    }
+  }
+  const canonicalBoundaries = new Float32Array(nRays + 1);
+  for (let i = 0; i <= nRays; i++) {
+    canonicalBoundaries[i] = i * degPerBin;
+  }
+  return { ...frame, gateData: canonicalGateData, rayBoundariesDeg: canonicalBoundaries };
+}
+function sortRadarFrameByAzimuth(frame) {
+  const nRays = frame.nRays;
+  const nGates = frame.nGates;
+  const bytesPerRay = nGates * 2;
+  const rayOrder = Array.from({ length: nRays }, (_, i) => i).sort(
+    (a, b) => frame.rayBoundariesDeg[a] - frame.rayBoundariesDeg[b]
+  );
+  const sortedGateData = new Uint8Array(nRays * bytesPerRay);
+  const sortedBoundaries = new Float32Array(nRays + 1);
+  for (let newIdx = 0; newIdx < nRays; newIdx++) {
+    const oldIdx = rayOrder[newIdx];
+    sortedGateData.set(
+      frame.gateData.subarray(oldIdx * bytesPerRay, (oldIdx + 1) * bytesPerRay),
+      newIdx * bytesPerRay
+    );
+    sortedBoundaries[newIdx] = frame.rayBoundariesDeg[oldIdx];
+  }
+  sortedBoundaries[nRays] = frame.rayBoundariesDeg[rayOrder[nRays - 1]] + (frame.rayBoundariesDeg[rayOrder[1]] - frame.rayBoundariesDeg[rayOrder[0]]);
+  return { ...frame, gateData: sortedGateData, rayBoundariesDeg: sortedBoundaries };
+}
+function prepareRadarFrameForGpuReadout(frame, options) {
+  const hasLayoutKey = options?.geometryLayoutKey != null && options.geometryLayoutKey !== "";
+  return hasLayoutKey ? canonicalBinsRadarFrame(frame) : sortRadarFrameByAzimuth(frame);
+}
+export {
+  canonicalBinsRadarFrame,
+  prepareRadarFrameForGpuReadout,
+  sortRadarFrameByAzimuth
+};