react-native-instant-webview 0.1.0

package/src/WebViewPoolProvider.tsx

@@ -0,0 +1,138 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { WebViewProps } from 'react-native-webview';
+import { DEFAULT_POOL_CONFIG } from './constants';
+import WebViewManager from './WebViewManager';
+import WebViewSlot from './WebViewSlot';
+import type {
+  BorrowResult,
+  InstanceLayout,
+  PoolConfig,
+  PoolState,
+  WebViewPoolContextValue,
+  WebViewPoolProviderProps,
+} from './types';
+
+const WebViewPoolContext = createContext<WebViewPoolContextValue | null>(null);
+
+export function useWebViewPool(): WebViewPoolContextValue {
+  const ctx = useContext(WebViewPoolContext);
+  if (!ctx) {
+    throw new Error('useWebViewPool must be used within a WebViewPoolProvider');
+  }
+  return ctx;
+}
+
+export const WebViewPoolProvider: React.FC<WebViewPoolProviderProps> = ({
+  config,
+  children,
+}) => {
+  const managerRef = useRef(WebViewManager.getInstance());
+  const mergedConfig = useRef<PoolConfig>({
+    ...DEFAULT_POOL_CONFIG,
+    ...config,
+  }).current;
+
+  const [poolState, setPoolState] = useState<PoolState>(() => {
+    const mgr = managerRef.current;
+    mgr.initialize(mergedConfig);
+    return mgr.getState();
+  });
+
+  const layoutsRef = useRef<Map<string, InstanceLayout | null>>(new Map());
+  const propsRef = useRef<Map<string, Partial<WebViewProps>>>(new Map());
+
+  const [, forceRender] = useState(0);
+
+  useEffect(() => {
+    const mgr = managerRef.current;
+    const unsub = mgr.subscribe((state) => {
+      setPoolState(state);
+    });
+    return unsub;
+  }, []);
+
+  const borrow = useCallback(
+    (borrowerId: string): BorrowResult | null => {
+      return managerRef.current.borrow(borrowerId);
+    },
+    [],
+  );
+
+  const release = useCallback((instanceId: string): void => {
+    layoutsRef.current.delete(instanceId);
+    propsRef.current.delete(instanceId);
+    managerRef.current.release(instanceId);
+  }, []);
+
+  const setInstanceLayout = useCallback(
+    (instanceId: string, layout: InstanceLayout | null): void => {
+      layoutsRef.current.set(instanceId, layout);
+      forceRender((c) => c + 1);
+    },
+    [],
+  );
+
+  const setInstanceProps = useCallback(
+    (instanceId: string, props: Partial<WebViewProps>): void => {
+      propsRef.current.set(instanceId, props);
+      // No forceRender here — the slot reads from propsRef on next render
+      // triggered by the Manager's state change (borrow/release).
+    },
+    [],
+  );
+
+  const getInstanceLayout = useCallback(
+    (instanceId: string): InstanceLayout | null => {
+      return layoutsRef.current.get(instanceId) ?? null;
+    },
+    [],
+  );
+
+  const getInstanceProps = useCallback(
+    (instanceId: string): Partial<WebViewProps> | undefined => {
+      return propsRef.current.get(instanceId);
+    },
+    [],
+  );
+
+  const handleCleanupComplete = useCallback((instanceId: string) => {
+    managerRef.current.markIdle(instanceId);
+  }, []);
+
+  const contextValue: WebViewPoolContextValue = {
+    state: poolState,
+    borrow,
+    release,
+    setInstanceLayout,
+    setInstanceProps,
+    getInstanceLayout,
+    getInstanceProps,
+  };
+
+  return (
+    <WebViewPoolContext.Provider value={contextValue}>
+      <View style={styles.container}>
+        {children}
+        {poolState.instances.map((instance) => (
+          <WebViewSlot
+            key={instance.id}
+            instance={instance}
+            layout={layoutsRef.current.get(instance.id) ?? null}
+            instanceProps={propsRef.current.get(instance.id)}
+            config={mergedConfig}
+            onCleanupComplete={handleCleanupComplete}
+          />
+        ))}
+      </View>
+    </WebViewPoolContext.Provider>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});
+
+export default WebViewPoolProvider;

package/src/WebViewSlot.tsx

