@aguacerowx/react-native 0.0.52 → 0.0.54

package/ios/SatelliteLayerView.swift

@@ -1,517 +1,517 @@
-import Foundation
-import MapboxMaps
-import React
-import UIKit
-
-@objc(SatelliteLayerView)
-public final class SatelliteLayerView: UIView {
-
-    /// Xcode / device console — grep `[AguaceroWX][SatelliteLayerView]` or `SatelliteLayerView`
-    private static func satLog(_ message: String) {
-        NSLog("[AguaceroWX][SatelliteLayerView] %@", message)
-    }
-
-    public static let satelliteLayerId = "aguacero-satellite-layer"
-    private static let weatherGridLayerId = "aguacero-weather-grid-custom"
-
-    @objc public var layerInstance: AguaceroSatelliteRenderer!
-    @objc public weak var mapView: MapView?
-    @objc public var layerId: String = SatelliteLayerView.satelliteLayerId
-    @objc public var belowID: String?
-
-    @objc public weak var bridge: RCTBridge?
-
-    private var isLayerAdded = false
-    private var satReparentScheduled = false
-
-    @objc public var satelliteLayerAdded: Bool { isLayerAdded }
-
-    private let decodeQueue = DispatchQueue(label: "com.aguacero.satellite-decode", qos: .utility)
-    private var decodeGeneration = 0
-    private var lastRunKey: String?
-
-    private var fetchInFlight = Set<Int64>()
-    private let fetchLock = NSLock()
-
-    private lazy var urlSession: URLSession = {
-        let c = URLSessionConfiguration.ephemeral
-        c.timeoutIntervalForRequest = 120
-        return URLSession(configuration: c)
-    }()
-
-    public override init(frame: CGRect) {
-        layerInstance = AguaceroSatelliteRenderer(id: SatelliteLayerView.satelliteLayerId)
-        super.init(frame: frame)
-        isOpaque = false
-        Self.satLog("init(frame:) SatelliteLayerView=\(Unmanaged.passUnretained(self).toOpaque())")
-    }
-
-    required init?(coder: NSCoder) {
-        layerInstance = AguaceroSatelliteRenderer(id: SatelliteLayerView.satelliteLayerId)
-        super.init(coder: coder)
-        isOpaque = false
-        Self.satLog("init(coder:) SatelliteLayerView=\(Unmanaged.passUnretained(self).toOpaque())")
-    }
-
-    public override func didMoveToWindow() {
-        super.didMoveToWindow()
-        if window != nil && !isLayerAdded {
-            findMapViewAndAddLayer(in: window!)
-        }
-    }
-
-    public override func layoutSubviews() {
-        super.layoutSubviews()
-        if !isLayerAdded {
-            let root = window ?? superview
-            if let root {
-                findMapViewAndAddLayer(in: root)
-            }
-        }
-    }
-
-    private func findMapViewAndAddLayer(in view: UIView) {
-        if isLayerAdded { return }
-        if let map = findMapViewRecursive(view) {
-            Self.satLog("findMapView: OK mapView attached, belowID=\(belowID ?? "nil")")
-            self.mapView = map
-            waitForStyleLoadAndAddLayer()
-        } else {
-            Self.satLog("findMapView: MapView not found under RNMBX hierarchy yet (will retry from layout/window)")
-        }
-    }
-
-    private func findMapViewRecursive(_ view: UIView) -> MapView? {
-        let name = NSStringFromClass(type(of: view))
-        if name == "RNMBXMapView", view.subviews.count > 0 {
-            let first = view.subviews[0]
-            let subName = NSStringFromClass(type(of: first))
-            if subName.contains("MapboxMaps.MapView") || subName == "MapView" {
-                return first as? MapView
-            }
-        }
-        for sub in view.subviews {
-            if let found = findMapViewRecursive(sub) {
-                return found
-            }
-        }
-        return nil
-    }
-
-    private func waitForStyleLoadAndAddLayer() {
-        guard let mapView else { return }
-        let anchor = belowID ?? "AML_-_terrain"
-        let anchorExists = GridRenderLayerBridge.layerExists(in: mapView, layerId: anchor)
-        Self.satLog("waitForStyle: anchor=\(anchor) exists=\(anchorExists) gridLayer=\(GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId))")
-        if anchorExists {
-            addLayerToMap()
-            return
-        }
-        pollForLayerExistence(anchor: anchor, attempts: 0)
-    }
-
-    private func pollForLayerExistence(anchor: String, attempts: Int) {
-        guard let mapView, !isLayerAdded else { return }
-        if attempts > 80 {
-            Self.satLog("pollAnchor: GAVE UP after ~\(attempts * 100)ms — layer id \"\(anchor)\" never appeared. Satellite custom layer was NOT added. Check Mapbox style / belowID prop.")
-            return
-        }
-        if attempts % 20 == 0, attempts > 0 {
-            Self.satLog("pollAnchor: still waiting for \"\(anchor)\" attempt=\(attempts)")
-        }
-        if GridRenderLayerBridge.layerExists(in: mapView, layerId: anchor) {
-            Self.satLog("pollAnchor: anchor \"\(anchor)\" appeared after \(attempts) attempts")
-            addLayerToMap()
-            return
-        }
-        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self] in
-            self?.pollForLayerExistence(anchor: anchor, attempts: attempts + 1)
-        }
-    }
-
-    private func addLayerToMap() {
-        guard let mapView, !isLayerAdded else { return }
-        guard let host = layerInstance.getHostWrapper() as? CustomLayerHost else {
-            Self.satLog("addLayerToMap: ABORT — CustomLayer host missing")
-            return
-        }
-
-        let success = GridRenderLayerBridge.addSatelliteCustomLayer(
-            to: mapView,
-            layerHost: host,
-            layerId: layerId,
-            weatherGridLayerId: Self.weatherGridLayerId,
-            belowLayerId: belowID
-        )
-
-        if success {
-            isLayerAdded = true
-            let gridThere = GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId)
-            Self.satLog("addLayerToMap: OK layerId=\(layerId) aboveGrid=\(gridThere) belowID=\(belowID ?? "nil")")
-            GridRenderLayerBridge.triggerRepaint(on: mapView)
-            scheduleReparentAboveGridOnce()
-        } else {
-            Self.satLog("addLayerToMap: FAILED Mapbox addLayer for layerId=\(layerId) — see GridRenderLayerBridge logs")
-        }
-    }
-
-    private func scheduleReparentAboveGridOnce() {
-        if satReparentScheduled { return }
-        satReparentScheduled = true
-        DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) { [weak self] in
-            self?.satReparentScheduled = false
-            self?.reparentAboveGridIfNeeded()
-        }
-    }
-
-    private func reparentAboveGridIfNeeded() {
-        guard let mapView else { return }
-        let gridOk = GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId)
-        let satOk = GridRenderLayerBridge.layerExists(in: mapView, layerId: layerId)
-        guard gridOk, satOk else {
-            Self.satLog("reparentAboveGrid: skip grid=\(gridOk) satellite=\(satOk)")
-            return
-        }
-        guard let host = layerInstance.getHostWrapper() as? CustomLayerHost else { return }
-
-        GridRenderLayerBridge.removeCustomLayer(from: mapView, layerId: layerId)
-        _ = GridRenderLayerBridge.addSatelliteCustomLayer(
-            to: mapView,
-            layerHost: host,
-            layerId: layerId,
-            weatherGridLayerId: Self.weatherGridLayerId,
-            belowLayerId: belowID
-        )
-        GridRenderLayerBridge.triggerRepaint(on: mapView)
-    }
-
-    private struct FrameClass {
-        let trueColor: Bool
-        let colormapKind: String
-        let useColormap: Bool
-    }
-
-    private static func classifyShaderFileName(_ shaderFileName: String?) -> FrameClass {
-        let fn = shaderFileName ?? ""
-        let isTrueColor =
-            fn.contains("_truecolor_")
-            || fn.contains("_geocolor_")
-            || fn.contains("_firetemperature_")
-            || fn.contains("_dust_")
-            || fn.contains("_simplewatervapor_")
-            || fn.contains("_ntmicro_")
-            || fn.contains("_daycloudphase_")
-            || fn.contains("_daylandcloudfire_")
-            || fn.contains("_airmass_")
-            || fn.contains("_sandwich_")
-
-        var colormapType = "none"
-        if fn.contains("C13") || fn.contains("C14") || fn.contains("C15") || fn.contains("C16") {
-            colormapType = "ir"
-        } else if fn.contains("C08") || fn.contains("C09") || fn.contains("C10") {
-            colormapType = "wv"
-        }
-
-        let useColormap = !isTrueColor && colormapType != "none"
-        return FrameClass(trueColor: isTrueColor, colormapKind: colormapType, useColormap: useColormap)
-    }
-
-    /// Match `WeatherLayerManager` grid `buildGridFrameProcessOptions`: authoritative `apiKey` in the query string
-    /// plus `x-api-key` on the request (same pattern as `AguaceroCore` grid / NEXRAD CDN).
-    private static func satelliteFetchURL(from url: URL, apiKey: String) -> URL {
-        guard var c = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return url }
-        var q = c.queryItems ?? []
-        q.removeAll { $0.name == "apiKey" }
-        q.append(URLQueryItem(name: "apiKey", value: apiKey))
-        if !q.contains(where: { $0.name == "userId" }) {
-            q.append(URLQueryItem(name: "userId", value: "sdk-user"))
-        }
-        c.queryItems = q
-        return c.url ?? url
-    }
-
-    @objc public func clearSatellite() {
-        Self.satLog("clearSatellite: bump decodeGeneration (was \(decodeGeneration)) → \(decodeGeneration + 1), cancel in-flight fetches")
-        decodeGeneration += 1
-        fetchLock.lock()
-        fetchInFlight.removeAll()
-        fetchLock.unlock()
-        layerInstance.clearAll()
-        if let mapView {
-            GridRenderLayerBridge.triggerRepaint(on: mapView)
-        }
-    }
-
-    @objc public func syncFromJson(_ json: String?) {
-        guard let json, !json.isEmpty,
-              let data = json.data(using: .utf8),
-              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
-        else {
-            Self.satLog("syncFromJson: SKIP empty or invalid JSON (nil=\(json == nil) len=\(json?.count ?? 0))")
-            return
-        }
-
-        let runKey = (obj["runKey"] as? String) ?? ""
-        if !runKey.isEmpty, runKey != lastRunKey {
-            Self.satLog("syncFromJson: new runKey=\(runKey) (invalidate caches + bump generation)")
-            lastRunKey = runKey
-            decodeGeneration += 1
-            fetchLock.lock()
-            fetchInFlight.removeAll()
-            fetchLock.unlock()
-            layerInstance.clearAll()
-        }
-
-        layerInstance.setVisible((obj["visible"] as? Bool) ?? true)
-        layerInstance.setOpacity(Float((obj["opacity"] as? Double) ?? 1.0))
-        layerInstance.setFillSmoothing(obj["fillSmoothing"] as? Int ?? 0)
-
-        if let tu = obj["targetUnix"] as? Int64 {
-            layerInstance.setActiveUnix(NSNumber(value: tu))
-        } else if let tu = obj["targetUnix"] as? Int {
-            layerInstance.setActiveUnix(NSNumber(value: Int64(tu)))
-        } else if let tu = obj["targetUnix"] as? Double {
-            layerInstance.setActiveUnix(NSNumber(value: Int64(tu)))
-        }
-
-        let apiKey = (obj["apiKey"] as? String) ?? ""
-        let bundleId = (obj["bundleId"] as? String) ?? ""
-        var gridSiteOrigin = (obj["gridRequestSiteOrigin"] as? String) ?? ""
-        gridSiteOrigin = gridSiteOrigin.trimmingCharacters(in: .whitespacesAndNewlines)
-        while gridSiteOrigin.hasSuffix("/") {
-            gridSiteOrigin.removeLast()
-        }
-        let frames = obj["frames"] as? [[String: Any]]
-        let frameCount = frames?.count ?? 0
-        let tgt = obj["targetUnix"]
-        Self.satLog(
-            "syncFromJson: runKey=\(runKey.isEmpty ? "(none)" : runKey) frames=\(frameCount) apiKey.len=\(apiKey.count) bundleId.len=\(bundleId.count) gridOrigin.len=\(gridSiteOrigin.count) visible=\((obj["visible"] as? Bool) ?? true) targetUnix=\(String(describing: tgt)) layerOnMap=\(isLayerAdded)"
-        )
-
-        guard let frames, !frames.isEmpty, !apiKey.isEmpty else {
-            if frames == nil {
-                Self.satLog("syncFromJson: EARLY EXIT — \"frames\" missing or not an array (no KTX URLs to fetch)")
-            } else if frames?.isEmpty == true {
-                Self.satLog("syncFromJson: EARLY EXIT — frames[] empty (JS timeline map likely not loaded yet; nothing to fetch)")
-            } else {
-                Self.satLog("syncFromJson: EARLY EXIT — apiKey empty (cannot authorize satellite CDN)")
-            }
-            if let mapView {
-                GridRenderLayerBridge.triggerRepaint(on: mapView)
-            }
-            return
-        }
-
-        let gen = decodeGeneration
-
-        for (idx, item) in frames.enumerated() {
-            guard let unixNum = item["unix"],
-                  let urlStr = item["url"] as? String,
-                  let url = URL(string: urlStr)
-            else { continue }
-            let unix: Int64
-            if let i = unixNum as? Int64 {
-                unix = i
-            } else if let i = unixNum as? Int {
-                unix = Int64(i)
-            } else if let d = unixNum as? Double {
-                unix = Int64(d)
-            } else {
-                continue
-            }
-            let shaderFileName = item["shaderFileName"] as? String ?? ""
-            if idx < 5 {
-                Self.satLog("scheduleFetch[\(idx)]: unix=\(unix) host=\(url.host ?? "?") shader=\(shaderFileName.prefix(48))…")
-            }
-            scheduleFetchIfNeeded(
-                gen: gen,
-                unix: unix,
-                url: url,
-                shaderFileName: shaderFileName,
-                apiKey: apiKey,
-                bundleId: bundleId,
-                gridRequestSiteOrigin: gridSiteOrigin
-            )
-        }
-        if frames.count > 5 {
-            Self.satLog("scheduleFetch: … and \(frames.count - 5) more frame(s) not listed")
-        }
-
-        if let mapView {
-            GridRenderLayerBridge.triggerRepaint(on: mapView)
-        }
-    }
-
-    private func scheduleFetchIfNeeded(
-        gen: Int,
-        unix: Int64,
-        url: URL,
-        shaderFileName: String,
-        apiKey: String,
-        bundleId: String,
-        gridRequestSiteOrigin: String
-    ) {
-        if layerInstance.isFrameCached(unix) {
-            Self.satLog("fetch: unix=\(unix) already cached — skip download")
-            return
-        }
-
-        fetchLock.lock()
-        if fetchInFlight.contains(unix) {
-            fetchLock.unlock()
-            Self.satLog("fetch: unix=\(unix) already in flight — skip duplicate")
-            return
-        }
-        fetchInFlight.insert(unix)
-        fetchLock.unlock()
-
-        decodeQueue.async { [weak self] in
-            guard let self else { return }
-            if gen != self.decodeGeneration {
-                Self.satLog("fetch: unix=\(unix) aborted — decodeGeneration changed (stale run)")
-                self.fetchLock.lock()
-                self.fetchInFlight.remove(unix)
-                self.fetchLock.unlock()
-                return
-            }
-
-            let fetchURL = Self.satelliteFetchURL(from: url, apiKey: apiKey)
-            var req = URLRequest(url: fetchURL)
-            req.setValue(apiKey, forHTTPHeaderField: "x-api-key")
-            if !bundleId.isEmpty {
-                req.setValue(bundleId, forHTTPHeaderField: "x-app-identifier")
-            }
-            // Match WeatherFrameProcessorModule + AguaceroCore grid fetch (CloudFront returns 403 without Origin on RN).
-            var gridOrigin = gridRequestSiteOrigin.trimmingCharacters(in: .whitespacesAndNewlines)
-            if gridOrigin.isEmpty {
-                gridOrigin = "https://localhost"
-            }
-            while gridOrigin.hasSuffix("/") {
-                gridOrigin.removeLast()
-            }
-            if !gridOrigin.isEmpty {
-                req.setValue(gridOrigin, forHTTPHeaderField: "Origin")
-                req.setValue("\(gridOrigin)/", forHTTPHeaderField: "Referer")
-            }
-
-            let sem = DispatchSemaphore(value: 0)
-            var outData: Data?
-            var httpStatus = -1
-            let task = self.urlSession.dataTask(with: req) { data, response, _ in
-                if let http = response as? HTTPURLResponse {
-                    httpStatus = http.statusCode
-                }
-                outData = data
-                sem.signal()
-            }
-            task.resume()
-            sem.wait()
-
-            if gen != self.decodeGeneration {
-                Self.satLog("fetch: unix=\(unix) post-network abort — generation bumped")
-                DispatchQueue.main.async {
-                    self.fetchLock.lock()
-                    self.fetchInFlight.remove(unix)
-                    self.fetchLock.unlock()
-                }
-                return
-            }
-
-            guard httpStatus == 200, let ktxBytes = outData, !ktxBytes.isEmpty else {
-                let bodyLen = outData?.count ?? 0
-                Self.satLog("fetch: unix=\(unix) HTTP \(httpStatus) bodyBytes=\(bodyLen) — expected 200 + non-empty KTX2 body")
-                DispatchQueue.main.async {
-                    self.fetchLock.lock()
-                    self.fetchInFlight.remove(unix)
-                    self.fetchLock.unlock()
-                }
-                return
-            }
-
-            if gen != self.decodeGeneration {
-                DispatchQueue.main.async {
-                    self.fetchLock.lock()
-                    self.fetchInFlight.remove(unix)
-                    self.fetchLock.unlock()
-                }
-                return
-            }
-
-            let packedOpt = AguaceroSatelliteKtxBridge.transcodeKtx2(ktxBytes)
-            let parsedOpt = packedOpt.flatMap { AguaceroSatelliteRenderer.parsePacked($0) }
-            let meshOpt: SatelliteMeshBuilder.MeshResult? =
-                parsedOpt.flatMap { p in
-                    SatelliteMeshBuilder.buildMesh(shaderFileName: shaderFileName, width: p.width, height: p.height)
-                }
-            guard packedOpt != nil,
-                  let parsed = parsedOpt,
-                  let mesh = meshOpt
-            else {
-                Self.satLog(
-                    "fetch: unix=\(unix) DECODE FAIL — ktxIn=\(ktxBytes.count)B packed=\(packedOpt?.count ?? -1) parsed=\(parsedOpt != nil) mesh=\(meshOpt != nil) shader=\(shaderFileName.prefix(40))"
-                )
-                DispatchQueue.main.async {
-                    self.fetchLock.lock()
-                    self.fetchInFlight.remove(unix)
-                    self.fetchLock.unlock()
-                }
-                return
-            }
-
-            let fc = Self.classifyShaderFileName(shaderFileName)
-            let pending = AguaceroSatelliteRenderer.PendingGpuUpload(
-                unix: unix,
-                mesh: mesh,
-                decoded: parsed,
-                trueColor: fc.trueColor,
-                colormapKind: fc.colormapKind,
-                useColormap: fc.useColormap
-            )
-
-            DispatchQueue.main.async {
-                self.fetchLock.lock()
-                self.fetchInFlight.remove(unix)
-                self.fetchLock.unlock()
-
-                if gen != self.decodeGeneration {
-                    return
-                }
-                if !self.isLayerAdded {
-                    if let w = self.window {
-                        self.findMapViewAndAddLayer(in: w)
-                    } else if let sv = self.superview {
-                        self.findMapViewAndAddLayer(in: sv)
-                    }
-                }
-                Self.satLog(
-                    "GPU queue: unix=\(unix) \(parsed.width)x\(parsed.height) tc=\(fc.trueColor) cmap=\(fc.colormapKind) layerOnMap=\(self.isLayerAdded)"
-                )
-                self.layerInstance.queueGpuUpload(pending)
-                if let mv = self.mapView {
-                    GridRenderLayerBridge.triggerRepaint(on: mv)
-                }
-            }
-        }
-    }
-
-    @objc public func activateSatelliteCachedUnix(_ unix: Int64) {
-        Self.satLog("activateSatelliteCachedUnix: unix=\(unix) cached=\(layerInstance.isFrameCached(unix))")
-        layerInstance.activateCachedUnix(unix)
-        if let mapView {
-            GridRenderLayerBridge.triggerRepaint(on: mapView)
-        }
-    }
-
-    @objc public func updateStyleFromJson(_ json: String?) {
-        guard let json, !json.isEmpty,
-              let data = json.data(using: .utf8),
-              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
-        else { return }
-        layerInstance.setVisible((obj["visible"] as? Bool) ?? true)
-        layerInstance.setOpacity(Float((obj["opacity"] as? Double) ?? 1.0))
-        layerInstance.setFillSmoothing(obj["fillSmoothing"] as? Int ?? 0)
-        if let mapView {
-            GridRenderLayerBridge.triggerRepaint(on: mapView)
-        }
-    }
-}
+import Foundation
+import MapboxMaps
+import React
+import UIKit
+
+@objc(SatelliteLayerView)
+public final class SatelliteLayerView: UIView {
+
+    /// Xcode / device console — grep `[AguaceroWX][SatelliteLayerView]` or `SatelliteLayerView`
+    private static func satLog(_ message: String) {
+        NSLog("[AguaceroWX][SatelliteLayerView] %@", message)
+    }
+
+    public static let satelliteLayerId = "aguacero-satellite-layer"
+    private static let weatherGridLayerId = "aguacero-weather-grid-custom"
+
+    @objc public var layerInstance: AguaceroSatelliteRenderer!
+    @objc public weak var mapView: MapView?
+    @objc public var layerId: String = SatelliteLayerView.satelliteLayerId
+    @objc public var belowID: String?
+
+    @objc public weak var bridge: RCTBridge?
+
+    private var isLayerAdded = false
+    private var satReparentScheduled = false
+
+    @objc public var satelliteLayerAdded: Bool { isLayerAdded }
+
+    private let decodeQueue = DispatchQueue(label: "com.aguacero.satellite-decode", qos: .utility)
+    private var decodeGeneration = 0
+    private var lastRunKey: String?
+
+    private var fetchInFlight = Set<Int64>()
+    private let fetchLock = NSLock()
+
+    private lazy var urlSession: URLSession = {
+        let c = URLSessionConfiguration.ephemeral
+        c.timeoutIntervalForRequest = 120
+        return URLSession(configuration: c)
+    }()
+
+    public override init(frame: CGRect) {
+        layerInstance = AguaceroSatelliteRenderer(id: SatelliteLayerView.satelliteLayerId)
+        super.init(frame: frame)
+        isOpaque = false
+        Self.satLog("init(frame:) SatelliteLayerView=\(Unmanaged.passUnretained(self).toOpaque())")
+    }
+
+    required init?(coder: NSCoder) {
+        layerInstance = AguaceroSatelliteRenderer(id: SatelliteLayerView.satelliteLayerId)
+        super.init(coder: coder)
+        isOpaque = false
+        Self.satLog("init(coder:) SatelliteLayerView=\(Unmanaged.passUnretained(self).toOpaque())")
+    }
+
+    public override func didMoveToWindow() {
+        super.didMoveToWindow()
+        if window != nil && !isLayerAdded {
+            findMapViewAndAddLayer(in: window!)
+        }
+    }
+
+    public override func layoutSubviews() {
+        super.layoutSubviews()
+        if !isLayerAdded {
+            let root = window ?? superview
+            if let root {
+                findMapViewAndAddLayer(in: root)
+            }
+        }
+    }
+
+    private func findMapViewAndAddLayer(in view: UIView) {
+        if isLayerAdded { return }
+        if let map = findMapViewRecursive(view) {
+            Self.satLog("findMapView: OK mapView attached, belowID=\(belowID ?? "nil")")
+            self.mapView = map
+            waitForStyleLoadAndAddLayer()
+        } else {
+            Self.satLog("findMapView: MapView not found under RNMBX hierarchy yet (will retry from layout/window)")
+        }
+    }
+
+    private func findMapViewRecursive(_ view: UIView) -> MapView? {
+        let name = NSStringFromClass(type(of: view))
+        if name == "RNMBXMapView", view.subviews.count > 0 {
+            let first = view.subviews[0]
+            let subName = NSStringFromClass(type(of: first))
+            if subName.contains("MapboxMaps.MapView") || subName == "MapView" {
+                return first as? MapView
+            }
+        }
+        for sub in view.subviews {
+            if let found = findMapViewRecursive(sub) {
+                return found
+            }
+        }
+        return nil
+    }
+
+    private func waitForStyleLoadAndAddLayer() {
+        guard let mapView else { return }
+        let anchor = belowID ?? "AML_-_terrain"
+        let anchorExists = GridRenderLayerBridge.layerExists(in: mapView, layerId: anchor)
+        Self.satLog("waitForStyle: anchor=\(anchor) exists=\(anchorExists) gridLayer=\(GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId))")
+        if anchorExists {
+            addLayerToMap()
+            return
+        }
+        pollForLayerExistence(anchor: anchor, attempts: 0)
+    }
+
+    private func pollForLayerExistence(anchor: String, attempts: Int) {
+        guard let mapView, !isLayerAdded else { return }
+        if attempts > 80 {
+            Self.satLog("pollAnchor: GAVE UP after ~\(attempts * 100)ms — layer id \"\(anchor)\" never appeared. Satellite custom layer was NOT added. Check Mapbox style / belowID prop.")
+            return
+        }
+        if attempts % 20 == 0, attempts > 0 {
+            Self.satLog("pollAnchor: still waiting for \"\(anchor)\" attempt=\(attempts)")
+        }
+        if GridRenderLayerBridge.layerExists(in: mapView, layerId: anchor) {
+            Self.satLog("pollAnchor: anchor \"\(anchor)\" appeared after \(attempts) attempts")
+            addLayerToMap()
+            return
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self] in
+            self?.pollForLayerExistence(anchor: anchor, attempts: attempts + 1)
+        }
+    }
+
+    private func addLayerToMap() {
+        guard let mapView, !isLayerAdded else { return }
+        guard let host = layerInstance.getHostWrapper() as? CustomLayerHost else {
+            Self.satLog("addLayerToMap: ABORT — CustomLayer host missing")
+            return
+        }
+
+        let success = GridRenderLayerBridge.addSatelliteCustomLayer(
+            to: mapView,
+            layerHost: host,
+            layerId: layerId,
+            weatherGridLayerId: Self.weatherGridLayerId,
+            belowLayerId: belowID
+        )
+
+        if success {
+            isLayerAdded = true
+            let gridThere = GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId)
+            Self.satLog("addLayerToMap: OK layerId=\(layerId) aboveGrid=\(gridThere) belowID=\(belowID ?? "nil")")
+            GridRenderLayerBridge.triggerRepaint(on: mapView)
+            scheduleReparentAboveGridOnce()
+        } else {
+            Self.satLog("addLayerToMap: FAILED Mapbox addLayer for layerId=\(layerId) — see GridRenderLayerBridge logs")
+        }
+    }
+
+    private func scheduleReparentAboveGridOnce() {
+        if satReparentScheduled { return }
+        satReparentScheduled = true
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) { [weak self] in
+            self?.satReparentScheduled = false
+            self?.reparentAboveGridIfNeeded()
+        }
+    }
+
+    private func reparentAboveGridIfNeeded() {
+        guard let mapView else { return }
+        let gridOk = GridRenderLayerBridge.layerExists(in: mapView, layerId: Self.weatherGridLayerId)
+        let satOk = GridRenderLayerBridge.layerExists(in: mapView, layerId: layerId)
+        guard gridOk, satOk else {
+            Self.satLog("reparentAboveGrid: skip grid=\(gridOk) satellite=\(satOk)")
+            return
+        }
+        guard let host = layerInstance.getHostWrapper() as? CustomLayerHost else { return }
+
+        GridRenderLayerBridge.removeCustomLayer(from: mapView, layerId: layerId)
+        _ = GridRenderLayerBridge.addSatelliteCustomLayer(
+            to: mapView,
+            layerHost: host,
+            layerId: layerId,
+            weatherGridLayerId: Self.weatherGridLayerId,
+            belowLayerId: belowID
+        )
+        GridRenderLayerBridge.triggerRepaint(on: mapView)
+    }
+
+    private struct FrameClass {
+        let trueColor: Bool
+        let colormapKind: String
+        let useColormap: Bool
+    }
+
+    private static func classifyShaderFileName(_ shaderFileName: String?) -> FrameClass {
+        let fn = shaderFileName ?? ""
+        let isTrueColor =
+            fn.contains("_truecolor_")
+            || fn.contains("_geocolor_")
+            || fn.contains("_firetemperature_")
+            || fn.contains("_dust_")
+            || fn.contains("_simplewatervapor_")
+            || fn.contains("_ntmicro_")
+            || fn.contains("_daycloudphase_")
+            || fn.contains("_daylandcloudfire_")
+            || fn.contains("_airmass_")
+            || fn.contains("_sandwich_")
+
+        var colormapType = "none"
+        if fn.contains("C13") || fn.contains("C14") || fn.contains("C15") || fn.contains("C16") {
+            colormapType = "ir"
+        } else if fn.contains("C08") || fn.contains("C09") || fn.contains("C10") {
+            colormapType = "wv"
+        }
+
+        let useColormap = !isTrueColor && colormapType != "none"
+        return FrameClass(trueColor: isTrueColor, colormapKind: colormapType, useColormap: useColormap)
+    }
+
+    /// Match `WeatherLayerManager` grid `buildGridFrameProcessOptions`: authoritative `apiKey` in the query string
+    /// plus `x-api-key` on the request (same pattern as `AguaceroCore` grid / NEXRAD CDN).
+    private static func satelliteFetchURL(from url: URL, apiKey: String) -> URL {
+        guard var c = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return url }
+        var q = c.queryItems ?? []
+        q.removeAll { $0.name == "apiKey" }
+        q.append(URLQueryItem(name: "apiKey", value: apiKey))
+        if !q.contains(where: { $0.name == "userId" }) {
+            q.append(URLQueryItem(name: "userId", value: "sdk-user"))
+        }
+        c.queryItems = q
+        return c.url ?? url
+    }
+
+    @objc public func clearSatellite() {
+        Self.satLog("clearSatellite: bump decodeGeneration (was \(decodeGeneration)) → \(decodeGeneration + 1), cancel in-flight fetches")
+        decodeGeneration += 1
+        fetchLock.lock()
+        fetchInFlight.removeAll()
+        fetchLock.unlock()
+        layerInstance.clearAll()
+        if let mapView {
+            GridRenderLayerBridge.triggerRepaint(on: mapView)
+        }
+    }
+
+    @objc public func syncFromJson(_ json: String?) {
+        guard let json, !json.isEmpty,
+              let data = json.data(using: .utf8),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else {
+            Self.satLog("syncFromJson: SKIP empty or invalid JSON (nil=\(json == nil) len=\(json?.count ?? 0))")
+            return
+        }
+
+        let runKey = (obj["runKey"] as? String) ?? ""
+        if !runKey.isEmpty, runKey != lastRunKey {
+            Self.satLog("syncFromJson: new runKey=\(runKey) (invalidate caches + bump generation)")
+            lastRunKey = runKey
+            decodeGeneration += 1
+            fetchLock.lock()
+            fetchInFlight.removeAll()
+            fetchLock.unlock()
+            layerInstance.clearAll()
+        }
+
+        layerInstance.setVisible((obj["visible"] as? Bool) ?? true)
+        layerInstance.setOpacity(Float((obj["opacity"] as? Double) ?? 1.0))
+        layerInstance.setFillSmoothing(obj["fillSmoothing"] as? Int ?? 0)
+
+        if let tu = obj["targetUnix"] as? Int64 {
+            layerInstance.setActiveUnix(NSNumber(value: tu))
+        } else if let tu = obj["targetUnix"] as? Int {
+            layerInstance.setActiveUnix(NSNumber(value: Int64(tu)))
+        } else if let tu = obj["targetUnix"] as? Double {
+            layerInstance.setActiveUnix(NSNumber(value: Int64(tu)))
+        }
+
+        let apiKey = (obj["apiKey"] as? String) ?? ""
+        let bundleId = (obj["bundleId"] as? String) ?? ""
+        var gridSiteOrigin = (obj["gridRequestSiteOrigin"] as? String) ?? ""
+        gridSiteOrigin = gridSiteOrigin.trimmingCharacters(in: .whitespacesAndNewlines)
+        while gridSiteOrigin.hasSuffix("/") {
+            gridSiteOrigin.removeLast()
+        }
+        let frames = obj["frames"] as? [[String: Any]]
+        let frameCount = frames?.count ?? 0
+        let tgt = obj["targetUnix"]
+        Self.satLog(
+            "syncFromJson: runKey=\(runKey.isEmpty ? "(none)" : runKey) frames=\(frameCount) apiKey.len=\(apiKey.count) bundleId.len=\(bundleId.count) gridOrigin.len=\(gridSiteOrigin.count) visible=\((obj["visible"] as? Bool) ?? true) targetUnix=\(String(describing: tgt)) layerOnMap=\(isLayerAdded)"
+        )
+
+        guard let frames, !frames.isEmpty, !apiKey.isEmpty else {
+            if frames == nil {
+                Self.satLog("syncFromJson: EARLY EXIT — \"frames\" missing or not an array (no KTX URLs to fetch)")
+            } else if frames?.isEmpty == true {
+                Self.satLog("syncFromJson: EARLY EXIT — frames[] empty (JS timeline map likely not loaded yet; nothing to fetch)")
+            } else {
+                Self.satLog("syncFromJson: EARLY EXIT — apiKey empty (cannot authorize satellite CDN)")
+            }
+            if let mapView {
+                GridRenderLayerBridge.triggerRepaint(on: mapView)
+            }
+            return
+        }
+
+        let gen = decodeGeneration
+
+        for (idx, item) in frames.enumerated() {
+            guard let unixNum = item["unix"],
+                  let urlStr = item["url"] as? String,
+                  let url = URL(string: urlStr)
+            else { continue }
+            let unix: Int64
+            if let i = unixNum as? Int64 {
+                unix = i
+            } else if let i = unixNum as? Int {
+                unix = Int64(i)
+            } else if let d = unixNum as? Double {
+                unix = Int64(d)
+            } else {
+                continue
+            }
+            let shaderFileName = item["shaderFileName"] as? String ?? ""
+            if idx < 5 {
+                Self.satLog("scheduleFetch[\(idx)]: unix=\(unix) host=\(url.host ?? "?") shader=\(shaderFileName.prefix(48))…")
+            }
+            scheduleFetchIfNeeded(
+                gen: gen,
+                unix: unix,
+                url: url,
+                shaderFileName: shaderFileName,
+                apiKey: apiKey,
+                bundleId: bundleId,
+                gridRequestSiteOrigin: gridSiteOrigin
+            )
+        }
+        if frames.count > 5 {
+            Self.satLog("scheduleFetch: … and \(frames.count - 5) more frame(s) not listed")
+        }
+
+        if let mapView {
+            GridRenderLayerBridge.triggerRepaint(on: mapView)
+        }
+    }
+
+    private func scheduleFetchIfNeeded(
+        gen: Int,
+        unix: Int64,
+        url: URL,
+        shaderFileName: String,
+        apiKey: String,
+        bundleId: String,
+        gridRequestSiteOrigin: String
+    ) {
+        if layerInstance.isFrameCached(unix) {
+            Self.satLog("fetch: unix=\(unix) already cached — skip download")
+            return
+        }
+
+        fetchLock.lock()
+        if fetchInFlight.contains(unix) {
+            fetchLock.unlock()
+            Self.satLog("fetch: unix=\(unix) already in flight — skip duplicate")
+            return
+        }
+        fetchInFlight.insert(unix)
+        fetchLock.unlock()
+
+        decodeQueue.async { [weak self] in
+            guard let self else { return }
+            if gen != self.decodeGeneration {
+                Self.satLog("fetch: unix=\(unix) aborted — decodeGeneration changed (stale run)")
+                self.fetchLock.lock()
+                self.fetchInFlight.remove(unix)
+                self.fetchLock.unlock()
+                return
+            }
+
+            let fetchURL = Self.satelliteFetchURL(from: url, apiKey: apiKey)
+            var req = URLRequest(url: fetchURL)
+            req.setValue(apiKey, forHTTPHeaderField: "x-api-key")
+            if !bundleId.isEmpty {
+                req.setValue(bundleId, forHTTPHeaderField: "x-app-identifier")
+            }
+            // Match WeatherFrameProcessorModule + AguaceroCore grid fetch (CloudFront returns 403 without Origin on RN).
+            var gridOrigin = gridRequestSiteOrigin.trimmingCharacters(in: .whitespacesAndNewlines)
+            if gridOrigin.isEmpty {
+                gridOrigin = "https://localhost"
+            }
+            while gridOrigin.hasSuffix("/") {
+                gridOrigin.removeLast()
+            }
+            if !gridOrigin.isEmpty {
+                req.setValue(gridOrigin, forHTTPHeaderField: "Origin")
+                req.setValue("\(gridOrigin)/", forHTTPHeaderField: "Referer")
+            }
+
+            let sem = DispatchSemaphore(value: 0)
+            var outData: Data?
+            var httpStatus = -1
+            let task = self.urlSession.dataTask(with: req) { data, response, _ in
+                if let http = response as? HTTPURLResponse {
+                    httpStatus = http.statusCode
+                }
+                outData = data
+                sem.signal()
+            }
+            task.resume()
+            sem.wait()
+
+            if gen != self.decodeGeneration {
+                Self.satLog("fetch: unix=\(unix) post-network abort — generation bumped")
+                DispatchQueue.main.async {
+                    self.fetchLock.lock()
+                    self.fetchInFlight.remove(unix)
+                    self.fetchLock.unlock()
+                }
+                return
+            }
+
+            guard httpStatus == 200, let ktxBytes = outData, !ktxBytes.isEmpty else {
+                let bodyLen = outData?.count ?? 0
+                Self.satLog("fetch: unix=\(unix) HTTP \(httpStatus) bodyBytes=\(bodyLen) — expected 200 + non-empty KTX2 body")
+                DispatchQueue.main.async {
+                    self.fetchLock.lock()
+                    self.fetchInFlight.remove(unix)
+                    self.fetchLock.unlock()
+                }
+                return
+            }
+
+            if gen != self.decodeGeneration {
+                DispatchQueue.main.async {
+                    self.fetchLock.lock()
+                    self.fetchInFlight.remove(unix)
+                    self.fetchLock.unlock()
+                }
+                return
+            }
+
+            let packedOpt = AguaceroSatelliteKtxBridge.transcodeKtx2(ktxBytes)
+            let parsedOpt = packedOpt.flatMap { AguaceroSatelliteRenderer.parsePacked($0) }
+            let meshOpt: SatelliteMeshBuilder.MeshResult? =
+                parsedOpt.flatMap { p in
+                    SatelliteMeshBuilder.buildMesh(shaderFileName: shaderFileName, width: p.width, height: p.height)
+                }
+            guard packedOpt != nil,
+                  let parsed = parsedOpt,
+                  let mesh = meshOpt
+            else {
+                Self.satLog(
+                    "fetch: unix=\(unix) DECODE FAIL — ktxIn=\(ktxBytes.count)B packed=\(packedOpt?.count ?? -1) parsed=\(parsedOpt != nil) mesh=\(meshOpt != nil) shader=\(shaderFileName.prefix(40))"
+                )
+                DispatchQueue.main.async {
+                    self.fetchLock.lock()
+                    self.fetchInFlight.remove(unix)
+                    self.fetchLock.unlock()
+                }
+                return
+            }
+
+            let fc = Self.classifyShaderFileName(shaderFileName)
+            let pending = AguaceroSatelliteRenderer.PendingGpuUpload(
+                unix: unix,
+                mesh: mesh,
+                decoded: parsed,
+                trueColor: fc.trueColor,
+                colormapKind: fc.colormapKind,
+                useColormap: fc.useColormap
+            )
+
+            DispatchQueue.main.async {
+                self.fetchLock.lock()
+                self.fetchInFlight.remove(unix)
+                self.fetchLock.unlock()
+
+                if gen != self.decodeGeneration {
+                    return
+                }
+                if !self.isLayerAdded {
+                    if let w = self.window {
+                        self.findMapViewAndAddLayer(in: w)
+                    } else if let sv = self.superview {
+                        self.findMapViewAndAddLayer(in: sv)
+                    }
+                }
+                Self.satLog(
+                    "GPU queue: unix=\(unix) \(parsed.width)x\(parsed.height) tc=\(fc.trueColor) cmap=\(fc.colormapKind) layerOnMap=\(self.isLayerAdded)"
+                )
+                self.layerInstance.queueGpuUpload(pending)
+                if let mv = self.mapView {
+                    GridRenderLayerBridge.triggerRepaint(on: mv)
+                }
+            }
+        }
+    }
+
+    @objc public func activateSatelliteCachedUnix(_ unix: Int64) {
+        Self.satLog("activateSatelliteCachedUnix: unix=\(unix) cached=\(layerInstance.isFrameCached(unix))")
+        layerInstance.activateCachedUnix(unix)
+        if let mapView {
+            GridRenderLayerBridge.triggerRepaint(on: mapView)
+        }
+    }
+
+    @objc public func updateStyleFromJson(_ json: String?) {
+        guard let json, !json.isEmpty,
+              let data = json.data(using: .utf8),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return }
+        layerInstance.setVisible((obj["visible"] as? Bool) ?? true)
+        layerInstance.setOpacity(Float((obj["opacity"] as? Double) ?? 1.0))
+        layerInstance.setFillSmoothing(obj["fillSmoothing"] as? Int ?? 0)
+        if let mapView {
+            GridRenderLayerBridge.triggerRepaint(on: mapView)
+        }
+    }
+}