@@ -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()
+  })
+})
@@ -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 })
+    }
+  }
+)
@@ -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}>
 
@@ -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'
 
@@ -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()
+  })
+})
@@ -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)
+}
@@ -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
  */