catalyst-core 0.1.0-canary.9 → 0.2.0-beta.2

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt

@@ -31,10 +31,12 @@ class CustomWebView(
 ) : CoroutineScope {
 
     private val TAG = "WebViewDebug"
+    private val FLOW_TAG = "CatalystOfflineFlow"
     private val job = SupervisorJob()
     override val coroutineContext = Dispatchers.Main + job
 
     private var cacheManager: WebCacheManager
+    private var offlineCacheService: OfflineCacheService
     private val metricsMonitor = MetricsMonitor.getInstance(context)
     private var buildType: String = "debug"  // Default to debug
     private var cachePatterns: List<String> = emptyList()
@@ -50,18 +52,19 @@ class CustomWebView(
     private val offlineAssetUrl = "file:///android_asset/$offlineAssetPath"
     private var offlinePageVisible = false
     private var lastTargetUrl: String? = null
+    private var activeOfflineRouteOrigin: String? = null
+    private var visibleOfflineSnapshotUrl: String? = null
     private var defaultRequestHeaders: Map<String, String> = emptyMap()
+    var onPageStarted: (() -> Unit)? = null
 
     // Counters for asset loading statistics
     private var assetLoadAttempts = 0
     private var assetLoadFailures = 0
 
-    // Track ongoing cache fetches to prevent duplicates
-    private val ongoingCacheFetches = mutableSetOf<String>()
-
     init {
         setupFromProperties()
         cacheManager = WebCacheManager(context, properties)
+        offlineCacheService = OfflineCacheService(context)
         setupWebView()
     }
 
@@ -96,7 +99,7 @@ class CustomWebView(
 
         // Access control toggle
         accessControlEnabled = properties
-            .getProperty("accessControl.enabled", "true")
+            .getProperty("accessControl.enabled", "false")
             .equals("true", ignoreCase = true)
 
         // Initialize URLWhitelistManager with access control configuration
@@ -136,6 +139,15 @@ class CustomWebView(
 
     private fun loadUrlInternal(url: String) {
         val isNetworkUrl = url.startsWith("http://") || url.startsWith("https://")
+        val isOnline = NetworkUtils.getCurrentStatus(context).isOnline
+
+        if (BuildConfig.DEBUG) {
+            Log.d(FLOW_TAG, "WEBVIEW load-url start online=$isOnline url=$url headers=${defaultRequestHeaders.keys.sorted()}")
+        }
+
+        if (isNetworkUrl && isOnline) {
+            offlineCacheService.refreshManifestAsync(url, defaultRequestHeaders)
+        }
 
         if (isNetworkUrl && defaultRequestHeaders.isNotEmpty()) {
             if (BuildConfig.DEBUG) {
@@ -145,11 +157,16 @@ class CustomWebView(
         } else {
             webView.loadUrl(url)
         }
+        if (BuildConfig.DEBUG) {
+            Log.d(FLOW_TAG, "WEBVIEW load-url dispatched url=$url")
+        }
     }
 
     fun loadUrl(url: String) {
         lastTargetUrl = url
         offlinePageVisible = false
+        visibleOfflineSnapshotUrl = null
+        activeOfflineRouteOrigin = null
         loadUrlInternal(url)
     }
 
@@ -166,6 +183,8 @@ class CustomWebView(
         try {
             context.assets.open(offlineAssetPath).close()
             offlinePageVisible = true
+            visibleOfflineSnapshotUrl = null
+            activeOfflineRouteOrigin = null
             loadUrlInternal(offlineAssetUrl)
             if (BuildConfig.DEBUG) {
                 Log.d(TAG, "📴 Showing offline page from assets: $offlineAssetPath")
@@ -191,6 +210,32 @@ class CustomWebView(
 
     fun clearAllCache() {
         cacheManager.clearAll()
+        offlineCacheService.clearAll()
+        activeOfflineRouteOrigin = null
+        visibleOfflineSnapshotUrl = null
+    }
+
+    fun showOfflineRouteOrOfflinePage(url: String) {
+        val snapshotUrl = normalizeUrlWithoutFragment(url)
+        if (visibleOfflineSnapshotUrl == snapshotUrl) {
+            if (BuildConfig.DEBUG) {
+                Log.d(TAG, "📴 Cached offline route snapshot already visible: $url")
+            }
+            return
+        }
+
+        if (offlineCacheService.hasRouteSnapshot(url)) {
+            offlinePageVisible = false
+            visibleOfflineSnapshotUrl = snapshotUrl
+            updateActiveOfflineRoute(url, true)
+            loadUrlInternal(url)
+            if (BuildConfig.DEBUG) {
+                Log.d(TAG, "📴 Loading cached offline route through request interceptor: $url")
+            }
+            return
+        }
+
+        showOfflinePage()
     }
 
     fun canGoBack(): Boolean = webView.canGoBack()
@@ -233,7 +278,7 @@ class CustomWebView(
         }
 
         // Additional security check: only allow whitelisted interface names
-        val allowedInterfaces = setOf("NativeBridge", "AndroidBridge")
+        val allowedInterfaces = setOf("NativeBridge", "AndroidBridge", "PluginBridge")
         if (name !in allowedInterfaces) {
             Log.e(TAG, "❌ Security: Interface name '$name' is not in whitelist. Refusing to add interface.")
             return
@@ -246,6 +291,17 @@ class CustomWebView(
         }
     }
 
+    fun removeJavascriptInterface(name: String) {
+        try {
+            webView.removeJavascriptInterface(name)
+            if (BuildConfig.DEBUG) {
+                Log.d(TAG, "🔌 Removed JavaScript interface: $name")
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "⚠️ Failed to remove JavaScript interface '$name': ${e.message}")
+        }
+    }
+
     fun destroy() {
         job.cancel()
         webView.destroy()
@@ -292,25 +348,112 @@ class CustomWebView(
         }
     }
 
-    private fun shouldCacheUrl(url: String): Boolean {
+    private fun shouldCacheRequest(request: WebResourceRequest, url: String): Boolean {
         if (BuildConfig.DEBUG) {
             Log.d(TAG, "🔍 CACHE_CHECK: Checking if URL should be cached: $url")
             Log.d(TAG, "🔍 CACHE_CHECK: Cache patterns: $cachePatterns")
         }
 
-        val shouldCache = matchesCachePattern(url, cachePatterns)
+        val matchesPattern = matchesCachePattern(url, cachePatterns)
+        val offlineRouteSubresource = shouldCacheOfflineRouteSubresource(request, url)
+        val shouldCache = matchesPattern || offlineRouteSubresource
 
         if (BuildConfig.DEBUG) {
             if (shouldCache) {
-                Log.d(TAG, "✅ CACHE_CHECK: URL WILL be cached: $url")
+                Log.d(TAG, "✅ CACHE_CHECK: URL WILL be cached: $url (pattern=$matchesPattern, offlineRouteSubresource=$offlineRouteSubresource)")
+                Log.d(FLOW_TAG, "CACHE eligible=true pattern=$matchesPattern offlineRouteSubresource=$offlineRouteSubresource mainFrame=${request.isForMainFrame} method=${request.method} dest=${requestHeader(request, "Sec-Fetch-Dest") ?: "none"} accept=${requestHeader(request, "Accept") ?: "none"} activeOrigin=${activeOfflineRouteOrigin ?: "none"} url=$url")
             } else {
                 Log.d(TAG, "❌ CACHE_CHECK: URL will NOT be cached (no pattern match): $url")
+                Log.d(FLOW_TAG, "CACHE eligible=false pattern=$matchesPattern offlineRouteSubresource=$offlineRouteSubresource mainFrame=${request.isForMainFrame} method=${request.method} dest=${requestHeader(request, "Sec-Fetch-Dest") ?: "none"} accept=${requestHeader(request, "Accept") ?: "none"} activeOrigin=${activeOfflineRouteOrigin ?: "none"} url=$url")
             }
         }
 
         return shouldCache
     }
 
+    private fun shouldCacheOfflineRouteSubresource(request: WebResourceRequest, url: String): Boolean {
+        if (request.isForMainFrame || request.method != "GET") return false
+        if (!isHttpUrl(url) || isApiCall(url) || isInternalOfflineRuntimeUrl(url)) return false
+
+        val activeOrigin = activeOfflineRouteOrigin ?: return false
+        if (originForUrl(url) != activeOrigin) return false
+
+        val destination = requestHeader(request, "Sec-Fetch-Dest")?.lowercase()
+        if (destination == "document" || destination == "empty") return false
+        if (destination in setOf("script", "style", "image", "font", "audio", "video", "track", "manifest")) {
+            return true
+        }
+
+        val accept = requestHeader(request, "Accept")?.lowercase().orEmpty()
+        if (accept.contains("text/html") ||
+            accept.contains("application/json") ||
+            accept.contains("text/event-stream")
+        ) {
+            return false
+        }
+        if (accept.contains("text/css") ||
+            accept.contains("javascript") ||
+            accept.contains("image/") ||
+            accept.contains("font/") ||
+            accept.contains("application/font") ||
+            accept.contains("application/wasm")
+        ) {
+            return true
+        }
+
+        return offlineCacheService.shouldCacheAssetUrl(url)
+    }
+
+    private fun requestHeader(request: WebResourceRequest, name: String): String? {
+        return request.requestHeaders.entries.firstOrNull {
+            it.key.equals(name, ignoreCase = true)
+        }?.value
+    }
+
+    private fun updateActiveOfflineRoute(url: String, active: Boolean) {
+        activeOfflineRouteOrigin = if (active) originForUrl(url) else null
+        if (BuildConfig.DEBUG) {
+            Log.d(FLOW_TAG, "ROUTE active=$active activeOrigin=${activeOfflineRouteOrigin ?: "none"} url=$url")
+        }
+    }
+
+    private fun isVisibleOfflineSnapshot(url: String?): Boolean {
+        if (url == null) return false
+        return visibleOfflineSnapshotUrl == normalizeUrlWithoutFragment(url)
+    }
+
+    private fun normalizeUrlWithoutFragment(url: String): String {
+        return try {
+            Uri.parse(url).buildUpon().fragment(null).build().toString()
+        } catch (_: Exception) {
+            url
+        }
+    }
+
+    private fun originForUrl(url: String): String? {
+        return try {
+            val uri = Uri.parse(url)
+            val scheme = uri.scheme?.lowercase() ?: return null
+            val authority = uri.authority ?: return null
+            if (scheme != "http" && scheme != "https") return null
+            "$scheme://$authority"
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun isHttpUrl(url: String): Boolean {
+        val scheme = Uri.parse(url).scheme?.lowercase()
+        return scheme == "http" || scheme == "https"
+    }
+
+    private fun isInternalOfflineRuntimeUrl(url: String): Boolean {
+        val path = Uri.parse(url).path ?: return false
+        return path == "/catalyst-offline-manifest.json" ||
+            path == "/catalyst-sw.js" ||
+            path == "/offline.html"
+    }
+
     /**
      * Handle special URL schemes (tel:, mailto:, sms:)
      */
@@ -453,6 +596,18 @@ class CustomWebView(
         return "build/public/$fileName"
     }
 
+    private fun withCorsHeaders(response: WebResourceResponse): WebResourceResponse {
+        val responseHeaders = response.responseHeaders
+        if (responseHeaders.isNullOrEmpty()) {
+            response.responseHeaders = mutableMapOf(
+                "Access-Control-Allow-Origin" to "*",
+                "Access-Control-Allow-Methods" to "GET, OPTIONS",
+                "Access-Control-Allow-Headers" to "*"
+            )
+        }
+        return response
+    }
+
     private fun getMimeType(path: String): String {
         return when {
             path.endsWith(".html") -> "text/html"
@@ -478,11 +633,13 @@ class CustomWebView(
             serviceWorkerController.setServiceWorkerClient(object : ServiceWorkerClientCompat() {
                 override fun shouldInterceptRequest(request: WebResourceRequest): WebResourceResponse? {
                     val url = request.url.toString()
+                    val isOnline = NetworkUtils.getCurrentStatus(context).isOnline
 
                     if (BuildConfig.DEBUG) {
                         Log.d(TAG, "🔧 SERVICE_WORKER: Intercepting request: $url")
                         Log.d(TAG, "🔧 SERVICE_WORKER: Method: ${request.method}")
                         Log.d(TAG, "🔧 SERVICE_WORKER: Headers: ${request.requestHeaders}")
+                        Log.d(FLOW_TAG, "SW intercept method=${request.method} online=$isOnline mainFrame=${request.isForMainFrame} url=$url")
                     }
 
                     // Check if URL is allowed
@@ -502,7 +659,7 @@ class CustomWebView(
                     }
 
                     // Check if this should be cached
-                    if (request.method == "GET" && shouldCacheUrl(url)) {
+                    if (request.method == "GET" && shouldCacheRequest(request, url)) {
                         if (BuildConfig.DEBUG) {
                             Log.d(TAG, "🎯 SERVICE_WORKER: Using cache system for: $url")
                         }
@@ -516,49 +673,22 @@ class CustomWebView(
                             }
 
                             // Get cached response synchronously (non-blocking for ServiceWorker)
-                            val response = cacheManager.getCachedResponseSync(url, headers)
+                            val response = if (NetworkUtils.getCurrentStatus(context).isOnline) {
+                                cacheManager.getCachedResponseOrFetchSync(url, headers)
+                            } else {
+                                cacheManager.getCachedResponseSync(url, headers)
+                            }
                             if (response != null) {
                                 if (BuildConfig.DEBUG) {
                                     Log.d(TAG, "✅ SERVICE_WORKER: Served from cache: $url")
+                                    Log.d(FLOW_TAG, "SW response source=cache-or-fetch mime=${response.mimeType ?: "unknown"} encoding=${response.encoding ?: "unknown"} url=$url")
                                 }
-                                response
+                                withCorsHeaders(response)
                             } else {
                                 if (BuildConfig.DEBUG) {
                                     Log.d(TAG, "❌ SERVICE_WORKER: Cache miss: $url")
+                                    Log.d(FLOW_TAG, "SW response source=network-fallback reason=cache-null url=$url")
                                 }
-
-                                // Trigger async cache population for next request (with deduplication)
-                                val shouldFetch = synchronized(ongoingCacheFetches) {
-                                    ongoingCacheFetches.add(url)
-                                }
-
-                                if (shouldFetch) {
-                                    if (BuildConfig.DEBUG) {
-                                        Log.d(TAG, "🔄 SERVICE_WORKER: Triggering async cache fetch for: $url")
-                                    }
-                                    launch(Dispatchers.IO) {
-                                        try {
-                                            cacheManager.getCachedResponse(url, headers)
-                                            if (BuildConfig.DEBUG) {
-                                                Log.d(TAG, "✅ SERVICE_WORKER: Async cache fetch completed: $url")
-                                            }
-                                        } catch (e: Exception) {
-                                            if (BuildConfig.DEBUG) {
-                                                Log.e(TAG, "❌ SERVICE_WORKER: Async cache fetch failed: $url - ${e.message}")
-                                            }
-                                        } finally {
-                                            synchronized(ongoingCacheFetches) {
-                                                ongoingCacheFetches.remove(url)
-                                            }
-                                        }
-                                    }
-                                } else {
-                                    if (BuildConfig.DEBUG) {
-                                        Log.d(TAG, "⏭️ SERVICE_WORKER: Cache fetch already in progress for: $url")
-                                    }
-                                }
-
-                                // Let this request fall back to network
                                 null
                             }
                         } catch (e: Exception) {
@@ -570,7 +700,7 @@ class CustomWebView(
                     } else {
                         if (BuildConfig.DEBUG) {
                             Log.d(TAG, "⏭️ SERVICE_WORKER: Skipping cache for: $url")
-                            Log.d(TAG, "⏭️ SERVICE_WORKER: Method: ${request.method}, shouldCache: ${shouldCacheUrl(url)}")
+                            Log.d(TAG, "⏭️ SERVICE_WORKER: Method: ${request.method}, shouldCache: ${shouldCacheRequest(request, url)}")
                         }
                     }
 
@@ -606,6 +736,9 @@ class CustomWebView(
             domStorageEnabled = true
             allowFileAccess = true
             allowContentAccess = true
+            setSupportZoom(false)
+            builtInZoomControls = false
+            displayZoomControls = false
 
             // TODO: Enable these when build optimization feature is implemented
             // These are deprecated but may be needed for local file access in development
@@ -660,6 +793,7 @@ class CustomWebView(
                 request: WebResourceRequest
             ): WebResourceResponse? {
                 val url = request.url.toString()
+                val isOnline = NetworkUtils.getCurrentStatus(context).isOnline
 
                 // Track all network requests
                 metricsMonitor.recordNetworkRequest(url)
@@ -670,6 +804,7 @@ class CustomWebView(
                     Log.d(TAG, "🔄 INTERCEPT: Thread: ${Thread.currentThread().name}")
                     Log.d(TAG, "🔄 INTERCEPT: File extension: ${url.substringAfterLast('.', "none")}")
                     Log.d(TAG, "🔄 INTERCEPT: isInitialPageLoaded: $isInitialPageLoaded")
+                    Log.d(FLOW_TAG, "WV intercept method=${request.method} online=$isOnline mainFrame=${request.isForMainFrame} initialLoaded=$isInitialPageLoaded dest=${requestHeader(request, "Sec-Fetch-Dest") ?: "none"} accept=${requestHeader(request, "Accept") ?: "none"} url=$url")
                 }
 
                 if (!URLWhitelistManager.isUrlAllowed(url)) {
@@ -686,6 +821,51 @@ class CustomWebView(
                     }
                 }
 
+                val isMainFrameDocument = request.isForMainFrame &&
+                    request.method == "GET" &&
+                    (request.url.scheme == "http" || request.url.scheme == "https") &&
+                    !isApiCall(url)
+
+                if (isMainFrameDocument) {
+                    val headers = defaultRequestHeaders.toMutableMap().apply {
+                        putAll(request.requestHeaders)
+                    }
+                    if (BuildConfig.DEBUG) {
+                        Log.d(FLOW_TAG, "DOCUMENT intercept online=$isOnline url=$url headers=${headers.keys.sorted()}")
+                    }
+
+                    if (isOnline) {
+                        offlineCacheService.refreshManifestIfMissing(url, headers)
+                        val isOfflineRoute = offlineCacheService.isOfflineRouteUrl(url)
+                        updateActiveOfflineRoute(url, isOfflineRoute)
+                        visibleOfflineSnapshotUrl = null
+                        if (BuildConfig.DEBUG) {
+                            Log.d(FLOW_TAG, "DOCUMENT online routeEligible=$isOfflineRoute action=allow-network-and-background-snapshot url=$url")
+                        }
+                        offlineCacheService.storeRouteSnapshotAsync(url, headers)
+                    } else {
+                        val snapshotResponse = offlineCacheService.getRouteSnapshotResponse(url)
+                        if (snapshotResponse != null) {
+                            updateActiveOfflineRoute(url, true)
+                            visibleOfflineSnapshotUrl = normalizeUrlWithoutFragment(url)
+                            if (BuildConfig.DEBUG) {
+                                Log.d(TAG, "📴 INTERCEPT: Serving offline route snapshot: $url")
+                                Log.d(FLOW_TAG, "DOCUMENT offline response=route-snapshot mime=${snapshotResponse.mimeType ?: "unknown"} url=$url")
+                            }
+                            return withCorsHeaders(snapshotResponse)
+                        }
+                        updateActiveOfflineRoute(url, false)
+                        if (BuildConfig.DEBUG) {
+                            Log.d(FLOW_TAG, "DOCUMENT offline response=network-fallback reason=snapshot-miss url=$url")
+                        }
+                    }
+                } else if (request.isForMainFrame &&
+                    request.method == "GET" &&
+                    (request.url.scheme == "http" || request.url.scheme == "https")
+                ) {
+                    updateActiveOfflineRoute(url, false)
+                }
+
                 // TODO: Add HTML file workflow - index.html not available yet
                 // Handle the initial route request - intercept first request regardless of host
                 // if (!isInitialApiCalled && request.method == "GET") {
@@ -720,12 +900,12 @@ class CustomWebView(
                     if (BuildConfig.DEBUG) {
                         Log.d(TAG, "🔍 STEP_4_CHECK: Initial page not loaded yet, checking for static resources")
                         Log.d(TAG, "🔍 STEP_4_CHECK: isStaticResourceRequest($url) = ${isStaticResourceRequest(url)}")
-                        Log.d(TAG, "🔍 STEP_4_CHECK: shouldCacheUrl($url) = ${shouldCacheUrl(url)}")
+                        Log.d(TAG, "🔍 STEP_4_CHECK: shouldCacheRequest($url) = ${shouldCacheRequest(request, url)}")
                     }
 
                     // IMPORTANT: Skip asset loading if the URL matches a cache pattern
                     // This allows cached resources to be served from the cache system instead
-                    if (request.method == "GET" && isStaticResourceRequest(url) && !shouldCacheUrl(url)) {
+                    if (request.method == "GET" && isStaticResourceRequest(url) && !shouldCacheRequest(request, url)) {
                         val assetPath = extractAssetPath(url)
                         assetLoadAttempts++
 
@@ -763,7 +943,7 @@ class CustomWebView(
                             }
                             // Unexpected error - fall through to cache check below
                         }
-                    } else if (shouldCacheUrl(url)) {
+                    } else if (shouldCacheRequest(request, url)) {
                         if (BuildConfig.DEBUG) {
                             Log.d(TAG, "⏭️ STEP_4_SKIP: Skipping asset loading for cached URL: $url")
                         }
@@ -778,10 +958,10 @@ class CustomWebView(
                 if (BuildConfig.DEBUG) {
                     Log.d(TAG, "🔍 STEP_5_CACHE_CHECK: Evaluating cache conditions")
                     Log.d(TAG, "🔍 STEP_5_CACHE_CHECK: Request method: ${request.method} (need GET)")
-                    Log.d(TAG, "🔍 STEP_5_CACHE_CHECK: shouldCacheUrl($url) = ${shouldCacheUrl(url)}")
+                    Log.d(TAG, "🔍 STEP_5_CACHE_CHECK: shouldCacheRequest($url) = ${shouldCacheRequest(request, url)}")
                 }
 
-                if (request.method == "GET" && shouldCacheUrl(url)) {
+                if (request.method == "GET" && shouldCacheRequest(request, url)) {
                     // Track that this request was evaluated for caching
                     metricsMonitor.recordCacheEvaluation(url)
                     if (BuildConfig.DEBUG) {
@@ -804,45 +984,27 @@ class CustomWebView(
                         }
 
                         // Use synchronous cache check to avoid blocking
-                        val response = cacheManager.getCachedResponseSync(url, headers)
+                        val response = if (NetworkUtils.getCurrentStatus(context).isOnline) {
+                            cacheManager.getCachedResponseOrFetchSync(url, headers)
+                        } else {
+                            cacheManager.getCachedResponseSync(url, headers)
+                        }
 
                         if (response != null) {
                             if (BuildConfig.DEBUG) {
                                 val duration = System.currentTimeMillis() - startTime
                                 Log.d(TAG, "✅ WEBVIEW_CLIENT: Served from cache in ${duration}ms: $url")
+                                Log.d(FLOW_TAG, "ASSET response source=cache-or-fetch online=${NetworkUtils.getCurrentStatus(context).isOnline} durationMs=$duration mime=${response.mimeType ?: "unknown"} encoding=${response.encoding ?: "unknown"} url=$url")
                             }
                             metricsMonitor.recordCacheHit(url)
-                            return response
+                            return withCorsHeaders(response)
                         } else {
                             if (BuildConfig.DEBUG) {
-                                Log.d(TAG, "❌ WEBVIEW_CLIENT: Cache miss, triggering async fetch: $url")
+                                Log.d(TAG, "❌ WEBVIEW_CLIENT: Cache miss: $url")
+                                Log.d(FLOW_TAG, "ASSET response source=network-fallback reason=cache-null online=${NetworkUtils.getCurrentStatus(context).isOnline} url=$url")
                             }
                             metricsMonitor.recordCacheMiss(url)
 
-                            // Trigger async cache population for next time
-                            val shouldFetch = synchronized(ongoingCacheFetches) {
-                                ongoingCacheFetches.add(url)
-                            }
-
-                            if (shouldFetch) {
-                                launch(Dispatchers.IO) {
-                                    try {
-                                        cacheManager.getCachedResponse(url, headers)
-                                        if (BuildConfig.DEBUG) {
-                                            Log.d(TAG, "✅ WEBVIEW_CLIENT: Async cache fetch completed: $url")
-                                        }
-                                    } catch (e: Exception) {
-                                        if (BuildConfig.DEBUG) {
-                                            Log.e(TAG, "❌ WEBVIEW_CLIENT: Async cache fetch failed: $url - ${e.message}")
-                                        }
-                                    } finally {
-                                        synchronized(ongoingCacheFetches) {
-                                            ongoingCacheFetches.remove(url)
-                                        }
-                                    }
-                                }
-                            }
-
                             // Return null to let network handle this request
                             return null
                         }
@@ -870,7 +1032,7 @@ class CustomWebView(
                         Log.d(TAG, "❌ STEP_5_FAIL: URL doesn't match cache criteria, skipping cache")
                         Log.d(TAG, "❌ STEP_5_FAIL: URL: $url")
                         Log.d(TAG, "❌ STEP_5_FAIL: Request method: ${request.method} (need GET)")
-                        Log.d(TAG, "❌ STEP_5_FAIL: shouldCacheUrl result: ${shouldCacheUrl(url)}")
+                        Log.d(TAG, "❌ STEP_5_FAIL: shouldCacheRequest result: ${shouldCacheRequest(request, url)}")
                         Log.d(TAG, "❌ STEP_5_FAIL: This request will go through normal network loading")
                     }
                 }
@@ -882,6 +1044,10 @@ class CustomWebView(
                 super.onPageStarted(view, url, favicon)
                 if (url != null && url != offlineAssetUrl) {
                     offlinePageVisible = false
+                    if (!isVisibleOfflineSnapshot(url)) {
+                        visibleOfflineSnapshotUrl = null
+                    }
+                    onPageStarted?.invoke()
                 }
                 progressBar.visibility = View.VISIBLE
                 val startTime = System.currentTimeMillis()
@@ -889,6 +1055,7 @@ class CustomWebView(
                 url?.let { metricsMonitor.trackPageLoadStart(it) }
                 if (BuildConfig.DEBUG) {
                     Log.d(TAG, "⏳ Page load started for: $url - Hardware Acceleration: $isHardwareAccelerationEnabled")
+                    Log.d(FLOW_TAG, "PAGE started url=$url online=${NetworkUtils.getCurrentStatus(context).isOnline} offlinePageVisible=$offlinePageVisible visibleSnapshot=${visibleOfflineSnapshotUrl ?: "none"} activeOrigin=${activeOfflineRouteOrigin ?: "none"}")
                 }
             }
 
@@ -902,6 +1069,7 @@ class CustomWebView(
                     val startTime = view?.tag as? Long ?: return
                     val loadTime = System.currentTimeMillis() - startTime
                     Log.d(TAG, "✅ Page load finished for: $url - Load time: ${loadTime}ms - Hardware Acceleration: $isHardwareAccelerationEnabled")
+                    Log.d(FLOW_TAG, "PAGE finished url=$url loadTimeMs=$loadTime online=${NetworkUtils.getCurrentStatus(context).isOnline} offlinePageVisible=$offlinePageVisible visibleSnapshot=${visibleOfflineSnapshotUrl ?: "none"} activeOrigin=${activeOfflineRouteOrigin ?: "none"}")
                     Log.d(TAG, "📊 Asset loading stats: Attempted: $assetLoadAttempts, Failed: $assetLoadFailures (${String.format("%.1f", assetLoadFailures * 100.0 / assetLoadAttempts.coerceAtLeast(1))}%)")
                     Log.d(TAG, "📊 ${metricsMonitor.getCacheStats()}")
 
@@ -924,7 +1092,30 @@ class CustomWebView(
             override fun onReceivedError(view: WebView?, request: WebResourceRequest?, error: WebResourceError?) {
                 if (error != null) {
                     Log.e(TAG, "❌ Error loading ${request?.url}: ${error.errorCode} ${error.description}")
+                    if (BuildConfig.DEBUG) {
+                        Log.e(FLOW_TAG, "PAGE resource-error mainFrame=${request?.isForMainFrame} method=${request?.method} code=${error.errorCode} description=${error.description} url=${request?.url}")
+                    }
+                }
+
+                val failedUrl = request?.url?.toString()
+                if (request?.isForMainFrame == true && isVisibleOfflineSnapshot(failedUrl)) {
+                    if (BuildConfig.DEBUG) {
+                        Log.d(TAG, "📴 Ignoring repeated error for visible offline route snapshot: $failedUrl")
+                    }
+                    return
+                }
+
+                if (request?.isForMainFrame == true &&
+                    failedUrl != null &&
+                    failedUrl != offlineAssetUrl &&
+                    !NetworkUtils.getCurrentStatus(context).isOnline
+                ) {
+                    view?.post {
+                        showOfflineRouteOrOfflinePage(failedUrl)
+                    }
+                    return
                 }
+
                 super.onReceivedError(view, request, error)
             }
 
@@ -976,6 +1167,7 @@ class CustomWebView(
             override fun onConsoleMessage(consoleMessage: ConsoleMessage?): Boolean {
                 if (BuildConfig.DEBUG) {
                     Log.d(TAG, "Console: ${consoleMessage?.message()} -- From line ${consoleMessage?.lineNumber()} of ${consoleMessage?.sourceId()}")
+                    Log.d(FLOW_TAG, "CONSOLE level=${consoleMessage?.messageLevel()} line=${consoleMessage?.lineNumber()} source=${consoleMessage?.sourceId()} message=${consoleMessage?.message()}")
                 }
                 return true
             }