@linktr.ee/messaging-react 2.1.0 → 2.2.0-rc-1778753733

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { ChannelSort } from 'stream-chat';
 import { ComponentType } from 'react';
 import { default as default_2 } from 'react';
 import { EmptyStateIndicatorProps } from 'stream-chat-react';
+import { FC } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { LocalMessage } from 'stream-chat';
 import { MessagingUser } from '@linktr.ee/messaging-core';
@@ -25,6 +26,42 @@ declare type AgeSafetySystemType = 'SYSTEM_AGE_SAFETY_BLOCKED';
 
 export declare type AttachmentSourceType = 'image' | 'audio' | 'video' | 'document';
 
+declare interface AudioAttachmentSharedProps extends MessageAttachmentBaseProps {
+    /** Audio source URL (`mp3`, `aac`, `wav`, …). */
+    src?: string;
+    /** MIME type hint — typed onto the inline `<source>` element. */
+    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?: 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.
+     */
+    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;
+}
+
 /**
  * Avatar component that displays a user image or colored initial fallback
  */
@@ -41,6 +78,13 @@ export declare interface AvatarProps {
     dmAgentEnabled?: boolean;
 }
 
+/**
+ * Build the meta line shown under the title in compact document / file
+ * attachments — `EXT · SIZE` (`PDF · 379.5 KB`). Either part is dropped
+ * when not available so audio / generic files still get a useful label.
+ */
+export declare function buildCompactMetaLabel(mimeType?: string, filename?: string, fileSize?: number): string | undefined;
+
 /**
  * Empty state component shown when a channel has no messages
  * Returns null to show nothing - the LoadingIndicator handles the loading state
@@ -267,6 +311,12 @@ export declare interface ComposerCardProps extends LockedAttachmentBaseProps {
     onEditClick?: () => void;
 }
 
+/** Shared props for the `Composer` state of every attachment type. */
+declare interface ComposerExtras {
+    /** Renders a dismiss `×` button overlaid on the attachment. */
+    onDismiss?: () => void;
+}
+
 /**
  * @deprecated Renamed to `SentCardProps`. Drafting usages (with `onDismiss`)
  * should migrate to `ComposerCardProps`.
@@ -310,43 +360,129 @@ export declare interface FaqListProps {
     avatarName?: string;
 }
 
+declare interface FileAttachmentSharedProps extends MessageAttachmentBaseProps {
+    /** Source URL of the file (used as the download target). */
+    src?: string;
+    /** Filename — drives the title + the meta line + the download default name. */
+    filename?: string;
+    fileSize?: number;
+    /** MIME type — drives the type icon. Defaults to `application/octet-stream`. */
+    mimeType?: string;
+    /**
+     * Override displayed title (defaults to `filename`). Useful when a
+     * sender renames the attachment before sending.
+     */
+    title?: string;
+    /**
+     * Stacked files. Takes precedence over `src` when set. Each item
+     * renders as its own row inside the bubble; clicking a row downloads
+     * that file. Sent + Received only — the composer surface accepts a
+     * single attachment at a time.
+     */
+    items?: MessageAttachmentFileItem[];
+    /**
+     * Forwarded to the row trigger. When omitted the click still
+     * downloads the file. Supply this for analytics, or return `false`
+     * to fully intercept the download (e.g. show a confirmation modal,
+     * route to a custom preview, throttle large files). Any other
+     * return value — including `void`/`undefined` — lets the built-in
+     * download proceed. For stacked attachments the `index` argument
+     * identifies the row.
+     */
+    onClick?: (index: number) => boolean | void;
+}
+
+/**
+ * Format a byte count as a short human-readable string (`'379.5 KB'`).
+ * Mirrors the meta line shown next to file attachments in the mobile chat
+ * design — `EXT · SIZE`, e.g. `PDF · 379.5 KB`.
+ */
+export declare function formatFileSize(bytes: number): string;
+
 /**
  * Format a date - shows time for today, relative time for older messages
  * (e.g., "Just now", "2:08 PM" for today, "Yesterday" for yesterday, "2d" for 2 days ago)
  */
 export declare const formatRelativeTime: (date: Date) => string;
 
