@ethora/chat-component 26.9.6 → 26.10.1

package/dist/helpers/attachments.d.ts

@@ -28,6 +28,27 @@ export declare const serializeAttachments: (attachments: IAttachment[]) => strin
  * predates this feature - and every message from a client that does not
  * speak it - takes the second path.
  */
-export declare const getMessageAttachments: (message?: Pick<IMessage, "attachments" | "location" | "locationPreview" | "mimetype" | "originalName" | "fileName" | "size"> | null) => IAttachment[];
+export declare const getMessageAttachments: (message?: (Pick<IMessage, "attachments" | "location" | "locationPreview" | "mimetype" | "originalName" | "fileName" | "size"> & {
+    duration?: unknown;
+    mediaDuration?: unknown;
+}) | null) => IAttachment[];
+/**
+ * True when the message carries a file: flagged `isMediafile`, or (older
+ * senders that never set the flag) with a real file URL or attachment. The
+ * one test every surface uses for "is this a media bubble".
+ */
+export declare const isMediaMessage: (message?: (Partial<Pick<IMessage, "isDeleted" | "isMediafile" | "attachments">> & {
+    location?: unknown;
+    mimetype?: unknown;
+    originalName?: unknown;
+    fileName?: unknown;
+    locationPreview?: unknown;
+}) | null) => boolean;
+/**
+ * Maps one object from POST /files/ `results` to the attachment a sent
+ * message carries. Field names here follow the API's own spelling
+ * (`originalname`, `filename`), not the wire attribute names.
+ */
+export declare const toUploadedAttachment: (raw: any) => IAttachment;
 /** Name to show for an attachment, with the URL tail as the last resort. */
 export declare const getAttachmentName: (attachment: IAttachment) => string;

package/dist/helpers/avatarImageCache.d.ts

@@ -0,0 +1,9 @@
+export declare const FAILED_TTL_MS = 60000;
+export declare const avatarIdentity: (url: string) => string;
+/** The URL that already loaded for this file (any token), if any. */
+export declare const getLoadedAvatarUrl: (url: string) => string | undefined;
+export declare const markAvatarLoaded: (url: string) => void;
+export declare const markAvatarFailed: (url: string) => void;
+export declare const hasAvatarFailed: (url: string) => boolean;
+/** Test helper. */
+export declare const resetAvatarCache: () => void;

package/dist/helpers/caption.d.ts

@@ -0,0 +1,63 @@
+import { IMentionSpan } from '../types/types';
+/**
+ * The text typed with a set of attachments, sent as part of the media
+ * message itself (never as a separate text stanza).
+ *
+ * `mentions` index into `text`, the same way a text message's mention spans
+ * index into its body.
+ */
+export interface CaptionInput {
+    text: string;
+    mentions?: IMentionSpan[];
+}
+export interface NormalizedCaption {
+    caption: string;
+    mentions?: IMentionSpan[];
+}
+/**
+ * Mention spans for a caption, checked against the caption text: a span that
+ * no longer reads "@Name" at its offset is dropped. Undefined when nothing is
+ * left, so a caption without mentions carries no empty attribute.
+ */
+export declare const normalizeCaptionMentions: (value: unknown, caption: string) => IMentionSpan[] | undefined;
+/**
+ * Turns what the composer typed into the caption that travels with the
+ * media. Undefined for blank text, which means "no caption".
+ */
+export declare const normalizeCaptionInput: (input?: CaptionInput | null) => NormalizedCaption | undefined;
+/** What a media message's text is, and the @-mention spans that index into it. */
+export interface ResolvedCaption {
+    text: string;
+    mentions?: IMentionSpan[];
+}
+export interface CaptionOptions {
+    /**
+     * The caller already knows this is a media message (a thin `lastMessage`
+     * that only says so by its id). Otherwise it is read off the message.
+     */
+    isMedia?: boolean;
+    /** The message is sealed: only a caption that came out of the envelope counts. */
+    sealed?: boolean;
+    /** Extra names of the sender, which a body may merely echo. */
+    senderNames?: string[];
+}
+/**
+ * The text of a media message, from whichever format carried it. The one
+ * place that knows the formats, so every surface (bubble, room list preview,
+ * notification, reply quote, copy) agrees:
+ *
+ *  1. `caption` (+ `captionMentions`): what this SDK sends. The only source
+ *     for a sealed message, whose caption comes out of the envelope.
+ *  2. The caption under another name on `<data>` (`captionText`, `text`,
+ *     `message`, `description`, `title`) from other clients.
+ *  3. A real `body`: older clients and other SDKs put the text in the
+ *     `<body>` of the media message itself. "media", the file's name or URL,
+ *     the sender's own name or e-mail and generated labels are not text.
+ *
+ * Never derived for a sealed message, and never for a message with no file.
+ */
+export declare const resolveMessageCaption: (message?: object | null, options?: CaptionOptions) => ResolvedCaption | undefined;
+/** The caption a message carries, or undefined when it has none. */
+export declare const getMessageCaption: (message?: object | null, options?: CaptionOptions) => string | undefined;
+/** The mention spans of `getMessageCaption`'s text. */
+export declare const getMessageCaptionMentions: (message?: object | null, options?: CaptionOptions) => IMentionSpan[] | undefined;

