@adatechnology/conversations-ui 0.6.0 → 0.7.0

package/src/participant/participantMessageInline.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'bun:test'
+
+import { show } from './participantMessageFormat.test-helper'
+import { parseInline } from './participantMessageInline'
+
+function inline(line: string): string {
+  return show(parseInline(line))
+}
+
+describe('parseInline - basic marks', () => {
+  it('formats bold, italic, strike and inline code', () => {
+    expect(inline('*a b*')).toBe('⟦s:a b⟧')
+    expect(inline('x *a* y')).toBe('x ⟦s:a⟧ y')
+    expect(inline('_a b_')).toBe('⟦e:a b⟧')
+    expect(inline('~a b~')).toBe('⟦d:a b⟧')
+    expect(inline('`a b`')).toBe('⟦c:a b⟧')
+    expect(inline('oi *tudo* _bem_ ~mal~ `ok`')).toBe('oi ⟦s:tudo⟧ ⟦e:bem⟧ ⟦d:mal⟧ ⟦c:ok⟧')
+  })
+
+  it('formats marks that touch punctuation', () => {
+    expect(inline('(*a*)')).toBe('(⟦s:a⟧)')
+    expect(inline('*a*, _b_.')).toBe('⟦s:a⟧, ⟦e:b⟧.')
+  })
+
+  it('treats triple backticks in the middle of a line as inline code', () => {
+    expect(inline('veja ```x y``` aqui')).toBe('veja ⟦c:x y⟧ aqui')
+  })
+})
+
+describe('parseInline - nesting', () => {
+  it('nests valid combinations in both orders', () => {
+    expect(inline('*_negrito itálico_*')).toBe('⟦s:⟦e:negrito itálico⟧⟧')
+    expect(inline('_*assim*_')).toBe('⟦e:⟦s:assim⟧⟧')
+    expect(inline('~*_x_*~')).toBe('⟦d:⟦s:⟦e:x⟧⟧⟧')
+    expect(inline('*a _b_ c*')).toBe('⟦s:a ⟦e:b⟧ c⟧')
+  })
+
+  it('does not let crossing marks form invalid trees', () => {
+    expect(inline('*a _b* c_')).toBe('⟦s:a _b⟧ c_')
+    expect(inline('_a *b_ c*')).toBe('⟦e:a *b⟧ c*')
+  })
+
+  it('keeps code inside marks and never formats inside code', () => {
+    expect(inline('*a `b` c*')).toBe('⟦s:a ⟦c:b⟧ c⟧')
+    expect(inline('`*a*`')).toBe('⟦c:*a*⟧')
+    expect(inline('`_a_ ~b~`')).toBe('⟦c:_a_ ~b~⟧')
+  })
+})
+
+describe('parseInline - loose markers', () => {
+  it('does not format when the marker is glued to whitespace', () => {
+    expect(inline('* a *')).toBe('* a *')
+    expect(inline('2 * 3 * 4')).toBe('2 * 3 * 4')
+    expect(inline('_ a _')).toBe('_ a _')
+    expect(inline('~ a ~')).toBe('~ a ~')
+  })
+
+  it('does not format inside a word', () => {
+    expect(inline('snake_case_nome')).toBe('snake_case_nome')
+    expect(inline('a*b*c')).toBe('a*b*c')
+    expect(inline('2*3*4')).toBe('2*3*4')
+  })
+
+  it('leaves unmatched and empty markers alone', () => {
+    expect(inline('*a')).toBe('*a')
+    expect(inline('a*')).toBe('a*')
+    expect(inline('**')).toBe('**')
+    expect(inline('__')).toBe('__')
+    expect(inline('``')).toBe('``')
+    expect(inline('`aberto')).toBe('`aberto')
+  })
+})
+
+describe('parseInline - emoji', () => {
+  it('keeps ZWJ sequences, flags, skin tones and variation selectors intact', () => {
+    expect(inline('*👨‍👩‍👧*')).toBe('⟦s:👨‍👩‍👧⟧')
+    expect(inline('🇧🇷 _oi_')).toBe('🇧🇷 ⟦e:oi⟧')
+    expect(inline('👍🏽*x*')).toBe('👍🏽⟦s:x⟧')
+    expect(inline('‼️ ~não~')).toBe('‼️ ⟦d:não⟧')
+    expect(inline('👨‍👩‍👧 🇧🇷 👍🏽 ‼️')).toBe('👨‍👩‍👧 🇧🇷 👍🏽 ‼️')
+  })
+})

