@linktr.ee/messaging-react 2.2.3 → 2.3.0-rc-1779486690

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-IlgylJT2.cjs");exports.ActionButton=e.ActionButton;exports.Avatar=e.Avatar;exports.ChannelEmptyState=e.ChannelEmptyState;exports.ChannelList=e.ChannelList;exports.ChannelView=e.ChannelView;exports.CustomMessageProvider=e.CustomMessageProvider;exports.FaqList=e.FaqList;exports.FaqListItem=e.FaqListItem;exports.LinkAttachment=e.LinkAttachment;exports.LockedAttachment=e.LockedAttachment;exports.MediaMessage=e.MediaMessage;exports.MessageAttachment=e.MessageAttachment;exports.MessageVoteButtons=e.MessageVoteButtons;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.buildCompactMetaLabel=e.buildCompactMetaLabel;exports.formatFileSize=e.formatFileSize;exports.formatRelativeTime=e.formatRelativeTime;exports.getFileExtensionLabel=e.getFileExtensionLabel;exports.getMessageDisplayText=e.getMessageDisplayText;exports.isLinkAttachment=e.isLinkAttachment;exports.isUuidLike=e.isUuidLike;exports.messageAttachmentGroupPositionFromStream=e.bubbleGroupPositionFromStream;exports.normalizeLanguageCode=e.normalizeLanguageCode;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useCustomMessage=e.useCustomMessage;exports.useMessageVote=e.useMessageVote;exports.useMessaging=e.useMessaging;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-CQ913euH.cjs");exports.ActionButton=e.ActionButton;exports.Avatar=e.Avatar;exports.ChannelEmptyState=e.ChannelEmptyState;exports.ChannelList=e.ChannelList;exports.ChannelView=e.ChannelView;exports.CustomMessageProvider=e.CustomMessageProvider;exports.FaqList=e.FaqList;exports.FaqListItem=e.FaqListItem;exports.LinkAttachment=e.LinkAttachment;exports.LockedAttachment=e.LockedAttachment;exports.MediaMessage=e.MediaMessage;exports.MessageAttachment=e.MessageAttachment;exports.MessageVoteButtons=e.MessageVoteButtons;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.buildCompactMetaLabel=e.buildCompactMetaLabel;exports.formatFileSize=e.formatFileSize;exports.formatRelativeTime=e.formatRelativeTime;exports.getFileExtensionLabel=e.getFileExtensionLabel;exports.getMessageDisplayText=e.getMessageDisplayText;exports.isLinkAttachment=e.isLinkAttachment;exports.isUuidLike=e.isUuidLike;exports.messageAttachmentGroupPositionFromStream=e.bubbleGroupPositionFromStream;exports.normalizeLanguageCode=e.normalizeLanguageCode;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useCustomMessage=e.useCustomMessage;exports.useMessageVote=e.useMessageVote;exports.useMessaging=e.useMessaging;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -428,7 +428,7 @@ declare interface ImageAttachmentSharedProps extends MessageAttachmentBaseProps
     /** Single image — convenience for the most common case. */
     src?: string;
     alt?: string;
