[ramonjd]

What

This PR introduces a new hook useMediaEditorEdit( name, defaultValue ), which is a shortcut for a panel that owns one named edit.

So, think of a plugin that adds a Media Editor panel to apply image filters.

It's a baby step towards a public API for the image editor.

Fourth step of #79175, after #84591.

Why

Panels drive the editor through the session, useMediaEditor(): the cropper controller, crop options, edits, the source image, reset and history. That is the interface plugins get, so a plugin can ship its own crop tools or load new pixels and the canvas follows.

Core keeps what lives outside the session: the canvas component, the modal shell, Save and Cancel, shortcuts, notices, persistence, and the undo stacks themselves.

Within that, most panels will own a single value, a slider amount or a filter preset, and every one of them would write the same two lines: read session.edits[ name ] ?? default, and on change decide whether to store the value or remove the edit. This hook is that convenience. It also holds the one rule we kept out of the engine in #83899: the session only knows an edit that is set, so the default lives with the panel. When a panel sets a value equal in content to its default, the hook removes the edit rather than storing it, so the session reads as clean and no undo entry is spent on a default.

It is not a fence. A panel that needs more than its own value, an AI tool that also crops to the subject it found, say, uses the session directly alongside this hook.

What changed

• New state/use-media-editor-edit.ts, exported from the package's state barrel. Not on privateApis yet; nothing outside the package needs it until panels register.
• A sentence in architecture.md.

Nothing in production calls it, so there is no visible change.

Tests

Four cases in a new use-media-editor-edit.jsdom.test.ts: the default is reported while the edit is not set; setValue records the value and the session is dirty; setting a value equal to the default removes the edit and the session is clean; changes inside a gesture make one undo entry.

Manual testing

No behaviour change. Open the media editor from an Image block and confirm crop, undo, redo and Reset behave as on trunk.

[github-actions]

🤖 PR meta 🤖

🏷️ Labels

This pull request needs exactly one label indicating its type, and has 0.

• Required: any label starting with [Type].
• Found: none.

Read more about Type labels in Gutenberg. If you cannot add labels yourself, a reviewer can do it for you.

📦 Bundle size

Size Change: 0 B

Total Size: 8.64 MB

