@umituz/react-native-ai-fal-provider 3.2.30 → 3.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-fal-provider",
-  "version": "3.2.30",
+  "version": "3.2.32",
   "description": "FAL AI provider for React Native - implements IAIProvider interface for unified AI generation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/infrastructure/services/fal-provider-subscription.ts

@@ -1,6 +1,12 @@
 /**
  * FAL Provider Subscription Handlers
- * Handles subscribe, run methods and cancellation logic
+ * Handles subscribe, run methods with retry, timeout, and cancellation
+ *
+ * Retry strategy for subscribe:
+ * - Retries on: network errors, timeouts, server errors (5xx)
+ * - NO retry on: auth, validation, NSFW, quota, user cancellation
+ * - Max 1 retry (2 total attempts) with 3s delay
+ * - Upload results are preserved (images already on CDN)
  */
 
 import { fal, ApiError, ValidationError } from "@fal-ai/client";
@@ -10,12 +16,12 @@ import { mapFalStatusToJobStatus } from "./fal-status-mapper";
 import { validateNSFWContent } from "../validators/nsfw-validator";
 import { NSFWContentError } from "./nsfw-content-error";
 import { isBase64DataUri } from "../utils/validators/data-uri-validator.util";
+import { generationLogCollector } from "../utils/log-collector";
+
+const TAG = 'fal-subscription';
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
 
-/**
- * Validate that FAL response images contain HTTPS URLs, never base64 data URIs.
- * FAL models should always return CDN URLs. If base64 is returned, it means the model
- * was called with sync_mode:true or wrong parameters. Throw an explicit error to catch early.
- */
 function validateNoBase64InResponse(data: unknown): void {
   if (!data || typeof data !== "object") return;
   const record = data as Record<string, unknown>;
@@ -41,10 +47,6 @@ function validateNoBase64InResponse(data: unknown): void {
   }
 }
 
