@adatechnology/conversations-ui 0.4.2 → 0.5.0

package/src/participant/participantSendController.ts

@@ -0,0 +1,134 @@
+import type { ParticipantMessage, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantLocalPendingMessage, ParticipantPendingMessage } from './participantApi.types'
+import type { ParticipantDraft, ParticipantSendContent } from './participantDrafts'
+
+/** 'sent': the server accepted it; the bubble stays until the echo with the clientMessageId shows up in the messages. */
+export type ParticipantSendEntryState = 'sending' | 'queued' | 'failed' | 'sent'
+
+/** The bubble owns the content of a send: text and files live here until the server (or the host queue) reflects the id. */
+export type ParticipantSendEntry = {
+  readonly clientMessageId: string
+  readonly subject: ParticipantSubjectRef
+  readonly text?: string
+  readonly files: readonly File[]
+  readonly createdAt: string
+  readonly state: ParticipantSendEntryState
+  readonly sentMessage?: ParticipantMessage
+}
+
+export type ParticipantSendAction =
+  | { readonly type: 'started'; readonly entry: ParticipantSendEntry }
+  | { readonly type: 'sent'; readonly clientMessageId: string; readonly message: ParticipantMessage }
+  | { readonly type: 'queued'; readonly clientMessageId: string }
+  | { readonly type: 'failed'; readonly clientMessageId: string }
+  | { readonly type: 'retried'; readonly clientMessageId: string }
+  | { readonly type: 'discarded'; readonly clientMessageId: string }
+  | { readonly type: 'reflected'; readonly knownClientMessageIds: ReadonlySet<string> }
+
+export type CreateParticipantSendEntryParams = {
+  readonly clientMessageId: string
+  readonly subject: ParticipantSubjectRef
+  readonly content: ParticipantSendContent
+  readonly createdAt: string
+  readonly files?: readonly File[]
+  readonly state?: ParticipantSendEntryState
+}
+
+export type CollectKnownClientMessageIdsParams = {
+  readonly messages: readonly ParticipantMessage[]
+  readonly hostPending: readonly ParticipantPendingMessage[]
+}
+
+export function createParticipantSendEntry(params: CreateParticipantSendEntryParams): ParticipantSendEntry {
+  const { clientMessageId, subject, content, createdAt, state = 'sending' } = params
+  return {
+    clientMessageId,
+    subject,
+    ...(content.text ? { text: content.text } : {}),
+    files: params.files ?? content.files ?? [],
+    createdAt,
+    state,
+  }
+}
+
+function setState(
+  entries: readonly ParticipantSendEntry[],
+  clientMessageId: string,
+  allowedFrom: readonly ParticipantSendEntryState[],
+  next: ParticipantSendEntryState,
+): readonly ParticipantSendEntry[] {
+  const target = entries.find((item) => item.clientMessageId === clientMessageId)
+  if (!target || !allowedFrom.includes(target.state) || target.state === next) return entries
+  return entries.map((item) => (item === target ? { ...item, state: next } : item))
+}
+
+function markSent(entries: readonly ParticipantSendEntry[], clientMessageId: string, message: ParticipantMessage): readonly ParticipantSendEntry[] {
+  const target = entries.find((item) => item.clientMessageId === clientMessageId)
+  if (!target || target.state === 'sent') return entries
+  return entries.map((item) => (item === target ? { ...item, state: 'sent', sentMessage: message } : item))
+}
+
+function remove(entries: readonly ParticipantSendEntry[], shouldRemove: (item: ParticipantSendEntry) => boolean): readonly ParticipantSendEntry[] {
+  const kept = entries.filter((item) => !shouldRemove(item))
+  return kept.length === entries.length ? entries : kept
+}
+
+export function participantSendReducer(
+  entries: readonly ParticipantSendEntry[],
+  action: ParticipantSendAction,
+): readonly ParticipantSendEntry[] {
+  switch (action.type) {
+    case 'started':
+      return [...entries.filter((item) => item.clientMessageId !== action.entry.clientMessageId), action.entry]
+    case 'discarded':
+      return remove(entries, (item) => item.clientMessageId === action.clientMessageId)
+    case 'sent':
+      return markSent(entries, action.clientMessageId, action.message)
+    case 'queued':
+      return setState(entries, action.clientMessageId, ['sending'], 'queued')
+    case 'failed':
+      return setState(entries, action.clientMessageId, ['sending', 'queued'], 'failed')
+    case 'retried':
+      return setState(entries, action.clientMessageId, ['failed'], 'sending')
+    case 'reflected':
+      return remove(entries, (item) => action.knownClientMessageIds.has(item.clientMessageId))
+  }
+}
+
+export function findFailedEntry(entries: readonly ParticipantSendEntry[], clientMessageId: string): ParticipantSendEntry | undefined {
+  return entries.find((item) => item.clientMessageId === clientMessageId && item.state === 'failed')
+}
+
+export function hasSendingEntry(entries: readonly ParticipantSendEntry[]): boolean {
+  return entries.some((item) => item.state === 'sending')
+}
+
+export function collectKnownClientMessageIds(params: CollectKnownClientMessageIdsParams): ReadonlySet<string> {
+  const known = new Set<string>()
+  for (const message of params.messages) {
+    if (message.clientMessageId) known.add(message.clientMessageId)
+  }
+  for (const pending of params.hostPending) known.add(pending.clientMessageId)
+  return known
+}
+
+export function toLocalPending(entries: readonly ParticipantSendEntry[]): readonly ParticipantLocalPendingMessage[] {
+  return entries.map((item) => {
+    const attachments = item.files.map((file) => ({ filename: file.name, mimeType: file.type, sizeBytes: file.size }))
+    return {
+      clientMessageId: item.clientMessageId,
+      subject: item.subject,
+      createdAt: item.createdAt,
+      state: item.state,
+      ...(item.text ? { text: item.text } : {}),
+      ...(attachments.length > 0 ? { attachments } : {}),
+    }
+  })
+}
+
+/** Edit hands the content back to the field; whatever the user typed meanwhile stays after it. */
+export function appendEntryToDraft(entry: ParticipantSendEntry, current: ParticipantDraft): ParticipantDraft {
+  const text = [entry.text, current.text].filter((part): part is string => Boolean(part)).join('\n')
+  return { text, files: [...entry.files, ...current.files] }
+}

