@teardown/dev-client 2.0.70 → 2.0.72

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/dev-client",
-	"version": "2.0.70",
+	"version": "2.0.72",
 	"private": false,
 	"type": "module",
 	"publishConfig": {
@@ -34,7 +34,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
-		"@teardown/tsconfig": "2.0.70",
+		"@teardown/tsconfig": "2.0.72",
 		"@types/bun": "1.3.5",
 		"@types/react": "~19.1.0",
 		"react": "19.1.0",

package/src/components/bundler-waiting/bundler-waiting-overlay.tsx

@@ -0,0 +1,448 @@
+/**
+ * BundlerWaitingOverlay Component
+ *
+ * Full-screen overlay shown when the Metro bundler is not connected.
+ * Provides visual feedback while waiting for bundler connection,
+ * similar to Expo's dev launcher experience.
+ */
+
+import type React from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	ActivityIndicator,
+	Animated,
+	Keyboard,
+	KeyboardAvoidingView,
+	Platform,
+	StyleSheet,
+	Text,
+	TextInput,
+	type TextStyle,
+	TouchableOpacity,
+	View,
+	type ViewStyle,
+} from "react-native";
+import type { BundlerStatus } from "../../types";
+import { isValidBundlerUrl } from "../../utils/bundler-url";
+
+/**
+ * BundlerWaitingOverlay component props
+ */
+export interface BundlerWaitingOverlayProps {
+	/** Current bundler status */
+	bundlerStatus: BundlerStatus;
+
+	/** Expected bundler URL */
+	bundlerUrl: string | null;
+
+	/** Callback to retry connection */
+	onRetry?: () => void;
+
+	/** Callback when user enters custom URL */
+	onCustomUrl?: (url: string) => void;
+
+	/** Whether overlay is visible */
+	visible: boolean;
+
+	/** Test ID for testing */
+	testID?: string;
+}
+
+/**
+ * Connection state for display
+ */
+type ConnectionState = "connecting" | "failed" | "connected";
+
+/**
+ * Get connection state from bundler status
+ */
+function getConnectionState(status: BundlerStatus): ConnectionState {
+	if (status.connected) {
+		return "connected";
+	}
+	if (status.error) {
+		return "failed";
+	}
+	return "connecting";
+}
+
+/**
+ * BundlerWaitingOverlay component
+ *
+ * Shows a full-screen overlay while waiting for Metro bundler connection.
+ * Features:
+ * - Animated spinner during connection
+ * - Error message display
+ * - Retry button
+ * - Manual URL entry option
+ * - Auto-dismisses when connected
+ *
+ * @example
+ * ```tsx
+ * <BundlerWaitingOverlay
+ *   bundlerStatus={bundlerStatus}
+ *   bundlerUrl="http://localhost:8081"
+ *   onRetry={() => checkConnection()}
+ *   visible={!bundlerStatus.connected}
+ * />
+ * ```
+ */
+export function BundlerWaitingOverlay(props: BundlerWaitingOverlayProps): React.JSX.Element | null {
+	const { bundlerStatus, bundlerUrl, onRetry, onCustomUrl, visible, testID = "bundler-waiting-overlay" } = props;
+
+	// Animation for fade in/out
+	const fadeAnim = useRef(new Animated.Value(0)).current;
+
+	// Track if overlay should be rendered (for fade out animation)
+	const [isRendered, setIsRendered] = useState(visible);
+
+	// Manual URL input state
+	const [showUrlInput, setShowUrlInput] = useState(false);
+	const [customUrl, setCustomUrl] = useState("");
+	const [urlError, setUrlError] = useState<string | null>(null);
+
+	// Connection state
+	const connectionState = getConnectionState(bundlerStatus);
+
+	// Fade in/out animation
+	useEffect(() => {
+		if (visible) {
+			setIsRendered(true);
+		}
+
+		Animated.timing(fadeAnim, {
+			toValue: visible ? 1 : 0,
+			duration: 300,
+			useNativeDriver: true,
+		}).start(() => {
+			// After fade out animation completes, stop rendering
+			if (!visible) {
+				setIsRendered(false);
+			}
+		});
+	}, [visible, fadeAnim]);
+
+	// Handle retry
+	const handleRetry = useCallback(() => {
+		onRetry?.();
+	}, [onRetry]);
+
+	// Handle custom URL submission
+	const handleCustomUrlSubmit = useCallback(() => {
+		if (!customUrl.trim()) {
+			setUrlError("Please enter a URL");
+			return;
+		}
+
+		// Add http:// if not present
+		let url = customUrl.trim();
+		if (!url.includes("://")) {
+			url = `http://${url}`;
+		}
+
+		if (!isValidBundlerUrl(url)) {
+			setUrlError("Invalid URL format");
+			return;
+		}
+
+		setUrlError(null);
+		Keyboard.dismiss();
+		onCustomUrl?.(url);
+	}, [customUrl, onCustomUrl]);
+
+	// Handle URL tap - for future clipboard support
+	const handleUrlTap = useCallback(() => {
+		// Clipboard functionality can be added when @react-native-clipboard/clipboard is available
+		// For now, this is a no-op but provides touch feedback
+	}, []);
+
+	// Toggle URL input section
+	const toggleUrlInput = useCallback(() => {
+		setShowUrlInput((prev) => !prev);
+		setUrlError(null);
+	}, []);
+
+	// Don't render if not visible and animation complete
+	if (!isRendered) {
+		return null;
+	}
+
+	// Don't show in production
+	if (!__DEV__) {
+		return null;
+	}
+
+	return (
+		<Animated.View
+			style={[styles.container, { opacity: fadeAnim }]}
+			testID={testID}
+			accessibilityLabel="Bundler connection overlay"
+			accessibilityRole="alert"
+		>
+			<KeyboardAvoidingView behavior={Platform.OS === "ios" ? "padding" : "height"} style={styles.keyboardView}>
+				<View style={styles.content}>
+					{/* Logo/Icon */}
+					<View style={styles.logoContainer}>
+						<Text style={styles.logoText}>T</Text>
+					</View>
+
+					{/* Status */}
+					<View style={styles.statusContainer}>
+						{connectionState === "connecting" && (
+							<>
+								<ActivityIndicator size="large" color="#007aff" accessibilityLabel="Connecting" />
+								<Text style={styles.statusText}>Connecting to bundler...</Text>
+							</>
+						)}
+
+						{connectionState === "failed" && (
+							<>
+								<Text style={styles.errorIcon}>!</Text>
+								<Text style={styles.statusText}>Connection failed</Text>
+								<Text style={styles.errorText}>{bundlerStatus.error}</Text>
+							</>
+						)}
+
+						{connectionState === "connected" && (
+							<>
+								<Text style={styles.successIcon}>✓</Text>
+								<Text style={styles.statusText}>Connected</Text>
+							</>
+						)}
+					</View>
+
+					{/* Bundler URL */}
+					{bundlerUrl && connectionState !== "connected" && (
+						<TouchableOpacity
+							style={styles.urlContainer}
+							onPress={handleUrlTap}
+							activeOpacity={0.7}
+							accessibilityLabel={`Bundler URL: ${bundlerUrl}`}
+						>
+							<Text style={styles.urlLabel}>Waiting for:</Text>
+							<Text style={styles.urlText}>{bundlerUrl}</Text>
+						</TouchableOpacity>
+					)}
+
+					{/* Actions */}
+					{connectionState !== "connected" && (
+						<View style={styles.actions}>
+							{/* Retry Button */}
+							<TouchableOpacity
+								style={styles.retryButton}
+								onPress={handleRetry}
+								activeOpacity={0.7}
+								accessibilityLabel="Retry connection"
+								accessibilityRole="button"
+							>
+								<Text style={styles.retryButtonText}>Retry Connection</Text>
+							</TouchableOpacity>
+
+							{/* Manual URL Toggle */}
+							<TouchableOpacity
+								style={styles.toggleButton}
+								onPress={toggleUrlInput}
+								activeOpacity={0.7}
+								accessibilityLabel={showUrlInput ? "Hide URL input" : "Enter URL manually"}
+								accessibilityRole="button"
+							>
+								<Text style={styles.toggleButtonText}>{showUrlInput ? "▼" : "▶"} Enter URL manually</Text>
+							</TouchableOpacity>
+
+							{/* URL Input Section */}
+							{showUrlInput && (
+								<View style={styles.urlInputContainer}>
+									<TextInput
+										style={[styles.urlInput, urlError && styles.urlInputError]}
+										value={customUrl}
+										onChangeText={(text) => {
+											setCustomUrl(text);
+											setUrlError(null);
+										}}
+										placeholder="http://10.0.0.25:8081"
+										placeholderTextColor="#666666"
+										autoCapitalize="none"
+										autoCorrect={false}
+										keyboardType="url"
+										returnKeyType="go"
+										onSubmitEditing={handleCustomUrlSubmit}
+										accessibilityLabel="Custom bundler URL"
+									/>
+									{urlError && <Text style={styles.urlErrorText}>{urlError}</Text>}
+									<TouchableOpacity
+										style={[styles.connectButton, !customUrl.trim() && styles.connectButtonDisabled]}
+										onPress={handleCustomUrlSubmit}
+										disabled={!customUrl.trim()}
+										activeOpacity={0.7}
+										accessibilityLabel="Connect to custom URL"
+										accessibilityRole="button"
+									>
+										<Text style={styles.connectButtonText}>Connect</Text>
+									</TouchableOpacity>
+								</View>
+							)}
+						</View>
+					)}
+				</View>
+			</KeyboardAvoidingView>
+		</Animated.View>
+	);
+}
+
+const styles = StyleSheet.create({
+	container: {
+		...StyleSheet.absoluteFillObject,
+		backgroundColor: "#1a1a1a",
+		zIndex: 10001,
+	} as ViewStyle,
+	keyboardView: {
+		flex: 1,
+	} as ViewStyle,
+	content: {
+		flex: 1,
+		justifyContent: "center",
+		alignItems: "center",
+		padding: 24,
+	} as ViewStyle,
+
+	// Logo
+	logoContainer: {
+		width: 80,
+		height: 80,
+		borderRadius: 20,
+		backgroundColor: "#2a2a2a",
+		justifyContent: "center",
+		alignItems: "center",
+		marginBottom: 32,
+	} as ViewStyle,
+	logoText: {
+		fontSize: 40,
+		fontWeight: "bold",
+		color: "#007aff",
+	} as TextStyle,
+
+	// Status
+	statusContainer: {
+		alignItems: "center",
+		marginBottom: 24,
+	} as ViewStyle,
+	statusText: {
+		fontSize: 18,
+		fontWeight: "600",
+		color: "#ffffff",
+		marginTop: 16,
+	} as TextStyle,
+	errorIcon: {
+		fontSize: 32,
+		fontWeight: "bold",
+		color: "#ff3b30",
+		width: 48,
+		height: 48,
+		lineHeight: 48,
+		textAlign: "center",
+		backgroundColor: "#3a1010",
+		borderRadius: 24,
+		overflow: "hidden",
+	} as TextStyle,
+	successIcon: {
+		fontSize: 32,
+		fontWeight: "bold",
+		color: "#34c759",
+	} as TextStyle,
+	errorText: {
+		fontSize: 14,
+		color: "#ff6b6b",
+		marginTop: 8,
+		textAlign: "center",
+		maxWidth: 280,
+	} as TextStyle,
+
+	// URL display
+	urlContainer: {
+		backgroundColor: "#2a2a2a",
+		borderRadius: 12,
+		padding: 16,
+		alignItems: "center",
+		marginBottom: 24,
+		minWidth: 280,
+	} as ViewStyle,
+	urlLabel: {
+		fontSize: 12,
+		color: "#888888",
+		marginBottom: 4,
+		textTransform: "uppercase",
+	} as TextStyle,
+	urlText: {
+		fontSize: 16,
+		color: "#ffffff",
+		fontFamily: Platform.OS === "ios" ? "Menlo" : "monospace",
+	} as TextStyle,
+
+	// Actions
+	actions: {
+		alignItems: "center",
+		width: "100%",
+		maxWidth: 320,
+	} as ViewStyle,
+	retryButton: {
+		backgroundColor: "#007aff",
+		paddingVertical: 14,
+		paddingHorizontal: 32,
+		borderRadius: 12,
+		minWidth: 200,
+		alignItems: "center",
+		marginBottom: 16,
+	} as ViewStyle,
+	retryButtonText: {
+		color: "#ffffff",
+		fontSize: 16,
+		fontWeight: "600",
+	} as TextStyle,
+	toggleButton: {
+		paddingVertical: 12,
+	} as ViewStyle,
+	toggleButtonText: {
+		color: "#888888",
+		fontSize: 14,
+	} as TextStyle,
+
+	// URL Input
+	urlInputContainer: {
+		width: "100%",
+		marginTop: 12,
+	} as ViewStyle,
+	urlInput: {
+		backgroundColor: "#2a2a2a",
+		borderRadius: 8,
+		paddingHorizontal: 16,
+		paddingVertical: 12,
+		fontSize: 16,
+		color: "#ffffff",
+		borderWidth: 1,
+		borderColor: "#3a3a3a",
+	} as TextStyle,
+	urlInputError: {
+		borderColor: "#ff3b30",
+	} as ViewStyle,
+	urlErrorText: {
+		color: "#ff3b30",
+		fontSize: 12,
+		marginTop: 4,
+		marginLeft: 4,
+	} as TextStyle,
+	connectButton: {
+		backgroundColor: "#333333",
+		paddingVertical: 12,
+		borderRadius: 8,
+		alignItems: "center",
+		marginTop: 12,
+	} as ViewStyle,
+	connectButtonDisabled: {
+		opacity: 0.5,
+	} as ViewStyle,
+	connectButtonText: {
+		color: "#ffffff",
+		fontSize: 16,
+		fontWeight: "600",
+	} as TextStyle,
+});

