Media editor: Add a session boundary above the cropper

[ramonjd]

What

The media editor controller becomes the editing session instead of extending CropperController.

The cropper is now a geometry-only sub-controller at session.cropper.

First step of #79175.

Why

The editor's state is a crop-related with extras bolted on (zoom etc). That works for crop, but for nothing else like non-geomentric changes to the image itself. For example:

• There is nowhere to check or save non-cropping history state. For example isCropperDirty returns the crop state, but other "edits" might be image-based, like filters. The state needs to cater for more than crop values.
• Related to the above: extensions need the same undo history, dirty state and save path as crop. They should attach to the session, not the cropper. See Media editor modal: state management for media editor extensions #79175 and Integrate media features and experiments with Gutenberg's experimental Media Editor ai#325

How

This PR just creates the boundary - it doesn't add anything else new.

• useMediaEditor() returns the session. Pass session.cropper to <Cropper>. session.cropper.isDirty covers geometry only.
• setSourceImage replaces setImage on the session: a different image resets geometry, crop options, baseline and history. session.cropper.setImage is the same function, since <Cropper> reports its loaded image through it.
• hasOutputEdits replaces isCropperDirty for Save enablement and the save hook. The save hook still builds the /edit modifiers.
• Architecture and recipe docs updated.

Notes for review

• setSourceImage duplicates the setImage change in Media editor: restore original image in modal #81805 on purpose, so this doesn't wait on it. Whichever lands second drops its copy.
• Private API only, so no changelog entry.

What's next

The next PR gives the media editor a place to keep edits other than cropping, such as a brightness level or a plugin’s filter.

Each edit will be stored by name alongside the crop.

Undo, redo and "unsaved changes" then treat them like any crop change.

Manual testing

No behavioural changes. There should be no regressions.

1. Insert an Image block, choose an image, and click "Edit image" in the block toolbar.
2. Rotate, flip, zoom and crop. Undo, redo and Reset should behave as on trunk, including with the keyboard shortcuts.
3. Save. The block should switch to the new, edited image.
4. Reopen the editor, change only the alt text, and save. No new image should be created.
5. With the "Media Editor (Route)" experiment enabled, open an image from the media library and repeat steps 2 and 3.

2026-09-29.17.36.00.mp4

Use of AI

AI generated code while I harassed and guided. Output reviewed by me.

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: +54 B (0%)

Total Size: 8.25 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	616 kB	+54 B (+0.01%)

