Media Editor experiment: add experimental image editor and cropper

[ramonjd]

Summary

A modular image cropper inside @wordpress/media-editor with a custom implementation built on gl-matrix for precise 2D transforms.

Desktop

Kapture.2026-04-20.at.12.00.18.mp4

Mobile

ScreenRecording_04-20-2026.11-55-26_1.mp4

Architecture

Two layers in one package:

• Core (core/) — Framework-agnostic pure functions. Zero React dependency.
• React (react/) — Thin adapter: hooks wrapping core functions, and components for rendering.

Features

• Rectangular crop with 8 resize handles and aspect ratio lock
• Fixed crop mode (react-easy-crop style) and freeform crop mode with settle animation
• Continuous ±45° rotation slider + 90° snap rotation (Google Photos style, preserves image selection)
• Focal-point zoom (mouse wheel and pinch-to-zoom center on cursor/finger position)
• Touch support: single-finger pan, two-finger pinch zoom with combined pan, double-tap zoom
• Gesture-based undo/redo via onGestureStart/onGestureEnd callbacks
• JSON-serializable transform pipeline (TransformOperation[]) for AI agent integration
• Canvas export: applyToCanvas() accepts any CanvasImageSource for multi-step editing pipelines
• getSourceRegion() / getSourceRegionPercent() for server-side processing (FFmpeg, WP REST API)
• Headless processing: stateFromPipeline() replays operations without DOM
• Pluggable stencils via StencilProps interface
• Full keyboard accessibility (arrow keys, +/-, R) with ARIA live region announcements
• CSS-only theming via BEM classes (.wp-media-editor-image-cropper__*)
• Pointer capture for iframe-safe drag interactions

Public API (26 exports)

React: Cropper, CropperProvider, useCropper, useCropperState
Functions: getSourceRegion, getSourceRegionPercent, exportCroppedImage, applyToCanvas, stateFromPipeline, applyOperationToState
Constants: DEFAULT_STATE, DEFAULT_ASPECT_RATIOS, ORIGINAL_ASPECT_RATIO
Types: CropperState, CropperAction, TransformOperation, NormalizedRect, NormalizedPoint, Size, Flip, StencilProps, SourceRegion, SourceRegionPercent, AspectRatioPreset, CropperProps, UseCropperStateReturn

New dependency: gl-matrix

The cropper uses gl-matrix (v3) for 2D affine matrix math — specifically mat2d (5 functions) and vec2 (2 functions). This provides:

• Composable transforms: pan, rotation, flip, zoom as a single mat2d matrix
• Invertible camera: restriction projects crop corners through the inverse camera, guaranteeing the restriction agrees with what's rendered
• JIT-optimized Float32Array-backed operations
• ~15 KB minified tree-shaken (only mat2d + vec2 + common are included; sideEffects: false enables tree-shaking)
• Well-tested, stable library with no transitive dependencies

The alternative — hand-rolling 2D affine math — would save ~15 KB but introduce maintenance surface for matrix inversion and composition with no user-visible benefit.

Documentation

• README.md — Full public API reference
• docs/architecture.md — Coordinate spaces, data flow, design decisions
• docs/recipes.md — Getting started, extension points, integration patterns

Test coverage

254 unit tests across 5 core test suites:

• Camera math and containment invariant (184 tests, including 200 random state combinations)
• State reducer: SETTLE_CROP accuracy, enforceContainment ordering, focal-point zoom (16 tests)
• Interaction controller: pointer drag, wheel zoom, keyboard, touch pan/pinch transitions (30 tests)
• Plus pipeline and export tests

Test plan

Automated

• npx wp-scripts test-unit-js --testPathPattern="image-editor/core/test" — 254 tests pass
• npx tsc --project tsconfig.json --noEmit — zero errors

Storybook (manual)

Run npm run storybook and test each story under MediaEditor/ImageEditor:

• Default — Image renders, can pan by dragging, mouse wheel zooms
• WithControls — Rotation slider, zoom slider, flip buttons, aspect ratio presets, freeform toggle all work. Export preview updates live.
• WithPreview — Freeform crop toggle works. Export preview matches cropper view at all zoom/pan/rotation/flip states.

