@adatechnology/conversations-ui 0.8.0 → 0.10.0

package/src/participant/participantFailedMenuState.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  CLOSED_FAILED_MENU,
+  failedMenuReducer,
+  resolveFailedMenuKey,
+  resolveFailedMenuPlacement,
+  resolveFailedMenuTriggerKey,
+} from './participantFailedMenuState'
+
+describe('failed menu state', () => {
+  it('toggles open on first focus item and closes again', () => {
+    const open = failedMenuReducer(CLOSED_FAILED_MENU, { type: 'toggle' })
+    expect(open).toEqual({ isOpen: true, initialFocus: 'first' })
+    expect(failedMenuReducer(open, { type: 'toggle' })).toEqual(CLOSED_FAILED_MENU)
+  })
+
+  it('opens on the last item when asked and ignores a close while closed', () => {
+    expect(failedMenuReducer(CLOSED_FAILED_MENU, { type: 'open', initialFocus: 'last' }).initialFocus).toBe('last')
+    expect(failedMenuReducer(CLOSED_FAILED_MENU, { type: 'close' })).toBe(CLOSED_FAILED_MENU)
+  })
+})
+
+describe('failed menu keyboard', () => {
+  it('Escape closes and gives the focus back to the trigger', () => {
+    expect(resolveFailedMenuKey({ key: 'Escape', index: 0, count: 2 })).toEqual({ type: 'close', shouldRestoreFocus: true })
+  })
+
+  it('Tab closes without trapping: focus is not pulled back', () => {
+    expect(resolveFailedMenuKey({ key: 'Tab', index: 1, count: 2 })).toEqual({ type: 'close', shouldRestoreFocus: false })
+  })
+
+  it('arrows wrap around, Home and End jump', () => {
+    expect(resolveFailedMenuKey({ key: 'ArrowDown', index: 1, count: 2 })).toEqual({ type: 'focus', index: 0 })
+    expect(resolveFailedMenuKey({ key: 'ArrowUp', index: 0, count: 2 })).toEqual({ type: 'focus', index: 1 })
+    expect(resolveFailedMenuKey({ key: 'Home', index: 1, count: 2 })).toEqual({ type: 'focus', index: 0 })
+    expect(resolveFailedMenuKey({ key: 'End', index: 0, count: 2 })).toEqual({ type: 'focus', index: 1 })
+    expect(resolveFailedMenuKey({ key: 'a', index: 0, count: 2 })).toBeUndefined()
+  })
+
+  it('ArrowDown and ArrowUp open the menu from the trigger on the matching end', () => {
+    expect(resolveFailedMenuTriggerKey('ArrowDown')).toBe('first')
+    expect(resolveFailedMenuTriggerKey('ArrowUp')).toBe('last')
+    expect(resolveFailedMenuTriggerKey('Enter')).toBeUndefined()
+  })
+})
+
+describe('failed menu placement', () => {
+  it('opens above when the scroller leaves room for the menu', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 300, scrollerTop: 100, menuHeight: 90 })).toBe('above')
+  })
+
+  it('flips below for the first bubble of the conversation, where the scroller would clip it', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 112, scrollerTop: 100, menuHeight: 90 })).toBe('below')
+  })
+
+  it('needs the gap too: room for exactly the menu is not enough', () => {
+    expect(resolveFailedMenuPlacement({ anchorTop: 190, scrollerTop: 100, menuHeight: 90 })).toBe('below')
+    expect(resolveFailedMenuPlacement({ anchorTop: 198, scrollerTop: 100, menuHeight: 90 })).toBe('above')
+  })
+})

package/src/participant/participantFailedMenuState.ts

