@aws-amplify/ui-react-storage 3.17.2 → 3.18.0

package/dist/{createStorageBrowser-CtfBkr62.js → createStorageBrowser-S_PgkSVv.js}

@@ -33,8 +33,6 @@ function _interopNamespace(e) {
 
 var React__namespace = /*#__PURE__*/_interopNamespace(React);
 
-const VERSION = '3.17.2';
-
 const DEFAULT_CHECKSUM_ALGORITHM = 'crc-32';
 // 5MiB for multipart upload
 // https://github.com/aws-amplify/amplify-js/blob/1a5366d113c9af4ce994168653df3aadb142c581/packages/storage/src/providers/s3/utils/constants.ts#L16
@@ -208,138 +206,30 @@ const createFileDataItem = (data) => ({
     ...data,
     fileKey: getFileKey(data.key),
 });
-const getProgress = ({ totalBytes, transferredBytes, }) => totalBytes ? transferredBytes / totalBytes : undefined;
-const isMultipartUpload = (file) => file.size > MULTIPART_UPLOAD_THRESHOLD_BYTES;
-
-const toAccessGrantPermission = (permission) => {
-    let result = '';
-    permission.forEach((access) => {
-        if (['read', 'get', 'list'].includes(access)) {
-            if (!result.includes('READ')) {
-                result = 'READ' + result;
-            }
-        }
-        if (['write', 'delete'].includes(access)) {
-            if (!result.includes('WRITE')) {
-                result += 'WRITE';
-            }
-        }
-    });
-    if (result === '') {
-        throw new Error('Improper Permission: Please provide correct permission.');
-    }
-    return result;
-};
-const parseAmplifyAuthPermission = (permissions) => {
-    const result = [];
-    permissions.forEach((access) => {
-        if (access === 'read') {
-            if (!result.includes('list')) {
-                result.push('list');
-            }
-            if (!result.includes('get')) {
-                result.push('get');
-            }
-        }
-        else if (['delete', 'get', 'list', 'write'].includes(access) &&
-            !result.includes(access)) {
-            result.push(access);
-        }
-    });
-    if (result.length === 0) {
-        throw new Error('Improper Permission: Please provide correct permission.');
-    }
-    return result.sort();
-};
-
-const getPaginatedLocations = ({ items, pageSize, nextToken, }) => {
-    if (pageSize) {
-        if (nextToken) {
-            if (Number(nextToken) > items.length) {
-                return { items: [], nextToken: undefined };
-            }
-            const start = parseInt(nextToken, 10) * -1;
-            const end = start + pageSize < 0 ? start + pageSize : undefined;
-            return {
-                items: items.slice(start, end),
-                nextToken: end ? `${-end}` : undefined,
-            };
-        }
-        return {
-            items: items.slice(0, pageSize),
-            nextToken: items.length > pageSize ? `${items.length - pageSize}` : undefined,
-        };
-    }
-    return { items, nextToken: undefined };
-};
-
-const createAmplifyListLocationsHandler = () => {
-    let cachedItems = [];
-    return async function listLocations(input) {
-        const { options } = input ?? {};
-        const { nextToken, pageSize } = options ?? {};
-        if (cachedItems.length > 0) {
-            return getPaginatedLocations({
-                items: cachedItems,
-                pageSize,
-                nextToken,
-            });
-        }
-        const { locations } = await internals.listPaths();
-        const sanitizedItems = locations.map(({ bucket, permission, prefix, type }) => {
-            return {
-                type,
-                permissions: parseAmplifyAuthPermission(permission),
-                bucket,
-                prefix: prefix.endsWith('*') ? prefix.slice(0, -1) : prefix,
-                id: crypto.randomUUID(),
-            };
-        });
-        // Deduplicate locations with the same bucket and prefix, keeping broader permissions
-        cachedItems = deduplicateLocations(sanitizedItems);
-        return getPaginatedLocations({
-            items: cachedItems,
-            pageSize,
-            nextToken,
-        });
-    };
-};
-
-const MISSING_BUCKET_OR_REGION_ERROR = 'Amplify Storage configuration not found. Did you run `Amplify.configure` from your project root?';
-const MISSING_IDENTITY_ID_ERROR = '`identityId` not found.';
-const MISSING_TEMPORARY_CREDENTIALS_ERROR = 'Temporary Auth `credentials` not found.';
-const isTemporaryCredentials = (value) => !!value?.sessionToken || !!value?.expiration;
-const createAmplifyAuthAdapter = () => {
-    const { bucket, region } = awsAmplify.Amplify.getConfig()?.Storage?.S3 ?? {};
-    if (!bucket || !region) {
-        throw new Error(MISSING_BUCKET_OR_REGION_ERROR);
-    }
-    const listLocations = createAmplifyListLocationsHandler();
-    const getLocationCredentials = async () => {
-        const { credentials, identityId } = await auth.fetchAuthSession();
-        if (!isTemporaryCredentials(credentials)) {
-            throw new Error(MISSING_TEMPORARY_CREDENTIALS_ERROR);
-        }
-        if (!identityId) {
-            throw new Error(MISSING_IDENTITY_ID_ERROR);
-        }
-        return { credentials, identityId };
-    };
-    const registerAuthListener = (onStateChange) => {
-        const remove = utils.Hub.listen('auth', (data) => {
-            if (data.payload.event === 'signedOut') {
-                onStateChange();
-                remove();
-            }
-        });
-    };
+/**
+ * Builds a download item ({@link DownloadHandlerData}) from a {@link FileData}
+ * plus the current browse-location prefix `P`.
+ *
+ * `relativePath = key.slice(P.length)` yields a zip entry path relative to the
+ * selected folder's *parent* (e.g. selecting `photos/` produces entries like
+ * `photos/vacation/beach.jpg`). This keeps each top-level folder name as a
+ * namespace, avoiding collisions across multiple selected folders. For loose
+ * files at the current prefix it reduces to the basename.
+ */
+const createDownloadItem = (data, locationPrefix) => {
+    // Assumes `locationPrefix` is '' or ends in '/' (StorageBrowser convention),
+    // so the slice yields a clean folder-relative path with no leading segment.
+    // Defensive: strip a single leading '/' so a prefix NOT ending in '/' can
+    // never yield a leading-slash (absolute) zip entry path.
+    const sliced = data.key.slice(locationPrefix.length);
     return {
-        getLocationCredentials,
-        listLocations,
-        registerAuthListener,
-        region,
+        ...data,
+        fileKey: getFileKey(data.key),
+        relativePath: sliced.startsWith('/') ? sliced.slice(1) : sliced,
     };
 };
+const getProgress = ({ totalBytes, transferredBytes, }) => totalBytes ? transferredBytes / totalBytes : undefined;
+const isMultipartUpload = (file) => file.size > MULTIPART_UPLOAD_THRESHOLD_BYTES;
 
 const copyHandler = (input) => {
     const { config, data } = input;
@@ -482,7 +372,7 @@ function downloadFromUrl(fileName, url) {
     a.click();
     document.body.removeChild(a);
 }
-const downloadHandler$1 = ({ config, data }) => {
+const downloadHandler = ({ config, data, }) => {
     const { accountId, credentials, customEndpoint } = config;
     const { key } = data;
     const result = internals.getUrl({
@@ -507,70 +397,176 @@ const downloadHandler$1 = ({ config, data }) => {
     return { result };
 };
 
-const zipper = (() => {
-    let blobWriter = null;
-    let zipWriter = null;
-    return {
-        addFile: async (file, name, options) => {
-            const { data, signal, onProgress } = options ?? {};
-            if (!blobWriter) {
-                blobWriter = new zip_js.BlobWriter('application/zip');
-                zipWriter = new zip_js.ZipWriter(blobWriter);
-            }
-            await zipWriter.add(name, new zip_js.BlobReader(file), {
-                level: 0,
-                signal,
-                onprogress: (progress, total) => {
-                    if (ui.isFunction(onProgress) && data) {
-                        onProgress(progress / total, name, data);
-                    }
-                    return undefined;
-                },
-            });
-        },
-        getBlobUrl: async () => {
-            if (!zipWriter) {
-                throw new Error('no zip');
-            }
-            const blob = await zipWriter.close();
-            zipWriter = null;
-            blobWriter = null;
-            return URL.createObjectURL(blob);
-        },
-        destroy: () => {
-            zipWriter = null;
-            blobWriter = null;
-        },
-    };
-})();
+/**
+ * Zip Download Handler
+ *
+ * Downloads multiple S3 files sequentially into a streaming zip archive,
+ * delivered via service worker (with blob fallback for browsers without SW support).
+ *
+ * State machine: IDLE → DOWNLOADING → COMPLETE | CANCELLED
+ *
+ * Batch state is scoped per download session using a WeakMap keyed by the `all`
+ * array identity (guaranteed stable per useProcessTasks invocation).
+ * This avoids module-level singleton issues if multiple StorageBrowser instances
+ * share the same module.
+ *
+ * Cancel paths:
+ * - UI cancel (onActionCancel button): cancelBatch() → aborts fetch + writable → reset
+ * - Browser-dialog cancel: SW stream closes → addPromise rejects → cancelled=true → drain remaining files
+ */
+/**
+ * Batch state is keyed by a stable serialization of the file IDs in the batch.
+ * useProcessTasks recreates the `all` array on each handler call (spread + map),
+ * so we cannot rely on reference identity. Sorting IDs produces a deterministic
+ * key that remains identical across calls for the same set of files.
+ */
+const batchMap = new Map();
+/** Derives a stable batch key from the task data array. */
+const getBatchKey = (all) => all
+    .map((item) => item.id)
+    .sort()
+    .join('\0');
+/** Tears down all listeners and removes batch from map. */
+const reset = (batchKey, state) => {
+    if (state.keepaliveInterval) {
+        clearInterval(state.keepaliveInterval);
+    }
+    batchMap.delete(batchKey);
+};
+/**
+ * Marks the batch cancelled and tears down the active stream, but deliberately
+ * KEEPS the batchMap entry alive. Idempotent.
+ *
+ * The `cancelled` sentinel and the map entry share one key, so deleting the
+ * entry here would erase the very flag the drain path relies on: with
+ * `concurrency: 1`, useProcessTasks re-dispatches each remaining QUEUED file to
+ * the handler on settle. If the entry were gone, those files would miss the
+ * `existingBatch.cancelled` early-exit and build a brand-new batch — resurrecting
+ * the download. Instead we leave a tombstoned entry; the remaining files hit the
+ * early-exit branch and `reset()` runs only once `batchDone === batchTotal`
+ * (in the STEP 1 early-exit or onFileSettled), for both cancel and completion.
+ */
+const cancelBatch = (batchKey) => {
+    const state = batchMap.get(batchKey);
+    if (!state || state.cancelled)
+        return;
+    state.cancelled = true;
+    state.batchAbort.abort();
+    // Terminate the SW response stream by aborting the writable side of the TransformStream.
+    // This errors the readable (transferred to SW), which errors the Response, failing the browser download.
+    state.zipWritable.abort('Download cancelled').catch(() => { });
+    // Stop keepalive pings immediately, but do NOT delete the map entry — the
+    // remaining queued files must still find this (cancelled) batch. The entry is
+    // removed by reset() at the final drain.
+    if (state.keepaliveInterval) {
+        clearInterval(state.keepaliveInterval);
+        state.keepaliveInterval = null;
+    }
+};
+// ─── Utilities ───
+/** Extracts the S3 bucket descriptor from handler config. */
 const constructBucket = ({ bucket: bucketName, region, }) => ({ bucketName, region });
-const readBody = async (response, { data, options }) => {
-    let loading = true;
+/**
+ * Derives the zip filename from the first key's parent folder.
+ *
+ * Examples:
+ * - "photos/vacation/beach.jpg" → "vacation"
+ * - "photos/file.txt" → "photos"
+ * - "file.txt" (no slash) → "archive"
+ * - "/file.txt" (slash at index 0 only) → "archive"
+ *
+ * For root-level multi-file selections (no common parent folder), returns "archive".
+ */
+const getFolderName$1 = (key) => {
+    const lastSlash = key.lastIndexOf('/');
+    if (lastSlash <= 0)
+        return 'archive';
+    const parentPath = key.substring(0, lastSlash);
+    return parentPath.split('/').pop() ?? 'archive';
+};
+/** Collects a ReadableStream into a single Blob (fallback when SW is unavailable). */
+const collectBlob = async (readable) => {
+    const reader = readable.getReader();
     const chunks = [];
-    const reader = response.body.getReader();
-    const size = +(response.headers.get('content-length') ?? 0);
-    let received = 0;
-    while (loading) {
+    for (;;) {
         const { value, done } = await reader.read();
-        if (done) {
-            loading = false;
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return new Blob(chunks, { type: 'application/zip' });
+};
+// ─── Service Worker Initialization ───
+/**
+ * Registers the SW stream transfer (MessageChannel handshake + keepalive)
+ * or falls back to in-memory blob collection when SW is unavailable.
+ * Mutates state.swReady and state.blobPromise.
+ */
+const initServiceWorkerStream = (state) => {
+    if (!navigator.serviceWorker) {
+        state.blobPromise = collectBlob(state.zipReadable);
+        return;
+    }
+    state.swReady = navigator.serviceWorker
+        .getRegistration('/amplify-storage-download/')
+        .then((reg) => {
+        // If the batch was cancelled while getRegistration() was pending, bail out
+        // before wiring up the MessageChannel or keepalive interval. Otherwise the
+        // interval would be created after reset() already cleared batchMap, leaking
+        // a timer with no reference to clear it.
+        if (state.cancelled) {
+            return;
         }
-        else {
-            chunks.push(value);
-            received += value.length;
-            if (ui.isFunction(options?.onProgress)) {
-                options?.onProgress(data, getProgress({
-                    totalBytes: size,
-                    transferredBytes: received,
-                }), 'PENDING');
-            }
+        if (!reg?.active) {
+            state.blobPromise = collectBlob(state.zipReadable);
+            return;
         }
-    }
-    return new Blob(chunks);
+        // Cancel detection works via addPromise.catch: when the user dismisses the
+        // download dialog, the SW response stream closes → TransformStream writable
+        // errors → zipWriter.add() rejects → cancelled flag is set.
+        const { port1, port2 } = new MessageChannel();
+        port1.onmessage = () => {
+            const a = document.createElement('a');
+            a.href = `/amplify-storage-download/${state.downloadId}`;
+            a.download = `${state.folder}.zip`;
+            a.click();
+            port1.close();
+        };
+        // Send the user-facing filename explicitly. `downloadId` embeds Date.now()
+        // to keep the SW's stream-map key unique across batches — that timestamp
+        // must NOT leak into the saved filename. The SW uses `filename` for the
+        // Content-Disposition header so the SW path and the blob-fallback path both
+        // save `${folder}.zip`.
+        reg.active.postMessage({
+            downloadId: state.downloadId,
+            filename: `${state.folder}.zip`,
+            stream: state.zipReadable,
+        }, [state.zipReadable, port2]);
+        state.zipReadable = null;
+        // Keepalive pings run for the entire batch duration to prevent Firefox's
+        // 30s SW idle timeout from terminating the worker mid-stream.
+        state.keepaliveInterval = setInterval(() => {
+            reg.active?.postMessage({ type: 'keepalive' });
+        }, 10000);
+    });
 };
-const download = async ({ config, data, all, options }, abortController) => {
+// ─── Per-file Download ───
+/**
+ * Downloads a single file, streams it into the zip writer entry.
+ * Receives the active batch state explicitly — throws if state is invalid.
+ */
+const download = async (state, { config, data, options }) => {
     const { customEndpoint, credentials, accountId } = config;
     const { key } = data;
+    // Prefer the folder-relative path (set during folder expansion) so nested
+    // files keep their structure inside the zip; fall back to the bare basename
+    // for loose files / legacy inputs that don't carry a relativePath.
+    const filename = data.relativePath ?? key.split('/').pop();
+    await state.swReady;
+    if (state.cancelled) {
+        throw new Error('Download cancelled');
+    }
+    // Note: getUrl is a presigned URL generation call (local, fast) — not cancellable
     const { url } = await internals.getUrl({
         path: key,
         options: {
@@ -584,78 +580,196 @@ const download = async ({ config, data, all, options }, abortController) => {
     });
     const response = await fetch(url, {
         mode: 'cors',
-        signal: abortController.signal,
+        signal: state.batchAbort.signal,
     });
-    const blob = await readBody(response, { data, options });
-    const [filename] = key.split('/').reverse();
-    await zipper.addFile(blob, filename, {
-        data,
-        signal: abortController.signal,
-        onProgress: (progress, _name, _data) => {
-            if (ui.isFunction(options?.onProgress)) {
-                options?.onProgress(_data, progress, progress === 1 ? 'COMPLETE' : 'FINISHING');
-            }
+    if (!response.body)
+        throw new Error(`Empty response body for ${key}`);
+    const size = data.size ?? +(response.headers.get('content-length') ?? 0);
+    let transferred = 0;
+    // Intermediate stream decouples fetch errors from zip.js internals.
+    // Closing this stream cleanly lets zip.js finalize the entry without
+    // uncaught AbortError rejections from its codec-worker.
+    let streamController;
+    const fileStream = new ReadableStream({
+        start(controller) {
+            streamController = controller;
         },
     });
+    // Start the zip add — returns a promise that resolves when the
+    // ReadableStream we gave it closes.
+    const addPromise = state.zipWriter.add(filename, fileStream, { level: 0 });
+    // When the browser dismisses the download dialog, the SW response stream
+    // closes → TransformStream writable errors → zipWriter.add() rejects.
+    // We flag cancellation from two robust signals: an explicit abort in flight
+    // (UI cancel aborts batchAbort) or a standard `AbortError` (the DOM error name
+    // zip.js surfaces when its output stream is terminated by a dialog cancel).
+    // We deliberately avoid substring-matching zip.js's internal error messages,
+    // which are not a public API contract. Any other rejection is a genuine error.
+    addPromise.catch((error) => {
+        const err = error instanceof Error ? error : undefined;
+        if (state.batchAbort.signal.aborted || err?.name === 'AbortError') {
+            state.cancelled = true;
+        }
+        // Re-throw is not needed — the await below will surface the rejection.
+    });
+    try {
+        const reader = response.body.getReader();
+        for (;;) {
+            if (state.cancelled) {
+                streamController.close();
+                throw new Error('Download cancelled');
+            }
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            transferred += value.length;
+            streamController.enqueue(value);
+            if (size > 0 && ui.isFunction(options?.onProgress)) {
+                options.onProgress(data, getProgress({ totalBytes: size, transferredBytes: transferred }), 'PENDING');
+            }
+        }
+        // All chunks read — close the stream so zip.js finalizes the entry
+        streamController.close();
+        await addPromise;
+        if (ui.isFunction(options?.onProgress)) {
+            options.onProgress(data, 1, 'COMPLETE');
+        }
+    }
+    catch (e) {
+        const err = e;
+        try {
+            streamController.close();
+        }
+        catch {
+            /* already closed */
+        }
+        try {
+            await Promise.race([
+                addPromise,
+                new Promise((_, reject) => setTimeout(() => reject(new Error('addPromise timeout')), 1000)),
+            ]);
+        }
+        catch {
+            /* swallow — zip entry incomplete */
+        }
+        throw state.cancelled || err.name === 'AbortError'
+            ? new Error('Download cancelled')
+            : err;
+    }
     return filename;
 };
-const downloadHandler = (() => {
-    const fileDownloadQueue = new Map();
-    const handler = ({ config, data, all, options }) => {
-        const { key } = data;
-        const [, folder] = key.split('/').reverse();
-        fileDownloadQueue.set(key, false);
-        const abortController = new AbortController();
+// ─── Post-file Settlement ───
+/**
+ * Called after each file completes (success or failure).
+ * Increments progress and triggers batch cleanup when all files are settled.
+ *
+ * IMPORTANT: For the final file, this function awaits cleanup completion
+ * (zipWriter.close + blob download) before returning. This ensures the
+ * user receives the download before useProcessTasks marks the task "done"
+ * and the component can unmount.
+ */
+const onFileSettled = async (batchKey, state, taskResult) => {
+    state.batchDone++;
+    if (state.batchDone < state.batchTotal) {
+        return taskResult;
+    }
+    // Final file — run cleanup synchronously in this promise chain so that
+    // the task result is not returned until the download is triggered.
+    try {
+        if (!state.cancelled && state.zipWriter) {
+            await state.zipWriter.close();
+            if (state.blobPromise) {
+                const blob = await state.blobPromise;
+                const a = document.createElement('a');
+                a.href = URL.createObjectURL(blob);
+                a.download = `${state.folder}.zip`;
+                a.click();
+                URL.revokeObjectURL(a.href);
+            }
+        }
+    }
+    catch {
+        // zip close failed — batch was likely cancelled
+    }
+    finally {
+        reset(batchKey, state);
+    }
+    return taskResult;
+};
+// ─── Handler ───
+/** Main entry point — called once per file in a multi-select download batch. */
+const zipDownloadHandler = ({ config, data, all, options, }) => {
+    const { key } = data;
+    const firstKey = all[0]?.key ?? key;
+    // The view computes the batch zip name (last segment of the common ancestor
+    // dir of all files) and stamps it onto every item. Prefer it; fall back to
+    // the legacy first-key parent-folder heuristic when it's absent.
+    const folder = all[0]?.archiveName ?? getFolderName$1(firstKey);
+    const batchKey = getBatchKey(all);
+    const existingBatch = batchMap.get(batchKey);
+    // ─── STEP 1: Handle cancelled state ───
+    if (existingBatch?.cancelled) {
+        existingBatch.batchDone++;
+        const result = Promise.resolve({
+            status: 'CANCELED',
+            message: 'Download cancelled',
+        });
+        if (existingBatch.batchDone >= existingBatch.batchTotal) {
+            result.finally(() => reset(batchKey, existingBatch));
+        }
         return {
+            result,
             cancel: () => {
-                abortController.abort();
-                fileDownloadQueue.set(key, true);
+                /* already cancelled — noop */
             },
-            result: download({ config, data, all, options }, abortController)
-                .then(() => {
-                fileDownloadQueue.set(key, true);
-                return {
-                    status: 'COMPLETE',
-                };
-            })
-                .catch((e) => {
-                const error = e;
-                fileDownloadQueue.set(key, true);
-                return {
-                    status: 'FAILED',
-                    message: error.message,
-                    error,
-                };
-            })
-                .finally(() => {
-                const done = all.every(({ key }) => {
-                    return fileDownloadQueue.get(key);
-                });
-                if (done) {
-                    zipper
-                        .getBlobUrl()
-                        .then((blobURL) => {
-                        if (blobURL) {
-                            zipper.destroy();
-                            const anchor = document.createElement('a');
-                            const clickEvent = new MouseEvent('click');
-                            anchor.href = blobURL;
-                            anchor.download = `${folder || 'archive'}.zip`;
-                            anchor.dispatchEvent(clickEvent);
-                        }
-                    })
-                        .catch(() => {
-                        // this catch happens, when no zip was created.
-                        // it is handled by the UI showing "FAILED" for all files
-                    });
-                }
-            }),
         };
+    }
+    // ─── STEP 2: Initialize zip writer on first file ───
+    let currentBatch;
+    if (!existingBatch) {
+        const { readable, writable } = new TransformStream();
+        currentBatch = {
+            zipWriter: new zip_js.ZipWriter(writable),
+            zipWritable: writable,
+            zipReadable: readable,
+            downloadId: `${folder}-${Date.now()}.zip`,
+            blobPromise: null,
+            swReady: Promise.resolve(),
+            cancelled: false,
+            batchAbort: new AbortController(),
+            batchTotal: all.length,
+            batchDone: 0,
+            keepaliveInterval: null,
+            folder,
+        };
+        batchMap.set(batchKey, currentBatch);
+        initServiceWorkerStream(currentBatch);
+    }
+    else {
+        currentBatch = existingBatch;
+    }
+    // ─── STEP 3: Normal download ───
+    return {
+        cancel: () => {
+            cancelBatch(batchKey);
+        },
+        result: download(currentBatch, { config, data, options })
+            .then(() => ({ status: 'COMPLETE' }))
+            .catch((e) => {
+            const err = e;
+            if (err.message === 'Download cancelled' ||
+                err.name === 'AbortError' ||
+                currentBatch.cancelled) {
+                currentBatch.cancelled = true;
+                return { status: 'CANCELED', message: 'Download cancelled' };
+            }
+            return { status: 'FAILED', message: err.message, error: err };
+        })
+            .then((taskResult) => onFileSettled(batchKey, currentBatch, taskResult)),
     };
-    return handler;
-})();
+};
 
-const composedDownloadHandler = (input) => input.all.length === 1 ? downloadHandler$1(input) : downloadHandler(input);
+const composedDownloadHandler = (input) => input.all.length === 1 ? downloadHandler(input) : zipDownloadHandler(input);
 
 const DEFAULT_PAGE_SIZE$2 = 1000;
 const parseItems = (items, excludedPath) => items
@@ -899,9 +1013,11 @@ const uploadActionConfig = {
 const downloadActionConfig = {
     viewName: 'DownloadView',
     actionListItem: {
+        // Only an empty selection disables Download; folder selections are
+        // expanded into files at the view level.
         disable: (selected) => {
             const hasNoSelection = !selected || selected.length === 0;
-            return hasNoSelection || hasSelectedFolders(selected);
+            return hasNoSelection;
         },
         hide: (permissions) => !permissions.includes('get'),
         icon: 'download',
@@ -929,6 +1045,136 @@ const getActionConfigs = (configs) => {
     return Object.entries({ ...configs.default, ...configs.custom }).reduce((configs, [type, config]) => !isActionConfig(config) ? configs : { ...configs, [type]: config }, {});
 };
 
+const toAccessGrantPermission = (permission) => {
+    let result = '';
+    permission.forEach((access) => {
+        if (['read', 'get', 'list'].includes(access)) {
+            if (!result.includes('READ')) {
+                result = 'READ' + result;
+            }
+        }
+        if (['write', 'delete'].includes(access)) {
+            if (!result.includes('WRITE')) {
+                result += 'WRITE';
+            }
+        }
+    });
+    if (result === '') {
+        throw new Error('Improper Permission: Please provide correct permission.');
+    }
+    return result;
+};
+const parseAmplifyAuthPermission = (permissions) => {
+    const result = [];
+    permissions.forEach((access) => {
+        if (access === 'read') {
+            if (!result.includes('list')) {
+                result.push('list');
+            }
+            if (!result.includes('get')) {
+                result.push('get');
+            }
+        }
+        else if (['delete', 'get', 'list', 'write'].includes(access) &&
+            !result.includes(access)) {
+            result.push(access);
+        }
+    });
+    if (result.length === 0) {
+        throw new Error('Improper Permission: Please provide correct permission.');
+    }
+    return result.sort();
+};
+
+const getPaginatedLocations = ({ items, pageSize, nextToken, }) => {
+    if (pageSize) {
+        if (nextToken) {
+            if (Number(nextToken) > items.length) {
+                return { items: [], nextToken: undefined };
+            }
+            const start = parseInt(nextToken, 10) * -1;
+            const end = start + pageSize < 0 ? start + pageSize : undefined;
+            return {
+                items: items.slice(start, end),
+                nextToken: end ? `${-end}` : undefined,
+            };
+        }
+        return {
+            items: items.slice(0, pageSize),
+            nextToken: items.length > pageSize ? `${items.length - pageSize}` : undefined,
+        };
+    }
+    return { items, nextToken: undefined };
+};
+
+const createAmplifyListLocationsHandler = () => {
+    let cachedItems = [];
+    return async function listLocations(input) {
+        const { options } = input ?? {};
+        const { nextToken, pageSize } = options ?? {};
+        if (cachedItems.length > 0) {
+            return getPaginatedLocations({
+                items: cachedItems,
+                pageSize,
+                nextToken,
+            });
+        }
+        const { locations } = await internals.listPaths();
+        const sanitizedItems = locations.map(({ bucket, permission, prefix, type }) => {
+            return {
+                type,
+                permissions: parseAmplifyAuthPermission(permission),
+                bucket,
+                prefix: prefix.endsWith('*') ? prefix.slice(0, -1) : prefix,
+                id: crypto.randomUUID(),
+            };
+        });
+        // Deduplicate locations with the same bucket and prefix, keeping broader permissions
+        cachedItems = deduplicateLocations(sanitizedItems);
+        return getPaginatedLocations({
+            items: cachedItems,
+            pageSize,
+            nextToken,
+        });
+    };
+};
+
+const MISSING_BUCKET_OR_REGION_ERROR = 'Amplify Storage configuration not found. Did you run `Amplify.configure` from your project root?';
+const MISSING_IDENTITY_ID_ERROR = '`identityId` not found.';
+const MISSING_TEMPORARY_CREDENTIALS_ERROR = 'Temporary Auth `credentials` not found.';
+const isTemporaryCredentials = (value) => !!value?.sessionToken || !!value?.expiration;
+const createAmplifyAuthAdapter = () => {
+    const { bucket, region } = awsAmplify.Amplify.getConfig()?.Storage?.S3 ?? {};
+    if (!bucket || !region) {
+        throw new Error(MISSING_BUCKET_OR_REGION_ERROR);
+    }
+    const listLocations = createAmplifyListLocationsHandler();
+    const getLocationCredentials = async () => {
+        const { credentials, identityId } = await auth.fetchAuthSession();
+        if (!isTemporaryCredentials(credentials)) {
+            throw new Error(MISSING_TEMPORARY_CREDENTIALS_ERROR);
+        }
+        if (!identityId) {
+            throw new Error(MISSING_IDENTITY_ID_ERROR);
+        }
+        return { credentials, identityId };
+    };
+    const registerAuthListener = (onStateChange) => {
+        const remove = utils.Hub.listen('auth', (data) => {
+            if (data.payload.event === 'signedOut') {
+                onStateChange();
+                remove();
+            }
+        });
+    };
+    return {
+        getLocationCredentials,
+        listLocations,
+        registerAuthListener,
+        region,
+    };
+};
+
 function Button(props) {
     const { disabled, variant } = props;
     switch (variant) {
@@ -2285,9 +2531,13 @@ function useHandler(handler, options) {
             ...(hasData
                 ? { data: input.data, all: [input.data] }
                 : // if no `data` provided, provide `concurrency` to `options`
-                    { options: { concurrency: DEFAULT_ACTION_CONCURRENCY } }),
+                    {
+                        options: {
+                            concurrency: options?.concurrency ?? DEFAULT_ACTION_CONCURRENCY,
+                        },
+                    }),
         });
-    }, [getConfig, handleProcessing, reset]);
+    }, [getConfig, handleProcessing, reset, options?.concurrency]);
     if (isOptionsWithItems(options)) {
         return [{ ...rest, isProcessing, reset, tasks }, handleDispatch];
     }
@@ -2879,6 +3129,10 @@ const DEFAULT_DOWNLOAD_VIEW_DISPLAY_TEXT = {
         };
     },
     tableColumnProgressHeader: 'Progress',
+    enumeratingMessage: 'Listing folder contents…',
+    enumerationErrorMessage: 'Failed to list folder contents. Click Download to try again.',
+    noFilesMessage: 'The selected folders contain no files to download.',
+    tooManyFilesMessage: 'The selection exceeds the maximum of 5000 files for a single download. Download folders in smaller batches.',
 };
 
 const DEFAULT_STORAGE_BROWSER_DISPLAY_TEXT = {
@@ -3658,6 +3912,8 @@ const componentsDefault = {
     Title,
 };
 
+const VERSION = '3.18.0';
+
 const Fallback = () => (React__namespace["default"].createElement("div", { className: STORAGE_BROWSER_BLOCK_TO_BE_UPDATED },
     React__namespace["default"].createElement("div", { className: `${STORAGE_BROWSER_BLOCK_TO_BE_UPDATED}__error-boundary` }, "Something went wrong.")));
 class ErrorBoundary extends React__namespace["default"].Component {
@@ -4435,7 +4691,7 @@ const createDeleteConfirmationModalProps = ({ items, showConfirmation, displayTe
  * This prevents expensive operations on very large folders
  */
 const MAX_FILE_COUNT_LIMIT = 5000;
-const LIST_PAGE_SIZE = 1000;
+const LIST_PAGE_SIZE$1 = 1000;
 /**
  * Count the total number of files in a folder with pagination and limits
  * @param folderKey - The folder path to count files in
@@ -4457,7 +4713,7 @@ const countFilesInFolder = async (folderKey, config) => {
                     locationCredentialsProvider: credentials,
                     expectedBucketOwner: accountId,
                     customEndpoint,
-                    pageSize: LIST_PAGE_SIZE,
+                    pageSize: LIST_PAGE_SIZE$1,
                     nextToken,
                 },
             });
@@ -5809,11 +6065,51 @@ DeleteView.Title = TitleControl;
 
 function DownloadViewProvider({ children, ...props }) {
     const { DownloadView: displayText } = useDisplayText();
-    const { actionCancelLabel, actionExitLabel, actionStartLabel, title, statusDisplayCanceledLabel, statusDisplayCompletedLabel, statusDisplayFailedLabel, statusDisplayQueuedLabel, getActionCompleteMessage, } = displayText;
-    const { isProcessing, isProcessingComplete, statusCounts, tasks: items, onActionCancel, onActionStart, onActionExit, onTaskRemove, } = props;
-    const message = isProcessingComplete
-        ? getActionCompleteMessage({ counts: statusCounts })
-        : undefined;
+    const { actionCancelLabel, actionExitLabel, actionStartLabel, title, statusDisplayCanceledLabel, statusDisplayCompletedLabel, statusDisplayFailedLabel, statusDisplayQueuedLabel, getActionCompleteMessage, enumeratingMessage, enumerationErrorMessage, noFilesMessage, tooManyFilesMessage, } = displayText;
+    const { isProcessing, isProcessingComplete, enumerationStatus, hasFilesToDownload, hasSelection, statusCounts, tasks: items, onActionCancel, onActionStart, onTaskRemove, onActionExit, } = props;
+    const isEnumerationPending = enumerationStatus === 'PENDING';
+    const isEnumerationSucceeded = enumerationStatus === 'SUCCEEDED';
+    const isOverFileLimit = enumerationStatus === 'OVER_LIMIT';
+    // Surface the no-files message when the READY set is empty, covering BOTH
+    // empty states with one expression:
+    //   - enumeration succeeded but found only empty folders, and
+    //   - the ready set went empty because the user manually removed every row
+    //     (mirrors the Start-disable gate below).
+    // `'SUCCEEDED'` keeps the pending/error/over-limit statuses owning the
+    // message via the precedence order; the processing guards keep an active or
+    // completed download owning it. `hasSelection` scopes the message to a
+    // selection that is or was non-empty, so a bare mount with an empty
+    // selection (vacuously ready, nothing to download) shows no message.
+    const showNoFiles = hasSelection &&
+        isEnumerationSucceeded &&
+        !hasFilesToDownload &&
+        !isProcessing &&
+        !isProcessingComplete;
+    // Message precedence (most transient/actionable first):
+    //   1. 'PENDING'           -> "listing folder contents" (info)
+    //   2. 'ERROR'             -> failure + retry hint (error)
+    //   3. 'OVER_LIMIT'        -> selection exceeds the file cap (error)
+    //   4. showNoFiles         -> empty folders OR manually-emptied set (info)
+    //   5. isProcessingComplete-> post-download summary (existing)
+    //   6. otherwise           -> no message
+    // Ordering matters: the enumeration statuses are pre-dispatch and mutually
+    // exclusive with a completed download, so an earlier match short-circuits.
+    const message = isEnumerationPending
+        ? { content: enumeratingMessage, type: 'info' }
+        : enumerationStatus === 'ERROR'
+            ? { content: enumerationErrorMessage, type: 'error' }
+            : isOverFileLimit
+                ? { content: tooManyFilesMessage, type: 'error' }
+                : showNoFiles
+                    ? { content: noFilesMessage, type: 'info' }
+                    : isProcessingComplete
+                        ? getActionCompleteMessage({ counts: statusCounts })
+                        : undefined;
+    // `'NOT_STARTED'` and `'ERROR'` are the not-ready/partial statuses. They are
+    // deliberately NOT added to `isActionStartDisabled`: the no-partial-dispatch
+    // invariant is enforced inside the hook's `onActionStart` (guarded dispatch)
+    // so the Start button stays CLICKABLE in those statuses and re-clicking
+    // Start acts as the enumeration RETRY trigger.
     const tableData = useResolveTableData(DOWNLOAD_TABLE_KEYS, DOWNLOAD_TABLE_RESOLVERS, {
         items,
         props: { displayText, isProcessing, onTaskRemove },
@@ -5822,9 +6118,21 @@ function DownloadViewProvider({ children, ...props }) {
             actionCancelLabel,
             actionExitLabel,
             actionStartLabel,
-            isActionCancelDisabled: !isProcessing || isProcessingComplete,
-            isActionExitDisabled: isProcessing,
-            isActionStartDisabled: isProcessing || isProcessingComplete,
+            isActionCancelDisabled: (!isProcessing || isProcessingComplete) && !isEnumerationPending,
+            isActionExitDisabled: isProcessing || isEnumerationPending,
+            isActionStartDisabled: isProcessing ||
+                isProcessingComplete ||
+                isEnumerationPending ||
+                // The selection exceeds the file cap: retrying cannot succeed without
+                // changing the selection, so Start is hard-disabled (unlike the
+                // 'ERROR' status, where Start doubles as the retry trigger).
+                isOverFileLimit ||
+                // Every row was removed (or the ready set is otherwise empty, e.g.
+                // only empty folders were selected): nothing to download. Scoped to
+                // `'SUCCEEDED'` so this NEVER disables Start in the
+                // 'NOT_STARTED'/'ERROR' statuses, where a clickable Start is the
+                // enumeration RETRY trigger (empty resolvedItems is expected there).
+                (isEnumerationSucceeded && !hasFilesToDownload),
             statusDisplayCanceledLabel,
             statusDisplayCompletedLabel,
             statusDisplayFailedLabel,
@@ -5836,24 +6144,530 @@ function DownloadViewProvider({ children, ...props }) {
         }, onActionStart: onActionStart, onActionExit: onActionExit, onActionCancel: onActionCancel }, children));
 }
 
+/**
+ * Page size for the recursive `list()` used to expand a folder into its files.
+ * Mirrors the value used by DeleteView's `countFilesInFolder`.
+ */
+const LIST_PAGE_SIZE = 1000;
+/**
+ * Hard cap on the combined number of files a single download may contain,
+ * counted across every folder (and loose file) in the selection. Folder
+ * expansion stops paginating as soon as the running total would exceed this
+ * value and throws {@link FileLimitError}; the view then surfaces a blocked
+ * state instead of downloading a truncated set (silent truncation would be
+ * data loss). Mirrors the 5000 threshold DeleteView uses for its file count.
+ */
+const LARGE_DOWNLOAD_FILE_COUNT = 5000;
+/**
+ * Thrown by {@link expandFolderToFiles} when the combined expanded file count
+ * of the selection exceeds {@link LARGE_DOWNLOAD_FILE_COUNT}. Callers use it
+ * to distinguish the over-limit state from enumeration failures.
+ */
+class FileLimitError extends Error {
+    constructor() {
+        super(`Download selection exceeds the maximum of ${LARGE_DOWNLOAD_FILE_COUNT} files`);
+        this.name = 'FileLimitError';
+    }
+}
+/**
+ * Computes the base name for a multi-file zip archive from the flat list of
+ * file keys being zipped. Used for file-only, multi-item, and mixed
+ * selections; a selection of exactly one folder is named after that folder
+ * instead (see {@link resolveArchiveName}).
+ *
+ * Rule: the name is the last path segment of the LONGEST COMMON ANCESTOR
+ * DIRECTORY of all files. For each key the directory segments are
+ * `key.split('/')` without the final basename; the longest common prefix of
+ * those segment arrays is taken, and its last element is the name. When the
+ * common prefix is empty (root-level files or files with no shared ancestor)
+ * this falls back to `'download'`.
+ *
+ * Examples:
+ * - ['public/nested/one/pic.jpg', 'public/nested/two/pic.jpg'] -> 'nested'
+ * - ['public/nested/a.jpg', 'public/images/b.jpg', 'public/c.jpg'] -> 'public'
+ * - ['photos/a.jpg', 'photos/b.jpg'] -> 'photos'
+ * - ['a.jpg', 'b.jpg'] -> 'download'
+ * - ['public/x.jpg', 'other/y.jpg'] -> 'download'
+ * - [] -> 'download'
+ *
+ * Pure/synchronous; the base name only — the handler appends `.zip`.
+ */
+const getArchiveName = (fileKeys) => {
+    if (fileKeys.length === 0) {
+        return 'download';
+    }
+    // Directory segments per file = path split without the final basename.
+    const dirSegments = fileKeys.map((key) => key.split('/').slice(0, -1));
+    // Longest common prefix across every file's directory segment array.
+    const [first, ...rest] = dirSegments;
+    let commonLength = first.length;
+    for (const segments of rest) {
+        let i = 0;
+        while (i < commonLength &&
+            i < segments.length &&
+            segments[i] === first[i]) {
+            i += 1;
+        }
+        commonLength = i;
+        if (commonLength === 0) {
+            break;
+        }
+    }
+    // Last segment of the common ancestor dir; empty prefix OR an empty segment
+    // (e.g. a key like 'a//b.jpg') -> 'download'.
+    const name = commonLength === 0 ? '' : first[commonLength - 1];
+    return name === '' ? 'download' : name;
+};
+/**
+ * Resolves the zip archive base name for the current SELECTION.
+ *
+ * When the selection consists of exactly ONE FOLDER (no other items), the
+ * archive is named after that folder (basename of `folder.key`, trailing
+ * slash stripped): the download was initiated from that folder, so selecting
+ * `photos/` yields `photos.zip` even when every file lives in a deeper
+ * subfolder like `photos/vacation/`. Every other selection shape (file-only,
+ * multi-folder, mixed) falls back to the longest-common-ancestor rule of
+ * {@link getArchiveName}.
+ */
+const resolveArchiveName = (dataItems, fileKeys) => {
+    if (dataItems.length === 1 && dataItems[0].type === 'FOLDER') {
+        const basename = dataItems[0].key.replace(/\/$/, '').split('/').pop();
+        if (basename) {
+            return basename;
+        }
+    }
+    return getArchiveName(fileKeys);
+};
+/**
+ * Recursively expands a folder into the flat list of downloadable files it
+ * contains, preserving each file's folder-relative zip path.
+ *
+ * Clones the pagination loop from DeleteView's `countFilesInFolder`, but:
+ * - collects {@link DownloadHandlerData} items instead of counting,
+ * - stops paginating and throws {@link FileLimitError} once the shared
+ *   `fileCounter` would exceed {@link LARGE_DOWNLOAD_FILE_COUNT} (the caller
+ *   surfaces a blocked state; a truncated zip is never produced),
+ * - filters out directory markers (keys ending in `'/'`),
+ * - is cancellable via `signal`, checked between `list()` pages.
+ */
+const expandFolderToFiles = async ({ folderKey, config, locationPrefix, signal, fileCounter = { count: 0 }, }) => {
+    const { accountId, credentials, customEndpoint } = config;
+    const bucket = constructBucket$1(config);
+    const files = [];
+    let nextToken;
+    do {
+        // Abort is checked between pages (and before the first page) so a cancel
+        // during enumeration stops promptly without emitting a partial result.
+        if (signal?.aborted) {
+            throw new DOMException('Folder expansion aborted', 'AbortError');
+        }
+        // Short-circuit between pages when the SHARED counter already exceeds the
+        // cap (e.g. a sibling folder's expansion pushed it over while this one
+        // awaited `list()`): no point paginating a selection that is blocked.
+        if (fileCounter.count > LARGE_DOWNLOAD_FILE_COUNT) {
+            throw new FileLimitError();
+        }
+        const { items, nextToken: listNextToken } = await internals.list({
+            path: folderKey,
+            options: {
+                bucket,
+                locationCredentialsProvider: credentials,
+                expectedBucketOwner: accountId,
+                customEndpoint,
+                pageSize: LIST_PAGE_SIZE,
+                nextToken,
+            },
+        });
+        for (const item of items) {
+            // Skip directory markers (zero-byte keys ending in '/') — only real files
+            // become zip entries.
+            if (item.path.endsWith('/')) {
+                continue;
+            }
+            // Enforce the cap per file so the loop stops as soon as the combined
+            // selection exceeds it, mid-page included.
+            fileCounter.count += 1;
+            if (fileCounter.count > LARGE_DOWNLOAD_FILE_COUNT) {
+                throw new FileLimitError();
+            }
+            const fileData = {
+                key: item.path,
+                id: crypto.randomUUID(),
+                // `list()` may omit size/lastModified; fall back defensively instead
+                // of asserting non-null.
+                size: item.size ?? 0,
+                lastModified: item.lastModified ?? new Date(0),
+                eTag: item.eTag,
+                type: 'FILE',
+            };
+            files.push(createDownloadItem(fileData, locationPrefix));
+        }
+        nextToken = listNextToken;
+    } while (nextToken);
+    return files;
+};
+
 // assign to constant to ensure referential equality
 const EMPTY_ITEMS = [];
+// Referentially-stable empty set used as the "no removals" sentinel so a
+// selection change can filter with an empty set without allocating.
+const EMPTY_SET = new Set();
+/**
+ * Drops rows the user removed via `onTaskRemove`, keyed by the item's stable
+ * id. Needed because folder-EXPANDED file rows carry ids minted during
+ * enumeration that never exist in `dataItems`, so the REMOVE_LOCATION_ITEM
+ * reducer path no-ops for them — this id filter is what actually removes them.
+ */
+const filterRemoved = (items, removedIds) => removedIds.size === 0
+    ? items
+    : items.filter((item) => !removedIds.has(item.id));
+/**
+ * Builds the flat list of download items from the current selection:
+ * loose files become download items directly; folders contribute their
+ * already-expanded files from `cache` (empty until enumeration runs).
+ */
+const buildDownloadItems = (dataItems, prefix, cache) => {
+    const items = [];
+    for (const item of dataItems) {
+        if (item.type === 'FILE') {
+            items.push(createDownloadItem(item, prefix));
+        }
+        else {
+            const expanded = cache.get(item.id);
+            if (expanded) {
+                items.push(...expanded);
+            }
+        }
+    }
+    return items;
+};
+/**
+ * Resolves the EFFECTIVE download set for the current selection: builds the
+ * flat item list, drops user-removed rows, then names the zip archive from
+ * the POST-removal set.
+ *
+ * The archive name is computed here, in the view — NOT in the handler — and
+ * stamped uniformly onto every item so the zip handler can read it from
+ * `all[0].archiveName`. It MUST be computed after `filterRemoved` so the name
+ * reflects the files actually being downloaded (removing rows can shift the
+ * common ancestor). A single-folder SELECTION is still named after that
+ * folder — the selection (`dataItems`) is unaffected by per-row removal, only
+ * the LCA input (file keys) is post-filter; every other shape uses the common
+ * ancestor directory of the remaining files (see resolveArchiveName).
+ */
+const resolveDownloadItems = ({ dataItems, prefix, cache, removedIds, }) => {
+    const items = filterRemoved(buildDownloadItems(dataItems, prefix, cache), removedIds);
+    const archiveName = resolveArchiveName(dataItems, items.map((i) => i.key));
+    return items.map((i) => ({ ...i, archiveName }));
+};
 const useDownloadView = (options) => {
     const { onExit: _onExit } = options ?? {};
     const [{ location }, storeDispatch] = useStore();
     const [locationItems, locationItemsDispatch] = useLocationItems();
     const { current } = location;
-    const { fileDataItems: items = EMPTY_ITEMS } = locationItems;
+    const { dataItems = EMPTY_ITEMS } = locationItems;
+    const getConfig = useGetActionInput();
+    // Cache of folder id -> expanded download items, mirroring DeleteView's
+    // `folderCountsRef`. Survives re-renders so re-expanding is avoided.
+    // Intentional per-session cache: entries are keyed by the (stable, per-mount)
+    // folder id and are never individually invalidated — the whole ref is
+    // discarded when the view unmounts on exit (RESET_LOCATION_ITEMS), which is
+    // the only path that changes the underlying location. This matches
+    // DeleteView's `folderCountsRef` semantics.
+    const folderExpansionRef = React__namespace["default"].useRef(new Map());
+    // AbortController for the in-flight enumeration (cancellable pre-dispatch).
+    const enumAbortRef = React__namespace["default"].useRef(null);
+    // Tracks the last selection (id SET of dataItems + current) the sync effect
+    // ran for, so it can tell a GENUINE selection change (which resets stale
+    // flags and the per-row removal set) apart from a within-selection row
+    // removal or a re-run triggered solely by a `removedItemIds` update (which
+    // must NOT reset the removals it just applied). The id SET — not the array
+    // reference — is stored because the reducer rebuilds the `dataItems` array
+    // on a LOOSE-row removal (same selection minus a row), so identity alone
+    // can't distinguish removal from re-selection (see the subset check in the
+    // sync effect below).
+    const prevSelectionRef = React__namespace["default"].useRef({ dataItemIds: new Set(dataItems.map((item) => item.id)), current });
+    const [resolvedItems, setResolvedItems] = React__namespace["default"].useState([]);
+    // `true` while folder selections are being expanded into their files. Drives
+    // the `'PENDING'` enumeration status, which disables Start until enumeration
+    // settles.
+    const [isEnumerating, setIsEnumerating] = React__namespace["default"].useState(false);
+    // `true` when the pre-dispatch enumeration failed for a non-abort reason.
+    // Surfaced on the view model so the Start control re-enabling isn't the only
+    // (silent) feedback the user gets on failure.
+    const [isEnumerationError, setIsEnumerationError] = React__namespace["default"].useState(false);
+    // `true` when the combined expanded file count of the selection exceeded
+    // LARGE_DOWNLOAD_FILE_COUNT during enumeration. A truncated zip would be
+    // silent data loss, so this state BLOCKS dispatch entirely (same invariant
+    // as `allFoldersReady`) and the view surfaces an explanatory message.
+    const [isOverFileLimit, setIsOverFileLimit] = React__namespace["default"].useState(false);
+    // Retry counter; bumping re-runs the enumeration effect for still-uncached
+    // folders.
+    const [enumAttempt, setEnumAttempt] = React__namespace["default"].useState(0);
+    // Stable ids of rows the user removed via `onTaskRemove`. Folder-EXPANDED
+    // file rows can't be removed through the locationItems reducer (their ids
+    // aren't in `dataItems`, so REMOVE_LOCATION_ITEM no-ops), so we track removals
+    // here and filter `resolvedItems` by them. Reset on a GENUINE selection change
+    // (a new id or location change — NOT a within-selection row removal) so
+    // removals don't leak into a new selection (see the sync effect below).
+    const [removedItemIds, setRemovedItemIds] = React__namespace["default"].useState(() => new Set());
+    // Latest-value mirror of `removedItemIds` so the async enumeration closure can
+    // read the current removals WITHOUT `removedItemIds` becoming an enumeration
+    // dep (which would abort/re-run enumeration on every row removal). Mirrors the
+    // `callbacksRef` pattern in useProcessTasks.
+    const removedItemIdsRef = React__namespace["default"].useRef(removedItemIds);
+    removedItemIdsRef.current = removedItemIds;
+    const hasFolders = hasSelectedFolders(dataItems);
+    // `true` once the selection has been non-empty at any point in this mount.
+    // Sticky on purpose: removing every row empties `dataItems` for a loose-file
+    // selection, and the "no files" message must still show in that manually
+    // -emptied state, while a bare mount with no selection must NOT show it.
+    const hadSelectionRef = React__namespace["default"].useRef(false);
+    if (dataItems.length > 0) {
+        hadSelectionRef.current = true;
+    }
+    const hasSelection = hadSelectionRef.current;
+    // `resolvedItems` (not the raw selection) is what `useAction` turns into
+    // tasks. Keep it in sync with the selection + expansion cache so item
+    // removal (onTaskRemove) stays consistent. For a file-only selection this
+    // fully populates `resolvedItems` on mount (no enumeration needed); for
+    // folders it seeds any already-expanded (cached) files and the enumeration
+    // effect below fills in the rest.
+    React__namespace["default"].useEffect(() => {
+        const prefix = current?.prefix ?? '';
+        // Distinguish a GENUINE selection change (new/changed selection or
+        // location change) from a within-selection row removal or a re-run
+        // triggered solely by a `removedItemIds` update. Only a real selection
+        // change should clear stale pre-dispatch flags and the per-row removal
+        // set — resetting on anything else would resurrect rows the user just
+        // removed. `dataItems` identity is NOT a reliable signal: removing a
+        // LOOSE row rebuilds the array (same selection minus a row), and the
+        // `SET_LOCATION_ITEMS` reducer `.concat`s a NEW reference even when
+        // re-selecting the SAME items. Compare by id set instead: when the new id
+        // set is a SUBSET of the previous one (no NEW id), rows were only removed
+        // (or nothing changed), so removals — which for folder-EXPANDED rows live
+        // ONLY in `removedItemIds` (the reducer no-ops for their ids) — must
+        // carry over. Only a NEW id (or a `current` change) marks a genuine
+        // selection change. Consequence vs. the previous identity compare:
+        // re-selecting the identical id set no longer resets removals, so
+        // previously-removed rows STAY removed instead of re-appearing.
+        const prev = prevSelectionRef.current;
+        const dataItemIds = new Set();
+        let hasNewId = false;
+        for (const item of dataItems) {
+            dataItemIds.add(item.id);
+            if (!prev.dataItemIds.has(item.id)) {
+                hasNewId = true;
+            }
+        }
+        const selectionChanged = prev.current !== current || hasNewId;
+        prevSelectionRef.current = { dataItemIds, current };
+        // On a genuine selection change no prior removals carry over; otherwise
+        // apply the current removal set. (Removing a LOOSE file also mutates
+        // dataItems, but its id set stays a subset of the previous one, so it
+        // correctly does NOT read as a selection change: the reducer prunes the
+        // loose row from dataItems while `removedItemIds` keeps previously-removed
+        // folder-EXPANDED rows hidden — those no-op in the reducer, so dataItems is
+        // unchanged for them and this filter is what removes them.)
+        const effectiveRemovedIds = selectionChanged ? EMPTY_SET : removedItemIds;
+        setResolvedItems(resolveDownloadItems({
+            dataItems,
+            prefix,
+            cache: folderExpansionRef.current,
+            removedIds: effectiveRemovedIds,
+        }));
+        if (selectionChanged) {
+            // Selection changed: clear stale pre-dispatch flags so a prior error
+            // /over-limit result doesn't leak into the new selection.
+            setIsEnumerationError(false);
+            setIsOverFileLimit(false);
+            // Clear per-row removals so a prior selection's removals don't hide items
+            // in the new selection (no-op when already empty to avoid a needless
+            // re-render/effect loop).
+            setRemovedItemIds((prev) => (prev.size === 0 ? prev : new Set()));
+        }
+    }, [dataItems, current, removedItemIds]);
+    // Auto-run folder enumeration on mount and whenever the selection changes.
+    //
+    // WHY ON MOUNT (not gated behind Start): the view renders its rows from
+    // `resolvedItems` -> useAction `tasks`. A FOLDER contributes files only from
+    // the expansion cache, which is empty on mount, so a folder selection would
+    // otherwise render zero rows (and log nothing) until Start was clicked.
+    // Expanding eagerly here — mirroring DeleteView's `initializeFolderCounts`
+    // mount effect — resolves the files so the rows render as soon as the view
+    // opens.
+    //
+    // WHY DISPATCH IS DECOUPLED FROM ENUMERATION: this effect only populates
+    // `resolvedItems`; it MUST NOT auto-start the download. The zip is triggered
+    // solely by the user clicking Start (`onActionStart` -> `handleProcess`). By
+    // the time Start is enabled, `resolvedItems` has already synced into
+    // useAction's `tasksRef`, so the previous "set state + dispatch in one tick"
+    // sequencing hack is no longer required.
+    React__namespace["default"].useEffect(() => {
+        if (!hasFolders || !current) {
+            // A prior in-flight enumeration may have been aborted by this effect's
+            // cleanup (selection change); its catch is now a no-op, so clear the flag
+            // defensively here to ensure `isEnumerating` can't stick true (which would
+            // also trap Exit). React bails on same-value setState, so this is a no-op
+            // in the normal file-only / already-idle paths and can't loop.
+            setIsEnumerating(false);
+            return;
+        }
+        // Only expand folders we haven't already cached (cache is keyed by the
+        // stable folder id). If every selected folder is already cached, the sync
+        // effect above has rebuilt `resolvedItems` from the cache and there's
+        // nothing to enumerate — avoids a spurious enumerating flash and re-runs.
+        const foldersToExpand = dataItems.filter((item) => item.type === 'FOLDER' && !folderExpansionRef.current.has(item.id));
+        if (foldersToExpand.length === 0) {
+            // Same defensive clear as above: an aborted prior run can't reset the flag.
+            setIsEnumerating(false);
+            return;
+        }
+        const config = getConfig(current);
+        const { prefix } = current;
+        const controller = new AbortController();
+        enumAbortRef.current = controller;
+        setIsEnumerationError(false);
+        setIsOverFileLimit(false);
+        setIsEnumerating(true);
+        // Shared running file total for the LARGE_DOWNLOAD_FILE_COUNT cap. Seeded
+        // with the files already in the selection (loose files plus previously
+        // cached folder expansions) so the cap applies to the COMBINED selection,
+        // then passed to every expansion in this run.
+        const fileCounter = {
+            count: dataItems.reduce((count, item) => {
+                if (item.type === 'FILE')
+                    return count + 1;
+                return count + (folderExpansionRef.current.get(item.id)?.length ?? 0);
+            }, 0),
+        };
+        const runEnumeration = async () => {
+            try {
+                await Promise.all(foldersToExpand.map(async (folder) => {
+                    const expanded = await expandFolderToFiles({
+                        folderKey: folder.key,
+                        config,
+                        locationPrefix: prefix,
+                        signal: controller.signal,
+                        fileCounter,
+                    });
+                    folderExpansionRef.current.set(folder.id, expanded);
+                }));
+                // Cancelled mid-flight — `onActionCancel` (or this effect's cleanup on
+                // selection change / unmount) already aborted. Leave state alone to
+                // avoid a setState race with the newer run.
+                if (controller.signal.aborted)
+                    return;
+                const resolved = resolveDownloadItems({
+                    dataItems,
+                    prefix,
+                    cache: folderExpansionRef.current,
+                    // Apply any per-row removals the user made before enumeration
+                    // settled (the sync effect re-filters on later removals via its
+                    // removedItemIds dep, but ref-population here doesn't trigger it, so
+                    // filter now too). Read through the ref for the latest value.
+                    removedIds: removedItemIdsRef.current,
+                });
+                // NOTE: `resolved` may be empty (only empty folders selected). The
+                // empty folders were still cached above, so the derived enumeration
+                // status flips to `'SUCCEEDED'` with `hasFilesToDownload` false — the
+                // view surfaces the "no files" message from that combination. No zip
+                // is started in this case (Start is disabled on an empty ready set).
+                setResolvedItems(resolved);
+                setIsEnumerating(false);
+            }
+            catch (error) {
+                // Abort surfaces here too; distinguish it from real failures.
+                if (controller.signal.aborted) ;
+                else if (error instanceof FileLimitError) {
+                    // The combined selection exceeds LARGE_DOWNLOAD_FILE_COUNT. Abort the
+                    // sibling expansions still paginating (their result can never be
+                    // dispatched) and surface the blocked state. The over-limit folder was
+                    // never cached, so `allFoldersReady` stays false and dispatch is
+                    // structurally blocked as well.
+                    controller.abort();
+                    setIsOverFileLimit(true);
+                    setIsEnumerating(false);
+                }
+                else {
+                    // No dedicated package logger exists here; `console.error` matches the
+                    // convention used elsewhere in StorageBrowser (e.g. validateStoreProps,
+                    // useAction). AbortError is expected on cancel and handled above, so
+                    // only genuine failures reach this branch.
+                    // eslint-disable-next-line no-console
+                    console.error('Failed to expand folders for download:', error);
+                    setIsEnumerationError(true);
+                    setIsEnumerating(false);
+                }
+            }
+        };
+        runEnumeration();
+        // Abort the in-flight enumeration when the selection changes or the view
+        // unmounts, so its `list()` loop stops and no setState-after-unmount occurs.
+        return () => {
+            controller.abort();
+        };
+    }, [dataItems, current, hasFolders, getConfig, enumAttempt]);
+    // Readiness gate: Start may only dispatch once EVERY selected folder has been
+    // expanded into the cache. Files are always ready; a FOLDER is ready only when
+    // folderExpansionRef has cached its expanded items. Recomputed each render —
+    // state changes from enumeration (setResolvedItems/setIsEnumerating) trigger the
+    // re-render that flips this true after the ref is populated.
+    const allFoldersReady = dataItems.every((item) => item.type !== 'FOLDER' || folderExpansionRef.current.has(item.id));
+    // Public enumeration status, DERIVED from the internal flags each render
+    // (never stored — `allFoldersReady` is itself derived from dataItems + the
+    // expansion cache, so storing the union would create a second source of
+    // truth). Precedence: an in-flight run owns the status; then the terminal
+    // error/limit outcomes; then readiness. A file-only selection has no folders
+    // to expand, so it is vacuously ready -> `'SUCCEEDED'` immediately on mount.
+    const enumerationStatus = isEnumerating
+        ? 'PENDING'
+        : isEnumerationError
+            ? 'ERROR'
+            : isOverFileLimit
+                ? 'OVER_LIMIT'
+                : allFoldersReady
+                    ? 'SUCCEEDED'
+                    : 'NOT_STARTED';
     const [processState, handleProcess] = useAction('download', {
-        items,
+        items: resolvedItems,
+        concurrency: 1,
     });
     const { isProcessing, isProcessingComplete, statusCounts, tasks } = processState;
     const onActionStart = () => {
         if (!current)
             return;
+        // Enumeration in flight (Start is disabled anyway) — do nothing.
+        if (isEnumerating)
+            return;
+        // Selection exceeds the file cap: dispatching would produce a truncated
+        // zip (silent data loss) and retrying cannot succeed without changing the
+        // selection, so do nothing (Start is disabled in this state anyway).
+        if (isOverFileLimit)
+            return;
+        // RETRY PATH: a prior enumeration was cancelled or failed, so some selected
+        // folders are still uncached. NEVER dispatch an incomplete set (CORE
+        // INVARIANT). Instead re-trigger enumeration for the uncached folders by
+        // bumping enumAttempt; the user retries simply by clicking Start again.
+        // Dispatch happens on a later click, once allFoldersReady is true.
+        if (!allFoldersReady) {
+            setIsEnumerationError(false);
+            setEnumAttempt((n) => n + 1);
+            return;
+        }
+        // Every selected folder is expanded and resolvedItems is synced into
+        // useAction's tasksRef — safe to dispatch the complete set. Download starts
+        // ONLY here (never auto-started on enumeration completion).
         handleProcess();
     };
     const onActionCancel = () => {
+        // Cancel during the (mount) pre-dispatch enumeration phase: abort the
+        // `list()` loop and return to idle without starting a zip.
+        if (isEnumerating) {
+            enumAbortRef.current?.abort();
+            setIsEnumerating(false);
+            return;
+        }
         tasks.forEach((task) => {
             // Calling cancel on task works only on queued tasks.
             // In case of download, all download presigned url open at once
@@ -5871,11 +6685,33 @@ const useDownloadView = (options) => {
             _onExit(current);
     };
     const onTaskRemove = React__namespace["default"].useCallback(({ data }) => {
+        // Track the removal by the item's STABLE id. Folder-EXPANDED file rows
+        // have ids minted in `expandFolderToFiles` (cached in folderExpansionRef)
+        // that never live in `dataItems`, so REMOVE_LOCATION_ITEM alone no-ops for
+        // them — filtering `resolvedItems` by `removedItemIds` is what removes
+        // those rows. For LOOSE selection items the dispatch still prunes the
+        // selection state (and is a harmless no-op for expanded ids).
+        setRemovedItemIds((prev) => {
+            if (prev.has(data.id))
+                return prev;
+            const next = new Set(prev);
+            next.add(data.id);
+            return next;
+        });
         locationItemsDispatch({ type: 'REMOVE_LOCATION_ITEM', id: data.id });
     }, [locationItemsDispatch]);
+    // Effective (post-removal) download set is empty -> nothing to download. Used
+    // (with a `'SUCCEEDED'` status) to gate Start in a ready/idle state and to
+    // surface the "no files" message — covering both empty folders detected
+    // during enumeration and a manually-emptied row set (see
+    // DownloadViewProvider).
+    const hasFilesToDownload = resolvedItems.length > 0;
     return {
         isProcessing,
         isProcessingComplete,
+        enumerationStatus,
+        hasFilesToDownload,
+        hasSelection,
         location,
         statusCounts,
         tasks,
@@ -7090,6 +7926,28 @@ function createProvider({ actions, components, config, options, filePreview = {}
     return Provider;
 }
 
+const SW_DOWNLOAD_SCOPE = '/amplify-storage-download/';
+const SW_URL = '/amplify-storage-download/download-sw.js';
+function useServiceWorkerRegistration() {
+    React.useEffect(() => {
+        if ('serviceWorker' in navigator) {
+            navigator.serviceWorker
+                .register(SW_URL, { scope: SW_DOWNLOAD_SCOPE })
+                .catch((err) => {
+                // Registration failure is non-critical; the blob fallback handles
+                // downloads. We still surface it: a failed registration is a real
+                // (silent otherwise) degradation, and the most common cause is
+                // forgetting the copy-serviceworker setup step so the SW file isn't
+                // served from the app's public directory.
+                // eslint-disable-next-line no-console
+                console.warn('[StorageBrowser] Download service worker registration failed; ' +
+                    'falling back to in-memory blob downloads. Ensure the service ' +
+                    'worker file is served (see the copy-serviceworker setup step):', err);
+            });
+        }
+    }, []);
+}
+
 /**
  * Handles default `StorageBrowser` behavior:
  * - render `LocationsView` on init
@@ -7097,6 +7955,7 @@ function createProvider({ actions, components, config, options, filePreview = {}
  * - render `ActionView` on action selection
  */
 function StorageBrowserDefault() {
+    useServiceWorkerRegistration();
     const { primary } = useViews();
     const { LocationActionView, LocationDetailView, LocationsView } = primary;
     const [{ actionType, location }] = useStore();