package/src/participant/participantSendStates.ts

@@ -0,0 +1,31 @@
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import { draftKey } from './participantDrafts'
+import { participantSendReducer, type ParticipantSendAction, type ParticipantSendEntry } from './participantSendController'
+
+/** Entries of every subject, kept above the conversation so leaving and coming back does not lose a failed message. */
+export type ParticipantSendStates = ReadonlyMap<string, readonly ParticipantSendEntry[]>
+
+export type ParticipantSendStatesAction = {
+  readonly subject: ParticipantSubjectRef
+  readonly action: ParticipantSendAction
+}
+
+const NO_ENTRIES: readonly ParticipantSendEntry[] = []
+
+export function selectSendEntries(states: ParticipantSendStates, subject: ParticipantSubjectRef): readonly ParticipantSendEntry[] {
+  return states.get(draftKey(subject)) ?? NO_ENTRIES
+}
+
+export function participantSendStatesReducer(
+  states: ParticipantSendStates,
+  { subject, action }: ParticipantSendStatesAction,
+): ParticipantSendStates {
+  const current = selectSendEntries(states, subject)
+  const next = participantSendReducer(current, action)
+  if (next === current) return states
+  const copy = new Map(states)
+  if (next.length === 0) copy.delete(draftKey(subject))
+  else copy.set(draftKey(subject), next)
+  return copy
+}

