@linktr.ee/messaging-react 4.1.5 → 4.2.0-rc-1787083791

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-9elRVMIF.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.MessageBubble=e.MessageBubble;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.RichCard=e.RichCard;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.optimizeMessagingAttachmentUrl=e.optimizeMessagingAttachmentUrl;exports.resolveConversationParticipant=e.resolveConversationParticipant;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useComposerLocked=e.useComposerLocked;exports.useCustomMessage=e.useCustomMessage;exports.useMessaging=e.useMessaging;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-B-9LkWep.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.MessageBubble=e.MessageBubble;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.RichCard=e.RichCard;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.optimizeMessagingAttachmentUrl=e.optimizeMessagingAttachmentUrl;exports.resolveConversationParticipant=e.resolveConversationParticipant;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useComposerLocked=e.useComposerLocked;exports.useCustomMessage=e.useCustomMessage;exports.useMessaging=e.useMessaging;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -36,37 +36,24 @@ export declare type AttachmentSourceType = 'image' | 'audio' | 'video' | 'docume
 declare interface AudioAttachmentSharedProps extends MessageAttachmentBaseProps {
     /** Audio source URL (`mp3`, `aac`, `wav`, …). */
     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). The HTML `<audio>` element doesn't
-     * expose a built-in title slot, so we don't render the filename
-     * inside the bubble itself.
+     * Filename — the download default name for the trailing action, and
+     * part of each control's accessible name.
      */
     filename?: string;
     /**
      * Stacked audio. Takes precedence over `src` when set. Each item
-     * renders its own native `<audio controls>` player, vertically
-     * stacked inside the same bubble with an 8px gap between players.
-     * Sent + Received only — the composer surface accepts a single
-     * attachment at a time.
+     * renders its own waveform row, vertically stacked inside the same
+     * bubble with an 8px gap. Sent + Received only — the composer surface
+     * accepts a single attachment at a time.
      */
     items?: MessageAttachmentAudioItem[];
-    /**
-     * `<audio preload>` hint applied to every player on the bubble.
-     * When omitted, the default depends on the rendered shape:
-     *
-     *   - Single audio (no `items`, or `items.length === 1`) →
-     *     `'metadata'` so the native player surfaces duration
-     *     immediately.
-     *   - Stacked audio (`items.length > 1`) → `'none'` so a thread
-     *     of voice memos doesn't fan out N parallel metadata requests
-     *     on first paint.
-     *
-     * Per-track overrides live on `AudioItem.preload`.
-     */
-    preload?: MediaPreloadMode;
+    /** See `AudioItem.durationSeconds`. Applies to the single-`src` shape. */
+    durationSeconds?: number;
+    /** See `AudioItem.waveformData`. Applies to the single-`src` shape. */
+    waveformData?: number[];
 }
 
 /**
@@ -994,7 +981,7 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  *   - 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,
@@ -1012,12 +999,29 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  * 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
@@ -1038,13 +1042,12 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  *     `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.
@@ -1089,28 +1092,40 @@ export declare interface MessageAttachmentAudioComposerProps extends ComposerExt
     src?: string;
     mimeType?: string;
     filename?: string;
-    /** See `AudioAttachmentSharedProps.preload`. */
-    preload?: MediaPreloadMode;
+    /** See `AudioItem.durationSeconds`. */
+    durationSeconds?: number;
+    /** See `AudioItem.waveformData`. */
+    waveformData?: number[];
 }
 
 /** A single audio file inside an Audio attachment (single or stacked). */
 export declare interface MessageAttachmentAudioItem {
     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[];
 }
 
 export declare type MessageAttachmentAudioReceivedProps = AudioAttachmentSharedProps;

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 r, f as l, L as g, h as c, M, i as h, j as L, k as u, l as d, R as p, m as C, n as v, p as A, q as k, s as F, t as b, u as P, v as f, w as x, o as y, x as z, y as S, z as q, B, D, E, G as R } from "./index-qKUd4Fz2.js";
+import { a as e, b as t, C as i, c as n, d as o, e as m, F as r, f as l, L as g, h as c, M, i as h, j as L, k as u, l as d, R as p, m as C, n as v, p as A, q as k, s as F, t as b, u as P, v as f, w as x, o as y, x as z, y as S, z as q, B, D, E, G as R } from "./index-C93LTGLc.js";
 export {
   e as ActionButton,
   t as Avatar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/messaging-react",
-  "version": "4.1.5",
+  "version": "4.2.0-rc-1787083791",
   "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.4.0",
+    "@linktr.ee/messaging-core": "2.4.0-rc-1787083791",
     "@linktr.ee/messaging-taxonomy": "^0.10.0",
     "@phosphor-icons/react": "^2.1.10"
   },