@@ -0,0 +1,57 @@
+export type FailedMenuFocus = 'first' | 'last'
+
+export type FailedMenuState = { readonly isOpen: boolean; readonly initialFocus: FailedMenuFocus }
+
+export type FailedMenuAction =
+  | { readonly type: 'open'; readonly initialFocus: FailedMenuFocus }
+  | { readonly type: 'close' }
+  | { readonly type: 'toggle' }
+
+export const CLOSED_FAILED_MENU: FailedMenuState = { isOpen: false, initialFocus: 'first' }
+
+export function failedMenuReducer(state: FailedMenuState, action: FailedMenuAction): FailedMenuState {
+  if (action.type === 'open') return { isOpen: true, initialFocus: action.initialFocus }
+  if (action.type === 'close') return state.isOpen ? CLOSED_FAILED_MENU : state
+  return state.isOpen ? CLOSED_FAILED_MENU : { isOpen: true, initialFocus: 'first' }
+}
+
+export type FailedMenuKeyResult =
+  | { readonly type: 'focus'; readonly index: number }
+  | { readonly type: 'close'; readonly shouldRestoreFocus: boolean }
+
+type MenuKeyParams = { readonly key: string; readonly index: number; readonly count: number }
+
+/** Roving focus inside the open menu; Tab is never trapped, it closes the menu and lets focus move on. */
+export function resolveFailedMenuKey({ key, index, count }: MenuKeyParams): FailedMenuKeyResult | undefined {
+  if (key === 'Escape') return { type: 'close', shouldRestoreFocus: true }
+  if (key === 'Tab') return { type: 'close', shouldRestoreFocus: false }
+  if (key === 'ArrowDown') return { type: 'focus', index: (index + 1) % count }
+  if (key === 'ArrowUp') return { type: 'focus', index: (index - 1 + count) % count }
+  if (key === 'Home') return { type: 'focus', index: 0 }
+  if (key === 'End') return { type: 'focus', index: count - 1 }
+  return undefined
+}
+
+/** Keys that open the menu from its trigger; Enter and Space already open it through the click. */
+export function resolveFailedMenuTriggerKey(key: string): FailedMenuFocus | undefined {
+  if (key === 'ArrowDown') return 'first'
+  if (key === 'ArrowUp') return 'last'
+  return undefined
+}
+
+export type FailedMenuPlacement = 'above' | 'below'
+
+const MENU_GAP_PX = 8
+
+type MenuPlacementParams = {
+  /** Top edge of the bubble the menu hangs from. */
+  readonly anchorTop: number
+  /** Top edge of the scroller that clips the menu. */
+  readonly scrollerTop: number
+  readonly menuHeight: number
+}
+
+/** The menu opens above its bubble; it flips below when the scroller would clip it. */
+export function resolveFailedMenuPlacement({ anchorTop, scrollerTop, menuHeight }: MenuPlacementParams): FailedMenuPlacement {
+  return anchorTop - scrollerTop >= menuHeight + MENU_GAP_PX ? 'above' : 'below'
+}

