GIF to video conversion: make it opt-in. Switching via block transforms

[adamsilverstein]

What?

Closes #79787.

Makes the animated GIF → video conversion opt-in: uploading an animated GIF now keeps the Image block, and the conversion to the Video block's "GIF" variation is offered through the standard block switcher (Transforms API), with a matching transform back to the Image block.

Follow-up to #78410, addressing the design feedback in #79787.

Why?

Per feedback from @jasmussen and @Mamaduka on #79787:

• The automatic swap happened after a background transcode finished, marking the document dirty again and changing the block underneath the author (a race-condition-like delayed conversion).
• The conversion is a media-type change with visible consequences (slight softening, different block tools), so it should be the author's explicit choice.
• The bespoke "Display as video" / "Display as GIF" toolbar buttons took up scarce toolbar space and stepped into bespoke territory; the built-in transforms dropdown is the established surface for exactly this.

Using the Transforms API also gets us behaviors the custom buttons had to reimplement: the transform is hidden when the target block can't be inserted (e.g. inside a Gallery, or when the Video block is disabled), and the change is a single, regular undo step.

How?

• packages/block-library/src/image/edit.js: removed the automatic Image → Video block replacement that ran when a GIF upload's sideloaded companion became available. The companion video is still transcoded and sideloaded at upload time - only the block swap became opt-in.
• Removed AnimatedGifConvertControl (Image block) and GifRestoreControl (Video block) toolbar buttons.
• packages/block-library/src/image/transforms.js: new to transform to core/video. It only matches when the attachment record carries a sideloaded animated_video companion, so ordinary images never see it. The transform creates the Video block's GIF variation (muted, looping, autoplaying, inline, no controls) with the GIF's intrinsic dimensions.
• packages/block-library/src/video/transforms.js: new to transform to core/image, offered only for GIF-behaving videos whose attachment is an image, restoring the original GIF.
• Block transforms match synchronously, so the shared helpers in packages/block-library/src/utils/gif-conversion.js (renamed from gif-conversion-attributes.js) read the attachment record straight from the core-data store. The Image block already resolves the record while selected; the Video block now does the same for GIF-behaving videos.
• Updated the gif-to-video.spec.js e2e test to cover the new flow: upload stays an Image block, round-trip through the block switcher.