package/src/participant/participantTheme.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from 'react'
+
+import type { ConversationsTheme } from '../types'
+
+const THEME_TO_VARIABLE = {
+  primaryColor: '--cv-p-accent',
+  backgroundColor: '--cv-p-surface',
+  textPrimary: '--cv-p-text',
+  textSecondary: '--cv-p-text-muted',
+} as const
+
+export function buildParticipantThemeStyle(theme: ConversationsTheme | undefined): CSSProperties | undefined {
+  if (!theme) return undefined
+  const style: Record<string, string> = {}
+  for (const [key, variable] of Object.entries(THEME_TO_VARIABLE)) {
+    const value = theme[key as keyof typeof THEME_TO_VARIABLE]
+    if (value) style[variable] = value
+  }
+  return Object.keys(style).length > 0 ? (style as CSSProperties) : undefined
+}

package/src/participant/participantThreadState.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+import { INITIAL_PARTICIPANT_THREAD_STATE, participantThreadReducer, type ParticipantThreadState } from './participantThreadState'
+
+
+function message(id: string, createdAt: string, overrides: Partial<ParticipantMessage> = {}): ParticipantMessage {
+  return { id, direction: 'outbound', attachments: [], createdAt, ...overrides }
+}
+function ids(state: ParticipantThreadState): string[] {
+  return state.messages.map((item) => item.id)
+}
+
+describe('participantThreadReducer', () => {
+  it('loaded stores messages ascending and the hasMore flag', () => {
+    const state = participantThreadReducer(INITIAL_PARTICIPANT_THREAD_STATE, {
+      type: 'loaded',
+      messages: [message('m2', '2026-10-01T10:02:00.000Z'), message('m1', '2026-10-01T10:01:00.000Z')],
+      hasMore: true,
+    })
+    expect(ids(state)).toEqual(['m1', 'm2'])
+    expect(state).toMatchObject({ status: 'ready', hasMore: true })
+  })
+
+  it('olderLoaded prepends without duplicating by id', () => {
+    const first = participantThreadReducer(INITIAL_PARTICIPANT_THREAD_STATE, {
+      type: 'loaded',
+      messages: [message('m3', '2026-10-01T10:03:00.000Z'), message('m4', '2026-10-01T10:04:00.000Z')],
+      hasMore: true,
+    })
+    const next = participantThreadReducer(first, {
+      type: 'olderLoaded',
+      messages: [message('m1', '2026-10-01T10:01:00.000Z'), message('m2', '2026-10-01T10:02:00.000Z'), message('m3', '2026-10-01T10:03:00.000Z')],
+      hasMore: false,
+    })
+    expect(ids(next)).toEqual(['m1', 'm2', 'm3', 'm4'])
+    expect(next.hasMore).toBe(false)
+  })
+
+  it('a revalidation keeps older pages already fetched and the existing hasMore', () => {
+    const first = participantThreadReducer(INITIAL_PARTICIPANT_THREAD_STATE, {
+      type: 'loaded',
+      messages: [message('m2', '2026-10-01T10:02:00.000Z')],
+      hasMore: true,
+    })
+    const older = participantThreadReducer(first, { type: 'olderLoaded', messages: [message('m1', '2026-10-01T10:01:00.000Z')], hasMore: false })
+    const revalidated = participantThreadReducer(older, {
+      type: 'loaded',
+      messages: [message('m2', '2026-10-01T10:02:00.000Z', { status: 'read' }), message('m3', '2026-10-01T10:03:00.000Z')],
+      hasMore: true,
+    })
+    expect(ids(revalidated)).toEqual(['m1', 'm2', 'm3'])
+    expect(revalidated.messages[1]?.status).toBe('read')
+    expect(revalidated.hasMore).toBe(false)
+  })
+
+  it('sendConfirmed adds the server message once, ascending', () => {
+    const base = participantThreadReducer(INITIAL_PARTICIPANT_THREAD_STATE, {
+      type: 'loaded',
+      messages: [message('m1', '2026-10-01T10:00:00.000Z')],
+      hasMore: false,
+    })
+    const sent = message('m2', '2026-10-01T10:01:00.000Z', { clientMessageId: 'c1' })
+    const confirmed = participantThreadReducer(participantThreadReducer(base, { type: 'sendConfirmed', message: sent }), { type: 'sendConfirmed', message: sent })
+
+    expect(ids(confirmed)).toEqual(['m1', 'm2'])
+  })
+
+  it('reset returns to the initial state and failed records the error', () => {
+    const loaded = participantThreadReducer(INITIAL_PARTICIPANT_THREAD_STATE, { type: 'loaded', messages: [message('m1', '2026-10-01T10:00:00.000Z')], hasMore: false })
+    expect(participantThreadReducer(loaded, { type: 'reset' })).toEqual(INITIAL_PARTICIPANT_THREAD_STATE)
+    expect(participantThreadReducer(loaded, { type: 'failed', error: 'boom' })).toMatchObject({ status: 'error', error: 'boom' })
+  })
+})

