VolvoxCommunity · BillChirico · Dec 9, 2025 · Dec 8, 2025 · Dec 8, 2025 · Dec 8, 2025
diff --git a/__mocks__/expoRouterHead.js b/__mocks__/expoRouterHead.js
@@ -0,0 +1,20 @@
+/**
+ * Mock for expo-router/head module to prevent ESM parsing errors in Jest tests.
+ * This provides a simple passthrough component that renders children.
+ */
+
+const React = require('react');
+
+/**
+ * Renders the provided children inside a React Fragment.
+ * @param {object} props - Component props.
+ * @param {import('react').ReactNode} props.children - Elements to render inside the fragment.
+ * @returns {import('react').ReactElement} A React Fragment containing the given children.
+ */
+function Head({ children }) {
+  return React.createElement(React.Fragment, null, children);
+}
+
+module.exports = Head;
+module.exports.default = Head;
+module.exports.__esModule = true;
diff --git a/__tests__/lib/analytics.web.test.ts b/__tests__/lib/analytics.web.test.ts
@@ -20,6 +20,7 @@ import {
   setUserPropertiesPlatform as setUserPropertiesWeb,
   trackScreenViewPlatform as trackScreenViewWeb,
   resetAnalyticsPlatform as resetAnalyticsWeb,
+  __resetForTesting,
 } from '@/lib/analytics/platform.web';
 
 const mockLoggerWarn = jest.fn();
