Add downloadIfMissing parameter to media GetFileStream APIs.

backend/FwLite/FwDataMiniLcmBridge/Api/FwDataMiniLcmApi.cs

@@ -1957,7 +1957,7 @@ public Task DeletePicture(Guid entryId, Guid senseId, Guid pictureId)
         return Task.CompletedTask;
     }
 
-    public Task<ReadFileResponse> GetFileStream(MediaUri mediaUri)
+    public Task<ReadFileResponse> GetFileStream(MediaUri mediaUri, bool downloadIfMissing = true)
     {
         if (mediaUri == MediaUri.NotFound) return Task.FromResult(new ReadFileResponse(ReadFileResult.NotFound));
         var pathFromMediaUri = mediaAdapter.PathFromMediaUri(mediaUri, Cache);

backend/FwLite/FwLiteShared/Services/MediaFilesServiceJsInvokable.cs

@@ -32,9 +32,9 @@ public async Task<LcmFileMetadata> GetFileMetadata(Guid fileId)
     }
 
     [JSInvokable]
-    public async Task<MiniLcmJsInvokable.ReadFileResponseJs> GetFileStream(Guid fileId)
+    public async Task<MiniLcmJsInvokable.ReadFileResponseJs> GetFileStream(Guid fileId, bool downloadIfMissing)
     {
-        var result = await mediaService.GetFileStream(fileId);
+        var result = await mediaService.GetFileStream(fileId, downloadIfMissing);
         var stream = result.Stream is null ? null : new DotNetStreamReference(result.Stream);
         return new MiniLcmJsInvokable.ReadFileResponseJs(stream, result.FileName, result.Result, result.ErrorMessage);
     }

backend/FwLite/FwLiteShared/Services/MiniLcmJsInvokable.cs

@@ -522,9 +522,9 @@ public async Task DeletePicture(Guid entryId, Guid senseId, Guid pictureId)
     }
 
     [JSInvokable]
-    public async Task<ReadFileResponseJs?> GetFileStream(string mediaUri)
+    public async Task<ReadFileResponseJs?> GetFileStream(string mediaUri, bool downloadIfMissing)
     {
-        var result = await _wrappedApi.GetFileStream(new MediaUri(mediaUri));
+        var result = await _wrappedApi.GetFileStream(new MediaUri(mediaUri), downloadIfMissing);
         var stream = result.Stream is null ? null : new DotNetStreamReference(result.Stream);
         return new ReadFileResponseJs(stream, result.FileName, result.Result, result.ErrorMessage);
     }

backend/FwLite/LcmCrdt/CrdtMiniLcmApi.cs

@@ -998,10 +998,10 @@ public async Task DeletePicture(Guid entryId, Guid senseId, Guid pictureId)
         await AddChange(new RemoveSensePictureChange(pictureId, senseId));
     }
 
-    public async Task<ReadFileResponse> GetFileStream(MediaUri mediaUri)
+    public async Task<ReadFileResponse> GetFileStream(MediaUri mediaUri, bool downloadIfMissing = true)
     {
         if (mediaUri == MediaUri.NotFound) return new ReadFileResponse(ReadFileResult.NotFound);
-        return await lcmMediaService.GetFileStream(mediaUri.FileId);
+        return await lcmMediaService.GetFileStream(mediaUri.FileId, downloadIfMissing);
     }
 
     public async Task<UploadFileResponse> SaveFile(Stream stream, LcmFileMetadata metadata)

backend/FwLite/LcmCrdt/MediaServer/LcmMediaService.cs

@@ -56,10 +56,11 @@ public async Task DeleteResource(Guid fileId)
     }
 
     /// <summary>
-    /// return a stream for the file, if it's not cached locally, it will be downloaded
+    /// Return a stream for the file. When <paramref name="downloadIfMissing"/> is true (the default),
+    /// a file that is not cached locally will be downloaded first.
     /// </summary>
     /// <param name="fileId">media file Id</param>
-    /// <returns></returns>
+    /// <param name="downloadIfMissing">When false, returns <see cref="ReadFileResult.NotFound"/> if the file is not already cached locally.</param>
     /// <exception cref="FileNotFoundException"></exception>
     // Coalesces concurrent downloads of the same file into one shared task. Without this, two
     // requests for a not-yet-cached file (e.g. the UI loading a picture more than once at first
@@ -70,11 +71,12 @@ public async Task DeleteResource(Guid fileId)
     // parallel.
     private static readonly ConcurrentDictionary<Guid, Task<LocalResource>> DownloadTasks = new();
 
