@dynamic-labs/react-native-extension 4.83.1 → 4.83.2-alpha.0

package/index.js

@@ -1,9 +1,10 @@
 import { assertPackageVersion } from '@dynamic-labs/assert-package-version';
 import { StyleSheet, Platform } from 'react-native';
-import { useEffect, useRef, useState, useCallback } from 'react';
+import { useEffect, useRef, useCallback, useState } from 'react';
 import { WebView as WebView$1 } from 'react-native-webview';
 import { Logger } from '@dynamic-labs/logger';
 import { messageTransportDataJsonReviver, parseMessageTransportData, messageTransportDataJsonReplacer, createRequestChannel } from '@dynamic-labs/message-transport';
+import { sdkHasLoadedEventName } from '@dynamic-labs/webview-messages';
 import { jsx } from 'react/jsx-runtime';
 import { requireNativeModule } from 'expo-modules-core';
 import { Passkey } from 'react-native-passkey';
@@ -12,7 +13,7 @@ import { openAuthSessionAsync } from 'expo-web-browser';
 import { getItemAsync, deleteItemAsync, setItemAsync } from 'expo-secure-store';
 import { createPasskey, PasskeyStamper } from '@turnkey/react-native-passkey-stamper';
 
-var version = "4.83.1";
+var version = "4.83.2-alpha.0";
 
 function _extends() {
   return _extends = Object.assign ? Object.assign.bind() : function (n) {
@@ -100,6 +101,122 @@ const useMessageTransportWebViewBridge = (core, webViewRef) => {
   };
 };
 
+const CLEAR_STATE_PARAM = 'clear-state';
+const ENVIRONMENT_ID_PARAM = 'environmentId';
+const WEBVIEW_START_TIME_PARAM = 'webviewStartTime';
+
+const hasClearStateInUrl = webViewUrl => Boolean(webViewUrl.searchParams.get(CLEAR_STATE_PARAM));
+
+const MANIFEST_MESSAGE_TYPE$1 = 'manifest';
+const RETRY_QUERY_PARAM = 'retry';
+const emptyPerAttemptState$1 = () => ({
+  htmlLoadStartedAt: null,
+  htmlLoadedAt: null,
+  manifestReceivedAt: null,
+  onLoadEndAt: null,
+  sdkReadyAt: null
+});
+const diffMs$1 = (later, earlier) => later !== null && earlier !== null ? later - earlier : null;
+const readRetryCount = webViewUrl => {
+  const raw = webViewUrl.searchParams.get(RETRY_QUERY_PARAM);
+  if (raw === null) return 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Tracks how long each step of the WebView load took, so when we raise
+ * `WebViewFailedToLoadError` we can attach the timings to the error log.
+ *
+ * The timings cover the host-side phases of the load — the webview-side
+ * timings (`webview.time_to_load_manifest`, `webview.time_to_sdk_ready`)
+ * still come from the webview itself once it boots, but those don't help
+ * when the webview never boots in the first place.
+ */
+const useWebViewPhaseTimers = ({
+  core,
+  webViewUrl,
+  loadingTimeout,
+  recoveryTimeout
+}) => {
+  const perAttemptRef = useRef(emptyPerAttemptState$1());
+  const nativeErrorCountRef = useRef(0);
+  const osKillCountRef = useRef(0);
+  const webViewUrlRef = useRef(webViewUrl);
+  webViewUrlRef.current = webViewUrl;
+  /**
+   * Listen on the message transport for the two webview-originated
+   * messages that mark "JS bundle alive" and "SDK ready".
+   *
+   * We only record the first occurrence per attempt so that a healthy
+   * reload doesn't overwrite the timing from the attempt that ultimately
+   * failed.
+   */
+  useEffect(() => {
+    const handler = message => {
+      if (message.origin !== 'webview') return;
+      if (message.type === MANIFEST_MESSAGE_TYPE$1 && perAttemptRef.current.manifestReceivedAt === null) {
+        perAttemptRef.current.manifestReceivedAt = Date.now();
+      }
+      if (message.type === sdkHasLoadedEventName && perAttemptRef.current.sdkReadyAt === null) {
+        perAttemptRef.current.sdkReadyAt = Date.now();
+      }
+    };
+    core.messageTransport.on(handler);
+    return () => core.messageTransport.off(handler);
+  }, [core]);
+  const recordEvent = useCallback(event => {
+    const now = Date.now();
+    switch (event) {
+      case 'load_start':
+        perAttemptRef.current = emptyPerAttemptState$1();
+        perAttemptRef.current.htmlLoadStartedAt = now;
+        break;
+      case 'load':
+        perAttemptRef.current.htmlLoadedAt = now;
+        break;
+      case 'load_end':
+        perAttemptRef.current.onLoadEndAt = now;
+        break;
+      case 'native_error':
+        nativeErrorCountRef.current += 1;
+        break;
+      case 'os_kill':
+        osKillCountRef.current += 1;
+        break;
+    }
+  }, []);
+  const getMeta = useCallback(({
+    phase
+  }) => {
+    const url = webViewUrlRef.current;
+    const {
+      htmlLoadStartedAt,
+      htmlLoadedAt,
+      onLoadEndAt,
+      manifestReceivedAt,
+      sdkReadyAt
+    } = perAttemptRef.current;
+    return {
+      hadClearState: hasClearStateInUrl(url),
+      htmlLoadMs: diffMs$1(htmlLoadedAt, htmlLoadStartedAt),
+      loadingTimeoutMs: loadingTimeout,
+      manifestReceivedMs: diffMs$1(manifestReceivedAt, onLoadEndAt),
+      nativeErrorCount: nativeErrorCountRef.current,
+      onLoadToOnLoadEndMs: diffMs$1(onLoadEndAt, htmlLoadedAt),
+      osKillCount: osKillCountRef.current,
+      phase,
+      recoveryTimeoutMs: recoveryTimeout,
+      retryCount: readRetryCount(url),
+      sdkReadyMs: diffMs$1(sdkReadyAt, onLoadEndAt),
+      webviewUrl: url.toString()
+    };
+  }, [loadingTimeout, recoveryTimeout]);
+  return {
+    getMeta,
+    recordEvent
+  };
+};
+
 const useWebViewVisibility = core => {
   const webViewVisibilityRequestChannelRef = useRef(createRequestChannel(core.messageTransport));
   const [visible, setVisible] = useState(false);
@@ -136,10 +253,6 @@ const styles = StyleSheet.create({
   }
 });
 
-const CLEAR_STATE_PARAM = 'clear-state';
-const ENVIRONMENT_ID_PARAM = 'environmentId';
-const WEBVIEW_START_TIME_PARAM = 'webviewStartTime';
-
 const setClearStateToUrl = webViewUrl => {
   const newWebViewUrl = new URL(webViewUrl);
   newWebViewUrl.searchParams.set(CLEAR_STATE_PARAM, 'true');
@@ -147,8 +260,6 @@ const setClearStateToUrl = webViewUrl => {
   return newWebViewUrl;
 };
 
-const hasClearStateInUrl = webViewUrl => Boolean(webViewUrl.searchParams.get(CLEAR_STATE_PARAM));
-
 const useWebViewRecoveryTimeout = ({
   core,
   webViewUrl,
@@ -301,15 +412,15 @@ const shouldAllowNavigation = (request, webViewUrl) => {
   return false;
 };
 
-const DEFAULT_RECOVERY_TIMEOUT_MS = 20000;
-const DEFAULT_LOADING_TIMEOUT_MS = 20000;
+const DEFAULT_RECOVERY_TIMEOUT_MS$1 = 20000;
+const DEFAULT_LOADING_TIMEOUT_MS$1 = 20000;
 const WebView = ({
   webviewUrl: initialWebViewUrl,
   core,
   webviewDebuggingEnabled: _webviewDebuggingEnabled = false,
   disableRecovery: _disableRecovery = false,
-  recoveryTimeout: _recoveryTimeout = DEFAULT_RECOVERY_TIMEOUT_MS,
-  loadingTimeout: _loadingTimeout = DEFAULT_LOADING_TIMEOUT_MS
+  recoveryTimeout: _recoveryTimeout = DEFAULT_RECOVERY_TIMEOUT_MS$1,
+  loadingTimeout: _loadingTimeout = DEFAULT_LOADING_TIMEOUT_MS$1
 }) => {
   const webViewRef = useRef(null);
   const {
@@ -319,6 +430,15 @@ const WebView = ({
   const {
     onMessageHandler
   } = useMessageTransportWebViewBridge(core, webViewRef);
+  const {
+    recordEvent,
+    getMeta
+  } = useWebViewPhaseTimers({
+    core,
+    loadingTimeout: _loadingTimeout,
+    recoveryTimeout: _recoveryTimeout,
+    webViewUrl
+  });
   const containerStyles = [styles['container'], visible ? styles.show : styles.hide];
   /**
    * Block the message transport when the webview is unmounted
@@ -360,13 +480,23 @@ const WebView = ({
       return newWebViewUrl;
     });
   }, [core]);
-  const blockAndReloadWebViewOsKill = useCallback(() => blockAndReloadWebView('os_kill'), [blockAndReloadWebView]);
+  const blockAndReloadWebViewOsKill = useCallback(() => {
+    recordEvent('os_kill');
+    blockAndReloadWebView('os_kill');
+  }, [blockAndReloadWebView, recordEvent]);
   useEffect(() => core.messageTransport.recoveryManager.onRecoveryRequested(() => blockAndReloadWebView('recovery')), [core, blockAndReloadWebView]);
-  const setWebViewLoadError = useCallback(() => {
+  const setWebViewLoadError = useCallback(phase => {
     // Error was already thrown, do not throw again
     if (core.initialization.error instanceof WebViewFailedToLoadError) return;
-    core.initialization.error = new WebViewFailedToLoadError();
-  }, [core]);
+    core.initialization.error = new WebViewFailedToLoadError(getMeta({
+      phase
+    }));
+  }, [core, getMeta]);
+  /**
+   * Wraps `setWebViewLoadError` so the consumer doesn't need to know
+   * about the phase enum; each callsite below binds its own phase.
+   */
+  const setWebViewLoadErrorWithPhase = useCallback(phase => () => setWebViewLoadError(phase), [setWebViewLoadError]);
   /**
    * Reload the webview with a clean state when a timeout is reached
    * and the webview did not get to the loaded state yet
@@ -374,7 +504,7 @@ const WebView = ({
   const startRecoveryTimeout = useWebViewRecoveryTimeout({
     core,
     disableRecovery: _disableRecovery,
-    onFailedToLoadAfterClearState: setWebViewLoadError,
+    onFailedToLoadAfterClearState: setWebViewLoadErrorWithPhase('after_clear_state'),
     recoveryTimeout: _recoveryTimeout,
     setWebViewUrl,
     webViewUrl
@@ -382,17 +512,30 @@ const WebView = ({
   const webViewLoadErrorCountRef = useRef(0);
   const onWebViewLoadError = useCallback(() => {
     webViewLoadErrorCountRef.current = webViewLoadErrorCountRef.current + 1;
+    recordEvent('native_error');
     /**
      * This is the first attempt to load the webview, do not throw an error
      * because the recovery system will attempt to reload the webview
      */
     if (webViewLoadErrorCountRef.current === 1) return;
-    setWebViewLoadError();
-  }, [setWebViewLoadError]);
+    setWebViewLoadError('native_error');
+  }, [recordEvent, setWebViewLoadError]);
   const {
-    onLoad,
-    onLoadStart
-  } = useWebViewLoadingTimeout(_loadingTimeout, setWebViewLoadError);
+    onLoad: onLoadFromTimeout,
+    onLoadStart: onLoadStartFromTimeout
+  } = useWebViewLoadingTimeout(_loadingTimeout, setWebViewLoadErrorWithPhase('html_load'));
+  const onLoadStart = useCallback(() => {
+    recordEvent('load_start');
+    onLoadStartFromTimeout();
+  }, [onLoadStartFromTimeout, recordEvent]);
+  const onLoad = useCallback(() => {
+    recordEvent('load');
+    onLoadFromTimeout();
+  }, [onLoadFromTimeout, recordEvent]);
+  const onLoadEnd = useCallback(() => {
+    recordEvent('load_end');
+    startRecoveryTimeout();
+  }, [recordEvent, startRecoveryTimeout]);
   return /*#__PURE__*/jsx(WebView$1, {
     ref: webViewRef,
     source: {
@@ -401,7 +544,7 @@ const WebView = ({
     containerStyle: containerStyles,
     style: styles['webview'],
     onMessage: onMessageHandler,
-    onLoadEnd: () => startRecoveryTimeout(),
+    onLoadEnd: onLoadEnd,
     onLoadStart: onLoadStart,
     onLoad: onLoad,
     hideKeyboardAccessoryView: true,
@@ -453,6 +596,105 @@ const getEmbeddedWebView = () => {
   }
 };
 
+const MANIFEST_MESSAGE_TYPE = 'manifest';
+const emptyPerAttemptState = () => ({
+  htmlLoadStartedAt: null,
+  htmlLoadedAt: null,
+  manifestReceivedAt: null,
+  onLoadEndAt: null,
+  sdkReadyAt: null
+});
+const diffMs = (later, earlier) => later !== null && earlier !== null ? later - earlier : null;
+/**
+ * Non-React equivalent of `useWebViewPhaseTimers` for the embedded native
+ * webview path. The embedded path is a singleton wired by `setupEmbeddedWebView`
+ * (not a React component), so we expose the same phase-timing surface as a
+ * plain factory.
+ *
+ * The hook and the factory are intentionally separate: the embedded path does
+ * not have a retry or clear-state model, so `retryCount` is always `0` and
+ * `hadClearState` is always `false` in the meta produced here. Sharing one
+ * implementation would require either pulling React into a hot non-React path
+ * or threading a stateless adapter through both consumers \u2014 the duplication
+ * is small enough that keeping them separate stays cleaner.
+ */
+const createEmbeddedWebViewPhaseTimers = ({
+  core,
+  webViewUrl,
+  loadingTimeoutMs,
+  recoveryTimeoutMs
+}) => {
+  let perAttempt = emptyPerAttemptState();
+  let nativeErrorCount = 0;
+  let osKillCount = 0;
+  const handleMessage = message => {
+    if (message.origin !== 'webview') return;
+    if (message.type === MANIFEST_MESSAGE_TYPE && perAttempt.manifestReceivedAt === null) {
+      perAttempt.manifestReceivedAt = Date.now();
+    }
+    if (message.type === sdkHasLoadedEventName && perAttempt.sdkReadyAt === null) {
+      perAttempt.sdkReadyAt = Date.now();
+    }
+  };
+  core.messageTransport.on(handleMessage);
+  const recordEvent = event => {
+    const now = Date.now();
+    switch (event) {
+      case 'load_start':
+        perAttempt = emptyPerAttemptState();
+        perAttempt.htmlLoadStartedAt = now;
+        break;
+      case 'load':
+        perAttempt.htmlLoadedAt = now;
+        break;
+      case 'load_end':
+        perAttempt.onLoadEndAt = now;
+        break;
+      case 'native_error':
+        nativeErrorCount += 1;
+        break;
+      case 'os_kill':
+        osKillCount += 1;
+        break;
+    }
+  };
+  const getMeta = ({
+    phase
+  }) => {
+    const {
+      htmlLoadStartedAt,
+      htmlLoadedAt,
+      onLoadEndAt,
+      manifestReceivedAt,
+      sdkReadyAt
+    } = perAttempt;
+    return {
+      hadClearState: false,
+      htmlLoadMs: diffMs(htmlLoadedAt, htmlLoadStartedAt),
+      loadingTimeoutMs,
+      manifestReceivedMs: diffMs(manifestReceivedAt, onLoadEndAt),
+      nativeErrorCount,
+      onLoadToOnLoadEndMs: diffMs(onLoadEndAt, htmlLoadedAt),
+      osKillCount,
+      phase,
+      recoveryTimeoutMs,
+      retryCount: 0,
+      sdkReadyMs: diffMs(sdkReadyAt, onLoadEndAt),
+      webviewUrl: webViewUrl.toString()
+    };
+  };
+  const dispose = () => {
+    core.messageTransport.off(handleMessage);
+  };
+  return {
+    dispose,
+    getMeta,
+    recordEvent
+  };
+};
+
+const DEFAULT_LOADING_TIMEOUT_MS = 20000;
+const DEFAULT_RECOVERY_TIMEOUT_MS = 20000;
 // Wires the JS-side bridge to the native WKWebView singleton owned by Swift.
 // This is intentionally not a React component: the embedded webview lives
 // outside the React tree (in a dedicated UIWindow on iOS), so its setup runs
@@ -465,10 +707,47 @@ const getEmbeddedWebView = () => {
 const setupEmbeddedWebView = ({
   webviewUrl,
   core,
-  webviewDebuggingEnabled: _webviewDebuggingEnabled = false
+  webviewDebuggingEnabled: _webviewDebuggingEnabled = false,
+  loadingTimeoutMs: _loadingTimeoutMs = DEFAULT_LOADING_TIMEOUT_MS,
+  recoveryTimeoutMs: _recoveryTimeoutMs = DEFAULT_RECOVERY_TIMEOUT_MS
 }) => {
   const native = getEmbeddedWebView();
   const builtUrl = assignStartTimeToUrl(assignEnvironmentIdToUrl(webviewUrl, core.environmentId));
+  const phaseTimers = createEmbeddedWebViewPhaseTimers({
+    core,
+    loadingTimeoutMs: _loadingTimeoutMs,
+    recoveryTimeoutMs: _recoveryTimeoutMs,
+    webViewUrl: builtUrl
+  });
+  let loadingTimer = null;
+  let recoveryTimer = null;
+  let hasFailed = false;
+  const clearLoadingTimer = () => {
+    if (loadingTimer !== null) {
+      clearTimeout(loadingTimer);
+      loadingTimer = null;
+    }
+  };
+  const clearRecoveryTimer = () => {
+    if (recoveryTimer !== null) {
+      clearTimeout(recoveryTimer);
+      recoveryTimer = null;
+    }
+  };
+  // Raise `WebViewFailedToLoadError` once per setup. Subsequent triggers
+  // (e.g. recovery timeout firing after html_load already failed) are
+  // suppressed so we don't spam the initialization-error setter with
+  // duplicate logs for the same load attempt.
+  const raiseFailure = (phase, extraMeta = {}) => {
+    if (hasFailed) return;
+    hasFailed = true;
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    const meta = phaseTimers.getMeta({
+      phase
+    });
+    core.initialization.error = new WebViewFailedToLoadError(Object.assign(Object.assign({}, meta), extraMeta));
+  };
   const visibilityChannel = createRequestChannel(core.messageTransport);
   const removeVisibilityHandler = visibilityChannel.handle('setVisibility', visible => {
     native.setVisible(visible).catch(err => {
@@ -482,6 +761,15 @@ const setupEmbeddedWebView = ({
     });
   };
   core.messageTransport.on(handleHostMessage);
+  // Watch for the webview-side SDK ready signal so we can clear the
+  // recovery timer. The phase-timer factory also subscribes for its own
+  // bookkeeping — both subscriptions are independent and idempotent.
+  const handleSdkReady = message => {
+    if (message.origin !== 'webview') return;
+    if (message.type !== sdkHasLoadedEventName) return;
+    clearRecoveryTimer();
+  };
+  core.messageTransport.on(handleSdkReady);
   const onMessageSub = native.addListener('onMessage', event => {
     let parsed = null;
     try {
@@ -504,7 +792,32 @@ const setupEmbeddedWebView = ({
       logger.warn('EmbeddedWebView.respondToShouldStartLoad failed', err);
     });
   });
+  const onLoadStartSub = native.addListener('onLoadStart', () => {
+    phaseTimers.recordEvent('load_start');
+    // Re-arm both timers on every load_start. A retry from the native
+    // side (e.g. a redirect, or a reload after a transient failure)
+    // resets the html_load window cleanly without leaving a stale timer
+    // around from the previous attempt.
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    loadingTimer = setTimeout(() => {
+      raiseFailure('html_load');
+    }, _loadingTimeoutMs);
+  });
+  const onLoadSub = native.addListener('onLoad', () => {
+    phaseTimers.recordEvent('load');
+    clearLoadingTimer();
+  });
+  const onLoadEndSub = native.addListener('onLoadEnd', () => {
+    phaseTimers.recordEvent('load_end');
+    clearLoadingTimer();
+    clearRecoveryTimer();
+    recoveryTimer = setTimeout(() => {
+      raiseFailure('sdk_bootstrap');
+    }, _recoveryTimeoutMs);
+  });
   const onLoadErrorSub = native.addListener('onLoadError', event => {
+    phaseTimers.recordEvent('native_error');
     logger.warn('EmbeddedWebView load error', event);
     logger.instrument('Embedded webview load error', {
       environmentId: core.environmentId,
@@ -518,7 +831,13 @@ const setupEmbeddedWebView = ({
       time: 0,
       webviewUrl: builtUrl.toString()
     });
-    core.initialization.error = new WebViewFailedToLoadError();
+    raiseFailure('embedded_native_error', {
+      nativeErrorCode: event.code,
+      nativeErrorDescription: event.description,
+      nativeErrorDomain: event.domain,
+      nativeErrorFailedUrl: event.url,
+      nativeErrorIsProvisional: event.isProvisional
+    });
   });
   native.setDebuggingEnabled(_webviewDebuggingEnabled).catch(err => {
     logger.warn('EmbeddedWebView.setDebuggingEnabled failed', err);
@@ -527,11 +846,18 @@ const setupEmbeddedWebView = ({
     logger.warn('EmbeddedWebView.setUrl failed', err);
   });
   return () => {
+    clearLoadingTimer();
+    clearRecoveryTimer();
     removeVisibilityHandler();
     core.messageTransport.off(handleHostMessage);
+    core.messageTransport.off(handleSdkReady);
     onMessageSub.remove();
     onShouldStartLoadSub.remove();
+    onLoadStartSub.remove();
+    onLoadSub.remove();
+    onLoadEndSub.remove();
     onLoadErrorSub.remove();
+    phaseTimers.dispose();
   };
 };
 

package/ios/EmbeddedWebViewController.swift

@@ -380,12 +380,34 @@ extension EmbeddedWebViewController: WKNavigationDelegate {
     emitLoadError(error: error as NSError, isProvisional: false, url: webView.url?.absoluteString)
   }
 
+  public func webView(
+    _ webView: WKWebView,
+    didStartProvisionalNavigation _: WKNavigation!
+  ) {
+    eventEmitter?("onLoadStart", [
+      "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)
+
+    // didCommit fires when the first byte of the response is rendered —
+    // analogous to RN's `onLoad` callback (page content has actually
+    // started arriving, not just the navigation request).
+    eventEmitter?("onLoad", [
+      "url": webView.url?.absoluteString ?? "",
+    ])
+  }
+
+  public func webView(_ webView: WKWebView, didFinish _: WKNavigation!) {
+    eventEmitter?("onLoadEnd", [
+      "url": webView.url?.absoluteString ?? "",
+    ])
   }
 
   public func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {

package/ios/EmbeddedWebViewModule.swift

@@ -6,7 +6,14 @@ public class EmbeddedWebViewModule: Module {
   public func definition() -> ModuleDefinition {
     Name("EmbeddedWebView")
 
-    Events("onMessage", "onShouldStartLoad", "onLoadError")
+    Events(
+      "onMessage",
+      "onShouldStartLoad",
+      "onLoadError",
+      "onLoadStart",
+      "onLoad",
+      "onLoadEnd"
+    )
 
     OnCreate {
       self.emitterToken = EmbeddedWebViewController.shared.setEmitter { [weak self] name, payload in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-labs/react-native-extension",
-  "version": "4.83.1",
+  "version": "4.83.2-alpha.0",
   "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.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"
+    "@dynamic-labs/assert-package-version": "4.83.2-alpha.0",
+    "@dynamic-labs/client": "4.83.2-alpha.0",
+    "@dynamic-labs/logger": "4.83.2-alpha.0",
+    "@dynamic-labs/message-transport": "4.83.2-alpha.0",
+    "@dynamic-labs/webview-messages": "4.83.2-alpha.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0 <20.0.0",

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

@@ -3,5 +3,24 @@ export type SetupEmbeddedWebViewArgs = {
     webviewUrl: string;
     core: Core;
     webviewDebuggingEnabled?: boolean;
+    /**
+     * Max time (ms) between the native webview reporting it has started a
+     * navigation (`onLoadStart`) and reporting that the response committed
+     * (`onLoad`). If this elapses, the SDK raises
+     * {@link WebViewFailedToLoadError} with `phase: 'html_load'` so the page
+     * can no longer hang silently waiting for bytes that never arrive.
+     *
+     * Defaults to 20s, matching the RN `<WebView>` path.
+     */
+    loadingTimeoutMs?: number;
+    /**
+     * Max time (ms) between the native webview reporting it has finished
+     * loading (`onLoadEnd`) and the SDK signalling it has finished booting
+     * (`sdkHasLoadedEventName`). If this elapses, the SDK raises
+     * {@link WebViewFailedToLoadError} with `phase: 'sdk_bootstrap'`.
+     *
+     * Defaults to 20s, matching the RN `<WebView>` path.
+     */
+    recoveryTimeoutMs?: number;
 };
-export declare const setupEmbeddedWebView: ({ webviewUrl, core, webviewDebuggingEnabled, }: SetupEmbeddedWebViewArgs) => (() => void);
+export declare const setupEmbeddedWebView: ({ webviewUrl, core, webviewDebuggingEnabled, loadingTimeoutMs, recoveryTimeoutMs, }: SetupEmbeddedWebViewArgs) => (() => void);

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

@@ -0,0 +1,52 @@
+import { Core } from '@dynamic-labs/client';
+import { WebViewFailedToLoadErrorMeta, WebViewFailedToLoadErrorPhase } from '../../../../errors/WebViewFailedToLoadError';
+/**
+ * Per-attempt lifecycle event recorded by
+ * {@link createEmbeddedWebViewPhaseTimers}. `load_start` resets the per-attempt
+ * state (so the timings reflect the current load); `native_error` and
+ * `os_kill` increment cumulative counters that persist across reloads.
+ */
+export type EmbeddedWebViewPhaseEvent = 'load_start' | 'load' | 'load_end' | 'native_error' | 'os_kill';
+type EmbeddedWebViewPhaseTimersProps = {
+    core: Core;
+    webViewUrl: URL;
+    loadingTimeoutMs: number;
+    recoveryTimeoutMs: number;
+};
+export type EmbeddedWebViewPhaseTimers = {
+    /**
+     * Record a per-attempt lifecycle event. See {@link EmbeddedWebViewPhaseEvent}
+     * for the semantics of each event.
+     */
+    recordEvent: (event: EmbeddedWebViewPhaseEvent) => void;
+    /**
+     * Build the structured meta to attach to
+     * {@link WebViewFailedToLoadError}. The `phase` argument reflects the
+     * source of the failure; the duration fields come from the recorded
+     * lifecycle events and observed message-transport activity.
+     */
+    getMeta: (args: {
+        phase: WebViewFailedToLoadErrorPhase;
+    }) => WebViewFailedToLoadErrorMeta;
+    /**
+     * Detach from the message transport. Call this on teardown so the
+     * embedded webview controller can be re-created without leaking
+     * subscriptions.
+     */
+    dispose: () => void;
+};
+/**
+ * Non-React equivalent of `useWebViewPhaseTimers` for the embedded native
+ * webview path. The embedded path is a singleton wired by `setupEmbeddedWebView`
+ * (not a React component), so we expose the same phase-timing surface as a
+ * plain factory.
+ *
+ * The hook and the factory are intentionally separate: the embedded path does
+ * not have a retry or clear-state model, so `retryCount` is always `0` and
+ * `hadClearState` is always `false` in the meta produced here. Sharing one
+ * implementation would require either pulling React into a hot non-React path
+ * or threading a stateless adapter through both consumers \u2014 the duplication
+ * is small enough that keeping them separate stays cleaner.
+ */
+export declare const createEmbeddedWebViewPhaseTimers: ({ core, webViewUrl, loadingTimeoutMs, recoveryTimeoutMs, }: EmbeddedWebViewPhaseTimersProps) => EmbeddedWebViewPhaseTimers;
+export {};

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

@@ -0,0 +1 @@
+export { createEmbeddedWebViewPhaseTimers, type EmbeddedWebViewPhaseEvent, type EmbeddedWebViewPhaseTimers, } from './embeddedWebViewPhaseTimers';

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

@@ -0,0 +1 @@
+export { useWebViewPhaseTimers, type WebViewPhaseTimers, } from './useWebViewPhaseTimers';