Media Editor: Magnify the crop to fill the canvas

[ramonjd]

What

At rest, the crop now magnifies so it fills most of the canvas, and the minimum crop size adapts to the on-screen scale. Fixes small/unusable crops when a large image is shown in a small window.

Before

Kapture.2026-06-10.at.11.12.06.mp4

After

Kapture.2026-06-10.at.11.08.10.mp4

What changed

• getViewScale: presentational magnification that scales the whole scene (image + overlays) so the crop reaches ~80% of its constraining canvas axis; image bleeds past the canvas and is clipped. Never touches zoom/pan/cropRect, so the export is unchanged.
• Magnification holds steady during a resize (frozen at grab) and recomputes on settle, so grabbing a handle no longer resets the zoom.
• Folded the magnification into the image's single transform so the settle animates as one coherent motion (no left/right jump).
• Adaptive minimum crop (getMinCropPixels), now view-scale aware, so handles stay operable on large scaled-down images and yield to the 24px source floor once shown large enough. Replaces Media Editor: Keep crop handles operable on large images #79011 (reverted here).

Manual testing

Tip

Test in playground

1. Open the media editor on an image much larger than the canvas (e.g. 1400x2500), in a small window.
2. Crop a square region and release; confirm the crop magnifies to fill the canvas and the image bleeds off the edges.
3. Watch the settle: the image should slide/scale to position, not jump sideways.
4. Grab a handle again; confirm the view stays put (no zoom-out) while dragging, then re-fits on release.
5. On the first crop of a large image, drag a handle inward as far as it goes; confirm the handles stay grabbable and don't collapse.
6. Repeat on a small image and a crop that already fills the canvas; confirm no magnification is applied.

Use of AI

Reasoning and code generation.

[github-actions]

Size Change: +153 B (0%)

Total Size: 8.59 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	468 kB	+153 B (+0.03%)

_{compressed-size-action}

[Copilot]

Pull request overview

This PR updates the Media Editor cropper to apply a presentational “view-scale” magnification at rest so under-filling crops occupy ~80% of the available canvas, while also making the minimum crop size adaptive to the effective on-screen scale (fit × zoom × view-scale) to keep handles usable on large images shown small.

Changes:

• Added getViewScale and related constants to compute a capped magnification factor that scales the whole scene without affecting exported output.
• Froze view-scale during active resize gestures and folded the magnification into the image transform to keep settle/drag behavior visually stable.
• Updated cropper tests and camera tests to cover the new view-scale behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/media-editor/src/image-editor/react/components/test/cropper.tsx	Adds integration-style assertions for view-scale magnification and freezing behavior during resize.
packages/media-editor/src/image-editor/react/components/cropper.tsx	Applies view-scale to rendering/interaction sizing, freezes it during resize, and updates min-crop sizing to be view-scale aware.
packages/media-editor/src/image-editor/core/test/camera.ts	Adds unit tests for getViewScale behavior (no magnification, target fill, clamping, degenerate inputs).
packages/media-editor/src/image-editor/core/stencil-math.ts	Updates getMinCropPixels docs to reflect inclusion of view-scale in display scale.
packages/media-editor/src/image-editor/core/constants.ts	Introduces SETTLE_TARGET_CANVAS_FILL and MAX_VIEW_SCALE constants for the new magnification behavior.
packages/media-editor/src/image-editor/core/camera.ts	Adds getViewScale helper for computing presentational magnification.

[github-actions]

Flaky tests detected in 534ce6e.
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/27463736385
📝 Reported issues:

• [Flaky Test] Insert from URL prepends https when URL has no protocol #79156 in /test/e2e/specs/editor/blocks/image.spec.js
• [Flaky Test] image inserted via link should appear in the frontend published post content #79170 in /test/e2e/specs/editor/blocks/image.spec.js
• [Flaky Test] should insert block with the slash inserter when using multiple words #78887 in /test/e2e/specs/editor/various/inserting-blocks.spec.js

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

[ramonjd]

@andrewserong when you have 5 mins, I'd love to get your opinion on this change. Just a quick smoke test would help a lot.

The motivation was that I found it awkward to create thin/small slices in small viewport sizes. This PR zooms the cropped area to fill more of the available space.

A link to test in playground

[andrewserong]

From a quick smoke test, it's feeling good to me! With the current behaviour of the cropper where we don't have a manual viewport zoom or navigator component (like Photoshop, etc) we do need some smarts to make the viewport area the right level of zoom for what a user is attempting to do.

And in general this is feeling good to me for the case you've got in the PR description — a tall image where you want to create a thin slice. So overall I think this is a good direction (I haven't looked at the code 😄)