package/dist/helpers/checkUniqueUsers.d.ts

@@ -1,3 +1,3 @@
 import { IMessage, RoomMember } from '../types/types';
-export declare const checkUniqueUsers: (messages: IMessage[]) => Promise<RoomMember[]>;
-export declare const checkSingleUser: (usersSet: Record<string, RoomMember>, xmppUsername: string) => Promise<RoomMember>;
+export declare const checkUniqueUsers: (messages: IMessage[]) => any;
+export declare const checkSingleUser: (usersSet: Record<string, RoomMember>, xmppUsername: string) => Promise<any>;

package/dist/helpers/composerFocus.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hands "focus the message input" from the room list to the composer.
+ *
+ * The room list and the composer live in different subtrees, and the
+ * composer may only mount after the switch (or re-render later), so a plain
+ * callback would race it. Instead the request is parked here until the
+ * mounted composer for that room claims it. A claim is one-shot, so a single
+ * click focuses exactly once.
+ */
+type Listener = () => void;
+/** Ask the composer for `roomJid` to take focus. Wakes mounted composers. */
+export declare const requestComposerFocus: (roomJid: string | null | undefined) => void;
+/** Mounted composers subscribe here to learn that a request arrived. */
+export declare const subscribeComposerFocus: (listener: Listener) => (() => void);
+/**
+ * Claims a pending request for `roomJid`. Returns true exactly once per
+ * request, and only for the room the request was made for.
+ */
+export declare const takeComposerFocusRequest: (roomJid: string | null | undefined) => boolean;
+/** Test helper: drops any parked request and all listeners. */
+export declare const resetComposerFocusForTests: () => void;
+export {};

package/dist/helpers/createMainMessageForThread.d.ts

@@ -1,2 +1,2 @@
 import { IMessage } from '../types/types';
-export declare const createMainMessageForThread: (message: IMessage) => string;
+export declare const createMainMessageForThread: (message: IMessage, t?: (key: string, vars?: Record<string, string | number>) => string) => string;

package/dist/helpers/dedupeMembers.d.ts

@@ -0,0 +1,10 @@
+import { RoomMember } from '../types/types';
+/** Stable identity of a member: normalised xmppUsername local part, else _id. */
+export declare const memberKey: (m: Partial<RoomMember> | null | undefined) => string;
+/**
+ * Drops repeated members (keeps the first occurrence, order preserved).
+ * The room directory endpoint can return the same user on several pages;
+ * duplicates would produce duplicate React keys and inflated counts.
+ * Members without any identity are dropped.
+ */
+export declare const dedupeMembers: <T extends Partial<RoomMember>>(list: ReadonlyArray<T> | null | undefined) => T[];

package/dist/helpers/downloadFile.d.ts

