Media: Backport client-side media improvements from WordPress core backports

[adamsilverstein]

What

A combined "reverse-backport" PR: robustness improvements made to the client-side-media REST endpoints in WordPress core (via the wordpress-develop backport PRs) are brought back into Gutenberg where they still apply - mostly the lib/media/ sideload/finalize controller, plus coordinated token renames in the upload-media client that calls it. Each improvement lands as its own commit and is checked for current applicability against trunk first (some guards core added have since been covered differently in Gutenberg and are intentionally skipped).

Trunk has been merged into this branch so the animated-GIF-to-video code (#78410) is present and its sideload tokens can be normalized alongside the rest.

Items

• Scaled sideload attached-file guards (Core Undo action doesn't update block selection #12002 ↔ this repo's Upload Media: Enable concurrent sideload uploads #75888): in sideload_item()'s scaled branch, return rest_sideload_no_attached_file (404) when get_attached_file() is empty instead of passing a falsy value to wp_basename(), and only repoint the attached file when it changed, returning rest_sideload_update_attached_file_failed (500) if update_attached_file() fails. Core's third guard (re-read + dimension/filesize validation) is not ported - Gutenberg already validates the scaled image up-front in sideload_item() via wp_getimagesize() + validate_image_dimensions().

• Finalize sub-size schema + original-image guard (mirrors core finalize-endpoint hardening): require minLength 1 on the sub_sizes file and original_image schema properties so empty strings are rejected at validation time, and guard the finalize original branch with isset( $sub_size['file'] ) so a missing file key cannot write a null original_image into the attachment metadata.

• Non-image format-field test (Core RichText: discourage direct getting/setting of value properties #12007): assert image_output_format and image_save_progressive are omitted from the REST response for a non-image attachment (a .woff font), matching the controller's wp_attachment_is_image() gating.

• Normalize sideload image_size tokens to underscores (coordinates with Core Preview window for reusable templates are broken #11323 and Fix/button css specificity #12005): rename the special sideload size tokens to the underscore convention so they line up with the metadata keys they write:

  • original-heic → source_original (also format-agnostic - the flow handles HEIF too; writes source_image). Applied to both the upload-media client and the Gutenberg lib/media controller.
  • animated-video → animated_video and animated-video-poster → animated_video_poster (writes animated_video / animated_video_poster). Applied to the controller and client.

  These are transient request values - the files are still recorded under the source_image, animated_video, and animated_video_poster metadata keys - so no migration is required. Token comparisons use the IMAGE_SIZE_* constants and metadata writes use the META_KEY_* constants, so the now-equal token/key values never collide.

• Source-format originals skip the sideload dimension read (Core Update dropzone context API #11100/Preview window for reusable templates are broken #11323 as merged): sideload_item() no longer calls wp_getimagesize() for the source_original companion. The source format (e.g. HEIC) may not be readable by wp_getimagesize() on servers without HEIC/HEIF support - exactly the servers the client-side flow is designed to help - so reading dimensions would reject the companion as "corrupted or unsupported". Dimensions are neither validated nor recorded for source originals, matching core.

• Sideload route no longer advertises generate_sub_sizes (Core review feedback on Fix/button css specificity #12005, asserted in core's route test): sideload_item() never reads the arg, so declaring it misleads clients into expecting server-side sub-size generation from a sideload. The upload-media client never sends it to this route, and that arg keeps doing real work on create_item() (POST /wp/v2/media).

• Still HEIC/HEIF uploads always pass the permission check (Core Preview window for reusable templates are broken #11323): create_item_permissions_check() bypasses the server-side image-editor support check for still image/heic / image/heif uploads regardless of generate_sub_sizes, since the browser's canvas fallback can decode them with the native HEVC decoder. The multi-frame -sequence variants (Live Photos) are deliberately excluded and keep hitting the standard unsupported mime-type error.

• Remaining dimension-validation test coverage (Core Update dropzone context API #11100): the original-size dimension mismatch/match tests and the unreadable-image rejection test (a JFIF header with no frame data, so wp_getimagesize() fails after a successful upload).

Testing instructions

Client-side media processing exercises the sideload + finalize REST flow on upload. With the feature enabled:

1. Upload a large image (so a -scaled derivative is generated) and confirm the upload succeeds and the attachment's original_image is recorded. The scaled/finalize branches only short-circuit on failure paths (no attached file / failed repoint / missing sub-size file) that should not occur in normal operation.
2. Upload a HEIC/HEIF image and confirm the source-format original is preserved (recorded under source_image in the attachment metadata) alongside the JPEG derivative - including on a server whose PHP cannot read HEIC dimensions.
3. Upload an animated GIF and confirm it converts to a video companion (recorded under animated_video / animated_video_poster) and the block offers the core/video GIF variation.
4. Run the PHP tests for the Gutenberg attachments controller and the upload-media JS unit tests (packages/upload-media/src/store/test/) to confirm the sideload tokens and non-image gating behave as expected.

Notes

Companion to the wordpress-develop client-side-media backport PRs (#11100, #12002, #12007, #11323, #12005).

The image_quality field from the core stack (wordpress-develop #11856) is deliberately not duplicated here: #78420 already reverse-ports it, together with the client-side consumption in upload-media.

[github-actions]

Size Change: -1 B (0%)

Total Size: 7.61 MB

📦 View Changed

Filename	Size	Change
build/scripts/upload-media/index.min.js	14.3 kB	-1 B (-0.01%)

_{compressed-size-action}

[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.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>

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

[github-actions]

Flaky tests detected in bc343e3.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28550513153
📝 Reported issues:

• [Flaky Test] activate block theme when live previewing in edit mode #77712 in /test/e2e/specs/site-editor/activate-theme.spec.js
• [Flaky Test] can use appender in site editor sidebar list view #79632 in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js

[andrewserong]

This backport of the backports looks good to me!

Smoke tested uploading a GIF and the GIF -> MP4 conversion and the removal of the MP4 when deleting the item in the media library.

LGTM! 🚀