ramonjd · Sep 30, 2026 · Sep 27, 2026 · Sep 29, 2026 · Sep 30, 2026 · andrewserong
diff --git a/packages/media-editor/src/components/media-editor-canvas/index.tsx b/packages/media-editor/src/components/media-editor-canvas/index.tsx
@@ -42,10 +42,10 @@ export default function MediaEditorCanvas( {
 	disabled = false,
 }: MediaEditorCanvasProps ) {
 	const { media } = useMediaEditorContext();
-	const controller = useMediaEditor();
-	const { aspectRatioValue } = controller.cropOptions;
-	const cropperImage = controller.state.image;
-	const { beginGesture, endGesture, setImage } = controller;
+	const session = useMediaEditor();
+	const { aspectRatioValue } = session.cropOptions;
+	const cropperImage = session.cropper.state.image;
+	const { beginGesture, endGesture, setSourceImage } = session;
 
 	// Tracks whether the image pixels have actually loaded. The cropper's
 	// geometry is driven by the known media dimensions, so its handles and
@@ -89,12 +89,12 @@ export default function MediaEditorCanvas( {
 		) {
 			return;
 		}
-		setImage( {
+		setSourceImage( {
 			src: mediaUrl,
 			naturalWidth: mediaWidth,
 			naturalHeight: mediaHeight,
 		} );
 setImage( { 
 	src, 
 	naturalWidth: size.width, 
 	naturalHeight: size.height, 
 } ); 
 setImage( { 
 	src, 
 	naturalWidth: size.width, 
 	naturalHeight: size.height, 
 } ); 
-	}, [ cropperImage, mediaUrl, mediaWidth, mediaHeight, setImage ] );
+	}, [ cropperImage, mediaUrl, mediaWidth, mediaHeight, setSourceImage ] );
 
 	const isImage = mediaType.type === 'image';
 
