@aguacerowx/javascript-sdk 0.0.24 → 0.0.26

package/src/nws/NwsWatchesWarningsOverlay.js

@@ -0,0 +1,977 @@
+/**
+ * NWS watches/warnings overlay for Mapbox GL (default: all alert types; optional user allowlist).
+ * Pairs with aguacero-frontend defaults and NWWS HTTP + SSE feeds.
+ */
+
+import {
+    buildNwsDualLinePaint,
+    buildNwsFillColorExpression,
+    buildNwsLineDasharrayExpression,
+    buildWarningsFillOpacityExpr,
+    buildWarningsLineOpacityExpr,
+    collectNwsExpressionEventKeys,
+    NWS_DEFAULT_FILL_HIDDEN,
+} from './nwsSdkConstants.js';
+import {
+    applyNwwsDeltaToCollection,
+    buildAlertClickPayload,
+    cloneNwwsFeatureCollectionStrippingVolatile,
+    enrichWarningsWithColors,
+    filterNwwsTerminalStatusFeatures,
+    filterNwsAlertsByScope,
+    getNwwsProductKeyFromFeature,
+    normalizeFeatureCollectionForMapboxGl,
+    normalizeNwwsHttpAlertFeature,
+    nwsFeatureOverlapsUnixWindow,
+    nwsRevisionVisibilityActive,
+    parseNwwsWsDelta,
+    pickBestNwsRevisionAmongConflictingFeatures,
+    unwrapNwwsFeatureCollectionRoot,
+} from './nwsAlertsSupport.js';
+import {
+    buildNwwsActiveAlertsUrl,
+    nwsAlertsFetchSpecCacheKey,
+    nwwsAlertsFetchUnixWindow,
+} from './nwsAlertsFetchSpec.js';
+
+/** Aguacero base style: state polygon outlines — NWS alert lines render under this layer. */
+export const NWS_DEFAULT_LINE_BEFORE_LAYER_ID = 'AML_-_states';
+
+const DEFAULT_OPTS = {
+    enabled: false,
+    /**
+     * Optional manual override: insert NWS fill immediately **below** this layer id.
+     * When null, {@link NwsWatchesWarningsOverlay._resolveFillAnchorLayerId} picks the lower of
+     * `weatherLayerId` and {@link NWS_DEFAULT_LINE_BEFORE_LAYER_ID} so fill does not cover state outlines
+     * when the weather custom layer is stacked above `AML_-_states`.
+     */
+    fillBeforeLayerId: null,
+    /**
+     * Active satellite / MRMS / NEXRAD Mapbox layer id (set by {@link WeatherLayerManager}).
+     * Used with {@link NWS_DEFAULT_LINE_BEFORE_LAYER_ID} for automatic fill stacking when `fillBeforeLayerId` is unset.
+     */
+    weatherLayerId: null,
+    /**
+     * Insert NWS outline lines immediately **below** this layer (under state boundaries, above terrain).
+     * @default {@link NWS_DEFAULT_LINE_BEFORE_LAYER_ID}
+     */
+    lineBeforeLayerId: NWS_DEFAULT_LINE_BEFORE_LAYER_ID,
+    /** Base URL without trailing slash; `/alerts` and `/alerts/stream` are appended. */
+    alertsBaseUrl: 'https://api.aguacerowx.com',
+    /** When true, time filter uses wall clock and onset window (matches frontend `activeOnlyRealtime`). */
+    activeOnlyRealtime: false,
+    /** When false, map clicks do not emit `nws:alert:click`. */
+    alertInteractionEnabled: true,
+    fillOpacity: 1,
+    lineOpacity: 0.9,
+    lineWidth: 2,
+    /** Debounce SSE delta merges (ms). */
+    deltaDebounceMs: 500,
+    nwsAlertSettings: null,
+};
+
+function normalizeAlertScope(d) {
+    const s = d?.alertScope;
+    if (s === 'user') {
+        return 'user';
+    }
+    return 'all';
+}
+
+function mergeNwsSettings(base) {
+    const d = base ?? {};
+    return {
+        colors: { ...(d.colors ?? {}) },
+        fillHidden: {
+            ...NWS_DEFAULT_FILL_HIDDEN,
+            ...(d.fillHidden ?? {}),
+        },
+        lineHidden: { ...(d.lineHidden ?? {}) },
+        fillOpacity: d.fillOpacity != null ? { ...d.fillOpacity } : {},
+        lineStyles: { ...(d.lineStyles ?? {}) },
+        lineDash: d.lineDash ?? 'solid',
+        flashStyles: { ...(d.flashStyles ?? {}) },
+        activeOnlyRealtime: d.activeOnlyRealtime ?? false,
+        /**
+         * `'all'` (default): every alert with a resolved `event_name`.
+         * `'user'`: only alerts listed in `includedAlerts` (exact NWS names; subtypes match if parent is listed).
+         */
+        alertScope: normalizeAlertScope(d),
+        /** @type {string[]} */
+        includedAlerts: Array.isArray(d.includedAlerts)
+            ? d.includedAlerts.map((x) => (x != null ? String(x).trim() : '')).filter(Boolean)
+            : [],
+    };
+}
+
+export class NwsWatchesWarningsOverlay {
+    /**
+     * @param {import('mapbox-gl').Map} map
+     * @param {object} [options]
+     */
+    constructor(map, options = {}) {
+        this.map = map;
+        this.options = { ...DEFAULT_OPTS, ...options };
+        this._nwsAlertSettings = mergeNwsSettings({
+            ...(options.nwsAlertSettings ?? {}),
+            ...(options.activeOnlyRealtime !== undefined ? { activeOnlyRealtime: options.activeOnlyRealtime } : {}),
+        });
+
+        this._sourceId = 'aguacero-nws-alerts-source';
+        this._fillId = 'aguacero-nws-alerts-fill';
+        this._lineCasingId = 'aguacero-nws-alerts-line-casing';
+        this._lineCoreId = 'aguacero-nws-alerts-line-core';
+
+        this._workingFc = { type: 'FeatureCollection', features: [] };
+        /** Terminal + enriched features before `alertScope` / `includedAlerts` filtering (full dataset for SSE + scope changes). */
+        this._preScopeFc = { type: 'FeatureCollection', features: [] };
+        this._eventSource = null;
+        this._deltaTimer = null;
+        this._pendingDeltas = [];
+        this._boundClick = this._onMapClick.bind(this);
+        /** @type {((ev: MessageEvent) => void) | null} */
+        this._sseInboundHandler = null;
+        /** @type {string[] | null} */
+        this._sseBoundEventNames = null;
+        this._sseFirstOpen = true;
+        this._destroyed = false;
+        /** When true, baseline fetch + SSE have been started for the current enabled session. */
+        this._started = false;
+        /** GET `/alerts?hours=` — same basis as aguacero-frontend observational duration (tier-clamped). */
+        this._alertsFetchHours = 1;
+        /** {@link nwsAlertsFetchSpecCacheKey} for the last baseline request; refetch when hours change. */
+        this._lastAlertsSpecKey = null;
+        /** Invalidates in-flight baseline HTTP when a newer hours spec is requested. */
+        this._baselineFetchGen = 0;
+
+        /** @type {number | null | undefined} */
+        this._timelineUnix = undefined;
+        /** Timeline unix list for the active layer (satellite / MRMS / NEXRAD) — used to match frontend “live edge” behavior. */
+        this._timelineTimes = null;
+        /** Last finite scrub time while sat/MRMS/NEXRAD is active — keeps filters during brief `nexradTimestamp: null` gaps. */
+        this._stickyTimelineUnix = null;
+    }
+
+    getAlertsUrl() {
+        const base = String(this.options.alertsBaseUrl || '').replace(/\/$/, '');
+        return `${base}/alerts`;
+    }
+
+    getStreamUrl() {
+        const base = String(this.options.alertsBaseUrl || '').replace(/\/$/, '');
+        return `${base}/alerts/stream`;
+    }
+
+    /**
+     * Update merged NWS user settings (colors, allowlist, fill/line visibility, etc.).
+     * @param {object} partial
+     */
+    setNwsAlertSettings(partial) {
+        this._nwsAlertSettings = mergeNwsSettings({ ...this._nwsAlertSettings, ...partial });
+        this._refreshPaint();
+        this._resyncSourceDataFilters();
+    }
+
+    /** Merge top-level options (e.g. `deltaDebounceMs`, `alertsBaseUrl`) and/or nested `nwsAlertSettings`. */
+    updateOptions(partial) {
+        if (!partial || typeof partial !== 'object') return;
+        const prevScope = this._nwsAlertSettings.alertScope ?? 'all';
+        const prevIncludedKey = JSON.stringify(this._nwsAlertSettings.includedAlerts ?? []);
+        const prevActiveOnly = this._nwsAlertSettings.activeOnlyRealtime;
+        for (const [k, v] of Object.entries(partial)) {
+            if (v === undefined) continue;
+            if (k === 'nwsAlertSettings' && v && typeof v === 'object') {
+                this._nwsAlertSettings = mergeNwsSettings({
+                    ...this._nwsAlertSettings,
+                    ...v,
+                });
+            } else {
+                this.options[k] = v;
+            }
+        }
+        if (this.map?.getLayer?.(this._fillId)) {
+            const nextScope = this._nwsAlertSettings.alertScope ?? 'all';
+            const nextIncludedKey = JSON.stringify(this._nwsAlertSettings.includedAlerts ?? []);
+            const scopeFilterChanged = prevScope !== nextScope || prevIncludedKey !== nextIncludedKey;
+            const activeOnlyChanged = prevActiveOnly !== this._nwsAlertSettings.activeOnlyRealtime;
+            this._refreshPaint();
+            if (scopeFilterChanged) {
+                this._resyncSourceDataFilters();
+            } else if (activeOnlyChanged) {
+                this._applyTimeFilters();
+            }
+            this._syncClickHandler();
+            this._applyLayerOrder();
+        }
+    }
+
+    /**
+     * Layer id to insert/move NWS fill **before** (Mapbox: directly under that layer).
+     * Manual `fillBeforeLayerId` wins. When the active weather layer exists, fill is always anchored under it
+     * so radar/satellite/MRMS draws above the alert fill. Without weather, falls back under state outlines when present.
+     * @returns {string | null}
+     */
+    _resolveFillAnchorLayerId() {
+        const m = this.map;
+        const styleLayers = m.getStyle()?.layers;
+        if (!styleLayers) {
+            return null;
+        }
+
+        const manual = this.options.fillBeforeLayerId;
+        if (manual != null && String(manual) !== '' && m.getLayer(String(manual))) {
+            return String(manual);
+        }
+
+        const layerIndex = (id) => styleLayers.findIndex((l) => l.id === id);
+        const weatherId = this.options.weatherLayerId;
+        const statesId = NWS_DEFAULT_LINE_BEFORE_LAYER_ID;
+
+        if (weatherId && m.getLayer(weatherId)) {
+            return weatherId;
+        }
+
+        const iS = m.getLayer(statesId) ? layerIndex(statesId) : -1;
+        if (iS >= 0) {
+            return statesId;
+        }
+        return null;
+    }
+
+    /**
+     * Stack: alert fill below weather; NEXRAD/satellite/MRMS below alert lines.
+     * When weather is present, lines sit directly under whatever layer is above the weather layer (often state outlines).
+     */
+    _applyLayerOrder() {
+        const m = this.map;
+        if (!m?.getStyle?.() || !m.getLayer(this._fillId)) {
+            return;
+        }
+        const weatherId = this.options.weatherLayerId;
+        const statesFallback = this.options.lineBeforeLayerId || NWS_DEFAULT_LINE_BEFORE_LAYER_ID;
+
+        try {
+            const fillAnchor = this._resolveFillAnchorLayerId();
+            if (fillAnchor) {
+                m.moveLayer(this._fillId, fillAnchor);
+            }
+
+            const layers = m.getStyle()?.layers ?? [];
+            let lineBeforeId = null;
+            if (weatherId && m.getLayer(weatherId)) {
+                const iw = layers.findIndex((l) => l.id === weatherId);
+                if (iw >= 0 && iw < layers.length - 1) {
+                    lineBeforeId = layers[iw + 1].id;
+                }
+            }
+            if (!lineBeforeId && m.getLayer(statesFallback)) {
+                lineBeforeId = statesFallback;
+            }
+
+            if (lineBeforeId && m.getLayer(this._lineCasingId) && m.getLayer(lineBeforeId)) {
+                m.moveLayer(this._lineCasingId, lineBeforeId);
+            }
+            if (lineBeforeId && m.getLayer(this._lineCoreId) && m.getLayer(lineBeforeId)) {
+                m.moveLayer(this._lineCoreId, lineBeforeId);
+            }
+        } catch {
+            /* style still settling */
+        }
+    }
+
+    /**
+     * @param {boolean} enabled - Master switch; when false, stream is torn down and layers cleared.
+     */
+    setEnabled(enabled) {
+        this.options.enabled = !!enabled;
+        this.syncWithMode({
+            enabled: this.options.enabled,
+            timelineUnix: this._timelineUnix,
+            timelineTimes: this._timelineTimes,
+            alertsFetchHours: this._alertsFetchHours,
+        });
+    }
+
+    /**
+     * Whether clicking alerts emits `nws:alert:click` on the map.
+     * @param {boolean} on
+     */
+    setAlertInteractionEnabled(on) {
+        this.options.alertInteractionEnabled = !!on;
+        this._syncClickHandler();
+    }
+
+    /**
+     * Timeline unix (satellite / MRMS / NEXRAD slider) for time-of-day filtering.
+     * @param {number | null | undefined} unixSeconds
+     */
+    setTimelineUnix(unixSeconds) {
+        this._timelineUnix = unixSeconds;
+        if (unixSeconds != null && Number.isFinite(Number(unixSeconds))) {
+            this._stickyTimelineUnix = Number(unixSeconds);
+        }
+        this._applyTimeFilters();
+    }
+
+    _userColors() {
+        return this._nwsAlertSettings.colors ?? {};
+    }
+
+    _lineStyles() {
+        return this._nwsAlertSettings.lineStyles ?? {};
+    }
+
+    _flashStyles() {
+        return this._nwsAlertSettings.flashStyles ?? {};
+    }
+
+    _hasNonEmptyTimelineTimes() {
+        const times = this._timelineTimes;
+        return Array.isArray(times) && times.length > 0;
+    }
+
+    /**
+     * Scrub reference: live `timelineUnix`, else last good scrub while observation data is loading, else newest tick.
+     */
+    _effectiveScrubUnix() {
+        const raw = this._timelineUnix;
+        if (raw != null && Number.isFinite(Number(raw))) {
+            return Number(raw);
+        }
+        if (this._stickyTimelineUnix != null && Number.isFinite(this._stickyTimelineUnix)) {
+            return this._stickyTimelineUnix;
+        }
+        const times = this._timelineTimes;
+        if (Array.isArray(times) && times.length > 0) {
+            let latest = -Infinity;
+            for (const t of times) {
+                if (typeof t === 'number' && Number.isFinite(t) && t > latest) {
+                    latest = t;
+                }
+            }
+            if (Number.isFinite(latest)) {
+                return latest;
+            }
+        }
+        return null;
+    }
+
+    _isFollowingLatestTimelineAnchor() {
+        const current = this._effectiveScrubUnix();
+        if (current == null || !Number.isFinite(current)) return false;
+        const times = this._timelineTimes;
+        if (!Array.isArray(times) || times.length === 0) return false;
+        let latest = -Infinity;
+        for (const t of times) {
+            if (typeof t === 'number' && Number.isFinite(t) && t > latest) {
+                latest = t;
+            }
+        }
+        if (!Number.isFinite(latest)) return false;
+        return Math.abs(current - latest) <= 1;
+    }
+
+    /**
+     * Matches aguacero-frontend {@link WatchesWarningsLayer.resolveNwsDisplayTimeMode}: at the last slider
+     * step, use wall clock so SSE/stream updates appear even when the timeline tick lags.
+     */
+    _resolveDisplayTimeMode() {
+        const userPinnedRealtime = this._nwsAlertSettings.activeOnlyRealtime === true;
+        const effectiveUnix = this._effectiveScrubUnix();
+        const followRealtimeAtLatestAnchor = !userPinnedRealtime && this._isFollowingLatestTimelineAnchor();
+        const noScrubObservationTimelineUseWallClock =
+            !userPinnedRealtime &&
+            effectiveUnix == null &&
+            !this._hasNonEmptyTimelineTimes();
+        let useRealtime =
+            userPinnedRealtime || followRealtimeAtLatestAnchor || noScrubObservationTimelineUseWallClock;
+        let timelineUnixOut = useRealtime ? undefined : effectiveUnix;
+        if (!useRealtime && (timelineUnixOut == null || !Number.isFinite(timelineUnixOut))) {
+            useRealtime = true;
+            timelineUnixOut = undefined;
+        }
+        return {
+            useRealtime,
+            timelineUnix: timelineUnixOut,
+        };
+    }
+
+    _applyTimeFilters() {
+        const m = this.map;
+        if (!m?.getSource?.(this._sourceId)) return;
+
+        const timeMode = this._resolveDisplayTimeMode();
+        const referenceUnix = timeMode.useRealtime
+            ? Math.floor(Date.now() / 1000)
+            : timeMode.timelineUnix;
+        const useOnsetWindow = this._nwsAlertSettings.activeOnlyRealtime === true;
+
+        /** @type {Map<number, boolean>} */
+        const tentativeActive = new Map();
+
+        for (const f of this._workingFc.features ?? []) {
+            if (f.id == null) continue;
+            const fid = typeof f.id === 'number' ? f.id : Number(f.id);
+            if (!Number.isFinite(fid)) continue;
+
+            let isActive = true;
+            if (referenceUnix != null && Number.isFinite(referenceUnix)) {
+                const p = f.properties ?? {};
+                const rev = nwsRevisionVisibilityActive(p, referenceUnix);
+                if (rev === false) {
+                    isActive = false;
+                } else {
+                    const startWindow = useOnsetWindow ? (p.active_start_unix ?? p.start_unix) : p.start_unix;
+                    if (startWindow != null && referenceUnix < startWindow) {
+                        isActive = false;
+                    } else if (p.end_unix != null && referenceUnix > p.end_unix) {
+                        isActive = false;
+                    }
+                }
+            }
+
+            tentativeActive.set(fid, isActive);
+        }
+
+        if (referenceUnix != null && Number.isFinite(referenceUnix)) {
+            const keyToFeatures = new globalThis.Map();
+            for (const f of this._workingFc.features ?? []) {
+                if (f.id == null) continue;
+                const fid = typeof f.id === 'number' ? f.id : Number(f.id);
+                if (!Number.isFinite(fid) || !tentativeActive.get(fid)) continue;
+                const pk = getNwwsProductKeyFromFeature(f);
+                if (!pk) continue;
+                let bucket = keyToFeatures.get(pk);
+                if (!bucket) {
+                    bucket = [];
+                    keyToFeatures.set(pk, bucket);
+                }
+                bucket.push(f);
+            }
+            for (const [, group] of keyToFeatures) {
+                if (group.length <= 1) continue;
+                const winner = pickBestNwsRevisionAmongConflictingFeatures(group, referenceUnix);
+                const winId = typeof winner?.id === 'number' ? winner.id : Number(winner?.id);
+                for (const f of group) {
+                    const gfid = typeof f.id === 'number' ? f.id : Number(f.id);
+                    if (Number.isFinite(gfid) && Number.isFinite(winId) && gfid !== winId) {
+                        tentativeActive.set(gfid, false);
+                    }
+                }
+            }
+        }
+
+        for (const f of this._workingFc.features ?? []) {
+            if (f.id == null) continue;
+            const fid = typeof f.id === 'number' ? f.id : Number(f.id);
+            if (!Number.isFinite(fid)) continue;
+            const isActive = tentativeActive.get(fid) ?? true;
+            try {
+                m.setFeatureState({ source: this._sourceId, id: f.id }, { active: isActive });
+            } catch {
+                /* ignore */
+            }
+        }
+    }
+
+    _buildPaint() {
+        const settings = this._nwsAlertSettings;
+        const visible = this.options.enabled !== false;
+        const fillOpacity = Number(this.options.fillOpacity ?? 1);
+        const lineOpacity = Number(this.options.lineOpacity ?? 0.9);
+        const lineWidth = Number(this.options.lineWidth ?? 2);
+
+        const userColors = this._userColors();
+        const exprKeys = collectNwsExpressionEventKeys(settings);
+        const fillColorExpr = buildNwsFillColorExpression(userColors, exprKeys);
+        const dualLine = buildNwsDualLinePaint(userColors, this._lineStyles(), lineWidth, exprKeys);
+        const lineDashExpr = buildNwsLineDasharrayExpression(this._lineStyles(), settings.lineDash ?? 'solid', exprKeys);
+
+        const baseFillOpacityExpr = buildWarningsFillOpacityExpr(
+            visible,
+            fillOpacity,
+            settings.fillHidden,
+            settings.fillOpacity,
+            exprKeys
+        );
+        const baseLineOpacityExpr = buildWarningsLineOpacityExpr(visible, lineOpacity, settings.lineHidden, exprKeys);
+
+        const fillOpacityExpr = ['case', ['boolean', ['feature-state', 'active'], false], baseFillOpacityExpr, 0];
+        const lineOpacityExpr = ['case', ['boolean', ['feature-state', 'active'], false], baseLineOpacityExpr, 0];
+
+        return { fillColorExpr, dualLine, lineDashExpr, fillOpacityExpr, lineOpacityExpr, lineLayout: {
+            'line-cap': 'round',
+            'line-join': 'round',
+            'line-sort-key': ['coalesce', ['get', '_nws_render_priority'], 0],
+        } };
+    }
+
+    _refreshPaint() {
+        const m = this.map;
+        if (!m?.getLayer?.(this._fillId)) return;
+        const p = this._buildPaint();
+        m.setPaintProperty(this._fillId, 'fill-color', p.fillColorExpr);
+        m.setPaintProperty(this._fillId, 'fill-opacity', p.fillOpacityExpr);
+        m.setPaintProperty(this._lineCasingId, 'line-color', p.dualLine.casingColor);
+        m.setPaintProperty(this._lineCasingId, 'line-width', p.dualLine.casingWidth);
+        m.setPaintProperty(this._lineCasingId, 'line-opacity', p.lineOpacityExpr);
+        m.setPaintProperty(this._lineCasingId, 'line-dasharray', p.lineDashExpr);
+        m.setPaintProperty(this._lineCoreId, 'line-color', p.dualLine.coreColor);
+        m.setPaintProperty(this._lineCoreId, 'line-width', p.dualLine.coreWidth);
+        m.setPaintProperty(this._lineCoreId, 'line-opacity', p.lineOpacityExpr);
+        m.setPaintProperty(this._lineCoreId, 'line-dasharray', p.lineDashExpr);
+    }
+
+    /**
+     * Re-apply `alertScope` / `includedAlerts` against the last full pre-scope snapshot (no Mapbox `disabled` filter).
+     */
+    _resyncSourceDataFilters() {
+        const src = this.map?.getSource?.(this._sourceId);
+        if (!src || typeof src.setData !== 'function') return;
+        if (!this._preScopeFc?.features?.length) return;
+        const scope = this._nwsAlertSettings.alertScope ?? 'all';
+        const included = this._nwsAlertSettings.includedAlerts ?? [];
+        const next = normalizeFeatureCollectionForMapboxGl(
+            filterNwsAlertsByScope(this._preScopeFc, scope, included)
+        );
+        this._workingFc = next;
+        try {
+            src.setData(next);
+        } catch {
+            /* ignore */
+        }
+        this._applyTimeFilters();
+    }
+
+    _ensureLayers() {
+        const m = this.map;
+        if (!m?.addSource) return;
+
+        const paint = this._buildPaint();
+
+        const sourceData = normalizeFeatureCollectionForMapboxGl(this._workingFc);
+        if (!m.getSource(this._sourceId)) {
+            m.addSource(this._sourceId, {
+                type: 'geojson',
+                data: sourceData,
+            });
+        } else {
+            m.getSource(this._sourceId).setData(sourceData);
+        }
+
+        const fillLayer = {
+            id: this._fillId,
+            type: 'fill',
+            source: this._sourceId,
+            layout: { 'fill-sort-key': ['coalesce', ['get', '_nws_render_priority'], 0] },
+            paint: {
+                'fill-color': paint.fillColorExpr,
+                'fill-opacity': paint.fillOpacityExpr,
+            },
+        };
+        const casingLayer = {
+            id: this._lineCasingId,
+            type: 'line',
+            source: this._sourceId,
+            layout: paint.lineLayout,
+            paint: {
+                'line-color': paint.dualLine.casingColor,
+                'line-width': paint.dualLine.casingWidth,
+                'line-opacity': paint.lineOpacityExpr,
+                'line-dasharray': paint.lineDashExpr,
+            },
+        };
+        const coreLayer = {
+            id: this._lineCoreId,
+            type: 'line',
+            source: this._sourceId,
+            layout: paint.lineLayout,
+            paint: {
+                'line-color': paint.dualLine.coreColor,
+                'line-width': paint.dualLine.coreWidth,
+                'line-opacity': paint.lineOpacityExpr,
+                'line-dasharray': paint.lineDashExpr,
+            },
+        };
+
+        const fillAnchor = this._resolveFillAnchorLayerId();
+        const lineAnchorId = this.options.lineBeforeLayerId || NWS_DEFAULT_LINE_BEFORE_LAYER_ID;
+        const lineBefore = m.getLayer(lineAnchorId) ? lineAnchorId : undefined;
+
+        if (!m.getLayer(this._fillId)) {
+            m.addLayer(fillLayer, fillAnchor ?? undefined);
+        }
+        if (!m.getLayer(this._lineCasingId)) {
+            m.addLayer(casingLayer, lineBefore);
+        }
+        if (!m.getLayer(this._lineCoreId)) {
+            m.addLayer(coreLayer, lineBefore);
+        }
+
+        this._applyTimeFilters();
+        this._syncClickHandler();
+        this._applyLayerOrder();
+        requestAnimationFrame(() => this._applyLayerOrder());
+    }
+
+    _removeLayers() {
+        const m = this.map;
+        if (!m) return;
+        for (const id of [this._lineCoreId, this._lineCasingId, this._fillId]) {
+            if (m.getLayer(id)) {
+                m.removeLayer(id);
+            }
+        }
+        if (m.getSource(this._sourceId)) {
+            m.removeSource(this._sourceId);
+        }
+        this._workingFc = { type: 'FeatureCollection', features: [] };
+        this._preScopeFc = { type: 'FeatureCollection', features: [] };
+    }
+
+    _syncClickHandler() {
+        const m = this.map;
+        if (!m) return;
+        m.off('click', this._boundClick);
+        if (this.options.alertInteractionEnabled && this.options.enabled && m.getLayer(this._fillId)) {
+            m.on('click', this._boundClick);
+        }
+    }
+
+    _onMapClick(e) {
+        if (!this.options.alertInteractionEnabled) return;
+        const m = this.map;
+        const layers = [this._fillId, this._lineCasingId, this._lineCoreId].filter((id) => m.getLayer(id));
+        if (!layers.length) return;
+        const feats = m.queryRenderedFeatures(e.point, { layers });
+        const hit = feats.find((f) => f.source === this._sourceId);
+        if (!hit) return;
+        try {
+            const payload = buildAlertClickPayload(hit);
+            const layerId = hit.layer && typeof hit.layer === 'object' ? hit.layer.id : hit.layer;
+            m.fire('nws:alert:click', {
+                originalEvent: e,
+                featureSummary: { id: hit.id, source: hit.source, layerId },
+                ...payload,
+                feature: hit,
+            });
+        } catch {
+            /* ignore */
+        }
+    }
+
+    _normalizeSnapshot(fc) {
+        const pre = filterNwwsTerminalStatusFeatures(enrichWarningsWithColors(fc));
+        this._preScopeFc = pre;
+        const scope = this._nwsAlertSettings.alertScope ?? 'all';
+        const included = this._nwsAlertSettings.includedAlerts ?? [];
+        return filterNwsAlertsByScope(pre, scope, included);
+    }
+
+    _setWorkingData(fc) {
+        this._workingFc = cloneNwwsFeatureCollectionStrippingVolatile(fc);
+        const src = this.map?.getSource?.(this._sourceId);
+        if (src) {
+            src.setData(this._workingFc);
+        }
+        this._applyTimeFilters();
+    }
+
+    async _fetchBaseline() {
+        const myGen = ++this._baselineFetchGen;
+        const hours = Math.max(1, Math.floor(Number(this._alertsFetchHours) || 1));
+        const url = buildNwwsActiveAlertsUrl(this.getAlertsUrl(), hours);
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`NWS alerts HTTP ${res.status}`);
+        const parsed = await res.json();
+        if (myGen !== this._baselineFetchGen) return null;
+        const geojson = unwrapNwwsFeatureCollectionRoot(parsed);
+        if (!geojson) return null;
+        const { winStartSec, winEndSec } = nwwsAlertsFetchUnixWindow(hours, null);
+        const overlapping = (geojson.features ?? []).filter((f) =>
+            nwsFeatureOverlapsUnixWindow(f, winStartSec, winEndSec)
+        );
+        const filtered = { ...geojson, features: overlapping };
+        if (myGen !== this._baselineFetchGen) return null;
+        return this._normalizeSnapshot(filtered);
+    }
+
+    async _refetchBaselineForNewHours() {
+        if (this._destroyed || !this.options.enabled) return;
+        try {
+            const baseline = await this._fetchBaseline();
+            if (baseline && !this._destroyed && this.options.enabled) {
+                this._workingFc = baseline;
+                this._setWorkingData(baseline);
+            }
+        } catch (err) {
+            console.warn('[NwsWatchesWarningsOverlay] Baseline refetch (hours change) failed:', err);
+        }
+    }
+
+    _processInboundSocketText(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        } catch {
+            return;
+        }
+        if (!msg || typeof msg !== 'object') return;
+        if (msg.type === 'ping') return;
+
+        if (msg.type === 'alert' && msg.alert != null && typeof msg.alert === 'object') {
+            const raw = msg.alert;
+            const feature =
+                raw.type === 'Feature'
+                    ? raw
+                    : {
+                          type: 'Feature',
+                          id: raw.id,
+                          geometry: raw.geometry,
+                          properties: raw.properties ?? {},
+                      };
+            this._processInboundSocketText(JSON.stringify(normalizeNwwsHttpAlertFeature(feature, true)));
+            return;
+        }
+
+        if (msg.type === 'history' && Array.isArray(msg.alerts)) {
+            const fc = {
+                type: 'FeatureCollection',
+                features: msg.alerts.map((f) => normalizeNwwsHttpAlertFeature(f, true)),
+            };
+            const next = this._normalizeSnapshot(fc);
+            this._workingFc = next;
+            if (this.map?.getSource?.(this._sourceId)) {
+                this._setWorkingData(next);
+            }
+            return;
+        }
+
+        if (Array.isArray(msg.alerts)) {
+            const normalized = msg.alerts.map((f) =>
+                f?.type === 'Feature' ? normalizeNwwsHttpAlertFeature(f, true) : f
+            );
+            this._processInboundSocketText(JSON.stringify({ upserts: normalized }));
+            return;
+        }
+
+        if (msg.type === 'Feature') {
+            this._processInboundSocketText(JSON.stringify({ upsert: [msg] }));
+            return;
+        }
+
+        const maybeFeature = msg.feature;
+        if (maybeFeature && typeof maybeFeature === 'object' && maybeFeature.type === 'Feature') {
+            this._processInboundSocketText(
+                JSON.stringify({
+                    ...msg,
+                    feature: normalizeNwwsHttpAlertFeature(maybeFeature, true),
+                })
+            );
+            return;
+        }
+
+        const delta = parseNwwsWsDelta(msg);
+        if (delta.upserts.length || delta.cancelIds.length || delta.expireIds.length) {
+            this._pendingDeltas.push(delta);
+            this._scheduleDeltaProcessing();
+            return;
+        }
+
+        const fcSnapshot = unwrapNwwsFeatureCollectionRoot(msg);
+        if (fcSnapshot) {
+            const next = this._normalizeSnapshot(fcSnapshot);
+            this._workingFc = next;
+            if (this.map?.getSource?.(this._sourceId)) {
+                this._setWorkingData(next);
+            }
+        }
+    }
+
+    _scheduleDeltaProcessing() {
+        if (this._deltaTimer != null) return;
+        const ms = Math.max(0, Number(this.options.deltaDebounceMs) || 500);
+        this._deltaTimer = setTimeout(() => {
+            this._deltaTimer = null;
+            this._flushDeltas();
+        }, ms);
+    }
+
+    _flushDeltas() {
+        if (this._destroyed) return;
+        if (!this._pendingDeltas.length) return;
+        const batches = this._pendingDeltas.splice(0, this._pendingDeltas.length);
+        let merged =
+            this._preScopeFc?.features?.length > 0 ? this._preScopeFc : this._workingFc;
+        for (const d of batches) {
+            merged = applyNwwsDeltaToCollection(merged, d);
+        }
+        const next = this._normalizeSnapshot(merged);
+        this._workingFc = next;
+        if (this.map?.getSource?.(this._sourceId)) {
+            this._setWorkingData(next);
+        }
+    }
+
+    _tearDownStream() {
+        if (this._eventSource) {
+            try {
+                const es = this._eventSource;
+                es.onopen = null;
+                es.onmessage = null;
+                es.onerror = null;
+                if (this._sseInboundHandler && this._sseBoundEventNames) {
+                    for (const name of this._sseBoundEventNames) {
+                        es.removeEventListener(name, this._sseInboundHandler);
+                    }
+                }
+                this._sseInboundHandler = null;
+                this._sseBoundEventNames = null;
+                es.close();
+            } catch {
+                /* ignore */
+            }
+            this._eventSource = null;
+        }
+        if (this._deltaTimer != null) {
+            clearTimeout(this._deltaTimer);
+            this._deltaTimer = null;
+        }
+        this._pendingDeltas = [];
+    }
+
+    async _initialLoad() {
+        if (this._destroyed || !this.options.enabled) return;
+
+        const paintWhenReady = () => {
+            this._ensureLayers();
+            this._setWorkingData(this._workingFc);
+        };
+
+        if (!this.map.isStyleLoaded()) {
+            this.map.once('style.load', paintWhenReady);
+        } else {
+            paintWhenReady();
+        }
+
+        void this._fetchBaseline()
+            .then((baseline) => {
+                if (this._destroyed || !this.options.enabled) return;
+                if (baseline) {
+                    this._workingFc = baseline;
+                }
+                this._setWorkingData(this._workingFc);
+            })
+            .catch((err) => {
+                console.warn('[NwsWatchesWarningsOverlay] Baseline fetch failed:', err);
+            });
+
+        this._connectSse();
+    }
+
+    _connectSse() {
+        if (this._destroyed || !this.options.enabled) return;
+        if (typeof EventSource === 'undefined') {
+            console.warn('[NwsWatchesWarningsOverlay] EventSource not available; live stream disabled.');
+            return;
+        }
+        if (this._eventSource) return;
+
+        const url = this.getStreamUrl();
+        try {
+            const es = new EventSource(url);
+            this._eventSource = es;
+            es.onopen = () => {
+                if (!this._sseFirstOpen) {
+                    void this._fetchBaseline().then((fresh) => {
+                        if (fresh && !this._destroyed) {
+                            this._workingFc = fresh;
+                            this._setWorkingData(fresh);
+                        }
+                    });
+                }
+                this._sseFirstOpen = false;
+            };
+            this._sseInboundHandler = (ev) => {
+                if (typeof ev.data === 'string' && ev.data && !ev.data.startsWith(':')) {
+                    this._processInboundSocketText(ev.data);
+                }
+            };
+            this._sseBoundEventNames = ['message', 'alert', 'update', 'delta', 'patch', 'data'];
+            for (const name of this._sseBoundEventNames) {
+                es.addEventListener(name, this._sseInboundHandler);
+            }
+            es.onerror = () => {
+                if (this._eventSource?.readyState === EventSource.CLOSED) {
+                    this._tearDownStream();
+                    this._sseFirstOpen = true;
+                    setTimeout(() => {
+                        if (this.options.enabled && !this._destroyed) {
+                            this._connectSse();
+                        }
+                    }, 2000);
+                }
+            };
+        } catch (e) {
+            console.warn('[NwsWatchesWarningsOverlay] SSE connect failed:', e);
+        }
+    }
+
+    /**
+     * Called by WeatherLayerManager when radar/satellite/MRMS mode is active.
+     * @param {object} opts
+     * @param {boolean} opts.enabled
+     * @param {number | null | undefined} opts.timelineUnix - Active scrubber unix for satellite / MRMS / NEXRAD.
+     * @param {number[] | null | undefined} [opts.timelineTimes] - Full timeline for the current layer (for “live edge” = wall clock).
+     * @param {boolean} [opts.hasObservationTimeline] - When false (model / base map only), scrub hold is cleared and wall clock is used until observation data returns.
+     * @param {number} [opts.alertsFetchHours] - GET `/alerts?hours=` (from WeatherLayerManager / {@link computeNwsAlertsFetchHoursFromAguaceroState}); refetches baseline when this changes.
+     */
+    syncWithMode({ enabled, timelineUnix, timelineTimes, hasObservationTimeline, alertsFetchHours }) {
+        if (this._destroyed) return;
+        const hours =
+            alertsFetchHours != null && Number.isFinite(Number(alertsFetchHours))
+                ? Math.max(1, Math.floor(Number(alertsFetchHours)))
+                : 1;
+        const specKey = nwsAlertsFetchSpecCacheKey(hours);
+        this._alertsFetchHours = hours;
+
+        this.options.enabled = !!enabled;
+        if (hasObservationTimeline === false) {
+            this._stickyTimelineUnix = null;
+        }
+        if (timelineTimes !== undefined) {
+            this._timelineTimes = Array.isArray(timelineTimes) ? timelineTimes : null;
+        }
+        this.setTimelineUnix(timelineUnix);
+        if (!this.options.enabled) {
+            this._stickyTimelineUnix = null;
+            this._started = false;
+            this._lastAlertsSpecKey = null;
+            this._sseFirstOpen = true;
+            this._tearDownStream();
+            this._removeLayers();
+            return;
+        }
+        if (!this._started) {
+            this._started = true;
+            this._lastAlertsSpecKey = specKey;
+            void this._initialLoad();
+            return;
+        }
+        if (this._lastAlertsSpecKey !== specKey) {
+            this._lastAlertsSpecKey = specKey;
+            void this._refetchBaselineForNewHours();
+        }
+        // When already running, time filtering is applied in setTimelineUnix (avoids double work
+        // per scrub tick, matching aguacero-frontend: no full setData on slider move).
+    }
+
+    destroy() {
+        this._destroyed = true;
+        this._started = false;
+        this._stickyTimelineUnix = null;
+        this.map?.off?.('click', this._boundClick);
+        this._tearDownStream();
+        this._removeLayers();
+    }
+}