@@ -0,0 +1,19 @@
+export type DownloadResult = 'blob' | 'direct' | 'http-error';
+export interface DownloadDeps {
+    fetchImpl?: typeof fetch;
+    /** Hands a blob to the browser as a download. */
+    saveBlob?: (blob: Blob, fileName: string) => void;
+    /** Hands a plain URL to the browser as a download / new tab. */
+    saveUrl?: (url: string, fileName: string) => void;
+}
+/**
+ * Saves a media file. The blob route is preferred (it keeps the user's file
+ * name), but it needs CORS: <img>/<video>/<a> to a host such as
+ * secure-files.* never did, so a host without Access-Control-Allow-Origin
+ * makes fetch() reject with a bare TypeError. That says nothing about the
+ * file, so fall back to handing the URL to the browser directly.
+ *
+ * A reachable server that answers with an error status is different: its
+ * body is an error page, not the file, so nothing is saved.
+ */
+export declare function downloadFile(url: string, fileName: string, deps?: DownloadDeps): Promise<DownloadResult>;

package/dist/helpers/fileKind.d.ts

@@ -11,7 +11,24 @@ export type FileKind = 'image' | 'video' | 'audio' | 'pdf' | 'file';
 /** Lowercase extension without the dot; '' when the name carries none. */
 export declare const getFileExtension: (name?: string) => string;
 export declare const isPdfFile: (mimetype?: string, name?: string) => boolean;
+/**
+ * SVG is deliberately not an image here. It does not render reliably as a
+ * message picture, can be blocked by the host's CSP, and is a script
+ * injection vector when opened directly. It is treated as a plain file.
+ */
+export declare const isSvgFile: (mimetype?: string, name?: string) => boolean;
+/** True when the file renders as a picture (never for SVG). */
+export declare const isRasterImage: (mimetype?: string, name?: string) => boolean;
+/**
+ * The mimetype a file name's extension stands for, for the pictures, videos,
+ * audio and PDFs a bubble can show. Undefined for anything else.
+ */
+export declare const inferMimeFromName: (name?: string) => string | undefined;
+/** A mimetype that says nothing: empty, or the storage's "could not sniff". */
+export declare const isGenericMime: (mimetype?: string) => boolean;
 export declare const getFileKind: (mimetype?: string, name?: string) => FileKind;
 export declare const formatFileSize: (sizeInBytes?: string | number) => string;
 /** Middle-truncates the base name, always keeping the extension visible. */
 export declare const formatFileName: (name: string, maxLength: number) => string;
+/** An animated-picture candidate: image/gif, or a name or URL ending in .gif. */
+export declare const isGifFile: (mimetype?: string, nameOrUrl?: string) => boolean;

package/dist/helpers/historyPreloadConfig.d.ts

@@ -0,0 +1,25 @@
+import { IConfig } from '../types/types';
+export type HistoryPreloadMode = 'staged' | 'all' | 'off';
+export interface ResolvedHistoryPreload {
+    /**
+     * 'legacy' only when a host explicitly pinned
+     * `historyQoS.stagedPreloadEnabled: false`: the old cache catch-up path
+     * (updateMessagesTillLast). Everything else resolves to a public mode.
+     */
+    mode: HistoryPreloadMode | 'legacy';
+    /** Rooms (by recent activity) the background sweep covers. 0 = no cap. */
+    topRooms: number;
+    concurrency: number;
+    firstPassSize: number;
+    secondPassSize: number;
+}
+export declare const DEFAULT_PRELOAD_TOP_ROOMS = 8;
+export declare const DEFAULT_PRELOAD_CONCURRENCY = 3;
+export declare const TEASER_ROOM_FACTOR = 4;
+/**
+ * One place that turns `config.historyPreload` (and the older
+ * `historyQoS.stagedPreload*` / `preloadTopKRooms` names, still honoured)
+ * into the numbers the preload sweeps use. Staged preload is the default:
+ * the sweep covers the top N rooms, every other room loads when it is opened.
+ */
+export declare const resolveHistoryPreloadConfig: (config?: Pick<IConfig, "historyPreload" | "historyQoS"> | null) => ResolvedHistoryPreload;

package/dist/helpers/historyPreloadScheduler.d.ts

@@ -1,4 +1,5 @@
 import { default as XmppClient } from '../networking/xmppClient';
