@marktiderman/genesis-chat 0.2.0 → 0.2.2

package/src/native/topics.tsx

@@ -6,8 +6,8 @@
  * name field). `ChatThreadScreen` shows it when the conversation has topics, and reads the
  * messages of the topic chosen. The same rules as the web's `ChatTopicBar`.
  */
-import { useState } from "react";
-import { ScrollView, View } from "react-native";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ScrollView, View, type LayoutChangeEvent } from "react-native";
 import { NativeButton, NativeChip, NativeChipGroup, NativeIcon, NativeInput, NativeListItem, NativeSheet, NativeText, useToast } from "@marktiderman/genesis-ui-native/components";
 import { useThemeRoles } from "@marktiderman/genesis-ui-native/hooks";
 import { topicKey } from "../core/extras";
@@ -48,6 +48,17 @@ export function checkTopicName(title: string, topics: readonly ChatTopic[], rena
   return topics.some((t) => t.topic === key) ? { error: "exists" } : { key };
 }
 
+/**
+ * Where the bar scrolls to so a chip shows whole (with `margin` to spare), or null when it already
+ * does: a chip past the right edge comes in from the right, one before the left from the left.
+ */
+export function scrollToShow(chip: { x: number; width: number }, view: { offset: number; width: number }, margin = 8): number | null {
+  if (view.width <= 0) return null;
+  if (chip.x - margin < view.offset) return Math.max(0, chip.x - margin);
+  if (chip.x + chip.width + margin > view.offset + view.width) return Math.max(0, chip.x + chip.width + margin - view.width);
+  return null;
+}
+
 export interface ChatTopicBarProps {
   topics: ChatTopic[];
   /** The topic shown; null for "All". */
@@ -72,6 +83,31 @@ export function ChatTopicBar({ topics, value, onValueChange, canManage = false,
   const [error, setError] = useState<string | null>(null);
   const current = value ? (topics.find((t) => t.topic === value) ?? null) : null;
 
+  // The chosen chip is scrolled into view: a topic just added sits at the end, past the edge.
+  const scrollRef = useRef<{ scrollTo?: (o: { x: number; animated?: boolean }) => void } | null>(null);
+  const chips = useRef(new Map<string, { x: number; width: number }>());
+  const view = useRef({ offset: 0, width: 0 });
+  const reveal = useCallback((key: string | null) => {
+    const chip = chips.current.get(key ?? ALL);
+    if (!chip) return;
+    const to = scrollToShow(chip, view.current);
+    if (to === null) return;
+    view.current.offset = to;
+    scrollRef.current?.scrollTo?.({ x: to, animated: true });
+  }, []);
+  const latestValue = useRef(value);
+  latestValue.current = value;
+  useEffect(() => reveal(value), [value, reveal]);
+  const trackOffset = (e: { nativeEvent: { contentOffset: { x: number } } }) => {
+    view.current.offset = e.nativeEvent.contentOffset.x;
+  };
+  const onChipLayout = (key: string) => (e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    chips.current.set(key, { x, width });
+    // A new topic is chosen before its chip exists: it is shown once the chip has its place.
+    if (key === (latestValue.current ?? ALL)) reveal(latestValue.current);
+  };
+
   const close = () => {
     if (busy) return;
     setSheet(null);
@@ -117,25 +153,44 @@ export function ChatTopicBar({ topics, value, onValueChange, canManage = false,
 
   return (
     <View testID={testID} style={{ flexDirection: "row", alignItems: "center", backgroundColor: colors.groupedBackground, paddingLeft: 8 }}>
-      <ScrollView horizontal showsHorizontalScrollIndicator={false} accessibilityLabel={copy.topics} contentContainerStyle={{ paddingVertical: 4, paddingRight: 8 }} style={{ flex: 1 }}>
+      <ScrollView
+        ref={scrollRef as never}
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        accessibilityLabel={copy.topics}
+        contentContainerStyle={{ paddingVertical: 4, paddingRight: 8 }}
+        style={{ flex: 1 }}
+        onLayout={(e: LayoutChangeEvent) => {
+          view.current.width = e.nativeEvent.layout.width;
+          reveal(latestValue.current);
+        }}
+        onScroll={trackOffset}
+        onScrollEndDrag={trackOffset}
+        onMomentumScrollEnd={trackOffset}
+        scrollEventThrottle={64}
+      >
         <NativeChipGroup mode="single" value={value ?? ALL} onChange={(v) => onValueChange(v === ALL ? null : (v as string))} className="flex-nowrap" testID={`${testID}-group`}>
-          <NativeChip value={ALL} testID={`${testID}-all`}>
-            {copy.topicAll}
-          </NativeChip>
-          {topics.map((t) => (
-            <NativeChip key={t.topic} value={t.topic} testID={`${testID}-${t.topic}`}>
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
-                {t.closedAt ? <NativeIcon name="lock" size={13} color={colors.secondaryLabel} label={copy.topicClosed} /> : null}
-                <NativeText preset="body-sm" numberOfLines={1} style={{ maxWidth: 180, fontWeight: value === t.topic ? "600" : "400", color: value === t.topic ? colors.tint : colors.label }}>
-                  {t.title}
-                </NativeText>
-              </View>
+          <View onLayout={onChipLayout(ALL)}>
+            <NativeChip value={ALL} testID={`${testID}-all`}>
+              {copy.topicAll}
             </NativeChip>
+          </View>
+          {topics.map((t) => (
+            <View key={t.topic} onLayout={onChipLayout(t.topic)}>
+              <NativeChip value={t.topic} testID={`${testID}-${t.topic}`}>
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+                  {t.closedAt ? <NativeIcon name="lock" size={13} color={colors.secondaryLabel} label={copy.topicClosed} /> : null}
+                  <NativeText preset="body-sm" numberOfLines={1} style={{ maxWidth: 180, fontWeight: value === t.topic ? "600" : "400", color: value === t.topic ? colors.tint : colors.label }}>
+                    {t.title}
+                  </NativeText>
+                </View>
+              </NativeChip>
+            </View>
           ))}
         </NativeChipGroup>
       </ScrollView>
       {canManage && onSetTopic ? <ChatIconButton testID={`${testID}-menu`} icon="more" label={copy.topicOptions} onPress={() => setSheet({ step: "menu" })} /> : null}
-      <NativeSheet open={sheet !== null} onOpenChange={(o) => (o ? undefined : close())} testID={`${testID}-sheet`}>
+      <NativeSheet open={sheet !== null} onOpenChange={(o) => (o ? undefined : close())} fitContent testID={`${testID}-sheet`}>
         {sheet?.step === "name" ? (
           <View style={{ padding: 16, gap: 12 }}>
             <NativeText preset="h4" accessibilityRole="header">

package/src/native/video-player.tsx

@@ -6,10 +6,12 @@
  * playback id; a stored one plays from its signed link (or, while it uploads, from the
  * phone). Until Mux has processed it, it says so. One plays at a time, voice notes included:
  * it takes the same playback slot (`claimPlayback`), so starting it pauses a voice note and
- * the other way round. The bubble's VoiceOver actions reach it by id (`toggleVideo`).
+ * the other way round. The bubble's VoiceOver actions reach it by id (`toggleVideo`). It pauses
+ * when the app goes to the background and when it unmounts; the thread pauses it when the
+ * screen loses focus (`ChatThreadScreen focused`), since a tab switch keeps the screen mounted.
  */
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { ActivityIndicator, Pressable, View, useWindowDimensions } from "react-native";
+import { ActivityIndicator, AppState, Pressable, View, useWindowDimensions } from "react-native";
 import { NativeIcon, NativeImage, NativeText } from "@marktiderman/genesis-ui-native/components";
 import { useThemeRoles } from "@marktiderman/genesis-ui-native/hooks";
 import { formatDuration, nextPlaybackRate } from "../core/media";
@@ -267,10 +269,18 @@ function ActiveVideo({
   const [muted, setMuted] = useState(false);
   const [rate, setRate] = useState(1);
   const ended = useRef(false);
+  // Full screen on Android is another activity: the app reads as backgrounded while it shows.
+  const fullScreenOpen = useRef(false);
+  const setUp = useRef(false);
 
   useEffect(() => {
-    claimPlayback(id, () => player.pause());
-    setPlayingId(id, true);
+    // The first time, the player was just told to play; set up again (a remount that keeps the
+    // player), it says for itself whether it plays.
+    const now = setUp.current ? Boolean(player.playing) : true;
+    setUp.current = true;
+    setPlaying(now);
+    setPlayingId(id, now);
+    if (now) claimPlayback(id, () => player.pause());
     const subs = [
       player.addListener("playingChange", ((payload: { isPlaying: boolean }) => {
         setPlaying(payload.isPlaying);
@@ -290,8 +300,24 @@ function ActiveVideo({
         if (payload.status === "error") latestBroken.current();
       }) as (payload: never) => void),
     ];
+    // Not on in the background: a video plays only while you can see it (full screen aside).
+    const appSub = AppState?.addEventListener?.("change", (next: string) => {
+      if (next === "background" && !fullScreenOpen.current) {
+        try {
+          player.pause();
+        } catch {
+          // A player already released has nothing to pause.
+        }
+      }
+    });
     return () => {
       subs.forEach((s) => s.remove());
+      appSub?.remove?.();
+      try {
+        player.pause();
+      } catch {
+        // Released with the view: nothing left to pause.
+      }
       setPlayingId(id, false);
       releasePlayback(id);
     };
@@ -320,9 +346,23 @@ function ActiveVideo({
   };
   handles.current = { toggle, fullScreen, mute: toggleMute, rate: cycleRate };
   const { VideoView } = video;
-    return (
+  return (
     <View testID={`${testID}-active`} style={style}>
-      <VideoView ref={viewRef} player={player} nativeControls={false} contentFit="cover" allowsPictureInPicture={false} style={{ width: "100%", height: "100%" }} testID={`${testID}-view`} />
+      <VideoView
+        ref={viewRef}
+        player={player}
+        nativeControls={false}
+        contentFit="cover"
+        allowsPictureInPicture={false}
+        onFullscreenEnter={() => {
+          fullScreenOpen.current = true;
+        }}
+        onFullscreenExit={() => {
+          fullScreenOpen.current = false;
+        }}
+        style={{ width: "100%", height: "100%" }}
+        testID={`${testID}-view`}
+      />
       <Pressable
         testID={`${testID}-surface`}
         accessibilityRole="button"

package/src/native/video-recorder.tsx

@@ -8,7 +8,7 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AccessibilityInfo, Linking, Modal, Pressable, View } from "react-native";
-import { SafeAreaView } from "react-native-safe-area-context";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { NativeButton, NativeIcon, NativeText } from "@marktiderman/genesis-ui-native/components";
 import { useThemeRoles } from "@marktiderman/genesis-ui-native/hooks";
 import { formatDuration } from "../core/media";
@@ -49,6 +49,9 @@ export function ChatVideoRecorder(props: ChatVideoRecorderProps) {
 
 function RecorderBody({ camera, onClose, limitMs, onStart, onTick, onRecorded, now = Date.now, testID }: ChatVideoRecorderProps & { camera: ExpoCameraLike; testID: string }) {
   const { copy, modules } = useChatNative();
+  // The app's insets, as padding: a SafeAreaView inside the full-screen Modal measured none on
+  // iOS 27, which put Close and the timer under the status bar (the photo viewer does the same).
+  const insets = useSafeAreaInsets();
   const colors = useThemeRoles();
   const [state, setState] = useState<VideoRecorderState>(() => initialVideoRecorder());
   const stateRef = useRef(state);
@@ -171,7 +174,7 @@ function RecorderBody({ camera, onClose, limitMs, onStart, onTick, onRecorded, n
           onMountError={() => dispatch({ type: "camera-failed" })}
         />
       ) : null}
-      <SafeAreaView edges={["top", "bottom", "left", "right"]} style={{ flex: 1, justifyContent: "space-between" }}>
+      <View style={{ flex: 1, justifyContent: "space-between", paddingTop: insets.top, paddingBottom: insets.bottom, paddingLeft: insets.left, paddingRight: insets.right }}>
         <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 8, paddingTop: 4 }}>
           <Pressable
             testID={`${testID}-close`}
@@ -265,7 +268,7 @@ function RecorderBody({ camera, onClose, limitMs, onStart, onTick, onRecorded, n
             </NativeText>
           ) : null}
         </View>
-      </SafeAreaView>
+      </View>
     </View>
   );
 }

package/src/native/voice-player.tsx

@@ -82,6 +82,24 @@ export function cycleVoiceNoteRate(id: string): boolean {
   return Boolean(c);
 }
 
+/**
+ * Pauses the voice note or video playing, if any; with `ids` (or a test of an id), only when it
+ * is one of them (a screen's own attachments). For a screen losing focus: a tab switch keeps it mounted, so its
+ * player would play on. Returns whether one was paused.
+ */
+export function pauseChatPlayback(ids?: Iterable<string> | ((id: string) => boolean)): boolean {
+  if (!active) return false;
+  if (typeof ids === "function" ? !ids(active.id) : ids && !new Set(ids).has(active.id)) return false;
+  const { id, pause } = active;
+  try {
+    pause();
+  } catch {
+    // A player already gone has nothing to pause.
+  }
+  releasePlayback(id);
+  return true;
+}
+
 /** The playing voice note's id, for tests. */
 export function activePlaybackId(): string | null {
   return active?.id ?? null;

package/src/react/index.tsx

@@ -8,7 +8,16 @@
 import { useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import type { ChatClient, ConversationChannel, MessagePage } from "../core/client";
-import { createOutbox, type LocalFile, type Outbox, type OutboxStore, type QueuedMessage } from "../core/outbox";
+import {
+  createOutbox,
+  type HostedUpload,
+  type LocalFile,
+  type Outbox,
+  type OutboxStore,
+  type QueuedMessage,
+  type StorageUpload,
+} from "../core/outbox";
+import { sendBytes } from "../core/transfer";
 import { currentActivity, firstUnreadId, mergeThread, throttle, upsertMessages, type ThreadItem } from "../core/thread";
 import { attachmentKindFor, randomId } from "../core/media";
 import type {
@@ -76,20 +85,55 @@ export function belongsTo(key: readonly unknown[], m: ChatMessage): boolean {
 }
 
 /**
- * Hosted video uploads (Mux direct uploads): your server makes an upload and returns its URL;
- * the renderer PUTs the recording there and sends `{ kind: "video", provider: "mux", providerId,
- * status: "pending" }`. Without it, videos go to storage as files.
+ * Hosted video uploads (Mux direct uploads): your server makes an upload and returns its URL
+ * (`createVideoUploadHandler` in /server). A video the composer marks `hosted` is sent through
+ * the outbox at once, in order, with `{ kind: "video", provider, providerId, status: "pending" }`,
+ * while its bytes are PUT to that URL (see `hostedUploadFrom`). Without it, videos go to storage
+ * as files.
  */
 export interface ChatVideoUpload {
   create(conversationId: string): Promise<{ url: string; providerId: string; provider: "mux" }>;
 }
 
+/**
+ * The outbox's `hostedUpload` from a `ChatVideoUpload`: mints the upload (or, resuming, reuses
+ * the one minted before), resolves at once with its id, and PUTs the whole file to its URL in
+ * the background (XMLHttpRequest where there is one, for progress). A native file URI is read
+ * with `readFile`. Native apps with chunked, resumable uploads pass their own `hostedUpload`.
+ */
+export function hostedUploadFrom(
+  videoUpload: ChatVideoUpload,
+  options: { readFile?: (uri: string) => Promise<Blob | ArrayBuffer>; fetch?: typeof fetch } = {},
+): HostedUpload {
+  return async (conversationId, file, { signal, onProgress, resume }) => {
+    const minted = resume?.url
+      ? { url: resume.url, providerId: resume.providerId, provider: resume.provider }
+      : await videoUpload.create(conversationId);
+    const done = (async () => {
+      const body =
+        typeof file.data === "string"
+          ? await (options.readFile ?? (() => Promise.reject(new Error("This file can't be read on this device"))))(file.data)
+          : file.data;
+      await sendBytes(minted.url, body, { method: "PUT", headers: { "Content-Type": file.contentType }, signal, onProgress, fetch: options.fetch });
+    })();
+    return { provider: minted.provider, providerId: minted.providerId, status: "pending", url: minted.url, done };
+  };
+}
+
+/** What a kind's `title`, `subtitle` and `action` are told besides the attachment. */
+export interface ChatCardContext {
+  /** The card is on a message you sent (your own check-in reads "Sent", not "Answer"). */
+  mine: boolean;
+}
+
 /** What an app attachment kind's card shows (a form, a check-in): plain data, drawn by each renderer. */
 export interface ChatAttachmentKind {
-  title(attachment: ChatAttachment): string;
-  subtitle?(attachment: ChatAttachment): string | null | undefined;
+  title(attachment: ChatAttachment, ctx?: ChatCardContext): string;
+  subtitle?(attachment: ChatAttachment, ctx?: ChatCardContext): string | null | undefined;
   /** The card's button: a link (`href`) or a handler (`onPress`). */
-  action?(attachment: ChatAttachment): { label: string; href?: string; onPress?: () => void } | null | undefined;
+  action?(attachment: ChatAttachment, ctx?: ChatCardContext): { label: string; href?: string; onPress?: () => void } | null | undefined;
+  /** What previews call it (the inbox's last message, "Check-in"); the title by default. */
+  label?: string;
 }
 
 interface ChatContextValue {
@@ -118,8 +162,17 @@ export interface ChatProviderProps {
   outboxStore?: OutboxStore;
   /** Reads a native file URI for upload. */
   readFile?: (uri: string) => Promise<Blob | ArrayBuffer>;
-  /** Replaces the plain upload (resumable uploads on native). `signal` aborts when the message is discarded or the outbox cleared. */
-  upload?: (conversationId: string, file: LocalFile, opts?: { signal?: AbortSignal }) => Promise<string>;
+  /**
+   * Replaces the plain upload (resumable uploads on native). `signal` aborts when the message is
+   * discarded or the outbox cleared; `onProgress(sent, total)` fills the pending bubble's bar.
+   */
+  upload?: StorageUpload;
+  /**
+   * Starts a hosted upload for files marked `hosted` (see HostedUpload): resolve with
+   * `{ provider, providerId, status: "pending", url?, done }` once the upload id exists. Default:
+   * `hostedUploadFrom(videoUpload)` when `videoUpload` is given.
+   */
+  hostedUpload?: HostedUpload;
   /** Makes client ids (default: a random UUID that works without crypto.randomUUID). */
   newId?: () => string;
   /** Keeps a byte file (a pasted image, a recording) across launches: write it, return a URI. */
@@ -148,6 +201,7 @@ export function ChatProvider({
   outboxStore,
   readFile,
   upload,
+  hostedUpload,
   newId,
   persistFile,
   releasePreview,
@@ -159,6 +213,10 @@ export function ChatProvider({
   const queryClient = useQueryClient();
   const [queue, setQueue] = useState<QueuedMessage[]>([]);
   const listeners = useRef(new Set<(s: ChatSignal) => void>());
+  // The outbox lives as long as the client and user, so it reads the app's functions here at call
+  // time: an inline `videoUpload.create` closing over a refreshed token keeps working.
+  const live = useRef({ readFile, upload, hostedUpload, videoUpload, persistFile });
+  live.current = { readFile, upload, hostedUpload, videoUpload, persistFile };
 
   const outbox = useMemo(
     () =>
@@ -166,10 +224,19 @@ export function ChatProvider({
         client,
         userId,
         store: outboxStore,
-        readFile,
-        upload,
+        readFile: readFile && ((uri) => (live.current.readFile ?? readFile)(uri)),
+        upload: upload && ((...args) => (live.current.upload ?? upload)(...args)),
+        hostedUpload:
+          hostedUpload || videoUpload
+            ? (...args) => {
+                const now = live.current;
+                const video = now.videoUpload ?? videoUpload;
+                const send = now.hostedUpload ?? (video ? hostedUploadFrom(video, { readFile: now.readFile ?? readFile }) : hostedUpload!);
+                return send(...args);
+              }
+            : undefined,
         newId,
-        persistFile,
+        persistFile: persistFile && ((file) => (live.current.persistFile ?? persistFile)(file)),
         releasePreview,
         onChange: setQueue,
         onSent: (message) => {
@@ -396,6 +463,20 @@ export function useConversation(conversationId: string | null | undefined, opts:
     if (shouldMark && latestSeq > 0) void markRead().catch(() => undefined);
   }, [shouldMark, latestSeq, markRead]);
 
+  const refetchConversation = useCallback(
+    () =>
+      Promise.all([
+        // The conversation and what hangs off it (topics, availability), never its message lists:
+        // a refetch would replace loaded history and merged live messages with one fresh page.
+        queryClient.refetchQueries({ queryKey: chatKeys.conversation(id), predicate: (q) => q.queryKey[3] !== "messages" }),
+        queryClient.refetchQueries({ queryKey: chatKeys.members(id) }),
+        queryClient.refetchQueries({ queryKey: chatKeys.role(id) }),
+        queryClient.refetchQueries({ queryKey: chatKeys.pins(id) }),
+        queryClient.refetchQueries({ queryKey: ["genesis-chat", "kind"] }),
+      ]).then(() => undefined),
+    [queryClient, id],
+  );
+
   const loadEarlier = useCallback(async () => {
     const first = list[0];
     if (!first || loadingEarlier) return;
@@ -466,7 +547,10 @@ export function useConversation(conversationId: string | null | undefined, opts:
     conversationLoading: conversation.isLoading,
     /** Your role couldn't be loaded (offline): offer `refetchAccess`, don't say "can't post". */
     accessError: access.error ?? null,
-    refetchAccess: access.refetch,
+    /** Retries everything this conversation loads (role, members, the conversation, topics, availability, pins), not only access. */
+    refetchAccess: refetchConversation,
+    /** Same as refetchAccess: every per-conversation lookup again, for a Retry after being offline. */
+    refetchConversation,
     /** The kind's rules (max members, threads, who posts). */
     kind: kindRules.data ?? null,
     /** May you pin here: owners and admins, or anyone in a two-person conversation. */
@@ -613,11 +697,12 @@ export function useTopics(conversationId: string | null | undefined) {
 
 /**
  * Your scheduled messages (in one conversation, or all), soonest first, with `schedule` and
- * `cancel`. `schedule` uploads byte files first (`LocalFile.data` a Blob or ArrayBuffer; a
- * native URI goes through the provider's `readFile`), then schedules them with the message.
+ * `cancel` (which also removes one that failed). `schedule` uploads its files to storage first,
+ * the way `send` does (the provider's `upload` hook, or a native URI read through `readFile`),
+ * then schedules them with the message. A file marked `hosted` goes to storage too.
  */
 export function useScheduled(conversationId?: string | null, opts: { enabled?: boolean } = {}) {
-  const { client, userId } = useChat();
+  const { client, outbox } = useChat();
   const queryClient = useQueryClient();
   const query = useQuery({
     queryKey: chatKeys.scheduled(conversationId),
@@ -630,15 +715,14 @@ export function useScheduled(conversationId?: string | null, opts: { enabled?: b
     async (input: Omit<ScheduleInput, "clientId"> & { clientId?: string }, files: LocalFile[] = []) => {
       const attachments = [...(input.attachments ?? [])];
       for (const f of files) {
-        if (typeof f.data === "string") throw new Error("Scheduled files must be bytes (a Blob or ArrayBuffer)");
-        const path = await client.upload(input.conversationId, userId, f.data, { name: f.name, contentType: f.contentType });
+        const path = await outbox.uploadFile(input.conversationId, f);
         attachments.push({ ...f.meta, kind: f.meta?.kind ?? attachmentKindFor(f.contentType), path, name: f.meta?.name ?? f.name, mime: f.contentType });
       }
       const id = await client.schedule({ ...input, clientId: input.clientId ?? randomId(), attachments });
       await refresh();
       return id;
     },
-    [client, refresh, userId],
+    [client, outbox, refresh],
   );
   const cancel = useCallback(
     async (id: string) => {

package/src/react/previews.ts

@@ -0,0 +1,51 @@
+/**
+ * @feat:chat
+ * One-line previews of a message (the inbox, the long-press sheet) where an app attachment kind
+ * reads as its `label`, else its title ("Check-in"), not "Attachment". No React or DOM: web and
+ * native both draw from it.
+ */
+import { previewText } from "../core/thread";
+import type { ChatAttachment, ChatMessage } from "../core/types";
+import type { ChatAttachmentKind, ChatCardContext } from "./index";
+
+/** Calls a kind's `title`, `subtitle` or `action` with the card context. */
+export const callAttachmentKind = <K extends "title" | "subtitle" | "action">(kind: ChatAttachmentKind | undefined, key: K, a: ChatAttachment, ctx: ChatCardContext) =>
+  (kind?.[key] as ((this: ChatAttachmentKind, a: ChatAttachment, ctx: ChatCardContext) => unknown) | undefined)?.call(kind!, a, ctx) as
+    | ReturnType<NonNullable<ChatAttachmentKind[K]>>
+    | undefined;
+
+/** A card's title (the kind's, else the file's name, else the kind); an app kind that throws reads as its name. */
+export function cardTitle(kind: ChatAttachmentKind | undefined, a: ChatAttachment, ctx: ChatCardContext = { mine: false }): string {
+  try {
+    return callAttachmentKind(kind, "title", a, ctx) || a.name || a.kind;
+  } catch {
+    return a.name || a.kind;
+  }
+}
+
+/** An attachment with only its kind, for a preview that knows no more (the inbox's last message). */
+function bareAttachment(kind: string): ChatAttachment {
+  return { id: "", messageId: "", position: 0, kind, ref: {}, provider: "none", path: null, providerId: null, playbackId: null, url: null, status: "ready", name: null, mime: null, bytes: null, width: null, height: null, durationMs: null, waveform: null, posterPath: null, thumbhash: null, transcript: null, transcriptStatus: null };
+}
+
+/**
+ * A message's one-line preview: its text, else what it carries, where an app kind reads as its
+ * title ("Check-in") instead of "Attachment". `attachment` is the kind alone (the inbox) or the
+ * attachment itself.
+ */
+export function attachmentPreview(body: string, attachment: string | ChatAttachment | null | undefined, kinds: Record<string, ChatAttachmentKind> | undefined, deleted = false): string {
+  const kind = typeof attachment === "string" ? attachment : attachment?.kind;
+  const text = previewText(body, kind, deleted);
+  // Text that reads as something (not only markdown marks) is the preview, as previewText has it.
+  if (deleted || !kind || !kinds || !Object.prototype.hasOwnProperty.call(kinds, kind) || previewText(body, null)) return text;
+  const a = typeof attachment === "string" ? bareAttachment(attachment) : attachment!;
+  const k = kinds[kind];
+  const title = typeof k?.label === "string" && k.label.trim() ? k.label.trim() : cardTitle(k, a);
+  return title && title !== kind ? title : text;
+}
+
+/** The long-press sheet's caption for a message. */
+export function messagePreview(message: ChatMessage, kinds: Record<string, ChatAttachmentKind> | undefined): string {
+  return attachmentPreview(message.body, message.attachments[0], kinds, Boolean(message.deletedAt));
+}
+