fix(web): keep chat media at a stable size while it loads

[juliusmarminge]

Problem

Assistant markdown images in the chat timeline moved the rows below them two or three times while loading. Between the signed asset URL resolving and the bytes arriving, the <img> was zero height (the w-64 aspect-video placeholder only covered URL resolution), then it jumped to its natural size, and a failure swapped to a one-line chip. Remote https:// images had no loading or error state at all. Both used loading="lazy", which, since LegendList already virtualizes, deferred the fetch until the row was in the viewport, so the jump landed exactly where the user was looking rather than in the offscreen mount buffer. The video failure panel was min-h-28 while its loading and playing states were 16:9.

Fix

• A rehype pass marks an image standalone when it is the sole content of its block (paragraph, list item, cell, root), looking through inline wrappers like a link or emphasis. Standalone images are screenshots and figures; they reserve a 16:9 slot (or the authored width/height) through URL resolution and byte loading, host the <img> invisibly inside it until onLoad, and show the failure state in the same slot. Once decoded the image renders bare again, so its box, hit area, and alignment are exactly its own.
• Images that share a block with text or other images (badge rows, icons in a sentence) skip the slot and stay inline at natural size — a placeholder taller than a 20px badge would move the page more than the badge does.
• decoding="async" instead of loading="lazy", so rows settle in LegendList's mount buffer before they scroll into view.
• The component tracks which URL decoded and callers key it on file identity: a re-signed URL for the same file swaps in behind the decoded bitmap, a null src during re-resolution keeps the last image up, a failure forgets it so the retry loads behind the slot, and a different file starts from the slot.
• MediaVideoPlayer failure panel takes the same aspect-video slot as its loading and playing states, capped at max-h-full so it cannot overflow the file preview pane.

Mobile's ThreadMarkdownImage already does fixed-frame-then-measure, so no change there.

Evidence

Cold load of a seeded thread (3 badges, a linked figure beside text, landscape/portrait/wide workspace screenshots, a remote image, a missing file, a 404 remote image, a missing video) with image responses delayed 4 s, measured with a layout-shift PerformanceObserver armed before the timeline mounted.

	Before	After
Content height while loading → loaded	1448 → 2294 px	2742 → 2953 px
Media layout-shift entries (CLS)	6, total 0.497	1, total 0.013

The one remaining entry is the portrait screenshot growing past its 16:9 slot — the single shift the design accepts.

While images load — before: every image is a zero-height gap; after: standalone images hold their slot, the badge row and linked figure stay inline.

Settled — badges and the linked figure are inline in both; failure states for a missing workspace file, a 404 remote image (previously a broken-image glyph), and a missing video now share the media slot.

Recording — side by side, same throttling.

https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/968fc5e291327df4/t3-media-side-by-side.mp4

Verification

• vp test run on ChatMarkdown.workspace-images.test.tsx (29 passed), ChatMarkdown.test.tsx, MessagesTimeline.test.tsx. New cases: slot classes identical across URL-loading, byte-loading, and failure; a standalone remote image gets the slot; two images in one paragraph stay inline; an image wrapped in a link or emphasis beside text stays inline; an image alone in a list item or a link gets the slot.
• vp lint and vp run typecheck clean for apps/web.
• In-browser: every decoded <img> is a direct child of its <p>/<a> with vertical-align: middle, no wrapper. A delayed URL swap on a decoded image held its box at 271 px for 272 consecutive frames before the new bytes decoded in place.

Model: Claude Fable 5 · Harness: Claude Code in T3 Code

🤖 Generated with Claude Code

Note

Reserve stable 16:9 frames for ChatMarkdown images and MediaVideoPlayer

• Adds HAST helpers in ChatMarkdown.tsx to identify standalone Markdown images and marks them with a dataStandalone attribute.
• Replaces direct image rendering with a stateful ChatMarkdownImage loader that reserves a 16:9 frame while loading or on failure.
• Routes workspace-backed ChatMarkdownAssetImage through the shared loader so they use the same load-aware lifecycle.
• Updates MediaVideoPlayer.tsx to use the same 16:9 layout for failed videos instead of a fixed minimum height.
• Behavioral Change: Removes the old maximum-height class from workspace images; images sharing a block with text remain inline and keep their natural size.

^{Macroscope summarized 6d6472c.}

---

Note

Low Risk
UI-only markdown media rendering and layout; no auth, data, or API contract changes beyond allowed dataStandalone on sanitized images.

Overview
Reduces layout shift in chat markdown by treating figure-like images differently from inline badges/icons.

A rehype pass tags images as dataStandalone when they are the only meaningful content in a block (paragraph, list item, cell, etc.), including when wrapped in a link or emphasis. Standalone images go through new ChatMarkdownImage, which holds a 16:9 frame (or authored width/height) while the signed URL resolves, bytes decode, or load fails; the <img> loads invisibly inside the frame, then renders as a normal image once settled. Inline images in shared blocks skip the frame and keep natural sizing.

ChatMarkdownAssetImage and direct/remote image rendering delegate to ChatMarkdownImage, keyed on asset identity so re-signed URLs can swap without flashing; loading="lazy" is replaced with decoding="async". MediaVideoPlayer failure UI uses the same aspect-video slot as loading/playback. Tests cover standalone vs inline heuristics and stable frames across loading and failure.

^{Reviewed by Cursor Bugbot for commit 6d6472c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.5 KiB	13.5 KiB	+14 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+13 B (+0.2%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.0 KiB	57.0 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	8	8	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.6 KiB	+19 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	−5 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+24 B (+0.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.8 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	8	9	+1 (+12.5%)	21	✅

Baseline: c7dc3cb · PR result: 6d6472c · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit fe104b4. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This changes the default rendering lifecycle and layout of existing chat images, workspace media, and shared video failure states, with substantial new loader and Markdown-tree logic. The production-wide behavior change and new state management merit human review.

^{You can add or adjust custom eligibility rules. Learn more.}