+import { IRoom } from '../types/types';
 interface HistoryPreloadSchedulerOptions {
     client: XmppClient;
     signal?: AbortSignal;
@@ -10,6 +11,8 @@ interface HistoryPreloadSchedulerOptions {
     defaultRoomJids?: string[];
     forceReload?: boolean;
     completionState?: 'done' | 'partial';
+    skipApiPreview?: boolean;
 }
+export declare const hasApiPreview: (room?: IRoom) => boolean;
 export declare const runHistoryPreloadScheduler: (options: HistoryPreloadSchedulerOptions) => Promise<void>;
 export default runHistoryPreloadScheduler;

package/dist/helpers/insertMessageWithDelimiter.d.ts

@@ -1,4 +1,5 @@
 import { IMessage } from '../types/types';
+export declare function deepMerge(target: any, source: any): any;
 export declare function insertMessageWithDelimiter(roomMessages: Partial<IMessage>[], message: IMessage, lastViewedTimestamp: {
     toString: () => string;
 }): void;

package/dist/helpers/isMessageSearchEnabled.d.ts

@@ -0,0 +1,9 @@
+import { IConfig } from '../types/types';
+/**
+ * The single rule for message search. It is opt-in: the host must set
+ * `enableMessageSearch` AND provide an `appId` (the archive endpoint is scoped
+ * by app). A leftover `disableMessageSearch: true` still wins as a hard off.
+ * Every entry point (header button, profile entry, chat-list matches, the
+ * Ctrl/Cmd+F shortcut, the modal itself) goes through this helper.
+ */
+export declare const isMessageSearchEnabled: (config?: Pick<IConfig, "enableMessageSearch" | "disableMessageSearch" | "appId"> | null) => boolean;

package/dist/helpers/jumpThread.d.ts

@@ -0,0 +1,56 @@
+import { IMessage } from '../types/types';
+/** How long a jump request may stay pending before it is dropped. */
+export declare const JUMP_TTL_MS = 60000;
+/**
+ * Index of the message a jump names.
+ *
+ * By id first (message.id is the MAM stanza id for history, xmppId the client
+ * message id). When the request has no id at all, which is common for archive
+ * rows, by content: same text, sent within a few seconds of the same time.
+ */
+export declare const findMessageIndex: (messages: IMessage[], ids: string[], content?: {
+    createdAt?: string;
+    body?: string;
+}) => number;
+/**
+ * Where a jump to a thread REPLY lands, and the thread panel's parent message
+ * when that message is not in the room's live list.
+ *
+ * Replies never appear in the main list (it hides them unless they are also
+ * shown in the channel), so a jump to one has to open its parent's thread and
+ * highlight the reply there. Two things have to be remembered for that:
+ *  - which list owns the jump: `at` is the pending request this entry serves,
+ *    `parentId` the thread that owns it. The main list stays inert for a jump
+ *    that has an owner thread, and a thread list stays inert for any jump that
+ *    is not its own (see useJumpToMessage);
+ *  - the parent and the replies when they exist only in a jump window or came
+ *    from a separate fetch: the thread panel reads them from here, so it does
+ *    not depend on the window that found them still being on screen.
+ *
+ * Kept outside redux on purpose: the room slice's thread flag lives on
+ * messages of the live list, which is exactly what these messages are not in.
+ */
+export interface JumpThreadState {
+    roomJID: string;
+    parentId: string;
+    /** The pending request this entry serves; null for a thread opened by hand. */
+    at: number | null;
+    /** Set only when the parent is not in the room's live messages. */
+    parent: IMessage | null;
+    /** Replies known to belong to the thread beyond the live list. */
+    replies: IMessage[];
+}
+export declare const getJumpThread: () => JumpThreadState | null;
+export declare const setJumpThread: (next: JumpThreadState | null) => void;
+export declare const clearJumpThread: () => void;
+export declare const subscribeJumpThread: (listener: () => void) => (() => void);
+export declare const useJumpThread: () => JumpThreadState | null;
+/** The thread that owns the jump `at`, or null when the main list does. */
+export declare const ownerThreadFor: (thread: JumpThreadState | null, at: number | undefined) => string | null;
+/**
+ * The parent id of a message that is a thread reply and nothing else, or null:
+ * a reply also shown in the channel is in the main list, so it needs no thread.
+ */
+export declare const replyParentId: (message: IMessage) => string | null;
+/** `a` then `b`, one entry per message id, oldest first. */
+export declare const mergeById: (a: IMessage[], b: IMessage[]) => IMessage[];

package/dist/helpers/jumpWindow.d.ts

@@ -0,0 +1,73 @@
+import { HistoryWindowPage } from '../networking/xmppClient';
+import { JumpWindow } from '../roomStore/roomsSlice';
+import { IMessage } from '../types/types';
+/** Messages shown above / below the target when a window opens (tunable). */
+export declare const JUMP_WINDOW_BEFORE = 10;
+export declare const JUMP_WINDOW_AFTER = 10;
+/** Page size for loading more once the reader scrolls toward either edge. */
+export declare const JUMP_WINDOW_PAGE = 20;
+/** The slice of the XMPP client the window helpers need. */
+export interface HistoryWindowClient {
+    getHistoryWindow: (chatJID: string, max: number, cursor: {
+        before?: number;
+        after?: number;
+        start?: string;
+        end?: string;
+    }) => Promise<HistoryWindowPage>;
+}
+export type JumpWindowResult = 
+/** The window around the target is ready to be shown. */
+{
+    status: 'found';
+    window: JumpWindow;
+}
+/** The server answered, and the target is not in the archive. */
+ | {
+    status: 'missing';
+}
+/** No usable id, or a request failed: use the paging path instead. */
+ | {
+    status: 'unavailable';
+};
+/**
+ * How far apart the archive's timestamp and the transcript's may be for the
+ * same message. They are recorded by different components, so they are not
+ * identical, but never more than a moment apart.
+ */
+export declare const CONTENT_MATCH_WINDOW_MS = 5000;
+/** What a hit with no archive id can be located by. */
+export interface JumpContent {
+    createdAt?: string;
+    body?: string;
+}
+export declare const mamIdCandidates: (ids: string[]) => string[];
+/**
+ * Fetches about JUMP_WINDOW_BEFORE messages before the target, the target and
+ * about JUMP_WINDOW_AFTER after it: two MAM queries in parallel (the target
+ * itself comes with the "after" page, asked from one microsecond before it).
+ * Nothing is written to the store here.
+ */
+export declare function loadJumpWindow(client: HistoryWindowClient, roomJID: string, ids: string[], content?: JumpContent): Promise<JumpWindowResult>;
+/**
+ * For a hit with no usable archive id (older archive documents carry neither a
+ * stanza id nor a message id): ask the server for the rows within a few
+ * seconds of its timestamp (MAM start/end filter), find the one with the same
+ * text, and continue exactly as the id-based window does with that row's id.
+ * The server's answer is final: 'missing' only when it said the range holds no
+ * such row.
+ */
+export declare function loadJumpWindowByTime(client: HistoryWindowClient, roomJID: string, content: JumpContent): Promise<JumpWindowResult>;
+export interface OlderWindowPage {
+    messages: IMessage[];
+    olderCursor: number | null;
+    hasOlder: boolean;
+}
+export interface NewerWindowPage {
+    messages: IMessage[];
+    newerCursor: number | null;
+    hasNewer: boolean;
+}
+/** The page above the window; null when the request failed. */
+export declare function loadOlderWindowPage(client: HistoryWindowClient, window: JumpWindow): Promise<OlderWindowPage | null>;
+/** The page below the window; null when the request failed. */
+export declare function loadNewerWindowPage(client: HistoryWindowClient, window: JumpWindow): Promise<NewerWindowPage | null>;

package/dist/helpers/lastMessagePreview.d.ts

@@ -0,0 +1,55 @@
+import { LastMessage } from '../types/types';
+/**
+ * What the room list draws for a media last message.
+ *
+ * One derivation for every source of a last message: the live stanza that
+ * updates roomsSlice, the history loaded from MAM, and the flattened
+ * `lastMessage` the backend embeds in `GET /chats/my`. All three reach the row
+ * as the same loose message object, and since multi-attachment messages the
+ * file fields may sit in `attachments` only, with no top level `location` or
+ * `mimetype`, so the row reads through getMessageAttachments like the bubble.
+ */
+export type MediaPreviewKind = 'image' | 'video' | 'voice' | 'audio' | 'file'
+/** Media of unknown type: a thin backend payload that only says "media". */
+ | 'attachment' | 'sealed';
+export interface MediaPreview {
+    kind: MediaPreviewKind;
+    /** How many attachments the message carries (at least 1). */
+    count: number;
+    /** Thumbnail source, before the viewer's file token is appended. */
+    thumbUrl?: string;
+    /** The single file's name, for the file kind. */
+    fileName?: string;
+    /** "0:12" for a voice message or audio file, when the duration is known. */
+    durationText?: string;
+    /** The text the sender typed next to the media, if any. */
+    caption?: string;
+}
+type PreviewSource = Partial<LastMessage> & {
+    attachments?: unknown;
+    fileName?: string;
+    location?: string;
+    /** The caption the sender typed with the files, carried on the message. */
+    caption?: unknown;
+    duration?: unknown;
+    mediaDuration?: unknown;
+};
+/** True when the last message should render as media rather than text. */
+export declare const hasMediaPreview: (message?: PreviewSource | null) => boolean;
+/**
+ * `sealed` is true for an e2ee room or a message flagged `clientEncrypted`.
+ * Sealed content never gets a thumbnail: the server holds ciphertext, so the
+ * row shows the icon and the label only.
+ */
+export declare const deriveMediaPreview: (message?: PreviewSource | null, options?: {
+    sealed?: boolean;
+    senderNames?: string[];
+}) => MediaPreview | undefined;
+/**
+ * Which message the room row previews: the newest real message already in the
+ * room's `messages[]` (a live stanza or history), else the backend's
+ * `lastMessage` seed. Entries with neither text nor media (markers, receipts,
+ * state-only stanzas) are skipped.
+ */
+export declare const pickPreviewSource: <T extends PreviewSource>(messages: T[] | undefined, lastMessage?: T | null) => T | undefined;
+export {};

package/dist/helpers/mapWithConcurrency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs `worker` over `items` with at most `limit` calls in flight, and
+ * resolves with the results in INPUT order, whatever order the calls finish
+ * in. Workers that throw are reported as rejected entries instead of
+ * aborting the rest of the batch, so one failed upload never stops its
+ * siblings.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]>;

