Enable client-side media uploads in the Media Library

[adamsilverstein]

Trac ticket: https://core.trac.wordpress.org/ticket/65661

Description

Client-side media processing currently only works in the block editor - uploads from the Media Library grid and the Add New Media File screen still send the original file to async-upload.php and generate every sub-size on the server. This PR routes uploads on both screens through the same client-side pipeline the editor uses, so the browser resizes the image and generates the thumbnails.

Why this matters: server-side image processing is a common source of timeouts and memory errors on large images, and results vary depending on what image libraries the host has installed. Processing in the browser avoids both problems, and users get the same upload experience everywhere media is uploaded, not just in the editor.

How it works:

Both screens send the Document-Isolation-Policy header so the page is cross-origin isolated, which the wasm-vips image library requires. This reuses wp_set_up_cross_origin_isolation(), extended to cover the grid and the Add New Media File screen. A shared media-upload-pipeline script configures the @wordpress/upload-media store, queues files, tracks progress, and builds error text; a thin script on each screen intercepts files as they are added to the existing uploader and hands them to that pipeline instead: the original is uploaded via the REST API, the browser generates the sub-sizes and sideloads them, then the attachment is finalized. The existing UI - progress bars, grid tiles, error notices - is reused, so the screens look and behave unchanged. While an upload is in flight the page warns before you navigate away, since an interrupted client-side upload would lose thumbnails that were not sideloaded yet.

If the browser does not support cross-origin isolation (currently Chromium 137+ on a secure origin, exposed as wp_is_document_isolation_policy_supported()) or client-side processing is disabled, the scripts do nothing and uploads fall back to the classic flow unchanged. Audio files also stay on the classic path, since media_handle_upload() derives their title and description from ID3 tags and the REST endpoint does not. Any extra multipart params a plugin adds through plupload_default_params or wp.Uploader.param() are forwarded to the REST request so they still arrive in $_POST. A HEIC file the browser cannot decode (Linux, and Windows without the HEVC extension) is handed back to the classic uploader when the server's image editor supports HEIC, so the server converts it instead of the upload failing; when neither can convert it, the pipeline's error is shown.

Error messages come straight from the pipeline, so the platform-specific HEIC wording from WordPress/gutenberg#81130 shows up in the grid's error sidebar and in the Add New Media File error rows the same way it does in the editor. Progress is estimated from the pipeline's remaining operations and sideloaded sub-sizes, since the store does not report a percentage of its own.

Not covered here: the media modal inside the editor (the "Media Library" button on an Image block) still uploads through plupload to the server, so a HEIC dropped there fails where a drop on the block succeeds. That is tracked in WordPress/gutenberg#82409.

Testing Instructions

Test in Chrome 137 or newer on a secure origin (https or localhost).

Check that client-side processing is enabled:

1. Go to Media > Library in grid view.
2. Open DevTools and run crossOriginIsolated in the console - it should return true. You can also confirm the page response includes the Document-Isolation-Policy: isolate-and-credentialless header in the Network tab. Client-side processing is on by default in a secure context; the wp_client_side_media_processing_enabled filter can turn it off.

Verify uploads go through the client-side pipeline:

3. Keep the Network tab open and drag a large image onto the grid.
4. You should see a POST to wp/v2/media creating the attachment, followed by sideload and finalize requests - and no file POST to async-upload.php. That is how you can tell the client-side pipeline handled the upload.
5. Watch the tile while that happens: the progress bar should advance as the original uploads and thumbnails are sideloaded, rather than sitting at zero until the end.
6. Confirm the attachment looks normal: thumbnail in the grid, sub-sizes listed in the attachment details. Server files should match what you get before the patch.
7. Repeat on Media > Add New Media File - same network pattern, the percentage on the row should climb, and the finished upload should show the usual row with Edit and Copy URL links.
8. Start another large upload and try closing the tab before it finishes: the browser should ask for confirmation. After uploads complete, closing the tab should not prompt.
9. Test with multiple files at once, including the same file twice - every tile should resolve.

Error handling:

10. Try a disallowed file type (rename a text file to .xyz): the grid's error sidebar shows the file name and a readable reason, and the placeholder tile is removed rather than left spinning. On Add New Media File the error renders the same notice a server-side failure does, with a Dismiss button that announces the error and returns focus to the browse button.
11. To see a server error surface, block the wp/v2/media request in DevTools (Network > right-click > Block request URL) and upload again: the server's message appears in the sidebar under the file name.

Fallback:

12. Repeat an upload in Firefox or Safari (or add ?browser-uploader on media-new.php) - files should upload through async-upload.php as before. In list mode (Media > Library, list view) the Document-Isolation-Policy header is not sent and the grid script is not loaded.
13. Upload an MP3 or WAV on either screen: it goes through async-upload.php, and the attachment title comes from the file's tags as before.
14. Open Media > Add New Media File with ?post_id= set to a post that does not exist and upload an image: it uploads unattached, with no error, matching the classic behavior.

Formats:

15. Verify that all formats supported by client side media work as expected, regardless of the server's support for them. Tests should include:

