fix(files): reserve image layout space so images stop reflowing on load

A markdown image with no stored dimensions reserved zero vertical space until
it downloaded, then snapped to its natural height and pushed content below it
down (cumulative layout shift). Reserve the box up front from the image's
intrinsic aspect ratio instead.

Store intrinsic width/height as workspace_file metadata (not in the markdown —
it stays clean `![](src)`), read it synchronously from the already-loaded file
list to reserve a responsive aspect-ratio box on first render, and lazily
backfill it once per image on first view via a write-gated, idempotent PATCH.
The node view falls back to on-load measurement for the first-ever view and for
external images. Images stay fluid (max-width:100%, height:auto).

Author: waleedlatif1

apps/sim/app/api/workspaces/[id]/files/[fileId]/dimensions/route.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @vitest-environment node
+ */
+import { authMockFns, permissionsMock, permissionsMockFns } from '@sim/testing'
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockUpdateWorkspaceFileDimensions } = vi.hoisted(() => ({
+  mockUpdateWorkspaceFileDimensions: vi.fn(),
+}))
+
+vi.mock('@/lib/uploads/contexts/workspace/workspace-file-manager', () => ({
+  updateWorkspaceFileDimensions: mockUpdateWorkspaceFileDimensions,
+}))
+vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
+
+const WS = '7727ef3f-8cf6-4686-b063-2bb006a10785'
+const FILE = 'wf_abc123'
+
+import { PATCH } from '@/app/api/workspaces/[id]/files/[fileId]/dimensions/route'
+
+const routeContext = { params: Promise.resolve({ id: WS, fileId: FILE }) }
+
+function buildRequest(body: unknown): NextRequest {
+  return new NextRequest(`http://localhost/api/workspaces/${WS}/files/${FILE}/dimensions`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+describe('PATCH /api/workspaces/[id]/files/[fileId]/dimensions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    authMockFns.mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('write')
+    mockUpdateWorkspaceFileDimensions.mockResolvedValue(true)
+  })
+
+  it('stores dimensions for a writer', async () => {
+    const res = await PATCH(buildRequest({ width: 1600, height: 900 }), routeContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ success: true })
+    expect(mockUpdateWorkspaceFileDimensions).toHaveBeenCalledWith(WS, FILE, {
+      width: 1600,
+      height: 900,
+    })
+  })
+
+  it('allows an admin', async () => {
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('admin')
+    const res = await PATCH(buildRequest({ width: 10, height: 20 }), routeContext)
+    expect(res.status).toBe(200)
+    expect(mockUpdateWorkspaceFileDimensions).toHaveBeenCalledOnce()
+  })
+
+  it('rejects an unauthenticated caller before touching the DB', async () => {
+    authMockFns.mockGetSession.mockResolvedValue(null)
+    const res = await PATCH(buildRequest({ width: 10, height: 10 }), routeContext)
+    expect(res.status).toBe(401)
+    expect(mockUpdateWorkspaceFileDimensions).not.toHaveBeenCalled()
+  })
+
+  it('rejects a read-only member (backfill requires write)', async () => {
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('read')
+    const res = await PATCH(buildRequest({ width: 10, height: 10 }), routeContext)
+    expect(res.status).toBe(403)
+    expect(mockUpdateWorkspaceFileDimensions).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-positive / non-integer dimensions', async () => {
+    for (const body of [
+      { width: 0, height: 10 },
+      { width: 10, height: -5 },
+      { width: 10.5, height: 10 },
+      { width: 10 },
+    ]) {
+      const res = await PATCH(buildRequest(body), routeContext)
+      expect(res.status).toBe(400)
+    }
+    expect(mockUpdateWorkspaceFileDimensions).not.toHaveBeenCalled()
+  })
+})

apps/sim/app/api/workspaces/[id]/files/[fileId]/dimensions/route.ts

