@aguacerowx/javascript-sdk 0.0.24 → 0.0.26

package/src/nws/nwsAlertsSupport.js

@@ -0,0 +1,1337 @@
+/**
+ * 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;
+}
+
+/** CAP validity start fields (order matches aguacero-frontend `nwsWarningsModalHelpers`). */
+const NWS_VALIDITY_START_PROP_KEYS = ['onset', 'effective', 'issued_at', 'issued', 'sent'];
+
+/**
+ * True if CAP-validity [start, end] overlaps [winStartSec, winEndSec] (inclusive).
+ * Missing end time is treated as ongoing.
+ *
+ * @param {{ properties?: Record<string, unknown> }} feature
+ * @param {number} winStartSec
+ * @param {number} winEndSec
+ * @returns {boolean}
+ */
+export function nwsFeatureOverlapsUnixWindow(feature, winStartSec, winEndSec) {
+    const p = feature?.properties;
+    if (!p) return false;
+    const start =
+        typeof p.start_unix === 'number' && Number.isFinite(p.start_unix)
+            ? Math.floor(p.start_unix)
+            : parseNwsTimeToUnix(getNwsTimeProp(p, NWS_VALIDITY_START_PROP_KEYS));
+    const end =
+        typeof p.end_unix === 'number' && Number.isFinite(p.end_unix)
+            ? Math.floor(p.end_unix)
+            : parseNwsTimeToUnix(getNwsTimeProp(p, [...NWS_ALERT_END_TIME_PROP_KEYS]));
+    const s = typeof start === 'number' && Number.isFinite(start) ? start : 0;
+    const e = typeof end === 'number' && Number.isFinite(end) ? end : Number.POSITIVE_INFINITY;
+    return s <= winEndSec && e >= winStartSec;
+}
+
+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)
+    );
+}
+
+/**
+ * SVR revision visibility: superseded geometry only before cutover unix; updated geometry only at/after cutover.
+ * Returns null when this feature does not use revision split (fall back to start_unix / end_unix).
+ * Matches aguacero-frontend {@link nwsRevisionVisibilityActive}.
+ */
+export function nwsRevisionVisibilityActive(properties, referenceUnix) {
+    if (!properties) return null;
+    const role = properties._nws_revision_role;
+    const cut = properties._nws_revision_cutover_unix;
+    if (cut == null || typeof cut !== 'number' || !role) return null;
+    if (role === 'superseded') {
+        return referenceUnix < cut;
+    }
+    if (role === 'update') {
+        return referenceUnix >= cut;
+    }
+    if (role === 'current') {
+        return null;
+    }
+    return null;
+}
+
+/** nwws-server stores ids as `${vtecBaseId}.${issuedTs}`; strip the issued suffix for revision grouping. */
+function stripNwwsIssuedMillisSuffixFromId(id) {
+    const m = String(id).match(/^(.+)\.(\d{10,})$/);
+    return m ? m[1] : id;
+}
+
+/**
+ * One key per logical warning product (VTEC sequence / base id). Matches aguacero-frontend
+ * {@link getNwwsLogicalProductKey} for deduping superseded vs update rows on the time slider.
+ */
+export function getNwwsLogicalProductKey(feature) {
+    const p = feature?.properties ?? {};
+    const params = p.parameters;
+    const vtecRaw = params != null && typeof params === 'object' && !Array.isArray(params) ? params.VTEC : undefined;
+    const vtec = Array.isArray(vtecRaw)
+        ? vtecRaw[0]
+        : p.vtec ?? (p.details && typeof p.details === 'object' ? p.details.pvtec : undefined);
+    if (typeof vtec === 'string' && vtec.trim()) {
+        const parts = vtec.split('.');
+        if (parts.length >= 6) {
+            return `${parts[2]}.${parts[3]}.${parts[4]}.${parts[5]}`;
+        }
+    }
+    const base = getNwsBaseAlertIdFromFeature(feature);
+    if (base) return stripNwwsIssuedMillisSuffixFromId(base);
+    if (feature?.id != null && feature.id !== '') return stripNwwsIssuedMillisSuffixFromId(String(feature.id));
+    return null;
+}
+
+export function getNwwsProductKeyFromFeature(feature) {
+    const pk = feature?.properties?.nws_product_key;
+    if (typeof pk === 'string' && pk.trim() !== '') return pk.trim();
+    return getNwwsLogicalProductKey(feature);
+}
+
+/**
+ * When superseded + update rows both pass time checks, pick one per reference instant (same product key).
+ * Matches aguacero-frontend {@link pickBestNwsRevisionAmongConflictingFeatures}.
+ */
+export function pickBestNwsRevisionAmongConflictingFeatures(features, referenceUnix) {
+    if (!Array.isArray(features) || features.length === 0) return null;
+    if (features.length === 1) return features[0];
+    const scored = features.map((f) => {
+        const p = f?.properties ?? {};
+        const role = String(p._nws_revision_role ?? '');
+        const cut =
+            typeof p._nws_revision_cutover_unix === 'number' && Number.isFinite(p._nws_revision_cutover_unix)
+                ? p._nws_revision_cutover_unix
+                : null;
+        let slotScore = 0;
+        if (role === 'superseded' && cut != null) {
+            slotScore = referenceUnix < cut ? 2 : 0;
+        } else if (role === 'update' && cut != null) {
+            slotScore = referenceUnix >= cut ? 2 : 0;
+        } else if (role === 'current') {
+            slotScore = 1;
+        } else {
+            slotScore = 1;
+        }
+        const t =
+            parseNwsTimeToUnix(getNwsTimeProp(p, ['sent', 'updated_at', 'issued_at', 'issued'])) ?? 0;
+        return { f, slotScore, t };
+    });
+    scored.sort((a, b) => {
+        if (b.slotScore !== a.slotScore) return b.slotScore - a.slotScore;
+        return b.t - a.t;
+    });
+    return scored[0].f;
+}
+
+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];
+        }),
+    };
+}
+
+/**
+ * Parse `properties.parameters` (JSON string or object from NWWS / CAP-style extensions).
+ * @param {unknown} raw
+ * @returns {Record<string, unknown>|null}
+ */
+function parseNwsParametersJson(raw) {
+    if (raw == null) return null;
+    if (typeof raw === 'object' && !Array.isArray(raw)) return /** @type {Record<string, unknown>} */ (raw);
+    if (typeof raw === 'string') {
+        try {
+            const o = JSON.parse(raw);
+            return o && typeof o === 'object' && !Array.isArray(o) ? o : null;
+        } catch {
+            return null;
+        }
+    }
+    return null;
+}
+
+/**
+ * Human-oriented subset of `parameters` for severe wx / common warning types (hail, wind, radar source).
+ * @param {Record<string, unknown>|null} pObj
+ * @returns {Record<string, string> | null}
+ */
+function buildHazardDetailsFromParameters(pObj) {
+    if (!pObj || typeof pObj !== 'object') return null;
+    /** @type {Record<string, string>} */
+    const out = {};
+    const set = (key, from) => {
+        const v = pObj[from];
+        if (v != null && String(v).trim() !== '') out[key] = String(v);
+    };
+    set('source', 'source');
+    set('maxHailSize', 'max_hail_size');
+    set('maxWindGust', 'max_wind_gust');
+    set('damageThreat', 'damage_threat');
+    set('wmo', 'wmo');
+    if (pObj.tornado_detection != null && String(pObj.tornado_detection).trim() !== '')
+        out.tornadoDetection = String(pObj.tornado_detection);
+    if (pObj.flood_detection != null && String(pObj.flood_detection).trim() !== '')
+        out.floodDetection = String(pObj.flood_detection);
+    return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Normalized payload for `nws:alert:click`. Top-level fields are derived from `feature.properties`
+ * so you rarely need the duplicate `properties` object (kept for advanced / forward-compatible use).
+ *
+ * @param {GeoJSON.Feature|{ properties?: Record<string, unknown> }} feature
+ */
+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 name =
+        (properties.headline != null && String(properties.headline).trim() !== ''
+            ? String(properties.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 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);
+
+    const parametersParsed = parseNwsParametersJson(properties.parameters);
+    const hazardDetails = buildHazardDetailsFromParameters(parametersParsed);
+
+    return {
+        name,
+        eventName,
+        description,
+        tags,
+        startUnix,
+        endUnix,
+        activeStartUnix,
+        /** ISO-ish strings from the feed (see also unix fields above). */
+        issued: properties.issued != null ? String(properties.issued) : '',
+        updatedAt: properties.updated_at != null ? String(properties.updated_at) : '',
+        expiresAt: properties.expires != null ? String(properties.expires) : '',
+        alertId: properties.alert_id != null ? String(properties.alert_id) : '',
+        office: properties.office != null ? String(properties.office) : '',
+        nwsProductKey: properties.nws_product_key != null ? String(properties.nws_product_key) : '',
+        /** Parsed `properties.parameters` JSON when present (hail/wind/source keys vary by product). */
+        parametersParsed,
+        /** Short labels for SV / similar products: source, maxHailSize, maxWindGust, damageThreat, … */
+        hazardDetails,
+        /** Same as `feature.properties` — prefer top-level fields above when possible. */
+        properties,
+    };
+}