@dynamic-labs/react-native-extension 4.81.0 → 4.83.1

package/ios/EmbeddedWebViewController.swift

@@ -0,0 +1,426 @@
+import UIKit
+import WebKit
+
+private let scriptHandlerName = "dynamicEmbeddedWebView"
+private let navigationDecisionTimeout: TimeInterval = 2.0
+
+// Cleartext http is only permitted in debug builds (e.g. Metro at
+// http://localhost:4202). Release builds reject http top-frame and sub-frame
+// navigations regardless of what the JS allowlist says — so a JS compromise
+// cannot trick production into loading http content.
+#if DEBUG
+private let allowsHttpScheme = true
+#else
+private let allowsHttpScheme = false
+#endif
+
+public typealias EmbeddedWebViewEventEmitter = (String, [String: Any]) -> Void
+
+public final class EmbeddedWebViewController: NSObject {
+  public static let shared = EmbeddedWebViewController()
+
+  public var eventEmitter: EmbeddedWebViewEventEmitter?
+
+  private var window: UIWindow?
+  private var webView: WKWebView?
+  private var debuggingEnabled = false
+  private var hasLoaded = false
+  private var pendingNavigationDecisions: [String: (WKNavigationActionPolicy) -> Void] = [:]
+  private var navigationTimers: [String: Timer] = [:]
+  private var emitterToken: UUID?
+
+  private override init() {
+    super.init()
+  }
+
+  // Module-side hook: assign the emitter under a token. The token lets
+  // OnDestroy avoid clobbering an emitter that a newer OnCreate has already
+  // installed — relevant during dev hot reloads where module instances briefly
+  // overlap.
+  @discardableResult
+  public func setEmitter(_ emitter: @escaping EmbeddedWebViewEventEmitter) -> UUID {
+    let token = UUID()
+    emitterToken = token
+    eventEmitter = emitter
+    return token
+  }
+
+  public func clearEmitter(token: UUID) {
+    if emitterToken == token {
+      eventEmitter = nil
+      emitterToken = nil
+    }
+  }
+
+  // MARK: - Public API (must be called on main thread)
+
+  public func setUrl(_ url: String) {
+    // Match react-native-webview parity: any invalid URL surfaces as a load
+    // error instead of silently no-op'ing. WKWebView accepts URLs without a
+    // scheme but never emits a navigation event for them — fail fast here so
+    // the JS side throws WebViewFailedToLoadError.
+    guard let parsed = URL(string: url), parsed.scheme != nil else {
+      emitInvalidUrlError(url: url)
+      return
+    }
+    ensureWebView()
+    hasLoaded = true
+    webView?.load(URLRequest(url: parsed))
+  }
+
+  private func emitInvalidUrlError(url: String) {
+    eventEmitter?("onLoadError", [
+      "url": url,
+      "code": -1,
+      "domain": "EmbeddedWebViewInvalidUrl",
+      "description": "Invalid URL: \(url)",
+      "isProvisional": true,
+    ])
+  }
+
+  public func setVisible(_ visible: Bool) {
+    ensureWebView()
+    // We deliberately do NOT toggle `isHidden`. WKWebView attached to a hidden
+    // UIWindow gets throttled by iOS — JS timers slow, fetch callbacks stall,
+    // message events stop dispatching — so the page effectively pauses until
+    // the window becomes visible again. By keeping the window in the visible
+    // window stack and toggling `alpha` + interaction instead, the WKWebView
+    // stays "foreground" from the OS's POV and continues running normally.
+    if visible {
+      window?.alpha = 1
+      window?.isUserInteractionEnabled = true
+      window?.makeKeyAndVisible()
+    } else {
+      window?.alpha = 0
+      window?.isUserInteractionEnabled = false
+    }
+  }
+
+  public func setDebuggingEnabled(_ enabled: Bool) {
+    debuggingEnabled = enabled
+    if let webView = webView, #available(iOS 16.4, *) {
+      webView.isInspectable = enabled
+    }
+  }
+
+  public func destroy() {
+    webView?.stopLoading()
+    if let userContentController = webView?.configuration.userContentController {
+      userContentController.removeAllUserScripts()
+      userContentController.removeScriptMessageHandler(forName: scriptHandlerName)
+    }
+    webView?.navigationDelegate = nil
+    webView?.removeFromSuperview()
+    webView = nil
+
+    window?.isHidden = true
+    window?.rootViewController = nil
+    window = nil
+
+    // WKWebView contract: every policy decision handler must be invoked
+    // exactly once. Cancel any in-flight decisions before clearing.
+    pendingNavigationDecisions.values.forEach { $0(.cancel) }
+    pendingNavigationDecisions.removeAll()
+    navigationTimers.values.forEach { $0.invalidate() }
+    navigationTimers.removeAll()
+    hasLoaded = false
+  }
+
+  public func postMessage(_ message: String) {
+    guard let webView = webView else { return }
+    let escaped = jsStringLiteral(message)
+    let script = "window.dispatchEvent(new MessageEvent('message', { data: \(escaped) }));"
+    webView.evaluateJavaScript(script, completionHandler: nil)
+  }
+
+  public func respondToShouldStartLoad(id: String, allow: Bool) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      guard let handler = self.pendingNavigationDecisions.removeValue(forKey: id) else { return }
+      self.navigationTimers.removeValue(forKey: id)?.invalidate()
+      handler(allow ? .allow : .cancel)
+    }
+  }
+
+  // MARK: - Lazy creation
+
+  private func ensureWebView() {
+    if webView != nil { return }
+
+    let configuration = WKWebViewConfiguration()
+    configuration.websiteDataStore = .default()
+
+    let userContentController = WKUserContentController()
+    let polyfill = """
+    (function() {
+      if (window.ReactNativeWebView) return;
+      window.ReactNativeWebView = {
+        postMessage: function(message) {
+          window.webkit.messageHandlers.\(scriptHandlerName).postMessage(message);
+        }
+      };
+    })();
+    """
+    let userScript = WKUserScript(
+      source: polyfill,
+      injectionTime: .atDocumentStart,
+      forMainFrameOnly: false
+    )
+    userContentController.addUserScript(userScript)
+    userContentController.add(self, name: scriptHandlerName)
+    configuration.userContentController = userContentController
+
+    let frame = UIScreen.main.bounds
+    let webView = WKWebView(frame: frame, configuration: configuration)
+    webView.navigationDelegate = self
+    webView.scrollView.contentInsetAdjustmentBehavior = .never
+    webView.translatesAutoresizingMaskIntoConstraints = false
+
+    // Make the WKWebView transparent so the RN content beneath shows through
+    // when the webview-controller renders without an opaque backdrop.
+    webView.isOpaque = false
+    webView.backgroundColor = .clear
+    webView.scrollView.backgroundColor = .clear
+
+    if #available(iOS 16.4, *) {
+      webView.isInspectable = debuggingEnabled
+    }
+
+    let rootVC = UIViewController()
+    rootVC.view.backgroundColor = .clear
+    rootVC.view.isOpaque = false
+    rootVC.view.addSubview(webView)
+    NSLayoutConstraint.activate([
+      webView.topAnchor.constraint(equalTo: rootVC.view.topAnchor),
+      webView.bottomAnchor.constraint(equalTo: rootVC.view.bottomAnchor),
+      webView.leadingAnchor.constraint(equalTo: rootVC.view.leadingAnchor),
+      webView.trailingAnchor.constraint(equalTo: rootVC.view.trailingAnchor),
+    ])
+
+    let window = UIWindow(frame: frame)
+    window.windowLevel = .alert
+    window.backgroundColor = .clear
+    window.isOpaque = false
+    window.rootViewController = rootVC
+    // Keep the window in the visible window stack from creation onward so
+    // iOS does not throttle the WKWebView's JS execution. We start fully
+    // transparent and non-interactive — `setVisible(true)` flips `alpha` and
+    // interaction back on without ever hiding the window.
+    window.isHidden = false
+    window.alpha = 0
+    window.isUserInteractionEnabled = false
+
+    self.webView = webView
+    self.window = window
+  }
+
+  // Walk the WKWebView subview tree, find the WKContentView (the first
+  // responder for keyboard input), and dynamically subclass it so its
+  // `inputAccessoryView` getter returns nil. This is the same technique
+  // react-native-webview uses for `hideKeyboardAccessoryView`.
+  private func hideInputAccessoryView(on webView: WKWebView) {
+    let hiddenClassName = "DynamicEmbeddedWebViewHiddenAccessory"
+    guard let contentView = findContentView(in: webView) else { return }
+    if NSStringFromClass(type(of: contentView)) == hiddenClassName { return }
+    guard let baseClass = object_getClass(contentView) else { return }
+    let existing: AnyClass? = NSClassFromString(hiddenClassName)
+    let targetClass: AnyClass
+    if let existing = existing {
+      targetClass = existing
+    } else {
+      guard let newClass = objc_allocateClassPair(baseClass, hiddenClassName, 0) else { return }
+      let block: @convention(block) (Any) -> UIView? = { _ in nil }
+      let imp = imp_implementationWithBlock(block)
+      let selector = #selector(getter: UIResponder.inputAccessoryView)
+      class_addMethod(newClass, selector, imp, "@@:")
+      objc_registerClassPair(newClass)
+      targetClass = newClass
+    }
+    object_setClass(contentView, targetClass)
+  }
+
+  private func findContentView(in view: UIView) -> UIView? {
+    for subview in view.subviews {
+      let className = NSStringFromClass(type(of: subview))
+      if className.contains("WKContentView") { return subview }
+      if let found = findContentView(in: subview) { return found }
+    }
+    return nil
+  }
+
+  // Use JSONSerialization to safely encode an arbitrary string as a JS string literal.
+  private func jsStringLiteral(_ raw: String) -> String {
+    guard
+      let data = try? JSONSerialization.data(withJSONObject: [raw], options: []),
+      let arrayString = String(data: data, encoding: .utf8),
+      arrayString.count >= 2
+    else {
+      return "\"\""
+    }
+    let start = arrayString.index(after: arrayString.startIndex)
+    let end = arrayString.index(before: arrayString.endIndex)
+    return String(arrayString[start..<end])
+  }
+}
+
+extension EmbeddedWebViewController: WKScriptMessageHandler {
+  public func userContentController(
+    _: WKUserContentController,
+    didReceive message: WKScriptMessage
+  ) {
+    guard message.name == scriptHandlerName else { return }
+    let payload: String
+    if let asString = message.body as? String {
+      payload = asString
+    } else {
+      payload = String(describing: message.body)
+    }
+    eventEmitter?("onMessage", ["message": payload])
+  }
+}
+
+extension EmbeddedWebViewController: WKNavigationDelegate {
+  public func webView(
+    _: WKWebView,
+    decidePolicyFor navigationAction: WKNavigationAction,
+    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
+  ) {
+    let url = navigationAction.request.url?.absoluteString ?? ""
+    let scheme = navigationAction.request.url?.scheme?.lowercased()
+    let isTopFrame = navigationAction.targetFrame?.isMainFrame ?? true
+
+    // Sub-frame requests are auto-allowed (matches Android + JS allowlist).
+    // The trusted top-frame controls iframe content; iframes routinely start
+    // as `about:blank` and use `blob:` / `data:` / `about:srcdoc` URLs for
+    // legitimate functionality (WaaS MPC iframes, web workers, sandboxed
+    // inline content), so we defer iframe trust to the top-frame.
+    if !isTopFrame {
+      decisionHandler(.allow)
+      return
+    }
+
+    // Defense-in-depth: reject non-https top-frame schemes at the native layer
+    // before prompting JS. The JS allowlist would also reject these, but a JS
+    // bug approving a `javascript:` / `file:` / `data:` URL must not be enough
+    // to load it. http is permitted only in debug builds.
+    let isAllowedTopFrameScheme =
+      scheme == "https" || (allowsHttpScheme && scheme == "http")
+    if !isAllowedTopFrameScheme {
+      decisionHandler(.cancel)
+      eventEmitter?("onLoadError", [
+        "url": url,
+        "code": -1,
+        "domain": "EmbeddedWebViewBlockedScheme",
+        "description": "Blocked navigation to disallowed scheme: \(url)",
+        "isProvisional": true,
+      ])
+      return
+    }
+
+    let id = UUID().uuidString
+    pendingNavigationDecisions[id] = decisionHandler
+
+    let timer = Timer.scheduledTimer(withTimeInterval: navigationDecisionTimeout, repeats: false) { [weak self] _ in
+      guard let self = self else { return }
+      DispatchQueue.main.async {
+        if let handler = self.pendingNavigationDecisions.removeValue(forKey: id) {
+          self.navigationTimers.removeValue(forKey: id)?.invalidate()
+          handler(.cancel)
+        }
+      }
+    }
+    navigationTimers[id] = timer
+
+    eventEmitter?("onShouldStartLoad", [
+      "id": id,
+      "url": url,
+      "isTopFrame": isTopFrame,
+    ])
+  }
+
+  public func webView(
+    _: WKWebView,
+    decidePolicyFor navigationResponse: WKNavigationResponse,
+    decisionHandler: @escaping (WKNavigationResponsePolicy) -> Void
+  ) {
+    // WKWebView does not fire didFail / didFailProvisionalNavigation for HTTP
+    // error status codes — a 404 or 500 just renders an empty page. Surface
+    // main-frame HTTP errors as onLoadError so the SDK's load-error path runs.
+    if let httpResponse = navigationResponse.response as? HTTPURLResponse,
+      navigationResponse.isForMainFrame,
+      httpResponse.statusCode >= 400 {
+      let url = httpResponse.url?.absoluteString ?? ""
+      let description = HTTPURLResponse.localizedString(forStatusCode: httpResponse.statusCode)
+      decisionHandler(.cancel)
+      eventEmitter?("onLoadError", [
+        "url": url,
+        "code": httpResponse.statusCode,
+        "domain": "EmbeddedWebViewHttpError",
+        "description": "HTTP \(httpResponse.statusCode): \(description)",
+        "isProvisional": false,
+      ])
+      return
+    }
+    decisionHandler(.allow)
+  }
+
+  public func webView(
+    _ webView: WKWebView,
+    didFailProvisionalNavigation _: WKNavigation!,
+    withError error: Error
+  ) {
+    emitLoadError(error: error as NSError, isProvisional: true, url: webView.url?.absoluteString)
+  }
+
+  public func webView(
+    _ webView: WKWebView,
+    didFail _: WKNavigation!,
+    withError error: Error
+  ) {
+    emitLoadError(error: error as NSError, isProvisional: false, url: webView.url?.absoluteString)
+  }
+
+  public func webView(_ webView: WKWebView, didCommit _: WKNavigation!) {
+    // WKContentView is created lazily once content starts being committed —
+    // suppress its input accessory bar here so focusing inputs in the page
+    // doesn't show the system "< > Done" toolbar. Matches the
+    // `hideKeyboardAccessoryView` setting used by `react-native-webview`.
+    hideInputAccessoryView(on: webView)
+  }
+
+  public func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
+    eventEmitter?("onLoadError", [
+      "url": webView.url?.absoluteString ?? "",
+      "code": -1,
+      "domain": "EmbeddedWebViewProcessTerminated",
+      "description": "WebContent process terminated",
+      "isProvisional": false,
+    ])
+  }
+
+  // Errors from cancelling our own navigation (e.g. when the JS allowlist
+  // returns false or the 2 s decision timeout fires) are not real load
+  // failures and should not be instrumented as such.
+  private func isCancellationError(_ error: NSError) -> Bool {
+    if error.domain == NSURLErrorDomain && error.code == NSURLErrorCancelled {
+      return true
+    }
+    // WebKit "frame load interrupted" — fired when our policy decision cancels
+    // the navigation.
+    if error.domain == "WebKitErrorDomain" && error.code == 102 {
+      return true
+    }
+    return false
+  }
+
+  private func emitLoadError(error: NSError, isProvisional: Bool, url: String?) {
+    if isCancellationError(error) { return }
+    eventEmitter?("onLoadError", [
+      "url": url ?? "",
+      "code": error.code,
+      "domain": "EmbeddedWebViewLoadError",
+      "description": error.localizedDescription,
+      "isProvisional": isProvisional,
+    ])
+  }
+}