package/dist/helpers/mediaBox.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure sizing helpers for in-bubble media. Kept free of React and the DOM so
+ * the rules (clamping, never upscaling, duration formatting) are testable.
+ */
+/**
+ * Reference box a solo picture is fitted into. It is the largest the
+ * responsive media width ever gets (see MEDIA_WIDTH_CSS), so a picture is
+ * never upscaled past what the widest pane could show; the real, smaller cap
+ * for the current pane is applied in CSS from the shared width variable.
+ */
+export declare const SOLO_IMAGE_MAX_WIDTH_PX = 560;
+export declare const SOLO_IMAGE_MAX_HEIGHT_PX = 784;
+/** Box used while a solo image's dimensions are still unknown: 4:3. */
+export declare const SOLO_DEFAULT_BOX: {
+    readonly width: 560;
+    readonly height: 420;
+};
+/** Box used while a solo video's dimensions are unknown: 16:9. */
+export declare const SOLO_VIDEO_DEFAULT_BOX: {
+    readonly width: 560;
+    readonly height: 315;
+};
+/**
+ * The ONE width of the media block of a message: the album grid, a solo
+ * picture or video and the file cards under them all share it.
+ *
+ * `--ethora-pane-w` is the width of the message list pane (not the
+ * viewport), written by the message list's ResizeObserver, so a chat embedded
+ * in a narrow host sizes itself to that host. A container query would do the
+ * same, but `container-type` contains layout, which turns the list into the
+ * containing block of the context menu's `position: fixed` overlay.
+ *
+ *   pane 390   -> 300 (the bubble then clips it to its own width)
+ *   pane 700   -> 340
+ *   pane 1000  -> 430
+ *   pane 1400  -> 550
+ *   pane 1600+ -> 560
+ */
+export declare const MEDIA_WIDTH_VAR = "--ethora-media-w";
+export declare const PANE_WIDTH_VAR = "--ethora-pane-w";
+export declare const MEDIA_WIDTH_RULE = "clamp(300px, calc(var(--ethora-pane-w, 800px) * 0.3 + 130px), 560px)";
+/** Use inside a stylesheet or inline style; falls back when the list did not set it. */
+export declare const MEDIA_WIDTH_CSS = "var(--ethora-media-w, 340px)";
+/** A lone file card is capped so it does not become a giant bar. */
+export declare const FILE_ONLY_MAX_WIDTH_PX = 360;
+/** Tallest a solo picture gets, relative to the media width. */
+export declare const SOLO_MAX_HEIGHT_FACTOR = 1.4;
+/** CSS length of the tallest a solo picture may be: 60vh, or 1.4 x the media width. */
+export declare const SOLO_MAX_HEIGHT_CSS = "min(60vh, calc(1.4 * var(--ethora-media-w, 340px)))";
+export interface MediaBox {
+    width: number;
+    height: number;
+}
+/**
+ * Fit a natural size inside a max box, keeping its aspect ratio. Never
+ * upscales: a picture smaller than the box keeps its natural size. Returns
+ * null when either dimension is unknown or not positive.
+ */
+export declare const fitMediaBox: (naturalWidth: number | undefined, naturalHeight: number | undefined, maxWidth?: number, maxHeight?: number) => MediaBox | null;
+/** A picture whose longest side is below this is shown at its natural size. */
+export declare const SOLO_TINY_MAX_SIDE_PX = 120;
+/** Smallest frame drawn around a tiny picture. */
+export declare const SOLO_MIN_FRAME_PX = 64;
+/** Beyond this long:short ratio a picture is cropped rather than letterboxed. */
+export declare const SOLO_EXTREME_RATIO = 3;
+/** Shorter side of the box of an extreme-ratio picture. */
+export declare const SOLO_MIN_SHORT_SIDE_PX = 96;
+/**
+ * How the picture sits in its box.
+ *   fit     - same aspect ratio as the box, fills it.
+ *   cover   - extreme ratio: fills the box and is gently cropped from the centre.
+ *   natural - smaller than its frame: drawn at its own size, centred on a tile.
+ */
+export type SoloMode = 'fit' | 'cover' | 'natural';
+export interface SoloBox {
+    /** The frame (stage) size in CSS px. */
+    width: number;
+    height: number;
+    /** The drawn picture size; equals the frame unless `mode` is natural. */
+    imageWidth: number;
+    imageHeight: number;
+    mode: SoloMode;
+}
+/**
+ * The size policy of a single picture in a bubble.
+ *
+ *  - Inside the max box (560 x 784 by default) at its own aspect ratio,
+ *    never upscaled. CSS narrows it to the pane's media width and height.
+ *  - Tiny (longest side < 120): natural size on a tile of at least 64px.
+ *  - Extreme ratio (beyond 3:1 or 1:3): the shorter side is lifted to 96px
+ *    and the picture is cover-cropped (the viewer shows all of it).
+ *
+ * `ratioOnly` is for a size read from a downscaled preview: only its aspect
+ * ratio is trusted, so the box is scaled up to the real maximum instead of
+ * staying thumbnail-sized (which would jump when the full file arrives).
+ * Returns null while a dimension is unknown.
+ */
+export declare const computeSoloBox: (naturalWidth: number | undefined, naturalHeight: number | undefined, options?: {
+    ratioOnly?: boolean;
+    maxWidth?: number;
+    maxHeight?: number;
+}) => SoloBox | null;
+/** Parses a dimension that may arrive as a number or a numeric string. */
+export declare const parseDimension: (value: unknown) => number | undefined;
+/**
+ * Formats a duration in seconds as m:ss, or h:mm:ss past one hour. Returns
+ * an empty string when the value is missing or not a positive number, so
+ * callers can skip the chip entirely.
+ */
+export declare const formatDuration: (seconds: string | number | undefined) => string;