@@ -159,7 +159,7 @@ export default function MediaEditorCanvas( {
 			>
 				<Cropper
 					src={ mediaUrl }
-					controller={ controller }
+					controller={ session.cropper }
 					aspectRatio={ aspectRatio }
 					freeformCrop
 					showGrid="interactive"

diff --git a/packages/media-editor/src/components/media-editor-fine-rotation/index.tsx b/packages/media-editor/src/components/media-editor-fine-rotation/index.tsx
@@ -28,7 +28,7 @@ export default function MediaEditorFineRotation( {
 	onPlacementControlInteraction,
 	disabled = false,
 }: MediaEditorFineRotationProps ) {
-	const { state, setRotation } = useMediaEditor();
+	const { state, setRotation } = useMediaEditor().cropper;
 	// `commitOnKeyUp: false` lets rapid arrow-key adjustments coalesce
 	// into one undo entry via the gesture idle window. Pointer-up still
 	// closes pointer drags immediately.

diff --git a/packages/media-editor/src/components/media-editor-image-controls/index.tsx b/packages/media-editor/src/components/media-editor-image-controls/index.tsx
@@ -77,7 +77,7 @@ export default function MediaEditorImageControls( {
 	zoomFactor = DEFAULT_ZOOM_FACTOR,
 	disabled = false,
 }: MediaEditorImageControlsProps ) {
-	const { state, setFlip, snapRotate90, setZoom } = useMediaEditor();
+	const { state, setFlip, snapRotate90, setZoom } = useMediaEditor().cropper;
 	const { aspectRatioValue, setAspectRatioValue, aspectRatioOptions } =
 		useCropOptions( { aspectRatioPresets } );
 	const hasAspectRatioControl = ! withLabels && showAspectRatioControl;

diff --git a/packages/media-editor/src/components/media-editor-image-controls/test/index.jsdom.test.tsx b/packages/media-editor/src/components/media-editor-image-controls/test/index.jsdom.test.tsx
@@ -20,7 +20,10 @@ function setup(
 }
 
 function CurrentState() {
-	const { state, cropOptions } = useMediaEditor();
+	const {
+		cropper: { state },
+		cropOptions,
+	} = useMediaEditor();
 
 	return (
 		<>

diff --git a/packages/media-editor/src/components/media-editor/index.tsx b/packages/media-editor/src/components/media-editor/index.tsx
@@ -294,7 +294,7 @@ function HistoryActions() {
 	const { isImage, isUndoRedoDisabled, onReset, isWide, activePanel } =
 		useMediaEditorFrameContext();
 	const {
-		reset,
+		cropper: { reset },
 		isDirty,
 		hasUndo,
 		hasRedo,
@@ -435,7 +435,7 @@ function MediaEditorContent( {
 	noticesPortalElement,
 	shouldCloseOnEsc = false,
 }: MediaEditorProps ) {
-	const cropper = useMediaEditor();
+	const session = useMediaEditor();
 	// Width decides whether the settings panel docks beside the canvas or
 	// takes the whole body. It docks from `small` (600px): the modal is the
 	// viewport less a 16px margin either side, so a 320px panel and the
@@ -516,7 +516,7 @@ function MediaEditorContent( {
 		[ id ]
 	);
 
-	const hasChanges = cropper.isCropperDirty || hasEdits;
+	const hasChanges = session.hasOutputEdits || hasEdits;
 
 	const { clearEntityRecordEdits, editEntityRecord, invalidateResolution } =
 		useDispatch( coreStore );
@@ -602,7 +602,7 @@ function MediaEditorContent( {
 		resetCropOptions,
 	} = useCropOptions( { aspectRatioPresets } );
 	const { isSaving, save: saveMediaEditor } = useSaveMediaEditor( {
-		cropper,
+		session,
 		id,
 		isImage,
 		media,
@@ -656,9 +656,9 @@ function MediaEditorContent( {
 					return;
 				}
 				if ( isRedoShortcut ) {
-					cropper.redo();
+					session.redo();
 				} else {
-					cropper.undo();
+					session.undo();
 				}
 			}
 		}

diff --git a/packages/media-editor/src/components/media-editor/use-crop-options.ts b/packages/media-editor/src/components/media-editor/use-crop-options.ts
@@ -50,7 +50,7 @@ export function useCropOptions( {
 }: UseCropOptionsArgs = {} ): UseCropOptionsReturn {
 	const controller = useMediaEditor();
 	const { aspectRatioValue } = controller.cropOptions;
-	const cropperImage = controller.state.image;
+	const cropperImage = controller.cropper.state.image;
 
 	const aspectRatioOptions = useMemo(
 		() => getAspectRatioOptions( aspectRatioPresets ),

diff --git a/packages/media-editor/src/components/media-editor/use-save-media-editor.ts b/packages/media-editor/src/components/media-editor/use-save-media-editor.ts
@@ -5,7 +5,7 @@ import { useCallback, useState } from '@wordpress/element';
 import { __, sprintf } from '@wordpress/i18n';
 import { store as noticesStore } from '@wordpress/notices';
 import type { Media } from '../media-editor-provider';
-import type { MediaEditorController } from '../../state';
+import type { MediaEditorSession } from '../../state';
 import {
 	buildModifiers,
 	type Modifier,
@@ -37,7 +37,7 @@ export interface MediaEditorSaveResult {
 }
 
 interface UseSaveMediaEditorArgs {
-	cropper: MediaEditorController;
+	session: MediaEditorSession;
 	id: number;
 	isImage: boolean;
 	media?: Media | null;
@@ -49,13 +49,14 @@ interface UseSaveMediaEditorReturn {
 	save: () => Promise< void >;
 }
 
-function getCropModifiers( cropper: MediaEditorController ): Modifier[] {
-	if ( ! cropper.isCropperDirty || ! cropper.state.image ) {
+function getCropModifiers( session: MediaEditorSession ): Modifier[] {
+	const { state } = session.cropper;
+	if ( ! session.hasOutputEdits || ! state.image ) {
 		return [];
 	}
-	return buildModifiers( cropper.state, {
-		width: cropper.state.image.naturalWidth,
-		height: cropper.state.image.naturalHeight,
+	return buildModifiers( state, {
+		width: state.image.naturalWidth,
+		height: state.image.naturalHeight,
 	} );
 }
 
@@ -80,7 +81,7 @@ function getMetadataEdits(
 }
 
 export function useSaveMediaEditor( {
-	cropper,
+	session,
 	id,
 	isImage,
 	media,
@@ -100,7 +101,7 @@ export function useSaveMediaEditor( {
 		setIsSaving( true );
 		try {
 			let saved: Media | null | undefined;
-			const modifiers = getCropModifiers( cropper );
+			const modifiers = getCropModifiers( session );
 			const previous =
 				modifiers.length > 0 && media
 					? {
@@ -155,7 +156,7 @@ export function useSaveMediaEditor( {
 
 			if ( next && next.id ) {
 				if ( next.id === id ) {
-					cropper.reset();
+					session.cropper.reset();
 				}
 				onSaved?.( {
 					id: next.id,
@@ -193,7 +194,6 @@ export function useSaveMediaEditor( {
 	}, [
 		clearEntityRecordEdits,
 		createErrorNotice,
-		cropper,
 		id,
 		isImage,
 		media,
@@ -202,6 +202,7 @@ export function useSaveMediaEditor( {
 		registry,
 		removeAllNotices,
 		saveEditedEntityRecord,
+		session,
 	] );
 
 	return { isSaving, save };

diff --git a/packages/media-editor/src/image-editor/docs/architecture.md b/packages/media-editor/src/image-editor/docs/architecture.md
@@ -8,7 +8,7 @@
 | React cropper | `src/image-editor/react/` | DOM measurement, interaction hooks, overlays, stencil rendering, and the pure `useCropperReducer` hook. |
 | Media editor state | `src/state/` | Composite state for the media editor: cropper state, crop options, undo/redo, and gesture boundaries. |
 
-The cropper layer does not own editor history. History belongs to the composite media editor controller because sidebar controls and cropper gestures need one shared undo stack.
+The cropper layer does not own editor history. History belongs to the media editor session because sidebar controls and cropper gestures need one shared undo stack.
 
 ## Coordinate Spaces
 
@@ -37,6 +37,10 @@ The render path uses focused calculations for CSS transforms, stencil placement,
 
 The core reducer is framework-agnostic and serializable. React and media-editor layers add DOM measurement, gestures, undo/redo, save behavior, and UI state.
 
+### Session
+
+`useMediaEditorState()` returns the media editor session. The session owns the source image, every editing slice, the shared undo/redo history, gesture boundaries, and whether the edits change the saved image (`hasOutputEdits`). The cropper is one participant: `session.cropper` is a geometry-only `CropperController` that a `<Cropper>` takes via its `controller` prop, and its `isDirty` covers geometry alone. Replacing the source image (`setSourceImage`, which the cropper's `setImage` also calls) starts a fresh session with default geometry and crop options, a clean baseline, and no history. Save code asks the session, not the cropper, whether image output needs saving.
+
 ### Viewport
 
 Viewport pan/zoom lets the user inspect or follow the crop area without changing the crop output. It is not part of export and should not create undo entries.
@@ -52,4 +56,4 @@ These APIs let code inside `@wordpress/media-editor` compose the cropper. They a
 | Crop data for REST requests | `getSourceRegion()` and `getSourceRegionPercent()`. |
 | Canvas export | `exportCroppedImage()` or `applyToCanvas()`. |
 | Shared cropper state across internal components | `CropperProvider` / `useCropper()`. |
-| Media editor history | `useMediaEditorState()` composite controller. |
+| Media editor history | `useMediaEditorState()` session. |
diff --git a/packages/media-editor/src/image-editor/docs/recipes.md b/packages/media-editor/src/image-editor/docs/recipes.md
@@ -76,29 +76,29 @@ function CropperPanel( { src }: { src: string } ) {
 }
 ```
 
-## Use the Media Editor Composite Controller
+## Use the Media Editor Session
 
-Use the media editor controller when cropper state must share history with controls such as aspect ratio.
+Use the media editor session when cropper state must share history with controls such as aspect ratio. The session owns history and gesture boundaries; pass its `cropper` controller to `<Cropper>`.
 
 ```tsx
 import { resolveAspectRatio, useMediaEditor } from '../../state';
 import { Cropper } from '../image-editor';
 
 function MediaEditorCanvas( { src }: { src: string } ) {
-	const controller = useMediaEditor();
+	const session = useMediaEditor();
 	const aspectRatio = resolveAspectRatio(
-		controller.cropOptions.aspectRatioValue,
-		controller.state.image
+		session.cropOptions.aspectRatioValue,
+		session.cropper.state.image
 	);
 
 	return (
 		<Cropper
 			src={ src }
-			controller={ controller }
+			controller={ session.cropper }
 			aspectRatio={ aspectRatio }
 			freeformCrop
-			onGestureStart={ controller.beginGesture }
-			onGestureEnd={ controller.endGesture }
+			onGestureStart={ session.beginGesture }
+			onGestureEnd={ session.endGesture }
 		/>
 	);
 }

diff --git a/packages/media-editor/src/state/index.ts b/packages/media-editor/src/state/index.ts
@@ -2,7 +2,7 @@ export {
 	useMediaEditorState,
 	resolveAspectRatio,
 } from './use-media-editor-state';
-export type { MediaEditorController } from './use-media-editor-state';
+export type { MediaEditorSession } from './use-media-editor-state';
 export {
 	MediaEditorStateProvider,
 	useMediaEditor,

diff --git a/packages/media-editor/src/state/media-editor-state-provider.tsx b/packages/media-editor/src/state/media-editor-state-provider.tsx
@@ -2,11 +2,11 @@ import { createContext, useContext } from '@wordpress/element';
 import type { CropperState } from '../image-editor';
 import {
 	useMediaEditorState,
-	type MediaEditorController,
+	type MediaEditorSession,
 } from './use-media-editor-state';
 import type { CropOptionsSlice } from './types';
 
-const MediaEditorStateContext = createContext< MediaEditorController | null >(
+const MediaEditorStateContext = createContext< MediaEditorSession | null >(
 	null
 );
 
@@ -20,9 +20,9 @@ interface MediaEditorStateProviderProps {
 }
 
 /**
- * Provider that vends the composite media-editor controller via
- * context. Wrap the media editor in this so every consumer
- * (canvas, toolbar, sidebar) reads from the same store.
+ * Provider that vends the media editor session via context. Wrap
+ * the media editor in this so every consumer (canvas, toolbar,
+ * sidebar) reads from the same store.
  *
  * @param props
  * @param props.initialCropperState
@@ -47,12 +47,12 @@ export function MediaEditorStateProvider( {
 }
 
 /**
- * Consume the composite media-editor controller. Throws if used
+ * Consume the media editor session. Throws if used
  * outside a `<MediaEditorStateProvider>`.
  *
- * @return The composite controller.
+ * @return The media editor session.
  */
-export function useMediaEditor(): MediaEditorController {
+export function useMediaEditor(): MediaEditorSession {
 	const context = useContext( MediaEditorStateContext );
 	if ( ! context ) {
 		throw new Error(

diff --git a/packages/media-editor/src/state/test/use-media-editor-state.browser.test.tsx b/packages/media-editor/src/state/test/use-media-editor-state.browser.test.tsx
@@ -6,7 +6,7 @@ import { useEffect } from '@wordpress/element';
 import { Cropper } from '../../image-editor';
 import {
 	useMediaEditorState,
-	type MediaEditorController,
+	type MediaEditorSession,
 } from '../use-media-editor-state';
 // Browser Mode needs the package's real styles for layout and transitions.
 // eslint-disable-next-line @wordpress/no-non-module-stylesheet-imports
@@ -23,15 +23,15 @@ const IMAGE = {
 function CropperWithHistory( {
 	onController,
 }: {
-	onController: ( controller: MediaEditorController ) => void;
+	onController: ( controller: MediaEditorSession ) => void;
 } ) {
 	const controller = useMediaEditorState( { cropper: { image: IMAGE } } );
 	useEffect( () => onController( controller ), [ controller, onController ] );
 	return (
 		<div style={ { width: 648, height: 448 } }>
 			<Cropper
 				src={ IMAGE.src }
-				controller={ controller }
+				controller={ controller.cropper }
 				freeformCrop
 				onGestureStart={ controller.beginGesture }
 				onGestureEnd={ controller.endGesture }
@@ -42,8 +42,8 @@ function CropperWithHistory( {
 
 describe( 'useMediaEditorState with a Cropper', () => {
 	it( 'keeps redo steps after redoing a handle crop that turns on pixel snapping', async () => {
-		let controller!: MediaEditorController;
-		const onController = ( next: MediaEditorController ) => {
+		let controller!: MediaEditorSession;
+		const onController = ( next: MediaEditorSession ) => {
 			controller = next;
 		};
 		await render( <CropperWithHistory onController={ onController } /> );
@@ -61,11 +61,11 @@ describe( 'useMediaEditorState with a Cropper', () => {
 				'{/Shift}'
 		);
 		await waitFor( () =>
-			expect( controller.state.zoom ).toBeGreaterThan( 1 )
+			expect( controller.cropper.state.zoom ).toBeGreaterThan( 1 )
 		);
 
 		act( () =>
-			controller.setFlip( { horizontal: true, vertical: false } )
+			controller.cropper.setFlip( { horizontal: true, vertical: false } )
 		);
 
 		for ( let i = 0; i < 10 && controller.hasUndo; i++ ) {