package/src/components/bundler-waiting/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Bundler Waiting Overlay
+ *
+ * Full-screen overlay shown when Metro bundler is not connected.
+ */
+
+export { BundlerWaitingOverlay, type BundlerWaitingOverlayProps } from "./bundler-waiting-overlay";

package/src/components/index.ts

@@ -2,6 +2,7 @@
  * Component exports
  */
 
+export { BundlerWaitingOverlay, type BundlerWaitingOverlayProps } from "./bundler-waiting";
 export { DevMenu, type DevMenuProps } from "./dev-menu";
 export { ErrorOverlay, type ErrorOverlayProps } from "./error-overlay";
 export { SplashScreen, type SplashScreenProps } from "./splash-screen";

package/src/dev-client-provider.tsx

@@ -2,13 +2,16 @@
  * DevClientProvider
  *
  * Root provider component that wraps the application and provides
- * development client functionality including dev menu and splash screen.
+ * development client functionality including dev menu, splash screen,
+ * and bundler connection overlay.
  */
 
-import React, { createContext, type PropsWithChildren, useContext, useMemo } from "react";
+import React, { createContext, type PropsWithChildren, useCallback, useContext, useMemo, useState } from "react";
+import { BundlerWaitingOverlay } from "./components/bundler-waiting";
 import { DevMenu } from "./components/dev-menu";
 import { SplashScreen } from "./components/splash-screen";
 import { useBundlerStatus } from "./hooks/use-bundler-status";
