From 9aa40c03046553fceeaebcd5588aede35e4a03dc Mon Sep 17 00:00:00 2001
From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com>
Date: Sat, 25 Apr 2026 13:15:14 +0200
Subject: [PATCH] docs: refresh stale embed renderer descriptions after Task 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Final-review reviewer flagged two minor staleness items:
- embeds.md §10 ImageEmbed bullets still described the pre-Task-1
  shape (no wrapper, no aspect-ratio). Replaced with the actual
  current shape, with an explicit pointer to the Dimension
  reservation contract section that explains why the dims-null
  branch deliberately has no fallback.
- message-list.md said VideoEmbed uses "padding-bottom" without
  noting the direct-video branch uses aspectRatio. Now describes
  both branches explicitly.

No code changes; both are documentation-only touch-ups.
---
 docs/systems/embeds.md       | 8 +++++---
 docs/systems/message-list.md | 2 +-
 2 files changed, 6 insertions(+), 4 deletions(-)

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.