@@ -0,0 +1,107 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { View, type ViewStyle } from 'react-native';
+import { WebView, type WebViewNavigation } from 'react-native-webview';
+import { BLANK_HTML_SOURCE, CLEANUP_SCRIPT, HIDDEN_STYLE } from './constants';
+import type { InstanceLayout, PoolConfig, WebViewInstance } from './types';
+import type { WebViewProps } from 'react-native-webview';
+
+interface WebViewSlotProps {
+  instance: WebViewInstance;
+  layout: InstanceLayout | null;
+  instanceProps: Partial<WebViewProps> | undefined;
+  config: PoolConfig;
+  onCleanupComplete: (instanceId: string) => void;
+}
+
+const WebViewSlot: React.FC<WebViewSlotProps> = ({
+  instance,
+  layout,
+  instanceProps,
+  config,
+  onCleanupComplete,
+}) => {
+  const isVisible = instance.status === 'borrowed' && layout != null;
+  const prevStatusRef = useRef(instance.status);
+
+  // Track whether this slot has ever had a WebView rendered.
+  // On first borrow the WebView is created with a valid user source,
+  // avoiding the Fabric crash where didMoveToWindow fires before
+  // the source prop is applied (causing loadFileURL: with nil URL).
+  // After the first borrow, the WebView stays alive through
+  // cleaning → idle cycles.
+  const [hasWebView, setHasWebView] = useState(false);
+
+  useEffect(() => {
+    if (instance.status === 'borrowed' && !hasWebView) {
+      setHasWebView(true);
+    }
+  }, [instance.status, hasWebView]);
+
+  // When entering cleaning state, inject cleanup script then mark idle
+  useEffect(() => {
+    if (prevStatusRef.current !== 'cleaning' && instance.status === 'cleaning') {
+      const ref = instance.webViewRef.current;
+      if (ref) {
+        const script = config.customCleanupScript ?? CLEANUP_SCRIPT;
+        ref.injectJavaScript(script);
+      }
+      const timer = setTimeout(() => {
+        onCleanupComplete(instance.id);
+      }, 100);
+      return () => clearTimeout(timer);
+    }
+    prevStatusRef.current = instance.status;
+  }, [instance.status, instance.id, instance.webViewRef, config.customCleanupScript, onCleanupComplete]);
+
+  const containerStyle = useMemo<ViewStyle>(() => {
+    if (!isVisible || !layout) {
+      return HIDDEN_STYLE;
+    }
+    return {
+      position: 'absolute',
+      top: layout.top,
+      left: layout.left,
+      width: layout.width,
+      height: layout.height,
+    };
+  }, [isVisible, layout]);
+
+  const handleNavigationStateChange = useCallback(
+    (navState: WebViewNavigation) => {
+      instanceProps?.onNavigationStateChange?.(navState);
+    },
+    [instanceProps],
+  );
+
+  const source = useMemo(() => {
+    if (instance.status === 'borrowed' && instanceProps?.source) {
+      return instanceProps.source;
+    }
+    return BLANK_HTML_SOURCE;
+  }, [instance.status, instanceProps?.source]);
+
+  // Don't render WebView until the first borrow.
+  // This avoids the Fabric crash where didMoveToWindow → visitSource
+  // fires before _source prop is applied on the native side.
+  const shouldRenderWebView = hasWebView;
+
+  return (
+    <View
+      style={containerStyle}
+      pointerEvents={isVisible ? 'auto' : 'none'}
+    >
+      {shouldRenderWebView && (
+        <WebView
+          ref={instance.webViewRef as React.RefObject<WebView>}
+          {...(instance.status === 'borrowed' ? instanceProps : undefined)}
+          source={source}
+          onNavigationStateChange={handleNavigationStateChange}
+          style={{ flex: 1 }}
+          {...(config.defaultWebViewProps || {})}
+        />
+      )}
+    </View>
+  );
+};
+
+export default React.memo(WebViewSlot);

package/src/__mocks__/react-native-webview.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+
+const WebView = React.forwardRef((props: any, ref: any) => {
+  return React.createElement('WebView', { ...props, testID: props.testID ?? 'mock-webview', ref });
+});
+WebView.displayName = 'WebView';
+
+export { WebView };
+export type WebViewProps = Record<string, any>;
+export type WebViewNavigation = {
+  url: string;
+  title: string;
+  loading: boolean;
+  canGoBack: boolean;
+  canGoForward: boolean;
+};

package/src/__mocks__/react-native.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+
+const View = React.forwardRef(({ children, testID, ...props }: any, ref: any) => {
+  return React.createElement('View', { ...props, testID, ref }, children);
+});
+View.displayName = 'View';
+
+const StyleSheet = {
+  create: (styles: any) => styles,
+};
+
+export { View, StyleSheet };
+export type ViewStyle = Record<string, any>;
+export type LayoutChangeEvent = { nativeEvent: { layout: { x: number; y: number; width: number; height: number } } };

package/src/constants.ts

@@ -0,0 +1,46 @@
+import type { ViewStyle } from 'react-native';
+import type { PoolConfig } from './types';
+
+export const DEFAULT_POOL_CONFIG: PoolConfig = {
+  poolSize: 3,
+  cleanupOnReturn: true,
+};
+
+export const HIDDEN_STYLE: ViewStyle = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  left: -9999,
+  top: -9999,
+  opacity: 0,
+};
+
+// Blank HTML source used for idle/cleaning WebViews.
+// Using { html } instead of { uri: 'about:blank' } because
+// react-native-webview's native code may route 'about:blank'
+// through loadFileURL: which throws NSInvalidArgumentException.
+export const BLANK_HTML_SOURCE = { html: '' } as const;
+
+// Cleanup script injected into WebView when returning to pool.
+// Resets scroll position, clears timers, and removes all body content.
+// The body.innerHTML = '' is intentional — it clears the WebView DOM
+// as part of the pool cleanup process (no user content involved).
+export const CLEANUP_SCRIPT = `
+(function() {
+  try {
+    window.scrollTo(0, 0);
+    var highestTimeoutId = setTimeout(function(){}, 0);
+    for (var i = 0; i < highestTimeoutId; i++) {
+      clearTimeout(i);
+    }
+    var highestIntervalId = setInterval(function(){}, 0);
+    for (var j = 0; j < highestIntervalId; j++) {
+      clearInterval(j);
+    }
+    if (document.body) {
+      document.body.innerHTML = '';
+    }
+  } catch(e) {}
+  true;
+})();
+`;