package/ios/EmbeddedWebViewModule.swift

@@ -0,0 +1,62 @@
+import ExpoModulesCore
+
+public class EmbeddedWebViewModule: Module {
+  private var emitterToken: UUID?
+
+  public func definition() -> ModuleDefinition {
+    Name("EmbeddedWebView")
+
+    Events("onMessage", "onShouldStartLoad", "onLoadError")
+
+    OnCreate {
+      self.emitterToken = EmbeddedWebViewController.shared.setEmitter { [weak self] name, payload in
+        guard let self = self else { return }
+        self.sendEvent(name, payload)
+      }
+    }
+
+    OnDestroy {
+      // Only clear if our emitter is still the live one. Prevents a stale
+      // OnDestroy (e.g. during dev hot reload after a newer OnCreate already
+      // ran) from nulling the active emitter.
+      if let token = self.emitterToken {
+        EmbeddedWebViewController.shared.clearEmitter(token: token)
+        self.emitterToken = nil
+      }
+    }
+
+    AsyncFunction("setUrl") { (url: String) in
+      DispatchQueue.main.async {
+        EmbeddedWebViewController.shared.setUrl(url)
+      }
+    }
+
+    AsyncFunction("setVisible") { (visible: Bool) in
+      DispatchQueue.main.async {
+        EmbeddedWebViewController.shared.setVisible(visible)
+      }
+    }
+
+    AsyncFunction("setDebuggingEnabled") { (enabled: Bool) in
+      DispatchQueue.main.async {
+        EmbeddedWebViewController.shared.setDebuggingEnabled(enabled)
+      }
+    }
+
+    AsyncFunction("destroy") {
+      DispatchQueue.main.async {
+        EmbeddedWebViewController.shared.destroy()
+      }
+    }
+
+    AsyncFunction("postMessage") { (message: String) in
+      DispatchQueue.main.async {
+        EmbeddedWebViewController.shared.postMessage(message)
+      }
+    }
+
+    AsyncFunction("respondToShouldStartLoad") { (id: String, allow: Bool) in
+      EmbeddedWebViewController.shared.respondToShouldStartLoad(id: id, allow: allow)
+    }
+  }
+}

