Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): tighten broken-image predicate + a11y + font size (media-fallback follow-up) (#3215)

Abraham6f6f7d9f561c
diff --git a/packages/app/src/components/ui/loading-image.tsx b/packages/app/src/components/ui/loading-image.tsx
index 8d1e54a91..283bc77a3 100644
--- a/packages/app/src/components/ui/loading-image.tsx
+++ b/packages/app/src/components/ui/loading-image.tsx
@@ -58,59 +58,43 @@ export function LoadingImage({
// Cached or preloaded images may be `complete` at mount and never fire
// onLoad after React commits — the skeleton would otherwise persist
// forever and the <img> stay stuck at opacity-0. Treating `complete` as
- // the terminal-state signal (regardless of naturalWidth) also dismisses
- // the skeleton for cached failures whose onError may not re-fire, mirroring
- // the onError handler's semantics. `naturalWidth === 0` on a `complete`
- // img means the load actually failed (broken/404 cache) — surface that as
- // the error placeholder instead of leaving the reader looking at the
- // browser's tiny default broken-image glyph. Re-running on src change
- // resets both flags when the same instance is reused with a new src.
- // biome-ignore lint/correctness/useExhaustiveDependencies: src is the reactive trigger; the body reads imgRef.current (refs don't trigger re-runs) so biome treats src as unused.
+ // the terminal-state signal dismisses the skeleton in that case.
+ // Re-running on src change resets both flags when the same instance is
+ // reused with a new src (e.g. AssetPreview switching assets).
+ // biome-ignore lint/correctness/useExhaustiveDependencies: src drives the reactive trigger only; the effect body reads imgRef.current so biome flags src as unused.
useLayoutEffect(() => {
const img = imgRef.current;
if (img?.complete) {
setLoaded(true);
- setHasError(img.naturalWidth === 0);
} else {
setLoaded(false);
- setHasError(false);
}
+ // NOTE: don't try to infer error from `complete && naturalWidth === 0`
+ // — per the HTML spec that shape is also produced by a successful
+ // load of a dimensionless resource (SVG with only a viewBox, images
+ // sized by CSS). onError is the only unambiguous signal.
+ setHasError(false);
}, [src]);
- if (hasError) {
- // A visible placeholder card replaces the browser's default 16x16
- // broken-image glyph so the reader can tell the asset is missing
- // instead of assuming the block rendered empty. Stays a `<span>` for
- // the same phrasing-content reason the slot is — Image.tsx wraps this
- // in `<Zoom wrapElement="span">` and markdown often lands `<img>`
- // inside `<p>`, where `<div>` is forbidden.
- const label = alt && alt.length > 0 ? alt : (src ?? '');
- return (
- <span
- data-testid={slotTestId}
- data-image-error="true"
- role="img"
- aria-label={t`Image failed to load: ${label}`}
- className={cn(
- 'inline-flex max-w-full items-center gap-2 rounded-md border border-dashed border-border bg-muted/40 px-2 py-1 text-muted-foreground',
- slotClassName,
- )}
- style={intrinsic ? slotStyle : undefined}
- >
- <ImageOff aria-hidden="true" className="size-3.5 shrink-0 opacity-70" />
- <span className="text-xs font-medium">{t`Image failed to load`}</span>
- {src ? (
- <span className="max-w-[24ch] truncate font-mono text-[10px] opacity-70" title={src}>
- {src}
- </span>
- ) : null}
- </span>
- );
- }
+ // A visible placeholder overlay replaces the browser's default 16x16
+ // broken-image glyph so the reader can tell the asset is missing instead
+ // of assuming the block rendered empty. The <img> stays mounted (hidden
+ // via CSS) so consumers that inspect the DOM — clipboard walker, prop
+ // panel, e2e tests reading img.src — still find it with the authored
+ // src, matching the storage-layer fidelity contract (bytes land verbatim
+ // in the CRDT even when the render layer shows a fallback).
+ //
+ // Always announce on error: `alt` at this layer conflates "author opted
+ // in to decorative" with "no alt was authored" (Image.tsx coerces
+ // `props.alt ?? ''`, and `![](/x.png)` markdown reaches here with
+ // alt=''). Silencing the pill for alt='' would silence broken
+ // no-alt-authored images too.
+ const errorLabel = alt && alt.length > 0 ? alt : (src ?? '');
return (
<span
data-testid={slotTestId}
+ data-image-error={hasError ? 'true' : undefined}
className={cn(
'relative inline-block overflow-hidden',
// Pre-load only: reserve a 16:9 slot to prevent the "0x0 box → reflow"
@@ -118,12 +102,12 @@ export function LoadingImage({
// object-contain / max-h-full styling can govern the image's
// natural shape — otherwise sidebar previews would be locked at 16:9
// forever, letterboxing portrait assets.
- !intrinsic && !loaded && 'aspect-[16/9] w-full max-w-full',
+ !intrinsic && !loaded && !hasError && 'aspect-[16/9] w-full max-w-full',
slotClassName,
)}
style={slotStyle}
>
- {!loaded && (
+ {!loaded && !hasError && (
// Inline-content the skeleton element directly rather than reaching for
// shadcn `<Skeleton>` (which is a `<div>`). The slot is a `<span>`
// because `Image.tsx`'s `<Zoom wrapElement="span">` constrains its
@@ -146,6 +130,10 @@ export function LoadingImage({
alt={alt}
width={width}
height={height}
+ // `hidden` keeps the img in the DOM (queryable by tests + the
+ // clipboard walker) but out of the visual + a11y trees when the
+ // error placeholder is showing.
+ hidden={hasError || undefined}
className={cn(
'block max-w-full transition-opacity motion-reduce:transition-none',
loaded ? 'opacity-100' : 'opacity-0',
@@ -157,7 +145,7 @@ export function LoadingImage({
onLoad?.(event);
}}
onError={(event) => {
- // Route into the placeholder branch on next render — the
+ // Route into the placeholder overlay on next render — the
// skeleton also dismisses so screen readers stop announcing
// aria-busy="true" forever.
setLoaded(true);
@@ -165,6 +153,21 @@ export function LoadingImage({
onError?.(event);
}}
/>
+ {hasError && (
+ <span
+ role="img"
+ aria-label={t`Image failed to load: ${errorLabel}`}
+ className="inline-flex max-w-full items-center gap-2 rounded-md border border-dashed border-border bg-muted/40 px-2 py-1 text-muted-foreground"
+ >
+ <ImageOff aria-hidden="true" className="size-3.5 shrink-0 opacity-70" />
+ <span className="text-xs font-medium">{t`Image failed to load`}</span>
+ {src ? (
+ <span className="max-w-[24ch] truncate font-mono text-xs opacity-70" title={src}>
+ {src}
+ </span>
+ ) : null}
+ </span>
+ )}
</span>
);
}
diff --git a/packages/app/src/editor/components/Image.dom.test.tsx b/packages/app/src/editor/components/Image.dom.test.tsx
index 3fd5d763a..698312ba7 100644
--- a/packages/app/src/editor/components/Image.dom.test.tsx
+++ b/packages/app/src/editor/components/Image.dom.test.tsx
@@ -119,16 +119,15 @@ describe('Image — loading-state placeholder (PRD-6638)', () => {
expect(screen.queryByTestId('image-loading-skeleton')).toBeNull();
});
- test('dismisses placeholder when the image is already complete at mount (covers cached-success and cached-failure)', () => {
+ test('dismisses placeholder when the image is already complete at mount', () => {
// Cached images may have `complete=true` at first paint and the `load`
// event may not re-fire after React commits — the skeleton would stay
- // visible forever and the <img> stuck at opacity-0. This covers both
- // cached-success (`complete=true, naturalWidth>0`) and cached-failure
- // (`complete=true, naturalWidth=0`) because the SUT treats `complete`
- // alone as the terminal-state signal — `naturalWidth` is intentionally
- // not consulted (so cached failures whose `onerror` won't re-fire still
- // dismiss the skeleton, letting the browser's native broken-image
- // indicator become visible).
+ // visible forever and the <img> stuck at opacity-0. The SUT treats
+ // `complete` alone as the terminal-state signal; `naturalWidth` is
+ // NOT consulted at mount (it can't distinguish a failed fetch from a
+ // dimensionless SVG, so onError is the only unambiguous error signal
+ // and cached-broken images fall through to the browser's default
+ // broken-image glyph).
// jsdom's preload doesn't expose HTMLImageElement on globalThis, so
// reach through `window` to override the prototype getters.
const ImgProto = (window as Window).HTMLImageElement.prototype;
@@ -148,6 +147,49 @@ describe('Image — loading-state placeholder (PRD-6638)', () => {
}
});
+ test('broken image always renders role=img + aria-label (alt="" no longer silences)', () => {
+ // alt="" at this layer conflates the WCAG decorative opt-in with the
+ // "no alt authored" case (Image.tsx coerces `props.alt ?? ''`, and
+ // `![](/x.png)` markdown reaches here with alt=''). Announcing on
+ // both is the safer default — otherwise broken no-alt-authored
+ // images fall silent to assistive tech.
+ const { container } = render(<Image src="/missing.png" alt="" width={400} height={300} />);
+ fireEvent.error(container.querySelector('img') as HTMLImageElement);
+ const slot = screen.getByTestId('image-slot');
+ expect(slot.getAttribute('data-image-error')).toBe('true');
+ // Placeholder overlay carries the ARIA — the slot's img is kept in
+ // DOM (hidden) so consumers can still inspect src.
+ const overlay = slot.querySelector('[role="img"]');
+ expect(overlay).not.toBeNull();
+ expect(overlay?.getAttribute('aria-label')).toBe('Image failed to load: /missing.png');
+ expect(slot.getAttribute('aria-hidden')).toBeNull();
+ // Img stays mounted (hidden) so tests + walkers can still find its src.
+ const img = slot.querySelector('img');
+ expect(img).not.toBeNull();
+ expect(img?.hasAttribute('hidden')).toBe(true);
+ expect(img?.getAttribute('src')).toBe('/missing.png');
+ });
+
+ test('non-decorative broken image (alt="...") uses alt in the aria-label', () => {
+ // Symmetric coverage: pin role=img + aria-label + no aria-hidden on
+ // the alt-provided branch, so a future refactor can't silently drop
+ // screen-reader semantics from either shape.
+ const { container } = render(
+ <Image src="/missing.png" alt="a cat photo" width={400} height={300} />,
+ );
+ fireEvent.error(container.querySelector('img') as HTMLImageElement);
+ const slot = screen.getByTestId('image-slot');
+ const overlay = slot.querySelector('[role="img"]');
+ expect(overlay?.getAttribute('aria-label')).toBe('Image failed to load: a cat photo');
+ expect(slot.getAttribute('aria-hidden')).toBeNull();
+ // Img stays mounted (hidden) in the alt-provided branch too, so DOM
+ // inspectors can still find src regardless of alt shape.
+ const img = slot.querySelector('img');
+ expect(img).not.toBeNull();
+ expect(img?.hasAttribute('hidden')).toBe(true);
+ expect(img?.getAttribute('src')).toBe('/missing.png');
+ });
+
test('renders a visible placeholder card after the inner <img>.error event fires (broken image)', () => {
// The browser's default broken-image glyph is a 16x16 icon that reads as
// "the block rendered empty" — the reporter's ask was for something
@@ -165,7 +207,7 @@ describe('Image — loading-state placeholder (PRD-6638)', () => {
expect(img).not.toBeNull();
fireEvent.error(img as HTMLImageElement);
- // Skeleton gone, placeholder card mounted, src surfaced for triage.
+ // Skeleton gone, placeholder overlay mounted, src surfaced for triage.
expect(screen.queryByTestId('image-loading-skeleton')).toBeNull();
const slot = screen.getByTestId('image-slot');
expect(slot.getAttribute('data-image-error')).toBe('true');
@@ -173,6 +215,11 @@ describe('Image — loading-state placeholder (PRD-6638)', () => {
expect(slot.textContent).toContain('/missing-asset.png');
// Stays inline for phrasing-content compatibility with <p>.
expect(slot.tagName).toBe('SPAN');
+ // Img stays mounted (hidden) so DOM inspectors still find src.
+ const imgAfterError = slot.querySelector('img');
+ expect(imgAfterError).not.toBeNull();
+ expect(imgAfterError?.getAttribute('src')).toBe('/missing-asset.png');
+ expect(imgAfterError?.hasAttribute('hidden')).toBe(true);
});
test('restores the placeholder when src changes (e.g. AssetPreview switching assets)', () => {
@@ -192,4 +239,28 @@ describe('Image — loading-state placeholder (PRD-6638)', () => {
expect(screen.queryByTestId('image-loading-skeleton')).not.toBeNull();
});
+
+ test('src change after an error clears the error placeholder', () => {
+ // The mount-time effect resets hasError on src change; without this,
+ // an AssetPreview that hits a broken asset first would stay pinned on
+ // the "Image failed to load" pill for every subsequent selection.
+ const { container, rerender } = render(
+ <Image src="/missing.png" alt="broken" width={400} height={300} />,
+ );
+ fireEvent.error(container.querySelector('img') as HTMLImageElement);
+ expect(screen.getByTestId('image-slot').getAttribute('data-image-error')).toBe('true');
+
+ rerender(<Image src="/assets/works.png" alt="works" width={400} height={300} />);
+ // Placeholder cleared; back to the loading-state slot.
+ expect(screen.getByTestId('image-slot').getAttribute('data-image-error')).toBeNull();
+ // loaded was also reset — skeleton must reappear for the new src or
+ // the '0x0 box → bytes arrive → reflow' layout shift would silently
+ // recur when a broken image is followed by a good one.
+ expect(screen.queryByTestId('image-loading-skeleton')).not.toBeNull();
+ // hidden was also cleared — the <img> must be visible for the new src.
+ // Pins the inverse of the error-state assertions (lines 169, 189, 222)
+ // so the recovery path can't silently regress.
+ const imgAfterRecovery = screen.getByTestId('image-slot').querySelector('img');
+ expect(imgAfterRecovery?.hasAttribute('hidden')).toBe(false);
+ });
});
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index eabc90c0f..872555a4e 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -1839,7 +1839,6 @@
"U6wmNc": ["Sync paused"],
"U88xbi": ["Failed to create the schema file"],
"U8CD-l": ["Copy full path, No workspace"],
- "U8sPsM": ["Image failed to load: ", ["label"]],
"U9tm58": ["Hide problem indicators"],
"UBv8UK": ["Delete Permanently"],
"UDFrWm": ["Checking GitHub connection..."],
@@ -3343,6 +3342,7 @@
"qjHMHf": ["Failed to disable sync — ", ["detail"]],
"qkqG0b": ["Take upstream"],
"qlAIQ1": ["Remote"],
+ "qlnfTD": ["Image failed to load: ", ["errorLabel"]],
"qmL1UG": ["Uploading securely"],
"qo4zCg": ["Path cannot contain backslashes"],
"qpQwGC": ["Describe what you're working on and the agent sets it up for you."],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 7914c5f32..d7ec739ca 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -5598,8 +5598,8 @@ msgid "Image failed to load"
msgstr "Image failed to load"
#: src/components/ui/loading-image.tsx
-msgid "Image failed to load: {label}"
-msgstr "Image failed to load: {label}"
+msgid "Image failed to load: {errorLabel}"
+msgstr "Image failed to load: {errorLabel}"
#: src/components/ImportSkillForm.tsx
msgid "Import"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index ee7d614ef..d1ad8c45a 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -1839,7 +1839,6 @@
"U6wmNc": ["Śŷńć ƥàũśēď"],
"U88xbi": ["Ƒàĩĺēď ţō ćŕēàţē ţĥē śćĥēḿà ƒĩĺē"],
"U8CD-l": ["Ćōƥŷ ƒũĺĺ ƥàţĥ, Ńō ŵōŕķśƥàćē"],
- "U8sPsM": ["Ĩḿàĝē ƒàĩĺēď ţō ĺōàď: ", ["label"]],
"U9tm58": ["Ĥĩďē ƥŕōƀĺēḿ ĩńďĩćàţōŕś"],
"UBv8UK": ["Ďēĺēţē Ƥēŕḿàńēńţĺŷ"],
"UDFrWm": ["Ćĥēćķĩńĝ ĜĩţĤũƀ ćōńńēćţĩōń..."],
@@ -3343,6 +3342,7 @@
"qjHMHf": ["Ƒàĩĺēď ţō ďĩśàƀĺē śŷńć — ", ["detail"]],
"qkqG0b": ["Ţàķē ũƥśţŕēàḿ"],
"qlAIQ1": ["Ŕēḿōţē"],
+ "qlnfTD": ["Ĩḿàĝē ƒàĩĺēď ţō ĺōàď: ", ["errorLabel"]],
"qmL1UG": ["Ũƥĺōàďĩńĝ śēćũŕēĺŷ"],
"qo4zCg": ["Ƥàţĥ ćàńńōţ ćōńţàĩń ƀàćķśĺàśĥēś"],
"qpQwGC": ["Ďēśćŕĩƀē ŵĥàţ ŷōũ'ŕē ŵōŕķĩńĝ ōń àńď ţĥē àĝēńţ śēţś ĩţ ũƥ ƒōŕ ŷōũ."],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index e30a71bb8..8eae387d6 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -5594,7 +5594,7 @@ msgid "Image failed to load"
msgstr ""
#: src/components/ui/loading-image.tsx
-msgid "Image failed to load: {label}"
+msgid "Image failed to load: {errorLabel}"
msgstr ""
#: src/components/ImportSkillForm.tsx