Not addressed here (still open on #79787): the @wordpress/video-conversion package support policy, and the on-drop prompt idea (per @Mamaduka, exploration for another release).

Testing Instructions

1. Enable client-side media processing (Gutenberg → Experiments) in a cross-origin-isolated environment.
2. Upload an animated GIF into an Image block.
3. Verify the block stays an Image block - no automatic conversion happens.
4. With the block selected, open the block switcher (the "Image" button in the block toolbar). Once the companion video has been sideloaded, a Video entry appears. Click it.
5. The block becomes the Video block's "GIF" variation: muted, looping, autoplaying, keeping alignment/anchor/class/caption.
6. Open the block switcher on the converted block and choose Image: the original GIF is restored.
7. Verify an ordinary (non-animated) image never offers the Video transform, and that a GIF inside a Gallery doesn't either.

npm run test:e2e -- test/e2e/specs/editor/various/gif-to-video.spec.js
npm run test:unit -- packages/block-library/src/utils/test/gif-conversion.js packages/block-library/src/image/test/transforms.js packages/block-library/src/video/test/transforms.js

Screenshots or screencast

The block switcher on an uploaded animated GIF offering the Video transform (no more dedicated toolbar button):

And the converted block - labeled with the GIF variation - offering the Image transform back:

Gif variation video block:

Transform variation button:

[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>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: jasmussen <joen@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]

Size Change: -631 B (-0.01%)

Total Size: 7.68 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-library/index.min.js	333 kB	-631 B (-0.19%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 3e8d205.
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/29046126495
📝 Reported issues:

• [Flaky Test] should undo backtick transform with backspace #76178 in /test/e2e/specs/editor/various/rich-text.spec.js

[Mamaduka]

A quick review:

• test/transforms.js - these unit tests aren't needed. It's not the block's responsibility to test the Block API. Even the existing stripFirstImage is a utility test. E2E tests will cover most of this behavior anyway.
• Let's single block handle the transformation, no need to have functionality/utilities "between" two blocks.
• IMO, transform back to GIF isn't needed. If the user doesn't like the results, they can undo the change. We can always add this later if it's requested.

[adamsilverstein]

A quick review:

• test/transforms.js - these unit tests aren't needed. It's not the block's responsibility to test the Block API. Even the existing stripFirstImage is a utility test. E2E tests will cover most of this behavior anyway.

Ok makes sense, will remove and check / improve e2e coverage.

• Let's single block handle the transformation, no need to have functionality/utilities "between" two blocks.

Ok will do.

• IMO, transform back to GIF isn't needed. If the user doesn't like the results, they can undo the change. We can always add this later if it's requested.

I should verify that undo works as expected now that you mention it and maybe add an e2e test for that :) I'm fine removing the transform back to GIF to simplify the feature. I've taken all of the design inspiration from @swissspidy's media-experiments plugin and mostly followed the patterns established there.

I'll remove the transform back to GIF for now, but I'm curious to hear what others think as well.

[adamsilverstein]

Addressed in 3dc9135 and e2322f2:

• Removed the transform back to GIF (and the attachment prefetch in the Video block that only served it). Verified undo restores the Image block and the e2e test now asserts that.
• The Image block now owns the transformation; the helpers moved into its transforms.js and the shared util is gone.
• Removed the unit tests; the e2e test covers the conversion behavior.

[adamsilverstein]

@Mamaduka ready for another review when you have a chance!

[andrewserong]

Sorry, I didn't get a chance to review this properly before finishing up for the week. Happy to give it a closer look next week if it's still open. Just on this feature:

IMO, transform back to GIF isn't needed. If the user doesn't like the results, they can undo the change. We can always add this later if it's requested.

Oftentimes folks will want to make a change after testing how something looks on the site frontend. In the case of switching to a Video, maybe someone sees how it looks on the site frontend and then thinks "Nah, this worked better as an Image block, I'll switch it back". So in general, if we offer transforms in one direction, it feels strange to me (from a UX perspective) to not allow it back in the opposite direction.

I don't feel strongly about this, though, but since we're discussing it, just wanted to share the perspective 🙂

[Mamaduka]

There are many one-directional block transformations, so there's no clear UX for this in the project. You can still undo changes after previewing the posts.

I think we can ship this way and see how people are using it, then adjust as needed.

[andrewserong]

There are many one-directional block transformations, so there's no clear UX for this in the project.

Good point. I think I'm just not much of a fan of them, but again this is likely just my personal preference.

I think we can ship this way and see how people are using it, then adjust as needed.

Absolutely, no need to block on this!

[Mamaduka]

I think I'm just not much of a fan of them, but again this is likely just my personal preference.

Undos can be better (like many other things in this project), but they work fairly well, and most users are familiar with the concept. Made a mistake, undo it, didn't like the change, undo it, etc.

[andrewserong]

Also I was totally overthinking this one — the GIF is still in the Media library, so a user can just add the Image block again and select the image directly if they want to.

[andrewserong]

Alrighty, this is an incredibly cursory review from a smoke test and a skim of the code, so you might want to also confirm from @Mamaduka or others, but this LGTM 👍

✅ The Video option is available in transforms for a GIF that can be converted to an MP4
✅ It is not available for a transparent GIF
✅ The conversion to MP4 only happens once, so subsequent adding of Image blocks and converting to Video doesn't result in multiple MP4 files in the media library
✅ The GIF is still available in the media library for users to add an Image block again if they really want to

One tiny wrinkle that's probably not a real issue: we're using select from the default registry, which isn't guaranteed to always contain the attachment records (e.g. for custom editors that might use a custom registry). But I don't think this is an issue because it'll fallback gracefully to simply not showing the transform in the list.

So this LGTM and has my vote. Thanks for the follow-up @adamsilverstein and for the persistence in honing in on a good UX @Mamaduka!

[Mamaduka]

Works as expected and code looks good ✅

One tiny wrinkle that's probably not a real issue: we're using select from the default registry, which isn't guaranteed to always contain the attachment records

@andrewserong, right, also don't love it, but there we have no other option at the moment. The File block has been using a similar method for years now, and I've not seen any bug reports. I guess it's fine for transformations, but it has its own downsides, as you mentioned.

[adamsilverstein]

Thanks for pushing this forward @andrewserong and @Mamaduka!