package/src/participant/participantThreadState.ts

@@ -0,0 +1,59 @@
+import type { ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+export type ParticipantThreadState = {
+  readonly status: 'idle' | 'loading' | 'ready' | 'error'
+  /** Ascending by createdAt. */
+  readonly messages: readonly ParticipantMessage[]
+  readonly hasMore: boolean
+  readonly error?: string
+}
+
+export type ParticipantThreadAction =
+  | { readonly type: 'reset' }
+  | { readonly type: 'started' }
+  | { readonly type: 'loaded'; readonly messages: readonly ParticipantMessage[]; readonly hasMore: boolean }
+  | { readonly type: 'olderLoaded'; readonly messages: readonly ParticipantMessage[]; readonly hasMore: boolean }
+  | { readonly type: 'failed'; readonly error: string }
+  | { readonly type: 'sendConfirmed'; readonly message: ParticipantMessage }
+
+export const INITIAL_PARTICIPANT_THREAD_STATE: ParticipantThreadState = {
+  status: 'idle',
+  messages: [],
+  hasMore: false,
+}
+
+function unionById(
+  current: readonly ParticipantMessage[],
+  incoming: readonly ParticipantMessage[],
+): readonly ParticipantMessage[] {
+  const byId = new Map(current.map((message) => [message.id, message]))
+  for (const message of incoming) byId.set(message.id, message)
+  return [...byId.values()].sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt))
+}
+
+function mergeMessages(
+  state: ParticipantThreadState,
+  incoming: readonly ParticipantMessage[],
+  hasMore: boolean,
+): ParticipantThreadState {
+  const messages = unionById(state.messages, incoming)
+  const { error: _error, ...rest } = state
+  return { ...rest, status: 'ready', messages, hasMore }
+}
+
+export function participantThreadReducer(state: ParticipantThreadState, action: ParticipantThreadAction): ParticipantThreadState {
+  switch (action.type) {
+    case 'reset':
+      return INITIAL_PARTICIPANT_THREAD_STATE
+    case 'started':
+      return state.status === 'ready' ? state : { ...state, status: 'loading' }
+    case 'loaded':
+      return mergeMessages(state, action.messages, state.messages.length === 0 ? action.hasMore : state.hasMore)
+    case 'olderLoaded':
+      return mergeMessages(state, action.messages, action.hasMore)
+    case 'failed':
+      return { ...state, status: 'error', error: action.error }
+    case 'sendConfirmed':
+      return { ...state, messages: unionById(state.messages, [action.message]) }
+  }
+}

