@wildo-ai/saas-frontend-lib 1.1.3 → 1.1.5

package/dist/esm/components/form/fields/form-field-file.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { awaitFileRequest, FileReadinessError, waitForFileReadiness } from '../controls/file/file-readiness.frontend.utils.js';
 import React, { forwardRef, useMemo } from 'react';
 import { FrontendComponentType, CorePresetNames } from '@wildo-ai/presets-components-models';
 import { createComponentResolverWithRef } from '../../../core/components-registry/component-resolver.frontend.helper.js';
@@ -11,9 +12,10 @@ import { IconSize, StandardIconReference } from "../../../core/icons/icon-regist
 import { LoadingSpinner } from "../../../components/feedback/loading-spinner.js";
 import { Button, ButtonVariants_Variant } from "../../../components/actions/button.js";
 import { UIBehavior, FormControlVariant, ButtonSize } from "@wildo-ai/presets-components-models";
-import { getFileMetadata, getFileUI, formatFileSize, isMimeTypeAllowed, getAcceptDescription, buildAcceptAttribute, FileDisplayNature, resolveFileDisplayNature, } from "@wildo-ai/zod-decorators";
+import { FileReadiness, getFileMetadata, getFileUI, formatFileSize, isMimeTypeAllowed, getAcceptedFileKinds, buildAcceptAttribute, FileDisplayNature, resolveFileDisplayNature, } from "@wildo-ai/zod-decorators";
 import { determineValidationMode, getZodErrorParams } from "../../../components/form/validation-errors/form-validation.js";
 import { resolveFormFieldFileProviderConstraints } from './form-field-file-provider-constraints.frontend.utils.js';
+import { describeAcceptedFileKinds } from './accepted-file-kinds-description.frontend.utils.js';
 import { ProviderFilePickerHost } from '../../../core/external-providers/ProviderFilePickerHost.js';
 import { ProviderFrontendSelectionDelivery } from '@wildo-ai/saas-models/public-runtime';
 import { ImageCrop } from '../../../components/form/controls/file/image-crop.js';