_{48c84ed Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	f6de5e6	trunk	% Change
timeToFirstByte	42.6 ms +4.93% -3.05%	42.25 ms +2.6% -2.37%	0.83%
largestContentfulPaint	72 ms +11.11% -0%	72 ms +8.33% -5.56%	0%
lcpMinusTtfb	29.95 ms +18.2% -3.34%	28.95 ms +22.63% -4.32%	3.45%
wpBeforeTemplate	21.45 ms +10.07% -1.21%	21.01 ms +4.43% -1.14%	2.09%
wpTemplate	17.38 ms +5.87% -6.04%	17.23 ms +5.17% -4.93%	0.87%
wpTotal	38.91 ms +5.83% -2.72%	38.83 ms +2.45% -2.42%	0.21%
wpMemoryUsage	7.59 MB +0% -0%	7.55 MB +0% -0%	0.45%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	f6de5e6	trunk	% Change
timeToFirstByte	35.55 ms +3.8% -2.11%	31.45 ms +4.93% -1.91%	13.04%
largestContentfulPaint	84 ms +0% -4.76%	72 ms +0% -0%	16.67%
lcpMinusTtfb	46.9 ms +4.26% -2.99%	40.25 ms +1.74% -4.22%	16.52%
wpBeforeTemplate	18.87 ms +5.78% -1.06%	18.7 ms +6.04% -1.71%	0.91%
wpTemplate	13.37 ms +4.64% -2.39%	10.03 ms +2.69% -2.09%	33.3%
wpTotal	32.52 ms +4.61% -1.97%	28.78 ms +5.07% -1.88%	13%
wpMemoryUsage	6.25 MB +0% -0%	6.10 MB +0% -0%	2.39%
wpDbQueries	14 +0% -0%	10 +0% -0%	40%

media-processing

Metric	f6de5e6	trunk	% Change
mediaProcessingJpeg	346.32 ms +2.78% -1.54%	336.7 ms +1.66% -0.43%	2.86%
mediaProcessingAvif	4945.49 ms +0.37% -0.68%	4903.6 ms +0.26% -0.14%	0.85%
mediaProcessingJpegToAvif	3364.65 ms +0.37% -0.33%	3333.84 ms +0.39% -0.44%	0.92%

media-upload

Metric	f6de5e6	trunk	% Change
jpegUploadProcessing	1410.2 ms +1.32% -0.65%	1402.46 ms +0.79% -0.55%	0.55%
pngUploadProcessing	187.55 ms +2.46% -1.59%	191.79 ms +1.11% -1.06%	-2.21%
largeJpegUploadProcessing	1398.2 ms +0.77% -0.16%	1404.12 ms +0.68% -0.41%	-0.42%
multipleImageUploadProcessing	1517.26 ms +0.31% -1.27%	1483.63 ms +0.56% -0.58%	2.27%

post-editor

Metric	f6de5e6	trunk	% Change
serverResponse	235.91 ms +8.58% -4.68%	250.52 ms +5.13% -6.08%	-5.83%
firstPaint	224.09 ms +43.47% -11.88%	193.39 ms +69.78% -20.73%	15.87%
domContentLoaded	691.84 ms +2.07% -1.48%	705.05 ms +4.51% -2.27%	-1.87%
loaded	692.99 ms +2.07% -1.48%	706.14 ms +4.5% -2.25%	-1.86%
firstContentfulPaint	324.34 ms +1.68% -4.66%	332.3 ms +1.96% -1.19%	-2.4%
firstBlock	2002.58 ms +2.21% -1.42%	2059.3 ms +0.74% -0.97%	-2.75%
type	13.1 ms +2.14% -1.22%	13.16 ms +3.19% -3.42%	-0.46%
typeWithoutInspector	12.79 ms +2.58% -4.77%	13.25 ms +4.38% -4.6%	-3.47%
typeWithTopToolbar	15.95 ms +3.76% -6.83%	16.75 ms +6.45% -2.75%	-4.78%
typeContainer	6.22 ms +1.61% -7.56%	6.36 ms +2.99% -5.66%	-2.2%
focus	69.63 ms +7.55% -3.72%	72.43 ms +2.54% -11.21%	-3.87%
firstFocus	135.49 ms +0% -0%	138.75 ms +0% -0%	-2.35%
selectAll	323.28 ms +11.29% -1.06%	352.49 ms +3.53% -0.33%	-8.29%
listViewOpen	46.47 ms +5.64% -8.35%	45.86 ms +4.06% -5.91%	1.33%
inserterOpen	23.74 ms +17.78% -1.1%	27.16 ms +13.33% -6.22%	-12.59%
inserterHover	8.84 ms +3.05% -7.81%	8.72 ms +4.7% -5.73%	1.38%
inserterSearch	6.25 ms +6.88% -3.68%	6.44 ms +12.27% -11.65%	-2.95%
loadPatterns	421.71 ms +2.51% -1.96%	418.25 ms +4.1% -4.39%	0.83%
wpTotal	228.17 ms +8.51% -4.68%	243.12 ms +5.21% -6.3%	-6.15%
wpMemoryUsage	13.34 MB +0% -0%	13.30 MB +0% -0%	0.28%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	f6de5e6	trunk	% Change
serverResponse	380.24 ms +2.47% -1.76%	379.2 ms +1.21% -4.06%	0.27%
firstPaint	251.14 ms +77.81% -22.73%	248.77 ms +29.28% -18.89%	0.95%
domContentLoaded	1039.68 ms +2.97% -1.04%	1049.89 ms +0.56% -3.55%	-0.97%
loaded	1040.71 ms +2.97% -1.01%	1050.87 ms +0.57% -3.54%	-0.97%
firstContentfulPaint	451.89 ms +0.29% -4.21%	447.06 ms +1.6% -7.28%	1.08%
firstBlock	3863.85 ms +0.48% -2.3%	3811.16 ms +1.02% -0.98%	1.38%
type	16.54 ms +7.26% -3.45%	16.52 ms +2.42% -1.45%	0.12%
navigate	105.74 ms +15.68% -3.5%	103.1 ms +12.66% -2.01%	2.56%
loadPatterns	1117.29 ms +7.33% -6.69%	1087.58 ms +2.32% -4.34%	2.73%
loadPages	1027.05 ms +2.68% -1.62%	1007.65 ms +2.53% -2.37%	1.93%
wpTotal	369.63 ms +2.33% -1.95%	369.32 ms +1.1% -4.28%	0.08%
wpMemoryUsage	12.37 MB +0% -0%	12.35 MB +0% -0%	0.13%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{48c84ed Run}