@linktr.ee/messaging-react 4.4.7 → 4.5.0-rc-1788297811

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

@@ -18,7 +18,9 @@ describe('Bubble', () => {
       </Bubble>
     )
     const bubble = screen.getByTestId('bubble')
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     if (present) expect(bubble.querySelector('p')).not.toBeNull()
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     else expect(bubble.querySelector('p')).toBeNull()
     expect(bubble).toHaveClass(present ? 'pb-0' : 'py-2')
   })

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

@@ -1,12 +1,13 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import CarouselNav from './CarouselNav'
 import { VIEWER_NAV_CLASS } from './viewerChromeClasses'
 
 describe('CarouselNav', () => {
-  it('uses default labels and independent handlers', () => {
+  it('uses default labels and independent handlers', async () => {
+    const user = userEvent.setup()
     const onPrev = vi.fn()
     const onNext = vi.fn()
     renderWithProviders(<CarouselNav onPrev={onPrev} onNext={onNext} />)
@@ -15,8 +16,8 @@ describe('CarouselNav', () => {
     const next = screen.getByRole('button', { name: 'Next' })
     expect(prev).toHaveClass(VIEWER_NAV_CLASS, 'left-4')
     expect(next).toHaveClass(VIEWER_NAV_CLASS, 'right-4')
-    fireEvent.click(prev)
-    fireEvent.click(next)
+    await user.click(prev)
+    await user.click(next)
     expect(onPrev).toHaveBeenCalledOnce()
     expect(onNext).toHaveBeenCalledOnce()
   })

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

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import CompactDocumentRow from './CompactDocumentRow'
 
@@ -71,7 +71,8 @@ describe('CompactDocumentRow', () => {
     )
   })
 
-  it('activates its body without nesting the trailing action', () => {
+  it('activates its body without nesting the trailing action', async () => {
+    const user = userEvent.setup()
     const onActivate = vi.fn()
     renderWithProviders(
       <CompactDocumentRow
@@ -87,7 +88,7 @@ describe('CompactDocumentRow', () => {
     expect(body).not.toContainElement(
       screen.getByRole('button', { name: 'Download' })
     )
-    fireEvent.click(body)
+    await user.click(body)
     expect(onActivate).toHaveBeenCalledOnce()
   })
 

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

@@ -1,11 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import DismissButton from './DismissButton'
 
 describe('DismissButton', () => {
-  it('uses the default label, invokes the handler, and stops propagation', () => {
+  it('uses the default label, invokes the handler, and stops propagation', async () => {
+    const user = userEvent.setup()
     const onClick = vi.fn()
     const outerClick = vi.fn()
     renderWithProviders(
@@ -15,7 +16,7 @@ describe('DismissButton', () => {
       </div>
     )
 
-    fireEvent.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
+    await user.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
     expect(onClick).toHaveBeenCalledOnce()
     expect(outerClick).not.toHaveBeenCalled()
   })

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

@@ -1,10 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import {
-  fireEvent,
   renderWithProviders,
   screen,
   waitFor,
+  userEvent,
 } from '../../../test/utils'
 
 import DownloadAction from './DownloadAction'
@@ -83,6 +83,7 @@ describe('DownloadAction', () => {
   )
 
   it('stops propagation and calls the download once', async () => {
+    const user = userEvent.setup()
     const outerClick = vi.fn()
     renderWithProviders(
       // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
@@ -94,7 +95,7 @@ describe('DownloadAction', () => {
         />
       </div>
     )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    await user.click(screen.getByRole('button', { name: 'Download' }))
     await waitFor(() =>
       expect(mockedTriggerDownload).toHaveBeenCalledWith(
         '/file.pdf',
@@ -106,6 +107,7 @@ describe('DownloadAction', () => {
   })
 
   it('disables repeated clicks while downloading and settles on success', async () => {
+    const user = userEvent.setup()
     let resolve: () => void = () => undefined
     mockedTriggerDownload.mockReturnValueOnce(
       new Promise<void>((done) => {
@@ -117,8 +119,8 @@ describe('DownloadAction', () => {
       <DownloadAction url="/file.pdf" onTriggered={onTriggered} />
     )
     const button = screen.getByRole('button', { name: 'Download' })
-    fireEvent.click(button)
-    fireEvent.click(button)
+    await user.click(button)
+    await user.click(button)
     expect(button).toBeDisabled()
     expect(mockedTriggerDownload).toHaveBeenCalledOnce()
     resolve()
@@ -127,13 +129,14 @@ describe('DownloadAction', () => {
   })
 
   it('settles and notifies even when downloading rejects', async () => {
+    const user = userEvent.setup()
     mockedTriggerDownload.mockRejectedValueOnce(new Error('offline'))
     const onTriggered = vi.fn()
     renderWithProviders(
       <DownloadAction url="/file.pdf" onTriggered={onTriggered} />
     )
     const button = screen.getByRole('button', { name: 'Download' })
-    fireEvent.click(button)
+    await user.click(button)
     await waitFor(() => expect(button).toBeEnabled())
     expect(onTriggered).toHaveBeenCalledOnce()
   })

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

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import ImageViewer from './ImageViewer'
 
@@ -14,6 +14,7 @@ describe('ImageViewer', () => {
     const { container } = renderWithProviders(
       <ImageViewer open onClose={vi.fn()} items={[]} />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- the null-rendering DOM contract has no semantic query.
     expect(container.firstChild).toBeNull()
   })
 
@@ -29,6 +30,7 @@ describe('ImageViewer', () => {
     expect(
       screen
         .getByTestId('image-viewer')
+        // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
         .querySelector('button[aria-label="Download one.jpg"]')
     ).toBeInTheDocument()
     rerender(<ImageViewer open onClose={vi.fn()} items={[items[0]]} />)
@@ -36,7 +38,8 @@ describe('ImageViewer', () => {
     expect(screen.getByRole('img')).toHaveAttribute('draggable', 'false')
   })
 
-  it('renders counter and navigation only for multiple items', () => {
+  it('renders counter and navigation only for multiple items', async () => {
+    const user = userEvent.setup()
     renderWithProviders(
       <ImageViewer open onClose={vi.fn()} items={items} initialIndex={99} />
     )
@@ -45,7 +48,7 @@ describe('ImageViewer', () => {
       screen.getByRole('button', { name: 'Previous image' })
     ).toBeInTheDocument()
     expect(screen.getByRole('img')).toHaveAttribute('src', items[1].src)
-    fireEvent.click(screen.getByRole('button', { name: 'Previous image' }))
+    await user.click(screen.getByRole('button', { name: 'Previous image' }))
     expect(screen.getByText('1 / 2')).toBeInTheDocument()
     expect(screen.getByRole('img')).toHaveAttribute('src', items[0].src)
   })

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

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import MediaStackGrid from './MediaStackGrid'
 
@@ -13,6 +13,7 @@ const tiles = (count: number) =>
 describe('MediaStackGrid', () => {
   it('renders nothing for empty tiles', () => {
     const { container } = renderWithProviders(<MediaStackGrid tiles={[]} />)
+    // eslint-disable-next-line testing-library/no-node-access -- the null-rendering DOM contract has no semantic query.
     expect(container.firstChild).toBeNull()
   })
 
@@ -25,6 +26,7 @@ describe('MediaStackGrid', () => {
     const { container } = renderWithProviders(
       <MediaStackGrid tiles={tiles(count)} className="custom-grid" />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- the component shell wrapper has no semantic query.
     expect(container.firstElementChild).toHaveClass(layoutClass, 'custom-grid')
     expect(screen.getAllByText(/tile/)).toHaveLength(count)
   })
@@ -35,12 +37,14 @@ describe('MediaStackGrid', () => {
     )
     expect(screen.getAllByText(/tile/)).toHaveLength(4)
     expect(screen.getByText('+2')).toBeInTheDocument()
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     expect(screen.getByText('+2').parentElement).toHaveTextContent('tile 4')
     rerender(<MediaStackGrid tiles={tiles(2)} maxVisible={4} />)
     expect(screen.getAllByText(/tile/)).toHaveLength(2)
     expect(screen.queryByText(/^\+/)).toBeNull()
     rerender(<MediaStackGrid tiles={tiles(1)} singleAspectRatio={0.5} />)
     expect(
+      // eslint-disable-next-line testing-library/no-node-access -- the component wrapper class has no semantic query.
       screen.getByText('tile 1').closest('div')?.parentElement
     ).toHaveStyle({
       aspectRatio: '0.5',
@@ -58,6 +62,7 @@ describe('MediaStackGrid', () => {
       )
       expect(screen.getAllByText(/tile/)).toHaveLength(maxVisible)
       expect(screen.getByText(badge)).toBeInTheDocument()
+      // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
       expect(screen.getByText(badge).parentElement).toHaveTextContent(lastTile)
     }
   )
@@ -65,6 +70,7 @@ describe('MediaStackGrid', () => {
   it('shows overflow on the single visible tile', () => {
     renderWithProviders(<MediaStackGrid tiles={tiles(3)} maxVisible={1} />)
     expect(screen.getAllByText(/tile/)).toHaveLength(1)
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     expect(screen.getByText('+2').parentElement).toHaveTextContent('tile 1')
   })
 
@@ -73,7 +79,8 @@ describe('MediaStackGrid', () => {
     expect(screen.queryByText(/^\+/)).toBeNull()
   })
 
-  it('renders activatable buttons with labels and indexes', () => {
+  it('renders activatable buttons with labels and indexes', async () => {
+    const user = userEvent.setup()
     const onActivate = vi.fn()
     renderWithProviders(
       <MediaStackGrid tiles={tiles(3)} onTileActivate={onActivate} />
@@ -82,8 +89,8 @@ describe('MediaStackGrid', () => {
     expect(buttons).toHaveLength(3)
     expect(buttons[0]).toHaveAttribute('aria-label', 'Open media 1')
     expect(buttons[1]).toHaveAttribute('aria-label', 'Second tile')
-    fireEvent.click(buttons[0])
-    fireEvent.click(buttons[2])
+    await user.click(buttons[0])
+    await user.click(buttons[2])
     expect(onActivate).toHaveBeenNthCalledWith(1, 0)
     expect(onActivate).toHaveBeenNthCalledWith(2, 2)
   })

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

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import { userEvent, renderWithProviders, screen } from '../../../test/utils'
 
 import PdfViewer from './PdfViewer'
 
@@ -14,6 +14,7 @@ describe('PdfViewer', () => {
     const { container } = renderWithProviders(
       <PdfViewer open onClose={vi.fn()} items={[]} />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- the null-rendering DOM contract has no semantic query.
     expect(container.firstChild).toBeNull()
   })
 
@@ -30,7 +31,8 @@ describe('PdfViewer', () => {
     )
   })
 
-  it('uses filename precedence and navigates stacked documents', () => {
+  it('uses filename precedence and navigates stacked documents', async () => {
+    const user = userEvent.setup()
     renderWithProviders(
       <PdfViewer open onClose={vi.fn()} items={items} initialIndex={1} />
     )
@@ -39,7 +41,7 @@ describe('PdfViewer', () => {
       'second.pdf'
     )
     expect(screen.getByText('2 / 2')).toBeInTheDocument()
-    fireEvent.click(screen.getByRole('button', { name: 'Previous document' }))
+    await user.click(screen.getByRole('button', { name: 'Previous document' }))
     expect(screen.getByTitle('one.pdf')).toBeInTheDocument()
   })
 })

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

@@ -2,10 +2,10 @@ import { describe, expect, it, vi } from 'vitest'
 
 import {
   act,
-  fireEvent,
   renderWithProviders,
   screen,
   within,
+  userEvent,
 } from '../../../test/utils'
 
 import VideoViewer from './VideoViewer'
@@ -26,6 +26,7 @@ describe('VideoViewer', () => {
     const { container } = renderWithProviders(
       <VideoViewer open onClose={vi.fn()} items={[]} />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- the null-rendering DOM contract has no semantic query.
     expect(container.firstChild).toBeNull()
   })
 
@@ -33,6 +34,7 @@ describe('VideoViewer', () => {
     renderWithProviders(
       <VideoViewer open onClose={vi.fn()} items={[items[0]]} />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     const video = screen.getByTestId('video-viewer').querySelector('video')
     expect(video).not.toBeNull()
     if (!video) throw new Error('Expected video element')
@@ -41,20 +43,25 @@ describe('VideoViewer', () => {
     expect(video).toHaveAttribute('preload', 'auto')
     expect(video).toHaveAttribute('autoplay')
     expect(video?.muted).toBe(true)
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     expect(video.querySelector('source')).toHaveAttribute('type', 'video/mp4')
   })
 
-  it('defaults preload and navigates stacked items', () => {
+  it('defaults preload and navigates stacked items', async () => {
+    const user = userEvent.setup()
     renderWithProviders(<VideoViewer open onClose={vi.fn()} items={items} />)
     expect(screen.getByText('1 / 2')).toBeInTheDocument()
     expect(
+      // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
       screen.getByTestId('video-viewer').querySelector('video')
     ).toHaveAttribute('preload', 'auto')
-    fireEvent.click(screen.getByRole('button', { name: 'Next video' }))
+    await user.click(screen.getByRole('button', { name: 'Next video' }))
     expect(
+      // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
       screen.getByTestId('video-viewer').querySelector('video')
     ).toHaveAttribute('src', items[1].src)
     expect(
+      // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
       screen.getByTestId('video-viewer').querySelector('video')
     ).toHaveAttribute('preload', 'metadata')
   })
@@ -85,6 +92,7 @@ describe('VideoViewer', () => {
       const { rerender } = renderWithProviders(
         <VideoViewer open onClose={vi.fn()} items={[items[0]]} />
       )
+      // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
       const video = screen.getByTestId('video-viewer').querySelector('video')
       if (!video) throw new Error('Expected video element')
       const pause = vi.spyOn(video, 'pause').mockImplementation(() => {})
@@ -96,6 +104,7 @@ describe('VideoViewer', () => {
       // Still there, so the last frame doesn't blink out from under the
       // 150ms backdrop fade — but paused, so nothing plays under it.
       expect(
+        // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
         screen.getByTestId('video-viewer').querySelector('video')
       ).not.toBeNull()
       expect(pause).toHaveBeenCalled()

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

@@ -1,7 +1,12 @@
 import { useLayoutEffect } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import {
+  userEvent,
+  fireEvent,
+  renderWithProviders,
+  screen,
+} from '../../../test/utils'
 
 import { VIEWER_ACTION_CLASS } from './viewerChromeClasses'
 import ViewerShell from './ViewerShell'
@@ -33,6 +38,7 @@ const restoreDialogMethod = (
 
 const PreOpenDialog = () => {
   useLayoutEffect(() => {
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     document.querySelector('[data-testid="viewer"]')?.setAttribute('open', '')
   }, [])
   return null
@@ -201,7 +207,7 @@ describe('ViewerShell', () => {
         </ViewerShell>
       )
     ).not.toThrow()
-    expect(document.activeElement).not.toBe(previouslyFocused)
+    expect(previouslyFocused).not.toHaveFocus()
   })
 
   it('uses the default accessible label', () => {
@@ -227,7 +233,8 @@ describe('ViewerShell', () => {
     expect(close).not.toHaveBeenCalled()
   })
 
-  it('closes from the close, native close, and backdrop events', () => {
+  it('closes from the close, native close, and backdrop events', async () => {
+    const user = userEvent.setup()
     const onClose = vi.fn()
     renderWithProviders(
       <ViewerShell open onClose={onClose} data-testid="viewer">
@@ -235,12 +242,12 @@ describe('ViewerShell', () => {
       </ViewerShell>
     )
     const dialog = screen.getByTestId('viewer')
-    fireEvent.click(screen.getByRole('button', { name: 'Close viewer' }))
+    await user.click(screen.getByRole('button', { name: 'Close viewer' }))
     fireEvent(dialog, new Event('close'))
-    fireEvent.click(dialog)
+    await user.click(dialog)
     expect(onClose).toHaveBeenCalledTimes(3)
     onClose.mockClear()
-    fireEvent.click(screen.getByText('content'))
+    await user.click(screen.getByText('content'))
     expect(onClose).not.toHaveBeenCalled()
   })
 })

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

@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'vitest'
 
-import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+import {
+  userEvent,
+  fireEvent,
+  renderWithProviders,
+  screen,
+} from '../../../test/utils'
 
 import { useCarousel } from './useCarousel'
 
@@ -28,14 +33,15 @@ const Harness = ({
 }
 
 describe('useCarousel', () => {
-  it('clamps initial index, wraps, and resets on reopen', () => {
+  it('clamps initial index, wraps, and resets on reopen', async () => {
+    const user = userEvent.setup()
     const { rerender } = renderWithProviders(
       <Harness open length={3} initialIndex={99} />
     )
     expect(screen.getByTestId('index')).toHaveTextContent('2')
-    fireEvent.click(screen.getByRole('button', { name: 'Next' }))
+    await user.click(screen.getByRole('button', { name: 'Next' }))
     expect(screen.getByTestId('index')).toHaveTextContent('0')
-    fireEvent.click(screen.getByRole('button', { name: 'Prev' }))
+    await user.click(screen.getByRole('button', { name: 'Prev' }))
     expect(screen.getByTestId('index')).toHaveTextContent('2')
     rerender(<Harness open={false} length={3} initialIndex={1} />)
     rerender(<Harness open length={3} initialIndex={1} />)

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

@@ -0,0 +1,23 @@
+import { useSyncExternalStore } from 'react'
+
+/** No store to subscribe to — the value flips once, at hydration. */
+const subscribe = () => () => {}
+const getSnapshot = () => true
+const getServerSnapshot = () => false
+
+/**
+ * `false` while server-rendering and for the hydration render, `true`
+ * from the first client render onwards.
+ *
+ * `useSyncExternalStore` is what makes that safe: React uses
+ * `getServerSnapshot` for both the server pass and hydration, so the
+ * two trees match and only then does the component re-render as
+ * interactive. The `useState` + `useEffect` spelling of this produces
+ * the same result but trips `react-hooks/set-state-in-effect`.
+ *
+ * Used to keep browser-only work out of a server render — see
+ * `WaveformAudioRow`, where constructing Stream's pooled `AudioPlayer`
+ * reaches for `new Audio()` (MES-1360).
+ */
+export const useIsClient = (): boolean =>
+  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)

package/src/components/MessageAttachment/index.tsx

@@ -56,7 +56,7 @@ import VideoAttachment, {
  *   - Pdf / Audio / File render their compact rows / players in a
  *     vertical stack with an 8px gap between rows. Each row keeps
  *     its own activation target — Pdf opens the carousel-aware
- *     `PdfViewer` at that index, Audio gets its own native player,
+ *     `PdfViewer` at that index, Audio gets its own waveform player,
  *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
@@ -74,12 +74,29 @@ import VideoAttachment, {
  * download button to the chrome; the Video viewer relies on the
  * native `<video controls>` download menu, and the Pdf viewer
  * inherits the browser's built-in PDF download. Sibling-row Download
- * buttons on Pdf / File and the native `<audio>` controls expose
+ * buttons on Pdf / File and the Audio card's trailing action expose
  * downloads outside the viewer too. The lightbox chrome is styled
  * with plain CSS (`.mes-media-viewer*`) so the package's shipped
  * stylesheet is enough to render the viewer correctly without a
  * Tailwind dependency in the consumer.
  *
+ * # Audio requires a `<Channel>` ancestor
+ *
+ * `MessageAttachment.Audio.*` renders the waveform player card —
+ * a 32px play toggle, a 35-bar waveform with a progress fill and a
+ * native seek control, the duration, and a 32px trailing action
+ * (Remove in the composer, Download once sent). Playback is
+ * `stream-chat-react`'s pooled `AudioPlayer`, which is what supplies
+ * single-player-at-a-time across a thread, pause-on-navigation and
+ * saved-position restore across virtualized remounts.
+ *
+ * That pool is provided by `<Channel>`. Rendered outside one the card
+ * still draws in full, but its play and seek controls are disabled —
+ * so a story or a new consumer surface must mount `<Channel>` (or
+ * `stream-chat-react`'s `WithAudioPlayback`) for the card to be
+ * playable. The waveform bars themselves are styled with plain CSS
+ * (`.mes-audio-wave*`), so the shipped stylesheet is enough.
+ *
  * # Lazy-loading defaults
  *
  * Media attachments bake in network-friendly defaults for long chat
@@ -100,13 +117,12 @@ import VideoAttachment, {
  *     `VideoItem.preload` per item). Once the viewer is open the
  *     active item bumps to `preload="metadata"` so duration / the
  *     first frame appear immediately.
- *   - **Audio** — a single audio bubble defaults to
- *     `preload="metadata"` so the native player surfaces duration
- *     immediately. A stacked audio bubble (`items.length > 1`)
- *     defaults to `preload="none"` for every player so a thread of
- *     voice memos doesn't fan out N parallel metadata requests on
- *     first paint. Override via the attachment's `preload` prop
- *     (or `AudioItem.preload` per track).
+ *   - **Audio** — no audio bytes are fetched until the user presses
+ *     play: the pooled `AudioPlayer` acquires the shared `<audio>`
+ *     element lazily. A card whose `durationSeconds` is unknown makes
+ *     one `preload="metadata"` header request to fill the duration
+ *     slot; supplying `durationSeconds` (which `StreamAttachmentMessage`
+ *     maps from the attachment's persisted `duration`) avoids even that.
  *   - **Pdf** / **File** — no inline media element to throttle; the
  *     bubble renders compact rows that download / open lazily on
  *     activation. No `loading` / `preload` props on these surfaces.

package/src/components/MessageAttachment/types.ts

@@ -133,21 +133,31 @@ export interface PdfItem {
 /** A single audio file inside an Audio attachment (single or stacked). */
 export interface AudioItem {
   src: string
-  /** MIME type hint — typed onto the inline `<source>` element. */
+  /** MIME type hint — gates playability via the player's `canPlayType` probe. */
   mimeType?: string
   /**
-   * Filename — used as the download default name (consumed by the
-   * native player's kebab menu).
+   * Filename — the download default name for the card's trailing
+   * action, and part of the card's accessible name.
    */
   filename?: string
   /**
-   * Per-track override for the `<audio preload>` hint. Defaults to
-   * the parent attachment's `preload` value, which itself defaults
-   * to `'metadata'` for a single audio (so the native player can
-   * surface duration immediately) and `'none'` for a stacked thread
-   * (so a fan-out of metadata requests doesn't happen on first paint).
+   * Track length in seconds. Rendered as `MM:SS` before playback
+   * starts, so the duration is correct on first paint with no network
+   * request. Sourced from the Stream attachment's `duration` field,
+   * which the composer writes at send time. When omitted the card
+   * shows `--:--` until a one-shot `loadedmetadata` probe resolves.
    */
-  preload?: MediaPreloadMode
+  durationSeconds?: number
+  /**
+   * Waveform amplitudes, each `0..1`, in track order. Resampled to the
+   * rendered bar count, so any length is accepted. Sourced from the
+   * Stream attachment's `waveform_data`, which the composer computes
+   * from the local file and writes at send time.
+   *
+   * When omitted, the card renders a flat placeholder row: every bar at
+   * the minimum height, with the progress fill still tracking playback.
+   */
+  waveformData?: number[]
 }
 
 /** A single generic file inside a File attachment (single or stacked). */

package/src/components/MessageBubble/MessageBubble.test.tsx

@@ -23,11 +23,15 @@ describe('MessageBubble', () => {
       <MessageBubble.Sent text="tailed" />
     )
     // The bubble box wraps the text; its last child is the tail <span>.
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const bubble = screen.getByText('tailed').parentElement as HTMLElement
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     expect(bubble.querySelector('span[aria-hidden="true"]')).not.toBeNull()
 
     rerender(<MessageBubble.Sent text="tailed" tail={false} />)
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const bubbleNoTail = screen.getByText('tailed').parentElement as HTMLElement
+    // eslint-disable-next-line testing-library/no-node-access -- media or rendered-markup internals have no user-facing query.
     expect(bubbleNoTail.querySelector('span[aria-hidden="true"]')).toBeNull()
   })
 
@@ -47,12 +51,14 @@ describe('MessageBubble', () => {
 
   it('applies the sent and received surface treatments from theme vars', () => {
     const { rerender } = renderWithProviders(<MessageBubble.Sent text="mine" />)
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const sent = screen.getByText('mine').parentElement as HTMLElement
     expect(sent.style.backgroundColor).toBe(
       'var(--str-chat__own-message-bubble-background-color, #1e2330)'
     )
 
     rerender(<MessageBubble.Received text="theirs" />)
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const received = screen.getByText('theirs').parentElement as HTMLElement
     expect(received.style.backgroundColor).toBe(
       'var(--str-chat__message-bubble-background-color, #f1f0ee)'
@@ -61,6 +67,7 @@ describe('MessageBubble', () => {
 
   it('masks message content from session replay by default', () => {
     renderWithProviders(<MessageBubble.Received header="Brie" text="secret" />)
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const bubble = screen.getByText('secret').parentElement as HTMLElement
     expect(bubble.getAttribute('data-dd-privacy')).toBe('mask')
   })
@@ -69,6 +76,7 @@ describe('MessageBubble', () => {
     renderWithProviders(
       <MessageBubble.Sent text="wide" className="w-fit max-w-[520px]" />
     )
+    // eslint-disable-next-line testing-library/no-node-access -- the wrapper class is a deliberate DOM contract with no semantic query.
     const bubble = screen.getByText('wide').parentElement as HTMLElement
     expect(bubble.classList.contains('w-fit')).toBe(true)
   })