@@ -66,7 +68,7 @@ function getNeutralFileAttachmentLabel(filename, t) {
     return t('File attached') ?? 'File attached';
 }
 function getSafeFileMutationErrorMessage(fallbackMessage, _err) {
-    return fallbackMessage;
+    return _err instanceof FileReadinessError ? _err.message : fallbackMessage;
 }
 /**
  * FormFieldFile component
@@ -96,10 +98,11 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const metadataLoadFailedMessage = t('Unable to load file details') ?? 'Unable to load file details';
     // Get file metadata from schema
     const fileSchemaMetadata = getFileMetadata(schema);
-    const providerConstraints = resolveFormFieldFileProviderConstraints({
-        schema,
-        frontendProviderRegistry,
-    });
+    // The FIELD's own constraints. A provider's declared limits are laid under
+    // these inside `ProviderFilePickerHost`, per chosen provider (#380) — they do
+    // not reach the native upload below, which goes to the field's own storage and
+    // is no vendor's business.
+    const providerConstraints = resolveFormFieldFileProviderConstraints({ schema });
     // Get options from metadata
     const allowedMimeTypes = providerConstraints.allowedMimeTypes;
     const maxSize = providerConstraints.maxSize;
@@ -118,10 +121,6 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const [internalValue, setInternalValue] = React.useState(defaultValue ?? null);
     // Internal validation error state (Hybrid Pattern - see file header comment)
     const [internalError, setInternalError] = React.useState();
-    // P1-T09: Propagate internal errors to parent (FormField) for RHF sync
-    React.useEffect(() => {
-        onValidationError?.(internalError);
-    }, [internalError, onValidationError]);
     // Clear internal error when value is cleared (form reset or manual clear)
     const prevValueRef = React.useRef(controlledValue);
     React.useEffect(() => {
@@ -140,6 +139,20 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const [uploadProgress, setUploadProgress] = React.useState(0); // Aggregate progress for single mode
     const [fileMetadataMap, setFileMetadataMap] = React.useState(new Map());
     const [dragOver, setDragOver] = React.useState(false);
+    const readinessRequests = React.useRef(new Set());
+    const readinessGeneration = React.useRef(0);
+    const [pendingReadiness, setPendingReadiness] = React.useState(new Set());
+    const processingMessage = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_processing');
+    const unavailableMessage = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_unavailable');
+    const unverifiedMessage = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_readiness_unverified');
+    const cancelReadiness = React.useCallback(() => {
+        readinessGeneration.current += 1;
+        for (const request of readinessRequests.current)
+            request.abort();
+        for (const upload of uploadingFilesRef.current.values())
+            upload.abortController.abort();
+        readinessRequests.current.clear();
+    }, []);
     // File input ref
     const fileInputRef = React.useRef(null);
     // Controlled ⇔ the caller supplied a change handler (or a defined value).
@@ -152,7 +165,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const isControlled = onChange !== undefined || controlledValue !== undefined;
     const currentValue = controlledValue ?? internalValue;
     // Derived state
-    const uploading = uploadingFiles.size > 0;
+    const uploading = Array.from(uploadingFiles.values()).some(file => file.status === 'uploading');
     const currentFileId = isSingleFileValue(currentValue) ? currentValue.fileId : null;
     const currentFileIds = isMultipleFileValue(currentValue) ? currentValue.fileIds : [];
     const hasUploadCapability = isMultiple
@@ -170,6 +183,16 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     fileMetadataMapRef.current = fileMetadataMap;
     // Get first metadata for single file mode display
     const fileMetadata = currentFileId ? fileMetadataMap.get(currentFileId) ?? null : null;
+    const visibleIds = currentFileId ? [currentFileId] : currentFileIds;
+    const existingReadinessError = visibleIds.some(id => fileMetadataMap.get(id)?.readiness === FileReadiness.UNAVAILABLE)
+        ? unavailableMessage
+        : visibleIds.some(id => ![FileReadiness.READY, FileReadiness.ATTACHED].includes(fileMetadataMap.get(id)?.readiness))
+            ? processingMessage : undefined;
+    const failedUploadError = Array.from(uploadingFiles.values()).find(file => file.status === 'error')?.error;
+    const readinessError = uploading || pendingReadiness.size > 0 ? processingMessage : failedUploadError ?? existingReadinessError;
+    React.useEffect(() => {
+        onValidationError?.(internalError ?? readinessError);
+    }, [internalError, readinessError, onValidationError]);
     // ==========================================================================
     // HTTP OPERATIONS — delegates to the injected httpOperations interface
     // ==========================================================================
@@ -178,58 +201,89 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     // ==========================================================================
     // METADATA FETCHING — for existing files
     // ==========================================================================
+    React.useEffect(() => () => cancelReadiness(), [endpoints.getMetadata, endpoints.upload, endpoints.override, httpOperations, authenticatedGet, cancelReadiness]);
+    const metadataEndpointRef = React.useRef({ endpoint: endpoints.getMetadata, get: authenticatedGet });
     React.useEffect(() => {
-        if (!endpoints.getMetadata)
-            return;
-        // Determine which fileIds need metadata fetched
-        const idsToFetch = [];
-        if (currentFileId) {
-            idsToFetch.push(currentFileId);
-        }
-        if (currentFileIds.length > 0) {
-            idsToFetch.push(...currentFileIds);
+        const ids = currentFileId ? [currentFileId] : currentFileIds;
+        const endpointChanged = metadataEndpointRef.current.endpoint !== endpoints.getMetadata || metadataEndpointRef.current.get !== authenticatedGet;
+        metadataEndpointRef.current = { endpoint: endpoints.getMetadata, get: authenticatedGet };
+        if (endpointChanged) {
+            fileMetadataMapRef.current = new Map();
+            setFileMetadataMap(new Map());
         }
-        if (idsToFetch.length === 0) {
+        if (ids.length === 0) {
             setFileMetadataMap(new Map());
-            setInternalError((current) => current === metadataLoadFailedMessage ? undefined : current);
+            setInternalError(current => current === metadataLoadFailedMessage ? undefined : current);
             return;
         }
         let cancelled = false;
-        const fetchAll = async () => {
-            const newMap = new Map();
-            let metadataFetchFailed = false;
-            // Read from ref to get the latest cached metadata (avoids stale closure)
-            const cachedMap = fileMetadataMapRef.current;
-            await Promise.allSettled(idsToFetch.map(async (fileId) => {
-                // Skip if we already have metadata for this file (read from ref for freshness)
-                if (cachedMap.has(fileId)) {
-                    newMap.set(fileId, cachedMap.get(fileId));
+        const controller = new AbortController();
+        let timer;
+        const refresh = async () => {
+            let retry = false;
+            let failed = false;
+            const updates = new Map();
+            await Promise.all(ids.map(async (fileId) => {
+                const cached = fileMetadataMapRef.current.get(fileId);
+                if (cached && [FileReadiness.READY, FileReadiness.ATTACHED, FileReadiness.UNAVAILABLE].includes(cached.readiness))
+                    return;
+                if (!endpoints.getMetadata) {
+                    failed = true;
                     return;
                 }
                 try {
-                    // Build URL: endpoints.getMetadata is a template base, append /{fileId}/metadata
-                    // Backend route: GET /files/:fileId/metadata
-                    const url = `${endpoints.getMetadata}/${encodeURIComponent(fileId)}/metadata`;
-                    const data = await authenticatedGet(url);
-                    if (!cancelled) {
-                        newMap.set(fileId, data);
-                    }
+                    const data = await awaitFileRequest(() => authenticatedGet(`${endpoints.getMetadata}/${encodeURIComponent(fileId)}/metadata`), controller.signal, 120_000, metadataLoadFailedMessage);
+                    if (data.fileId !== fileId || !Object.values(FileReadiness).includes(data.readiness))
+                        throw new Error('Invalid file metadata');
+                    updates.set(fileId, data);
+                    if (data.readiness === FileReadiness.PROCESSING)
+                        retry = true;
                 }
                 catch {
-                    metadataFetchFailed = true;
+                    failed = true;
+                    retry = true;
                     console.warn('Unable to load file metadata for one or more files.');
                 }
             }));
-            if (!cancelled) {
-                setFileMetadataMap(newMap);
-                setInternalError((current) => (metadataFetchFailed
-                    ? metadataLoadFailedMessage
-                    : (current === metadataLoadFailedMessage ? undefined : current)));
-            }
+            if (cancelled)
+                return;
+            setFileMetadataMap(previous => {
+                const next = new Map(previous);
+                for (const [id, metadata] of updates)
+                    next.set(id, metadata);
+                return next;
+            });
+            setInternalError(current => failed ? metadataLoadFailedMessage : current === metadataLoadFailedMessage ? undefined : current);
+            if (retry)
+                timer = setTimeout(refresh, 2_000);
         };
-        fetchAll();
-        return () => { cancelled = true; };
+        void refresh();
+        return () => { cancelled = true; controller.abort(); if (timer)
+            clearTimeout(timer); };
     }, [currentFileId, fileIdsKey, endpoints.getMetadata, authenticatedGet, metadataLoadFailedMessage]);
+    const admitUploadResult = React.useCallback(async (result, signal) => {
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        if (signal?.aborted)
+            controller.abort();
+        signal?.addEventListener('abort', abort, { once: true });
+        readinessRequests.current.add(controller);
+        try {
+            const metadata = await waitForFileReadiness({
+                ...result, signal: controller.signal,
+                getMetadata: endpoints.getMetadata ? () => authenticatedGet(`${endpoints.getMetadata}/${encodeURIComponent(result.fileId)}/metadata`) : undefined,
+                onPending: () => setPendingReadiness(previous => new Set(previous).add(result.fileId)),
+                unavailableMessage, unverifiedMessage,
+            });
+            controller.signal.throwIfAborted();
+            return { fileId: result.fileId, metadata };
+        }
+        finally {
+            signal?.removeEventListener('abort', abort);
+            readinessRequests.current.delete(controller);
+            setPendingReadiness(previous => { const next = new Set(previous); next.delete(result.fileId); return next; });
+        }
+    }, [authenticatedGet, endpoints.getMetadata, unavailableMessage, unverifiedMessage]);
     // ==========================================================================
     // VALIDATION
     // ==========================================================================
@@ -242,7 +296,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const validateFileMimeType = React.useCallback((file) => {
         if (allowedMimeTypes && allowedMimeTypes.length > 0) {
             if (!isMimeTypeAllowed(file.type, allowedMimeTypes)) {
-                const accepted = getAcceptDescription(allowedMimeTypes);
+                const accepted = describeAcceptedFileKinds(getAcceptedFileKinds(allowedMimeTypes), tComponent);
                 return tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_type_not_allowed', { accepted });
             }
         }
@@ -276,12 +330,17 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
         if (isReplacing && existingFileId) {
             formData.append('fileId', existingFileId);
         }
-        return httpOperations.upload(uploadUrl, formData, { onProgress, signal });
-    }, [httpOperations]);
+        const request = () => httpOperations.upload(uploadUrl, formData, { onProgress, signal });
+        const result = signal ? await awaitFileRequest(request, signal, undefined, unverifiedMessage) : await request();
+        signal?.throwIfAborted();
+        return admitUploadResult(result, signal);
+    }, [httpOperations, admitUploadResult, unverifiedMessage]);
     // ==========================================================================
     // UPLOAD HANDLERS — single mode
     // ==========================================================================
     const handleSingleFileUpload = React.useCallback(async (file) => {
+        cancelReadiness();
+        const generation = readinessGeneration.current;
         const uploadUrl = resolveSingleFileUploadUrl(endpoints, currentFileId);
         if (!uploadUrl) {
             setInternalError(t('File uploads are unavailable for this field') ?? 'File uploads are unavailable for this field');
@@ -303,6 +362,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
                     abortController,
                 }]]));
         setUploadProgress(0);
+        onValidationError?.(processingMessage);
         setInternalError(undefined);
         try {
             const isReplacing = !!currentFileId;
@@ -316,6 +376,8 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
                     return next;
                 });
             }, abortController.signal);
+            if (generation !== readinessGeneration.current)
+                return;
             // Build new value
             const newValue = {
                 fileId: result.fileId,
@@ -347,19 +409,20 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
             }
         }
         catch (err) {
-            if (isCancellationError(err))
+            if (abortController.signal.aborted || generation !== readinessGeneration.current || isCancellationError(err))
                 return;
             setInternalError(getSafeFileMutationErrorMessage(uploadFailedMessage, err));
         }
         finally {
-            setUploadingFiles(new Map());
+            setUploadingFiles(previous => { const next = new Map(previous); next.delete(tempId); return next; });
             setUploadProgress(0);
         }
-    }, [currentFileId, endpoints, isControlled, onChange, t, validateFile, validationMode, schema, tErrorValidation, uploadSingleFile]);
+    }, [currentFileId, endpoints, isControlled, onChange, t, validateFile, validationMode, schema, tErrorValidation, uploadSingleFile, cancelReadiness, onValidationError, processingMessage, uploadFailedMessage]);
     // ==========================================================================
     // UPLOAD HANDLERS — multiple mode
     // ==========================================================================
     const handleMultipleFilesUpload = React.useCallback(async (files) => {
+        const generation = readinessGeneration.current;
         if (!hasActionableMultipleFileEndpoint(endpoints)) {
             setInternalError(t('File uploads are unavailable for this field') ?? 'File uploads are unavailable for this field');
             return;
@@ -383,6 +446,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
             }
             validFiles.push(file);
         }
+        onValidationError?.(processingMessage);
         setInternalError(undefined);
         // Create upload state for each file
         const initialStates = new Map();
@@ -444,7 +508,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
                 return result.fileId;
             }
             catch (err) {
-                if (isCancellationError(err)) {
+                if (abortController.signal.aborted || generation !== readinessGeneration.current || isCancellationError(err)) {
                     setUploadingFiles(prev => {
                         const next = new Map(prev);
                         next.delete(tempId);
@@ -473,9 +537,10 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
                 newFileIds.push(result.value);
             }
         }
-        if (newFileIds.length > 0) {
+        if (newFileIds.length > 0 && generation === readinessGeneration.current) {
             // Read latest file IDs via ref to avoid stale closure
             const updatedFileIds = [...currentFileIdsRef.current, ...newFileIds];
+            currentFileIdsRef.current = updatedFileIds;
             const newValue = {
                 fileIds: updatedFileIds,
                 updatedAt: new Date(),
@@ -485,14 +550,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
             }
             onChange?.(newValue);
         }
-        // Report errors if any uploads failed (exclude intentional cancellations)
-        const failedCount = results.filter(r => r.status === 'rejected' && !isCancellationError(r.reason)).length;
-        if (failedCount > 0 && failedCount < files.length) {
-            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'some_uploads_failed', { failed: failedCount, total: files.length }));
-        }
-        else if (failedCount === files.length) {
-            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'upload_failed'));
-        }
+        // Failed candidates own their visible error until explicitly dismissed.
         // Clear completed uploads from state (keep errors for display)
         setUploadingFiles(prev => {
             const next = new Map(prev);
@@ -502,7 +560,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
             }
             return next;
         });
-    }, [endpoints, isControlled, maxFiles, onChange, tComponent, uploadSingleFile, validateFile, uploadFailedMessage]);
+    }, [endpoints, isControlled, maxFiles, onChange, tComponent, uploadSingleFile, validateFile, uploadFailedMessage, onValidationError, processingMessage]);
     // ==========================================================================
     // CROP STEP — aspect-ratio-constrained image fields
     // ==========================================================================
@@ -581,59 +639,139 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
      * crop step and the upload pipeline are the ones already written here rather
      * than a second, provider-only path that would drift from them.
      *
-     * The third, REMOTE_REFERENCE, deliberately does NOT. It is an opaque id only
-     * the application backend can resolve, and the door it needs — an executor
-     * that fetches on the user's behalf with the connected account's credential —
-     * does not exist yet. So the field REFUSES it with a message instead of
-     * dropping it silently: a user who picks a file and sees nothing happen has
-     * no way to learn that the provider and the application disagree about who
-     * fetches. A provider declares its delivery kind and the host has already
-     * refused anything that contradicts that declaration, so this branch is a
-     * capability gap, never a malformed selection.
+     * The third, REMOTE_REFERENCE, carries no bytes: the file STAYS at the vendor
+     * and only the application backend can resolve the id (#394 P5). It goes to
+     * the SAME endpoint an upload does, as a JSON body, and the backend verifies
+     * the reference at the vendor as this person, holds it to the field's
+     * constraints, and creates the row in the vendor's storage. What comes back
+     * is a fileId, exactly as an upload's, so the value is committed by the same
+     * code. The host has already refused any selection that contradicts the
+     * provider's declaration, and the chooser offered this provider only because
+     * the field accepts its storage — so a refusal here is the vendor's or the
+     * backend's, and is shown as one message.
      */
