@atlaskit/editor-plugin-media 12.4.1 → 12.5.0

package/dist/esm/nodeviews/nodeviewHelpers.js

@@ -0,0 +1,20 @@
+import { akEditorFullWidthLayoutWidth, akEditorWideLayoutWidth } from '@atlaskit/editor-shared-styles';
+var MIN_MEDIA_DISPLAY_WIDTH = 24;
+/**
+ * Computes the new mediaSingle display width that preserves the original display height
+ * when a media node is replaced with a file of a different aspect ratio, clamped to valid bounds.
+ *
+ * @param targetDisplayHeight - The display height to preserve (from the old image)
+ * @param newIntrinsicWidth - The new file's intrinsic pixel width
+ * @param newIntrinsicHeight - The new file's intrinsic pixel height
+ * @param layout - The mediaSingle layout (affects max width)
+ * @param lineLength - The editor content column width in pixels
+ */
+export var computeReplacementDisplayWidth = function computeReplacementDisplayWidth(targetDisplayHeight, newIntrinsicWidth, newIntrinsicHeight, layout, lineLength) {
+  if (newIntrinsicHeight <= 0) {
+    return MIN_MEDIA_DISPLAY_WIDTH;
+  }
+  var unclamped = targetDisplayHeight * (newIntrinsicWidth / newIntrinsicHeight);
+  var maxWidth = layout === 'full-width' ? akEditorFullWidthLayoutWidth : layout === 'wide' ? akEditorWideLayoutWidth : lineLength;
+  return Math.max(MIN_MEDIA_DISPLAY_WIDTH, Math.min(unclamped, maxWidth));
+};

package/dist/esm/pm-plugins/main.js

@@ -13,6 +13,7 @@ import React from 'react';
 import { RawIntlProvider } from 'react-intl';
 // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
 import uuid from 'uuid';
+import { SetAttrsStep } from '@atlaskit/adf-schema/steps';
 import { ACTION, ACTION_SUBJECT, ACTION_SUBJECT_ID, EVENT_TYPE, INPUT_METHOD } from '@atlaskit/editor-common/analytics';
 import { getBrowserInfo } from '@atlaskit/editor-common/browser';
 import { mediaInlineImagesEnabled } from '@atlaskit/editor-common/media-inline';
@@ -27,6 +28,7 @@ import { CellSelection } from '@atlaskit/editor-tables/cell-selection';
 import { isFileIdentifier } from '@atlaskit/media-client';
 import { getMediaFeatureFlag } from '@atlaskit/media-common';
 import { fg } from '@atlaskit/platform-feature-flags';
+import { createMediaNodeUpdater } from '../nodeviews/mediaNodeUpdater';
 // Ignored via go/ees005
 // eslint-disable-next-line import/no-namespace
 import * as helpers from '../pm-plugins/commands/helpers';
@@ -87,6 +89,15 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
     _defineProperty(this, "destroyed", false);
     _defineProperty(this, "removeOnCloseListener", function () {});
     _defineProperty(this, "onPopupToggleCallback", function () {});
+    // When non-null, holds the file ID of the media node being replaced. Used both as a
+    // flag (non-null = replace mode) and as a cross-check to ensure the correct node is
+    // updated if the selection moves between the picker opening and the file being picked.
+    _defineProperty(this, "replaceMediaFileId", null);
+    // The display height (in pixels) of the mediaSingle being replaced, computed at replace time
+    // from its display width and the old media node's intrinsic aspect ratio.
+    // Used by the nodeview to recompute display width from the new file's aspect ratio after
+    // dimensions are fetched, preserving visual height rather than visual width.
+    _defineProperty(this, "replaceMediaTargetDisplayHeight", null);
     _defineProperty(this, "identifierCount", new Map());
     // This is to enable mediaShallowCopySope to enable only shallow copying media referenced within the edtior
     // see: trackOutOfScopeIdentifier
