@reverbia/sdk 1.0.0-next.20260109181949 → 1.0.0-next.20260110155148

package/dist/expo/index.cjs

@@ -1642,6 +1642,34 @@ function useChatStorage(options) {
         if (!content) {
           return extractedSources;
         }
+        const jsonBlockRegex = /```(?:json)?\s*(\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\})\s*```/g;
+        let jsonMatch;
+        let foundJsonSources = false;
+        while ((jsonMatch = jsonBlockRegex.exec(content)) !== null) {
+          if (jsonMatch[1]) {
+            try {
+              const parsed = JSON.parse(jsonMatch[1]);
+              if (Array.isArray(parsed.sources)) {
+                foundJsonSources = true;
+                for (const source of parsed.sources) {
+                  if (source.url && !seenUrls.has(source.url)) {
+                    seenUrls.add(source.url);
+                    extractedSources.push({
+                      title: source.title || void 0,
+                      url: source.url,
+                      // Map 'description' from JSON to 'snippet' in SearchSource type
+                      snippet: source.description || source.snippet || void 0
+                    });
+                  }
+                }
+              }
+            } catch {
+            }
+          }
+        }
+        if (foundJsonSources) {
+          return extractedSources;
+        }
         const markdownLinkRegex = /\[([^\]]*)\]\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
         const plainUrlRegex = /https?:\/\/[^\s<>\[\]()'"]+/g;
         let match;
@@ -1889,12 +1917,15 @@ function useChatStorage(options) {
         content: assistantContent,
         sources
       });