package/src/components/CustomMessage/StreamAttachmentMessage.test.tsx

@@ -257,4 +257,37 @@ describe('StreamAttachmentMessage', () => {
       )
     ).toHaveTextContent('from the trip')
   })
+
+  it('forwards a persisted duration and waveform to the audio card', () => {
+    // Audio is sent as `type: "file"` with an `audio/*` mime type (for
+    // mobile compatibility), and the composer persists `duration` +
+    // `waveform_data` on the outgoing attachment. Without this
+    // passthrough every sent and received card would fall back to
+    // `--:--` and a flat placeholder even though the data is there.
+    renderWithProviders(
+      <StreamAttachmentMessage
+        groupPosition="single"
+        isMyMessage
+        message={message([
+          {
+            type: 'file',
+            asset_url: 'https://cdn.example.com/take-1.mp3',
+            mime_type: 'audio/mpeg',
+            title: 'take-1.mp3',
+            duration: 12,
+            waveform_data: [0.2, 0.9, 0.5, 0.7],
+          },
+        ])}
+      />
+    )
+
+    expect(screen.getByText('00:12')).toBeInTheDocument()
+    // The flat placeholder renders every bar at 0%; a real waveform is
+    // observable as bars drawn above that floor.
+    const barHeights = screen
+      .getAllByTestId('amplitude-bar')
+      .map((bar) => bar.style.getPropertyValue('--mes-audio-wave-bar'))
+    expect(barHeights).toHaveLength(35)
+    expect(barHeights.some((height) => height !== '0%')).toBe(true)
+  })
 })

package/src/components/CustomMessage/StreamAttachmentMessage.tsx