package/src/index.tsx

@@ -0,0 +1,17 @@
+export { WebViewPoolProvider, useWebViewPool } from './WebViewPoolProvider';
+export { default as PooledWebView } from './PooledWebView';
+export { usePooledWebView } from './usePooledWebView';
+export { default as WebViewManager } from './WebViewManager';
+
+export type {
+  PoolConfig,
+  InstanceStatus,
+  WebViewInstance,
+  PoolState,
+  BorrowResult,
+  WebViewPoolContextValue,
+  InstanceLayout,
+  PooledWebViewProps,
+  WebViewPoolProviderProps,
+  UsePooledWebViewReturn,
+} from './types';

package/src/types.ts

@@ -0,0 +1,72 @@
+import type { RefObject } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { WebView, WebViewProps } from 'react-native-webview';
+
+export interface PoolConfig {
+  poolSize: number;
+  cleanupOnReturn: boolean;
+  customCleanupScript?: string;
+  defaultWebViewProps?: Partial<WebViewProps>;
+}
+
+export type InstanceStatus = 'idle' | 'borrowed' | 'cleaning';
+
+export interface WebViewInstance {
+  id: string;
+  status: InstanceStatus;
+  webViewRef: RefObject<WebView | null>;
+  borrowerId: string | null;
+  createdAt: number;
+  borrowedAt: number | null;
+}
+
+export interface PoolState {
+  instances: WebViewInstance[];
+  availableCount: number;
+  borrowedCount: number;
+  initialized: boolean;
+}
+
+export interface BorrowResult {
+  instanceId: string;
+  webViewRef: RefObject<WebView | null>;
+}
+
+export interface InstanceLayout {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+export interface WebViewPoolContextValue {
+  state: PoolState;
+  borrow: (borrowerId: string) => BorrowResult | null;
+  release: (instanceId: string) => void;
+  setInstanceLayout: (instanceId: string, layout: InstanceLayout | null) => void;
+  setInstanceProps: (instanceId: string, props: Partial<WebViewProps>) => void;
+  getInstanceLayout: (instanceId: string) => InstanceLayout | null;
+  getInstanceProps: (instanceId: string) => Partial<WebViewProps> | undefined;
+}
+
+export interface PooledWebViewProps extends Omit<WebViewProps, 'ref'> {
+  poolKey?: string;
+  containerStyle?: StyleProp<ViewStyle>;
+  onPoolExhausted?: () => void;
+  onBorrowed?: (instanceId: string) => void;
+  onReturned?: (instanceId: string) => void;
+}
+
+export interface WebViewPoolProviderProps {
+  config?: Partial<PoolConfig>;
+  children: React.ReactNode;
+}
+
+export interface UsePooledWebViewReturn {
+  borrow: () => BorrowResult | null;
+  release: () => void;
+  instanceId: string | null;
+  webViewRef: RefObject<WebView | null> | null;
+}
+
+export type PoolListener = (state: PoolState) => void;

package/src/usePooledWebView.ts

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+import type { WebView } from 'react-native-webview';
+import { useWebViewPool } from './WebViewPoolProvider';
+import type { UsePooledWebViewReturn } from './types';
+
+let hookBorrowerIdCounter = 0;
+
+export function usePooledWebView(): UsePooledWebViewReturn {
+  const pool = useWebViewPool();
+  const instanceIdRef = useRef<string | null>(null);
+  const webViewRefRef = useRef<RefObject<WebView | null> | null>(null);
+  const [instanceId, setInstanceId] = useState<string | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (instanceIdRef.current) {
+        pool.release(instanceIdRef.current);
+        instanceIdRef.current = null;
+        webViewRefRef.current = null;
+      }
+    };
+  }, [pool]);
+
+  const borrow = useCallback(() => {
+    if (instanceIdRef.current) {
+      return {
+        instanceId: instanceIdRef.current,
+        webViewRef: webViewRefRef.current!,
+      };
+    }
+
+    const borrowerId = `hook-borrower-${++hookBorrowerIdCounter}`;
+    const result = pool.borrow(borrowerId);
+    if (!result) return null;
+
+    instanceIdRef.current = result.instanceId;
+    webViewRefRef.current = result.webViewRef;
+    setInstanceId(result.instanceId);
+    return result;
+  }, [pool]);
+
+  const release = useCallback(() => {
+    if (instanceIdRef.current) {
+      pool.release(instanceIdRef.current);
+      instanceIdRef.current = null;
+      webViewRefRef.current = null;
+      setInstanceId(null);
+    }
+  }, [pool]);
+
+  return {
+    borrow,
+    release,
+    instanceId,
+    webViewRef: webViewRefRef.current,
+  };
+}