+      const jsonSourcesBlockRegex = /```(?:json)?\s*\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\}\s*```/g;
+      let cleanedContent = assistantContent.replace(jsonSourcesBlockRegex, "").trim();
+      cleanedContent = cleanedContent.replace(/\n{3,}/g, "\n\n");
       let storedAssistantMessage;
       try {
         storedAssistantMessage = await createMessageOp(storageCtx, {
           conversationId: convId,
           role: "assistant",
-          content: assistantContent,
+          content: cleanedContent,
           model: responseData.model || model,
           usage: convertUsageToStored(responseData.usage),
           responseDuration,

package/dist/expo/index.d.mts

@@ -777,12 +777,38 @@ declare function generateCompositeKey(namespace: string, key: string): string;
 declare function generateUniqueKey(namespace: string, key: string, value: string): string;
 
 type ChatRole = "user" | "assistant" | "system";
+/**
+ * Metadata for files attached to messages.
+ *
+ * Note the distinction between `url` and `sourceUrl`:
+ * - `url`: Content URL that gets sent to the AI as part of the message (e.g., data URIs for user uploads)
+ * - `sourceUrl`: Original external URL for locally-cached files (for lookup only, never sent to AI)
+ */
 interface FileMetadata {
+    /** Unique identifier for the file (used as OPFS key for cached files) */
     id: string;
+    /** Display name of the file */
     name: string;
+    /** MIME type (e.g., "image/png") */
     type: string;
+    /** File size in bytes */
     size: number;
+    /**
+     * Content URL to include when sending this message to the AI.
+     * When present, this URL is added as an `image_url` content part.
+     * Typically used for user-uploaded files (data URIs) that should be sent with the message.
+     *
+     * NOT used for MCP-cached files - those use `sourceUrl` for lookup and render from OPFS.
+     */
     url?: string;
+    /**
+     * Original external URL for files downloaded and cached locally (e.g., from MCP R2).
+     * Used purely for URL→OPFS mapping to enable fallback when the source returns 404.
+     *
+     * This is metadata for local lookup only - it is NOT sent to the AI or rendered directly.
+     * The file content is served from OPFS using the `id` field.
+     */
+    sourceUrl?: string;
 }
 interface ChatCompletionUsage {
     promptTokens?: number;

package/dist/expo/index.d.ts

@@ -777,12 +777,38 @@ declare function generateCompositeKey(namespace: string, key: string): string;
 declare function generateUniqueKey(namespace: string, key: string, value: string): string;
 
 type ChatRole = "user" | "assistant" | "system";
+/**
+ * Metadata for files attached to messages.
+ *
+ * Note the distinction between `url` and `sourceUrl`:
+ * - `url`: Content URL that gets sent to the AI as part of the message (e.g., data URIs for user uploads)
+ * - `sourceUrl`: Original external URL for locally-cached files (for lookup only, never sent to AI)
+ */
 interface FileMetadata {
+    /** Unique identifier for the file (used as OPFS key for cached files) */
     id: string;
+    /** Display name of the file */
     name: string;
+    /** MIME type (e.g., "image/png") */
     type: string;
+    /** File size in bytes */
     size: number;
+    /**
+     * Content URL to include when sending this message to the AI.
+     * When present, this URL is added as an `image_url` content part.
+     * Typically used for user-uploaded files (data URIs) that should be sent with the message.
+     *
+     * NOT used for MCP-cached files - those use `sourceUrl` for lookup and render from OPFS.
+     */
     url?: string;
+    /**
+     * Original external URL for files downloaded and cached locally (e.g., from MCP R2).
+     * Used purely for URL→OPFS mapping to enable fallback when the source returns 404.
+     *
+     * This is metadata for local lookup only - it is NOT sent to the AI or rendered directly.
+     * The file content is served from OPFS using the `id` field.
+     */
+    sourceUrl?: string;
 }
 interface ChatCompletionUsage {
     promptTokens?: number;

package/dist/expo/index.mjs

@@ -1606,6 +1606,34 @@ function useChatStorage(options) {
         if (!content) {
           return extractedSources;
         }
+        const jsonBlockRegex = /```(?:json)?\s*(\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\})\s*```/g;
+        let jsonMatch;
+        let foundJsonSources = false;
+        while ((jsonMatch = jsonBlockRegex.exec(content)) !== null) {
+          if (jsonMatch[1]) {
+            try {
+              const parsed = JSON.parse(jsonMatch[1]);
+              if (Array.isArray(parsed.sources)) {
+                foundJsonSources = true;
+                for (const source of parsed.sources) {
+                  if (source.url && !seenUrls.has(source.url)) {
+                    seenUrls.add(source.url);
+                    extractedSources.push({
+                      title: source.title || void 0,
+                      url: source.url,
+                      // Map 'description' from JSON to 'snippet' in SearchSource type
+                      snippet: source.description || source.snippet || void 0
+                    });
+                  }
+                }
+              }
+            } catch {
+            }
+          }
+        }
+        if (foundJsonSources) {
+          return extractedSources;
+        }
         const markdownLinkRegex = /\[([^\]]*)\]\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
         const plainUrlRegex = /https?:\/\/[^\s<>\[\]()'"]+/g;
         let match;
@@ -1853,12 +1881,15 @@ function useChatStorage(options) {
         content: assistantContent,
         sources
       });
+      const jsonSourcesBlockRegex = /```(?:json)?\s*\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\}\s*```/g;
+      let cleanedContent = assistantContent.replace(jsonSourcesBlockRegex, "").trim();
+      cleanedContent = cleanedContent.replace(/\n{3,}/g, "\n\n");
       let storedAssistantMessage;
       try {
         storedAssistantMessage = await createMessageOp(storageCtx, {
           conversationId: convId,
           role: "assistant",
-          content: assistantContent,
+          content: cleanedContent,
           model: responseData.model || model,
           usage: convertUsageToStored(responseData.usage),
           responseDuration,

package/dist/react/index.cjs

@@ -74,6 +74,7 @@ __export(index_exports, {
   encryptData: () => encryptData,
   exportPublicKey: () => exportPublicKey,
   extractConversationContext: () => extractConversationContext,
+  findFileIdBySourceUrl: () => findFileIdBySourceUrl,
   formatMemoriesForChat: () => formatMemoriesForChat,
   generateCompositeKey: () => generateCompositeKey,
   generateConversationId: () => generateConversationId,
@@ -101,6 +102,7 @@ __export(index_exports, {
   memoryStorageSchema: () => memoryStorageSchema,
   refreshCalendarToken: () => refreshCalendarToken,
   refreshDriveToken: () => refreshDriveToken,
+  replaceUrlWithMCPPlaceholder: () => replaceUrlWithMCPPlaceholder,
   requestEncryptionKey: () => requestEncryptionKey,
   requestKeyPair: () => requestKeyPair,
   revokeCalendarToken: () => revokeCalendarToken,
@@ -2828,6 +2830,26 @@ async function searchMessagesOp(ctx, queryVector, options) {
 }
 
 // src/react/useChatStorage.ts
+function replaceUrlWithMCPPlaceholder(content, url, fileId) {
+  const escapedUrl = url.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const placeholder = `![MCP_IMAGE:${fileId}]`;
+  let result = content;
+  const markdownImagePattern = new RegExp(
+    `!\\[[^\\]]*\\]\\([\\s]*${escapedUrl}[\\s]*\\)`,
+    "g"
+  );
+  result = result.replace(markdownImagePattern, placeholder);
+  result = result.replace(new RegExp(escapedUrl, "g"), placeholder);
+  const orphanedMarkdownPattern = new RegExp(
+    `!\\[[^\\]]*\\]\\([\\s]*\\!\\[MCP_IMAGE:${fileId}\\][\\s]*\\)`,
+    "g"
+  );
+  result = result.replace(orphanedMarkdownPattern, placeholder);
+  return result;
+}
+function findFileIdBySourceUrl(files, sourceUrl) {
+  return files?.find((f) => f.sourceUrl === sourceUrl)?.id;
+}
 function storedToLlmapiMessage(stored) {
   const content = [
     { type: "text", text: stored.content }
@@ -2987,6 +3009,34 @@ function useChatStorage(options) {
         if (!content) {
           return extractedSources;
         }
+        const jsonBlockRegex = /```(?:json)?\s*(\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\})\s*```/g;
+        let jsonMatch;
+        let foundJsonSources = false;
+        while ((jsonMatch = jsonBlockRegex.exec(content)) !== null) {
+          if (jsonMatch[1]) {
+            try {
+              const parsed = JSON.parse(jsonMatch[1]);
+              if (Array.isArray(parsed.sources)) {
+                foundJsonSources = true;
+                for (const source of parsed.sources) {
+                  if (source.url && !seenUrls.has(source.url)) {
+                    seenUrls.add(source.url);
+                    extractedSources.push({
+                      title: source.title || void 0,
+                      url: source.url,
+                      // Map 'description' from JSON to 'snippet' in SearchSource type
+                      snippet: source.description || source.snippet || void 0
+                    });
+                  }
+                }
+              }
+            } catch {
+            }
+          }
+        }
+        if (foundJsonSources) {
+          return extractedSources;
+        }
         const markdownLinkRegex = /\[([^\]]*)\]\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
         const plainUrlRegex = /(?<![(\[])https?:\/\/[^\s<>\[\]()'"]+(?<![.,;:!?])/g;
         let match;
@@ -3026,7 +3076,8 @@ function useChatStorage(options) {
     []
   );
   const extractAndStoreMCPImages = (0, import_react2.useCallback)(
-    async (content, writeFile) => {
+    async (content, writeFile, options2) => {
+      const { replaceUrls = true } = options2 ?? {};
       try {
         const MCP_IMAGE_URL_PATTERN = new RegExp(
           `https://${MCP_R2_DOMAIN.replace(/\./g, "\\.")}[^\\s)]*`,
@@ -3100,9 +3151,10 @@ function useChatStorage(options) {
               id: fileId,
               name: fileName,
               type: mimeType,
-              size
+              size,
+              sourceUrl: imageUrl
             });
-            if (imageUrl) {
+            if (replaceUrls && imageUrl) {
               replaceUrlWithPlaceholder(imageUrl, fileId);
             }
           } else {
@@ -3312,11 +3364,13 @@ function useChatStorage(options) {
         content: assistantContent,
         sources
       }).filter((source) => !source.url?.includes(MCP_R2_DOMAIN));
+      const jsonSourcesBlockRegex = /```(?:json)?\s*\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\}\s*```/g;
+      let cleanedContent = assistantContent.replace(jsonSourcesBlockRegex, "").trim();
+      cleanedContent = cleanedContent.replace(/\n{3,}/g, "\n\n");
       let processedFiles = [];
-      let cleanedContent = assistantContent;
       if (writeFile) {
         const result2 = await extractAndStoreMCPImages(
-          assistantContent,
+          cleanedContent,
           writeFile
         );
         processedFiles = result2.processedFiles;
@@ -9157,6 +9211,7 @@ function hasDriveCredentials() {
   encryptData,
   exportPublicKey,
   extractConversationContext,
+  findFileIdBySourceUrl,
   formatMemoriesForChat,
   generateCompositeKey,
   generateConversationId,
@@ -9184,6 +9239,7 @@ function hasDriveCredentials() {
   memoryStorageSchema,
   refreshCalendarToken,
   refreshDriveToken,
+  replaceUrlWithMCPPlaceholder,
   requestEncryptionKey,
   requestKeyPair,
   revokeCalendarToken,

package/dist/react/index.d.mts

@@ -1423,12 +1423,38 @@ declare function generateCompositeKey(namespace: string, key: string): string;
 declare function generateUniqueKey(namespace: string, key: string, value: string): string;
 
 type ChatRole = "user" | "assistant" | "system";
+/**
+ * Metadata for files attached to messages.
+ *
+ * Note the distinction between `url` and `sourceUrl`:
+ * - `url`: Content URL that gets sent to the AI as part of the message (e.g., data URIs for user uploads)
+ * - `sourceUrl`: Original external URL for locally-cached files (for lookup only, never sent to AI)
+ */
 interface FileMetadata {
+    /** Unique identifier for the file (used as OPFS key for cached files) */
     id: string;
+    /** Display name of the file */
     name: string;
+    /** MIME type (e.g., "image/png") */
     type: string;
+    /** File size in bytes */
     size: number;
+    /**
+     * Content URL to include when sending this message to the AI.
+     * When present, this URL is added as an `image_url` content part.
+     * Typically used for user-uploaded files (data URIs) that should be sent with the message.
+     *
+     * NOT used for MCP-cached files - those use `sourceUrl` for lookup and render from OPFS.
+     */
     url?: string;
+    /**
+     * Original external URL for files downloaded and cached locally (e.g., from MCP R2).
+     * Used purely for URL→OPFS mapping to enable fallback when the source returns 404.
+     *
+     * This is metadata for local lookup only - it is NOT sent to the AI or rendered directly.
+     * The file content is served from OPFS using the `id` field.
+     */
+    sourceUrl?: string;
 }
 interface ChatCompletionUsage {
     promptTokens?: number;
@@ -1744,6 +1770,39 @@ declare class Conversation extends Model {
     isDeleted: boolean;
 }
 
+/**
+ * Replace a URL in content with an MCP_IMAGE placeholder.
+ * This is used to swap external URLs with locally-stored file references.
+ *
+ * @param content - The message content containing the URL
+ * @param url - The URL to replace
+ * @param fileId - The OPFS file ID to reference
+ * @returns The content with the URL replaced by ![MCP_IMAGE:fileId]
+ *
+ * @example
+ * ```ts
+ * // Replace a URL that returned 404 with local file reference
+ * const newContent = replaceUrlWithMCPPlaceholder(
+ *   message.content,
+ *   "https://example.com/image.png",
+ *   "abc-123-def"
+ * );
+ * await updateMessage(message.uniqueId, { content: newContent });
+ * ```
+ */
+declare function replaceUrlWithMCPPlaceholder(content: string, url: string, fileId: string): string;
+/**
+ * Find the OPFS file ID for a given source URL from a message's files.
+ * Used to look up local file storage when an external URL fails (e.g., 404).
+ *
+ * @param files - Array of FileMetadata from a stored message
+ * @param sourceUrl - The original URL to look up
+ * @returns The file ID if found, or undefined
+ */
+declare function findFileIdBySourceUrl(files: {
+    id: string;
+    sourceUrl?: string;
+}[] | undefined, sourceUrl: string): string | undefined;
 /**
  * Options for useChatStorage hook (React version)
  *
@@ -3742,4 +3801,4 @@ declare function storeDriveToken(accessToken: string, expiresIn?: number, refres
  */
 declare function hasDriveCredentials(): boolean;
 
-export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as BACKUP_ICLOUD_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateUserPreferenceOptions, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_DROPBOX_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_ICLOUD_BACKUP_FOLDER, DEFAULT_PERSONALITY_SETTINGS, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type EmbeddedWalletSignerFn, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type ICloudAuthContextValue, ICloudAuthProvider, type ICloudAuthProviderProps, type ICloudExportResult, type ICloudImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type ProfileUpdate, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, SLIDER_CONFIG, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type StoredUserPreference, UserPreference as StoredUserPreferenceModel, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UpdateUserPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseEncryptionResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseICloudBackupOptions, type UseICloudBackupResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsResult, type UseOCRResult, type UsePdfResult, type UseSearchResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearAllEncryptionKeys, clearAllKeyPairs, clearCalendarToken, clearDriveToken, clearToken as clearDropboxToken, clearEncryptionKey, clearGoogleDriveToken, clearICloudAuth, clearKeyPair, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, exportPublicKey, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getAndClearCalendarPendingMessage, getAndClearCalendarReturnUrl, getAndClearDrivePendingMessage, getAndClearDriveReturnUrl, getCalendarAccessToken, getDriveAccessToken, getGoogleDriveStoredToken, getValidCalendarToken, getValidDriveToken, handleCalendarCallback, handleDriveCallback, hasCalendarCredentials, hasDriveCredentials, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, hasICloudCredentials, hasKeyPair, isCalendarCallback, isDriveCallback, memoryStorageSchema, refreshCalendarToken, refreshDriveToken, requestEncryptionKey, requestKeyPair, revokeCalendarToken, revokeDriveToken, sdkMigrations, sdkModelClasses, sdkSchema, settingsStorageSchema, startCalendarAuth, startDriveAuth, storeCalendarPendingMessage, storeCalendarReturnUrl, storeCalendarToken, storeDrivePendingMessage, storeDriveReturnUrl, storeDriveToken, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useICloudAuth, useICloudBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings, userPreferencesStorageSchema };
+export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as BACKUP_ICLOUD_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateUserPreferenceOptions, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_DROPBOX_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_ICLOUD_BACKUP_FOLDER, DEFAULT_PERSONALITY_SETTINGS, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type EmbeddedWalletSignerFn, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type ICloudAuthContextValue, ICloudAuthProvider, type ICloudAuthProviderProps, type ICloudExportResult, type ICloudImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type ProfileUpdate, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, SLIDER_CONFIG, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type StoredUserPreference, UserPreference as StoredUserPreferenceModel, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UpdateUserPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseEncryptionResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseICloudBackupOptions, type UseICloudBackupResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsResult, type UseOCRResult, type UsePdfResult, type UseSearchResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearAllEncryptionKeys, clearAllKeyPairs, clearCalendarToken, clearDriveToken, clearToken as clearDropboxToken, clearEncryptionKey, clearGoogleDriveToken, clearICloudAuth, clearKeyPair, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, exportPublicKey, extractConversationContext, findFileIdBySourceUrl, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getAndClearCalendarPendingMessage, getAndClearCalendarReturnUrl, getAndClearDrivePendingMessage, getAndClearDriveReturnUrl, getCalendarAccessToken, getDriveAccessToken, getGoogleDriveStoredToken, getValidCalendarToken, getValidDriveToken, handleCalendarCallback, handleDriveCallback, hasCalendarCredentials, hasDriveCredentials, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, hasICloudCredentials, hasKeyPair, isCalendarCallback, isDriveCallback, memoryStorageSchema, refreshCalendarToken, refreshDriveToken, replaceUrlWithMCPPlaceholder, requestEncryptionKey, requestKeyPair, revokeCalendarToken, revokeDriveToken, sdkMigrations, sdkModelClasses, sdkSchema, settingsStorageSchema, startCalendarAuth, startDriveAuth, storeCalendarPendingMessage, storeCalendarReturnUrl, storeCalendarToken, storeDrivePendingMessage, storeDriveReturnUrl, storeDriveToken, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useICloudAuth, useICloudBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings, userPreferencesStorageSchema };

package/dist/react/index.d.ts

@@ -1423,12 +1423,38 @@ declare function generateCompositeKey(namespace: string, key: string): string;
 declare function generateUniqueKey(namespace: string, key: string, value: string): string;
 
 type ChatRole = "user" | "assistant" | "system";
+/**
+ * Metadata for files attached to messages.
+ *
+ * Note the distinction between `url` and `sourceUrl`:
+ * - `url`: Content URL that gets sent to the AI as part of the message (e.g., data URIs for user uploads)
+ * - `sourceUrl`: Original external URL for locally-cached files (for lookup only, never sent to AI)
+ */
 interface FileMetadata {
+    /** Unique identifier for the file (used as OPFS key for cached files) */
     id: string;
+    /** Display name of the file */
     name: string;
+    /** MIME type (e.g., "image/png") */
     type: string;
+    /** File size in bytes */
     size: number;
+    /**
+     * Content URL to include when sending this message to the AI.
+     * When present, this URL is added as an `image_url` content part.
+     * Typically used for user-uploaded files (data URIs) that should be sent with the message.
+     *
+     * NOT used for MCP-cached files - those use `sourceUrl` for lookup and render from OPFS.
+     */
     url?: string;
+    /**
+     * Original external URL for files downloaded and cached locally (e.g., from MCP R2).
+     * Used purely for URL→OPFS mapping to enable fallback when the source returns 404.
+     *
+     * This is metadata for local lookup only - it is NOT sent to the AI or rendered directly.
+     * The file content is served from OPFS using the `id` field.
+     */
+    sourceUrl?: string;
 }
 interface ChatCompletionUsage {
     promptTokens?: number;
@@ -1744,6 +1770,39 @@ declare class Conversation extends Model {
     isDeleted: boolean;
 }
 
+/**
+ * Replace a URL in content with an MCP_IMAGE placeholder.
+ * This is used to swap external URLs with locally-stored file references.
+ *
+ * @param content - The message content containing the URL
+ * @param url - The URL to replace
+ * @param fileId - The OPFS file ID to reference
+ * @returns The content with the URL replaced by ![MCP_IMAGE:fileId]
+ *
+ * @example
+ * ```ts
+ * // Replace a URL that returned 404 with local file reference
+ * const newContent = replaceUrlWithMCPPlaceholder(
+ *   message.content,
+ *   "https://example.com/image.png",
+ *   "abc-123-def"
+ * );
+ * await updateMessage(message.uniqueId, { content: newContent });
+ * ```
+ */
+declare function replaceUrlWithMCPPlaceholder(content: string, url: string, fileId: string): string;
+/**
+ * Find the OPFS file ID for a given source URL from a message's files.
+ * Used to look up local file storage when an external URL fails (e.g., 404).
+ *
+ * @param files - Array of FileMetadata from a stored message
+ * @param sourceUrl - The original URL to look up
+ * @returns The file ID if found, or undefined
+ */
+declare function findFileIdBySourceUrl(files: {
+    id: string;
+    sourceUrl?: string;
+}[] | undefined, sourceUrl: string): string | undefined;
 /**
  * Options for useChatStorage hook (React version)
  *
@@ -3742,4 +3801,4 @@ declare function storeDriveToken(accessToken: string, expiresIn?: number, refres
  */
 declare function hasDriveCredentials(): boolean;
 
-export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as BACKUP_ICLOUD_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateUserPreferenceOptions, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_DROPBOX_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_ICLOUD_BACKUP_FOLDER, DEFAULT_PERSONALITY_SETTINGS, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type EmbeddedWalletSignerFn, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type ICloudAuthContextValue, ICloudAuthProvider, type ICloudAuthProviderProps, type ICloudExportResult, type ICloudImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type ProfileUpdate, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, SLIDER_CONFIG, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type StoredUserPreference, UserPreference as StoredUserPreferenceModel, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UpdateUserPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseEncryptionResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseICloudBackupOptions, type UseICloudBackupResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsResult, type UseOCRResult, type UsePdfResult, type UseSearchResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearAllEncryptionKeys, clearAllKeyPairs, clearCalendarToken, clearDriveToken, clearToken as clearDropboxToken, clearEncryptionKey, clearGoogleDriveToken, clearICloudAuth, clearKeyPair, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, exportPublicKey, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getAndClearCalendarPendingMessage, getAndClearCalendarReturnUrl, getAndClearDrivePendingMessage, getAndClearDriveReturnUrl, getCalendarAccessToken, getDriveAccessToken, getGoogleDriveStoredToken, getValidCalendarToken, getValidDriveToken, handleCalendarCallback, handleDriveCallback, hasCalendarCredentials, hasDriveCredentials, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, hasICloudCredentials, hasKeyPair, isCalendarCallback, isDriveCallback, memoryStorageSchema, refreshCalendarToken, refreshDriveToken, requestEncryptionKey, requestKeyPair, revokeCalendarToken, revokeDriveToken, sdkMigrations, sdkModelClasses, sdkSchema, settingsStorageSchema, startCalendarAuth, startDriveAuth, storeCalendarPendingMessage, storeCalendarReturnUrl, storeCalendarToken, storeDrivePendingMessage, storeDriveReturnUrl, storeDriveToken, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useICloudAuth, useICloudBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings, userPreferencesStorageSchema };
+export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as BACKUP_ICLOUD_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateUserPreferenceOptions, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_DROPBOX_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_ICLOUD_BACKUP_FOLDER, DEFAULT_PERSONALITY_SETTINGS, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type EmbeddedWalletSignerFn, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type ICloudAuthContextValue, ICloudAuthProvider, type ICloudAuthProviderProps, type ICloudExportResult, type ICloudImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type ProfileUpdate, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, SLIDER_CONFIG, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type StoredUserPreference, UserPreference as StoredUserPreferenceModel, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UpdateUserPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseEncryptionResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseICloudBackupOptions, type UseICloudBackupResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsResult, type UseOCRResult, type UsePdfResult, type UseSearchResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearAllEncryptionKeys, clearAllKeyPairs, clearCalendarToken, clearDriveToken, clearToken as clearDropboxToken, clearEncryptionKey, clearGoogleDriveToken, clearICloudAuth, clearKeyPair, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, exportPublicKey, extractConversationContext, findFileIdBySourceUrl, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getAndClearCalendarPendingMessage, getAndClearCalendarReturnUrl, getAndClearDrivePendingMessage, getAndClearDriveReturnUrl, getCalendarAccessToken, getDriveAccessToken, getGoogleDriveStoredToken, getValidCalendarToken, getValidDriveToken, handleCalendarCallback, handleDriveCallback, hasCalendarCredentials, hasDriveCredentials, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, hasICloudCredentials, hasKeyPair, isCalendarCallback, isDriveCallback, memoryStorageSchema, refreshCalendarToken, refreshDriveToken, replaceUrlWithMCPPlaceholder, requestEncryptionKey, requestKeyPair, revokeCalendarToken, revokeDriveToken, sdkMigrations, sdkModelClasses, sdkSchema, settingsStorageSchema, startCalendarAuth, startDriveAuth, storeCalendarPendingMessage, storeCalendarReturnUrl, storeCalendarToken, storeDrivePendingMessage, storeDriveReturnUrl, storeDriveToken, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useICloudAuth, useICloudBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings, userPreferencesStorageSchema };

package/dist/react/index.mjs

@@ -2701,6 +2701,26 @@ async function searchMessagesOp(ctx, queryVector, options) {
 }
 
 // src/react/useChatStorage.ts
+function replaceUrlWithMCPPlaceholder(content, url, fileId) {
+  const escapedUrl = url.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const placeholder = `![MCP_IMAGE:${fileId}]`;
+  let result = content;
+  const markdownImagePattern = new RegExp(
+    `!\\[[^\\]]*\\]\\([\\s]*${escapedUrl}[\\s]*\\)`,
+    "g"
+  );
+  result = result.replace(markdownImagePattern, placeholder);
+  result = result.replace(new RegExp(escapedUrl, "g"), placeholder);
+  const orphanedMarkdownPattern = new RegExp(
+    `!\\[[^\\]]*\\]\\([\\s]*\\!\\[MCP_IMAGE:${fileId}\\][\\s]*\\)`,
+    "g"
+  );
+  result = result.replace(orphanedMarkdownPattern, placeholder);
+  return result;
+}
+function findFileIdBySourceUrl(files, sourceUrl) {
+  return files?.find((f) => f.sourceUrl === sourceUrl)?.id;
+}
 function storedToLlmapiMessage(stored) {
   const content = [
     { type: "text", text: stored.content }
@@ -2860,6 +2880,34 @@ function useChatStorage(options) {
         if (!content) {
           return extractedSources;
         }
+        const jsonBlockRegex = /```(?:json)?\s*(\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\})\s*```/g;
+        let jsonMatch;
+        let foundJsonSources = false;
+        while ((jsonMatch = jsonBlockRegex.exec(content)) !== null) {
+          if (jsonMatch[1]) {
+            try {
+              const parsed = JSON.parse(jsonMatch[1]);
+              if (Array.isArray(parsed.sources)) {
+                foundJsonSources = true;
+                for (const source of parsed.sources) {
+                  if (source.url && !seenUrls.has(source.url)) {
+                    seenUrls.add(source.url);
+                    extractedSources.push({
+                      title: source.title || void 0,
+                      url: source.url,
+                      // Map 'description' from JSON to 'snippet' in SearchSource type
+                      snippet: source.description || source.snippet || void 0
+                    });
+                  }
+                }
+              }
+            } catch {
+            }
+          }
+        }
+        if (foundJsonSources) {
+          return extractedSources;
+        }
         const markdownLinkRegex = /\[([^\]]*)\]\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
         const plainUrlRegex = /(?<![(\[])https?:\/\/[^\s<>\[\]()'"]+(?<![.,;:!?])/g;
         let match;
@@ -2899,7 +2947,8 @@ function useChatStorage(options) {
     []
   );
   const extractAndStoreMCPImages = useCallback2(
-    async (content, writeFile) => {
+    async (content, writeFile, options2) => {
+      const { replaceUrls = true } = options2 ?? {};
       try {
         const MCP_IMAGE_URL_PATTERN = new RegExp(
           `https://${MCP_R2_DOMAIN.replace(/\./g, "\\.")}[^\\s)]*`,
@@ -2973,9 +3022,10 @@ function useChatStorage(options) {
               id: fileId,
               name: fileName,
               type: mimeType,
-              size
+              size,
+              sourceUrl: imageUrl
             });
-            if (imageUrl) {
+            if (replaceUrls && imageUrl) {
               replaceUrlWithPlaceholder(imageUrl, fileId);
             }
           } else {
@@ -3185,11 +3235,13 @@ function useChatStorage(options) {
         content: assistantContent,
         sources
       }).filter((source) => !source.url?.includes(MCP_R2_DOMAIN));
+      const jsonSourcesBlockRegex = /```(?:json)?\s*\{(?:(?!```)[^])*?"sources"(?:(?!```)[^])*?\}\s*```/g;
+      let cleanedContent = assistantContent.replace(jsonSourcesBlockRegex, "").trim();
+      cleanedContent = cleanedContent.replace(/\n{3,}/g, "\n\n");
       let processedFiles = [];
-      let cleanedContent = assistantContent;
       if (writeFile) {
         const result2 = await extractAndStoreMCPImages(
-          assistantContent,
+          cleanedContent,
           writeFile
         );
         processedFiles = result2.processedFiles;
@@ -9062,6 +9114,7 @@ export {
   encryptData,
   exportPublicKey,
   extractConversationContext,
+  findFileIdBySourceUrl,
   formatMemoriesForChat,
   generateCompositeKey,
   generateConversationId,
@@ -9089,6 +9142,7 @@ export {
   memoryStorageSchema,
   refreshCalendarToken,
   refreshDriveToken,
+  replaceUrlWithMCPPlaceholder,
   requestEncryptionKey,
   requestKeyPair,
   revokeCalendarToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reverbia/sdk",
-  "version": "1.0.0-next.20260109181949",
+  "version": "1.0.0-next.20260110155148",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",