@@ -122,7 +133,7 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
      * called when we insert a new file via the picker (connected via pickerfacade)
      */
     _defineProperty(this, "insertFile", function (mediaState, onMediaStateChanged, pickerType, insertMediaVia) {
-      var _this$pluginInjection, _mediaState$collectio, _this$pluginInjection2;
+      var _this$pluginInjection, _mediaState$collectio, _this$pluginInjection3;
       var state = _this.view.state;
       var editorAnalyticsAPI = (_this$pluginInjection = _this.pluginInjectionApi) === null || _this$pluginInjection === void 0 || (_this$pluginInjection = _this$pluginInjection.analytics) === null || _this$pluginInjection === void 0 ? void 0 : _this$pluginInjection.actions;
       var mediaStateWithContext = _objectSpread(_objectSpread({}, mediaState), {}, {
@@ -133,6 +144,19 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
         return;
       }
 
+      // If replace mode was set but the selection has moved away from a mediaSingle
+      // (e.g. the user cancelled the replace picker and then inserted media elsewhere),
+      // clear replace state so this insertion proceeds as a normal insert.
+      if (_this.replaceMediaFileId !== null) {
+        var _state$selection$node;
+        var mediaSingle = state.schema.nodes.mediaSingle;
+        var isStillOnTargetMedia = state.selection instanceof NodeSelection && state.selection.node.type === mediaSingle && ((_state$selection$node = state.selection.node.firstChild) === null || _state$selection$node === void 0 ? void 0 : _state$selection$node.attrs.id) === _this.replaceMediaFileId;
+        if (!isStillOnTargetMedia) {
+          _this.replaceMediaFileId = null;
+          _this.replaceMediaTargetDisplayHeight = null;
+        }
+      }
+
       // We need to dispatch the change to event dispatcher only for successful files
       if (mediaState.status !== 'error') {
         _this.updateAndDispatch({
@@ -145,13 +169,124 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
         });
         _this.uploadInProgressSubscriptionsNotified = true;
       }
+
+      // Replace mode: if a media node is being replaced, update its attrs in-place
+      // rather than inserting a new node. This preserves layout, width, and caption.
+      if (_this.replaceMediaFileId !== null) {
+        var _mediaState$fileMimeT, _mediaState$fileName, _mediaState$fileSize;
+        // Clear replace mode immediately so subsequent insertions behave normally
+        _this.replaceMediaFileId = null;
+        var currentState = _this.view.state;
+        var mediaSinglePos = currentState.selection.from;
+        var mediaPos = mediaSinglePos + 1;
+        var mediaNode = currentState.doc.nodeAt(mediaPos);
+        if (!mediaNode || mediaNode.type.name !== 'media') {
+          return;
+        }
+
+        // Build a single transaction that:
+        // 1. Updates the media child node attrs (new file identity + cleared dimensions)
+        // 2. Re-creates the NodeSelection so the toolbar picks up the fresh node
+        var tr = currentState.tr;
+        tr.step(new SetAttrsStep(mediaPos, {
+          id: mediaState.id,
+          collection: collection,
+          type: 'file',
+          __fileMimeType: (_mediaState$fileMimeT = mediaState.fileMimeType) !== null && _mediaState$fileMimeT !== void 0 ? _mediaState$fileMimeT : null,
+          __fileName: (_mediaState$fileName = mediaState.fileName) !== null && _mediaState$fileName !== void 0 ? _mediaState$fileName : null,
+          __fileSize: (_mediaState$fileSize = mediaState.fileSize) !== null && _mediaState$fileSize !== void 0 ? _mediaState$fileSize : null,
+          __mediaTraceId: null,
+          // Clear intrinsic dimensions — they'll be fetched once the file
+          // is processed and applied via updateDimensions in a single tx
+          // with the height-preserving mediaSingle width adjustment.
+          width: null,
+          height: null
+        }));
+        // Re-create the selection so the floating toolbar picks up
+        // the updated node and renders the full set of controls.
+        tr.setSelection(NodeSelection.create(tr.doc, mediaSinglePos));
+        tr.setMeta('scrollIntoView', false);
+        _this.view.dispatch(tr);
+
+        // Still register the state-change listener so upload completion is tracked
+        onMediaStateChanged(_this.handleMediaState);
+        var _isEndState = function _isEndState(state) {
+          return state.status && MEDIA_RESOLVED_STATES.includes(state.status);
+        };
+
+        // After the file finishes uploading/processing, trigger a dimension fetch.
+        // getRemoteDimensions may fail if called too early (isImageRepresentationReady
+        // returns false while processing), so we wait for the ready state first.
+        var triggerDimensionFetch = function triggerDimensionFetch() {
+          // Find the media node in the doc by id and create a temporary
+          // MediaNodeUpdater to fetch and apply dimensions
+          var editorState = _this.view.state;
+          var mediaSingleType = editorState.schema.nodes.mediaSingle;
+          var mediaChildNode = null;
+          editorState.doc.descendants(function (node) {
+            if (mediaChildNode) {
+              return false;
+            }
+            if (node.type === mediaSingleType) {
+              var child = node.firstChild;
+              if (child && child.attrs.id === mediaState.id) {
+                mediaChildNode = child;
+              }
+            }
+            return true;
+          });
+          if (mediaChildNode) {
+            var _this$pluginInjection2;
+            var updater = createMediaNodeUpdater({
+              view: _this.view,
+              mediaProvider: _this.mediaProvider ? Promise.resolve(_this.mediaProvider) : undefined,
+              contextIdentifierProvider: _this.contextIdentifierProvider ? Promise.resolve(_this.contextIdentifierProvider) : undefined,
+              node: mediaChildNode,
+              isMediaSingle: true,
+              lineLength: (_this$pluginInjection2 = _this.pluginInjectionApi) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.width) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.sharedState.currentState()) === null || _this$pluginInjection2 === void 0 ? void 0 : _this$pluginInjection2.lineLength
+            });
+            updater.getRemoteDimensions().then(function (dims) {
+              if (dims) {
+                updater.updateDimensions(dims);
+              }
+            }).catch(function () {
+              // Silently ignore — if dimensions can't be fetched (e.g. network error),
+              // the image will render at its current size without the height-preserving
+              // width adjustment. This is an acceptable degraded experience.
+            });
+          }
+        };
+        if (!_isEndState(mediaStateWithContext)) {
+          var uploadingPromise = new Promise(function (resolve) {
+            onMediaStateChanged(function (newState) {
+              if (_isEndState(newState)) {
+                resolve(newState);
+              }
+            });
+          });
+          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+            _this.updateAndDispatch({
+              allUploadsFinished: true
+            });
+            triggerDimensionFetch();
+          });
+        } else {
+          // File is already in a resolved state — fetch dimensions immediately
+          triggerDimensionFetch();
+        }
+        var _view = _this.view;
+        if (!_view.hasFocus()) {
+          _view.focus();
+        }
+        return;
+      }
       switch (getMediaNodeInsertionType(state, _this.mediaOptions, mediaStateWithContext.fileMimeType)) {
         case 'inline':
           insertMediaInlineNode(editorAnalyticsAPI)(_this.view, mediaStateWithContext, collection, _this.allowInlineImages, _this.getInputMethod(pickerType), insertMediaVia);
           break;
         case 'block':
           // read width state right before inserting to get up-to-date and define values
-          var widthPluginState = (_this$pluginInjection2 = _this.pluginInjectionApi) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.width) === null || _this$pluginInjection2 === void 0 ? void 0 : _this$pluginInjection2.sharedState.currentState();
+          var widthPluginState = (_this$pluginInjection3 = _this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.width) === null || _this$pluginInjection3 === void 0 ? void 0 : _this$pluginInjection3.sharedState.currentState();
           insertMediaSingleNode(_this.view, mediaStateWithContext, _this.getInputMethod(pickerType), collection, _this.mediaOptions && _this.mediaOptions.alignLeftOnInsert, widthPluginState, editorAnalyticsAPI, _this.onNodeInserted, insertMediaVia, _this.mediaOptions && _this.mediaOptions.allowPixelResizing);
           break;
         case 'group':
