Upload Media: Add retry with exponential backoff and network resilience

packages/editor/CHANGELOG.md

@@ -7,6 +7,7 @@
 ### Enhancements
 
 -   Editor: Add padding around inline notices in the editor content area and distraction-free header.
+-   Editor: Pause the client-side media upload queue while the browser is offline and resume it automatically when connectivity returns ([#76765](https://github.com/WordPress/gutenberg/pull/76765)).
 -   The Media Editor modal is now mounted unconditionally and the `openMediaEditorModal` setting is always provided to the block editor. Previously both were gated behind the `gutenberg-media-editor-modal` experiment, which has been removed.
 
 ### Bug Fixes

packages/editor/src/components/provider/index.js

@@ -36,6 +36,7 @@ import { useHideBlocksFromInserter } from './use-hide-blocks-from-inserter';
 import { useRevisionBlocks } from './use-revision-blocks';
 import useCommands from '../commands';
 import useUploadSaveLock from './use-upload-save-lock';
+import useNetworkReconnect from './use-network-reconnect';
 import BlockRemovalWarnings from '../block-removal-warnings';
 import StartPageOptions from '../start-page-options';
 import KeyboardShortcutHelpModal from '../keyboard-shortcut-help-modal';
@@ -403,6 +404,9 @@ export const ExperimentalEditorProvider = withRegistryProvider(
 		// Lock post saving when media uploads are in progress (experimental feature).
 		useUploadSaveLock();
 
+		// Pause/resume media upload queue on network disconnect/reconnect.
+		useNetworkReconnect();
+
 		if ( ! isReady || ! mode ) {
 			return null;
 		}

packages/editor/src/components/provider/test/use-network-reconnect.js

@@ -0,0 +1,137 @@
+/**
+ * External dependencies
+ */
+import { renderHook } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useRegistry } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import useNetworkReconnect from '../use-network-reconnect';
+
+const mockPauseQueue = jest.fn();
+const mockResumeQueue = jest.fn();
+
+jest.mock( '@wordpress/data', () => ( {
+	useRegistry: jest.fn(),
+} ) );
+
+jest.mock( '@wordpress/upload-media', () => ( {
+	store: 'core/upload-media',
+} ) );
+
+jest.mock( '../../../lock-unlock', () => ( {
+	unlock: jest.fn( () => ( {
+		pauseQueue: mockPauseQueue,
+		resumeQueue: mockResumeQueue,
+	} ) ),
+} ) );
+
+describe( 'useNetworkReconnect', () => {
+	const originalAddEventListener = window.addEventListener;
+	const originalRemoveEventListener = window.removeEventListener;
+	let listeners;
+
+	beforeEach( () => {
+		mockPauseQueue.mockClear();
+		mockResumeQueue.mockClear();
+		listeners = {};
+		window.addEventListener = jest.fn( ( event, cb ) => {
+			listeners[ event ] = cb;
+		} );
+		window.removeEventListener = jest.fn( ( event ) => {
+			delete listeners[ event ];
+		} );
+		useRegistry.mockReturnValue( {
+			dispatch: jest.fn( () => ( {} ) ),
+		} );
+	} );
+
+	afterEach( () => {
+		window.addEventListener = originalAddEventListener;
+		window.removeEventListener = originalRemoveEventListener;
+		delete window.__clientSideMediaProcessing;
+	} );
+
+	it( 'does nothing when client-side media processing is disabled', () => {
+		window.__clientSideMediaProcessing = false;
+		renderHook( () => useNetworkReconnect() );
+
+		expect( window.addEventListener ).not.toHaveBeenCalled();
+	} );
+
+	it( 'does nothing when the flag is undefined', () => {
+		renderHook( () => useNetworkReconnect() );
+
+		expect( window.addEventListener ).not.toHaveBeenCalled();
+	} );
+
+	it( 'registers offline and online listeners when enabled', () => {
+		window.__clientSideMediaProcessing = true;
+		renderHook( () => useNetworkReconnect() );
+
+		expect( window.addEventListener ).toHaveBeenCalledWith(
+			'offline',
+			expect.any( Function )
+		);
+		expect( window.addEventListener ).toHaveBeenCalledWith(
+			'online',
+			expect.any( Function )
+		);
+	} );
+
+	it( 'pauses the queue when the offline event fires', () => {
+		window.__clientSideMediaProcessing = true;
+		renderHook( () => useNetworkReconnect() );
+
+		listeners.offline();
+
+		expect( mockPauseQueue ).toHaveBeenCalledTimes( 1 );
+		expect( mockResumeQueue ).not.toHaveBeenCalled();
+	} );
+
+	it( 'resumes the queue when the online event fires', () => {
+		window.__clientSideMediaProcessing = true;
+		renderHook( () => useNetworkReconnect() );
+
+		listeners.online();
+
+		expect( mockResumeQueue ).toHaveBeenCalledTimes( 1 );
+		expect( mockPauseQueue ).not.toHaveBeenCalled();
+	} );
+
+	it( 'handles multiple offline/online cycles', () => {
+		window.__clientSideMediaProcessing = true;
+		renderHook( () => useNetworkReconnect() );
+
+		listeners.offline();
+		listeners.online();
+		listeners.offline();
+		listeners.online();
+
+		expect( mockPauseQueue ).toHaveBeenCalledTimes( 2 );
+		expect( mockResumeQueue ).toHaveBeenCalledTimes( 2 );
+	} );
+
+	it( 'removes the listeners on unmount', () => {
+		window.__clientSideMediaProcessing = true;
+		const { unmount } = renderHook( () => useNetworkReconnect() );
+
+		unmount();
+
+		expect( window.removeEventListener ).toHaveBeenCalledWith(
+			'offline',
+			expect.any( Function )
+		);
+		expect( window.removeEventListener ).toHaveBeenCalledWith(
+			'online',
+			expect.any( Function )
+		);
+		expect( listeners.offline ).toBeUndefined();
+		expect( listeners.online ).toBeUndefined();
+	} );
+} );

packages/editor/src/components/provider/use-network-reconnect.js

@@ -0,0 +1,44 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect } from '@wordpress/element';
+import { useRegistry } from '@wordpress/data';
+import { store as uploadStore } from '@wordpress/upload-media';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+/**
+ * A hook that pauses the media upload queue when the browser goes offline
+ * and resumes it when connectivity is restored.
+ *
+ * Only active when client-side media processing is enabled.
+ */
+export default function useNetworkReconnect() {
+	const isEnabled = window.__clientSideMediaProcessing;
+	const registry = useRegistry();
+
+	useEffect( () => {
+		if ( ! isEnabled ) {
+			return;
+		}
+
+		const handleOffline = () => {
+			unlock( registry.dispatch( uploadStore ) ).pauseQueue();
+		};
+
+		const handleOnline = () => {
+			unlock( registry.dispatch( uploadStore ) ).resumeQueue();
+		};
+
+		window.addEventListener( 'offline', handleOffline );
+		window.addEventListener( 'online', handleOnline );
+
+		return () => {
+			window.removeEventListener( 'offline', handleOffline );
+			window.removeEventListener( 'online', handleOnline );
+		};
+	}, [ isEnabled, registry ] );
+}

packages/upload-media/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancement
+
+- Automatically retry failed uploads with exponential backoff for transient (network/server) errors. Retry behavior is configurable via the `retry` store setting; non-transient failures and child sideloads are not retried. The upload queue can also be paused and resumed, allowing uploads to halt while the browser is offline and continue on reconnect ([#76765](https://github.com/WordPress/gutenberg/pull/76765)).
+
 ## 0.32.0 (2026-05-27)
 
 ### Bug Fix

packages/upload-media/README.md

@@ -61,12 +61,24 @@ _Parameters_
 
 Cancels an item in the queue based on an error.
 
+If the error is retryable and the item hasn't exceeded the maximum retry attempts, it will be scheduled for automatic retry instead of being cancelled.
+
 _Parameters_
 
 -   _id_ `QueueItemId`: Item ID.
 -   _error_ `Error`: Error instance.
 -   _silent_ Whether to cancel the item silently, without invoking its `onError` callback.
 
+#### executeRetry
+
+Executes a scheduled retry for an item.
+
+This is called by the timer set in scheduleRetry. It verifies the item is still in PendingRetry status before proceeding with the retry.
+
+_Parameters_
+
+-   _id_ `QueueItemId`: Item ID.
+
 #### retryItem
 
 Retries a failed item in the queue.
@@ -75,6 +87,17 @@ _Parameters_
 
 -   _id_ `QueueItemId`: Item ID.
 
+#### scheduleRetry
+
+Schedules an automatic retry for a failed item.
+
+Uses exponential backoff with jitter to determine the retry delay. The item will be placed in PendingRetry status and automatically retried after the calculated delay.
+
+_Parameters_
+
+-   _id_ `QueueItemId`: Item ID.
+-   _error_ `Error`: The error that caused the failure.
+
 <!-- END TOKEN(Autogenerated actions|src/store/actions.ts) -->
 
 ### Selectors