@aguacerowx/mapsgl 0.0.46 → 0.0.48

package/src/nwsAlertsSupport.js

@@ -1,1111 +1,1156 @@
-/**
- * NWWS HTTP + SSE merge pipeline (subset of aguacero-frontend WatchesWarningsLayer).
- */
-
-import { resolveNwsWarningCustomizationKey } from './nwsWarningCustomizationKey.gen.js';
-import { NWS_ALERT_END_TIME_PROP_KEYS, NWS_WARNINGS_SUBTYPE_PARENT } from './nwsSdkConstants.js';
-
-export const NWS_RENDER_PRIORITY_PROP = '_nws_render_priority';
-
-export const SDK_ALLOWED_EVENT_SET = new Set([
-    'Tornado Watch',
-    'Tornado Warning',
-    'Tornado Warning (Observed)',
-    'Tornado Warning (PDS)',
-    'Tornado Warning (Emergency)',
-    'Severe Thunderstorm Watch',
-    'Severe Thunderstorm Warning',
-    'Severe Thunderstorm Warning (Considerable)',
-    'Severe Thunderstorm Warning (Destructive)',
-]);
-
-const NWS_EVENT_CANONICAL_MAP = new Map(
-    [...SDK_ALLOWED_EVENT_SET].map((name) => [normalizeNwsEventName(name), name])
-);
-
-function normalizeNwsEventName(raw) {
-    if (raw == null) return '';
-    return String(raw).trim().replace(/\s+/g, ' ').toLowerCase();
-}
-
-function canonicalizeNwsEventName(raw) {
-    const normalized = normalizeNwsEventName(raw);
-    if (!normalized) return '';
-    return NWS_EVENT_CANONICAL_MAP.get(normalized) ?? String(raw).trim();
-}
-
-export function getNwsAlertEventLabelFromProperties(p) {
-    if (!p) return '';
-    const explicitEventName = canonicalizeNwsEventName(p.event_name);
-    const raw = [p.event, p.phenomenon, p.event_name].find((v) => v != null && String(v).trim() !== '');
-    if (raw == null) return '';
-    const base = canonicalizeNwsEventName(raw);
-    if (!base) return '';
-    const resolved = resolveNwsWarningCustomizationKey(base, p);
-    if (
-        resolved === base &&
-        explicitEventName &&
-        explicitEventName !== base &&
-        NWS_WARNINGS_SUBTYPE_PARENT[explicitEventName] === base
-    ) {
-        return explicitEventName;
-    }
-    return resolved;
-}
-
-function normalizeNwsRankToken(raw) {
-    if (!raw) return '';
-    if (typeof raw === 'string') return raw.trim().toLowerCase();
-    return String(raw).trim().toLowerCase();
-}
-
-function computeNwsAlertRenderPriority(properties, precomputedEventName) {
-    if (!properties) return 0;
-    const eventName = normalizeNwsRankToken(precomputedEventName ?? getNwsAlertEventLabelFromProperties(properties));
-    const severity = normalizeNwsRankToken(properties.severity);
-    const urgency = normalizeNwsRankToken(properties.urgency);
-    const certainty = normalizeNwsRankToken(properties.certainty);
-    const response = normalizeNwsRankToken(properties.response);
-    const significance = normalizeNwsRankToken(properties.significance);
-
-    let score = 0;
-    if (eventName.includes('emergency')) score += 500;
-    else if (eventName.includes('warning')) score += 400;
-    else if (eventName.includes('watch')) score += 300;
-    else if (eventName.includes('advisory')) score += 200;
-    else if (eventName.includes('statement')) score += 120;
-
-    if (significance === 'w') score += 80;
-    else if (significance === 'a') score += 60;
-    else if (significance === 'y') score += 40;
-    else if (significance === 's') score += 20;
-
-    if (severity === 'extreme') score += 100;
-    else if (severity === 'severe') score += 75;
-    else if (severity === 'moderate') score += 50;
-    else if (severity === 'minor') score += 25;
-
-    if (urgency === 'immediate') score += 60;
-    else if (urgency === 'expected') score += 40;
-    else if (urgency === 'future') score += 20;
-
-    if (certainty === 'observed') score += 40;
-    else if (certainty === 'likely') score += 28;
-    else if (certainty === 'possible') score += 16;
-    else if (certainty === 'unlikely') score += 4;
-
-    if (response === 'immediate') score += 25;
-    else if (response === 'execute') score += 15;
-
-    return score;
-}
-
-function sortWarningsFeaturesForRender(features) {
-    if (!Array.isArray(features) || features.length <= 1) return features;
-    const copy = features.slice();
-    for (let i = 0; i < copy.length; i++) {
-        const f = copy[i];
-        const props = f?.properties;
-        if (props && typeof props[NWS_RENDER_PRIORITY_PROP] !== 'number') {
-            copy[i] = {
-                ...f,
-                properties: {
-                    ...props,
-                    [NWS_RENDER_PRIORITY_PROP]: computeNwsAlertRenderPriority(props),
-                },
-            };
-        }
-    }
-    copy.sort((a, b) => {
-        const pA = a?.properties?.[NWS_RENDER_PRIORITY_PROP] ?? 0;
-        const pB = b?.properties?.[NWS_RENDER_PRIORITY_PROP] ?? 0;
-        return pA - pB;
-    });
-    return copy;
-}
-
-export function getNwsTimeProp(properties, keys) {
-    if (!properties) return null;
-    for (let i = 0; i < keys.length; i++) {
-        const v = properties[keys[i]];
-        if (v != null && v !== '') return v;
-    }
-    return null;
-}
-
-export function parseNwsTimeToUnix(value) {
-    if (value == null || value === '') return null;
-    if (typeof value === 'number') {
-        if (!Number.isFinite(value)) return null;
-        return value > 1e12 ? Math.floor(value / 1000) : Math.floor(value);
-    }
-    const s = String(value).trim();
-    if (s.includes('T') || s.includes('-')) {
-        const t = Date.parse(s);
-        if (!Number.isNaN(t)) return Math.floor(t / 1000);
-    }
-    if (s.length === 10 && /^\d{10}$/.test(s)) {
-        return Number(s);
-    }
-    if (s.length === 13 && /^\d{13}$/.test(s)) {
-        return Math.floor(Number(s) / 1000);
-    }
-    const t = Date.parse(s);
-    if (!Number.isNaN(t)) return Math.floor(t / 1000);
-    return null;
-}
-
-const NWS_START_UNIX_KEYS = ['issued_at', 'issued', 'sent', 'onset', 'effective'];
-const NWS_ACTIVE_START_UNIX_KEYS = ['onset', 'effective', 'issued_at', 'issued', 'sent'];
-
-function getNwsStartUnixForMap(properties) {
-    const startStr = getNwsTimeProp(properties, NWS_START_UNIX_KEYS);
-    return parseNwsTimeToUnix(startStr) ?? 0;
-}
-
-function getNwsActiveStartUnix(properties) {
-    const startStr = getNwsTimeProp(properties, NWS_ACTIVE_START_UNIX_KEYS);
-    return parseNwsTimeToUnix(startStr) ?? 0;
-}
-
-export function getEarliestNwsReferenceSentRaw(properties) {
-    if (!properties) return null;
-    let refs = properties.references;
-    if (typeof refs === 'string') {
-        try {
-            refs = JSON.parse(refs);
-        } catch {
-            return null;
-        }
-    }
-    if (!Array.isArray(refs) || refs.length === 0) return null;
-    let best = null;
-    for (const r of refs) {
-        if (!r || typeof r !== 'object') continue;
-        const raw = r.sent ?? r.Sent;
-        if (raw == null || raw === '') continue;
-        const s = String(raw);
-        const t = new Date(s).getTime();
-        if (Number.isNaN(t)) continue;
-        if (!best || t < best.t) best = { t, raw: s };
-    }
-    return best?.raw ?? null;
-}
-
-let nextWarningFeatureId = 1;
-
-function allocateNwsMapboxFeatureId(rawId) {
-    if (typeof rawId === 'number' && Number.isFinite(rawId) && rawId >= 0 && rawId <= Number.MAX_SAFE_INTEGER) {
-        return Math.trunc(rawId);
-    }
-    return nextWarningFeatureId++;
-}
-
-function ensureDistinctMapboxIdsOnFeatures(features) {
-    const used = new Set();
-    return features.map((f) => {
-        let id =
-            typeof f?.id === 'number' && Number.isFinite(f.id) && f.id >= 0 && f.id <= Number.MAX_SAFE_INTEGER
-                ? Math.trunc(f.id)
-                : null;
-        if (id == null) {
-            while (used.has(nextWarningFeatureId)) {
-                nextWarningFeatureId++;
-            }
-            id = nextWarningFeatureId++;
-            used.add(id);
-            return { ...f, id };
-        }
-        if (!used.has(id)) {
-            used.add(id);
-            return f;
-        }
-        while (used.has(nextWarningFeatureId)) {
-            nextWarningFeatureId++;
-        }
-        const newId = nextWarningFeatureId++;
-        used.add(newId);
-        return { ...f, id: newId };
-    });
-}
-
-export function enrichWarningsWithColors(geojson) {
-    if (!geojson?.features?.length) return geojson;
-    const features = geojson.features.map((f) => {
-        const p = f.properties || {};
-        const earliestRef = getEarliestNwsReferenceSentRaw(p);
-        const hasExplicitIssued = getNwsTimeProp(p, ['issued_at', 'issued']) != null;
-        const nwsIssuedPatch =
-            earliestRef && !hasExplicitIssued ? { _nws_issued_at: earliestRef } : null;
-
-        const eventName = getNwsAlertEventLabelFromProperties(p);
-        const renderPriority = computeNwsAlertRenderPriority(p, eventName);
-
-        const startUnix = getNwsStartUnixForMap(p);
-        const activeStartUnix = getNwsActiveStartUnix(p);
-        const endStr = getNwsTimeProp(p, [...NWS_ALERT_END_TIME_PROP_KEYS]);
-        const endUnix = parseNwsTimeToUnix(endStr) ?? 2147483647;
-
-        const mapboxFeatureId = allocateNwsMapboxFeatureId(f.id);
-
-        const hasEventName = !!eventName;
-        const eventNameUnchanged = !hasEventName || p.event_name === eventName;
-        const priorityUnchanged = p[NWS_RENDER_PRIORITY_PROP] === renderPriority;
-        const startUnchanged = p.start_unix === startUnix;
-        const activeStartUnchanged = p.active_start_unix === activeStartUnix;
-        const endUnchanged = p.end_unix === endUnix;
-        const idUnchanged = f.id === mapboxFeatureId;
-        const nwsIssuedUnchanged =
-            nwsIssuedPatch == null || String(p._nws_issued_at ?? '') === String(nwsIssuedPatch._nws_issued_at);
-
-        if (
-            eventNameUnchanged &&
-            priorityUnchanged &&
-            startUnchanged &&
-            activeStartUnchanged &&
-            endUnchanged &&
-            idUnchanged &&
-            nwsIssuedUnchanged
-        ) {
-            return f;
-        }
-        return {
-            ...f,
-            id: mapboxFeatureId,
-            properties: {
-                ...p,
-                ...(nwsIssuedPatch ?? {}),
-                ...(hasEventName ? { event_name: eventName } : {}),
-                [NWS_RENDER_PRIORITY_PROP]: renderPriority,
-                start_unix: startUnix,
-                active_start_unix: activeStartUnix,
-                end_unix: endUnix,
-            },
-        };
-    });
-    const distinctIds = ensureDistinctMapboxIdsOnFeatures(features);
-    return { type: 'FeatureCollection', features: sortWarningsFeaturesForRender(distinctIds) };
-}
-
-export function normalizeNwwsAlertId(value) {
-    if (value == null || value === '') return null;
-    const s = String(value).trim();
-    if (!s) return null;
-    const marker = '/alerts/';
-    const idx = s.indexOf(marker);
-    if (idx >= 0) {
-        const tail = s.slice(idx + marker.length).trim();
-        return tail || s;
-    }
-    return s;
-}
-
-function isNwwsVtecTimestampInstanceId(id) {
-    const parts = id.split('.');
-    if (parts.length < 5) return false;
-    const last = parts[parts.length - 1] ?? '';
-    return /^\d{8,}$/.test(last);
-}
-
-function nwwsFeatureIdLooksLikeMapboxAllocation(raw) {
-    if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 && raw <= Number.MAX_SAFE_INTEGER) {
-        return true;
-    }
-    if (typeof raw === 'string') {
-        const t = raw.trim();
-        if (t.includes('.')) return false;
-        if (/^\d+$/.test(t) && t.length <= 16) return true;
-    }
-    return false;
-}
-
-export function getNwwsApiAlertUniqueId(feature) {
-    if (!feature || typeof feature !== 'object') return null;
-    const p = feature.properties;
-    const fromProps =
-        normalizeNwwsAlertId(p?.base_alert_id) ??
-        normalizeNwwsAlertId(p?.base_alertid ?? p?.baseAlertId ?? p?.base_alertId) ??
-        normalizeNwwsAlertId(p?.alert_id ?? p?.alertId) ??
-        normalizeNwwsAlertId(p?.id);
-    if (fromProps) return fromProps;
-    const rid = feature.id;
-    if (rid == null || rid === '' || nwwsFeatureIdLooksLikeMapboxAllocation(rid)) return null;
-    return normalizeNwwsAlertId(rid);
-}
-
-function getNwwsVtecSequenceBaseFromInstanceId(fullId) {
-    const parts = String(fullId).trim().split('.');
-    if (parts.length < 5) return null;
-    return parts.slice(0, 4).join('.');
-}
-
-function getNwwsVtecSeqBaseFromFeature(feature) {
-    const p = feature?.properties;
-    if (!p) return null;
-    const pinned = p._nws_vtec_seq_base;
-    if (typeof pinned === 'string' && pinned.includes('.')) return pinned.trim();
-    const uid = getNwwsApiAlertUniqueId(feature);
-    if (uid) {
-        const fromUid = getNwwsVtecSequenceBaseFromInstanceId(uid);
-        if (fromUid) return fromUid;
-    }
-    return extractNwsVtecStableId(p);
-}
-
-export function getNwwsTrackerStatusFromProperties(properties) {
-    if (!properties) return null;
-    const raw = properties._trackerStatus ?? properties.trackerStatus ?? properties.tracker_status;
-    if (raw == null || raw === '') {
-        if (properties.is_cancelled === true) return 'cancelled';
-        return null;
-    }
-    const s = String(raw).trim().toLowerCase();
-    if (!s) return null;
-    if (s === 'canceled') return 'cancelled';
-    if (s === 'cancel') return 'cancelled';
-    if (s === 'expire') return 'expired';
-    if (s === 'upgrade') return 'upgraded';
-    if (s === 'extend' || s === 'extended' || s === 'extension' || s === 'expanded' || s === 'expansion') {
-        return 'extended';
-    }
-    if (s === 'continuation' || s === 'continued' || s === 'correction' || s === 'continue') {
-        return 'continuation';
-    }
-    return s;
-}
-
-export function isNwwsTrackerStatusTerminal(status) {
-    return status === 'cancelled' || status === 'expired';
-}
-
-/**
- * CAP references / explicit replace fields for the previous bulletin(s) in the same event chain.
- * Used so extensions/upgrades/continuations remove polygons keyed by superseded ids, not only by
- * the new feature's `base_alert_id`.
- */
-function collectNwwsReplacementReferenceIds(properties) {
-    if (!properties || typeof properties !== 'object') return [];
-    const out = [];
-    const pushRaw = (v) => {
-        if (v == null) return;
-        if (Array.isArray(v)) {
-            for (const x of v) pushRaw(x);
-            return;
-        }
-        const n = normalizeNwwsAlertId(v);
-        if (n) out.push(n);
-    };
-    pushRaw(properties._upgradedFrom ?? properties.upgradedFrom);
-    pushRaw(properties._replaces ?? properties.replaces ?? properties.replaced_alert_id ?? properties.replacedAlertId);
-    let refs = properties.references;
-    if (typeof refs === 'string') {
-        try {
-            refs = JSON.parse(refs);
-        } catch {
-            refs = null;
-        }
-    }
-    if (Array.isArray(refs)) {
-        for (const r of refs) {
-            if (typeof r === 'string') pushRaw(r);
-            else if (r && typeof r === 'object') {
-                const ro = r;
-                pushRaw(ro.identifier ?? ro.id ?? ro.alert_id ?? ro.alertId ?? ro.base_alert_id);
-            }
-        }
-    }
-    return out;
-}
-
-export function getNwsBaseAlertIdFromFeature(feature) {
-    const p = feature?.properties;
-    const base = normalizeNwwsAlertId(p?.base_alert_id ?? p?.base_alertid ?? p?.baseAlertId ?? p?.base_alertId);
-    if (base) return base;
-    const fromAlert = normalizeNwwsAlertId(p?.alert_id ?? p?.alertId ?? p?.id);
-    if (fromAlert) return fromAlert;
-    const rid = feature?.id;
-    if (rid == null || nwwsFeatureIdLooksLikeMapboxAllocation(rid)) return null;
-    return normalizeNwwsAlertId(rid);
-}
-
-export function getNwsAlertInstanceIdFromFeature(feature) {
-    return (
-        getNwwsApiAlertUniqueId(feature) ??
-        normalizeNwwsAlertId(feature?.properties?.unique_id ?? feature?.properties?.uniqueId) ??
-        getNwsBaseAlertIdFromFeature(feature)
-    );
-}
-
-export function isUsableNwwsAlertGeometry(geometry) {
-    if (geometry == null || typeof geometry !== 'object') return false;
-    const g = geometry;
-    const t = g.type;
-    if (!t || t === 'GeometryCollection') {
-        return Array.isArray(g.geometries) && g.geometries.length > 0;
-    }
-    const c = g.coordinates;
-    if (c == null) return false;
-    if (t === 'Point') return Array.isArray(c) && c.length >= 2;
-    if (t === 'LineString') return Array.isArray(c) && c.length >= 2;
-    if (t === 'MultiPoint' || t === 'MultiLineString' || t === 'Polygon') {
-        return Array.isArray(c) && c.length > 0;
-    }
-    if (t === 'MultiPolygon') {
-        return Array.isArray(c) && c.length > 0;
-    }
-    return true;
-}
-
-export function applyNwwsDeltaToCollection(data, delta) {
-    let features = [...data.features];
-    const cancelSet = new Set(delta.cancelIds);
-    const expireSet = new Set(delta.expireIds);
-    const removeIds = new Set([...expireSet, ...cancelSet]);
-
-    for (const feat of delta.upserts) {
-        if (!feat || feat.type !== 'Feature') continue;
-        const norm = normalizeNwwsHttpAlertFeature(
-            {
-                type: 'Feature',
-                id: feat.id,
-                geometry: feat.geometry,
-                properties: { ...(feat.properties ?? {}) },
-            },
-            true
-        );
-        for (const refId of collectNwwsReplacementReferenceIds(norm.properties)) {
-            removeIds.add(refId);
-        }
-    }
-
-    const replacedBaseIds = new Set();
-    // Secondary: VTEC-derived stable IDs from upserts. Used as a fallback when base_alert_id
-    // differs between the stored feature and the update (e.g. when the content hash changed but
-    // the VTEC event number did not). This handles sessions where old hash-keyed features already
-    // exist in the working collection when an update with a VTEC-keyed ID arrives.
-    const replacedVtecIds = new Set();
-    const vtecStaleSweep = new Map();
-    for (const feat of delta.upserts) {
-        if (!feat || feat.type !== 'Feature') continue;
-        const norm = normalizeNwwsHttpAlertFeature(
-            {
-                type: 'Feature',
-                id: feat.id,
-                geometry: feat.geometry,
-                properties: { ...(feat.properties ?? {}) },
-            },
-            true
-        );
-        const trackerPre = getNwwsTrackerStatusFromProperties(norm.properties);
-        if (!isNwwsTrackerStatusTerminal(trackerPre)) {
-            const uid = getNwwsApiAlertUniqueId(norm);
-            const vtecBase = uid ? getNwwsVtecSequenceBaseFromInstanceId(uid) : null;
-            if (uid && vtecBase) vtecStaleSweep.set(vtecBase, uid);
-        }
-        const baseId = getNwsBaseAlertIdFromFeature(norm);
-        if (baseId) replacedBaseIds.add(baseId);
-        const pr = norm.properties;
-        const vtecIdCap = extractNwsVtecStableId(pr);
-        if (vtecIdCap) replacedVtecIds.add(vtecIdCap);
-        else {
-            const uidForVtec = getNwwsApiAlertUniqueId(norm);
-            const vbOnly = uidForVtec ? getNwwsVtecSequenceBaseFromInstanceId(uidForVtec) : null;
-            if (vbOnly) replacedVtecIds.add(vbOnly);
-        }
-    }
-
-    const clearedGeometryByInstance = new Map();
-    const clearedMapboxIdByInstance = new Map();
-
-    if (replacedBaseIds.size > 0 || replacedVtecIds.size > 0 || vtecStaleSweep.size > 0) {
-        features = features.filter((f) => {
-            const baseId = getNwsBaseAlertIdFromFeature(f);
-            const matchesPrimary = baseId != null && replacedBaseIds.has(baseId);
-            const fp = f?.properties;
-            const vtecOnStored =
-                extractNwsVtecStableId(fp) ?? (typeof fp?._nws_vtec_seq_base === 'string' ? fp._nws_vtec_seq_base : null);
-            const matchesVtec =
-                !matchesPrimary &&
-                replacedVtecIds.size > 0 &&
-                vtecOnStored != null &&
-                replacedVtecIds.has(vtecOnStored);
-            const fid = getNwwsApiAlertUniqueId(f);
-            const seqB = getNwwsVtecSeqBaseFromFeature(f);
-            let matchesStaleInstance = false;
-            if (vtecStaleSweep.size > 0) {
-                for (const [vtecBase, newUid] of vtecStaleSweep) {
-                    if (fid) {
-                        const sameSeries = fid === vtecBase || fid.startsWith(`${vtecBase}.`);
-                        if (sameSeries && fid !== newUid) {
-                            matchesStaleInstance = true;
-                            break;
-                        }
-                    }
-                    if (!matchesStaleInstance && seqB != null && seqB === vtecBase && (fid == null || fid !== newUid)) {
-                        matchesStaleInstance = true;
-                        break;
-                    }
-                }
-            }
-            if (!matchesPrimary && !matchesVtec && !matchesStaleInstance) return true;
-            const iid = getNwsAlertInstanceIdFromFeature(f) ?? baseId;
-            if (f.geometry) clearedGeometryByInstance.set(iid, f.geometry);
-            if (f.id != null) clearedMapboxIdByInstance.set(iid, f.id);
-            return false;
-        });
-    }
-
-    for (const feat of delta.upserts) {
-        if (!feat || feat.type !== 'Feature') continue;
-        const normalizedFeat = normalizeNwwsHttpAlertFeature(
-            {
-                type: 'Feature',
-                id: feat.id,
-                geometry: feat.geometry,
-                properties: { ...(feat.properties ?? {}) },
-            },
-            true
-        );
-        const enriched = enrichWarningsWithColors({ type: 'FeatureCollection', features: [normalizedFeat] }).features[0];
-        const trackerStatus = getNwwsTrackerStatusFromProperties(enriched?.properties);
-        if (isNwwsTrackerStatusTerminal(trackerStatus)) {
-            const terminalId = getNwsBaseAlertIdFromFeature(enriched);
-            if (terminalId) removeIds.add(terminalId);
-            continue;
-        }
-        const baseId = getNwsBaseAlertIdFromFeature(enriched);
-        const instanceId = getNwsAlertInstanceIdFromFeature(enriched) ?? baseId;
-
-        const clearedGeometry = instanceId ? clearedGeometryByInstance.get(instanceId) : undefined;
-        const clearedMapboxId = instanceId ? clearedMapboxIdByInstance.get(instanceId) : undefined;
-
-        features.push({
-            ...enriched,
-            id: clearedMapboxId ?? enriched.id,
-            geometry: isUsableNwwsAlertGeometry(enriched.geometry)
-                ? enriched.geometry
-                : clearedGeometry ?? enriched.geometry,
-        });
-    }
-
-    if (removeIds.size) {
-        features = features.filter((f) => {
-            const baseId = getNwsBaseAlertIdFromFeature(f);
-            if (baseId && removeIds.has(baseId)) return false;
-            const inst = getNwsAlertInstanceIdFromFeature(f);
-            if (inst && removeIds.has(inst)) return false;
-            return true;
-        });
-    }
-
-    features = ensureDistinctMapboxIdsOnFeatures(features);
-    return { type: 'FeatureCollection', features };
-}
-
-function pushIds(target, val) {
-    if (!Array.isArray(val)) return;
-    for (const x of val) {
-        if (x == null) continue;
-        if (typeof x === 'object') {
-            const o = x;
-            const id =
-                o.base_alert_id ??
-                o.base_alertid ??
-                o.baseAlertId ??
-                o.base_alertId ??
-                o.alert_id ??
-                o.alertId ??
-                o.id;
-            const normalizedId = normalizeNwwsAlertId(id);
-            if (normalizedId) target.push(normalizedId);
-        } else if (x !== '') {
-            const normalizedId = normalizeNwwsAlertId(x);
-            if (normalizedId) target.push(normalizedId);
-        }
-    }
-}
-
-export function parseNwwsWsDelta(raw) {
-    const upserts = [];
-    const cancelIds = [];
-    const expireIds = [];
-
-    const pushSupersededIdsFromFeature = (feature) => {
-        const status = getNwwsTrackerStatusFromProperties(feature?.properties);
-        if (status === 'cancelled' || status === 'expired') return;
-
-        const p = feature?.properties ?? {};
-        const self = new Set();
-        const b = getNwsBaseAlertIdFromFeature(feature);
-        const inst = getNwsAlertInstanceIdFromFeature(feature);
-        if (b) self.add(b);
-        if (inst) self.add(inst);
-
-        for (const id of collectNwwsReplacementReferenceIds(p)) {
-            if (!self.has(id)) cancelIds.push(id);
-        }
-    };
-
-    const collectUpsertFeatures = (val) => {
-        if (!val) return;
-        const collectMaybeFeatureObject = (obj) => {
-            if (!obj || typeof obj !== 'object') return;
-            if (obj.type !== 'Feature' && obj.geometry != null && obj.properties != null && typeof obj.properties === 'object') {
-                obj = { type: 'Feature', id: obj.id, geometry: obj.geometry, properties: obj.properties };
-            }
-            if (obj.type === 'Feature') {
-                const status = getNwwsTrackerStatusFromProperties(obj?.properties);
-                const baseId = getNwsBaseAlertIdFromFeature(obj);
-                if (status === 'cancelled' && baseId) {
-                    cancelIds.push(baseId);
-                    return;
-                }
-                if (status === 'expired' && baseId) {
-                    expireIds.push(baseId);
-                    return;
-                }
-                pushSupersededIdsFromFeature(obj);
-                upserts.push(obj);
-                return;
-            }
-            if (obj.new != null) collectUpsertFeatures(obj.new);
-            if (obj.feature != null) collectUpsertFeatures(obj.feature);
-            if (obj.alert != null) collectUpsertFeatures(obj.alert);
-            if (obj.current != null) collectUpsertFeatures(obj.current);
-        };
-        if (Array.isArray(val)) {
-            for (const item of val) {
-                collectMaybeFeatureObject(item);
-            }
-            return;
-        }
-        const candidate = val;
-        if (candidate?.type === 'Feature') {
-            collectMaybeFeatureObject(candidate);
-            return;
-        }
-        if (candidate?.type === 'FeatureCollection' && Array.isArray(candidate.features)) {
-            for (const item of candidate.features) {
-                collectMaybeFeatureObject(item);
-            }
-            return;
-        }
-        if (candidate?.data != null) collectUpsertFeatures(candidate.data);
-        if (candidate?.payload != null) collectUpsertFeatures(candidate.payload);
-        if (candidate?.feature != null) collectUpsertFeatures(candidate.feature);
-        if (candidate?.features != null) collectUpsertFeatures(candidate.features);
-        if (candidate?.items != null) collectUpsertFeatures(candidate.items);
-        if (candidate?.records != null) collectUpsertFeatures(candidate.records);
-        if (candidate?.alerts != null) collectUpsertFeatures(candidate.alerts);
-        if (candidate?.upsert != null) collectUpsertFeatures(candidate.upsert);
-        if (candidate?.upserts != null) collectUpsertFeatures(candidate.upserts);
-        if (candidate?.insert != null) collectUpsertFeatures(candidate.insert);
-        if (candidate?.inserts != null) collectUpsertFeatures(candidate.inserts);
-        if (candidate?.created != null) collectUpsertFeatures(candidate.created);
-        if (candidate?.updated != null) collectUpsertFeatures(candidate.updated);
-        if (candidate?.delta != null) {
-            const deltaInner = candidate.delta;
-            collectUpsertFeatures(deltaInner?.upsert ?? deltaInner?.upserts ?? deltaInner?.features ?? deltaInner?.data);
-        }
-        if (candidate?.patch != null) collectUpsertFeatures(candidate.patch);
-    };
-
-    if (raw == null || typeof raw !== 'object') return { upserts, cancelIds, expireIds };
-    if (Array.isArray(raw)) {
-        collectUpsertFeatures(raw);
-        return { upserts, cancelIds, expireIds };
-    }
-    const msg = raw;
-    const collectBuckets = (container) => {
-        const action = container.type ?? container.action;
-
-        if (container.upsert != null) collectUpsertFeatures(container.upsert);
-        if (container.upserts != null) collectUpsertFeatures(container.upserts);
-        if (container.alert != null) collectUpsertFeatures(container.alert);
-        if (container.alerts != null) collectUpsertFeatures(container.alerts);
-        if (container.new != null) collectUpsertFeatures(container.new);
-        if (container.extended != null) collectUpsertFeatures(container.extended);
-        if (container.upgraded != null) collectUpsertFeatures(container.upgraded);
-        if (action === 'upsert' || action === 'Upsert') {
-            collectUpsertFeatures(container.features ?? container.items ?? container.data);
-        }
-        if (container.features != null && container.type !== 'FeatureCollection') {
-            collectUpsertFeatures(container.features);
-        }
-
-        if (container.cancel != null) pushIds(cancelIds, container.cancel);
-        if (container.cancels != null) pushIds(cancelIds, container.cancels);
-        if (container.cancelled != null) pushIds(cancelIds, container.cancelled);
-        if (container.canceled != null) pushIds(cancelIds, container.canceled);
-        if (action === 'cancel' || action === 'Cancel') {
-            pushIds(cancelIds, container.ids ?? container.base_alert_ids ?? container.items);
-        }
-
-        if (container.expire != null) pushIds(expireIds, container.expire);
-        if (container.expires != null) pushIds(expireIds, container.expires);
-        if (container.expired != null) pushIds(expireIds, container.expired);
-        if (action === 'expire' || action === 'Expire') {
-            pushIds(expireIds, container.ids ?? container.base_alert_ids ?? container.items);
-        }
-    };
-
-    collectBuckets(msg);
-    if (msg.diff != null && typeof msg.diff === 'object') {
-        collectBuckets(msg.diff);
-    }
-
-    return { upserts, cancelIds, expireIds };
-}
-
-export function filterNwwsTerminalStatusFeatures(fc) {
-    return {
-        type: 'FeatureCollection',
-        features: (fc.features ?? []).filter((feature) => {
-            const status = getNwwsTrackerStatusFromProperties(feature?.properties);
-            return !isNwwsTrackerStatusTerminal(status);
-        }),
-    };
-}
-
-/**
- * Legacy filter: tornado + severe-thunderstorm family only (same as pre–all-alerts SDK).
- * @param {import('geojson').FeatureCollection} fc
- */
-export function filterToConvectiveSdkEvents(fc) {
-    const out = [];
-    for (const f of fc.features ?? []) {
-        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
-        if (ev && SDK_ALLOWED_EVENT_SET.has(ev)) {
-            out.push(f);
-        }
-    }
-    return { type: 'FeatureCollection', features: out };
-}
-
-/**
- * Whether a resolved NWS `event_name` should be shown when the user chose {@link filterNwsAlertsByIncludedList}.
- * Matches exact names; also matches when the user lists a parent product (e.g. "Tornado Warning") and the feature
- * is a known subtype (e.g. "Tornado Warning (PDS)") via {@link NWS_WARNINGS_SUBTYPE_PARENT}.
- * @param {string[] | null | undefined} includedAlerts
- * @param {string} eventLabel
- */
-export function isNwsEventIncludedInAllowlist(includedAlerts, eventLabel) {
-    if (!includedAlerts?.length || !eventLabel) {
-        return false;
-    }
-    const set = new Set(
-        includedAlerts.map((x) => (x != null ? String(x).trim() : '')).filter(Boolean)
-    );
-    if (set.size === 0) {
-        return false;
-    }
-    const ev = String(eventLabel).trim();
-    if (set.has(ev)) {
-        return true;
-    }
-    const parent = NWS_WARNINGS_SUBTYPE_PARENT[ev];
-    if (parent && set.has(parent)) {
-        return true;
-    }
-    if (ev === 'Tornado Warning (Observed)' && set.has('Tornado Warning (Reported)')) {
-        return true;
-    }
-    return false;
-}
-
-/**
- * @param {import('geojson').FeatureCollection} fc
- * @param {string[]} includedAlerts
- */
-export function filterNwsAlertsByIncludedList(fc, includedAlerts) {
-    const out = [];
-    for (const f of fc.features ?? []) {
-        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
-        if (isNwsEventIncludedInAllowlist(includedAlerts, ev)) {
-            out.push(f);
-        }
-    }
-    return { type: 'FeatureCollection', features: out };
-}
-
-/**
- * @param {import('geojson').FeatureCollection} fc
- * @param {'all' | 'user'} [scope]
- * @param {string[] | undefined} [includedAlerts] - Used when `scope === 'user'`: exact NWS `event_name` strings to show.
- */
-export function filterNwsAlertsByScope(fc, scope = 'all', includedAlerts) {
-    if (scope === 'user') {
-        return filterNwsAlertsByIncludedList(fc, includedAlerts ?? []);
-    }
-    const features = (fc.features ?? []).filter((f) => {
-        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
-        return !!(ev && String(ev).trim());
-    });
-    return { type: 'FeatureCollection', features };
-}
-
-/** @deprecated Use {@link filterToConvectiveSdkEvents} or {@link filterNwsAlertsByScope} with `scope: 'user'` and an explicit `includedAlerts` list. */
-export function filterToSdkAllowedEvents(fc) {
-    return filterToConvectiveSdkEvents(fc);
-}
-
-function extractRawNwwsVtecString(properties) {
-    if (!properties) return null;
-    if (properties.vtec != null) return String(properties.vtec);
-    if (properties.VTEC != null) return String(properties.VTEC);
-    const details = properties.details;
-    if (details?.pvtec != null) return String(details.pvtec);
-    const params = properties.parameters;
-    if (params != null && typeof params === 'object' && !Array.isArray(params)) {
-        const direct = params.VTEC ?? params.vtec;
-        if (direct != null) {
-            return Array.isArray(direct) ? String(direct[0] ?? '') : String(direct);
-        }
-        for (const k of Object.keys(params)) {
-            if (String(k).toUpperCase() === 'VTEC') {
-                const x = params[k];
-                if (x != null) return Array.isArray(x) ? String(x[0] ?? '') : String(x);
-            }
-        }
-    }
-    return null;
-}
-
-function normalizeNwsChainTimeComponent(v) {
-    if (v == null || v === '') return null;
-    if (typeof v === 'number' && Number.isFinite(v)) {
-        return new Date(v > 1e12 ? v : v * 1000).toISOString();
-    }
-    const s = String(v).trim();
-    const ms = Date.parse(s);
-    if (!Number.isNaN(ms)) return new Date(ms).toISOString();
-    return s;
-}
-
-function getNwsOfficeEventIssuedChainId(properties) {
-    if (!properties) return null;
-    const office = String(properties.office ?? properties.sender_icao ?? properties.sender ?? '').trim();
-    const ev = String(properties.event ?? properties.event_name ?? '').trim();
-    const rawIssued = getNwsTimeProp(properties, ['issued', 'issued_at']);
-    if (!office || !ev || rawIssued == null || rawIssued === '') return null;
-    const issuedNorm = normalizeNwsChainTimeComponent(rawIssued);
-    if (!issuedNorm) return null;
-    return `${office}|${ev}|${issuedNorm}`;
-}
-
-/**
- * Extracts a stable VTEC-derived alert ID (e.g. "KWNS.SV.A.0108") from raw feature properties.
- * The VTEC event number is stable across CON/EXT/CAN actions for the same watch/warning,
- * unlike content-based hashes which change on every update.
- */
-function extractNwsVtecStableId(properties) {
-    const vtec = extractRawNwwsVtecString(properties);
-    if (vtec == null || vtec === '') return null;
-    const parts = String(vtec).split('.');
-    if (parts.length < 6) return null;
-    const office = parts[2]?.trim();
-    const ph = parts[3]?.trim();
-    const sig = parts[4]?.trim();
-    const seq = parts[5]?.trim();
-    if (!office || !ph || !sig || !seq) return null;
-    return `${office}.${ph}.${sig}.${seq}`;
-}
-
-function getNwsHttpAlertStableId(properties) {
-    if (!properties) return null;
-    const details = properties.details;
-    if (details && typeof details === 'object') {
-        const tr = details.tracking;
-        if (tr != null && String(tr).trim() !== '') return String(tr).trim();
-    }
-    // Same DB key as backend — use if trim drops details/hash (see API trim payloads).
-    for (const k of ['nws_stable_id', 'stable_id', 'alert_chain_id']) {
-        const v = properties[k];
-        if (v != null && String(v).trim() !== '') return String(v).trim();
-    }
-    if (properties.tracking != null && typeof properties.tracking === 'string' && String(properties.tracking).trim() !== '') {
-        return String(properties.tracking).trim();
-    }
-    // Prefer VTEC-derived ID over hash: VTEC event number is stable across all CON/EXT/UPG
-    // actions while the content hash changes on every update, causing phantom duplicates on the map.
-    const vtecId = extractNwsVtecStableId(properties);
-    if (vtecId) return vtecId;
-    const chainId = getNwsOfficeEventIssuedChainId(properties);
-    if (chainId) return chainId;
-    const h = properties.hash;
-    if (h != null && String(h).trim() !== '') return String(h).trim();
-    return null;
-}
-
-function mapHttpActionToTrackerStatus(p, forLiveStream) {
-    if (!forLiveStream) return undefined;
-    if (p.is_cancelled === true) return 'cancelled';
-    const at = String(p.action_type ?? '').trim().toLowerCase();
-    if (at === 'cancelled' || at === 'canceled') return 'cancelled';
-    if (at === 'expired') return 'expired';
-    if (at === 'upgraded') return 'upgraded';
-    if (at === 'extended' || at === 'extension') return 'extended';
-    if (at === 'updated') return 'extended';
-    if (at === 'continuation' || at === 'continued') return 'continuation';
-    if (at === 'issued' || at === 'new') return 'issued';
-    if (at === '') return 'issued';
-    return 'issued';
-}
-
-export function normalizeNwwsHttpAlertFeature(raw, forLiveStream) {
-    if (!raw || typeof raw !== 'object' || raw.type !== 'Feature') return raw;
-    const p = { ...(raw.properties ?? {}) };
-    const explicitUid =
-        normalizeNwwsAlertId(raw.id) ?? normalizeNwwsAlertId(p.id) ?? normalizeNwwsAlertId(p.alert_id ?? p.alertId);
-    if (explicitUid && isNwwsVtecTimestampInstanceId(explicitUid)) {
-        p.base_alert_id = explicitUid;
-        p.alert_id = explicitUid;
-        const vb = getNwwsVtecSequenceBaseFromInstanceId(explicitUid);
-        if (vb) p._nws_vtec_seq_base = vb;
-    } else {
-        const stableId = getNwsHttpAlertStableId(p);
-        if (stableId) {
-            p.base_alert_id = stableId;
-            p.alert_id = stableId;
-        } else {
-            const fallback =
-                normalizeNwwsAlertId(raw.id) ?? normalizeNwwsAlertId(p.id) ?? normalizeNwwsAlertId(p.alert_id ?? p.alertId);
-            if (fallback) {
-                p.base_alert_id = fallback;
-                p.alert_id = fallback;
-            } else {
-                const chain = getNwsOfficeEventIssuedChainId(p);
-                if (chain) {
-                    p.base_alert_id = chain;
-                    p.alert_id = chain;
-                }
-            }
-        }
-    }
-    const tracker = mapHttpActionToTrackerStatus(p, forLiveStream);
-    if (tracker !== undefined) {
-        p._trackerStatus = tracker;
-    }
-    if (p._nws_vtec_seq_base == null) {
-        const capV = extractNwsVtecStableId(p);
-        if (capV) p._nws_vtec_seq_base = capV;
-    }
-    return { ...raw, properties: p };
-}
-
-export function unwrapNwwsFeatureCollectionRoot(parsed) {
-    if (Array.isArray(parsed)) {
-        return {
-            type: 'FeatureCollection',
-            features: parsed.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
-        };
-    }
-    if (!parsed || typeof parsed !== 'object') return null;
-    const o = parsed;
-    if (o.type === 'FeatureCollection' && Array.isArray(o.features)) {
-        return {
-            type: 'FeatureCollection',
-            features: o.features.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
-        };
-    }
-    for (const key of ['geojson', 'data', 'payload', 'body', 'collection', 'result', 'message', 'record']) {
-        const inner = o[key];
-        if (
-            inner &&
-            typeof inner === 'object' &&
-            inner.type === 'FeatureCollection' &&
-            Array.isArray(inner.features)
-        ) {
-            return {
-                type: 'FeatureCollection',
-                features: inner.features.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
-            };
-        }
-    }
-    return null;
-}
-
-export function cloneNwwsFeatureCollectionStrippingVolatile(data) {
-    return {
-        type: 'FeatureCollection',
-        features: (data.features || []).flatMap((f) => {
-            const p = f?.properties;
-            if (p) {
-                const ex = p.nwws_expired;
-                if (ex === true || ex === 1 || String(ex).toLowerCase() === 'true') {
-                    return [];
-                }
-            }
-            const copy = {
-                ...f,
-                properties: p ? { ...p } : {},
-            };
-            delete copy._lastActiveState;
-            if (copy.properties && 'nwws_expired' in copy.properties) {
-                delete copy.properties.nwws_expired;
-            }
-            if (copy.properties) {
-                delete copy.properties._nws_flash_until_unix;
-                delete copy.properties._nws_webhook_debug_flash;
-            }
-            return [copy];
-        }),
-    };
-}
-
-export function buildAlertClickPayload(feature) {
-    const properties = feature?.properties ? { ...feature.properties } : {};
-    const eventName = getNwsAlertEventLabelFromProperties(properties);
-    let tags = properties.tags;
-    if (typeof tags === 'string') {
-        try {
-            tags = JSON.parse(tags);
-        } catch {
-            tags = null;
-        }
-    }
-    if (!Array.isArray(tags)) {
-        tags = tags != null ? [String(tags)] : [];
-    }
-    const headline = properties.headline != null ? String(properties.headline) : '';
-    const name =
-        headline ||
-        eventName ||
-        (properties.event != null ? String(properties.event) : '') ||
-        (properties.event_name != null ? String(properties.event_name) : '');
-    const description =
-        properties.description != null
-            ? String(properties.description)
-            : properties.raw_text != null
-              ? String(properties.raw_text)
-              : '';
-    const summary = properties.summary != null ? String(properties.summary) : '';
-    const instruction = properties.instruction != null ? String(properties.instruction) : '';
-
-    const startUnix =
-        typeof properties.start_unix === 'number'
-            ? properties.start_unix
-            : getNwsStartUnixForMap(properties);
-    const endUnix =
-        typeof properties.end_unix === 'number'
-            ? properties.end_unix
-            : parseNwsTimeToUnix(getNwsTimeProp(properties, [...NWS_ALERT_END_TIME_PROP_KEYS]));
-    const activeStartUnix =
-        typeof properties.active_start_unix === 'number'
-            ? properties.active_start_unix
-            : getNwsActiveStartUnix(properties);
-
-    return {
-        name,
-        eventName,
-        headline,
-        summary,
-        description,
-        instruction,
-        tags,
-        startUnix,
-        endUnix,
-        activeStartUnix,
-        properties,
-    };
-}
+/**
+ * NWWS HTTP + SSE merge pipeline (subset of aguacero-frontend WatchesWarningsLayer).
+ */
+
+import { resolveNwsWarningCustomizationKey } from './nwsWarningCustomizationKey.gen.js';
+import { NWS_ALERT_END_TIME_PROP_KEYS, NWS_WARNINGS_SUBTYPE_PARENT } from './nwsSdkConstants.js';
+
+export const NWS_RENDER_PRIORITY_PROP = '_nws_render_priority';
+
+export const SDK_ALLOWED_EVENT_SET = new Set([
+    'Tornado Watch',
+    'Tornado Warning',
+    'Tornado Warning (Observed)',
+    'Tornado Warning (PDS)',
+    'Tornado Warning (Emergency)',
+    'Severe Thunderstorm Watch',
+    'Severe Thunderstorm Warning',
+    'Severe Thunderstorm Warning (Considerable)',
+    'Severe Thunderstorm Warning (Destructive)',
+]);
+
+const NWS_EVENT_CANONICAL_MAP = new Map(
+    [...SDK_ALLOWED_EVENT_SET].map((name) => [normalizeNwsEventName(name), name])
+);
+
+function normalizeNwsEventName(raw) {
+    if (raw == null) return '';
+    return String(raw).trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function canonicalizeNwsEventName(raw) {
+    const normalized = normalizeNwsEventName(raw);
+    if (!normalized) return '';
+    return NWS_EVENT_CANONICAL_MAP.get(normalized) ?? String(raw).trim();
+}
+
+export function getNwsAlertEventLabelFromProperties(p) {
+    if (!p) return '';
+    const explicitEventName = canonicalizeNwsEventName(p.event_name);
+    const raw = [p.event, p.phenomenon, p.event_name].find((v) => v != null && String(v).trim() !== '');
+    if (raw == null) return '';
+    const base = canonicalizeNwsEventName(raw);
+    if (!base) return '';
+    const resolved = resolveNwsWarningCustomizationKey(base, p);
+    if (
+        resolved === base &&
+        explicitEventName &&
+        explicitEventName !== base &&
+        NWS_WARNINGS_SUBTYPE_PARENT[explicitEventName] === base
+    ) {
+        return explicitEventName;
+    }
+    return resolved;
+}
+
+function normalizeNwsRankToken(raw) {
+    if (!raw) return '';
+    if (typeof raw === 'string') return raw.trim().toLowerCase();
+    return String(raw).trim().toLowerCase();
+}
+
+function computeNwsAlertRenderPriority(properties, precomputedEventName) {
+    if (!properties) return 0;
+    const eventName = normalizeNwsRankToken(precomputedEventName ?? getNwsAlertEventLabelFromProperties(properties));
+    const severity = normalizeNwsRankToken(properties.severity);
+    const urgency = normalizeNwsRankToken(properties.urgency);
+    const certainty = normalizeNwsRankToken(properties.certainty);
+    const response = normalizeNwsRankToken(properties.response);
+    const significance = normalizeNwsRankToken(properties.significance);
+
+    let score = 0;
+    if (eventName.includes('emergency')) score += 500;
+    else if (eventName.includes('warning')) score += 400;
+    else if (eventName.includes('watch')) score += 300;
+    else if (eventName.includes('advisory')) score += 200;
+    else if (eventName.includes('statement')) score += 120;
+
+    if (significance === 'w') score += 80;
+    else if (significance === 'a') score += 60;
+    else if (significance === 'y') score += 40;
+    else if (significance === 's') score += 20;
+
+    if (severity === 'extreme') score += 100;
+    else if (severity === 'severe') score += 75;
+    else if (severity === 'moderate') score += 50;
+    else if (severity === 'minor') score += 25;
+
+    if (urgency === 'immediate') score += 60;
+    else if (urgency === 'expected') score += 40;
+    else if (urgency === 'future') score += 20;
+
+    if (certainty === 'observed') score += 40;
+    else if (certainty === 'likely') score += 28;
+    else if (certainty === 'possible') score += 16;
+    else if (certainty === 'unlikely') score += 4;
+
+    if (response === 'immediate') score += 25;
+    else if (response === 'execute') score += 15;
+
+    return score;
+}
+
+function sortWarningsFeaturesForRender(features) {
+    if (!Array.isArray(features) || features.length <= 1) return features;
+    const copy = features.slice();
+    for (let i = 0; i < copy.length; i++) {
+        const f = copy[i];
+        const props = f?.properties;
+        if (props && typeof props[NWS_RENDER_PRIORITY_PROP] !== 'number') {
+            copy[i] = {
+                ...f,
+                properties: {
+                    ...props,
+                    [NWS_RENDER_PRIORITY_PROP]: computeNwsAlertRenderPriority(props),
+                },
+            };
+        }
+    }
+    copy.sort((a, b) => {
+        const pA = a?.properties?.[NWS_RENDER_PRIORITY_PROP] ?? 0;
+        const pB = b?.properties?.[NWS_RENDER_PRIORITY_PROP] ?? 0;
+        return pA - pB;
+    });
+    return copy;
+}
+
+export function getNwsTimeProp(properties, keys) {
+    if (!properties) return null;
+    for (let i = 0; i < keys.length; i++) {
+        const v = properties[keys[i]];
+        if (v != null && v !== '') return v;
+    }
+    return null;
+}
+
+export function parseNwsTimeToUnix(value) {
+    if (value == null || value === '') return null;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) return null;
+        return value > 1e12 ? Math.floor(value / 1000) : Math.floor(value);
+    }
+    const s = String(value).trim();
+    if (s.includes('T') || s.includes('-')) {
+        const t = Date.parse(s);
+        if (!Number.isNaN(t)) return Math.floor(t / 1000);
+    }
+    if (s.length === 10 && /^\d{10}$/.test(s)) {
+        return Number(s);
+    }
+    if (s.length === 13 && /^\d{13}$/.test(s)) {
+        return Math.floor(Number(s) / 1000);
+    }
+    const t = Date.parse(s);
+    if (!Number.isNaN(t)) return Math.floor(t / 1000);
+    return null;
+}
+
+const NWS_START_UNIX_KEYS = ['issued_at', 'issued', 'sent', 'onset', 'effective'];
+const NWS_ACTIVE_START_UNIX_KEYS = ['onset', 'effective', 'issued_at', 'issued', 'sent'];
+
+function getNwsStartUnixForMap(properties) {
+    const startStr = getNwsTimeProp(properties, NWS_START_UNIX_KEYS);
+    return parseNwsTimeToUnix(startStr) ?? 0;
+}
+
+function getNwsActiveStartUnix(properties) {
+    const startStr = getNwsTimeProp(properties, NWS_ACTIVE_START_UNIX_KEYS);
+    return parseNwsTimeToUnix(startStr) ?? 0;
+}
+
+export function getEarliestNwsReferenceSentRaw(properties) {
+    if (!properties) return null;
+    let refs = properties.references;
+    if (typeof refs === 'string') {
+        try {
+            refs = JSON.parse(refs);
+        } catch {
+            return null;
+        }
+    }
+    if (!Array.isArray(refs) || refs.length === 0) return null;
+    let best = null;
+    for (const r of refs) {
+        if (!r || typeof r !== 'object') continue;
+        const raw = r.sent ?? r.Sent;
+        if (raw == null || raw === '') continue;
+        const s = String(raw);
+        const t = new Date(s).getTime();
+        if (Number.isNaN(t)) continue;
+        if (!best || t < best.t) best = { t, raw: s };
+    }
+    return best?.raw ?? null;
+}
+
+let nextWarningFeatureId = 1;
+
+function allocateNwsMapboxFeatureId(rawId) {
+    if (typeof rawId === 'number' && Number.isFinite(rawId) && rawId >= 0 && rawId <= Number.MAX_SAFE_INTEGER) {
+        return Math.trunc(rawId);
+    }
+    return nextWarningFeatureId++;
+}
+
+function ensureDistinctMapboxIdsOnFeatures(features) {
+    const used = new Set();
+    return features.map((f) => {
+        let id =
+            typeof f?.id === 'number' && Number.isFinite(f.id) && f.id >= 0 && f.id <= Number.MAX_SAFE_INTEGER
+                ? Math.trunc(f.id)
+                : null;
+        if (id == null) {
+            while (used.has(nextWarningFeatureId)) {
+                nextWarningFeatureId++;
+            }
+            id = nextWarningFeatureId++;
+            used.add(id);
+            return { ...f, id };
+        }
+        if (!used.has(id)) {
+            used.add(id);
+            return f;
+        }
+        while (used.has(nextWarningFeatureId)) {
+            nextWarningFeatureId++;
+        }
+        const newId = nextWarningFeatureId++;
+        used.add(newId);
+        return { ...f, id: newId };
+    });
+}
+
+export function enrichWarningsWithColors(geojson) {
+    if (!geojson || typeof geojson !== 'object') {
+        return { type: 'FeatureCollection', features: [] };
+    }
+    const rawFeats = geojson.features;
+    if (!Array.isArray(rawFeats) || rawFeats.length === 0) {
+        return { type: 'FeatureCollection', features: [] };
+    }
+    const features = rawFeats.map((f) => {
+        const p = f.properties || {};
+        const earliestRef = getEarliestNwsReferenceSentRaw(p);
+        const hasExplicitIssued = getNwsTimeProp(p, ['issued_at', 'issued']) != null;
+        const nwsIssuedPatch =
+            earliestRef && !hasExplicitIssued ? { _nws_issued_at: earliestRef } : null;
+
+        const eventName = getNwsAlertEventLabelFromProperties(p);
+        const renderPriority = computeNwsAlertRenderPriority(p, eventName);
+
+        const startUnix = getNwsStartUnixForMap(p);
+        const activeStartUnix = getNwsActiveStartUnix(p);
+        const endStr = getNwsTimeProp(p, [...NWS_ALERT_END_TIME_PROP_KEYS]);
+        const endUnix = parseNwsTimeToUnix(endStr) ?? 2147483647;
+
+        const mapboxFeatureId = allocateNwsMapboxFeatureId(f.id);
+
+        const hasEventName = !!eventName;
+        const eventNameUnchanged = !hasEventName || p.event_name === eventName;
+        const priorityUnchanged = p[NWS_RENDER_PRIORITY_PROP] === renderPriority;
+        const startUnchanged = p.start_unix === startUnix;
+        const activeStartUnchanged = p.active_start_unix === activeStartUnix;
+        const endUnchanged = p.end_unix === endUnix;
+        const idUnchanged = f.id === mapboxFeatureId;
+        const nwsIssuedUnchanged =
+            nwsIssuedPatch == null || String(p._nws_issued_at ?? '') === String(nwsIssuedPatch._nws_issued_at);
+
+        if (
+            eventNameUnchanged &&
+            priorityUnchanged &&
+            startUnchanged &&
+            activeStartUnchanged &&
+            endUnchanged &&
+            idUnchanged &&
+            nwsIssuedUnchanged
+        ) {
+            return f;
+        }
+        return {
+            ...f,
+            id: mapboxFeatureId,
+            properties: {
+                ...p,
+                ...(nwsIssuedPatch ?? {}),
+                ...(hasEventName ? { event_name: eventName } : {}),
+                [NWS_RENDER_PRIORITY_PROP]: renderPriority,
+                start_unix: startUnix,
+                active_start_unix: activeStartUnix,
+                end_unix: endUnix,
+            },
+        };
+    });
+    const distinctIds = ensureDistinctMapboxIdsOnFeatures(features);
+    return { type: 'FeatureCollection', features: sortWarningsFeaturesForRender(distinctIds) };
+}
+
+export function normalizeNwwsAlertId(value) {
+    if (value == null || value === '') return null;
+    const s = String(value).trim();
+    if (!s) return null;
+    const marker = '/alerts/';
+    const idx = s.indexOf(marker);
+    if (idx >= 0) {
+        const tail = s.slice(idx + marker.length).trim();
+        return tail || s;
+    }
+    return s;
+}
+
+function isNwwsVtecTimestampInstanceId(id) {
+    const parts = id.split('.');
+    if (parts.length < 5) return false;
+    const last = parts[parts.length - 1] ?? '';
+    return /^\d{8,}$/.test(last);
+}
+
+function nwwsFeatureIdLooksLikeMapboxAllocation(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 && raw <= Number.MAX_SAFE_INTEGER) {
+        return true;
+    }
+    if (typeof raw === 'string') {
+        const t = raw.trim();
+        if (t.includes('.')) return false;
+        if (/^\d+$/.test(t) && t.length <= 16) return true;
+    }
+    return false;
+}
+
+export function getNwwsApiAlertUniqueId(feature) {
+    if (!feature || typeof feature !== 'object') return null;
+    const p = feature.properties;
+    const fromProps =
+        normalizeNwwsAlertId(p?.base_alert_id) ??
+        normalizeNwwsAlertId(p?.base_alertid ?? p?.baseAlertId ?? p?.base_alertId) ??
+        normalizeNwwsAlertId(p?.alert_id ?? p?.alertId) ??
+        normalizeNwwsAlertId(p?.id);
+    if (fromProps) return fromProps;
+    const rid = feature.id;
+    if (rid == null || rid === '' || nwwsFeatureIdLooksLikeMapboxAllocation(rid)) return null;
+    return normalizeNwwsAlertId(rid);
+}
+
+function getNwwsVtecSequenceBaseFromInstanceId(fullId) {
+    const parts = String(fullId).trim().split('.');
+    if (parts.length < 5) return null;
+    return parts.slice(0, 4).join('.');
+}
+
+function getNwwsVtecSeqBaseFromFeature(feature) {
+    const p = feature?.properties;
+    if (!p) return null;
+    const pinned = p._nws_vtec_seq_base;
+    if (typeof pinned === 'string' && pinned.includes('.')) return pinned.trim();
+    const uid = getNwwsApiAlertUniqueId(feature);
+    if (uid) {
+        const fromUid = getNwwsVtecSequenceBaseFromInstanceId(uid);
+        if (fromUid) return fromUid;
+    }
+    return extractNwsVtecStableId(p);
+}
+
+export function getNwwsTrackerStatusFromProperties(properties) {
+    if (!properties) return null;
+    const raw = properties._trackerStatus ?? properties.trackerStatus ?? properties.tracker_status;
+    if (raw == null || raw === '') {
+        if (properties.is_cancelled === true) return 'cancelled';
+        return null;
+    }
+    const s = String(raw).trim().toLowerCase();
+    if (!s) return null;
+    if (s === 'canceled') return 'cancelled';
+    if (s === 'cancel') return 'cancelled';
+    if (s === 'expire') return 'expired';
+    if (s === 'upgrade') return 'upgraded';
+    if (s === 'extend' || s === 'extended' || s === 'extension' || s === 'expanded' || s === 'expansion') {
+        return 'extended';
+    }
+    if (s === 'continuation' || s === 'continued' || s === 'correction' || s === 'continue') {
+        return 'continuation';
+    }
+    return s;
+}
+
+export function isNwwsTrackerStatusTerminal(status) {
+    return status === 'cancelled' || status === 'expired';
+}
+
+/**
+ * CAP references / explicit replace fields for the previous bulletin(s) in the same event chain.
+ * Used so extensions/upgrades/continuations remove polygons keyed by superseded ids, not only by
+ * the new feature's `base_alert_id`.
+ */
+function collectNwwsReplacementReferenceIds(properties) {
+    if (!properties || typeof properties !== 'object') return [];
+    const out = [];
+    const pushRaw = (v) => {
+        if (v == null) return;
+        if (Array.isArray(v)) {
+            for (const x of v) pushRaw(x);
+            return;
+        }
+        const n = normalizeNwwsAlertId(v);
+        if (n) out.push(n);
+    };
+    pushRaw(properties._upgradedFrom ?? properties.upgradedFrom);
+    pushRaw(properties._replaces ?? properties.replaces ?? properties.replaced_alert_id ?? properties.replacedAlertId);
+    let refs = properties.references;
+    if (typeof refs === 'string') {
+        try {
+            refs = JSON.parse(refs);
+        } catch {
+            refs = null;
+        }
+    }
+    if (Array.isArray(refs)) {
+        for (const r of refs) {
+            if (typeof r === 'string') pushRaw(r);
+            else if (r && typeof r === 'object') {
+                const ro = r;
+                pushRaw(ro.identifier ?? ro.id ?? ro.alert_id ?? ro.alertId ?? ro.base_alert_id);
+            }
+        }
+    }
+    return out;
+}
+
+export function getNwsBaseAlertIdFromFeature(feature) {
+    const p = feature?.properties;
+    const base = normalizeNwwsAlertId(p?.base_alert_id ?? p?.base_alertid ?? p?.baseAlertId ?? p?.base_alertId);
+    if (base) return base;
+    const fromAlert = normalizeNwwsAlertId(p?.alert_id ?? p?.alertId ?? p?.id);
+    if (fromAlert) return fromAlert;
+    const rid = feature?.id;
+    if (rid == null || nwwsFeatureIdLooksLikeMapboxAllocation(rid)) return null;
+    return normalizeNwwsAlertId(rid);
+}
+
+export function getNwsAlertInstanceIdFromFeature(feature) {
+    return (
+        getNwwsApiAlertUniqueId(feature) ??
+        normalizeNwwsAlertId(feature?.properties?.unique_id ?? feature?.properties?.uniqueId) ??
+        getNwsBaseAlertIdFromFeature(feature)
+    );
+}
+
+export function isUsableNwwsAlertGeometry(geometry) {
+    if (geometry == null || typeof geometry !== 'object') return false;
+    const g = geometry;
+    const t = g.type;
+    if (t === 'GeometryCollection') {
+        const geoms = g.geometries;
+        return (
+            Array.isArray(geoms) &&
+            geoms.length > 0 &&
+            geoms.some((sub) => isUsableNwwsAlertGeometry(sub))
+        );
+    }
+    if (!t) return false;
+    const c = g.coordinates;
+    if (c == null) return false;
+    if (t === 'Point') return Array.isArray(c) && c.length >= 2;
+    if (t === 'LineString') return Array.isArray(c) && c.length >= 2;
+    if (t === 'MultiPoint' || t === 'MultiLineString' || t === 'Polygon') {
+        return Array.isArray(c) && c.length > 0;
+    }
+    if (t === 'MultiPolygon') {
+        return Array.isArray(c) && c.length > 0;
+    }
+    return true;
+}
+
+/** Empty collection safe for Mapbox GL `geojson` sources (never pass `features: null`). */
+export const EMPTY_FEATURE_COLLECTION = Object.freeze({
+    type: 'FeatureCollection',
+    features: [],
+});
+
+/**
+ * Coerces input into a FeatureCollection Mapbox can load without worker errors
+ * (null `features`, invalid nested GeometryCollections, or null coordinates).
+ */
+export function normalizeFeatureCollectionForMapboxGl(input) {
+    if (!input || typeof input !== 'object' || input.type !== 'FeatureCollection') {
+        return { type: 'FeatureCollection', features: [] };
+    }
+    const raw = input.features;
+    if (!Array.isArray(raw)) {
+        return { type: 'FeatureCollection', features: [] };
+    }
+    const out = [];
+    for (const f of raw) {
+        if (!f || typeof f !== 'object' || f.type !== 'Feature') continue;
+        if (!isUsableNwwsAlertGeometry(f.geometry)) continue;
+        out.push(f);
+    }
+    return { type: 'FeatureCollection', features: out };
+}
+
+export function applyNwwsDeltaToCollection(data, delta) {
+    const base = normalizeFeatureCollectionForMapboxGl(data);
+    let features = [...base.features];
+    const cancelSet = new Set(delta.cancelIds);
+    const expireSet = new Set(delta.expireIds);
+    const removeIds = new Set([...expireSet, ...cancelSet]);
+
+    for (const feat of delta.upserts) {
+        if (!feat || feat.type !== 'Feature') continue;
+        const norm = normalizeNwwsHttpAlertFeature(
+            {
+                type: 'Feature',
+                id: feat.id,
+                geometry: feat.geometry,
+                properties: { ...(feat.properties ?? {}) },
+            },
+            true
+        );
+        for (const refId of collectNwwsReplacementReferenceIds(norm.properties)) {
+            removeIds.add(refId);
+        }
+    }
+
+    const replacedBaseIds = new Set();
+    // Secondary: VTEC-derived stable IDs from upserts. Used as a fallback when base_alert_id
+    // differs between the stored feature and the update (e.g. when the content hash changed but
+    // the VTEC event number did not). This handles sessions where old hash-keyed features already
+    // exist in the working collection when an update with a VTEC-keyed ID arrives.
+    const replacedVtecIds = new Set();
+    const vtecStaleSweep = new Map();
+    for (const feat of delta.upserts) {
+        if (!feat || feat.type !== 'Feature') continue;
+        const norm = normalizeNwwsHttpAlertFeature(
+            {
+                type: 'Feature',
+                id: feat.id,
+                geometry: feat.geometry,
+                properties: { ...(feat.properties ?? {}) },
+            },
+            true
+        );
+        const trackerPre = getNwwsTrackerStatusFromProperties(norm.properties);
+        if (!isNwwsTrackerStatusTerminal(trackerPre)) {
+            const uid = getNwwsApiAlertUniqueId(norm);
+            const vtecBase = uid ? getNwwsVtecSequenceBaseFromInstanceId(uid) : null;
+            if (uid && vtecBase) vtecStaleSweep.set(vtecBase, uid);
+        }
+        const baseId = getNwsBaseAlertIdFromFeature(norm);
+        if (baseId) replacedBaseIds.add(baseId);
+        const pr = norm.properties;
+        const vtecIdCap = extractNwsVtecStableId(pr);
+        if (vtecIdCap) replacedVtecIds.add(vtecIdCap);
+        else {
+            const uidForVtec = getNwwsApiAlertUniqueId(norm);
+            const vbOnly = uidForVtec ? getNwwsVtecSequenceBaseFromInstanceId(uidForVtec) : null;
+            if (vbOnly) replacedVtecIds.add(vbOnly);
+        }
+    }
+
+    const clearedGeometryByInstance = new Map();
+    const clearedMapboxIdByInstance = new Map();
+
+    if (replacedBaseIds.size > 0 || replacedVtecIds.size > 0 || vtecStaleSweep.size > 0) {
+        features = features.filter((f) => {
+            const baseId = getNwsBaseAlertIdFromFeature(f);
+            const matchesPrimary = baseId != null && replacedBaseIds.has(baseId);
+            const fp = f?.properties;
+            const vtecOnStored =
+                extractNwsVtecStableId(fp) ?? (typeof fp?._nws_vtec_seq_base === 'string' ? fp._nws_vtec_seq_base : null);
+            const matchesVtec =
+                !matchesPrimary &&
+                replacedVtecIds.size > 0 &&
+                vtecOnStored != null &&
+                replacedVtecIds.has(vtecOnStored);
+            const fid = getNwwsApiAlertUniqueId(f);
+            const seqB = getNwwsVtecSeqBaseFromFeature(f);
+            let matchesStaleInstance = false;
+            if (vtecStaleSweep.size > 0) {
+                for (const [vtecBase, newUid] of vtecStaleSweep) {
+                    if (fid) {
+                        const sameSeries = fid === vtecBase || fid.startsWith(`${vtecBase}.`);
+                        if (sameSeries && fid !== newUid) {
+                            matchesStaleInstance = true;
+                            break;
+                        }
+                    }
+                    if (!matchesStaleInstance && seqB != null && seqB === vtecBase && (fid == null || fid !== newUid)) {
+                        matchesStaleInstance = true;
+                        break;
+                    }
+                }
+            }
+            if (!matchesPrimary && !matchesVtec && !matchesStaleInstance) return true;
+            const iid = getNwsAlertInstanceIdFromFeature(f) ?? baseId;
+            if (f.geometry) clearedGeometryByInstance.set(iid, f.geometry);
+            if (f.id != null) clearedMapboxIdByInstance.set(iid, f.id);
+            return false;
+        });
+    }
+
+    for (const feat of delta.upserts) {
+        if (!feat || feat.type !== 'Feature') continue;
+        const normalizedFeat = normalizeNwwsHttpAlertFeature(
+            {
+                type: 'Feature',
+                id: feat.id,
+                geometry: feat.geometry,
+                properties: { ...(feat.properties ?? {}) },
+            },
+            true
+        );
+        const enriched = enrichWarningsWithColors({ type: 'FeatureCollection', features: [normalizedFeat] }).features[0];
+        const trackerStatus = getNwwsTrackerStatusFromProperties(enriched?.properties);
+        if (isNwwsTrackerStatusTerminal(trackerStatus)) {
+            const terminalId = getNwsBaseAlertIdFromFeature(enriched);
+            if (terminalId) removeIds.add(terminalId);
+            continue;
+        }
+        const baseId = getNwsBaseAlertIdFromFeature(enriched);
+        const instanceId = getNwsAlertInstanceIdFromFeature(enriched) ?? baseId;
+
+        const clearedGeometry = instanceId ? clearedGeometryByInstance.get(instanceId) : undefined;
+        const clearedMapboxId = instanceId ? clearedMapboxIdByInstance.get(instanceId) : undefined;
+
+        features.push({
+            ...enriched,
+            id: clearedMapboxId ?? enriched.id,
+            geometry: isUsableNwwsAlertGeometry(enriched.geometry)
+                ? enriched.geometry
+                : clearedGeometry ?? enriched.geometry,
+        });
+    }
+
+    if (removeIds.size) {
+        features = features.filter((f) => {
+            const baseId = getNwsBaseAlertIdFromFeature(f);
+            if (baseId && removeIds.has(baseId)) return false;
+            const inst = getNwsAlertInstanceIdFromFeature(f);
+            if (inst && removeIds.has(inst)) return false;
+            return true;
+        });
+    }
+
+    features = ensureDistinctMapboxIdsOnFeatures(features);
+    return normalizeFeatureCollectionForMapboxGl({ type: 'FeatureCollection', features });
+}
+
+function pushIds(target, val) {
+    if (!Array.isArray(val)) return;
+    for (const x of val) {
+        if (x == null) continue;
+        if (typeof x === 'object') {
+            const o = x;
+            const id =
+                o.base_alert_id ??
+                o.base_alertid ??
+                o.baseAlertId ??
+                o.base_alertId ??
+                o.alert_id ??
+                o.alertId ??
+                o.id;
+            const normalizedId = normalizeNwwsAlertId(id);
+            if (normalizedId) target.push(normalizedId);
+        } else if (x !== '') {
+            const normalizedId = normalizeNwwsAlertId(x);
+            if (normalizedId) target.push(normalizedId);
+        }
+    }
+}
+
+export function parseNwwsWsDelta(raw) {
+    const upserts = [];
+    const cancelIds = [];
+    const expireIds = [];
+
+    const pushSupersededIdsFromFeature = (feature) => {
+        const status = getNwwsTrackerStatusFromProperties(feature?.properties);
+        if (status === 'cancelled' || status === 'expired') return;
+
+        const p = feature?.properties ?? {};
+        const self = new Set();
+        const b = getNwsBaseAlertIdFromFeature(feature);
+        const inst = getNwsAlertInstanceIdFromFeature(feature);
+        if (b) self.add(b);
+        if (inst) self.add(inst);
+
+        for (const id of collectNwwsReplacementReferenceIds(p)) {
+            if (!self.has(id)) cancelIds.push(id);
+        }
+    };
+
+    const collectUpsertFeatures = (val) => {
+        if (!val) return;
+        const collectMaybeFeatureObject = (obj) => {
+            if (!obj || typeof obj !== 'object') return;
+            if (obj.type !== 'Feature' && obj.geometry != null && obj.properties != null && typeof obj.properties === 'object') {
+                obj = { type: 'Feature', id: obj.id, geometry: obj.geometry, properties: obj.properties };
+            }
+            if (obj.type === 'Feature') {
+                const status = getNwwsTrackerStatusFromProperties(obj?.properties);
+                const baseId = getNwsBaseAlertIdFromFeature(obj);
+                if (status === 'cancelled' && baseId) {
+                    cancelIds.push(baseId);
+                    return;
+                }
+                if (status === 'expired' && baseId) {
+                    expireIds.push(baseId);
+                    return;
+                }
+                pushSupersededIdsFromFeature(obj);
+                upserts.push(obj);
+                return;
+            }
+            if (obj.new != null) collectUpsertFeatures(obj.new);
+            if (obj.feature != null) collectUpsertFeatures(obj.feature);
+            if (obj.alert != null) collectUpsertFeatures(obj.alert);
+            if (obj.current != null) collectUpsertFeatures(obj.current);
+        };
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                collectMaybeFeatureObject(item);
+            }
+            return;
+        }
+        const candidate = val;
+        if (candidate?.type === 'Feature') {
+            collectMaybeFeatureObject(candidate);
+            return;
+        }
+        if (candidate?.type === 'FeatureCollection' && Array.isArray(candidate.features)) {
+            for (const item of candidate.features) {
+                collectMaybeFeatureObject(item);
+            }
+            return;
+        }
+        if (candidate?.data != null) collectUpsertFeatures(candidate.data);
+        if (candidate?.payload != null) collectUpsertFeatures(candidate.payload);
+        if (candidate?.feature != null) collectUpsertFeatures(candidate.feature);
+        if (candidate?.features != null) collectUpsertFeatures(candidate.features);
+        if (candidate?.items != null) collectUpsertFeatures(candidate.items);
+        if (candidate?.records != null) collectUpsertFeatures(candidate.records);
+        if (candidate?.alerts != null) collectUpsertFeatures(candidate.alerts);
+        if (candidate?.upsert != null) collectUpsertFeatures(candidate.upsert);
+        if (candidate?.upserts != null) collectUpsertFeatures(candidate.upserts);
+        if (candidate?.insert != null) collectUpsertFeatures(candidate.insert);
+        if (candidate?.inserts != null) collectUpsertFeatures(candidate.inserts);
+        if (candidate?.created != null) collectUpsertFeatures(candidate.created);
+        if (candidate?.updated != null) collectUpsertFeatures(candidate.updated);
+        if (candidate?.delta != null) {
+            const deltaInner = candidate.delta;
+            collectUpsertFeatures(deltaInner?.upsert ?? deltaInner?.upserts ?? deltaInner?.features ?? deltaInner?.data);
+        }
+        if (candidate?.patch != null) collectUpsertFeatures(candidate.patch);
+    };
+
+    if (raw == null || typeof raw !== 'object') return { upserts, cancelIds, expireIds };
+    if (Array.isArray(raw)) {
+        collectUpsertFeatures(raw);
+        return { upserts, cancelIds, expireIds };
+    }
+    const msg = raw;
+    const collectBuckets = (container) => {
+        const action = container.type ?? container.action;
+
+        if (container.upsert != null) collectUpsertFeatures(container.upsert);
+        if (container.upserts != null) collectUpsertFeatures(container.upserts);
+        if (container.alert != null) collectUpsertFeatures(container.alert);
+        if (container.alerts != null) collectUpsertFeatures(container.alerts);
+        if (container.new != null) collectUpsertFeatures(container.new);
+        if (container.extended != null) collectUpsertFeatures(container.extended);
+        if (container.upgraded != null) collectUpsertFeatures(container.upgraded);
+        if (action === 'upsert' || action === 'Upsert') {
+            collectUpsertFeatures(container.features ?? container.items ?? container.data);
+        }
+        if (container.features != null && container.type !== 'FeatureCollection') {
+            collectUpsertFeatures(container.features);
+        }
+
+        if (container.cancel != null) pushIds(cancelIds, container.cancel);
+        if (container.cancels != null) pushIds(cancelIds, container.cancels);
+        if (container.cancelled != null) pushIds(cancelIds, container.cancelled);
+        if (container.canceled != null) pushIds(cancelIds, container.canceled);
+        if (action === 'cancel' || action === 'Cancel') {
+            pushIds(cancelIds, container.ids ?? container.base_alert_ids ?? container.items);
+        }
+
+        if (container.expire != null) pushIds(expireIds, container.expire);
+        if (container.expires != null) pushIds(expireIds, container.expires);
+        if (container.expired != null) pushIds(expireIds, container.expired);
+        if (action === 'expire' || action === 'Expire') {
+            pushIds(expireIds, container.ids ?? container.base_alert_ids ?? container.items);
+        }
+    };
+
+    collectBuckets(msg);
+    if (msg.diff != null && typeof msg.diff === 'object') {
+        collectBuckets(msg.diff);
+    }
+
+    return { upserts, cancelIds, expireIds };
+}
+
+export function filterNwwsTerminalStatusFeatures(fc) {
+    const base = normalizeFeatureCollectionForMapboxGl(fc);
+    return {
+        type: 'FeatureCollection',
+        features: base.features.filter((feature) => {
+            const status = getNwwsTrackerStatusFromProperties(feature?.properties);
+            return !isNwwsTrackerStatusTerminal(status);
+        }),
+    };
+}
+
+/**
+ * Legacy filter: tornado + severe-thunderstorm family only (same as pre–all-alerts SDK).
+ * @param {import('geojson').FeatureCollection} fc
+ */
+export function filterToConvectiveSdkEvents(fc) {
+    const base = normalizeFeatureCollectionForMapboxGl(fc);
+    const out = [];
+    for (const f of base.features) {
+        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
+        if (ev && SDK_ALLOWED_EVENT_SET.has(ev)) {
+            out.push(f);
+        }
+    }
+    return { type: 'FeatureCollection', features: out };
+}
+
+/**
+ * Whether a resolved NWS `event_name` should be shown when the user chose {@link filterNwsAlertsByIncludedList}.
+ * Matches exact names; also matches when the user lists a parent product (e.g. "Tornado Warning") and the feature
+ * is a known subtype (e.g. "Tornado Warning (PDS)") via {@link NWS_WARNINGS_SUBTYPE_PARENT}.
+ * @param {string[] | null | undefined} includedAlerts
+ * @param {string} eventLabel
+ */
+export function isNwsEventIncludedInAllowlist(includedAlerts, eventLabel) {
+    if (!includedAlerts?.length || !eventLabel) {
+        return false;
+    }
+    const set = new Set(
+        includedAlerts.map((x) => (x != null ? String(x).trim() : '')).filter(Boolean)
+    );
+    if (set.size === 0) {
+        return false;
+    }
+    const ev = String(eventLabel).trim();
+    if (set.has(ev)) {
+        return true;
+    }
+    const parent = NWS_WARNINGS_SUBTYPE_PARENT[ev];
+    if (parent && set.has(parent)) {
+        return true;
+    }
+    if (ev === 'Tornado Warning (Observed)' && set.has('Tornado Warning (Reported)')) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * @param {import('geojson').FeatureCollection} fc
+ * @param {string[]} includedAlerts
+ */
+export function filterNwsAlertsByIncludedList(fc, includedAlerts) {
+    const base = normalizeFeatureCollectionForMapboxGl(fc);
+    const out = [];
+    for (const f of base.features) {
+        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
+        if (isNwsEventIncludedInAllowlist(includedAlerts, ev)) {
+            out.push(f);
+        }
+    }
+    return { type: 'FeatureCollection', features: out };
+}
+
+/**
+ * @param {import('geojson').FeatureCollection} fc
+ * @param {'all' | 'user'} [scope]
+ * @param {string[] | undefined} [includedAlerts] - Used when `scope === 'user'`: exact NWS `event_name` strings to show.
+ */
+export function filterNwsAlertsByScope(fc, scope = 'all', includedAlerts) {
+    const safe = normalizeFeatureCollectionForMapboxGl(fc);
+    if (scope === 'user') {
+        return filterNwsAlertsByIncludedList(safe, includedAlerts ?? []);
+    }
+    const features = safe.features.filter((f) => {
+        const ev = getNwsAlertEventLabelFromProperties(f?.properties ?? {});
+        return !!(ev && String(ev).trim());
+    });
+    return { type: 'FeatureCollection', features };
+}
+
+/** @deprecated Use {@link filterToConvectiveSdkEvents} or {@link filterNwsAlertsByScope} with `scope: 'user'` and an explicit `includedAlerts` list. */
+export function filterToSdkAllowedEvents(fc) {
+    return filterToConvectiveSdkEvents(fc);
+}
+
+function extractRawNwwsVtecString(properties) {
+    if (!properties) return null;
+    if (properties.vtec != null) return String(properties.vtec);
+    if (properties.VTEC != null) return String(properties.VTEC);
+    const details = properties.details;
+    if (details?.pvtec != null) return String(details.pvtec);
+    const params = properties.parameters;
+    if (params != null && typeof params === 'object' && !Array.isArray(params)) {
+        const direct = params.VTEC ?? params.vtec;
+        if (direct != null) {
+            return Array.isArray(direct) ? String(direct[0] ?? '') : String(direct);
+        }
+        for (const k of Object.keys(params)) {
+            if (String(k).toUpperCase() === 'VTEC') {
+                const x = params[k];
+                if (x != null) return Array.isArray(x) ? String(x[0] ?? '') : String(x);
+            }
+        }
+    }
+    return null;
+}
+
+function normalizeNwsChainTimeComponent(v) {
+    if (v == null || v === '') return null;
+    if (typeof v === 'number' && Number.isFinite(v)) {
+        return new Date(v > 1e12 ? v : v * 1000).toISOString();
+    }
+    const s = String(v).trim();
+    const ms = Date.parse(s);
+    if (!Number.isNaN(ms)) return new Date(ms).toISOString();
+    return s;
+}
+
+function getNwsOfficeEventIssuedChainId(properties) {
+    if (!properties) return null;
+    const office = String(properties.office ?? properties.sender_icao ?? properties.sender ?? '').trim();
+    const ev = String(properties.event ?? properties.event_name ?? '').trim();
+    const rawIssued = getNwsTimeProp(properties, ['issued', 'issued_at']);
+    if (!office || !ev || rawIssued == null || rawIssued === '') return null;
+    const issuedNorm = normalizeNwsChainTimeComponent(rawIssued);
+    if (!issuedNorm) return null;
+    return `${office}|${ev}|${issuedNorm}`;
+}
+
+/**
+ * Extracts a stable VTEC-derived alert ID (e.g. "KWNS.SV.A.0108") from raw feature properties.
+ * The VTEC event number is stable across CON/EXT/CAN actions for the same watch/warning,
+ * unlike content-based hashes which change on every update.
+ */
+function extractNwsVtecStableId(properties) {
+    const vtec = extractRawNwwsVtecString(properties);
+    if (vtec == null || vtec === '') return null;
+    const parts = String(vtec).split('.');
+    if (parts.length < 6) return null;
+    const office = parts[2]?.trim();
+    const ph = parts[3]?.trim();
+    const sig = parts[4]?.trim();
+    const seq = parts[5]?.trim();
+    if (!office || !ph || !sig || !seq) return null;
+    return `${office}.${ph}.${sig}.${seq}`;
+}
+
+function getNwsHttpAlertStableId(properties) {
+    if (!properties) return null;
+    const details = properties.details;
+    if (details && typeof details === 'object') {
+        const tr = details.tracking;
+        if (tr != null && String(tr).trim() !== '') return String(tr).trim();
+    }
+    // Same DB key as backend — use if trim drops details/hash (see API trim payloads).
+    for (const k of ['nws_stable_id', 'stable_id', 'alert_chain_id']) {
+        const v = properties[k];
+        if (v != null && String(v).trim() !== '') return String(v).trim();
+    }
+    if (properties.tracking != null && typeof properties.tracking === 'string' && String(properties.tracking).trim() !== '') {
+        return String(properties.tracking).trim();
+    }
+    // Prefer VTEC-derived ID over hash: VTEC event number is stable across all CON/EXT/UPG
+    // actions while the content hash changes on every update, causing phantom duplicates on the map.
+    const vtecId = extractNwsVtecStableId(properties);
+    if (vtecId) return vtecId;
+    const chainId = getNwsOfficeEventIssuedChainId(properties);
+    if (chainId) return chainId;
+    const h = properties.hash;
+    if (h != null && String(h).trim() !== '') return String(h).trim();
+    return null;
+}
+
+function mapHttpActionToTrackerStatus(p, forLiveStream) {
+    if (!forLiveStream) return undefined;
+    if (p.is_cancelled === true) return 'cancelled';
+    const at = String(p.action_type ?? '').trim().toLowerCase();
+    if (at === 'cancelled' || at === 'canceled') return 'cancelled';
+    if (at === 'expired') return 'expired';
+    if (at === 'upgraded') return 'upgraded';
+    if (at === 'extended' || at === 'extension') return 'extended';
+    if (at === 'updated') return 'extended';
+    if (at === 'continuation' || at === 'continued') return 'continuation';
+    if (at === 'issued' || at === 'new') return 'issued';
+    if (at === '') return 'issued';
+    return 'issued';
+}
+
+export function normalizeNwwsHttpAlertFeature(raw, forLiveStream) {
+    if (!raw || typeof raw !== 'object' || raw.type !== 'Feature') return raw;
+    const p = { ...(raw.properties ?? {}) };
+    const explicitUid =
+        normalizeNwwsAlertId(raw.id) ?? normalizeNwwsAlertId(p.id) ?? normalizeNwwsAlertId(p.alert_id ?? p.alertId);
+    if (explicitUid && isNwwsVtecTimestampInstanceId(explicitUid)) {
+        p.base_alert_id = explicitUid;
+        p.alert_id = explicitUid;
+        const vb = getNwwsVtecSequenceBaseFromInstanceId(explicitUid);
+        if (vb) p._nws_vtec_seq_base = vb;
+    } else {
+        const stableId = getNwsHttpAlertStableId(p);
+        if (stableId) {
+            p.base_alert_id = stableId;
+            p.alert_id = stableId;
+        } else {
+            const fallback =
+                normalizeNwwsAlertId(raw.id) ?? normalizeNwwsAlertId(p.id) ?? normalizeNwwsAlertId(p.alert_id ?? p.alertId);
+            if (fallback) {
+                p.base_alert_id = fallback;
+                p.alert_id = fallback;
+            } else {
+                const chain = getNwsOfficeEventIssuedChainId(p);
+                if (chain) {
+                    p.base_alert_id = chain;
+                    p.alert_id = chain;
+                }
+            }
+        }
+    }
+    const tracker = mapHttpActionToTrackerStatus(p, forLiveStream);
+    if (tracker !== undefined) {
+        p._trackerStatus = tracker;
+    }
+    if (p._nws_vtec_seq_base == null) {
+        const capV = extractNwsVtecStableId(p);
+        if (capV) p._nws_vtec_seq_base = capV;
+    }
+    return { ...raw, properties: p };
+}
+
+export function unwrapNwwsFeatureCollectionRoot(parsed) {
+    if (Array.isArray(parsed)) {
+        return {
+            type: 'FeatureCollection',
+            features: parsed.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
+        };
+    }
+    if (!parsed || typeof parsed !== 'object') return null;
+    const o = parsed;
+    if (o.type === 'FeatureCollection' && Array.isArray(o.features)) {
+        return {
+            type: 'FeatureCollection',
+            features: o.features.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
+        };
+    }
+    for (const key of ['geojson', 'data', 'payload', 'body', 'collection', 'result', 'message', 'record']) {
+        const inner = o[key];
+        if (
+            inner &&
+            typeof inner === 'object' &&
+            inner.type === 'FeatureCollection' &&
+            Array.isArray(inner.features)
+        ) {
+            return {
+                type: 'FeatureCollection',
+                features: inner.features.map((f) => normalizeNwwsHttpAlertFeature(f, false)),
+            };
+        }
+    }
+    return null;
+}
+
+export function cloneNwwsFeatureCollectionStrippingVolatile(data) {
+    const norm = normalizeFeatureCollectionForMapboxGl(data);
+    return {
+        type: 'FeatureCollection',
+        features: norm.features.flatMap((f) => {
+            const p = f?.properties;
+            if (p) {
+                const ex = p.nwws_expired;
+                if (ex === true || ex === 1 || String(ex).toLowerCase() === 'true') {
+                    return [];
+                }
+            }
+            const copy = {
+                ...f,
+                properties: p ? { ...p } : {},
+            };
+            delete copy._lastActiveState;
+            if (copy.properties && 'nwws_expired' in copy.properties) {
+                delete copy.properties.nwws_expired;
+            }
+            if (copy.properties) {
+                delete copy.properties._nws_flash_until_unix;
+                delete copy.properties._nws_webhook_debug_flash;
+            }
+            return [copy];
+        }),
+    };
+}
+
+export function buildAlertClickPayload(feature) {
+    const properties = feature?.properties ? { ...feature.properties } : {};
+    const eventName = getNwsAlertEventLabelFromProperties(properties);
+    let tags = properties.tags;
+    if (typeof tags === 'string') {
+        try {
+            tags = JSON.parse(tags);
+        } catch {
+            tags = null;
+        }
+    }
+    if (!Array.isArray(tags)) {
+        tags = tags != null ? [String(tags)] : [];
+    }
+    const headline = properties.headline != null ? String(properties.headline) : '';
+    const name =
+        headline ||
+        eventName ||
+        (properties.event != null ? String(properties.event) : '') ||
+        (properties.event_name != null ? String(properties.event_name) : '');
+    const description =
+        properties.description != null
+            ? String(properties.description)
+            : properties.raw_text != null
+              ? String(properties.raw_text)
+              : '';
+    const summary = properties.summary != null ? String(properties.summary) : '';
+    const instruction = properties.instruction != null ? String(properties.instruction) : '';
+
+    const startUnix =
+        typeof properties.start_unix === 'number'
+            ? properties.start_unix
+            : getNwsStartUnixForMap(properties);
+    const endUnix =
+        typeof properties.end_unix === 'number'
+            ? properties.end_unix
+            : parseNwsTimeToUnix(getNwsTimeProp(properties, [...NWS_ALERT_END_TIME_PROP_KEYS]));
+    const activeStartUnix =
+        typeof properties.active_start_unix === 'number'
+            ? properties.active_start_unix
+            : getNwsActiveStartUnix(properties);
+
+    return {
+        name,
+        eventName,
+        headline,
+        summary,
+        description,
+        instruction,
+        tags,
+        startUnix,
+        endUnix,
+        activeStartUnix,
+        properties,
+    };
+}