package/src/participant/participantMessageInline.ts

@@ -0,0 +1,99 @@
+import { findInlineAtoms } from './participantMessageAtoms'
+import type { InlineAtom, InlineNode } from './participantMessageFormat.types'
+
+type MarkKind = 'strong' | 'em' | 'del'
+
+const MARKS: Readonly<Record<string, MarkKind>> = { '*': 'strong', _: 'em', '~': 'del' }
+
+type LineContext = {
+  readonly text: string
+  readonly atomAt: ReadonlyMap<number, InlineAtom>
+  readonly isMasked: readonly boolean[]
+  readonly closers: Readonly<Record<string, readonly number[]>>
+}
+
+function isWord(character: string | undefined): boolean {
+  return character !== undefined && /[\p{L}\p{N}]/u.test(character)
+}
+
+function isSpace(character: string | undefined): boolean {
+  return character === undefined || /\s/u.test(character)
+}
+
+function characterBefore(text: string, index: number): string | undefined {
+  if (index <= 0) return undefined
+  const code = text.charCodeAt(index - 1)
+  const isLowSurrogate = code >= 0xdc00 && code <= 0xdfff
+  if (isLowSurrogate && index >= 2) return String.fromCodePoint(text.codePointAt(index - 2) ?? code)
+  return text.charAt(index - 1)
+}
+
+function buildContext(text: string): LineContext {
+  const atoms = findInlineAtoms(text)
+  const isMasked: boolean[] = new Array<boolean>(text.length).fill(false)
+  for (const atom of atoms) isMasked.fill(true, atom.start, atom.end)
+  const closers: Record<string, number[]> = { '*': [], _: [], '~': [] }
+  for (let index = 1; index < text.length; index += 1) {
+    const character = text.charAt(index)
+    const list = closers[character]
+    const isCloser = list !== undefined && !isMasked[index] && !isSpace(text[index - 1]) && !isWord(text[index + 1])
+    if (isCloser) list.push(index)
+  }
+  return { text, atomAt: new Map(atoms.map((atom) => [atom.start, atom])), isMasked, closers }
+}
+
+function isOpener(context: LineContext, index: number): boolean {
+  const { text } = context
+  const next = text[index + 1]
+  if (context.isMasked[index] || next === undefined || isSpace(next) || next === text[index]) return false
+  return !isWord(characterBefore(text, index))
+}
+
+function findCloser(context: LineContext, mark: string, from: number, limit: number): number | undefined {
+  const list = context.closers[mark] ?? []
+  let low = 0
+  let high = list.length
+  while (low < high) {
+    const middle = (low + high) >> 1
+    if ((list[middle] ?? 0) < from) low = middle + 1
+    else high = middle
+  }
+  const found = list[low]
+  return found !== undefined && found < limit ? found : undefined
+}
+
+function parseRange(context: LineContext, start: number, end: number): InlineNode[] {
+  const nodes: InlineNode[] = []
+  let textStart = start
+  let index = start
+  const flush = (until: number): void => {
+    if (until > textStart) nodes.push({ kind: 'text', value: context.text.slice(textStart, until) })
+  }
+  while (index < end) {
+    const atom = context.atomAt.get(index)
+    const mark = MARKS[context.text.charAt(index)]
+    const closer =
+      mark !== undefined && !atom && isOpener(context, index)
+        ? findCloser(context, context.text.charAt(index), index + 2, end)
+        : undefined
+    if (atom) {
+      flush(index)
+      nodes.push(atom.node)
+      index = atom.end
+    } else if (mark !== undefined && closer !== undefined) {
+      flush(index)
+      nodes.push({ kind: mark, children: parseRange(context, index + 1, closer) })
+      index = closer + 1
+    } else {
+      index += 1
+      continue
+    }
+    textStart = index
+  }
+  flush(end)
+  return nodes
+}
+
+export function parseInline(line: string): InlineNode[] {
+  return parseRange(buildContext(line), 0, line.length)
+}