Touch (manual, on mobile/tablet)

• Single-finger pan works
• Two-finger pinch zoom works reliably (fingers can land at different times)
• Double-tap toggles between 1x and 2x zoom
• Freeform crop handles work without triggering image pan
• Releasing one finger after pinch does NOT switch to pan

Keyboard (manual)

• Arrow keys pan the image
• +/- zoom in/out
• R rotates 90°
• Tab to crop handles, arrow keys resize (in freeform mode)

Use of AI

I used various models (mainly Opus 4.6/47, GPT 5.4) to build, test, review, debug and document this feature.

Specs were human-driven, so too manual and acceptance criteria testing.

[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: ramonjd <ramonopoly@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.

[andrewserong]

Just an idle thought about the tests in this file: I like that we're adding some e2e tests for the storybook case: I didn't realise we could do that in the GB repo. Even though they're only run manually, given the granular nature of the cropping tools, I do like that we're adding coverage, as I think it'll help with developing the library.

A question re: the readImageMatrix tests: are these duplicative of some of the unit tests already in place? Totally fine if what we need to do here is the actual integration testing (especially of mouse wheel events, etc), but just wondered how useful the tests are.

(I don't mind at all including them, it just stood out as I was reading over so thought I'd leave a comment)

[ramonjd]

Agreed. The reducer logic is covered in unit tests.

I asked for this to act as integration smoke tests. They are meant to prove that the browser events (wheel, pointer capture, keyboard focus) fire and do something.

Happy to narrow them down if that’s too much for manual-run tests

I'll add a comment here to explain why they exist for now. Happy to remove them all once we do a "real" integration.

[andrewserong]

(Totally optional!) This is a bit of a code quality nit, but the camera.ts file is pretty big. I'm wondering if it would make sense for some or all of the restrict* functions to be moved into a separate file, possibly named containment.ts so that the camera.ts file is more about the camera layer?

Basically I'm thinking that the containment logic is important enough to warrant its own file.

[ramonjd]

Yeah, good call. Almost as if we need a "containment" split. Let me see if we can break it down into logical streams. I appreciate your feedback here!

[andrewserong]

This is testing really nicely so far! Love all the interactions and especially how nice the freeform crop feels to use. It looks like you've done a lot of polishing on the interactions before opening up a Gutenberg PR, nice work 👍

A couple of things I noticed while testing this out in Storybook. The first I think might just be a bug in the story, but would be good to fix up as it's the example usage for the component. In the fine-grained rotation slider, if you drag it to > 224 degrees, it goes into a bit of an infinite loop if you continue dragging, which I think is due to the calculation. I'm new to looking at this code so I used Claude to look into this locally, here's a couple of suggestions from Claude (please take it with a grain of salt). Happy to dig in further if you'd like:

Slider rotation wraps at ±MAX_ROTATION_OFFSET (rectangle-crop.story.tsx:148-167, and same pattern at :514-533)

Dragging the fine-rotation slider past 224° makes the thumb jump back to the left edge and the rotation value oscillates. baseAngle is computed as Math.round(state.rotation / 90) * 90 every render, so at rotation = 225°, Math.round(2.5) === 3 flips baseAngle from 180→270 and fineOffset wraps from +45→−45. While the user is still dragging, the native range input re-syncs the thumb to the pointer, which re-triggers the wrap.

Two fixes worth considering: (a) clamp the slider so the exact midpoint (225°/135°/315°) is unreachable — e.g. cap max at MAX_ROTATION_OFFSET − step; or (b) track baseAngle as local component state, updated only via snapRotate90/the ±90 buttons, so the slider's reference frame is stable across renders.

Here's where the bug appears in my testing:

2026-04-20.14.37.23.mp4

---

The other thing I noticed is that the logic that ensures that we zoom in (and restrict the zoom values) when rotation occurs so that the crop area doesn't fall outside of the area of the image itself, feels a little too restrictive. In the following video note that the zooming goes a little more zoomed in than looks necessary visually, and I can't zoom out to get it closer to the edge. Apologies, I haven't looked closely at the code that determines this just yet, but I'm wondering if the calculation is slightly off, or if there's a threshold that's used, if it's a little too wide:

2026-04-20.14.42.53.mp4

---

In general, as discussed on your earlier work on this, I really like the architectural direction for this, for a few reasons:

• The world/camera/screen idea sets things up nicely for further features that allow browsing and panning the image independently, so we could eventually add a Photoshop navigator-like feature or just zooming and interacting with larger images
• In lots of the previous PRs and work we've done on image cropping in the block editor and in media editor experiments we've consistently run into issues with 3rd party cropping libraries, either bugs, missing features, or the cropping libraries being in variable states of maintenance. Especially since media management is such an important part of WordPress, I think the timing is right to include a bespoke cropping library.
• I like the transform operation pipeline, and the idea that we'll be able to store or replay a stack of operations 👍
• Proposing the image-editor within the media-editor gives us a good place to try out and iterate on this cropper as part of media editor experiments, without exposing it directly as an API. I think this helps build confidence in the approach, as we'll be able to see how the cropper feels (both in UI and in its code) while still being able to remove it or replace with a 3rd party library if it winds up being too complex to maintain ourselves
• However, all up I'm feeling pretty confident in this being a good direction 🎉

I've only skimmed the code so far, but I'll give it a bit more of a closer look and drop further comments as I test. But this is an exciting PR!

[andrewserong]

I left a comment about potentially splitting out part of camera.ts into a separate file. Some other ideas about further splitting things up for readability / maintainability — these are just thoughts, not a blocker to this PR as it could be explored separately in follow-ups, and I don't want to delay any work here needlessly. But to capture the thoughts:

• interaction-controller.ts is pretty big, especially in the handleTouchStart method. Is there an opportunity to further split the innards of that up into smaller parts, i.e. helpers in a separate file called interaction-touch or something like that? handleTouchStart in this class would still be the entry point.
• In cropper.tsx there might be opportunities to extract some logic into separate hooks, as currently there's a lot going on in the file with lots of useEffects.
  • Could we create a hook to include buildAnnouncement function and the useEffect that calls it? E.g. something like useAriaAnnouncer?
  • Around line 235 there's a useEffect to auto-size the crop rect. Similarly around line 275 there's a useEffect for computing the largest inscribed rect of the new ratio. Could these be moved into something like a useCropRectAutoResize hook or something like that?
• In rectangle-stencil.tsx there's potentially another opportunity to break things down into smaller hooks. This is a smaller file altogether, though, so the benefit might be minimal. Just something to keep in mind as it grows.

[ramonjd]

The first I think might just be a bug in the story, but would be good to fix up as it's the example usage for the component. In the fine-grained rotation slider, if you drag it to > 224 degrees, it goes into a bit of an infinite loop if you continue dragging

yes! I also saw this while testing and the conclusion was that it’s a known quirk of the native element. When you drag past the rail edge, the native slider keeps tracking the pointer’s x-coordinate and snaps to the min or max. I'll see if the custom RangeControl component works better here.

Edit: it doesn't it's a native control issue. Maybe the remedy is to use a different control or wrap the control and add some events to prevent mouse drag. I'll keep it on the list, but don't think it's a blocker yet.

[andrewserong]

Edit: it doesn't it's a native control issue. Maybe the remedy is to use a different control or wrap the control and add some events to prevent mouse drag. I'll keep it on the list, but don't think it's a blocker yet.

Good stuff. We can revisit if we run into any issues when implementing the cropper in media-editor components 👍

[ramonjd]

en rotation occurs so that the crop area doesn't fall outside of the area of the image itself, feels a little too restrictive.

Looks like we can tweak the threshold - it was over-estimated

[ramonjd]

I think I've addressed most of the feedback.

One UX improvement I'm looking at in parallel is to explore more intelligent zooming, e.g., drag handle zoom-out, increasing crop size if it fits the container.

This video shows the latter.

2026-04-20.19.36.41.mp4

To make it work consistently requires a rewire so I'm treating it as a follow up on the roadmap.

[ramonjd]

Just updated the story with proper WordPress components and an upload button so we can test different original aspect ratios