@@ -167,7 +302,7 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
         return state.status && MEDIA_RESOLVED_STATES.indexOf(state.status) !== -1;
       };
       if (!isEndState(mediaStateWithContext)) {
-        var uploadingPromise = new Promise(function (resolve) {
+        var _uploadingPromise = new Promise(function (resolve) {
           onMediaStateChanged(function (newState) {
             // When media item reaches its final state, remove listener and resolve
             if (isEndState(newState)) {
@@ -176,7 +311,7 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
           });
         });
         if (fg('platform_editor_media_disable_save_during_upload')) {
-          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+          _this.taskManager.addPendingTask(_uploadingPromise, mediaStateWithContext.id).then(function () {
             _this.updateAndDispatch({
               allUploadsFinished: true
             });
@@ -190,7 +325,7 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
             });
           });
         } else {
-          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+          _this.taskManager.addPendingTask(_uploadingPromise, mediaStateWithContext.id).then(function () {
             _this.updateAndDispatch({
               allUploadsFinished: true
             });
@@ -232,6 +367,64 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
       }
       _this.onPopupToggleCallback(true);
     });
+    /**
+     * Opens the media picker in "replace" mode. The next file selected/uploaded
+     * will replace the currently selected mediaSingle node's media child in-place,
+     * preserving layout, width, and caption.
+     *
+     * The display height is computed and stored so that after the new file's intrinsic
+     * dimensions are fetched, the mediaSingle display width can be adjusted to maintain
+     * visual height stability rather than width stability.
+     */
+    _defineProperty(this, "showMediaPickerForReplace", function () {
+      var _this$pluginInjection4, _this$pluginInjection5;
+      var state = _this.view.state;
+      var mediaSingle = state.schema.nodes.mediaSingle;
+      var selection = state.selection;
+
+      // Only activate replace mode when a mediaSingle is selected
+      if (!(selection instanceof NodeSelection) || selection.node.type !== mediaSingle) {
+        return;
+      }
+      var mediaSingleNode = selection.node;
+      var mediaNode = mediaSingleNode.firstChild;
+      if (!mediaNode) {
+        return;
+      }
+
+      // Store the current media node's id so insertFile can identify and replace it
+      _this.replaceMediaFileId = mediaNode.attrs.id;
+
+      // Compute and store the current display height so we can preserve it after
+      // the new file's intrinsic dimensions are known.
+      // displayHeight = displayWidth * (intrinsicHeight / intrinsicWidth)
+      var widthAttr = mediaSingleNode.attrs.width;
+      var widthType = mediaSingleNode.attrs.widthType;
+      var intrinsicWidth = mediaNode.attrs.width;
+      var intrinsicHeight = mediaNode.attrs.height;
+
+      // Resolve actual pixel display width from mediaSingle attrs.
+      var lineLength = (_this$pluginInjection4 = (_this$pluginInjection5 = _this.pluginInjectionApi) === null || _this$pluginInjection5 === void 0 || (_this$pluginInjection5 = _this$pluginInjection5.width) === null || _this$pluginInjection5 === void 0 || (_this$pluginInjection5 = _this$pluginInjection5.sharedState.currentState()) === null || _this$pluginInjection5 === void 0 ? void 0 : _this$pluginInjection5.lineLength) !== null && _this$pluginInjection4 !== void 0 ? _this$pluginInjection4 : 760;
+      var displayWidth = null;
+      if (widthAttr && widthType === 'pixel') {
+        displayWidth = widthAttr;
+      } else if (widthAttr) {
+        // Default widthType is 'percentage' — convert to pixels
+        displayWidth = widthAttr / 100 * lineLength;
+      } else if (intrinsicWidth) {
+        // No width set at all (never resized) — fall back to intrinsic width
+        displayWidth = intrinsicWidth;
+      }
+      if (displayWidth && intrinsicWidth && intrinsicHeight && intrinsicWidth > 0) {
+        _this.replaceMediaTargetDisplayHeight = displayWidth * (intrinsicHeight / intrinsicWidth);
+      } else {
+        // Can't compute display height — fall back to preserving width
+        _this.replaceMediaTargetDisplayHeight = null;
+      }
+
+      // Finally, show the media picker
+      _this.showMediaPicker();
+    });
     _defineProperty(this, "setBrowseFn", function (browseFn) {
       _this.openMediaPickerBrowser = browseFn;
     });
@@ -687,8 +880,8 @@ export var MediaPluginStateImplementation = /*#__PURE__*/function () {
   }, {
     key: "contextIdentifierProvider",
     get: function get() {
-      var _this$pluginInjection3;
-      return (_this$pluginInjection3 = this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.contextIdentifier) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.sharedState.currentState()) === null || _this$pluginInjection3 === void 0 ? void 0 : _this$pluginInjection3.contextIdentifierProvider;
+      var _this$pluginInjection6;
+      return (_this$pluginInjection6 = this.pluginInjectionApi) === null || _this$pluginInjection6 === void 0 || (_this$pluginInjection6 = _this$pluginInjection6.contextIdentifier) === null || _this$pluginInjection6 === void 0 || (_this$pluginInjection6 = _this$pluginInjection6.sharedState.currentState()) === null || _this$pluginInjection6 === void 0 ? void 0 : _this$pluginInjection6.contextIdentifierProvider;
     }
   }, {
     key: "selectLastAddedMediaNode",
@@ -923,9 +1116,9 @@ export var createPlugin = function createPlugin(_schema, options, getIntl, plugi
       return;
     },
     key: stateKey,
-    view: function view(_view) {
-      var pluginState = getMediaPluginState(_view.state);
-      pluginState.setView(_view);
+    view: function view(_view2) {
+      var pluginState = getMediaPluginState(_view2.state);
+      pluginState.setView(_view2);
       pluginState.updateElement();
       return {
         update: function update() {

package/dist/esm/ui/toolbar/index.js

@@ -23,6 +23,7 @@ import ImageFullscreenIcon from '@atlaskit/icon/core/image-fullscreen';
 import ImageInlineIcon from '@atlaskit/icon/core/image-inline';
 import MaximizeIcon from '@atlaskit/icon/core/maximize';
 import SmartLinkCardIcon from '@atlaskit/icon/core/smart-link-card';
+import UploadIcon from '@atlaskit/icon/core/upload';
 import { mediaFilmstripItemDOMSelector } from '@atlaskit/media-filmstrip';
 import { messages } from '@atlaskit/media-ui';
 import { fg } from '@atlaskit/platform-feature-flags';
@@ -883,6 +884,7 @@ export var floatingToolbar = function floatingToolbar(state, intl) {
   if (!mediaPluginState.isResizing && areToolbarFlagsEnabled(Boolean(pluginInjectionApi === null || pluginInjectionApi === void 0 ? void 0 : pluginInjectionApi.toolbar))) {
     var _pluginInjectionApi$a0, _pluginInjectionApi$a1, _pluginInjectionApi$a10;
     updateToFullHeightSeparator(items);
+    var showReplaceOption = !isViewOnly && mediaPluginState.allowsUploads && expValEquals('platform_editor_inline_media_replacement', 'isEnabled', true) && selectedNodeType === mediaSingle;
     var customOptions = [].concat(_toConsumableArray(getLinkingDropdownOptions(state, intl, mediaLinkingState, allowMediaInline && selectedNodeType && selectedNodeType === mediaInline, allowLinking, isViewOnly)), _toConsumableArray(getAltTextDropdownOption(state, intl.formatMessage, allowAltTextOnImages, selectedNodeType, pluginInjectionApi === null || pluginInjectionApi === void 0 || (_pluginInjectionApi$a0 = pluginInjectionApi.analytics) === null || _pluginInjectionApi$a0 === void 0 ? void 0 : _pluginInjectionApi$a0.actions)), _toConsumableArray(getResizeDropdownOption(options, state, intl.formatMessage, selectedNodeType)));
     if (customOptions.length) {
       customOptions.push({
@@ -901,7 +903,17 @@ export var floatingToolbar = function floatingToolbar(state, intl) {
       type: 'overflow-dropdown',
       id: 'media',
       testId: overflowDropdwonBtnTriggerTestId,
-      options: [].concat(_toConsumableArray(customOptions), [_objectSpread({
+      options: [].concat(_toConsumableArray(customOptions), _toConsumableArray(showReplaceOption ? [{
+        title: intl.formatMessage(mediaAndEmbedToolbarMessages.replaceMedia),
+        onClick: function onClick() {
+          mediaPluginState.showMediaPickerForReplace();
+          return true;
+        },
+        icon: /*#__PURE__*/React.createElement(UploadIcon, {
+          label: ""
+        }),
+        testId: 'media-replace-toolbar-button'
+      }] : []), [_objectSpread({
         title: intl === null || intl === void 0 ? void 0 : intl.formatMessage(commonMessages.copyToClipboard),
         onClick: function onClick() {
           var _pluginInjectionApi$c4, _pluginInjectionApi$f3;

package/dist/types/nodeviews/mediaNodeUpdater.d.ts

@@ -3,7 +3,7 @@ import type { ContextIdentifierProvider, MediaProvider } from '@atlaskit/editor-
 import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
 import type { EditorView } from '@atlaskit/editor-prosemirror/view';
 import { type MediaTraceContext } from '@atlaskit/media-common';
-import type { MediaOptions, MediaPluginState, getPosHandler as ProsemirrorGetPosHandler, SupportedMediaAttributes } from '../types';
+import type { getPosHandler as ProsemirrorGetPosHandler, MediaOptions, MediaPluginState, SupportedMediaAttributes } from '../types';
 type RemoteDimensions = {
     height: number;
     id: string;
@@ -13,6 +13,8 @@ export interface MediaNodeUpdaterProps {
     contextIdentifierProvider?: Promise<ContextIdentifierProvider>;
     dispatchAnalyticsEvent?: DispatchAnalyticsEvent;
     isMediaSingle: boolean;
+    /** Content column width in pixels, used to clamp display width on media replacement. */
+    lineLength?: number;
     mediaOptions?: MediaOptions;
     mediaProvider?: Promise<MediaProvider>;
     node: PMNode;

package/dist/types/nodeviews/nodeviewHelpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Computes the new mediaSingle display width that preserves the original display height
+ * when a media node is replaced with a file of a different aspect ratio, clamped to valid bounds.
+ *
+ * @param targetDisplayHeight - The display height to preserve (from the old image)
+ * @param newIntrinsicWidth - The new file's intrinsic pixel width
+ * @param newIntrinsicHeight - The new file's intrinsic pixel height
+ * @param layout - The mediaSingle layout (affects max width)
+ * @param lineLength - The editor content column width in pixels
+ */
+export declare const computeReplacementDisplayWidth: (targetDisplayHeight: number, newIntrinsicWidth: number, newIntrinsicHeight: number, layout: string, lineLength: number) => number;

package/dist/types/pm-plugins/main.d.ts

@@ -52,6 +52,8 @@ export declare class MediaPluginStateImplementation implements MediaPluginState
     private removeOnCloseListener;
     private openMediaPickerBrowser?;
     private onPopupToggleCallback;
+    replaceMediaFileId: string | null;
+    replaceMediaTargetDisplayHeight: number | null;
     private identifierCount;
     private outOfEditorScopeIdentifierMap;
     private taskManager;
@@ -88,6 +90,16 @@ export declare class MediaPluginStateImplementation implements MediaPluginState
     splitMediaGroup: () => boolean;
     onPopupPickerClose: () => void;
     showMediaPicker: () => void;
+    /**
+     * Opens the media picker in "replace" mode. The next file selected/uploaded
+     * will replace the currently selected mediaSingle node's media child in-place,
+     * preserving layout, width, and caption.
+     *
+     * The display height is computed and stored so that after the new file's intrinsic
+     * dimensions are fetched, the mediaSingle display width can be adjusted to maintain
+     * visual height stability rather than width stability.
+     */
+    showMediaPickerForReplace: () => void;
     setBrowseFn: (browseFn: () => void) => void;
     onPopupToggle: (onPopupToggleCallback: (isOpen: boolean) => void) => void;
     /**

package/dist/types/pm-plugins/types.d.ts

@@ -53,6 +53,8 @@ export interface MediaPluginState {
     pickerPromises: Array<Promise<PickerFacade>>;
     pickers: PickerFacade[];
     removeSelectedMediaContainer: () => boolean;
+    replaceMediaFileId: string | null;
+    replaceMediaTargetDisplayHeight: number | null;
     resizingWidth: number;
     selectedMediaContainerNode: () => PMNode | undefined;
     setBrowseFn: (browseFn: () => void) => void;
@@ -63,6 +65,7 @@ export interface MediaPluginState {
     showDropzone: boolean;
     showEditingDialog?: boolean;
     showMediaPicker: () => void;
+    showMediaPickerForReplace: () => void;
     splitMediaGroup: () => boolean;
     subscribeToUploadInProgressState: (fn: (isUploading: boolean) => void) => void;
     trackOutOfScopeIdentifier: (identifier: Identifier) => void;

package/dist/types-ts4.5/nodeviews/mediaNodeUpdater.d.ts

@@ -3,7 +3,7 @@ import type { ContextIdentifierProvider, MediaProvider } from '@atlaskit/editor-
 import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
 import type { EditorView } from '@atlaskit/editor-prosemirror/view';
 import { type MediaTraceContext } from '@atlaskit/media-common';
-import type { MediaOptions, MediaPluginState, getPosHandler as ProsemirrorGetPosHandler, SupportedMediaAttributes } from '../types';
+import type { getPosHandler as ProsemirrorGetPosHandler, MediaOptions, MediaPluginState, SupportedMediaAttributes } from '../types';
 type RemoteDimensions = {
     height: number;
     id: string;
@@ -13,6 +13,8 @@ export interface MediaNodeUpdaterProps {
     contextIdentifierProvider?: Promise<ContextIdentifierProvider>;
     dispatchAnalyticsEvent?: DispatchAnalyticsEvent;
     isMediaSingle: boolean;
+    /** Content column width in pixels, used to clamp display width on media replacement. */
+    lineLength?: number;
     mediaOptions?: MediaOptions;
     mediaProvider?: Promise<MediaProvider>;
     node: PMNode;

package/dist/types-ts4.5/nodeviews/nodeviewHelpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Computes the new mediaSingle display width that preserves the original display height
+ * when a media node is replaced with a file of a different aspect ratio, clamped to valid bounds.
+ *
+ * @param targetDisplayHeight - The display height to preserve (from the old image)
+ * @param newIntrinsicWidth - The new file's intrinsic pixel width
+ * @param newIntrinsicHeight - The new file's intrinsic pixel height
+ * @param layout - The mediaSingle layout (affects max width)
+ * @param lineLength - The editor content column width in pixels
+ */
+export declare const computeReplacementDisplayWidth: (targetDisplayHeight: number, newIntrinsicWidth: number, newIntrinsicHeight: number, layout: string, lineLength: number) => number;

package/dist/types-ts4.5/pm-plugins/main.d.ts

@@ -52,6 +52,8 @@ export declare class MediaPluginStateImplementation implements MediaPluginState
     private removeOnCloseListener;
     private openMediaPickerBrowser?;
     private onPopupToggleCallback;
+    replaceMediaFileId: string | null;
+    replaceMediaTargetDisplayHeight: number | null;
     private identifierCount;
     private outOfEditorScopeIdentifierMap;
     private taskManager;
@@ -88,6 +90,16 @@ export declare class MediaPluginStateImplementation implements MediaPluginState
     splitMediaGroup: () => boolean;
     onPopupPickerClose: () => void;
     showMediaPicker: () => void;
+    /**
+     * Opens the media picker in "replace" mode. The next file selected/uploaded
+     * will replace the currently selected mediaSingle node's media child in-place,
+     * preserving layout, width, and caption.
+     *
+     * The display height is computed and stored so that after the new file's intrinsic
+     * dimensions are fetched, the mediaSingle display width can be adjusted to maintain
+     * visual height stability rather than width stability.
+     */
+    showMediaPickerForReplace: () => void;
     setBrowseFn: (browseFn: () => void) => void;
     onPopupToggle: (onPopupToggleCallback: (isOpen: boolean) => void) => void;
     /**

package/dist/types-ts4.5/pm-plugins/types.d.ts

@@ -53,6 +53,8 @@ export interface MediaPluginState {
     pickerPromises: Array<Promise<PickerFacade>>;
     pickers: PickerFacade[];
     removeSelectedMediaContainer: () => boolean;
+    replaceMediaFileId: string | null;
+    replaceMediaTargetDisplayHeight: number | null;
     resizingWidth: number;
     selectedMediaContainerNode: () => PMNode | undefined;
     setBrowseFn: (browseFn: () => void) => void;
@@ -63,6 +65,7 @@ export interface MediaPluginState {
     showDropzone: boolean;
     showEditingDialog?: boolean;
     showMediaPicker: () => void;
+    showMediaPickerForReplace: () => void;
     splitMediaGroup: () => boolean;
     subscribeToUploadInProgressState: (fn: (isUploading: boolean) => void) => void;
     trackOutOfScopeIdentifier: (identifier: Identifier) => void;

package/nodeviewHelpers/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/editor-plugin-media/nodeviewHelpers",
+  "main": "../dist/cjs/nodeviews/nodeviewHelpers.js",
+  "module": "../dist/esm/nodeviews/nodeviewHelpers.js",
+  "module:es2019": "../dist/es2019/nodeviews/nodeviewHelpers.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/nodeviews/nodeviewHelpers.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/nodeviews/nodeviewHelpers.d.ts"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-media",
-	"version": "12.4.1",
+	"version": "12.5.0",
 	"description": "Media plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -35,7 +35,7 @@
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/editor-palette": "^2.1.0",
 		"@atlaskit/editor-plugin-analytics": "^10.0.0",
-		"@atlaskit/editor-plugin-annotation": "^10.1.0",
+		"@atlaskit/editor-plugin-annotation": "^10.2.0",
 		"@atlaskit/editor-plugin-connectivity": "^10.0.0",
 		"@atlaskit/editor-plugin-decorations": "^10.0.0",
 		"@atlaskit/editor-plugin-editor-disabled": "^10.0.0",
@@ -61,12 +61,12 @@
 		"@atlaskit/media-common": "^13.2.0",
 		"@atlaskit/media-filmstrip": "^51.3.0",
 		"@atlaskit/media-picker": "^71.2.0",
-		"@atlaskit/media-ui": "^29.1.0",
+		"@atlaskit/media-ui": "^29.2.0",
 		"@atlaskit/media-viewer": "^53.1.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/textfield": "^8.3.0",
-		"@atlaskit/tmp-editor-statsig": "^74.7.0",
+		"@atlaskit/tmp-editor-statsig": "^74.10.0",
 		"@atlaskit/tokens": "^13.0.0",
 		"@atlaskit/tooltip": "^22.0.0",
 		"@babel/runtime": "^7.0.0",
@@ -78,7 +78,7 @@
 		"uuid": "^3.1.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^114.18.0",
+		"@atlaskit/editor-common": "^114.19.0",
 		"@atlaskit/media-core": "^37.0.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",