package/dist/helpers/mediaBubble.d.ts

@@ -0,0 +1,39 @@
+import { IAttachment } from '../types/types';
+/**
+ * How a message's files share one column:
+ *  - album: two or more pictures or videos, one grid; cards stretch to it.
+ *  - solo: one picture or video; the block shrink-wraps it (at most the media
+ *    width) and any cards stretch to that.
+ *  - files: documents only; the media width, capped so a lone card is no bar.
+ *  - plain: voice notes only, which keep their own width.
+ */
+export type MediaBlockMode = 'album' | 'solo' | 'files' | 'plain';
+export interface AttachmentItem {
+    attachment: IAttachment;
+    /** Position in the message's attachments, used for retry. */
+    index: number;
+}
+export interface AttachmentPartition {
+    /** Pictures and videos rendered as one album grid (empty for a lone one). */
+    tiles: AttachmentItem[];
+    /** Everything else, rendered one after another below the grid. */
+    rows: AttachmentItem[];
+}
+export declare const attachmentKind: (attachment: IAttachment) => import('./fileKind').FileKind;
+/**
+ * Splits a message's files into the album and the rows below it. Pictures and
+ * videos always come first, in the order they were picked; the remaining files
+ * (documents, svg, pdf, audio) follow, also in their picked order. A lone
+ * picture is not an album: it stays a row, but it still leads the message.
+ */
+export declare const partitionAttachments: (attachments: IAttachment[]) => AttachmentPartition;
+/** The block mode for a message's files, from the partition it renders. */
+export declare const getMediaBlockMode: (attachments: IAttachment[]) => MediaBlockMode;
+/**
+ * Whether the time can sit as a glass pill over the media (Telegram style):
+ * only when the bubble is pictures and videos and nothing else. A caption or
+ * any card or audio row puts the time on its own line at the bottom right.
+ */
+export declare const usesMediaOverlayTime: (attachments: IAttachment[], options?: {
+    hasCaption?: boolean;
+}) => boolean;

