From 999c7a3c305325a8a37887c542b73666d3913477 Mon Sep 17 00:00:00 2001
From: wojtekpiskorz <wojciechpiskorz@gmail.com>
Date: Fri, 15 May 2026 11:54:37 +0200
Subject: [PATCH 1/2] fix(admin): show placeholder when media picker image is
 missing

When a media_picker field references an image that no longer exists
(e.g. after syncing DB between environments without syncing uploads),
the img tag 404s and the preview container collapses to 0px height.
Since Change/Remove buttons are position: absolute, they become
invisible and unreachable via mouse.

Fix: add onError handler + min-height on img + broken-image placeholder
with accessible Change/Remove buttons. Applied to both:
- BlockKitMediaPickerField.tsx (Block Kit plugin field)
- ContentEditor.tsx (standalone image field)

Tests: 3 new tests for broken image behavior, all 878 tests pass.
---
 .changeset/fix-media-picker-broken-image.md   |  5 ++
 .../components/BlockKitMediaPickerField.tsx   | 84 +++++++++++++------
 .../admin/src/components/ContentEditor.tsx    | 75 +++++++++++++----
 .../BlockKitMediaPickerField.test.tsx         | 47 +++++++++++
 4 files changed, 170 insertions(+), 41 deletions(-)
 create mode 100644 .changeset/fix-media-picker-broken-image.md

diff --git a/.changeset/fix-media-picker-broken-image.md b/.changeset/fix-media-picker-broken-image.md
new file mode 100644
index 000000000..a6f397dba
--- /dev/null
+++ b/.changeset/fix-media-picker-broken-image.md
@@ -0,0 +1,5 @@
+---
+"@emdash-cms/admin": patch
+---
+
+Fixes broken image collapsing media picker container — adds `onError` handler and fallback placeholder so Change/Remove buttons remain accessible when referenced image is missing from storage
diff --git a/packages/admin/src/components/BlockKitMediaPickerField.tsx b/packages/admin/src/components/BlockKitMediaPickerField.tsx
index 8ee052389..2bcd21255 100644
--- a/packages/admin/src/components/BlockKitMediaPickerField.tsx
+++ b/packages/admin/src/components/BlockKitMediaPickerField.tsx
@@ -1,6 +1,6 @@
 import { Button } from "@cloudflare/kumo";
 import { useLingui } from "@lingui/react/macro";
-import { Image as ImageIcon, X } from "@phosphor-icons/react";
+import { Image as ImageIcon, ImageBroken, X } from "@phosphor-icons/react";
 import * as React from "react";
 
 import type { MediaItem } from "../lib/api";
