@strapi/content-manager 5.45.0 → 5.46.0

package/dist/admin/preview/utils/previewScript.mjs

@@ -38,6 +38,138 @@ const previewScript = (config)=>{
     const getElementsByPath = (path)=>{
         return document.querySelectorAll(`[${SOURCE_ATTRIBUTE}*="path=${path}"]`);
     };
+    const isMediaElement = (element)=>{
+        return element.tagName === 'IMG' || element.tagName === 'VIDEO' || element.tagName === 'AUDIO';
+    };
+    /**
+   * When a media field's mime type changes (e.g. image -> video), we can't
+   * swap the rendered DOM tag in place — the host framework (e.g. React)
+   * owns the original element and throws on removeChild if we replaceChild
+   * it. Instead we leave the original where it is, hide it, and insert our
+   * own sibling element of the correct tag. The injection lives outside the
+   * host framework's virtual DOM, so reconciliation never touches it.
+   *
+   * On save the host framework re-renders with the saved data and unmounts
+   * the original, leaving our injection orphaned next to its replacement —
+   * which is what was producing duplicate previews. The childList observer
+   * below uses these maps to drop the injection whenever its associated
+   * original is removed.
+   */ const originalToInjection = new Map();
+    const injectionToOriginal = new Map();
+    const trackInjection = (original, injection)=>{
+        originalToInjection.set(original, injection);
+        injectionToOriginal.set(injection, original);
+    };
+    const untrackInjection = (injection)=>{
+        const original = injectionToOriginal.get(injection);
+        if (original) originalToInjection.delete(original);
+        injectionToOriginal.delete(injection);
+    };
+    /**
+   * When a media field is cleared, the original media element gets hidden and
+   * has no bounding box, so the highlight system stops drawing a clickable
+   * area for it. That leaves the user no way to re-add media from the preview.
+   * We insert a sized placeholder div carrying the original's source attribute
+   * so the highlight system keeps tracking the spot. The placeholder is
+   * tracked in the same injection maps as a real injection, so the next
+   * `setMediaElement` call (when the user picks new media) tears it down and
+   * restores/replaces the original element via the existing flow.
+   */ const PLACEHOLDER_ATTRIBUTE = 'data-strapi-media-placeholder';
+    /**
+   * For a multi-media field, growing the rendered DOM (e.g. 1 image → 2)
+   * needs a slot for the new item, but the host framework only re-renders
+   * the gallery on save. We synthesize the missing slots by cloning the
+   * last rendered item and marking each clone with this attribute so the
+   * ghost-sweep below can drop them once the framework eventually re-renders
+   * with the saved value.
+   */ const CLONE_ATTRIBUTE = 'data-strapi-media-clone';
+    /**
+   * Galleries commonly wrap each media element in its own layout cell
+   * (e.g. `<div class="grid"><div><img/></div><div><img/></div></div>`),
+   * so cloning just the IMG makes the new item stack inside the existing
+   * wrapper. We walk up to the closest ancestor whose parent uses a sibling
+   * layout (flex/grid) and clone that instead, marking the cloned wrapper
+   * so cleanup removes the wrapper rather than leaving an empty cell.
+   */ const CLONE_WRAPPER_ATTRIBUTE = 'data-strapi-media-clone-wrapper';
+    const createMediaPlaceholder = (sourceAttr, rect)=>{
+        const placeholder = document.createElement('div');
+        placeholder.setAttribute(PLACEHOLDER_ATTRIBUTE, '');
+        placeholder.setAttribute(SOURCE_ATTRIBUTE, sourceAttr);
+        const width = rect.width > 0 ? rect.width : 200;
+        const height = rect.height > 0 ? rect.height : 200;
+        placeholder.style.cssText = `
+      display: inline-block;
+      width: ${width}px;
+      height: ${height}px;
+      background-color: rgba(0, 0, 0, 0.04);
+      border: 2px dashed rgba(0, 0, 0, 0.15);
+      border-radius: 4px;
+      box-sizing: border-box;
+      vertical-align: top;
+    `;
+        return placeholder;
+    };
+    /**
+   * Form values for media fields carry the raw Strapi URL (often relative,
+   * e.g. "/uploads/foo.jpg"). The host framework typically renders the
+   * original element with an absolute URL (resolved against the Strapi
+   * backend, not the iframe origin). If we naively set the relative form
+   * value as src, the browser resolves it against the iframe origin and
+   * fails to load. Resolve against the original element's existing src
+   * origin so the swap targets the same backend.
+   */ const resolveMediaUrl = (originalEl, rawUrl)=>{
+        if (/^(?:[a-z]+:)?\/\//i.test(rawUrl) || rawUrl.startsWith('data:')) {
+            return rawUrl;
+        }
+        const currentSrc = originalEl.getAttribute('src');
+        if (!currentSrc) return rawUrl;
+        try {
+            const currentUrl = new URL(currentSrc, window.location.href);
+            return new URL(rawUrl, currentUrl.origin).href;
+        } catch  {
+            return rawUrl;
+        }
+    };
+    /**
+   * Extract a recognizable media filename from a URL string. Works for
+   * direct backend URLs, relative paths, and proxy URLs that embed the
+   * real path in a query parameter (e.g. Next.js's "/_next/image?url=...").
+   * Used to detect whether the rendered element already shows the same
+   * asset as the form value, so we can skip src updates that would only
+   * substitute one URL representation for another.
+   */ const getMediaFilename = (raw)=>{
+        if (!raw) return '';
+        let decoded = raw;
+        try {
+            decoded = decodeURIComponent(raw);
+        } catch  {}
+        const match = decoded.match(/([^/?#&=\s]+\.(?:jpg|jpeg|png|gif|webp|avif|svg|mp4|mov|webm|ogg|m4v|mp3|wav|m4a|aac|flac|opus))(?:[?#&]|$)/i);
+        return match ? match[1].toLowerCase() : '';
+    };
+    /**
+   * Get the field path to use for focusing a media field.
+   * - For IMG/VIDEO elements: the path was already normalized (stripped of .url) during stega decoding
+   * - For tracked injections (e.g., placeholder divs we insert when media is cleared): the source
+   *   attribute was copied from the post-normalization media element, so it's already correct
+   * - For non-media elements with model=plugin::upload.file (e.g., caption text): strip the last
+   *   segment to focus the parent media field (e.g., "hero.caption" -> "hero")
+   */ const getFieldPathForMedia = (sourceAttr, element)=>{
+        if (isMediaElement(element) || injectionToOriginal.has(element)) {
+            return sourceAttr;
+        }
+        // For non-media elements, check if it's a media asset field
+        const params = new URLSearchParams(sourceAttr);
+        if (params.get('model') === 'plugin::upload.file') {
+            const elementPath = params.get('path');
+            if (elementPath) {
+                // Strip the last segment (e.g., "hero.caption" -> "hero")
+                const parentPath = elementPath.split('.').slice(0, -1).join('.');
+                params.set('path', parentPath);
+                return params.toString();
+            }
+        }
+        return sourceAttr;
+    };
     /* -----------------------------------------------------------------------------------------------
    * Functionality pieces
    * ---------------------------------------------------------------------------------------------*/ const setupStegaDOMObserver = async ()=>{
@@ -48,6 +180,33 @@ const previewScript = (config)=>{
         // eslint-disable-next-line import/no-unresolved
         'https://cdn.jsdelivr.net/npm/@vercel/stega@0.1.2/+esm');
         const applyStegaToElement = (element)=>{
+            // Handle img and video tags - check src attribute for stega encoding
+            if (isMediaElement(element)) {
+                const src = element.getAttribute('src');
+                if (src) {
+                    try {
+                        const result = stegaDecode(src);
+                        if (result && 'strapiSource' in result) {
+                            // Parse the source and remove .url suffix to point to the media field
+                            const sourceValue = result.strapiSource;
+                            const pathMatch = sourceValue.match(/path=([^&]+)/);
+                            if (pathMatch) {
+                                const originalPath = pathMatch[1];
+                                // Remove .url to get the media field path
+                                const mediaPath = originalPath.replace(/\.url$/, '');
+                                const newSource = sourceValue.replace(`path=${originalPath}`, `path=${mediaPath}`);
+                                element.setAttribute(SOURCE_ATTRIBUTE, newSource);
+                            }
+                        }
+                        // Clean the src attribute so the resource can load
+                        const cleanedSrc = stegaClean(src);
+                        if (cleanedSrc !== src) {
+                            element.setAttribute('src', cleanedSrc);
+                        }
+                    } catch (error) {}
+                }
+                return;
+            }
             const directTextNodes = Array.from(element.childNodes).filter((node)=>node.nodeType === Node.TEXT_NODE);
             const directTextContent = directTextNodes.map((node)=>node.textContent || '').join('');
             if (directTextContent) {
@@ -92,12 +251,23 @@ const previewScript = (config)=>{
                 if (mutation.type === 'characterData' && mutation.target.parentElement) {
                     applyStegaToElement(mutation.target.parentElement);
                 }
+                // Handle src attribute changes for img/video elements
+                if (mutation.type === 'attributes' && mutation.attributeName === 'src') {
+                    const target = mutation.target;
+                    if (isMediaElement(target)) {
+                        applyStegaToElement(target);
+                    }
+                }
             });
         });
         observer.observe(document, {
             childList: true,
             subtree: true,
-            characterData: true
+            characterData: true,
+            attributes: true,
+            attributeFilter: [
+                'src'
+            ]
         });
         return observer;
     };
@@ -151,51 +321,99 @@ const previewScript = (config)=>{
         return overlay;
     };
     const createHighlightManager = (overlay)=>{
-        const elementsToHighlight = new Map();
+        const groups = new Map();
+        const elementToGroupKey = new Map();
         const eventListeners = [];
         const focusedHighlights = [];
-        const pendingClicks = new Map(); // number is timeout id
+        const pendingClicks = new Map();
         let focusedField = null;
-        const drawHighlight = (target, highlight)=>{
-            if (!highlight) return;
-            const rect = target.getBoundingClientRect();
-            highlight.style.width = `${rect.width + HIGHLIGHT_PADDING * 2}px`;
-            highlight.style.height = `${rect.height + HIGHLIGHT_PADDING * 2}px`;
-            highlight.style.transform = `translate(${rect.left - HIGHLIGHT_PADDING}px, ${rect.top - HIGHLIGHT_PADDING}px)`;
-        };
-        const updateAllHighlights = ()=>{
-            elementsToHighlight.forEach((highlight, element)=>{
-                drawHighlight(element, highlight);
+        const computeGroupRect = (group)=>{
+            let minLeft = Infinity;
+            let minTop = Infinity;
+            let maxRight = -Infinity;
+            let maxBottom = -Infinity;
+            let any = false;
+            group.elements.forEach((el)=>{
+                const r = el.getBoundingClientRect();
+                if (r.width === 0 && r.height === 0) return;
+                any = true;
+                if (r.left < minLeft) minLeft = r.left;
+                if (r.top < minTop) minTop = r.top;
+                if (r.right > maxRight) maxRight = r.right;
+                if (r.bottom > maxBottom) maxBottom = r.bottom;
             });
+            if (!any) return null;
+            return {
+                left: minLeft,
+                top: minTop,
+                width: maxRight - minLeft,
+                height: maxBottom - minTop
+            };
         };
-        const createHighlightForElement = (element)=>{
-            if (elementsToHighlight.has(element)) {
-                // Already has a highlight
+        const drawGroup = (group)=>{
+            const rect = computeGroupRect(group);
+            if (!rect) {
+                group.highlight.style.display = 'none';
                 return;
             }
+            group.highlight.style.display = '';
+            group.highlight.style.width = `${rect.width + HIGHLIGHT_PADDING * 2}px`;
+            group.highlight.style.height = `${rect.height + HIGHLIGHT_PADDING * 2}px`;
+            group.highlight.style.transform = `translate(${rect.left - HIGHLIGHT_PADDING}px, ${rect.top - HIGHLIGHT_PADDING}px)`;
+        };
+        const updateAllHighlights = ()=>{
+            groups.forEach(drawGroup);
+        };
+        /**
+     * Pick the underlying source element under the pointer so single-click
+     * redispatch hits the specific item the user clicked, even when the group
+     * highlight covers several elements (multi-media gallery).
+     */ const pickElementAtPoint = (group, x, y)=>{
+            for (const el of group.elements){
+                const r = el.getBoundingClientRect();
+                if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) {
+                    return el;
+                }
+            }
+            const first = group.elements.values().next().value;
+            return first ?? null;
+        };
+        const createGroup = (groupKey)=>{
             const highlight = document.createElement('div');
             highlight.className = 'strapi-highlight';
+            const group = {
+                highlight,
+                elements: new Set()
+            };
             const clickHandler = (event)=>{
-                // Skip if this is a re-dispatched event from our delayed handler to avoid infinite loops
                 if (event.__strapi_redispatched) {
                     return;
                 }
-                // Prevent the immediate action for interactive elements
                 event.preventDefault();
                 event.stopPropagation();
-                // Clear any existing timeout for this element
-                const existingTimeout = pendingClicks.get(element);
+                const existingTimeout = pendingClicks.get(group);
                 if (existingTimeout) {
                     window.clearTimeout(existingTimeout);
-                    pendingClicks.delete(element);
+                    pendingClicks.delete(group);
                 }
-                // Set up a delayed single-click handler
                 const timeout = window.setTimeout(()=>{
-                    pendingClicks.delete(element);
-                    // Send single-click hint notification
+                    pendingClicks.delete(group);
                     sendMessage(INTERNAL_EVENTS.STRAPI_FIELD_SINGLE_CLICK_HINT, null);
-                    // Re-trigger the click on the underlying element after the double-click timeout
-                    // Create a new event to dispatch with a marker to prevent re-handling
+                    // Pick the specific underlying element under the pointer so the
+                    // redispatched click targets the right item in a multi-element group
+                    const underlying = pickElementAtPoint(group, event.clientX, event.clientY);
+                    if (!underlying) return;
+                    let targetElement = underlying;
+                    if (isMediaElement(underlying)) {
+                        let parent = underlying.parentElement;
+                        while(parent){
+                            if (parent.tagName === 'A' || parent.tagName === 'BUTTON' || parent.hasAttribute('onclick') || parent.getAttribute('role') === 'button' || parent.getAttribute('role') === 'link') {
+                                targetElement = parent;
+                                break;
+                            }
+                            parent = parent.parentElement;
+                        }
+                    }
                     const newEvent = new MouseEvent('click', {
                         bubbles: true,
                         cancelable: true,
@@ -211,38 +429,38 @@ const previewScript = (config)=>{
                         metaKey: event.metaKey
                     });
                     newEvent.__strapi_redispatched = true;
-                    element.dispatchEvent(newEvent);
+                    targetElement.dispatchEvent(newEvent);
                 }, DOUBLE_CLICK_TIMEOUT);
-                pendingClicks.set(element, timeout);
+                pendingClicks.set(group, timeout);
             };
             const doubleClickHandler = (event)=>{
-                // Prevent the default behavior on double-click
                 event.preventDefault();
                 event.stopPropagation();
-                // Clear any pending single-click action
-                const existingTimeout = pendingClicks.get(element);
+                const existingTimeout = pendingClicks.get(group);
                 if (existingTimeout) {
                     clearTimeout(existingTimeout);
-                    pendingClicks.delete(element);
-                }
-                const sourceAttribute = element.getAttribute(SOURCE_ATTRIBUTE);
-                if (sourceAttribute) {
-                    const rect = element.getBoundingClientRect();
-                    sendMessage(INTERNAL_EVENTS.STRAPI_FIELD_FOCUS_INTENT, {
-                        path: sourceAttribute,
-                        position: {
-                            top: rect.top,
-                            left: rect.left,
-                            right: rect.right,
-                            bottom: rect.bottom,
-                            width: rect.width,
-                            height: rect.height
-                        }
-                    });
+                    pendingClicks.delete(group);
                 }
+                const anchor = pickElementAtPoint(group, event.clientX, event.clientY);
+                if (!anchor) return;
+                const sourceAttribute = anchor.getAttribute(SOURCE_ATTRIBUTE);
+                if (!sourceAttribute) return;
+                const path = getFieldPathForMedia(sourceAttribute, anchor);
+                const rect = computeGroupRect(group);
+                if (!rect) return;
+                sendMessage(INTERNAL_EVENTS.STRAPI_FIELD_FOCUS_INTENT, {
+                    path,
+                    position: {
+                        top: rect.top,
+                        left: rect.left,
+                        right: rect.left + rect.width,
+                        bottom: rect.top + rect.height,
+                        width: rect.width,
+                        height: rect.height
+                    }
+                });
             };
             const mouseDownHandler = (event)=>{
-                // Prevent default multi click to select behavior
                 if (event.detail >= 2) {
                     event.preventDefault();
                 }
@@ -250,7 +468,6 @@ const previewScript = (config)=>{
             highlight.addEventListener('click', clickHandler);
             highlight.addEventListener('dblclick', doubleClickHandler);
             highlight.addEventListener('mousedown', mouseDownHandler);
-            // Store event listeners for cleanup
             eventListeners.push({
                 element: highlight,
                 type: 'click',
@@ -264,28 +481,120 @@ const previewScript = (config)=>{
                 type: 'mousedown',
                 handler: mouseDownHandler
             });
-            elementsToHighlight.set(element, highlight);
             overlay.appendChild(highlight);
-            drawHighlight(element, highlight);
+            groups.set(groupKey, group);
+            return group;
         };
-        const removeHighlightForElement = (element)=>{
-            const highlight = elementsToHighlight.get(element);
-            if (!highlight) return;
-            // Clear any pending click timeout for this element
-            const pendingTimeout = pendingClicks.get(element);
+        const destroyGroup = (groupKey, group)=>{
+            const pendingTimeout = pendingClicks.get(group);
             if (pendingTimeout) {
                 window.clearTimeout(pendingTimeout);
-                pendingClicks.delete(element);
+                pendingClicks.delete(group);
             }
-            highlight.remove();
-            elementsToHighlight.delete(element);
-            // Remove event listeners for this highlight
-            const listenersToRemove = eventListeners.filter((listener)=>listener.element === highlight);
+            const focusedIndex = focusedHighlights.indexOf(group.highlight);
+            if (focusedIndex !== -1) {
+                focusedHighlights.splice(focusedIndex, 1);
+            }
+            group.highlight.remove();
+            const listenersToRemove = eventListeners.filter((listener)=>listener.element === group.highlight);
             listenersToRemove.forEach(({ element, type, handler })=>{
                 element.removeEventListener(type, handler);
             });
-            // Mutate eventListeners to remove listeners for this highlight
-            eventListeners.splice(0, eventListeners.length, ...eventListeners.filter((listener)=>listener.element !== highlight));
+            eventListeners.splice(0, eventListeners.length, ...eventListeners.filter((listener)=>listener.element !== group.highlight));
+            groups.delete(groupKey);
+        };
+        const createHighlightForElement = (element)=>{
+            if (elementToGroupKey.has(element)) {
+                return;
+            }
+            const groupKey = element.getAttribute(SOURCE_ATTRIBUTE);
+            if (!groupKey) return;
+            let group = groups.get(groupKey);
+            // When a framework-rendered media element joins a group that still
+            // holds stale ghosts from a previous clear (a standalone placeholder,
+            // our injection paired with a hidden placeholder, or a clone we
+            // synthesized to give an added array item a slot), sweep the ghosts
+            // so we don't end up with two visible elements stacked on top of
+            // each other after a save commits a real value.
+            if (group && isMediaElement(element) && !injectionToOriginal.has(element) && !element.hasAttribute(CLONE_ATTRIBUTE)) {
+                const ghostInjections = [];
+                const ghostPlaceholders = [];
+                const ghostClones = [];
+                group.elements.forEach((el)=>{
+                    if (injectionToOriginal.has(el)) {
+                        ghostInjections.push(el);
+                    } else if (el.hasAttribute(CLONE_ATTRIBUTE)) {
+                        ghostClones.push(el);
+                    } else if (el.hasAttribute(PLACEHOLDER_ATTRIBUTE)) {
+                        ghostPlaceholders.push(el);
+                    }
+                });
+                ghostInjections.forEach((injection)=>{
+                    const orig = injectionToOriginal.get(injection);
+                    untrackInjection(injection);
+                    if (orig?.hasAttribute(CLONE_ATTRIBUTE)) {
+                        // Tag-swap injection of a clone (e.g. user added a video as
+                        // the new item, swapping our cloned IMG for a VIDEO). Remove
+                        // the wrapper so we don't leave an empty layout cell behind.
+                        const wrapper = orig.closest(`[${CLONE_WRAPPER_ATTRIBUTE}]`);
+                        (wrapper ?? orig).remove();
+                    } else if (orig?.hasAttribute(PLACEHOLDER_ATTRIBUTE)) {
+                        orig.remove();
+                    }
+                    group?.elements.delete(injection);
+                    elementToGroupKey.delete(injection);
+                    injection.remove();
+                });
+                ghostPlaceholders.forEach((placeholder)=>{
+                    group?.elements.delete(placeholder);
+                    elementToGroupKey.delete(placeholder);
+                    placeholder.remove();
+                });
+                // Remove the wrapper if we cloned an ancestor for layout — falling
+                // back to the clone itself when it's its own root. Removing via
+                // .remove() also triggers the mutation observer's removedNodes
+                // branch, which untracks any injection paired with descendants.
+                ghostClones.forEach((clone)=>{
+                    group?.elements.delete(clone);
+                    elementToGroupKey.delete(clone);
+                    const wrapper = clone.closest(`[${CLONE_WRAPPER_ATTRIBUTE}]`);
+                    (wrapper ?? clone).remove();
+                });
+            }
+            if (!group) {
+                group = createGroup(groupKey);
+            }
+            group.elements.add(element);
+            elementToGroupKey.set(element, groupKey);
+            drawGroup(group);
+        };
+        const removeHighlightForElement = (element)=>{
+            const groupKey = elementToGroupKey.get(element);
+            if (!groupKey) return;
+            const group = groups.get(groupKey);
+            if (!group) return;
+            group.elements.delete(element);
+            elementToGroupKey.delete(element);
+            if (group.elements.size === 0) {
+                destroyGroup(groupKey, group);
+            } else {
+                drawGroup(group);
+            }
+        };
+        /**
+     * Resolve groups whose elements match a focused field path. We delegate
+     * to `getElementsByPath` so this preserves the same loose substring match
+     * the highlight system has always used (e.g. focusing `hero` matches
+     * `hero.caption` too).
+     */ const findGroupForPath = (path)=>{
+            const matched = new Set();
+            getElementsByPath(path).forEach((el)=>{
+                const key = elementToGroupKey.get(el);
+                if (!key) return;
+                const group = groups.get(key);
+                if (group) matched.add(group);
+            });
+            return Array.from(matched);
         };
         // Process all existing elements with source attributes
         const initialElements = window.document.querySelectorAll(`[${SOURCE_ATTRIBUTE}]`);
@@ -296,16 +605,17 @@ const previewScript = (config)=>{
         });
         return {
             get elements () {
-                return Array.from(elementsToHighlight.keys());
+                return Array.from(elementToGroupKey.keys());
             },
-            get highlights () {
-                return Array.from(elementsToHighlight.values());
+            get groups () {
+                return Array.from(groups.values());
             },
             updateAllHighlights,
             eventListeners,
             focusedHighlights,
             createHighlightForElement,
             removeHighlightForElement,
+            findGroupForPath,
             setFocusedField: (field)=>{
                 focusedField = field;
             },
@@ -406,6 +716,22 @@ const previewScript = (config)=>{
                         if (node.nodeType === Node.ELEMENT_NODE) {
                             const element = node;
                             highlightManager.removeHighlightForElement(element);
+                            // If a tracked media original (or its ancestor) was removed —
+                            // typically when the host framework re-renders after save and
+                            // unmounts the previous element — drop our matching injection
+                            // so we don't end up with duplicate previews next to the new one.
+                            // This applies to placeholders too: once the framework owns
+                            // the layout for a cleared field (and likely renders its own
+                            // empty state), our placeholder would just stack next to it.
+                            originalToInjection.forEach((injection, original)=>{
+                                if (element === original || element.contains(original)) {
+                                    untrackInjection(injection);
+                                    injection.remove();
+                                } else if (element === injection || element.contains(injection)) {
+                                    // Our injection itself was removed (e.g. parent unmounted)
+                                    untrackInjection(injection);
+                                }
+                            });
                         }
                     });
                 }
@@ -426,17 +752,230 @@ const previewScript = (config)=>{
         };
     };
     const setupEventHandlers = (highlightManager)=>{
+        const setMediaElement = (el, url, mime)=>{
+            const original = injectionToOriginal.get(el) ?? el;
+            const injection = originalToInjection.get(original) ?? null;
+            const removeInjection = ()=>{
+                if (!injection) return;
+                // Move the source attribute back to the original so highlights track it again
+                const sourceAttr = injection.getAttribute(SOURCE_ATTRIBUTE);
+                if (sourceAttr) original.setAttribute(SOURCE_ATTRIBUTE, sourceAttr);
+                untrackInjection(injection);
+                injection.remove();
+            };
+            if (!url) {
+                // Capture rect from whatever's currently visible before any DOM
+                // changes, so the placeholder can be sized to match.
+                const visibleEl = injection ?? original;
+                const rect = visibleEl.getBoundingClientRect();
+                // removeInjection moves the source attr back to original, so we read
+                // it after.
+                removeInjection();
+                const sourceAttr = original.getAttribute(SOURCE_ATTRIBUTE);
+                if (!sourceAttr) {
+                    original.style.display = 'none';
+                    return;
+                }
+                // Hide the host-framework-managed original. We deliberately keep
+                // its `src` attribute around so `resolveMediaUrl` can still derive
+                // the backend origin when the user later picks a new media file
+                // with a relative URL.
+                original.style.display = 'none';
+                // Move the source attr onto a placeholder div so the highlight
+                // system keeps tracking the spot and the user can click to re-add
+                // media.
+                original.removeAttribute(SOURCE_ATTRIBUTE);
+                const placeholder = createMediaPlaceholder(sourceAttr, rect);
+                original.parentNode?.insertBefore(placeholder, original.nextSibling);
+                trackInjection(original, placeholder);
+                return;
+            }
+            const desiredTag = mime?.startsWith('image/') ? 'IMG' : mime?.startsWith('video/') ? 'VIDEO' : mime?.startsWith('audio/') ? 'AUDIO' : null;
+            // If the rendered element already shows the same media file as the
+            // form value, do nothing. Compare by filename so we're agnostic to
+            // URL representation — the host framework may have rendered a proxy
+            // URL (e.g. Next.js's "/_next/image?url=...") that wouldn't match a
+            // raw form-value URL string-wise but resolves to the same asset.
+            const active = injection ?? original;
+            const newFilename = getMediaFilename(url);
+            const currentFilename = getMediaFilename(active.getAttribute('src') ?? '');
+            const tagAlreadyMatches = !desiredTag || active.tagName === desiredTag;
+            if (tagAlreadyMatches && newFilename && newFilename === currentFilename) {
+                active.style.display = '';
+                return;
+            }
+            // Resolve relative form-value URLs against the existing src's origin
+            // so the swap targets the Strapi backend, not the iframe origin.
+            const resolvedUrl = resolveMediaUrl(original, url);
+            // No mime info — fall back to updating whatever's active
+            if (!desiredTag) {
+                if (active.getAttribute('src') !== resolvedUrl) {
+                    active.setAttribute('src', resolvedUrl);
+                }
+                active.style.display = '';
+                return;
+            }
+            // Original's tag matches: restore it (removing any previous injection)
+            if (original.tagName === desiredTag) {
+                removeInjection();
+                if (original.getAttribute('src') !== resolvedUrl) {
+                    original.setAttribute('src', resolvedUrl);
+                }
+                original.style.display = '';
+                return;
+            }
+            // Existing injection of the right tag: just update its src
+            if (injection && injection.tagName === desiredTag) {
+                if (injection.getAttribute('src') !== resolvedUrl) {
+                    injection.setAttribute('src', resolvedUrl);
+                }
+                return;
+            }
+            // Need a fresh injection of the correct tag
+            removeInjection();
+            const newInjection = document.createElement(desiredTag);
+            // Mirror the original's attributes so styling/classes carry over.
+            // Skip src/srcset — those carry the *previous* media's URL and would
+            // make the new element try to load it (a video element fed an image
+            // URL renders a permanent "No supported format" error). We set src
+            // explicitly below.
+            // For audio, skip visual-sizing attributes too — image/video classes
+            // (e.g. aspect-square, h-96) don't suit a horizontal audio control
+            // and produce a giant empty box around the player.
+            const isAudio = desiredTag === 'AUDIO';
+            const skipForAudio = new Set([
+                'class',
+                'style',
+                'width',
+                'height'
+            ]);
+            Array.from(original.attributes).forEach((attr)=>{
+                if (attr.name === 'id' || attr.name === 'src' || attr.name === 'srcset') return;
+                if (isAudio && skipForAudio.has(attr.name)) return;
+                newInjection.setAttribute(attr.name, attr.value);
+            });
+            newInjection.setAttribute('src', resolvedUrl);
+            if (desiredTag === 'VIDEO' || desiredTag === 'AUDIO') {
+                newInjection.setAttribute('controls', '');
+            }
+            if (!isAudio) {
+                newInjection.style.cssText = original.style.cssText;
+            }
+            newInjection.style.display = '';
+            // Hide the host-framework-managed original and let highlights track our injection
+            original.style.display = 'none';
+            original.removeAttribute(SOURCE_ATTRIBUTE);
+            original.parentNode?.insertBefore(newInjection, original.nextSibling);
+            trackInjection(original, newInjection);
+        };
         const handleMessage = (event)=>{
             if (!event.data?.type) return;
             // The user typed in an input, reflect the change in the preview
             if (event.data.type === INTERNAL_EVENTS.STRAPI_FIELD_CHANGE) {
                 const { field, value } = event.data.payload;
                 if (!field) return;
-                getElementsByPath(field).forEach((element)=>{
-                    if (element instanceof HTMLElement) {
-                        element.textContent = value || '';
+                const matchedElements = Array.from(getElementsByPath(field)).filter((el)=>el instanceof HTMLElement);
+                // A cleared media field is represented by a placeholder div sitting
+                // where the (hidden or unmounted) original used to be. Treat it like
+                // a media element here so the next change routes through
+                // setMediaElement and tears the placeholder down. Standalone
+                // placeholders (those whose original was unmounted by the host
+                // framework after save) are not in the injection maps but still
+                // need to be matchable.
+                const isMediaTarget = (el)=>isMediaElement(el) || injectionToOriginal.has(el) || el.hasAttribute(PLACEHOLDER_ATTRIBUTE);
+                // Multi-media field: value is an array of media items. After the
+                // server change, every item shares `path=<field>`, so we map array
+                // items to media elements in DOM order. Removing items reuses
+                // existing elements (extras get cleared into placeholders); adding
+                // items synthesizes new slots by cloning the last rendered element,
+                // since the host framework only re-renders the gallery on save.
+                if (Array.isArray(value)) {
+                    const mediaEls = matchedElements.filter(isMediaTarget);
+                    if (mediaEls.length > 0 && mediaEls.length < value.length) {
+                        const lastEl = mediaEls[mediaEls.length - 1];
+                        // Walk up until we reach an ancestor whose parent lays out
+                        // children as siblings (flex/grid). Record indices so we can
+                        // re-find the media element inside each cloned wrapper.
+                        const indices = [];
+                        let template = lastEl;
+                        let parent = template.parentElement;
+                        const SIBLING_LAYOUTS = new Set([
+                            'flex',
+                            'inline-flex',
+                            'grid',
+                            'inline-grid'
+                        ]);
+                        const MAX_DEPTH = 5;
+                        for(let depth = 0; parent && depth < MAX_DEPTH; depth++){
+                            if (SIBLING_LAYOUTS.has(window.getComputedStyle(parent).display)) {
+                                break;
+                            }
+                            indices.push(Array.prototype.indexOf.call(parent.children, template));
+                            template = parent;
+                            parent = parent.parentElement;
+                        }
+                        let insertAfter = template;
+                        for(let i = mediaEls.length; i < value.length; i++){
+                            const wrapperClone = template.cloneNode(true);
+                            let cloneMedia = wrapperClone;
+                            for(let j = indices.length - 1; j >= 0; j--){
+                                cloneMedia = cloneMedia.children[indices[j]];
+                            }
+                            cloneMedia.setAttribute(CLONE_ATTRIBUTE, '');
+                            cloneMedia.removeAttribute('id');
+                            if (wrapperClone !== cloneMedia) {
+                                wrapperClone.setAttribute(CLONE_WRAPPER_ATTRIBUTE, '');
+                            }
+                            insertAfter.parentNode?.insertBefore(wrapperClone, insertAfter.nextSibling);
+                            mediaEls.push(cloneMedia);
+                            insertAfter = wrapperClone;
+                        }
                     }
-                });
+                    mediaEls.forEach((el, index)=>{
+                        const item = value[index];
+                        if (item && typeof item === 'object') {
+                            const url = item.url;
+                            const mime = item.mime;
+                            setMediaElement(el, url || null, mime);
+                        } else {
+                            setMediaElement(el, null);
+                        }
+                    });
+                } else {
+                    matchedElements.forEach((element)=>{
+                        if (isMediaTarget(element)) {
+                            const url = typeof value === 'object' && value !== null ? value.url : value;
+                            const mime = typeof value === 'object' && value !== null ? value.mime : undefined;
+                            setMediaElement(element, url || null, mime);
+                        } else {
+                            element.textContent = value || '';
+                        }
+                    });
+                }
+                // Handle nested media asset fields (caption, alt, etc.)
+                // These are identified by model=plugin::upload.file in the source attribute
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    const allSourceElements = document.querySelectorAll(`[${SOURCE_ATTRIBUTE}]`);
+                    allSourceElements.forEach((element)=>{
+                        const sourceAttr = element.getAttribute(SOURCE_ATTRIBUTE);
+                        if (!sourceAttr) return;
+                        // Parse the source attribute as URL search params
+                        const params = new URLSearchParams(sourceAttr);
+                        const model = params.get('model');
+                        const elementPath = params.get('path');
+                        // Only process media asset fields
+                        if (model !== 'plugin::upload.file' || !elementPath) return;
+                        // Check if this element's path starts with the field path (e.g., "hero.caption" starts with "hero")
+                        if (elementPath.startsWith(`${field}.`)) {
+                            // Extract the property name (e.g., "caption" from "hero.caption")
+                            const propertyName = elementPath.slice(field.length + 1);
+                            const propertyValue = value[propertyName];
+                            if (element instanceof HTMLElement && propertyValue !== undefined) {
+                                element.textContent = propertyValue || '';
+                            }
+                        }
+                    });
+                }
                 // Update highlight dimensions since the new text content may affect them
                 highlightManager.updateAllHighlights();
                 return;
@@ -450,20 +989,19 @@ const previewScript = (config)=>{
                     highlight.classList.remove('strapi-highlight-focused');
                 });
                 highlightManager.focusedHighlights.length = 0;
-                // Set new focused field and highlight matching elements
+                // Set new focused field and highlight matching groups
                 highlightManager.setFocusedField(field);
-                getElementsByPath(field).forEach((element, index)=>{
+                const matchingGroups = highlightManager.findGroupForPath(field);
+                matchingGroups.forEach((group, index)=>{
                     if (index === 0) {
-                        element.scrollIntoView({
+                        const first = group.elements.values().next().value;
+                        first?.scrollIntoView({
                             behavior: 'smooth',
                             block: 'center'
                         });
                     }
-                    const highlight = highlightManager.highlights[Array.from(highlightManager.elements).indexOf(element)];
-                    if (highlight) {
-                        highlight.classList.add('strapi-highlight-focused');
-                        highlightManager.focusedHighlights.push(highlight);
-                    }
+                    group.highlight.classList.add('strapi-highlight-focused');
+                    highlightManager.focusedHighlights.push(group.highlight);
                 });
                 return;
             }