@@ -221,6 +221,12 @@ function mediaItemForKind(
         src: trimToUndefined(attachment.asset_url) ?? '',
         mimeType: trimToUndefined(attachment.mime_type) ?? 'audio/mpeg',
         filename: trimToUndefined((attachment as { title?: string }).title),
+        // Both are first-class `stream-chat` Attachment fields. The
+        // composer writes them at send time so the waveform card paints
+        // the real amplitudes and the correct duration with no remote
+        // decode and no CDN CORS exposure.
+        durationSeconds: attachment.duration,
+        waveformData: attachment.waveform_data,
       }
     case 'pdf':
       return {

package/src/components/MessageAttachment/Audio/AudioAttachment.stories.tsx

@@ -1,6 +1,8 @@
-import type { Meta, StoryFn } from '@storybook/react'
+import type { Decorator, Meta, StoryFn } from '@storybook/react'
 import React from 'react'
+import { Chat, WithAudioPlayback } from 'stream-chat-react'
 
+import { createMockStreamChatClient } from '../../../testing/createMockStreamChatClient'
 import {
   StoryGrid,
   StoryHeading,
@@ -14,27 +16,63 @@ import AudioAttachment from '.'
 const AUDIO_SRC =
   'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'
 
+/** Resolves nothing, so the metadata probe never fills the duration slot. */
+const UNREACHABLE_SRC = 'https://cdn.example.invalid/unreachable.mp3'
+
+/**
+ * The exact amplitudes Figma draws (`2754:17710` → `sound-wave`
+ * `…;2754:8065`), as bar heights on the 30px track normalised to `0..1`.
+ * Rendering the design's own values is what makes these stories a usable
+ * pixel reference.
+ */
+const FIGMA_WAVEFORM = [
+  4, 4, 4, 4, 24, 20, 16, 21, 8, 9, 13, 15, 16, 21, 24, 18, 14, 11, 11, 11, 11,
+  11, 18, 24, 24, 30, 25, 21, 19, 16, 11, 12, 8, 4, 4,
+].map((height) => height / 30)
+
 const STACK_AUDIO: AudioItem[] = [
   {
     src: AUDIO_SRC,
     mimeType: 'audio/mpeg',
     filename: 'Take 1 — full mix.mp3',
+    durationSeconds: 12,
+    waveformData: FIGMA_WAVEFORM,
   },
   {
     src: AUDIO_SRC,
     mimeType: 'audio/mpeg',
     filename: 'Take 2 — vocals isolated.mp3',
+    durationSeconds: 95,
+    waveformData: [...FIGMA_WAVEFORM].reverse(),
   },
   {
     src: AUDIO_SRC,
     mimeType: 'audio/mpeg',
     filename: 'Take 3 — instrumental only.mp3',
+    durationSeconds: 3812,
   },
 ]
 
+/**
+ * The card's playback comes from `stream-chat-react`'s pooled
+ * `AudioPlayer`, which `<Channel>` mounts in production. Mounting the
+ * pool directly gives the stories the same contract — real playback,
+ * one player at a time across the page — without needing a channel that
+ * can `watch()` against a backend. Without it every play / seek control
+ * renders disabled.
+ */
+const withAudioPlayback: Decorator = (Story) => (
+  <Chat client={createMockStreamChatClient({ id: 'story-user' })}>
+    <WithAudioPlayback>
+      <Story />
+    </WithAudioPlayback>
+  </Chat>
+)
+
 const meta: Meta = {
   title: 'MessageAttachment/Audio',
   parameters: { layout: 'fullscreen' },
+  decorators: [withAudioPlayback],
 }
 export default meta
 
@@ -43,16 +81,16 @@ const handleDismiss = () => {
 }
 
 /**
- * Native `<audio controls>` player inside a chat bubble. The browser
- * chrome provides play / scrub / volume / kebab-menu (which already
- * includes a download), so we don't render any extra controls.
- * Composer adds an inline dismiss `×` to the right of the player.
+ * The design's waveform player card: a 299×72 bubble holding a 32px
+ * play toggle, a 35-bar waveform with a progress fill and an invisible
+ * native seek control over it, the duration, and a 32px trailing action
+ * — Remove in the composer, Download once sent.
  */
 export const Single: StoryFn = () => (
   <StoryPage>
     <StoryHeading
       title="Audio attachment"
-      description="Native browser audio chrome — play, scrub, volume, and the built-in download in the kebab menu. Composer renders an inline dismiss button next to the player."
+      description="Play to watch the fill advance bar by bar and the duration count up; click or drag the waveform to seek, or Tab to it and use the arrow keys. Starting a second card pauses the first — one player at a time across the whole thread."
     />
     <StoryGrid>
       <StoryRow
@@ -62,6 +100,8 @@ export const Single: StoryFn = () => (
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
             filename="Morning meditation.mp3"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
             onDismiss={handleDismiss}
           />
         }
@@ -70,6 +110,8 @@ export const Single: StoryFn = () => (
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
             filename="Morning meditation.mp3"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
           />
         }
         received={
@@ -77,6 +119,8 @@ export const Single: StoryFn = () => (
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
             filename="Morning meditation.mp3"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
           />
         }
       />
@@ -84,20 +128,28 @@ export const Single: StoryFn = () => (
   </StoryPage>
 )
 
-export const SingleWithText: StoryFn = () => (
+/**
+ * Every case where no amplitudes can be produced — a decode failure, an
+ * unsupported codec, a file over the composer's decode ceiling, a clip
+ * re-staged from *Recently shared* (whose `File` is a zero-byte
+ * placeholder), or anything sent before `waveform_data` was persisted
+ * (legacy web, the mobile app, a visitor).
+ */
+export const NoWaveform: StoryFn = () => (
   <StoryPage>
     <StoryHeading
-      title="Audio with caption"
-      description="Caption sits below the player, inside the same bubble."
+      title="Degraded states"
+      description="The waveform falls back to every bar at the design's 4px minimum, so the card keeps exactly the same silhouette and the progress fill still tracks playback. An unknown duration holds its slot as `--:--` until a metadata probe resolves it."
     />
     <StoryGrid>
       <StoryRow
-        label="Caption"
+        label="No waveform"
         composer={
           <AudioAttachment.Composer
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
+            filename="Voice note.m4a"
+            durationSeconds={12}
             onDismiss={handleDismiss}
           />
         }
@@ -105,87 +157,100 @@ export const SingleWithText: StoryFn = () => (
           <AudioAttachment.Sent
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
-            text="Recorded this morning before training"
+            filename="Voice note.m4a"
+            durationSeconds={12}
           />
         }
         received={
           <AudioAttachment.Received
             src={AUDIO_SRC}
             mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
-            text="Recorded this morning before training"
+            filename="Voice note.m4a"
+            durationSeconds={12}
           />
         }
       />
-    </StoryGrid>
-  </StoryPage>
-)
-
-/**
- * Stacked audio attachments — multiple clips inside one bubble. Each
- * clip renders its own native `<audio controls>` player, vertically
- * stacked with a hairline separator.
- *
- * Sent + Received only — the composer surface accepts a single
- * attachment at a time.
- */
-export const Stacked: StoryFn = () => (
-  <StoryPage>
-    <StoryHeading
-      title="Stacked audio"
-      description="Each clip plays independently with its own native controls. Composer column is intentionally blank — the composer accepts a single attachment at a time."
-    />
-    <StoryGrid>
       <StoryRow
-        label="2 clips"
+        label="No waveform, no duration"
         composer={
           <AudioAttachment.Composer
-            src={AUDIO_SRC}
-            mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
+            src={UNREACHABLE_SRC}
+            filename="Unreachable.mp3"
             onDismiss={handleDismiss}
           />
         }
-        sent={<AudioAttachment.Sent items={STACK_AUDIO.slice(0, 2)} />}
-        received={<AudioAttachment.Received items={STACK_AUDIO.slice(0, 2)} />}
+        sent={
+          <AudioAttachment.Sent
+            src={UNREACHABLE_SRC}
+            filename="Unreachable.mp3"
+          />
+        }
+        received={
+          <AudioAttachment.Received
+            src={UNREACHABLE_SRC}
+            filename="Unreachable.mp3"
+          />
+        }
       />
       <StoryRow
-        label="3 clips"
+        label="Unplayable codec"
         composer={
           <AudioAttachment.Composer
             src={AUDIO_SRC}
-            mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
+            mimeType="audio/x-made-up"
+            filename="Master.aiff"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
             onDismiss={handleDismiss}
           />
         }
-        sent={<AudioAttachment.Sent items={STACK_AUDIO} />}
-        received={<AudioAttachment.Received items={STACK_AUDIO} />}
+        sent={
+          <AudioAttachment.Sent
+            src={AUDIO_SRC}
+            mimeType="audio/x-made-up"
+            filename="Master.aiff"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
+          />
+        }
+        received={
+          <AudioAttachment.Received
+            src={AUDIO_SRC}
+            mimeType="audio/x-made-up"
+            filename="Master.aiff"
+            durationSeconds={12}
+            waveformData={FIGMA_WAVEFORM}
+          />
+        }
       />
     </StoryGrid>
   </StoryPage>
 )
 
-/** Stacked audio with an accompanying caption.
- *  Sent + Received only — see `Stacked` for the rationale. */
-export const StackedWithText: StoryFn = () => (
+/**
+ * Stacked audio — multiple clips clustered into one bubble, as
+ * `StreamAttachmentMessage` does for consecutive same-kind attachments.
+ * Sent + Received only: the composer accepts one attachment at a time.
+ */
+export const Stacked: StoryFn = () => (
   <StoryPage>
     <StoryHeading
-      title="Stacked audio with caption"
-      description="Caption sits inside the same bubble, below the player stack. Composer column is intentionally blank — the composer accepts a single attachment at a time."
+      title="Stacked audio"
+      description="Each clip is its own row and its own player, stacked with an 8px gap. Only one can play at a time. The third row has no waveform, so it shows the flat fallback beside two real ones."
     />
     <StoryGrid>
+      <StoryRow
+        label="2 clips"
+        sent={<AudioAttachment.Sent items={STACK_AUDIO.slice(0, 2)} />}
+        received={<AudioAttachment.Received items={STACK_AUDIO.slice(0, 2)} />}
+      />
+      <StoryRow
+        label="3 clips"
+        sent={<AudioAttachment.Sent items={STACK_AUDIO} />}
+        received={<AudioAttachment.Received items={STACK_AUDIO} />}
+      />
       <StoryRow
         label="3 clips + caption"
-        composer={
-          <AudioAttachment.Composer
-            src={AUDIO_SRC}
-            mimeType="audio/mpeg"
-            filename="Morning meditation.mp3"
-            onDismiss={handleDismiss}
-          />
-        }
         sent={
           <AudioAttachment.Sent
             items={STACK_AUDIO}
@@ -202,3 +267,45 @@ export const StackedWithText: StoryFn = () => (
     </StoryGrid>
   </StoryPage>
 )
+
+/**
+ * The card keeps a uniform 20px radius in every grouping position — a
+ * 32px control tucked into a 4px flattened corner would collide with it
+ * — so a run of audio bubbles reads as a stack of identical cards.
+ */
+export const Grouped: StoryFn = () => (
+  <StoryPage>
+    <StoryHeading
+      title="Same-author run"
+      description="`groupPosition` still serialises onto the bubble, but the audio card opts out of the corner flattening the text bubbles apply."
+    />
+    <StoryGrid>
+      {(['first', 'middle', 'end'] as const).map((groupPosition) => (
+        <StoryRow
+          key={groupPosition}
+          label={groupPosition}
+          sent={
+            <AudioAttachment.Sent
+              src={AUDIO_SRC}
+              mimeType="audio/mpeg"
+              filename="Morning meditation.mp3"
+              durationSeconds={12}
+              waveformData={FIGMA_WAVEFORM}
+              groupPosition={groupPosition}
+            />
+          }
+          received={
+            <AudioAttachment.Received
+              src={AUDIO_SRC}
+              mimeType="audio/mpeg"
+              filename="Morning meditation.mp3"
+              durationSeconds={12}
+              waveformData={FIGMA_WAVEFORM}
+              groupPosition={groupPosition}
+            />
+          }
+        />
+      ))}
+    </StoryGrid>
+  </StoryPage>
+)