@adatechnology/conversations-ui 0.4.2 → 0.6.0

package/src/participant/participantProtocolCopy.ts

@@ -0,0 +1,32 @@
+export type ProtocolClipboard = {
+  readonly writeText: (text: string) => Promise<void>
+}
+
+/** Failure is silent by design: the protocol stays visible and selectable. */
+export async function copyProtocolToClipboard(
+  protocol: string,
+  clipboard: ProtocolClipboard | undefined,
+): Promise<boolean> {
+  if (clipboard === undefined) return false
+  try {
+    await clipboard.writeText(protocol)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export type ProtocolCopyState = {
+  readonly copyCount: number
+  readonly isCopied: boolean
+}
+
+export type ProtocolCopyAction = { readonly type: 'copied' } | { readonly type: 'expired' }
+
+export const INITIAL_PROTOCOL_COPY_STATE: ProtocolCopyState = { copyCount: 0, isCopied: false }
+
+/** The counter changes on every copy so a repeat inside the window restarts the timer. */
+export function protocolCopyReducer(state: ProtocolCopyState, action: ProtocolCopyAction): ProtocolCopyState {
+  if (action.type === 'copied') return { copyCount: state.copyCount + 1, isCopied: true }
+  return { ...state, isCopied: false }
+}

package/src/participant/participantQuickReply.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'bun:test'
+
+import { applyQuickReply } from './participantQuickReply'
+
+describe('applyQuickReply', () => {
+  it('fills an empty text with the reply', () => {
+    expect(applyQuickReply('', 'On my way')).toBe('On my way')
+    expect(applyQuickReply('   ', 'On my way')).toBe('On my way')
+  })
+
+  it('appends to existing text separated by a space', () => {
+    expect(applyQuickReply('Hello', 'On my way')).toBe('Hello On my way')
+  })
+
+  it('does not double the separator when the text already ends in whitespace', () => {
+    expect(applyQuickReply('Hello ', 'On my way')).toBe('Hello On my way')
+    expect(applyQuickReply('Hello\n', 'On my way')).toBe('Hello\nOn my way')
+  })
+
+  it('returns the text untouched for an empty reply', () => {
+    expect(applyQuickReply('Hello', '')).toBe('Hello')
+  })
+})

package/src/participant/participantQuickReply.ts

@@ -0,0 +1,6 @@
+/** Fills the composer text with a quick reply; the caller must never send because of it. */
+export function applyQuickReply(currentText: string, replyText: string): string {
+  if (replyText === '') return currentText
+  if (currentText.trim() === '') return replyText
+  return /\s$/.test(currentText) ? `${currentText}${replyText}` : `${currentText} ${replyText}`
+}

package/src/participant/participantScroll.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  NEAR_BOTTOM_THRESHOLD_PX,
+  resolveScrollAction,
+  scrollAnchorAfterPrepend,
+  shouldStickToBottom,
+} from './participantScroll'
+
+describe('shouldStickToBottom', () => {
+  const base = { clientHeight: 400, scrollHeight: 1000, threshold: 80 }
+
+  it('is true at the very bottom', () => {
+    expect(shouldStickToBottom({ ...base, scrollTop: 600 })).toBe(true)
+  })
+
+  it('is true within the threshold and false beyond it', () => {
+    expect(shouldStickToBottom({ ...base, scrollTop: 520 })).toBe(true)
+    expect(shouldStickToBottom({ ...base, scrollTop: 519 })).toBe(false)
+  })
+
+  it('is true when the content fits without scrolling', () => {
+    expect(shouldStickToBottom({ scrollTop: 0, clientHeight: 400, scrollHeight: 300, threshold: 80 })).toBe(true)
+  })
+
+  it('uses an 80px default threshold', () => {
+    expect(NEAR_BOTTOM_THRESHOLD_PX).toBe(80)
+  })
+})
+
+describe('scrollAnchorAfterPrepend', () => {
+  it('keeps the same message in view by adding the height that was prepended', () => {
+    expect(scrollAnchorAfterPrepend({ previousScrollTop: 10, previousScrollHeight: 1000, scrollHeight: 1600 })).toBe(610)
+  })
+
+  it('does not move when nothing was prepended', () => {
+    expect(scrollAnchorAfterPrepend({ previousScrollTop: 10, previousScrollHeight: 1000, scrollHeight: 1000 })).toBe(10)
+  })
+})
+
+describe('resolveScrollAction', () => {
+  const settled = { hasPositioned: true, previousFirstKey: 'a', previousLastKey: 'c', firstKey: 'a', lastKey: 'c', wasNearBottom: true }
+
+  it('does nothing while there are no items', () => {
+    expect(resolveScrollAction({ ...settled, hasPositioned: false, firstKey: undefined, lastKey: undefined })).toBe('none')
+  })
+
+  it('jumps to the bottom on the first load even when the user was not near the bottom', () => {
+    expect(resolveScrollAction({ ...settled, hasPositioned: false, previousFirstKey: undefined, previousLastKey: undefined, wasNearBottom: false })).toBe('bottom')
+  })
+
+  it('follows a new last message only when the user was near the bottom', () => {
+    expect(resolveScrollAction({ ...settled, lastKey: 'd' })).toBe('bottom')
+    expect(resolveScrollAction({ ...settled, lastKey: 'd', wasNearBottom: false })).toBe('none')
+  })
+
+  it('anchors when older messages are prepended, whatever the position', () => {
+    expect(resolveScrollAction({ ...settled, firstKey: 'z' })).toBe('anchor')
+    expect(resolveScrollAction({ ...settled, firstKey: 'z', wasNearBottom: false })).toBe('anchor')
+  })
+
+  it('anchors when both ends changed but the user was reading', () => {
+    expect(resolveScrollAction({ ...settled, firstKey: 'z', lastKey: 'd', wasNearBottom: false })).toBe('anchor')
+  })
+
+  it('does nothing when the keys are the same', () => {
+    expect(resolveScrollAction(settled)).toBe('none')
+  })
+})

package/src/participant/participantScroll.ts

@@ -0,0 +1,43 @@
+export const NEAR_BOTTOM_THRESHOLD_PX = 80
+
+export type ShouldStickToBottomParams = {
+  readonly scrollTop: number
+  readonly clientHeight: number
+  readonly scrollHeight: number
+  readonly threshold: number
+}
+
+export type ScrollAnchorAfterPrependParams = {
+  readonly previousScrollTop: number
+  readonly previousScrollHeight: number
+  readonly scrollHeight: number
+}
+
+export type ResolveScrollActionParams = {
+  readonly hasPositioned: boolean
+  readonly previousFirstKey: string | undefined
+  readonly previousLastKey: string | undefined
+  readonly firstKey: string | undefined
+  readonly lastKey: string | undefined
+  readonly wasNearBottom: boolean
+}
+
+export type ScrollAction = 'none' | 'bottom' | 'anchor'
+
+export function shouldStickToBottom(params: ShouldStickToBottomParams): boolean {
+  const { scrollTop, clientHeight, scrollHeight, threshold } = params
+  return scrollHeight - scrollTop - clientHeight <= threshold
+}
+
+export function scrollAnchorAfterPrepend(params: ScrollAnchorAfterPrependParams): number {
+  return params.previousScrollTop + (params.scrollHeight - params.previousScrollHeight)
+}
+
+export function resolveScrollAction(params: ResolveScrollActionParams): ScrollAction {
+  const { firstKey, lastKey } = params
+  if (firstKey === undefined || lastKey === undefined) return 'none'
+  if (!params.hasPositioned) return 'bottom'
+  if (lastKey !== params.previousLastKey && params.wasNearBottom) return 'bottom'
+  if (firstKey !== params.previousFirstKey) return 'anchor'
+  return 'none'
+}

package/src/participant/participantSendController.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantMessage } from '@adatechnology/conversation-contracts'
+
+import {
+  appendEntryToDraft,
+  collectKnownClientMessageIds,
+  createParticipantSendEntry,
+  findFailedEntry,
+  hasSendingEntry,
+  participantSendReducer,
+  toLocalPending,
+  type ParticipantSendEntry,
+} from './participantSendController'
+import { participantSendStatesReducer, selectSendEntries } from './participantSendStates'
+import { takeDraftForSend, setDraft } from './participantDrafts'
+
+const TRIP_A = { subjectType: 'trip', subjectId: 'a' }
+const TRIP_B = { subjectType: 'trip', subjectId: 'b' }
+
+function entry(clientMessageId: string, overrides: Partial<ParticipantSendEntry> = {}): ParticipantSendEntry {
+  return createParticipantSendEntry({
+    clientMessageId,
+    subject: TRIP_A,
+    content: { text: 'hello', files: [] },
+    createdAt: '2026-10-01T10:00:00.000Z',
+    ...overrides,
+  })
+}
+
+function serverMessage(id: string, clientMessageId?: string): ParticipantMessage {
+  return { id, direction: 'inbound', attachments: [], createdAt: '2026-10-01T10:00:00.000Z', ...(clientMessageId ? { clientMessageId } : {}) }
+}
+
+function states(entries: readonly ParticipantSendEntry[]) {
+  return entries.map((item) => [item.clientMessageId, item.state])
+}
+
+describe('participantSendReducer', () => {
+  it('starting a send registers a sending entry holding text and files', () => {
+    const file = new File(['x'], 'a.png', { type: 'image/png' })
+    const started = participantSendReducer([], {
+      type: 'started',
+      entry: entry('c1', { files: [file] }),
+    })
+
+    expect(states(started)).toEqual([['c1', 'sending']])
+    expect(started[0]?.files).toEqual([file])
+    expect(started[0]?.text).toBe('hello')
+  })
+
+  it('a sent send stays visible as sent, holding the server message, until the echo is reflected', () => {
+    const sending = participantSendReducer([], { type: 'started', entry: entry('c1') })
+    const message = serverMessage('m1', 'c1')
+    const sent = participantSendReducer(sending, { type: 'sent', clientMessageId: 'c1', message })
+
+    expect(states(sent)).toEqual([['c1', 'sent']])
+    expect(sent[0]?.sentMessage).toBe(message)
+    expect(toLocalPending(sent)[0]?.state).toBe('sent')
+  })
+
+  it('a sent entry survives leaving and coming back, and reflected removes it once the echo exists', () => {
+    const subjectStates = participantSendStatesReducer(new Map(), { subject: TRIP_A, action: { type: 'started', entry: entry('c1') } })
+    const afterSent = participantSendStatesReducer(subjectStates, {
+      subject: TRIP_A,
+      action: { type: 'sent', clientMessageId: 'c1', message: serverMessage('m1', 'c1') },
+    })
+    expect(states(selectSendEntries(afterSent, TRIP_A))).toEqual([['c1', 'sent']])
+
+    const notYet = participantSendStatesReducer(afterSent, { subject: TRIP_A, action: { type: 'reflected', knownClientMessageIds: new Set() } })
+    expect(states(selectSendEntries(notYet, TRIP_A))).toEqual([['c1', 'sent']])
+    const echoed = participantSendStatesReducer(afterSent, { subject: TRIP_A, action: { type: 'reflected', knownClientMessageIds: new Set(['c1']) } })
+    expect(selectSendEntries(echoed, TRIP_A)).toEqual([])
+  })
+
+  it('queued stays visible as queued until the host or the server reflect the id', () => {
+    const sending = participantSendReducer([], { type: 'started', entry: entry('c1') })
+    const queued = participantSendReducer(sending, { type: 'queued', clientMessageId: 'c1' })
+
+    expect(states(queued)).toEqual([['c1', 'queued']])
+    expect(states(participantSendReducer(queued, { type: 'reflected', knownClientMessageIds: new Set() }))).toEqual([['c1', 'queued']])
+    expect(participantSendReducer(queued, { type: 'reflected', knownClientMessageIds: new Set(['c1']) })).toEqual([])
+  })
+
+  it('reflecting an unknown id returns the same reference (no rerender)', () => {
+    const queued = participantSendReducer([], { type: 'started', entry: entry('c1') })
+    expect(participantSendReducer(queued, { type: 'reflected', knownClientMessageIds: new Set(['other']) })).toBe(queued)
+  })
+
+  it('a throw marks failed keeping text and files; retry reuses the same id and goes back to sending', () => {
+    const file = new File(['x'], 'a.png')
+    const failed = participantSendReducer(participantSendReducer([], { type: 'started', entry: entry('c1', { files: [file] }) }), {
+      type: 'failed',
+      clientMessageId: 'c1',
+    })
+
+    expect(findFailedEntry(failed, 'c1')?.files).toEqual([file])
+    const retried = participantSendReducer(failed, { type: 'retried', clientMessageId: 'c1' })
+    expect(states(retried)).toEqual([['c1', 'sending']])
+    expect(retried[0]?.text).toBe('hello')
+  })
+
+  it('retry only applies to failed entries', () => {
+    const sending = participantSendReducer([], { type: 'started', entry: entry('c1') })
+    expect(participantSendReducer(sending, { type: 'retried', clientMessageId: 'c1' })).toBe(sending)
+    expect(findFailedEntry(sending, 'c1')).toBeUndefined()
+  })
+
+  it('discard removes the pending', () => {
+    const failed = participantSendReducer(participantSendReducer([], { type: 'started', entry: entry('c1') }), { type: 'failed', clientMessageId: 'c1' })
+    expect(participantSendReducer(failed, { type: 'discarded', clientMessageId: 'c1' })).toEqual([])
+  })
+
+  it('edit returns text and files to the draft, with the current field content kept after them', () => {
+    const file = new File(['x'], 'a.png')
+    const other = new File(['y'], 'b.png')
+    const failed = entry('c1', { files: [file], state: 'failed' })
+
+    expect(appendEntryToDraft(failed, { text: '', files: [] })).toEqual({ text: 'hello', files: [file] })
+    expect(appendEntryToDraft(failed, { text: 'typed', files: [other] })).toEqual({ text: 'hello\ntyped', files: [file, other] })
+  })
+
+  it('maps entries to local pending messages without the files', () => {
+    const file = new File(['x'], 'a.png', { type: 'image/png' })
+    const [pending] = toLocalPending([entry('c1', { files: [file], state: 'queued' })])
+
+    expect(pending).toMatchObject({ clientMessageId: 'c1', state: 'queued', text: 'hello' })
+    expect(pending?.attachments).toEqual([{ filename: 'a.png', mimeType: 'image/png', sizeBytes: 1 }])
+    expect(pending).not.toHaveProperty('files')
+  })
+
+  it('collects the ids known by the server and by the host queue', () => {
+    const known = collectKnownClientMessageIds({
+      messages: [serverMessage('m1', 'c1'), serverMessage('m2')],
+      hostPending: [{ clientMessageId: 'c2', subject: TRIP_A, createdAt: '2026-10-01T10:00:00.000Z', state: 'queued' }],
+    })
+    expect([...known].sort()).toEqual(['c1', 'c2'])
+  })
+})
+
+describe('send flow with the double tap', () => {
+  it('the second tap finds the field already empty and sends nothing', () => {
+    const drafts = setDraft(new Map(), TRIP_A, { text: '  hello  ', files: [] })
+
+    const first = takeDraftForSend(drafts, TRIP_A)
+    const second = takeDraftForSend(first.drafts, TRIP_A)
+
+    expect(first.content).toEqual({ text: 'hello' })
+    expect(second.content).toBeUndefined()
+  })
+
+  it('an empty or whitespace-only field sends nothing and keeps the drafts reference', () => {
+    const drafts = setDraft(new Map(), TRIP_A, { text: '   ', files: [] })
+    const taken = takeDraftForSend(drafts, TRIP_A)
+
+    expect(taken.content).toBeUndefined()
+    expect(taken.drafts).toBe(drafts)
+  })
+
+  it('failure then edit hands the content back to the draft and leaves a single owner', () => {
+    const drafts = setDraft(new Map(), TRIP_A, { text: 'hello', files: [] })
+    const { drafts: cleared, content } = takeDraftForSend(drafts, TRIP_A)
+    const started = participantSendReducer([], {
+      type: 'started',
+      entry: createParticipantSendEntry({ clientMessageId: 'c1', subject: TRIP_A, content: content ?? { files: [] }, createdAt: '2026-10-01T10:00:00.000Z' }),
+    })
+    const failed = participantSendReducer(started, { type: 'failed', clientMessageId: 'c1' })
+    const failedEntry = findFailedEntry(failed, 'c1')
+
+    expect(cleared.get('trip:a')).toBeUndefined()
+    expect(failedEntry && appendEntryToDraft(failedEntry, { text: '', files: [] })).toEqual({ text: 'hello', files: [] })
+    expect(participantSendReducer(failed, { type: 'discarded', clientMessageId: 'c1' })).toEqual([])
+  })
+})
+
+describe('participantSendStatesReducer', () => {
+  it('keeps the entries per subject so leaving and coming back does not lose a failed message', () => {
+    const afterA = participantSendStatesReducer(new Map(), { subject: TRIP_A, action: { type: 'started', entry: entry('c1') } })
+    const afterFailed = participantSendStatesReducer(afterA, { subject: TRIP_A, action: { type: 'failed', clientMessageId: 'c1' } })
+
+    expect(states(selectSendEntries(afterFailed, TRIP_A))).toEqual([['c1', 'failed']])
+    expect(selectSendEntries(afterFailed, TRIP_B)).toEqual([])
+  })
+
+  it('drops the subject key when its last entry goes away and ignores no-ops by reference', () => {
+    const started = participantSendStatesReducer(new Map(), { subject: TRIP_A, action: { type: 'started', entry: entry('c1') } })
+    const noop = participantSendStatesReducer(started, { subject: TRIP_A, action: { type: 'reflected', knownClientMessageIds: new Set() } })
+    const gone = participantSendStatesReducer(started, { subject: TRIP_A, action: { type: 'discarded', clientMessageId: 'c1' } })
+
+    expect(noop).toBe(started)
+    expect(gone.size).toBe(0)
+  })
+})
+
+describe('hasSendingEntry', () => {
+  it('is true only while some send is in the sending state', () => {
+    expect(hasSendingEntry([])).toBe(false)
+    expect(hasSendingEntry([entry('a', { state: 'failed' }), entry('b', { state: 'queued' })])).toBe(false)
+    expect(hasSendingEntry([entry('a', { state: 'failed' }), entry('b', { state: 'sending' })])).toBe(true)
+  })
+})

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' })
+  })
+})