-    public async Task<ReadFileResponse> GetFileStream(Guid fileId)
+    public async Task<ReadFileResponse> GetFileStream(Guid fileId, bool downloadIfMissing = true)
     {
         var localResource = await resourceService.GetLocalResource(fileId);
         if (localResource is null)
         {
+            if (!downloadIfMissing) return new ReadFileResponse(ReadFileResult.NotFound);
             try
             {
                 localResource = await GetOrStartDownload(fileId);

backend/FwLite/MiniLcm/IMiniLcmReadApi.cs

@@ -37,7 +37,7 @@ public interface IMiniLcmReadApi
     /// </summary>
     Task<int> GetEntryIndex(Guid entryId, string? query = null, IndexQueryOptions? options = null);
 
-    Task<ReadFileResponse> GetFileStream(MediaUri mediaUri)
+    Task<ReadFileResponse> GetFileStream(MediaUri mediaUri, bool downloadIfMissing = true)
     {
         return Task.FromResult(new ReadFileResponse(ReadFileResult.NotSupported));
     }

frontend/viewer/src/lib/components/field-editors/audio-input.svelte

@@ -87,7 +87,7 @@
 
   async function defaultLoader(audioId: string) {
     if (!api) throw new Error('No api, unable to load audio');
-    const file = await api.getFileStream(audioId);
+    const file = await api.getFileStream(audioId, true);
     if (!file.stream) {
       switch (file.result) {
         case ReadFileResult.NotFound:

frontend/viewer/src/lib/dotnet-types/generated-types/FwLiteShared/Services/IMediaFilesServiceJsInvokable.ts

@@ -13,6 +13,6 @@ export interface IMediaFilesServiceJsInvokable
 	downloadResources(resourceIds: string[]) : Promise<void>;
 	uploadPendingResources() : Promise<void>;
 	getFileMetadata(fileId: string) : Promise<ILcmFileMetadata>;
-	getFileStream(fileId: string) : Promise<IReadFileResponseJs>;
+	getFileStream(fileId: string, downloadIfMissing: boolean) : Promise<IReadFileResponseJs>;
 }
 /* eslint-enable */

frontend/viewer/src/lib/dotnet-types/generated-types/FwLiteShared/Services/IMiniLcmJsInvokable.ts

@@ -100,7 +100,7 @@ export interface IMiniLcmJsInvokable
 	updatePicture(entryId: string, senseId: string, before: IPicture, after: IPicture) : Promise<IPicture>;
 	movePicture(entryId: string, senseId: string, pictureId: string, previousPictureId?: string, nextPictureId?: string) : Promise<void>;
 	deletePicture(entryId: string, senseId: string, pictureId: string) : Promise<void>;
-	getFileStream(mediaUri: string) : Promise<IReadFileResponseJs>;
+	getFileStream(mediaUri: string, downloadIfMissing: boolean) : Promise<IReadFileResponseJs>;
 	saveFile(streamReference: Blob | ArrayBuffer | Uint8Array, metadata: ILcmFileMetadata) : Promise<IUploadFileResponse>;
 }
 /* eslint-enable */

frontend/viewer/src/lib/entry-editor/field-editors/EditPictureDialog.svelte

@@ -69,7 +69,7 @@
     if (downloading) return;
     downloading = true;
     try {
-      const file = await api.getFileStream(mediaUri);
+      const file = await api.getFileStream(mediaUri, true);
       if (!file.stream) {
         AppNotification.display(file.errorMessage ?? $t`Unable to download the picture`, {type: 'error'});
         return;

frontend/viewer/src/lib/entry-editor/field-editors/PictureImage.svelte

@@ -38,7 +38,7 @@
   // branch on it rather than wrapping in try/catch (the global handler covers throws).
   async function loadImage(mediaUri: string): Promise<Exclude<LoadState, {status: 'loading'}>> {
     if (!api) return {status: 'error', message: $t`Unable to load image`};
-    const file = await api.getFileStream(mediaUri);
+    const file = await api.getFileStream(mediaUri, true);
     if (!file.stream) {
       switch (file.result) {
         case ReadFileResult.NotFound:

frontend/viewer/src/lib/media-manager/MediaFileDetail.svelte

@@ -64,7 +64,7 @@
     fileId: string,
     signal?: AbortSignal,
   ): Promise<{kind: 'success'; blob: Blob; filename?: string} | {kind: 'error'; response: IReadFileResponseJs}> {
-    const response = await service.getFileStream(fileId);
+    const response = await service.getFileStream(fileId, false);
     signal?.throwIfAborted();
     if (!response.stream) {
       return {kind: 'error', response};
@@ -94,7 +94,7 @@
         filename: loaded.filename ?? metadata.current?.filename ?? fileId,
       };
     }
-    const response = await mediaFilesService.getFileStream(fileId);
+    const response = await mediaFilesService.getFileStream(fileId, false);
     if (!response.stream) {
       AppNotification.error($t`Unable to load audio`, readFileErrorMessage(response.result, response.errorMessage));
       return LOADER_ERROR_HANDLED;
@@ -107,7 +107,7 @@
 
   const loadedMedia = resource(() => [file.id, file.local, mediaFilesService] as const,
     async ([fileId, local, service], _, {signal}) => {
-      // never fetch remote-only files: getFileStream implicitly downloads them, which is the Load button's job
+      // Remote-only files return NotFound when downloadIfMissing is false; the Load button handles fetching.
       if (!service || !local) return undefined;
 
       const result = await loadFileBlob(service, fileId, signal);

frontend/viewer/src/project/demo/in-memory-demo-api.ts

@@ -723,7 +723,7 @@ export class InMemoryDemoApi implements IMiniLcmJsInvokable {
   // filename (LcmMediaService keys by the file name within the project's resource cache).
   #uploadedFilenames = new Map<string, string>();
 
-  getFileStream(mediaUri: string): Promise<IReadFileResponseJs> {
+  getFileStream(mediaUri: string, _downloadIfMissing: boolean): Promise<IReadFileResponseJs> {
     const uploaded = this.#uploadedFiles.get(mediaUri);
     if (uploaded) {
       return Promise.resolve({