@adatechnology/conversations-ui 0.7.0 → 0.8.0

package/src/participant/ParticipantTimeline.tsx

@@ -15,6 +15,7 @@ import {
 } 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[]
@@ -26,6 +27,7 @@ export type ParticipantTimelineProps = {
   readonly avatars?: 'initials'
   readonly renderAuthorAvatar?: ParticipantAuthorAvatarRenderer
   readonly tail?: boolean
+  readonly perspective?: ParticipantPerspective
 }
 
 function createdAtOf(item: ParticipantTimelineItem): string {
@@ -38,9 +40,9 @@ function keyOf(item: ParticipantTimelineItem): string {
 
 type AuthorOfItem = { readonly isMine: boolean; readonly author: ParticipantAvatarAuthor }
 
-function authorOf(item: ParticipantTimelineItem): AuthorOfItem {
+function authorOf(item: ParticipantTimelineItem, perspective?: ParticipantPerspective): AuthorOfItem {
   if (item.kind === 'pending') return { isMine: true, author: null }
-  return { isMine: isOwnMessage(item.message), author: item.message.authorName ?? null }
+  return { isMine: isOwnMessage(item.message, perspective), author: item.message.authorName ?? null }
 }
 
 function resolveActions(item: ParticipantTimelineItem, pendingActions?: ParticipantPendingActions) {
@@ -76,7 +78,7 @@ export function ParticipantTimeline(props: ParticipantTimelineProps) {
       previousAuthor = undefined
     }
     previousDay = day
-    const { isMine, author } = authorOf(item)
+    const { isMine, author } = authorOf(item, props.perspective)
     const showAvatar = shouldShowAvatar({ previousAuthor, author, isMine })
     previousAuthor = isMine ? undefined : author
     const avatar = resolveAvatarSlot({
@@ -94,6 +96,7 @@ export function ParticipantTimeline(props: ParticipantTimelineProps) {
         confirmsRead={confirmsRead}
         resolveAttachmentUrl={resolveAttachmentUrl}
         tail={props.tail}
+        perspective={props.perspective}
         avatar={avatar}
         {...resolveActions(item, pendingActions)}
       />,

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) } : {}),
+  }
+}

package/src/participant/conversationThreadCss.test.ts

@@ -0,0 +1,116 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { declarationsIn, mediaBody, PARTICIPANT_CSS } from './participantCss.test-helper'
+
+const NEW_SOURCES = [
+  'ConversationThread.tsx',
+  'conversationThreadApi.ts',
+  'conversationThreadSummary.ts',
+  'participantPerspective.ts',
+  'useParticipantUnread.ts',
+  'useParticipantThreadController.ts',
+].map((file) => ({ file, source: readFileSync(join(import.meta.dir, file), 'utf8') }))
+
+describe('header additions', () => {
+  it('puts the counterpart line in one muted, ellipsized line', () => {
+    const rule = declarationsIn('.cv-p-thread__counterpart')
+    expect(rule.get('color')).toBe('var(--cv-p-i-text-muted)')
+    expect(rule.get('white-space')).toBe('nowrap')
+    expect(rule.get('text-overflow')).toBe('ellipsis')
+  })
+
+  it('keeps the host actions at the end of the bar, never wider than the bar', () => {
+    const rule = declarationsIn('.cv-p-thread__actions')
+    expect(rule.get('flex')).toBe('0 0 auto')
+    expect(rule.get('margin-inline-start')).toBe('auto')
+    expect(rule.get('max-width')).toBe('100%')
+  })
+
+  it('lets the bar wrap and gives the title a floor only when there are host actions', () => {
+    const withActions = '.cv-p-thread__header:has(.cv-p-thread__actions)'
+    expect(declarationsIn(withActions).get('flex-wrap')).toBe('wrap')
+    expect(declarationsIn(`${withActions} .cv-p-thread__heading`).get('min-width')).toBe('6rem')
+    expect(declarationsIn('.cv-p-thread__header').has('flex-wrap')).toBe(false)
+    expect(declarationsIn('.cv-p-thread__heading').get('min-width')).toBe('0')
+  })
+})
+
+describe('ticks', () => {
+  it('take their color from package tokens that a host can override, with a fallback', () => {
+    const root = declarationsIn('.cv-p')
+    expect(root.get('--cv-p-i-tick')).toBe('var(--cv-p-tick, var(--cv-p-i-text-muted))')
+    expect(root.get('--cv-p-i-tick-read')).toMatch(/^var\(--cv-p-tick-read, #[0-9a-f]{6}\)$/)
+    expect(declarationsIn('.dark .cv-p').get('--cv-p-i-tick-read')).toMatch(/^var\(--cv-p-tick-read, #[0-9a-f]{6}\)$/)
+  })
+
+  it('override the shared tick colors only inside the participant bubble', () => {
+    expect(declarationsIn('.cv-p-bubble .cv-status-ticks--sent').get('color')).toBe('var(--cv-p-i-tick)')
+    expect(declarationsIn('.cv-p-bubble .cv-status-ticks--delivered').get('color')).toBe('var(--cv-p-i-tick)')
+    expect(declarationsIn('.cv-p-bubble .cv-status-ticks--read').get('color')).toBe('var(--cv-p-i-tick-read)')
+    expect(declarationsIn('.cv-p-bubble .cv-status-ticks--failed').get('color')).toBe('var(--cv-p-i-danger)')
+    expect(declarationsIn('.cv-status-ticks--read').get('color')).toBe('rgb(14 165 233)')
+  })
+
+  it('give way to the system colors under forced-colors', () => {
+    const forced = mediaBody('(forced-colors: active)') ?? ''
+    expect(forced).toContain('.cv-p-bubble .cv-status-ticks')
+    expect(declarationsIn('.cv-p-bubble .cv-status-ticks', forced).get('color')).toBe('CanvasText')
+  })
+})
+
+describe('wallpaper and the strips around it', () => {
+  it('gives the load error a solid panel so no text depends on the dots', () => {
+    expect(declarationsIn('.cv-p-thread__scroll > .cv-p-error').get('background')).toBe('var(--cv-p-i-surface)')
+  })
+
+  it('paints the live strip like the composer it sits on', () => {
+    expect(declarationsIn('.cv-p-thread__live').get('background')).toBe('var(--cv-p-i-surface-raised)')
+  })
+
+  it('keeps the wallpaper off under forced-colors', () => {
+    expect(
+      declarationsIn('.cv-p-thread__scroll', mediaBody('(forced-colors: active)') ?? '').get('background-image'),
+    ).toBe('none')
+  })
+})
+
+describe('motion', () => {
+  it('adds no transition or animation outside the no-preference block', () => {
+    const rules = declarationsIn('.cv-p-thread__actions')
+    const counterpart = declarationsIn('.cv-p-thread__counterpart')
+    for (const declarations of [rules, counterpart]) {
+      expect(
+        [...declarations.keys()].some(
+          (property) => property.startsWith('transition') || property.startsWith('animation'),
+        ),
+      ).toBe(false)
+    }
+    expect(mediaBody('(prefers-reduced-motion: no-preference)')).toBeDefined()
+  })
+})
+
+describe('new sources', () => {
+  it('use no Tailwind utilities and none of the vocabulary of a specific product', () => {
+    for (const { file, source } of NEW_SOURCES) {
+      expect(source, file).not.toMatch(/className="[^"]*\b(flex|grid|p-\d|m-\d|text-(sm|xs|lg)|bg-\w+)\b/)
+      expect(source, file).not.toMatch(
+        /\b(nota|ocorr\w+|motorista|viagem|carga|entrega|frete|cte|nf-?e|transport\w*|trip|driver)\b/i,
+      )
+    }
+  })
+
+  it('stay under 200 lines and use no any', () => {
+    for (const { file, source } of NEW_SOURCES) {
+      expect(source.split('\n').length, file).toBeLessThanOrEqual(200)
+      expect(source, file).not.toMatch(/:\s*any\b|\bas any\b|<any>/)
+    }
+  })
+
+  it('declare the new tokens in the public theming comment', () => {
+    const raw = readFileSync(join(import.meta.dir, '..', 'styles.css'), 'utf8')
+    expect(raw).toContain('--cv-p-tick, --cv-p-tick-read')
+    expect(PARTICIPANT_CSS).toContain('--cv-p-i-tick-read')
+  })
+})

package/src/participant/conversationThreadSummary.ts

@@ -0,0 +1,34 @@
+import type {
+  ParticipantConversationStatus,
+  ParticipantConversationSummary,
+  ParticipantSubjectRef,
+} from '@adatechnology/conversation-contracts'
+
+export type BuildThreadSummaryParams = {
+  readonly subject: ParticipantSubjectRef
+  readonly title: string
+  readonly protocol?: string
+  readonly channels?: ParticipantConversationSummary['channels']
+  readonly status?: ParticipantConversationStatus
+}
+
+/** The header reads a summary; a single conversation has no list to take it from, so the host's props build it. */
+export function buildThreadSummary({
+  subject,
+  title,
+  protocol,
+  channels,
+  status,
+}: BuildThreadSummaryParams): ParticipantConversationSummary {
+  return {
+    subjectType: subject.subjectType,
+    subjectId: subject.subjectId,
+    subjectLabel: title,
+    lastMessageAt: null,
+    unreadCount: 0,
+    awaitingParticipant: false,
+    status: status ?? 'open',
+    ...(protocol ? { protocol } : {}),
+    ...(channels ? { channels } : {}),
+  }
+}

package/src/participant/index.ts

@@ -1,4 +1,7 @@
 export { ParticipantConversations, type ParticipantConversationsProps } from './ParticipantConversations'
+export { ConversationThread, type ConversationThreadProps } from './ConversationThread'
+export type { ConversationThreadApi } from './conversationThreadApi'
+export type { ParticipantPerspective } from './participantPerspective'
 export type { ParticipantAuthorAvatarRenderer } from './ParticipantAuthorAvatar'
 export { groupParticipantConversations } from './participantGrouping'
 export { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS, type ParticipantConversationsLabels } from './participantLabels'

package/src/participant/participantContrast.test-helper.ts

@@ -0,0 +1,116 @@
+import { declarationsIn } from './participantCss.test-helper'
+
+export type Rgba = { readonly r: number; readonly g: number; readonly b: number; readonly a: number }
+
+export type TokenName =
+  'surface' | 'raised' | 'text' | 'muted' | 'border' | 'accent' | 'accentContrast' | 'highlight' | 'danger'
+
+export type Palette = Readonly<Record<TokenName, Rgba>>
+
+const TOKEN_VARIABLE: Record<TokenName, string> = {
+  surface: '--cv-p-surface',
+  raised: '--cv-p-surface-raised',
+  text: '--cv-p-text',
+  muted: '--cv-p-text-muted',
+  border: '--cv-p-border',
+  accent: '--cv-p-accent',
+  accentContrast: '--cv-p-accent-contrast',
+  highlight: '--cv-p-highlight',
+  danger: '--cv-p-danger',
+}
+
+export function parseColor(source: string): Rgba {
+  const hex = /^#([0-9a-f]{6})$/i.exec(source.trim())
+  if (hex?.[1]) {
+    const value = hex[1]
+    return {
+      r: parseInt(value.slice(0, 2), 16),
+      g: parseInt(value.slice(2, 4), 16),
+      b: parseInt(value.slice(4, 6), 16),
+      a: 1,
+    }
+  }
+  const functional = /^rgb\(\s*(\d+)\s+(\d+)\s+(\d+)\s*(?:\/\s*(\d+)%)?\s*\)$/.exec(source.trim())
+  if (!functional) throw new Error(`unsupported color: ${source}`)
+  return {
+    r: Number(functional[1]),
+    g: Number(functional[2]),
+    b: Number(functional[3]),
+    a: Number(functional[4] ?? 100) / 100,
+  }
+}
+
+/** Paints `top` over an opaque `base`; the result is opaque. */
+export function over(top: Rgba, base: Rgba): Rgba {
+  const mixChannel = (from: number, to: number): number => Math.round(from * top.a + to * (1 - top.a))
+  return { r: mixChannel(top.r, base.r), g: mixChannel(top.g, base.g), b: mixChannel(top.b, base.b), a: 1 }
+}
+
+/** What `color-mix(in srgb, top <percent>%, transparent)` paints over `base`. */
+export function tint(top: Rgba, percent: number, base: Rgba): Rgba {
+  return over({ ...top, a: top.a * (percent / 100) }, base)
+}
+
+function channelLuminance(channel: number): number {
+  const unit = channel / 255
+  return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4
+}
+
+function luminance(color: Rgba): number {
+  return 0.2126 * channelLuminance(color.r) + 0.7152 * channelLuminance(color.g) + 0.0722 * channelLuminance(color.b)
+}
+
+/** WCAG 2.x contrast ratio; both colors must already be opaque. */
+export function contrastRatio(first: Rgba, second: Rgba): number {
+  const [lighter, darker] = [luminance(first), luminance(second)].sort((left, right) => right - left)
+  return ((lighter ?? 0) + 0.05) / ((darker ?? 0) + 0.05)
+}
+
+function fallbackOf(declaration: string | undefined): string {
+  const match = /^var\(--cv-p-[a-z-]+,\s*(.+)\)$/.exec(declaration ?? '')
+  if (!match?.[1]) throw new Error(`no fallback in: ${declaration}`)
+  return match[1]
+}
+
+function internalVariable(token: TokenName): string {
+  return TOKEN_VARIABLE[token].replace('--cv-p-', '--cv-p-i-')
+}
+
+/** The default palette as styles.css declares it: the light one on `.cv-p`, the dark one on `.dark .cv-p`. */
+export function defaultPalette(theme: 'light' | 'dark'): Palette {
+  const light = declarationsIn('.cv-p')
+  const dark = theme === 'dark' ? declarationsIn('.dark .cv-p') : new Map<string, string>()
+  const entries = (Object.keys(TOKEN_VARIABLE) as TokenName[]).map((token) => {
+    const variable = internalVariable(token)
+    return [token, parseColor(fallbackOf(dark.get(variable) ?? light.get(variable)))] as const
+  })
+  return Object.fromEntries(entries) as Palette
+}
+
+/** A host mapping: only the tokens it sets; the rest keeps the light defaults, exactly as the cascade would. */
+export function mappedPalette(overrides: Partial<Record<TokenName, string>>): Palette {
+  const base = defaultPalette('light')
+  const entries = (Object.keys(base) as TokenName[]).map((token) => {
+    const override = overrides[token]
+    return [token, override ? parseColor(override) : base[token]] as const
+  })
+  return Object.fromEntries(entries) as Palette
+}
+
+/** Opaque version of the palette: translucent tokens are painted over the surface they sit on. */
+export function flatten(palette: Palette): Palette {
+  const entries = (Object.keys(palette) as TokenName[]).map(
+    (token) => [token, over(palette[token], palette.surface)] as const,
+  )
+  return Object.fromEntries(entries) as Palette
+}
+
+/** Default value of a standalone token declared on `.cv-p` or `.dark .cv-p` (for example the read tick). */
+export function declaredToken(name: string, theme: 'light' | 'dark'): string {
+  const value =
+    (theme === 'dark' ? declarationsIn('.dark .cv-p').get(name) : undefined) ?? declarationsIn('.cv-p').get(name)
+  if (!value) throw new Error(`token not declared: ${name}`)
+  return value
+}
+
+export { fallbackOf }

package/src/participant/participantGolden.test.tsx

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { beforeAll, describe, expect, it } from 'bun:test'
+
+import { ParticipantConversations } from './ParticipantConversations'
+import { ParticipantThread } from './ParticipantThread'
+import { renderGoldenScenarios, type GoldenComponents } from './participantGoldenScenarios.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+
+const FIXTURES_DIRECTORY = join(import.meta.dir, 'test-fixtures')
+
+function readGolden(name: string): string {
+  return readFileSync(join(FIXTURES_DIRECTORY, `${name}.golden.html`), 'utf8')
+}
+
+describe('participant default markup against the recorded origin/main output', () => {
+  let rendered: Record<string, string> = {}
+
+  beforeAll(() => {
+    process.env.TZ = 'UTC'
+    rendered = renderGoldenScenarios({
+      ParticipantThread,
+      ParticipantConversations,
+      labels: DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS,
+    } as unknown as GoldenComponents)
+  })
+
+  const scenarioNames = [
+    'thread-default',
+    'thread-plain',
+    'thread-avatars-initials',
+    'thread-tail-off',
+    'thread-error',
+    'thread-loading',
+    'thread-closed',
+    'conversations-list',
+    'conversations-selected',
+  ]
+
+  for (const name of scenarioNames) {
+    it(`${name} is byte-identical`, () => {
+      expect(rendered[name]).toBe(readGolden(name))
+    })
+  }
+})

package/src/participant/participantGoldenScenarios.test-helper.tsx

@@ -0,0 +1,57 @@
+import type { ComponentType } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { buildConversation, buildMessage } from './participantFixtures.test-helper'
+
+/** The components under comparison are injected so the same scenarios render against any checkout. */
+export type GoldenComponents = {
+  readonly ParticipantThread: ComponentType<Record<string, unknown>>
+  readonly ParticipantConversations: ComponentType<Record<string, unknown>>
+  readonly labels: unknown
+}
+
+const NOOP = (): void => undefined
+const SUBJECT_GROUPS = [{ subjectType: 'invoice', label: 'Invoices' }]
+
+const ITEMS = [
+  { kind: 'server', message: buildMessage({ id: 'a', direction: 'inbound', authorName: 'Ana Souza', text: '**oi** 11 98888-7777 a@b.com https://x.com', createdAt: '2026-10-01T12:00:00.000Z' }) },
+  { kind: 'server', message: buildMessage({ id: 'b', direction: 'outbound', authorName: 'Op', status: 'read', createdAt: '2026-10-01T12:05:00.000Z' }) },
+  { kind: 'server', message: buildMessage({ id: 'b2', direction: 'inbound', status: 'delivered', createdAt: '2026-10-02T12:05:00.000Z' }) },
+  { kind: 'pending', origin: 'local', displayState: 'failed', pending: { clientMessageId: 'c', subject: { subjectType: 'invoice', subjectId: '1' }, text: 'W', createdAt: '2026-10-02T12:06:00.000Z', state: 'failed' } },
+]
+
+function buildThreadProps(labels: unknown): Record<string, unknown> {
+  return {
+    conversation: buildConversation({ subjectId: '1', subjectLabel: 'Invoice 4521', protocol: 'P-1', channels: ['app', 'whatsapp'] }),
+    items: ITEMS, hasMore: true, onLoadOlder: NOOP, labels, resolveAttachmentUrl: async () => 'x',
+    draft: { value: 'abc', onChange: NOOP, files: [], onFilesChange: NOOP }, onSend: NOOP, status: 'ready', refresh: NOOP,
+    scroll: { ref: { current: null }, onScroll: NOOP, isAwayFromBottom: true, scrollToLatest: NOOP },
+    newMessagesCount: 2, isSending: false, onBack: NOOP,
+    pendingActions: { retryLocal: NOOP, discardLocal: NOOP, editLocal: NOOP },
+    quickReplies: [{ id: '1', title: 'T', shortcut: 't', body: 'b' }],
+  }
+}
+
+const THREAD_VARIANTS: Record<string, Record<string, unknown>> = {
+  'thread-default': {},
+  'thread-plain': { hasMore: false, newMessagesCount: 0, quickReplies: [], scroll: { ref: { current: null }, onScroll: NOOP, isAwayFromBottom: false, scrollToLatest: NOOP }, items: ITEMS.slice(0, 2) },
+  'thread-avatars-initials': { avatars: 'initials' },
+  'thread-tail-off': { tail: false },
+  'thread-error': { status: 'error', items: [] },
+  'thread-loading': { status: 'loading', items: [] },
+  'thread-closed': { conversation: buildConversation({ subjectId: '2', status: 'closed' }) },
+}
+
+export function renderGoldenScenarios({ ParticipantThread, ParticipantConversations, labels }: GoldenComponents): Record<string, string> {
+  const base = buildThreadProps(labels)
+  const html: Record<string, string> = {}
+  for (const [name, extra] of Object.entries(THREAD_VARIANTS)) {
+    html[name] = renderToStaticMarkup(<ParticipantThread {...base} {...extra} />)
+  }
+  const api = { listConversations: async () => ({ data: [] }), fetchMessages: async () => [], sendMessage: async () => ({ outcome: 'queued' }), markRead: async () => undefined, resolveAttachmentUrl: async () => 'x' }
+  html['conversations-list'] = renderToStaticMarkup(<ParticipantConversations api={api} subjectGroups={SUBJECT_GROUPS} />)
+  html['conversations-selected'] = renderToStaticMarkup(
+    <ParticipantConversations api={api} subjectGroups={SUBJECT_GROUPS} selected={{ subjectType: 'invoice', subjectId: '1' }} />,
+  )
+  return html
+}

package/src/participant/participantMessages.ts

@@ -1,6 +1,7 @@
 import type { MessageDeliveryStatus, ParticipantMessage, ParticipantSubjectRef } from '@adatechnology/conversation-contracts'
 
 import type { ParticipantLocalPendingMessage, ParticipantPendingMessage } from './participantApi.types'
+import { isMessageMine, type ParticipantPerspective } from './participantPerspective'
 
 export type ParticipantPendingDisplayState = 'sending' | 'queued' | 'failed' | 'sent'
 export type ParticipantOwnMessageStatus = 'sending' | 'queued' | 'sent' | 'delivered' | 'read' | 'failed'
@@ -58,9 +59,9 @@ export function mergeParticipantMessages(params: MergeParticipantMessagesParams)
   return items.sort((left, right) => createdAtOf(left) - createdAtOf(right))
 }
 
-/** Direction is from the company perspective: the participant is the inbound side. */
-export function isOwnMessage(message: ParticipantMessage): boolean {
-  return message.direction === 'inbound'
+/** Direction is from the company side: the participant is the inbound side, the operator the outbound one. */
+export function isOwnMessage(message: ParticipantMessage, perspective?: ParticipantPerspective): boolean {
+  return isMessageMine(message, perspective)
 }
 
 export function resolveOwnMessageStatus(params: ResolveOwnMessageStatusParams): ParticipantOwnMessageStatus {

package/src/participant/participantNewMessages.test.ts

@@ -52,3 +52,24 @@ describe('collectServerMessageIds', () => {
     expect([...collectServerMessageIds([server('a', 'inbound'), server('b', 'outbound')])]).toEqual(['a', 'b'])
   })
 })
+
+describe('countNewIncomingMessages with the operator perspective', () => {
+  const seen = [server('s', 'inbound', '2026-10-01T10:00:00.000Z')]
+  const seenIds = collectServerMessageIds(seen)
+
+  it('counts a new inbound message as news', () => {
+    const items = [...seen, server('n', 'inbound', '2026-10-01T10:05:00.000Z')]
+    expect(countNewIncomingMessages(seenIds, items, 'operator')).toBe(1)
+  })
+
+  it('does not count a new outbound message (written by the operator)', () => {
+    const items = [...seen, server('n', 'outbound', '2026-10-01T10:05:00.000Z')]
+    expect(countNewIncomingMessages(seenIds, items, 'operator')).toBe(0)
+  })
+
+  it('keeps the participant behavior when the perspective is omitted or participant', () => {
+    const items = [...seen, server('n', 'outbound', '2026-10-01T10:05:00.000Z'), server('m', 'inbound', '2026-10-01T10:06:00.000Z')]
+    expect(countNewIncomingMessages(seenIds, items)).toBe(1)
+    expect(countNewIncomingMessages(seenIds, items, 'participant')).toBe(1)
+  })
+})

package/src/participant/participantNewMessages.ts

@@ -1,4 +1,5 @@
 import type { ParticipantTimelineItem } from './participantMessages'
+import { isMessageMine, type ParticipantPerspective } from './participantPerspective'
 
 export function collectServerMessageIds(items: readonly ParticipantTimelineItem[]): ReadonlySet<string> {
   const ids = new Set<string>()
@@ -16,13 +17,17 @@ function latestSeenTime(previousIds: ReadonlySet<string>, items: readonly Partic
   return latest
 }
 
-/** Messages from the other side ('outbound') newer than what the participant has seen; older history loaded above is not news. */
-export function countNewIncomingMessages(previousIds: ReadonlySet<string>, currentItems: readonly ParticipantTimelineItem[]): number {
+/** Messages from the other side of the viewer's perspective newer than what the participant has seen; older history loaded above is not news. */
+export function countNewIncomingMessages(
+  previousIds: ReadonlySet<string>,
+  currentItems: readonly ParticipantTimelineItem[],
+  perspective?: ParticipantPerspective,
+): number {
   const latestSeen = latestSeenTime(previousIds, currentItems)
   return currentItems.filter(
     (item) =>
       item.kind === 'server' &&
-      item.message.direction === 'outbound' &&
+      !isMessageMine(item.message, perspective) &&
       !previousIds.has(item.message.id) &&
       Date.parse(item.message.createdAt) > latestSeen,
   ).length

package/src/participant/participantPerspective.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildMessage } from './participantFixtures.test-helper'
+import { isOwnMessage } from './participantMessages'
+import {
+  countOtherSideMessages,
+  countUnreadByViewer,
+  isMessageMine,
+  resolveViewerUnread,
+} from './participantPerspective'
+
+const INBOUND = buildMessage({ id: 'i', direction: 'inbound' })
+const OUTBOUND = buildMessage({ id: 'o', direction: 'outbound' })
+
+describe('isMessageMine', () => {
+  it('treats inbound as mine for the participant, and by default', () => {
+    expect(isMessageMine(INBOUND, 'participant')).toBe(true)
+    expect(isMessageMine(OUTBOUND, 'participant')).toBe(false)
+    expect(isMessageMine(INBOUND)).toBe(true)
+    expect(isMessageMine(OUTBOUND)).toBe(false)
+  })
+
+  it('inverts for the operator: outbound is mine', () => {
+    expect(isMessageMine(OUTBOUND, 'operator')).toBe(true)
+    expect(isMessageMine(INBOUND, 'operator')).toBe(false)
+  })
+
+  it('keeps isOwnMessage identical without a perspective', () => {
+    expect(isOwnMessage(INBOUND)).toBe(true)
+    expect(isOwnMessage(OUTBOUND)).toBe(false)
+    expect(isOwnMessage(OUTBOUND, 'operator')).toBe(true)
+  })
+})
+
+describe('unread by the viewer', () => {
+  const MESSAGES = [
+    buildMessage({ id: 'a', direction: 'inbound' }),
+    buildMessage({ id: 'b', direction: 'inbound', status: 'read' }),
+    buildMessage({ id: 'c', direction: 'inbound', readAt: '2026-10-01T11:00:00.000Z' }),
+    buildMessage({ id: 'd', direction: 'outbound' }),
+    buildMessage({ id: 'e', direction: 'outbound' }),
+  ]
+
+  it('counts only the other side, never the viewer own messages', () => {
+    expect(countUnreadByViewer(MESSAGES, 'operator')).toBe(1)
+    expect(countUnreadByViewer(MESSAGES, 'participant')).toBe(2)
+    expect(countOtherSideMessages(MESSAGES, 'operator')).toBe(3)
+    expect(countOtherSideMessages(MESSAGES, 'participant')).toBe(2)
+  })
+
+  it('reads nothing as unread when the operator has only outbound messages', () => {
+    expect(countUnreadByViewer([OUTBOUND, OUTBOUND], 'operator')).toBe(0)
+  })
+
+  it('resolves to zero until something new arrives after the acknowledgement', () => {
+    const base = { messages: MESSAGES, perspective: 'operator' } as const
+    expect(resolveViewerUnread({ ...base, acknowledgedCount: 0 })).toBe(1)
+    expect(resolveViewerUnread({ ...base, acknowledgedCount: 3 })).toBe(0)
+    expect(
+      resolveViewerUnread({
+        ...base,
+        messages: [...MESSAGES, buildMessage({ id: 'f', direction: 'inbound' })],
+        acknowledgedCount: 3,
+      }),
+    ).toBe(2)
+  })
+})