@aguacerowx/mapsgl 0.0.57 → 0.0.59

package/src/nexrad/radarArchiveCore.ts

@@ -1,1974 +1,1987 @@
-/* eslint-disable */
-// Vendored from aguacero-frontend RadarLayer.tsx — fetch/decode only (no React).
-import { Buffer } from 'buffer';
-import * as bzip from 'seek-bzip';
-import {
-    getNexradLevel3EntryByRadarKey,
-    level3EetHeightKmFromLevel,
-    level3ValuePacking,
-    nexradLevel3IsHydrometeorClassification,
-    nexradLevel3UsesTiltIndexedS3Products,
-    nexradLevel3S3ProductForSiteTilt,
-    type Level3DecodeMode,
-} from './nexradLevel3Products.js';
-import {
-    applyLevel3StormRelativeToFrame,
-    parseLevel3StormMotionFromBuffer,
-    pickNearestLevel3ObjectKey,
-} from './level3StormRelative.js';
-import type { NexradSite } from './PreprocessedSweepParser.js';
-import { archiveCache, setArchiveCache, type DecodedRadarFrame } from './nexradArchiveCache.js';
-import { loadNexradSites } from './loadNexradSites.js';
-export { setNexradSitesJsonUrl, setNexradSitesFetchAuth } from './loadNexradSites.js';
-import { sampleNexradFrameAtLatLon } from './nexradCrossSectionSampleAtLatLon.js';
-import { decodeRadarSlotMessage, type DecodeSlotRequest } from './radarDecodeSlot.js';
-import { nexradArchiveDiag, redactApiKeyFromUrl } from './nexradArchiveDiag.js';
-
-// seek-bzip pulls in node-bzip paths that use `new Buffer()` as a global; browsers have no Buffer.
-if (typeof (globalThis as { Buffer?: typeof Buffer }).Buffer === 'undefined') {
-    (globalThis as { Buffer: typeof Buffer }).Buffer = Buffer;
-}
-
-/** RN/Hermes has no global {@link DOMException}; keep AbortError semantics for fetch abort paths. */
-function createAbortError(message = 'Aborted'): Error {
-    const g = globalThis as typeof globalThis & { DOMException?: typeof DOMException };
-    if (typeof g.DOMException !== 'undefined') {
-        return new g.DOMException(message, 'AbortError');
-    }
-    const err = new Error(message);
-    err.name = 'AbortError';
-    return err;
-}
-
-function isAbortError(err: unknown): boolean {
-    if (err == null || typeof err !== 'object') return false;
-    return (err as Error).name === 'AbortError';
-}
-
-let NEXRAD_ARCHIVE_API_KEY = '';
-/** Same as {@link AguaceroCore} grid fetches: `x-app-identifier` on React Native when set. */
-let NEXRAD_ARCHIVE_BUNDLE_ID = '';
-
-export function setNexradArchiveApiKey(k: string) {
-    NEXRAD_ARCHIVE_API_KEY = k || '';
-}
-
-export function setNexradArchiveBundleId(bundleId: string) {
-    NEXRAD_ARCHIVE_BUNDLE_ID = bundleId || '';
-}
-
-/** Match {@link AguaceroCore} `urlWithApiKeyParam` for the same CloudFront distribution. */
-function cloudFrontUrlWithApiKeyQuery(baseUrl: string): string {
-    if (!NEXRAD_ARCHIVE_API_KEY) return baseUrl;
-    const sep = baseUrl.includes('?') ? '&' : '?';
-    return `${baseUrl}${sep}apiKey=${NEXRAD_ARCHIVE_API_KEY}`;
-}
-
-/** Level-II: match AguaceroCore grid `fetch` headers (x-api-key, x-app-identifier on RN when bundleId set) plus Range. */
-function level2CloudFrontFetchHeaders(range: string | undefined): Record<string, string> {
-    const headers: Record<string, string> = {
-        'x-api-key': NEXRAD_ARCHIVE_API_KEY,
-    };
-    if (range !== undefined) {
-        headers['Range'] = range;
-    }
-    const g = globalThis as typeof globalThis & { navigator?: { product?: string } };
-    if (g.navigator?.product === 'ReactNative' && NEXRAD_ARCHIVE_BUNDLE_ID) {
-        headers['x-app-identifier'] = NEXRAD_ARCHIVE_BUNDLE_ID;
-    }
-    return headers;
-}
-
-type RadarDecodeWorkerResponse = {
-    type: 'DECODE_RESULT';
-    requestId: number;
-    gateData: Uint8Array | null;
-    nRays?: number;
-    nGates?: number;
-    stationLat?: number;
-    stationLon?: number;
-    firstGateKm?: number;
-    gateWidthKm?: number;
-    valueScale?: number;
-    valueOffset?: number;
-    rayBoundariesDeg?: Float32Array;
-    error?: string;
-};
-
-function shouldDecodeRadarOnMainThread(): boolean {
-    const g = globalThis as typeof globalThis & { navigator?: { product?: string } };
-    return typeof Worker === 'undefined' || g.navigator?.product === 'ReactNative';
-}
-
-/** Hermes/RN has no web Workers; mirror Worker.postMessage/onmessage on the JS thread. */
-class MainThreadRadarDecodeWorker implements Pick<Worker, 'postMessage' | 'onmessage' | 'onerror' | 'terminate'> {
-    onmessage: ((ev: MessageEvent<RadarDecodeWorkerResponse>) => void) | null = null;
-    onerror: ((ev: ErrorEvent) => void) | null = null;
-
-    postMessage(data: unknown): void {
-        const msg = data as DecodeSlotRequest;
-        if (!msg || msg.type !== 'DECODE_SLOT') return;
-        queueMicrotask(() => {
-            try {
-                const response = decodeRadarSlotMessage(msg);
-                this.onmessage?.({ data: response } as MessageEvent<RadarDecodeWorkerResponse>);
-            } catch (error) {
-                this.onmessage?.({
-                    data: {
-                        type: 'DECODE_RESULT',
-                        requestId: msg.requestId,
-                        gateData: null,
-                        error: error instanceof Error ? error.message : 'Main-thread radar decode failed',
-                    },
-                } as MessageEvent<RadarDecodeWorkerResponse>);
-            }
-        });
-    }
-
-    terminate(): void {}
-}
-
-function createRadarDecodeWorker(): Worker {
-    if (shouldDecodeRadarOnMainThread()) {
-        return new MainThreadRadarDecodeWorker() as unknown as Worker;
-    }
-    return new Worker(new URL('./radarDecode.worker.bundled.js', import.meta.url), { type: 'module' });
-}
-
-const LEVEL2_BASE_URL = 'https://d3dc62msmxkrd7.cloudfront.net/level-2';
-const LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
-
-const PREFETCH_DELAY_MS = 0;
-const PREFETCH_CONCURRENCY = 6;
-
-/** Underscore-style throttle for no-arg work — coalesces bursts (slider scrub) without delaying the first call. */
-function throttleVoid(fn: () => void, waitMs: number): () => void {
-    let timeout: ReturnType<typeof setTimeout> | null = null;
-    let previous = 0;
-    return () => {
-        const now = Date.now();
-        const remaining = waitMs - (now - previous);
-        if (remaining <= 0 || remaining > waitMs) {
-            if (timeout) {
-                clearTimeout(timeout);
-                timeout = null;
-            }
-            previous = now;
-            fn();
-        } else if (!timeout) {
-            timeout = setTimeout(() => {
-                timeout = null;
-                previous = Date.now();
-                fn();
-            }, remaining);
-        }
-    };
-}
-
-/**
- * Level-III KDP/N0H: throttle runSlot so rapid slider motion coalesces **fetches** (~10/s max) while a trailing
- * edge still applies the final time. MapboxRadarLayer caches the polar mesh on layout + coarse ray-boundary
- * fingerprint so scrubbing is fast while sweep registration stays geographic.
- */
-function createLatestPayloadThrottle(waitMs: number): (run: () => void) => void {
-    let latest: (() => void) | null = null;
-    const runLatest = () => {
-        const fn = latest;
-        latest = null;
-        fn?.();
-    };
-    const throttled = throttleVoid(runLatest, waitMs);
-    return (run: () => void) => {
-        latest = run;
-        throttled();
-    };
-}
-
-const azimuthKeyedRunSlotThrottleBySlot = new Map<string, ReturnType<typeof createLatestPayloadThrottle>>();
-
-function getAzimuthKeyedRunSlotThrottle(slotLayerId: string): (run: () => void) => void {
-    let t = azimuthKeyedRunSlotThrottleBySlot.get(slotLayerId);
-    if (!t) {
-        t = createLatestPayloadThrottle(110);
-        azimuthKeyedRunSlotThrottleBySlot.set(slotLayerId, t);
-    }
-    return t;
-}
-const DECODE_WORKER_POOL_SIZE = 2;
-const PREFETCH_WORKER_START_INDEX = 1;
-
-// ─── Fetch / parse with deduplication ────────────────────────────────────────
-
-// Tracks in-flight fetches so concurrent calls for the same URL share one request.
-const inflightFetches = new Map<string, Promise<DecodedRadarFrame | null>>();
-const inflightFetchMeta = new Map<
-    string,
-    {
-        requestId: number;
-        startedAt: number;
-        callers: number;
-        objectKey: string;
-        radarVariable: string;
-        radarSource: 'level2' | 'level3';
-        priority: 'display' | 'prefetch';
-    }
->();
-let radarFetchRequestSeq = 0;
-
-let radarDecodeWorkers: Worker[] = [];
-let radarDecodeRequestId = 0;
-const radarDecodePending = new Map<number, {
-    resolve: (frame: DecodedRadarFrame | null) => void;
-    reject: (error: Error) => void;
-}>();
-const radarDecodeRequestMeta = new Map<number, { objectKey: string; workerIndex: number }>();
-let radarDecodePrefetchWorkerIndex = PREFETCH_WORKER_START_INDEX;
-
-function createDecodeWorker(workerIndex: number): Worker {
-    const worker = createRadarDecodeWorker();
-    worker.onmessage = (event: MessageEvent<RadarDecodeWorkerResponse>) => {
-        const message = event.data;
-        if (!message || message.type !== 'DECODE_RESULT') return;
-        const pending = radarDecodePending.get(message.requestId);
-        if (!pending) return;
-        radarDecodePending.delete(message.requestId);
-        radarDecodeRequestMeta.delete(message.requestId);
-        if (message.error) {
-            pending.reject(new Error(message.error));
-            return;
-        }
-        if (
-            !message.gateData
-            || typeof message.nRays !== 'number'
-            || typeof message.nGates !== 'number'
-            || typeof message.stationLat !== 'number'
-            || typeof message.stationLon !== 'number'
-            || typeof message.firstGateKm !== 'number'
-            || typeof message.gateWidthKm !== 'number'
-            || typeof message.valueScale !== 'number'
-            || typeof message.valueOffset !== 'number'
-            || !(message.rayBoundariesDeg instanceof Float32Array)
-        ) {
-            pending.resolve(null);
-            return;
-        }
-        pending.resolve({
-            gateData: message.gateData,
-            nRays: message.nRays,
-            nGates: message.nGates,
-            stationLat: message.stationLat,
-            stationLon: message.stationLon,
-            firstGateKm: message.firstGateKm,
-            gateWidthKm: message.gateWidthKm,
-            valueScale: message.valueScale,
-            valueOffset: message.valueOffset,
-            rayBoundariesDeg: message.rayBoundariesDeg,
-        });
-    };
-    worker.onerror = (error) => {
-        radarDecodePending.forEach(({ reject }) => reject(new Error(error.message || 'Radar decode worker failed')));
-        radarDecodePending.clear();
-        radarDecodeRequestMeta.clear();
-    };
-    return worker;
-}
-
-function getRadarDecodeWorkers(): Worker[] {
-    if (radarDecodeWorkers.length > 0) return radarDecodeWorkers;
-    radarDecodeWorkers = Array.from({ length: DECODE_WORKER_POOL_SIZE }, (_, idx) => createDecodeWorker(idx));
-    return radarDecodeWorkers;
-}
-
-function getDecodeWorkerForPriority(priority: 'display' | 'prefetch'): { worker: Worker; workerIndex: number } {
-    const workers = getRadarDecodeWorkers();
-    if (priority === 'display' || workers.length === 1) {
-        return { worker: workers[0], workerIndex: 0 };
-    }
-    const prefetchWorkerCount = Math.max(workers.length - PREFETCH_WORKER_START_INDEX, 1);
-    const offset = (radarDecodePrefetchWorkerIndex - PREFETCH_WORKER_START_INDEX + prefetchWorkerCount) % prefetchWorkerCount;
-    const workerIndex = PREFETCH_WORKER_START_INDEX + offset;
-    radarDecodePrefetchWorkerIndex = PREFETCH_WORKER_START_INDEX + ((offset + 1) % prefetchWorkerCount);
-    return { worker: workers[Math.min(workerIndex, workers.length - 1)], workerIndex: Math.min(workerIndex, workers.length - 1) };
-}
-
-/** Get physical value at lat/lon from a decoded radar frame. Returns null if outside coverage or no data. */
-function getSampleAtLatLonForRadarFrame(
-    frame: DecodedRadarFrame,
-    lat: number,
-    lon: number,
-    smoothPolar: boolean,
-): { value: number; groundRangeKm: number } | null {
-    return sampleNexradFrameAtLatLon(frame, lat, lon, { smoothPolar });
-}
-
-export function objectKeyToUrl(objectKey: string, radarSource: 'level2' | 'level3' = 'level2'): string {
-    if (objectKey.startsWith('http')) return objectKey;
-    const baseUrl = radarSource === 'level3' ? LEVEL3_BASE_URL : LEVEL2_BASE_URL;
-    return `${baseUrl.replace(/\/$/, '')}/${objectKey}`;
-}
-
-class Level3Raf {
-    private offset = 0;
-    private view: DataView;
-    private bytes: Uint8Array;
-
-    constructor(input: Uint8Array | ArrayBuffer) {
-        this.bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
-        this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
-    }
-
-    getPos(): number { return this.offset; }
-    getLength(): number { return this.bytes.length; }
-    seek(pos: number): void { this.offset = pos; }
-    skip(delta: number): void { this.offset += delta; }
-    read(bytes = 1): Uint8Array {
-        const out = this.bytes.subarray(this.offset, this.offset + bytes);
-        this.offset += bytes;
-        return out;
-    }
-    readByte(): number {
-        const v = this.view.getUint8(this.offset);
-        this.offset += 1;
-        return v;
-    }
-    readShort(): number {
-        const v = this.view.getInt16(this.offset, false);
-        this.offset += 2;
-        return v;
-    }
-    readUShort(): number {
-        const v = this.view.getUint16(this.offset, false);
-        this.offset += 2;
-        return v;
-    }
-    readInt(): number {
-        const v = this.view.getInt32(this.offset, false);
-        this.offset += 4;
-        return v;
-    }
-    readUInt32(): number {
-        const v = this.view.getUint32(this.offset, false);
-        this.offset += 4;
-        return v;
-    }
-    readString(bytes: number): string {
-        const slice = this.read(bytes);
-        return String.fromCharCode(...slice);
-    }
-}
-
-function concatUint8(a: Uint8Array, b: Uint8Array): Uint8Array {
-    const out = new Uint8Array(a.length + b.length);
-    out.set(a, 0);
-    out.set(b, a.length);
-    return out;
-}
-
-/**
- * NEXRAD Level-III: range to gate g (m) = g * range_scale_symbology * multiplier[message_code] + first_bin (m).
- * Without multipliers, super-res products (e.g. message 153 reflectivity, 154 velocity) decode ~4× too coarse in range.
- * Aligned with Py-ART / jjhelmus `PRODUCT_RANGE_RESOLUTION`.
- */
-const LEVEL3_PRODUCT_RANGE_SCALE_MUL: Record<number, number> = {
-    19: 1, 20: 2, 25: 0.25, 27: 1, 28: 0.25, 30: 1, 32: 1, 34: 1, 56: 1,
-    57: 1000,
-    78: 1, 79: 1, 80: 1, 94: 1, 99: 0.25,
-    134: 1000, 135: 1000, 138: 1,
-    153: 0.25, 154: 0.25, 155: 0.25, 159: 0.25, 161: 0.25, 163: 0.25, 165: 0.25,
-    166: 0.25, 167: 0.25, 168: 0.25,
-    169: 1000, 170: 1000, 171: 1000, 172: 1000, 173: 1000, 174: 1000, 175: 1000,
-    /** Py-ART `PRODUCT_RANGE_RESOLUTION`: 176/177 are digital-style radials (0.25×), not 1 km like 169–175. */
-    176: 0.25, 177: 0.25,
-    181: 150, 182: 150, 186: 300,
-};
-
-/**
- * MetPy `GenericDigitalMapper` products: symbology levels map as (L - offset) / scale
- * where scale/offset are big-endian float32 from PDB thr1–thr2 and thr3–thr4 (see MetPy `nexrad.float32`).
- * DAA (170) was incorrectly decoded as min + L*inc, producing bogus inches and fan artifacts.
- */
-const LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES = new Set([
-    159, 161, 163, 167, 168,
-    170, 172, 173, 174, 175, 176,
-]);
-
-/**
- * NWS digital accumulation (MetPy `GenericDigitalMapper`) carries **depth in millimeters**.
- * Layer colormap / readout expect **inches** (see `nexradLevel3Products` precip packing).
- */
-const LEVEL3_GENERIC_DIGITAL_DEPTH_MM_TO_IN_PRODUCTS = new Set([170, 172, 173, 174, 175]);
-
-/**
- * MetPy `DigitalHMCMapper`: digital / hybrid hydrometeor classification (165, 177).
- * 8-bit radial (packet 0x0010): `lut[i] = i // 10` is the **1-based** NWS category (1=BI … 6=RA … 12=GH).
- * Fill colormap / `NEXRAD_HYDROMETEOR_CLASS_LABELS` use **0-based** indices in the same order → `floor(level/10) - 1`.
- * 150 = range-fold.
- * 4-bit raster / RLE (0xBA07, 0xAF1F): levels 2–15 → 0-based class index `level − 2`.
- */
-const LEVEL3_DIGITAL_HMC_PRODUCT_CODES = new Set([165, 177]);
-
-function level3PhysicalFromDigitalHmc(level: number, precision: 'byte' | 'nibble'): number | null {
-    if (!Number.isFinite(level)) return null;
-    if (precision === 'nibble') {
-        if (level < 2 || level > 15) return null;
-        return level - 2;
-    }
-    if (level === 150) return null;
-    if (level < 10 || level >= 256) return null;
-    const cls = Math.floor(level / 10) - 1;
-    if (cls < 0 || cls > 11) return null;
-    return cls;
-}
-
-/**
- * Per-product mm calibration before ÷25.4 for generic digital accumulation (170, 172–175).
- * 170 (DAA) field‑checked at 0.125. 172–175 were too low at 0.125, too high at 1.0; 0.5 still ~2× high
- * in the field → 0.25 for those products (halve again if needed).
- */
-function level3GenericDigitalAccumMmFactor(productCode: number): number {
-    switch (productCode) {
-        case 170: // DAA — 1‑hour digital accumulation array
-            return 0.125;
-        case 172: // Digital storm total accumulation (generic)
-        case 173: // DU3 — user‑selectable (e.g. 3‑hour)
-        case 174: // Digital one‑hour difference accumulation
-        case 175: // Digital storm total difference accumulation
-            return 0.25;
-        default:
-            return 1;
-    }
-}
-
-type Level3GenericDigitalParams = {
-    scale: number;
-    offset: number;
-    leadingFlags: number;
-    trailingFlags: number;
-    maxDataVal: number;
-};
-
-function level3UnpackFloat32FromThresholdPair(short0: number, short1: number): number {
-    const buf = new ArrayBuffer(4);
-    const view = new DataView(buf);
-    view.setUint16(0, short0 & 0xffff, false);
-    view.setUint16(2, short1 & 0xffff, false);
-    return view.getFloat32(0, false);
-}
-
-function parseLevel3GenericDigitalParams(dep: number[]): Level3GenericDigitalParams | null {
-    /**
-     * `raf.read(48)` is read **after** PDB fields through `el_num`, so this 24-short block is:
-     * dep[0]=dep3, dep[1]=thr1, dep[2]=thr2, … dep[16]=thr16, dep[17]=dep4, …
-     * MetPy GenericDigitalMapper: scale=float32(thr1,thr2), offset=float32(thr3,thr4),
-     * max=thr6, leading=thr7, trailing=thr8 → dep indices 1..8.
-     */
-    if (dep.length < 9) return null;
-    const scale = level3UnpackFloat32FromThresholdPair(dep[1], dep[2]);
-    const offset = level3UnpackFloat32FromThresholdPair(dep[3], dep[4]);
-    const maxDataVal = dep[6] & 0xffff;
-    const leadingFlags = dep[7];
-    const trailingFlags = dep[8];
-    if (!Number.isFinite(scale) || scale === 0 || !Number.isFinite(offset)) return null;
-    if (leadingFlags < 0 || leadingFlags > 255 || trailingFlags < 0 || trailingFlags > 255) return null;
-    if (maxDataVal < leadingFlags) return null;
-    return { scale, offset, leadingFlags, trailingFlags, maxDataVal };
-}
-
-function level3PhysicalFromGenericDigital(
-    level: number,
-    p: Level3GenericDigitalParams,
-    productCode: number,
-): number | null {
-    if (!Number.isFinite(level)) return null;
-    if (level < p.leadingFlags) return null;
-    const upper = p.maxDataVal - p.trailingFlags;
-    if (level > upper) return null;
-    let out = (level - p.offset) / p.scale;
-    if (!Number.isFinite(out)) return null;
-    if (LEVEL3_GENERIC_DIGITAL_DEPTH_MM_TO_IN_PRODUCTS.has(productCode)) {
-        out *= level3GenericDigitalAccumMmFactor(productCode);
-        out /= 25.4;
-    }
-    return out;
-}
-
-type Level3SymbologyMode =
-    | 'reflectivity'
-    /**
-     * MetPy `DigitalMapper` linear products (precip inches, etc.): phys = min + (L - 2) * inc.
-     * Kept separate from `reflectivity` so legacy/category-style symbology is unchanged.
-     */
-    | 'standard_digital'
-    /** Packet 0x0010: full-byte data levels; NEXRAD digital velocity uses threshold + (L-2)*inc. */
-    | 'digital_velocity_byte'
-    /**
-     * Packet 0xAF1F: 4-bit levels in RLE nibbles. Threshold+increment from the PDB only spans a
-     * small negative band (~−64…−57 m/s), so values fall entirely outside typical −30…+30 m/s
-     * colormaps and the map looks empty. Use a centered mapping (0 m/s ≈ level 8, ~4 m/s per step).
-     */
-    | 'digital_velocity_rle4';
-
-/**
- * Map symbology data level to a physical value (dBZ, m/s, etc.) depending on product/packet mode.
- */
-const LEVEL3_MSG134_PRODUCTS = new Set([134]);
-
-// Replace the reflectivity branch in level3PhysicalFromDataLevel:
-function level3PhysicalFromDataLevel(
-    level: number,
-    minimumDataValue: number,
-    dataIncrement: number,
-    mode: Level3SymbologyMode,
-    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
-): number | null {
-    if (!Number.isFinite(level)) return null;
-    if (mode === 'digital_velocity_byte') {
-        if (level < 2) return null;
-        return minimumDataValue + (level - 2) * dataIncrement;
-    }
-    if (mode === 'digital_velocity_rle4') {
-        if (level < 2) return null;
-        const MS_PER_STEP = 4;
-        const CENTER_LEVEL = 8;
-        return (level - CENTER_LEVEL) * MS_PER_STEP;
-    }
-    // Product 134 (Digital VIL): piecewise linear + log, params from threshold halfwords
-    if (msg134Params) {
-        if (level < 2) return null;
-        const { linearScale, linearOffset, logStart, logScale, logOffset } = msg134Params;
-        if (level < logStart) {
-            return (level - linearOffset) / linearScale;
-        } else {
-            return Math.exp((level - logOffset) / logScale);
-        }
-    }
-    if (mode === 'standard_digital') {
-        if (level < 2) return null;
-        return minimumDataValue + (level - 2) * dataIncrement;
-    }
-    if (level <= 1) return null;
-    return minimumDataValue + level * dataIncrement;
-}
-
-function parseLevel3Packet0010(
-    raf: Level3Raf,
-    minimumDataValue: number,
-    dataIncrement: number,
-    levelMode: Level3SymbologyMode,
-    l3ProductCode: number,
-    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
-    eetThresholds?: { dataMask: number; scale: number; offset: number } | null,
-    genericDigital?: Level3GenericDigitalParams | null,
-) {
-    const packetCode = raf.readUShort();
-    if (packetCode !== 16) throw new Error(`Unexpected packet code ${packetCode}`);
-    const firstBinMeters = raf.readShort();
-    let numberBins = raf.readShort();
-    raf.readShort(); // iSweepCenter
-    raf.readShort(); // jSweepCenter
-    const rangeScaleRaw = raf.readShort();
-    const numberRadials = raf.readShort();
-    // Py-ART: packet 16 sometimes has nbins ≠ per-radial nbytes; true gate count follows first radial header.
-    if (numberRadials > 0) {
-        const peek = raf.getPos();
-        const nbytesFirst = raf.readShort();
-        raf.seek(peek);
-        if (nbytesFirst !== numberBins) {
-            numberBins = nbytesFirst;
-        }
-    }
-    const radials: Array<{ startAngle: number; angleDelta: number; bins: Array<number | null> }> = [];
-    for (let r = 0; r < numberRadials; r++) {
-        const bytesInRadial = raf.readShort();
-        const startAngle = raf.readShort() / 10;
-        const angleDelta = raf.readShort() / 10;
-        const bins: Array<number | null> = [];
-        for (let i = 0; i < numberBins; i++) {
-            const level = raf.readByte();
-            if (eetThresholds) {
-                bins.push(
-                    level3EetHeightKmFromLevel(level, eetThresholds.dataMask, eetThresholds.scale, eetThresholds.offset),
-                );
-            } else if (LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)) {
-                bins.push(level3PhysicalFromDigitalHmc(level, 'byte'));
-            } else if (genericDigital) {
-                bins.push(level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode));
-            } else {
-                bins.push(level3PhysicalFromDataLevel(level, minimumDataValue, dataIncrement, levelMode, msg134Params));
-            }
-        }
-        if (bytesInRadial > numberBins) raf.skip(bytesInRadial - numberBins);
-        radials.push({ startAngle, angleDelta, bins });
-    }
-    return { firstBinMeters, numberBins, rangeScaleRaw, numberRadials, radials };
-}
-function parseLevel3PacketAF1F(
-    raf: Level3Raf,
-    minimumDataValue: number,
-    dataIncrement: number,
-    levelMode: Level3SymbologyMode,
-    l3ProductCode: number,
-    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
-    eetThresholds?: { dataMask: number; scale: number; offset: number } | null,
-    genericDigital?: Level3GenericDigitalParams | null,
-) {
-    const packetCode = raf.readUShort();
-    if (packetCode !== 0xAF1F) throw new Error(`Unexpected packet code ${packetCode}`);
-    const firstBinMeters = raf.readShort();
-    const numberBins = raf.readShort();
-    raf.readShort(); // iSweepCenter
-    raf.readShort(); // jSweepCenter
-    const rangeScaleRaw = raf.readShort();
-    const numRadials = raf.readShort();
-    const radials: Array<{ startAngle: number; angleDelta: number; bins: Array<number | null> }> = [];
-    for (let r = 0; r < numRadials; r++) {
-        const rleBytes = raf.readShort() * 2;
-        const startAngle = raf.readShort() / 10;
-        const angleDelta = raf.readShort() / 10;
-        const bins: Array<number | null> = [];
-        for (let i = 0; i < rleBytes; i++) {
-            const byte = raf.readByte();
-            const run = byte >> 4;
-            const level = byte & 0x0f;
-            const value = eetThresholds
-                ? level3EetHeightKmFromLevel(level, eetThresholds.dataMask, eetThresholds.scale, eetThresholds.offset)
-                : LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)
-                  ? level3PhysicalFromDigitalHmc(level, 'nibble')
-                  : genericDigital
-                    ? level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode)
-                    : level3PhysicalFromDataLevel(level, minimumDataValue, dataIncrement, levelMode, msg134Params);
-            for (let j = 0; j < run; j++) bins.push(value);
-        }
-        if (bins.length > numberBins) bins.length = numberBins;
-        while (bins.length < numberBins) bins.push(null);
-        radials.push({ startAngle, angleDelta, bins });
-    }
-    return { firstBinMeters, numberBins, rangeScaleRaw, numberRadials: numRadials, radials };
-}
-
-function buildRayBoundariesFromLevel3Radials(radials: any[]): Float32Array {
-    const n = radials.length;
-    const boundaries = new Float32Array(n + 1);
-    let prev = -Infinity;
-    for (let i = 0; i < n; i++) {
-        const startAngle = Number(radials[i]?.startAngle);
-        const angleDelta = Number(radials[i]?.angleDelta);
-        const start = Number.isFinite(startAngle) ? startAngle : 0;
-        const delta = Number.isFinite(angleDelta) && angleDelta > 0 ? angleDelta : 1;
-        let lower = start - delta * 0.5;
-        while (lower <= prev) lower += 360;
-        boundaries[i] = lower;
-        prev = lower;
-    }
-    const lastDeltaRaw = Number(radials[n - 1]?.angleDelta);
-    const lastDelta = Number.isFinite(lastDeltaRaw) && lastDeltaRaw > 0 ? lastDeltaRaw : 1;
-    boundaries[n] = boundaries[n - 1] + lastDelta;
-    return boundaries;
-}
-
-function encodeSigned16ToHiLo(value: number): [number, number] {
-    const signed = Math.max(-32768, Math.min(32767, value));
-    const raw = signed < 0 ? signed + 65536 : signed;
-    return [(raw >> 8) & 0xff, raw & 0xff];
-}
-
-function level3RadialSpatialScore(p: { numberBins: number; numberRadials: number } | null | undefined): number {
-    if (!p) return -1;
-    const nb = Number(p.numberBins);
-    const nr = Number(p.numberRadials);
-    if (!Number.isFinite(nb) || !Number.isFinite(nr) || nb <= 0 || nr <= 0) return -1;
-    return nb * nr;
-}
-
-type Level3RadialPick = { kind: 0x10 | 0xaf1f; packet: any };
-
-function level3RadialPickIsBetter(cand: Level3RadialPick, prev: Level3RadialPick | null): boolean {
-    const sC = level3RadialSpatialScore(cand.packet);
-    const sP = level3RadialSpatialScore(prev?.packet);
-    if (sC > sP) return true;
-    if (sC < sP) return false;
-    if (!prev) return true;
-    /** Same footprint: prefer full-byte digital radial (0x10) over 4-bit RLE (0xAF1F) for smoother velocity. */
-    if (cand.kind === 0x10 && prev.kind === 0xaf1f) return true;
-    return false;
-}
-
-/**
- * Advance past a non-radial symbology packet so later packets in the same layer can be read.
- * Caller must position RAF at the packet code; we consume code + body.
- * Uniform text (1, 8): u16 payload length then that many bytes (MetPy / ICD).
- */
-function trySkipLevel3OverlayPacket(raf: Level3Raf, packetCode: number, layerEnd: number): boolean {
-    const pos0 = raf.getPos();
-    if (packetCode !== 1 && packetCode !== 2 && packetCode !== 8) return false;
-    if (layerEnd - pos0 < 4) return false;
-    const codeRead = raf.readUShort();
-    if (codeRead !== packetCode) {
-        raf.seek(pos0);
-        return false;
-    }
-    const payloadBytes = raf.readUShort();
-    if (payloadBytes > layerEnd - raf.getPos()) {
-        raf.seek(pos0);
-        return false;
-    }
-    raf.skip(payloadBytes);
-    return true;
-}
-
-/** Symbology packet 0xBA07: raster image (RLE rows). MetPy `packet_map[0xba07]`. Used by NVL (57), EET, etc. */
-const LEVEL3_PACKET_RASTER_BA07 = 0xba07;
-/** First u32 after packet code; MetPy asserts this for raster payload. */
-const LEVEL3_RASTER_INNER_CODE = 0x800000c0;
-
-function unpackLevel3RasterRle(rowBytes: Uint8Array): number[] {
-    const unpacked: number[] = [];
-    for (let i = 0; i < rowBytes.length; i++) {
-        const b = rowBytes[i];
-        const run = b >> 4;
-        const val = b & 0x0f;
-        for (let j = 0; j < run; j++) unpacked.push(val);
-    }
-    return unpacked;
-}
-
-function level3CombineRasterScale(int16: number, frac16: number): number {
-    const i = Math.abs(int16);
-    const f = Math.abs(frac16) / 10000;
-    const s = i + f;
-    return s > 0 ? s : 1;
-}
-
-type Level3ParsedRaster = {
-    iStart: number;
-    jStart: number;
-    cellKmX: number;
-    cellKmY: number;
-    startXKm: number;
-    startYKm: number;
-    nCols: number;
-    nRows: number;
-    rows: number[][];
-};
-
-/**
- * Parse raster symbology (packet 0xBA07). RAF must be positioned at the packet code (first u16).
- * Leaves RAF at `layerEnd` on success or after skipping on failure.
- */
-function parseLevel3PacketRasterBA07(raf: Level3Raf, layerEnd: number, objectKey: string): Level3ParsedRaster | null {
-    const pos0 = raf.getPos();
-    const packetCode = raf.readUShort();
-    if (packetCode !== LEVEL3_PACKET_RASTER_BA07) {
-        raf.seek(pos0);
-        return null;
-    }
-    const room = layerEnd - raf.getPos();
-    if (room < 20) {
-        raf.seek(layerEnd);
-        return null;
-    }
-    const inner = raf.readUInt32();
-    if (inner !== LEVEL3_RASTER_INNER_CODE) {
-        raf.seek(layerEnd);
-        return null;
-    }
-    const iStart = raf.readShort();
-    const jStart = raf.readShort();
-    const xscaleInt = raf.readShort();
-    const xscaleFrac = raf.readShort();
-    const yscaleInt = raf.readShort();
-    const yscaleFrac = raf.readShort();
-    const numRows = raf.readUShort();
-    const packing = raf.readUShort();
-    if (packing !== 2) {
-        console.warn('[aguacero][nexrad-l3][raster-ba07-packing]', { objectKey, packing, hint: 'MetPy expects packing=2; raster parse skipped for this layer' });
-        raf.seek(layerEnd);
-        return null;
-    }
-    if (numRows <= 0 || numRows > 2000 || raf.getPos() > layerEnd) {
-        raf.seek(layerEnd);
-        return null;
-    }
-    const cellKmX = level3CombineRasterScale(xscaleInt, xscaleFrac);
-    const cellKmY = level3CombineRasterScale(yscaleInt, yscaleFrac);
-    /** Match MetPy: start corner from integer scales only (see `metpy.io.nexrad` `_unpack_packet_raster_data`). */
-    const startXKm = iStart * xscaleInt;
-    const startYKm = jStart * yscaleInt;
-    const rows: number[][] = [];
-    let nCols = -1;
-    for (let r = 0; r < numRows; r++) {
-        if (raf.getPos() + 2 > layerEnd) {
-            raf.seek(layerEnd);
-            return null;
-        }
-        const rowNumBytes = raf.readUShort();
-        if (rowNumBytes === 0 || raf.getPos() + rowNumBytes > layerEnd) {
-            raf.seek(layerEnd);
-            return null;
-        }
-        const rowBytes = raf.read(rowNumBytes);
-        const expanded = unpackLevel3RasterRle(rowBytes);
-        if (nCols < 0) nCols = expanded.length;
-        else if (expanded.length !== nCols) {
-            raf.seek(layerEnd);
-            return null;
-        }
-        rows.push(expanded);
-    }
-    if (nCols <= 0) {
-        raf.seek(layerEnd);
-        return null;
-    }
-    if (raf.getPos() < layerEnd) {
-        raf.seek(layerEnd);
-    }
-    return {
-        iStart,
-        jStart,
-        cellKmX,
-        cellKmY,
-        startXKm,
-        startYKm,
-        nCols,
-        nRows: numRows,
-        rows,
-    };
-}
-
-function level3RasterPdbScales(
-    decodeMode: Level3DecodeMode,
-    productCode: number,
-    minimumDataValue: number,
-    dataIncrement: number,
-    depProductDescriptionShorts: number[] | null,
-    objectKey: string,
-    genericDigital: Level3GenericDigitalParams | null,
-): {
-    minT: number;
-    dataInc: number;
-    symMode: Level3SymbologyMode;
-    vilLevelThresholds: number[] | null;
-} {
-    const minBad =
-        !Number.isFinite(minimumDataValue) || Math.abs(minimumDataValue) > 500;
-    const incBad = !Number.isFinite(dataIncrement) || dataIncrement <= 0;
-    const bad = minBad || incBad;
-    let minT = minimumDataValue;
-    let dataInc = dataIncrement;
-    let vilLevelThresholds: number[] | null = null;
-    /**
-     * NVL often encodes an invalid linear min (e.g. -32766 sentinel), while real level thresholds
-     * are present in product-description shorts 33..46 (values like 5,10,...,70 kg/m²).
-     * Prefer those thresholds when present so data-level 2..15 map to physically meaningful VIL.
-     */
-    if (
-        decodeMode === 'vil' &&
-        productCode === 57 &&
-        Array.isArray(depProductDescriptionShorts) &&
-        depProductDescriptionShorts.length >= 17 &&
-        depProductDescriptionShorts[1] <= -30000
-    ) {
-        const byLevel = new Array<number>(16).fill(Number.NaN);
-        let validCount = 0;
-        for (let level = 2; level <= 15; level++) {
-            const raw = depProductDescriptionShorts[level + 1];
-            if (Number.isFinite(raw) && raw > 0) {
-                byLevel[level] = raw;
-                validCount += 1;
-            }
-        }
-        if (validCount >= 8) {
-            vilLevelThresholds = byLevel;
-        }
-    }
-    if (bad) {
-        /** VIL: PDB min is often garbage; increment 0.1 is still valid. phys = minT + level*inc with level≥2 → use minT = -inc so level 2 → +inc (e.g. 0.1). */
-        if (decodeMode === 'vil' && minBad && !incBad && dataIncrement >= 0.05 && dataIncrement <= 2) {
-            minT = -dataIncrement;
-            dataInc = dataIncrement;
-        } else if (decodeMode === 'vil') {
-            minT = 0;
-            dataInc = 1;
-        } else if (decodeMode === 'precip') {
-            minT = 0;
-            dataInc = 0.25;
-        } else if (decodeMode === 'tops_kft') {
-            minT = 0;
-            dataInc = 1;
-        } else if (decodeMode === 'categorical') {
-            minT = 0;
-            dataInc = 1;
-        } else if (decodeMode === 'generic_physical') {
-            minT = -2;
-            dataInc = 0.05;
-        } else {
-            minT = -32;
-            dataInc = 0.5;
-        }
-    }
-    const symMode: Level3SymbologyMode =
-        decodeMode === 'velocity'
-            ? 'digital_velocity_byte'
-            : decodeMode === 'precip' && !genericDigital
-              ? 'standard_digital'
-              : 'reflectivity';
-    return { minT, dataInc, symMode, vilLevelThresholds };
-}
-
-/** Resample Cartesian raster (km east/north from radar) into the polar texture the Mapbox radar shader expects. */
-function level3RasterToPolarFrame(
-    raster: Level3ParsedRaster,
-    stationLat: number,
-    stationLon: number,
-    decodeMode: Level3DecodeMode,
-    minT: number,
-    dataInc: number,
-    symMode: Level3SymbologyMode,
-    vilLevelThresholds: number[] | null,
-    eetThresholds: { dataMask: number; scale: number; offset: number } | null,
-    valueScale: number,
-    valueOffset: number,
-    objectKey: string,
-    genericDigital: Level3GenericDigitalParams | null = null,
-    l3ProductCode = 0,
-): DecodedRadarFrame | null {
-    const { rows, nCols, nRows, startXKm, startYKm, cellKmX, cellKmY, iStart, jStart } = raster;
-    const widthKm = nCols * cellKmX;
-    const heightKm = nRows * cellKmY;
-    /**
-     * ICD raster I/J origin 0 with a square grid is a box **centered** on the radar (±half extent in km).
-     * Treating (0,0) as the southwest corner only covers the northeast quadrant — data appears displaced
-     * toward +x,+y (e.g. Atlantic for East Coast sites) and few polar samples hit the grid.
-     */
-    let originXK = startXKm;
-    let originYK = startYKm;
-    if (iStart === 0 && jStart === 0 && nCols === nRows && nCols >= 16) {
-        originXK = startXKm - widthKm / 2;
-        originYK = startYKm - heightKm / 2;
-    }
-    const xMin = originXK;
-    const xMax = originXK + widthKm;
-    const yMin = originYK;
-    const yMax = originYK + heightKm;
-    const corner = (x: number, y: number) => Math.hypot(x, y);
-    let maxR = corner(xMin, yMin);
-    maxR = Math.max(maxR, corner(xMax, yMin));
-    maxR = Math.max(maxR, corner(xMin, yMax));
-    maxR = Math.max(maxR, corner(xMax, yMax));
-    maxR = Math.min(460, Math.max(50, maxR * 1.02));
-
-    const nRays = 720;
-    const gateWidthKm = 0.5;
-    const nGates = Math.min(920, Math.max(64, Math.ceil(maxR / gateWidthKm)));
-    const firstGateKm = 0;
-
-    const gateData = new Uint8Array(nRays * nGates * 2);
-    const rayBoundariesDeg = new Float32Array(nRays + 1);
-    const deltaAz = 360 / nRays;
-    for (let i = 0; i <= nRays; i++) {
-        rayBoundariesDeg[i] = i * deltaAz - deltaAz * 0.5;
-    }
-
-    let samples = 0;
-    let nodata = 0;
-    for (let rayIdx = 0; rayIdx < nRays; rayIdx++) {
-        const azDeg = (rayIdx + 0.5) * deltaAz;
-        const azRad = (azDeg * Math.PI) / 180;
-        const sinAz = Math.sin(azRad);
-        const cosAz = Math.cos(azRad);
-        for (let g = 0; g < nGates; g++) {
-            const rKm = firstGateKm + (g + 0.5) * gateWidthKm;
-            const xKm = rKm * sinAz;
-            const yKm = rKm * cosAz;
-            const fc = (xKm - originXK) / cellKmX;
-            const fr = (yKm - originYK) / cellKmY;
-            const c = Math.floor(fc);
-            const r = Math.floor(fr);
-            let level: number | null = null;
-            if (c >= 0 && c < nCols && r >= 0 && r < nRows) {
-                level = rows[r][c] ?? null;
-            }
-            let phys: number | null = null;
-            if (level != null && Number.isFinite(level)) {
-                if (
-                    decodeMode === 'vil' &&
-                    vilLevelThresholds &&
-                    level >= 0 &&
-                    level < vilLevelThresholds.length &&
-                    Number.isFinite(vilLevelThresholds[level])
-                ) {
-                    phys = vilLevelThresholds[level];
-                } else if (decodeMode === 'tops_kft' && eetThresholds) {
-                    phys = level3EetHeightKmFromLevel(
-                        level,
-                        eetThresholds.dataMask,
-                        eetThresholds.scale,
-                        eetThresholds.offset,
-                    );
-                } else if (LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)) {
-                    phys = level3PhysicalFromDigitalHmc(level, 'nibble');
-                } else if (genericDigital) {
-                    phys = level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode);
-                } else {
-                    phys = level3PhysicalFromDataLevel(level, minT, dataInc, symMode);
-                }
-            }
-            if (phys == null || !Number.isFinite(phys)) {
-                nodata++;
-                const offset = (rayIdx * nGates + g) * 2;
-                gateData[offset] = 0x80;
-                gateData[offset + 1] = 0x00;
-                continue;
-            }
-            samples++;
-            const rawSigned = Math.round((phys - valueOffset) / valueScale);
-            const [hi, lo] = encodeSigned16ToHiLo(rawSigned);
-            const offset = (rayIdx * nGates + g) * 2;
-            gateData[offset] = hi;
-            gateData[offset + 1] = lo;
-        }
-    }
-    if (samples < 8) {
-        console.warn('[aguacero][nexrad-l3][raster-nearly-empty]', { objectKey, samples, nodata });
-        return null;
-    }
-    return {
-        gateData,
-        nRays,
-        nGates,
-        stationLat,
-        stationLon,
-        firstGateKm,
-        gateWidthKm,
-        valueScale,
-        valueOffset,
-        rayBoundariesDeg,
-    };
-}
-
-/**
- * Validate Level-III Product Description Block (PDB) start at `pos`.
- *
- * Two valid layouts are seen in the wild:
- * 1) Divider-first PDB (`0xFFFF`, then lat/lon)
- * 2) Message-header-first (`productCode`, ... , divider at +18, then lat/lon)
- *
- * Use strict plausibility checks so we don't lock onto random halfwords.
- */
-function isValidLevel3PdbStart(bytes: Uint8Array, pos: number): boolean {
-    const len = bytes.length;
-    if (pos + 14 > len) return false;
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    const latLonPlausible = (latMilli: number, lonMilli: number): boolean => {
-        const lat = latMilli / 1000;
-        const lon = lonMilli / 1000;
-        return (
-            lat >= -60 &&
-            lat <= 72 &&
-            lon >= -180 &&
-            lon <= 180 &&
-            Math.abs(lat) > 1 &&
-            Math.abs(lon) > 1
-        );
-    };
-
-    // Layout A: divider-first
-    if (bytes[pos] === 0xff && bytes[pos + 1] === 0xff) {
-        const latMilli = view.getInt32(pos + 2, false);
-        const lonMilli = view.getInt32(pos + 6, false);
-        return latLonPlausible(latMilli, lonMilli);
-    }
-
-    // Layout B: message-header-first (divider at +18, lat/lon at +20/+24)
-    if (pos + 28 <= len) {
-        const productCode = view.getUint16(pos, false);
-        const divider = view.getInt16(pos + 18, false);
-        if (productCode >= 1 && productCode <= 499 && divider === -1) {
-            const latMilli = view.getInt32(pos + 20, false);
-            const lonMilli = view.getInt32(pos + 24, false);
-            if (latLonPlausible(latMilli, lonMilli)) return true;
-        }
-    }
-
-    return false;
-}
-
-/**
- * PDB byte offset within the Level-III file (after optional SDUS trim).
- * NOAAPort/Unidata objects use a short ASCII preamble (SDUS line + product/site line) then binary.
- * A naive scan for 0xFFFF+lat/lon matches an *internal* digital divider (e.g. DVL at byte ~48) and
- * mis-parses symbology offsets — only consider candidates that start immediately after a line break.
- */
-function findLevel3PdbByteOffset(bytes: Uint8Array): number {
-    const len = bytes.length;
-    let pos = 0;
-    while (pos < len) {
-        let lineEnd = pos;
-        while (lineEnd < len && bytes[lineEnd] !== 0x0a && bytes[lineEnd] !== 0x0d) lineEnd++;
-        while (lineEnd < len && (bytes[lineEnd] === 0x0a || bytes[lineEnd] === 0x0d)) lineEnd++;
-        const nextStart = lineEnd;
-        if (nextStart >= len - 2) break;
-        if (isValidLevel3PdbStart(bytes, nextStart)) return nextStart;
-        pos = nextStart;
-    }
-    if (len < 30) return 30;
-    const end = Math.min(len - 14, 900);
-    for (let i = 16; i <= end; i++) {
-        if (isValidLevel3PdbStart(bytes, i)) return i;
-    }
-    return 30;
-}
-
-/** Decode Level-III radial raster (symbology block, packets 0x0010 / 0xAF1F) or raster image 0xBA07. */
-function decodeLevel3RasterProduct(buffer: ArrayBuffer, objectKey: string, radarVariable: string): DecodedRadarFrame | null {
-    try {
-        const bytes = new Uint8Array(buffer);
-        const marker = [83, 68, 85, 83]; // SDUS
-        let startIndex = 0;
-        for (let i = 0; i <= bytes.length - marker.length; i++) {
-            if (
-                bytes[i] === marker[0] &&
-                bytes[i + 1] === marker[1] &&
-                bytes[i + 2] === marker[2] &&
-                bytes[i + 3] === marker[3]
-            ) {
-                startIndex = i;
-                break;
-            }
-        }
-        const trimmed = startIndex > 0 ? bytes.subarray(startIndex) : bytes;
-        const raf = new Level3Raf(trimmed);
-
-        const fileType = raf.readString(6);
-        if (!fileType.startsWith('SDUS')) {
-            throw new Error(`Unexpected Level3 header ${fileType}`);
-        }
-        const pdbByteOffset = findLevel3PdbByteOffset(trimmed);
-        raf.seek(pdbByteOffset);
-        const headerWord0 = raf.readShort();
-        let stationLat: number;
-        let stationLon: number;
-        let productCode: number;
-        if (headerWord0 === -1) {
-            stationLat = raf.readInt() / 1000;
-            stationLon = raf.readInt() / 1000;
-            raf.readShort(); // height
-            productCode = raf.readUShort();
-        } else {
-            raf.seek(pdbByteOffset);
-            productCode = raf.readUShort();
-            raf.readShort(); // julianDate
-            raf.readInt(); // seconds
-            raf.readInt(); // length
-            raf.readShort(); // source
-            raf.readShort(); // dest
-            raf.readShort(); // blocks
-            const divider = raf.readShort();
-            if (divider !== -1) throw new Error(`Invalid product divider ${divider}`);
-            stationLat = raf.readInt() / 1000;
-            stationLon = raf.readInt() / 1000;
-            raf.readShort(); // height
-            raf.readShort(); // code
-        }
-        raf.readShort(); // mode
-        raf.readShort(); // vcp
-        raf.readShort(); // sequenceNumber
-        raf.readShort(); // volumeScanNumber
-        raf.readShort(); // volumeScanDate
-        raf.readInt(); // volumeScanTime
-        raf.readShort(); // productDate
-        raf.readInt(); // productTime
-        raf.read(4); // dependent27_28
-        raf.readShort(); // elevationNumber
-
-        const dep30_53 = new Level3Raf(raf.read(48));
-        const depProductDescriptionShorts: number[] = [];
-        for (let i = 0; i < 24; i++) {
-            depProductDescriptionShorts.push(dep30_53.readShort());
-        }
-        const minimumDataValue = depProductDescriptionShorts[1] / 10;
-        const dataIncrement = depProductDescriptionShorts[2] / 10;
-        const compressionMethod = depProductDescriptionShorts[21];
-        const genericDigitalParams = LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES.has(productCode)
-            ? parseLevel3GenericDigitalParams(depProductDescriptionShorts)
-            : null;
-
-        if (LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES.has(productCode) && !genericDigitalParams) {
-            console.warn('[aguacero][nexrad-l3][generic-digital-params-null]', {
-                objectKey,
-                radarVariable,
-                productCode,
-                depHead: depProductDescriptionShorts.slice(0, 12),
-                hint: 'Continuing with legacy min/inc; precip values may be wrong — check dep alignment / PDB offset.',
-            });
-        }
-
-        // Product 134 (Digital VIL) uses a piecewise linear+log scale encoded
-        // in threshold halfwords 31-35, not the standard min+level*inc formula.
-        let msg134Params: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null = null;
-        if (productCode === 134 && depProductDescriptionShorts.length >= 6) {
-            const hw31 = depProductDescriptionShorts[1];
-            const hw32 = depProductDescriptionShorts[2];
-            const hw33 = depProductDescriptionShorts[3];
-            const hw34 = depProductDescriptionShorts[4];
-            const hw35 = depProductDescriptionShorts[5];
-            msg134Params = {
-                linearScale:  int16ToFloat16(hw31),
-                linearOffset: int16ToFloat16(hw32),
-                logStart:     hw33,
-                logScale:     int16ToFloat16(hw34),
-                logOffset:    int16ToFloat16(hw35),
-            };
-        }
-        const l3Entry = getNexradLevel3EntryByRadarKey(radarVariable);
-        const decodeMode: Level3DecodeMode =
-            l3Entry?.decodeMode ??
-            (radarVariable === 'VEL' ||
-            radarVariable === 'N0G' ||
-            radarVariable === 'SW' ||
-            radarVariable === 'N0W'
-                ? 'velocity'
-                : 'dbz');
-        const isVelSw = decodeMode === 'velocity';
-
-        let minThreshold = minimumDataValue;
-        let dataInc = dataIncrement;
-        if (isVelSw) {
-            const pdbLooksInvalid =
-                !Number.isFinite(dataInc) ||
-                dataInc <= 0 ||
-                dataInc > 25 ||
-                !Number.isFinite(minThreshold) ||
-                Math.abs(minThreshold) > 130;
-            if (pdbLooksInvalid) {
-                minThreshold = -63.5;
-                dataInc = 0.5;
-            }
-        }
-        /** Product 138 (DTA): MetPy `DigitalStormPrecipMapper` uses thr2 × 0.01 in, not × 0.1. */
-        if (decodeMode === 'precip' && productCode === 138) {
-            dataInc = depProductDescriptionShorts[2] * 0.01;
-        }
-
-        /** Product 135 (EET) only: DigitalEET threshold triple in PDB. Classic echo tops (41 / NET) use min+inc like reflectivity. */
-        const eetRadialThresholds =
-            decodeMode === 'tops_kft' && productCode === 135
-                ? {
-                      dataMask: depProductDescriptionShorts[1],
-                      scale: depProductDescriptionShorts[2],
-                      offset: depProductDescriptionShorts[3],
-                  }
-                : null;
-        raf.readByte(); // version
-        raf.readByte(); // spotBlank
-        const offsetSymbology = raf.readInt();
-        raf.readInt(); // offsetGraphic
-        raf.readInt(); // offsetTabular
-
-        let parseBytes = trimmed;
-        if (compressionMethod > 0) {
-            const headerBytes = trimmed.subarray(0, raf.getPos());
-            const compressedTail = trimmed.subarray(raf.getPos());
-            const decompressedTail = bzip.decode(compressedTail) as Uint8Array;
-            parseBytes = concatUint8(headerBytes, decompressedTail);
-        }
-        const parseRaf = new Level3Raf(parseBytes);
-        const symbologyOffsetBytes = pdbByteOffset + offsetSymbology * 2;
-
-        parseRaf.seek(symbologyOffsetBytes);
-
-        const blockDivider = parseRaf.readShort();
-        const blockId = parseRaf.readShort();
-        if (blockDivider !== -1 || blockId !== 1) {
-            const oob = symbologyOffsetBytes < 0 || symbologyOffsetBytes >= parseBytes.length;
-            console.warn('[aguacero][nexrad-l3][symbology-header-bad]', {
-                objectKey,
-                radarVariable,
-                productCode,
-                blockDivider,
-                blockId,
-                symbologyOffsetBytes,
-                parseBytesLength: parseBytes.length,
-                seekOob: oob,
-                hint: 'Usually wrong PDB byte offset; check [sym-offset] and findLevel3PdbByteOffset.',
-            });
-            throw new Error(`Invalid symbology header ${blockDivider}/${blockId}`);
-        }
-        parseRaf.readInt(); // blockLength
-        const numberLayers = parseRaf.readShort();
-
-        /** Scan every layer and every packet (MetPy-style): prefer largest gate×ray footprint, then 0x10 over RLE. */
-        let bestRadial: Level3RadialPick | null = null;
-        let rasterParsed: Level3ParsedRaster | null = null;
-        const symbologyPacketCodes: number[] = [];
-        for (let layerIndex = 0; layerIndex < numberLayers; layerIndex++) {
-            const layerStart = parseRaf.getPos();
-            const layerDivider = parseRaf.readShort();
-            /** Bytes of symbology payload following this 4-byte field (ICD; same as MetPy `layer_hdr.length`). */
-            const layerPayloadLength = parseRaf.readInt();
-            if (layerDivider !== -1) {
-                parseRaf.seek(layerStart + 6 + layerPayloadLength);
-                continue;
-            }
-            /** End of layer = after 6-byte layer record (divider + length) + payload (MetPy marks `layer_start` after header). */
-            const layerEnd = parseRaf.getPos() + layerPayloadLength;
-            while (parseRaf.getPos() < layerEnd) {
-                const packetPos = parseRaf.getPos();
-                const packetCode = parseRaf.readUShort();
-                symbologyPacketCodes.push(packetCode);
-                parseRaf.seek(packetPos);
-                if (packetCode === 16) {
-                    const symMode: Level3SymbologyMode = isVelSw
-                        ? 'digital_velocity_byte'
-                        : decodeMode === 'precip' && !genericDigitalParams
-                          ? 'standard_digital'
-                          : 'reflectivity';
-                    const p = parseLevel3Packet0010(
-                        parseRaf,
-                        minThreshold,
-                        dataInc,
-                        symMode,
-                        productCode,
-                        msg134Params,
-                        eetRadialThresholds,
-                        genericDigitalParams,
-                    );
-                    const cand: Level3RadialPick = { kind: 0x10, packet: p };
-                    if (level3RadialPickIsBetter(cand, bestRadial)) bestRadial = cand;
-                    continue;
-                }
-                if (packetCode === 0xAF1F) {
-                    const symMode: Level3SymbologyMode = isVelSw
-                        ? 'digital_velocity_rle4'
-                        : decodeMode === 'precip' && !genericDigitalParams
-                          ? 'standard_digital'
-                          : 'reflectivity';
-                    const p = parseLevel3PacketAF1F(
-                        parseRaf,
-                        minThreshold,
-                        dataInc,
-                        symMode,
-                        productCode,
-                        msg134Params,
-                        eetRadialThresholds,
-                        genericDigitalParams,
-                    );
-                    const cand: Level3RadialPick = { kind: 0xaf1f, packet: p };
-                    if (level3RadialPickIsBetter(cand, bestRadial)) bestRadial = cand;
-                    continue;
-                }
-                if (packetCode === LEVEL3_PACKET_RASTER_BA07) {
-                    parseRaf.seek(packetPos);
-                    const parsed = parseLevel3PacketRasterBA07(parseRaf, layerEnd, objectKey);
-                    if (parsed && rasterParsed === null) rasterParsed = parsed;
-                    else if (!parsed) parseRaf.seek(layerEnd);
-                    continue;
-                }
-                if (trySkipLevel3OverlayPacket(parseRaf, packetCode, layerEnd)) {
-                    continue;
-                }
-                parseRaf.seek(layerEnd);
-                break;
-            }
-            parseRaf.seek(layerEnd);
-        }
-
-        /**
-         * EET (135): ICD uses up to **256** data levels on digital radials (packet 0x0010 full bytes).
-         * Raster 0xBA07 RLE is **4-bit** (levels 0–15 only), which caps echo-top heights near ~10 km (~33 kft)
-         * even though the radial product carries the full dynamic range. Prefer radials when both exist.
-         *
-         * Digital precip: raster grid avoids radial fan artifacts.
-         * Do **not** prefer raster for dual-pol generic-digital products (e.g. 163 N0K KDP): 0xBA07 RLE is **4-bit**
-         * (levels 0–15) while 0x0010 radials are **8-bit** — using the raster makes KDP/ZDR-style fields one flat color.
-         */
-        const shouldPreferRaster =
-            rasterParsed != null &&
-            ((decodeMode === 'tops_kft' && productCode !== 135) || decodeMode === 'precip');
-
-        if (bestRadial && !shouldPreferRaster) {
-            const radialPacket = bestRadial.packet;
-            const radials = radialPacket?.radials;
-            const nRays = Number(radialPacket?.numberRadials);
-            const nGates = Number(radialPacket?.numberBins);
-            if (!Array.isArray(radials) || !Number.isFinite(nRays) || !Number.isFinite(nGates) || !Number.isFinite(stationLat) || !Number.isFinite(stationLon)) {
-                console.warn('[aguacero][nexrad-l3][invalid-radial-packet]', { objectKey, radarVariable, nRays, nGates, stationLat, stationLon });
-            } else {
-                const gateData = new Uint8Array(nRays * nGates * 2);
-                const { valueScale, valueOffset } = level3ValuePacking(decodeMode);
-                for (let r = 0; r < nRays; r++) {
-                    const bins = radials[r]?.bins;
-                    for (let g = 0; g < nGates; g++) {
-                        const v = bins?.[g];
-                        const isNoData = v == null || !Number.isFinite(v);
-                        const rawSigned = isNoData
-                            ? -32768
-                            : Math.round((Number(v) - valueOffset) / valueScale);
-                        const [hi, lo] = encodeSigned16ToHiLo(rawSigned);
-                        const offset = (r * nGates + g) * 2;
-                        gateData[offset] = hi;
-                        gateData[offset + 1] = lo;
-                    }
-                }
-
-                const rangeMul = LEVEL3_PRODUCT_RANGE_SCALE_MUL[productCode] ?? 1;
-                const rangeScaleRaw = Number(radialPacket?.rangeScaleRaw);
-                const gateSpacingM =
-                    Number.isFinite(rangeScaleRaw) && rangeScaleRaw > 0 ? rangeScaleRaw * rangeMul : 250;
-                let gateWidthKm = gateSpacingM / 1000;
-                const firstBinM = Number(radialPacket?.firstBinMeters);
-                let firstGateKm = Number.isFinite(firstBinM) && firstBinM >= 0 ? firstBinM / 1000 : 0;
-                const decodedCoverageKm = firstGateKm + nGates * gateWidthKm;
-                if (decodedCoverageKm > 0 && decodedCoverageKm < 20 && nGates >= 100) {
-                    gateWidthKm *= 1000;
-                    firstGateKm *= 1000;
-                }
-                // Guard against km↔m mismatch producing global wedges for precip products.
-                if (decodeMode === 'precip' && decodedCoverageKm > 1500) {
-                    gateWidthKm /= 1000;
-                    firstGateKm /= 1000;
-                }
-                const rayBoundariesDeg = buildRayBoundariesFromLevel3Radials(radials);
-
-                return {
-                    gateData,
-                    nRays,
-                    nGates,
-                    stationLat,
-                    stationLon,
-                    firstGateKm,
-                    gateWidthKm,
-                    valueScale,
-                    valueOffset,
-                    rayBoundariesDeg,
-                };
-            }
-        }
-
-        if (rasterParsed) {
-            const { valueScale, valueOffset } = level3ValuePacking(decodeMode);
-            const { minT, dataInc: rasterDataInc, symMode, vilLevelThresholds } = level3RasterPdbScales(
-                decodeMode,
-                productCode,
-                minThreshold,
-                dataInc,
-                depProductDescriptionShorts,
-                objectKey,
-                genericDigitalParams,
-            );
-            const eetThresholds =
-                decodeMode === 'tops_kft' && productCode === 135
-                    ? {
-                          dataMask: depProductDescriptionShorts[1],
-                          scale: depProductDescriptionShorts[2],
-                          offset: depProductDescriptionShorts[3],
-                      }
-                    : null;
-            const rasterFrame = level3RasterToPolarFrame(
-                rasterParsed,
-                stationLat,
-                stationLon,
-                decodeMode,
-                minT,
-                rasterDataInc,
-                symMode,
-                vilLevelThresholds,
-                eetThresholds,
-                valueScale,
-                valueOffset,
-                objectKey,
-                genericDigitalParams,
-                productCode,
-            );
-            if (rasterFrame) {
-                return rasterFrame;
-            }
-        }
-
-        const hex = symbologyPacketCodes.map((c) => `0x${c.toString(16)}`);
-        if (!bestRadial) {
-            console.warn('[aguacero][nexrad-l3][no-radial-symbology]', {
-                objectKey,
-                radarVariable,
-                messageCode: productCode,
-                numberLayers,
-                symbologyPacketCodes,
-                symbologyPacketCodesHex: hex,
-                hint: 'Radial: packets 0x10 / 0xAF1F. Raster: 0xBA07 is supported; if rasterParsed failed, check parseLevel3PacketRasterBA07 / inner code logs.',
-            });
-        }
-        return null;
-    } catch (err) {
-        console.warn('[aguacero][nexrad-l3][decode-throw]', { objectKey, radarVariable, err });
-        return null;
-    }
-}
-
-const GROUP2_VARS = ['SW'];
-/** g2 split-cut in clear-air mode (VCP 35): REF + VEL + SW in one file (legacy archives only). */
-const GROUP2_COMBINED_3_VARS = ['REF', 'VEL', 'SW'];
-/** g1 dual-pol + REF; order must match writer. KDP is Level-III (N0K), not in g1 bins. */
-const GROUP1_VARS = ['REF', 'ZDR', 'RHO', 'PHI'] as const;
-/** g2 combined tilt with KDP (7 slots); order must match writer. */
-const GROUP2_COMBINED_7_VARS = ['REF', 'ZDR', 'RHO', 'PHI', 'KDP', 'VEL', 'SW'];
-const GROUP2_COMBINED_VARS = ['REF', 'ZDR', 'RHO', 'PHI', 'VEL', 'SW'];
-
-// Fixed sizes matching the Python writer (`lambda_function.py` MAX_RAYS / AZ_BLOCK_BYTES).
-const FILE_HDR_BYTES = 64;
-const LEVEL2_AZ_BLOCK_RAYS = 720;
-const LEVEL2_AZ_BLOCK_BYTES = LEVEL2_AZ_BLOCK_RAYS * 4;
-/** Per-sweep Nyquist (m/s), big-endian float32 after azimuth block and before slot index (writer `nyquist_bytes`). */
-const LEVEL2_FILE_NYQUIST_BYTES = 4;
-const SLOT_INDEX_ENTRY = 18;
-const MAX_SLOTS = 7; // g2 combined tilt can write 7 fields (GROUP2_COMBINED_7_VARS)
-
-interface FileHeader {
-    unixTime:   number;
-    nRays:      number;
-    nGates:     number;
-    elevAngle:  number;
-    firstGateKm: number;
-    gateWidthKm: number;
-    nSlots:     number;
-    azimuthsBuffer: ArrayBuffer;  // raw big-endian float32 bytes (720*4)
-    slots: Array<{ offset: number; compressedSize: number; uncompressedSize: number }>;
-    /** Nyquist velocity (m/s) from file header after azimuths; null if non-finite / out of band. */
-    embeddedNyquistMs: number | null;
-}
-
-function int16ToFloat16(val: number): number {
-    const sign = (val & 0b1000000000000000) / 0b1000000000000000;
-    const exponent = (val & 0b0111110000000000) / 0b0000010000000000;
-    const fraction = val & 0b0000001111111111;
-    if (exponent === 0) {
-        return Math.pow(-1, sign) * 2 * (0 + fraction / Math.pow(2, 10));
-    }
-    return Math.pow(-1, sign) * Math.pow(2, exponent - 16) * (1 + fraction / Math.pow(2, 10));
-}
-
-/**
- * Total Level-II object size when known.
- * For 206 partial responses, only `Content-Range: bytes a-b/total` gives `total` — `Content-Length` is the segment size.
- */
-function nexradLevel2ResourceTotalBytes(resp: Response): number | null {
-    const cr = resp.headers.get('Content-Range');
-    if (cr) {
-        const m = cr.trim().match(/\/(\d+)\s*$/);
-        if (m) {
-            const n = Number(m[1]);
-            return Number.isFinite(n) && n > 0 ? n : null;
-        }
-    }
-    if (resp.status === 200) {
-        const cl = resp.headers.get('Content-Length');
-        if (cl) {
-            const n = Number(cl);
-            return Number.isFinite(n) && n > 0 ? n : null;
-        }
-    }
-    return null;
-}
-
-function parseFileHeader(buffer: ArrayBuffer, azBlockBytes: number): FileHeader {
-    const view = new DataView(buffer);
-    const magic = view.getUint32(0, false);
-    if (magic !== 0x4E584244) throw new Error(`Bad magic: 0x${magic.toString(16)}`);
-
-    const unixTime    = view.getUint32(4,  false);
-    const nRays       = view.getUint16(8,  false);
-    const nGates      = view.getUint16(10, false);
-    const elevAngle   = view.getFloat32(12, false);
-    const firstGateKm = view.getFloat32(16, false);
-    const gateWidthKm = view.getFloat32(20, false);
-    const nSlots      = view.getUint16(24, false);
-
-    const azimuthsBuffer = buffer.slice(FILE_HDR_BYTES, FILE_HDR_BYTES + azBlockBytes);
-
-    const azEnd = FILE_HDR_BYTES + azBlockBytes;
-    const idxStart = azEnd + LEVEL2_FILE_NYQUIST_BYTES;
-    const needBytes = idxStart + nSlots * SLOT_INDEX_ENTRY;
-    if (buffer.byteLength < needBytes) {
-        throw new Error(`level2 header buffer too small: ${buffer.byteLength} < ${needBytes}`);
-    }
-
-    const nyqCandidate = view.getFloat32(azEnd, false);
-    const embeddedNyquistMs =
-        Number.isFinite(nyqCandidate) && nyqCandidate > 0.5 && nyqCandidate < 128 ? nyqCandidate : null;
-
-    const slots: Array<{ offset: number; compressedSize: number; uncompressedSize: number }> = [];
-    for (let i = 0; i < nSlots; i++) {
-        const base = idxStart + i * SLOT_INDEX_ENTRY;
-        const offsetHigh = view.getUint32(base, false);
-        const offsetLow = view.getUint32(base + 4, false);
-        const offset = offsetHigh * 2 ** 32 + offsetLow;
-        const compressedSize = view.getUint32(base + 8, false);
-        const uncompressedSize = view.getUint32(base + 12, false);
-        slots.push({ offset, compressedSize, uncompressedSize });
-    }
-
-    return {
-        unixTime,
-        nRays,
-        nGates,
-        elevAngle,
-        firstGateKm,
-        gateWidthKm,
-        nSlots,
-        azimuthsBuffer,
-        slots,
-        embeddedNyquistMs,
-    };
-}
-
-function decodeSweepInWorker(
-    objectKey: string,
-    slotBuffer: ArrayBuffer,
-    header: FileHeader,
-    sites: NexradSite[],
-    priority: 'display' | 'prefetch',
-    signal?: AbortSignal,
-): Promise<DecodedRadarFrame | null> {
-    if (signal?.aborted) return Promise.reject(createAbortError());
-
-    const { worker } = getDecodeWorkerForPriority(priority);
-    const requestId = ++radarDecodeRequestId;
-
-    // Transfer a copy of azimuthsBuffer so we don't detach the cached header
-    const azCopy = header.azimuthsBuffer.slice(0);
-
-    return new Promise((resolve, reject) => {
-        let isSettled = false;
-        const onAbort = () => {
-            if (isSettled) return;
-            isSettled = true;
-            radarDecodePending.delete(requestId);
-            radarDecodeRequestMeta.delete(requestId);
-            signal?.removeEventListener('abort', onAbort);
-            reject(createAbortError());
-        };
-
-        radarDecodePending.set(requestId, {
-            resolve: (frame) => { if (!isSettled) { isSettled = true; signal?.removeEventListener('abort', onAbort); resolve(frame); } },
-            reject:  (err)   => { if (!isSettled) { isSettled = true; signal?.removeEventListener('abort', onAbort); reject(err); } },
-        });
-
-        if (signal) signal.addEventListener('abort', onAbort, { once: true });
-
-        worker.postMessage({
-            type: 'DECODE_SLOT',
-            requestId,
-            objectKey,
-            slotBuffer,
-            nRays:       header.nRays,
-            nGates:      header.nGates,
-            firstGateKm: header.firstGateKm,
-            gateWidthKm: header.gateWidthKm,
-            azimuthsBuffer: azCopy,
-            sites,
-        }, [slotBuffer, azCopy]);
-    });
-}
-
-function resolveLevel3SrvMotionObjectKey(
-    unixTime: number | null | undefined,
-    motionMap: Record<string, string> | undefined,
-    radarSource: 'level2' | 'level3',
-    radarVar: string,
-    useStormRelativeMotion: boolean,
-): string | null {
-    if (radarVar !== 'VEL' || !useStormRelativeMotion || unixTime == null || !motionMap) {
-        return null;
-    }
-    return pickNearestLevel3ObjectKey(unixTime, motionMap);
-}
-
-/** Reuse parsed N0S motion across time steps (SRV: same motion key is common while scrubbing). */
-const N0S_MOTION_CACHE_MAX = 128;
-const n0sMotionVectorCache = new Map<string, { speedMs: number; directionDeg: number }>();
-
-function getCachedN0sMotion(motionObjectKey: string) {
-    return n0sMotionVectorCache.get(motionObjectKey);
-}
-function setCachedN0sMotion(
-    motionObjectKey: string,
-    motion: { speedMs: number; directionDeg: number },
-) {
-    n0sMotionVectorCache.set(motionObjectKey, motion);
-    while (n0sMotionVectorCache.size > N0S_MOTION_CACHE_MAX) {
-        const first = n0sMotionVectorCache.keys().next().value as string | undefined;
-        if (first === undefined) break;
-        n0sMotionVectorCache.delete(first);
-    }
-}
-
-async function applyStormMotionFromN0sObjectKey(
-    frame: DecodedRadarFrame,
-    motionObjectKey: string,
-    logLabel: string,
-): Promise<DecodedRadarFrame> {
-    const cached = getCachedN0sMotion(motionObjectKey);
-    if (cached) {
-        return applyLevel3StormRelativeToFrame(frame, cached.speedMs, cached.directionDeg);
-    }
-    const motionUrl = objectKeyToUrl(motionObjectKey, 'level3');
-    try {
-        const motionResp = await fetch(motionUrl);
-        if (motionResp.ok) {
-            const motionBuf = await motionResp.arrayBuffer();
-            const motion = parseLevel3StormMotionFromBuffer(motionBuf);
-            if (motion) {
-                setCachedN0sMotion(motionObjectKey, motion);
-                return applyLevel3StormRelativeToFrame(frame, motion.speedMs, motion.directionDeg);
-            }
-        }
-    } catch (e) {
-        console.log(`${logLabel}:srvMotionFetchError`, { motionObjectKey, err: e });
-    }
-    return frame;
-}
-
-export async function fetchAndParseArchive(
-    url: string,
-    objectKey: string,
-    radarVariable: string,
-    groupId: number,
-    radarSource: 'level2' | 'level3',
-    options?: {
-        signal?: AbortSignal;
-        priority?: 'display' | 'prefetch';
-        /** N0S S3 object key — with VEL, apply SRV (L3: N0G+motion; L2: super-res velocity + nearest-time N0S motion). */
-        level3MotionObjectKey?: string | null;
-    },
-): Promise<DecodedRadarFrame | null> {
-    const mot = options?.level3MotionObjectKey ? `|${options.level3MotionObjectKey}` : '';
-    const cacheKey = `${url}:${radarVariable}:${radarSource}${mot}`;
-    const priority = options?.priority ?? 'display';
-
-    if (archiveCache.has(cacheKey)) {
-        const cached = archiveCache.get(cacheKey)!;
-        setArchiveCache(cacheKey, cached);
-        return cached;
-    }
-    const existingInflight = inflightFetches.get(cacheKey);
-    if (existingInflight) {
-        const meta = inflightFetchMeta.get(cacheKey);
-        if (meta) {
-            meta.callers += 1;
-        }
-        return existingInflight;
-    }
-
-    if (options?.signal?.aborted) {
-        return null;
-    }
-
-    const requestId = ++radarFetchRequestSeq;
-    const startedAt = performance.now();
-    inflightFetchMeta.set(cacheKey, {
-        requestId,
-        startedAt,
-        callers: 1,
-        objectKey,
-        radarVariable,
-        radarSource,
-        priority,
-    });
-
-    const promise = (async (): Promise<DecodedRadarFrame | null> => {
-        try {
-            if (radarSource === 'level3') {
-                const response = await fetch(url);
-                if (!response.ok) throw new Error(`HTTP ${response.status} fetching level3 ${url}`);
-                const buffer = await response.arrayBuffer();
-                let decoded = decodeLevel3RasterProduct(buffer, objectKey, radarVariable);
-                const motionKey = options?.level3MotionObjectKey;
-                if (decoded && motionKey && radarVariable === 'VEL') {
-                    decoded = await applyStormMotionFromN0sObjectKey(
-                        decoded,
-                        motionKey,
-                        'fetchAndParseArchive:level3',
-                    );
-                }
-                if (!decoded) {
-                    console.warn('[aguacero][nexrad-l3][fetch-ok-decode-null]', {
-                        objectKey,
-                        radarVariable,
-                        byteLength: buffer.byteLength,
-                        filterConsole: 'Also check [aguacero][nexrad-l3][no-radial-symbology] or decode catch logs',
-                    });
-                } else {
-                    setArchiveCache(cacheKey, decoded);
-                }
-                return decoded;
-            }
-
-// ── Level-2 two-request range path ───────────────────────────────────────
-            const level2Url = cloudFrontUrlWithApiKeyQuery(url);
-            nexradArchiveDiag('level2.pipeline.start', {
-                objectKey,
-                radarVariable,
-                groupId,
-                apiKeyLen: NEXRAD_ARCHIVE_API_KEY.length,
-                bundleIdLen: NEXRAD_ARCHIVE_BUNDLE_ID.length,
-                urlNoSecret: redactApiKeyFromUrl(level2Url),
-            });
-            // Request 1: fetch just the header + slot index to find byte offsets
-            const azBlockBytes = LEVEL2_AZ_BLOCK_BYTES;
-            const INDEX_FETCH_BYTES =
-                FILE_HDR_BYTES + azBlockBytes + LEVEL2_FILE_NYQUIST_BYTES + MAX_SLOTS * SLOT_INDEX_ENTRY;
-            nexradArchiveDiag('level2.index.fetch', {
-                objectKey,
-                byteRangeEnd: INDEX_FETCH_BYTES - 1,
-            });
-            const indexResp = await fetch(level2Url, {
-                headers: level2CloudFrontFetchHeaders(`bytes=0-${INDEX_FETCH_BYTES - 1}`),
-            });
-            nexradArchiveDiag('level2.index.response', {
-                objectKey,
-                status: indexResp.status,
-                ok: indexResp.ok,
-            });
-            if (!indexResp.ok && indexResp.status !== 206) {
-                throw new Error(`HTTP ${indexResp.status} fetching level2 index ${url}`);
-            }
-            const indexBuffer = await indexResp.arrayBuffer();
-            const indexResourceTotal = nexradLevel2ResourceTotalBytes(indexResp);
-            const header = parseFileHeader(indexBuffer, azBlockBytes);
-
-            const slotIndexBytes =
-                FILE_HDR_BYTES + azBlockBytes + LEVEL2_FILE_NYQUIST_BYTES + header.nSlots * SLOT_INDEX_ENTRY;
-            if (indexBuffer.byteLength < slotIndexBytes) {
-                console.warn('[RadarLayer] level2 index response shorter than slot table', {
-                    objectKey,
-                    byteLength: indexBuffer.byteLength,
-                    need: slotIndexBytes,
-                    nSlots: header.nSlots,
-                });
-                setArchiveCache(cacheKey, null);
-                return null;
-            }
-
-            // ── Step 2: find slot for this variable ─────────────────────
-            let varList: string[];
-            if (groupId === 2 && header.nSlots === 7) {
-                varList = GROUP2_COMBINED_7_VARS;
-            } else if (groupId === 2 && header.nSlots === 6) {
-                varList = GROUP2_COMBINED_VARS;
-            } else if (groupId === 2 && header.nSlots === 3) {
-                varList = GROUP2_COMBINED_3_VARS;
-            } else if (groupId === 2) {
-                varList = GROUP2_VARS;
-            } else {
-                varList = [...GROUP1_VARS];
-            }
-
-            const slotIdx = varList.indexOf(radarVariable);
-            if (slotIdx < 0 || slotIdx >= header.slots.length) {
-                console.warn(`[RadarLayer] ${radarVariable} not in group ${groupId} (nSlots=${header.nSlots})`);
-                setArchiveCache(cacheKey, null);
-                return null;
-            }
-
-            const slot = header.slots[slotIdx];
-            if (slot.compressedSize === 0) {
-                console.warn(`[RadarLayer] ${radarVariable} slot ${slotIdx} has compressedSize=0`);
-                setArchiveCache(cacheKey, null);
-                return null;
-            }
-
-            // ── Step 3: fetch exactly the slot bytes ────────────────────
-            const slotEndExclusive = slot.offset + slot.compressedSize;
-            if (indexResourceTotal != null && slotEndExclusive > indexResourceTotal) {
-                console.warn('[RadarLayer] level2 slot extends past object size (bad index or stale CDN)', {
-                    objectKey,
-                    radarVariable,
-                    slotIdx,
-                    offset: slot.offset,
-                    compressedSize: slot.compressedSize,
-                    indexResourceTotal,
-                });
-                setArchiveCache(cacheKey, null);
-                return null;
-            }
-
-            const slotRangeEnd = slotEndExclusive - 1;
-            const slotHeaders = level2CloudFrontFetchHeaders(`bytes=${slot.offset}-${slotRangeEnd}`);
-            nexradArchiveDiag('level2.slot.fetch', {
-                objectKey,
-                slotIdx,
-                compressedSize: slot.compressedSize,
-                offset: slot.offset,
-            });
-            let slotResp = await fetch(level2Url, { headers: slotHeaders });
-            nexradArchiveDiag('level2.slot.response', {
-                objectKey,
-                status: slotResp.status,
-                ok: slotResp.ok,
-            });
-            let slotBuffer: ArrayBuffer;
-            if (slotResp.ok || slotResp.status === 206) {
-                slotBuffer = await slotResp.arrayBuffer();
-            } else if (slotResp.status === 416) {
-                const fullResp = await fetch(level2Url, { headers: level2CloudFrontFetchHeaders(undefined) });
-                if (!fullResp.ok) {
-                    throw new Error(`HTTP ${fullResp.status} full fetch after 416 for level2 ${url}`);
-                }
-                const fullBuf = await fullResp.arrayBuffer();
-                if (slot.offset >= fullBuf.byteLength || slotEndExclusive > fullBuf.byteLength) {
-                    throw new Error(
-                        `level2 slot out of bounds after 416 fallback (offset=${slot.offset}, end=${slotEndExclusive}, file=${fullBuf.byteLength}) for ${url}`,
-                    );
-                }
-                slotBuffer = fullBuf.slice(slot.offset, slotEndExclusive);
-            } else {
-                throw new Error(`HTTP ${slotResp.status} fetching level2 slot ${url}`);
-            }
-
-            // ── Step 4: decode in worker ────────────────────────────────
-            nexradArchiveDiag('level2.decode.start', { objectKey, radarVariable });
-            const sites = await loadNexradSites();
-            let decoded = await decodeSweepInWorker(
-                objectKey, slotBuffer, header, sites,
-                options?.priority ?? 'display',
-                undefined,
-            );
-
-            if (!decoded) { setArchiveCache(cacheKey, null); return null; }
-            decoded = { ...decoded, embeddedNyquistMs: header.embeddedNyquistMs };
-            const l2MotionKey = options?.level3MotionObjectKey;
-            if (l2MotionKey && radarVariable === 'VEL') {
-                decoded = await applyStormMotionFromN0sObjectKey(
-                    decoded,
-                    l2MotionKey,
-                    'fetchAndParseArchive:level2',
-                );
-            }
-            setArchiveCache(cacheKey, decoded);
-            nexradArchiveDiag('level2.decode.done', {
-                objectKey,
-                radarVariable,
-                nRays: decoded.nRays ?? null,
-                nGates: decoded.nGates ?? null,
-            });
-            return decoded;
-        } catch (err) {
-            if (isAbortError(err)) {
-                return null;
-            }
-            nexradArchiveDiag('fetchAndParseArchive.failed', {
-                objectKey,
-                radarSource,
-                message: err instanceof Error ? err.message : String(err),
-            });
-            console.error(`[RadarLayer] fetchAndParseArchive failed for ${objectKey}:`, err);
-            return null;
-        } finally {
-            inflightFetches.delete(cacheKey);
-            inflightFetchMeta.delete(cacheKey);
-        }
-    })();
-
-    inflightFetches.set(cacheKey, promise);
-    return promise;
-}
-
+/* eslint-disable */
+// Vendored from aguacero-frontend RadarLayer.tsx — fetch/decode only (no React).
+import { Buffer } from 'buffer';
+import * as bzip from 'seek-bzip';
+import {
+    getNexradLevel3EntryByRadarKey,
+    level3EetHeightKmFromLevel,
+    level3ValuePacking,
+    nexradLevel3IsHydrometeorClassification,
+    nexradLevel3UsesTiltIndexedS3Products,
+    nexradLevel3S3ProductForSiteTilt,
+    type Level3DecodeMode,
+} from './nexradLevel3Products.js';
+import {
+    applyLevel3StormRelativeToFrame,
+    parseLevel3StormMotionFromBuffer,
+    pickNearestLevel3ObjectKey,
+} from './level3StormRelative.js';
+import type { NexradSite } from './PreprocessedSweepParser.js';
+import { archiveCache, setArchiveCache, type DecodedRadarFrame } from './nexradArchiveCache.js';
+import { loadNexradSites } from './loadNexradSites.js';
+export { setNexradSitesJsonUrl, setNexradSitesFetchAuth } from './loadNexradSites.js';
+import { sampleNexradFrameAtLatLon } from './nexradCrossSectionSampleAtLatLon.js';
+import { decodeRadarSlotMessage, type DecodeSlotRequest } from './radarDecodeSlot.js';
+import { nexradArchiveDiag, redactApiKeyFromUrl } from './nexradArchiveDiag.js';
+
+// seek-bzip pulls in node-bzip paths that use `new Buffer()` as a global; browsers have no Buffer.
+if (typeof (globalThis as { Buffer?: typeof Buffer }).Buffer === 'undefined') {
+    (globalThis as { Buffer: typeof Buffer }).Buffer = Buffer;
+}
+
+/** RN/Hermes has no global {@link DOMException}; keep AbortError semantics for fetch abort paths. */
+function createAbortError(message = 'Aborted'): Error {
+    const g = globalThis as typeof globalThis & { DOMException?: typeof DOMException };
+    if (typeof g.DOMException !== 'undefined') {
+        return new g.DOMException(message, 'AbortError');
+    }
+    const err = new Error(message);
+    err.name = 'AbortError';
+    return err;
+}
+
+function isAbortError(err: unknown): boolean {
+    if (err == null || typeof err !== 'object') return false;
+    return (err as Error).name === 'AbortError';
+}
+
+let NEXRAD_ARCHIVE_API_KEY = '';
+/** Same as {@link AguaceroCore} grid fetches: `x-app-identifier` on React Native when set. */
+let NEXRAD_ARCHIVE_BUNDLE_ID = '';
+/** Same as {@link AguaceroCore#gridRequestSiteOrigin}: CloudFront often allowlists Origin/Referer (RN has no browser default). */
+let NEXRAD_ARCHIVE_SITE_ORIGIN = '';
+
+export function setNexradArchiveApiKey(k: string) {
+    NEXRAD_ARCHIVE_API_KEY = k || '';
+}
+
+export function setNexradArchiveBundleId(bundleId: string) {
+    NEXRAD_ARCHIVE_BUNDLE_ID = bundleId || '';
+}
+
+export function setNexradArchiveSiteOrigin(origin: string | null | undefined) {
+    const raw = typeof origin === 'string' ? origin.trim() : '';
+    NEXRAD_ARCHIVE_SITE_ORIGIN = raw ? raw.replace(/\/+$/, '') : '';
+}
+
+/** Match {@link AguaceroCore} `urlWithApiKeyParam` / grid & satellite fetches: `?apiKey=` on CloudFront URLs. */
+function cloudFrontUrlWithApiKeyQuery(baseUrl: string): string {
+    if (!NEXRAD_ARCHIVE_API_KEY) return baseUrl;
+    if (/[?&]apiKey=/i.test(baseUrl)) return baseUrl;
+    const sep = baseUrl.includes('?') ? '&' : '?';
+    return `${baseUrl}${sep}apiKey=${encodeURIComponent(NEXRAD_ARCHIVE_API_KEY)}`;
+}
+
+/** Level-II: match AguaceroCore grid `fetch` headers (x-api-key, x-app-identifier on RN when bundleId set) plus Range. */
+function level2CloudFrontFetchHeaders(range: string | undefined): Record<string, string> {
+    const headers: Record<string, string> = {
+        'x-api-key': NEXRAD_ARCHIVE_API_KEY,
+    };
+    if (range !== undefined) {
+        headers['Range'] = range;
+    }
+    const g = globalThis as typeof globalThis & { navigator?: { product?: string } };
+    if (g.navigator?.product === 'ReactNative' && NEXRAD_ARCHIVE_BUNDLE_ID) {
+        headers['x-app-identifier'] = NEXRAD_ARCHIVE_BUNDLE_ID;
+    }
+    if (NEXRAD_ARCHIVE_SITE_ORIGIN) {
+        headers['Origin'] = NEXRAD_ARCHIVE_SITE_ORIGIN;
+        headers['Referer'] = `${NEXRAD_ARCHIVE_SITE_ORIGIN}/`;
+    }
+    return headers;
+}
+
+type RadarDecodeWorkerResponse = {
+    type: 'DECODE_RESULT';
+    requestId: number;
+    gateData: Uint8Array | null;
+    nRays?: number;
+    nGates?: number;
+    stationLat?: number;
+    stationLon?: number;
+    firstGateKm?: number;
+    gateWidthKm?: number;
+    valueScale?: number;
+    valueOffset?: number;
+    rayBoundariesDeg?: Float32Array;
+    error?: string;
+};
+
+function shouldDecodeRadarOnMainThread(): boolean {
+    const g = globalThis as typeof globalThis & { navigator?: { product?: string } };
+    return typeof Worker === 'undefined' || g.navigator?.product === 'ReactNative';
+}
+
+/** Hermes/RN has no web Workers; mirror Worker.postMessage/onmessage on the JS thread. */
+class MainThreadRadarDecodeWorker implements Pick<Worker, 'postMessage' | 'onmessage' | 'onerror' | 'terminate'> {
+    onmessage: ((ev: MessageEvent<RadarDecodeWorkerResponse>) => void) | null = null;
+    onerror: ((ev: ErrorEvent) => void) | null = null;
+
+    postMessage(data: unknown): void {
+        const msg = data as DecodeSlotRequest;
+        if (!msg || msg.type !== 'DECODE_SLOT') return;
+        queueMicrotask(() => {
+            try {
+                const response = decodeRadarSlotMessage(msg);
+                this.onmessage?.({ data: response } as MessageEvent<RadarDecodeWorkerResponse>);
+            } catch (error) {
+                this.onmessage?.({
+                    data: {
+                        type: 'DECODE_RESULT',
+                        requestId: msg.requestId,
+                        gateData: null,
+                        error: error instanceof Error ? error.message : 'Main-thread radar decode failed',
+                    },
+                } as MessageEvent<RadarDecodeWorkerResponse>);
+            }
+        });
+    }
+
+    terminate(): void {}
+}
+
+function createRadarDecodeWorker(): Worker {
+    if (shouldDecodeRadarOnMainThread()) {
+        return new MainThreadRadarDecodeWorker() as unknown as Worker;
+    }
+    return new Worker(new URL('./radarDecode.worker.bundled.js', import.meta.url), { type: 'module' });
+}
+
+const LEVEL2_BASE_URL = 'https://d3dc62msmxkrd7.cloudfront.net/level-2';
+const LEVEL3_BASE_URL = 'https://unidata-nexrad-level3.s3.amazonaws.com';
+
+const PREFETCH_DELAY_MS = 0;
+const PREFETCH_CONCURRENCY = 6;
+
+/** Underscore-style throttle for no-arg work — coalesces bursts (slider scrub) without delaying the first call. */
+function throttleVoid(fn: () => void, waitMs: number): () => void {
+    let timeout: ReturnType<typeof setTimeout> | null = null;
+    let previous = 0;
+    return () => {
+        const now = Date.now();
+        const remaining = waitMs - (now - previous);
+        if (remaining <= 0 || remaining > waitMs) {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+            previous = now;
+            fn();
+        } else if (!timeout) {
+            timeout = setTimeout(() => {
+                timeout = null;
+                previous = Date.now();
+                fn();
+            }, remaining);
+        }
+    };
+}
+
+/**
+ * Level-III KDP/N0H: throttle runSlot so rapid slider motion coalesces **fetches** (~10/s max) while a trailing
+ * edge still applies the final time. MapboxRadarLayer caches the polar mesh on layout + coarse ray-boundary
+ * fingerprint so scrubbing is fast while sweep registration stays geographic.
+ */
+function createLatestPayloadThrottle(waitMs: number): (run: () => void) => void {
+    let latest: (() => void) | null = null;
+    const runLatest = () => {
+        const fn = latest;
+        latest = null;
+        fn?.();
+    };
+    const throttled = throttleVoid(runLatest, waitMs);
+    return (run: () => void) => {
+        latest = run;
+        throttled();
+    };
+}
+
+const azimuthKeyedRunSlotThrottleBySlot = new Map<string, ReturnType<typeof createLatestPayloadThrottle>>();
+
+function getAzimuthKeyedRunSlotThrottle(slotLayerId: string): (run: () => void) => void {
+    let t = azimuthKeyedRunSlotThrottleBySlot.get(slotLayerId);
+    if (!t) {
+        t = createLatestPayloadThrottle(110);
+        azimuthKeyedRunSlotThrottleBySlot.set(slotLayerId, t);
+    }
+    return t;
+}
+const DECODE_WORKER_POOL_SIZE = 2;
+const PREFETCH_WORKER_START_INDEX = 1;
+
+// ─── Fetch / parse with deduplication ────────────────────────────────────────
+
+// Tracks in-flight fetches so concurrent calls for the same URL share one request.
+const inflightFetches = new Map<string, Promise<DecodedRadarFrame | null>>();
+const inflightFetchMeta = new Map<
+    string,
+    {
+        requestId: number;
+        startedAt: number;
+        callers: number;
+        objectKey: string;
+        radarVariable: string;
+        radarSource: 'level2' | 'level3';
+        priority: 'display' | 'prefetch';
+    }
+>();
+let radarFetchRequestSeq = 0;
+
+let radarDecodeWorkers: Worker[] = [];
+let radarDecodeRequestId = 0;
+const radarDecodePending = new Map<number, {
+    resolve: (frame: DecodedRadarFrame | null) => void;
+    reject: (error: Error) => void;
+}>();
+const radarDecodeRequestMeta = new Map<number, { objectKey: string; workerIndex: number }>();
+let radarDecodePrefetchWorkerIndex = PREFETCH_WORKER_START_INDEX;
+
+function createDecodeWorker(workerIndex: number): Worker {
+    const worker = createRadarDecodeWorker();
+    worker.onmessage = (event: MessageEvent<RadarDecodeWorkerResponse>) => {
+        const message = event.data;
+        if (!message || message.type !== 'DECODE_RESULT') return;
+        const pending = radarDecodePending.get(message.requestId);
+        if (!pending) return;
+        radarDecodePending.delete(message.requestId);
+        radarDecodeRequestMeta.delete(message.requestId);
+        if (message.error) {
+            pending.reject(new Error(message.error));
+            return;
+        }
+        if (
+            !message.gateData
+            || typeof message.nRays !== 'number'
+            || typeof message.nGates !== 'number'
+            || typeof message.stationLat !== 'number'
+            || typeof message.stationLon !== 'number'
+            || typeof message.firstGateKm !== 'number'
+            || typeof message.gateWidthKm !== 'number'
+            || typeof message.valueScale !== 'number'
+            || typeof message.valueOffset !== 'number'
+            || !(message.rayBoundariesDeg instanceof Float32Array)
+        ) {
+            pending.resolve(null);
+            return;
+        }
+        pending.resolve({
+            gateData: message.gateData,
+            nRays: message.nRays,
+            nGates: message.nGates,
+            stationLat: message.stationLat,
+            stationLon: message.stationLon,
+            firstGateKm: message.firstGateKm,
+            gateWidthKm: message.gateWidthKm,
+            valueScale: message.valueScale,
+            valueOffset: message.valueOffset,
+            rayBoundariesDeg: message.rayBoundariesDeg,
+        });
+    };
+    worker.onerror = (error) => {
+        radarDecodePending.forEach(({ reject }) => reject(new Error(error.message || 'Radar decode worker failed')));
+        radarDecodePending.clear();
+        radarDecodeRequestMeta.clear();
+    };
+    return worker;
+}
+
+function getRadarDecodeWorkers(): Worker[] {
+    if (radarDecodeWorkers.length > 0) return radarDecodeWorkers;
+    radarDecodeWorkers = Array.from({ length: DECODE_WORKER_POOL_SIZE }, (_, idx) => createDecodeWorker(idx));
+    return radarDecodeWorkers;
+}
+
+function getDecodeWorkerForPriority(priority: 'display' | 'prefetch'): { worker: Worker; workerIndex: number } {
+    const workers = getRadarDecodeWorkers();
+    if (priority === 'display' || workers.length === 1) {
+        return { worker: workers[0], workerIndex: 0 };
+    }
+    const prefetchWorkerCount = Math.max(workers.length - PREFETCH_WORKER_START_INDEX, 1);
+    const offset = (radarDecodePrefetchWorkerIndex - PREFETCH_WORKER_START_INDEX + prefetchWorkerCount) % prefetchWorkerCount;
+    const workerIndex = PREFETCH_WORKER_START_INDEX + offset;
+    radarDecodePrefetchWorkerIndex = PREFETCH_WORKER_START_INDEX + ((offset + 1) % prefetchWorkerCount);
+    return { worker: workers[Math.min(workerIndex, workers.length - 1)], workerIndex: Math.min(workerIndex, workers.length - 1) };
+}
+
+/** Get physical value at lat/lon from a decoded radar frame. Returns null if outside coverage or no data. */
+function getSampleAtLatLonForRadarFrame(
+    frame: DecodedRadarFrame,
+    lat: number,
+    lon: number,
+    smoothPolar: boolean,
+): { value: number; groundRangeKm: number } | null {
+    return sampleNexradFrameAtLatLon(frame, lat, lon, { smoothPolar });
+}
+
+export function objectKeyToUrl(objectKey: string, radarSource: 'level2' | 'level3' = 'level2'): string {
+    if (objectKey.startsWith('http')) return objectKey;
+    const baseUrl = radarSource === 'level3' ? LEVEL3_BASE_URL : LEVEL2_BASE_URL;
+    const url = `${baseUrl.replace(/\/$/, '')}/${objectKey}`;
+    return radarSource === 'level2' ? cloudFrontUrlWithApiKeyQuery(url) : url;
+}
+
+class Level3Raf {
+    private offset = 0;
+    private view: DataView;
+    private bytes: Uint8Array;
+
+    constructor(input: Uint8Array | ArrayBuffer) {
+        this.bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+        this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
+    }
+
+    getPos(): number { return this.offset; }
+    getLength(): number { return this.bytes.length; }
+    seek(pos: number): void { this.offset = pos; }
+    skip(delta: number): void { this.offset += delta; }
+    read(bytes = 1): Uint8Array {
+        const out = this.bytes.subarray(this.offset, this.offset + bytes);
+        this.offset += bytes;
+        return out;
+    }
+    readByte(): number {
+        const v = this.view.getUint8(this.offset);
+        this.offset += 1;
+        return v;
+    }
+    readShort(): number {
+        const v = this.view.getInt16(this.offset, false);
+        this.offset += 2;
+        return v;
+    }
+    readUShort(): number {
+        const v = this.view.getUint16(this.offset, false);
+        this.offset += 2;
+        return v;
+    }
+    readInt(): number {
+        const v = this.view.getInt32(this.offset, false);
+        this.offset += 4;
+        return v;
+    }
+    readUInt32(): number {
+        const v = this.view.getUint32(this.offset, false);
+        this.offset += 4;
+        return v;
+    }
+    readString(bytes: number): string {
+        const slice = this.read(bytes);
+        return String.fromCharCode(...slice);
+    }
+}
+
+function concatUint8(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+
+/**
+ * NEXRAD Level-III: range to gate g (m) = g * range_scale_symbology * multiplier[message_code] + first_bin (m).
+ * Without multipliers, super-res products (e.g. message 153 reflectivity, 154 velocity) decode ~4× too coarse in range.
+ * Aligned with Py-ART / jjhelmus `PRODUCT_RANGE_RESOLUTION`.
+ */
+const LEVEL3_PRODUCT_RANGE_SCALE_MUL: Record<number, number> = {
+    19: 1, 20: 2, 25: 0.25, 27: 1, 28: 0.25, 30: 1, 32: 1, 34: 1, 56: 1,
+    57: 1000,
+    78: 1, 79: 1, 80: 1, 94: 1, 99: 0.25,
+    134: 1000, 135: 1000, 138: 1,
+    153: 0.25, 154: 0.25, 155: 0.25, 159: 0.25, 161: 0.25, 163: 0.25, 165: 0.25,
+    166: 0.25, 167: 0.25, 168: 0.25,
+    169: 1000, 170: 1000, 171: 1000, 172: 1000, 173: 1000, 174: 1000, 175: 1000,
+    /** Py-ART `PRODUCT_RANGE_RESOLUTION`: 176/177 are digital-style radials (0.25×), not 1 km like 169–175. */
+    176: 0.25, 177: 0.25,
+    181: 150, 182: 150, 186: 300,
+};
+
+/**
+ * MetPy `GenericDigitalMapper` products: symbology levels map as (L - offset) / scale
+ * where scale/offset are big-endian float32 from PDB thr1–thr2 and thr3–thr4 (see MetPy `nexrad.float32`).
+ * DAA (170) was incorrectly decoded as min + L*inc, producing bogus inches and fan artifacts.
+ */
+const LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES = new Set([
+    159, 161, 163, 167, 168,
+    170, 172, 173, 174, 175, 176,
+]);
+
+/**
+ * NWS digital accumulation (MetPy `GenericDigitalMapper`) carries **depth in millimeters**.
+ * Layer colormap / readout expect **inches** (see `nexradLevel3Products` precip packing).
+ */
+const LEVEL3_GENERIC_DIGITAL_DEPTH_MM_TO_IN_PRODUCTS = new Set([170, 172, 173, 174, 175]);
+
+/**
+ * MetPy `DigitalHMCMapper`: digital / hybrid hydrometeor classification (165, 177).
+ * 8-bit radial (packet 0x0010): `lut[i] = i // 10` is the **1-based** NWS category (1=BI … 6=RA … 12=GH).
+ * Fill colormap / `NEXRAD_HYDROMETEOR_CLASS_LABELS` use **0-based** indices in the same order → `floor(level/10) - 1`.
+ * 150 = range-fold.
+ * 4-bit raster / RLE (0xBA07, 0xAF1F): levels 2–15 → 0-based class index `level − 2`.
+ */
+const LEVEL3_DIGITAL_HMC_PRODUCT_CODES = new Set([165, 177]);
+
+function level3PhysicalFromDigitalHmc(level: number, precision: 'byte' | 'nibble'): number | null {
+    if (!Number.isFinite(level)) return null;
+    if (precision === 'nibble') {
+        if (level < 2 || level > 15) return null;
+        return level - 2;
+    }
+    if (level === 150) return null;
+    if (level < 10 || level >= 256) return null;
+    const cls = Math.floor(level / 10) - 1;
+    if (cls < 0 || cls > 11) return null;
+    return cls;
+}
+
+/**
+ * Per-product mm calibration before ÷25.4 for generic digital accumulation (170, 172–175).
+ * 170 (DAA) field‑checked at 0.125. 172–175 were too low at 0.125, too high at 1.0; 0.5 still ~2× high
+ * in the field → 0.25 for those products (halve again if needed).
+ */
+function level3GenericDigitalAccumMmFactor(productCode: number): number {
+    switch (productCode) {
+        case 170: // DAA — 1‑hour digital accumulation array
+            return 0.125;
+        case 172: // Digital storm total accumulation (generic)
+        case 173: // DU3 — user‑selectable (e.g. 3‑hour)
+        case 174: // Digital one‑hour difference accumulation
+        case 175: // Digital storm total difference accumulation
+            return 0.25;
+        default:
+            return 1;
+    }
+}
+
+type Level3GenericDigitalParams = {
+    scale: number;
+    offset: number;
+    leadingFlags: number;
+    trailingFlags: number;
+    maxDataVal: number;
+};
+
+function level3UnpackFloat32FromThresholdPair(short0: number, short1: number): number {
+    const buf = new ArrayBuffer(4);
+    const view = new DataView(buf);
+    view.setUint16(0, short0 & 0xffff, false);
+    view.setUint16(2, short1 & 0xffff, false);
+    return view.getFloat32(0, false);
+}
+
+function parseLevel3GenericDigitalParams(dep: number[]): Level3GenericDigitalParams | null {
+    /**
+     * `raf.read(48)` is read **after** PDB fields through `el_num`, so this 24-short block is:
+     * dep[0]=dep3, dep[1]=thr1, dep[2]=thr2, … dep[16]=thr16, dep[17]=dep4, …
+     * MetPy GenericDigitalMapper: scale=float32(thr1,thr2), offset=float32(thr3,thr4),
+     * max=thr6, leading=thr7, trailing=thr8 → dep indices 1..8.
+     */
+    if (dep.length < 9) return null;
+    const scale = level3UnpackFloat32FromThresholdPair(dep[1], dep[2]);
+    const offset = level3UnpackFloat32FromThresholdPair(dep[3], dep[4]);
+    const maxDataVal = dep[6] & 0xffff;
+    const leadingFlags = dep[7];
+    const trailingFlags = dep[8];
+    if (!Number.isFinite(scale) || scale === 0 || !Number.isFinite(offset)) return null;
+    if (leadingFlags < 0 || leadingFlags > 255 || trailingFlags < 0 || trailingFlags > 255) return null;
+    if (maxDataVal < leadingFlags) return null;
+    return { scale, offset, leadingFlags, trailingFlags, maxDataVal };
+}
+
+function level3PhysicalFromGenericDigital(
+    level: number,
+    p: Level3GenericDigitalParams,
+    productCode: number,
+): number | null {
+    if (!Number.isFinite(level)) return null;
+    if (level < p.leadingFlags) return null;
+    const upper = p.maxDataVal - p.trailingFlags;
+    if (level > upper) return null;
+    let out = (level - p.offset) / p.scale;
+    if (!Number.isFinite(out)) return null;
+    if (LEVEL3_GENERIC_DIGITAL_DEPTH_MM_TO_IN_PRODUCTS.has(productCode)) {
+        out *= level3GenericDigitalAccumMmFactor(productCode);
+        out /= 25.4;
+    }
+    return out;
+}
+
+type Level3SymbologyMode =
+    | 'reflectivity'
+    /**
+     * MetPy `DigitalMapper` linear products (precip inches, etc.): phys = min + (L - 2) * inc.
+     * Kept separate from `reflectivity` so legacy/category-style symbology is unchanged.
+     */
+    | 'standard_digital'
+    /** Packet 0x0010: full-byte data levels; NEXRAD digital velocity uses threshold + (L-2)*inc. */
+    | 'digital_velocity_byte'
+    /**
+     * Packet 0xAF1F: 4-bit levels in RLE nibbles. Threshold+increment from the PDB only spans a
+     * small negative band (~−64…−57 m/s), so values fall entirely outside typical −30…+30 m/s
+     * colormaps and the map looks empty. Use a centered mapping (0 m/s ≈ level 8, ~4 m/s per step).
+     */
+    | 'digital_velocity_rle4';
+
+/**
+ * Map symbology data level to a physical value (dBZ, m/s, etc.) depending on product/packet mode.
+ */
+const LEVEL3_MSG134_PRODUCTS = new Set([134]);
+
+// Replace the reflectivity branch in level3PhysicalFromDataLevel:
+function level3PhysicalFromDataLevel(
+    level: number,
+    minimumDataValue: number,
+    dataIncrement: number,
+    mode: Level3SymbologyMode,
+    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
+): number | null {
+    if (!Number.isFinite(level)) return null;
+    if (mode === 'digital_velocity_byte') {
+        if (level < 2) return null;
+        return minimumDataValue + (level - 2) * dataIncrement;
+    }
+    if (mode === 'digital_velocity_rle4') {
+        if (level < 2) return null;
+        const MS_PER_STEP = 4;
+        const CENTER_LEVEL = 8;
+        return (level - CENTER_LEVEL) * MS_PER_STEP;
+    }
+    // Product 134 (Digital VIL): piecewise linear + log, params from threshold halfwords
+    if (msg134Params) {
+        if (level < 2) return null;
+        const { linearScale, linearOffset, logStart, logScale, logOffset } = msg134Params;
+        if (level < logStart) {
+            return (level - linearOffset) / linearScale;
+        } else {
+            return Math.exp((level - logOffset) / logScale);
+        }
+    }
+    if (mode === 'standard_digital') {
+        if (level < 2) return null;
+        return minimumDataValue + (level - 2) * dataIncrement;
+    }
+    if (level <= 1) return null;
+    return minimumDataValue + level * dataIncrement;
+}
+
+function parseLevel3Packet0010(
+    raf: Level3Raf,
+    minimumDataValue: number,
+    dataIncrement: number,
+    levelMode: Level3SymbologyMode,
+    l3ProductCode: number,
+    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
+    eetThresholds?: { dataMask: number; scale: number; offset: number } | null,
+    genericDigital?: Level3GenericDigitalParams | null,
+) {
+    const packetCode = raf.readUShort();
+    if (packetCode !== 16) throw new Error(`Unexpected packet code ${packetCode}`);
+    const firstBinMeters = raf.readShort();
+    let numberBins = raf.readShort();
+    raf.readShort(); // iSweepCenter
+    raf.readShort(); // jSweepCenter
+    const rangeScaleRaw = raf.readShort();
+    const numberRadials = raf.readShort();
+    // Py-ART: packet 16 sometimes has nbins ≠ per-radial nbytes; true gate count follows first radial header.
+    if (numberRadials > 0) {
+        const peek = raf.getPos();
+        const nbytesFirst = raf.readShort();
+        raf.seek(peek);
+        if (nbytesFirst !== numberBins) {
+            numberBins = nbytesFirst;
+        }
+    }
+    const radials: Array<{ startAngle: number; angleDelta: number; bins: Array<number | null> }> = [];
+    for (let r = 0; r < numberRadials; r++) {
+        const bytesInRadial = raf.readShort();
+        const startAngle = raf.readShort() / 10;
+        const angleDelta = raf.readShort() / 10;
+        const bins: Array<number | null> = [];
+        for (let i = 0; i < numberBins; i++) {
+            const level = raf.readByte();
+            if (eetThresholds) {
+                bins.push(
+                    level3EetHeightKmFromLevel(level, eetThresholds.dataMask, eetThresholds.scale, eetThresholds.offset),
+                );
+            } else if (LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)) {
+                bins.push(level3PhysicalFromDigitalHmc(level, 'byte'));
+            } else if (genericDigital) {
+                bins.push(level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode));
+            } else {
+                bins.push(level3PhysicalFromDataLevel(level, minimumDataValue, dataIncrement, levelMode, msg134Params));
+            }
+        }
+        if (bytesInRadial > numberBins) raf.skip(bytesInRadial - numberBins);
+        radials.push({ startAngle, angleDelta, bins });
+    }
+    return { firstBinMeters, numberBins, rangeScaleRaw, numberRadials, radials };
+}
+function parseLevel3PacketAF1F(
+    raf: Level3Raf,
+    minimumDataValue: number,
+    dataIncrement: number,
+    levelMode: Level3SymbologyMode,
+    l3ProductCode: number,
+    msg134Params?: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null,
+    eetThresholds?: { dataMask: number; scale: number; offset: number } | null,
+    genericDigital?: Level3GenericDigitalParams | null,
+) {
+    const packetCode = raf.readUShort();
+    if (packetCode !== 0xAF1F) throw new Error(`Unexpected packet code ${packetCode}`);
+    const firstBinMeters = raf.readShort();
+    const numberBins = raf.readShort();
+    raf.readShort(); // iSweepCenter
+    raf.readShort(); // jSweepCenter
+    const rangeScaleRaw = raf.readShort();
+    const numRadials = raf.readShort();
+    const radials: Array<{ startAngle: number; angleDelta: number; bins: Array<number | null> }> = [];
+    for (let r = 0; r < numRadials; r++) {
+        const rleBytes = raf.readShort() * 2;
+        const startAngle = raf.readShort() / 10;
+        const angleDelta = raf.readShort() / 10;
+        const bins: Array<number | null> = [];
+        for (let i = 0; i < rleBytes; i++) {
+            const byte = raf.readByte();
+            const run = byte >> 4;
+            const level = byte & 0x0f;
+            const value = eetThresholds
+                ? level3EetHeightKmFromLevel(level, eetThresholds.dataMask, eetThresholds.scale, eetThresholds.offset)
+                : LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)
+                  ? level3PhysicalFromDigitalHmc(level, 'nibble')
+                  : genericDigital
+                    ? level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode)
+                    : level3PhysicalFromDataLevel(level, minimumDataValue, dataIncrement, levelMode, msg134Params);
+            for (let j = 0; j < run; j++) bins.push(value);
+        }
+        if (bins.length > numberBins) bins.length = numberBins;
+        while (bins.length < numberBins) bins.push(null);
+        radials.push({ startAngle, angleDelta, bins });
+    }
+    return { firstBinMeters, numberBins, rangeScaleRaw, numberRadials: numRadials, radials };
+}
+
+function buildRayBoundariesFromLevel3Radials(radials: any[]): Float32Array {
+    const n = radials.length;
+    const boundaries = new Float32Array(n + 1);
+    let prev = -Infinity;
+    for (let i = 0; i < n; i++) {
+        const startAngle = Number(radials[i]?.startAngle);
+        const angleDelta = Number(radials[i]?.angleDelta);
+        const start = Number.isFinite(startAngle) ? startAngle : 0;
+        const delta = Number.isFinite(angleDelta) && angleDelta > 0 ? angleDelta : 1;
+        let lower = start - delta * 0.5;
+        while (lower <= prev) lower += 360;
+        boundaries[i] = lower;
+        prev = lower;
+    }
+    const lastDeltaRaw = Number(radials[n - 1]?.angleDelta);
+    const lastDelta = Number.isFinite(lastDeltaRaw) && lastDeltaRaw > 0 ? lastDeltaRaw : 1;
+    boundaries[n] = boundaries[n - 1] + lastDelta;
+    return boundaries;
+}
+
+function encodeSigned16ToHiLo(value: number): [number, number] {
+    const signed = Math.max(-32768, Math.min(32767, value));
+    const raw = signed < 0 ? signed + 65536 : signed;
+    return [(raw >> 8) & 0xff, raw & 0xff];
+}
+
+function level3RadialSpatialScore(p: { numberBins: number; numberRadials: number } | null | undefined): number {
+    if (!p) return -1;
+    const nb = Number(p.numberBins);
+    const nr = Number(p.numberRadials);
+    if (!Number.isFinite(nb) || !Number.isFinite(nr) || nb <= 0 || nr <= 0) return -1;
+    return nb * nr;
+}
+
+type Level3RadialPick = { kind: 0x10 | 0xaf1f; packet: any };
+
+function level3RadialPickIsBetter(cand: Level3RadialPick, prev: Level3RadialPick | null): boolean {
+    const sC = level3RadialSpatialScore(cand.packet);
+    const sP = level3RadialSpatialScore(prev?.packet);
+    if (sC > sP) return true;
+    if (sC < sP) return false;
+    if (!prev) return true;
+    /** Same footprint: prefer full-byte digital radial (0x10) over 4-bit RLE (0xAF1F) for smoother velocity. */
+    if (cand.kind === 0x10 && prev.kind === 0xaf1f) return true;
+    return false;
+}
+
+/**
+ * Advance past a non-radial symbology packet so later packets in the same layer can be read.
+ * Caller must position RAF at the packet code; we consume code + body.
+ * Uniform text (1, 8): u16 payload length then that many bytes (MetPy / ICD).
+ */
+function trySkipLevel3OverlayPacket(raf: Level3Raf, packetCode: number, layerEnd: number): boolean {
+    const pos0 = raf.getPos();
+    if (packetCode !== 1 && packetCode !== 2 && packetCode !== 8) return false;
+    if (layerEnd - pos0 < 4) return false;
+    const codeRead = raf.readUShort();
+    if (codeRead !== packetCode) {
+        raf.seek(pos0);
+        return false;
+    }
+    const payloadBytes = raf.readUShort();
+    if (payloadBytes > layerEnd - raf.getPos()) {
+        raf.seek(pos0);
+        return false;
+    }
+    raf.skip(payloadBytes);
+    return true;
+}
+
+/** Symbology packet 0xBA07: raster image (RLE rows). MetPy `packet_map[0xba07]`. Used by NVL (57), EET, etc. */
+const LEVEL3_PACKET_RASTER_BA07 = 0xba07;
+/** First u32 after packet code; MetPy asserts this for raster payload. */
+const LEVEL3_RASTER_INNER_CODE = 0x800000c0;
+
+function unpackLevel3RasterRle(rowBytes: Uint8Array): number[] {
+    const unpacked: number[] = [];
+    for (let i = 0; i < rowBytes.length; i++) {
+        const b = rowBytes[i];
+        const run = b >> 4;
+        const val = b & 0x0f;
+        for (let j = 0; j < run; j++) unpacked.push(val);
+    }
+    return unpacked;
+}
+
+function level3CombineRasterScale(int16: number, frac16: number): number {
+    const i = Math.abs(int16);
+    const f = Math.abs(frac16) / 10000;
+    const s = i + f;
+    return s > 0 ? s : 1;
+}
+
+type Level3ParsedRaster = {
+    iStart: number;
+    jStart: number;
+    cellKmX: number;
+    cellKmY: number;
+    startXKm: number;
+    startYKm: number;
+    nCols: number;
+    nRows: number;
+    rows: number[][];
+};
+
+/**
+ * Parse raster symbology (packet 0xBA07). RAF must be positioned at the packet code (first u16).
+ * Leaves RAF at `layerEnd` on success or after skipping on failure.
+ */
+function parseLevel3PacketRasterBA07(raf: Level3Raf, layerEnd: number, objectKey: string): Level3ParsedRaster | null {
+    const pos0 = raf.getPos();
+    const packetCode = raf.readUShort();
+    if (packetCode !== LEVEL3_PACKET_RASTER_BA07) {
+        raf.seek(pos0);
+        return null;
+    }
+    const room = layerEnd - raf.getPos();
+    if (room < 20) {
+        raf.seek(layerEnd);
+        return null;
+    }
+    const inner = raf.readUInt32();
+    if (inner !== LEVEL3_RASTER_INNER_CODE) {
+        raf.seek(layerEnd);
+        return null;
+    }
+    const iStart = raf.readShort();
+    const jStart = raf.readShort();
+    const xscaleInt = raf.readShort();
+    const xscaleFrac = raf.readShort();
+    const yscaleInt = raf.readShort();
+    const yscaleFrac = raf.readShort();
+    const numRows = raf.readUShort();
+    const packing = raf.readUShort();
+    if (packing !== 2) {
+        console.warn('[aguacero][nexrad-l3][raster-ba07-packing]', { objectKey, packing, hint: 'MetPy expects packing=2; raster parse skipped for this layer' });
+        raf.seek(layerEnd);
+        return null;
+    }
+    if (numRows <= 0 || numRows > 2000 || raf.getPos() > layerEnd) {
+        raf.seek(layerEnd);
+        return null;
+    }
+    const cellKmX = level3CombineRasterScale(xscaleInt, xscaleFrac);
+    const cellKmY = level3CombineRasterScale(yscaleInt, yscaleFrac);
+    /** Match MetPy: start corner from integer scales only (see `metpy.io.nexrad` `_unpack_packet_raster_data`). */
+    const startXKm = iStart * xscaleInt;
+    const startYKm = jStart * yscaleInt;
+    const rows: number[][] = [];
+    let nCols = -1;
+    for (let r = 0; r < numRows; r++) {
+        if (raf.getPos() + 2 > layerEnd) {
+            raf.seek(layerEnd);
+            return null;
+        }
+        const rowNumBytes = raf.readUShort();
+        if (rowNumBytes === 0 || raf.getPos() + rowNumBytes > layerEnd) {
+            raf.seek(layerEnd);
+            return null;
+        }
+        const rowBytes = raf.read(rowNumBytes);
+        const expanded = unpackLevel3RasterRle(rowBytes);
+        if (nCols < 0) nCols = expanded.length;
+        else if (expanded.length !== nCols) {
+            raf.seek(layerEnd);
+            return null;
+        }
+        rows.push(expanded);
+    }
+    if (nCols <= 0) {
+        raf.seek(layerEnd);
+        return null;
+    }
+    if (raf.getPos() < layerEnd) {
+        raf.seek(layerEnd);
+    }
+    return {
+        iStart,
+        jStart,
+        cellKmX,
+        cellKmY,
+        startXKm,
+        startYKm,
+        nCols,
+        nRows: numRows,
+        rows,
+    };
+}
+
+function level3RasterPdbScales(
+    decodeMode: Level3DecodeMode,
+    productCode: number,
+    minimumDataValue: number,
+    dataIncrement: number,
+    depProductDescriptionShorts: number[] | null,
+    objectKey: string,
+    genericDigital: Level3GenericDigitalParams | null,
+): {
+    minT: number;
+    dataInc: number;
+    symMode: Level3SymbologyMode;
+    vilLevelThresholds: number[] | null;
+} {
+    const minBad =
+        !Number.isFinite(minimumDataValue) || Math.abs(minimumDataValue) > 500;
+    const incBad = !Number.isFinite(dataIncrement) || dataIncrement <= 0;
+    const bad = minBad || incBad;
+    let minT = minimumDataValue;
+    let dataInc = dataIncrement;
+    let vilLevelThresholds: number[] | null = null;
+    /**
+     * NVL often encodes an invalid linear min (e.g. -32766 sentinel), while real level thresholds
+     * are present in product-description shorts 33..46 (values like 5,10,...,70 kg/m²).
+     * Prefer those thresholds when present so data-level 2..15 map to physically meaningful VIL.
+     */
+    if (
+        decodeMode === 'vil' &&
+        productCode === 57 &&
+        Array.isArray(depProductDescriptionShorts) &&
+        depProductDescriptionShorts.length >= 17 &&
+        depProductDescriptionShorts[1] <= -30000
+    ) {
+        const byLevel = new Array<number>(16).fill(Number.NaN);
+        let validCount = 0;
+        for (let level = 2; level <= 15; level++) {
+            const raw = depProductDescriptionShorts[level + 1];
+            if (Number.isFinite(raw) && raw > 0) {
+                byLevel[level] = raw;
+                validCount += 1;
+            }
+        }
+        if (validCount >= 8) {
+            vilLevelThresholds = byLevel;
+        }
+    }
+    if (bad) {
+        /** VIL: PDB min is often garbage; increment 0.1 is still valid. phys = minT + level*inc with level≥2 → use minT = -inc so level 2 → +inc (e.g. 0.1). */
+        if (decodeMode === 'vil' && minBad && !incBad && dataIncrement >= 0.05 && dataIncrement <= 2) {
+            minT = -dataIncrement;
+            dataInc = dataIncrement;
+        } else if (decodeMode === 'vil') {
+            minT = 0;
+            dataInc = 1;
+        } else if (decodeMode === 'precip') {
+            minT = 0;
+            dataInc = 0.25;
+        } else if (decodeMode === 'tops_kft') {
+            minT = 0;
+            dataInc = 1;
+        } else if (decodeMode === 'categorical') {
+            minT = 0;
+            dataInc = 1;
+        } else if (decodeMode === 'generic_physical') {
+            minT = -2;
+            dataInc = 0.05;
+        } else {
+            minT = -32;
+            dataInc = 0.5;
+        }
+    }
+    const symMode: Level3SymbologyMode =
+        decodeMode === 'velocity'
+            ? 'digital_velocity_byte'
+            : decodeMode === 'precip' && !genericDigital
+              ? 'standard_digital'
+              : 'reflectivity';
+    return { minT, dataInc, symMode, vilLevelThresholds };
+}
+
+/** Resample Cartesian raster (km east/north from radar) into the polar texture the Mapbox radar shader expects. */
+function level3RasterToPolarFrame(
+    raster: Level3ParsedRaster,
+    stationLat: number,
+    stationLon: number,
+    decodeMode: Level3DecodeMode,
+    minT: number,
+    dataInc: number,
+    symMode: Level3SymbologyMode,
+    vilLevelThresholds: number[] | null,
+    eetThresholds: { dataMask: number; scale: number; offset: number } | null,
+    valueScale: number,
+    valueOffset: number,
+    objectKey: string,
+    genericDigital: Level3GenericDigitalParams | null = null,
+    l3ProductCode = 0,
+): DecodedRadarFrame | null {
+    const { rows, nCols, nRows, startXKm, startYKm, cellKmX, cellKmY, iStart, jStart } = raster;
+    const widthKm = nCols * cellKmX;
+    const heightKm = nRows * cellKmY;
+    /**
+     * ICD raster I/J origin 0 with a square grid is a box **centered** on the radar (±half extent in km).
+     * Treating (0,0) as the southwest corner only covers the northeast quadrant — data appears displaced
+     * toward +x,+y (e.g. Atlantic for East Coast sites) and few polar samples hit the grid.
+     */
+    let originXK = startXKm;
+    let originYK = startYKm;
+    if (iStart === 0 && jStart === 0 && nCols === nRows && nCols >= 16) {
+        originXK = startXKm - widthKm / 2;
+        originYK = startYKm - heightKm / 2;
+    }
+    const xMin = originXK;
+    const xMax = originXK + widthKm;
+    const yMin = originYK;
+    const yMax = originYK + heightKm;
+    const corner = (x: number, y: number) => Math.hypot(x, y);
+    let maxR = corner(xMin, yMin);
+    maxR = Math.max(maxR, corner(xMax, yMin));
+    maxR = Math.max(maxR, corner(xMin, yMax));
+    maxR = Math.max(maxR, corner(xMax, yMax));
+    maxR = Math.min(460, Math.max(50, maxR * 1.02));
+
+    const nRays = 720;
+    const gateWidthKm = 0.5;
+    const nGates = Math.min(920, Math.max(64, Math.ceil(maxR / gateWidthKm)));
+    const firstGateKm = 0;
+
+    const gateData = new Uint8Array(nRays * nGates * 2);
+    const rayBoundariesDeg = new Float32Array(nRays + 1);
+    const deltaAz = 360 / nRays;
+    for (let i = 0; i <= nRays; i++) {
+        rayBoundariesDeg[i] = i * deltaAz - deltaAz * 0.5;
+    }
+
+    let samples = 0;
+    let nodata = 0;
+    for (let rayIdx = 0; rayIdx < nRays; rayIdx++) {
+        const azDeg = (rayIdx + 0.5) * deltaAz;
+        const azRad = (azDeg * Math.PI) / 180;
+        const sinAz = Math.sin(azRad);
+        const cosAz = Math.cos(azRad);
+        for (let g = 0; g < nGates; g++) {
+            const rKm = firstGateKm + (g + 0.5) * gateWidthKm;
+            const xKm = rKm * sinAz;
+            const yKm = rKm * cosAz;
+            const fc = (xKm - originXK) / cellKmX;
+            const fr = (yKm - originYK) / cellKmY;
+            const c = Math.floor(fc);
+            const r = Math.floor(fr);
+            let level: number | null = null;
+            if (c >= 0 && c < nCols && r >= 0 && r < nRows) {
+                level = rows[r][c] ?? null;
+            }
+            let phys: number | null = null;
+            if (level != null && Number.isFinite(level)) {
+                if (
+                    decodeMode === 'vil' &&
+                    vilLevelThresholds &&
+                    level >= 0 &&
+                    level < vilLevelThresholds.length &&
+                    Number.isFinite(vilLevelThresholds[level])
+                ) {
+                    phys = vilLevelThresholds[level];
+                } else if (decodeMode === 'tops_kft' && eetThresholds) {
+                    phys = level3EetHeightKmFromLevel(
+                        level,
+                        eetThresholds.dataMask,
+                        eetThresholds.scale,
+                        eetThresholds.offset,
+                    );
+                } else if (LEVEL3_DIGITAL_HMC_PRODUCT_CODES.has(l3ProductCode)) {
+                    phys = level3PhysicalFromDigitalHmc(level, 'nibble');
+                } else if (genericDigital) {
+                    phys = level3PhysicalFromGenericDigital(level, genericDigital, l3ProductCode);
+                } else {
+                    phys = level3PhysicalFromDataLevel(level, minT, dataInc, symMode);
+                }
+            }
+            if (phys == null || !Number.isFinite(phys)) {
+                nodata++;
+                const offset = (rayIdx * nGates + g) * 2;
+                gateData[offset] = 0x80;
+                gateData[offset + 1] = 0x00;
+                continue;
+            }
+            samples++;
+            const rawSigned = Math.round((phys - valueOffset) / valueScale);
+            const [hi, lo] = encodeSigned16ToHiLo(rawSigned);
+            const offset = (rayIdx * nGates + g) * 2;
+            gateData[offset] = hi;
+            gateData[offset + 1] = lo;
+        }
+    }
+    if (samples < 8) {
+        console.warn('[aguacero][nexrad-l3][raster-nearly-empty]', { objectKey, samples, nodata });
+        return null;
+    }
+    return {
+        gateData,
+        nRays,
+        nGates,
+        stationLat,
+        stationLon,
+        firstGateKm,
+        gateWidthKm,
+        valueScale,
+        valueOffset,
+        rayBoundariesDeg,
+    };
+}
+
+/**
+ * Validate Level-III Product Description Block (PDB) start at `pos`.
+ *
+ * Two valid layouts are seen in the wild:
+ * 1) Divider-first PDB (`0xFFFF`, then lat/lon)
+ * 2) Message-header-first (`productCode`, ... , divider at +18, then lat/lon)
+ *
+ * Use strict plausibility checks so we don't lock onto random halfwords.
+ */
+function isValidLevel3PdbStart(bytes: Uint8Array, pos: number): boolean {
+    const len = bytes.length;
+    if (pos + 14 > len) return false;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const latLonPlausible = (latMilli: number, lonMilli: number): boolean => {
+        const lat = latMilli / 1000;
+        const lon = lonMilli / 1000;
+        return (
+            lat >= -60 &&
+            lat <= 72 &&
+            lon >= -180 &&
+            lon <= 180 &&
+            Math.abs(lat) > 1 &&
+            Math.abs(lon) > 1
+        );
+    };
+
+    // Layout A: divider-first
+    if (bytes[pos] === 0xff && bytes[pos + 1] === 0xff) {
+        const latMilli = view.getInt32(pos + 2, false);
+        const lonMilli = view.getInt32(pos + 6, false);
+        return latLonPlausible(latMilli, lonMilli);
+    }
+
+    // Layout B: message-header-first (divider at +18, lat/lon at +20/+24)
+    if (pos + 28 <= len) {
+        const productCode = view.getUint16(pos, false);
+        const divider = view.getInt16(pos + 18, false);
+        if (productCode >= 1 && productCode <= 499 && divider === -1) {
+            const latMilli = view.getInt32(pos + 20, false);
+            const lonMilli = view.getInt32(pos + 24, false);
+            if (latLonPlausible(latMilli, lonMilli)) return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * PDB byte offset within the Level-III file (after optional SDUS trim).
+ * NOAAPort/Unidata objects use a short ASCII preamble (SDUS line + product/site line) then binary.
+ * A naive scan for 0xFFFF+lat/lon matches an *internal* digital divider (e.g. DVL at byte ~48) and
+ * mis-parses symbology offsets — only consider candidates that start immediately after a line break.
+ */
+function findLevel3PdbByteOffset(bytes: Uint8Array): number {
+    const len = bytes.length;
+    let pos = 0;
+    while (pos < len) {
+        let lineEnd = pos;
+        while (lineEnd < len && bytes[lineEnd] !== 0x0a && bytes[lineEnd] !== 0x0d) lineEnd++;
+        while (lineEnd < len && (bytes[lineEnd] === 0x0a || bytes[lineEnd] === 0x0d)) lineEnd++;
+        const nextStart = lineEnd;
+        if (nextStart >= len - 2) break;
+        if (isValidLevel3PdbStart(bytes, nextStart)) return nextStart;
+        pos = nextStart;
+    }
+    if (len < 30) return 30;
+    const end = Math.min(len - 14, 900);
+    for (let i = 16; i <= end; i++) {
+        if (isValidLevel3PdbStart(bytes, i)) return i;
+    }
+    return 30;
+}
+
+/** Decode Level-III radial raster (symbology block, packets 0x0010 / 0xAF1F) or raster image 0xBA07. */
+function decodeLevel3RasterProduct(buffer: ArrayBuffer, objectKey: string, radarVariable: string): DecodedRadarFrame | null {
+    try {
+        const bytes = new Uint8Array(buffer);
+        const marker = [83, 68, 85, 83]; // SDUS
+        let startIndex = 0;
+        for (let i = 0; i <= bytes.length - marker.length; i++) {
+            if (
+                bytes[i] === marker[0] &&
+                bytes[i + 1] === marker[1] &&
+                bytes[i + 2] === marker[2] &&
+                bytes[i + 3] === marker[3]
+            ) {
+                startIndex = i;
+                break;
+            }
+        }
+        const trimmed = startIndex > 0 ? bytes.subarray(startIndex) : bytes;
+        const raf = new Level3Raf(trimmed);
+
+        const fileType = raf.readString(6);
+        if (!fileType.startsWith('SDUS')) {
+            throw new Error(`Unexpected Level3 header ${fileType}`);
+        }
+        const pdbByteOffset = findLevel3PdbByteOffset(trimmed);
+        raf.seek(pdbByteOffset);
+        const headerWord0 = raf.readShort();
+        let stationLat: number;
+        let stationLon: number;
+        let productCode: number;
+        if (headerWord0 === -1) {
+            stationLat = raf.readInt() / 1000;
+            stationLon = raf.readInt() / 1000;
+            raf.readShort(); // height
+            productCode = raf.readUShort();
+        } else {
+            raf.seek(pdbByteOffset);
+            productCode = raf.readUShort();
+            raf.readShort(); // julianDate
+            raf.readInt(); // seconds
+            raf.readInt(); // length
+            raf.readShort(); // source
+            raf.readShort(); // dest
+            raf.readShort(); // blocks
+            const divider = raf.readShort();
+            if (divider !== -1) throw new Error(`Invalid product divider ${divider}`);
+            stationLat = raf.readInt() / 1000;
+            stationLon = raf.readInt() / 1000;
+            raf.readShort(); // height
+            raf.readShort(); // code
+        }
+        raf.readShort(); // mode
+        raf.readShort(); // vcp
+        raf.readShort(); // sequenceNumber
+        raf.readShort(); // volumeScanNumber
+        raf.readShort(); // volumeScanDate
+        raf.readInt(); // volumeScanTime
+        raf.readShort(); // productDate
+        raf.readInt(); // productTime
+        raf.read(4); // dependent27_28
+        raf.readShort(); // elevationNumber
+
+        const dep30_53 = new Level3Raf(raf.read(48));
+        const depProductDescriptionShorts: number[] = [];
+        for (let i = 0; i < 24; i++) {
+            depProductDescriptionShorts.push(dep30_53.readShort());
+        }
+        const minimumDataValue = depProductDescriptionShorts[1] / 10;
+        const dataIncrement = depProductDescriptionShorts[2] / 10;
+        const compressionMethod = depProductDescriptionShorts[21];
+        const genericDigitalParams = LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES.has(productCode)
+            ? parseLevel3GenericDigitalParams(depProductDescriptionShorts)
+            : null;
+
+        if (LEVEL3_GENERIC_DIGITAL_PRODUCT_CODES.has(productCode) && !genericDigitalParams) {
+            console.warn('[aguacero][nexrad-l3][generic-digital-params-null]', {
+                objectKey,
+                radarVariable,
+                productCode,
+                depHead: depProductDescriptionShorts.slice(0, 12),
+                hint: 'Continuing with legacy min/inc; precip values may be wrong — check dep alignment / PDB offset.',
+            });
+        }
+
+        // Product 134 (Digital VIL) uses a piecewise linear+log scale encoded
+        // in threshold halfwords 31-35, not the standard min+level*inc formula.
+        let msg134Params: { linearScale: number; linearOffset: number; logStart: number; logScale: number; logOffset: number } | null = null;
+        if (productCode === 134 && depProductDescriptionShorts.length >= 6) {
+            const hw31 = depProductDescriptionShorts[1];
+            const hw32 = depProductDescriptionShorts[2];
+            const hw33 = depProductDescriptionShorts[3];
+            const hw34 = depProductDescriptionShorts[4];
+            const hw35 = depProductDescriptionShorts[5];
+            msg134Params = {
+                linearScale:  int16ToFloat16(hw31),
+                linearOffset: int16ToFloat16(hw32),
+                logStart:     hw33,
+                logScale:     int16ToFloat16(hw34),
+                logOffset:    int16ToFloat16(hw35),
+            };
+        }
+        const l3Entry = getNexradLevel3EntryByRadarKey(radarVariable);
+        const decodeMode: Level3DecodeMode =
+            l3Entry?.decodeMode ??
+            (radarVariable === 'VEL' ||
+            radarVariable === 'N0G' ||
+            radarVariable === 'SW' ||
+            radarVariable === 'N0W'
+                ? 'velocity'
+                : 'dbz');
+        const isVelSw = decodeMode === 'velocity';
+
+        let minThreshold = minimumDataValue;
+        let dataInc = dataIncrement;
+        if (isVelSw) {
+            const pdbLooksInvalid =
+                !Number.isFinite(dataInc) ||
+                dataInc <= 0 ||
+                dataInc > 25 ||
+                !Number.isFinite(minThreshold) ||
+                Math.abs(minThreshold) > 130;
+            if (pdbLooksInvalid) {
+                minThreshold = -63.5;
+                dataInc = 0.5;
+            }
+        }
+        /** Product 138 (DTA): MetPy `DigitalStormPrecipMapper` uses thr2 × 0.01 in, not × 0.1. */
+        if (decodeMode === 'precip' && productCode === 138) {
+            dataInc = depProductDescriptionShorts[2] * 0.01;
+        }
+
+        /** Product 135 (EET) only: DigitalEET threshold triple in PDB. Classic echo tops (41 / NET) use min+inc like reflectivity. */
+        const eetRadialThresholds =
+            decodeMode === 'tops_kft' && productCode === 135
+                ? {
+                      dataMask: depProductDescriptionShorts[1],
+                      scale: depProductDescriptionShorts[2],
+                      offset: depProductDescriptionShorts[3],
+                  }
+                : null;
+        raf.readByte(); // version
+        raf.readByte(); // spotBlank
+        const offsetSymbology = raf.readInt();
+        raf.readInt(); // offsetGraphic
+        raf.readInt(); // offsetTabular
+
+        let parseBytes = trimmed;
+        if (compressionMethod > 0) {
+            const headerBytes = trimmed.subarray(0, raf.getPos());
+            const compressedTail = trimmed.subarray(raf.getPos());
+            const decompressedTail = bzip.decode(compressedTail) as Uint8Array;
+            parseBytes = concatUint8(headerBytes, decompressedTail);
+        }
+        const parseRaf = new Level3Raf(parseBytes);
+        const symbologyOffsetBytes = pdbByteOffset + offsetSymbology * 2;
+
+        parseRaf.seek(symbologyOffsetBytes);
+
+        const blockDivider = parseRaf.readShort();
+        const blockId = parseRaf.readShort();
+        if (blockDivider !== -1 || blockId !== 1) {
+            const oob = symbologyOffsetBytes < 0 || symbologyOffsetBytes >= parseBytes.length;
+            console.warn('[aguacero][nexrad-l3][symbology-header-bad]', {
+                objectKey,
+                radarVariable,
+                productCode,
+                blockDivider,
+                blockId,
+                symbologyOffsetBytes,
+                parseBytesLength: parseBytes.length,
+                seekOob: oob,
+                hint: 'Usually wrong PDB byte offset; check [sym-offset] and findLevel3PdbByteOffset.',
+            });
+            throw new Error(`Invalid symbology header ${blockDivider}/${blockId}`);
+        }
+        parseRaf.readInt(); // blockLength
+        const numberLayers = parseRaf.readShort();
+
+        /** Scan every layer and every packet (MetPy-style): prefer largest gate×ray footprint, then 0x10 over RLE. */
+        let bestRadial: Level3RadialPick | null = null;
+        let rasterParsed: Level3ParsedRaster | null = null;
+        const symbologyPacketCodes: number[] = [];
+        for (let layerIndex = 0; layerIndex < numberLayers; layerIndex++) {
+            const layerStart = parseRaf.getPos();
+            const layerDivider = parseRaf.readShort();
+            /** Bytes of symbology payload following this 4-byte field (ICD; same as MetPy `layer_hdr.length`). */
+            const layerPayloadLength = parseRaf.readInt();
+            if (layerDivider !== -1) {
+                parseRaf.seek(layerStart + 6 + layerPayloadLength);
+                continue;
+            }
+            /** End of layer = after 6-byte layer record (divider + length) + payload (MetPy marks `layer_start` after header). */
+            const layerEnd = parseRaf.getPos() + layerPayloadLength;
+            while (parseRaf.getPos() < layerEnd) {
+                const packetPos = parseRaf.getPos();
+                const packetCode = parseRaf.readUShort();
+                symbologyPacketCodes.push(packetCode);
+                parseRaf.seek(packetPos);
+                if (packetCode === 16) {
+                    const symMode: Level3SymbologyMode = isVelSw
+                        ? 'digital_velocity_byte'
+                        : decodeMode === 'precip' && !genericDigitalParams
+                          ? 'standard_digital'
+                          : 'reflectivity';
+                    const p = parseLevel3Packet0010(
+                        parseRaf,
+                        minThreshold,
+                        dataInc,
+                        symMode,
+                        productCode,
+                        msg134Params,
+                        eetRadialThresholds,
+                        genericDigitalParams,
+                    );
+                    const cand: Level3RadialPick = { kind: 0x10, packet: p };
+                    if (level3RadialPickIsBetter(cand, bestRadial)) bestRadial = cand;
+                    continue;
+                }
+                if (packetCode === 0xAF1F) {
+                    const symMode: Level3SymbologyMode = isVelSw
+                        ? 'digital_velocity_rle4'
+                        : decodeMode === 'precip' && !genericDigitalParams
+                          ? 'standard_digital'
+                          : 'reflectivity';
+                    const p = parseLevel3PacketAF1F(
+                        parseRaf,
+                        minThreshold,
+                        dataInc,
+                        symMode,
+                        productCode,
+                        msg134Params,
+                        eetRadialThresholds,
+                        genericDigitalParams,
+                    );
+                    const cand: Level3RadialPick = { kind: 0xaf1f, packet: p };
+                    if (level3RadialPickIsBetter(cand, bestRadial)) bestRadial = cand;
+                    continue;
+                }
+                if (packetCode === LEVEL3_PACKET_RASTER_BA07) {
+                    parseRaf.seek(packetPos);
+                    const parsed = parseLevel3PacketRasterBA07(parseRaf, layerEnd, objectKey);
+                    if (parsed && rasterParsed === null) rasterParsed = parsed;
+                    else if (!parsed) parseRaf.seek(layerEnd);
+                    continue;
+                }
+                if (trySkipLevel3OverlayPacket(parseRaf, packetCode, layerEnd)) {
+                    continue;
+                }
+                parseRaf.seek(layerEnd);
+                break;
+            }
+            parseRaf.seek(layerEnd);
+        }
+
+        /**
+         * EET (135): ICD uses up to **256** data levels on digital radials (packet 0x0010 full bytes).
+         * Raster 0xBA07 RLE is **4-bit** (levels 0–15 only), which caps echo-top heights near ~10 km (~33 kft)
+         * even though the radial product carries the full dynamic range. Prefer radials when both exist.
+         *
+         * Digital precip: raster grid avoids radial fan artifacts.
+         * Do **not** prefer raster for dual-pol generic-digital products (e.g. 163 N0K KDP): 0xBA07 RLE is **4-bit**
+         * (levels 0–15) while 0x0010 radials are **8-bit** — using the raster makes KDP/ZDR-style fields one flat color.
+         */
+        const shouldPreferRaster =
+            rasterParsed != null &&
+            ((decodeMode === 'tops_kft' && productCode !== 135) || decodeMode === 'precip');
+
+        if (bestRadial && !shouldPreferRaster) {
+            const radialPacket = bestRadial.packet;
+            const radials = radialPacket?.radials;
+            const nRays = Number(radialPacket?.numberRadials);
+            const nGates = Number(radialPacket?.numberBins);
+            if (!Array.isArray(radials) || !Number.isFinite(nRays) || !Number.isFinite(nGates) || !Number.isFinite(stationLat) || !Number.isFinite(stationLon)) {
+                console.warn('[aguacero][nexrad-l3][invalid-radial-packet]', { objectKey, radarVariable, nRays, nGates, stationLat, stationLon });
+            } else {
+                const gateData = new Uint8Array(nRays * nGates * 2);
+                const { valueScale, valueOffset } = level3ValuePacking(decodeMode);
+                for (let r = 0; r < nRays; r++) {
+                    const bins = radials[r]?.bins;
+                    for (let g = 0; g < nGates; g++) {
+                        const v = bins?.[g];
+                        const isNoData = v == null || !Number.isFinite(v);
+                        const rawSigned = isNoData
+                            ? -32768
+                            : Math.round((Number(v) - valueOffset) / valueScale);
+                        const [hi, lo] = encodeSigned16ToHiLo(rawSigned);
+                        const offset = (r * nGates + g) * 2;
+                        gateData[offset] = hi;
+                        gateData[offset + 1] = lo;
+                    }
+                }
+
+                const rangeMul = LEVEL3_PRODUCT_RANGE_SCALE_MUL[productCode] ?? 1;
+                const rangeScaleRaw = Number(radialPacket?.rangeScaleRaw);
+                const gateSpacingM =
+                    Number.isFinite(rangeScaleRaw) && rangeScaleRaw > 0 ? rangeScaleRaw * rangeMul : 250;
+                let gateWidthKm = gateSpacingM / 1000;
+                const firstBinM = Number(radialPacket?.firstBinMeters);
+                let firstGateKm = Number.isFinite(firstBinM) && firstBinM >= 0 ? firstBinM / 1000 : 0;
+                const decodedCoverageKm = firstGateKm + nGates * gateWidthKm;
+                if (decodedCoverageKm > 0 && decodedCoverageKm < 20 && nGates >= 100) {
+                    gateWidthKm *= 1000;
+                    firstGateKm *= 1000;
+                }
+                // Guard against km↔m mismatch producing global wedges for precip products.
+                if (decodeMode === 'precip' && decodedCoverageKm > 1500) {
+                    gateWidthKm /= 1000;
+                    firstGateKm /= 1000;
+                }
+                const rayBoundariesDeg = buildRayBoundariesFromLevel3Radials(radials);
+
+                return {
+                    gateData,
+                    nRays,
+                    nGates,
+                    stationLat,
+                    stationLon,
+                    firstGateKm,
+                    gateWidthKm,
+                    valueScale,
+                    valueOffset,
+                    rayBoundariesDeg,
+                };
+            }
+        }
+
+        if (rasterParsed) {
+            const { valueScale, valueOffset } = level3ValuePacking(decodeMode);
+            const { minT, dataInc: rasterDataInc, symMode, vilLevelThresholds } = level3RasterPdbScales(
+                decodeMode,
+                productCode,
+                minThreshold,
+                dataInc,
+                depProductDescriptionShorts,
+                objectKey,
+                genericDigitalParams,
+            );
+            const eetThresholds =
+                decodeMode === 'tops_kft' && productCode === 135
+                    ? {
+                          dataMask: depProductDescriptionShorts[1],
+                          scale: depProductDescriptionShorts[2],
+                          offset: depProductDescriptionShorts[3],
+                      }
+                    : null;
+            const rasterFrame = level3RasterToPolarFrame(
+                rasterParsed,
+                stationLat,
+                stationLon,
+                decodeMode,
+                minT,
+                rasterDataInc,
+                symMode,
+                vilLevelThresholds,
+                eetThresholds,
+                valueScale,
+                valueOffset,
+                objectKey,
+                genericDigitalParams,
+                productCode,
+            );
+            if (rasterFrame) {
+                return rasterFrame;
+            }
+        }
+
+        const hex = symbologyPacketCodes.map((c) => `0x${c.toString(16)}`);
+        if (!bestRadial) {
+            console.warn('[aguacero][nexrad-l3][no-radial-symbology]', {
+                objectKey,
+                radarVariable,
+                messageCode: productCode,
+                numberLayers,
+                symbologyPacketCodes,
+                symbologyPacketCodesHex: hex,
+                hint: 'Radial: packets 0x10 / 0xAF1F. Raster: 0xBA07 is supported; if rasterParsed failed, check parseLevel3PacketRasterBA07 / inner code logs.',
+            });
+        }
+        return null;
+    } catch (err) {
+        console.warn('[aguacero][nexrad-l3][decode-throw]', { objectKey, radarVariable, err });
+        return null;
+    }
+}
+
+const GROUP2_VARS = ['SW'];
+/** g2 split-cut in clear-air mode (VCP 35): REF + VEL + SW in one file (legacy archives only). */
+const GROUP2_COMBINED_3_VARS = ['REF', 'VEL', 'SW'];
+/** g1 dual-pol + REF; order must match writer. KDP is Level-III (N0K), not in g1 bins. */
+const GROUP1_VARS = ['REF', 'ZDR', 'RHO', 'PHI'] as const;
+/** g2 combined tilt with KDP (7 slots); order must match writer. */
+const GROUP2_COMBINED_7_VARS = ['REF', 'ZDR', 'RHO', 'PHI', 'KDP', 'VEL', 'SW'];
+const GROUP2_COMBINED_VARS = ['REF', 'ZDR', 'RHO', 'PHI', 'VEL', 'SW'];
+
+// Fixed sizes matching the Python writer (`lambda_function.py` MAX_RAYS / AZ_BLOCK_BYTES).
+const FILE_HDR_BYTES = 64;
+const LEVEL2_AZ_BLOCK_RAYS = 720;
+const LEVEL2_AZ_BLOCK_BYTES = LEVEL2_AZ_BLOCK_RAYS * 4;
+/** Per-sweep Nyquist (m/s), big-endian float32 after azimuth block and before slot index (writer `nyquist_bytes`). */
+const LEVEL2_FILE_NYQUIST_BYTES = 4;
+const SLOT_INDEX_ENTRY = 18;
+const MAX_SLOTS = 7; // g2 combined tilt can write 7 fields (GROUP2_COMBINED_7_VARS)
+
+interface FileHeader {
+    unixTime:   number;
+    nRays:      number;
+    nGates:     number;
+    elevAngle:  number;
+    firstGateKm: number;
+    gateWidthKm: number;
+    nSlots:     number;
+    azimuthsBuffer: ArrayBuffer;  // raw big-endian float32 bytes (720*4)
+    slots: Array<{ offset: number; compressedSize: number; uncompressedSize: number }>;
+    /** Nyquist velocity (m/s) from file header after azimuths; null if non-finite / out of band. */
+    embeddedNyquistMs: number | null;
+}
+
+function int16ToFloat16(val: number): number {
+    const sign = (val & 0b1000000000000000) / 0b1000000000000000;
+    const exponent = (val & 0b0111110000000000) / 0b0000010000000000;
+    const fraction = val & 0b0000001111111111;
+    if (exponent === 0) {
+        return Math.pow(-1, sign) * 2 * (0 + fraction / Math.pow(2, 10));
+    }
+    return Math.pow(-1, sign) * Math.pow(2, exponent - 16) * (1 + fraction / Math.pow(2, 10));
+}
+
+/**
+ * Total Level-II object size when known.
+ * For 206 partial responses, only `Content-Range: bytes a-b/total` gives `total` — `Content-Length` is the segment size.
+ */
+function nexradLevel2ResourceTotalBytes(resp: Response): number | null {
+    const cr = resp.headers.get('Content-Range');
+    if (cr) {
+        const m = cr.trim().match(/\/(\d+)\s*$/);
+        if (m) {
+            const n = Number(m[1]);
+            return Number.isFinite(n) && n > 0 ? n : null;
+        }
+    }
+    if (resp.status === 200) {
+        const cl = resp.headers.get('Content-Length');
+        if (cl) {
+            const n = Number(cl);
+            return Number.isFinite(n) && n > 0 ? n : null;
+        }
+    }
+    return null;
+}
+
+function parseFileHeader(buffer: ArrayBuffer, azBlockBytes: number): FileHeader {
+    const view = new DataView(buffer);
+    const magic = view.getUint32(0, false);
+    if (magic !== 0x4E584244) throw new Error(`Bad magic: 0x${magic.toString(16)}`);
+
+    const unixTime    = view.getUint32(4,  false);
+    const nRays       = view.getUint16(8,  false);
+    const nGates      = view.getUint16(10, false);
+    const elevAngle   = view.getFloat32(12, false);
+    const firstGateKm = view.getFloat32(16, false);
+    const gateWidthKm = view.getFloat32(20, false);
+    const nSlots      = view.getUint16(24, false);
+
+    const azimuthsBuffer = buffer.slice(FILE_HDR_BYTES, FILE_HDR_BYTES + azBlockBytes);
+
+    const azEnd = FILE_HDR_BYTES + azBlockBytes;
+    const idxStart = azEnd + LEVEL2_FILE_NYQUIST_BYTES;
+    const needBytes = idxStart + nSlots * SLOT_INDEX_ENTRY;
+    if (buffer.byteLength < needBytes) {
+        throw new Error(`level2 header buffer too small: ${buffer.byteLength} < ${needBytes}`);
+    }
+
+    const nyqCandidate = view.getFloat32(azEnd, false);
+    const embeddedNyquistMs =
+        Number.isFinite(nyqCandidate) && nyqCandidate > 0.5 && nyqCandidate < 128 ? nyqCandidate : null;
+
+    const slots: Array<{ offset: number; compressedSize: number; uncompressedSize: number }> = [];
+    for (let i = 0; i < nSlots; i++) {
+        const base = idxStart + i * SLOT_INDEX_ENTRY;
+        const offsetHigh = view.getUint32(base, false);
+        const offsetLow = view.getUint32(base + 4, false);
+        const offset = offsetHigh * 2 ** 32 + offsetLow;
+        const compressedSize = view.getUint32(base + 8, false);
+        const uncompressedSize = view.getUint32(base + 12, false);
+        slots.push({ offset, compressedSize, uncompressedSize });
+    }
+
+    return {
+        unixTime,
+        nRays,
+        nGates,
+        elevAngle,
+        firstGateKm,
+        gateWidthKm,
+        nSlots,
+        azimuthsBuffer,
+        slots,
+        embeddedNyquistMs,
+    };
+}
+
+function decodeSweepInWorker(
+    objectKey: string,
+    slotBuffer: ArrayBuffer,
+    header: FileHeader,
+    sites: NexradSite[],
+    priority: 'display' | 'prefetch',
+    signal?: AbortSignal,
+): Promise<DecodedRadarFrame | null> {
+    if (signal?.aborted) return Promise.reject(createAbortError());
+
+    const { worker } = getDecodeWorkerForPriority(priority);
+    const requestId = ++radarDecodeRequestId;
+
+    // Transfer a copy of azimuthsBuffer so we don't detach the cached header
+    const azCopy = header.azimuthsBuffer.slice(0);
+
+    return new Promise((resolve, reject) => {
+        let isSettled = false;
+        const onAbort = () => {
+            if (isSettled) return;
+            isSettled = true;
+            radarDecodePending.delete(requestId);
+            radarDecodeRequestMeta.delete(requestId);
+            signal?.removeEventListener('abort', onAbort);
+            reject(createAbortError());
+        };
+
+        radarDecodePending.set(requestId, {
+            resolve: (frame) => { if (!isSettled) { isSettled = true; signal?.removeEventListener('abort', onAbort); resolve(frame); } },
+            reject:  (err)   => { if (!isSettled) { isSettled = true; signal?.removeEventListener('abort', onAbort); reject(err); } },
+        });
+
+        if (signal) signal.addEventListener('abort', onAbort, { once: true });
+
+        worker.postMessage({
+            type: 'DECODE_SLOT',
+            requestId,
+            objectKey,
+            slotBuffer,
+            nRays:       header.nRays,
+            nGates:      header.nGates,
+            firstGateKm: header.firstGateKm,
+            gateWidthKm: header.gateWidthKm,
+            azimuthsBuffer: azCopy,
+            sites,
+        }, [slotBuffer, azCopy]);
+    });
+}
+
+function resolveLevel3SrvMotionObjectKey(
+    unixTime: number | null | undefined,
+    motionMap: Record<string, string> | undefined,
+    radarSource: 'level2' | 'level3',
+    radarVar: string,
+    useStormRelativeMotion: boolean,
+): string | null {
+    if (radarVar !== 'VEL' || !useStormRelativeMotion || unixTime == null || !motionMap) {
+        return null;
+    }
+    return pickNearestLevel3ObjectKey(unixTime, motionMap);
+}
+
+/** Reuse parsed N0S motion across time steps (SRV: same motion key is common while scrubbing). */
+const N0S_MOTION_CACHE_MAX = 128;
+const n0sMotionVectorCache = new Map<string, { speedMs: number; directionDeg: number }>();
+
+function getCachedN0sMotion(motionObjectKey: string) {
+    return n0sMotionVectorCache.get(motionObjectKey);
+}
+function setCachedN0sMotion(
+    motionObjectKey: string,
+    motion: { speedMs: number; directionDeg: number },
+) {
+    n0sMotionVectorCache.set(motionObjectKey, motion);
+    while (n0sMotionVectorCache.size > N0S_MOTION_CACHE_MAX) {
+        const first = n0sMotionVectorCache.keys().next().value as string | undefined;
+        if (first === undefined) break;
+        n0sMotionVectorCache.delete(first);
+    }
+}
+
+async function applyStormMotionFromN0sObjectKey(
+    frame: DecodedRadarFrame,
+    motionObjectKey: string,
+    logLabel: string,
+): Promise<DecodedRadarFrame> {
+    const cached = getCachedN0sMotion(motionObjectKey);
+    if (cached) {
+        return applyLevel3StormRelativeToFrame(frame, cached.speedMs, cached.directionDeg);
+    }
+    const motionUrl = objectKeyToUrl(motionObjectKey, 'level3');
+    try {
+        const motionResp = await fetch(motionUrl);
+        if (motionResp.ok) {
+            const motionBuf = await motionResp.arrayBuffer();
+            const motion = parseLevel3StormMotionFromBuffer(motionBuf);
+            if (motion) {
+                setCachedN0sMotion(motionObjectKey, motion);
+                return applyLevel3StormRelativeToFrame(frame, motion.speedMs, motion.directionDeg);
+            }
+        }
+    } catch (e) {
+        console.log(`${logLabel}:srvMotionFetchError`, { motionObjectKey, err: e });
+    }
+    return frame;
+}
+
+export async function fetchAndParseArchive(
+    url: string,
+    objectKey: string,
+    radarVariable: string,
+    groupId: number,
+    radarSource: 'level2' | 'level3',
+    options?: {
+        signal?: AbortSignal;
+        priority?: 'display' | 'prefetch';
+        /** N0S S3 object key — with VEL, apply SRV (L3: N0G+motion; L2: super-res velocity + nearest-time N0S motion). */
+        level3MotionObjectKey?: string | null;
+    },
+): Promise<DecodedRadarFrame | null> {
+    const mot = options?.level3MotionObjectKey ? `|${options.level3MotionObjectKey}` : '';
+    const cacheKey = `${url}:${radarVariable}:${radarSource}${mot}`;
+    const priority = options?.priority ?? 'display';
+
+    if (archiveCache.has(cacheKey)) {
+        const cached = archiveCache.get(cacheKey)!;
+        setArchiveCache(cacheKey, cached);
+        return cached;
+    }
+    const existingInflight = inflightFetches.get(cacheKey);
+    if (existingInflight) {
+        const meta = inflightFetchMeta.get(cacheKey);
+        if (meta) {
+            meta.callers += 1;
+        }
+        return existingInflight;
+    }
+
+    if (options?.signal?.aborted) {
+        return null;
+    }
+
+    const requestId = ++radarFetchRequestSeq;
+    const startedAt = performance.now();
+    inflightFetchMeta.set(cacheKey, {
+        requestId,
+        startedAt,
+        callers: 1,
+        objectKey,
+        radarVariable,
+        radarSource,
+        priority,
+    });
+
+    const promise = (async (): Promise<DecodedRadarFrame | null> => {
+        try {
+            if (radarSource === 'level3') {
+                const response = await fetch(url);
+                if (!response.ok) throw new Error(`HTTP ${response.status} fetching level3 ${url}`);
+                const buffer = await response.arrayBuffer();
+                let decoded = decodeLevel3RasterProduct(buffer, objectKey, radarVariable);
+                const motionKey = options?.level3MotionObjectKey;
+                if (decoded && motionKey && radarVariable === 'VEL') {
+                    decoded = await applyStormMotionFromN0sObjectKey(
+                        decoded,
+                        motionKey,
+                        'fetchAndParseArchive:level3',
+                    );
+                }
+                if (!decoded) {
+                    console.warn('[aguacero][nexrad-l3][fetch-ok-decode-null]', {
+                        objectKey,
+                        radarVariable,
+                        byteLength: buffer.byteLength,
+                        filterConsole: 'Also check [aguacero][nexrad-l3][no-radial-symbology] or decode catch logs',
+                    });
+                } else {
+                    setArchiveCache(cacheKey, decoded);
+                }
+                return decoded;
+            }
+
+// ── Level-2 two-request range path ───────────────────────────────────────
+            const level2Url = cloudFrontUrlWithApiKeyQuery(url);
+            nexradArchiveDiag('level2.pipeline.start', {
+                objectKey,
+                radarVariable,
+                groupId,
+                apiKeyLen: NEXRAD_ARCHIVE_API_KEY.length,
+                bundleIdLen: NEXRAD_ARCHIVE_BUNDLE_ID.length,
+                urlNoSecret: redactApiKeyFromUrl(level2Url),
+            });
+            // Request 1: fetch just the header + slot index to find byte offsets
+            const azBlockBytes = LEVEL2_AZ_BLOCK_BYTES;
+            const INDEX_FETCH_BYTES =
+                FILE_HDR_BYTES + azBlockBytes + LEVEL2_FILE_NYQUIST_BYTES + MAX_SLOTS * SLOT_INDEX_ENTRY;
+            nexradArchiveDiag('level2.index.fetch', {
+                objectKey,
+                byteRangeEnd: INDEX_FETCH_BYTES - 1,
+            });
+            const indexResp = await fetch(level2Url, {
+                headers: level2CloudFrontFetchHeaders(`bytes=0-${INDEX_FETCH_BYTES - 1}`),
+            });
+            nexradArchiveDiag('level2.index.response', {
+                objectKey,
+                status: indexResp.status,
+                ok: indexResp.ok,
+            });
+            if (!indexResp.ok && indexResp.status !== 206) {
+                throw new Error(`HTTP ${indexResp.status} fetching level2 index ${url}`);
+            }
+            const indexBuffer = await indexResp.arrayBuffer();
+            const indexResourceTotal = nexradLevel2ResourceTotalBytes(indexResp);
+            const header = parseFileHeader(indexBuffer, azBlockBytes);
+
+            const slotIndexBytes =
+                FILE_HDR_BYTES + azBlockBytes + LEVEL2_FILE_NYQUIST_BYTES + header.nSlots * SLOT_INDEX_ENTRY;
+            if (indexBuffer.byteLength < slotIndexBytes) {
+                console.warn('[RadarLayer] level2 index response shorter than slot table', {
+                    objectKey,
+                    byteLength: indexBuffer.byteLength,
+                    need: slotIndexBytes,
+                    nSlots: header.nSlots,
+                });
+                setArchiveCache(cacheKey, null);
+                return null;
+            }
+
+            // ── Step 2: find slot for this variable ─────────────────────
+            let varList: string[];
+            if (groupId === 2 && header.nSlots === 7) {
+                varList = GROUP2_COMBINED_7_VARS;
+            } else if (groupId === 2 && header.nSlots === 6) {
+                varList = GROUP2_COMBINED_VARS;
+            } else if (groupId === 2 && header.nSlots === 3) {
+                varList = GROUP2_COMBINED_3_VARS;
+            } else if (groupId === 2) {
+                varList = GROUP2_VARS;
+            } else {
+                varList = [...GROUP1_VARS];
+            }
+
+            const slotIdx = varList.indexOf(radarVariable);
+            if (slotIdx < 0 || slotIdx >= header.slots.length) {
+                console.warn(`[RadarLayer] ${radarVariable} not in group ${groupId} (nSlots=${header.nSlots})`);
+                setArchiveCache(cacheKey, null);
+                return null;
+            }
+
+            const slot = header.slots[slotIdx];
+            if (slot.compressedSize === 0) {
+                console.warn(`[RadarLayer] ${radarVariable} slot ${slotIdx} has compressedSize=0`);
+                setArchiveCache(cacheKey, null);
+                return null;
+            }
+
+            // ── Step 3: fetch exactly the slot bytes ────────────────────
+            const slotEndExclusive = slot.offset + slot.compressedSize;
+            if (indexResourceTotal != null && slotEndExclusive > indexResourceTotal) {
+                console.warn('[RadarLayer] level2 slot extends past object size (bad index or stale CDN)', {
+                    objectKey,
+                    radarVariable,
+                    slotIdx,
+                    offset: slot.offset,
+                    compressedSize: slot.compressedSize,
+                    indexResourceTotal,
+                });
+                setArchiveCache(cacheKey, null);
+                return null;
+            }
+
+            const slotRangeEnd = slotEndExclusive - 1;
+            const slotHeaders = level2CloudFrontFetchHeaders(`bytes=${slot.offset}-${slotRangeEnd}`);
+            nexradArchiveDiag('level2.slot.fetch', {
+                objectKey,
+                slotIdx,
+                compressedSize: slot.compressedSize,
+                offset: slot.offset,
+            });
+            let slotResp = await fetch(level2Url, { headers: slotHeaders });
+            nexradArchiveDiag('level2.slot.response', {
+                objectKey,
+                status: slotResp.status,
+                ok: slotResp.ok,
+            });
+            let slotBuffer: ArrayBuffer;
+            if (slotResp.ok || slotResp.status === 206) {
+                slotBuffer = await slotResp.arrayBuffer();
+            } else if (slotResp.status === 416) {
+                const fullResp = await fetch(level2Url, { headers: level2CloudFrontFetchHeaders(undefined) });
+                if (!fullResp.ok) {
+                    throw new Error(`HTTP ${fullResp.status} full fetch after 416 for level2 ${url}`);
+                }
+                const fullBuf = await fullResp.arrayBuffer();
+                if (slot.offset >= fullBuf.byteLength || slotEndExclusive > fullBuf.byteLength) {
+                    throw new Error(
+                        `level2 slot out of bounds after 416 fallback (offset=${slot.offset}, end=${slotEndExclusive}, file=${fullBuf.byteLength}) for ${url}`,
+                    );
+                }
+                slotBuffer = fullBuf.slice(slot.offset, slotEndExclusive);
+            } else {
+                throw new Error(`HTTP ${slotResp.status} fetching level2 slot ${url}`);
+            }
+
+            // ── Step 4: decode in worker ────────────────────────────────
+            nexradArchiveDiag('level2.decode.start', { objectKey, radarVariable });
+            const sites = await loadNexradSites();
+            let decoded = await decodeSweepInWorker(
+                objectKey, slotBuffer, header, sites,
+                options?.priority ?? 'display',
+                undefined,
+            );
+
+            if (!decoded) { setArchiveCache(cacheKey, null); return null; }
+            decoded = { ...decoded, embeddedNyquistMs: header.embeddedNyquistMs };
+            const l2MotionKey = options?.level3MotionObjectKey;
+            if (l2MotionKey && radarVariable === 'VEL') {
+                decoded = await applyStormMotionFromN0sObjectKey(
+                    decoded,
+                    l2MotionKey,
+                    'fetchAndParseArchive:level2',
+                );
+            }
+            setArchiveCache(cacheKey, decoded);
+            nexradArchiveDiag('level2.decode.done', {
+                objectKey,
+                radarVariable,
+                nRays: decoded.nRays ?? null,
+                nGates: decoded.nGates ?? null,
+            });
+            return decoded;
+        } catch (err) {
+            if (isAbortError(err)) {
+                return null;
+            }
+            nexradArchiveDiag('fetchAndParseArchive.failed', {
+                objectKey,
+                radarSource,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            console.error(`[RadarLayer] fetchAndParseArchive failed for ${objectKey}:`, err);
+            return null;
+        } finally {
+            inflightFetches.delete(cacheKey);
+            inflightFetchMeta.delete(cacheKey);
+        }
+    })();
+
+    inflightFetches.set(cacheKey, promise);
+    return promise;
+}
+