_{4b24cb4 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	45852a3	trunk	% Change
timeToFirstByte	57.95 ms +12.68% -4.75%	57.1 ms +10.6% -3.42%	1.49%
largestContentfulPaint	100 ms +6% -4%	96 ms +2.08% -8.33%	4.17%
lcpMinusTtfb	42.15 ms +7.12% -17.67%	34.5 ms +17.83% -5.22%	22.17%
wpBeforeTemplate	29.54 ms +18.28% -5.55%	28.11 ms +18.89% -2.13%	5.09%
wpTemplate	24.78 ms +4.64% -5.29%	24.14 ms +5.14% -2.9%	2.65%
wpTotal	54.05 ms +12.6% -4.26%	53.48 ms +10.08% -3.78%	1.07%
wpMemoryUsage	7.62 MB +0% -0%	7.59 MB +0% -0%	0.46%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	45852a3	trunk	% Change
timeToFirstByte	47.55 ms +6.83% -1.58%	46.8 ms +5.02% -1.39%	1.6%
largestContentfulPaint	104 ms +1.92% -3.85%	100 ms +4% -0%	4%
lcpMinusTtfb	54 ms +5.65% -1.39%	53.8 ms +1.21% -1.77%	0.37%
wpBeforeTemplate	26.38 ms +6.86% -1.33%	25.74 ms +1.79% -1.44%	2.49%
wpTemplate	17.9 ms +3.58% -0.89%	17.88 ms +1.29% -1.06%	0.11%
wpTotal	44.66 ms +6.67% -1.86%	43.82 ms +4.66% -1.55%	1.92%
wpMemoryUsage	6.25 MB +0% -0%	6.20 MB +0% -0%	0.71%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	45852a3	trunk	% Change
mediaProcessingJpeg	397.56 ms +3.32% -1.54%	392.67 ms +0.72% -0.17%	1.25%
mediaProcessingAvif	6064.31 ms +0.1% -0.15%	6039.45 ms +0.06% -0.25%	0.41%
mediaProcessingJpegToAvif	4182.18 ms +0.13% -0.1%	4162.57 ms +0.2% -0.15%	0.47%

media-upload

Metric	45852a3	trunk	% Change
jpegUploadProcessing	1693.76 ms +15.65% -16.5%	1420.55 ms +0.76% -0.61%	19.23%
pngUploadProcessing	191.96 ms +10.22% -8.57%	173.68 ms +29.13% -2.04%	10.53%
largeJpegUploadProcessing	1408.85 ms +0.51% -0.98%	1409.59 ms +0.85% -0.74%	-0.05%
multipleImageUploadProcessing	1572.71 ms +0.53% -1.28%	1579.67 ms +9% -1.78%	-0.44%

post-editor

Metric	45852a3	trunk	% Change
serverResponse	419.07 ms +2.32% -7.04%	434.63 ms +2.21% -2.65%	-3.58%
firstPaint	221.46 ms +31.86% -7.09%	227.03 ms +10.65% -15.41%	-2.45%
domContentLoaded	1028.52 ms +0.93% -0.88%	1034.62 ms +0.4% -0.48%	-0.59%
loaded	1029.7 ms +0.92% -0.88%	1035.86 ms +0.4% -0.5%	-0.59%
firstContentfulPaint	425.84 ms +1.02% -2.83%	426.92 ms +0.92% -0.64%	-0.25%
firstBlock	3044.85 ms +2.08% -0.95%	3026.39 ms +1.37% -1.04%	0.61%
type	17.14 ms +6.01% -3.38%	17.6 ms +1.42% -4.49%	-2.61%
typeWithoutInspector	15.86 ms +10.53% -2.4%	17.13 ms +4.79% -3.21%	-7.41%
typeWithTopToolbar	22.99 ms +4.44% -6%	23.19 ms +8.84% -9.57%	-0.86%
typeContainer	8.26 ms +13.2% -8.72%	8.24 ms +8.62% -11.89%	0.24%
focus	69.01 ms +17.43% -8.11%	65.52 ms +10.13% -1.57%	5.33%
firstFocus	185.94 ms +0% -0%	192.84 ms +0% -0%	-3.58%
selectAll	448.96 ms +2.96% -2.09%	482.92 ms +4.44% -5.55%	-7.03%
listViewOpen	61.94 ms +5.57% -4.07%	60.32 ms +6.83% -8.41%	2.69%
inserterOpen	21.51 ms +19.34% -10%	22.38 ms +15.37% -5.76%	-3.89%
inserterHover	2.14 ms +13.55% -7.48%	2.16 ms +13.43% -5.09%	-0.93%
inserterSearch	7.7 ms +10.52% -1.69%	8.98 ms +9.58% -14.92%	-14.25%
loadPatterns	684.16 ms +5.22% -3.01%	695.9 ms +4.98% -4.67%	-1.69%
wpTotal	409.64 ms +2.11% -7.21%	425.13 ms +2.24% -2.74%	-3.64%
wpMemoryUsage	13.16 MB +0% -0%	13.13 MB +0% -0%	0.28%
wpDbQueries	54 +0% -1.85%	54 +0% -1.85%	0%

site-editor

Metric	45852a3	trunk	% Change
serverResponse	418.76 ms +1.45% -0.97%	409.76 ms +4.2% -1.44%	2.2%
firstPaint	243.8 ms +7.26% -17.27%	255.76 ms +13.48% -10.74%	-4.68%
domContentLoaded	1079.4 ms +1.72% -0.43%	1089.75 ms +0.7% -0.57%	-0.95%
loaded	1080.51 ms +1.71% -0.42%	1090.87 ms +0.72% -0.57%	-0.95%
firstContentfulPaint	428.67 ms +1.02% -1.51%	433.8 ms +1.03% -2.77%	-1.18%
firstBlock	3872.15 ms +0.21% -0.6%	3899.73 ms +0.87% -0.55%	-0.71%
type	17.52 ms +5.94% -5.14%	17.47 ms +3.66% -2.18%	0.29%
navigate	115.98 ms +11.14% -1.55%	106.01 ms +11.44% -0.91%	9.4%
loadPatterns	1301.72 ms +6.98% -2.69%	1377.34 ms +10.03% -6.98%	-5.49%
loadPages	1052.57 ms +14.02% -1.13%	1045.24 ms +2.3% -0.57%	0.7%
wpTotal	409.47 ms +1.54% -0.96%	400.4 ms +4.29% -1.44%	2.27%
wpMemoryUsage	12.14 MB +0% -0%	12.11 MB +0% -0%	0.3%
wpDbQueries	43.5 +1.15% -1.15%	43.5 +1.15% -1.15%	0%

_{4b24cb4 Run}

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[andrewserong]

Just left a few nitpicky questions/comments, but nothing blocking! (The block editor media editor modal and route-based experiment are both testing well for me).

Overall I like this idea, and session feels like a clearer name / container to me, and I like the hasOutputEdits name over isDirty for the overall state, too 👍

Thanks for thinking through how this'll work for consumers!

[andrewserong]

Just wondering, if we're building the initial media editor state whenever a new image is set, does this mean that the existing initialCropperState behaviour isn't really needed anymore? Or is that original/default state still useful 🤔

[ramonjd]

Hmm, yeah... Only tests use it today.

I think it's fine to leave, but it might confuse. I'll see if I can just define a test fixture and be done with it.

[ramonjd]

Actually, I'll do that in a follow up. Touches a few more files than I expected. Would be just a clean up PR after this one.

[ramonjd]

#83893

[andrewserong]

Please forgive me if I'm way off with this comment, I may very well have been led astray looking through the code with Claude as my assistant here. But! We call setSourceImage here in this useEffect which now also resets state. But over in cropper.tsx we also set the image when the image loads here:

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

Lines 707 to 711 in 186dfe5

	setImage( {
	src,
	naturalWidth: size.width,
	naturalHeight: size.height,
	} );

Previously, my hunch is that setting the image twice was effectively a no-op, whereas now this useEffect could potentially reset state. Is that an issue? I suspect not because we show a loading indicator during load, but just thought I'd mention it in case we want to make sure setSourceImage only fires once 🤔

[ramonjd]

Not way off. I think the second call still is a no-op.

I guess there's a slight risk. It'll reset if the stored width and height don’t match the file’s. So maybe in the case where a user who rotates or picks out a ratio in the fraction of a second before the file's pixels are loaded.

I think the does not clear history when the same image is reported again test covers the general issue.

There's a follow up planned though.

Once the editor supports edits that replace the pixels, e.g., AI, the cropper will have to ignore each "new image" edit since that'd reset everything.

The fix later is for Cropper’s load handler to report the pixel size rather than set the image.

It's on the list over at #79175: "<Cropper> currently treats a new src as a new image."

Does that answer the question? I myself jumped down the rabbit hole!

[andrewserong]

Yes, I think that answers the question, thanks! Sounds like something we don't need to worry about for now 🙂