@@ -0,0 +1,49 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { updateWorkspaceFileDimensionsContract } from '@/lib/api/contracts/workspace-files'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { updateWorkspaceFileDimensions } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+const logger = createLogger('WorkspaceFileDimensionsAPI')
+
+/**
+ * PATCH /api/workspaces/[id]/files/[fileId]/dimensions
+ *
+ * Backfill an image file's intrinsic pixel dimensions — a pure rendering hint the editor uses to reserve
+ * layout space before the image loads. Requires write permission and is idempotent (a no-op once the
+ * dimensions are already stored), so the client can fire it once per image without coordination.
+ */
+export const PATCH = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string; fileId: string }> }) => {
+    const session = await getSession()
+    if (!session?.user?.id) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const parsed = await parseRequest(updateWorkspaceFileDimensionsContract, request, context)
+    if (!parsed.success) return parsed.response
+    const { id: workspaceId, fileId } = parsed.data.params
+    const { width, height } = parsed.data.body
+
+    const permission = await getUserEntityPermissions(session.user.id, 'workspace', workspaceId)
+    if (permission !== 'admin' && permission !== 'write') {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 })
+    }
+
+    try {
+      await updateWorkspaceFileDimensions(workspaceId, fileId, { width, height })
+      return NextResponse.json({ success: true as const })
+    } catch (error) {
+      logger.error('Failed to backfill workspace file dimensions', {
+        workspaceId,
+        fileId,
+        error: getErrorMessage(error),
+      })
+      return NextResponse.json({ error: 'Failed to update dimensions' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/file-viewer.tsx

@@ -5,7 +5,11 @@ import { Music } from '@sim/emcn/icons'
 import dynamic from 'next/dynamic'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
 import { getFileExtension } from '@/lib/uploads/utils/file-utils'
-import { useWorkspaceFileBinary, useWorkspaceFileContent } from '@/hooks/queries/workspace-files'
+import {
+  useWorkspaceFileBinary,
+  useWorkspaceFileContent,
+  useWorkspaceImageDimensionsAdapter,
+} from '@/hooks/queries/workspace-files'
 import {
   createWorkspaceFileContentSource,
   type FileContentSource,
@@ -126,9 +130,10 @@ interface FileViewerProps {
 
 export function FileViewer(props: FileViewerProps) {
   const { contentSource, workspaceId } = props
+  const imageDimensions = useWorkspaceImageDimensionsAdapter(workspaceId)
   const source = useMemo(
-    () => contentSource ?? createWorkspaceFileContentSource(workspaceId),
-    [contentSource, workspaceId]
+    () => contentSource ?? createWorkspaceFileContentSource(workspaceId, imageDimensions),
+    [contentSource, workspaceId, imageDimensions]
   )
   return (
     <FileContentSourceProvider value={source}>

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/rich-markdown-editor/image.tsx

@@ -1,9 +1,9 @@
-import { useEffect, useRef, useState } from 'react'
+import { type CSSProperties, useEffect, useMemo, useRef, useState } from 'react'
 import { cn } from '@sim/emcn'
 import { NodeSelection, Plugin } from '@tiptap/pm/state'
 import type { ReactNodeViewProps } from '@tiptap/react'
 import { NodeViewWrapper, ReactNodeViewRenderer } from '@tiptap/react'
-import { useFileContentSource } from '@/hooks/use-file-content-source'
+import { type ImageDimensions, useFileContentSource } from '@/hooks/use-file-content-source'
 import { MarkdownImage } from './image-schema'
 import { normalizeLinkHref } from './markdown-fidelity'
 import { useEditorEditable } from './use-editor-editable'
@@ -24,6 +24,11 @@ function ResizableImageView({ node, updateAttributes, selected, editor }: ReactN
   const [dragWidth, setDragWidth] = useState<number | null>(null)
   /** Whether the current src failed to load; reset on src change so a retried/edited src can load. */
   const [failed, setFailed] = useState(false)
+  /**
+   * Intrinsic dimensions measured from the loaded image — holds the aspect-ratio box for THIS view when
+   * the content source has no stored dimensions yet (the first-ever view of an image). Reset on src change.
+   */
+  const [measuredDimensions, setMeasuredDimensions] = useState<ImageDimensions | null>(null)
   const attrs = node.attrs as {
     src?: string
     alt?: string
@@ -33,7 +38,16 @@ function ResizableImageView({ node, updateAttributes, selected, editor }: ReactN
   }
 
   useEffect(() => () => dragAbortRef.current?.abort(), [])
-  useEffect(() => setFailed(false), [attrs.src])
+
+  // Reset the load-failure flag and this-session measurement when the src changes — adjusted during
+  // render (not in an effect) so the previous image's aspect-ratio box never paints for a frame. A `key`
+  // remount isn't available here: TipTap owns this node view's instantiation.
+  const [prevSrc, setPrevSrc] = useState(attrs.src)
+  if (prevSrc !== attrs.src) {
+    setPrevSrc(attrs.src)
+    setFailed(false)
+    setMeasuredDimensions(null)
+  }
 
   const startResize = (event: React.PointerEvent) => {
     event.preventDefault()
@@ -73,12 +87,27 @@ function ResizableImageView({ node, updateAttributes, selected, editor }: ReactN
       ? `${attrs.width}px`
       : attrs.width
     : undefined
-  const widthStyle =
+  // Stored intrinsic dimensions reserve the box on the very first render. Memoized on the src (not the
+  // live drag width) so a resize drag never re-scans the file list. Falls back to what we measured on
+  // load this session for a first-ever view the metadata hasn't caught up on.
+  const storedDimensions = useMemo(
+    () => source.getImageDimensions?.(attrs.src) ?? null,
+    [source, attrs.src]
+  )
+  const intrinsicDimensions = storedDimensions ?? measuredDimensions
+  const displayWidth =
     dragWidth !== null
-      ? { width: `${dragWidth}px` }
-      : committedWidth
-        ? { width: committedWidth }
-        : undefined
+      ? `${dragWidth}px`
+      : (committedWidth ?? (intrinsicDimensions ? `${intrinsicDimensions.width}px` : undefined))
+  // width + aspect-ratio (with `max-w-full`/`h-auto` from the class list) reserves a responsive box the
+  // image can't reflow into, per the CLS-avoidance pattern for known-ratio responsive images. React drops
+  // the undefined keys, so an unmeasured image simply gets no reservation (its prior behavior).
+  const imageStyle: CSSProperties = {
+    width: displayWidth,
+    aspectRatio: intrinsicDimensions
+      ? `${intrinsicDimensions.width} / ${intrinsicDimensions.height}`
+      : undefined,
+  }
 
   // Sanitize the linked-image target before rendering the anchor — a parsed markdown href is
   // untrusted and could be `javascript:`/`data:`; an unsafe value drops the link (image only).
@@ -99,11 +128,21 @@ function ResizableImageView({ node, updateAttributes, selected, editor }: ReactN
       // the resize button sits outside this element, so it keeps its own pointer behavior.)
       draggable={editable}
       data-drag-handle={editable ? '' : undefined}
-      style={widthStyle}
+      style={imageStyle}
       onError={() => setFailed(true)}
-      onLoad={() => setFailed(false)}
+      onLoad={(event) => {
+        setFailed(false)
+        const { naturalWidth, naturalHeight } = event.currentTarget
+        if (naturalWidth <= 0 || naturalHeight <= 0) return
+        // Already reserved from stored metadata (possibly just backfilled by a sibling view) — done.
+        if (source.getImageDimensions?.(attrs.src)) return
+        // Hold the box for this first-ever view, and persist so later views reserve before load. The
+        // report is idempotent and de-duped downstream (stored-check + server `width IS NULL`).
+        setMeasuredDimensions({ width: naturalWidth, height: naturalHeight })
+        source.reportImageDimensions?.(attrs.src, { width: naturalWidth, height: naturalHeight })
+      }}
       className={cn(
-        'block max-w-full rounded-lg border border-[var(--border)]',
+        'block h-auto max-w-full rounded-lg border border-[var(--border)]',
         editable && 'cursor-grab',
         failed &&
           'min-h-[72px] min-w-[140px] bg-[var(--surface-5)] p-3 text-[var(--text-muted)] text-caption'

apps/sim/hooks/queries/utils/find-workspace-file-by-src.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
+import { findWorkspaceFileBySrc } from './find-workspace-file-by-src'
+
+function record(over: Partial<WorkspaceFileRecord>): WorkspaceFileRecord {
+  return { id: 'wf_x', key: 'workspace/ws1/x.png', ...over } as WorkspaceFileRecord
+}
+
+const records = [
+  record({ id: 'wf_a', key: 'workspace/ws1/a.png' }),
+  record({ id: 'wf_b', key: 'workspace/ws1/b.png' }),
+]
+
+const serveUrl = (key: string) => `/api/files/serve/${encodeURIComponent(key)}?context=workspace`
+
+describe('findWorkspaceFileBySrc', () => {
+  it('matches a serve URL by storage key', () => {
+    expect(findWorkspaceFileBySrc(records, serveUrl('workspace/ws1/b.png'))?.id).toBe('wf_b')
+  })
+
+  it('matches a /api/files/view/<id> URL by file id', () => {
+    expect(findWorkspaceFileBySrc(records, '/api/files/view/wf_a')?.id).toBe('wf_a')
+  })
+
+  it('matches a /workspace/<ws>/files/<id> URL by file id', () => {
+    expect(findWorkspaceFileBySrc(records, '/workspace/ws1/files/wf_b')?.id).toBe('wf_b')
+  })
+
+  it('returns undefined for a serve URL whose key is not in the list', () => {
+    expect(findWorkspaceFileBySrc(records, serveUrl('workspace/ws1/missing.png'))).toBeUndefined()
+  })
+
+  it('returns undefined for external, data:, and undefined srcs', () => {
+    expect(findWorkspaceFileBySrc(records, 'https://example.com/x.png')).toBeUndefined()
+    expect(findWorkspaceFileBySrc(records, 'data:image/png;base64,AAAA')).toBeUndefined()
+    expect(findWorkspaceFileBySrc(records, undefined)).toBeUndefined()
+  })
+
+  it('returns undefined when the file list has not loaded yet', () => {
+    expect(findWorkspaceFileBySrc(undefined, '/api/files/view/wf_a')).toBeUndefined()
+  })
+})

apps/sim/hooks/queries/utils/find-workspace-file-by-src.ts

@@ -0,0 +1,19 @@
+import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
+import { extractEmbeddedFileRef } from '@/lib/uploads/utils/embedded-image-ref'
+
+/**
+ * Resolve the workspace file record an embedded image `src` points at, matching the persisted serve-URL
+ * shape by storage key or file id. Returns `undefined` for external / `data:` / unrecognized srcs, and
+ * when the file list isn't loaded — callers then fall back to on-load measurement rather than reserving
+ * from metadata.
+ */
+export function findWorkspaceFileBySrc(
+  records: WorkspaceFileRecord[] | undefined,
+  src: string | undefined
+): WorkspaceFileRecord | undefined {
+  const ref = src ? extractEmbeddedFileRef(src) : null
+  if (!ref || !records) return undefined
+  return 'key' in ref
+    ? records.find((record) => record.key === ref.key)
+    : records.find((record) => record.id === ref.fileId)
+}

apps/sim/hooks/queries/workspace-files.ts

@@ -1,3 +1,4 @@
+import { useMemo } from 'react'
 import { toast } from '@sim/emcn'
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
@@ -15,6 +16,7 @@ import {
   renameWorkspaceFileContract,
   restoreWorkspaceFileContract,
   updateWorkspaceFileContentContract,
+  updateWorkspaceFileDimensionsContract,
 } from '@/lib/api/contracts/workspace-files'
 import {
   DirectUploadError,
@@ -23,7 +25,8 @@ import {
 } from '@/lib/uploads/client/direct-upload'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
 import type { UserFile } from '@/executor/types'
-import { useFileContentSource } from '@/hooks/use-file-content-source'
+import { findWorkspaceFileBySrc } from '@/hooks/queries/utils/find-workspace-file-by-src'
+import { type ImageDimensionsSource, useFileContentSource } from '@/hooks/use-file-content-source'
 
 const logger = createLogger('WorkspaceFilesQuery')
 
@@ -123,6 +126,47 @@ export function useWorkspaceFiles(
   })
 }
 
+/**
+ * Back the file content source's image-dimension capability with workspace file metadata. Reads intrinsic
+ * dimensions straight from the already-loaded active file list (synchronous, so a stored image reserves
+ * its box on the first render), and lazily backfills them once per image on first measurement. The
+ * backfill is fire-and-forget and idempotent: the optimistic cache patch makes a second measurement of
+ * the same file a no-op locally, and the server ignores an already-populated row — so it never storms,
+ * never blocks render, and never touches the collaborative document.
+ */
+export function useWorkspaceImageDimensionsAdapter(workspaceId: string): ImageDimensionsSource {
+  const queryClient = useQueryClient()
+  return useMemo<ImageDimensionsSource>(() => {
+    const listKey = workspaceFilesKeys.list(workspaceId, 'active')
+    const findRecord = (src: string | undefined): WorkspaceFileRecord | undefined =>
+      findWorkspaceFileBySrc(queryClient.getQueryData<WorkspaceFileRecord[]>(listKey), src)
+    return {
+      getImageDimensions: (src) => {
+        const record = findRecord(src)
+        return record?.width != null && record.height != null
+          ? { width: record.width, height: record.height }
+          : null
+      },
+      reportImageDimensions: (src, dimensions) => {
+        const record = findRecord(src)
+        // Skip when the file isn't ours to key (external/unlisted) or its dimensions are already stored.
+        if (!record || (record.width != null && record.height != null)) return
+        const patch = (width: number | null, height: number | null) =>
+          queryClient.setQueryData<WorkspaceFileRecord[]>(listKey, (previous) =>
+            previous?.map((entry) => (entry.id === record.id ? { ...entry, width, height } : entry))
+          )
+        // Optimistically populate the cache so this and sibling views reserve space immediately and a
+        // concurrent measurement of the same file short-circuits above.
+        patch(dimensions.width, dimensions.height)
+        void requestJson(updateWorkspaceFileDimensionsContract, {
+          params: { id: workspaceId, fileId: record.id },
+          body: dimensions,
+        }).catch(() => patch(null, null))
+      },
+    }
+  }, [queryClient, workspaceId])
+}
+
 /**
  * Fetch file content as text via a content-source URL
  */