package/src/participant/shouldMarkRead.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test'
+
+import { shouldMarkParticipantRead } from './shouldMarkRead'
+
+const SUBJECT = { subjectType: 'trip', subjectId: 'a' }
+
+describe('shouldMarkParticipantRead', () => {
+  it('is true for the selected subject, visible, with unread messages', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: { ...SUBJECT }, visibilityState: 'visible', unreadCount: 2 })).toBe(true)
+  })
+  it('is false when nothing is selected', () => {
+    expect(shouldMarkParticipantRead({ selected: undefined, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+  })
+  it('is false when another subject is selected (id or type differs)', () => {
+    expect(shouldMarkParticipantRead({ selected: { subjectType: 'trip', subjectId: 'b' }, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+    expect(shouldMarkParticipantRead({ selected: { subjectType: 'invoice', subjectId: 'a' }, subject: SUBJECT, visibilityState: 'visible', unreadCount: 2 })).toBe(false)
+  })
+  it('is false while the document is hidden', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: SUBJECT, visibilityState: 'hidden', unreadCount: 2 })).toBe(false)
+  })
+  it('is false without unread messages', () => {
+    expect(shouldMarkParticipantRead({ selected: SUBJECT, subject: SUBJECT, visibilityState: 'visible', unreadCount: 0 })).toBe(false)
+  })
+})

package/src/participant/shouldMarkRead.ts

@@ -0,0 +1,16 @@
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+export type ShouldMarkParticipantReadParams = {
+  readonly selected: ParticipantSubjectRef | undefined
+  readonly subject: ParticipantSubjectRef
+  readonly visibilityState: DocumentVisibilityState
+  readonly unreadCount: number
+}
+
+export function shouldMarkParticipantRead(params: ShouldMarkParticipantReadParams): boolean {
+  const { selected, subject, visibilityState, unreadCount } = params
+  if (!selected) return false
+  if (selected.subjectType !== subject.subjectType || selected.subjectId !== subject.subjectId) return false
+  if (visibilityState !== 'visible') return false
+  return unreadCount > 0
+}

package/src/participant/useDocumentVisibility.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react'
+
+export function useDocumentVisibility(): DocumentVisibilityState {
+  const [visibilityState, setVisibilityState] = useState<DocumentVisibilityState>(() =>
+    typeof document === 'undefined' ? 'visible' : document.visibilityState,
+  )
+
+  useEffect(() => {
+    function handleVisibilityChange(): void {
+      setVisibilityState(document.visibilityState)
+    }
+    handleVisibilityChange()
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
+  }, [])
+
+  return visibilityState
+}

package/src/participant/useParticipantConversationView.ts

@@ -0,0 +1,60 @@
+import { useCallback, useMemo, type Dispatch } from 'react'
+
+import type { ParticipantConversationSummary, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ConversationChannel } from '../conversationChannel'
+import type { ParticipantConversationsApi, ParticipantPendingMessage } from './participantApi.types'
+import { mergeParticipantMessages, type ParticipantTimelineItem } from './participantMessages'
+import type { ParticipantSendAction, ParticipantSendEntry } from './participantSendController'
+import { selectSendEntries, type ParticipantSendStates, type ParticipantSendStatesAction } from './participantSendStates'
+import { useParticipantThread, type UseParticipantThreadResult } from './useParticipantThread'
+
+export type UseParticipantConversationViewParams = {
+  readonly api: ParticipantConversationsApi
+  readonly subject: ParticipantSubjectRef
+  readonly conversation: ParticipantConversationSummary
+  readonly channel?: ConversationChannel
+  readonly onMarkedRead: (subject: ParticipantSubjectRef) => void
+  readonly pendingMessages?: readonly ParticipantPendingMessage[]
+  readonly sendStates: ParticipantSendStates
+  readonly dispatchSendStates: Dispatch<ParticipantSendStatesAction>
+}
+
+export type UseParticipantConversationViewResult = {
+  readonly thread: UseParticipantThreadResult
+  readonly items: readonly ParticipantTimelineItem[]
+  readonly sendEntries: readonly ParticipantSendEntry[]
+  readonly dispatchSend: (action: ParticipantSendAction) => void
+}
+
+export function useParticipantConversationView(params: UseParticipantConversationViewParams): UseParticipantConversationViewResult {
+  const { api, subject, conversation, pendingMessages, sendStates, dispatchSendStates } = params
+  const { subjectType, subjectId } = subject
+  const sendEntries = selectSendEntries(sendStates, subject)
+  const dispatchSend = useCallback(
+    (action: ParticipantSendAction) => dispatchSendStates({ subject: { subjectType, subjectId }, action }),
+    [dispatchSendStates, subjectType, subjectId],
+  )
+  const thread = useParticipantThread({
+    api,
+    subject,
+    channel: params.channel,
+    unreadCount: conversation.unreadCount,
+    onMarkedRead: params.onMarkedRead,
+    sendEntries,
+    dispatchSend,
+    hostPending: pendingMessages,
+  })
+  const items = useMemo(
+    () =>
+      mergeParticipantMessages({
+        serverMessages: thread.messages,
+        hostPending: pendingMessages ?? [],
+        localPending: thread.localPending,
+        subject,
+      }),
+    [thread.messages, thread.localPending, pendingMessages, subject],
+  )
+
+  return { thread, items, sendEntries, dispatchSend }
+}

