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

package/dist/esm/components/StorageBrowser/createStorageBrowser/createStorageBrowser.mjs

@@ -27,11 +27,11 @@ import 'aws-amplify';
 import '@zip.js/zip.js';
 import 'aws-amplify/storage';
 import { DownloadView } from '../views/LocationActionView/DownloadView/DownloadView.mjs';
+import '../actions/configs/context.mjs';
 import { LocationActionView } from '../views/LocationActionView/LocationActionView.mjs';
 import { UploadView } from '../views/LocationActionView/UploadView/UploadView.mjs';
 import '../fileItems/context.mjs';
 import { LocationDetailView } from '../views/LocationDetailView/LocationDetailView.mjs';
-import '../actions/configs/context.mjs';
 import '../filePreview/context.mjs';
 import { LocationsView } from '../views/LocationsView/LocationsView.mjs';
 import { useView } from '../views/useView.mjs';

package/dist/esm/components/StorageBrowser/displayText/libraries/en/downloadView.mjs

@@ -21,6 +21,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.',
 };
 
 export { DEFAULT_DOWNLOAD_VIEW_DISPLAY_TEXT };

package/dist/esm/components/StorageBrowser/service-worker/useServiceWorkerRegistration.mjs

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+
+const SW_DOWNLOAD_SCOPE = '/amplify-storage-download/';
+const SW_URL = '/amplify-storage-download/download-sw.js';
+function useServiceWorkerRegistration() {
+    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);
+            });
+        }
+    }, []);
+}
+
+export { SW_DOWNLOAD_SCOPE, useServiceWorkerRegistration };

package/dist/esm/components/StorageBrowser/useAction/useHandler.mjs

@@ -24,9 +24,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];
     }

package/dist/esm/components/StorageBrowser/views/LocationActionView/DownloadView/DownloadViewProvider.mjs

@@ -16,11 +16,51 @@ import { DOWNLOAD_TABLE_RESOLVERS, DOWNLOAD_TABLE_KEYS } from '../../utils/table
 
 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 },
@@ -29,9 +69,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,

package/dist/esm/components/StorageBrowser/views/LocationActionView/DownloadView/useDownloadView.mjs

@@ -1,35 +1,384 @@
 import React__default from 'react';
 import { isFunction } from '@aws-amplify/ui';
+import '@aws-amplify/storage/internals';
+import { createDownloadItem } from '../../../actions/handlers/utils.mjs';
+import '@zip.js/zip.js';
+import 'aws-amplify/storage';
+import '../../../actions/configs/context.mjs';
+import '../../../actions/configs/defaults.mjs';
 import { useLocationItems } from '../../../locationItems/context.mjs';
+import { hasSelectedFolders } from '../../../locationItems/utils.mjs';
 import { useStore } from '../../../store/context.mjs';
 import '../../../useAction/context.mjs';
 import { useAction } from '../../../useAction/useAction.mjs';
 import '@aws-amplify/ui-react-core';
 import '@aws-amplify/ui-react-core/elements';
 import '../../../credentials/context.mjs';
-import '@aws-amplify/storage/internals';
-import '../../../configuration/context.mjs';
+import { useGetActionInput } from '../../../configuration/context.mjs';
 import '../../../configuration/paginationContext.mjs';
-import '../../../actions/configs/defaults.mjs';
+import { resolveArchiveName, expandFolderToFiles, FileLimitError } from './utils.mjs';
 
 // 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__default.useRef(new Map());
+    // AbortController for the in-flight enumeration (cancellable pre-dispatch).
+    const enumAbortRef = React__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__default.useRef({ dataItemIds: new Set(dataItems.map((item) => item.id)), current });
+    const [resolvedItems, setResolvedItems] = React__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__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__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__default.useState(false);
+    // Retry counter; bumping re-runs the enumeration effect for still-uncached
+    // folders.
+    const [enumAttempt, setEnumAttempt] = React__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__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__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__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__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__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
@@ -47,11 +396,33 @@ const useDownloadView = (options) => {
             _onExit(current);
     };
     const onTaskRemove = React__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,