+import { useDeepLinkBundler } from "./hooks/use-deep-link-bundler";
 import { useDevMenu } from "./hooks/use-dev-menu";
 import { useSplashScreen } from "./hooks/use-splash-screen";
 import type { DevClientConfig, DevClientContextValue } from "./types";
@@ -45,6 +48,9 @@ export interface DevClientProviderProps extends PropsWithChildren {
 
 	/** Whether to enable dev menu (default: true in dev) */
 	enableDevMenu?: boolean;
+
+	/** Whether to show bundler waiting overlay when not connected (default: true in dev) */
+	showBundlerWaiting?: boolean;
 }
 
 /**
@@ -74,7 +80,19 @@ export interface DevClientProviderProps extends PropsWithChildren {
  * ```
  */
 export function DevClientProvider(props: DevClientProviderProps): React.JSX.Element {
-	const { children, config: userConfig, showSplash = __DEV__, enableDevMenu = __DEV__ } = props;
+	const {
+		children,
+		config: userConfig,
+		showSplash = __DEV__,
+		enableDevMenu = __DEV__,
+		showBundlerWaiting = __DEV__,
+	} = props;
+
+	// Deep link bundler URL (if app was launched with dev deep link)
+	const { bundlerUrl: deepLinkBundlerUrl } = useDeepLinkBundler();
+
+	// Custom bundler URL override (from manual entry in overlay)
+	const [customBundlerUrl, setCustomBundlerUrl] = useState<string | null>(null);
 
 	// Merge config with defaults
 	const config: DevClientConfig = useMemo(
@@ -89,12 +107,31 @@ export function DevClientProvider(props: DevClientProviderProps): React.JSX.Elem
 		[userConfig]
 	);
 
+	// Effective bundler URL: custom > deep link > config
+	const effectiveBundlerUrl = customBundlerUrl ?? deepLinkBundlerUrl ?? config.bundlerUrl;
+
+	// Bundler status - track connection retry trigger
+	const [retryTrigger, setRetryTrigger] = useState(0);
+
 	// Bundler status
 	const bundlerStatus = useBundlerStatus({
-		bundlerUrl: config.bundlerUrl,
+		bundlerUrl: effectiveBundlerUrl,
 		enablePolling: __DEV__,
+		// Force re-check when retry is triggered
+		pollInterval: retryTrigger > 0 ? 2000 : 5000,
 	});
 
+	// Handle retry connection
+	const handleRetryConnection = useCallback(() => {
+		setRetryTrigger((prev) => prev + 1);
+	}, []);
+
+	// Handle custom URL from overlay
+	const handleCustomUrl = useCallback((url: string) => {
+		setCustomBundlerUrl(url);
+		setRetryTrigger((prev) => prev + 1);
+	}, []);
+
 	// Dev menu
 	const devMenu = useDevMenu({
 		enableShakeGesture: enableDevMenu && config.enableShakeGesture,
@@ -106,6 +143,9 @@ export function DevClientProvider(props: DevClientProviderProps): React.JSX.Elem
 		config: config.splash,
 	});
 
+	// Show bundler waiting overlay when not connected in dev mode
+	const showWaitingOverlay = showBundlerWaiting && __DEV__ && !bundlerStatus.connected;
+
 	// Context value
 	const contextValue: DevClientContextValue = useMemo(
 		() => ({
@@ -153,6 +193,18 @@ export function DevClientProvider(props: DevClientProviderProps): React.JSX.Elem
 					testID="teardown-splash-screen"
 				/>
 			)}
+
+			{/* Bundler Waiting Overlay - shown when not connected in dev */}
+			{showBundlerWaiting && (
+				<BundlerWaitingOverlay
+					bundlerStatus={bundlerStatus}
+					bundlerUrl={effectiveBundlerUrl ?? null}
+					onRetry={handleRetryConnection}
+					onCustomUrl={handleCustomUrl}
+					visible={showWaitingOverlay}
+					testID="teardown-bundler-waiting"
+				/>
+			)}
 		</DevClientContext.Provider>
 	);
 }