+/**
+ * Returns the short uppercase extension label shown in the meta line of
+ * compact document / file attachments. Prefers the filename extension
+ * when present (matches the mobile design which trusts the filename),
+ * and falls back to a label derived from the MIME type.
+ */
+export declare function getFileExtensionLabel(mimeType?: string, filename?: string): string | undefined;
+
 export declare function getMessageDisplayText({ message, viewerLanguage, }: {
     message?: MessageWithI18n | null;
     viewerLanguage?: string;
 }): string | undefined;
 
+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?: string;
+    /**
+     * Stacked images. Takes precedence over `src` when set. Renders a
+     * 1 / 2 / 3 / 4-tile grid (5+ collapse into a `+N` overflow tile).
+     * Sent + Received only — the composer surface intentionally accepts
+     * a single attachment at a time.
+     */
+    items?: MessageAttachmentImageItem[];
+    /**
+     * Native lazy-load hint forwarded to every `<img>` rendered on the
+     * bubble surface (Composer thumbnail, single + stacked tiles, and
+     * the `+N` overflow tile). Defaults to `'lazy'` — chat surfaces
+     * usually scroll a long history, and lazy loading prevents every
+     * historical image from being fetched on mount. Set `'eager'` for
+     * above-the-fold hero attachments. Per-tile overrides live on
+     * `ImageItem.loading`. The opened `ImageViewer` always eager-loads
+     * the active image regardless of this value.
+     */
+    loading?: ImageLoadingMode;
+    /**
+     * Forwarded to the Image viewer trigger. When omitted the click
+     * still opens the built-in viewer — supply this for analytics, or
+     * return `false` to intercept the open (e.g. switch to a route-
+     * based gallery / confirmation modal). Any other return value
+     * (including `void`/`undefined`) lets the built-in viewer open.
+     * For stacked attachments the `index` argument identifies the tile.
+     */
+    onClick?: (index: number) => boolean | void;
+}
+
+/** Loading hint forwarded to the underlying `<img>` element. */
+declare type ImageLoadingMode = 'lazy' | 'eager';
+
 export declare function isLinkAttachment(a: Attachment): boolean;
 
 /**
- * Link attachments (image / file media + 1P/3P Link Apps) shown in the chat
- * thread. Mirrors the `LockedAttachment` API — render `LinkAttachment.Composer`
- * while drafting, `LinkAttachment.Sent` after posting, and
+ * Link previews (1P / 3P Link Apps) shown in the chat thread. Mirrors
+ * the `LockedAttachment` API — render `LinkAttachment.Composer` while
+ * drafting, `LinkAttachment.Sent` after posting, and
  * `LinkAttachment.Received` in the recipient's thread. Maps to the
- * "Attachments" and "LinkApps" sections of the messaging design system.
+ * "LinkApps" section of the messaging design system.
  *
  * Two visual layouts via the `layout` prop:
- *   - **Featured** (default) — 180px hero thumbnail above the body. Used by
- *     image / file Attachments and by hero-image LinkApps (Spotify with
- *     cover art, TikTok with a frame, etc.).
+ *   - **Featured** (default) — 180px hero thumbnail above the body. Used
+ *     by hero-image LinkApps (Spotify with cover art, TikTok with a
+ *     frame, etc.).
  *   - **Classic** — compact card with no hero thumbnail; title /
  *     description / URL / CTA only. Used for LinkApp embeds without
  *     artwork (FAQ, Form) and any link preview that lacks OG imagery.
  *
- * Image / file Attachments use `layout="featured"` and skip the title /
- * description / URL body entirely (`CardBody` collapses to nothing when no
- * text content is provided). LinkApps always carry a title + description
- * and prefix the title with an `appIcon` brand badge.
+ * For chat **document / image / video / audio attachments**, reach for
+ * `MessageAttachment.{Image,Video,Audio,Pdf,File}` instead — those
+ * render as bubbles with built-in viewers (zoom-capable image
+ * lightbox, native PDF viewer, video / audio with download) and a
+ * caption slot for accompanying text.
  */
 export declare const LinkAttachment: {
-    Composer: (props: LinkAttachmentComposerCardProps) => JSX_2.Element;
-    Sent: (props: LinkAttachmentSentCardProps) => JSX_2.Element;
-    Received: (props: LinkAttachmentReceivedCardProps) => JSX_2.Element;
+    Composer: FC<LinkAttachmentComposerCardProps>;
+    Sent: FC<LinkAttachmentSentCardProps>;
+    Received: FC<LinkAttachmentReceivedCardProps>;
 };
 
 /**
@@ -373,9 +509,11 @@ export declare interface LinkAttachmentBaseProps {
     /** Hero thumbnail (180px tall) shown above the title block. */
     thumbnailUrl?: string;
     /**
-     * Source URL for playable media (video, audio). When provided alongside a
-     * video / audio `mimeType`, the hero region renders an inline player with
-     * native controls instead of the static thumbnail / type-icon.
+     * Source URL for playable media in the hero region. When provided
+     * alongside a video / audio `mimeType`, the hero renders an inline
+     * native player (used by media-rich link previews that embed a
+     * preview clip). For chat document / file attachments, reach for
+     * `MessageAttachment.{Pdf,File}` instead.
      */
     sourceUrl?: string;
     /**
@@ -422,11 +560,16 @@ export declare interface LinkAttachmentCta {
  * Visual layout for a `LinkAttachment.*` card.
  *
  * - `featured` — full card with a 180px hero thumbnail above the body.
- *   The default; matches the "Attachments" frames and the hero-image
- *   "LinkApps" frames in Figma.
+ *   The default; matches the hero-image "LinkApps" frames in Figma
+ *   (Spotify with cover art, TikTok with a frame, etc.).
  * - `classic` — compact card without a hero thumbnail. Title /
  *   description / URL / CTA only. Used for Link App embeds that don't
  *   carry artwork (and for plain link previews without OG imagery).
+ *
+ * For document / image / video / audio chat attachments, reach for
+ * `MessageAttachment.{Image,Video,Audio,Pdf,File}` instead — those
+ * render as bubbles with built-in viewers and download support and
+ * carry a `text` slot for accompanying captions.
  */
 export declare type LinkAttachmentLayout = 'featured' | 'classic';
 
