Images flicker and cause layout shift (CLS) on pages with tables or code blocks

Is there an existing issue for this?

• I have searched the existing issues

This is not related to configuring Outline

• The issue is not related to self-hosting config

Current Behavior

Describe the bug

When opening a document that contains images along with tables or code blocks, the images flicker visibly on initial page load. Images momentarily disappear, surrounding text reflows, and then images reappear — causing significant Cumulative Layout Shift (CLS).

To Reproduce

Create a document with a complex table (e.g., multi-row table with merged or empty cells) near the top Add a code block anywhere in the document Add several block images below the table or code block Open the document in view or edit mode Observe images flickering and text reflowing on load Expected behavior

Images should load in place without causing layout shifts. Space for images should be reserved during initial render.

Observed behavior

Images below a code block flicker due to asynchronous syntax highlighting triggering a DOM reflow Images below a complex table flicker due to column width recalculation Text surrounding images shifts position during the flicker The issue does not occur for images placed above the triggering element (table/code block) Separating inline images into block-level images does not resolve the issue Environment

Outline version: 0.82.x (1.9.2) Deployment: Self-hosted via Docker (outlinewiki/outline:latest) Browser: Tested on Chrome / Edge Proxy: Nginx with proxy_buffering off (confirmed not the cause) Additional context

The root cause appears to be that Outline's ProseMirror renderer does not reserve image dimensions (width/height) during initial layout, causing the browser to reflow when images finish loading. This is compounded by asynchronous syntax highlighting and table column width recalculation triggering additional reflows after initial render.

A workaround exists for code blocks: converting them to plain text eliminates the flicker for images below that block. However, this is not a viable solution at scale.

Reserving image space (e.g., via CSS aspect-ratio or by persisting image dimensions in the document model) would resolve this issue.

Expected Behavior

No response

Steps To Reproduce

No response

Environment

- Outline:
- Browser:

Anything else?

No response