diff --git a/docs/systems/embeds.md b/docs/systems/embeds.md
index 5ef3e83c..02c6853c 100644
--- a/docs/systems/embeds.md
+++ b/docs/systems/embeds.md
@@ -394,9 +394,11 @@ Two modes based on whether a provider is present:
 
 ### ImageEmbed
 
-- Renders `<img>` with `max-w-[400px]`, `max-h-[300px]`, `loading="lazy"`, `referrerPolicy="no-referrer"`
-- Image source: `embed.image ?? embed.url`
-- Click opens image preview lightbox via `useUIStore.openImagePreview()`
+- When `embed.width && embed.height` are populated: wraps the `<img>` in a sized container with `style={{ aspectRatio: ${width}/${height}, maxWidth: Math.min(width, 400), maxHeight: 300 }}` (mirrors `AttachmentRenderer.tsx:81-100`). Eliminates layout shift on image load.
+- When dimensions are null: no wrapper sizing, no fallback aspect-ratio. Inner `<img>` renders within `max-w-[400px]`, `max-h-[300px]`. The absent fallback is deliberate — see the *Dimension reservation contract* section below.
+- Inner `<img>`: `object-contain`, `loading="lazy"`, `referrerPolicy="no-referrer"`.
+- Image source: `embed.image ?? embed.url`.
+- Click opens image preview lightbox via `useUIStore.openImagePreview()`.
 
 ### RichEmbed (Spotify)
 
diff --git a/docs/systems/message-list.md b/docs/systems/message-list.md
index 5c3a2171..6e2b03e5 100644
--- a/docs/systems/message-list.md
+++ b/docs/systems/message-list.md
@@ -42,7 +42,7 @@ When dimensions are not known (probe failed, no OG tags, non-image type), the re
 Renderers known to satisfy the contract today:
 - `AttachmentRenderer.tsx` — reserves from `attachment.width/height`.
 - `embeds/ImageEmbed.tsx` — reserves from `embed.width/height` when populated.
-- `embeds/VideoEmbed.tsx` — fixed 16:9 padding-bottom for the iframe area.
+- `embeds/VideoEmbed.tsx` — fixed 16:9 reservation for both branches: `aspectRatio: '16/9'` for the direct-video container, `paddingBottom: 56.25%` for the provider-iframe container.
 - `embeds/RichEmbed.tsx` — explicit `height` from `getIframeHeight()`; fixed 80×80 thumbnail in collapsed state.
 - `embeds/GenericEmbed.tsx` — fixed 80×80 thumbnail.