@aguacerowx/mapsgl 0.0.42 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/mapsgl",
-  "version": "0.0.42",
+  "version": "0.0.43",
   "private": false,
   "publishConfig": {
     "access": "public"

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(); }
@@ -741,15 +941,50 @@ export class WeatherLayerManager extends EventEmitter {
             : (state.availableHours || []);
 
         let timeSteps;
+        let mrmsTimelineSource = '';
         if (state.isMRMS) {
-            timeSteps = fromState.length ? fromState : fromCore;
+            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;
         }
 
-        return (timeSteps || [])
+        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;
     }
 
     /**
@@ -763,6 +998,12 @@ export class WeatherLayerManager extends EventEmitter {
             if (mode === 'rebuild') {
                 this._initialGridLoadPending = false;
             }
+            this._debugLog('_runParallelGridFrameLoads:skip', {
+                reason: !times.length ? 'no times' : 'no shaderLayer',
+                mode,
+                rebuildId,
+                timesLen: times.length,
+            });
             return;
         }
 
@@ -778,6 +1019,25 @@ export class WeatherLayerManager extends EventEmitter {
         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)
@@ -798,9 +1058,20 @@ export class WeatherLayerManager extends EventEmitter {
                                 : 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;
                         }
@@ -833,9 +1104,17 @@ export class WeatherLayerManager extends EventEmitter {
                             this.currentLoadedTimeKey = time;
                             this.map.triggerRepaint();
                         }
+                    } else if (this._debug && mode === 'append') {
+                        this._debugLog('_loadGridData:empty grid (append)', { time, mode, rebuildId });
                     }
                 })
-                .catch(() => {
+                .catch((err) => {
+                    this._debugLog('_loadGridData:error', {
+                        time,
+                        mode,
+                        rebuildId,
+                        message: err?.message || String(err),
+                    });
                     if (
                         mode === 'rebuild' &&
                         Number.isFinite(primaryTimeForRebuild) &&
@@ -910,8 +1189,26 @@ export class WeatherLayerManager extends EventEmitter {
         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;
         }
 
@@ -925,11 +1222,21 @@ export class WeatherLayerManager extends EventEmitter {
         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;
         }
 
@@ -1171,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