• AVIF, WebP, HEIC formats
• HDR JPEG images with Gain maps, HDR AVIF images
• WebP and PNGs with various transparency types and color depths
• PDFs, Audio and Video files also upload as expected
• GIF's get a companion video created

Automated coverage: npm run test:e2e -- media-library-client-side-upload media-new-client-side-upload runs 28 tests on Chromium (which supports DIP as of the bundled Chrome 149), covering the headers, the pipeline requests, the classic fallback when the page is not isolated, multi-file uploads with duplicates, mid-upload progress, the unload guard, audio staying classic, forwarded upload params, an invalid post_id, the error message, file name, and accessible Dismiss button for rejected and failed uploads, the readiness gate before the store's settings land, the HEIC hand-off to a server that can convert it, and a PostInit handler another script placed in wpUploaderInit.

AI Use

Code and description both written with 🤖 Claude Code. I will review and test.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props adamsilverstein, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Copilot]

Pull request overview

Extends WordPress’s client-side media processing pipeline beyond the block editor to the remaining admin upload surfaces (Media Library grid and Media > Add New), including cross-origin isolation setup, upload routing via the @wordpress/upload-media store, and new automated coverage to validate the end-to-end pipeline and headers.

Changes:

• Adds Media Library mode resolution and new helpers to enable Document-Isolation-Policy isolation and enqueue upload-routing scripts for upload.php (grid) and media-new.php.
• Introduces new admin upload integration scripts (media-library-upload, media-new-upload) that intercept plupload flows and route files through the REST-based client-side pipeline.
• Adds comprehensive PHPUnit + Playwright E2E tests covering header gating, pipeline upload behavior (create/sideload/finalize), beforeunload guards, and error handling.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/phpunit/tests/media/wpMediaNewCrossOriginIsolation.php	Adds PHPUnit coverage for DIP isolation setup on media-new.php.
tests/phpunit/tests/media/wpMediaLibraryCrossOriginIsolation.php	Adds PHPUnit coverage for DIP isolation setup and Media Library mode resolution on upload.php grid.
tests/phpunit/tests/media/wpEnqueueMediaNewUpload.php	Adds PHPUnit coverage for enqueueing media-new-upload and inline settings.
tests/phpunit/tests/media/wpEnqueueMediaLibraryUpload.php	Adds PHPUnit coverage for enqueueing media-library-upload, inline settings, and filter plumbing into settings.
tests/e2e/specs/media-upload.test.js	Adjusts an existing E2E assertion to support both server and client-side rejection UIs.
tests/e2e/specs/media-new-client-side-upload.test.js	Adds E2E coverage for media-new.php DIP header, pipeline upload, beforeunload guard, and disallowed types.
tests/e2e/specs/media-library-client-side-upload.test.js	Adds E2E coverage for upload.php grid DIP header, pipeline upload, beforeunload guard, and disallowed types (plus list-mode header absence).
src/wp-includes/script-loader.php	Registers the new admin script handles and their dependencies/translations.
src/wp-includes/media.php	Adds mode helper, isolation setup helpers, shared upload settings helper, and enqueue helpers for the two upload surfaces.
src/wp-includes/default-filters.php	Wires the new isolation setup callbacks into the relevant load-* hooks.
src/wp-admin/upload.php	Enqueues the new grid upload integration script in Media Library grid mode.
src/wp-admin/media-new.php	Enqueues the new Media > Add New upload integration script.
src/js/_enqueues/admin/media-new-upload.js	Implements media-new.php plupload interception, pipeline routing, UI mirroring, progress sync, and beforeunload guard.
src/js/_enqueues/admin/media-library-upload.js	Implements Media Library grid uploader interception, pipeline routing, UI mirroring, progress sync, and beforeunload guard.
Gruntfile.js	Adds build mappings for the two new admin scripts.

Comments suppressed due to low confidence (1)

src/wp-includes/media.php:6846

• wp_enqueue_media_new_upload() enqueues the pipeline integration on any secure origin, but wp_start_cross_origin_isolation_output_buffer() (and therefore crossOriginIsolated) is Chromium 137+ only. On other browsers this script cannot run and will always no-op, so enqueueing it adds avoidable page weight. Consider gating enqueueing on wp_get_chromium_major_version() >= 137 to skip loading unused bundles in browsers that can’t be isolated by DIP.

	if ( ! wp_is_client_side_media_processing_enabled() ) {
		return;
	}

	wp_enqueue_script( 'media-new-upload' );

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

tests/phpunit/tests/media/wpEnqueueMediaLibraryUpload.php:46

• tear_down() restores HTTP_HOST but not HTTP_USER_AGENT. If set_up() sets a Chromium UA for deterministic enqueue behavior, tear_down() should restore/unset it to avoid leaking the UA into later tests.

		if ( null === $this->original_http_host ) {
			unset( $_SERVER['HTTP_HOST'] );
		} else {
			$_SERVER['HTTP_HOST'] = $this->original_http_host;
		}

[westonruter]

