@adatechnology/conversations-ui 0.6.1 → 0.8.0

package/src/participant/ParticipantThreadAvatarSequence.test.tsx

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { buildConversation, buildMessage } from './participantFixtures.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import type { ParticipantTimelineItem } from './participantMessages'
+import { ParticipantThread } from './ParticipantThread'
+
+function ana(id: string, createdAt: string): ParticipantTimelineItem {
+  return { kind: 'server', message: buildMessage({ id, authorName: 'Ana Souza', createdAt }) }
+}
+
+function mine(id: string, createdAt: string): ParticipantTimelineItem {
+  return { kind: 'server', message: buildMessage({ id, direction: 'inbound', authorName: 'Ana Souza', createdAt }) }
+}
+
+function render(items: readonly ParticipantTimelineItem[]): string {
+  return renderToStaticMarkup(
+    <ParticipantThread
+      conversation={buildConversation({ subjectId: '1' })}
+      items={items}
+      hasMore={false}
+      labels={DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS}
+      resolveAttachmentUrl={async () => 'https://files.example/a'}
+      draft={{ value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined }}
+      onSend={() => undefined}
+      status="ready"
+      refresh={() => undefined}
+      scroll={{ ref: { current: null }, onScroll: () => undefined }}
+      newMessagesCount={0}
+      isSending={false}
+      avatars="initials"
+    />,
+  )
+}
+
+function countAvatars(markup: string): number {
+  return markup.match(/class="cv-p-avatar" aria-hidden="true">AS</g)?.length ?? 0
+}
+
+describe('avatar sequence in the thread', () => {
+  it('shows one avatar for consecutive messages of the same author', () => {
+    const markup = render([ana('a', '2026-10-01T10:00:00.000Z'), ana('b', '2026-10-01T10:01:00.000Z')])
+    expect(countAvatars(markup)).toBe(1)
+  })
+
+  it('shows the avatar again after an own message of the same author in between', () => {
+    const markup = render([
+      ana('a', '2026-10-01T10:00:00.000Z'),
+      mine('b', '2026-10-01T10:01:00.000Z'),
+      ana('c', '2026-10-01T10:02:00.000Z'),
+    ])
+    expect(countAvatars(markup)).toBe(2)
+  })
+
+  it('shows the avatar again after the day separator', () => {
+    const markup = render([ana('a', '2026-10-01T10:00:00.000Z'), ana('b', '2026-10-03T10:00:00.000Z')])
+    expect(markup).toMatch(/role="separator" aria-label="[^"]+"/)
+    expect(countAvatars(markup)).toBe(2)
+  })
+
+  it('never draws the avatar on own messages', () => {
+    expect(render([mine('a', '2026-10-01T10:00:00.000Z')])).not.toContain('cv-p-avatar')
+  })
+})

package/src/participant/ParticipantThreadHeader.test.tsx