-    const handleProviderSelections = React.useCallback(async (_providerRef, selections) => {
-        const files = [];
-        let sawRemoteReference = false;
-        let sawFetchFailure = false;
-        for (const selection of selections) {
-            if (selection.kind === ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE) {
-                files.push(selection.file);
-                continue;
+    const linkRemoteSelections = React.useCallback(async (providerRef, selections) => {
+        if (!isMultiple)
+            cancelReadiness();
+        const generation = readinessGeneration.current;
+        const toLink = isMultiple ? selections : selections.slice(0, 1);
+        const uploadUrl = isMultiple ? endpoints.upload : resolveSingleFileUploadUrl(endpoints, currentFileId);
+        if (!uploadUrl) {
+            setInternalError(t('File uploads are unavailable for this field') ?? 'File uploads are unavailable for this field');
+            return;
+        }
+        onValidationError?.(processingMessage);
+        setInternalError(undefined);
+        const results = await Promise.allSettled(toLink.map(async (selection) => {
+            const activityId = generateTempId();
+            setPendingReadiness(previous => new Set(previous).add(activityId));
+            const controller = new AbortController();
+            readinessRequests.current.add(controller);
+            try {
+                const linked = await awaitFileRequest(() => httpOperations.linkRemoteReference(uploadUrl, {
+                    remoteReference: {
+                        providerRef,
+                        externalId: selection.externalId,
+                        ...(selection.displayName !== undefined ? { displayName: selection.displayName } : {}),
+                        ...(selection.mimeType !== undefined ? { mimeType: selection.mimeType } : {}),
+                        ...(selection.sizeBytes !== undefined ? { sizeBytes: selection.sizeBytes } : {}),
+                    },
+                }), controller.signal, 120_000, unverifiedMessage);
+                controller.signal.throwIfAborted();
+                const result = await admitUploadResult(linked, controller.signal);
+                if (result.metadata) {
+                    setFileMetadataMap(prev => {
+                        const next = new Map(prev);
+                        next.set(result.fileId, result.metadata);
+                        return next;
+                    });
+                }
+                return result.fileId;
             }
-            if (selection.kind === ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL) {
-                try {
-                    // The url is fetchable by the browser BY DECLARATION — its origin has
-                    // to be admitted by the surface's composed CSP, which is the
-                    // application's decision and not something this field can check. A
-                    // blocked origin therefore arrives here as an ordinary fetch failure.
-                    const response = await fetch(selection.url);
-                    if (!response.ok) {
+            finally {
+                readinessRequests.current.delete(controller);
+                setPendingReadiness(previous => { const next = new Set(previous); next.delete(activityId); return next; });
+            }
+        }));
+        const linkedFileIds = results.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
+        if (linkedFileIds.length > 0 && generation === readinessGeneration.current) {
+            const newValue = isMultiple
+                ? { fileIds: [...currentFileIdsRef.current, ...linkedFileIds], updatedAt: new Date() }
+                : { fileId: linkedFileIds[0], updatedAt: new Date() };
+            if (isMultipleFileValue(newValue))
+                currentFileIdsRef.current = newValue.fileIds;
+            if (!isControlled) {
+                setInternalValue(newValue);
+            }
+            onChange?.(newValue);
+        }
+        if (linkedFileIds.length < toLink.length && generation === readinessGeneration.current) {
+            const failure = results.find(result => result.status === 'rejected');
+            setInternalError(getSafeFileMutationErrorMessage(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_link_failed'), failure?.status === 'rejected' ? failure.reason : undefined));
+        }
+    }, [currentFileId, endpoints, httpOperations, isControlled, isMultiple, onChange, t, tComponent, admitUploadResult, cancelReadiness, onValidationError, processingMessage, unverifiedMessage]);
+    const handleProviderSelections = React.useCallback(async (providerRef, selections) => {
+        if (!isMultiple)
+            cancelReadiness();
+        const generation = readinessGeneration.current;
+        const acquisition = new AbortController();
+        const activityId = generateTempId();
+        readinessRequests.current.add(acquisition);
+        onValidationError?.(processingMessage);
+        setPendingReadiness(previous => new Set(previous).add(activityId));
+        try {
+            const files = [];
+            const remoteReferences = [];
+            let sawFetchFailure = false;
+            for (const selection of selections) {
+                if (selection.kind === ProviderFrontendSelectionDelivery.BROWSER_READABLE_FILE) {
+                    files.push(selection.file);
+                    continue;
+                }
+                if (selection.kind === ProviderFrontendSelectionDelivery.BROWSER_READABLE_URL) {
+                    try {
+                        // The url is fetchable by the browser BY DECLARATION — its origin has
+                        // to be admitted by the surface's composed CSP, which is the
+                        // application's decision and not something this field can check. A
+                        // blocked origin therefore arrives here as an ordinary fetch failure.
+                        const response = await awaitFileRequest(() => fetch(selection.url, { signal: acquisition.signal }), acquisition.signal, 120_000, unverifiedMessage);
+                        if (!response.ok) {
+                            sawFetchFailure = true;
+                            continue;
+                        }
+                        const blob = await awaitFileRequest(() => response.blob(), acquisition.signal, 120_000, unverifiedMessage);
+                        files.push(new File([blob], selection.displayName ?? 'file', { type: selection.mimeType ?? blob.type }));
+                    }
+                    catch {
+                        if (acquisition.signal.aborted || generation !== readinessGeneration.current)
+                            return;
                         sawFetchFailure = true;
-                        continue;
                     }
-                    const blob = await response.blob();
-                    files.push(new File([blob], selection.displayName ?? 'file', { type: selection.mimeType ?? blob.type }));
-                }
-                catch {
-                    sawFetchFailure = true;
+                    continue;
                 }
-                continue;
+                remoteReferences.push(selection);
             }
-            sawRemoteReference = true;
-        }
-        if (sawRemoteReference) {
-            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_selection_not_supported'));
-            return;
+            if (acquisition.signal.aborted || generation !== readinessGeneration.current)
+                return;
+            if (remoteReferences.length > 0) {
+                await linkRemoteSelections(providerRef, remoteReferences);
+                // A picker has one declared delivery kind. Remote linking owns the handoff and cancellation.
+                return;
+            }
+            if (sawFetchFailure && files.length === 0) {
+                setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_fetch_failed'));
+                return;
+            }
+            if (files.length === 0)
+                return;
+            setInternalError(sawFetchFailure ? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_fetch_failed') : undefined);
+            handleFiles(files);
         }
-        if (sawFetchFailure && files.length === 0) {
-            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_fetch_failed'));
-            return;
+        finally {
+            readinessRequests.current.delete(acquisition);
+            setPendingReadiness(previous => { const next = new Set(previous); next.delete(activityId); return next; });
         }
-        if (files.length === 0)
-            return;
-        setInternalError(sawFetchFailure ? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'provider_fetch_failed') : undefined);
-        handleFiles(files);
-    }, [handleFiles, tComponent]);
+    }, [handleFiles, linkRemoteSelections, tComponent, isMultiple, cancelReadiness, onValidationError, processingMessage, unverifiedMessage]);
     /*
      * A picker that failed and a picker that contradicted its own declaration
      * reach here as one message, because they are one thing to the person looking
@@ -683,6 +821,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     }, [isUploadInteractionDisabled, uploading, handleFiles]);
     // Handle remove single file
     const handleRemoveSingle = React.useCallback(async () => {
+        cancelReadiness();
         if (!currentFileId)
             return;
         if (endpoints.delete) {
@@ -713,6 +852,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     // Uses currentFileIdsRef to avoid stale closure: two rapid removes would both
     // capture the same closure value, and the second would re-add the file removed by the first.
     const handleRemoveFromMultiple = React.useCallback(async (fileId) => {
+        cancelReadiness();
         if (endpoints.delete) {
             try {
                 const url = `${endpoints.delete}/${encodeURIComponent(fileId)}`;
@@ -728,6 +868,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
         setInternalError(undefined);
         // Read latest file IDs via ref — prevents lost removals during rapid clicks
         const updatedIds = currentFileIdsRef.current.filter(id => id !== fileId);
+        currentFileIdsRef.current = updatedIds;
         const newValue = updatedIds.length > 0
             ? { fileIds: updatedIds, updatedAt: new Date() }
             : null;
@@ -788,7 +929,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const renderFileIcon = (mimeType, size = IconSize.MD) => {
         return renderIcon(getFileIconRef(mimeType), { size });
     };
-    const acceptDescription = getAcceptDescription(allowedMimeTypes);
+    const acceptDescription = describeAcceptedFileKinds(getAcceptedFileKinds(allowedMimeTypes), tComponent);
     // ==========================================================================
     // RENDER — Nature detection for preview routing
     // ==========================================================================
@@ -812,6 +953,8 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     // RENDER — Single file display (nature-aware)
     // ==========================================================================
     const renderSingleFileDisplay = (fileId, meta) => {
+        if (meta && ![FileReadiness.READY, FileReadiness.ATTACHED].includes(meta.readiness))
+            meta = { ...meta, url: undefined, thumbnailUrl: undefined };
         if (!meta) {
             // No metadata yet — show generic card
             return (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border bg-muted/30", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(undefined, IconSize.LG) }), renderFileInfo(fileId, null), renderFileActions(handleRemoveSingle)] }));
@@ -835,6 +978,8 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     // ==========================================================================
     /** Render a single item within the multiple-file list */
     const renderMultipleFileItem = (fileId, meta) => {
+        if (meta && ![FileReadiness.READY, FileReadiness.ATTACHED].includes(meta.readiness))
+            meta = { ...meta, url: undefined, thumbnailUrl: undefined };
         const nature = resolveFileDisplayNature(schemaNature, meta?.mimeType);
         const onRemove = () => handleRemoveFromMultiple(fileId);
         // Compact image preview — thumbnail inline
@@ -851,7 +996,7 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
     const renderMultipleFileList = () => (_jsxs("div", { className: "space-y-element", children: [currentFileIds.map((fileId) => {
                 const meta = fileMetadataMap.get(fileId);
                 return renderMultipleFileItem(fileId, meta);
-            }), Array.from(uploadingFiles.values()).map((uploadState) => (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border border-primary/20 bg-primary/5", children: [uploadState.status === 'uploading' && (_jsx(LoadingSpinner, { size: 20, className: "text-primary flex-shrink-0", "aria-hidden": "true" })), uploadState.status === 'error' && (_jsx("span", { className: "text-destructive flex-shrink-0", "aria-hidden": "true", children: renderIcon(StandardIconReference.WARNING, { size: IconSize.MD }) })), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("span", { className: "font-medium text-sm truncate block", children: uploadState.fileName }), uploadState.status === 'uploading' && (_jsx("div", { className: "w-full h-1 bg-muted rounded-full mt-1 overflow-hidden", children: uploadState.progress < 0 ? (_jsx("div", { className: "h-full w-1/3 bg-primary animate-pulse rounded-full" })) : (_jsx("div", { className: "h-full bg-primary transition-all duration-[var(--motion-duration-fast)]", style: { width: `${uploadState.progress}%` } })) })), uploadState.status === 'error' && uploadState.error && (_jsx("span", { className: "text-xs text-destructive", children: uploadState.error }))] }), uploadState.status === 'uploading' && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, onClick: () => handleCancelUpload(uploadState.tempId), className: "text-muted-foreground hover:text-destructive h-6 w-6 p-0", "aria-label": tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), title: tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), children: renderIcon(StandardIconReference.CLOSE, { size: IconSize.SM }) }))] }, uploadState.tempId)))] }));
+            }), Array.from(uploadingFiles.values()).map((uploadState) => (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border border-primary/20 bg-primary/5", children: [uploadState.status === 'uploading' && (_jsx(LoadingSpinner, { size: 20, className: "text-primary flex-shrink-0", "aria-hidden": "true" })), uploadState.status === 'error' && (_jsx("span", { className: "text-destructive flex-shrink-0", "aria-hidden": "true", children: renderIcon(StandardIconReference.WARNING, { size: IconSize.MD }) })), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("span", { className: "font-medium text-sm truncate block", children: uploadState.fileName }), uploadState.status === 'uploading' && (_jsx("div", { className: "w-full h-1 bg-muted rounded-full mt-1 overflow-hidden", children: uploadState.progress < 0 ? (_jsx("div", { className: "h-full w-1/3 bg-primary animate-pulse rounded-full" })) : (_jsx("div", { className: "h-full bg-primary transition-all duration-[var(--motion-duration-fast)]", style: { width: `${uploadState.progress}%` } })) })), uploadState.status === 'error' && uploadState.error && (_jsx("span", { className: "text-xs text-destructive", children: uploadState.error }))] }), (uploadState.status === 'uploading' || uploadState.status === 'error') && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, onClick: () => handleCancelUpload(uploadState.tempId), className: "text-muted-foreground hover:text-destructive h-6 w-6 p-0", "aria-label": tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), title: tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), children: renderIcon(StandardIconReference.CLOSE, { size: IconSize.SM }) }))] }, uploadState.tempId)))] }));
     // ==========================================================================
     // RENDER — Constraint hints (below upload area)
     // ==========================================================================
@@ -946,12 +1091,12 @@ export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, va
      * name is an i18n KEY: the host cannot resolve it without depending on the
      * i18n service, and this field already has one.
      */
-    const renderProviderPickers = () => (_jsx(ProviderFilePickerHost, { constraints: providerConstraints, onSelect: handleProviderSelections, onProviderFailure: handleProviderFailure, renderChooser: ({ choices, chosen, choose }) => (_jsx("div", { role: "group", className: "flex flex-wrap gap-item-xs mt-element", children: choices.map((choice) => (_jsx(Button, { type: "button", size: ButtonSize.SM, variant: choice.providerRef === chosen ? ButtonVariants_Variant.DEFAULT : ButtonVariants_Variant.OUTLINE, "aria-pressed": choice.providerRef === chosen, onClick: () => choose(choice.providerRef), children: t(choice.displayNameLabelKey) ?? choice.displayName ?? choice.providerRef }, choice.providerRef))) })) }));
+    const renderProviderPickers = () => (_jsx(ProviderFilePickerHost, { multiple: isMultiple, constraints: providerConstraints, acceptedStorages: fileSchemaMetadata?.storageAccepted, onSelect: handleProviderSelections, onProviderFailure: handleProviderFailure, renderChooser: ({ choices, chosen, choose }) => (_jsx("div", { role: "group", className: "flex flex-wrap gap-item-xs mt-element", children: choices.map((choice) => (_jsx(Button, { type: "button", size: ButtonSize.SM, variant: choice.providerRef === chosen ? ButtonVariants_Variant.DEFAULT : ButtonVariants_Variant.OUTLINE, "aria-pressed": choice.providerRef === chosen, onClick: () => choose(choice.providerRef), children: t(choice.displayNameLabelKey) ?? choice.displayName ?? choice.providerRef }, choice.providerRef))) })) }));
     if (!isReady)
         return null;
-    return (_jsxs("div", { ref: ref, className: className, children: [_jsx("input", { ref: fileInputRef, type: "file", accept: accept, multiple: isMultiple, onChange: handleFileChange, className: "hidden", disabled: isUploadInteractionDisabled }), isMultiple ? (
+    return (_jsxs("div", { ref: ref, className: className, children: [(internalError ?? readinessError) && _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: internalError ?? readinessError }), pendingReadiness.size > 0 && _jsx(Button, { type: "button", onClick: cancelReadiness, children: tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel') }), _jsx("input", { ref: fileInputRef, type: "file", accept: accept, multiple: isMultiple, onChange: handleFileChange, className: "hidden", disabled: isUploadInteractionDisabled }), isMultiple ? (
             // Multiple file mode
-            _jsxs("div", { className: "space-y-element", children: [currentFileIds.length > 0 && renderMultipleFileList(), !isUploadInteractionDisabled && canAddMore && renderUploadZone(currentFileIds.length > 0), !isUploadInteractionDisabled && currentFileIds.length === 0 && !canAddMore && renderUploadZone(false), !isUploadInteractionDisabled && canAddMore && renderProviderPickers()] })) : (
+            _jsxs("div", { className: "space-y-element", children: [(currentFileIds.length > 0 || uploadingFiles.size > 0) && renderMultipleFileList(), !isUploadInteractionDisabled && canAddMore && renderUploadZone(currentFileIds.length > 0), !isUploadInteractionDisabled && currentFileIds.length === 0 && !canAddMore && renderUploadZone(false), !isUploadInteractionDisabled && canAddMore && renderProviderPickers()] })) : (
             // Single file mode
             currentFileId
                 ? renderSingleFileDisplay(currentFileId, fileMetadata)
@@ -992,6 +1137,14 @@ export const FormFieldFile = forwardRef(({ preset = CorePresetNames.DEFAULT, htt
                 }
                 throw new Error('upload_failed');
             },
+            linkRemoteReference: async (url, body) => {
+                // Same route, same response shape as an upload — see `FileHttpOperations`.
+                const response = await httpClient.post(url, body);
+                if (response?.file?.fileId) {
+                    return { fileId: response.file.fileId, metadata: response.file };
+                }
+                throw new Error('link_failed');
+            },
             get: async (url) => {
                 return httpClient.get(url);
             },