@@ -35,6 +35,7 @@ export function BlockKitMediaPickerField({
 }: BlockKitMediaPickerFieldProps) {
 	const { t } = useLingui();
 	const [pickerOpen, setPickerOpen] = React.useState(false);
+	const [imageBroken, setImageBroken] = React.useState(false);
 	const url = typeof value === "string" && value.length > 0 ? value : "";
 	const filter = mimeTypeFilter ?? "image/";
 	const canPreview = isSafePreviewUrl(url);
@@ -55,30 +56,65 @@ export function BlockKitMediaPickerField({
 		<div>
 			<label className="text-sm font-medium mb-1.5 block">{label}</label>
 			{canPreview ? (
-				<div className="relative group">
-					<img
-						src={url}
-						alt=""
-						className="max-h-40 w-full rounded-md border border-kumo-line object-contain bg-kumo-muted"
-						referrerPolicy="no-referrer"
-						loading="lazy"
-					/>
-					<div className="absolute top-2 end-2 opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto transition-opacity flex gap-1">
-						<Button type="button" size="sm" variant="secondary" onClick={() => setPickerOpen(true)}>
-							{t`Change`}
-						</Button>
-						<Button
-							type="button"
-							shape="square"
-							variant="destructive"
-							className="h-8 w-8"
-							onClick={() => onChange(actionId, "")}
-							aria-label={t`Remove`}
-						>
-							<X className="h-4 w-4" />
-						</Button>
+				imageBroken ? (
+					<div className="relative group min-h-20">
+						<div className="min-h-20 w-full rounded-md border border-kumo-line bg-kumo-muted flex items-center justify-center gap-2 text-kumo-subtle">
+							<ImageBroken className="h-5 w-5" />
+							<span className="text-sm">{t`Image not found`}</span>
+						</div>
+						<div className="absolute top-2 end-2 opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto transition-opacity flex gap-1">
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								onClick={() => setPickerOpen(true)}
+							>
+								{t`Change`}
+							</Button>
+							<Button
+								type="button"
+								shape="square"
+								variant="destructive"
+								className="h-8 w-8"
+								onClick={() => onChange(actionId, "")}
+								aria-label={t`Remove`}
+							>
+								<X className="h-4 w-4" />
+							</Button>
+						</div>
 					</div>
-				</div>
+				) : (
+					<div className="relative group">
+						<img
+							src={url}
+							alt=""
+							className="max-h-40 min-h-20 w-full rounded-md border border-kumo-line object-contain bg-kumo-muted"
+							referrerPolicy="no-referrer"
+							loading="lazy"
+							onError={() => setImageBroken(true)}
+						/>
+						<div className="absolute top-2 end-2 opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto transition-opacity flex gap-1">
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								onClick={() => setPickerOpen(true)}
+							>
+								{t`Change`}
+							</Button>
+							<Button
+								type="button"
+								shape="square"
+								variant="destructive"
+								className="h-8 w-8"
+								onClick={() => onChange(actionId, "")}
+								aria-label={t`Remove`}
+							>
+								<X className="h-4 w-4" />
+							</Button>
+						</div>
+					</div>
+				)
 			) : (
 				<Button
 					type="button"
diff --git a/packages/admin/src/components/ContentEditor.tsx b/packages/admin/src/components/ContentEditor.tsx
index 5c7d6589c..06f2fedf8 100644
--- a/packages/admin/src/components/ContentEditor.tsx
+++ b/packages/admin/src/components/ContentEditor.tsx
@@ -23,6 +23,7 @@ import {
 	ArrowsInSimple,
 	ArrowsOutSimple,
 	ArrowSquareOut,
+	ImageBroken,
 } from "@phosphor-icons/react";
 import { Link, useNavigate } from "@tanstack/react-router";
 import type { Editor } from "@tiptap/react";
@@ -1574,6 +1575,7 @@ function ImageFieldRenderer({
 }: ImageFieldRendererProps) {
 	const { t } = useLingui();
 	const [pickerOpen, setPickerOpen] = React.useState(false);
+	const [imageBroken, setImageBroken] = React.useState(false);
 	// Normalize value to get display URL (handles both object and legacy string)
 	// Prefer previewUrl for admin display, fall back to src, then derive from storageKey/id
 	const displayUrl =
@@ -1609,24 +1611,63 @@ function ImageFieldRenderer({
 		<div id={id}>
 			<Label>{label}</Label>
 			{displayUrl ? (
-				<div className="mt-2 relative group">
-					<img src={displayUrl} alt="" className="max-h-48 rounded-lg border object-cover" />
-					<div className="absolute top-2 end-2 opacity-0 group-hover:opacity-100 transition-opacity flex gap-1">
-						<Button type="button" size="sm" variant="secondary" onClick={() => setPickerOpen(true)}>
-							{t`Change`}
-						</Button>
-						<Button
-							type="button"
-							shape="square"
-							variant="destructive"
-							className="h-8 w-8"
-							onClick={handleRemove}
-							aria-label={t`Remove image`}
-						>
-							<X className="h-4 w-4" />
-						</Button>
+				imageBroken ? (
+					<div className="mt-2 relative group">
+						<div className="min-h-20 rounded-lg border bg-kumo-muted flex items-center justify-center gap-2 text-kumo-subtle">
+							<ImageBroken className="h-5 w-5" />
+							<span className="text-sm">{t`Image not found`}</span>
+						</div>
+						<div className="absolute top-2 end-2 opacity-0 group-hover:opacity-100 transition-opacity flex gap-1">
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								onClick={() => setPickerOpen(true)}
+							>
+								{t`Change`}
+							</Button>
+							<Button
+								type="button"
+								shape="square"
+								variant="destructive"
+								className="h-8 w-8"
+								onClick={handleRemove}
+								aria-label={t`Remove image`}
+							>
+								<X className="h-4 w-4" />
+							</Button>
+						</div>
 					</div>
-				</div>
+				) : (
+					<div className="mt-2 relative group">
+						<img
+							src={displayUrl}
+							alt=""
+							className="max-h-48 min-h-20 rounded-lg border object-cover"
+							onError={() => setImageBroken(true)}
+						/>
+						<div className="absolute top-2 end-2 opacity-0 group-hover:opacity-100 transition-opacity flex gap-1">
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								onClick={() => setPickerOpen(true)}
+							>
+								{t`Change`}
+							</Button>
+							<Button
+								type="button"
+								shape="square"
+								variant="destructive"
+								className="h-8 w-8"
+								onClick={handleRemove}
+								aria-label={t`Remove image`}
+							>
+								<X className="h-4 w-4" />
+							</Button>
+						</div>
+					</div>
+				)
 			) : (
 				<Button
 					type="button"
diff --git a/packages/admin/tests/components/BlockKitMediaPickerField.test.tsx b/packages/admin/tests/components/BlockKitMediaPickerField.test.tsx
index 2c285ae77..35c530417 100644
--- a/packages/admin/tests/components/BlockKitMediaPickerField.test.tsx
+++ b/packages/admin/tests/components/BlockKitMediaPickerField.test.tsx
@@ -165,6 +165,53 @@ describe("BlockKitMediaPickerField", () => {
 		});
 	});
 
+	describe("broken image", () => {
+		it("shows a broken-image placeholder when the img fails to load", async () => {
+			const { screen } = await renderField({
+				value: "/_emdash/api/media/file/missing.png",
+			});
+
+			// Image should render initially
+			const img = await waitForImg();
+			expect(img.getAttribute("src")).toBe("/_emdash/api/media/file/missing.png");
+
+			// Simulate image load failure
+			img.dispatchEvent(new Event("error"));
+
+			// Broken-image placeholder should appear
+			await expect.element(screen.getByText("Image not found")).toBeInTheDocument();
+		});
+
+		it("keeps Change and Remove buttons accessible when the image is broken", async () => {
+			const { screen } = await renderField({
+				value: "/_emdash/api/media/file/missing.png",
+			});
+
+			const img = await waitForImg();
+			img.dispatchEvent(new Event("error"));
+
+			// Both action buttons must remain in the DOM and accessible
+			await expect.element(screen.getByLabelText("Remove")).toBeInTheDocument();
+			await expect.element(screen.getByText("Change")).toBeInTheDocument();
+		});
+
+		it("maintains a minimum height so the container does not collapse", async () => {
+			const { screen } = await renderField({
+				value: "/_emdash/api/media/file/missing.png",
+			});
+
+			const img = await waitForImg();
+			img.dispatchEvent(new Event("error"));
+
+			// The broken-image placeholder should be visible (its presence confirms
+			// the container didn't collapse — a zero-height container can't show text)
+			await expect.element(screen.getByText("Image not found")).toBeInTheDocument();
+
+			// The remove button must remain accessible via label
+			await expect.element(screen.getByLabelText("Remove")).toBeInTheDocument();
+		});
+	});
+
 	describe("remove", () => {
 		it("clears the value when Remove is clicked", async () => {
 			const onChange = vi.fn();

From 43dd79ea17077e20c2d6295b541744f4e0c06a27 Mon Sep 17 00:00:00 2001
From: wojtekpiskorz <wojciechpiskorz@gmail.com>
Date: Fri, 15 May 2026 12:24:45 +0200
Subject: [PATCH 2/2] fix(admin): reset imageBroken state when URL changes

Addresses Copilot review: imageBroken was never reset when the user
selected a new image via Change, so the broken placeholder persisted.
Now useEffect resets imageBroken when url/displayUrl changes.
---
 packages/admin/src/components/BlockKitMediaPickerField.tsx | 4 ++++
 packages/admin/src/components/ContentEditor.tsx            | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/packages/admin/src/components/BlockKitMediaPickerField.tsx b/packages/admin/src/components/BlockKitMediaPickerField.tsx
index 2bcd21255..febadc32c 100644
--- a/packages/admin/src/components/BlockKitMediaPickerField.tsx
+++ b/packages/admin/src/components/BlockKitMediaPickerField.tsx
@@ -37,6 +37,10 @@ export function BlockKitMediaPickerField({
 	const [pickerOpen, setPickerOpen] = React.useState(false);
 	const [imageBroken, setImageBroken] = React.useState(false);
 	const url = typeof value === "string" && value.length > 0 ? value : "";
+
+	React.useEffect(() => {
+		setImageBroken(false);
+	}, [url]);
 	const filter = mimeTypeFilter ?? "image/";
 	const canPreview = isSafePreviewUrl(url);
 
diff --git a/packages/admin/src/components/ContentEditor.tsx b/packages/admin/src/components/ContentEditor.tsx
index 06f2fedf8..df9cc0cf5 100644
--- a/packages/admin/src/components/ContentEditor.tsx
+++ b/packages/admin/src/components/ContentEditor.tsx
@@ -1587,6 +1587,10 @@ function ImageFieldRenderer({
 					? `/_emdash/api/media/file/${typeof value.meta?.storageKey === "string" ? value.meta.storageKey : value.id}`
 					: undefined);
 
+	React.useEffect(() => {
+		setImageBroken(false);
+	}, [displayUrl]);
+
 	const handleSelect = (item: MediaItem) => {
 		const isLocalProvider = !item.provider || item.provider === "local";