@linktr.ee/messaging-react 4.1.7-rc-1787194909 → 4.1.7-rc-1787202056

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/messaging-react",
-  "version": "4.1.7-rc-1787194909",
+  "version": "4.1.7-rc-1787202056",
   "description": "React messaging components built on messaging-core for web applications",
   "type": "module",
   "main": "dist/index.cjs",
@@ -50,7 +50,7 @@
     "chromatic:local": "yarn storybook:build && chromatic"
   },
   "dependencies": {
-    "@linktr.ee/messaging-core": "2.5.0-rc-1787194909",
+    "@linktr.ee/messaging-core": "2.5.0-rc-1787202056",
     "@linktr.ee/messaging-taxonomy": "^0.10.0",
     "@phosphor-icons/react": "^2.1.10"
   },

package/src/components/MessageAttachment/MessageAttachment.behavior.test.tsx

@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../test/utils'
+
+import { triggerDownload } from './_shared/triggerDownload'
+import { bubbleVariantForState, bubbleGroupPositionFromStream } from './types'
+
+import MessageAttachment from '.'
+
+vi.mock('./_shared/triggerDownload', () => ({
+  triggerDownload: vi.fn(() => Promise.resolve()),
+}))
+
+const mockedDownload = vi.mocked(triggerDownload)
+
+describe('MessageAttachment behavior', () => {
+  it('renders file rows with precedence, fallback names, and cancellation', () => {
+    const onClick = vi.fn(() => false)
+    const { rerender } = renderWithProviders(
+      <MessageAttachment.File.Sent
+        src="https://cdn.example.com/fallback.txt"
+        filename="fallback.txt"
+        items={[
+          {
+            src: 'https://cdn.example.com/first.pdf',
+            filename: 'first.pdf',
+          },
+          { src: 'https://cdn.example.com/second.pdf' },
+        ]}
+        onClick={onClick}
+      />
+    )
+    expect(screen.getByText('first.pdf')).toBeInTheDocument()
+    expect(screen.getByText('second.pdf')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Download first.pdf' }))
+    expect(onClick).toHaveBeenCalledWith(0)
+    expect(mockedDownload).not.toHaveBeenCalled()
+
+    rerender(
+      <MessageAttachment.File.Sent src="https://cdn.example.com/fallback.txt" />
+    )
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Download fallback.txt' })
+    )
+    expect(mockedDownload).toHaveBeenCalledWith(
+      'https://cdn.example.com/fallback.txt',
+      'fallback.txt'
+    )
+  })
+
+  it('renders no file when inputs are absent and supports composer dismissal', () => {
+    const { container } = renderWithProviders(
+      <MessageAttachment.File.Received />
+    )
+    expect(container.firstChild).toBeNull()
+    const onDismiss = vi.fn()
+    renderWithProviders(
+      <MessageAttachment.File.Composer
+        src="https://cdn.example.com/file"
+        onDismiss={onDismiss}
+      />
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
+    expect(onDismiss).toHaveBeenCalledOnce()
+  })
+
+  it('renders image stacks, forwards loading, and supports click cancellation', () => {
+    const onClick = vi.fn(() => false)
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        src="https://cdn.example.com/fallback.jpg"
+        items={[
+          { src: 'https://cdn.example.com/one.jpg' },
+          { src: 'https://cdn.example.com/two.jpg', loading: 'eager' },
+        ]}
+        loading="lazy"
+        onClick={onClick}
+      />
+    )
+    expect(screen.getAllByRole('img')[0]).toHaveAttribute('loading', 'lazy')
+    expect(screen.getAllByRole('img')).toHaveLength(2)
+    fireEvent.click(screen.getByRole('button', { name: 'Open image 2 of 2' }))
+    expect(onClick).toHaveBeenCalledWith(1)
+    expect(screen.queryByTestId('image-viewer')).not.toHaveAttribute('open')
+  })
+
+  it('opens images at the clicked index and suffixes a shared filename', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        filename="photos.jpg"
+        items={[
+          { src: 'https://cdn.example.com/one.jpg' },
+          { src: 'https://cdn.example.com/two.jpg' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Open image 2 of 2' }))
+    expect(screen.getByTestId('image-viewer')).toHaveAttribute(
+      'aria-label',
+      'photos.jpg (2)'
+    )
+    expect(screen.getByRole('img', { name: 'photos.jpg (2)' })).toHaveAttribute(
+      'src',
+      'https://cdn.example.com/two.jpg'
+    )
+  })
+
+  it('renders video poster and fallback, and wires viewer attributes', () => {
+    const onDismiss = vi.fn()
+    const { rerender } = renderWithProviders(
+      <MessageAttachment.Video.Composer
+        src="https://cdn.example.com/video.mp4"
+        poster="/poster.jpg"
+        mimeType="video/mp4"
+        preload="auto"
+        onDismiss={onDismiss}
+      />
+    )
+    expect(
+      screen.getByRole('img', { name: 'Video 1 thumbnail' })
+    ).toHaveAttribute('src', '/poster.jpg')
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
+    expect(onDismiss).toHaveBeenCalledOnce()
+    rerender(
+      <MessageAttachment.Video.Sent
+        items={[{ src: 'https://cdn.example.com/video.mp4' }]}
+      />
+    )
+    expect(screen.getByLabelText('Play video 1 of 1')).toBeInTheDocument()
+  })
+
+  it('supports PDF titles, download actions, dismiss, and viewer index', () => {
+    const onDismiss = vi.fn()
+    renderWithProviders(
+      <MessageAttachment.Pdf.Composer
+        src="https://cdn.example.com/report.pdf"
+        title="Quarterly report"
+        onDismiss={onDismiss}
+      />
+    )
+    expect(screen.getByText('Quarterly report')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
+    expect(onDismiss).toHaveBeenCalledOnce()
+
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        items={[
+          { src: 'https://cdn.example.com/one.pdf' },
+          { src: 'https://cdn.example.com/two.pdf', filename: 'two.pdf' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Open two.pdf' }))
+    expect(screen.getAllByTestId('pdf-viewer').at(-1)).toHaveAttribute(
+      'aria-label',
+      'two.pdf'
+    )
+  })
+
+  it('maps state and stream grouping contracts', () => {
+    expect(bubbleVariantForState('composer')).toBe('dark')
+    expect(bubbleVariantForState('sent')).toBe('dark')
+    expect(bubbleVariantForState('received')).toBe('light')
+    expect(bubbleGroupPositionFromStream({})).toBe('single')
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: true,
+        firstOfGroup: true,
+        endOfGroup: true,
+      })
+    ).toBe('single')
+    expect(
+      bubbleGroupPositionFromStream({ groupedByUser: true, firstOfGroup: true })
+    ).toBe('first')
+    expect(
+      bubbleGroupPositionFromStream({ groupedByUser: true, endOfGroup: true })
+    ).toBe('end')
+    expect(bubbleGroupPositionFromStream({ groupedByUser: true })).toBe(
+      'middle'
+    )
+  })
+})

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

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+
+import { renderWithProviders, screen } from '../../../test/utils'
+
+import Bubble from './Bubble'
+
+describe('Bubble', () => {
+  it.each([
+    [undefined, false],
+    [null, false],
+    ['', false],
+    ['caption', true],
+    [0, true],
+  ])('renders caption %j according to its value', (text, present) => {
+    renderWithProviders(
+      <Bubble variant="dark" text={text} data-testid="bubble">
+        <span>child</span>
+      </Bubble>
+    )
+    const bubble = screen.getByTestId('bubble')
+    if (present) expect(bubble.querySelector('p')).not.toBeNull()
+    else expect(bubble.querySelector('p')).toBeNull()
+    expect(bubble).toHaveClass(present ? 'pb-0' : 'py-2')
+  })
+
+  it('maps variants, group positions, borders, and forwarded content', () => {
+    const { rerender } = renderWithProviders(
+      <Bubble
+        variant="dark"
+        groupPosition="middle"
+        data-testid="bubble"
+        className="custom"
+      >
+        child
+      </Bubble>
+    )
+    let bubble = screen.getByTestId('bubble')
+    expect(bubble).toHaveClass('bg-[#1e2330]', 'text-white', 'border')
+    expect(bubble).toHaveClass('rounded-tr-[4px]', 'rounded-br-[4px]')
+    expect(bubble).toHaveAttribute('data-group-position', 'middle')
+    expect(bubble).toHaveClass('custom')
+    expect(bubble).toHaveTextContent('child')
+
+    rerender(
+      <Bubble
+        variant="light"
+        bordered={false}
+        groupPosition="first"
+        data-testid="bubble"
+      >
+        child
+      </Bubble>
+    )
+    bubble = screen.getByTestId('bubble')
+    expect(bubble).toHaveClass('bg-[#f2f1ef]', 'text-[#000000]')
+    expect(bubble).not.toHaveClass('border', 'border-black/[0.08]')
+    expect(bubble).toHaveClass('rounded-bl-[4px]')
+  })
+
+  it('lets an explicit radius replace the group corner table', () => {
+    renderWithProviders(
+      <Bubble
+        variant="light"
+        groupPosition="middle"
+        radiusClassName="rounded-[20px]"
+        widthClassName="w-fit"
+        paddingClassName="p-0.5"
+        data-testid="bubble"
+      >
+        child
+      </Bubble>
+    )
+    const bubble = screen.getByTestId('bubble')
+    expect(bubble).toHaveClass('rounded-[20px]', 'w-fit', 'p-0.5')
+    expect(bubble).not.toHaveClass('rounded-tl-[4px]')
+  })
+})

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

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import CarouselNav from './CarouselNav'
+import { VIEWER_NAV_CLASS } from './viewerChromeClasses'
+
+describe('CarouselNav', () => {
+  it('uses default labels and independent handlers', () => {
+    const onPrev = vi.fn()
+    const onNext = vi.fn()
+    renderWithProviders(<CarouselNav onPrev={onPrev} onNext={onNext} />)
+
+    const prev = screen.getByRole('button', { name: 'Previous' })
+    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)
+    expect(onPrev).toHaveBeenCalledOnce()
+    expect(onNext).toHaveBeenCalledOnce()
+  })
+
+  it('supports custom accessible labels', () => {
+    renderWithProviders(
+      <CarouselNav
+        onPrev={vi.fn()}
+        onNext={vi.fn()}
+        prevLabel="Previous image"
+        nextLabel="Next image"
+      />
+    )
+    expect(screen.getByRole('button', { name: 'Previous image' })).toBeVisible()
+    expect(screen.getByRole('button', { name: 'Next image' })).toBeVisible()
+  })
+})

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

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import CompactDocumentRow from './CompactDocumentRow'
+
+describe('CompactDocumentRow', () => {
+  it('resolves title from title, filename, then File', () => {
+    const { rerender } = renderWithProviders(
+      <CompactDocumentRow variant="dark" title="Custom" filename="name.pdf" />
+    )
+    expect(screen.getByText('Custom')).toBeInTheDocument()
+    rerender(<CompactDocumentRow variant="dark" filename="name.pdf" />)
+    expect(screen.getByText('name.pdf')).toBeInTheDocument()
+    rerender(<CompactDocumentRow variant="dark" />)
+    expect(screen.getByText('File')).toBeInTheDocument()
+  })
+
+  it('renders metadata only when it has a value and defaults MIME type', () => {
+    const { container, rerender } = renderWithProviders(
+      <CompactDocumentRow
+        variant="dark"
+        filename="report.pdf"
+        fileSize={1024}
+      />
+    )
+    expect(screen.getByText('PDF · 1.0 KB')).toBeInTheDocument()
+    rerender(
+      <CompactDocumentRow
+        variant="dark"
+        filename="report"
+        mimeType="application/octet-stream"
+      />
+    )
+    expect(screen.queryByText(/·/)).toBeNull()
+    const genericIconMarkup = container.querySelector('svg')?.innerHTML
+    rerender(
+      <CompactDocumentRow
+        variant="dark"
+        filename="report.pdf"
+        mimeType="application/pdf"
+      />
+    )
+    expect(container.querySelector('svg')?.innerHTML).not.toBe(
+      genericIconMarkup
+    )
+  })
+
+  it('maps variant classes across metadata, icon, and activation', () => {
+    const onActivate = vi.fn()
+    const { container, rerender } = renderWithProviders(
+      <CompactDocumentRow
+        variant="dark"
+        filename="report.pdf"
+        onActivate={onActivate}
+        activateLabel="Open report"
+      />
+    )
+    expect(screen.getByText('PDF')).toHaveClass('text-white/55')
+    const darkIconTile = container.querySelector('div[aria-hidden]')
+    expect(darkIconTile).toHaveClass('bg-white/10')
+    expect(darkIconTile?.querySelector('svg')).toHaveClass(
+      'size-6',
+      'text-white/85'
+    )
+    expect(screen.getByRole('button', { name: 'Open report' })).toHaveClass(
+      'hover:bg-white/[0.04]'
+    )
+
+    rerender(
+      <CompactDocumentRow
+        variant="light"
+        filename="report.pdf"
+        onActivate={onActivate}
+        activateLabel="Open report"
+      />
+    )
+    expect(screen.getByText('PDF')).toHaveClass('text-black/65')
+    const lightIconTile = container.querySelector('div[aria-hidden]')
+    expect(lightIconTile).toHaveClass('bg-black/5')
+    expect(lightIconTile?.querySelector('svg')).toHaveClass(
+      'size-6',
+      'text-black/85'
+    )
+    expect(screen.getByRole('button', { name: 'Open report' })).toHaveClass(
+      'hover:bg-black/[0.04]'
+    )
+  })
+
+  it('activates its body without nesting the trailing action', () => {
+    const onActivate = vi.fn()
+    renderWithProviders(
+      <CompactDocumentRow
+        variant="dark"
+        filename="report.pdf"
+        onActivate={onActivate}
+        activateLabel="Open report"
+        trailingAction={<button type="button">Download</button>}
+      />
+    )
+    const body = screen.getByRole('button', { name: 'Open report' })
+    expect(body).toBeInTheDocument()
+    expect(body).not.toContainElement(
+      screen.getByRole('button', { name: 'Download' })
+    )
+    fireEvent.click(body)
+    expect(onActivate).toHaveBeenCalledOnce()
+  })
+
+  it('renders a plain body when activation is omitted', () => {
+    renderWithProviders(
+      <CompactDocumentRow variant="dark" filename="report.pdf" />
+    )
+    expect(screen.queryByRole('button', { name: /report/ })).toBeNull()
+  })
+})

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

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import DismissButton from './DismissButton'
+
+describe('DismissButton', () => {
+  it('uses the default label, invokes the handler, and stops propagation', () => {
+    const onClick = vi.fn()
+    const outerClick = vi.fn()
+    renderWithProviders(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={outerClick}>
+        <DismissButton onClick={onClick} />
+      </div>
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss attachment' }))
+    expect(onClick).toHaveBeenCalledOnce()
+    expect(outerClick).not.toHaveBeenCalled()
+  })
+
+  it('supports a custom label and inline styling', () => {
+    renderWithProviders(
+      <DismissButton
+        onClick={vi.fn()}
+        ariaLabel="Remove file"
+        variant="inline"
+      />
+    )
+    const button = screen.getByRole('button', { name: 'Remove file' })
+    expect(button).toHaveClass('bg-white/15')
+    expect(button).not.toHaveClass('bg-[#121110]/85')
+  })
+})

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

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  fireEvent,
+  renderWithProviders,
+  screen,
+  waitFor,
+} from '../../../test/utils'
+
+import DownloadAction from './DownloadAction'
+import { triggerDownload } from './triggerDownload'
+import { VIEWER_ACTION_CLASS } from './viewerChromeClasses'
+
+vi.mock('./triggerDownload', () => ({
+  triggerDownload: vi.fn(() => Promise.resolve()),
+}))
+
+const mockedTriggerDownload = vi.mocked(triggerDownload)
+
+beforeEach(() => {
+  mockedTriggerDownload.mockReset()
+  mockedTriggerDownload.mockResolvedValue(undefined)
+})
+
+describe('DownloadAction', () => {
+  it('uses a visible label for the default pill variant', () => {
+    renderWithProviders(<DownloadAction url="/file.pdf" />)
+    const button = screen.getByRole('button', { name: 'Download' })
+    expect(button).toHaveTextContent('Download')
+    expect(button).not.toHaveAttribute('aria-label')
+  })
+
+  it.each(['inline', 'viewer'] as const)(
+    'uses an accessible-only label for the %s variant',
+    (variant) => {
+      renderWithProviders(
+        <DownloadAction url="/file.pdf" variant={variant} label="Save file" />
+      )
+      const button = screen.getByRole('button', { name: 'Save file' })
+      expect(button).not.toHaveTextContent('Save file')
+    }
+  )
+
+  it('allows iconOnly to override the pill default', () => {
+    const { rerender } = renderWithProviders(
+      <DownloadAction url="/file.pdf" label="Save" iconOnly />
+    )
+    expect(screen.getByRole('button', { name: 'Save' })).not.toHaveTextContent(
+      'Save'
+    )
+    rerender(
+      <DownloadAction
+        url="/file.pdf"
+        variant="viewer"
+        label="Save"
+        iconOnly={false}
+      />
+    )
+    expect(screen.getByRole('button', { name: 'Save' })).not.toHaveTextContent(
+      'Save'
+    )
+  })
+
+  it('stops propagation and calls the download once', async () => {
+    const outerClick = vi.fn()
+    renderWithProviders(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={outerClick}>
+        <DownloadAction
+          url="/file.pdf"
+          filename="report.pdf"
+          onTriggered={vi.fn()}
+        />
+      </div>
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    await waitFor(() =>
+      expect(mockedTriggerDownload).toHaveBeenCalledWith(
+        '/file.pdf',
+        'report.pdf'
+      )
+    )
+    expect(mockedTriggerDownload).toHaveBeenCalledOnce()
+    expect(outerClick).not.toHaveBeenCalled()
+  })
+
+  it('disables repeated clicks while downloading and settles on success', async () => {
+    let resolve: () => void = () => undefined
+    mockedTriggerDownload.mockReturnValueOnce(
+      new Promise<void>((done) => {
+        resolve = done
+      })
+    )
+    const onTriggered = vi.fn()
+    renderWithProviders(
+      <DownloadAction url="/file.pdf" onTriggered={onTriggered} />
+    )
+    const button = screen.getByRole('button', { name: 'Download' })
+    fireEvent.click(button)
+    fireEvent.click(button)
+    expect(button).toBeDisabled()
+    expect(mockedTriggerDownload).toHaveBeenCalledOnce()
+    resolve()
+    await waitFor(() => expect(button).toBeEnabled())
+    expect(onTriggered).toHaveBeenCalledOnce()
+  })
+
+  it('settles and notifies even when downloading rejects', async () => {
+    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 waitFor(() => expect(button).toBeEnabled())
+    expect(onTriggered).toHaveBeenCalledOnce()
+  })
+
+  it('maps tone classes for pill and inline variants', () => {
+    const { rerender } = renderWithProviders(
+      <DownloadAction url="/file.pdf" tone="dark" />
+    )
+    expect(screen.getByRole('button', { name: 'Download' })).toHaveClass(
+      'bg-[#121110]',
+      'text-white'
+    )
+    rerender(<DownloadAction url="/file.pdf" tone="light" />)
+    expect(screen.getByRole('button', { name: 'Download' })).toHaveClass(
+      'bg-white',
+      'text-[#121110]'
+    )
+    rerender(<DownloadAction url="/file.pdf" variant="inline" tone="dark" />)
+    expect(screen.getByRole('button', { name: 'Download' })).toHaveClass(
+      'text-white/70'
+    )
+    rerender(<DownloadAction url="/file.pdf" variant="inline" tone="light" />)
+    expect(screen.getByRole('button', { name: 'Download' })).toHaveClass(
+      'text-black/70'
+    )
+  })
+
+  it('uses the shared viewer action class', () => {
+    renderWithProviders(<DownloadAction url="/file.pdf" variant="viewer" />)
+    expect(screen.getByRole('button', { name: 'Download' })).toHaveClass(
+      VIEWER_ACTION_CLASS
+    )
+  })
+})

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

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import ImageViewer from './ImageViewer'
+
+describe('ImageViewer', () => {
+  const items = [
+    { src: 'https://cdn.example.com/one.jpg', alt: 'One' },
+    { src: 'https://cdn.example.com/two.jpg', filename: 'two.png' },
+  ]
+
+  it('renders nothing without an active item', () => {
+    const { container } = renderWithProviders(
+      <ImageViewer open onClose={vi.fn()} items={[]} />
+    )
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('gates the image on open and resolves filename labels', () => {
+    const { rerender } = renderWithProviders(
+      <ImageViewer open={false} onClose={vi.fn()} items={[items[0]]} />
+    )
+    expect(screen.queryByRole('img')).toBeNull()
+    expect(screen.getByTestId('image-viewer')).toHaveAttribute(
+      'aria-label',
+      'one.jpg'
+    )
+    expect(
+      screen
+        .getByTestId('image-viewer')
+        .querySelector('button[aria-label="Download one.jpg"]')
+    ).toBeInTheDocument()
+    rerender(<ImageViewer open onClose={vi.fn()} items={[items[0]]} />)
+    expect(screen.getByRole('img')).toHaveAttribute('alt', 'One')
+    expect(screen.getByRole('img')).toHaveAttribute('draggable', 'false')
+  })
+
+  it('renders counter and navigation only for multiple items', () => {
+    renderWithProviders(
+      <ImageViewer open onClose={vi.fn()} items={items} initialIndex={99} />
+    )
+    expect(screen.getByText('2 / 2')).toBeInTheDocument()
+    expect(
+      screen.getByRole('button', { name: 'Previous image' })
+    ).toBeInTheDocument()
+    expect(screen.getByRole('img')).toHaveAttribute('src', items[1].src)
+    fireEvent.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

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import MediaStackGrid from './MediaStackGrid'
+
+const tiles = (count: number) =>
+  Array.from({ length: count }, (_, index) => ({
+    content: <span>tile {index + 1}</span>,
+    ariaLabel: index === 1 ? 'Second tile' : undefined,
+  }))
+
+describe('MediaStackGrid', () => {
+  it('renders nothing for empty tiles', () => {
+    const { container } = renderWithProviders(<MediaStackGrid tiles={[]} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it.each([
+    [1, 'aspect-square'],
+    [2, 'aspect-[16/9]'],
+    [3, 'aspect-[4/3]'],
+    [4, 'aspect-[379/286]'],
+  ])('renders the %s-tile layout', (count, layoutClass) => {
+    const { container } = renderWithProviders(
+      <MediaStackGrid tiles={tiles(count)} className="custom-grid" />
+    )
+    expect(container.firstElementChild).toHaveClass(layoutClass, 'custom-grid')
+    expect(screen.getAllByText(/tile/)).toHaveLength(count)
+  })
+
+  it('clamps visible tiles and places overflow on the last tile', () => {
+    const { container, rerender } = renderWithProviders(
+      <MediaStackGrid tiles={tiles(6)} maxVisible={4} />
+    )
+    expect(container.querySelectorAll('span')).toHaveLength(4)
+    expect(screen.getByText('+2')).toBeInTheDocument()
+    expect(screen.getByText('+2').parentElement).toHaveTextContent('tile 4')
+    rerender(<MediaStackGrid tiles={tiles(2)} maxVisible={4} />)
+    expect(container.querySelectorAll('span')).toHaveLength(2)
+    expect(screen.queryByText(/^\+/)).toBeNull()
+    rerender(<MediaStackGrid tiles={tiles(1)} singleAspectRatio={0.5} />)
+    expect(
+      screen.getByText('tile 1').closest('div')?.parentElement
+    ).toHaveStyle({
+      aspectRatio: '0.5',
+    })
+  })
+
+  it('renders activatable buttons with labels and indexes', () => {
+    const onActivate = vi.fn()
+    renderWithProviders(
+      <MediaStackGrid tiles={tiles(3)} onTileActivate={onActivate} />
+    )
+    const buttons = screen.getAllByRole('button')
+    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])
+    expect(onActivate).toHaveBeenNthCalledWith(1, 0)
+    expect(onActivate).toHaveBeenNthCalledWith(2, 2)
+  })
+
+  it('uses non-interactive shells when no activation handler is supplied', () => {
+    renderWithProviders(<MediaStackGrid tiles={tiles(2)} />)
+    expect(screen.queryAllByRole('button')).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import PdfViewer from './PdfViewer'
+
+describe('PdfViewer', () => {
+  const items = [
+    { src: 'https://cdn.example.com/one.pdf#page=3' },
+    { src: 'https://cdn.example.com/two.pdf', filename: 'second.pdf' },
+  ]
+
+  it('renders nothing with no active document', () => {
+    const { container } = renderWithProviders(
+      <PdfViewer open onClose={vi.fn()} items={[]} />
+    )
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('merges viewer parameters into existing fragments', () => {
+    renderWithProviders(<PdfViewer open onClose={vi.fn()} items={[items[0]]} />)
+    const iframe = screen.getByTitle('one.pdf')
+    expect(iframe).toHaveAttribute(
+      'src',
+      'https://cdn.example.com/one.pdf#page=3&toolbar=0&navpanes=0'
+    )
+    expect(iframe).toHaveAttribute(
+      'sandbox',
+      'allow-scripts allow-forms allow-popups allow-downloads'
+    )
+  })
+
+  it('uses filename precedence and navigates stacked documents', () => {
+    renderWithProviders(
+      <PdfViewer open onClose={vi.fn()} items={items} initialIndex={1} />
+    )
+    expect(screen.getByRole('dialog')).toHaveAttribute(
+      'aria-label',
+      'second.pdf'
+    )
+    expect(screen.getByText('2 / 2')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Previous document' }))
+    expect(screen.getByTitle('one.pdf')).toBeInTheDocument()
+  })
+})

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

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import VideoViewer from './VideoViewer'
+
+describe('VideoViewer', () => {
+  const items = [
+    {
+      src: 'https://cdn.example.com/one.mp4',
+      poster: '/one.jpg',
+      mimeType: 'video/mp4',
+      filename: 'one.mp4',
+      preload: 'auto' as const,
+    },
+    { src: 'https://cdn.example.com/two.webm', mimeType: 'video/webm' },
+  ]
+
+  it('renders nothing with no active video', () => {
+    const { container } = renderWithProviders(
+      <VideoViewer open onClose={vi.fn()} items={[]} />
+    )
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders media attributes and an optional source type', () => {
+    renderWithProviders(
+      <VideoViewer open onClose={vi.fn()} items={[items[0]]} />
+    )
+    const video = screen.getByTestId('video-viewer').querySelector('video')
+    expect(video).not.toBeNull()
+    if (!video) throw new Error('Expected video element')
+    expect(video).toHaveAttribute('src', items[0].src)
+    expect(video).toHaveAttribute('poster', items[0].poster)
+    expect(video).toHaveAttribute('preload', 'auto')
+    expect(video).toHaveAttribute('autoplay')
+    expect(video?.muted).toBe(true)
+    expect(video.querySelector('source')).toHaveAttribute('type', 'video/mp4')
+  })
+
+  it('defaults preload and navigates stacked items', () => {
+    renderWithProviders(<VideoViewer open onClose={vi.fn()} items={items} />)
+    expect(screen.getByText('1 / 2')).toBeInTheDocument()
+    expect(
+      screen.getByTestId('video-viewer').querySelector('video')
+    ).toHaveAttribute('preload', 'auto')
+    fireEvent.click(screen.getByRole('button', { name: 'Next video' }))
+    expect(
+      screen.getByTestId('video-viewer').querySelector('video')
+    ).toHaveAttribute('src', items[1].src)
+    expect(
+      screen.getByTestId('video-viewer').querySelector('video')
+    ).toHaveAttribute('preload', 'metadata')
+  })
+})

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

@@ -0,0 +1,246 @@
+import { useLayoutEffect } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import { VIEWER_ACTION_CLASS } from './viewerChromeClasses'
+import ViewerShell from './ViewerShell'
+
+const dialogPrototype = HTMLDialogElement.prototype
+const originalDialogDescriptors = {
+  close: Object.getOwnPropertyDescriptor(dialogPrototype, 'close'),
+  showModal: Object.getOwnPropertyDescriptor(dialogPrototype, 'showModal'),
+}
+
+const defineDialogMethod = (
+  name: 'close' | 'showModal',
+  implementation: () => void
+) => {
+  Object.defineProperty(dialogPrototype, name, {
+    configurable: true,
+    value: implementation,
+    writable: true,
+  })
+}
+
+const restoreDialogMethod = (
+  name: 'close' | 'showModal',
+  descriptor: PropertyDescriptor | undefined
+) => {
+  if (descriptor) Object.defineProperty(dialogPrototype, name, descriptor)
+  else Reflect.deleteProperty(dialogPrototype, name)
+}
+
+const PreOpenDialog = () => {
+  useLayoutEffect(() => {
+    document.querySelector('[data-testid="viewer"]')?.setAttribute('open', '')
+  }, [])
+  return null
+}
+
+afterEach(() => {
+  restoreDialogMethod('close', originalDialogDescriptors.close)
+  restoreDialogMethod('showModal', originalDialogDescriptors.showModal)
+  vi.restoreAllMocks()
+})
+
+describe('ViewerShell', () => {
+  it('drives open state, chrome content, and forwarded attributes', () => {
+    const { rerender } = renderWithProviders(
+      <ViewerShell
+        open
+        onClose={vi.fn()}
+        counter="2 / 3"
+        actions={<button type="button">Action</button>}
+        ariaLabel="report.pdf"
+        data-testid="viewer"
+      >
+        content
+      </ViewerShell>
+    )
+    const dialog = screen.getByTestId('viewer')
+    expect(dialog).toHaveAttribute('open')
+    expect(dialog).toHaveAttribute('aria-label', 'report.pdf')
+    expect(dialog).toHaveTextContent('2 / 3')
+    expect(screen.getByRole('button', { name: 'Action' })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Close viewer' })).toHaveClass(
+      VIEWER_ACTION_CLASS
+    )
+
+    rerender(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(dialog).not.toHaveAttribute('open')
+  })
+
+  it('focuses close on open and restores the previous focus on close', () => {
+    const onClose = vi.fn()
+    const previouslyFocused = document.createElement('button')
+    document.body.appendChild(previouslyFocused)
+    previouslyFocused.focus()
+    const { rerender } = renderWithProviders(
+      <ViewerShell open={false} onClose={onClose} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    rerender(
+      <ViewerShell open onClose={onClose} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(screen.getByRole('button', { name: 'Close viewer' })).toHaveFocus()
+    rerender(
+      <ViewerShell open={false} onClose={onClose} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(previouslyFocused).toHaveFocus()
+    previouslyFocused.remove()
+  })
+
+  it('falls back to the open attribute when dialog methods are absent', () => {
+    Reflect.deleteProperty(dialogPrototype, 'showModal')
+    Reflect.deleteProperty(dialogPrototype, 'close')
+    const { rerender } = renderWithProviders(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    const dialog = screen.getByTestId('viewer')
+    expect(dialog).toHaveAttribute('open')
+    rerender(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(dialog).not.toHaveAttribute('open')
+  })
+
+  it('falls back when showModal throws', () => {
+    const showModal = vi.fn(() => {
+      throw new Error('not supported')
+    })
+    defineDialogMethod('showModal', showModal)
+    const { container } = renderWithProviders(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(container.querySelector('dialog')).toHaveAttribute('open')
+    expect(showModal).toHaveBeenCalledOnce()
+  })
+
+  it('falls back when close throws during cleanup', () => {
+    const close = vi.fn(() => {
+      throw new Error('not supported')
+    })
+    defineDialogMethod('close', close)
+    Reflect.deleteProperty(dialogPrototype, 'showModal')
+    const { rerender } = renderWithProviders(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    const dialog = screen.getByTestId('viewer')
+    rerender(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(close).toHaveBeenCalledOnce()
+    expect(dialog).not.toHaveAttribute('open')
+  })
+
+  it('falls back when close throws in the closed branch', () => {
+    const close = vi.fn(() => {
+      throw new Error('not supported')
+    })
+    defineDialogMethod('close', close)
+    renderWithProviders(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        <PreOpenDialog />
+      </ViewerShell>
+    )
+    expect(close).toHaveBeenCalledOnce()
+    expect(screen.getByTestId('viewer')).not.toHaveAttribute('open')
+  })
+
+  it('does not call showModal when the dialog is already open', () => {
+    const showModal = vi.fn()
+    defineDialogMethod('showModal', showModal)
+    renderWithProviders(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        <PreOpenDialog />
+      </ViewerShell>
+    )
+    expect(screen.getByTestId('viewer')).toHaveAttribute('open')
+    expect(showModal).not.toHaveBeenCalled()
+  })
+
+  it('does not restore focus to a detached element', () => {
+    const previouslyFocused = document.createElement('button')
+    document.body.appendChild(previouslyFocused)
+    previouslyFocused.focus()
+    const { rerender } = renderWithProviders(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    rerender(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    previouslyFocused.remove()
+    expect(() =>
+      rerender(
+        <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+          content
+        </ViewerShell>
+      )
+    ).not.toThrow()
+    expect(document.activeElement).not.toBe(previouslyFocused)
+  })
+
+  it('uses the default accessible label', () => {
+    renderWithProviders(
+      <ViewerShell open onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(screen.getByTestId('viewer')).toHaveAttribute(
+      'aria-label',
+      'Attachment viewer'
+    )
+  })
+
+  it('does not close a dialog that was never opened', () => {
+    const close = vi.fn()
+    defineDialogMethod('close', close)
+    renderWithProviders(
+      <ViewerShell open={false} onClose={vi.fn()} data-testid="viewer">
+        content
+      </ViewerShell>
+    )
+    expect(close).not.toHaveBeenCalled()
+  })
+
+  it('closes from the close, native close, and backdrop events', () => {
+    const onClose = vi.fn()
+    renderWithProviders(
+      <ViewerShell open onClose={onClose} data-testid="viewer">
+        <span>content</span>
+      </ViewerShell>
+    )
+    const dialog = screen.getByTestId('viewer')
+    fireEvent.click(screen.getByRole('button', { name: 'Close viewer' }))
+    fireEvent(dialog, new Event('close'))
+    fireEvent.click(dialog)
+    expect(onClose).toHaveBeenCalledTimes(3)
+    onClose.mockClear()
+    fireEvent.click(screen.getByText('content'))
+    expect(onClose).not.toHaveBeenCalled()
+  })
+})

package/src/components/MessageAttachment/_shared/fileMeta.test.ts

@@ -25,6 +25,14 @@ describe('formatFileSize', () => {
     expect(formatFileSize(Infinity)).toBe('')
     expect(formatFileSize(-1)).toBe('')
   })
+
+  it('handles unit boundaries without crossing into the next unit early', () => {
+    expect(formatFileSize(1023)).toBe('1023 B')
+    expect(formatFileSize(1024 * 1024 - 1)).toBe('1024.0 KB')
+    expect(formatFileSize(1024 * 1024)).toBe('1.00 MB')
+    expect(formatFileSize(1024 ** 3 - 1)).toBe('1024.00 MB')
+    expect(formatFileSize(1024 ** 3)).toBe('1.00 GB')
+  })
 })
 
 describe('getFileExtensionLabel', () => {
@@ -43,6 +51,18 @@ describe('getFileExtensionLabel', () => {
     expect(getFileExtensionLabel('application/octet-stream')).toBeUndefined()
     expect(getFileExtensionLabel()).toBeUndefined()
   })
+
+  it('handles dot boundaries, extension length, and MIME fallbacks', () => {
+    expect(getFileExtensionLabel('text/plain', '.gitignore')).toBe('TXT')
+    expect(getFileExtensionLabel('text/plain', 'notes.')).toBe('TXT')
+    expect(getFileExtensionLabel('image/webp', 'photo.webp')).toBe('WEBP')
+    expect(getFileExtensionLabel('image/webp', 'photo.abcdef')).toBe('WEBP')
+    expect(getFileExtensionLabel('application/json', 'data.12345')).toBe(
+      '12345'
+    )
+    expect(getFileExtensionLabel('image/*')).toBeUndefined()
+    expect(getFileExtensionLabel('application/octet-stream')).toBeUndefined()
+  })
 })
 
 describe('buildCompactMetaLabel', () => {
@@ -59,6 +79,23 @@ describe('buildCompactMetaLabel', () => {
   it('returns undefined when nothing is renderable', () => {
     expect(buildCompactMetaLabel()).toBeUndefined()
   })
+
+  it('drops non-positive and non-number sizes while retaining size-only labels', () => {
+    expect(buildCompactMetaLabel('application/pdf', 'report.pdf', 0)).toBe(
+      'PDF'
+    )
+    expect(buildCompactMetaLabel('application/pdf', 'report.pdf', -1)).toBe(
+      'PDF'
+    )
+    expect(buildCompactMetaLabel(undefined, undefined, 1024)).toBe('1.0 KB')
+    expect(
+      buildCompactMetaLabel(
+        'application/octet-stream',
+        undefined,
+        '1024' as never
+      )
+    ).toBeUndefined()
+  })
 })
 
 describe('filenameFromUrl', () => {
@@ -77,4 +114,11 @@ describe('filenameFromUrl', () => {
   it('falls back to a default when the URL cannot be parsed', () => {
     expect(filenameFromUrl('not a url at all')).toBe('download')
   })
+
+  it('handles trailing slashes, deep paths, and query strings', () => {
+    expect(filenameFromUrl('https://cdn.example.com/folder/')).toBe('download')
+    expect(
+      filenameFromUrl('https://cdn.example.com/a/b/c/report.pdf?download=1')
+    ).toBe('report.pdf')
+  })
 })

package/src/components/MessageAttachment/_shared/triggerDownload.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { triggerDownload } from './triggerDownload'
+
+describe('triggerDownload', () => {
+  const fetchMock = vi.fn()
+  const openMock = vi.fn()
+  const createObjectURLMock = vi.fn()
+  const revokeObjectURLMock = vi.fn()
+  const clickMock = vi
+    .spyOn(HTMLAnchorElement.prototype, 'click')
+    .mockImplementation(() => undefined)
+
+  beforeEach(() => {
+    vi.stubGlobal('fetch', fetchMock)
+    vi.spyOn(window, 'open').mockImplementation(openMock)
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: createObjectURLMock,
+    })
+    Object.defineProperty(URL, 'revokeObjectURL', {
+      configurable: true,
+      value: revokeObjectURLMock,
+    })
+    fetchMock.mockReset()
+    openMock.mockReset()
+    createObjectURLMock.mockReset()
+    revokeObjectURLMock.mockReset()
+    clickMock.mockClear()
+  })
+
+  it('downloads a successful response with the supplied filename', async () => {
+    const blob = new Blob(['file'])
+    fetchMock.mockResolvedValue({
+      ok: true,
+      blob: () => Promise.resolve(blob),
+    })
+    createObjectURLMock.mockReturnValue('blob:attachment')
+    const appendSpy = vi.spyOn(document.body, 'appendChild')
+    const removeSpy = vi.spyOn(document.body, 'removeChild')
+
+    await expect(
+      triggerDownload('https://cdn.example.com/file.pdf', 'report.pdf')
+    ).resolves.toBeUndefined()
+
+    expect(fetchMock).toHaveBeenCalledWith('https://cdn.example.com/file.pdf', {
+      mode: 'cors',
+    })
+    expect(createObjectURLMock).toHaveBeenCalledWith(blob)
+    expect(clickMock).toHaveBeenCalledOnce()
+    expect(revokeObjectURLMock).toHaveBeenCalledWith('blob:attachment')
+    const anchor = appendSpy.mock.calls.at(-1)?.[0] as HTMLAnchorElement
+    expect(anchor.href).toBe('blob:attachment')
+    expect(anchor.download).toBe('report.pdf')
+    expect(anchor.style.display).toBe('none')
+    expect(removeSpy).toHaveBeenCalledWith(anchor)
+  })
+
+  it('uses the URL filename when no filename is supplied', async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      blob: () => Promise.resolve(new Blob()),
+    })
+    createObjectURLMock.mockReturnValue('blob:attachment')
+    const appendSpy = vi.spyOn(document.body, 'appendChild')
+
+    await triggerDownload('https://cdn.example.com/a/My%20file.pdf')
+
+    expect(
+      (appendSpy.mock.calls.at(-1)?.[0] as HTMLAnchorElement).download
+    ).toBe('My file.pdf')
+  })
+
+  it.each(['a non-ok response', 'a rejected fetch'])(
+    'falls back to a new window for %s',
+    async (label) => {
+      if (label === 'a non-ok response') {
+        fetchMock.mockResolvedValue({ ok: false, status: 404 })
+      } else {
+        fetchMock.mockRejectedValue(new Error('offline'))
+      }
+      openMock.mockReturnValue({})
+
+      await expect(
+        triggerDownload('https://cdn.example.com/file.pdf')
+      ).resolves.toBeUndefined()
+
+      expect(openMock).toHaveBeenCalledWith(
+        'https://cdn.example.com/file.pdf',
+        '_blank',
+        'noopener,noreferrer'
+      )
+    }
+  )
+
+  it('uses a raw-url anchor when the popup is blocked', async () => {
+    fetchMock.mockRejectedValue(new Error('offline'))
+    openMock.mockReturnValue(null)
+    const appendSpy = vi.spyOn(document.body, 'appendChild')
+    const removeSpy = vi.spyOn(document.body, 'removeChild')
+
+    await expect(
+      triggerDownload('https://cdn.example.com/file.pdf')
+    ).resolves.toBeUndefined()
+
+    const anchor = appendSpy.mock.calls.at(-1)?.[0] as HTMLAnchorElement
+    expect(anchor.href).toBe('https://cdn.example.com/file.pdf')
+    expect(anchor.download).toBe('file.pdf')
+    expect(anchor.target).toBe('_blank')
+    expect(anchor.rel).toBe('noopener noreferrer')
+    expect(removeSpy).toHaveBeenCalledWith(anchor)
+  })
+})

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

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+
+import { fireEvent, renderWithProviders, screen } from '../../../test/utils'
+
+import { useCarousel } from './useCarousel'
+
+const Harness = ({
+  open,
+  length,
+  initialIndex = 0,
+}: {
+  open: boolean
+  length: number
+  initialIndex?: number
+}) => {
+  const { index, prev, next } = useCarousel({ open, length, initialIndex })
+  return (
+    <div>
+      <span data-testid="index">{index}</span>
+      <button type="button" onClick={prev}>
+        Prev
+      </button>
+      <button type="button" onClick={next}>
+        Next
+      </button>
+    </div>
+  )
+}
+
+describe('useCarousel', () => {
+  it('clamps initial index, wraps, and resets on reopen', () => {
+    const { rerender } = renderWithProviders(
+      <Harness open length={3} initialIndex={99} />
+    )
+    expect(screen.getByTestId('index')).toHaveTextContent('2')
+    fireEvent.click(screen.getByRole('button', { name: 'Next' }))
+    expect(screen.getByTestId('index')).toHaveTextContent('0')
+    fireEvent.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} />)
+    expect(screen.getByTestId('index')).toHaveTextContent('1')
+  })
+
+  it('handles arrows only when open with multiple items', () => {
+    const { rerender } = renderWithProviders(
+      <Harness open length={2} initialIndex={0} />
+    )
+    const right = fireEvent.keyDown(window, { key: 'ArrowRight' })
+    expect(screen.getByTestId('index')).toHaveTextContent('1')
+    expect(right).toBe(false)
+    for (const tagName of ['video', 'audio'] as const) {
+      const media = document.createElement(tagName)
+      media.tabIndex = 0
+      document.body.appendChild(media)
+      media.focus()
+      fireEvent.keyDown(window, { key: 'ArrowLeft' })
+      expect(screen.getByTestId('index')).toHaveTextContent('1')
+      media.remove()
+    }
+    rerender(<Harness open length={1} />)
+    fireEvent.keyDown(window, { key: 'ArrowRight' })
+    expect(screen.getByTestId('index')).toHaveTextContent('0')
+    rerender(<Harness open={false} length={2} />)
+    fireEvent.keyDown(window, { key: 'ArrowRight' })
+    expect(screen.getByTestId('index')).toHaveTextContent('0')
+  })
+})

package/src/components/MessageAttachment/_shared/viewerChromeClasses.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+
+import { VIEWER_ACTION_CLASS, VIEWER_NAV_CLASS } from './viewerChromeClasses'
+
+describe('viewer chrome classes', () => {
+  it('keeps the load-bearing action button tokens', () => {
+    expect(VIEWER_ACTION_CLASS).toContain('size-10')
+    expect(VIEWER_ACTION_CLASS).toContain('rounded-full')
+  })
+
+  it('keeps the load-bearing navigation button tokens', () => {
+    expect(VIEWER_NAV_CLASS).toContain('absolute')
+    expect(VIEWER_NAV_CLASS).toContain('size-12')
+    expect(VIEWER_NAV_CLASS).toContain('-translate-y-1/2')
+  })
+})