package/src/participant/participantFailedMessage.test.tsx

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { OwnStatus, RetryButton } from './ParticipantBubbleStatus'
+import { ParticipantFailedMenu } from './ParticipantFailedMenu'
+import { declarationsIn } from './participantCss.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS as LABELS } from './participantLabels'
+
+const noop = (): void => undefined
+
+describe('failed message: markup', () => {
+  it('puts retry in a round icon button with the long text as its name, no visible text', () => {
+    const markup = renderToStaticMarkup(<RetryButton labels={LABELS} onRetry={noop} />)
+
+    expect(markup).toContain('aria-label="Failed — tap to retry"')
+    expect(markup).toContain('aria-hidden="true"')
+    expect(markup.replace(/<svg.*<\/svg>/, '')).not.toMatch(/>[A-Za-z]/)
+  })
+
+  it('keeps the meta of a failed bubble to the red icon, with the short text for screen readers only', () => {
+    const withRetry = renderToStaticMarkup(<OwnStatus status="failed" labels={LABELS} onRetry={noop} />)
+    const withoutRetry = renderToStaticMarkup(<OwnStatus status="failed" labels={LABELS} />)
+
+    expect(withRetry).not.toContain('<button')
+    expect(withRetry).toContain('cv-status-ticks--failed')
+    expect(withRetry).toContain('cv-p-sr-only">Failed<')
+    expect(withoutRetry).toContain('cv-p-bubble__status-text">Failed<')
+  })
+
+  it('renders a closed menu trigger with the menu button semantics, and no menu without handlers', () => {
+    const markup = renderToStaticMarkup(<ParticipantFailedMenu labels={LABELS} onEdit={noop} onDiscard={noop} />)
+
+    expect(markup).toContain('aria-haspopup="menu"')
+    expect(markup).toContain('aria-expanded="false"')
+    expect(markup).toContain('data-cv-tooltip="Message options"')
+    expect(markup).toContain('aria-label="Message options"')
+    expect(markup).not.toContain('role="menu"')
+    expect(renderToStaticMarkup(<ParticipantFailedMenu labels={LABELS} />)).toBe('')
+  })
+})
+
+describe('failed message: styles', () => {
+  it('hangs the retry button beside the bubble: 44px target, 2rem circle, no layout space taken', () => {
+    const button = declarationsIn('.cv-p-failed-retry')
+    const icon = declarationsIn('.cv-p-failed-retry__icon')
+
+    expect(button.get('position')).toBe('absolute')
+    expect(button.get('right')).toContain('100%')
+    expect(button.get('width')).toBe('var(--cv-p-i-touch)')
+    expect(button.get('height')).toBe('var(--cv-p-i-touch)')
+    expect(icon.get('width')).toBe('2rem')
+    expect(icon.get('border-radius')).toBe('50%')
+    expect(button.get('color')).toBe('var(--cv-p-i-danger)')
+  })
+
+  it('keeps the bubble cap of 85% by not wrapping the bubble in a row', () => {
+    expect(declarationsIn('.cv-p-bubble-row--failed').size).toBe(0)
+    expect(declarationsIn('.cv-p-bubble').get('max-width')).toBe('85%')
+  })
+
+  it('flips the menu below the bubble with a modifier', () => {
+    expect(declarationsIn('.cv-p-failed-menu__list--below').get('top')).toContain('100%')
+    expect(declarationsIn('.cv-p-failed-menu__list--below').get('bottom')).toBe('auto')
+  })
+
+  it('draws the menu with square corners, text and danger tokens, 44px items', () => {
+    expect(declarationsIn('.cv-p-failed-menu__list').get('border-radius')).toBe('var(--cv-p-i-radius)')
+    expect(declarationsIn('.cv-p-failed-menu__list').get('bottom')).toContain('100%')
+    expect(declarationsIn('.cv-p-failed-menu__item').get('color')).toBe('var(--cv-p-i-text)')
+    expect(declarationsIn('.cv-p-failed-menu__item').get('min-height')).toBe('var(--cv-p-i-touch)')
+    expect(declarationsIn('.cv-p-failed-menu__item--danger').get('color')).toBe('var(--cv-p-i-danger)')
+  })
+
+  it('keeps the trigger hit area inside the bubble padding (0.5rem), never into other rows', () => {
+    expect(declarationsIn('.cv-p-failed-menu__trigger::after').get('inset')).toBe('-0.5rem -0.4rem')
+  })
+
+  it('has no leftover action-row or bordered-retry rules', () => {
+    for (const selector of ['.cv-p-bubble__retry', '.cv-p-bubble__action', '.cv-p-bubble__actions']) {
+      expect(declarationsIn(selector).size).toBe(0)
+    }
+  })
+})

package/src/participant/participantFileValidation.ts

@@ -15,7 +15,7 @@ export type ValidateParticipantFilesResult = {
   readonly rejection?: ParticipantFileRejection
 }
 
