@linktr.ee/messaging-react 4.3.2 → 4.4.0-rc-1787598778

package/src/components/MessageAttachment/Video/index.tsx

@@ -3,7 +3,11 @@ import React from 'react'
 
 import Bubble from '../_shared/Bubble'
 import DismissButton from '../_shared/DismissButton'
-import MediaStackGrid, { type MediaStackTile } from '../_shared/MediaStackGrid'
+import MediaStackGrid, {
+  MEDIA_STACK_MAX_VISIBLE,
+  type MediaStackTile,
+} from '../_shared/MediaStackGrid'
+import { useSingleMediaRatio } from '../_shared/useSingleMediaRatio'
 import { useViewer } from '../_shared/useViewer'
 import VideoViewer, { type VideoViewerItem } from '../_shared/VideoViewer'
 import {
@@ -19,6 +23,12 @@ export interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps {
   src?: string
   /** Poster image — preview shown before playback starts. */
   poster?: string
+  /**
+   * Width ÷ height of the source clip. See `VideoItem.naturalAspectRatio` —
+   * this is the single-`src` convenience form of the same thing, and is what
+   * lets a posterless portrait clip size itself correctly (MES-1353).
+   */
+  naturalAspectRatio?: number
   /** MIME type hint — typed onto the inline `<source>` element. */
   mimeType?: string
   /** Filename used as the viewer dialog's accessible name. */
@@ -51,9 +61,41 @@ export interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps {
   onClick?: (index: number) => boolean | void
 }
 
+/**
+ * A single-video card is sized by its own clip rather than force-cropped
+ * square: Figma draws the same component at 16:9 (`2032:16189`) and 4:3
+ * (`2032:22660`).
+ *
+ * The ratio is taken from `VideoItem.naturalAspectRatio` when the sender
+ * recorded it, and only otherwise measured off the decoded poster. Measuring
+ * the poster alone was not enough: an uploaded clip may have no poster, and a
+ * portrait video then sat in whatever `FALLBACK_ASPECT` guessed. Reading the
+ * dimensions Stream already stores costs nothing at render time and needs no
+ * `loadedmetadata` probe, which would fetch video bytes for every card in the
+ * thread against the deliberate `preload: 'none'`.
+ *
+ * `FALLBACK_ASPECT` is **square** on purpose. It covers only the case where we
+ * know nothing — no recorded dimensions, no decoded poster — and a square box
+ * is what this card rendered before any of this existed, so an unknown clip
+ * can never look worse than it used to. Guessing 16:9 here put portrait clips
+ * in a letterbox, which is more wrong than a square (MES-1353).
+ */
+const FALLBACK_ASPECT = 1
+/**
+ * Tallest permitted card — Instagram's portrait limit.
+ *
+ * A 9:16 clip (0.5625) clamps to this, so it renders 4:5 and the poster is
+ * cropped rather than shown whole. Figma specifies only 16:9 and 4:3, so true
+ * portrait was never drawn; relaxing this to `9 / 16` is a one-line change if
+ * design wants a full-height portrait card.
+ */
+const MIN_ASPECT = 4 / 5
+/** Widest permitted card. */
+const MAX_ASPECT = 16 / 9
+
 const PlayBadge: React.FC = () => (
   <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
-    <span className="flex size-12 items-center justify-center rounded-full bg-black/55 text-white backdrop-blur">
+    <span className="flex size-12 items-center justify-center rounded-full bg-black/25 text-white backdrop-blur-[20px]">
       <PlayIcon className="size-6" weight="fill" aria-hidden />
     </span>
   </div>
@@ -65,40 +107,78 @@ const PlayBadge: React.FC = () => (
 // its own. A `rounded-md` here would round all four corners of every
 // tile at 6px, cutting dark wedges out of the `bg-[#0d0d0d]` backing
 // at each interior grid junction.
-const PosterTile: React.FC<{ item: VideoItem; index: number }> = ({
-  item,
-  index,
-}) => (
-  <div className="absolute inset-0 size-full bg-[#0d0d0d]">
-    {item.poster ? (
-      <img
-        src={item.poster}
-        alt={`Video ${index + 1} thumbnail`}
-        draggable={false}
-        loading="lazy"
-        decoding="async"
-        className="absolute inset-0 size-full object-cover"
-      />
-    ) : (
-      <div className="absolute inset-0 flex items-center justify-center">
-        <VideoCameraIcon
-          className="size-16 text-white/30"
-          weight="regular"
-          aria-hidden
+const PosterTile: React.FC<{
+  item: VideoItem
+  index: number
+  /**
+   * Suppressed on the grid's `+N` overflow tile — Figma gives that tile
+   * the count scrim as its only child (`2032:16414`), and a play badge
+   * stacked underneath just muddies the number.
+   */
+  showPlayBadge?: boolean
+  /**
+   * Set on the single-video tile only — see `useSingleMediaRatio`. Both
+   * are needed: the ref catches a poster the browser already had in
+   * cache, which never fires `load`.
+   */
+  imgRef?: React.Ref<HTMLImageElement>
+  onLoad?: React.ReactEventHandler<HTMLImageElement>
+}> = ({ item, index, showPlayBadge = true, imgRef, onLoad }) => {
+  return (
+    <div className="absolute inset-0 size-full bg-[#0d0d0d]">
+      {item.poster ? (
+        <img
+          ref={imgRef}
+          src={item.poster}
+          alt={`Video ${index + 1} thumbnail`}
+          draggable={false}
+          loading="lazy"
+          decoding="async"
+          onLoad={onLoad}
+          className="absolute inset-0 size-full object-cover"
         />
-      </div>
-    )}
-    <PlayBadge />
-  </div>
-)
+      ) : (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <VideoCameraIcon
+            className="size-16 text-white/30"
+            weight="regular"
+            aria-hidden
+          />
+        </div>
+      )}
+      {showPlayBadge ? <PlayBadge /> : null}
+    </div>
+  )
+}
 
-const tileFromItem = (
-  item: VideoItem,
-  index: number,
+const tileFromItem = ({
+  item,
+  index,
+  totalCount,
+  isOverflowTile,
+  imgRef,
+  onLoad,
+}: {
+  item: VideoItem
+  index: number
   totalCount: number
-): MediaStackTile => ({
+  isOverflowTile: boolean
+  imgRef?: React.Ref<HTMLImageElement>
+  onLoad?: React.ReactEventHandler<HTMLImageElement>
+}): MediaStackTile => ({
   ariaLabel: `Play video ${index + 1} of ${totalCount}`,
-  content: <PosterTile item={item} index={index} />,
+  // Activating a video tile starts playback rather than magnifying a
+  // still, so the grid's default zoom cursor would be a lie.
+  cursorClassName: 'cursor-pointer',
+  content: (
+    <PosterTile
+      item={item}
+      index={index}
+      showPlayBadge={!isOverflowTile}
+      imgRef={imgRef}
+      onLoad={onLoad}
+    />
+  ),
 })
 
 const resolveItems = ({
@@ -106,12 +186,14 @@ const resolveItems = ({
   poster,
   mimeType,
   preload,
+  naturalAspectRatio,
   items,
 }: {
   src?: string
   poster?: string
   mimeType?: string
   preload?: MediaPreloadMode
+  naturalAspectRatio?: number
   items?: VideoItem[]
 }): VideoItem[] => {
   if (items && items.length > 0) {
@@ -119,7 +201,11 @@ const resolveItems = ({
       ? items.map((it) => ({ ...it, preload: it.preload ?? preload }))
       : items
   }
-  if (src) return [{ src, poster, mimeType, preload }]
+  // `naturalAspectRatio` has to be carried onto the item here, not read off
+  // the props later: everything downstream sizes itself from `VideoItem`, so a
+  // ratio left behind on the single-`src` shape would be silently dropped and
+  // the card would fall back to measuring a poster it may not have.
+  if (src) return [{ src, poster, mimeType, preload, naturalAspectRatio }]
   return []
 }
 
@@ -211,19 +297,61 @@ const VideoBubbleRow: React.FC<InternalVideoRowProps> = ({
   text,
   groupPosition,
   preload,
+  naturalAspectRatio,
   onClick,
 }) => {
-  const resolvedItems = resolveItems({ src, poster, mimeType, preload, items })
+  const resolvedItems = resolveItems({
+    src,
+    poster,
+    mimeType,
+    preload,
+    naturalAspectRatio,
+    items,
+  })
   const variant = bubbleVariantForState(state)
   const { viewerOpen, viewerIndex, handleActivate, closeViewer } =
     useViewer(onClick)
+  const isSingle = resolvedItems.length === 1
+  const singleItem = isSingle ? resolvedItems[0] : undefined
+  // Recorded dimensions first — known on first paint and available even
+  // with no poster — then the decoded poster, then square. The hook
+  // measures from a ref as well as `onLoad`, so a poster the browser
+  // already had in cache still resolves; `onLoad` alone left the card
+  // stuck on the fallback.
+  const single = useSingleMediaRatio({
+    src: singleItem?.poster,
+    suppliedRatio: singleItem?.naturalAspectRatio,
+    fallbackRatio: FALLBACK_ASPECT,
+  })
 
   if (resolvedItems.length === 0) {
     return null
   }
 
+  const overflowTileIndex =
+    resolvedItems.length > MEDIA_STACK_MAX_VISIBLE
+      ? MEDIA_STACK_MAX_VISIBLE - 1
+      : -1
+
   const tiles: MediaStackTile[] = resolvedItems.map((item, index) =>
-    tileFromItem(item, index, resolvedItems.length)
+    tileFromItem({
+      item,
+      index,
+      totalCount: resolvedItems.length,
+      isOverflowTile: index === overflowTileIndex,
+      // Only the single card is aspect-driven — grid tiles are cropped
+      // to a fixed 2×2 geometry, so measuring them is noise.
+      imgRef: isSingle ? single.imgRef : undefined,
+      onLoad: isSingle ? single.onLoad : undefined,
+    })
+  )
+
+  // Clamped so a 9:16 clip can't render a 587px-tall card and a panorama
+  // can't collapse into a strip. Only consumed by the grid's 1-tile
+  // layout; ignored for 2+.
+  const singleAspectRatio = Math.min(
+    Math.max(single.ratio, MIN_ASPECT),
+    MAX_ASPECT
   )
 
   return (
@@ -231,10 +359,41 @@ const VideoBubbleRow: React.FC<InternalVideoRowProps> = ({
       variant={variant}
       text={text}
       groupPosition={groupPosition}
+      // The card carries no stroke in Figma, and the default hairline
+      // would eat 2px of the inset: 330 − 2×1 − 2×2 = 324, not the 326
+      // the inner media measures (`2032:16189`).
+      bordered={false}
+      // The card hugs its media plus the 2px the design leaves around
+      // it, so the 20px outer radius resolves to 18px inside. Figma's
+      // single card is 330px (`1972:13149`) and its grid card 383px
+      // (`1973:13668`), but `MediaStackGrid` caps a single tile at
+      // 326px web / 309px mobile, so the single card tracks that fitted
+      // box via `w-fit` + a per-breakpoint maximum instead of pinning
+      // 330px and leaving a gutter below `sm`. Same treatment the image
+      // media card lands on.
+      widthClassName={
+        isSingle
+          ? 'w-fit max-w-[313px] sm:max-w-[330px]'
+          : 'w-[383px] max-w-full'
+      }
+      paddingClassName="p-0.5"
+      // Figma draws the media card with a uniform 20px radius. Only
+      // standalone bubbles get it: inside a same-author run the 18/4px
+      // corner table still has to flatten the facing corners so
+      // adjacent media clusters read as one surface.
+      radiusClassName={
+        groupPosition && groupPosition !== 'single'
+          ? undefined
+          : 'rounded-[20px]'
+      }
       data-testid="video-attachment"
     >
       <div className="relative">
-        <MediaStackGrid tiles={tiles} onTileActivate={handleActivate} />
+        <MediaStackGrid
+          tiles={tiles}
+          onTileActivate={handleActivate}
+          singleAspectRatio={isSingle ? singleAspectRatio : undefined}
+        />
       </div>
 
       <VideoViewer

package/src/components/MessageAttachment/_shared/MediaStackGrid.tsx

@@ -6,8 +6,23 @@ export interface MediaStackTile {
   content: React.ReactNode
   /** Pure-tile aria label (e.g. `'Photo 1'`). Used by `Pressable` mode. */
   ariaLabel?: string
+  /**
+   * Cursor utility for the pressable tile shell. Defaults to
+   * `'cursor-zoom-in'` (correct for images); Video passes
+   * `'cursor-pointer'` because activating a video tile starts playback
+   * rather than magnifying a still.
+   */
+  cursorClassName?: string
 }
 
+/**
+ * Tiles rendered before the last one collapses into a `+N` overflow
+ * indicator. Exported so callers that need to style the overflow tile
+ * differently can work out which index it lands on without restating
+ * the number.
+ */
+export const MEDIA_STACK_MAX_VISIBLE = 4
+
 export interface MediaStackGridProps {
   tiles: MediaStackTile[]
   /**
@@ -109,7 +124,7 @@ const SINGLE_HEIGHT_CAP_PX = 436
 const MediaStackGrid: React.FC<MediaStackGridProps> = ({
   tiles,
   onTileActivate,
-  maxVisible = 4,
+  maxVisible = MEDIA_STACK_MAX_VISIBLE,
   singleAspectRatio,
   className,
 }) => {
@@ -120,7 +135,13 @@ const MediaStackGrid: React.FC<MediaStackGridProps> = ({
   const overflow = total - visible.length
   const overflowBadge =
     overflow > 0 ? (
-      <div className="absolute inset-0 flex items-center justify-center bg-black/55 text-2xl font-semibold text-white">
+      // `aria-hidden` because the tile's own label already reads
+      // "… 4 of 9" — announcing "+5" on top of that just makes the
+      // user do the arithmetic twice.
+      <div
+        aria-hidden
+        className="absolute inset-0 flex items-center justify-center bg-[#040403]/50 text-2xl font-bold leading-[28px] tracking-[-0.24px] text-white"
+      >
         +{overflow}
       </div>
     ) : null
@@ -142,7 +163,10 @@ const MediaStackGrid: React.FC<MediaStackGridProps> = ({
           key={index}
           onClick={() => onTileActivate(index)}
           aria-label={tile.ariaLabel ?? `Open media ${index + 1}`}
-          className={classNames(sharedClass, 'cursor-zoom-in')}
+          className={classNames(
+            sharedClass,
+            tile.cursorClassName ?? 'cursor-zoom-in'
+          )}
         >
           {tile.content}
           {extra}

package/src/components/MessageAttachment/_shared/VideoViewer.test.tsx

@@ -1,6 +1,11 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import {
+  act,
+  fireEvent,
+  renderWithProviders,
+  screen,
+} from '../../../test/utils'
 
 import VideoViewer from './VideoViewer'
 
@@ -52,4 +57,66 @@ describe('VideoViewer', () => {
       screen.getByTestId('video-viewer').querySelector('video')
     ).toHaveAttribute('preload', 'metadata')
   })
+
+  it('pauses the toolkit\u2019s own native audio when it opens', () => {
+    // `useActiveAudioPlayer` only covers the players stream-chat-react
+    // mounts. `MessageAttachment.Audio` and the playable `LinkAttachment`
+    // card render plain `<audio>` elements that never reach that pool, so
+    // without the marker sweep thread audio kept sounding under the video.
+    const audio = document.createElement('audio')
+    audio.setAttribute('data-mes-native-player', '')
+    document.body.appendChild(audio)
+    const pause = vi.spyOn(audio, 'pause').mockImplementation(() => {})
+
+    try {
+      renderWithProviders(
+        <VideoViewer open onClose={vi.fn()} items={[items[0]]} />
+      )
+      expect(pause).toHaveBeenCalledTimes(1)
+    } finally {
+      audio.remove()
+    }
+  })
+
+  it('keeps the frame mounted, paused, until the dialog finishes closing', () => {
+    vi.useFakeTimers()
+    try {
+      const { rerender } = renderWithProviders(
+        <VideoViewer open onClose={vi.fn()} items={[items[0]]} />
+      )
+      const video = screen.getByTestId('video-viewer').querySelector('video')
+      if (!video) throw new Error('Expected video element')
+      const pause = vi.spyOn(video, 'pause').mockImplementation(() => {})
+
+      rerender(
+        <VideoViewer open={false} onClose={vi.fn()} items={[items[0]]} />
+      )
+
+      // Still there, so the last frame doesn't blink out from under the
+      // 150ms backdrop fade — but paused, so nothing plays under it.
+      expect(
+        screen.getByTestId('video-viewer').querySelector('video')
+      ).not.toBeNull()
+      expect(pause).toHaveBeenCalled()
+
+      act(() => {
+        vi.advanceTimersByTime(150)
+      })
+
+      // Gone once the dialog is: a `<video preload="metadata">` left in a
+      // closed viewer fetches a header per bubble in the thread.
+      expect(
+        screen.getByTestId('video-viewer').querySelector('video')
+      ).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('mounts no video before the viewer has ever opened', () => {
+    renderWithProviders(
+      <VideoViewer open={false} onClose={vi.fn()} items={[items[0]]} />
+    )
+    expect(screen.getByTestId('video-viewer').querySelector('video')).toBeNull()
+  })
 })

package/src/components/MessageAttachment/_shared/VideoViewer.tsx

@@ -1,5 +1,7 @@
-import React, { useMemo } from 'react'
+import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { useActiveAudioPlayer } from 'stream-chat-react'
 
+import { pauseNativeMediaPlayers } from '../../../utils/nativeMediaPlayers'
 import type { MediaPreloadMode } from '../types'
 
 import CarouselNav from './CarouselNav'
@@ -30,6 +32,14 @@ export interface VideoViewerProps {
   onClose: () => void
 }
 
+/**
+ * How long the viewer's `<video>` survives a close, in ms. Matches
+ * `--transition-duration` on `.mes-media-viewer` in `styles.css` — the
+ * dialog and its backdrop fade over the same window, and the frame has
+ * to stay put until they are gone.
+ */
+const VIEWER_EXIT_TRANSITION_MS = 150
+
 /**
  * Full-viewport video viewer used by every `MessageAttachment.Video.*`
  * variant. Renders a single `<video controls>` element with the
@@ -52,6 +62,47 @@ const VideoViewer: React.FC<VideoViewerProps> = ({
     open,
   })
 
+  const videoRef = useRef<HTMLVideoElement | null>(null)
+
+  // Opening the lightbox stops any audio still playing in the thread —
+  // two media surfaces should never sound at once. That takes both
+  // halves: stream-chat-react's `AudioPlayerPool` for the players it
+  // mounts (voice recordings), and `pauseNativeMediaPlayers` for the
+  // plain `<audio>` elements the toolkit renders itself, which never
+  // register with the pool. Outside a `<Channel>` (Storybook, profiles'
+  // mock chat) the context default makes the pool call a no-op, which
+  // is why the optional call is load-bearing.
+  const activeAudioPlayer = useActiveAudioPlayer()
+  useEffect(() => {
+    if (!open) return
+    activeAudioPlayer?.pause()
+    pauseNativeMediaPlayers(videoRef.current)
+  }, [open, activeAudioPlayer])
+
+  // The `<video>` outlives `open` by the length of the dialog's exit
+  // transition. `ViewerShell` keeps its `<dialog>` mounted so the
+  // platform close animation can play (`--transition-duration` in
+  // `styles.css`), and unmounting the element the moment `open` flips
+  // made the frame vanish while an empty overlay faded out. It is
+  // paused immediately instead, so nothing plays under the fade, and
+  // the element is gone once the dialog is — which is what keeps a
+  // closed viewer from preloading every clip in the thread.
+  const [mounted, setMounted] = useState(open)
+  // Adjusted during render rather than from an effect, so the element is
+  // in the very first committed tree of an open viewer — an effect would
+  // paint one empty frame first, and `react-hooks/set-state-in-effect`
+  // rejects it anyway.
+  if (open && !mounted) setMounted(true)
+  useEffect(() => {
+    if (open || !mounted) return undefined
+    videoRef.current?.pause()
+    const timer = window.setTimeout(
+      () => setMounted(false),
+      VIEWER_EXIT_TRANSITION_MS
+    )
+    return () => window.clearTimeout(timer)
+  }, [open, mounted])
+
   const item = items[index]
   const filename = useMemo(
     () => item?.filename ?? (item ? filenameFromUrl(item.src) : 'video'),
@@ -72,30 +123,40 @@ const VideoViewer: React.FC<VideoViewerProps> = ({
           for chat attachments, and an empty `<track kind="captions" />`
           emits a runtime warning. Re-add a real track (with `src`,
           `srcLang`, and `default`) once caption support ships. */}
-      <video
-        // Forcing a key swap on item change ensures the new source
-        // mounts a fresh element instead of reusing the previous
-        // playback state — keeps the video paused-at-start when
-        // navigating between stacked items.
-        key={`${index}:${item.src}`}
-        src={item.src}
-        poster={item.poster}
-        controls
-        // `autoPlay` without `muted` is blocked by Chrome / Safari /
-        // Firefox autoplay policies — the click that opens the viewer
-        // doesn't count as a user-gesture for the freshly-mounted
-        // `<video>` element. Defaulting to muted means playback
-        // actually starts (matches how IG / Slack handle their video
-        // lightboxes); the user can unmute via the native controls if
-        // they want sound.
-        autoPlay
-        muted
-        playsInline
-        preload={item.preload ?? 'metadata'}
-        className="block h-auto max-h-[calc(100dvh-128px)] w-auto max-w-[min(96vw,1400px)] bg-black"
-      >
-        {item.mimeType ? <source src={item.src} type={item.mimeType} /> : null}
-      </video>
+      {/* Mounted from the first open until the close transition ends —
+          see the effect above. A `<video preload="metadata">` sitting in
+          a never-opened (or already-closed) dialog fetches the clip's
+          header for every video bubble in the thread, which is exactly
+          what the poster-only bubble surface exists to avoid. */}
+      {mounted ? (
+        <video
+          ref={videoRef}
+          // Forcing a key swap on item change ensures the new source
+          // mounts a fresh element instead of reusing the previous
+          // playback state — keeps the video paused-at-start when
+          // navigating between stacked items.
+          key={`${index}:${item.src}`}
+          src={item.src}
+          poster={item.poster}
+          controls
+          // `autoPlay` without `muted` is blocked by Chrome / Safari /
+          // Firefox autoplay policies — the click that opens the viewer
+          // doesn't count as a user-gesture for the freshly-mounted
+          // `<video>` element. Defaulting to muted means playback
+          // actually starts (matches how IG / Slack handle their video
+          // lightboxes); the user can unmute via the native controls if
+          // they want sound.
+          autoPlay
+          muted
+          playsInline
+          preload={item.preload ?? 'metadata'}
+          className="block h-auto max-h-[calc(100dvh-128px)] w-auto max-w-[min(96vw,1400px)] bg-black"
+        >
+          {item.mimeType ? (
+            <source src={item.src} type={item.mimeType} />
+          ) : null}
+        </video>
+      ) : null}
 
       {items.length > 1 ? (
         <CarouselNav

package/src/components/MessageAttachment/_shared/useSingleMediaRatio.ts

@@ -0,0 +1,75 @@
+import React from 'react'
+
+/**
+ * Resolves the aspect ratio (width ÷ height) of a single-media bubble,
+ * in order:
+ *
+ *   1. `suppliedRatio` — known at first paint, so the card never
+ *      resizes. `ImageItem.width` / `height` for images, and for video
+ *      `VideoItem.naturalAspectRatio`, taken from the dimensions Stream
+ *      stores on the attachment.
+ *   2. the decoded `<img>`'s `naturalWidth` / `naturalHeight`;
+ *   3. `fallbackRatio`.
+ *
+ * Measurement reads both from `onLoad` **and** from the ref, because an
+ * image already in the browser cache can be `complete` before React
+ * attaches a `load` listener — a second card showing the same URL, a
+ * remount while scrolling a thread, or a Storybook HMR update all hit
+ * that path, and an `onLoad`-only hook silently keeps the fallback
+ * forever.
+ *
+ * Shared by the image and video cards: a video's poster is an `<img>`
+ * on the bubble surface, so it measures identically (MES-1353).
+ */
+export const useSingleMediaRatio = ({
+  src,
+  suppliedRatio,
+  fallbackRatio,
+}: {
+  /** Media source, used to discard a measurement from a previous item. */
+  src: string | undefined
+  /** Ratio the caller already knows, if any. Wins over measuring. */
+  suppliedRatio?: number
+  /** Used until something better is known. */
+  fallbackRatio: number
+}): {
+  ratio: number
+  imgRef: (img: HTMLImageElement | null) => void
+  onLoad: React.ReactEventHandler<HTMLImageElement>
+} => {
+  const [measured, setMeasured] = React.useState<{
+    src: string
+    ratio: number
+  }>()
+
+  const measure = React.useCallback(
+    (img: HTMLImageElement | null) => {
+      if (!img || img.naturalWidth <= 0 || img.naturalHeight <= 0) return
+      if (src === undefined) return
+      const ratio = img.naturalWidth / img.naturalHeight
+      // Returning `prev` unchanged matters: the ref callback runs on
+      // every commit, and a fresh object each time would schedule an
+      // endless render loop.
+      setMeasured((prev) =>
+        prev && prev.src === src && prev.ratio === ratio ? prev : { src, ratio }
+      )
+    },
+    [src]
+  )
+
+  const handleLoad = React.useCallback(
+    (event: React.SyntheticEvent<HTMLImageElement>) =>
+      measure(event.currentTarget),
+    [measure]
+  )
+
+  // Discard a measurement left over from a previous `src`.
+  const measuredRatio =
+    measured && measured.src === src ? measured.ratio : undefined
+
+  return {
+    ratio: suppliedRatio ?? measuredRatio ?? fallbackRatio,
+    imgRef: measure,
+    onLoad: handleLoad,
+  }
+}

package/src/components/MessageAttachment/types.ts

@@ -99,6 +99,15 @@ export interface VideoItem {
   src: string
   /** Poster / thumbnail rendered before playback starts. */
   poster?: string
+  /**
+   * Width ÷ height of the source clip, when the sender recorded it on the
+   * attachment (Stream's `original_width` / `original_height`). Preferred over
+   * measuring the poster, because it is known before any image loads and works
+   * for a clip that has no poster at all — the case that otherwise leaves a
+   * portrait video in a square or landscape box. Absent on anything sent
+   * before the composer began writing it (MES-1353).
+   */
+  naturalAspectRatio?: number
   /** Optional MIME type (e.g. `video/mp4`). */
   mimeType?: string
   /**