@jmruthers/pace-core 0.6.10 → 0.6.11

package/dist/{chunk-FBZ7U3ID.js → chunk-J2KQK6DG.js}

@@ -1,8 +1,9 @@
-import { clearPalette, parseAndNormalizeEventColours, applyPalette } from './chunk-JJEYZ3DX.js';
-import { EventServiceContext } from './chunk-Y4PF6HIM.js';
+import { EventServiceContext } from './chunk-4R3T5ENU.js';
+import { clearPalette, parseAndNormalizeEventColours, applyPalette } from './chunk-D6BMFMQZ.js';
 import { assertAppId } from './chunk-4SXLQIZO.js';
-import { fetchPlaceDetails, createAddressFromPlaceResult, getAddressByPlaceId, fetchPlaceAutocomplete, setOrganisationContext } from './chunk-7YDC7LMU.js';
+import { fetchPlaceDetails, createAddressFromPlaceResult, getAddressByPlaceId, fetchPlaceAutocomplete, setOrganisationContext } from './chunk-XPFVT3GN.js';
 import { createLogger, logger } from './chunk-BTHN5MKC.js';
+import { ok, err } from './chunk-44CNXN4P.js';
 import { useState, useEffect, useCallback, useMemo, useRef, useContext } from 'react';
 import { useLocation } from 'react-router-dom';
 
@@ -41,7 +42,6 @@ if (typeof window !== "undefined" && !cleanupTimer) {
     if (cleanupTimer) {
       clearInterval(cleanupTimer);
       cleanupTimer = null;
-      log.debug("Query cache cleanup timer cleared on page unload.");
     }
   });
 }
@@ -49,7 +49,6 @@ function cleanupQueryCache() {
   if (cleanupTimer) {
     clearInterval(cleanupTimer);
     cleanupTimer = null;
-    log.debug("Query cache cleanup timer cleared.");
   }
 }
 function useQueryCache(_supabase) {
@@ -200,6 +199,44 @@ var queryCacheHelpers = {
     return promise;
   }
 };