@@ -0,0 +1,181 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { splitBlocks } from '../cssBlocks.test-helper'
+import { buildConversation } from './participantFixtures.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { ParticipantProtocolBadgeView } from './ParticipantProtocolBadge'
+import { ParticipantThreadHeader, type ParticipantThreadHeaderProps } from './ParticipantThreadHeader'
+
+const LABELS = DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS
+const GROUPS = [{ subjectType: 'invoice', label: 'Invoices' }]
+
+function render(overrides: Partial<ParticipantThreadHeaderProps> = {}): string {
+  return renderToStaticMarkup(
+    <ParticipantThreadHeader
+      conversation={buildConversation({ subjectId: '1', subjectLabel: 'Item 4521' })}
+      labels={LABELS}
+      {...overrides}
+    />,
+  )
+}
+
+function metaOf(markup: string): string {
+  const start = markup.indexOf('class="cv-p-thread__meta"')
+  const end = markup.indexOf('</header>', start)
+  return start === -1 ? '' : markup.slice(start, end)
+}
+
+describe('thread header structure', () => {
+  const conversation = buildConversation({
+    subjectId: '1',
+    subjectLabel: 'Item 4521',
+    protocol: '261009-K7M2',
+    channels: ['app', 'whatsapp'],
+  })
+
+  it('draws the eyebrow only when the subject type has a group', () => {
+    expect(render({ subjectGroups: GROUPS })).toContain('<p class="cv-p-thread__eyebrow">Invoices</p>')
+    expect(render()).not.toContain('cv-p-thread__eyebrow')
+    expect(render({ subjectGroups: [{ subjectType: 'other', label: 'Other' }] })).not.toContain('cv-p-thread__eyebrow')
+  })
+
+  it('draws the title, clickable only with onOpenSubject', () => {
+    expect(render()).toContain('Item 4521')
+    expect(render()).not.toContain('cv-p-thread__title-button')
+    expect(render({ onOpenSubject: () => undefined })).toContain('cv-p-thread__title-button')
+  })
+
+  it('keeps protocol, copy button and channel badges in one single meta line', () => {
+    const markup = render({ conversation })
+    expect(markup.match(/cv-p-thread__meta"/g)?.length).toBe(1)
+    const meta = metaOf(markup)
+    expect(meta).toContain('261009-K7M2')
+    expect(meta).toContain('cv-p-protocol__copy')
+    expect(meta).toContain('cv-p-channel--app')
+    expect(meta).toContain('cv-p-channel--whatsapp')
+    expect(markup.match(/cv-p-channels/g)?.length).toBe(1)
+    expect(markup.indexOf('cv-p-channels')).toBeGreaterThan(markup.indexOf('cv-p-thread__meta'))
+  })
+
+  it('does not draw a separate channels row', () => {
+    const markup = render({ conversation })
+    expect(markup).not.toContain('<ul')
+    expect(markup).toContain('<span class="cv-p-channels">')
+  })
+
+  it('draws the meta line with channels only when there is no protocol', () => {
+    const markup = render({ conversation: buildConversation({ subjectId: '1', channels: ['app'] }) })
+    expect(metaOf(markup)).toContain('cv-p-channel--app')
+    expect(markup).not.toContain('cv-p-protocol')
+  })
+
+  it('draws no meta line without protocol and without channels', () => {
+    const markup = render()
+    expect(markup).not.toContain('cv-p-thread__meta')
+    expect(markup).not.toContain('cv-p-protocol')
+    expect(markup).not.toContain('cv-p-channels')
+  })
+
+  it('draws the back button only with onBack', () => {
+    expect(render()).not.toContain('cv-p-thread__back')
+    expect(render({ onBack: () => undefined })).toContain('cv-p-thread__back')
+  })
+})
+
+describe('copy button as an icon', () => {
+  const view = (isCopied: boolean) =>
+    renderToStaticMarkup(
+      <ParticipantProtocolBadgeView
+        protocol="261009-K7M2"
+        labels={LABELS}
+        copyState={{ copyCount: isCopied ? 1 : 0, isCopied }}
+        onCopy={() => undefined}
+      />,
+    )
+
+  it('has the full accessible name and no visible text', () => {
+    const markup = view(false)
+    expect(markup).toContain('aria-label="Copy protocol 261009-K7M2"')
+    const button = markup.slice(markup.indexOf('<button'), markup.indexOf('</button>'))
+    expect(button).toContain('<svg')
+    expect(button.replace(/<[^>]+>/g, '')).toBe('')
+    expect(markup.replace(/aria-label="[^"]*"/g, '')).not.toContain('Copy protocol')
+  })
+
+  it('shows the short confirmation next to the icon while copied', () => {
+    const markup = view(true)
+    const button = markup.slice(markup.indexOf('<button'), markup.indexOf('</button>'))
+    expect(button).toContain(`<span class="cv-p-protocol__copied" aria-hidden="true">${LABELS.protocolCopied}</span>`)
+    expect(markup).toMatch(/aria-live="polite"><span>Protocol copied<\/span><\/div>/)
+  })
+
+  it('keeps the live region outside the protocol block', () => {
+    const markup = view(true)
+    const block = markup.slice(markup.indexOf('cv-p-protocol--header'), markup.indexOf('</button>'))
+    expect(block).not.toContain('aria-live')
+  })
+})
+
+const CSS = readFileSync(join(import.meta.dir, '..', 'styles.css'), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+
+function declarationsOf(selector: string): Map<string, string> {
+  const declarations = new Map<string, string>()
+  for (const { prelude, body } of splitBlocks(CSS)) {
+    if (body === undefined || prelude.startsWith('@')) continue
+    if (!prelude.split(',').some((entry) => entry.trim() === selector)) continue
+    for (const declaration of body.split(';')) {
+      const separator = declaration.indexOf(':')
+      if (separator === -1) continue
+      declarations.set(declaration.slice(0, separator).trim().toLowerCase(), declaration.slice(separator + 1).trim())
+    }
+  }
+  return declarations
+}
+
+function toRem(value: string | undefined): number {
+  const match = /^(\d*\.?\d+)rem$/.exec(value ?? '')
+  return match ? Number(match[1]) : 0
+}
+
+describe('thread header CSS', () => {
+  it('lays the meta line out as a wrapping flex row', () => {
+    const meta = declarationsOf('.cv-p-thread__meta')
+    expect(meta.get('display')).toBe('flex')
+    expect(meta.get('flex-wrap')).toBe('wrap')
+  })
+
+  it('gives the copy button a wide touch area without inflating the line', () => {
+    const copy = declarationsOf('.cv-p-protocol__copy')
+    expect(toRem(copy.get('min-width'))).toBeGreaterThanOrEqual(2.75)
+    expect(toRem(copy.get('min-height'))).toBeGreaterThanOrEqual(2)
+    expect(copy.get('margin')).toMatch(/^-/)
+  })
+
+  it('sets a floor of 4rem on the header but never a fixed or maximum height', () => {
+    const header = declarationsOf('.cv-p-thread__header')
+    for (const property of ['height', 'max-height']) expect(header.has(property)).toBe(false)
+    expect(toRem(header.get('min-height'))).toBeGreaterThanOrEqual(4)
+  })
+
+  it('clamps the title to one line', () => {
+    expect(declarationsOf('.cv-p-thread__title-text').get('-webkit-line-clamp')).toBe('1')
+  })
+
+  it('draws the eyebrow like the list row kind label', () => {
+    const eyebrow = declarationsOf('.cv-p-thread__eyebrow')
+    expect(eyebrow.get('text-transform')).toBe('uppercase')
+    expect(eyebrow.get('font')).toContain('monospace')
+  })
+})
+
+describe('avatar CSS', () => {
+  it('draws a 2rem box that follows the host radius token', () => {
+    const avatar = declarationsOf('.cv-p-avatar')
+    expect(avatar.get('width')).toBe('2rem')
+    expect(avatar.get('height')).toBe('2rem')
+    expect(avatar.get('border-radius')).toBe('var(--cv-p-i-radius)')
+  })
+})

package/src/participant/ParticipantThreadHeader.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode } from 'react'
+
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import { ParticipantBackButton } from './ParticipantBackButton'
+import { ParticipantChannelBadges } from './ParticipantChannelBadges'
+import { resolveParticipantChannels } from './participantChannels'
+import { ParticipantConversationAvatar } from './ParticipantConversationAvatar'
+import { ParticipantProtocolBadge } from './ParticipantProtocolBadge'
+import type { ParticipantSubjectGroup, ParticipantSubjectIconRenderer } from './participant.types'
+import type { ParticipantConversationsLabels } from './participantLabels'
+import { resolveConversationIcon } from './participantSubjectIcon'
+
+export type ParticipantThreadHeaderProps = {
+  readonly conversation: ParticipantConversationSummary
+  readonly labels: ParticipantConversationsLabels
+  readonly subjectGroups?: readonly ParticipantSubjectGroup[]
+  readonly renderSubjectIcon?: ParticipantSubjectIconRenderer
+  readonly onBack?: () => void
+  readonly onOpenSubject?: (subject: ParticipantSubjectRef) => void
+  /** Short line under the title, written by the host (for example who is on the other side). */
+  readonly counterpartLabel?: string
+  /** Host slot at the end of the bar; the package knows none of these actions. */
+  readonly actions?: ReactNode
+}
+
+type TitleProps = Pick<ParticipantThreadHeaderProps, 'conversation' | 'labels' | 'onOpenSubject'>
+
+function Title({ conversation, labels, onOpenSubject }: TitleProps) {
+  const { subjectType, subjectId, subjectLabel } = conversation
+  return (
+    <h2 className="cv-p-thread__title">
+      {onOpenSubject ? (
+        <button
+          type="button"
+          className="cv-p-thread__title-button"
+          aria-label={`${labels.openSubject}: ${subjectLabel}`}
+          onClick={() => onOpenSubject({ subjectType, subjectId })}
+        >
+          <span className="cv-p-thread__title-text">{subjectLabel}</span>
+        </button>
+      ) : (
+        <span className="cv-p-thread__title-text">{subjectLabel}</span>
+      )}
+    </h2>
+  )
+}
+
+export function ParticipantThreadHeader({
+  conversation,
+  labels,
+  subjectGroups,
+  renderSubjectIcon,
+  onBack,
+  onOpenSubject,
+  counterpartLabel,
+  actions,
+}: ParticipantThreadHeaderProps) {
+  const group = subjectGroups?.find((candidate) => candidate.subjectType === conversation.subjectType)
+  const icon = resolveConversationIcon({ conversation, group, renderSubjectIcon })
+  const hasChannels = resolveParticipantChannels(conversation.channels).length > 0
+
+  return (
+    <header className="cv-p-thread__header">
+      {onBack ? <ParticipantBackButton label={labels.back} onBack={onBack} /> : null}
+      {icon !== undefined ? <ParticipantConversationAvatar icon={icon} /> : null}
+      <div className="cv-p-thread__heading">
+        {icon === undefined && group ? <p className="cv-p-thread__eyebrow">{group.label}</p> : null}
+        <Title conversation={conversation} labels={labels} onOpenSubject={onOpenSubject} />
+        {counterpartLabel ? <p className="cv-p-thread__counterpart">{counterpartLabel}</p> : null}
+        {conversation.protocol || hasChannels ? (
+          <div className="cv-p-thread__meta">
+            {conversation.protocol ? (
+              <ParticipantProtocolBadge protocol={conversation.protocol} labels={labels} />
+            ) : null}
+            <ParticipantChannelBadges channels={conversation.channels} labels={labels} variant="inline" iconSize={16} />
+          </div>
+        ) : null}
+      </div>
+      {actions ? <div className="cv-p-thread__actions">{actions}</div> : null}
+    </header>
+  )
+}

package/src/participant/ParticipantThreadScreen.tsx

@@ -1,18 +1,15 @@
-import { useEffect, useMemo, useState, type Dispatch, type MutableRefObject } from 'react'
+import { useEffect, useState, type Dispatch, type MutableRefObject } from 'react'
 
 import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
 
+import { ParticipantBackButton } from './ParticipantBackButton'
 import { ParticipantThread } from './ParticipantThread'
 import type { ParticipantConversationsScreenProps } from './ParticipantConversationsScreen'
-import { bindAttachmentUrlResolver } from './bindAttachmentUrlResolver'
 import type { ParticipantDrafts } from './participantDrafts'
 import type { ParticipantConversationsLabels } from './participantLabels'
 import type { ParticipantConversationsApi } from './participantApi.types'
-import { findFailedEntry, hasSendingEntry } from './participantSendController'
 import type { ParticipantSendStates, ParticipantSendStatesAction } from './participantSendStates'
-import { useParticipantDraft } from './useParticipantDraft'
-import { useParticipantConversationView } from './useParticipantConversationView'
-import { useParticipantThreadScroll } from './useParticipantThreadScroll'
+import { useParticipantThreadController } from './useParticipantThreadController'
 
 export type ParticipantThreadScreenProps = Omit<ParticipantConversationsScreenProps, 'selected' | 'labels'> & {
   readonly selected: ParticipantSubjectRef
@@ -24,9 +21,15 @@ export type ParticipantThreadScreenProps = Omit<ParticipantConversationsScreenPr
   readonly dispatchSendStates: Dispatch<ParticipantSendStatesAction>
 }
 
-type OpenedState = { readonly status: 'idle' | 'loading' | 'missing' } | { readonly status: 'found'; readonly conversation: ParticipantConversationSummary }
+type OpenedState =
+  | { readonly status: 'idle' | 'loading' | 'missing' }
+  | { readonly status: 'found'; readonly conversation: ParticipantConversationSummary }
 
-function useOpenedConversation(api: ParticipantConversationsApi, subject: ParticipantSubjectRef, isNeeded: boolean): OpenedState {
+function useOpenedConversation(
+  api: ParticipantConversationsApi,
+  subject: ParticipantSubjectRef,
+  isNeeded: boolean,
+): OpenedState {
   const [opened, setOpened] = useState<OpenedState>({ status: 'idle' })
   const { subjectType, subjectId } = subject
   const canOpen = api.openConversation !== undefined
@@ -47,16 +50,17 @@ function useOpenedConversation(api: ParticipantConversationsApi, subject: Partic
   return opened
 }
 
-function NotFound({ labels, onBack }: { readonly labels: ParticipantConversationsLabels; readonly onBack?: () => void }) {
+function NotFound({
+  labels,
+  onBack,
+}: {
+  readonly labels: ParticipantConversationsLabels
+  readonly onBack?: () => void
+}) {
   return (
     <div className="cv-p cv-p-thread">
       <header className="cv-p-thread__header">
-        {onBack ? (
-          <button type="button" className="cv-p-button cv-p-thread__back" onClick={onBack}>
-            <span aria-hidden="true">‹</span>
-            <span className="cv-p-sr-only">{labels.back}</span>
-          </button>
-        ) : null}
+        {onBack ? <ParticipantBackButton label={labels.back} onBack={onBack} /> : null}
       </header>
       <p className="cv-p-empty">{labels.notFound}</p>
     </div>
@@ -74,62 +78,32 @@ export function ParticipantThreadScreen(props: ParticipantThreadScreenProps) {
   if (conversation) return <LoadedThread {...props} conversation={conversation} />
   const isResolving = opened.status === 'loading' || (api.openConversation !== undefined && opened.status === 'idle')
   const isListLoading = inbox.status === 'idle' || inbox.status === 'loading'
-  if (isResolving || (api.openConversation === undefined && isListLoading)) return <div className="cv-p cv-p-thread" aria-busy="true" />
+  if (isResolving || (api.openConversation === undefined && isListLoading))
+    return <div className="cv-p cv-p-thread" aria-busy="true" />
   return <NotFound labels={labels} onBack={props.onBack} />
 }
 
 type LoadedThreadProps = ParticipantThreadScreenProps & { readonly conversation: ParticipantConversationSummary }
 
 function LoadedThread(props: LoadedThreadProps) {
-  const { api, selected, conversation, draftsRef, inbox } = props
-  const { draft, setText, setFiles, takeForSend, restoreFromEntry } = useParticipantDraft(draftsRef, selected)
-  const { thread, items, sendEntries, dispatchSend } = useParticipantConversationView({
+  const core = useParticipantThreadController({
     ...props,
-    subject: selected,
-    onMarkedRead: inbox.markSubjectRead,
+    subject: props.selected,
+    onMarkedRead: props.inbox.markSubjectRead,
   })
-  const resolveAttachmentUrl = useMemo(() => bindAttachmentUrlResolver(api), [api])
-  const { scroll, newMessagesCount } = useParticipantThreadScroll(items)
-
-  function handleSend(): void {
-    const content = takeForSend()
-    if (content) void thread.send(content)
-  }
-
-  function handleEdit(clientMessageId: string): void {
-    const entry = findFailedEntry(sendEntries, clientMessageId)
-    if (!entry) return
-    restoreFromEntry(entry)
-    dispatchSend({ type: 'discarded', clientMessageId })
-  }
 
   return (
     <ParticipantThread
-      conversation={conversation}
-      items={items}
-      hasMore={thread.hasMore}
-      labels={props.labels}
-      resolveAttachmentUrl={resolveAttachmentUrl}
-      draft={{ value: draft.text, onChange: setText, files: draft.files, onFilesChange: setFiles }}
-      onSend={handleSend}
-      status={thread.status}
-      refresh={() => void thread.refresh()}
-      scroll={scroll}
-      newMessagesCount={newMessagesCount}
-      isSending={hasSendingEntry(sendEntries)}
-      channel={props.channel}
-      locale={props.locale}
+      {...core}
       onBack={props.onBack}
       onOpenSubject={props.onOpenSubject}
-      onLoadOlder={() => void thread.loadOlder()}
-      pendingActions={{
-        retryLocal: (clientMessageId) => void thread.retry(clientMessageId),
-        discardLocal: (clientMessageId) => dispatchSend({ type: 'discarded', clientMessageId }),
-        editLocal: handleEdit,
-        ...(props.onRetryPending ? { retryHost: props.onRetryPending } : {}),
-      }}
       quickReplies={props.quickReplies}
       renderSubjectCard={props.renderSubjectCard}
+      subjectGroups={props.subjectGroups}
+      renderSubjectIcon={props.renderSubjectIcon}
+      avatars={props.avatars}
+      renderAuthorAvatar={props.renderAuthorAvatar}
+      tail={props.tail}
     />
   )
 }

package/src/participant/ParticipantTimeline.tsx

@@ -0,0 +1,106 @@
+import type { ReactNode } from 'react'
+
+import { channelCapabilityFor } from '../channelCapability'
+import type { ConversationChannel } from '../conversationChannel'
+import { isSameDay } from '../lib/format'
+import type { ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
+import { ParticipantAuthorAvatar, type ParticipantAuthorAvatarRenderer } from './ParticipantAuthorAvatar'
+import { ParticipantDayDivider } from './ParticipantDayDivider'
+import { ParticipantMessageBubble } from './ParticipantMessageBubble'
+import { shouldShowAvatar, type ParticipantAvatarAuthor } from './participantAvatar'
+import {
+  bindPendingActions,
+  resolveParticipantBubbleActions,
+  type ParticipantPendingActions,
+} from './participantBubbleActions'
+import type { ParticipantConversationsLabels } from './participantLabels'
+import { isOwnMessage, type ParticipantTimelineItem } from './participantMessages'
+import type { ParticipantPerspective } from './participantPerspective'
+
+export type ParticipantTimelineProps = {
+  readonly items: readonly ParticipantTimelineItem[]
+  readonly labels: ParticipantConversationsLabels
+  readonly resolveAttachmentUrl: ResolveParticipantAttachmentUrl
+  readonly channel?: ConversationChannel
+  readonly locale?: string
+  readonly pendingActions?: ParticipantPendingActions
+  readonly avatars?: 'initials'
+  readonly renderAuthorAvatar?: ParticipantAuthorAvatarRenderer
+  readonly tail?: boolean
+  readonly perspective?: ParticipantPerspective
+}
+
+function createdAtOf(item: ParticipantTimelineItem): string {
+  return item.kind === 'server' ? item.message.createdAt : item.pending.createdAt
+}
+
+function keyOf(item: ParticipantTimelineItem): string {
+  return item.kind === 'server' ? item.message.id : `pending:${item.pending.clientMessageId}`
+}
+
+type AuthorOfItem = { readonly isMine: boolean; readonly author: ParticipantAvatarAuthor }
+
+function authorOf(item: ParticipantTimelineItem, perspective?: ParticipantPerspective): AuthorOfItem {
+  if (item.kind === 'pending') return { isMine: true, author: null }
+  return { isMine: isOwnMessage(item.message, perspective), author: item.message.authorName ?? null }
+}
+
+function resolveActions(item: ParticipantTimelineItem, pendingActions?: ParticipantPendingActions) {
+  if (!pendingActions || item.kind === 'server') return {}
+  return resolveParticipantBubbleActions(item, bindPendingActions(pendingActions, item.pending.clientMessageId))
+}
+
+type AvatarSlotParams = {
+  readonly isEnabled: boolean
+  readonly isMine: boolean
+  readonly showAvatar: boolean
+  readonly author: ParticipantAvatarAuthor
+  readonly render?: ParticipantAuthorAvatarRenderer
+}
+
+function resolveAvatarSlot({ isEnabled, isMine, showAvatar, author, render }: AvatarSlotParams): ReactNode {
+  if (!isEnabled || isMine) return undefined
+  return showAvatar ? <ParticipantAuthorAvatar name={author} render={render} /> : null
+}
+
+export function ParticipantTimeline(props: ParticipantTimelineProps) {
+  const { items, labels, locale, resolveAttachmentUrl, pendingActions } = props
+  const confirmsRead = channelCapabilityFor(props.channel ?? 'app').confirmsRead
+  const isAvatarEnabled = props.avatars === 'initials' || props.renderAuthorAvatar !== undefined
+  const nodes: ReactNode[] = []
+  let previousDay: Date | undefined
+  let previousAuthor: ParticipantAvatarAuthor | undefined
+
+  for (const item of items) {
+    const day = new Date(createdAtOf(item))
+    if (previousDay === undefined || !isSameDay(previousDay, day)) {
+      nodes.push(<ParticipantDayDivider key={`day:${keyOf(item)}`} day={day} locale={locale} />)
+      previousAuthor = undefined
+    }
+    previousDay = day
+    const { isMine, author } = authorOf(item, props.perspective)
+    const showAvatar = shouldShowAvatar({ previousAuthor, author, isMine })
+    previousAuthor = isMine ? undefined : author
+    const avatar = resolveAvatarSlot({
+      isEnabled: isAvatarEnabled,
+      isMine,
+      showAvatar,
+      author,
+      render: props.renderAuthorAvatar,
+    })
+    nodes.push(
+      <ParticipantMessageBubble
+        key={keyOf(item)}
+        item={item}
+        labels={labels}
+        confirmsRead={confirmsRead}
+        resolveAttachmentUrl={resolveAttachmentUrl}
+        tail={props.tail}
+        perspective={props.perspective}
+        avatar={avatar}
+        {...resolveActions(item, pendingActions)}
+      />,
+    )
+  }
+  return <div className="cv-p-thread__messages">{nodes}</div>
+}

package/src/participant/conversationThreadApi.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test'
+
+import { toParticipantApi, type ConversationThreadApi } from './conversationThreadApi'
+
+const SUBJECT = { subjectType: 'invoice', subjectId: '1' }
+
+function buildApi(overrides: Partial<ConversationThreadApi> = {}): ConversationThreadApi {
+  return {
+    fetchMessages: async () => [],
+    sendMessage: async () => ({ outcome: 'queued' }),
+    resolveAttachmentUrl: async () => 'x',
+    ...overrides,
+  } as ConversationThreadApi
+}
+
+describe('toParticipantApi markRead', () => {
+  it('rejects when the host does not implement markRead, so nothing is reported as read', async () => {
+    await expect(toParticipantApi(buildApi()).markRead(SUBJECT)).rejects.toThrow()
+  })
+
+  it('delegates to the host markRead keeping its this', async () => {
+    const calls: unknown[] = []
+    const host = buildApi({ markRead: async function (this: unknown, subject) { calls.push([this, subject]) } })
+    await toParticipantApi(host).markRead(SUBJECT)
+    expect(calls).toEqual([[host, SUBJECT]])
+  })
+})

package/src/participant/conversationThreadApi.ts

@@ -0,0 +1,24 @@
+import type { ParticipantConversationsApi } from './participantApi.types'
+
+/** What one conversation needs from the host: no list, no open-by-subject. `markRead` and `subscribe` are optional. */
+export type ConversationThreadApi = Pick<
+  ParticipantConversationsApi,
+  'fetchMessages' | 'sendMessage' | 'resolveAttachmentUrl'
+> &
+  Partial<Pick<ParticipantConversationsApi, 'markRead' | 'subscribe'>>
+
+/** Methods are delegated, never detached, so adapters written as classes keep their `this`. */
+export function toParticipantApi(api: ConversationThreadApi): ParticipantConversationsApi {
+  const { subscribe } = api
+  return {
+    listConversations: async () => ({ data: [] }),
+    fetchMessages: (subject, params) => api.fetchMessages(subject, params),
+    sendMessage: (input) => api.sendMessage(input),
+    markRead: async (subject) => {
+      if (!api.markRead) throw new Error('The host api has no markRead')
+      await api.markRead(subject)
+    },
+    resolveAttachmentUrl: (attachment, disposition) => api.resolveAttachmentUrl(attachment, disposition),
+    ...(subscribe ? { subscribe: (listener) => api.subscribe?.(listener) ?? (() => undefined) } : {}),
+  }
+}