package/ios/Keychain.podspec

@@ -1,8 +1,8 @@
 Pod::Spec.new do |s|
   s.name           = 'Keychain'
   s.version        = '1.0.0'
-  s.summary        = 'TEE-backed key operations for Dynamic SDK'
-  s.description    = 'Provides Secure Enclave key generation, signing, and management via Expo Modules'
+  s.summary        = 'Native iOS modules for Dynamic SDK'
+  s.description    = 'Provides Secure Enclave keychain operations and an embedded WKWebView host for the Dynamic webview-controller, exposed via Expo Modules.'
   s.homepage       = 'https://www.dynamic.xyz'
   s.license        = { type: 'MIT' }
   s.author         = 'Dynamic Labs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-labs/react-native-extension",
-  "version": "4.81.0",
+  "version": "4.83.1",
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "./src/index.d.ts",
@@ -18,11 +18,11 @@
     "@turnkey/react-native-passkey-stamper": "1.2.7",
     "@react-native-documents/picker": "^11.0.0",
     "react-native-fs": ">=2.20.0",
-    "@dynamic-labs/assert-package-version": "4.81.0",
-    "@dynamic-labs/client": "4.81.0",
-    "@dynamic-labs/logger": "4.81.0",
-    "@dynamic-labs/message-transport": "4.81.0",
-    "@dynamic-labs/webview-messages": "4.81.0"
+    "@dynamic-labs/assert-package-version": "4.83.1",
+    "@dynamic-labs/client": "4.83.1",
+    "@dynamic-labs/logger": "4.83.1",
+    "@dynamic-labs/message-transport": "4.83.1",
+    "@dynamic-labs/webview-messages": "4.83.1"
   },
   "peerDependencies": {
     "react": ">=18.0.0 <20.0.0",

package/src/ReactNativeExtension/ReactNativeExtension.d.ts

@@ -16,10 +16,33 @@ export type ReactNativeExtensionProps = {
      * Note: Deep link redirects use the auto-configured redirectUrl from expo-linking.
      */
     appOrigin?: string;
+    /**
+     * When true on iOS / Android, the SDK hosts the webview-controller in a
+     * native WKWebView (iOS) or android.webkit.WebView (Android) owned by a
+     * dedicated overlay window outside the React Native view tree. This
+     * isolates the webview from RN re-renders, navigation transitions, and
+     * other lifecycle events.
+     *
+     * When this flag is on, the `WebView` returned under
+     * `extension.reactNative.WebView` is a no-op component — do not render it.
+     * The native overlay is created lazily and retained for the process
+     * lifetime; subsequent extension factory invocations re-bind the JS bridge
+     * to the same native overlay (e.g. when the consumer recreates the client
+     * with a new `environmentId`).
+     *
+     * There is no automatic load recovery on this path. Any HTTP error,
+     * network failure, blocked navigation, SSL error, or process termination
+     * surfaces as `core.initialization.error` with `WebViewFailedToLoadError`
+     * — consumers should treat the SDK as un-initialised and react accordingly.
+     *
+     * On platforms other than iOS / Android (e.g. web), this flag is ignored.
+     * Defaults to false.
+     */
+    embeddedWebView?: boolean;
 };
 export type IReactNativeExtension = {
     reactNative: {
         WebView: FC<WebViewProps> | (() => null);
     };
 };
-export declare const ReactNativeExtension: ({ webviewUrl, webviewDebuggingEnabled, appOrigin, }?: ReactNativeExtensionProps) => Extension<IReactNativeExtension>;
+export declare const ReactNativeExtension: ({ webviewUrl, webviewDebuggingEnabled, appOrigin, embeddedWebView, }?: ReactNativeExtensionProps) => Extension<IReactNativeExtension>;

package/src/components/WebView/EmbeddedWebView/EmbeddedWebView.d.ts

@@ -0,0 +1,7 @@
+import { Core } from '@dynamic-labs/client';
+export type SetupEmbeddedWebViewArgs = {
+    webviewUrl: string;
+    core: Core;
+    webviewDebuggingEnabled?: boolean;
+};
+export declare const setupEmbeddedWebView: ({ webviewUrl, core, webviewDebuggingEnabled, }: SetupEmbeddedWebViewArgs) => (() => void);

package/src/components/WebView/EmbeddedWebView/index.d.ts

@@ -0,0 +1 @@
+export * from './EmbeddedWebView';

package/src/components/WebView/utils/shouldAllowNavigation/index.d.ts

@@ -0,0 +1 @@
+export * from './shouldAllowNavigation';

package/src/components/WebView/utils/shouldAllowNavigation/shouldAllowNavigation.d.ts

@@ -0,0 +1,5 @@
+export type NavigationRequest = {
+    url: string;
+    isTopFrame: boolean;
+};
+export declare const shouldAllowNavigation: (request: NavigationRequest, webViewUrl: URL) => boolean;

package/src/errors/WebViewFailedToLoadError.d.ts

@@ -1,3 +1,86 @@
+/**
+ * Categorical phase the WebView was in when the failure was raised.
+ *
+ * Use this for high-level grouping; the duration fields on
+ * {@link WebViewFailedToLoadErrorMeta} give the granular timing data.
+ */
+export type WebViewFailedToLoadErrorPhase = 'html_load' | 'sdk_bootstrap' | 'after_clear_state' | 'native_error' | 'embedded_native_error' | 'unknown';
+/**
+ * Structured context attached to {@link WebViewFailedToLoadError} so the
+ * resulting error log carries enough information to tell *which* step the
+ * WebView was stuck in when the failure was raised, and how long each step
+ * took.
+ *
+ * The setter on `InitializationModule.error` forwards this object directly
+ * to `logger.error`, so every field below ends up as a structured field on
+ * the same Datadog log as the error message.
+ */
+export type WebViewFailedToLoadErrorMeta = {
+    phase: WebViewFailedToLoadErrorPhase;
+    /**
+     * Milliseconds between RN's `onLoadStart` and `onLoad` callbacks (the
+     * HTML + asset fetch). `null` if `onLoad` never fired.
+     */
+    htmlLoadMs: number | null;
+    /**
+     * Milliseconds between RN's `onLoad` and `onLoadEnd` callbacks. Usually
+     * small; mostly there to flag pathological cases. `null` if `onLoadEnd`
+     * never fired.
+     */
+    onLoadToOnLoadEndMs: number | null;
+    /**
+     * Milliseconds between `onLoadEnd` and the first `manifest` request
+     * received from the webview-side SDK. Proxy for "the JS bundle is alive
+     * and the message bridge works". `null` if the manifest request never
+     * arrived.
+     */
+    manifestReceivedMs: number | null;
+    /**
+     * Milliseconds between `onLoadEnd` and the webview-side SDK signalling
+     * it has finished initialising (via the `sdkHasLoadedEventName` store
+     * change). `null` if the SDK never signalled it was ready.
+     */
+    sdkReadyMs: number | null;
+    /**
+     * Number of `retry` increments in the WebView URL at the time of failure
+     * (covers OS-kill reloads, load_error reloads, and recovery reloads).
+     */
+    retryCount: number;
+    /**
+     * Whether the `clear-state` query parameter was present in the URL when
+     * the failure was raised. `true` indicates we already retried with a
+     * clean state and still couldn't finish loading.
+     */
+    hadClearState: boolean;
+    /**
+     * Number of times RN's `onError` fired across the lifetime of the
+     * WebView component instance.
+     */
+    nativeErrorCount: number;
+    /**
+     * Number of times the OS killed the WebView process (via
+     * `onContentProcessDidTerminate` on iOS or `onRenderProcessGone` on
+     * Android) across the lifetime of the WebView component instance.
+     */
+    osKillCount: number;
+    /** The configured value for `loadingTimeout` (ms). */
+    loadingTimeoutMs: number;
+    /** The configured value for `recoveryTimeout` (ms). */
+    recoveryTimeoutMs: number;
+    /** The URL the WebView was attempting to load when the failure occurred. */
+    webviewUrl?: string;
+    /**
+     * Native error info, only populated when the failure originated from the
+     * embedded native WebView path (iOS WKWebView / Android WebView), where
+     * we get a single `onLoadError` event with these fields.
+     */
+    nativeErrorCode?: number;
+    nativeErrorDescription?: string;
+    nativeErrorDomain?: string;
+    nativeErrorIsProvisional?: boolean;
+    nativeErrorFailedUrl?: string;
+};
 export declare class WebViewFailedToLoadError extends Error {
-    constructor();
+    readonly meta?: WebViewFailedToLoadErrorMeta;
+    constructor(meta?: WebViewFailedToLoadErrorMeta);
 }