Beyond 7.1, it's making me wonder about some of the nuance for really small images. Some of this mightn't be necessary for the majority use case, but when we think about a generalised media / image cropper, a couple of things come up for me once we start zooming in on smaller images. Take a tiny image for example:

2026-06-10.12.29.49.mp4

With this PR, if we open it up in the cropper, then it helpfully expands to be zoomed in, making it easier to crop. But at the same time, I notice a few wrinkles in the behaviour:

• The rendering in the canvas is smoothed so instead of nearest-neighbour rendering where we can see the exact boundary of each pixel, it's hard to see where we'll actually be cropping.
• Dragging the drag handles does not snap to individual pixels.
• We can't toggle preview at actual size.

So, and this is not at all a blocker for this PR, but it makes me wonder how we can take some of the smarts we're building and add lightweight control or affordances on top of it. This is probably a similar question to advanced controls and enabling users to toggle the 3rds grid, etc. But eventually, it might be nice to make the drag handles snap to pixel size + add a button (somewhere!) to toggle viewing at actual size. We might never wind up adding a full Photoshop-like navigator, but in principle, I'd like to think that we could 😄.

Anyway, those are my first impressions! TL;DR — I like the idea, and I think this behaviour will make it feel more usable on balance.

(Happy to give this a proper review if/when you're ready, just tinkering with some Dynamic Gallery stuff in the meantime)

[ramonjd]

Thanks, much appreciated!

I didn't want to monopolize your time too early, so I appreciate the thoughtful feedback.

I'll keep this one simmering and see if I can smooth the edges around those points you mentioned.

🍺

[andrewserong]

Cheers! I think the smooth scaling one is likely going to be a challenge. In most non-zoomed-in cases it'll look much more pleasing when it's smoothed. It's only really when you're deep into per-pixel cropping that you'd want it nearest neighbor instead of bilinear 🤔

In any case, thanks for digging in, with each of these steps the cropper is feeling more and more polished 👍

[ramonjd]

I've pulled the nearest-neighbour fix (image-rendering: pixelated) into this PR in 93761b3

The other two I'm going to document for follow-up investigations:

• Pixel-snapping handles: the one that actually changes which pixels you get. Probably want to gate it on "zoomed past ~1:1" so it doesn't make framing feel notchy on large images where a source pixel is sub-pixel on screen.
• View at actual size: this is really the thin end of a viewport-zoom model (fit / fill / 100%, and one day, your navigator 😄?). The auto-magnification becomes the default rather than the only option.

As mentioned, no rush to review on this.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

[ramonjd]

This is really the heart of things here.

• viewScaleRest: the magnification that makes the at-rest crop fill ~80% of the canvas, derived live from cropRect.
• viewScale: frozen at its pre-grab value during a resize (so grabbing a handle doesn't reset the zoom and the scene doesn't re-zoom under the cursor).
• scaledVisualSize = visualSize × viewScale: the magnified footprint. This is the single value threaded into everything downstream so the whole scene scales together.

[ramonjd]

minCropSize has been refactored to use the new viewScale so the adaptive floor accounts for the magnification.

[ramonjd]

This bit ensures the magnification happens in one transform instead of "settle, then jump"

[ramonjd]

The other two I'm going to document for follow-up investigations:

A couple more:

• Extend outward gain to locked-ratio paths: Square/Original/fixed-ratio currently keep the slow drag-out. Apply the same outward amplification to the locked paths.
• Tune the constants (eyeball it): SETTLE_TARGET_CANVAS_FILL 0.8, MAX_VIEW_SCALE 8, RESIZE_OUTWARD_GAIN 2, MIN_CROP_SCREEN_PX 44.

[ramonjd]

Fuzz testing results on this branch

## Fuzz / property-based testing report

The crop canvas-fill magnification logic was battle-tested locally with a property-based fuzz harness targeting the pure functions introduced/touched by this PR. The harness generates large numbers of randomized inputs and asserts
invariants rather than fixed expected values.

> Scope: pure core functions only. The harness is local tooling and is **not**
> part of this PR's committed changes. No core source was modified for testing.

### What was fuzzed

| Function | Why it's risky | Suites |
| --- | --- | --- |
| `getViewScale` | Nonlinear clamp; must stay finite and bounded for hostile input | valid inputs, non-finite/degenerate |
| `restrictCropGrowth` | Bisection that assumes coverage-zoom monotonicity; wired into every interactive resize | outward, corner/diagonal, monotonicity, shrink passthrough, multi-frame drag, baseline comparison |
| `computeFreeResizeRect` (`outwardGain`) | Per-edge amplification on a hot path | outward gain, bounds + `minCropSize` across all 8 handles |

### Invariants asserted

- **`getViewScale`** — result is finite and within `[1, maxScale]`; equals
  `min(maxScale, max(1, k))`; when magnifying (not clamped) the binding axis
  reaches `targetFill × canvas`; any non-finite/zero input returns `1`.
- **`restrictCropGrowth`** — result is finite; coverable at the current zoom
  (`getMinZoomForCover ≤ zoom`); lies on the `prev→next` segment; edges that
  did not move are preserved; `next` is returned unchanged when already
  coverable or when shrinking; coverage zoom is **monotonic non-decreasing**
  along `prev→next` (the property the bisection relies on).
- **`computeFreeResizeRect`** — outward gain amplifies only the crop-growing
  direction (inward stays 1:1); result respects bounds and never collapses
  below `minCropSize`, for all edge and corner handles.

### Results

Run: 50,000 iterations per case (~425k simulated drag frames across the
multi-frame suites). Node 20, local. **10/10 suites pass, 0 failures.**

| Suite | Target | Status |
| --- | --- | --- |
| valid inputs | `getViewScale` | ✅ PASS |
| non-finite / degenerate inputs | `getViewScale` | ✅ PASS |
| outward resize steps | `restrictCropGrowth` | ✅ PASS |
| corner (diagonal) resize steps | `restrictCropGrowth` | ✅ PASS |
| coverage zoom monotonic along prev→next | `restrictCropGrowth` | ✅ PASS |
| shrink passthrough | `restrictCropGrowth` | ✅ PASS |
| simulated multi-frame pointer drag | `restrictCropGrowth` | ✅ PASS |
| baseline comparison (startRect vs committed) | `restrictCropGrowth` | ✅ PASS |
| outward gain ≥ 1 | `computeFreeResizeRect` | ✅ PASS |
| bounds + minCropSize, all handles | `computeFreeResizeRect` | ✅ PASS |

Total wall time ≈ 258 s.

### Key findings

1. **Monotonicity holds.** Coverage zoom is non-decreasing along `prev→next`
   across all tested rotations and aspect ratios, so the bisection in
   `restrictCropGrowth` is sound. This was the highest-risk unverified
   assumption and it survives 50k randomized seeds.

2. **No NaN/∞ leaks, no out-of-bounds, no sub-floor crops** were found, across
   all handles and hostile inputs.

3. **Baseline divergence: 23.1%** (98,012 / 424,984 frames). Clamping each
   drag frame against the last committed rect (production behaviour) versus the
   pointer-down snapshot produces different geometry ~1 frame in 4 — but **both
   remain coverable**. This is empirical evidence that the coverage invariant
   does not distinguish the two; the difference is purely in per-frame handle
   tracking. (An experiment using the snapshot baseline was tried and reverted
   because it made the handle visibly slip from the cursor during drag — a
   tracking/animation concern that property tests correctly do not flag.)

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

This is testing really well for me! I think the current shape of this PR is in a good place: it helps us for the really small crops to see the crop area more explicitly, while keeping the overall feel of using the drag handles etc just the same as on trunk. In short: this feels like a good iterative step to me 👍

Interacting with fine-grained rotation, crop sizes of various different aspect ratios etc felt much the same on this branch as on trunk doing common tasks.

The only thing that came up from running through this PR with Claude was a potential test gap between when the transform string is created and the scale being used. Not sure how legit this is, but it sounded like there's a potential test gap. Sharing the lines of code below, but apologies if this is a red herring!

Line 526 deliberately uses the unscaled visualSize and relies on the scale(viewScale) on line 721 to magnify it. That coupling isn't
documented and isn't exercised unless the image is panned. Worth a comment on 526 pointing at 721, and a test that pans a magnified crop —
otherwise a future "consistency" cleanup silently double-applies the magnification.

gutenberg/packages/media-editor/src/image-editor/react/components/cropper.tsx

Line 526 in e4d8b83

const transformString = useTransformStyle( state, visualSize );

gutenberg/packages/media-editor/src/image-editor/react/components/cropper.tsx

Line 721 in e4d8b83

transform: `scale(${ viewScale }) ${ transformString }`,

---

Otherwise, all looking good to me! 🚀

[andrewserong]

Not a blocker at all, but something we might want to play around with (or get a feel for) is at what point beyond a displayScale of 1 it feels like you want precise pixel-based control, and at which point does it look better smoothed. I.e. if you have an image slightly rotated and so the scale might be slightly more than 1, versus when you're really zoomed and doing precise pixel-based cropping.

(1 feels fine to me for now, just mentioning that it might be something to continue playing around with)

[ramonjd]

Helpful to note this, thanks. Something to test maybe in #79139

[ramonjd]

but it sounded like there's a potential test gap

Tests added! Thanks again for testing this one.