@@ -440,12 +583,11 @@ export declare interface LinkAttachmentReceivedCardProps extends LinkAttachmentB
      *   - **Link app with a URL** (Spotify / TikTok / generic link): the card
      *     chrome is an `<a target="_blank">` opening `url` — `onClick` fires
      *     alongside the navigation (use for analytics).
-     *   - **Image / file / placeholder attachment**: the card has no URL, so
-     *     it renders as a button. `onClick` is the consumer's hook for
-     *     opening an image / file preview (lightbox).
-     *   - **Video / audio attachment**: the shell stays non-interactive so
-     *     the native media controls remain operable — `onClick` is ignored
-     *     in this configuration.
+     *   - **Hero-image only card**: the card has no URL, so it renders as
+     *     a button. `onClick` is the consumer's hook for opening a preview.
+     *   - **Video / audio link previews**: the shell stays non-interactive
+     *     so the native media controls remain operable — `onClick` is
+     *     ignored in this configuration.
      */
     onClick?: () => void;
 }
@@ -525,6 +667,363 @@ export declare interface MediaMessageResolved {
     thumbnailUrl?: string;
 }
 
+/** Preload hint forwarded to the underlying `<video>` / `<audio>` element. */
+declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
+
+/**
+ * Per-MIME chat attachment cards used inside the messaging stream.
+ *
+ * Each subnamespace (`Image`, `Video`, `Audio`, `Pdf`, `File`) exposes
+ * three states (`Composer`, `Sent`, `Received`) that map to the
+ * sender / recipient sides of a chat:
+ *
+ *   - `Composer` — sender draft state with a dismiss `×` affordance.
+ *   - `Sent`     — sender-side state shown after posting.
+ *   - `Received` — recipient-side state.
+ *
+ * Sent / Received variants accept an optional `text` prop that renders
+ * inside the same bubble as the attachment — mirroring the mobile chat
+ * where a sender can pair a caption with an attachment ('Here is the
+ * file', 'Here is the image'). Composer prop types intentionally omit
+ * `text` (and `items` / `groupPosition`) so the type system enforces
+ * the same contract: captions live in the message-input textarea, not
+ * inside the draft attachment preview.
+ *
+ * Stacked attachments — every type except `Composer` accepts an
+ * `items={[…]}` prop on Sent / Received that takes precedence over
+ * the singular `src`/`filename`/etc. inputs:
+ *
+ *   - 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.
+ *   - 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.
+ *
+ * The Composer surface accepts only a single attachment at a time,
+ * so its props omit `items` / `text`.
+ *
+ * Image / Video Composer renders bare — just the media with rounded
+ * corners and a dismiss overlay, no surrounding bubble — so the draft
+ * preview reads as an in-progress attachment instead of a sent
+ * 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.
+ *
+ * # Lazy-loading defaults
+ *
+ * Media attachments bake in network-friendly defaults for long chat
+ * histories and expose explicit escape hatches when a caller knows
+ * better (e.g. a hero attachment that's already on-screen):
+ *
+ *   - **Image** — every `<img>` rendered on the bubble surface
+ *     (Composer thumbnail, single + stacked tiles, `+N` overflow)
+ *     ships with `loading="lazy" decoding="async"`. Override via the
+ *     attachment's `loading` prop (or `ImageItem.loading` for per-tile
+ *     control). The opened `ImageViewer` always eager-loads the
+ *     active image so it appears immediately.
+ *   - **Video** — the `<video>` rendered inside the `VideoViewer`
+ *     defaults to `preload="none"`, so no video bytes are fetched
+ *     until the user opens the viewer. Poster `<img>` thumbnails on
+ *     the bubble surface are `loading="lazy" decoding="async"`.
+ *     Override via the attachment's `preload` prop (or
+ *     `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).
+ *   - **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.
+ */
+export declare const MessageAttachment: {
+    Image: {
+        Composer: FC<MessageAttachmentImageComposerProps>;
+        Sent: FC<ImageAttachmentSharedProps>;
+        Received: FC<ImageAttachmentSharedProps>;
+    };
+    Video: {
+        Composer: FC<MessageAttachmentVideoComposerProps>;
+        Sent: FC<VideoAttachmentSharedProps>;
+        Received: FC<VideoAttachmentSharedProps>;
+    };
+    Audio: {
+        Composer: FC<MessageAttachmentAudioComposerProps>;
+        Sent: FC<AudioAttachmentSharedProps>;
+        Received: FC<AudioAttachmentSharedProps>;
+    };
+    Pdf: {
+        Composer: FC<MessageAttachmentPdfComposerProps>;
+        Sent: FC<PdfAttachmentSharedProps>;
+        Received: FC<PdfAttachmentSharedProps>;
+    };
+    File: {
+        Composer: FC<MessageAttachmentFileComposerProps>;
+        Sent: FC<FileAttachmentSharedProps>;
+        Received: FC<FileAttachmentSharedProps>;
+    };
+};
+
+/**
+ * Composer-only props. Single audio (`src`) only — the composer
+ * surface accepts a single attachment at a time, so `items` is not
+ * supported. Captions (`text`) and `groupPosition` are also dropped:
+ * the composer renders a standalone draft, not part of a same-author
+ * run, and captions live in the message-input textarea, not inside
+ * the draft attachment preview.
+ */
+export declare interface MessageAttachmentAudioComposerProps extends ComposerExtras {
+    src?: string;
+    mimeType?: string;
+    filename?: string;
+    /** See `AudioAttachmentSharedProps.preload`. */
+    preload?: MediaPreloadMode;
+}
+
+/** 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. */
+    mimeType?: string;
+    /**
+     * Filename — used as the download default name (consumed by the
+     * native player's kebab menu).
+     */
+    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).
+     */
+    preload?: MediaPreloadMode;
+}
+
+export declare type MessageAttachmentAudioReceivedProps = AudioAttachmentSharedProps;
+
+export declare type MessageAttachmentAudioSentProps = AudioAttachmentSharedProps;
+
+/** Shared props every `MessageAttachment.*.{Composer|Sent|Received}` accepts. */
+export declare interface MessageAttachmentBaseProps {
+    /**
+     * Optional text rendered below the attachment inside the same bubble.
+     * Mirrors the chat behavior in the mobile screenshots — `'Here is the
+     * file'`, `'Here is the image'`, etc.
+     */
+    text?: default_2.ReactNode;
+    /**
+     * Position of this attachment inside a same-author message run —
+     * mirrors the corner-flattening stream-chat-react applies to text
+     * bubbles in a clustered conversation. Defaults to `'single'`, so
+     * standalone usage keeps every corner rounded. Pass the value
+     * derived from `bubbleGroupPositionFromStream({ firstOfGroup,
+     * endOfGroup, groupedByUser })` when rendering inside a real
+     * `CustomMessage` thread to make the attachment visually merge
+     * with adjacent bubbles. Image / Video Composer ignore this — the
+     * draft preview renders bare without the surrounding bubble.
+     */
+    groupPosition?: MessageAttachmentGroupPosition;
+}
+
+/**
+ * Composer-only props. Single file (`src`) only — the composer surface
+ * accepts a single attachment at a time, so `items` is not supported.
+ * Captions (`text`) and `groupPosition` are also dropped: the composer
+ * renders a standalone draft, not part of a same-author run, and
+ * captions live in the message-input textarea, not inside the draft
+ * attachment preview.
+ */
+export declare interface MessageAttachmentFileComposerProps extends ComposerExtras {
+    src?: string;
+    filename?: string;
+    fileSize?: number;
+    mimeType?: string;
+    title?: string;
+    onClick?: (index: number) => boolean | void;
+}
+
+/** A single generic file inside a File attachment (single or stacked). */
+export declare interface MessageAttachmentFileItem {
+    src: string;
+    /** Filename — drives the title + the meta line + the download default name. */
+    filename?: string;
+    /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
+    fileSize?: number;
+    /** MIME type — drives the type icon. Defaults to `application/octet-stream`. */
+    mimeType?: string;
+    /** Override displayed title. Defaults to `filename`. */
+    title?: string;
+}
+
+export declare type MessageAttachmentFileReceivedProps = FileAttachmentSharedProps;
+
+export declare type MessageAttachmentFileSentProps = FileAttachmentSharedProps;
+
+/**
+ * Position of a bubble inside a same-author run, mirroring the grouping
+ * stream-chat-react applies to consecutive messages from the same user:
+ *
+ *   - `'single'` — standalone message, every corner fully rounded.
+ *   - `'first'`  — first in a 2+ message run; the corner facing the
+ *                  next bubble in the run is flattened.
+ *   - `'middle'` — both the corner facing the previous bubble and the
+ *                  corner facing the next bubble are flattened.
+ *   - `'end'`    — last in a 2+ message run; the corner facing the
+ *                  previous bubble is flattened (this is also the
+ *                  bubble the avatar attaches to on the receiver side).
+ *
+ * "Facing" is determined by the bubble's side: sender-aligned bubbles
+ * cluster against their right edge, receiver-aligned bubbles against
+ * their left edge.
+ */
+export declare type MessageAttachmentGroupPosition = 'single' | 'first' | 'middle' | 'end';
+
+/**
+ * Convenience adapter that derives the `BubbleGroupPosition` from the
+ * three booleans `stream-chat-react` forwards into the `Message` HOC.
+ * Drop-in for `useMessageContext()` consumers:
+ *
+ * ```tsx
+ * const { firstOfGroup, endOfGroup, groupedByUser } = useMessageContext()
+ * <MessageAttachment.Image.Sent
+ *   {...props}
+ *   groupPosition={bubbleGroupPositionFromStream({
+ *     firstOfGroup, endOfGroup, groupedByUser,
+ *   })}
+ * />
+ * ```
+ */
+export declare const messageAttachmentGroupPositionFromStream: ({ firstOfGroup, endOfGroup, groupedByUser, }: {
+    firstOfGroup?: boolean;
+    endOfGroup?: boolean;
+    groupedByUser?: boolean;
+}) => MessageAttachmentGroupPosition;
+
+/**
+ * Composer-only props. Single image (`src`) is required; stacked
+ * `items` and `text` captions are not supported in the composer state.
+ */
+export declare interface MessageAttachmentImageComposerProps {
+    src: string;
+    alt?: string;
+    filename?: string;
+    /**
+     * Native lazy-load hint forwarded to the composer thumbnail `<img>`.
+     * Defaults to `'lazy'`. See `ImageAttachmentSharedProps.loading` for
+     * the rationale.
+     */
+    loading?: ImageLoadingMode;
+    onClick?: (index: number) => boolean | void;
+    onDismiss?: () => void;
+}
+
+/** A single image inside an Image attachment (single or stacked). */
+export declare interface MessageAttachmentImageItem {
+    src: string;
+    alt?: string;
+    /** Optional width/height hint — preserved aspect on cover-fit. */
+    width?: number;
+    height?: number;
+    /**
+     * Per-tile native lazy-load override. Defaults to the parent
+     * attachment's `loading` value (which itself defaults to `'lazy'`).
+     * Pass `'eager'` for above-the-fold hero tiles.
+     */
+    loading?: ImageLoadingMode;
+}
+
+export declare type MessageAttachmentImageReceivedProps = ImageAttachmentSharedProps;
+
+export declare type MessageAttachmentImageSentProps = ImageAttachmentSharedProps;
+
+/**
+ * Composer-only props. Single PDF (`src`) only — the composer surface
+ * accepts a single attachment at a time, so `items` is not supported.
+ * Captions (`text`) and `groupPosition` are also dropped: the composer
+ * renders a standalone draft, not part of a same-author run, and
+ * captions live in the message-input textarea, not inside the draft
+ * attachment preview.
+ */
+export declare interface MessageAttachmentPdfComposerProps extends ComposerExtras {
+    src?: string;
+    filename?: string;
+    fileSize?: number;
+    title?: string;
+    onClick?: (index: number) => boolean | void;
+}
+
+/** 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?: string;
+    /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
+    fileSize?: number;
+    /** Override displayed title. Defaults to `filename`. */
+    title?: string;
+}
+
+export declare type MessageAttachmentPdfReceivedProps = PdfAttachmentSharedProps;
+
+export declare type MessageAttachmentPdfSentProps = PdfAttachmentSharedProps;
+
+/**
+ * Three messaging states a `MessageAttachment.*` card can render in,
+ * mirroring the LinkAttachment / LockedAttachment families.
+ */
+export declare type MessageAttachmentState = 'composer' | 'sent' | 'received';
+
+/**
+ * Composer-only props. Single video (`src`) is required; stacked
+ * `items` and `text` captions are not supported in the composer state.
+ */
+export declare interface MessageAttachmentVideoComposerProps {
+    src: string;
+    poster?: string;
+    mimeType?: string;
+    filename?: string;
+    /**
+     * `<video preload>` hint forwarded into the viewer. Defaults to
+     * `'none'`. See `VideoAttachmentSharedProps.preload`.
+     */
+    preload?: MediaPreloadMode;
+    onClick?: (index: number) => boolean | void;
+    onDismiss?: () => void;
+}
+
+/** A single video inside a Video attachment (single or stacked). */
+export declare interface MessageAttachmentVideoItem {
+    src: string;
+    /** Poster / thumbnail rendered before playback starts. */
+    poster?: string;
+    /** Optional MIME type (e.g. `video/mp4`). */
+    mimeType?: string;
+    /**
+     * Per-item override for the `<video preload>` hint. Defaults to the
+     * parent attachment's `preload` value (which itself defaults to
+     * `'none'` so the poster carries the visual weight and no video
+     * bytes are fetched until playback).
+     */
+    preload?: MediaPreloadMode;
+}
+
+export declare type MessageAttachmentVideoReceivedProps = VideoAttachmentSharedProps;
+
+export declare type MessageAttachmentVideoSentProps = VideoAttachmentSharedProps;
+
 declare type MessageCustomType = 'MESSAGE_TIP' | 'MESSAGE_PAID' | 'MESSAGE_CHATBOT' | 'MESSAGE_ATTACHMENT' | AgeSafetySystemType | DmAgentSystemType;
 
 export declare interface MessageMetadata {
@@ -674,6 +1173,36 @@ export declare interface Participant {
  */
 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?: string;
+    /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
+    fileSize?: number;
+    /**
+     * Override displayed title (defaults to `filename`). Useful when a
+     * sender re-titles a generated PDF before sending.
+     */
+    title?: string;
+    /**
+     * Stacked PDFs. Takes precedence over `src` when set. Each item
+     * renders as its own row inside the bubble; clicking a row opens
+     * that PDF in the viewer. Sent + Received only — the composer
+     * surface accepts a single attachment at a time.
+     */
+    items?: MessageAttachmentPdfItem[];
+    /**
+     * Forwarded to the viewer trigger. When omitted the click still
+     * opens the built-in `PdfViewer`. Supply this to fire analytics, or
+     * return `false` to intercept the open (e.g. swap to a route-based
+     * viewer / confirmation modal). Any other return value (including
+     * `void`/`undefined`) lets the built-in viewer open. For stacked
+     * attachments the `index` argument identifies the row.
+     */
+    onClick?: (index: number) => boolean | void;
+}
+
 export declare interface ReceivedCardProps extends LockedAttachmentBaseProps {
     /**
      * Called when the recipient clicks Unlock on an unpaid attachment.
@@ -739,6 +1268,43 @@ declare interface UseMessageVoteResult {
  */
 export declare const useMessaging: () => MessagingContextValue;
 
+declare interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps {
+    /** Single video — convenience for the most common case. */
+    src?: string;
+    /** Poster image — preview shown before playback starts. */
+    poster?: string;
+    /** MIME type hint — typed onto the inline `<source>` element. */
+    mimeType?: string;
+    /** Filename surfaced in the viewer toolbar + download default name. */
+    filename?: string;
+    /**
+     * Stacked videos. Takes precedence over `src` when set. Renders a
+     * 1 / 2 / 3 / 4-tile grid (5+ collapse into a `+N` overflow tile).
+     * Sent + Received only — the composer surface intentionally accepts
+     * a single attachment at a time.
+     */
+    items?: MessageAttachmentVideoItem[];
+    /**
+     * `<video preload>` hint forwarded into the viewer. Defaults to
+     * `'none'` — the poster `<img>` carries the visual weight on the
+     * bubble surface, and we shouldn't fetch any video bytes until the
+     * user actually opens the viewer. Per-item overrides live on
+     * `VideoItem.preload`. The opened `VideoViewer` always preloads
+     * metadata for the active item (so duration / first-frame appear
+     * immediately) regardless of this value.
+     */
+    preload?: MediaPreloadMode;
+    /**
+     * Forwarded to the viewer trigger. When omitted the click still
+     * opens the built-in `VideoViewer` — supply this for analytics, or
+     * return `false` to intercept the open (e.g. switch to a route-
+     * based player / confirmation modal). Any other return value
+     * (including `void`/`undefined`) lets the built-in viewer open.
+     * For stacked attachments the `index` argument identifies the tile.
+     */
+    onClick?: (index: number) => boolean | void;
+}
+
 /** @deprecated Renamed to `ReceivedCardProps`. */
 export declare type VisitorCardProps = ReceivedCardProps;