package/src/participant/useParticipantDraft.ts

@@ -0,0 +1,45 @@
+import { useState, type MutableRefObject } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import {
+  getDraft,
+  setDraft,
+  takeDraftForSend,
+  type ParticipantDraft,
+  type ParticipantDrafts,
+  type ParticipantSendContent,
+} from './participantDrafts'
+import { appendEntryToDraft, type ParticipantSendEntry } from './participantSendController'
+
+export type UseParticipantDraftResult = {
+  readonly draft: ParticipantDraft
+  readonly setText: (text: string) => void
+  readonly setFiles: (files: readonly File[]) => void
+  /** Clears the field synchronously and hands the content over; undefined when there is nothing to send. */
+  readonly takeForSend: () => ParticipantSendContent | undefined
+  readonly restoreFromEntry: (entry: ParticipantSendEntry) => void
+}
+
+/** The ref holds the truth (read at call time, so a double tap sees the cleared field); state only re-renders. */
+export function useParticipantDraft(draftsRef: MutableRefObject<ParticipantDrafts>, subject: ParticipantSubjectRef): UseParticipantDraftResult {
+  const [draft, setDraftState] = useState<ParticipantDraft>(() => getDraft(draftsRef.current, subject))
+
+  function replaceDrafts(next: ParticipantDrafts): void {
+    draftsRef.current = next
+    setDraftState(getDraft(next, subject))
+  }
+  function update(change: Partial<ParticipantDraft>): void {
+    replaceDrafts(setDraft(draftsRef.current, subject, { ...getDraft(draftsRef.current, subject), ...change }))
+  }
+  function takeForSend(): ParticipantSendContent | undefined {
+    const taken = takeDraftForSend(draftsRef.current, subject)
+    if (taken.content) replaceDrafts(taken.drafts)
+    return taken.content
+  }
+  function restoreFromEntry(entry: ParticipantSendEntry): void {
+    update(appendEntryToDraft(entry, getDraft(draftsRef.current, subject)))
+  }
+
+  return { draft, setText: (text) => update({ text }), setFiles: (files) => update({ files }), takeForSend, restoreFromEntry }
+}

