@sagepilot-ai/react-native-sdk 0.2.4 → 0.3.0

package/dist/index.mjs

@@ -1,3 +1,6 @@
+// src/public/SdkClient.ts
+import { Platform } from "react-native";
+
 // src/core/errors/SagepilotChatError.ts
 var SagepilotChatError = class extends Error {
   constructor(code, message, options = {}) {
@@ -15,7 +18,7 @@ var SagepilotChatError = class extends Error {
 
 // src/core/config/constants.ts
 var SDK_NAME = "@sagepilot-ai/react-native-sdk";
-var SDK_VERSION = "0.2.4";
+var SDK_VERSION = "0.3.0";
 var DEFAULT_HOST = "https://app.sagepilot.ai";
 var DEFAULT_WIDGET_HOST = "https://app.sagepilot.ai";
 var CUSTOMER_API_PREFIX = "/customer-api/v1";
@@ -324,6 +327,34 @@ async function resolveDeviceInfo(adapter) {
   return adapter.getDeviceInfo();
 }
 
+// src/core/storage/cache.ts
+function createAsyncStorageCacheStorage(asyncStorage) {
+  return {
+    getItem: (key) => asyncStorage.getItem(key),
+    setItem: (key, value) => asyncStorage.setItem(key, value),
+    removeItem: (key) => asyncStorage.removeItem(key)
+  };
+}
+function createJsonCache(storage, namespace) {
+  return {
+    async get(key) {
+      const value = await storage.getItem(`${namespace}:${key}`);
+      if (!value) return null;
+      try {
+        return JSON.parse(value);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      await storage.setItem(`${namespace}:${key}`, JSON.stringify(value));
+    },
+    async remove(key) {
+      await storage.removeItem(`${namespace}:${key}`);
+    }
+  };
+}
+
 // src/resources/channels.ts
 function bootstrapChannel(http, host, channelId) {
   return http.request(
@@ -407,6 +438,9 @@ function fetchUnreadCount(http, host, channelId, sessionId, authorizationHeader)
 }
 
 // src/public/SdkClient.ts
+var PRESENTATION_CACHE_NAMESPACE = "sagepilot_rn_presentation";
+var PRESENTATION_CACHE_KEY = "state";
+var PRESENTATION_RESTORE_MAX_AGE_MS = 15 * 60 * 1e3;
 var DEFAULT_MOBILE_LAUNCHER_CONFIG = {
   label: "Chat",
   buttonColor: "#173c2d",
@@ -476,6 +510,10 @@ function readRecordField(input, key) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
   return value;
 }
+function isFreshPresentationState(updatedAt) {
+  if (typeof updatedAt !== "number" || !Number.isFinite(updatedAt)) return false;
+  return Date.now() - updatedAt <= PRESENTATION_RESTORE_MAX_AGE_MS;
+}
 function toPublicSessionState(session) {
   return {
     session_id: session.session_id,
@@ -532,6 +570,9 @@ var SagepilotReactNativeChat = class {
     const { workspaceId, channelId } = parseKey(config.key);
     this.runtimeOptions = {
       behavior: config.behavior,
+      cacheStorage: config.cacheStorage,
+      filePicker: config.filePicker,
+      fileStore: config.fileStore,
       presentation: config.presentation,
       theme: config.theme,
       hostedClaimsStorageKeyPrefix: config.hostedClaimsStorageKeyPrefix || DEFAULT_HOSTED_CLAIMS_STORAGE_KEY_PREFIX
@@ -562,6 +603,7 @@ var SagepilotReactNativeChat = class {
       this.channel = channel;
       this.session = session;
       this.isConfigured = true;
+      await this.restorePresentationFromCache();
       this.emitReady();
       this.emitState();
       if (config.behavior?.enableUnreadPolling ?? true) {
@@ -701,12 +743,14 @@ var SagepilotReactNativeChat = class {
     this.hostedChatView = { screen: "home" };
     if (this.presented) {
       this.emitState();
+      this.persistPresentationState();
       return true;
     }
     this.presented = true;
     this.setUnreadCount(0);
     this.presentCallbacks.forEach((callback) => callback(this.getLifecycleState()));
     this.emitState();
+    this.persistPresentationState();
     return true;
   }
   presentMessages() {
@@ -734,6 +778,7 @@ var SagepilotReactNativeChat = class {
     this.emitUnreadChange();
     this.dismissCallbacks.forEach((callback) => callback(this.getLifecycleState()));
     this.emitState();
+    this.persistPresentationState();
     return true;
   }
   hide() {
@@ -868,6 +913,10 @@ var SagepilotReactNativeChat = class {
     }
     return this.session?.conversation_id ?? void 0;
   }
+  /** Returns the chat id that is explicitly part of the current hosted URL. */
+  getHostedRouteChatId() {
+    return this.hostedChatView.screen === "composer" ? this.hostedChatView.chatId : void 0;
+  }
   getHostedIdentityMessage() {
     if (!this.legacyWidgetJwt) return null;
     return {
@@ -878,6 +927,34 @@ var SagepilotReactNativeChat = class {
       }
     };
   }
+  /** Captures the hosted route that should receive a picked attachment batch. */
+  getHostedAttachmentTarget() {
+    return {
+      chatId: this.getActiveHostedChatId(),
+      routeChatId: this.getHostedRouteChatId(),
+      hostedChatView: this.serializeHostedChatView(this.hostedChatView)
+    };
+  }
+  /** Restores the hosted route for a queued attachment batch before delivery. */
+  restoreHostedAttachmentTarget(target) {
+    if (Platform.OS !== "android") return false;
+    if (!target) return false;
+    const hostedChatView = this.readPersistedHostedChatView(target.hostedChatView);
+    if (!hostedChatView) return false;
+    const currentChatId = this.getActiveHostedChatId();
+    const targetChatId = normalizeOptionalString(target.chatId);
+    const routeChatId = normalizeOptionalString(target.routeChatId) ?? (hostedChatView.screen === "composer" ? normalizeOptionalString(hostedChatView.chatId) : void 0);
+    const nextHostedChatView = routeChatId && hostedChatView.screen === "composer" ? this.withPinnedChatId(hostedChatView, routeChatId) : hostedChatView;
+    if (this.presented && (!targetChatId || currentChatId === targetChatId) && this.areHostedChatViewsEqual(this.hostedChatView, nextHostedChatView)) {
+      return false;
+    }
+    this.hostedChatView = nextHostedChatView;
+    this.presented = true;
+    this.setUnreadCount(0);
+    this.emitState();
+    this.persistPresentationState();
+    return true;
+  }
   handleHostedBridgeMessage(message) {
     if (!message) return false;
     if (message.type === "close_widget") {
@@ -945,6 +1022,7 @@ var SagepilotReactNativeChat = class {
   }
   destroy() {
     this.stopUnreadPolling();
+    this.persistPresentationState({ cleanShutdown: true, presented: false });
     this.resetRuntimeState();
     this.emitState();
     this.identifyCallbacks.clear();
@@ -1100,8 +1178,86 @@ var SagepilotReactNativeChat = class {
       this.presentCallbacks.forEach((callback) => callback(this.getLifecycleState()));
     }
     this.emitState();
+    this.persistPresentationState();
     return true;
   }
+  /** Returns the dedicated cache used for hosted-chat presentation recovery. */
+  getPresentationCache() {
+    const cacheStorage = this.runtimeOptions?.cacheStorage;
+    if (!cacheStorage) return null;
+    return createJsonCache(cacheStorage, PRESENTATION_CACHE_NAMESPACE);
+  }
+  /** Removes callback-only fields so the hosted route can be safely serialized. */
+  serializeHostedChatView(view) {
+    if (view.screen !== "composer") return view;
+    return {
+      screen: "composer",
+      message: view.message,
+      mode: view.mode,
+      chatId: view.chatId,
+      metadata: view.metadata
+    };
+  }
+  /** Validates a persisted hosted view before using it to rebuild a widget URL. */
+  readPersistedHostedChatView(view) {
+    if (!view || typeof view !== "object") return null;
+    const record = view;
+    if (record.screen === "home") return { screen: "home" };
+    if (record.screen === "messages") return { screen: "messages" };
+    if (record.screen !== "composer") return null;
+    const mode = record.mode === "new" ? "new" : "auto";
+    return {
+      screen: "composer",
+      message: typeof record.message === "string" ? record.message : void 0,
+      mode,
+      chatId: typeof record.chatId === "string" && record.chatId ? record.chatId : void 0,
+      metadata: readRecordField(record, "metadata")
+    };
+  }
+  /** Forces a persisted hosted route to target the exact chat that owns a pending attachment. */
+  withPinnedChatId(view, chatId) {
+    if (view.screen === "composer") {
+      return {
+        ...view,
+        chatId
+      };
+    }
+    return {
+      screen: "composer",
+      mode: "auto",
+      chatId
+    };
+  }
+  /** Compares hosted route state without relying on object identity. */
+  areHostedChatViewsEqual(first, second) {
+    return JSON.stringify(this.serializeHostedChatView(first)) === JSON.stringify(this.serializeHostedChatView(second));
+  }
+  /** Persists presentation state without blocking customer-facing SDK methods. */
+  persistPresentationState(options) {
+    const cache = this.getPresentationCache();
+    if (!cache) return;
+    const state = {
+      presented: options?.presented ?? this.presented,
+      hostedChatView: this.serializeHostedChatView(this.hostedChatView),
+      updatedAt: Date.now(),
+      cleanShutdown: options?.cleanShutdown
+    };
+    void cache.set(PRESENTATION_CACHE_KEY, state).catch(() => void 0);
+  }
+  /** Restores Android presentation state after configure without resetting the hosted route to Home. */
+  async restorePresentationFromCache() {
+    const cache = this.getPresentationCache();
+    if (!cache || Platform.OS !== "android") return;
+    const persisted = await cache.get(PRESENTATION_CACHE_KEY).catch(() => null);
+    if (persisted?.cleanShutdown) return;
+    if (!isFreshPresentationState(persisted?.updatedAt)) return;
+    if (!persisted?.presented) return;
+    const hostedChatView = this.readPersistedHostedChatView(persisted.hostedChatView);
+    if (!hostedChatView) return;
+    this.hostedChatView = hostedChatView;
+    this.presented = true;
+    this.setUnreadCount(0);
+  }
 };
 var internalSagepilotChat = new SagepilotReactNativeChat();
 var SagepilotChat = {
@@ -1138,22 +1294,337 @@ var SagepilotChat = {
   destroy: () => internalSagepilotChat.destroy()
 };
 
-// src/core/storage/cache.ts
-function createAsyncStorageCacheStorage(asyncStorage) {
+// src/core/storage/fileStore.ts
+var DEFAULT_DIRECTORY_NAME = "sagepilot-attachments";
+function sanitizeKey(key) {
+  return key.replace(/[^a-zA-Z0-9._-]/g, "_").replace(/\.{2,}/g, "_");
+}
+function createSagepilotFileStore(blobUtil, options = {}) {
+  const directory = `${blobUtil.fs.dirs.DocumentDir}/${options.directoryName ?? DEFAULT_DIRECTORY_NAME}`;
+  const pathFor = (key) => `${directory}/${sanitizeKey(key)}`;
+  let dirReady = null;
+  function ensureDirectory() {
+    if (!dirReady) {
+      dirReady = (async () => {
+        if (!await blobUtil.fs.exists(directory)) {
+          await blobUtil.fs.mkdir(directory);
+        }
+      })().catch((error) => {
+        dirReady = null;
+        throw error;
+      });
+    }
+    return dirReady;
+  }
   return {
-    getItem: (key) => asyncStorage.getItem(key),
-    setItem: (key, value) => asyncStorage.setItem(key, value),
-    removeItem: (key) => asyncStorage.removeItem(key)
+    async write(key, base64) {
+      await ensureDirectory();
+      await blobUtil.fs.writeFile(pathFor(key), base64, "base64");
+    },
+    async read(key) {
+      const content = await blobUtil.fs.readFile(pathFor(key), "base64");
+      if (typeof content !== "string" || content.length === 0) {
+        throw new Error("Persisted attachment is empty or unreadable.");
+      }
+      return content;
+    },
+    async remove(key) {
+      try {
+        if (await blobUtil.fs.exists(pathFor(key))) {
+          await blobUtil.fs.unlink(pathFor(key));
+        }
+      } catch {
+      }
+    },
+    async prune(keepKeys) {
+      try {
+        if (!await blobUtil.fs.exists(directory)) return;
+        const keep = new Set(keepKeys.map(sanitizeKey));
+        const entries = await blobUtil.fs.ls(directory);
+        await Promise.all(
+          entries.filter((entry) => !keep.has(entry)).map((entry) => blobUtil.fs.unlink(`${directory}/${entry}`).catch(() => void 0))
+        );
+      } catch {
+      }
+    }
+  };
+}
+
+// src/core/native/filePicker.ts
+import { Alert, Linking, PermissionsAndroid, Platform as Platform2 } from "react-native";
+
+// src/core/native/filePickerShared.ts
+var SagepilotFilePickerError = class extends Error {
+  /** Creates a typed picker error that can be surfaced over the widget bridge. */
+  constructor(code, message) {
+    super(message);
+    this.name = "SagepilotFilePickerError";
+    this.code = code;
+  }
+};
+var SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION = 1920;
+var SAGEPILOT_DEFAULT_IMAGE_QUALITY = 0.8;
+var SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES = 15 * 1024 * 1024;
+
+// src/core/native/filePicker.ts
+var DEBUG_PREFIX = "[SagepilotSDK][FilePicker]";
+var DEFAULT_IMAGE_MAX_DIMENSION = SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION;
+var DEFAULT_IMAGE_QUALITY = SAGEPILOT_DEFAULT_IMAGE_QUALITY;
+var DEFAULT_IMAGE_MIME_TYPE = "image/jpeg";
+var DEFAULT_DOCUMENT_MIME_TYPE = "application/octet-stream";
+var DEFAULT_IMAGE_SELECTION_LIMIT = 5;
+var DEFAULT_DOCUMENT_MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024;
+var DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES = SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES;
+function bytesToMb(bytes) {
+  return Math.round(bytes / (1024 * 1024) * 10) / 10;
+}
+function estimateBase64ByteSize(dataBase64) {
+  return Math.floor(dataBase64.length * 3 / 4);
+}
+function stripFileScheme(uri) {
+  return uri.startsWith("file://") ? uri.replace("file://", "") : uri;
+}
+function debugFilePicker(message, details) {
+  console.log(`${DEBUG_PREFIX} ${message}`, details ?? "");
+}
+async function promptOpenSagepilotCameraSettings() {
+  if (Platform2.OS !== "android") return;
+  await new Promise((resolve) => {
+    Alert.alert(
+      "Camera access is off",
+      "Enable camera access for this app in Settings to take a photo.",
+      [
+        {
+          text: "Not now",
+          style: "cancel",
+          onPress: resolve
+        },
+        {
+          text: "Open Settings",
+          onPress: () => {
+            Linking.openSettings().finally(resolve);
+          }
+        }
+      ]
+    );
+  });
+}
+async function ensureSagepilotAndroidCameraPermission() {
+  if (Platform2.OS !== "android") return;
+  let result;
+  try {
+    debugFilePicker("requesting Android camera permission");
+    result = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA);
+  } catch {
+    debugFilePicker("camera permission request threw; continuing to native launch");
+    return;
+  }
+  debugFilePicker("Android camera permission result", { result });
+  if (result === PermissionsAndroid.RESULTS.NEVER_ASK_AGAIN) {
+    await promptOpenSagepilotCameraSettings();
+    throw new SagepilotFilePickerError(
+      "permission_denied",
+      "Camera access is turned off. Enable it for this app in Settings to take a photo."
+    );
+  }
+  if (result === PermissionsAndroid.RESULTS.DENIED) {
+    throw new SagepilotFilePickerError(
+      "permission_denied",
+      "Camera permission is required to take a photo."
+    );
+  }
+}
+function canUseCameraSource(imagePicker) {
+  return Boolean(imagePicker);
+}
+function mapImagePickerErrorCode(errorCode) {
+  switch (errorCode) {
+    case "permission":
+      return "permission_denied";
+    case "camera_unavailable":
+      return "camera_unavailable";
+    default:
+      return "unknown";
+  }
+}
+function imageAssetsToPickedFiles(result, maxFileSizeBytes) {
+  if (result.didCancel) return [];
+  if (result.errorCode) {
+    throw new SagepilotFilePickerError(
+      mapImagePickerErrorCode(result.errorCode),
+      result.errorMessage || `Could not capture the photo (${result.errorCode}).`
+    );
+  }
+  const assets = result.assets ?? [];
+  const usable = assets.filter((asset) => typeof asset.base64 === "string" && asset.base64.length > 0);
+  if (assets.length > usable.length) {
+    throw new SagepilotFilePickerError(
+      "encode_failed",
+      assets.length === 1 ? "The photo could not be processed. Please try again." : "Some photos could not be processed. Please try selecting them again."
+    );
+  }
+  return usable.map((asset, index) => {
+    const dataBase64 = asset.base64;
+    const size = asset.fileSize ?? estimateBase64ByteSize(dataBase64);
+    if (maxFileSizeBytes > 0 && size > maxFileSizeBytes) {
+      throw new SagepilotFilePickerError(
+        "file_too_large",
+        `Image is too large (max ${bytesToMb(maxFileSizeBytes)}MB).`
+      );
+    }
+    return {
+      file_name: asset.fileName || `photo-${Date.now()}-${index + 1}.jpg`,
+      mime_type: asset.type || DEFAULT_IMAGE_MIME_TYPE,
+      size,
+      data_base64: dataBase64
+    };
+  });
+}
+async function readUriAsBase64(uri, fileReader) {
+  if (fileReader) {
+    const content = await fileReader.fs.readFile(stripFileScheme(uri), "base64");
+    if (typeof content !== "string") {
+      throw new Error("File reader returned unexpected content.");
+    }
+    return content;
+  }
+  const response = await fetch(uri);
+  const blob = await response.blob();
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const dataUrl = typeof reader.result === "string" ? reader.result : "";
+      const [, payload = ""] = dataUrl.split(",");
+      if (!payload) {
+        reject(new Error("Could not read the selected file."));
+        return;
+      }
+      resolve(payload);
+    };
+    reader.onerror = () => reject(new Error("Could not read the selected file."));
+    reader.readAsDataURL(blob);
+  });
+}
+function createSagepilotFilePicker(options) {
+  const { imagePicker, documentsPicker, fileReader } = options;
+  const imageMaxDimension = options.imageMaxDimension ?? DEFAULT_IMAGE_MAX_DIMENSION;
+  const imageQuality = options.imageQuality ?? DEFAULT_IMAGE_QUALITY;
+  const imageSelectionLimit = options.imageSelectionLimit ?? DEFAULT_IMAGE_SELECTION_LIMIT;
+  const documentMaxFileSizeBytes = options.documentMaxFileSizeBytes ?? DEFAULT_DOCUMENT_MAX_FILE_SIZE_BYTES;
+  const imageMaxFileSizeBytes = options.imageMaxFileSizeBytes ?? DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES;
+  const sources = [];
+  if (canUseCameraSource(imagePicker)) sources.push("camera");
+  if (imagePicker) sources.push("library");
+  if (documentsPicker) sources.push("documents");
+  debugFilePicker("adapter created", {
+    platform: Platform2.OS,
+    hasImagePicker: Boolean(imagePicker),
+    hasDocumentsPicker: Boolean(documentsPicker),
+    hasFileReader: Boolean(fileReader),
+    sources
+  });
+  if (sources.length === 0) return void 0;
+  const imageOptions = {
+    mediaType: "photo",
+    includeBase64: true,
+    maxWidth: imageMaxDimension,
+    maxHeight: imageMaxDimension,
+    quality: imageQuality,
+    saveToPhotos: false
+  };
+  async function pickFromCamera() {
+    debugFilePicker("camera pick requested", {
+      platform: Platform2.OS,
+      imageMaxDimension,
+      imageQuality,
+      imageMaxFileSizeBytes
+    });
+    await ensureSagepilotAndroidCameraPermission();
+    if (!imagePicker) {
+      throw new SagepilotFilePickerError("camera_unavailable", "The camera picker is not available in this build.");
+    }
+    debugFilePicker("launching image-picker camera", { platform: Platform2.OS });
+    return imageAssetsToPickedFiles(await imagePicker.launchCamera(imageOptions), imageMaxFileSizeBytes);
+  }
+  async function pickFromLibrary(multiple) {
+    if (!imagePicker) return [];
+    debugFilePicker("library pick requested", { multiple, imageSelectionLimit });
+    return imageAssetsToPickedFiles(await imagePicker.launchImageLibrary({
+      ...imageOptions,
+      // Bounded multi-select: 0 (unlimited) lets a huge batch OOM the bridge.
+      selectionLimit: multiple ? Math.max(0, imageSelectionLimit) : 1
+    }), imageMaxFileSizeBytes);
+  }
+  async function pickDocuments(multiple) {
+    if (!documentsPicker) return [];
+    debugFilePicker("document pick requested", { multiple, documentMaxFileSizeBytes });
+    let picked;
+    try {
+      picked = await documentsPicker.pick({ allowMultiSelection: multiple });
+    } catch (error) {
+      if (error && typeof error === "object" && error.code === "OPERATION_CANCELED") {
+        return [];
+      }
+      throw error;
+    }
+    const files = [];
+    for (const file of picked) {
+      if (documentMaxFileSizeBytes > 0 && typeof file.size === "number" && file.size > documentMaxFileSizeBytes) {
+        throw new SagepilotFilePickerError(
+          "file_too_large",
+          `"${file.name || "File"}" is too large (max ${bytesToMb(documentMaxFileSizeBytes)}MB).`
+        );
+      }
+      let readableUri = file.uri;
+      if (documentsPicker.keepLocalCopy) {
+        const fileName = file.name || `file-${Date.now()}`;
+        const [copy] = await documentsPicker.keepLocalCopy({
+          files: [{ uri: file.uri, fileName }],
+          destination: "cachesDirectory"
+        });
+        if (copy?.status === "success" && copy.localUri) {
+          readableUri = copy.localUri;
+        }
+      }
+      let dataBase64;
+      try {
+        dataBase64 = await readUriAsBase64(readableUri, fileReader);
+      } catch (error) {
+        throw new SagepilotFilePickerError(
+          "read_failed",
+          error instanceof Error && error.message ? error.message : "Could not read the selected file."
+        );
+      }
+      files.push({
+        file_name: file.name || `file-${Date.now()}`,
+        mime_type: file.type || DEFAULT_DOCUMENT_MIME_TYPE,
+        size: file.size ?? estimateBase64ByteSize(dataBase64),
+        data_base64: dataBase64
+      });
+    }
+    return files;
+  }
+  return {
+    sources,
+    async pickFiles(request) {
+      debugFilePicker("pickFiles request", request);
+      if (request.source === "camera") return pickFromCamera();
+      if (request.source === "library") return pickFromLibrary(request.multiple);
+      return pickDocuments(request.multiple);
+    }
   };
 }
 
 // src/ui/SagepilotChatProvider.ts
 import { createElement, useCallback, useEffect, useRef, useState } from "react";
+import { Camera, FileText, Images, X } from "lucide-react-native";
 import {
   ActivityIndicator,
+  AppState,
   KeyboardAvoidingView,
+  Linking as Linking2,
   Modal,
-  Platform,
+  Platform as Platform3,
   Pressable,
   SafeAreaView,
   StyleSheet,
@@ -1163,6 +1634,40 @@ import {
 import { WebView } from "react-native-webview";
 
 // src/core/webview/mobileBridge.ts
+var FILE_PICKER_PROTOCOL_VERSION = 2;
+function buildBridgeCapabilitiesPayload(capabilities) {
+  return { ...capabilities, filePickerProtocol: FILE_PICKER_PROTOCOL_VERSION };
+}
+function buildBridgeCapabilitiesScript(capabilities) {
+  const payload = buildBridgeCapabilitiesPayload(capabilities);
+  return [
+    "(function(){",
+    "try {",
+    "if (window.SagepilotMobileBridge) {",
+    `window.SagepilotMobileBridge.capabilities = Object.assign({}, window.SagepilotMobileBridge.capabilities, ${JSON.stringify(payload)});`,
+    "}",
+    "} catch (_) {}",
+    "true;",
+    "})();"
+  ].join("\n");
+}
+function buildLivenessPingScript(nonce, staleMs) {
+  return [
+    "(function(){",
+    "try {",
+    "var hb = window.__sagepilotWidgetHeartbeat;",
+    "var supports = typeof hb === 'number';",
+    `var alive = !supports ? true : (Date.now() - hb < ${Math.max(0, Math.floor(staleMs))});`,
+    "var send = function(){",
+    "  var msg = JSON.stringify({ type: 'sagepilot:pong', nonce: " + JSON.stringify(nonce) + ", alive: alive, supportsHeartbeat: supports });",
+    "  if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) { window.ReactNativeWebView.postMessage(msg); }",
+    "};",
+    "send();",
+    "} catch (_) {}",
+    "true;",
+    "})();"
+  ].join("\n");
+}
 function isHostedBridgeMessage(value) {
   if (!value || typeof value !== "object") return false;
   const message = value;
@@ -1183,9 +1688,23 @@ function parseHostedBridgeMessage(rawData) {
     return null;
   }
 }
-var mobileWebViewBridgeScript = `
+function buildMobileWebViewBridgeScript(capabilities) {
+  const payload = buildBridgeCapabilitiesPayload(capabilities);
+  return `
   (function () {
-    if (window.__sagepilotRnBridgeInstalled) return true;
+    var bridgeCapabilities = ${JSON.stringify(payload)};
+    var applyBridgeCapabilities = function () {
+      try {
+        if (window.SagepilotMobileBridge) {
+          window.SagepilotMobileBridge.capabilities = Object.assign({}, window.SagepilotMobileBridge.capabilities, bridgeCapabilities);
+        }
+      } catch (error) {}
+    };
+
+    if (window.__sagepilotRnBridgeInstalled) {
+      applyBridgeCapabilities();
+      return true;
+    }
     window.__sagepilotRnBridgeInstalled = true;
 
     var ensureViewport = function () {
@@ -1226,9 +1745,11 @@ var mobileWebViewBridgeScript = `
     };
 
     window.SagepilotMobileBridge = {
+      capabilities: bridgeCapabilities,
       postMessage: sendToReactNative,
       ready: function () { sendToReactNative({ type: "sagepilot:ready" }); }
     };
+    applyBridgeCapabilities();
 
     document.addEventListener("click", function (event) {
       try {
@@ -1269,6 +1790,7 @@ var mobileWebViewBridgeScript = `
     return true;
   })();
 `;
+}
 
 // src/specs/SagepilotInsetsViewNativeComponent.ts
 import codegenNativeComponent from "react-native/Libraries/Utilities/codegenNativeComponent";
@@ -1285,12 +1807,133 @@ function readPresentationState() {
     presentation: internalSagepilotChat.getConfig()?.presentation
   };
 }
+function getBridgeCapabilities() {
+  return {
+    nativeFilePicker: Boolean(internalSagepilotChat.getConfig()?.filePicker)
+  };
+}
 function getInjectedWebViewScript() {
+  const capabilities = getBridgeCapabilities();
   return [
     internalSagepilotChat.getHostedAuthScript(),
-    mobileWebViewBridgeScript
+    buildMobileWebViewBridgeScript(capabilities),
+    buildBridgeCapabilitiesScript(capabilities)
   ].filter(Boolean).join("\n");
 }
+var FILE_PICKER_SOURCE_LABELS = {
+  camera: "Take photo",
+  library: "Choose from gallery",
+  documents: "Browse files"
+};
+var FILE_PICKER_SOURCE_DESCRIPTIONS = {
+  camera: "Use the in-app camera",
+  library: "Photos and videos on this device",
+  documents: "PDFs, documents, and Drive files"
+};
+var FILE_PICKER_SOURCE_ICONS = {
+  camera: Camera,
+  library: Images,
+  documents: FileText
+};
+var FILE_PICKER_SOURCE_ICON_COLORS = {
+  camera: "#0284c7",
+  library: "#16a34a",
+  documents: "#7c3aed"
+};
+var DEBUG_PREFIX2 = "[SagepilotSDK][Provider]";
+var DELIVERY_RETRY_MS = 1500;
+var DELIVERY_LEGACY_FALLBACK_ATTEMPTS = 2;
+var DELIVERY_MAX_ATTEMPTS = 8;
+var PERSIST_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+var PENDING_FILES_CACHE_NAMESPACE = "sagepilot_rn_picker";
+var PENDING_FILES_CACHE_KEY = "pending_batch";
+var LIVENESS_HEARTBEAT_STALE_MS = 4e3;
+var LIVENESS_PONG_TIMEOUT_MS = 1500;
+var LIVENESS_MAX_PING_ATTEMPTS = 2;
+var LIVENESS_PICKER_GRACE_MS = 8e3;
+var LIVENESS_MAX_REMOUNTS = 2;
+var batchSequence = 0;
+function nextBatchId() {
+  batchSequence += 1;
+  const entropy = Math.random().toString(36).slice(2, 8);
+  return `b_${Date.now().toString(36)}_${batchSequence}_${entropy}`;
+}
+function totalBase64Bytes(files) {
+  return files.reduce((sum, file) => sum + (file.data_base64?.length ?? 0), 0);
+}
+function storageKeyFor(batchId, index) {
+  return `${batchId}_${index}.bin`;
+}
+function renderFilePickerSourceIcon(source) {
+  const Icon = FILE_PICKER_SOURCE_ICONS[source];
+  return createElement(
+    View,
+    { style: getFilePickerSourceIconStyle(source) },
+    createElement(Icon, {
+      color: FILE_PICKER_SOURCE_ICON_COLORS[source],
+      size: 23,
+      strokeWidth: 2.35
+    })
+  );
+}
+function getFilePickerSourceIconStyle(source) {
+  if (source === "camera") return [styles.sheetOptionIcon, styles.cameraOptionIcon];
+  if (source === "library") return [styles.sheetOptionIcon, styles.libraryOptionIcon];
+  return [styles.sheetOptionIcon, styles.documentsOptionIcon];
+}
+function getSheetOptionStyle(pressed) {
+  return [styles.sheetOption, pressed && styles.sheetOptionPressed];
+}
+function getSheetCancelStyle(pressed) {
+  return [styles.sheetCancelButton, pressed && styles.sheetCancelButtonPressed];
+}
+function buildDispatchScript(messageLiteral) {
+  return [
+    "(function(){",
+    "try {",
+    `var message = ${messageLiteral};`,
+    "window.dispatchEvent(new MessageEvent('message', { data: message, origin: window.location.origin, source: window.parent || window }));",
+    "} catch (_) {}",
+    "true;",
+    "})();"
+  ].join("\n");
+}
+function buildFilesPickedScript(batch) {
+  return buildDispatchScript(JSON.stringify({
+    type: "sagepilot:files_picked",
+    batch_id: batch.batchId,
+    chat_id: batch.target?.chatId,
+    conversation_id: batch.target?.chatId,
+    files: batch.files
+  }));
+}
+function buildFilePickerErrorScript(message, code) {
+  return buildDispatchScript(
+    `{ type: "sagepilot:file_picker_error", message: ${JSON.stringify(message)}${code ? `, code: ${JSON.stringify(code)}` : ""} }`
+  );
+}
+function buildFilePickerCancelledScript() {
+  return buildDispatchScript(`{ type: "sagepilot:file_picker_cancelled" }`);
+}
+function readFilePickerError(error) {
+  if (error && typeof error === "object") {
+    const candidate = error;
+    const message = typeof candidate.message === "string" && candidate.message ? candidate.message : "Could not attach the selected file.";
+    const code = typeof candidate.code === "string" ? candidate.code : void 0;
+    return { message, code };
+  }
+  return { message: "Could not attach the selected file." };
+}
+function debugProvider(message, details) {
+  console.log(`${DEBUG_PREFIX2} ${message}`, details ?? "");
+}
+function describeAttachmentTarget(target) {
+  return {
+    targetChatId: target?.chatId,
+    targetRouteChatId: target?.routeChatId,
+    targetScreen: target?.hostedChatView.screen
+  };
+}
 function getHostedIdentityDispatchScript() {
   const message = internalSagepilotChat.getHostedIdentityMessage();
   if (!message) return "";
@@ -1313,10 +1956,13 @@ function readUrlOrigin(url) {
     return null;
   }
 }
+function isInternalWebViewScheme(url) {
+  return url.startsWith("about:") || url.startsWith("data:") || url.startsWith("blob:") || url.startsWith("javascript:") || url.startsWith("file:");
+}
 var hostedChatWebViewProps = {
   allowFileAccess: true,
   allowFileAccessFromFileURLs: true,
-  ...Platform.OS === "ios" ? {
+  ...Platform3.OS === "ios" ? {
     automaticallyAdjustContentInsets: false,
     contentInsetAdjustmentBehavior: "never",
     hideKeyboardAccessoryView: true
@@ -1331,7 +1977,7 @@ var hostedChatWebViewProps = {
   sharedCookiesEnabled: true,
   thirdPartyCookiesEnabled: true
 };
-var AndroidInsetsView = Platform.OS === "android" ? SagepilotInsetsViewNativeComponent_default : View;
+var AndroidInsetsView = Platform3.OS === "android" ? SagepilotInsetsViewNativeComponent_default : View;
 var emptyAndroidInsets = { top: 0, bottom: 0 };
 function SagepilotChatProvider({
   children,
@@ -1340,13 +1986,389 @@ function SagepilotChatProvider({
 }) {
   const [state, setState] = useState(readPresentationState);
   const [androidModalInsets, setAndroidModalInsets] = useState(emptyAndroidInsets);
+  const [nativeWebViewKey, setNativeWebViewKey] = useState(0);
+  const [preloadWebViewKey, setPreloadWebViewKey] = useState(0);
   const webFrameRef = useRef(null);
   const nativeWebViewRef = useRef(null);
+  const pendingBatchesRef = useRef([]);
+  const widgetReadyRef = useRef(false);
+  const deliveryTimerRef = useRef(null);
+  const deliveryAttemptsRef = useRef(0);
+  const pendingPingRef = useRef(null);
+  const pingTimeoutRef = useRef(null);
+  const livenessResumeTimerRef = useRef(null);
+  const livenessPausedUntilRef = useRef(0);
+  const pickerInFlightRef = useRef(false);
+  const livenessRemountCountRef = useRef(0);
+  const appStateRef = useRef(AppState.currentState);
+  const didReconcileRef = useRef(false);
+  const [androidRepaintTick, setAndroidRepaintTick] = useState(0);
+  const [sourceChooser, setSourceChooser] = useState(null);
+  const getPendingCache = useCallback(() => {
+    const cacheStorage = internalSagepilotChat.getConfig()?.cacheStorage;
+    if (!cacheStorage) return null;
+    return createJsonCache(cacheStorage, PENDING_FILES_CACHE_NAMESPACE);
+  }, []);
+  const writeManifest = useCallback(() => {
+    const cache = getPendingCache();
+    if (!cache) return;
+    const queue = pendingBatchesRef.current;
+    if (queue.length === 0) {
+      void cache.remove(PENDING_FILES_CACHE_KEY).catch(() => void 0);
+      return;
+    }
+    const hasFileStore = Boolean(internalSagepilotChat.getConfig()?.fileStore);
+    if (hasFileStore) {
+      const manifest = queue.filter((batch) => batch.storageKeys && batch.storageKeys.length === batch.files.length).map((batch) => ({
+        batchId: batch.batchId,
+        target: batch.target,
+        files: batch.files.map((file, index) => ({
+          file_name: file.file_name,
+          mime_type: file.mime_type,
+          size: file.size,
+          storageKey: batch.storageKeys[index]
+        }))
+      }));
+      if (manifest.length === 0) {
+        void cache.remove(PENDING_FILES_CACHE_KEY).catch(() => void 0);
+      } else {
+        void cache.set(PENDING_FILES_CACHE_KEY, manifest).catch(() => void 0);
+      }
+      return;
+    }
+    const totalBytes = queue.reduce((sum, batch) => sum + totalBase64Bytes(batch.files), 0);
+    if (totalBytes <= PERSIST_MAX_TOTAL_BYTES) {
+      const manifest = queue.map((batch) => ({
+        batchId: batch.batchId,
+        target: batch.target,
+        files: batch.files.map((file) => ({
+          file_name: file.file_name,
+          mime_type: file.mime_type,
+          size: file.size,
+          data_base64: file.data_base64
+        }))
+      }));
+      void cache.set(PENDING_FILES_CACHE_KEY, manifest).catch(() => void 0);
+    } else {
+      void cache.remove(PENDING_FILES_CACHE_KEY).catch(() => void 0);
+    }
+  }, [getPendingCache]);
+  const writeBatchBytes = useCallback(async (batch) => {
+    const fileStore = internalSagepilotChat.getConfig()?.fileStore;
+    if (!fileStore) return;
+    const entries = batch.files.map((file, index) => ({
+      key: storageKeyFor(batch.batchId, index),
+      base64: file.data_base64
+    }));
+    try {
+      await Promise.all(entries.map((entry) => fileStore.write(entry.key, entry.base64)));
+    } catch {
+      return;
+    }
+    if (!pendingBatchesRef.current.some((queued) => queued.batchId === batch.batchId)) {
+      void Promise.all(entries.map((entry) => fileStore.remove(entry.key).catch(() => void 0)));
+    }
+  }, []);
+  const discardBatchFiles = useCallback((batch) => {
+    if (!batch?.storageKeys) return;
+    const fileStore = internalSagepilotChat.getConfig()?.fileStore;
+    if (!fileStore) return;
+    void Promise.all(batch.storageKeys.map((key) => fileStore.remove(key).catch(() => void 0)));
+  }, []);
+  const pumpDelivery = useCallback(() => {
+    if (deliveryTimerRef.current) {
+      clearTimeout(deliveryTimerRef.current);
+      deliveryTimerRef.current = null;
+    }
+    const batch = pendingBatchesRef.current[0];
+    if (!batch) return;
+    if (internalSagepilotChat.restoreHostedAttachmentTarget(batch.target)) {
+      debugProvider("restored hosted attachment target", {
+        batchId: batch.batchId,
+        ...describeAttachmentTarget(batch.target)
+      });
+      widgetReadyRef.current = false;
+      deliveryTimerRef.current = setTimeout(() => pumpDelivery(), DELIVERY_RETRY_MS);
+      return;
+    }
+    deliveryAttemptsRef.current += 1;
+    const attempts = deliveryAttemptsRef.current;
+    const ref = nativeWebViewRef.current;
+    const shouldDeliver = ref && (widgetReadyRef.current || attempts >= DELIVERY_LEGACY_FALLBACK_ATTEMPTS);
+    if (shouldDeliver && ref) {
+      debugProvider("delivering native picked files", {
+        batchId: batch.batchId,
+        attempt: attempts,
+        widgetReady: widgetReadyRef.current,
+        count: batch.files.length,
+        ...describeAttachmentTarget(batch.target)
+      });
+      ref.injectJavaScript(buildFilesPickedScript(batch));
+    }
+    if (attempts < DELIVERY_MAX_ATTEMPTS) {
+      deliveryTimerRef.current = setTimeout(() => pumpDelivery(), DELIVERY_RETRY_MS);
+    }
+  }, []);
+  const startDelivery = useCallback(() => {
+    deliveryAttemptsRef.current = 0;
+    pumpDelivery();
+  }, [pumpDelivery]);
+  const ensureDelivery = useCallback(() => {
+    if (pendingBatchesRef.current.length === 0) return;
+    if (deliveryTimerRef.current) return;
+    startDelivery();
+  }, [startDelivery]);
+  const acknowledgeHeadBatch = useCallback(() => {
+    const head = pendingBatchesRef.current[0];
+    pendingBatchesRef.current = pendingBatchesRef.current.slice(1);
+    deliveryAttemptsRef.current = 0;
+    if (deliveryTimerRef.current) {
+      clearTimeout(deliveryTimerRef.current);
+      deliveryTimerRef.current = null;
+    }
+    discardBatchFiles(head);
+    writeManifest();
+    if (pendingBatchesRef.current.length > 0) startDelivery();
+  }, [discardBatchFiles, writeManifest, startDelivery]);
+  const queuePickedFiles = useCallback((files) => {
+    const batchId = nextBatchId();
+    const hasFileStore = Boolean(internalSagepilotChat.getConfig()?.fileStore);
+    const storageKeys = hasFileStore ? files.map((_, index) => storageKeyFor(batchId, index)) : void 0;
+    const batch = {
+      batchId,
+      files,
+      storageKeys,
+      target: internalSagepilotChat.getHostedAttachmentTarget()
+    };
+    debugProvider("queued native picked files", {
+      batchId,
+      count: files.length,
+      totalBase64Bytes: totalBase64Bytes(files),
+      persistedToFileStore: hasFileStore,
+      ...describeAttachmentTarget(batch.target)
+    });
+    pendingBatchesRef.current = [...pendingBatchesRef.current, batch];
+    ensureDelivery();
+    writeManifest();
+    void writeBatchBytes(batch);
+  }, [ensureDelivery, writeManifest, writeBatchBytes]);
+  const recoverNativeWebView = useCallback((reasonOrEvent) => {
+    const reason = typeof reasonOrEvent === "string" ? reasonOrEvent : "webview_render_process";
+    debugProvider("recovering native WebView", { reason });
+    widgetReadyRef.current = false;
+    setNativeWebViewKey((key) => key + 1);
+  }, []);
+  const recoverPreloadWebView = useCallback(() => {
+    setPreloadWebViewKey((key) => key + 1);
+  }, []);
+  const pauseLivenessAfterPicker = useCallback((durationMs) => {
+    if (Platform3.OS !== "android") return;
+    livenessPausedUntilRef.current = Math.max(livenessPausedUntilRef.current, Date.now() + durationMs);
+  }, []);
+  const runNativeFilePicker = useCallback((source, multiple) => {
+    const filePicker = internalSagepilotChat.getConfig()?.filePicker;
+    if (!filePicker) {
+      debugProvider("native file picker requested but no adapter is configured", { source, multiple });
+      return;
+    }
+    if (pickerInFlightRef.current) {
+      debugProvider("native file picker ignored because another picker is in flight", { source, multiple });
+      return;
+    }
+    debugProvider("native file picker starting", {
+      source,
+      multiple,
+      configuredSources: filePicker.sources
+    });
+    pauseLivenessAfterPicker(6e4);
+    pickerInFlightRef.current = true;
+    filePicker.pickFiles({ source, multiple }).then((files) => {
+      debugProvider("native file picker resolved", {
+        source,
+        count: files.length,
+        files: files.map((file) => ({
+          fileName: file.file_name,
+          mimeType: file.mime_type,
+          size: file.size,
+          base64Length: file.data_base64.length
+        }))
+      });
+      if (files.length === 0) {
+        nativeWebViewRef.current?.injectJavaScript(buildFilePickerCancelledScript());
+        return;
+      }
+      queuePickedFiles(files);
+    }).catch((error) => {
+      const { message, code } = readFilePickerError(error);
+      debugProvider("native file picker failed", { source, code, message });
+      nativeWebViewRef.current?.injectJavaScript(buildFilePickerErrorScript(message, code));
+    }).finally(() => {
+      pickerInFlightRef.current = false;
+      pauseLivenessAfterPicker(LIVENESS_PICKER_GRACE_MS);
+    });
+  }, [pauseLivenessAfterPicker, queuePickedFiles]);
+  const openNativeFilePicker = useCallback((multiple) => {
+    const filePicker = internalSagepilotChat.getConfig()?.filePicker;
+    if (!filePicker || filePicker.sources.length === 0) {
+      debugProvider("open native file picker ignored", {
+        multiple,
+        hasAdapter: Boolean(filePicker),
+        sources: filePicker?.sources ?? []
+      });
+      return;
+    }
+    debugProvider("open native file picker", { multiple, sources: filePicker.sources });
+    const [onlySource] = filePicker.sources;
+    if (filePicker.sources.length === 1 && onlySource && onlySource !== "camera") {
+      runNativeFilePicker(onlySource, multiple);
+      return;
+    }
+    setSourceChooser({ multiple });
+  }, [runNativeFilePicker]);
+  const handleSourceChoice = useCallback((source) => {
+    const chooser = sourceChooser;
+    setSourceChooser(null);
+    if (chooser) runNativeFilePicker(source, chooser.multiple);
+  }, [sourceChooser, runNativeFilePicker]);
   useEffect(() => {
     return internalSagepilotChat.onStateChange(() => {
       setState(readPresentationState());
     });
   }, []);
+  useEffect(() => {
+    let cancelled = false;
+    const cache = getPendingCache();
+    if (!cache) return;
+    const reconcile = async () => {
+      if (didReconcileRef.current) return;
+      const manifest = await cache.get(PENDING_FILES_CACHE_KEY).catch(() => null);
+      if (cancelled || didReconcileRef.current || !Array.isArray(manifest) || manifest.length === 0) return;
+      const fileStore = internalSagepilotChat.getConfig()?.fileStore;
+      const restored = [];
+      for (const batch of manifest) {
+        if (!batch || typeof batch.batchId !== "string" || !Array.isArray(batch.files) || batch.files.length === 0) continue;
+        const files = [];
+        const storageKeys = [];
+        let intact = true;
+        for (const file of batch.files) {
+          let dataBase64 = null;
+          if (typeof file.storageKey === "string" && fileStore) {
+            try {
+              dataBase64 = await fileStore.read(file.storageKey);
+              storageKeys.push(file.storageKey);
+            } catch {
+              intact = false;
+            }
+          } else if (typeof file.data_base64 === "string" && file.data_base64) {
+            dataBase64 = file.data_base64;
+          }
+          if (!dataBase64) {
+            intact = false;
+            break;
+          }
+          files.push({ file_name: file.file_name, mime_type: file.mime_type, size: file.size, data_base64: dataBase64 });
+        }
+        if (intact && files.length === batch.files.length) {
+          restored.push({
+            batchId: batch.batchId,
+            files,
+            storageKeys: storageKeys.length === files.length ? storageKeys : void 0,
+            target: batch.target
+          });
+        }
+      }
+      if (cancelled || didReconcileRef.current) return;
+      didReconcileRef.current = true;
+      pendingBatchesRef.current = [...restored, ...pendingBatchesRef.current];
+      writeManifest();
+      if (fileStore) {
+        const keep = pendingBatchesRef.current.flatMap(
+          (batch) => batch.files.map((_, index) => storageKeyFor(batch.batchId, index))
+        );
+        void fileStore.prune(keep).catch(() => void 0);
+      }
+      startDelivery();
+    };
+    void reconcile();
+    return () => {
+      cancelled = true;
+    };
+  }, [getPendingCache, startDelivery, writeManifest]);
+  const clearPing = useCallback(() => {
+    pendingPingRef.current = null;
+    if (pingTimeoutRef.current) {
+      clearTimeout(pingTimeoutRef.current);
+      pingTimeoutRef.current = null;
+    }
+  }, []);
+  const clearDeferredLivenessProbe = useCallback(() => {
+    if (livenessResumeTimerRef.current) {
+      clearTimeout(livenessResumeTimerRef.current);
+      livenessResumeTimerRef.current = null;
+    }
+  }, []);
+  useEffect(() => {
+    return () => {
+      if (deliveryTimerRef.current) {
+        clearTimeout(deliveryTimerRef.current);
+        deliveryTimerRef.current = null;
+      }
+      if (pingTimeoutRef.current) {
+        clearTimeout(pingTimeoutRef.current);
+        pingTimeoutRef.current = null;
+      }
+      clearDeferredLivenessProbe();
+    };
+  }, [clearDeferredLivenessProbe]);
+  const runLivenessProbe = useCallback(() => {
+    if (Platform3.OS !== "android") return;
+    const ref = nativeWebViewRef.current;
+    if (!ref || !internalSagepilotChat.isPresented()) return;
+    const pauseRemainingMs = livenessPausedUntilRef.current - Date.now();
+    if (pickerInFlightRef.current || pauseRemainingMs > 0) {
+      const retryDelayMs = pickerInFlightRef.current ? 500 : Math.max(0, pauseRemainingMs);
+      debugProvider("liveness probe deferred after picker", {
+        pickerInFlight: pickerInFlightRef.current,
+        retryDelayMs
+      });
+      clearDeferredLivenessProbe();
+      livenessResumeTimerRef.current = setTimeout(() => {
+        livenessResumeTimerRef.current = null;
+        runLivenessProbe();
+      }, retryDelayMs);
+      return;
+    }
+    setAndroidRepaintTick((tick) => tick + 1);
+    const attempts = (pendingPingRef.current?.attempts ?? 0) + 1;
+    const nonce = `${Date.now().toString(36)}_${attempts}`;
+    pendingPingRef.current = { nonce, attempts };
+    ref.injectJavaScript(buildLivenessPingScript(nonce, LIVENESS_HEARTBEAT_STALE_MS));
+    if (pingTimeoutRef.current) clearTimeout(pingTimeoutRef.current);
+    pingTimeoutRef.current = setTimeout(() => {
+      if (attempts >= LIVENESS_MAX_PING_ATTEMPTS) {
+        clearPing();
+        recoverNativeWebView("liveness_timeout");
+        return;
+      }
+      runLivenessProbe();
+    }, LIVENESS_PONG_TIMEOUT_MS);
+  }, [clearDeferredLivenessProbe, clearPing, recoverNativeWebView]);
+  useEffect(() => {
+    const subscription = AppState.addEventListener("change", (nextState) => {
+      const prev = appStateRef.current;
+      appStateRef.current = nextState;
+      if (nextState === "active" && (prev === "background" || prev === "inactive")) {
+        clearPing();
+        livenessRemountCountRef.current = 0;
+        runLivenessProbe();
+        ensureDelivery();
+      }
+    });
+    return () => {
+      subscription.remove();
+      clearPing();
+    };
+  }, [clearPing, runLivenessProbe, ensureDelivery]);
   const handleAndroidInsetsChange = useCallback((event) => {
     const nextBottomInset = event.nativeEvent?.bottom;
     const nextTopInset = event.nativeEvent?.top;
@@ -1360,11 +2382,11 @@ function SagepilotChatProvider({
   const presentationStyle = state.presentation?.style ?? "sheet";
   const isFullScreenModal = presentationStyle === "fullScreen";
   const animationType = presentationStyle === "fullScreen" || presentationStyle === "push" ? "slide" : "fade";
-  const ModalContainer = Platform.OS === "ios" && isFullScreenModal ? SafeAreaView : View;
-  const NativeModalContainer = Platform.OS === "android" ? AndroidInsetsView : ModalContainer;
-  const ChatContentContainer = Platform.OS === "ios" ? KeyboardAvoidingView : View;
-  const nativeModalContainerProps = Platform.OS === "android" ? { style: styles.container, onInsetsChange: handleAndroidInsetsChange } : { style: styles.container };
-  const chatContentContainerProps = Platform.OS === "ios" ? {
+  const ModalContainer = Platform3.OS === "ios" && isFullScreenModal ? SafeAreaView : View;
+  const NativeModalContainer = Platform3.OS === "android" ? AndroidInsetsView : ModalContainer;
+  const ChatContentContainer = Platform3.OS === "ios" ? KeyboardAvoidingView : View;
+  const nativeModalContainerProps = Platform3.OS === "android" ? { style: styles.container, onInsetsChange: handleAndroidInsetsChange } : { style: styles.container };
+  const chatContentContainerProps = Platform3.OS === "ios" ? {
     behavior: "padding",
     enabled: true,
     keyboardVerticalOffset: 0,
@@ -1372,14 +2394,57 @@ function SagepilotChatProvider({
   } : {
     style: [
       styles.modalContent,
-      Platform.OS === "android" ? {
+      Platform3.OS === "android" ? {
         paddingTop: androidModalInsets.top,
         paddingBottom: androidModalInsets.bottom
       } : null
     ].filter(Boolean)
   };
   const handleWebViewMessage = (event) => {
-    internalSagepilotChat.handleHostedBridgeMessage(parseHostedBridgeMessage(event.nativeEvent?.data));
+    const message = parseHostedBridgeMessage(event.nativeEvent?.data);
+    if (message?.type === "sagepilot:open_file_picker") {
+      openNativeFilePicker(message.multiple ?? true);
+      return;
+    }
+    if (message?.type === "sagepilot:widget_listener_ready") {
+      widgetReadyRef.current = true;
+      startDelivery();
+      return;
+    }
+    if (message?.type === "sagepilot:files_received") {
+      const ackBatchId = message.batch_id;
+      const head = pendingBatchesRef.current[0];
+      if (head && (!ackBatchId || ackBatchId === head.batchId)) {
+        debugProvider("native picked files acknowledged", {
+          batchId: head.batchId,
+          ackBatchId,
+          count: message.count
+        });
+        acknowledgeHeadBatch();
+      }
+      return;
+    }
+    if (message?.type === "sagepilot:pong") {
+      const pending = pendingPingRef.current;
+      if (pending && (!message.nonce || message.nonce === pending.nonce)) {
+        if (message.alive === false) {
+          clearPing();
+          debugProvider("liveness probe reported dead widget", {
+            supportsHeartbeat: message.supportsHeartbeat,
+            remountCount: livenessRemountCountRef.current
+          });
+          if (livenessRemountCountRef.current < LIVENESS_MAX_REMOUNTS) {
+            livenessRemountCountRef.current += 1;
+            recoverNativeWebView("liveness_dead_pong");
+          }
+        } else {
+          livenessRemountCountRef.current = 0;
+          clearPing();
+        }
+      }
+      return;
+    }
+    internalSagepilotChat.handleHostedBridgeMessage(message);
   };
   const postIdentityToWebFrame = () => {
     const message = internalSagepilotChat.getHostedIdentityMessage();
@@ -1392,8 +2457,31 @@ function SagepilotChatProvider({
     if (!script || !nativeWebViewRef.current) return;
     nativeWebViewRef.current.injectJavaScript(script);
   };
+  const injectNativeBridgeToNativeWebView = () => {
+    if (!nativeWebViewRef.current) return;
+    nativeWebViewRef.current.injectJavaScript(getInjectedWebViewScript());
+  };
+  const handleNativeWebViewLoadEnd = () => {
+    debugProvider("native WebView load end");
+    injectNativeBridgeToNativeWebView();
+    postIdentityToNativeWebView();
+    widgetReadyRef.current = false;
+    startDelivery();
+  };
+  const handleShouldStartLoadWithRequest = useCallback((request) => {
+    const url = request?.url ?? "";
+    if (!url || request?.isTopFrame === false || isInternalWebViewScheme(url)) {
+      return true;
+    }
+    const widgetOrigin = readUrlOrigin(state.conversationUrl ?? state.preloadUrl);
+    if (widgetOrigin && readUrlOrigin(url) === widgetOrigin) {
+      return true;
+    }
+    Linking2.openURL(url).catch(() => void 0);
+    return false;
+  }, [state.conversationUrl, state.preloadUrl]);
   useEffect(() => {
-    if (Platform.OS !== "web" || typeof window === "undefined") return;
+    if (Platform3.OS !== "web" || typeof window === "undefined") return;
     const trustedWidgetOrigin = readUrlOrigin(state.conversationUrl);
     if (!trustedWidgetOrigin) return;
     const handleWindowMessage = (event) => {
@@ -1404,14 +2492,14 @@ function SagepilotChatProvider({
     return () => window.removeEventListener("message", handleWindowMessage);
   }, [state.conversationUrl]);
   useEffect(() => {
-    if (Platform.OS !== "web" || !state.isPresented) return;
+    if (Platform3.OS !== "web" || !state.isPresented) return;
     postIdentityToWebFrame();
   }, [state.isPresented, state.conversationUrl, state.configured]);
   useEffect(() => {
-    if (Platform.OS === "web" || !state.isPresented) return;
+    if (Platform3.OS === "web" || !state.isPresented) return;
     postIdentityToNativeWebView();
   }, [state.isPresented, state.conversationUrl, state.configured]);
-  if (Platform.OS === "web") {
+  if (Platform3.OS === "web") {
     return createElement(
       View,
       { style: styles.root },
@@ -1454,10 +2542,18 @@ function SagepilotChatProvider({
     children,
     state.configured && !state.isPresented && state.shouldPreload && state.preloadUrl ? createElement(WebView, {
       ...hostedChatWebViewProps,
+      // Separate key from the hosted WebView: a hidden-preload renderer crash
+      // must not bump the hosted key (which would reset widgetReadyRef and
+      // disrupt an in-flight delivery). onRenderProcessGone must still be
+      // handled here or an unhandled renderer kill crashes the whole app.
+      key: `sagepilot-preload-webview-${preloadWebViewKey}`,
       source: { uri: state.preloadUrl },
       style: styles.preloadWebview,
       injectedJavaScriptBeforeContentLoaded: getInjectedWebViewScript(),
-      onMessage: handleWebViewMessage
+      onMessage: handleWebViewMessage,
+      onShouldStartLoadWithRequest: handleShouldStartLoadWithRequest,
+      onRenderProcessGone: recoverPreloadWebView,
+      onContentProcessDidTerminate: recoverPreloadWebView
     }) : null,
     createElement(
       Modal,
@@ -1465,8 +2561,8 @@ function SagepilotChatProvider({
         visible: state.configured && state.isPresented,
         animationType,
         presentationStyle: isFullScreenModal ? "fullScreen" : "pageSheet",
-        statusBarTranslucent: Platform.OS === "android",
-        navigationBarTranslucent: Platform.OS === "android",
+        statusBarTranslucent: Platform3.OS === "android",
+        navigationBarTranslucent: Platform3.OS === "android",
         onRequestClose: () => internalSagepilotChat.dismiss()
       },
       createElement(
@@ -1491,13 +2587,23 @@ function SagepilotChatProvider({
           ) : null,
           state.conversationUrl ? createElement(WebView, {
             ...hostedChatWebViewProps,
+            key: `sagepilot-hosted-webview-${nativeWebViewKey}`,
             ref: nativeWebViewRef,
             source: { uri: state.conversationUrl },
-            style: styles.webview,
+            // The imperceptible opacity toggle forces the Android WebView
+            // surface to re-composite on resume, clearing the blank-but-alive
+            // surface bug without a reload (see runLivenessProbe).
+            style: Platform3.OS === "android" ? [styles.webview, { opacity: 1 - androidRepaintTick % 2 * 1e-3 }] : styles.webview,
             startInLoadingState: true,
             injectedJavaScriptBeforeContentLoaded: getInjectedWebViewScript(),
             onMessage: handleWebViewMessage,
-            onLoadEnd: postIdentityToNativeWebView,
+            onLoadEnd: handleNativeWebViewLoadEnd,
+            onShouldStartLoadWithRequest: handleShouldStartLoadWithRequest,
+            // Android: render process killed (commonly while the camera/file
+            // chooser activity is foregrounded). Remount to recover.
+            onRenderProcessGone: recoverNativeWebView,
+            // iOS equivalent: WKWebView content process terminated.
+            onContentProcessDidTerminate: recoverNativeWebView,
             renderLoading: () => createElement(
               View,
               { style: styles.loading },
@@ -1507,6 +2613,59 @@ function SagepilotChatProvider({
           }) : null
         )
       )
+    ),
+    // Native attachment-source chooser. Replaces the Android Alert (capped at
+    // 3 buttons) so camera/library/documents all show on every platform.
+    createElement(
+      Modal,
+      {
+        visible: sourceChooser !== null,
+        transparent: true,
+        animationType: "fade",
+        statusBarTranslucent: true,
+        onRequestClose: () => setSourceChooser(null)
+      },
+      createElement(
+        Pressable,
+        { style: styles.sheetBackdrop, onPress: () => setSourceChooser(null) },
+        createElement(
+          View,
+          { style: styles.sheetCard },
+          createElement(View, { style: styles.sheetHandle }),
+          createElement(Text, { style: styles.sheetTitle }, "Add attachment"),
+          ...(internalSagepilotChat.getConfig()?.filePicker?.sources ?? []).map(
+            (source) => createElement(
+              Pressable,
+              {
+                key: source,
+                accessibilityRole: "button",
+                android_ripple: { color: "rgba(15, 23, 42, 0.06)" },
+                hitSlop: 4,
+                style: ({ pressed }) => getSheetOptionStyle(pressed),
+                onPress: () => handleSourceChoice(source)
+              },
+              renderFilePickerSourceIcon(source),
+              createElement(
+                View,
+                { style: styles.sheetOptionText },
+                createElement(Text, { style: styles.sheetButtonText }, FILE_PICKER_SOURCE_LABELS[source]),
+                createElement(Text, { style: styles.sheetButtonDescription }, FILE_PICKER_SOURCE_DESCRIPTIONS[source])
+              )
+            )
+          ),
+          createElement(
+            Pressable,
+            {
+              accessibilityRole: "button",
+              android_ripple: { color: "rgba(15, 23, 42, 0.06)" },
+              style: ({ pressed }) => getSheetCancelStyle(pressed),
+              onPress: () => setSourceChooser(null)
+            },
+            createElement(X, { color: "#334155", size: 18, strokeWidth: 2.5, style: styles.sheetCancelIcon }),
+            createElement(Text, { style: styles.sheetCancelText }, "Cancel")
+          )
+        )
+      )
     )
   );
 }
@@ -1605,6 +2764,112 @@ var styles = StyleSheet.create({
     marginTop: 12,
     color: "#4b5563",
     fontSize: 14
+  },
+  sheetBackdrop: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "flex-end",
+    backgroundColor: "rgba(15, 23, 42, 0.48)"
+  },
+  sheetCard: {
+    width: "100%",
+    maxWidth: 540,
+    backgroundColor: "#ffffff",
+    borderTopLeftRadius: 26,
+    borderTopRightRadius: 26,
+    paddingTop: 10,
+    paddingBottom: 18,
+    paddingHorizontal: 14,
+    shadowColor: "#0f172a",
+    shadowOpacity: 0.22,
+    shadowRadius: 28,
+    shadowOffset: { width: 0, height: -10 },
+    elevation: 18
+  },
+  sheetHandle: {
+    alignSelf: "center",
+    width: 42,
+    height: 5,
+    borderRadius: 999,
+    backgroundColor: "#d1d5db",
+    marginBottom: 14
+  },
+  sheetTitle: {
+    color: "#111827",
+    fontSize: 17,
+    fontWeight: "700",
+    paddingBottom: 12,
+    paddingHorizontal: 4
+  },
+  sheetOption: {
+    minHeight: 70,
+    flexDirection: "row",
+    alignItems: "center",
+    borderRadius: 18,
+    paddingHorizontal: 12,
+    marginBottom: 6,
+    backgroundColor: "#ffffff"
+  },
+  sheetOptionPressed: {
+    backgroundColor: "#f8fafc",
+    transform: [{ scale: 0.985 }]
+  },
+  sheetOptionIcon: {
+    width: 46,
+    height: 46,
+    borderRadius: 16,
+    marginRight: 14,
+    alignItems: "center",
+    justifyContent: "center",
+    position: "relative",
+    overflow: "hidden"
+  },
+  sheetOptionText: {
+    flex: 1,
+    justifyContent: "center"
+  },
+  sheetButtonText: {
+    color: "#0f172a",
+    fontSize: 16,
+    fontWeight: "700"
+  },
+  sheetButtonDescription: {
+    color: "#64748b",
+    fontSize: 13,
+    fontWeight: "500",
+    marginTop: 3
+  },
+  cameraOptionIcon: {
+    backgroundColor: "#e0f2fe"
+  },
+  libraryOptionIcon: {
+    backgroundColor: "#ecfdf5"
+  },
+  documentsOptionIcon: {
+    backgroundColor: "#f5f3ff"
+  },
+  sheetCancelButton: {
+    minHeight: 56,
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 18,
+    marginTop: 8,
+    backgroundColor: "#f1f5f9"
+  },
+  sheetCancelButtonPressed: {
+    backgroundColor: "#e2e8f0",
+    transform: [{ scale: 0.985 }]
+  },
+  sheetCancelIcon: {
+    width: 18,
+    height: 18,
+    marginRight: 8
+  },
+  sheetCancelText: {
+    color: "#0f172a",
+    fontSize: 16,
+    fontWeight: "700"
   }
 });
 
@@ -1658,10 +2923,18 @@ function useSagepilotChat() {
   };
 }
 export {
+  SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION,
+  SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES,
+  SAGEPILOT_DEFAULT_IMAGE_QUALITY,
   SagepilotChat,
   SagepilotChatError,
   SagepilotChatProvider,
+  SagepilotFilePickerError,
   createAsyncStorageCacheStorage,
   createKeychainTokenStorage,
+  createSagepilotFilePicker,
+  createSagepilotFileStore,
+  ensureSagepilotAndroidCameraPermission,
+  promptOpenSagepilotCameraSettings,
   useSagepilotChat
 };