package/src/participant/participantMessageLinks.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'bun:test'
+
+import { show } from './participantMessageFormat.test-helper'
+import { isAllowedLinkHref } from './participantMessageLinks'
+import { parseInline } from './participantMessageInline'
+
+function inline(line: string): string {
+  return show(parseInline(line))
+}
+
+describe('isAllowedLinkHref', () => {
+  it('accepts only http, https, mailto and tel', () => {
+    expect(isAllowedLinkHref('http://a.com')).toBe(true)
+    expect(isAllowedLinkHref('https://a.com/x?y=1')).toBe(true)
+    expect(isAllowedLinkHref('HTTPS://A.COM')).toBe(true)
+    expect(isAllowedLinkHref('mailto:a@b.co')).toBe(true)
+    expect(isAllowedLinkHref('tel:+5511987654321')).toBe(true)
+  })
+
+  it('rejects every other protocol and non-URLs', () => {
+    expect(isAllowedLinkHref('javascript:alert(1)')).toBe(false)
+    expect(isAllowedLinkHref(' javascript:alert(1)')).toBe(false)
+    expect(isAllowedLinkHref('JaVaScRiPt:alert(1)')).toBe(false)
+    expect(isAllowedLinkHref('data:text/html,<b>x</b>')).toBe(false)
+    expect(isAllowedLinkHref('vbscript:x')).toBe(false)
+    expect(isAllowedLinkHref('file:///etc/passwd')).toBe(false)
+    expect(isAllowedLinkHref('ftp://a.com')).toBe(false)
+    expect(isAllowedLinkHref('//a.com')).toBe(false)
+    expect(isAllowedLinkHref('/relativo')).toBe(false)
+    expect(isAllowedLinkHref('')).toBe(false)
+  })
+})
+
+describe('autolink - http and https', () => {
+  it('links plain URLs and keeps the literal as the label', () => {
+    expect(inline('veja https://a.com/x agora')).toBe('veja ⟦l:https://a.com/x→https://a.com/x⟧ agora')
+    expect(inline('http://a.com')).toBe('⟦l:http://a.com→http://a.com⟧')
+  })
+
+  it('keeps trailing punctuation outside the link', () => {
+    expect(inline('https://a.com.')).toBe('⟦l:https://a.com→https://a.com⟧.')
+    expect(inline('https://a.com,')).toBe('⟦l:https://a.com→https://a.com⟧,')
+    expect(inline('https://a.com;')).toBe('⟦l:https://a.com→https://a.com⟧;')
+    expect(inline('https://a.com:')).toBe('⟦l:https://a.com→https://a.com⟧:')
+    expect(inline('https://a.com!')).toBe('⟦l:https://a.com→https://a.com⟧!')
+    expect(inline('https://a.com?')).toBe('⟦l:https://a.com→https://a.com⟧?')
+    expect(inline('https://a.com/x...')).toBe('⟦l:https://a.com/x→https://a.com/x⟧...')
+  })
+
+  it('keeps balanced parentheses inside and drops the unbalanced one', () => {
+    expect(inline('(veja https://a.com/p)')).toBe('(veja ⟦l:https://a.com/p→https://a.com/p⟧)')
+    expect(inline('https://a.com/p_(x)')).toBe('⟦l:https://a.com/p_(x)→https://a.com/p_(x)⟧')
+    expect(inline('(https://a.com/p_(x))')).toBe('(⟦l:https://a.com/p_(x)→https://a.com/p_(x)⟧)')
+  })
+
+  it('keeps query strings and ampersands', () => {
+    expect(inline('https://a.com/?a=1&b=2')).toBe('⟦l:https://a.com/?a=1&b=2→https://a.com/?a=1&b=2⟧')
+  })
+
+  it('accepts an uppercase scheme, normalising only the scheme of the href', () => {
+    expect(inline('HTTP://MAIUSCULO')).toBe('⟦l:HTTP://MAIUSCULO→http://MAIUSCULO⟧')
+  })
+
+  it('does not format marks inside a URL, but a mark may wrap it', () => {
+    expect(inline('https://a.com/_x_/~y~/*z*')).toBe('⟦l:https://a.com/_x_/~y~/*z→https://a.com/_x_/~y~/*z⟧*')
+    expect(inline('*https://a.com*')).toBe('⟦s:⟦l:https://a.com→https://a.com⟧⟧')
+  })
+
+  it('does not link a scheme with nothing after it, nor inside code', () => {
+    expect(inline('https://')).toBe('https://')
+    expect(inline('`https://a.com`')).toBe('⟦c:https://a.com⟧')
+  })
+})
+
+describe('autolink - unsafe protocols stay text', () => {
+  it('never links javascript, data or vbscript', () => {
+    expect(inline('javascript:alert(1)')).toBe('javascript:alert(1)')
+    expect(inline('data:text/html,<script>alert(1)</script>')).toBe('data:text/html,<script>alert(1)</script>')
+    expect(inline('vbscript:msgbox(1)')).toBe('vbscript:msgbox(1)')
+    expect(inline('clique: javascript://%0aalert(1)')).toBe('clique: javascript://%0aalert(1)')
+  })
+})
+
+describe('autolink - cost and userinfo', () => {
+  it('trims a long run of closing parentheses in linear time', () => {
+    const started = performance.now()
+    inline(`https://a${')'.repeat(7990)}`)
+    expect(performance.now() - started).toBeLessThan(20)
+  })
+
+  it('still balances parentheses', () => {
+    expect(inline('https://a.com/x_(y))')).toBe('⟦l:https://a.com/x_(y)→https://a.com/x_(y)⟧)')
+  })
+
+  it('leaves a link with credentials as text', () => {
+    expect(isAllowedLinkHref('https://user:pass@a.com')).toBe(false)
+    expect(isAllowedLinkHref('https://user@a.com')).toBe(false)
+    expect(inline('https://user:pass@a.com/x')).not.toContain('⟦l:')
+  })
+})