-/**
- * Unwrap fal.subscribe / fal.run Result<T> = { data: T, requestId: string }
- * Throws if response format is unexpected - no silent fallbacks
- */
 function unwrapFalResult<T>(rawResult: unknown): { data: T; requestId: string } {
   if (!rawResult || typeof rawResult !== "object") {
     throw new Error(
@@ -69,10 +71,6 @@ function unwrapFalResult<T>(rawResult: unknown): { data: T; requestId: string }
   return { data: result.data as T, requestId: result.requestId };
 }
 
-/**
- * Format fal-ai SDK errors into user-readable messages
- * Uses proper @fal-ai/client error types (ApiError, ValidationError)
- */
 function formatFalError(error: unknown): string {
   if (error instanceof ValidationError) {
     const details = error.fieldErrors;
@@ -83,7 +81,6 @@ function formatFalError(error: unknown): string {
   }
 
   if (error instanceof ApiError) {
-    // ApiError has .status, .body, .message
     if (error.status === 401 || error.status === 403) {
       return "Authentication failed. Please check your API key.";
     }
@@ -103,23 +100,57 @@ function formatFalError(error: unknown): string {
   return String(error);
 }
 
+// ─── Retry Logic ────────────────────────────────────────────────────────────
+
 /**
- * Handle FAL subscription with timeout and cancellation
+ * Determine if a subscribe error is retryable.
+ *
+ * Retryable:  network, timeout, server errors (500-504)
+ * NOT:        auth (401/403), validation (400/422), quota (402),
+ *             NSFW, user cancellation, rate limit (429 — FAL SDK already retries)
  */
-export async function handleFalSubscription<T = unknown>(
-  model: string,
-  input: Record<string, unknown>,
-  options?: SubscribeOptions<T>,
-  signal?: AbortSignal
-): Promise<{ result: T; requestId: string }> {
-  const timeoutMs = options?.timeoutMs ?? DEFAULT_FAL_CONFIG.defaultTimeoutMs;
+function isRetryableSubscribeError(error: unknown): boolean {
+  // Never retry NSFW
+  if (error instanceof NSFWContentError) return false;
 
-  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 3600000) {
-    throw new Error(
-      `Invalid timeout: ${timeoutMs}ms. Must be a positive integer between 1 and 3600000ms (1 hour)`
-    );
+  // Never retry user cancellation
+  if (error instanceof Error && error.message.includes("cancelled by user")) return false;
+
+  // ApiError — check status code
+  if (error instanceof ApiError) {
+    const status = error.status;
+    // 5xx server errors are retryable
+    if (status >= 500 && status <= 504) return true;
+    // Everything else (4xx) is not
+    return false;
   }
 
+  // ValidationError is never retryable
+  if (error instanceof ValidationError) return false;
+
+  // Generic Error — check message patterns
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    if (msg.includes("network")) return true;
+    if (msg.includes("timeout") || msg.includes("timed out")) return true;
+    if (msg.includes("fetch")) return true;
+    if (msg.includes("econnrefused") || msg.includes("enotfound")) return true;
+  }
+
+  return false;
+}
+
+// ─── Single Subscribe Attempt ───────────────────────────────────────────────
+
+async function singleSubscribeAttempt<T = unknown>(
+  model: string,
+  input: Record<string, unknown>,
+  options: SubscribeOptions<T> | undefined,
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+  attemptStart: number,
+  sessionId: string,
+): Promise<{ result: T; requestId: string }> {
   let timeoutId: ReturnType<typeof setTimeout> | null = null;
   let abortHandler: (() => void) | null = null;
   let listenerAdded = false;
@@ -146,9 +177,8 @@ export async function handleFalSubscription<T = unknown>(
           const statusWithPosition = `${jobStatus.status}:${jobStatus.queuePosition ?? ""}`;
           if (statusWithPosition !== lastStatus) {
             lastStatus = statusWithPosition;
-            if (typeof __DEV__ !== "undefined" && __DEV__) {
-              console.log(`[fal-provider] Job Status Update: ${jobStatus.status}${jobStatus.queuePosition ? ` (Position: ${jobStatus.queuePosition})` : ""}`);
-            }
+            const elapsed = Date.now() - attemptStart;
+            generationLogCollector.log(sessionId, TAG, `[${elapsed}ms] Queue: ${jobStatus.status}${jobStatus.queuePosition ? ` (pos: ${jobStatus.queuePosition})` : ""}`);
             if (options?.onProgress) {
               if (jobStatus.status === "IN_QUEUE" || jobStatus.status === "IN_PROGRESS") {
                 options.onProgress({ progress: -1, status: jobStatus.status });
@@ -176,7 +206,6 @@ export async function handleFalSubscription<T = unknown>(
         listenerAdded = true;
       });
       promises.push(abortPromise);
-      // Check after listener is attached to close the race window
       if (signal.aborted) {
         throw new Error("Request cancelled by user");
       }
@@ -185,42 +214,123 @@ export async function handleFalSubscription<T = unknown>(
     const rawResult = await Promise.race(promises);
     const { data, requestId } = unwrapFalResult<T>(rawResult);
 
-    // Validate response for base64 data URIs
-    // Since we use subscribe, we should always get CDN URLs, not base64 data URIs
     validateNoBase64InResponse(data);
     validateNSFWContent(data as Record<string, unknown>);
 
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.log(`[fal-provider] Subscription completed successfully. Request ID: ${requestId}`);
-    }
-
     options?.onResult?.(data);
     return { result: data, requestId };
-  } catch (error) {
-    if (error instanceof NSFWContentError) {
-      throw error;
-    }
-
-    const message = formatFalError(error);
-    throw new Error(message);
   } finally {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
+    if (timeoutId) clearTimeout(timeoutId);
     if (listenerAdded && abortHandler && signal) {
       signal.removeEventListener("abort", abortHandler);
     }
   }
 }
 
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Handle FAL subscription with timeout, cancellation, and retry.
+ *
+ * Retry is safe here because:
+ * - Input is already preprocessed (images uploaded to FAL CDN)
+ * - fal.subscribe is idempotent (same input → same generation)
+ * - Only retries on transient errors (network/timeout/5xx)
+ */
+export async function handleFalSubscription<T = unknown>(
+  model: string,
+  input: Record<string, unknown>,
+  sessionId: string,
+  options?: SubscribeOptions<T>,
+  signal?: AbortSignal,
+): Promise<{ result: T; requestId: string }> {
+  const overallStart = Date.now();
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_FAL_CONFIG.defaultTimeoutMs;
+  const maxRetries = DEFAULT_FAL_CONFIG.subscribeMaxRetries;
+  const retryDelay = DEFAULT_FAL_CONFIG.subscribeRetryDelayMs;
+
+  generationLogCollector.log(sessionId, TAG, `Starting subscription for model: ${model}`, {
+    timeoutMs,
+    maxRetries,
+    inputKeys: Object.keys(input),
+  });
+
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 3600000) {
+    throw new Error(
+      `Invalid timeout: ${timeoutMs}ms. Must be a positive integer between 1 and 3600000ms (1 hour)`
+    );
+  }
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const attemptStart = Date.now();
+
+    if (attempt > 0) {
+      generationLogCollector.warn(sessionId, TAG, `Retry ${attempt}/${maxRetries} after ${retryDelay}ms delay...`);
+      await new Promise(resolve => setTimeout(resolve, retryDelay));
+
+      // Check if cancelled during delay
+      if (signal?.aborted) {
+        throw new Error("Request cancelled by user");
+      }
+    }
+
+    try {
+      generationLogCollector.log(sessionId, TAG, `Attempt ${attempt + 1}/${maxRetries + 1} starting...`);
+
+      const result = await singleSubscribeAttempt<T>(
+        model, input, options, signal, timeoutMs, attemptStart, sessionId,
+      );
+
+      const totalElapsed = Date.now() - overallStart;
+      const suffix = attempt > 0 ? ` (succeeded on retry ${attempt})` : '';
+      generationLogCollector.log(sessionId, TAG, `Subscription completed in ${totalElapsed}ms${suffix}. Request ID: ${result.requestId}`);
+
+      return result;
+    } catch (error) {
+      lastError = error;
+      const attemptElapsed = Date.now() - attemptStart;
+
+      // NSFW errors never retry — re-throw immediately
+      if (error instanceof NSFWContentError) {
+        generationLogCollector.warn(sessionId, TAG, `NSFW content detected after ${attemptElapsed}ms`);
+        throw error;
+      }
+
+      const message = formatFalError(error);
+
+      // Check if retryable and we have attempts left
+      if (attempt < maxRetries && isRetryableSubscribeError(error)) {
+        generationLogCollector.warn(sessionId, TAG, `Attempt ${attempt + 1} failed after ${attemptElapsed}ms (retryable): ${message}`);
+        continue;
+      }
+
+      // Not retryable or no retries left
+      const totalElapsed = Date.now() - overallStart;
+      const retryInfo = attempt > 0 ? ` after ${attempt + 1} attempts` : '';
+      generationLogCollector.error(sessionId, TAG, `Subscription FAILED in ${totalElapsed}ms${retryInfo}: ${message}`);
+      throw new Error(message);
+    }
+  }
+
+  // Should never reach here, but TypeScript needs it
+  throw lastError;
+}
+
 /**
- * Handle FAL run with NSFW validation
+ * Handle FAL run with NSFW validation (no retry — runs are fast/synchronous)
  */
 export async function handleFalRun<T = unknown>(
   model: string,
   input: Record<string, unknown>,
-  options?: RunOptions
+  sessionId: string,
+  options?: RunOptions,
 ): Promise<T> {
+  const runTag = 'fal-run';
+  const startTime = Date.now();
+  generationLogCollector.log(sessionId, runTag, `Starting run for model: ${model}`);
+
   options?.onProgress?.({ progress: -1, status: "IN_PROGRESS" as const });
 
   try {
@@ -230,14 +340,21 @@ export async function handleFalRun<T = unknown>(
     validateNoBase64InResponse(data);
     validateNSFWContent(data as Record<string, unknown>);
 
+    const elapsed = Date.now() - startTime;
+    generationLogCollector.log(sessionId, runTag, `Run completed in ${elapsed}ms`);
+
     options?.onProgress?.({ progress: 100, status: "COMPLETED" as const });
     return data;
   } catch (error) {
+    const elapsed = Date.now() - startTime;
+
     if (error instanceof NSFWContentError) {
+      generationLogCollector.warn(sessionId, runTag, `NSFW content detected after ${elapsed}ms`);
       throw error;
     }
 
     const message = formatFalError(error);
+    generationLogCollector.error(sessionId, runTag, `Run FAILED after ${elapsed}ms for model ${model}: ${message}`);
     throw new Error(message);
   }
 }

package/src/infrastructure/services/fal-provider.constants.ts

@@ -1,16 +1,52 @@
 /**
  * FAL Provider Constants
  * Configuration and capability definitions for FAL AI provider
+ *
+ * Retry Strategy (layered):
+ * ┌──────────────────────────────────────────────────┐
+ * │ UPLOAD (fal.storage.upload) — per image          │
+ * │ Timeout: 30s / attempt                           │
+ * │ Retries: 2 (3 total attempts)                    │
+ * │ Backoff: 1s → 2s (exponential)                   │
+ * │ Retries on: network, timeout                     │
+ * ├──────────────────────────────────────────────────┤
+ * │ SUBSCRIBE (fal.subscribe) — generation           │
+ * │ Timeout: caller-defined (120s image / 300s video)│
+ * │ Retries: 1 (2 total attempts)                    │
+ * │ Backoff: 3s (fixed — server needs recovery time) │
+ * │ Retries on: network, timeout, server (5xx)       │
+ * │ NO retry: auth, validation, NSFW, quota, cancel  │
+ * ├──────────────────────────────────────────────────┤
+ * │ FAL SDK HTTP retry (fal.config)                  │
+ * │ Retries: 3 (internal HTTP-level only)            │
+ * │ Backoff: 1s → 10s                                │
+ * └──────────────────────────────────────────────────┘
  */
 
 import type { ProviderCapabilities } from "../../domain/types";
 
 export const DEFAULT_FAL_CONFIG = {
+  /** FAL SDK HTTP-level retry */
   maxRetries: 3,
   baseDelay: 1000,
   maxDelay: 10000,
+
+  /** Subscribe defaults */
   defaultTimeoutMs: 300000,
   pollInterval: 2500,
+
+  /** Subscribe retry — retries the entire fal.subscribe call on transient failures */
+  subscribeMaxRetries: 1,
+  subscribeRetryDelayMs: 3000,
+} as const;
+
+export const UPLOAD_CONFIG = {
+  /** Timeout per individual upload attempt */
+  timeoutMs: 30_000,
+  /** Max retries (2 = 3 total attempts) */
+  maxRetries: 2,
+  /** Initial backoff delay (doubles each retry) */
+  baseDelayMs: 1_000,
 } as const;
 
 export const FAL_CAPABILITIES: ProviderCapabilities = {

package/src/infrastructure/services/fal-provider.ts

@@ -1,5 +1,6 @@
 /**
  * FAL Provider - Implements IAIProvider interface
+ * Each subscribe/run call creates an isolated log session via sessionId.
  */
 
 import { fal } from "@fal-ai/client";
@@ -11,6 +12,8 @@ import type {
 import { DEFAULT_FAL_CONFIG, FAL_CAPABILITIES } from "./fal-provider.constants";
 import { handleFalSubscription, handleFalRun } from "./fal-provider-subscription";
 import { preprocessInput } from "../utils";
+import { generationLogCollector } from "../utils/log-collector";
+import type { LogEntry } from "../utils/log-collector";
 import {
   createRequestKey, getExistingRequest, storeRequest,
   removeRequest, cancelRequest, cancelAllRequests, hasActiveRequests,
@@ -25,6 +28,8 @@ export class FalProvider implements IAIProvider {
   private apiKey: string | null = null;
   private initialized = false;
   private lastRequestKey: string | null = null;
+  /** Tracks the active sessionId so callers can retrieve logs */
+  private activeSessionId: string | null = null;
 
   initialize(config: AIProviderConfig): void {
     this.apiKey = config.apiKey;
@@ -74,7 +79,10 @@ export class FalProvider implements IAIProvider {
   async submitJob(model: string, input: Record<string, unknown>): Promise<JobSubmission> {
     this.validateInit();
     validateInput(model, input);
-    const processedInput = await preprocessInput(input);
+    const sessionId = generationLogCollector.startSession();
+    this.activeSessionId = sessionId;
+    generationLogCollector.log(sessionId, 'fal-provider', `submitJob() for model: ${model}`);
+    const processedInput = await preprocessInput(input, sessionId);
     return queueOps.submitJob(model, processedInput);
   }
 
@@ -93,14 +101,28 @@ export class FalProvider implements IAIProvider {
     input: Record<string, unknown>,
     options?: SubscribeOptions<T>,
   ): Promise<T> {
+    const TAG = 'fal-provider';
+    const totalStart = Date.now();
     this.validateInit();
     validateInput(model, input);
 
-    const processedInput = await preprocessInput(input);
+    // Start a fresh log session for this generation
+    const sessionId = generationLogCollector.startSession();
+    this.activeSessionId = sessionId;
+    generationLogCollector.log(sessionId, TAG, `subscribe() called for model: ${model}`);
+
+    const preprocessStart = Date.now();
+    const processedInput = await preprocessInput(input, sessionId);
+    const preprocessElapsed = Date.now() - preprocessStart;
+    generationLogCollector.log(sessionId, TAG, `Preprocessing done in ${preprocessElapsed}ms`);
+
     const key = createRequestKey(model, processedInput);
 
     const existing = getExistingRequest<T>(key);
-    if (existing) return existing.promise;
+    if (existing) {
+      generationLogCollector.log(sessionId, TAG, `Dedup hit - returning existing request`);
+      return existing.promise;
+    }
 
     const abortController = new AbortController();
 
@@ -114,19 +136,22 @@ export class FalProvider implements IAIProvider {
     this.lastRequestKey = key;
     storeRequest(key, { promise, abortController, createdAt: Date.now() });
 
-    handleFalSubscription<T>(model, processedInput, options, abortController.signal)
-      .then((res) => resolvePromise(res.result))
-      .catch((error) => rejectPromise(error))
+    handleFalSubscription<T>(model, processedInput, sessionId, options, abortController.signal)
+      .then((res) => {
+        const totalElapsed = Date.now() - totalStart;
+        generationLogCollector.log(sessionId, TAG, `Generation SUCCESS in ${totalElapsed}ms (preprocess: ${preprocessElapsed}ms)`);
+        resolvePromise(res.result);
+      })
+      .catch((error) => {
+        const totalElapsed = Date.now() - totalStart;
+        generationLogCollector.error(sessionId, TAG, `Generation FAILED in ${totalElapsed}ms: ${error instanceof Error ? error.message : String(error)}`);
+        rejectPromise(error);
+      })
       .finally(() => {
         try {
           removeRequest(key);
         } catch (cleanupError) {
-          if (typeof __DEV__ !== "undefined" && __DEV__) {
-            console.error(
-              `[fal-provider] Error removing request: ${key}`,
-              cleanupError instanceof Error ? cleanupError.message : String(cleanupError)
-            );
-          }
+          generationLogCollector.warn(sessionId, TAG, `Error removing request: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
         }
       });
 
@@ -136,25 +161,30 @@ export class FalProvider implements IAIProvider {
   async run<T = unknown>(model: string, input: Record<string, unknown>, options?: RunOptions): Promise<T> {
     this.validateInit();
     validateInput(model, input);
-    const processedInput = await preprocessInput(input);
+
+    const sessionId = generationLogCollector.startSession();
+    this.activeSessionId = sessionId;
+    generationLogCollector.log(sessionId, 'fal-provider', `run() for model: ${model}`);
+
+    const processedInput = await preprocessInput(input, sessionId);
 
     const signal = options?.signal;
     if (signal?.aborted) {
       throw new Error("Request cancelled by user");
     }
 
-    return handleFalRun<T>(model, processedInput, options);
+    return handleFalRun<T>(model, processedInput, sessionId, options);
   }
 
   reset(): void {
     cancelAllRequests();
     this.lastRequestKey = null;
+    this.activeSessionId = null;
     this.apiKey = null;
     this.initialized = false;
   }
 
   cancelCurrentRequest(): void {
-    // Cancel only this provider instance's last request, not all global requests
     if (this.lastRequestKey) {
       cancelRequest(this.lastRequestKey);
       this.lastRequestKey = null;
@@ -164,6 +194,25 @@ export class FalProvider implements IAIProvider {
   hasRunningRequest(): boolean {
     return hasActiveRequests();
   }
+
+  /**
+   * Get all log entries collected during the current/last generation session.
+   * Returns empty array if no active session.
+   */
+  getSessionLogs(): LogEntry[] {
+    if (!this.activeSessionId) return [];
+    return generationLogCollector.getEntries(this.activeSessionId);
+  }
+
+  /**
+   * End the current log session and return all entries. Clears the buffer.
+   */
+  endLogSession(): LogEntry[] {
+    if (!this.activeSessionId) return [];
+    const entries = generationLogCollector.endSession(this.activeSessionId);
+    this.activeSessionId = null;
+    return entries;
+  }
 }
 
 export const falProvider = new FalProvider();

package/src/infrastructure/utils/fal-storage.util.ts

@@ -1,6 +1,7 @@
 /**
  * FAL Storage Utility
  * Handles image uploads to FAL storage (React Native compatible)
+ * Features: timeout protection, retry with exponential backoff, session-scoped logging
  */
 
 import { fal } from "@fal-ai/client";
@@ -9,15 +10,71 @@ import {
   deleteTempFile,
 } from "@umituz/react-native-design-system/filesystem";
 import { getErrorMessage } from './helpers/error-helpers.util';
+import { generationLogCollector } from './log-collector';
+import { UPLOAD_CONFIG } from '../services/fal-provider.constants';
+
+const TAG = 'fal-storage';
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`Upload timeout after ${ms}ms: ${label}`));
+    }, ms);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  sessionId: string,
+  label: string,
+  maxRetries: number = UPLOAD_CONFIG.maxRetries,
+  baseDelay: number = UPLOAD_CONFIG.baseDelayMs,
+): Promise<T> {
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 0) {
+        const delay = baseDelay * Math.pow(2, attempt - 1);
+        generationLogCollector.warn(sessionId, TAG, `Retry ${attempt}/${maxRetries} for ${label} after ${delay}ms`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const errorMsg = getErrorMessage(error);
+      const isTransient =
+        errorMsg.toLowerCase().includes('network') ||
+        errorMsg.includes('timeout') ||
+        errorMsg.includes('timed out') ||
+        errorMsg.includes('ECONNREFUSED') ||
+        errorMsg.includes('ENOTFOUND') ||
+        errorMsg.includes('fetch');
+
+      if (attempt < maxRetries && isTransient) {
+        generationLogCollector.warn(sessionId, TAG, `Attempt ${attempt + 1} failed for ${label}: ${errorMsg}`);
+        continue;
+      }
+      break;
+    }
+  }
+
+  throw lastError;
+}
 
 /**
  * Upload base64 image to FAL storage
- * Uses design system's filesystem utilities for React Native compatibility
  */
-export async function uploadToFalStorage(base64: string): Promise<string> {
-  if (typeof __DEV__ !== "undefined" && __DEV__) {
-    console.log(`[fal-storage] Uploading base64 image to FAL (first 50 chars): ${base64.substring(0, 50)}...`);
-  }
+export async function uploadToFalStorage(base64: string, sessionId: string): Promise<string> {
+  const startTime = Date.now();
+  const sizeKB = Math.round(base64.length / 1024);
+  const actualSizeKB = Math.round(sizeKB * 0.75); // base64 inflates ~33%
+  generationLogCollector.log(sessionId, TAG, `Starting upload (~${actualSizeKB}KB actual)`);
 
   const tempUri = await base64ToTempFile(base64);
 
@@ -26,66 +83,86 @@ export async function uploadToFalStorage(base64: string): Promise<string> {
   }
 
   try {
-    const response = await fetch(tempUri);
-    const blob = await response.blob();
-    const url = await fal.storage.upload(blob);
-    
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.log(`[fal-storage] Successfully uploaded base64 data to FAL. URL: ${url}`);
-    }
+    const url = await withRetry(
+      async () => {
+        const response = await fetch(tempUri);
+        const blob = await response.blob();
+        generationLogCollector.log(sessionId, TAG, `Blob created (${blob.size} bytes), uploading to FAL CDN...`);
+        return withTimeout(
+          fal.storage.upload(blob),
+          UPLOAD_CONFIG.timeoutMs,
+          `image (~${actualSizeKB}KB)`,
+        );
+      },
+      sessionId,
+      'upload',
+    );
 
+    const elapsed = Date.now() - startTime;
+    generationLogCollector.log(sessionId, TAG, `Upload complete in ${elapsed}ms`, { url, actualSizeKB, elapsed });
     return url;
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    generationLogCollector.error(sessionId, TAG, `Upload FAILED after ${elapsed}ms: ${getErrorMessage(error)}`, { actualSizeKB, elapsed });
+    throw error;
   } finally {
     try {
       await deleteTempFile(tempUri);
     } catch (cleanupError) {
-      // Log cleanup errors to prevent disk space leaks
-      console.warn(
-        `[fal-storage] Failed to delete temp file: ${tempUri}`,
-        getErrorMessage(cleanupError)
-      );
-      // Don't throw - cleanup errors shouldn't fail the upload
+      generationLogCollector.warn(sessionId, TAG, `Failed to delete temp file: ${getErrorMessage(cleanupError)}`);
     }
   }
 }
 
 /**
- * Upload a local file (file:// or content:// URI) to FAL storage
- * Directly fetches the file as a blob — no base64 intermediate step
+ * Upload a local file to FAL storage
  */
-export async function uploadLocalFileToFalStorage(fileUri: string): Promise<string> {
-  try {
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.log(`[fal-storage] Starting local file upload to FAL: ${fileUri}`);
-    }
+export async function uploadLocalFileToFalStorage(fileUri: string, sessionId: string): Promise<string> {
+  const startTime = Date.now();
+  generationLogCollector.log(sessionId, TAG, `Starting local file upload: ${fileUri}`);
 
-    const response = await fetch(fileUri);
-    const blob = await response.blob();
-    const url = await fal.storage.upload(blob);
-
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.log(`[fal-storage] Successfully uploaded local file to FAL. URL: ${url}`);
-    }
+  try {
+    const url = await withRetry(
+      async () => {
+        const response = await fetch(fileUri);
+        const blob = await response.blob();
+        generationLogCollector.log(sessionId, TAG, `Local file blob (${blob.size} bytes), uploading...`);
+        return withTimeout(
+          fal.storage.upload(blob),
+          UPLOAD_CONFIG.timeoutMs,
+          `local file`,
+        );
+      },
+      sessionId,
+      'local file upload',
+    );
 
+    const elapsed = Date.now() - startTime;
+    generationLogCollector.log(sessionId, TAG, `Local file upload complete in ${elapsed}ms`, { url, elapsed });
     return url;
   } catch (error) {
-    throw new Error(
-      `Failed to upload local file to FAL storage: ${getErrorMessage(error)}`
-    );
+    const elapsed = Date.now() - startTime;
+    generationLogCollector.error(sessionId, TAG, `Local file upload FAILED after ${elapsed}ms: ${getErrorMessage(error)}`, { elapsed });
+    throw error;
   }
 }
 
 /**
  * Upload multiple images to FAL storage in parallel
- * Uses Promise.allSettled to handle partial failures gracefully
- * @throws {Error} if any upload fails, with details about all failures
- * Note: Successful uploads before the first failure are NOT cleaned up automatically
- * as FAL storage doesn't provide a delete API. Monitor orphaned uploads externally.
  */
 export async function uploadMultipleToFalStorage(
   images: string[],
+  sessionId: string,
 ): Promise<string[]> {
-  const results = await Promise.allSettled(images.map(uploadToFalStorage));
+  const startTime = Date.now();
+  generationLogCollector.log(sessionId, TAG, `Starting batch upload of ${images.length} image(s)`);
+
+  const results = await Promise.allSettled(
+    images.map((img, i) => {
+      generationLogCollector.log(sessionId, TAG, `[${i}/${images.length}] Queuing upload (~${Math.round(img.length * 0.75 / 1024)}KB)`);
+      return uploadToFalStorage(img, sessionId);
+    })
+  );
 
   const successfulUploads: string[] = [];
   const failures: Array<{ index: number; error: unknown }> = [];
@@ -98,27 +175,19 @@ export async function uploadMultipleToFalStorage(
     }
   });
 
-  // If any upload failed, throw detailed error
+  const elapsed = Date.now() - startTime;
+
   if (failures.length > 0) {
     const errorMessage = failures
-      .map(({ index, error }) =>
-        `Image ${index}: ${getErrorMessage(error)}`
-      )
+      .map(({ index, error }) => `Image ${index}: ${getErrorMessage(error)}`)
       .join('; ');
 
-    // Log warning about orphaned uploads
-    if (successfulUploads.length > 0) {
-      console.warn(
-        `[fal-storage] ${successfulUploads.length} upload(s) succeeded before failure. ` +
-        'These files remain in FAL storage and may need manual cleanup:',
-        successfulUploads
-      );
-    }
-
+    generationLogCollector.error(sessionId, TAG, `Batch upload FAILED: ${successfulUploads.length}/${images.length} in ${elapsed}ms`, { elapsed });
     throw new Error(
-      `Failed to upload ${failures.length} of ${images.length} image(s): ${errorMessage}`
+      `Failed to upload ${failures.length} of ${images.length} image(s) (${elapsed}ms): ${errorMessage}`
     );
   }
 
+  generationLogCollector.log(sessionId, TAG, `Batch upload complete: ${images.length}/${images.length} in ${elapsed}ms`, { elapsed });
   return successfulUploads;
 }

package/src/infrastructure/utils/index.ts

@@ -41,6 +41,9 @@ export {
 
 export { preprocessInput } from "./input-preprocessor.util";
 
+export { generationLogCollector } from "./log-collector";
+export type { LogEntry } from "./log-collector";
+
 export { FalGenerationStateManager } from "./fal-generation-state-manager.util";
 export type { GenerationState } from "./fal-generation-state-manager.util";
 

package/src/infrastructure/utils/input-preprocessor.util.ts

@@ -1,183 +1,174 @@
 /**
  * Input Preprocessor Utility
  * Detects and uploads base64/local file images to FAL storage before API calls
+ *
+ * Upload strategy:
+ * - Array fields (image_urls): SEQUENTIAL uploads to avoid bandwidth contention
+ * - Individual fields (image_url, face_image_url): parallel (typically only 1)
  */
 
 import { uploadToFalStorage, uploadLocalFileToFalStorage } from "./fal-storage.util";
 import { getErrorMessage } from './helpers/error-helpers.util';
 import { IMAGE_URL_FIELDS } from './constants/image-fields.constants';
 import { isImageDataUri as isBase64DataUri } from './validators/data-uri-validator.util';
+import { generationLogCollector } from './log-collector';
+
+const TAG = 'preprocessor';
 
-/**
- * Check if a value is a local file URI (file:// or content://)
- */
 function isLocalFileUri(value: unknown): value is string {
   return typeof value === "string" && (
     value.startsWith("file://") || value.startsWith("content://")
   );
 }
 
+/**
+ * Classify a network error into a user-friendly message.
+ * Technical details are preserved in Firestore logs/session subcollection.
+ */
+function classifyUploadError(errorMsg: string): string {
+  const lower = errorMsg.toLowerCase();
+
+  if (lower.includes('timed out') || lower.includes('timeout')) {
+    return 'Photo upload took too long. Please try again on a stronger connection (WiFi recommended).';
+  }
+  if (lower.includes('network request failed') || lower.includes('network') || lower.includes('fetch')) {
+    return 'Photo upload failed due to network issues. Please check your internet connection and try again.';
+  }
+  if (lower.includes('econnrefused') || lower.includes('enotfound')) {
+    return 'Could not reach the upload server. Please check your internet connection and try again.';
+  }
+
+  return errorMsg;
+}
+
 /**
  * Preprocess input by uploading base64/local file images to FAL storage.
  * Also strips sync_mode to prevent base64 data URI responses.
  * Returns input with HTTPS URLs instead of base64/local URIs.
+ *
+ * Array fields are uploaded SEQUENTIALLY to avoid bandwidth contention
+ * on slow mobile connections (prevents simultaneous upload failures).
  */
 export async function preprocessInput(
   input: Record<string, unknown>,
+  sessionId: string,
 ): Promise<Record<string, unknown>> {
-  if (typeof __DEV__ !== "undefined" && __DEV__) {
-    console.log("[preprocessInput] Starting input preprocessing...", {
-      keys: Object.keys(input)
-    });
-  }
+  const startTime = Date.now();
+  const inputKeys = Object.keys(input);
+  generationLogCollector.log(sessionId, TAG, `Starting preprocessing...`, { keys: inputKeys });
 
   const result = { ...input };
   const uploadPromises: Promise<unknown>[] = [];
 
-  // SAFETY: Strip sync_mode to prevent base64 data URI responses
-  // FAL returns base64 when sync_mode:true — we always want CDN URLs
   if ("sync_mode" in result) {
     delete result.sync_mode;
-    if (typeof __DEV__ !== "undefined" && __DEV__) {
-      console.warn(
-        "[preprocessInput] Stripped sync_mode from input. " +
-        "sync_mode:true returns base64 data URIs which break Firestore persistence. " +
-        "Use falProvider.subscribe() for CDN URLs."
-      );
-    }
+    generationLogCollector.warn(sessionId, TAG, `Stripped sync_mode from input`);
   }
 
-  // Handle individual image URL keys
+  // Handle individual image URL keys (parallel — typically only 1 field)
+  let individualUploadCount = 0;
   for (const key of IMAGE_URL_FIELDS) {
     const value = result[key];
 
-    // Upload base64 data URIs to FAL storage
     if (isBase64DataUri(value)) {
-      const uploadPromise = uploadToFalStorage(value)
+      individualUploadCount++;
+      generationLogCollector.log(sessionId, TAG, `Found base64 field: ${key} (${Math.round(String(value).length / 1024)}KB)`);
+      const uploadPromise = uploadToFalStorage(value, sessionId)
         .then((url) => {
           result[key] = url;
           return url;
         })
         .catch((error) => {
           const errorMessage = `Failed to upload ${key}: ${getErrorMessage(error)}`;
-          console.error(`[preprocessInput] ${errorMessage}`);
+          generationLogCollector.error(sessionId, TAG, errorMessage);
           throw new Error(errorMessage);
         });
-
       uploadPromises.push(uploadPromise);
-    }
-    // Upload local file URIs to FAL storage (file://, content://)
-    else if (isLocalFileUri(value)) {
-      const uploadPromise = uploadLocalFileToFalStorage(value)
+    } else if (isLocalFileUri(value)) {
+      individualUploadCount++;
+      generationLogCollector.log(sessionId, TAG, `Found local file field: ${key}`);
+      const uploadPromise = uploadLocalFileToFalStorage(value, sessionId)
         .then((url) => {
           result[key] = url;
           return url;
         })
         .catch((error) => {
           const errorMessage = `Failed to upload local file ${key}: ${getErrorMessage(error)}`;
-          console.error(`[preprocessInput] ${errorMessage}`);
+          generationLogCollector.error(sessionId, TAG, errorMessage);
           throw new Error(errorMessage);
         });
-
       uploadPromises.push(uploadPromise);
     }
   }
 
+  if (individualUploadCount > 0) {
+    generationLogCollector.log(sessionId, TAG, `${individualUploadCount} individual field upload(s) queued`);
+  }
 
-  // Handle image URL arrays (image_urls, input_image_urls, reference_image_urls)
+  // Handle image URL arrays — SEQUENTIAL to avoid bandwidth contention
   for (const arrayField of ["image_urls", "input_image_urls", "reference_image_urls"] as const) {
     if (Array.isArray(result[arrayField]) && (result[arrayField] as unknown[]).length > 0) {
       const imageUrls = result[arrayField] as unknown[];
-      const uploadTasks: Array<{ index: number; url: string | Promise<string> }> = [];
-      const errors: string[] = [];
+      generationLogCollector.log(sessionId, TAG, `Processing ${arrayField}: ${imageUrls.length} item(s) (sequential)`);
+
+      const processedUrls: string[] = [];
+      const arrayStartTime = Date.now();
 
       for (let i = 0; i < imageUrls.length; i++) {
         const imageUrl = imageUrls[i];
 
         if (!imageUrl) {
-          errors.push(`${arrayField}[${i}] is null or undefined`);
-          continue;
+          throw new Error(`${arrayField}[${i}] is null or undefined`);
         }
 
         if (isBase64DataUri(imageUrl)) {
-          const uploadPromise = uploadToFalStorage(imageUrl)
-            .then((url) => url)
-            .catch((error) => {
-              const errorMessage = `Failed to upload ${arrayField}[${i}]: ${getErrorMessage(error)}`;
-              console.error(`[preprocessInput] ${errorMessage}`);
-              errors.push(errorMessage);
-              throw new Error(errorMessage);
-            });
-          uploadTasks.push({ index: i, url: uploadPromise });
+          const sizeKB = Math.round(String(imageUrl).length / 1024);
+          generationLogCollector.log(sessionId, TAG, `${arrayField}[${i}/${imageUrls.length}]: base64 (${sizeKB}KB) - uploading...`);
+
+          try {
+            const url = await uploadToFalStorage(imageUrl, sessionId);
+            processedUrls.push(url);
+            generationLogCollector.log(sessionId, TAG, `${arrayField}[${i}/${imageUrls.length}]: upload OK`);
+          } catch (error) {
+            const elapsed = Date.now() - arrayStartTime;
+            const technicalMsg = getErrorMessage(error);
+            generationLogCollector.error(sessionId, TAG, `${arrayField}[${i}] upload FAILED after ${elapsed}ms: ${technicalMsg}`);
+            throw new Error(classifyUploadError(technicalMsg));
+          }
         } else if (typeof imageUrl === "string") {
-          uploadTasks.push({ index: i, url: imageUrl });
-        } else {
-          errors.push(`${arrayField}[${i}] has invalid type: ${typeof imageUrl}`);
-        }
-      }
-
-      if (errors.length > 0) {
-        throw new Error(`Image URL validation failed:\n${errors.join('\n')}`);
-      }
-
-      if (uploadTasks.length === 0) {
-        throw new Error(`${arrayField} array must contain at least one valid image URL`);
-      }
-
-      const uploadResults = await Promise.allSettled(
-        uploadTasks.map((task) => Promise.resolve(task.url))
-      );
-
-      const processedUrls: string[] = [];
-      const uploadErrors: string[] = [];
-
-      uploadResults.forEach((uploadResult, index) => {
-        if (uploadResult.status === 'fulfilled') {
-          processedUrls.push(uploadResult.value);
+          generationLogCollector.log(sessionId, TAG, `${arrayField}[${i}/${imageUrls.length}]: already URL - pass through`);
+          processedUrls.push(imageUrl);
         } else {
-          uploadErrors.push(
-            `Upload ${index} failed: ${getErrorMessage(uploadResult.reason)}`
-          );
+          throw new Error(`${arrayField}[${i}] has invalid type: ${typeof imageUrl}`);
         }
-      });
-
-      if (uploadErrors.length > 0) {
-        console.warn(
-          `[input-preprocessor] ${processedUrls.length} of ${uploadTasks.length} uploads succeeded. ` +
-          'Successful uploads remain in FAL storage.'
-        );
-        throw new Error(`Image upload failures:\n${uploadErrors.join('\n')}`);
       }
 
+      const arrayElapsed = Date.now() - arrayStartTime;
+      generationLogCollector.log(sessionId, TAG, `${arrayField}: all ${processedUrls.length} upload(s) succeeded in ${arrayElapsed}ms`);
       result[arrayField] = processedUrls;
     }
   }
 
-  // Wait for ALL uploads to complete (both individual keys and array)
-  // Use Promise.allSettled to handle partial failures gracefully
+  // Wait for ALL individual field uploads
   if (uploadPromises.length > 0) {
+    generationLogCollector.log(sessionId, TAG, `Waiting for ${uploadPromises.length} individual field upload(s)...`);
     const individualUploadResults = await Promise.allSettled(uploadPromises);
 
     const failedUploads = individualUploadResults.filter(
-      (result) => result.status === 'rejected'
+      (r) => r.status === 'rejected'
     );
 
     if (failedUploads.length > 0) {
       const successCount = individualUploadResults.length - failedUploads.length;
-      console.warn(
-        `[input-preprocessor] ${successCount} of ${individualUploadResults.length} individual field uploads succeeded. ` +
-        'Successful uploads remain in FAL storage.'
-      );
-
-      const errorMessages = failedUploads.map((result) =>
-        result.status === 'rejected'
-          ? (getErrorMessage(result.reason))
-          : 'Unknown error'
+      const errorMessages = failedUploads.map((r) =>
+        r.status === 'rejected' ? getErrorMessage(r.reason) : 'Unknown error'
       );
-
-      throw new Error(`Some image uploads failed:\n${errorMessages.join('\n')}`);
+      generationLogCollector.error(sessionId, TAG, `Individual uploads: ${successCount}/${individualUploadResults.length} succeeded`, { errors: errorMessages });
+      throw new Error(classifyUploadError(errorMessages[0]));
     }
   }
 
+  const totalElapsed = Date.now() - startTime;
+  generationLogCollector.log(sessionId, TAG, `Preprocessing complete in ${totalElapsed}ms`);
   return result;
 }

package/src/infrastructure/utils/log-collector.ts

@@ -0,0 +1,106 @@
+/**
+ * Generation Log Collector
+ * Session-scoped log collection — each generation gets its own isolated session.
+ * Supports concurrent generations without data corruption.
+ *
+ * Usage:
+ *   const sessionId = collector.startSession();
+ *   collector.log(sessionId, 'tag', 'message');
+ *   const entries = collector.endSession(sessionId);
+ */
+
+export interface LogEntry {
+  readonly timestamp: number;
+  readonly elapsed: number;
+  readonly level: 'info' | 'warn' | 'error';
+  readonly tag: string;
+  readonly message: string;
+  readonly data?: Record<string, unknown>;
+}
+
+interface Session {
+  readonly startTime: number;
+  entries: LogEntry[];
+}
+
+let sessionCounter = 0;
+
+class GenerationLogCollector {
+  private sessions = new Map<string, Session>();
+
+  /**
+   * Start a new isolated logging session. Returns session ID.
+   */
+  startSession(): string {
+    const id = `session_${++sessionCounter}_${Date.now()}`;
+    this.sessions.set(id, { startTime: Date.now(), entries: [] });
+    return id;
+  }
+
+  log(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'info', tag, message, data);
+  }
+
+  warn(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'warn', tag, message, data);
+  }
+
+  error(sessionId: string, tag: string, message: string, data?: Record<string, unknown>): void {
+    this.addEntry(sessionId, 'error', tag, message, data);
+  }
+
+  /**
+   * Get all entries for a session (non-destructive).
+   */
+  getEntries(sessionId: string): LogEntry[] {
+    return [...(this.sessions.get(sessionId)?.entries ?? [])];
+  }
+
+  /**
+   * End session and return all entries. Removes the session.
+   */
+  endSession(sessionId: string): LogEntry[] {
+    const session = this.sessions.get(sessionId);
+    if (!session) return [];
+    const entries = [...session.entries];
+    this.sessions.delete(sessionId);
+    return entries;
+  }
+
+  private addEntry(
+    sessionId: string,
+    level: LogEntry['level'],
+    tag: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      // Session not started or already ended — still output to console, but don't buffer
+      this.consoleOutput(level, tag, message, data);
+      return;
+    }
+
+    const now = Date.now();
+    session.entries.push({
+      timestamp: now,
+      elapsed: now - session.startTime,
+      level,
+      tag,
+      message,
+      ...(data && { data }),
+    });
+
+    this.consoleOutput(level, tag, message, data);
+  }
+
+  private consoleOutput(level: LogEntry['level'], tag: string, message: string, data?: Record<string, unknown>): void {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      const fn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
+      fn(`[${tag}] ${message}`, data ?? '');
+    }
+  }
+}
+
+/** Module-level singleton — safe for concurrent sessions via session IDs */
+export const generationLogCollector = new GenerationLogCollector();