@@ -62,6 +63,8 @@ jest.mock('firebase/analytics', () => ({
 
 describe('Web Analytics', () => {
   beforeEach(() => {
+    // Reset module state to allow re-initialization between tests
+    __resetForTesting();
     jest.clearAllMocks();
     (getApps as jest.Mock).mockReturnValue([]);
     (isSupported as jest.Mock).mockResolvedValue(true);

diff --git a/app/_layout.tsx b/app/_layout.tsx
@@ -28,6 +28,7 @@ import {
   useNavigationContainerRef,
   useRootNavigationState,
 } from 'expo-router';
+import Head from 'expo-router/head';
 import { StatusBar } from 'expo-status-bar';
 import { useFrameworkReady } from '@/hooks/useFrameworkReady';
 import { AuthProvider, useAuth } from '@/contexts/AuthContext';
@@ -133,6 +134,26 @@ function RootLayoutNav() {
 
   return (
     <>
+      <Head>
+        <title>Sobriety Waypoint</title>
+        <meta name="description" content="Your companion on the journey to recovery" />
+
+        {/* Open Graph / Facebook */}
+        <meta property="og:type" content="website" />
+        <meta property="og:title" content="Sobriety Waypoint" />
+        <meta property="og:description" content="Your companion on the journey to recovery" />
+        <meta property="og:site_name" content="Sobriety Waypoint" />
+        <meta property="og:image" content="https://sobrietywaypoint.com/assets/images/banner.png" />
+
+        {/* Twitter */}
+        <meta name="twitter:card" content="summary_large_image" />
+        <meta name="twitter:title" content="Sobriety Waypoint" />
+        <meta name="twitter:description" content="Your companion on the journey to recovery" />
+        <meta
+          name="twitter:image"
+          content="https://sobrietywaypoint.com/assets/images/banner.png"
+        />
+      </Head>
       <Stack screenOptions={{ headerShown: false }}>
         <Stack.Screen name="login" />
         <Stack.Screen name="signup" />

diff --git a/assets/images/banner.png b/assets/images/banner.png
diff --git a/jest.config.js b/jest.config.js
@@ -4,7 +4,7 @@ module.exports = {
     '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
   },
   transformIgnorePatterns: [
-    'node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|@sentry|native-base|react-native-svg|lucide-react-native|@supabase)',
+    'node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|expo-router|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|@sentry|native-base|react-native-svg|lucide-react-native|@supabase)',
   ],
   setupFiles: ['<rootDir>/jest.setup.js'],
   testMatch: ['**/__tests__/**/*.(spec|test).[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
@@ -22,6 +22,8 @@ module.exports = {
     '\\.(jpg|jpeg|png|gif|svg)$': '<rootDir>/__mocks__/fileMock.js',
     // Mock expo virtual modules to prevent ESM parsing errors
     '^expo/virtual/(.*)$': '<rootDir>/__mocks__/expoVirtualMock.js',
+    // Mock expo-router/head to prevent ESM parsing errors
+    '^expo-router/head$': '<rootDir>/__mocks__/expoRouterHead.js',
   },
   collectCoverageFrom: [
     'app/**/*.{ts,tsx}',

diff --git a/lib/analytics/index.ts b/lib/analytics/index.ts
@@ -43,6 +43,15 @@ import {
 export { AnalyticsEvents, type AnalyticsEventName } from '@/types/analytics';
 export { calculateDaysSoberBucket } from '@/lib/analytics-utils';
 
+// =============================================================================
+// Module State
+// =============================================================================
+/**
+ * Guard flag to prevent multiple initialization attempts at the index level.
+ * This provides defense-in-depth against hot reload and React Strict Mode double-invocations.
+ */
+let isInitialized = false;
+
 /**
  * Initialize Firebase Analytics for the app.
  *
@@ -58,6 +67,16 @@ export { calculateDaysSoberBucket } from '@/lib/analytics-utils';
  * ```
  */
 export async function initializeAnalytics(): Promise<void> {
+  // Defense-in-depth: prevent re-initialization at the public API level
+  if (isInitialized) {
+    if (isDebugMode()) {
+      logger.debug('Analytics already initialized, skipping', {
+        category: LogCategory.ANALYTICS,
+      });
+    }
+    return;
+  }
+
   if (!shouldInitializeAnalytics()) {
     if (isDebugMode()) {
       logger.warn('Firebase not configured - analytics disabled', {
@@ -67,6 +86,9 @@ export async function initializeAnalytics(): Promise<void> {
     return;
   }
 
+  // Mark as initialized before async operations to prevent race conditions
+  isInitialized = true;
+
   // On native, Firebase reads config from GoogleService-Info.plist / google-services.json
   // On web, we need explicit configuration via environment variables
   const config: AnalyticsConfig = {
@@ -87,7 +109,16 @@ export async function initializeAnalytics(): Promise<void> {
     });
   }
 
-  await initializePlatformAnalytics(config);
+  try {
+    await initializePlatformAnalytics(config);
+  } catch (error) {
+    // Reset flag to allow retry on critical failures
+    isInitialized = false;
+    const err = error instanceof Error ? error : new Error(String(error));
+    logger.error('Failed to initialize analytics platform', err, {
+      category: LogCategory.ANALYTICS,
+    });
+  }
 }
 
 /**
@@ -156,27 +187,24 @@ export function setUserProperties(properties: UserProperties): void {
 }
 
 /**
- * Tracks a screen view event.
- *
- * This is typically called automatically by navigation tracking,
- * but can be called manually for non-standard screens.
+ * Record a screen view for analytics.
  *
- * @param screenName - The name of the screen
- * @param screenClass - Optional screen class name
+ * Typically invoked automatically by navigation tracking; call manually for non-standard or ephemeral screens.
  *
- * @example
- * ```ts
- * trackScreenView('HomeScreen', 'TabScreen');
- * ```
+ * @param screenName - The logical name of the screen (e.g., "Home", "Settings")
+ * @param screenClass - Optional class or category of the screen (e.g., "TabScreen")
  */
 export function trackScreenView(screenName: string, screenClass?: string): void {
   trackScreenViewPlatform(screenName, screenClass);
 }
 
 /**
- * Reset analytics state for the current user.
+ * Resets analytics state for the current user.
  *
  * Clears the analytics user identifier and any user-specific analytics data.
+ *
+ * Note: This does NOT reset the analytics initialization state (`isInitialized` flag).
+ * Analytics initialization persists after reset.
  */
 export async function resetAnalytics(): Promise<void> {
   await resetAnalyticsPlatform();

diff --git a/lib/analytics/platform.native.ts b/lib/analytics/platform.native.ts
@@ -50,10 +50,9 @@ function getAnalyticsInstance(): ReturnType<typeof getAnalytics> | null {
 }
 
 /**
- * Initialize Firebase Analytics for native platforms.
+ * Initializes Firebase Analytics for native platforms using the bundled native configuration.
  *
- * On iOS and Android the native Firebase configuration files are used; the
- * optional `config` argument is ignored by the native implementation.
+ * The optional `_config` argument is ignored on iOS and Android.
  *
  * @param _config - Optional analytics configuration; ignored on native platforms
  */
@@ -145,10 +144,10 @@ function hashUserIdForLogging(input: string | null): string | null {
 }
 
 /**
- * Sets the user ID for analytics.
+ * Set the analytics user ID for the current session.
  *
- * This function is synchronous (fire-and-forget) to match the public API in index.ts.
- * Errors are caught and logged but not propagated to avoid unhandled promise rejections.
+ * Passing `null` clears the current user ID. Errors encountered while setting the ID
+ * are caught and logged and will not be propagated.
  *
  * @param userId - The user ID to set, or `null` to clear the current user ID
  */
@@ -213,15 +212,13 @@ function sanitizeUserPropertiesForLogging(
 }
 
 /**
- * Sets user properties for analytics.
- *
- * This function is synchronous (fire-and-forget) to match the public API in index.ts.
- * Errors are caught and logged but not propagated to avoid unhandled promise rejections.
+ * Set analytics user properties for the native platform.
  *
- * Firebase requires user properties to be string or null. Boolean values are
- * converted to strings ('true'/'false') to preserve semantic meaning.
+ * Accepts an object mapping property names to values; `null` clears a property and `undefined` entries are ignored.
+ * Boolean values are converted to the strings `'true'` or `'false'` to meet Firebase requirements; other non-null values are converted to strings.
+ * Errors from the underlying analytics call are logged and not rethrown.
  *
- * @param properties - Object mapping property names to string values; use `null` to clear a property
+ * @param properties - Mapping of user property names to string, boolean, `null`, or `undefined` values
  */
 export function setUserPropertiesPlatform(properties: UserProperties): void {
   if (isDebugMode()) {
@@ -255,13 +252,9 @@ export function setUserPropertiesPlatform(properties: UserProperties): void {
 }
 
 /**
- * Tracks a screen view event.
+ * Record a screen view in analytics.
  *
- * Uses logEvent with 'screen_view' instead of the dedicated logScreenView function
- * to avoid deprecation warnings in React Native Firebase v22+.
- *
- * This function is synchronous (fire-and-forget) to match the public API in index.ts.
- * Errors are caught and logged but not propagated to avoid unhandled promise rejections.
+ * This is a fire-and-forget call: it enqueues a 'screen_view' event and catches/logs any errors without throwing.
  *
  * @param screenName - The displayed name of the screen to record
  * @param screenClass - Optional screen class; defaults to `screenName` when omitted
@@ -295,7 +288,9 @@ export function trackScreenViewPlatform(screenName: string, screenClass?: string
 }
 
 /**
- * Clear analytics state and stored analytics data (commonly used on user logout).
+ * Clear the native Firebase Analytics instance state and stored analytics data, typically used on user logout.
+ *
+ * If Firebase Analytics is unavailable, logs a warning and returns without error. Any errors encountered while resetting are logged and not rethrown.
  */
 export async function resetAnalyticsPlatform(): Promise<void> {
   try {

diff --git a/lib/analytics/platform.ts b/lib/analytics/platform.ts
@@ -12,11 +12,9 @@ import type { EventParams, UserProperties, AnalyticsConfig } from '@/types/analy
 import { logger, LogCategory } from '@/lib/logger';
 
 /**
- * Provide a fallback analytics initializer for unsupported platforms.
+ * Logs a warning that the fallback analytics implementation is active on unsupported platforms.
  *
- * Logs a warning that the fallback implementation is in use and performs no analytics initialization.
- *
- * @param _config - Optional analytics configuration; this implementation ignores the value
+ * @param _config - Optional analytics configuration; ignored by the fallback implementation
  */
 export async function initializePlatformAnalytics(_config?: AnalyticsConfig): Promise<void> {
   logger.warn('Analytics: Using fallback implementation (platform not supported)', {

diff --git a/lib/analytics/platform.web.ts b/lib/analytics/platform.web.ts
@@ -73,6 +73,12 @@ let analytics: Analytics | null = null;
 let app: FirebaseApp | null = null;
 let vercelAnalytics: VercelAnalytics | null = null;
 
+/**
+ * Guard flag to prevent multiple initialization attempts.
+ * This prevents duplicate Firebase connections during hot reload or React Strict Mode.
+ */
+let isInitialized = false;
+
 // =============================================================================
 // Constants (continued)
 // =============================================================================
@@ -335,25 +341,31 @@ function dispatchEvent(eventName: string, params?: EventParams): void {
 // Main Logic
 // =============================================================================
 /**
- * Initializes analytics providers for web.
+ * Initialize configured analytics providers for the web platform.
  *
- * Initializes Firebase Analytics and/or Vercel Analytics based on configuration.
- * Firebase requires explicit configuration; Vercel Analytics auto-detects if installed.
+ * This function is idempotent: once initialized, subsequent calls are no-ops.
+ * If Firebase analytics is enabled, `config` must contain the Firebase app settings.
  *
- * @param config - Firebase configuration (required if Firebase is enabled)
- * @returns Promise that resolves when initialization is complete
- *
- * @example
- * ```ts
- * await initializePlatformAnalytics({
- *   apiKey: 'your-api-key',
- *   projectId: 'your-project',
- *   appId: 'your-app-id',
- *   measurementId: 'G-XXXXXXXXXX'
- * });
- * ```
+ * @param config - Firebase configuration required when Firebase analytics is enabled.
+ *   If Firebase is enabled but config is missing or invalid (empty apiKey, projectId, or appId),
+ *   Firebase initialization will fail silently and be logged. Subsequent analytics calls
+ *   will be no-ops until the next successful initialization (requires page reload or
+ *   calling `__resetForTesting()` in tests).
  */
 export async function initializePlatformAnalytics(config: AnalyticsConfig): Promise<void> {
+  // Guard against multiple initialization attempts (hot reload, React Strict Mode, etc.)
+  if (isInitialized) {
+    if (isDebugMode()) {
+      logger.debug('Analytics already initialized, skipping re-initialization', {
+        category: LogCategory.ANALYTICS,
+      });
+    }
+    return;
+  }
+
+  // Mark as initialized immediately to prevent race conditions
+  isInitialized = true;
+
   // Initialize Firebase if enabled
   if (IS_FIREBASE_ENABLED) {
     try {
@@ -392,11 +404,14 @@ export async function initializePlatformAnalytics(config: AnalyticsConfig): Prom
         }
       }
     } catch (error) {
+      // Reset flag to allow retry on critical failures
+      isInitialized = false;
       logger.error(
         'Failed to initialize Firebase Analytics',
         error instanceof Error ? error : new Error(String(error)),
         { category: LogCategory.ANALYTICS }
       );
+      return;
     }
   }
 
@@ -554,10 +569,9 @@ export function trackScreenViewPlatform(screenName: string, screenClass?: string
 }
 
 /**
- * Resets analytics for logout.
+ * Reset analytics state for the current user.
  *
- * Clears user ID and user properties in Firebase Analytics.
- * Vercel Analytics does not support reset operations.
+ * Clears the Firebase Analytics user ID and user properties. No-op for Vercel Analytics because it does not expose a reset API.
  */
 export async function resetAnalyticsPlatform(): Promise<void> {
   if (isDebugMode()) {
@@ -567,6 +581,27 @@ export async function resetAnalyticsPlatform(): Promise<void> {
   setUserIdPlatform(null);
 }
 
+// =============================================================================
+// Testing Utilities
+// =============================================================================
+/**
+ * Reset the module's analytics initialization state for tests.
+ *
+ * Clears the internal initialization guard and removes stored Firebase and Vercel analytics instances so the module can be re-initialized in a test.
+ *
+ * @throws Will throw an Error if called when NODE_ENV is not 'test'.
+ * @internal
+ */
+export function __resetForTesting(): void {
+  if (process.env.NODE_ENV !== 'test') {
+    throw new Error('__resetForTesting should only be called in test environments');
+  }
+  isInitialized = false;
+  analytics = null;
+  app = null;
+  vercelAnalytics = null;
+}
+
 // =============================================================================
 // Exports
 // =============================================================================