package/src/hooks/index.ts

@@ -8,6 +8,11 @@ export {
 	useBundlerStatus,
 } from "./use-bundler-status";
 
+export {
+	type UseDeepLinkBundlerReturn,
+	useDeepLinkBundler,
+} from "./use-deep-link-bundler";
+
 export {
 	createInitialDevMenuState,
 	type DefaultMenuItemHandlers,

package/src/hooks/use-deep-link-bundler.ts

@@ -0,0 +1,143 @@
+/**
+ * Deep Link Bundler URL Hook
+ *
+ * Parses bundler URL from deep link when app is launched
+ * with a dev deep link (e.g., myapp://dev?bundler=http://localhost:8081)
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { Linking } from "react-native";
+
+/**
+ * Parse bundler URL from a deep link
+ *
+ * @param url - Deep link URL
+ * @returns Bundler URL or null if not found
+ */
+function parseBundlerFromUrl(url: string | null): string | null {
+	if (!url) {
+		return null;
+	}
+
+	try {
+		// Handle custom scheme URLs by replacing scheme with http for URL parsing
+		// e.g., myapp://dev?bundler=... -> http://dev?bundler=...
+		const normalizedUrl = url.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "http://");
+		const parsed = new URL(normalizedUrl);
+
+		// Check if this is a dev deep link
+		const pathname = parsed.hostname + parsed.pathname;
+		if (!pathname.includes("dev")) {
+			return null;
+		}
+
+		// Get bundler param
+		const bundler = parsed.searchParams.get("bundler");
+		if (bundler) {
+			return decodeURIComponent(bundler);
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Return type for the hook
+ */
+export interface UseDeepLinkBundlerReturn {
+	/** Bundler URL from deep link, if present */
+	bundlerUrl: string | null;
+	/** Whether initial URL has been checked */
+	isReady: boolean;
+	/** Clear the bundler URL (e.g., after connecting) */
+	clear: () => void;
+}
+
+/**
+ * Hook to get bundler URL from deep link
+ *
+ * Listens for the initial URL when the app launches and subsequent
+ * URL events to extract the bundler parameter from dev deep links.
+ *
+ * @returns Object with bundlerUrl and ready state
+ *
+ * @example
+ * ```tsx
+ * function MyApp() {
+ *   const { bundlerUrl, isReady } = useDeepLinkBundler();
+ *
+ *   useEffect(() => {
+ *     if (bundlerUrl) {
+ *       console.log('Bundler URL from deep link:', bundlerUrl);
+ *     }
+ *   }, [bundlerUrl]);
+ *
+ *   if (!isReady) {
+ *     return null; // Wait for initial URL check
+ *   }
+ *
+ *   return <App />;
+ * }
+ * ```
+ */
+export function useDeepLinkBundler(): UseDeepLinkBundlerReturn {
+	const [bundlerUrl, setBundlerUrl] = useState<string | null>(null);
+	const [isReady, setIsReady] = useState(false);
+
+	// Clear the bundler URL
+	const clear = useCallback(() => {
+		setBundlerUrl(null);
+	}, []);
+
+	// Check initial URL when app launches
+	useEffect(() => {
+		let mounted = true;
+
+		const checkInitialUrl = async () => {
+			try {
+				const initialUrl = await Linking.getInitialURL();
+				if (mounted) {
+					const parsed = parseBundlerFromUrl(initialUrl);
+					if (parsed) {
+						setBundlerUrl(parsed);
+					}
+					setIsReady(true);
+				}
+			} catch (error) {
+				if (mounted) {
+					setIsReady(true);
+				}
+			}
+		};
+
+		checkInitialUrl();
+
+		return () => {
+			mounted = false;
+		};
+	}, []);
+
+	// Listen for URL events (when app is already open)
+	useEffect(() => {
+		const handleUrl = (event: { url: string }) => {
+			const parsed = parseBundlerFromUrl(event.url);
+			if (parsed) {
+				setBundlerUrl(parsed);
+			}
+		};
+
+		const subscription = Linking.addEventListener("url", handleUrl);
+
+		return () => {
+			subscription.remove();
+		};
+	}, []);
+
+	return {
+		bundlerUrl,
+		isReady,
+		clear,
+	};
+}

package/src/index.ts

@@ -2,10 +2,11 @@
  * @teardown/dev-client
  *
  * React Native development client for Teardown applications.
- * Provides dev menu, splash screen, and error overlay functionality.
+ * Provides dev menu, splash screen, bundler waiting overlay, and error overlay functionality.
  */
 
 // Components
+export { BundlerWaitingOverlay, type BundlerWaitingOverlayProps } from "./components/bundler-waiting";
 export { DevMenu, type DevMenuProps } from "./components/dev-menu";
 export { ErrorOverlay, type ErrorOverlayProps } from "./components/error-overlay";
 export { SplashScreen, type SplashScreenProps } from "./components/splash-screen";
@@ -23,6 +24,10 @@ export {
 	type UseBundlerStatusOptions,
 	useBundlerStatus,
 } from "./hooks/use-bundler-status";
+export {
+	type UseDeepLinkBundlerReturn,
+	useDeepLinkBundler,
+} from "./hooks/use-deep-link-bundler";
 export {
 	createInitialDevMenuState,
 	getDefaultMenuItems,