@aguacerowx/mapsgl 0.0.53 → 0.0.55

package/src/NwsWatchesWarningsOverlay.js

@@ -22,11 +22,17 @@ import {
     getNwwsProductKeyFromFeature,
     normalizeFeatureCollectionForMapboxGl,
     normalizeNwwsHttpAlertFeature,
+    nwsFeatureOverlapsUnixWindow,
     nwsRevisionVisibilityActive,
     parseNwwsWsDelta,
     pickBestNwsRevisionAmongConflictingFeatures,
     unwrapNwwsFeatureCollectionRoot,
 } from './nwsAlertsSupport.js';
+import {
+    buildNwwsActiveAlertsUrl,
+    nwsAlertsFetchSpecCacheKey,
+    nwwsAlertsFetchUnixWindow,
+} from './nwsAlertsFetchSpec.js';
 
 /** Aguacero base style: state polygon outlines — NWS alert lines render under this layer. */
 export const NWS_DEFAULT_LINE_BEFORE_LAYER_ID = 'AML_-_states';
@@ -131,6 +137,12 @@ export class NwsWatchesWarningsOverlay {
         this._destroyed = false;
         /** When true, baseline fetch + SSE have been started for the current enabled session. */
         this._started = false;
+        /** GET `/alerts?hours=` — same basis as aguacero-frontend observational duration (tier-clamped). */
+        this._alertsFetchHours = 1;
+        /** {@link nwsAlertsFetchSpecCacheKey} for the last baseline request; refetch when hours change. */
+        this._lastAlertsSpecKey = null;
+        /** Invalidates in-flight baseline HTTP when a newer hours spec is requested. */
+        this._baselineFetchGen = 0;
 
         /** @type {number | null | undefined} */
         this._timelineUnix = undefined;
@@ -275,6 +287,8 @@ export class NwsWatchesWarningsOverlay {
         this.syncWithMode({
             enabled: this.options.enabled,
             timelineUnix: this._timelineUnix,
+            timelineTimes: this._timelineTimes,
+            alertsFetchHours: this._alertsFetchHours,
         });
     }
 
@@ -664,13 +678,35 @@ export class NwsWatchesWarningsOverlay {
     }
 
     async _fetchBaseline() {
-        const url = this.getAlertsUrl();
+        const myGen = ++this._baselineFetchGen;
+        const hours = Math.max(1, Math.floor(Number(this._alertsFetchHours) || 1));
+        const url = buildNwwsActiveAlertsUrl(this.getAlertsUrl(), hours);
         const res = await fetch(url);
         if (!res.ok) throw new Error(`NWS alerts HTTP ${res.status}`);
         const parsed = await res.json();
+        if (myGen !== this._baselineFetchGen) return null;
         const geojson = unwrapNwwsFeatureCollectionRoot(parsed);
         if (!geojson) return null;
-        return this._normalizeSnapshot(geojson);
+        const { winStartSec, winEndSec } = nwwsAlertsFetchUnixWindow(hours, null);
+        const overlapping = (geojson.features ?? []).filter((f) =>
+            nwsFeatureOverlapsUnixWindow(f, winStartSec, winEndSec)
+        );
+        const filtered = { ...geojson, features: overlapping };
+        if (myGen !== this._baselineFetchGen) return null;
+        return this._normalizeSnapshot(filtered);
+    }
+
+    async _refetchBaselineForNewHours() {
+        if (this._destroyed || !this.options.enabled) return;
+        try {
+            const baseline = await this._fetchBaseline();
+            if (baseline && !this._destroyed && this.options.enabled) {
+                this._workingFc = baseline;
+                this._setWorkingData(baseline);
+            }
+        } catch (err) {
+            console.warn('[NwsWatchesWarningsOverlay] Baseline refetch (hours change) failed:', err);
+        }
     }
 
     _processInboundSocketText(text) {
@@ -806,14 +842,6 @@ export class NwsWatchesWarningsOverlay {
 
     async _initialLoad() {
         if (this._destroyed || !this.options.enabled) return;
-        try {
-            const baseline = await this._fetchBaseline();
-            if (baseline) {
-                this._workingFc = baseline;
-            }
-        } catch (err) {
-            console.warn('[NwsWatchesWarningsOverlay] Baseline fetch failed:', err);
-        }
 
         const paintWhenReady = () => {
             this._ensureLayers();
@@ -826,6 +854,18 @@ export class NwsWatchesWarningsOverlay {
             paintWhenReady();
         }
 
+        void this._fetchBaseline()
+            .then((baseline) => {
+                if (this._destroyed || !this.options.enabled) return;
+                if (baseline) {
+                    this._workingFc = baseline;
+                }
+                this._setWorkingData(this._workingFc);
+            })
+            .catch((err) => {
+                console.warn('[NwsWatchesWarningsOverlay] Baseline fetch failed:', err);
+            });
+
         this._connectSse();
     }
 
@@ -884,9 +924,17 @@ export class NwsWatchesWarningsOverlay {
      * @param {number | null | undefined} opts.timelineUnix - Active scrubber unix for satellite / MRMS / NEXRAD.
      * @param {number[] | null | undefined} [opts.timelineTimes] - Full timeline for the current layer (for “live edge” = wall clock).
      * @param {boolean} [opts.hasObservationTimeline] - When false (model / base map only), scrub hold is cleared and wall clock is used until observation data returns.
+     * @param {number} [opts.alertsFetchHours] - GET `/alerts?hours=` (from WeatherLayerManager / {@link computeNwsAlertsFetchHoursFromAguaceroState}); refetches baseline when this changes.
      */
-    syncWithMode({ enabled, timelineUnix, timelineTimes, hasObservationTimeline }) {
+    syncWithMode({ enabled, timelineUnix, timelineTimes, hasObservationTimeline, alertsFetchHours }) {
         if (this._destroyed) return;
+        const hours =
+            alertsFetchHours != null && Number.isFinite(Number(alertsFetchHours))
+                ? Math.max(1, Math.floor(Number(alertsFetchHours)))
+                : 1;
+        const specKey = nwsAlertsFetchSpecCacheKey(hours);
+        this._alertsFetchHours = hours;
+
         this.options.enabled = !!enabled;
         if (hasObservationTimeline === false) {
             this._stickyTimelineUnix = null;
@@ -898,6 +946,7 @@ export class NwsWatchesWarningsOverlay {
         if (!this.options.enabled) {
             this._stickyTimelineUnix = null;
             this._started = false;
+            this._lastAlertsSpecKey = null;
             this._sseFirstOpen = true;
             this._tearDownStream();
             this._removeLayers();
@@ -905,7 +954,13 @@ export class NwsWatchesWarningsOverlay {
         }
         if (!this._started) {
             this._started = true;
+            this._lastAlertsSpecKey = specKey;
             void this._initialLoad();
+            return;
+        }
+        if (this._lastAlertsSpecKey !== specKey) {
+            this._lastAlertsSpecKey = specKey;
+            void this._refetchBaselineForNewHours();
         }
         // When already running, time filtering is applied in setTimelineUnix (avoids double work
         // per scrub tick, matching aguacero-frontend: no full setData on slider move).

package/src/WeatherLayerManager.js

@@ -6,6 +6,7 @@ import { SatelliteShaderManager } from './SatelliteShaderManager.js';
 import { NexradWeatherController } from './NexradWeatherController.js';
 import { NexradSitesOverlay } from './NexradSitesOverlay.js';
 import { NwsWatchesWarningsOverlay } from './NwsWatchesWarningsOverlay.js';
+import { computeNwsAlertsFetchHoursFromAguaceroState } from './nwsAlertsFetchSpec.js';
 import WorkerPool from './WorkerPool.js';
 
 import { DEFAULT_BASIS_BASE_URL } from './defaultBasisBaseUrl.js';
@@ -292,6 +293,10 @@ export class WeatherLayerManager extends EventEmitter {
     /**
      * NWS watches/warnings: same NWWS feed as aguacero-frontend. Shown whenever `enabled` is true (including
      * model-only maps — time filter uses wall clock until a satellite / MRMS / NEXRAD scrub timeline exists).
+     * Baseline GET `/alerts?hours=N` matches the **active** timeline span: NEXRAD uses `nexradDurationValue`,
+     * MRMS uses `mrmsDurationValue`, satellite uses `satelliteDurationValue`, model-only uses 1 hour.
+     * Hours are clamped by {@link AguaceroCore} `satelliteTier` (the core’s subscription tier field:
+     * `basic` / `enthusiast` / `professional`), same caps as the frontend radar duration menus.
      * By default `nwsAlertSettings.alertScope` is `'all'`. Use `'user'` with
      * `includedAlerts` (exact NWS `event_name` strings) to show only selected products.
      *
@@ -353,6 +358,8 @@ export class WeatherLayerManager extends EventEmitter {
             ? wopt.fillBeforeLayerId ?? null
             : null;
 
+        const alertsFetchHours = computeNwsAlertsFetchHoursFromAguaceroState(state);
+
         const nwsAlertSettingsForOpts = {
             ...(wopt.nwsAlertSettings ?? {}),
             ...(wopt.activeOnlyRealtime !== undefined ? { activeOnlyRealtime: wopt.activeOnlyRealtime } : {}),
@@ -384,7 +391,13 @@ export class WeatherLayerManager extends EventEmitter {
                 nwsAlertSettings: nwsAlertSettingsForOpts,
             });
         }
-        this._nwsOverlay.syncWithMode({ enabled, timelineUnix, timelineTimes, hasObservationTimeline });
+        this._nwsOverlay.syncWithMode({
+            enabled,
+            timelineUnix,
+            timelineTimes,
+            hasObservationTimeline,
+            alertsFetchHours,
+        });
     }
 
     /**

package/src/nexrad/loadNexradSites.ts

@@ -1,4 +1,6 @@
 import type { NexradSite } from './PreprocessedSweepParser.js';
+import nexradSitesDefault from './nexradSitesDefault.json';
+import { nexradArchiveDiag, redactApiKeyFromUrl } from './nexradArchiveDiag.js';
 
 type NexradSitesPayload = {
     sites?: NexradSite[];
@@ -13,22 +15,98 @@ export function setNexradSitesJsonUrl(url: string) {
     sitesUrl = url || sitesUrl;
 }
 
+/**
+ * When sitesUrl is HTTPS (e.g. CloudFront), use the same auth as AguaceroCore grid fetches:
+ * `?apiKey=`, `x-api-key`, and `x-app-identifier` on React Native when bundle id is set.
+ */
+let SITES_FETCH_API_KEY = '';
+let SITES_FETCH_BUNDLE_ID = '';
+export function setNexradSitesFetchAuth(apiKey: string, bundleId?: string) {
+    SITES_FETCH_API_KEY = apiKey || '';
+    if (bundleId !== undefined) {
+        SITES_FETCH_BUNDLE_ID = bundleId || '';
+    }
+}
+
 let nexradSitesPayloadPromise: Promise<NexradSitesPayload> | null = null;
 
+function sitesFetchUrl(): string {
+    if (!sitesUrl.startsWith('http') || !SITES_FETCH_API_KEY) {
+        return sitesUrl;
+    }
+    const sep = sitesUrl.includes('?') ? '&' : '?';
+    return `${sitesUrl}${sep}apiKey=${SITES_FETCH_API_KEY}`;
+}
+
+function sitesFetchHeaders(): Record<string, string> | undefined {
+    if (!SITES_FETCH_API_KEY) {
+        return undefined;
+    }
+    const headers: Record<string, string> = {
+        'x-api-key': SITES_FETCH_API_KEY,
+    };
+    const nav = (globalThis as { navigator?: { product?: string } }).navigator;
+    if (nav?.product === 'ReactNative' && SITES_FETCH_BUNDLE_ID) {
+        headers['x-app-identifier'] = SITES_FETCH_BUNDLE_ID;
+    }
+    return headers;
+}
+
+function embeddedSitesPayload(): NexradSitesPayload {
+    return nexradSitesDefault as NexradSitesPayload;
+}
+
 export function loadNexradSitesPayload(): Promise<NexradSitesPayload> {
     if (nexradSitesPayloadPromise) {
         return nexradSitesPayloadPromise;
     }
-    nexradSitesPayloadPromise = fetch(sitesUrl)
-        .then((response) => {
-            if (!response.ok) throw new Error(`nexrad.json fetch failed: HTTP ${response.status}`);
-            return response.json() as Promise<NexradSitesPayload>;
-        })
-        .catch((error) => {
+    nexradSitesPayloadPromise = (async (): Promise<NexradSitesPayload> => {
+        const url = sitesFetchUrl();
+        const headers = sitesFetchHeaders();
+        const headerKeys = headers ? Object.keys(headers).join(',') : '';
+        nexradArchiveDiag('sites.fetch.start', {
+            canonicalUrl: sitesUrl,
+            fetchUrl: redactApiKeyFromUrl(url),
+            hasApiKeyQuery: url.includes('apiKey='),
+            headerKeys: headerKeys || '(none)',
+            apiKeyLen: SITES_FETCH_API_KEY.length,
+            bundleIdLen: SITES_FETCH_BUNDLE_ID.length,
+        });
+        try {
+            const response = await fetch(url, headers ? { headers } : undefined);
+            if (response.ok) {
+                nexradArchiveDiag('sites.fetch.ok', {
+                    status: response.status,
+                    canonicalUrl: sitesUrl,
+                });
+                return (await response.json()) as NexradSitesPayload;
+            }
+            if (sitesUrl.startsWith('https://')) {
+                console.warn(
+                    `[mapsgl] nexrad.json HTTP ${response.status} for ${sitesUrl} — using embedded site list`,
+                );
+                nexradArchiveDiag('sites.fetch.fallbackEmbedded', {
+                    httpStatus: response.status,
+                    reason: 'HTTPS non-OK — CloudFront may not host /data/nexrad.json; embedded list used',
+                    canonicalUrl: sitesUrl,
+                });
+                return embeddedSitesPayload();
+            }
+            throw new Error(`nexrad.json fetch failed: HTTP ${response.status}`);
+        } catch (error) {
+            if (sitesUrl.startsWith('https://')) {
+                console.warn('[mapsgl] nexrad.json load failed — using embedded site list:', error);
+                nexradArchiveDiag('sites.fetch.catchFallbackEmbedded', {
+                    message: error instanceof Error ? error.message : String(error),
+                    canonicalUrl: sitesUrl,
+                });
+                return embeddedSitesPayload();
+            }
             console.error('[mapsgl] Could not load nexrad.json:', error);
             nexradSitesPayloadPromise = null;
             throw error;
-        });
+        }
+    })();
     return nexradSitesPayloadPromise;
 }
 

package/src/nexrad/nexradArchiveCache.ts

@@ -1,66 +1,286 @@
-// Shared archive cache for decoded NEXRAD sweep frames.
-// Lives in a separate module so RadarLayer and GlobalStateContext can both access it
-// without creating a circular import dependency.
-//
-// Rolling cache across all radar sites: we do NOT clear on station or variable change,
-// so returning to a previously viewed site reuses cached frames. When the cache exceeds
-// MAX_ARCHIVE_CACHE_ENTRIES, the oldest entries (by insertion order) are evicted.
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-export type DecodedRadarFrame = {
-    gateData: Uint8Array;
-    nRays: number;
-    nGates: number;
-    stationLat: number;
-    stationLon: number;
-    firstGateKm: number;
-    gateWidthKm: number;
-    valueScale: number;
-    valueOffset: number;
-    rayBoundariesDeg: Float32Array;
-    /** Nyquist velocity (m/s) from Level-II archive header; used for VEL readout (aguacero-frontend parity). */
-    embeddedNyquistMs?: number | null;
-};
-
-// ─── Cache storage ────────────────────────────────────────────────────────────
-
-// Rolling cache size. Keeps decoded frames across site/variable switches; evicts oldest when over.
-// ~14 tilts × ~72 time steps ≈ 1008 frames per site; 4 sites ≈ 4k frames.
-const MAX_ARCHIVE_CACHE_ENTRIES = 5000;
-
-export const archiveCache = new Map<string, DecodedRadarFrame | null>();
-
-export function setArchiveCache(url: string, archive: DecodedRadarFrame | null): void {
-    archiveCache.delete(url);
-    archiveCache.set(url, archive);
-    while (archiveCache.size > MAX_ARCHIVE_CACHE_ENTRIES) {
-        const oldestKey = archiveCache.keys().next().value;
-        if (!oldestKey) break;
-        archiveCache.delete(oldestKey);
-    }
-}
-
-// ─── Optional explicit eviction ────────────────────────────────────────────────
-
-/**
- * Remove all archiveCache entries that belong to a given radar station.
- * Not used on station change (rolling cache); available for manual/optional clearing.
- */
-export function clearArchiveCacheForStation(stationId: string): void {
-    const prefix = `/${stationId}_`;
-    for (const url of Array.from(archiveCache.keys())) {
-        if (url.includes(prefix)) archiveCache.delete(url);
-    }
-}
-
-/**
- * Remove all archiveCache entries for a specific station + variable combination.
- * Not used on variable change (rolling cache); available for manual/optional clearing.
- */
-export function clearArchiveCacheForStationVariable(stationId: string, variable: string): void {
-    const prefix = `/${stationId}_${variable}_`;
-    for (const url of Array.from(archiveCache.keys())) {
-        if (url.includes(prefix)) archiveCache.delete(url);
-    }
-}
+// Parity with aguacero-frontend `src/components/Map/layers/radar/nexradArchiveCache.ts`.
+// Listing-synced pruning + ref-counted clears; hard caps as failsafe.
+//
+// ─── Public URL bases (must match radarArchiveCore `objectKeyToUrl`) ───────────
+
+export const NEXRAD_ARCHIVE_LEVEL2_BASE_URL = 'https://d3dc62msmxkrd7.cloudfront.net/level-2';
+export const NEXRAD_ARCHIVE_LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type DecodedRadarFrame = {
+    gateData: Uint8Array;
+    nRays: number;
+    nGates: number;
+    stationLat: number;
+    stationLon: number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    valueScale: number;
+    valueOffset: number;
+    azimuthsDeg?: Float32Array;
+    rayBoundariesDeg: Float32Array;
+    embeddedNyquistMs?: number | null;
+};
+
+// ─── Cache storage ────────────────────────────────────────────────────────────
+
+const MAX_ARCHIVE_CACHE_ENTRIES = 400;
+const MAX_ARCHIVE_CACHE_BYTES = 180 * 1024 * 1024;
+
+export const archiveCache = new Map<string, DecodedRadarFrame | null>();
+
+let pruneAllowlistObjectKeys: ReadonlySet<string> | null = null;
+let pruneSupplementalObjectKeys: ReadonlySet<string> = new Set();
+
+export function setNexradArchivePruneSupplementalObjectKeys(keys: Set<string> | null): void {
+    pruneSupplementalObjectKeys = keys ?? new Set();
+}
+
+export function setNexradArchivePruneAllowlist(allowed: ReadonlySet<string> | null): void {
+    pruneAllowlistObjectKeys = allowed;
+}
+
+function canInsertCacheKey(cacheKey: string, frame: DecodedRadarFrame | null): boolean {
+    if (frame == null) return true;
+    if (pruneAllowlistObjectKeys == null) return true;
+    const o = extractObjectKeyFromCacheKey(cacheKey);
+    if (o == null) return true;
+    if (pruneAllowlistObjectKeys.has(o)) return true;
+    if (pruneSupplementalObjectKeys.has(o)) return true;
+    return false;
+}
+
+function estimateFrameBytes(value: DecodedRadarFrame | null | undefined): number {
+    if (value == null) return 0;
+    const g = value.gateData;
+    const r = value.rayBoundariesDeg;
+    const a = value.azimuthsDeg;
+    return (g?.byteLength ?? 0) + (r?.byteLength ?? 0) + (a?.byteLength ?? 0);
+}
+
+let cacheBytesTotal = 0;
+
+let onArchiveCacheKeysRemoved: ((keys: readonly string[]) => void) | null = null;
+
+export function setArchiveCacheKeyRemovalListener(fn: ((keys: readonly string[]) => void) | null): void {
+    onArchiveCacheKeysRemoved = fn;
+}
+
+function emitArchiveCacheKeysRemoved(keys: string[]): void {
+    if (keys.length === 0) return;
+    onArchiveCacheKeysRemoved?.(keys);
+}
+
+function recomputeCacheBytes(): void {
+    let n = 0;
+    for (const v of archiveCache.values()) {
+        n += estimateFrameBytes(v);
+    }
+    cacheBytesTotal = n;
+}
+
+function evictOldestWhileOverCap(): void {
+    const removed: string[] = [];
+    while (archiveCache.size > MAX_ARCHIVE_CACHE_ENTRIES || cacheBytesTotal > MAX_ARCHIVE_CACHE_BYTES) {
+        const oldestKey = archiveCache.keys().next().value;
+        if (!oldestKey) break;
+        const v = archiveCache.get(oldestKey);
+        archiveCache.delete(oldestKey);
+        removed.push(oldestKey);
+        cacheBytesTotal -= estimateFrameBytes(v);
+        if (cacheBytesTotal < 0) recomputeCacheBytes();
+    }
+    emitArchiveCacheKeysRemoved(removed);
+}
+
+export function setArchiveCache(cacheKey: string, archive: DecodedRadarFrame | null): void {
+    if (archive && !canInsertCacheKey(cacheKey, archive)) {
+        return;
+    }
+    const prev = archiveCache.get(cacheKey);
+    if (prev !== undefined) {
+        cacheBytesTotal -= estimateFrameBytes(prev);
+    }
+    archiveCache.delete(cacheKey);
+    archiveCache.set(cacheKey, archive);
+    if (archive) {
+        cacheBytesTotal += estimateFrameBytes(archive);
+    }
+    evictOldestWhileOverCap();
+}
+
+export function extractObjectKeyFromCacheKey(cacheKey: string): string | null {
+    const m = cacheKey.match(/:([A-Za-z0-9_]+):((?:level2|level3))(?:\|.*)?$/i);
+    if (!m || m.index == null || m.index < 1) return null;
+    const urlPart = cacheKey.slice(0, m.index);
+    return objectKeyFromArchiveUrlString(urlPart);
+}
+
+export function objectKeyFromArchiveUrlString(url: string): string | null {
+    for (const base of [NEXRAD_ARCHIVE_LEVEL2_BASE_URL, NEXRAD_ARCHIVE_LEVEL3_BASE_URL]) {
+        const prefix = base.endsWith('/') ? base : `${base}/`;
+        if (url.startsWith(prefix)) {
+            return url.slice(prefix.length);
+        }
+    }
+    if (url.startsWith('http')) {
+        try {
+            const u = new URL(url);
+            const p = u.pathname.replace(/^\/+/, '');
+            if (p.startsWith('level-2/')) return p.slice('level-2/'.length);
+            return p || null;
+        } catch {
+            return null;
+        }
+    }
+    return null;
+}
+
+type RadarLayerListPayload = {
+    timeToKeyMap?: Record<string, string>;
+    level3MotionTimeToKeyMap?: Record<string, string | undefined> | null;
+    unixTimes?: number[];
+};
+
+export function buildNexradArchiveAllowedObjectKeySet(
+    layers: Record<string, RadarLayerListPayload | undefined>,
+    radarLayerKeys: string[],
+    _matchedByRadarKey: Record<string, number | null | undefined>
+): Set<string> {
+    const s = new Set<string>();
+    for (const radarKey of radarLayerKeys) {
+        const L = layers[radarKey];
+        if (!L?.timeToKeyMap) continue;
+        for (const o of Object.values(L.timeToKeyMap)) {
+            if (o) s.add(o);
+        }
+        const mm = L.level3MotionTimeToKeyMap;
+        if (mm && typeof mm === 'object') {
+            for (const o of Object.values(mm)) {
+                if (o) s.add(o);
+            }
+        }
+    }
+    return s;
+}
+
+/**
+ * True if the cache key is for this station and radar variable (`url:VAR:level2|level3[|motion]`).
+ */
+export function archiveCacheKeyMatchesStationVariable(
+    cacheKey: string,
+    stationId: string,
+    variable: string,
+): boolean {
+    if (!stationId || !variable) return false;
+    const v = variable.toUpperCase();
+    const m = cacheKey.match(/:([A-Za-z0-9_]+):((?:level2|level3))(?:\|.*)?$/i);
+    if (!m || m[1].toUpperCase() !== v) return false;
+    const sid = stationId.toUpperCase();
+    const o = extractObjectKeyFromCacheKey(cacheKey);
+    if (o) {
+        return o.toUpperCase().startsWith(`${sid}_`);
+    }
+    return cacheKey.toUpperCase().includes(`/${sid}_`);
+}
+
+/**
+ * Best-effort sweep time (unix sec) from a NEXRAD S3 object key.
+ */
+export function parseNexradS3ObjectKeySweepUnixSec(objectKey: string): number | null {
+    if (!objectKey) return null;
+    const l2 = objectKey.match(/_(\d{10,12})_g[12](?:\.bin)?$/i);
+    if (l2) {
+        const u = parseInt(l2[1], 10);
+        if (u > 1e9 && u < 2e10) return u;
+    }
+    const m = objectKey.match(/_(\d{4})_(\d{2})_(\d{2})_(\d{2})_(\d{2})_(\d{2})(?:\.\w+)?$/);
+    if (m) {
+        const [, y, mo, d, h, mi, s] = m;
+        const unix = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) / 1000;
+        return Number.isFinite(unix) ? unix : null;
+    }
+    return null;
+}
+
+export function pruneArchiveCacheOutsideObservationalWindow(minSec: number, nowSec: number): void {
+    const removed: string[] = [];
+    for (const key of Array.from(archiveCache.keys())) {
+        const o = extractObjectKeyFromCacheKey(key);
+        if (o == null) {
+            continue;
+        }
+        if (pruneSupplementalObjectKeys.has(o)) continue;
+        const t = parseNexradS3ObjectKeySweepUnixSec(o);
+        if (t == null) {
+            continue;
+        }
+        if (t < minSec || t > nowSec) {
+            const v = archiveCache.get(key);
+            archiveCache.delete(key);
+            removed.push(key);
+            cacheBytesTotal -= estimateFrameBytes(v);
+        }
+    }
+    if (cacheBytesTotal < 0) recomputeCacheBytes();
+    evictOldestWhileOverCap();
+    emitArchiveCacheKeysRemoved(removed);
+}
+
+export function pruneArchiveCacheNotInAllowedObjectKeys(allowed: ReadonlySet<string>): void {
+    const removed: string[] = [];
+    for (const key of Array.from(archiveCache.keys())) {
+        const o = extractObjectKeyFromCacheKey(key);
+        if (o == null) {
+            const val = archiveCache.get(key);
+            archiveCache.delete(key);
+            removed.push(key);
+            cacheBytesTotal -= estimateFrameBytes(val);
+            continue;
+        }
+        if (allowed.has(o) || pruneSupplementalObjectKeys.has(o)) continue;
+        const v = archiveCache.get(key);
+        archiveCache.delete(key);
+        removed.push(key);
+        cacheBytesTotal -= estimateFrameBytes(v);
+    }
+    if (cacheBytesTotal < 0) recomputeCacheBytes();
+    evictOldestWhileOverCap();
+    emitArchiveCacheKeysRemoved(removed);
+}
+
+export function clearArchiveCacheForStation(stationId: string): void {
+    if (!stationId) return;
+    const prefix = `/${stationId}_`;
+    const removed: string[] = [];
+    for (const key of Array.from(archiveCache.keys())) {
+        if (key.includes(prefix)) {
+            const v = archiveCache.get(key);
+            archiveCache.delete(key);
+            removed.push(key);
+            cacheBytesTotal -= estimateFrameBytes(v);
+        }
+    }
+    if (cacheBytesTotal < 0) recomputeCacheBytes();
+    evictOldestWhileOverCap();
+    emitArchiveCacheKeysRemoved(removed);
+}
+
+/**
+ * Remove decoded frames for a station + radar variable. Keys are `...:VAR:level2|level3`, not in the S3 path.
+ */
+export function clearArchiveCacheForStationVariable(stationId: string, variable: string): void {
+    if (!stationId || !variable) return;
+    const removed: string[] = [];
+    for (const key of Array.from(archiveCache.keys())) {
+        if (!archiveCacheKeyMatchesStationVariable(key, stationId, variable)) continue;
+        const val = archiveCache.get(key);
+        archiveCache.delete(key);
+        removed.push(key);
+        cacheBytesTotal -= estimateFrameBytes(val);
+    }
+    if (cacheBytesTotal < 0) recomputeCacheBytes();
+    evictOldestWhileOverCap();
+    emitArchiveCacheKeysRemoved(removed);
+}