Let's add the new JS files in js/_enqueues/admin to the list of files being checked by TypeScript in tsconfig.json. This will avoid us having to add fixes later.

[westonruter]

Requesting changes for using ES6 and TypeScript checking.

[adamsilverstein]

Good call on adding these to tsconfig.json - it turned up a few loose types worth fixing now rather than after they ship. Pushed in eed1755.

Claude did the work here, rundown below:

All three new scripts are in tsconfig.json now, with a new
typings/media-uploads/index.d.ts describing the plupload surface they use
(plupload.File, plupload.Uploader) and the plupload-handlers globals on
media-new.php. npm run typecheck:js passes.

Making it pass meant a real pass over the types rather than a rename. The
Object params are typedefs for what they actually are now, the Promise
return types carry their value, and the errors the pipeline surfaces are
typed as { code, message } instead of Error, since a rejected apiFetch
is often a plain REST error object rather than an Error.

One correction to the batched suggestion: the files array plupload passes
to FilesAdded holds file objects, not strings - the handler reads
file.status, file.name, and file.getNative() off each entry - so those
are plupload.File[].

const/let is finished across all three files.

Separately, the placeholder tile's early mime scan was copied from
wp-plupload.js and only matched jpg/png/gif, so a WebP or AVIF drop did not
get the type-image class its JPEG equivalent gets. That regex now covers
the formats the client-side pipeline accepts. wp-plupload.js has the same gap
on the classic path, which looks worth a separate fix.

The 23 e2e tests still pass locally against Chrome 149.

[adamsilverstein]

Pushed another round covering all of @westonruter's items plus the two red checks on the previous push.

Claude worked through the review, rundown below:

• The shared typedefs from the three scripts live in typings/media-uploads/index.d.ts now, along with a named QueueFileCallbacks type for queueFile(). WPAttachment extends Backbone.Model via a new @types/backbone dev dependency, and wp-globals no longer declares Backbone as any (5fb6956).
• media-new-upload.js no longer uses jQuery. The DOM work is plain DOM, and the FilesAdded interceptor is bound from a PostInit handler placed in wpUploaderInit.init, which plupload binds while the uploader initializes (ab98e5a).
• wp_get_media_library_mode() only returns 'grid' or 'list' now, with the @phpstan-return. Nothing saved still resolves to grid because that is what upload.php renders; details in the thread (e78fbed).
• The two failing checks: the committed multi-line conditional carried trailing whitespace (fixed in e78fbed), and jshint rejected a ternary broken before its ? (11122eb).

Verified locally: npm run typecheck:js, grunt jshint:core, phpcs on the changed PHP, 67 PHPUnit tests across the four media classes, and the 23 e2e tests in both suites against Chrome 149.

Whenever you have a chance, could you take another look?

[adamsilverstein]

This is taken care of now, and it turned out to need no code change on our side.

Claude checked the pin after the trunk merge, here is what it found:

The branch was pinned to a Gutenberg build from the wp/7.1 branch (ea285b45) that predates #81130. Merging trunk in 86ebc0b moves the pin to 5715a613, which includes it, so the built upload-media bundle in the branch now carries the platform-specific HEIC messages and getHeicUnsupportedMessage. Both admin scripts already surface errors through wp.uploadMedia.getErrorMessage(), so they pick up the new text as is.

Verified after the merge: npm run typecheck:js, grunt jshint:core, phpcs on the changed PHP, the 47 PHPUnit tests across the five media classes, and all 23 e2e tests in both suites against the worktree's local env.

[adamsilverstein]

Pushed a round of fixes from a code review pass over the branch, and the PR description is updated to match. @westonruter whenever you have a chance, another look would be great.

Claude found and fixed these, here is the rundown:

• The readiness gate in media-upload-pipeline.js checked the store for a mediaUpload setting, but the upload-media store's default state already carries a no-op mediaUpload, so the gate passed before the provider had delivered the real settings. A file dropped in that window was pulled out of plupload and queued into a store that called the no-op: the tile stayed "uploading" forever and the unload prompt never cleared. The gate now checks for the pipeline's own mediaSideload, which only the provider sets.
• HEIC: the pipeline converts HEIC in the browser and fails outright where the platform has no HEIC decoder (Linux, Windows without the HEVC extension), even on a server whose Imagick would have converted it on the classic path. When the store reports HEIC_DECODE_ERROR and plupload carries no heic_upload_error (the server supports HEIC), the file is handed back to plupload, which uploads it the classic way and the server converts it. When neither side can convert it, the pipeline's platform-specific message is still what shows.
• On media-new.php, the wpUploaderInit.init hook replaced any PostInit handler another script had already placed there. It chains it now, the same way the function form already did.

Five e2e tests cover the three cases, one of which never renders the provider to reproduce the not-yet-ready window. Four of them fail against the previous scripts; the fifth pins the existing behavior when neither the browser nor the server can convert a HEIC. All 28 e2e tests in the two suites pass, along with npm run typecheck:js, grunt jshint:core, and the 47 PHPUnit tests in the five media classes.