package/src/participant/participantMessageLinks.ts

@@ -0,0 +1,54 @@
+import type { InlineAtom } from './participantMessageFormat.types'
+
+const ALLOWED_LINK_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+const URL_PATTERN = /https?:\/\/[^\s<>`\u0000-\u001f]+/giu
+const TRAILING_PUNCTUATION = '.,;:!?*_~\'"]}>'
+
+export function isAllowedLinkHref(href: string): boolean {
+  try {
+    const url = new URL(href)
+    return ALLOWED_LINK_PROTOCOLS.has(url.protocol) && url.username === '' && url.password === ''
+  } catch {
+    return false
+  }
+}
+
+function isAlphanumeric(character: string | undefined): boolean {
+  return character !== undefined && /[\p{L}\p{N}]/u.test(character)
+}
+
+function countOf(text: string, character: string): number {
+  let count = 0
+  for (const current of text) if (current === character) count += 1
+  return count
+}
+
+function trimUrl(raw: string): string {
+  let openCount = countOf(raw, '(')
+  let closeCount = countOf(raw, ')')
+  let end = raw.length
+  while (end > 0) {
+    const last = raw.charAt(end - 1)
+    if (last === ')' && closeCount > openCount) closeCount -= 1
+    else if (!TRAILING_PUNCTUATION.includes(last)) break
+    end -= 1
+  }
+  return raw.slice(0, end)
+}
+
+function toLinkAtom(text: string, start: number, raw: string): InlineAtom | undefined {
+  const label = trimUrl(raw)
+  if (/^https?:\/\/$/i.test(label) || isAlphanumeric(text[start - 1])) return undefined
+  const href = label.replace(/^https?/i, (scheme) => scheme.toLowerCase())
+  if (!isAllowedLinkHref(href)) return undefined
+  return { start, end: start + label.length, node: { kind: 'link', href, label } }
+}
+
+export function findLinkAtoms(text: string): InlineAtom[] {
+  const atoms: InlineAtom[] = []
+  for (const match of text.matchAll(URL_PATTERN)) {
+    const atom = toLinkAtom(text, match.index, match[0])
+    if (atom) atoms.push(atom)
+  }
+  return atoms
+}

package/src/participant/participantMessageTextStyle.test.ts

@@ -0,0 +1,137 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { splitBlocks } from '../cssBlocks.test-helper'
+import { PARTICIPANT_CSS, declarationsIn } from './participantCss.test-helper'
+
+const TEXT_SELECTOR = /\.cv-p-(text|copyable)/
+
+function collectBlocks(css: string): string[] {
+  return splitBlocks(css).flatMap(({ prelude, body }) => {
+    if (body === undefined) return []
+    if (prelude.startsWith('@media')) return collectBlocks(body)
+    return TEXT_SELECTOR.test(prelude) ? [`${prelude} {${body}}`] : []
+  })
+}
+
+function forcedColorsBody(): string {
+  return splitBlocks(PARTICIPANT_CSS)
+    .filter(({ prelude }) => prelude === '@media (forced-colors: active)')
+    .map(({ body }) => body ?? '')
+    .join('\n')
+}
+
+const TEXT_CSS = collectBlocks(PARTICIPANT_CSS).join('\n')
+
+describe('participant message text - stylesheet', () => {
+  it('has rules for the text, the code, the block, the quote and the tokens', () => {
+    expect(collectBlocks(PARTICIPANT_CSS).length).toBeGreaterThan(12)
+  })
+
+  it('uses no fixed colour and no url()', () => {
+    expect(TEXT_CSS).not.toMatch(/#[0-9a-f]{3,8}\b/i)
+    expect(TEXT_CSS).not.toMatch(/\b(rgb|rgba|hsl|hsla)\(/i)
+    expect(TEXT_CSS).not.toContain('url(')
+  })
+
+  it('keeps the text selectable and the typography of the old text', () => {
+    const text = declarationsIn('.cv-p-text')
+    expect(text.get('user-select')).toBe('text')
+    expect(text.get('white-space')).toBe('pre-wrap')
+    expect(text.get('font-size')).toBe('14.2px')
+    expect(text.get('line-height')).toBe('19px')
+  })
+
+  it('styles inline code and the block from the tokens', () => {
+    expect(declarationsIn('.cv-p-text__code').get('background')).toBe(
+      declarationsIn('.cv-p-text__pre').get('background'),
+    )
+    expect(declarationsIn('.cv-p-text__code').get('background')).toContain('color-mix(in srgb, var(--cv-p-i-border)')
+    expect(declarationsIn('.cv-p-text__code').get('border-radius')).toBe('var(--cv-p-i-radius)')
+    const pre = declarationsIn('.cv-p-text__pre')
+    expect(pre.get('overflow-x')).toBe('auto')
+    expect(pre.get('white-space')).toBe('pre')
+    expect(pre.get('border-inline-start')).toBe('2px solid var(--cv-p-i-accent)')
+    expect(pre.get('scrollbar-color')).toBe('var(--cv-p-i-scrollbar-thumb) transparent')
+  })
+
+  it('styles the quote, the lists and the links from the tokens', () => {
+    const quote = declarationsIn('.cv-p-text__quote')
+    expect(quote.get('border-inline-start')).toBe('3px solid var(--cv-p-i-border)')
+    expect(quote.get('color')).toBe('var(--cv-p-i-text-muted)')
+    expect(declarationsIn('.cv-p-text__list').get('padding-inline-start')).toBe('1.25rem')
+    const link = declarationsIn('.cv-p-text__link')
+    expect(link.get('color')).toBe('var(--cv-p-i-accent)')
+    expect(link.get('text-decoration')).toBe('underline')
+    expect(link.get('overflow-wrap')).toBe('anywhere')
+    expect(declarationsIn('.cv-p-text__link:focus-visible').get('outline')).toBe('2px solid var(--cv-p-i-accent)')
+  })
+
+  it('highlights tokens discreetly with the accent', () => {
+    const token = declarationsIn('.cv-p-copyable')
+    expect(token.get('background')).toBe('color-mix(in srgb, var(--cv-p-i-accent) 14%, transparent)')
+    expect(token.get('border-bottom')).toBe('1px dotted var(--cv-p-i-accent)')
+    expect(token.get('font-family')).toContain('monospace')
+    expect(token.get('border-radius')).toBe('var(--cv-p-i-radius)')
+    expect(token.get('user-select')).toBe('text')
+  })
+
+  it('keeps the tap target of tokens and the copy icon from invading neighbouring lines or the link text', () => {
+    expect(declarationsIn('.cv-p').get('--cv-p-i-touch')).toBe('2.75rem')
+    for (const selector of ['.cv-p-copyable::after', '.cv-p-text__link-copy::after']) {
+      expect(declarationsIn(selector).get('min-height')).toBe('1.5rem')
+    }
+    const icon = declarationsIn('.cv-p-text__link-copy::after')
+    expect(icon.get('inset-inline')).toBe('0 auto')
+    expect(icon.get('min-width')).toBe('var(--cv-p-i-touch)')
+    expect(icon.get('margin-inline-start')).toBeUndefined()
+    expect(declarationsIn('.cv-p-copyable').get('display')).toBe('inline')
+    expect(declarationsIn('.cv-p-copyable').get('position')).toBe('relative')
+  })
+
+  it('gets borders instead of backgrounds under forced colors', () => {
+    const forced = forcedColorsBody()
+    expect(forced).toContain('.cv-p-copyable')
+    expect(forced).toContain('.cv-p-text__pre')
+    expect(declarationsIn('.cv-p-copyable', forced).get('border')).toBe('1px solid')
+    expect(declarationsIn('.cv-p-copyable', forced).get('background')).toBe('none')
+  })
+})
+
+describe('participant message text - hygiene', () => {
+  const FILES = [
+    'participantMessageFormat.ts',
+    'participantMessageInline.ts',
+    'participantMessageAtoms.ts',
+    'participantMessageLinks.ts',
+    'participantMessageCopyables.ts',
+    'participantDocuments.ts',
+    'ParticipantMessageText.tsx',
+    'ParticipantMessageNodes.tsx',
+    'ParticipantCopyableToken.tsx',
+    'ParticipantCopyAnnouncer.tsx',
+    'useParticipantCopyFeedback.ts',
+  ] as const
+  const sources = FILES.map((file) => ({ file, source: readFileSync(join(import.meta.dir, file), 'utf8') }))
+
+  it('stays within 200 lines per file', () => {
+    for (const { file, source } of sources) {
+      expect({ file, ok: source.split('\n').length <= 200 }).toEqual({ file, ok: true })
+    }
+  })
+
+  it('never sets inner HTML, never uses any, never reuses the shared MessageText', () => {
+    for (const { source } of sources) {
+      expect(source).not.toMatch(/innerHTML|dangerouslySetInnerHTML|:\s*any\b|as any|MessageText\b.*from '\.\.\//)
+      expect(source).not.toContain('whatsapp-formatting')
+    }
+  })
+
+  it('has no Tailwind utilities and no vocabulary from a specific product', () => {
+    for (const { source } of sources) {
+      expect(source).not.toMatch(/className="[^"]*\b(flex|grid|p-\d|m-\d|text-(sm|xs|lg)|bg-\w+)\b/)
+      expect(source).not.toMatch(/\b(carga|entrega|frete|cte|nf-?e|transport\w*|motorista|viagem|trip|driver)\b/i)
+    }
+  })
+})

package/src/participant/participantScrollFocus.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test'
+
+import { SCROLLER_SELECTOR, focusScrollerOf } from './participantScrollFocus'
+
+describe('focusScrollerOf', () => {
+  it('moves focus to the scroller ancestor without scrolling it', () => {
+    const calls: unknown[] = []
+    const selectors: string[] = []
+    focusScrollerOf({
+      closest: (selector) => {
+        selectors.push(selector)
+        return { focus: (options) => void calls.push(options) }
+      },
+    })
+    expect(selectors).toEqual([SCROLLER_SELECTOR])
+    expect(calls).toEqual([{ preventScroll: true }])
+  })
+
+  it('does nothing when there is no scroller', () => {
+    expect(() => focusScrollerOf({ closest: () => null })).not.toThrow()
+  })
+})

package/src/participant/participantScrollFocus.ts

@@ -0,0 +1,10 @@
+export type FocusableAncestorSource = {
+  readonly closest: (selector: string) => { readonly focus: (options: { preventScroll: boolean }) => void } | null
+}
+
+export const SCROLLER_SELECTOR = '.cv-p-thread__scroll'
+
+/** The button unmounts on click; moving focus first keeps it from falling to the body. */
+export function focusScrollerOf(button: FocusableAncestorSource): void {
+  button.closest(SCROLLER_SELECTOR)?.focus({ preventScroll: true })
+}

package/src/participant/participantScrollView.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { resolveScrollToLatestView, scrollIntoViewOptions, scrollToLatestOptions } from './participantScrollView'
+
+describe('resolveScrollToLatestView', () => {
+  it('is hidden while the reader is near the end', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: false, newMessagesCount: 0, hasMessages: true })).toEqual({
+      isVisible: false,
+      badge: undefined,
+    })
+  })
+
+  it('is hidden when there is nothing to scroll to', () => {
+    expect(
+      resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 0, hasMessages: false }).isVisible,
+    ).toBe(false)
+  })
+
+  it('is visible without a badge when away and nothing new arrived', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 0, hasMessages: true })).toEqual({
+      isVisible: true,
+      badge: undefined,
+    })
+  })
+
+  it('carries the count of new incoming messages as the badge', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 3, hasMessages: true }).badge).toBe(
+      '3',
+    )
+  })
+
+  it('caps a large count', () => {
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 100, hasMessages: true }).badge).toBe(
+      '99+',
+    )
+    expect(resolveScrollToLatestView({ isAwayFromBottom: true, newMessagesCount: 99, hasMessages: true }).badge).toBe(
+      '99',
+    )
+  })
+})
+
+describe('scroll options', () => {
+  it('scrolls to the end of the list, smooth only without reduced motion', () => {
+    expect(scrollToLatestOptions({ scrollHeight: 900, isReducedMotion: false })).toEqual({
+      top: 900,
+      behavior: 'smooth',
+    })
+    expect(scrollToLatestOptions({ scrollHeight: 900, isReducedMotion: true })).toEqual({ top: 900, behavior: 'auto' })
+  })
+
+  it('reveals the active chip with the nearest rule and no animation under reduced motion', () => {
+    expect(scrollIntoViewOptions(false)).toEqual({ block: 'nearest', inline: 'nearest', behavior: 'smooth' })
+    expect(scrollIntoViewOptions(true)).toEqual({ block: 'nearest', inline: 'nearest', behavior: 'auto' })
+  })
+})
+
+describe('the near-the-end threshold has one owner', () => {
+  it('is declared only in participantScroll.ts', () => {
+    const sources = readdirSync(import.meta.dir).filter(
+      (name) => /\.tsx?$/.test(name) && !/\.test(-helper)?\.tsx?$/.test(name),
+    )
+    const declaring = sources.filter((name) =>
+      /NEAR_BOTTOM_THRESHOLD_PX\s*=/.test(readFileSync(join(import.meta.dir, name), 'utf8')),
+    )
+    expect(declaring).toEqual(['participantScroll.ts'])
+  })
+
+  it('is not re-derived by the scroll-to-latest rule', () => {
+    const source = readFileSync(join(import.meta.dir, 'participantScrollView.ts'), 'utf8')
+    expect(source).not.toMatch(/scrollTop|clientHeight|threshold/i)
+  })
+})

package/src/participant/participantScrollView.ts

@@ -0,0 +1,38 @@
+const BADGE_CAP = 99
+
+export type ScrollToLatestViewParams = {
+  /** Already decided by shouldStickToBottom; this rule never looks at pixels. */
+  readonly isAwayFromBottom: boolean
+  readonly newMessagesCount: number
+  readonly hasMessages: boolean
+}
+
+export type ScrollToLatestView = {
+  readonly isVisible: boolean
+  readonly badge: string | undefined
+}
+
+export type ScrollToLatestOptionsParams = {
+  readonly scrollHeight: number
+  readonly isReducedMotion: boolean
+}
+
+export function resolveScrollToLatestView(params: ScrollToLatestViewParams): ScrollToLatestView {
+  const { isAwayFromBottom, newMessagesCount, hasMessages } = params
+  if (!isAwayFromBottom || !hasMessages) return { isVisible: false, badge: undefined }
+  if (newMessagesCount <= 0) return { isVisible: true, badge: undefined }
+  return { isVisible: true, badge: newMessagesCount > BADGE_CAP ? `${BADGE_CAP}+` : String(newMessagesCount) }
+}
+
+export function scrollToLatestOptions(params: ScrollToLatestOptionsParams): ScrollToOptions {
+  return { top: params.scrollHeight, behavior: params.isReducedMotion ? 'auto' : 'smooth' }
+}
+
+export function scrollIntoViewOptions(isReducedMotion: boolean): ScrollIntoViewOptions {
+  return { block: 'nearest', inline: 'nearest', behavior: isReducedMotion ? 'auto' : 'smooth' }
+}
+
+export function readPrefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}