+async function fetchSuggestionsForInput(debouncedInput, apiKey, memoizedAutocompleteOptions, cacheEnabled, cacheTTLAutocomplete, getCachedQuery, isCancelledRef, setters) {
+  try {
+    let result;
+    if (cacheEnabled) {
+      result = await getCachedQuery(
+        "google-places-autocomplete",
+        "query",
+        debouncedInput,
+        async () => {
+          if (isCancelledRef.current) {
+            throw new Error("Request cancelled");
+          }
+          return fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+        },
+        { ttl: cacheTTLAutocomplete, enabled: true }
+      );
+    } else {
+      result = await fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+    }
+    if (isCancelledRef.current) return;
+    if (!result.ok) {
+      setters.setError(new Error(result.error.message));
+      setters.setSuggestions([]);
+      setters.setIsLoading(false);
+      return;
+    }
+    setters.setSuggestions(result.data);
+    setters.setIsLoading(false);
+  } catch (err2) {
+    if (isCancelledRef.current || err2 instanceof Error && err2.message === "Request cancelled") {
+      return;
+    }
+    const error = err2 instanceof Error ? err2 : new Error("Failed to fetch autocomplete suggestions");
+    setters.setError(error);
+    setters.setSuggestions([]);
+    setters.setIsLoading(false);
+  }
+}
 function useAddressAutocomplete(apiKey, inputValue, options = {}) {
   const {
     debounceDelay = 300,
@@ -244,45 +281,19 @@ function useAddressAutocomplete(apiKey, inputValue, options = {}) {
     }
     setIsLoading(true);
     setError(null);
-    let isCancelled = false;
-    const fetchSuggestions = async () => {
-      try {
-        let predictions;
-        if (cacheEnabled) {
-          predictions = await getCachedQuery(
-            "google-places-autocomplete",
-            "query",
-            debouncedInput,
-            async () => {
-              if (isCancelled) {
-                throw new Error("Request cancelled");
-              }
-              return fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
-            },
-            { ttl: cacheTTL.autocomplete, enabled: true }
-          );
-        } else {
-          predictions = await fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
-        }
-        if (!isCancelled) {
-          setSuggestions(predictions);
-          setIsLoading(false);
-        }
-      } catch (err) {
-        if (isCancelled || err instanceof Error && err.message === "Request cancelled") {
-          return;
-        }
-        if (!isCancelled) {
-          const error2 = err instanceof Error ? err : new Error("Failed to fetch autocomplete suggestions");
-          setError(error2);
-          setSuggestions([]);
-          setIsLoading(false);
-        }
-      }
-    };
-    fetchSuggestions();
+    const isCancelledRef = { current: false };
+    fetchSuggestionsForInput(
+      debouncedInput,
+      apiKey,
+      memoizedAutocompleteOptions,
+      cacheEnabled,
+      cacheTTL.autocomplete ?? 3600,
+      getCachedQuery,
+      isCancelledRef,
+      { setSuggestions, setError, setIsLoading }
+    );
     return () => {
-      isCancelled = true;
+      isCancelledRef.current = true;
     };
   }, [debouncedInput, apiKey, cacheEnabled, cacheTTL.autocomplete, memoizedAutocompleteOptions, getCachedQuery]);
   const selectAddress = useCallback(
@@ -293,25 +304,28 @@ function useAddressAutocomplete(apiKey, inputValue, options = {}) {
       setIsLoading(true);
       setError(null);
       try {
-        let placeDetails;
+        let placeResult;
         if (cacheEnabled) {
-          placeDetails = await getCachedQuery(
+          placeResult = await getCachedQuery(
             "google-places-details",
             "place_id",
             placeId,
-            async () => {
-              return fetchPlaceDetails(placeId, apiKey);
-            },
+            async () => fetchPlaceDetails(placeId, apiKey),
             { ttl: cacheTTL.placeDetails, enabled: true }
           );
         } else {
-          placeDetails = await fetchPlaceDetails(placeId, apiKey);
+          placeResult = await fetchPlaceDetails(placeId, apiKey);
+        }
+        if (!placeResult.ok) {
+          setError(new Error(placeResult.error.message));
+          setIsLoading(false);
+          return null;
         }
-        const parsedAddress = createAddressFromPlaceResult(placeDetails);
+        const parsedAddress = createAddressFromPlaceResult(placeResult.data);
         setIsLoading(false);
         return parsedAddress;
-      } catch (err) {
-        const error2 = err instanceof Error ? err : new Error("Failed to fetch place details");
+      } catch (err2) {
+        const error2 = err2 instanceof Error ? err2 : new Error("Failed to fetch place details");
         setError(error2);
         setIsLoading(false);
         return null;
@@ -326,25 +340,25 @@ function useAddressAutocomplete(apiKey, inputValue, options = {}) {
         return null;
       }
       try {
+        let result;
         if (cacheEnabled) {
-          return await getCachedQuery(
+          result = await getCachedQuery(
             "google-places-details",
             "place_id",
             placeId,
-            async () => {
-              const result = await getAddressByPlaceId(placeId, apiKey);
-              if (!result) {
-                throw new Error("Failed to fetch address");
-              }
-              return result;
-            },
+            async () => getAddressByPlaceId(placeId, apiKey),
             { ttl: cacheTTL.placeDetails, enabled: true }
           );
         } else {
-          return await getAddressByPlaceId(placeId, apiKey);
+          result = await getAddressByPlaceId(placeId, apiKey);
         }
-      } catch (err) {
-        const error2 = err instanceof Error ? err : new Error("Failed to get address by place_id");
+        if (!result.ok) {
+          setError(new Error(result.error.message));
+          return null;
+        }
+        return result.data;
+      } catch (err2) {
+        const error2 = err2 instanceof Error ? err2 : new Error("Failed to get address by place_id");
         setError(error2);
         return null;
       }
@@ -467,31 +481,38 @@ function generateUniqueFileName(originalName) {
   return `${timestamp}-${uuid}-${baseName}.${extension}`;
 }
 async function extractFileMetadata(file, options, uploadedBy) {
-  const metadata = {
-    mimeType: file.type,
-    size: file.size,
-    ...options.orgId && { orgId: options.orgId },
-    ...options.userId && { userId: options.userId },
-    appName: options.appName || "pace-core",
-    uploadedBy,
-    uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    tags: options.tags || [],
-    isPublic: options.isPublic || false,
-    customMetadata: options.metadata || {}
-  };
-  if (file.type.startsWith("image/")) {
+  try {
+    const metadata = {
+      mimeType: file.type,
+      size: file.size,
+      ...options.orgId && { orgId: options.orgId },
+      ...options.userId && { userId: options.userId },
+      appName: options.appName || "pace-core",
+      uploadedBy,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tags: options.tags || [],
+      isPublic: options.isPublic || false,
+      customMetadata: options.metadata || {}
+    };
+    if (file.type.startsWith("image/")) {
+      try {
+        const dimensions = await getImageDimensions(file);
+        metadata.width = dimensions.width;
+        metadata.height = dimensions.height;
+      } catch (_error) {
+      }
+    }
     try {
-      const dimensions = await getImageDimensions(file);
-      metadata.width = dimensions.width;
-      metadata.height = dimensions.height;
+      metadata.hash = await generateFileHash(file);
     } catch (_error) {
     }
+    return ok(metadata);
+  } catch (error) {
+    return err({
+      code: "EXTRACT_METADATA_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
-  try {
-    metadata.hash = await generateFileHash(file);
-  } catch (_error) {
-  }
-  return metadata;
 }
 async function getImageDimensions(file) {
   return new Promise((resolve, reject) => {
@@ -546,44 +567,37 @@ async function uploadFile(supabase, file, options) {
   try {
     const sizeValidation = validateFileSize(file);
     if (!sizeValidation.isValid) {
-      return {
-        success: false,
-        error: sizeValidation.error
-      };
+      return err({ code: "FILE_SIZE_INVALID", message: sizeValidation.error ?? "File size validation failed" });
     }
     const uniqueFileName = generateUniqueFileName(file.name);
     const filePath = generateFilePath(options, uniqueFileName);
     const folderPath = filePath.substring(0, filePath.lastIndexOf("/"));
-    const metadata = await extractFileMetadata(file, options, "current-user");
+    const metadataResult = await extractFileMetadata(file, options, "current-user");
+    if (!metadataResult.ok) {
+      return err(metadataResult.error);
+    }
+    const metadata = metadataResult.data;
     const bucketName = getBucketName(options.isPublic || false);
     await ensureFolderExists(supabase, folderPath, bucketName);
-    const { data, error } = await supabase.storage.from(bucketName).upload(filePath, file, {
+    const { error } = await supabase.storage.from(bucketName).upload(filePath, file, {
       cacheControl: "3600",
       upsert: false,
       contentType: file.type
     });
     if (error) {
-      return {
-        success: false,
-        error: `Upload failed: ${error.message}`
-      };
+      return err({ code: "UPLOAD_FAILED", message: error.message });
     }
     let publicUrl;
     if (options.isPublic) {
       const { data: urlData } = supabase.storage.from(bucketName).getPublicUrl(filePath);
       publicUrl = urlData.publicUrl;
     }
-    return {
-      success: true,
-      path: filePath,
-      publicUrl,
-      metadata
-    };
+    return ok({ path: filePath, publicUrl, metadata });
   } catch (error) {
-    return {
-      success: false,
-      error: `Upload failed: ${error instanceof Error ? error.message : "Unknown error"}`
-    };
+    return err({
+      code: "UPLOAD_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 function getPublicUrl(supabase, path, isPublic = true) {
@@ -646,15 +660,18 @@ async function getSignedUrl(supabase, path, options) {
     const { data, error } = await supabase.storage.from(bucketName).createSignedUrl(path, options.expiresIn || 3600);
     if (error) {
       log2.error("Failed to create signed URL:", error);
-      return null;
+      return err({ code: "SIGNED_URL_FAILED", message: error.message });
     }
-    return {
+    return ok({
       url: data.signedUrl,
       expiresAt: new Date(Date.now() + (options.expiresIn || 3600) * 1e3).toISOString()
-    };
+    });
   } catch (error) {
     log2.error("Failed to create signed URL:", error);
-    return null;
+    return err({
+      code: "SIGNED_URL_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 var globalUrlCache = /* @__PURE__ */ new Map();
@@ -679,101 +696,94 @@ function cleanupUrlCache() {
   }
 }
 async function generateFileUrlsBatch(supabase, fileReferences, options) {
-  const urlMap = /* @__PURE__ */ new Map();
-  if (fileReferences.length === 0) {
-    return urlMap;
-  }
-  const now = Date.now();
-  const ttl = (options.expiresIn || 3600) * 1e3;
-  const publicFiles = [];
-  const privateFiles = [];
-  const uncachedFiles = [];
-  for (const fileRef of fileReferences) {
-    const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
-    const cached = globalUrlCache.get(cacheKey);
-    if (cached && cached.expiresAt > now) {
-      urlMap.set(fileRef.id, cached.url);
-      continue;
-    }
-    if (fileRef.is_public) {
-      publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
-    } else {
-      privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+  try {
+    const urlMap = /* @__PURE__ */ new Map();
+    if (fileReferences.length === 0) {
+      return ok(urlMap);
     }
-    uncachedFiles.push(fileRef);
-  }
-  for (const file of publicFiles) {
-    try {
-      const url = getPublicUrl(supabase, file.file_path, true);
-      if (url) {
-        urlMap.set(file.id, url);
-        const cacheKey = getCacheKey(file.id, file.file_path, true);
-        globalUrlCache.set(cacheKey, {
-          url,
-          expiresAt: now + ttl
-        });
+    const now = Date.now();
+    const ttl = (options.expiresIn || 3600) * 1e3;
+    const publicFiles = [];
+    const privateFiles = [];
+    const uncachedFiles = [];
+    for (const fileRef of fileReferences) {
+      const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
+      const cached = globalUrlCache.get(cacheKey);
+      if (cached && cached.expiresAt > now) {
+        urlMap.set(fileRef.id, cached.url);
+        continue;
+      }
+      if (fileRef.is_public) {
+        publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+      } else {
+        privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
       }
-    } catch (err) {
-      log2.error(`Failed to generate public URL for file ${file.id}:`, err);
+      uncachedFiles.push(fileRef);
     }
-  }
-  if (privateFiles.length > 0) {
-    const signedUrlPromises = privateFiles.map(async (file) => {
+    for (const file of publicFiles) {
       try {
+        const url = getPublicUrl(supabase, file.file_path, true);
+        if (url) {
+          urlMap.set(file.id, url);
+          const cacheKey = getCacheKey(file.id, file.file_path, true);
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
+        }
+      } catch (e) {
+        log2.error(`Failed to generate public URL for file ${file.id}:`, e);
+      }
+    }
+    if (privateFiles.length > 0) {
+      const signedUrlPromises = privateFiles.map(async (file) => {
         const signedUrlResult = await getSignedUrl(supabase, file.file_path, {
           appName: options.appName || "pace-core",
           orgId: options.orgId,
           expiresIn: options.expiresIn || 3600
         });
-        const url = signedUrlResult?.url || null;
+        const url = signedUrlResult.ok ? signedUrlResult.data.url : null;
         if (url) {
           const cacheKey = getCacheKey(file.id, file.file_path, false);
-          globalUrlCache.set(cacheKey, {
-            url,
-            expiresAt: now + ttl
-          });
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
         }
         return { id: file.id, url };
-      } catch (err) {
-        log2.error(`Failed to generate signed URL for file ${file.id}:`, err);
-        return { id: file.id, url: null };
-      }
-    });
-    const signedUrlResults = await Promise.all(signedUrlPromises);
-    for (const result of signedUrlResults) {
-      if (result.url) {
-        urlMap.set(result.id, result.url);
+      });
+      const signedUrlResults = await Promise.all(signedUrlPromises);
+      for (const result of signedUrlResults) {
+        if (result.url) {
+          urlMap.set(result.id, result.url);
+        }
       }
     }
+    if (uncachedFiles.length > 0) {
+      cleanupUrlCache();
+    }
+    return ok(urlMap);
+  } catch (error) {
+    return err({
+      code: "BATCH_URLS_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
-  if (uncachedFiles.length > 0) {
-    cleanupUrlCache();
-  }
-  return urlMap;
 }
 async function deleteFile(supabase, path, isPublic = false) {
   try {
     const bucketName = getBucketName(isPublic);
     const { error } = await supabase.storage.from(bucketName).remove([path]);
     if (error) {
-      return {
-        success: false,
-        error: `Delete failed: ${error.message}`
-      };
+      return err({ code: "DELETE_FAILED", message: error.message });
     }
-    return { success: true };
+    return ok(void 0);
   } catch (error) {
-    return {
-      success: false,
-      error: `Delete failed: ${error instanceof Error ? error.message : "Unknown error"}`
-    };
+    return err({
+      code: "DELETE_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 async function listFiles(supabase, options) {
   try {
     const bucketName = getBucketName(options.isPublic || false);
     if (!options.orgId && !options.userId) {
-      throw new Error("Either orgId or userId is required for listing files");
+      return err({ code: "LIST_FILES_INVALID_OPTIONS", message: "Either orgId or userId is required for listing files" });
     }
     const basePath = options.orgId ? options.orgId : `users/${options.userId}`;
     const pathPrefix = `${basePath}/`;
@@ -785,7 +795,7 @@ async function listFiles(supabase, options) {
     });
     if (error) {
       log2.error("Failed to list files:", error);
-      return { files: [], totalCount: 0, hasMore: false };
+      return err({ code: "LIST_FILES_FAILED", message: error.message });
     }
     const files = (data || []).map((item) => ({
       name: item.name,
@@ -804,14 +814,17 @@ async function listFiles(supabase, options) {
         isPublic: options.isPublic || false
       }
     }));
-    return {
+    return ok({
       files,
       totalCount: files.length,
       hasMore: files.length >= (options.limit || 100)
-    };
+    });
   } catch (error) {
     log2.error("Failed to list files:", error);
-    return { files: [], totalCount: 0, hasMore: false };
+    return err({
+      code: "LIST_FILES_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 async function downloadFile(supabase, path, isPublic = false) {
@@ -820,27 +833,28 @@ async function downloadFile(supabase, path, isPublic = false) {
     const { data, error } = await supabase.storage.from(bucketName).download(path);
     if (error) {
       log2.error("Failed to download file:", error);
-      return null;
+      return err({ code: "DOWNLOAD_FAILED", message: error.message });
     }
     if (!data) {
-      return null;
+      return err({ code: "DOWNLOAD_FAILED", message: "No data returned" });
     }
     const fileName = path.split("/").pop() || "download";
-    const { data: fileInfo } = await supabase.storage.from(bucketName).list(path.split("/").slice(0, -1).join("/"), {
-      search: fileName
-    });
+    const { data: fileInfo } = await supabase.storage.from(bucketName).list(path.split("/").slice(0, -1).join("/"), { search: fileName });
     const metadata = fileInfo?.[0]?.metadata || {};
-    return {
+    return ok({
       blob: data,
       metadata: {
         name: fileName,
         size: metadata.size || data.size,
         type: metadata.mimetype || "application/octet-stream"
       }
-    };
+    });
   } catch (error) {
     log2.error("Failed to download file:", error);
-    return null;
+    return err({
+      code: "DOWNLOAD_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 async function archiveFile(supabase, path, options) {
@@ -852,25 +866,22 @@ async function archiveFile(supabase, path, options) {
     } else if (options.userId) {
       archivedPath = path.replace(`users/${options.userId}/`, `archived/users/${options.userId}/`);
     } else {
-      throw new Error("Either orgId or userId is required for archiving files");
+      return err({ code: "ARCHIVE_FAILED", message: "Either orgId or userId is required for archiving files" });
     }
     const { error: copyError } = await supabase.storage.from(bucketName).copy(path, archivedPath);
     if (copyError) {
-      return {
-        success: false,
-        error: `Archive failed: ${copyError.message}`
-      };
+      return err({ code: "ARCHIVE_FAILED", message: copyError.message });
     }
     const deleteResult = await deleteFile(supabase, path, options.isPublic || false);
-    if (!deleteResult.success) {
-      return deleteResult;
+    if (!deleteResult.ok) {
+      return err(deleteResult.error);
     }
-    return { success: true };
+    return ok(void 0);
   } catch (error) {
-    return {
-      success: false,
-      error: `Archive failed: ${error instanceof Error ? error.message : "Unknown error"}`
-    };
+    return err({
+      code: "ARCHIVE_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
   }
 }
 var publicFileCache = /* @__PURE__ */ new Map();
@@ -889,263 +900,80 @@ function usePublicFileDisplay(table_name, record_id, organisation_id, category,
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState(null);
   const fetchFiles = useCallback(async () => {
+    const emptySetters = () => {
+      applyEmptyPublicFileState(
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      );
+    };
     if (!table_name || !record_id || !supabase) {
-      setFileUrl(null);
-      setFileReference(null);
-      setFileReferences([]);
-      setFileUrls(/* @__PURE__ */ new Map());
-      setFileCount(0);
-      setIsLoading(false);
+      emptySetters();
       return;
     }
-    if (organisation_id) {
-      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-      if (!uuidRegex.test(organisation_id)) {
-        logger.warn("usePublicFileDisplay", "Invalid organisationId format (not a valid UUID)", { organisation_id });
-      }
-    }
-    const cacheKey = `public_file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
-    if (enableCache) {
-      const cached = publicFileCache.get(cacheKey);
-      if (cached && Date.now() - cached.timestamp < cached.ttl) {
-        const cachedData = cached.data;
-        setFileUrl(cachedData.fileUrl || null);
-        setFileReference(cachedData.fileReference || null);
-        setFileReferences(cachedData.fileReferences || []);
-        setFileUrls(cachedData.fileUrls || /* @__PURE__ */ new Map());
-        setFileCount(cachedData.fileCount || 0);
-        setIsLoading(false);
-        setError(null);
-        return;
-      }
+    warnInvalidOrganisationIdUuid(organisation_id ?? void 0);
+    const cacheKey = buildPublicFileCacheKey(table_name, record_id, organisation_id, category);
+    const cached = getCachedPublicFileData(cacheKey, enableCache);
+    if (cached) {
+      applyCachedPublicFileState(
+        cached,
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      );
+      return;
     }
     try {
       setIsLoading(true);
       setError(null);
-      let files = [];
-      if (organisation_id === void 0) {
-        logger.debug("usePublicFileDisplay", "organisation_id is undefined, searching both user-scoped and organisation-scoped files:", {
-          table_name,
-          record_id,
-          category
-        });
-        let userScopedFiles = [];
-        const orgScopedFiles = [];
-        if (category) {
-          const { data: userData, error: userRpcError } = await supabase.rpc("data_file_reference_by_category_list", {
-            p_table_name: table_name,
-            p_record_id: record_id,
-            p_category: category,
-            p_organisation_id: void 0
-          });
-          if (!userRpcError && userData) {
-            userScopedFiles = userData.filter((item) => item.is_public === true && item.id && item.file_path && item.file_metadata).map((item) => {
-              const metadata = item.file_metadata;
-              return {
-                id: item.id,
-                table_name,
-                record_id,
-                file_path: item.file_path,
-                file_metadata: item.file_metadata || null,
-                organisation_id: null,
-                app_id: metadata?.app_id || "",
-                is_public: true,
-                created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                created_by: null
-              };
-            });
-          }
-        } else {
-          const { data: userData, error: userRpcError } = await supabase.rpc("data_file_reference_list", {
-            p_table_name: table_name,
-            p_record_id: record_id,
-            p_organisation_id: void 0
-          });
-          if (!userRpcError && userData) {
-            const ids = userData.map((item) => item.id);
-            if (ids.length > 0) {
-              const { data: fullData } = await supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by").in("id", ids).eq("is_public", true);
-              userScopedFiles = fullData || [];
-            }
-          }
-        }
-        const allFiles = [...userScopedFiles, ...orgScopedFiles];
-        allFiles.sort((a, b) => {
-          const aTime = new Date(a.created_at || 0).getTime();
-          const bTime = new Date(b.created_at || 0).getTime();
-          return bTime - aTime;
-        });
-        files = allFiles;
-        logger.debug("usePublicFileDisplay", "Found files with undefined organisation_id:", {
-          userScopedCount: userScopedFiles.length,
-          orgScopedCount: orgScopedFiles.length,
-          totalCount: files.length
-        });
-      } else {
-        if (category) {
-          const rpcParams = {
-            p_table_name: table_name,
-            p_record_id: record_id,
-            p_category: category,
-            p_organisation_id: organisation_id ?? null
-          };
-          const { data, error: rpcError } = await supabase.rpc("data_file_reference_by_category_list", rpcParams);
-          if (rpcError) {
-            logger.error("usePublicFileDisplay", "RPC function error", {
-              function: "data_file_reference_by_category_list",
-              table_name,
-              record_id,
-              category,
-              organisation_id,
-              error: rpcError.message,
-              errorCode: rpcError.code,
-              errorDetails: rpcError.details,
-              errorHint: rpcError.hint
-            });
-            throw new Error(rpcError.message || "Failed to fetch file reference");
-          }
-          if (!data || data.length === 0) {
-            files = [];
-          } else {
-            files = data.filter((item) => {
-              return item.is_public === true && item.id && item.file_path && item.file_metadata;
-            }).map((item) => {
-              const metadata = item.file_metadata;
-              return {
-                id: item.id,
-                table_name,
-                record_id,
-                file_path: item.file_path,
-                file_metadata: item.file_metadata || null,
-                organisation_id: organisation_id ?? null,
-                app_id: metadata?.app_id || "",
-                is_public: true,
-                // RPC already filtered for public files
-                created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                created_by: null
-              };
-            });
-          }
-        } else {
-          const { data: fileIds, error: rpcError } = await supabase.rpc("data_file_reference_list", {
-            p_table_name: table_name,
-            p_record_id: record_id,
-            p_organisation_id: organisation_id ?? null
-          });
-          if (rpcError) {
-            logger.error("usePublicFileDisplay", "RPC function error", {
-              function: "data_file_reference_list",
-              table_name,
-              record_id,
-              organisation_id,
-              error: rpcError.message,
-              errorCode: rpcError.code,
-              errorDetails: rpcError.details,
-              errorHint: rpcError.hint
-            });
-            throw new Error(rpcError.message || "Failed to fetch file references");
-          }
-          if (!fileIds || fileIds.length === 0) {
-            files = [];
-          } else {
-            const ids = fileIds.map((item) => item.id);
-            const { data: fullData, error: fetchError } = await supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by").in("id", ids).eq("is_public", true);
-            if (fetchError) {
-              throw new Error(fetchError.message || "Failed to fetch file references");
-            }
-            files = fullData || [];
-          }
-        }
-      }
-      const publicFiles = files.filter((f) => f.is_public === true);
-      if (publicFiles.length === 0) {
-        setFileUrl(null);
-        setFileReference(null);
-        setFileReferences([]);
-        setFileUrls(/* @__PURE__ */ new Map());
-        setFileCount(0);
-        if (enableCache) {
-          publicFileCache.set(cacheKey, {
-            data: { fileUrl: null, fileReference: null, fileReferences: [], fileUrls: /* @__PURE__ */ new Map(), fileCount: 0 },
-            timestamp: Date.now(),
-            ttl: cacheTtl
-          });
-        }
+      const rows = await fetchPublicFileRows(supabase, table_name, record_id, organisation_id, category);
+      const publicRows = rows.filter((f) => f.is_public === true);
+      if (publicRows.length === 0) {
+        emptySetters();
+        setCachedPublicFileData(cacheKey, emptyCacheData, enableCache, cacheTtl);
         return;
       }
-      const fileRefs = publicFiles.map((f) => {
-        const fileName = f.file_path.split("/").pop() || "unknown";
-        const fileType = fileName.split(".").pop() || "unknown";
-        const metadata = f.file_metadata;
-        return {
-          id: f.id,
-          table_name: f.table_name,
-          record_id: f.record_id,
-          file_path: f.file_path,
-          file_metadata: {
-            fileName: metadata?.fileName || fileName,
-            fileType: metadata?.fileType || fileType,
-            category: metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
-            ...metadata || {}
-          },
-          organisation_id: f.organisation_id,
-          app_id: f.app_id,
-          is_public: f.is_public ?? true,
-          created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-          updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
-        };
-      });
+      const fileRefs = mapDbRowsToFileReferences(publicRows);
       setFileReferences(fileRefs);
       setFileCount(fileRefs.length);
       if (category && fileRefs.length > 0) {
         const firstFile = fileRefs[0];
         setFileReference(firstFile);
-        const url = getPublicUrl(supabase, firstFile.file_path, true);
-        setFileUrl(url);
+        setFileUrl(getPublicUrl(supabase, firstFile.file_path, true));
       } else {
-        const urlMap = await generateFileUrlsBatch(supabase, fileRefs, {
+        const urlResult = await generateFileUrlsBatch(supabase, fileRefs, {
           appName: "pace-core",
           orgId: organisation_id,
           expiresIn: 3600
         });
-        setFileUrls(urlMap);
+        setFileUrls(urlResult.ok ? urlResult.data : /* @__PURE__ */ new Map());
         setFileReference(null);
         setFileUrl(null);
       }
-      if (enableCache) {
-        publicFileCache.set(cacheKey, {
-          data: {
-            fileUrl: category ? fileRefs.length > 0 ? getPublicUrl(supabase, fileRefs[0].file_path, true) : null : null,
-            fileReference: category && fileRefs.length > 0 ? fileRefs[0] : null,
-            fileReferences: fileRefs,
-            fileUrls: category ? /* @__PURE__ */ new Map() : (() => {
-              const urlMap = /* @__PURE__ */ new Map();
-              for (const fileRef of fileRefs) {
-                const url = getPublicUrl(supabase, fileRef.file_path, true);
-                if (url) {
-                  urlMap.set(fileRef.id, url);
-                }
-              }
-              return urlMap;
-            })(),
-            fileCount: fileRefs.length
-          },
-          timestamp: Date.now(),
-          ttl: cacheTtl
-        });
-      }
-    } catch (err) {
+      setCachedPublicFileData(
+        cacheKey,
+        buildCacheDataFromRefs(fileRefs, category, supabase),
+        enableCache,
+        cacheTtl
+      );
+    } catch (err2) {
       logger.error("usePublicFileDisplay", "Error fetching files", {
         table_name,
         record_id,
         organisation_id,
         category,
-        error: err instanceof Error ? err.message : "Unknown error",
-        errorDetails: err instanceof Error ? err.stack : String(err)
+        error: err2 instanceof Error ? err2.message : "Unknown error",
+        errorDetails: err2 instanceof Error ? err2.stack : String(err2)
       });
-      const error2 = err instanceof Error ? err : new Error("Unknown error occurred");
+      const error2 = err2 instanceof Error ? err2 : new Error("Unknown error occurred");
       setError(error2);
       setFileUrl(null);
       setFileReference(null);
@@ -1172,7 +1000,7 @@ function usePublicFileDisplay(table_name, record_id, organisation_id, category,
   const refetch = useCallback(async () => {
     if (!table_name || !record_id) return;
     if (enableCache) {
-      const cacheKey = `public_file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
+      const cacheKey = buildPublicFileCacheKey(table_name, record_id, organisation_id, category);
       publicFileCache.delete(cacheKey);
     }
     await fetchFiles();
@@ -1188,6 +1016,217 @@ function usePublicFileDisplay(table_name, record_id, organisation_id, category,
     refetch
   };
 }
+function buildPublicFileCacheKey(table_name, record_id, organisation_id, category) {
+  return `public_file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
+}
+function getCachedPublicFileData(cacheKey, enableCache) {
+  if (!enableCache) return null;
+  const cached = publicFileCache.get(cacheKey);
+  if (!cached || Date.now() - cached.timestamp >= cached.ttl) return null;
+  return cached.data;
+}
+function setCachedPublicFileData(cacheKey, data, enableCache, cacheTtl) {
+  if (!enableCache) return;
+  publicFileCache.set(cacheKey, {
+    data,
+    timestamp: Date.now(),
+    ttl: cacheTtl
+  });
+}
+function mapRpcItemToRow(item, table_name, record_id, organisation_id) {
+  const metadata = item.file_metadata;
+  return {
+    id: item.id,
+    table_name,
+    record_id,
+    file_path: item.file_path,
+    file_metadata: item.file_metadata || null,
+    organisation_id,
+    app_id: metadata?.app_id || "",
+    is_public: true,
+    created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+    updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+    created_by: null
+  };
+}
+async function fetchPublicFileRowsWhenOrgUndefined(supabase, table_name, record_id, category) {
+  let userScopedFiles = [];
+  const orgScopedFiles = [];
+  logger.debug("usePublicFileDisplay", "organisation_id is undefined, searching both user-scoped and organisation-scoped files:", {
+    table_name,
+    record_id,
+    category
+  });
+  if (category) {
+    const { data: userData, error: userRpcError } = await supabase.rpc("data_file_reference_by_category_list", {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_category: category,
+      p_organisation_id: void 0
+    });
+    if (!userRpcError && userData) {
+      userScopedFiles = userData.filter((item) => item.is_public === true && item.id && item.file_path && item.file_metadata).map((item) => mapRpcItemToRow(item, table_name, record_id, null));
+    }
+  } else {
+    const { data: userData, error: userRpcError } = await supabase.rpc("data_file_reference_list", {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_organisation_id: void 0
+    });
+    if (!userRpcError && userData) {
+      const ids = userData.map((item) => item.id);
+      if (ids.length > 0) {
+        const { data: fullData } = await supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by").in("id", ids).eq("is_public", true);
+        userScopedFiles = fullData || [];
+      }
+    }
+  }
+  const allFiles = [...userScopedFiles, ...orgScopedFiles];
+  allFiles.sort((a, b) => {
+    const aTime = new Date(a.created_at || 0).getTime();
+    const bTime = new Date(b.created_at || 0).getTime();
+    return bTime - aTime;
+  });
+  logger.debug("usePublicFileDisplay", "Found files with undefined organisation_id:", {
+    userScopedCount: userScopedFiles.length,
+    orgScopedCount: orgScopedFiles.length,
+    totalCount: allFiles.length
+  });
+  return allFiles;
+}
+async function fetchPublicFileRowsWhenOrgDefined(supabase, table_name, record_id, organisation_id, category) {
+  if (category) {
+    const rpcParams = {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_category: category,
+      p_organisation_id: organisation_id ?? void 0
+    };
+    const { data, error: rpcError2 } = await supabase.rpc("data_file_reference_by_category_list", rpcParams);
+    if (rpcError2) {
+      logger.error("usePublicFileDisplay", "RPC function error", {
+        function: "data_file_reference_by_category_list",
+        table_name,
+        record_id,
+        category,
+        organisation_id,
+        error: rpcError2.message,
+        errorCode: rpcError2.code,
+        errorDetails: rpcError2.details,
+        errorHint: rpcError2.hint
+      });
+      throw new Error(rpcError2.message || "Failed to fetch file reference");
+    }
+    if (!data || data.length === 0) return [];
+    return data.filter((item) => item.is_public === true && item.id && item.file_path && item.file_metadata).map((item) => mapRpcItemToRow(item, table_name, record_id, organisation_id ?? null));
+  }
+  const { data: fileIds, error: rpcError } = await supabase.rpc("data_file_reference_list", {
+    p_table_name: table_name,
+    p_record_id: record_id,
+    p_organisation_id: organisation_id ?? void 0
+  });
+  if (rpcError) {
+    logger.error("usePublicFileDisplay", "RPC function error", {
+      function: "data_file_reference_list",
+      table_name,
+      record_id,
+      organisation_id,
+      error: rpcError.message,
+      errorCode: rpcError.code,
+      errorDetails: rpcError.details,
+      errorHint: rpcError.hint
+    });
+    throw new Error(rpcError.message || "Failed to fetch file references");
+  }
+  if (!fileIds || fileIds.length === 0) return [];
+  const ids = fileIds.map((item) => item.id);
+  const { data: fullData, error: fetchError } = await supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by").in("id", ids).eq("is_public", true);
+  if (fetchError) throw new Error(fetchError.message || "Failed to fetch file references");
+  return fullData || [];
+}
+async function fetchPublicFileRows(supabase, table_name, record_id, organisation_id, category) {
+  if (organisation_id === void 0) {
+    return fetchPublicFileRowsWhenOrgUndefined(supabase, table_name, record_id, category);
+  }
+  return fetchPublicFileRowsWhenOrgDefined(supabase, table_name, record_id, organisation_id, category);
+}
+function mapDbRowsToFileReferences(rows) {
+  return rows.map((f) => {
+    const fileName = f.file_path.split("/").pop() || "unknown";
+    const fileType = fileName.split(".").pop() || "unknown";
+    const metadata = f.file_metadata;
+    return {
+      id: f.id,
+      table_name: f.table_name,
+      record_id: f.record_id,
+      file_path: f.file_path,
+      file_metadata: {
+        fileName: metadata?.fileName || fileName,
+        fileType: metadata?.fileType || fileType,
+        category: metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
+        ...metadata || {}
+      },
+      organisation_id: f.organisation_id,
+      app_id: f.app_id,
+      is_public: f.is_public ?? true,
+      created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+      updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
+    };
+  });
+}
+function buildCacheDataFromRefs(fileRefs, category, supabase) {
+  const fileUrl = category && fileRefs.length > 0 ? getPublicUrl(supabase, fileRefs[0].file_path, true) : null;
+  const fileReference = category && fileRefs.length > 0 ? fileRefs[0] : null;
+  let fileUrls;
+  if (category) {
+    fileUrls = /* @__PURE__ */ new Map();
+  } else {
+    fileUrls = /* @__PURE__ */ new Map();
+    for (const fileRef of fileRefs) {
+      const url = getPublicUrl(supabase, fileRef.file_path, true);
+      if (url) fileUrls.set(fileRef.id, url);
+    }
+  }
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences: fileRefs,
+    fileUrls,
+    fileCount: fileRefs.length
+  };
+}
+var emptyCacheData = {
+  fileUrl: null,
+  fileReference: null,
+  fileReferences: [],
+  fileUrls: /* @__PURE__ */ new Map(),
+  fileCount: 0
+};
+function applyEmptyPublicFileState(setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount, setIsLoading, setError) {
+  setFileUrl(null);
+  setFileReference(null);
+  setFileReferences([]);
+  setFileUrls(/* @__PURE__ */ new Map());
+  setFileCount(0);
+  setIsLoading(false);
+  setError(null);
+}
+function applyCachedPublicFileState(cachedData, setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount, setIsLoading, setError) {
+  setFileUrl(cachedData.fileUrl || null);
+  setFileReference(cachedData.fileReference || null);
+  setFileReferences(cachedData.fileReferences || []);
+  setFileUrls(cachedData.fileUrls || /* @__PURE__ */ new Map());
+  setFileCount(cachedData.fileCount || 0);
+  setIsLoading(false);
+  setError(null);
+}
+function warnInvalidOrganisationIdUuid(organisation_id) {
+  if (!organisation_id) return;
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidRegex.test(organisation_id)) {
+    logger.warn("usePublicFileDisplay", "Invalid organisationId format (not a valid UUID)", { organisation_id });
+  }
+}
 function clearPublicFileDisplayCache() {
   for (const [key] of publicFileCache) {
     if (key.startsWith("public_file_")) {
@@ -1205,6 +1244,33 @@ function getPublicFileDisplayCacheStats() {
 
 // src/utils/file-reference/index.ts
 var log3 = createLogger("FileReferenceService");
+function toApiError(error) {
+  const message = error instanceof Error ? error.message : "Unknown error";
+  const code = error instanceof Error && error.code ? error.code : "FILE_REFERENCE_ERROR";
+  return { code, message };
+}
+function mapFileReferenceRowToFileReference(f) {
+  const fileName = f.file_path.split("/").pop() || "unknown";
+  const fileType = fileName.split(".").pop() || "unknown";
+  const metadata = f.file_metadata;
+  return {
+    id: f.id,
+    table_name: f.table_name,
+    record_id: f.record_id,
+    file_path: f.file_path,
+    file_metadata: {
+      fileName: metadata?.fileName || fileName,
+      fileType: metadata?.fileType || fileType,
+      category: metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
+      ...metadata || {}
+    },
+    organisation_id: f.organisation_id,
+    app_id: f.app_id,
+    is_public: f.is_public ?? false,
+    created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+    updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
 var FileReferenceServiceImpl = class {
   constructor(supabase) {
     this.supabase = supabase;
@@ -1223,6 +1289,114 @@ var FileReferenceServiceImpl = class {
       return "unknown";
     }
   }
+  validateCreateOptions(options) {
+    const isUserScoped = !options.organisation_id && !!options.userId;
+    if (!isUserScoped && !options.organisation_id) {
+      return err({ code: "VALIDATION_ERROR", message: "organisation_id is required for file upload, or userId must be provided for user-scoped files" });
+    }
+    if (!options.table_name) {
+      return err({ code: "VALIDATION_ERROR", message: "table_name is required for file upload" });
+    }
+    if (!options.record_id) {
+      return err({ code: "VALIDATION_ERROR", message: "record_id is required for file upload" });
+    }
+    if (!options.folder) {
+      return err({ code: "VALIDATION_ERROR", message: "folder is required for file upload. The folder prop determines the storage path." });
+    }
+    return ok({ isUserScoped });
+  }
+  async resolveAuthenticatedUserIdForUserScoped() {
+    const { data: { user: authUser }, error: authError } = await this.supabase.auth.getUser();
+    if (authError || !authUser) {
+      return err({ code: "UNAUTHORIZED", message: "User must be authenticated to upload user-scoped files" });
+    }
+    log3.debug("Using authenticated user ID for user-scoped file upload", { userId: authUser.id });
+    return ok(authUser.id);
+  }
+  async checkSuperAdminUser(userId) {
+    if (!userId) return false;
+    try {
+      const { isSuperAdmin } = await import('./api-BZR2CYXL.js');
+      const superResult = await isSuperAdmin(userId);
+      if (superResult.ok && superResult.data) {
+        log3.debug("Super admin detected - bypassing permission checks", { userId });
+        return true;
+      }
+      return false;
+    } catch (superAdminCheckError) {
+      log3.warn("Failed to check super-admin status, proceeding with normal permission checks", superAdminCheckError);
+      return false;
+    }
+  }
+  async uploadFileAndExtractMetadata(options, file, authenticatedUserId, isUserScoped) {
+    const userId = authenticatedUserId || (isUserScoped ? void 0 : options.userId);
+    const uploadResult = await uploadFile(this.supabase, file, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId,
+      isPublic: options.is_public || false,
+      customPath: options.folder
+    });
+    if (!uploadResult.ok) return err(uploadResult.error);
+    const metadataResult = await extractFileMetadata(file, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId,
+      isPublic: options.is_public || false
+    }, "system");
+    if (!metadataResult.ok) return err(metadataResult.error);
+    return ok({ path: uploadResult.data.path, metadata: metadataResult.data });
+  }
+  async setOrgContextIfNeeded(isUserScoped, organisation_id) {
+    if (isUserScoped || !organisation_id) return;
+    const ctxResult = await setOrganisationContext(this.supabase, organisation_id);
+    if (!ctxResult.ok) {
+      log3.warn("setOrganisationContext failed (non-fatal):", ctxResult.error.message);
+    }
+  }
+  async resolveRpcUserId(authenticatedUserId, options) {
+    if (authenticatedUserId) return authenticatedUserId;
+    if (options.userId) return options.userId;
+    const { data: { user: authUser } } = await this.supabase.auth.getUser();
+    return authUser?.id ?? null;
+  }
+  async buildPermissionDeniedMessage(options, isSuperAdminUser) {
+    const appName = await this.getAppName(options.app_id).catch(() => "unknown");
+    const pageContextDisplay = options.pageContext || "undefined";
+    return isSuperAdminUser ? `File upload failed for super-admin user. Page context: '${pageContextDisplay}', App: '${appName}'.` : `File upload denied: insufficient permissions. You need 'create:page.${pageContextDisplay}' or 'update:page.${pageContextDisplay}' for the '${pageContextDisplay}' page.`;
+  }
+  async rollbackUploadAndErr(filePath, isPublic, code, message) {
+    await deleteFile(this.supabase, filePath, isPublic);
+    return err({ code, message });
+  }
+  async fetchCreatedFileReference(createdId) {
+    const { data: fileRef, error: fetchError } = await this.supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at").eq("id", createdId).single();
+    if (fetchError || !fileRef) {
+      return err({ code: "FETCH_FAILED", message: fetchError?.message ?? "Failed to fetch created file reference" });
+    }
+    return ok(fileRef);
+  }
+  buildCreateRpcPayload(options, filePath, file, metadata, rpcUserId) {
+    return {
+      p_table_name: options.table_name,
+      p_record_id: options.record_id,
+      p_file_path: filePath,
+      p_organisation_id: options.organisation_id ?? null,
+      p_app_id: options.app_id,
+      p_page_context: options.pageContext,
+      p_event_id: options.event_id || null,
+      p_file_metadata: {
+        fileName: file.name,
+        fileType: file.type,
+        fileSize: file.size,
+        category: options.category,
+        ...metadata,
+        ...options.custom_metadata
+      },
+      p_is_public: options.is_public || false,
+      p_user_id: rpcUserId
+    };
+  }
   /**
    * Creates a file reference by uploading a file to storage and linking it in the database.
    * 
@@ -1239,122 +1413,38 @@ var FileReferenceServiceImpl = class {
    */
   async createFileReference(options, file) {
     try {
-      const isUserScoped = !options.organisation_id && options.userId;
-      if (!isUserScoped && !options.organisation_id) {
-        throw new Error("organisation_id is required for file upload, or userId must be provided for user-scoped files");
-      }
-      if (!options.table_name) {
-        throw new Error("table_name is required for file upload");
-      }
-      if (!options.record_id) {
-        throw new Error("record_id is required for file upload");
-      }
-      if (!options.folder) {
-        throw new Error("folder is required for file upload. The folder prop determines the storage path.");
-      }
-      let authenticatedUserId = void 0;
+      const validation = this.validateCreateOptions(options);
+      if (!validation.ok) return validation;
+      const { isUserScoped } = validation.data;
+      let authenticatedUserId;
       if (isUserScoped) {
-        const { data: { user: authUser }, error: authError } = await this.supabase.auth.getUser();
-        if (authError || !authUser) {
-          throw new Error("User must be authenticated to upload user-scoped files");
-        }
-        authenticatedUserId = authUser.id;
-        log3.debug("Using authenticated user ID for user-scoped file upload", { userId: authenticatedUserId });
+        const authResult = await this.resolveAuthenticatedUserIdForUserScoped();
+        if (!authResult.ok) return authResult;
+        authenticatedUserId = authResult.data;
       }
-      let isSuperAdminUser = false;
-      const userIdForCheck = authenticatedUserId || options.userId;
-      if (userIdForCheck) {
-        try {
-          const { isSuperAdmin } = await import('./api-F47QJ7FX.js');
-          isSuperAdminUser = await isSuperAdmin(userIdForCheck);
-          if (isSuperAdminUser) {
-            log3.debug("Super admin detected - bypassing permission checks", { userId: userIdForCheck });
-          }
-        } catch (superAdminCheckError) {
-          log3.warn("Failed to check super-admin status, proceeding with normal permission checks", superAdminCheckError);
-        }
-      }
-      const uploadResult = await uploadFile(this.supabase, file, {
-        appName: "file-reference",
-        orgId: options.organisation_id || void 0,
-        userId: authenticatedUserId || (isUserScoped ? void 0 : options.userId),
-        // Use auth.uid() for user-scoped files
-        isPublic: options.is_public || false,
-        customPath: options.folder
-        // Use folder prop as the custom path segment
-      });
-      if (!uploadResult.success) {
-        throw new Error(`Failed to upload file: ${uploadResult.error}`);
-      }
-      if (!uploadResult.path) {
-        throw new Error("File upload did not return a path");
-      }
-      const filePath = uploadResult.path;
-      const metadata = await extractFileMetadata(file, {
-        appName: "file-reference",
-        orgId: options.organisation_id || void 0,
-        userId: authenticatedUserId || (isUserScoped ? void 0 : options.userId),
-        // Use auth.uid() for user-scoped files
-        isPublic: options.is_public || false
-      }, "system");
-      if (!isUserScoped && options.organisation_id) {
-        await setOrganisationContext(this.supabase, options.organisation_id);
-      }
-      let rpcUserId = null;
-      if (authenticatedUserId) {
-        rpcUserId = authenticatedUserId;
-      } else if (options.userId) {
-        rpcUserId = options.userId;
-      } else {
-        const { data: { user: authUser } } = await this.supabase.auth.getUser();
-        if (authUser) {
-          rpcUserId = authUser.id;
-        }
-      }
-      const { data, error } = await this.supabase.rpc("data_file_reference_create", {
-        p_table_name: options.table_name,
-        p_record_id: options.record_id,
-        p_file_path: filePath,
-        // Storage path from step 1
-        p_organisation_id: options.organisation_id ?? null,
-        p_app_id: options.app_id,
-        p_page_context: options.pageContext,
-        p_event_id: options.event_id || null,
-        // Pass event_id for event-based apps
-        p_file_metadata: {
-          fileName: file.name,
-          fileType: file.type,
-          fileSize: file.size,
-          category: options.category,
-          ...metadata,
-          ...options.custom_metadata
-        },
-        p_is_public: options.is_public || false,
-        p_user_id: rpcUserId
-        // Always pass authenticated user ID for SECURITY DEFINER functions
-      });
+      const isSuperAdminUser = await this.checkSuperAdminUser(authenticatedUserId || options.userId);
+      const uploadResult = await this.uploadFileAndExtractMetadata(options, file, authenticatedUserId, isUserScoped);
+      if (!uploadResult.ok) return uploadResult;
+      const { path: filePath, metadata } = uploadResult.data;
+      await this.setOrgContextIfNeeded(isUserScoped, options.organisation_id ?? void 0);
+      const rpcUserId = await this.resolveRpcUserId(authenticatedUserId, options);
+      const payload = this.buildCreateRpcPayload(options, filePath, file, metadata, rpcUserId);
+      const { data, error } = await this.supabase.rpc("data_file_reference_create", payload);
       if (error) {
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-        throw new Error(`Failed to create file reference: ${error.message}`);
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, "CREATE_FAILED", error.message);
       }
       if (!data || data === null) {
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-        const appName = await this.getAppName(options.app_id).catch(() => "unknown");
-        const pageContextDisplay = options.pageContext || "undefined";
-        if (isSuperAdminUser) {
-          throw new Error(
-            `File upload failed for super-admin user. This may indicate a database issue. Page context: '${pageContextDisplay}', App: '${appName}'. Please check that the page '${pageContextDisplay}' exists in rbac_app_pages table for app '${appName}'.`
-          );
-        } else {
-          throw new Error(
-            `File upload denied: insufficient permissions. You need 'create:page.${pageContextDisplay}' or 'update:page.${pageContextDisplay}' permission for the '${pageContextDisplay}' page. Make sure the page exists in rbac_app_pages table for app '${appName}'.`
-          );
-        }
+        const message = await this.buildPermissionDeniedMessage(options, isSuperAdminUser);
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, "PERMISSION_DENIED", message);
       }
-      const { data: fileRef, error: fetchError } = await this.supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at").eq("id", data).single();
-      if (fetchError || !fileRef) {
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-        throw new Error(`Failed to fetch created file reference: ${fetchError?.message}`);
+      const fetchResult = await this.fetchCreatedFileReference(data);
+      if (!fetchResult.ok) {
+        return await this.rollbackUploadAndErr(
+          filePath,
+          options.is_public ?? false,
+          "FETCH_FAILED",
+          fetchResult.error.message
+        );
       }
       invalidateFileDisplayCache(
         options.table_name,
@@ -1362,10 +1452,10 @@ var FileReferenceServiceImpl = class {
         options.organisation_id || null,
         options.category
       );
-      return fileRef;
+      return ok(fetchResult.data);
     } catch (error) {
       log3.error("Error creating file reference:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getFileReference(table_name, record_id, organisation_id) {
@@ -1379,21 +1469,25 @@ var FileReferenceServiceImpl = class {
       const { data, error } = await query.single();
       if (error) {
         if (error.code === "PGRST116") {
-          return null;
+          return ok(null);
         }
-        throw new Error(`Failed to get file reference: ${error.message}`);
+        return err({ code: "FETCH_FAILED", message: error.message });
       }
-      return data;
+      return ok(data);
     } catch (error) {
       log3.error("Error getting file reference:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getFileUrl(table_name, record_id, organisation_id) {
     try {
-      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      if (!refResult.ok) {
+        return refResult;
+      }
+      const fileRef = refResult.data;
       if (!fileRef) {
-        return null;
+        return ok(null);
       }
       if (fileRef.is_public) {
         const { data: pathData } = await this.supabase.rpc("data_file_reference_url_get", {
@@ -1402,15 +1496,14 @@ var FileReferenceServiceImpl = class {
           p_organisation_id: organisation_id
         });
         if (!pathData) {
-          return null;
+          return ok(null);
         }
-        return getPublicUrl(this.supabase, pathData, true);
-      } else {
-        return await this.getSignedUrl(table_name, record_id, organisation_id);
+        return ok(getPublicUrl(this.supabase, pathData, true));
       }
+      return this.getSignedUrl(table_name, record_id, organisation_id);
     } catch (error) {
       log3.error("Error getting file URL:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getSignedUrl(table_name, record_id, organisation_id, expires_in = 3600) {
@@ -1422,10 +1515,10 @@ var FileReferenceServiceImpl = class {
         p_expires_in: expires_in
       });
       if (error) {
-        throw new Error(`Failed to get signed URL: ${error.message}`);
+        return err({ code: "SIGNED_URL_FAILED", message: error.message });
       }
       if (!filePath) {
-        return null;
+        return ok(null);
       }
       const signedUrlResult = await getSignedUrl(this.supabase, filePath, {
         appName: "file-reference",
@@ -1433,27 +1526,31 @@ var FileReferenceServiceImpl = class {
         userId: organisation_id ? void 0 : record_id,
         expiresIn: expires_in
       });
-      return signedUrlResult?.url || null;
+      if (!signedUrlResult.ok) {
+        return err(signedUrlResult.error);
+      }
+      return ok(signedUrlResult.data.url ?? null);
     } catch (error) {
       log3.error("Error getting signed URL:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async updateFileReference(id, updates) {
     try {
       const { data, error } = await this.supabase.from("core_file_references").update(updates).eq("id", id).select().single();
       if (error) {
-        throw new Error(`Failed to update file reference: ${error.message}`);
+        return err({ code: "UPDATE_FAILED", message: error.message });
       }
-      return data;
+      return ok(data);
     } catch (error) {
       log3.error("Error updating file reference:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async deleteFileReference(table_name, record_id, organisation_id, delete_file = false) {
     try {
-      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      const fileRef = refResult.ok ? refResult.data : null;
       const { error } = await this.supabase.rpc("data_file_reference_delete", {
         p_table_name: table_name,
         p_record_id: record_id,
@@ -1461,15 +1558,15 @@ var FileReferenceServiceImpl = class {
         p_delete_file: delete_file
       });
       if (error) {
-        throw new Error(`Failed to delete file reference: ${error.message}`);
+        return err({ code: "DELETE_FAILED", message: error.message });
       }
       if (delete_file && fileRef) {
         await deleteFile(this.supabase, fileRef.file_path, fileRef.is_public || false);
       }
-      return true;
+      return ok(true);
     } catch (error) {
       log3.error("Error deleting file reference:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async listFileReferences(table_name, record_id, organisation_id) {
@@ -1480,38 +1577,31 @@ var FileReferenceServiceImpl = class {
         p_organisation_id: organisation_id ?? null
       });
       if (error) {
-        throw new Error(`Failed to list file references: ${error.message}`);
+        return err({ code: "LIST_FAILED", message: error.message });
       }
       if (!data || data.length === 0) {
-        return [];
+        return ok([]);
       }
       const fileReferences = data.filter((item) => item.id && item.file_path && item.file_metadata).map((item) => {
         const fileName = item.file_path.split("/").pop() || "unknown";
         const fileType = fileName.split(".").pop() || "unknown";
-        const fileRef = {
+        return {
           id: item.id,
           table_name,
           record_id,
           file_path: item.file_path,
-          file_metadata: {
-            fileName,
-            fileType,
-            ...item.file_metadata || {}
-          },
+          file_metadata: { fileName, fileType, ...item.file_metadata || {} },
           organisation_id: organisation_id ?? null,
           app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(""),
-          // May not be in metadata, use empty string
           is_public: item.is_public ?? false,
           created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
           updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString()
-          // RPC doesn't return updated_at, use created_at
         };
-        return fileRef;
       });
-      return fileReferences;
+      return ok(fileReferences);
     } catch (error) {
       log3.error("Error listing file references:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getFileCount(table_name, record_id, organisation_id) {
@@ -1522,12 +1612,12 @@ var FileReferenceServiceImpl = class {
         p_organisation_id: organisation_id ?? null
       });
       if (error) {
-        throw new Error(`Failed to get file count: ${error.message}`);
+        return err({ code: "COUNT_FAILED", message: error.message });
       }
-      return data || 0;
+      return ok(data ?? 0);
     } catch (error) {
       log3.error("Error getting file count:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getFileReferenceById(id, organisation_id) {
@@ -1537,15 +1627,15 @@ var FileReferenceServiceImpl = class {
         p_organisation_id: organisation_id ?? null
       });
       if (error) {
-        throw new Error(`Failed to get file reference by ID: ${error.message}`);
+        return err({ code: "FETCH_FAILED", message: error.message });
       }
       if (!data || data.length === 0) {
-        return null;
+        return ok(null);
       }
-      return data[0];
+      return ok(data[0]);
     } catch (error) {
       log3.error("Error getting file reference by ID:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async getFilesByCategory(table_name, record_id, category, organisation_id) {
@@ -1557,61 +1647,36 @@ var FileReferenceServiceImpl = class {
         p_organisation_id: organisation_id ?? null
       });
       if (error) {
-        log3.error("RPC ERROR getting files by category:", {
-          error,
-          errorCode: error.code,
-          errorMessage: error.message,
-          errorDetails: error.details,
-          table_name,
-          record_id,
-          category,
-          organisation_id,
-          message: "CRITICAL: Category filtering MUST use RPC function data_file_reference_by_category_list. Direct queries with .eq('category', ...) will FAIL with HTTP 406 because category is stored in file_metadata JSONB field, not a direct column."
-        });
-        throw new Error(`Failed to get files by category: ${error.message}. Category filtering uses file_metadata JSONB field, not a direct column. RPC function required.`);
+        log3.error("RPC ERROR getting files by category:", { error, table_name, record_id, category });
+        return err({ code: "LIST_FAILED", message: error.message });
       }
       if (!data || data.length === 0) {
-        return [];
+        return ok([]);
       }
       const fileReferences = data.filter((item) => {
         const fileCategory = item.file_metadata?.category;
-        const matches = fileCategory === category;
-        if (!matches) {
-          log3.warn("File category mismatch in RPC response:", {
-            fileId: item.id,
-            expectedCategory: category,
-            actualCategory: fileCategory
-          });
-        }
-        return matches && item.id && item.file_path && item.file_metadata;
-      }).map((item) => {
-        const fileName = item.file_path.split("/").pop() || "unknown";
-        const fileType = fileName.split(".").pop() || "unknown";
-        const fileRef = {
-          id: item.id,
-          table_name,
-          record_id,
-          file_path: item.file_path,
-          file_metadata: {
-            fileName,
-            fileType,
-            category: item.file_metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
-            ...item.file_metadata || {}
-          },
-          organisation_id: organisation_id ?? null,
-          app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(""),
-          // May not be in metadata, use empty string
-          is_public: item.is_public ?? false,
-          created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-          updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString()
-          // RPC doesn't return updated_at, use created_at
-        };
-        return fileRef;
-      });
-      return fileReferences;
+        return fileCategory === category && item.id && item.file_path && item.file_metadata;
+      }).map((item) => ({
+        id: item.id,
+        table_name,
+        record_id,
+        file_path: item.file_path,
+        file_metadata: {
+          fileName: item.file_path.split("/").pop() || "unknown",
+          fileType: item.file_path.split(".").pop() || "unknown",
+          category: item.file_metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
+          ...item.file_metadata || {}
+        },
+        organisation_id: organisation_id ?? null,
+        app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(""),
+        is_public: item.is_public ?? false,
+        created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+        updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      return ok(fileReferences);
     } catch (error) {
       log3.error("Error getting files by category:", error);
-      throw error;
+      return err(toApiError(error));
     }
   }
   async uploadMultipleFiles(options, files) {
@@ -1619,8 +1684,9 @@ var FileReferenceServiceImpl = class {
     const failed = [];
     const results = [];
     for (const file of files) {
-      try {
-        const fileReference = await this.createFileReference(options, file);
+      const result = await this.createFileReference(options, file);
+      if (result.ok) {
+        const fileReference = result.data;
         success.push(fileReference);
         results.push({
           file,
@@ -1629,19 +1695,18 @@ var FileReferenceServiceImpl = class {
             file_url: fileReference.is_public ? getPublicUrl(this.supabase, fileReference.file_path, true) : ""
           }
         });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        failed.push({ file, error: message });
-        results.push({ file, result: null, error: message });
+      } else {
+        failed.push({ file, error: result.error.message });
+        results.push({ file, result: null, error: result.error.message });
       }
     }
-    return {
+    return ok({
       success,
       failed,
       total: results.length,
       successful: success.length,
       results
-    };
+    });
   }
 };
 function createFileReferenceService(supabase) {
@@ -1649,22 +1714,54 @@ function createFileReferenceService(supabase) {
 }
 async function uploadFileWithReference(supabase, options, file) {
   const service = createFileReferenceService(supabase);
-  const fileReference = await service.createFileReference(options, file);
-  const fileUrl = options.is_public ? getPublicUrl(supabase, fileReference.file_path, true) : await getSignedUrl(supabase, fileReference.file_path, {
-    appName: "file-reference",
-    orgId: options.organisation_id || void 0,
-    userId: options.userId || void 0,
-    expiresIn: 3600
-  });
-  const urlString = typeof fileUrl === "string" ? fileUrl : fileUrl?.url || "";
-  return {
+  const result = await service.createFileReference(options, file);
+  if (!result.ok) {
+    return result;
+  }
+  const fileReference = result.data;
+  let urlString;
+  if (options.is_public) {
+    urlString = getPublicUrl(supabase, fileReference.file_path, true);
+  } else {
+    const signedResult = await getSignedUrl(supabase, fileReference.file_path, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId: options.userId || void 0,
+      expiresIn: 3600
+    });
+    urlString = signedResult.ok ? signedResult.data.url ?? "" : "";
+  }
+  return ok({
     file_reference: fileReference,
     file_url: urlString,
     signed_url: options.is_public ? void 0 : urlString || void 0
-  };
+  });
+}
+
+// src/components/FileDisplay/useFileDisplayData.ts
+async function fetchFileDisplayDataInternal(params) {
+  const { table_name, record_id, organisation_id, category, supabase } = params;
+  if (!supabase) {
+    return [];
+  }
+  let query = supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by").eq("table_name", table_name).eq("record_id", record_id);
+  if (organisation_id === void 0 || organisation_id === null) {
+    query = query.is("organisation_id", null);
+  } else {
+    query = query.eq("organisation_id", organisation_id);
+  }
+  if (category !== void 0 && category !== null) {
+    query = query.contains("file_metadata", { category });
+  }
+  const { data, error } = await query.order("created_at", { ascending: false });
+  if (error) {
+    throw new Error(error.message ?? "Failed to fetch file references");
+  }
+  const rows = data ?? [];
+  return rows.map(mapFileReferenceRowToFileReference);
 }
 
-// src/hooks/useFileDisplay.ts
+// src/components/FileDisplay/useFileDisplay.ts
 var authenticatedFileCache = /* @__PURE__ */ new Map();
 var MAX_CACHE_SIZE2 = 100;
 function cleanupCache() {
@@ -1683,6 +1780,111 @@ function cleanupCache() {
     toRemove.forEach(([key]) => authenticatedFileCache.delete(key));
   }
 }
+function getFileDisplayCacheKey(table_name, record_id, organisation_id, category) {
+  return `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
+}
+async function tryApplyCacheHit(cacheKey, enableCache, cacheTtl, supabase, organisation_id, record_id, safeSetState, setters) {
+  if (!enableCache || !supabase) return false;
+  const cached = authenticatedFileCache.get(cacheKey);
+  if (!cached || Date.now() - cached.timestamp >= cached.ttl) return false;
+  const cachedData = cached.data;
+  if (cachedData.fileReference && !cachedData.fileUrl && cachedData.fileReference.is_public === false && supabase) {
+    try {
+      const signedUrlResult = await getSignedUrl(supabase, cachedData.fileReference.file_path, {
+        appName: "pace-core",
+        orgId: organisation_id,
+        userId: organisation_id ? void 0 : record_id,
+        expiresIn: 3600
+      });
+      const regeneratedUrl = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      safeSetState(setters.setFileUrl, regeneratedUrl);
+      safeSetState(setters.setFileReference, cachedData.fileReference);
+      safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+      safeSetState(setters.setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
+      safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+      safeSetState(setters.setIsLoading, false);
+      safeSetState(setters.setError, null);
+      return true;
+    } catch (err2) {
+      logger.warn("useFileDisplay", "Failed to regenerate signed URL from cache, falling back to fetch:", err2);
+    }
+  }
+  safeSetState(setters.setFileUrl, cachedData.fileUrl || null);
+  safeSetState(setters.setFileReference, cachedData.fileReference || null);
+  safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+  safeSetState(setters.setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
+  safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+  safeSetState(setters.setIsLoading, false);
+  safeSetState(setters.setError, null);
+  return true;
+}
+async function applyFetchedFilesAndCache(files, category, table_name, record_id, organisation_id, supabase, cacheKey, enableCache, cacheTtl, safeSetState, setters) {
+  safeSetState(setters.setFileReferences, files);
+  safeSetState(setters.setFileCount, files.length);
+  if (category && files.length > 0) {
+    const firstFile = files[0];
+    safeSetState(setters.setFileReference, firstFile);
+    let url = null;
+    if (firstFile.is_public) {
+      url = getPublicUrl(supabase, firstFile.file_path, true);
+    } else {
+      const signedUrlResult = await getSignedUrl(supabase, firstFile.file_path, {
+        appName: "pace-core",
+        orgId: organisation_id,
+        userId: organisation_id ? void 0 : record_id,
+        expiresIn: 3600
+      });
+      url = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      if (!url) {
+        logger.warn("useFileDisplay", "Failed to generate signed URL for file:", {
+          file_path: firstFile.file_path,
+          record_id,
+          table_name
+        });
+      }
+    }
+    safeSetState(setters.setFileUrl, url);
+  } else {
+    const urlResult = await generateFileUrlsBatch(supabase, files, {
+      appName: "pace-core",
+      orgId: organisation_id,
+      userId: organisation_id ? void 0 : record_id,
+      expiresIn: 3600
+    });
+    const urlMap = urlResult.ok ? urlResult.data : /* @__PURE__ */ new Map();
+    safeSetState(setters.setFileUrls, urlMap);
+    safeSetState(setters.setFileReference, null);
+    safeSetState(setters.setFileUrl, null);
+  }
+  if (enableCache) {
+    const cacheData = {
+      fileUrl: null,
+      fileReference: category && files.length > 0 ? files[0] : null,
+      fileReferences: files,
+      fileUrls: /* @__PURE__ */ new Map(),
+      fileCount: files.length
+    };
+    if (category && files.length > 0) {
+      const firstFile = files[0];
+      cacheData.fileUrl = firstFile.is_public ? getPublicUrl(supabase, firstFile.file_path, true) : null;
+    } else {
+      const urlMap = /* @__PURE__ */ new Map();
+      for (const fileRef of files) {
+        if (fileRef.is_public) {
+          const url = getPublicUrl(supabase, fileRef.file_path, true);
+          if (url) urlMap.set(fileRef.id, url);
+        }
+      }
+      cacheData.fileUrls = urlMap;
+    }
+    authenticatedFileCache.set(cacheKey, {
+      data: cacheData,
+      timestamp: Date.now(),
+      ttl: cacheTtl
+    });
+    cleanupCache();
+  }
+}
 function useFileDisplay(table_name, record_id, organisation_id, category, options) {
   const {
     cacheTtl = 30 * 60 * 1e3,
@@ -1719,261 +1921,36 @@ function useFileDisplay(table_name, record_id, organisation_id, category, option
         logger.warn("useFileDisplay", "Invalid organisationId format (not a valid UUID):", organisation_id);
       }
     }
-    const cacheKey = `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
-    if (enableCache) {
-      const cached = authenticatedFileCache.get(cacheKey);
-      if (cached && Date.now() - cached.timestamp < cached.ttl) {
-        const cachedData = cached.data;
-        if (cachedData.fileReference && !cachedData.fileUrl && cachedData.fileReference.is_public === false && supabase) {
-          try {
-            const signedUrlResult = await getSignedUrl(supabase, cachedData.fileReference.file_path, {
-              appName: "pace-core",
-              orgId: organisation_id,
-              userId: organisation_id ? void 0 : record_id,
-              expiresIn: 3600
-            });
-            const regeneratedUrl = signedUrlResult?.url || null;
-            safeSetState(setFileUrl, regeneratedUrl);
-            safeSetState(setFileReference, cachedData.fileReference);
-            safeSetState(setFileReferences, cachedData.fileReferences || []);
-            safeSetState(setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
-            safeSetState(setFileCount, cachedData.fileCount || 0);
-            safeSetState(setIsLoading, false);
-            safeSetState(setError, null);
-            return;
-          } catch (err) {
-            logger.warn("useFileDisplay", "Failed to regenerate signed URL from cache, falling back to fetch:", err);
-          }
-        }
-        safeSetState(setFileUrl, cachedData.fileUrl || null);
-        safeSetState(setFileReference, cachedData.fileReference || null);
-        safeSetState(setFileReferences, cachedData.fileReferences || []);
-        safeSetState(setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
-        safeSetState(setFileCount, cachedData.fileCount || 0);
-        safeSetState(setIsLoading, false);
-        safeSetState(setError, null);
-        return;
+    safeSetState(setIsLoading, true);
+    safeSetState(setError, null);
+    const cacheKey = getFileDisplayCacheKey(table_name, record_id, organisation_id, category);
+    const applied = await tryApplyCacheHit(
+      cacheKey,
+      enableCache,
+      cacheTtl,
+      supabase,
+      organisation_id,
+      record_id,
+      safeSetState,
+      {
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
       }
-    }
+    );
+    if (applied) return;
     try {
-      safeSetState(setIsLoading, true);
-      safeSetState(setError, null);
-      const service = createFileReferenceService(supabase);
-      let files = [];
-      const shouldSearchBothScopes = organisation_id === void 0;
-      if (shouldSearchBothScopes) {
-        let userScopedFiles = [];
-        let orgScopedFiles = [];
-        try {
-          if (category) {
-            userScopedFiles = await service.getFilesByCategory(
-              table_name,
-              record_id,
-              category,
-              void 0
-              // Explicitly pass undefined for user-scoped files (service converts to null for RPC)
-            );
-          } else {
-            userScopedFiles = await service.listFileReferences(
-              table_name,
-              record_id,
-              void 0
-              // Explicitly pass undefined for user-scoped files (service converts to null for RPC)
-            );
-          }
-        } catch (err) {
-          logger.warn("useFileDisplay", "Error querying user-scoped files:", err);
-          userScopedFiles = [];
-        }
-        try {
-          const { data: { user }, error: userError } = await supabase.auth.getUser();
-          if (userError) {
-            logger.warn("useFileDisplay", "Error getting user:", userError);
-          }
-          if (user) {
-            const { data: memberships, error: membershipError } = await supabase.from("core_organisation_memberships").select("organisation_id").eq("user_id", user.id);
-            if (membershipError) {
-              logger.warn("useFileDisplay", "Error querying organisation memberships:", membershipError);
-            }
-            if (memberships && memberships.length > 0) {
-              const orgIds = memberships.map((m) => m.organisation_id).filter(Boolean);
-              const orgQueries = orgIds.map(async (orgId) => {
-                try {
-                  if (category) {
-                    return await service.getFilesByCategory(
-                      table_name,
-                      record_id,
-                      category,
-                      orgId
-                    );
-                  } else {
-                    return await service.listFileReferences(
-                      table_name,
-                      record_id,
-                      orgId
-                    );
-                  }
-                } catch (_err) {
-                  return [];
-                }
-              });
-              const orgResults = await Promise.all(orgQueries);
-              orgScopedFiles = orgResults.flat();
-            } else {
-              try {
-                let fallbackQuery = supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at").eq("table_name", table_name).eq("record_id", record_id).order("created_at", { ascending: false });
-                if (category) {
-                  fallbackQuery = fallbackQuery.eq("file_metadata->>category", category);
-                }
-                const { data: fallbackFiles } = await fallbackQuery;
-                if (fallbackFiles && fallbackFiles.length > 0) {
-                  orgScopedFiles = fallbackFiles.map((f) => {
-                    const fileName = f.file_path.split("/").pop() || "unknown";
-                    const fileType = fileName.split(".").pop() || "unknown";
-                    const metadata = f.file_metadata;
-                    return {
-                      id: f.id,
-                      table_name: f.table_name,
-                      record_id: f.record_id,
-                      file_path: f.file_path,
-                      file_metadata: {
-                        fileName: metadata?.fileName || fileName,
-                        fileType: metadata?.fileType || fileType,
-                        category: metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
-                        ...metadata || {}
-                      },
-                      organisation_id: f.organisation_id,
-                      app_id: f.app_id,
-                      is_public: f.is_public ?? false,
-                      created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                      updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
-                    };
-                  });
-                }
-              } catch (_err) {
-              }
-            }
-          }
-        } catch (err) {
-          logger.warn("useFileDisplay", "Error querying organisation-scoped files:", err);
-          orgScopedFiles = [];
-        }
-        const allFiles = [...userScopedFiles, ...orgScopedFiles];
-        allFiles.sort((a, b) => {
-          const aTime = new Date(a.created_at).getTime();
-          const bTime = new Date(b.created_at).getTime();
-          return bTime - aTime;
-        });
-        if (orgScopedFiles.length > 0 && userScopedFiles.length > 0) {
-          files = allFiles.filter((f) => f.organisation_id !== null);
-        } else {
-          files = allFiles;
-        }
-        if (files.length === 0) {
-          try {
-            let directQuery = supabase.from("core_file_references").select("id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at").eq("table_name", table_name).eq("record_id", record_id).order("created_at", { ascending: false });
-            if (category) {
-              directQuery = directQuery.eq("file_metadata->>category", category);
-            }
-            const { data: directFiles } = await directQuery;
-            if (directFiles && directFiles.length > 0) {
-              files = directFiles.map((f) => {
-                const fileName = f.file_path.split("/").pop() || "unknown";
-                const fileType = fileName.split(".").pop() || "unknown";
-                const metadata = f.file_metadata;
-                return {
-                  id: f.id,
-                  table_name: f.table_name,
-                  record_id: f.record_id,
-                  file_path: f.file_path,
-                  file_metadata: {
-                    fileName: metadata?.fileName || fileName,
-                    fileType: metadata?.fileType || fileType,
-                    category: metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
-                    ...metadata || {}
-                  },
-                  organisation_id: f.organisation_id,
-                  app_id: f.app_id,
-                  is_public: f.is_public ?? false,
-                  created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-                  updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
-                };
-              });
-            }
-          } catch (_err) {
-          }
-        }
-      } else {
-        if (category) {
-          files = await service.getFilesByCategory(
-            table_name,
-            record_id,
-            category,
-            organisation_id
-          );
-        } else {
-          files = await service.listFileReferences(
-            table_name,
-            record_id,
-            organisation_id
-          );
-        }
-        if (files.length === 0 && (!organisation_id || organisation_id === "")) {
-          let userScopedFiles = [];
-          let orgScopedFiles = [];
-          try {
-            if (category) {
-              userScopedFiles = await service.getFilesByCategory(
-                table_name,
-                record_id,
-                category,
-                void 0
-              );
-            } else {
-              userScopedFiles = await service.listFileReferences(
-                table_name,
-                record_id,
-                void 0
-              );
-            }
-          } catch (_err) {
-          }
-          try {
-            const { data: { user } } = await supabase.auth.getUser();
-            if (user) {
-              const { data: memberships } = await supabase.from("core_organisation_memberships").select("organisation_id").eq("user_id", user.id).or("status.is.null,status.eq.active");
-              if (memberships && memberships.length > 0) {
-                const orgIds = memberships.map((m) => m.organisation_id).filter(Boolean);
-                const orgQueries = orgIds.map(async (orgId) => {
-                  try {
-                    if (category) {
-                      return await service.getFilesByCategory(table_name, record_id, category, orgId);
-                    } else {
-                      return await service.listFileReferences(table_name, record_id, orgId);
-                    }
-                  } catch (_err) {
-                    return [];
-                  }
-                });
-                const orgResults = await Promise.all(orgQueries);
-                orgScopedFiles = orgResults.flat();
-              }
-            }
-          } catch (_err) {
-          }
-          const allFiles = [...userScopedFiles, ...orgScopedFiles];
-          allFiles.sort((a, b) => {
-            const aTime = new Date(a.created_at).getTime();
-            const bTime = new Date(b.created_at).getTime();
-            return bTime - aTime;
-          });
-          if (orgScopedFiles.length > 0 && userScopedFiles.length > 0) {
-            files = allFiles.filter((f) => f.organisation_id !== null);
-          } else {
-            files = allFiles;
-          }
-        }
-      }
+      const files = await fetchFileDisplayDataInternal({
+        table_name,
+        record_id,
+        organisation_id,
+        category,
+        supabase
+      });
       if (files.length === 0) {
         safeSetState(setFileUrl, null);
         safeSetState(setFileReference, null);
@@ -1990,79 +1967,22 @@ function useFileDisplay(table_name, record_id, organisation_id, category, option
         }
         return;
       }
-      safeSetState(setFileReferences, files);
-      safeSetState(setFileCount, files.length);
-      if (category && files.length > 0) {
-        const firstFile = files[0];
-        safeSetState(setFileReference, firstFile);
-        let url = null;
-        if (firstFile.is_public) {
-          url = getPublicUrl(supabase, firstFile.file_path, true);
-        } else {
-          const signedUrlResult = await getSignedUrl(supabase, firstFile.file_path, {
-            appName: "pace-core",
-            orgId: organisation_id,
-            userId: organisation_id ? void 0 : record_id,
-            expiresIn: 3600
-          });
-          url = signedUrlResult?.url || null;
-          if (!url) {
-            logger.warn("useFileDisplay", "Failed to generate signed URL for file:", {
-              file_path: firstFile.file_path,
-              record_id,
-              table_name
-            });
-          }
-        }
-        safeSetState(setFileUrl, url);
-      } else {
-        const urlMap = await generateFileUrlsBatch(supabase, files, {
-          appName: "pace-core",
-          orgId: organisation_id,
-          userId: organisation_id ? void 0 : record_id,
-          expiresIn: 3600
-        });
-        safeSetState(setFileUrls, urlMap);
-        safeSetState(setFileReference, null);
-        safeSetState(setFileUrl, null);
-      }
-      if (enableCache) {
-        const cacheData = {
-          fileUrl: null,
-          fileReference: category && files.length > 0 ? files[0] : null,
-          fileReferences: files,
-          fileUrls: /* @__PURE__ */ new Map(),
-          fileCount: files.length
-        };
-        if (category && files.length > 0) {
-          const firstFile = files[0];
-          let url = null;
-          if (firstFile.is_public) {
-            url = getPublicUrl(supabase, firstFile.file_path, true);
-          }
-          cacheData.fileUrl = url;
-        } else {
-          const urlMap = /* @__PURE__ */ new Map();
-          for (const fileRef of files) {
-            if (fileRef.is_public) {
-              const url = getPublicUrl(supabase, fileRef.file_path, true);
-              if (url) {
-                urlMap.set(fileRef.id, url);
-              }
-            }
-          }
-          cacheData.fileUrls = urlMap;
-        }
-        authenticatedFileCache.set(cacheKey, {
-          data: cacheData,
-          timestamp: Date.now(),
-          ttl: cacheTtl
-        });
-        cleanupCache();
-      }
-    } catch (err) {
-      logger.error("useFileDisplay", "Error fetching files:", err);
-      const error2 = err instanceof Error ? err : new Error("Unknown error occurred");
+      await applyFetchedFilesAndCache(
+        files,
+        category,
+        table_name,
+        record_id,
+        organisation_id,
+        supabase,
+        cacheKey,
+        enableCache,
+        cacheTtl,
+        safeSetState,
+        { setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount }
+      );
+    } catch (err2) {
+      logger.error("useFileDisplay", "Error fetching files:", err2);
+      const error2 = err2 instanceof Error ? err2 : new Error("Unknown error occurred");
       safeSetState(setError, error2);
       safeSetState(setFileUrl, null);
       safeSetState(setFileReference, null);
@@ -2076,9 +1996,9 @@ function useFileDisplay(table_name, record_id, organisation_id, category, option
   useEffect(() => {
     isMountedRef.current = true;
     if (table_name && record_id && supabase) {
-      fetchFiles().catch((err) => {
+      fetchFiles().catch((err2) => {
         if (isMountedRef.current) {
-          safeSetState(setError, err instanceof Error ? err : new Error("Unknown error"));
+          safeSetState(setError, err2 instanceof Error ? err2 : new Error("Unknown error"));
         }
       });
     } else {
@@ -2097,8 +2017,7 @@ function useFileDisplay(table_name, record_id, organisation_id, category, option
   const refetch = useCallback(async () => {
     if (!table_name || !record_id || !supabase) return;
     if (enableCache) {
-      const cacheKey = `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
-      authenticatedFileCache.delete(cacheKey);
+      authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, organisation_id, category));
     }
     await fetchFiles();
   }, [fetchFiles, table_name, record_id, organisation_id, category, supabase, enableCache]);
@@ -2128,18 +2047,48 @@ function getFileDisplayCacheStats() {
   };
 }
 function invalidateFileDisplayCache(table_name, record_id, organisation_id, category) {
-  const cacheKey = `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
-  authenticatedFileCache.delete(cacheKey);
+  const orgId = organisation_id ?? void 0;
+  authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, category));
   if (category) {
-    const allCategoryKey = `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_all`;
-    authenticatedFileCache.delete(allCategoryKey);
+    authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, void 0));
   }
 }
 var log4 = createLogger("useEventTheme");
 function useEventTheme(event) {
   const location = useLocation();
   const eventServiceContext = useContext(EventServiceContext);
-  const eventsContextSelectedEvent = eventServiceContext?.eventService?.getSelectedEvent() ?? null;
+  const eventService = eventServiceContext?.eventService ?? null;
+  useEffect(() => {
+    if (event !== void 0 || !eventService) return;
+    const applyThemeFromService = () => {
+      const isOnLoginRoute = location.pathname === "/login" || location.pathname.startsWith("/login/");
+      if (isOnLoginRoute) {
+        clearPalette();
+        return;
+      }
+      const current = eventService.getSelectedEvent();
+      if (!current?.event_colours) {
+        clearPalette();
+        return;
+      }
+      const normalized = parseAndNormalizeEventColours(current.event_colours);
+      if (normalized) {
+        try {
+          applyPalette(normalized, current.event_name ?? "");
+        } catch (err2) {
+          log4.error("Failed to apply event palette (subscription):", err2);
+        }
+      } else {
+        clearPalette();
+      }
+    };
+    applyThemeFromService();
+    const unsubscribe = eventService.subscribe(applyThemeFromService);
+    return () => {
+      unsubscribe();
+    };
+  }, [event, eventService, location.pathname]);
+  const eventsContextSelectedEvent = eventService?.getSelectedEvent() ?? null;
   const selectedEvent = event !== void 0 ? event : eventsContextSelectedEvent;
   useEffect(() => {
     const isOnLoginRoute = location.pathname === "/login" || location.pathname.startsWith("/login");
@@ -2147,6 +2096,9 @@ function useEventTheme(event) {
       clearPalette();
       return;
     }
+    if (event === void 0) {
+      return;
+    }
     if (!selectedEvent) {
       clearPalette();
       return;
@@ -2158,13 +2110,11 @@ function useEventTheme(event) {
       return;
     }
     try {
-      applyPalette(normalized);
+      applyPalette(normalized, selectedEvent.event_name ?? "");
     } catch (error) {
       log4.error("Failed to apply event palette:", error);
     }
-    return () => {
-    };
-  }, [selectedEvent, location.pathname]);
+  }, [selectedEvent, location.pathname, event]);
 }
 function usePreventTabReload(options = {}) {
   const { enabled = true, gracePeriodMs = 2e3 } = options;