-    /** Filename surfaced in the viewer toolbar + download default name. */
+    /** Filename used as the viewer dialog's accessible name. */
     filename?: string;
     /**
      * Stacked images. Takes precedence over `src` when set. Renders a
@@ -703,13 +703,15 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  *
  *   - Image / Video render a 1 / 2 / 3 / 4-tile grid (5+ collapse
  *     into a `+N` overflow tile). Activating any tile opens the
- *     built-in `ImageViewer` / `VideoViewer` at that index, with
- *     arrow-key navigation between siblings.
+ *     built-in `ImageViewer` / `VideoViewer` at that index; when
+ *     `items.length > 1` the lightbox becomes a carousel (prev / next
+ *     chrome, ArrowLeft / ArrowRight, current / total counter) so the
+ *     user can browse siblings without closing the modal.
  *   - 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 viewer at that
- *     index, Audio gets its own native player, and File downloads
- *     the asset for that row.
+ *     its own activation target — Pdf opens the carousel-aware
+ *     `PdfViewer` at that index, Audio gets its own native player,
+ *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
  * so its props omit `items` / `text`.
@@ -720,10 +722,17 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  * message. Sent / Received wrap the media in the shared bubble chrome.
  *
  * Image / Video / Pdf are interactive in every state (Composer, Sent,
- * Received) — clicks open the corresponding native viewer with built-in
- * download. File rows download the asset directly. Audio renders a
- * native `<audio controls>` player which exposes its own download in
- * the kebab menu, so we don't render a separate Download affordance.
+ * Received) — clicks open the corresponding native lightbox `<dialog>`,
+ * which centers the media at reasonable max dimensions (Escape and
+ * backdrop click also dismiss). The Image viewer adds an explicit
+ * 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
+ * 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.
  *
  * # Lazy-loading defaults
  *
@@ -976,7 +985,7 @@ export declare interface MessageAttachmentPdfComposerProps extends ComposerExtra
 /** A single PDF inside a Pdf attachment (single or stacked). */
 export declare interface MessageAttachmentPdfItem {
     src: string;
-    /** Filename — drives the title + the meta line + the viewer toolbar. */
+    /** Filename — drives the row title + the meta line + the viewer dialog's accessible name. */
     filename?: string;
     /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
     fileSize?: number;
@@ -1190,7 +1199,7 @@ declare type PaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded';
 declare interface PdfAttachmentSharedProps extends MessageAttachmentBaseProps {
     /** Single PDF — convenience for the most common case. */
     src?: string;
-    /** Filename — drives the title + the meta line + the viewer toolbar. */
+    /** Filename — drives the row title + the meta line + the viewer dialog's accessible name. */
     filename?: string;
     /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
     fileSize?: number;
@@ -1295,7 +1304,7 @@ declare interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps
     poster?: string;
     /** MIME type hint — typed onto the inline `<source>` element. */
     mimeType?: string;
-    /** Filename surfaced in the viewer toolbar + download default name. */
+    /** Filename used as the viewer dialog's accessible name. */
     filename?: string;
     /**
      * Stacked videos. Takes precedence over `src` when set. Renders a

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as e, b as t, C as i, c as n, d as o, e as m, F as g, f as l, L as r, h as M, M as u, i as L, j as c, k as h, l as d, m as p, n as v, o as A, p as C, q as F, s as k, t as b, u as f, v as x, w as y, x as P, y as S, z as q, B as z, D as B } from "./index-uxWUZe1M.js";
+import { a as e, b as t, C as i, c as n, d as o, e as m, F as g, f as l, L as r, h as M, M as u, i as L, j as c, k as h, l as d, m as p, n as v, o as A, p as C, q as F, s as k, t as b, u as f, v as x, w as y, x as P, y as S, z as q, B as z, D as B } from "./index-BCbVXFHI.js";
 export {
   e as ActionButton,
   t as Avatar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/messaging-react",
-  "version": "2.2.3",
+  "version": "2.3.0-rc-1779486690",
   "description": "React messaging components built on messaging-core for web applications",
   "type": "module",
   "main": "dist/index.cjs",

package/src/components/MessageAttachment/Image/ImageAttachment.stories.tsx

@@ -35,14 +35,15 @@ const handleDismiss = () => {
 /**
  * Single image — renders inside a chat bubble with rounded corners.
  * Composer / Sent / Received are all interactive: clicking opens the
- * built-in `ImageViewer` lightbox with mouse-wheel zoom, drag-to-pan,
- * double-click toggle, and a download action in the toolbar.
+ * built-in `ImageViewer` lightbox (full-viewport `<dialog>`, image
+ * centered at reasonable max dimensions, close + download buttons in
+ * the chrome — Escape or backdrop click also dismiss).
  */
 export const Single: StoryFn = () => (
   <StoryPage>
     <StoryHeading
       title="Single image"
-      description="Click any bubble to open the lightbox viewer (mouse-wheel zoom, drag-to-pan, double-click toggle, download)."
+      description="Click any bubble to open the lightbox viewer. The dialog centers the image at reasonable max dimensions; close with the × button, Escape, or a backdrop click. The chrome carries a download button for grabbing the image without leaving the lightbox."
     />
     <StoryGrid>
       <StoryRow
@@ -143,7 +144,9 @@ export const SingleWithText: StoryFn = () => (
  * Stacked image attachments — multiple images in one bubble laid out
  * in a 1 / 2 / 3 / 4-tile grid. Five or more collapse into a `+N`
  * overflow tile on the bottom-right. Click any tile to open the
- * lightbox at that index, then arrow-navigate between siblings.
+ * lightbox on that specific image; the viewer becomes a carousel
+ * (prev/next chrome, ArrowLeft / ArrowRight, and a `current / total`
+ * counter) so the user can browse siblings without closing.
  *
  * Sent + Received only — the composer surface accepts a single image
  * at a time, so the Composer column is intentionally blank.
@@ -152,7 +155,7 @@ export const Stacked: StoryFn = () => (
   <StoryPage>
     <StoryHeading
       title="Stacked images"
-      description="Click any tile to open the lightbox at that index. Use arrow keys to navigate between siblings. Composer column is intentionally blank — the composer accepts a single image at a time."
+      description="Click any tile to open the lightbox at that index. Use the prev / next chrome or ArrowLeft / ArrowRight to navigate between siblings inside the viewer. Composer column is intentionally blank — the composer accepts a single image at a time."
     />
     <StoryGrid>
       <StoryRow

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

@@ -21,7 +21,7 @@ export interface ImageAttachmentSharedProps extends MessageAttachmentBaseProps {
   /** Single image — convenience for the most common case. */
   src?: string
   alt?: string
-  /** Filename surfaced in the viewer toolbar + download default name. */
+  /** Filename used as the viewer dialog's accessible name. */
   filename?: string
   /**
    * Stacked images. Takes precedence over `src` when set. Renders a
@@ -98,6 +98,12 @@ interface InternalImageRowProps extends ImageAttachmentSharedProps {
   onDismiss?: () => void
 }
 
+/**
+ * Project the bubble's `ImageItem`s onto the carousel-aware viewer's
+ * `ImageViewerItem` shape. When a shared outer `filename` is supplied
+ * for a stacked bubble, suffix `(N)` per sibling so each carousel page
+ * still gets a distinct accessible name + download default.
+ */
 const buildViewerItems = (
   resolvedItems: ImageItem[],
   filename?: string

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

@@ -17,6 +17,21 @@ beforeEach(() => {
   mockTriggerDownload.mockClear()
 })
 
+// The viewer's `<dialog>` stays mounted across open/close so the
+// platform open / close transitions (via `@starting-style` +
+// `allow-discrete`) can play. That means we can't gate openness on
+// "is the dialog in the DOM" — we have to look at the `[open]`
+// attribute the platform sets on a `<dialog>` while it's visible.
+const expectViewerClosed = (testId: string) => {
+  const dialog = screen.queryByTestId(testId)
+  if (dialog) expect(dialog).not.toHaveAttribute('open')
+}
+const expectViewerOpen = (testId: string) => {
+  const dialog = screen.getByTestId(testId)
+  expect(dialog).toHaveAttribute('open')
+  return dialog
+}
+
 describe('MessageAttachment.Image', () => {
   it('renders an image bubble with caption', () => {
     renderWithProviders(
@@ -43,11 +58,11 @@ describe('MessageAttachment.Image', () => {
       />
     )
 
-    expect(screen.queryByTestId('image-viewer')).toBeNull()
+    expectViewerClosed('image-viewer')
 
     fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
 
-    expect(screen.getByTestId('image-viewer')).toBeInTheDocument()
+    expectViewerOpen('image-viewer')
   })
 
   it('renders the dismiss button only on Composer state', () => {
@@ -81,6 +96,104 @@ describe('MessageAttachment.Image', () => {
     expect(screen.getByLabelText('Open image 3 of 3')).toBeInTheDocument()
   })
 
+  it('renders a download button inside the image viewer', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Received
+        src="https://cdn.example.com/photo.jpg"
+        alt="Photo"
+        filename="photo.jpg"
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
+    const viewer = expectViewerOpen('image-viewer')
+    // The viewer chrome carries its own download action — separate
+    // from any sibling download button on the bubble surface — so the
+    // user can grab the image without leaving the lightbox.
+    expect(
+      viewer.querySelector('button[aria-label="Download photo.jpg"]')
+    ).not.toBeNull()
+  })
+
+  it('does not render carousel nav controls for a single image', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Received
+        src="https://cdn.example.com/photo.jpg"
+        filename="photo.jpg"
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
+    expectViewerOpen('image-viewer')
+    expect(screen.queryByLabelText('Next image')).toBeNull()
+    expect(screen.queryByLabelText('Previous image')).toBeNull()
+  })
+
+  it('renders the stacked images as a carousel inside the viewer', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        filename="album"
+        items={[
+          { src: 'https://cdn.example.com/a.jpg', alt: 'A' },
+          { src: 'https://cdn.example.com/b.jpg', alt: 'B' },
+          { src: 'https://cdn.example.com/c.jpg', alt: 'C' },
+        ]}
+      />
+    )
+
+    // Open the second tile — the viewer should land on image 2.
+    fireEvent.click(screen.getByLabelText('Open image 2 of 3'))
+    const viewer = expectViewerOpen('image-viewer')
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.jpg'
+    )
+    // Counter + nav chrome only appear on multi-item viewers.
+    expect(viewer.textContent).toContain('2 / 3')
+
+    // Next button advances by one.
+    fireEvent.click(screen.getByLabelText('Next image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/c.jpg'
+    )
+    expect(viewer.textContent).toContain('3 / 3')
+
+    // Next wraps from the last item back to the first.
+    fireEvent.click(screen.getByLabelText('Next image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+
+    // Previous wraps from the first item to the last.
+    fireEvent.click(screen.getByLabelText('Previous image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/c.jpg'
+    )
+  })
+
+  it('uses ArrowRight / ArrowLeft to navigate stacked images', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        items={[
+          { src: 'https://cdn.example.com/a.jpg', alt: 'A' },
+          { src: 'https://cdn.example.com/b.jpg', alt: 'B' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 2'))
+    const viewer = expectViewerOpen('image-viewer')
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+
+    fireEvent.keyDown(window, { key: 'ArrowRight' })
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.jpg'
+    )
+
+    fireEvent.keyDown(window, { key: 'ArrowLeft' })
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+  })
+
   it('shows a +N overflow tile for 5+ items', () => {
     renderWithProviders(
       <MessageAttachment.Image.Sent
@@ -113,9 +226,9 @@ describe('MessageAttachment.Pdf', () => {
         filename="doc.pdf"
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Open doc.pdf'))
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
   })
 
   it('forwards the onClick handler before opening the viewer', () => {
@@ -167,11 +280,42 @@ describe('MessageAttachment.Pdf', () => {
         ]}
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Open b.pdf'))
-    const viewer = screen.getByTestId('pdf-viewer')
-    expect(viewer).toBeInTheDocument()
-    expect(viewer.textContent).toContain('b.pdf')
+    const viewer = expectViewerOpen('pdf-viewer')
+    // The active filename surfaces as the dialog's accessible name —
+    // the lightbox chrome is intentionally just close + carousel chrome
+    // so the filename isn't rendered as visible text inside the modal.
+    expect(viewer.getAttribute('aria-label')).toBe('b.pdf')
+    // Carousel chrome is present because items.length > 1.
+    expect(screen.getByLabelText('Next document')).toBeInTheDocument()
+    expect(screen.getByLabelText('Previous document')).toBeInTheDocument()
+    expect(viewer.textContent).toContain('2 / 2')
+  })
+
+  it('navigates between stacked PDFs via the carousel controls', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        items={[
+          { src: 'https://cdn.example.com/a.pdf', filename: 'a.pdf' },
+          { src: 'https://cdn.example.com/b.pdf', filename: 'b.pdf' },
+          { src: 'https://cdn.example.com/c.pdf', filename: 'c.pdf' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open a.pdf'))
+    const viewer = expectViewerOpen('pdf-viewer')
+    expect(viewer.getAttribute('aria-label')).toBe('a.pdf')
+
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('b.pdf')
+
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('c.pdf')
+
+    // Wraps back to the start.
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('a.pdf')
   })
 
   it('renders a sibling Download button on Sent / Received rows', () => {
@@ -214,11 +358,11 @@ describe('MessageAttachment.Pdf', () => {
         filename="notes.pdf"
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Download notes.pdf'))
     // Download should fire on its own without bubbling up to the row
     // activation that opens the viewer.
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
   })
 
   it('hides the Download button on the Composer state (dismiss takes its place)', () => {
@@ -249,7 +393,7 @@ describe('MessageAttachment.Pdf', () => {
       />
     )
     fireEvent.click(screen.getByLabelText('Open c.pdf'))
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
 
     expect(() =>
       rerender(
@@ -263,8 +407,12 @@ describe('MessageAttachment.Pdf', () => {
 
     // Bubble still renders the surviving row instead of blowing up.
     expect(screen.getByLabelText('Open a.pdf')).toBeInTheDocument()
-    // Viewer falls back to the last available item (the surviving one).
-    expect(screen.getByTestId('pdf-viewer').textContent).toContain('a.pdf')
+    // Viewer falls back to the last available item (the surviving one)
+    // — surfaced as the dialog's aria-label since the chrome no longer
+    // renders the filename as visible text.
+    expect(screen.getByTestId('pdf-viewer').getAttribute('aria-label')).toBe(
+      'a.pdf'
+    )
   })
 
   it('does not open the viewer when onClick returns false', () => {
@@ -278,7 +426,7 @@ describe('MessageAttachment.Pdf', () => {
     )
     fireEvent.click(screen.getByLabelText('Open doc.pdf'))
     expect(onClick).toHaveBeenCalledTimes(1)
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
   })
 })
 
@@ -450,9 +598,41 @@ describe('MessageAttachment.Video', () => {
         filename="clip.mp4"
       />
     )
-    expect(screen.queryByTestId('video-viewer')).toBeNull()
+    expectViewerClosed('video-viewer')
     fireEvent.click(screen.getByLabelText('Play video 1 of 1'))
-    expect(screen.getByTestId('video-viewer')).toBeInTheDocument()
+    expectViewerOpen('video-viewer')
+    // Single-item viewer has no carousel chrome.
+    expect(screen.queryByLabelText('Next video')).toBeNull()
+  })
+
+  it('navigates between stacked videos via the carousel controls', () => {
+    renderWithProviders(
+      <MessageAttachment.Video.Sent
+        filename="clip"
+        items={[
+          {
+            src: 'https://cdn.example.com/a.mp4',
+            poster: 'https://cdn.example.com/a.jpg',
+            mimeType: 'video/mp4',
+          },
+          {
+            src: 'https://cdn.example.com/b.mp4',
+            poster: 'https://cdn.example.com/b.jpg',
+            mimeType: 'video/mp4',
+          },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Play video 1 of 2'))
+    const viewer = expectViewerOpen('video-viewer')
+    expect(viewer.querySelector('video')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.mp4'
+    )
+
+    fireEvent.click(screen.getByLabelText('Next video'))
+    expect(viewer.querySelector('video')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.mp4'
+    )
   })
 })
 
@@ -485,13 +665,14 @@ describe('ViewerShell focus management', () => {
     expect(document.activeElement).toBe(opener)
 
     fireEvent.click(opener)
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
 
     fireEvent.click(screen.getByLabelText('Close viewer'))
 
     // After close, focus should hop back to whatever was focused
-    // before the viewer mounted (the row's Open button).
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    // before the viewer mounted (the row's Open button), and the
+    // dialog should no longer carry the `[open]` attribute.
+    expectViewerClosed('pdf-viewer')
     expect(document.activeElement).toBe(opener)
   })
 })

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

@@ -5,7 +5,7 @@ import CompactDocumentRow from '../_shared/CompactDocumentRow'
 import DismissButton from '../_shared/DismissButton'
 import DownloadAction from '../_shared/DownloadAction'
 import { filenameFromUrl } from '../_shared/fileMeta'
-import PdfViewer from '../_shared/PdfViewer'
+import PdfViewer, { type PdfViewerItem } from '../_shared/PdfViewer'
 import { useViewer } from '../_shared/useViewer'
 import {
   bubbleVariantForState,
@@ -19,7 +19,7 @@ import {
 export interface PdfAttachmentSharedProps extends MessageAttachmentBaseProps {
   /** Single PDF — convenience for the most common case. */
   src?: string
-  /** Filename — drives the title + the meta line + the viewer toolbar. */
+  /** Filename — drives the row title + the meta line + the viewer dialog's accessible name. */
   filename?: string
   /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
   fileSize?: number
@@ -128,15 +128,13 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
     return null
   }
 
-  // Clamp the viewer index defensively: if `items` shrinks between
-  // the open click and the next render (server push, optimistic
-  // update, etc.) `viewerIndex` may point past the new array.
-  // Dereferencing `undefined` would crash the whole bubble, so fall
-  // back to the last available row instead.
-  const safeIndex = Math.min(viewerIndex, resolvedItems.length - 1)
-  const activeItem = resolvedItems[safeIndex]
-  const activeFilename =
-    activeItem.filename ?? filenameFromUrl(activeItem.src)
+  // Project the bubble's `PdfItem`s onto the viewer's carousel-aware
+  // shape. The viewer clamps its own active index defensively, so we
+  // don't need to second-guess `viewerIndex` here.
+  const viewerItems: PdfViewerItem[] = resolvedItems.map((item) => ({
+    src: item.src,
+    filename: item.filename ?? filenameFromUrl(item.src),
+  }))
 
   return (
     <Bubble
@@ -154,8 +152,9 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
           // Composer only supports a single attachment so the dismiss
           // control sits on the only row. Sent / Received rows expose
           // a download icon button so the user can grab the PDF
-          // without opening the viewer first (the viewer also has a
-          // download in its toolbar — this is the quick-grab shortcut).
+          // without opening the viewer first — the viewer dialog is
+          // intentionally just the document + a close button, so this
+          // sibling action is the only one-click download surface.
           const trailingAction =
             showDismiss && index === 0 ? (
               <DismissButton onClick={onDismiss!} variant="inline" />
@@ -183,8 +182,8 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
 
       <PdfViewer
         open={viewerOpen}
-        src={activeItem.src}
-        filename={activeFilename}
+        items={viewerItems}
+        initialIndex={viewerIndex}
         onClose={closeViewer}
       />
     </Bubble>

package/src/components/MessageAttachment/Video/VideoAttachment.stories.tsx

@@ -53,13 +53,13 @@ const handleDismiss = () => {
 /**
  * Single video — the bubble shows the poster with a play overlay.
  * Clicking opens the full-viewport `VideoViewer` with native controls
- * (play / pause / seek / fullscreen / volume) and a download action.
+ * (play / pause / seek / fullscreen / volume / download).
  */
 export const Single: StoryFn = () => (
   <StoryPage>
     <StoryHeading
       title="Single video"
-      description="Click any bubble to open the full-screen video viewer with native controls and a download action."
+      description="Click any bubble to open the full-screen video viewer with the browser's native controls (play / pause / seek / fullscreen / volume / download)."
     />
     <StoryGrid>
       <StoryRow

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

@@ -23,7 +23,7 @@ export interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps {
   poster?: string
   /** MIME type hint — typed onto the inline `<source>` element. */
   mimeType?: string
-  /** Filename surfaced in the viewer toolbar + download default name. */
+  /** Filename used as the viewer dialog's accessible name. */
   filename?: string
   /**
    * Stacked videos. Takes precedence over `src` when set. Renders a
@@ -121,6 +121,12 @@ interface InternalVideoRowProps extends VideoAttachmentSharedProps {
   state: MessageAttachmentState
 }
 
+/**
+ * Project the bubble's `VideoItem`s onto the carousel-aware viewer's
+ * `VideoViewerItem` shape. When a shared outer `filename` is supplied
+ * for a stacked bubble, suffix `(N)` per sibling so each carousel page
+ * still gets a distinct accessible name.
+ */
 const buildViewerItems = (
   resolvedItems: VideoItem[],
   filename?: string
@@ -177,7 +183,10 @@ const VideoComposerInner: React.FC<{
 
       <VideoViewer
         open={viewerOpen}
-        items={buildViewerItems([{ src, poster, mimeType, preload }], filename)}
+        items={buildViewerItems(
+          [{ src, poster, mimeType, preload }],
+          filename
+        )}
         initialIndex={viewerIndex}
         onClose={closeViewer}
       />

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

@@ -0,0 +1,47 @@
+import { CaretLeftIcon, CaretRightIcon } from '@phosphor-icons/react'
+import React from 'react'
+
+export interface CarouselNavProps {
+  onPrev: () => void
+  onNext: () => void
+  /** Accessible label for the previous-item button. */
+  prevLabel?: string
+  /** Accessible label for the next-item button. */
+  nextLabel?: string
+}
+
+/**
+ * Prev / next chrome shared by every carousel-aware viewer. Rendered
+ * inside the dialog body so the buttons sit absolutely positioned
+ * against the viewer (`.mes-media-viewer__nav--{prev,next}`).
+ *
+ * Styling lives as plain CSS in `styles.css` so the buttons render
+ * correctly regardless of whether the consumer has Tailwind wired up.
+ */
+const CarouselNav: React.FC<CarouselNavProps> = ({
+  onPrev,
+  onNext,
+  prevLabel = 'Previous',
+  nextLabel = 'Next',
+}) => (
+  <>
+    <button
+      type="button"
+      onClick={onPrev}
+      aria-label={prevLabel}
+      className="mes-media-viewer__nav mes-media-viewer__nav--prev"
+    >
+      <CaretLeftIcon size={20} weight="bold" aria-hidden />
+    </button>
+    <button
+      type="button"
+      onClick={onNext}
+      aria-label={nextLabel}
+      className="mes-media-viewer__nav mes-media-viewer__nav--next"
+    >
+      <CaretRightIcon size={20} weight="bold" aria-hidden />
+    </button>
+  </>
+)
+
+export default CarouselNav