package/src/participant/useParticipantInbox.ts

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useReducer } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { INITIAL_PARTICIPANT_INBOX_STATE, participantInboxReducer, type ParticipantInboxState } from './participantInboxState'
+import { useParticipantRevalidation } from './useParticipantRevalidation'
+
+export type UseParticipantInboxResult = ParticipantInboxState & {
+  readonly hasMore: boolean
+  readonly refresh: () => Promise<void>
+  readonly loadMore: () => Promise<void>
+  readonly markSubjectRead: (subject: ParticipantSubjectRef) => void
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error'
+}
+
+export function useParticipantInbox(api: ParticipantConversationsApi): UseParticipantInboxResult {
+  const [state, dispatch] = useReducer(participantInboxReducer, INITIAL_PARTICIPANT_INBOX_STATE)
+
+  const refresh = useCallback(async (): Promise<void> => {
+    dispatch({ type: 'started' })
+    try {
+      const page = await api.listConversations()
+      dispatch({ type: 'loaded', conversations: page.data, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) })
+    } catch (error) {
+      dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [api])
+
+  const { nextCursor } = state
+  const loadMore = useCallback(async (): Promise<void> => {
+    if (!nextCursor) return
+    try {
+      const page = await api.listConversations({ cursor: nextCursor })
+      dispatch({ type: 'appended', conversations: page.data, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) })
+    } catch (error) {
+      dispatch({ type: 'failed', error: describeError(error) })
+    }
+  }, [api, nextCursor])
+
+  const markSubjectRead = useCallback((subject: ParticipantSubjectRef): void => {
+    dispatch({ type: 'markedRead', subject })
+  }, [])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useParticipantRevalidation(api, () => {
+    void refresh()
+  })
+
+  return { ...state, hasMore: nextCursor !== undefined, refresh, loadMore, markSubjectRead }
+}

package/src/participant/useParticipantMarkRead.ts

@@ -0,0 +1,26 @@
+import { useEffect, type MutableRefObject } from 'react'
+
+import type { ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantConversationsApi } from './participantApi.types'
+import { shouldMarkParticipantRead } from './shouldMarkRead'
+import { useDocumentVisibility } from './useDocumentVisibility'
+
+export type UseParticipantMarkReadParams = {
+  readonly apiRef: MutableRefObject<ParticipantConversationsApi>
+  readonly subject: ParticipantSubjectRef
+  readonly unreadCount: number
+  /** Marking again when a message arrives while the screen stays open. */
+  readonly messageCount: number
+  readonly onMarkedRead?: (subject: ParticipantSubjectRef) => void
+}
+
+export function useParticipantMarkRead(params: UseParticipantMarkReadParams): void {
+  const { apiRef, subject, unreadCount, messageCount, onMarkedRead } = params
+  const visibilityState = useDocumentVisibility()
+
+  useEffect(() => {
+    if (!shouldMarkParticipantRead({ selected: subject, subject, visibilityState, unreadCount })) return
+    void apiRef.current.markRead(subject).then(() => onMarkedRead?.(subject), () => undefined)
+  }, [apiRef, subject, visibilityState, unreadCount, messageCount, onMarkedRead])
+}

package/src/participant/useParticipantRevalidation.ts

@@ -0,0 +1,36 @@
+import { useEffect, useRef } from 'react'
+
+import type { ParticipantConversationEvent, ParticipantConversationsApi } from './participantApi.types'
+
+type RevalidationHandler = (event?: ParticipantConversationEvent) => void
+
+/** Subscribes to the host when it can push events (still revalidating on reconnection, when an event may have been lost); otherwise also on focus and visibility. */
+export function useParticipantRevalidation(api: ParticipantConversationsApi, onRevalidate: RevalidationHandler): void {
+  const handlerRef = useRef(onRevalidate)
+  handlerRef.current = onRevalidate
+
+  useEffect(() => {
+    function handleFocus(): void {
+      handlerRef.current()
+    }
+    if (api.subscribe) {
+      const unsubscribe = api.subscribe((event) => handlerRef.current(event))
+      window.addEventListener('online', handleFocus)
+      return () => {
+        unsubscribe()
+        window.removeEventListener('online', handleFocus)
+      }
+    }
+    function handleVisibilityChange(): void {
+      if (document.visibilityState === 'visible') handlerRef.current()
+    }
+    window.addEventListener('focus', handleFocus)
+    window.addEventListener('online', handleFocus)
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => {
+      window.removeEventListener('focus', handleFocus)
+      window.removeEventListener('online', handleFocus)
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+    }
+  }, [api])
+}