WIP - Add circle crop mask support by ramonjd · Pull Request #79393 · WordPress/gutenberg

ramonjd · 2026-06-22T07:16:37Z

What?

Adds MVP support for circular crops in the media editor. At the moment its state is MVP/POC to guide direction.

Kapture.2026-06-26.at.14.26.45.mp4

Backport PR here: WordPress/wordpress-develop#12327

Adds circle crop mask handling to the attachments REST edit flow.
Adds Gutenberg image editor subclasses for applying image masks.
Adds Rectangle/Circle stencil selection in the crop panel.
Adds a mobile/footer toolbar crop-shape dropdown.
Uses edge handles for the circle stencil so resizing feels like dragging the circle edge.
Saves circle crops as PNG to preserve transparency.

Testing Instructions

Open the media editor for an image.
Go to the Crop panel.
Confirm the Shape control shows Rectangle and Circle.
Select Rectangle and confirm aspect-ratio controls are available.
Select Circle and confirm aspect-ratio controls are hidden.
Crop and save the image.
Confirm the saved result is circular with transparent corners and is saved as PNG.
On a narrow/mobile viewport, confirm the footer toolbar shows the crop-shape dropdown.
Use the mobile dropdown to switch between Rectangle and Circle.
Confirm circle resizing uses the middle edge handles instead of corner handles.

github-actions · 2026-06-22T07:25:27Z

Size Change: +960 B (+0.01%)

Total Size: 7.5 MB

📦 View Changed

Filename	Size	Change
`build/scripts/editor/index.min.js`	477 kB	+830 B (+0.17%)
`build/styles/editor/style-rtl.css`	30.8 kB	+28 B (+0.09%)
`build/styles/editor/style-rtl.min.css`	26.2 kB	+35 B (+0.13%)
`build/styles/editor/style.css`	30.9 kB	+32 B (+0.1%)
`build/styles/editor/style.min.css`	26.2 kB	+35 B (+0.13%)

_{compressed-size-action}

ramonjd · 2026-06-22T07:27:30Z

