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

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

@@ -0,0 +1,93 @@
+/**
+ * @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'
+const KEY = 'workspace/7727ef3f/screenshot.png'
+
+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, keyed to the content version', async () => {
+    const res = await PATCH(buildRequest({ key: KEY, width: 1600, height: 900 }), routeContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ success: true })
+    expect(mockUpdateWorkspaceFileDimensions).toHaveBeenCalledWith(WS, FILE, {
+      key: KEY,
+      width: 1600,
+      height: 900,
+    })
+  })
+
+  it('allows an admin', async () => {
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('admin')
+    const res = await PATCH(buildRequest({ key: KEY, width: 10, height: 20 }), routeContext)
+    expect(res.status).toBe(200)
+    expect(mockUpdateWorkspaceFileDimensions).toHaveBeenCalledOnce()
+  })
+
+  it('reports success:false when the content-version guard rejects the write (key changed)', async () => {
+    mockUpdateWorkspaceFileDimensions.mockResolvedValue(false)
+    const res = await PATCH(buildRequest({ key: KEY, width: 10, height: 20 }), routeContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ success: false })
+  })
+
+  it('rejects an unauthenticated caller before touching the DB', async () => {
+    authMockFns.mockGetSession.mockResolvedValue(null)
+    const res = await PATCH(buildRequest({ key: KEY, 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({ key: KEY, width: 10, height: 10 }), routeContext)
+    expect(res.status).toBe(403)
+    expect(mockUpdateWorkspaceFileDimensions).not.toHaveBeenCalled()
+  })
+
+  it('rejects a missing key or non-positive / non-integer dimensions', async () => {
+    for (const body of [
+      { width: 10, height: 10 }, // missing key
+      { key: KEY, width: 0, height: 10 },
+      { key: KEY, width: 10, height: -5 },
+      { key: KEY, width: 10.5, height: 10 },
+      { key: KEY, 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,57 @@
+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
+ *
+ * Store 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. The write commits whenever the row
+ * still holds the measured storage key, overwriting any stale value so a wrong size self-corrects; the
+ * client reports only on a real mismatch, so this is not storm-y despite not being a backfill-once no-op.
+ */
+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 { key, 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 {
+      // `written` is false when the content-version guard rejected the write (the row's storage key no
+      // longer matches the key the client measured — the content was replaced since). That is not an
+      // error; the client's next measurement, once its file list has the new key, persists correctly.
+      const written = await updateWorkspaceFileDimensions(workspaceId, fileId, {
+        key,
+        width,
+        height,
+      })
+      return NextResponse.json({ success: written })
+    } catch (error) {
+      logger.error('Failed to store 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,15 +1,18 @@
-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'
 
 const MIN_WIDTH = 64
 
+/** A bare pixel count (`"640"`) that needs a `px` suffix, vs. an already-unit'd width (`"50%"`). */
+const BARE_PIXEL_WIDTH = /^\d+$/
+
 /**
  * Drag-to-resize image node view (handle at the bottom-right, revealed on selection). Dragging
  * commits the new pixel width to the `width` attribute, which serializes to `<img width>`.
@@ -24,6 +27,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 +41,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()
@@ -69,16 +86,34 @@ function ResizableImageView({ node, updateAttributes, selected, editor }: ReactN
   }
 
   const committedWidth = attrs.width
-    ? /^\d+$/.test(attrs.width)
+    ? BARE_PIXEL_WIDTH.test(attrs.width)
       ? `${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]
+  )
+  // The browser's post-load measurement is authoritative — EXIF-corrected, and correct even when the
+  // stored value is stale (e.g. left over after the file's content was replaced) — so it wins once
+  // available; stored metadata only reserves the box pre-load. Equal in the common case, so no shift.
+  const intrinsicDimensions = measuredDimensions ?? storedDimensions
+  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 +134,28 @@ 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
+        // The browser's measurement is authoritative. Reserve from it and persist whenever the stored
+        // metadata is absent or disagrees (EXIF-rotated, or stale after a content swap), so a wrong value
+        // self-corrects instead of sticking. Compare the memoized `storedDimensions` the render uses, NOT
+        // a fresh cache read — the memo is non-reactive, and this keeps the guard consistent with render.
+        if (
+          storedDimensions &&
+          storedDimensions.width === naturalWidth &&
+          storedDimensions.height === naturalHeight
+        ) {
+          return
+        }
+        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 '@/hooks/queries/utils/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)
+}