@aguacerowx/mapsgl 0.0.32 → 0.0.42

package/src/nwsAlertsSupport.js

@@ -0,0 +1,860 @@
+/**
+ * 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;
+}
+
+export function getNwwsTrackerStatusFromProperties(properties) {
+    if (!properties) return null;
+    const raw = properties._trackerStatus ?? properties.trackerStatus ?? properties.tracker_status;
+    if (raw == null || raw === '') 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';
+}
+
+function isNwwsTrackerStatusUpgrade(status) {
+    return status === 'upgraded';
+}
+
+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;
+    return normalizeNwwsAlertId(p?.alert_id ?? p?.alertId ?? p?.id ?? feature?.id);
+}
+
+export function getNwsAlertInstanceIdFromFeature(feature) {
+    const p = feature?.properties ?? {};
+    const baseId = getNwsBaseAlertIdFromFeature(feature);
+    const direct = normalizeNwwsAlertId(
+        p.alert_id ?? p.alertId ?? p.unique_id ?? p.uniqueId ?? p.id ?? feature?.id
+    );
+    return direct ?? baseId;
+}
+
+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]);
+
+    const replacedBaseIds = new Set();
+    for (const feat of delta.upserts) {
+        if (!feat || feat.type !== 'Feature') continue;
+        const baseId = getNwsBaseAlertIdFromFeature(feat);
+        if (baseId) replacedBaseIds.add(baseId);
+    }
+
+    const clearedGeometryByInstance = new Map();
+    const clearedMapboxIdByInstance = new Map();
+
+    if (replacedBaseIds.size > 0) {
+        features = features.filter((f) => {
+            const baseId = getNwsBaseAlertIdFromFeature(f);
+            if (!baseId || !replacedBaseIds.has(baseId)) 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 enriched = enrichWarningsWithColors({ type: 'FeatureCollection', features: [feat] }).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 pushUpgradeReplacedIdsFromFeature = (feature) => {
+        const status = getNwwsTrackerStatusFromProperties(feature?.properties);
+        if (!isNwwsTrackerStatusUpgrade(status)) return;
+        const p = feature?.properties ?? {};
+        const direct =
+            p._upgradedFrom ??
+            p.upgradedFrom ??
+            p._replaces ??
+            p.replaces ??
+            p.replaced_alert_id ??
+            p.replacedAlertId;
+        const directNorm = normalizeNwwsAlertId(direct);
+        if (directNorm) cancelIds.push(directNorm);
+
+        const refs = p.references ?? feature?.references;
+        if (Array.isArray(refs)) {
+            for (const r of refs) {
+                if (r == null) continue;
+                if (typeof r === 'string') {
+                    const id = normalizeNwwsAlertId(r);
+                    if (id) cancelIds.push(id);
+                    continue;
+                }
+                if (typeof r === 'object') {
+                    const ro = r;
+                    const id = normalizeNwwsAlertId(
+                        ro.identifier ?? ro.id ?? ro.alert_id ?? ro.alertId ?? ro.base_alert_id
+                    );
+                    if (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;
+                }
+                pushUpgradeReplacedIdsFromFeature(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 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();
+    }
+    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 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;
+        }
+    }
+    const tracker = mapHttpActionToTrackerStatus(p, forLiveStream);
+    if (tracker !== undefined) {
+        p._trackerStatus = tracker;
+    }
+    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,
+    };
+}