-function matchesAcceptedType(mimeType: string, acceptedTypes: readonly string[]): boolean {
+export function matchesAcceptedType(mimeType: string, acceptedTypes: readonly string[]): boolean {
   return acceptedTypes.some((accepted) =>
     accepted.endsWith('/*') ? mimeType.startsWith(accepted.slice(0, -1)) : mimeType === accepted,
   )

package/src/participant/participantGolden.test.tsx

@@ -36,6 +36,8 @@ describe('participant default markup against the recorded origin/main output', (
     'thread-closed',
     'conversations-list',
     'conversations-selected',
+    'thread-empty-draft',
+    'thread-audio-native',
   ]
 
   for (const name of scenarioNames) {

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

@@ -20,7 +20,17 @@ const ITEMS = [
   { 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> {
+export const EMPTY_DRAFT = { value: '', onChange: NOOP, files: [], onFilesChange: NOOP }
+
+const AUDIO_NATIVE_ITEMS = [
+  { kind: 'server', message: buildMessage({ id: 'au', direction: 'inbound', text: '', attachments: [{ id: 'att-1', kind: 'audio', filename: 'voice.webm', mimeType: 'audio/webm', sizeBytes: 2048 }], createdAt: '2026-10-01T12:00:00.000Z' }) },
+]
+
+const AUDIO_PLAYER_ITEMS = [
+  { kind: 'server', message: buildMessage({ id: 'au', direction: 'inbound', text: '', attachments: [{ id: 'att-1', kind: 'audio', filename: 'voice.webm', mimeType: 'audio/webm', sizeBytes: 2048, durationMs: 65_000 }], createdAt: '2026-10-01T12:00:00.000Z' }) },
+]
+
+export 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',
@@ -40,6 +50,9 @@ const THREAD_VARIANTS: Record<string, Record<string, unknown>> = {
   'thread-error': { status: 'error', items: [] },
   'thread-loading': { status: 'loading', items: [] },
   'thread-closed': { conversation: buildConversation({ subjectId: '2', status: 'closed' }) },
+  'thread-empty-draft': { draft: EMPTY_DRAFT },
+  'thread-audio-native': { items: AUDIO_NATIVE_ITEMS },
+  'thread-audio-player': { items: AUDIO_PLAYER_ITEMS },
 }
 
 export function renderGoldenScenarios({ ParticipantThread, ParticipantConversations, labels }: GoldenComponents): Record<string, string> {

package/src/participant/participantLabels.ts

@@ -1,3 +1,7 @@
+import { DEFAULT_PARTICIPANT_AUDIO_LABELS, type ParticipantAudioLabels } from './participantAudioLabels'
+
+export const DEFAULT_MESSAGE_OPTIONS_LABEL = 'Message options'
+
 export type ParticipantConversationsLabels = {
   readonly inboxTitle: string
   readonly sectionAwaiting: string
@@ -33,9 +37,12 @@ export type ParticipantConversationsLabels = {
   readonly statusRead: string
   readonly statusFailed: string
   readonly statusFailedShort: string
+  /** @deprecated No longer rendered by the default view: the retry button is icon-only and named by `statusFailed`. */
   readonly retry: string
   readonly discard: string
   readonly edit: string
+  /** Name of the menu button on a failed message. Optional; translated hosts should fill it, otherwise the English default shows. */
+  readonly messageOptions?: string
   readonly notFound: string
   readonly loading: string
   readonly loadError: string
@@ -60,7 +67,7 @@ export type ParticipantConversationsLabels = {
   /** Prefix of the accessible name of the copy buttons: "Copy 529.982.247-25". */
   readonly copyValue: string
   readonly valueCopied: string
-}
+} & Readonly<Partial<ParticipantAudioLabels>>
 
 export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsLabels = {
   inboxTitle: 'Conversations',
@@ -98,6 +105,7 @@ export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsL
   retry: 'Retry',
   discard: 'Discard',
   edit: 'Edit',
+  messageOptions: DEFAULT_MESSAGE_OPTIONS_LABEL,
   notFound: 'Conversation not found',
   loading: 'Loading…',
   loadError: 'Could not load. Check your connection and try again.',
@@ -119,6 +127,7 @@ export const DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS: ParticipantConversationsL
   externalLinkHint: 'opens in a new tab',
   copyValue: 'Copy',
   valueCopied: 'Copied',
+  ...DEFAULT_PARTICIPANT_AUDIO_LABELS,
 }
 
 export function formatParticipantLabel(template: string, count: number): string {

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

@@ -0,0 +1,82 @@
+type MediaState = {
+  paused: boolean
+  currentTime: number
+  duration: number
+  defaultPlaybackRate: number
+  playbackRate: number
+}
+
+export type FakeMediaControls = {
+  /** Elements in the order `play()` was called on them. */
+  readonly playCalls: HTMLMediaElement[]
+  readonly pauseCalls: HTMLMediaElement[]
+  /** What the next `play()` promises: the iOS gesture refusal is a rejection. */
+  playOutcome: 'resolve' | 'reject'
+  readonly stateOf: (audio: HTMLMediaElement) => MediaState
+  readonly emit: (audio: HTMLMediaElement, type: string) => void
+  readonly restore: () => void
+}
+
+const OVERRIDDEN = ['paused', 'currentTime', 'duration', 'defaultPlaybackRate', 'playbackRate', 'play', 'pause', 'load'] as const
+
+/** Replaces the HTMLMediaElement members the player uses with an in-memory media element. */
+export function installFakeMedia(): FakeMediaControls {
+  const prototype = HTMLMediaElement.prototype
+  const previous = OVERRIDDEN.map((name) => [name, Object.getOwnPropertyDescriptor(prototype, name)] as const)
+  const states = new WeakMap<object, MediaState>()
+  const stateOf = (audio: HTMLMediaElement): MediaState => {
+    const existing = states.get(audio)
+    if (existing) return existing
+    const created: MediaState = { paused: true, currentTime: 0, duration: Number.NaN, defaultPlaybackRate: 1, playbackRate: 1 }
+    states.set(audio, created)
+    return created
+  }
+  const emit = (audio: HTMLMediaElement, type: string): void => {
+    audio.dispatchEvent(new Event(type))
+  }
+  const controls: FakeMediaControls = {
+    playCalls: [],
+    pauseCalls: [],
+    playOutcome: 'resolve',
+    stateOf,
+    emit,
+    restore: () => {
+      for (const [name, descriptor] of previous) {
+        if (descriptor) Object.defineProperty(prototype, name, descriptor)
+        else delete (prototype as unknown as Record<string, unknown>)[name]
+      }
+    },
+  }
+  for (const name of ['paused', 'currentTime', 'duration', 'defaultPlaybackRate', 'playbackRate'] as const) {
+    Object.defineProperty(prototype, name, {
+      configurable: true,
+      get(this: HTMLMediaElement) {
+        return stateOf(this)[name]
+      },
+      set(this: HTMLMediaElement, value: never) {
+        ;(stateOf(this) as Record<string, unknown>)[name] = value
+      },
+    })
+  }
+  Object.defineProperty(prototype, 'play', {
+    configurable: true,
+    value(this: HTMLMediaElement): Promise<void> {
+      controls.playCalls.push(this)
+      if (controls.playOutcome === 'reject') return Promise.reject(new Error('NotAllowedError'))
+      stateOf(this).paused = false
+      emit(this, 'play')
+      return Promise.resolve()
+    },
+  })
+  Object.defineProperty(prototype, 'pause', {
+    configurable: true,
+    value(this: HTMLMediaElement): void {
+      if (stateOf(this).paused) return
+      controls.pauseCalls.push(this)
+      stateOf(this).paused = true
+      emit(this, 'pause')
+    },
+  })
+  Object.defineProperty(prototype, 'load', { configurable: true, value: () => undefined })
+  return controls
+}

package/src/participant/participantNoMicrophoneDom.test.tsx

@@ -0,0 +1,44 @@
+import type { ComponentType } from 'react'
+
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test'
+
+import { setupDom, type DomHarness } from '../domHarness.test-helper'
+import { buildThreadProps } from './participantGoldenScenarios.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { ParticipantThread } from './ParticipantThread'
+
+const UntypedThread = ParticipantThread as unknown as ComponentType<Record<string, unknown>>
+
+describe('empty composer in a recording browser without the audioRecording prop (contract 2.4 item 3)', () => {
+  let harness: DomHarness
+
+  beforeAll(async () => {
+    harness = await setupDom()
+    const globals = globalThis as Record<string, unknown>
+    globals.MediaRecorder = class FakeMediaRecorder {
+      static isTypeSupported(): boolean {
+        return true
+      }
+    }
+    ;(navigator as unknown as Record<string, unknown>).mediaDevices = { getUserMedia: async () => ({ getTracks: () => [] }) }
+  })
+
+  afterAll(() => {
+    delete (globalThis as Record<string, unknown>).MediaRecorder
+    harness.teardown()
+  })
+
+  it('renders no microphone button even though MediaRecorder and getUserMedia exist', () => {
+    const props = {
+      ...buildThreadProps(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS),
+      draft: { value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined },
+    }
+    const { container } = harness.mount(<UntypedThread {...props} />)
+
+    expect(typeof (globalThis as Record<string, unknown>).MediaRecorder).toBe('function')
+    expect(container.querySelector('.cv-p-composer__send') !== null).toBe(true)
+    expect(container.querySelector('.cv-p-composer__record') === null).toBe(true)
+    expect(container.querySelector('button[aria-label="Record audio"]') === null).toBe(true)
+    expect(Array.from(container.querySelectorAll('button')).some((button) => /record/i.test(button.getAttribute('aria-label') ?? ''))).toBe(false)
+  })
+})

package/src/participant/participantPublicTypes.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { ParticipantAttachment, ParticipantTranscription } from './index'
+
+describe('the /participant entry re-exports the transcription type next to ParticipantAttachment', () => {
+  it('lets a host type the field without importing the contracts package (checked by tsc)', () => {
+    const transcription: ParticipantTranscription = { status: 'pending' }
+    const attachment: Pick<ParticipantAttachment, 'transcription'> = { transcription }
+    expect(attachment.transcription?.status).toBe('pending')
+  })
+})

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

@@ -0,0 +1,131 @@
+import { act } from 'react'
+
+import { afterAll, afterEach, beforeAll, beforeEach, jest } from 'bun:test'
+
+import { setupDom, type DomHarness } from '../domHarness.test-helper'
+import type { ParticipantAudioRecordingOptions } from './participantAudio.types'
+import { useParticipantAudioRecorder } from './useParticipantAudioRecorder'
+
+export type RecorderApi = ReturnType<typeof useParticipantAudioRecorder>
+
+export class FakeTrack {
+  stopCount = 0
+  onended: (() => void) | null = null
+  onmute: (() => void) | null = null
+  onunmute: (() => void) | null = null
+  stop(): void {
+    this.stopCount += 1
+  }
+}
+
+export class FakeStream {
+  readonly track = new FakeTrack()
+  getTracks(): FakeTrack[] {
+    return [this.track]
+  }
+}
+
+/** Mutable state shared by the recorder DOM suites; each suite file builds its own through `setupRecorderDom`. */
+export type RecorderDomKit = {
+  harness: DomHarness
+  api: RecorderApi
+  stream: FakeStream
+  supportedTypes: readonly string[]
+  chunkBytes: number
+  revoked: string[]
+  captureEvents: boolean[]
+  resolveStream: ((value: FakeStream) => void) | undefined
+  getUserMediaImpl: () => Promise<FakeStream>
+  mountProbe: (options?: ParticipantAudioRecordingOptions) => ReturnType<DomHarness['mount']>
+  start: () => Promise<void>
+  advance: (milliseconds: number) => Promise<void>
+  recordFor: (milliseconds: number) => Promise<void>
+  deferStream: () => void
+  hidePage: () => void
+}
+
+export function setupRecorderDom(): RecorderDomKit {
+  class FakeMediaRecorder {
+    static isTypeSupported(mimeType: string): boolean {
+      return kit.supportedTypes.includes(mimeType)
+    }
+    state: 'inactive' | 'recording' = 'inactive'
+    ondataavailable: ((event: { data: Blob }) => void) | null = null
+    onstop: (() => void) | null = null
+    onerror: (() => void) | null = null
+    constructor(readonly stream: FakeStream, readonly options: { mimeType: string }) {}
+    start(): void {
+      this.state = 'recording'
+    }
+    stop(): void {
+      this.state = 'inactive'
+      this.ondataavailable?.({ data: new Blob([new Uint8Array(kit.chunkBytes)]) })
+      this.onstop?.()
+    }
+  }
+
+  function Probe({ options, channelMaxBytes }: { options?: ParticipantAudioRecordingOptions; channelMaxBytes?: number }) {
+    kit.api = useParticipantAudioRecorder({ options: { ...options, onCaptureChange: (isCapturing) => kit.captureEvents.push(isCapturing) }, channelMaxBytes })
+    return null
+  }
+
+  const kit = {
+    mountProbe: (options?: ParticipantAudioRecordingOptions) => kit.harness.mount(<Probe options={options} />),
+    start: async () => {
+      await act(async () => {
+        void kit.api.start()
+      })
+    },
+    advance: async (milliseconds: number) => {
+      await act(async () => {
+        jest.advanceTimersByTime(milliseconds)
+      })
+    },
+    recordFor: async (milliseconds: number) => {
+      await kit.start()
+      await kit.advance(milliseconds)
+    },
+    deferStream: () => {
+      kit.getUserMediaImpl = () => new Promise<FakeStream>((resolve) => (kit.resolveStream = resolve))
+    },
+    hidePage: () => {
+      Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => 'hidden' })
+      Object.defineProperty(document, 'hidden', { configurable: true, get: () => true })
+      act(() => {
+        document.dispatchEvent(new Event('visibilitychange'))
+      })
+      Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => 'visible' })
+      Object.defineProperty(document, 'hidden', { configurable: true, get: () => false })
+    },
+  } as unknown as RecorderDomKit
+
+  beforeAll(async () => {
+    kit.harness = await setupDom()
+  })
+
+  afterAll(() => kit.harness.teardown())
+
+  beforeEach(() => {
+    jest.useFakeTimers()
+    kit.supportedTypes = ['audio/ogg;codecs=opus', 'audio/mp4', 'audio/webm']
+    kit.chunkBytes = 4096
+    kit.revoked = []
+    kit.captureEvents = []
+    kit.stream = new FakeStream()
+    kit.resolveStream = undefined
+    kit.getUserMediaImpl = async () => kit.stream
+    ;(globalThis as Record<string, unknown>).MediaRecorder = FakeMediaRecorder
+    ;(navigator as unknown as Record<string, unknown>).mediaDevices = { getUserMedia: () => kit.getUserMediaImpl() }
+    URL.createObjectURL = () => 'blob:fake-recording'
+    URL.revokeObjectURL = (url: string) => {
+      kit.revoked.push(url)
+    }
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+    delete (globalThis as Record<string, unknown>).MediaRecorder
+  })
+
+  return kit
+}

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

@@ -0,0 +1,47 @@
+export type FakeRecordingControls = {
+  chunkBytes: number
+  readonly restore: () => void
+}
+
+class FakeTrack {
+  onended: (() => void) | null = null
+  onmute: (() => void) | null = null
+  onunmute: (() => void) | null = null
+  stop(): void {}
+}
+
+class FakeStream {
+  getTracks(): FakeTrack[] {
+    return [new FakeTrack()]
+  }
+}
+
+/** Installs a MediaRecorder and getUserMedia that record `controls.chunkBytes` bytes on stop. */
+export function installFakeRecording(initialChunkBytes = 4096): FakeRecordingControls {
+  const globals = globalThis as Record<string, unknown>
+  const navigatorObject = globalThis.navigator as unknown as Record<string, unknown>
+  const previousRecorder = globals.MediaRecorder
+  const previousMediaDevices = navigatorObject.mediaDevices
+  const controls: FakeRecordingControls = {
+    chunkBytes: initialChunkBytes,
+    restore: () => {
+      globals.MediaRecorder = previousRecorder
+      navigatorObject.mediaDevices = previousMediaDevices
+    },
+  }
+  globals.MediaRecorder = class FakeMediaRecorder {
+    static isTypeSupported(mimeType: string): boolean {
+      return mimeType === 'audio/ogg;codecs=opus'
+    }
+    ondataavailable: ((event: { data: Blob }) => void) | null = null
+    onstop: (() => void) | null = null
+    onerror: (() => void) | null = null
+    start(): void {}
+    stop(): void {
+      this.ondataavailable?.({ data: new Blob([new Uint8Array(controls.chunkBytes)]) })
+      this.onstop?.()
+    }
+  }
+  navigatorObject.mediaDevices = { getUserMedia: async () => new FakeStream() }
+  return controls
+}

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

@@ -0,0 +1,52 @@
+export class SpecTrack {
+  stopCount = 0
+  onended: (() => void) | null = null
+  onmute: (() => void) | null = null
+  onunmute: (() => void) | null = null
+  stop(): void {
+    this.stopCount += 1
+  }
+}
+
+export class SpecStream {
+  readonly track = new SpecTrack()
+  getTracks(): SpecTrack[] {
+    return [this.track]
+  }
+}
+
+/** Follows the MediaRecorder spec: stop() makes state inactive at once; dataavailable and stop arrive later. */
+export class SpecMediaRecorder {
+  static instances: SpecMediaRecorder[] = []
+  static chunkBytes = 4096
+  static isTypeSupported(mimeType: string): boolean {
+    return mimeType === 'audio/ogg;codecs=opus'
+  }
+  state: 'inactive' | 'recording' = 'inactive'
+  stopCalls = 0
+  ondataavailable: ((event: { data: Blob }) => void) | null = null
+  onstop: (() => void) | null = null
+  onerror: (() => void) | null = null
+  constructor() {
+    SpecMediaRecorder.instances.push(this)
+  }
+  start(): void {
+    this.state = 'recording'
+  }
+  stop(): void {
+    if (this.state === 'inactive') throw new DOMException('The MediaRecorder is already inactive', 'InvalidStateError')
+    this.stopCalls += 1
+    this.finishAsynchronously()
+  }
+  /** The user agent stops the recorder by itself (for example when the track ends). */
+  autoStop(): void {
+    this.finishAsynchronously()
+  }
+  private finishAsynchronously(): void {
+    this.state = 'inactive'
+    void Promise.resolve().then(() => {
+      this.ondataavailable?.({ data: new Blob([new Uint8Array(SpecMediaRecorder.chunkBytes)]) })
+      this.onstop?.()
+    })
+  }
+}