@aguacerowx/mapsgl 0.0.50 → 0.0.51

package/src/NwsWatchesWarningsOverlay.js

@@ -1,852 +1,858 @@
-/**
- * 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,
-    nwsRevisionVisibilityActive,
-    parseNwwsWsDelta,
-    pickBestNwsRevisionAmongConflictingFeatures,
-    unwrapNwwsFeatureCollectionRoot,
-} from './nwsAlertsSupport.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;
-
-        /** @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;
-    }
-
-    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;
-        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)) {
-            this._refreshPaint();
-            this._resyncSourceDataFilters();
-            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,
-        });
-    }
-
-    /**
-     * 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;
-        this._applyTimeFilters();
-    }
-
-    _userColors() {
-        return this._nwsAlertSettings.colors ?? {};
-    }
-
-    _lineStyles() {
-        return this._nwsAlertSettings.lineStyles ?? {};
-    }
-
-    _flashStyles() {
-        return this._nwsAlertSettings.flashStyles ?? {};
-    }
-
-    _isFollowingLatestTimelineAnchor() {
-        const current = this._timelineUnix;
-        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 followRealtimeAtLatestAnchor = !userPinnedRealtime && this._isFollowingLatestTimelineAnchor();
-        const useRealtime = userPinnedRealtime || followRealtimeAtLatestAnchor;
-        return {
-            useRealtime,
-            timelineUnix: useRealtime ? undefined : this._timelineUnix,
-        };
-    }
-
-    _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);
-            m.fire('nws:alert:click', { originalEvent: e, feature: hit, ...payload });
-        } 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 url = this.getAlertsUrl();
-        const res = await fetch(url);
-        if (!res.ok) throw new Error(`NWS alerts HTTP ${res.status}`);
-        const parsed = await res.json();
-        const geojson = unwrapNwwsFeatureCollectionRoot(parsed);
-        if (!geojson) return null;
-        return this._normalizeSnapshot(geojson);
-    }
-
-    _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;
-        try {
-            const baseline = await this._fetchBaseline();
-            if (baseline) {
-                this._workingFc = baseline;
-            }
-        } catch (err) {
-            console.warn('[NwsWatchesWarningsOverlay] Baseline fetch failed:', err);
-        }
-
-        const paintWhenReady = () => {
-            this._ensureLayers();
-            this._setWorkingData(this._workingFc);
-        };
-
-        if (!this.map.isStyleLoaded()) {
-            this.map.once('style.load', paintWhenReady);
-        } else {
-            paintWhenReady();
-        }
-
-        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).
-     */
-    syncWithMode({ enabled, timelineUnix, timelineTimes }) {
-        if (this._destroyed) return;
-        this.options.enabled = !!enabled;
-        if (timelineTimes !== undefined) {
-            this._timelineTimes = Array.isArray(timelineTimes) ? timelineTimes : null;
-        }
-        this.setTimelineUnix(timelineUnix);
-        if (!this.options.enabled) {
-            this._started = false;
-            this._sseFirstOpen = true;
-            this._tearDownStream();
-            this._removeLayers();
-            return;
-        }
-        if (!this._started) {
-            this._started = true;
-            void this._initialLoad();
-        } else {
-            this._applyTimeFilters();
-        }
-    }
-
-    destroy() {
-        this._destroyed = true;
-        this._started = false;
-        this.map?.off?.('click', this._boundClick);
-        this._tearDownStream();
-        this._removeLayers();
-    }
-}
+/**
+ * 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,
+    nwsRevisionVisibilityActive,
+    parseNwwsWsDelta,
+    pickBestNwsRevisionAmongConflictingFeatures,
+    unwrapNwwsFeatureCollectionRoot,
+} from './nwsAlertsSupport.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;
+
+        /** @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;
+    }
+
+    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;
+        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)) {
+            this._refreshPaint();
+            this._resyncSourceDataFilters();
+            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,
+        });
+    }
+
+    /**
+     * 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;
+        this._applyTimeFilters();
+    }
+
+    _userColors() {
+        return this._nwsAlertSettings.colors ?? {};
+    }
+
+    _lineStyles() {
+        return this._nwsAlertSettings.lineStyles ?? {};
+    }
+
+    _flashStyles() {
+        return this._nwsAlertSettings.flashStyles ?? {};
+    }
+
+    _isFollowingLatestTimelineAnchor() {
+        const current = this._timelineUnix;
+        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 followRealtimeAtLatestAnchor = !userPinnedRealtime && this._isFollowingLatestTimelineAnchor();
+        const useRealtime = userPinnedRealtime || followRealtimeAtLatestAnchor;
+        return {
+            useRealtime,
+            timelineUnix: useRealtime ? undefined : this._timelineUnix,
+        };
+    }
+
+    _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 url = this.getAlertsUrl();
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`NWS alerts HTTP ${res.status}`);
+        const parsed = await res.json();
+        const geojson = unwrapNwwsFeatureCollectionRoot(parsed);
+        if (!geojson) return null;
+        return this._normalizeSnapshot(geojson);
+    }
+
+    _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;
+        try {
+            const baseline = await this._fetchBaseline();
+            if (baseline) {
+                this._workingFc = baseline;
+            }
+        } catch (err) {
+            console.warn('[NwsWatchesWarningsOverlay] Baseline fetch failed:', err);
+        }
+
+        const paintWhenReady = () => {
+            this._ensureLayers();
+            this._setWorkingData(this._workingFc);
+        };
+
+        if (!this.map.isStyleLoaded()) {
+            this.map.once('style.load', paintWhenReady);
+        } else {
+            paintWhenReady();
+        }
+
+        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).
+     */
+    syncWithMode({ enabled, timelineUnix, timelineTimes }) {
+        if (this._destroyed) return;
+        this.options.enabled = !!enabled;
+        if (timelineTimes !== undefined) {
+            this._timelineTimes = Array.isArray(timelineTimes) ? timelineTimes : null;
+        }
+        this.setTimelineUnix(timelineUnix);
+        if (!this.options.enabled) {
+            this._started = false;
+            this._sseFirstOpen = true;
+            this._tearDownStream();
+            this._removeLayers();
+            return;
+        }
+        if (!this._started) {
+            this._started = true;
+            void this._initialLoad();
+        } else {
+            this._applyTimeFilters();
+        }
+    }
+
+    destroy() {
+        this._destroyed = true;
+        this._started = false;
+        this.map?.off?.('click', this._boundClick);
+        this._tearDownStream();
+        this._removeLayers();
+    }
+}