+	 *
+	 * @return array
+	 */
+	protected function get_edit_media_item_args() {


This is vibed coded as I wanted to test the flow first before doing it the right way. If it's a good direction, we'll do it with a more staggered approach.

ramonjd · 2026-06-22T07:32:21Z

+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
+	 */
+	public function edit_media_item( $request ) {


non-mask request → parent::edit_media_item( original request ) → done circle mask request → strip mask modifier → parent::edit_media_item( request without mask ) → Core creates unmasked edited attachment files → Gutenberg creates masked PNG replacement → delete Core-created unmasked files for that new attachment → regenerate metadata for PNG

ramonjd · 2026-06-23T06:48:16Z

+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return bool Whether the request has a circle mask modifier.
+	 */
+	protected function gutenberg_has_circle_mask_modifier( $request ) {


Maybe could be done inline too. Pretty chunky in there though.

github-actions · 2026-06-23T07:19:13Z

Flaky tests detected in 236386f.
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/28007715228
📝 Reported issues:

[Flaky Test] does not dirty related template parts or navigation menus when rendered in the post editor #79294 in /test/e2e/specs/editor/blocks/navigation-passive-rendering.spec.js

ramonjd · 2026-06-26T03:28:17Z

+	 * @param array $args Test arguments.
+	 * @return bool Whether this editor is supported.
+	 */
+	public static function test( $args = array() ) {


This function is oddly named for a public function.

I see there's a precendent: https://github.com/WordPress/wordpress-develop/blob/260fcbea3475459052c3ed3338c880a4d365ff5f/src/wp-includes/class-wp-image-editor-gd.php#L41

ramonjd · 2026-06-26T03:30:28Z

+/**
+ * Minimal disposable helper for mask argument validation.
+ */
+class Gutenberg_Image_Editor_Mask {


Just to confirm, this is a GB only helper. Maybe it could be a function, and named _gutenberg_something... and given a @private annotation?

Copilot

Pull request overview

Adds MVP/POC support for circular image crops in the Media Editor, spanning UI/state updates in packages/media-editor and a WordPress REST /edit compatibility layer that can apply a circular mask and output PNG to preserve transparency.

Changes:

Introduces a cropShape option (rectangle/circle) with undo/history integration and “dirty” tracking.
Adds a circular stencil UI (edge handles + circular overlay styling) and exposes shape selection in the Crop panel and mobile/toolbar controls.
Extends the attachments /edit flow with an experimental mask modifier and registers mask-capable image editors (Imagick/GD) to produce circular PNG outputs.

Reviewed changes

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

Show a summary per file

File	Description
packages/media-editor/src/state/use-media-editor-state.ts	Adds `setCropShape` controller API and includes crop shape in dirty tracking.
packages/media-editor/src/state/types.ts	Defines `CropShape` and adds `cropShape` to `CropOptionsSlice` + action types.
packages/media-editor/src/state/test/use-media-editor-state.ts	Adds coverage for undo/dirty behavior when switching crop shape.
packages/media-editor/src/state/index.ts	Re-exports `CropShape` type.
packages/media-editor/src/state/composite-reducer.ts	Implements `SET_CROP_SHAPE` handling and includes crop shape in equality checks.
packages/media-editor/src/image-editor/react/components/stencils/test/circle-stencil.tsx	Adds unit test ensuring circle stencil uses edge handles (not corners).
packages/media-editor/src/image-editor/react/components/stencils/rectangle-stencil.tsx	Adds internal props to support circle styling and edge-handle locking.
packages/media-editor/src/image-editor/react/components/stencils/circle-stencil.tsx	Implements circle stencil by composing `RectangleStencil` with square constraints.
packages/media-editor/src/image-editor/react/components/index.ts	Exports `CircleStencil`.
packages/media-editor/src/image-editor/react/components/cropper.tsx	Adds `stencilShape` support and enforces square constraints for circle crops.
packages/media-editor/src/image-editor/react/components/cropper.scss	Adds circular overlay styling (grid/dimming/stencil border radius).
packages/media-editor/src/image-editor/index.ts	Re-exports `CircleStencil` from the package surface.
packages/media-editor/src/image-editor/core/test/stencil-math.ts	Adds test coverage for locked edge-handle resizing behavior.
packages/media-editor/src/image-editor/core/stencil-math.ts	Adds `computeLockedEdgeResizeRect` and routes edge handles through it.
packages/media-editor/src/components/media-editor/use-save-media-editor.ts	Appends `mask` modifier when `cropShape` is `circle`.
packages/media-editor/src/components/media-editor/use-crop-options.ts	Exposes `cropShape` setters and resolves circle to a square aspect ratio.
packages/media-editor/src/components/media-editor/test/use-crop-options.tsx	Adds coverage for circle resolved aspect ratio and reset behavior.
packages/media-editor/src/components/media-editor/style.scss	Tweaks sidebar padding on small breakpoints.
packages/media-editor/src/components/media-editor/index.tsx	Wires crop shape into Crop panel and hides aspect ratio controls for circles.
packages/media-editor/src/components/media-editor-modal/build-modifiers.ts	Extends modifier union type to include `mask`.
packages/media-editor/src/components/media-editor-image-controls/test/index.tsx	Adds test coverage for toolbar crop-shape dropdown and circle behavior.
packages/media-editor/src/components/media-editor-image-controls/style.scss	Adjusts toolbar layout wrapping/centering for added controls.
packages/media-editor/src/components/media-editor-image-controls/index.tsx	Adds crop-shape dropdown and hides aspect ratio dropdown for circle crops.
packages/media-editor/src/components/media-editor-crop-panel/test/index.tsx	Adds test coverage for crop shape selection and circle-specific UI behavior.
packages/media-editor/src/components/media-editor-crop-panel/index.tsx	Adds shape toggle group and conditionally renders aspect ratio selector.
packages/media-editor/src/components/media-editor-canvas/index.tsx	Passes circle stencil + `stencilShape` to the Cropper when shape is circle.
lib/media/class-gutenberg-rest-attachments-controller.php	Switches controller base to a mask-capable attachments controller.
lib/compat/wordpress-7.1/image-editor-mask.php	Registers mask-capable Gutenberg image editors via `wp_image_editors` filter.
lib/compat/wordpress-7.1/image-editor-mask-validation.php	Adds validation/normalization helper for mask arguments.
lib/compat/wordpress-7.1/class-gutenberg-rest-attachments-controller-with-mask.php	Adds `mask` modifier schema and custom `/edit` flow to apply mask + PNG output.
lib/compat/wordpress-7.1/class-gutenberg-rest-attachments-controller-7-1.php	Updates 7.1 controller to inherit mask-capable base.
lib/compat/wordpress-7.1/class-gutenberg-image-editor-imagick.php	Adds Imagick editor subclass implementing `mask()` for circle cropping.
lib/compat/wordpress-7.1/class-gutenberg-image-editor-gd.php	Adds GD editor subclass implementing `mask()` for circle cropping.

+				'title'      => __( 'Mask', 'gutenberg' ),
+				'properties' => array(


ramonjd changed the title ~~Add circle crop mask support~~ WIP - Add circle crop mask support Jun 22, 2026

ramonjd self-assigned this Jun 22, 2026

ramonjd added [Type] Experimental Experimental feature or API. No Core Sync Required Indicates that any changes do not need to be synced to WordPress Core labels Jun 22, 2026

ramonjd commented Jun 22, 2026

View reviewed changes

ramonjd force-pushed the ramonjd/circle-crop-stencil branch from 3486e5e to a63aeb2 Compare June 22, 2026 07:29

ramonjd commented Jun 22, 2026

View reviewed changes

ramonjd force-pushed the ramonjd/circle-crop-stencil branch 2 times, most recently from 509d976 to 236386f Compare June 23, 2026 06:46

ramonjd commented Jun 23, 2026

View reviewed changes

ramonjd force-pushed the ramonjd/circle-crop-stencil branch from 236386f to 21c22f7 Compare June 26, 2026 03:46

Add circle crop mask support

792717d

ramonjd force-pushed the ramonjd/circle-crop-stencil branch from 21c22f7 to 792717d Compare June 26, 2026 03:54

ramonjd commented Jun 26, 2026

View reviewed changes

ramonjd added 3 commits June 26, 2026 14:01

Refine mask helper and media editor padding

e356443

Use edge handles for circle crop stencil

6d9750e

Add mobile crop shape toolbar control

2c159e3

ramonjd requested a review from Copilot June 26, 2026 04:27

Copilot started reviewing on behalf of ramonjd June 26, 2026 04:27 View session

ramonjd mentioned this pull request Jun 26, 2026

Media Editor Modal task tracking #73771

Open

75 tasks

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Comment thread lib/compat/wordpress-7.1/class-gutenberg-rest-attachments-controller-with-mask.php

Comment on lines +44 to +45

'title' => __( 'Mask', 'gutenberg' ),

'properties' => array(

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WIP - Add circle crop mask support#79393

WIP - Add circle crop mask support#79393
ramonjd wants to merge 4 commits into
trunkfrom
ramonjd/circle-crop-stencil

ramonjd commented Jun 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

ramonjd Jun 22, 2026

Uh oh!

ramonjd Jun 22, 2026

Uh oh!

ramonjd Jun 23, 2026

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

ramonjd Jun 26, 2026

Uh oh!

ramonjd Jun 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ramonjd commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Testing Instructions

Uh oh!

github-actions Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

ramonjd Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

ramonjd Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

ramonjd Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ramonjd Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ramonjd commented Jun 22, 2026 •

edited

Loading

github-actions Bot commented Jun 22, 2026 •

edited

Loading