package/dist/helpers/mediaLabel.d.ts

@@ -0,0 +1,10 @@
+import { getMessageAttachments } from './attachments';
+type Translate = (key: string, vars?: Record<string, string | number>) => string;
+/**
+ * What to call a media message's files when there is no text to show:
+ * "Photo", "Video", "Voice message", "File", "3 photos", "2 attachments".
+ * Empty when the message carries no file. The kind comes from the normalised
+ * attachment, so a file sent with no mimetype is still a photo by its name.
+ */
+export declare const getMediaLabel: (message: Parameters<typeof getMessageAttachments>[0], t: Translate) => string;
+export {};

package/dist/helpers/mediaSendRetry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Retry hooks for media messages whose uploads did not all land.
+ *
+ * The send closure lives inside useSendMessage, but the bubble that shows
+ * "Retry" is somewhere else in the tree and has no access to it. The send
+ * registers its retry runner under the message id while the message is
+ * unsent, and the bubble looks it up here. The runner is removed as soon as
+ * the message is delivered.
+ */
+export type MediaRetryRunner = (indices?: number[]) => Promise<boolean>;
+export declare const registerMediaRetry: (messageId: string, runner: MediaRetryRunner) => void;
+export declare const unregisterMediaRetry: (messageId: string) => void;
+export declare const hasMediaRetry: (messageId: string) => boolean;
+/**
+ * Re-runs the uploads still missing for `messageId` (only `index` / `indices`
+ * when given), then sends the message once every file is in. Resolves to
+ * false when nothing is registered or the attempt did not deliver.
+ */
+export declare const retryMediaSend: (messageId: string, index?: number | number[]) => Promise<boolean>;
+/**
+ * Asks for one file of `messageId` to be retried. Requests made in the same
+ * tick are merged into one run: the runner takes a single run at a time, so
+ * a separate call per tile would drop every retry after the first.
+ */
+export declare const requestMediaRetry: (messageId: string, index: number) => void;