@adatechnology/conversations-ui 0.9.0 → 0.11.0

package/src/participant/participantComposerAudioDom.test.tsx

@@ -0,0 +1,185 @@
+import { act, useState } from 'react'
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, jest, mock } from 'bun:test'
+
+import { setupDom, type DomHarness } from '../domHarness.test-helper'
+import { ConversationThread } from './ConversationThread'
+import { ParticipantComposer, type ParticipantComposerProps } from './ParticipantComposer'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { installFakeRecording, type FakeRecordingControls } from './participantRecorderFakes.test-helper'
+
+let harness: DomHarness
+let fakes: FakeRecordingControls
+let container: HTMLElement
+let sentAudio: File[]
+let draftTouches: string[]
+let captureEvents: boolean[]
+
+beforeAll(async () => {
+  harness = await setupDom()
+})
+
+afterAll(() => harness.teardown())
+
+beforeEach(() => {
+  jest.useFakeTimers()
+  fakes = installFakeRecording()
+  URL.createObjectURL = () => 'blob:fake-recording'
+  URL.revokeObjectURL = () => undefined
+  sentAudio = []
+  draftTouches = []
+  captureEvents = []
+})
+
+afterEach(() => {
+  jest.useRealTimers()
+  fakes.restore()
+})
+
+function mountComposer(overrides: Partial<ParticipantComposerProps> = {}): void {
+  const props: ParticipantComposerProps = {
+    value: '',
+    onChange: () => draftTouches.push('onChange'),
+    files: [],
+    onFilesChange: () => draftTouches.push('onFilesChange'),
+    onSend: () => draftTouches.push('onSend'),
+    labels: DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS,
+    audioRecording: { onCaptureChange: (isCapturing) => captureEvents.push(isCapturing) },
+    onSendAudio: (file) => sentAudio.push(file),
+    ...overrides,
+  }
+  container = harness.mount(<ParticipantComposer {...props} />).container
+}
+
+function find(selector: string): HTMLButtonElement {
+  const element = container.querySelector<HTMLButtonElement>(selector)
+  if (!element) throw new Error(`missing ${selector}`)
+  return element
+}
+
+async function press(selector: string): Promise<void> {
+  await act(async () => find(selector).click())
+}
+
+async function recordFor(milliseconds: number): Promise<void> {
+  await press('.cv-p-composer__record')
+  await act(async () => jest.advanceTimersByTime(milliseconds))
+  await press('.cv-p-recorder__stop')
+}
+
+describe('record, review and send from the composer', () => {
+  it('sends exactly one audio File and never touches the text draft or the attached files', async () => {
+    mountComposer()
+    await recordFor(1500)
+    expect(find('.cv-p-recorder--review')).toBeTruthy()
+    await press('.cv-p-recorder__send')
+
+    expect(sentAudio).toHaveLength(1)
+    expect(sentAudio[0]?.name).toMatch(/^audio-\d{8}-\d{6}\.ogg$/)
+    expect(sentAudio[0]?.type).toBe('audio/ogg')
+    expect(draftTouches).toEqual([])
+    expect(container.querySelector('.cv-p-composer__record')).not.toBeNull()
+  })
+
+  it('shows the recorder row in place of the field while recording, with the error above the row when idle', async () => {
+    mountComposer()
+    await press('.cv-p-composer__record')
+    expect(container.querySelector('.cv-p-composer__input')).toBeNull()
+    expect(find('.cv-p-recorder[role="group"]')).toBeTruthy()
+    expect(container.querySelector('[role="timer"]')?.textContent).toBe('0:00 of 5:00')
+  })
+
+  // Guard held here: recorder.confirm() returns the File once, because statusRef leaves 'review' synchronously
+  // (the Set<File> of useParticipantSendAudio is pinned by its own test file).
+  it('turns two synchronous clicks on "Send audio" into one message', async () => {
+    mountComposer()
+    await recordFor(1500)
+    const sendButton = find('.cv-p-recorder__send')
+    await act(async () => {
+      sendButton.click()
+      sendButton.click()
+    })
+    expect(sentAudio).toHaveLength(1)
+  })
+
+  it('refuses an audio over the size ceiling before sending, with the message above the microphone', async () => {
+    mountComposer({ audioRecording: { maxSizeBytes: 1000 } })
+    await recordFor(1500)
+    expect(sentAudio).toHaveLength(0)
+    expect(container.querySelector('[role="alert"]')?.textContent).toBe(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS.audioTooLarge)
+    expect(container.querySelector('.cv-p-composer__record')).not.toBeNull()
+  })
+
+  it('refuses an empty capture before sending', async () => {
+    fakes.chunkBytes = 0
+    mountComposer()
+    await recordFor(1500)
+    expect(sentAudio).toHaveLength(0)
+    expect(container.querySelector('[role="alert"]')?.textContent).toBe(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS.audioEmpty)
+  })
+
+  it('keeps the microphone disabled together with the composer', async () => {
+    mountComposer({ disabled: true })
+    expect(find('.cv-p-composer__record').disabled).toBe(true)
+  })
+
+  it('disables "Send audio" in review when the conversation becomes disabled, and still allows discarding', async () => {
+    let setDisabled: (next: boolean) => void = () => undefined
+    function Wrapper() {
+      const [disabled, update] = useState(false)
+      setDisabled = update
+      return (
+        <ParticipantComposer
+          value=""
+          onChange={() => undefined}
+          files={[]}
+          onFilesChange={() => undefined}
+          onSend={() => undefined}
+          labels={DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS}
+          audioRecording={{}}
+          onSendAudio={(file) => sentAudio.push(file)}
+          disabled={disabled}
+        />
+      )
+    }
+    container = harness.mount(<Wrapper />).container
+    await recordFor(1500)
+    expect(find('.cv-p-recorder__send').disabled).toBe(false)
+    act(() => setDisabled(true))
+    expect(find('.cv-p-recorder__send').disabled).toBe(true)
+    expect(find('.cv-p-recorder__discard').disabled).toBe(false)
+  })
+
+  it('reports the capture to the host from the request until the audio is sent', async () => {
+    mountComposer()
+    await press('.cv-p-composer__record')
+    expect(captureEvents).toEqual([true])
+    await act(async () => jest.advanceTimersByTime(1500))
+    await press('.cv-p-recorder__stop')
+    expect(captureEvents).toEqual([true])
+    await press('.cv-p-recorder__send')
+    expect(captureEvents).toEqual([true, false])
+  })
+})
+
+describe('the whole thread: the audio leaves as its own message through the attachment path', () => {
+  // Same guard as above (statusRef of confirm), now observed end to end at api.sendMessage.
+  it('calls api.sendMessage once with one File and no text, even on two synchronous clicks', async () => {
+    const sendMessage = mock(async () => ({ outcome: 'queued' as const }))
+    const api = { fetchMessages: async () => [], sendMessage, resolveAttachmentUrl: async () => 'https://files.example/a' }
+    container = harness.mount(
+      <ConversationThread api={api} subject={{ subjectType: 'case', subjectId: '7' }} title="Case 7" audioRecording={{}} />,
+    ).container
+    await recordFor(1500)
+    const sendButton = find('.cv-p-recorder__send')
+    await act(async () => {
+      sendButton.click()
+      sendButton.click()
+    })
+
+    expect(sendMessage).toHaveBeenCalledTimes(1)
+    const [request] = sendMessage.mock.calls[0] as unknown as [{ text?: string; files?: File[] }]
+    expect(request.text).toBeUndefined()
+    expect(request.files).toHaveLength(1)
+  })
+})

package/src/participant/participantComposerAudioGolden.test.tsx

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test'
+import type { ComponentType } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ParticipantAudioRecorderView } from './ParticipantAudioRecorderView'
+import { ParticipantThread } from './ParticipantThread'
+import { buildThreadProps } from './participantGoldenScenarios.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { installFakeRecording } from './participantRecorderFakes.test-helper'
+
+function readGolden(name: string): string {
+  return readFileSync(join(import.meta.dir, 'test-fixtures', `${name}.golden.html`), 'utf8')
+}
+
+const Thread = ParticipantThread as unknown as ComponentType<Record<string, unknown>>
+
+function renderThreadWithMicrophone(): string {
+  const props = {
+    ...buildThreadProps(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS),
+    draft: { value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined },
+    audioRecording: {},
+    onSendAudio: () => undefined,
+  }
+  return renderToStaticMarkup(<Thread {...props} />)
+}
+
+describe('the real composer with the microphone (contract 2.2), not only the pure view', () => {
+  let restore: (() => void) | undefined
+
+  beforeAll(() => {
+    process.env.TZ = 'UTC'
+  })
+
+  afterEach(() => restore?.())
+
+  it('thread-composer-microphone-idle is byte-identical to its golden', () => {
+    restore = installFakeRecording().restore
+    const markup = renderThreadWithMicrophone()
+    expect(markup).toBe(readGolden('thread-composer-microphone-idle'))
+  })
+})
+
+describe('composer-audio-*: the pure recorder view (contract 2.2-2.3)', () => {
+  for (const state of ['idle', 'recording', 'review', 'denied'] as const) {
+    it(`composer-audio-${state} is byte-identical to its golden`, () => {
+      const markup = renderToStaticMarkup(
+        <ParticipantAudioRecorderView state={state} elapsedMs={12_000} labels={DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS} />,
+      )
+      expect(markup).toBe(readGolden(`composer-audio-${state}`))
+    })
+  }
+})
+
+describe('the microphone in the composer (contract 2.2)', () => {
+  let restore: (() => void) | undefined
+
+  afterEach(() => restore?.())
+
+  it('takes the place of send only with the prop, an empty field and a recording browser', () => {
+    restore = installFakeRecording().restore
+    const withProp = renderThreadWithMicrophone()
+    expect(withProp).toContain('cv-p-composer__record')
+    expect(withProp).not.toContain('cv-p-composer__send')
+  })
+})

package/src/participant/participantComposerAudioSsr.test.tsx

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ParticipantComposer, type ParticipantComposerProps } from './ParticipantComposer'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { installFakeRecording, type FakeRecordingControls } from './participantRecorderFakes.test-helper'
+
+const BASE: ParticipantComposerProps = {
+  value: '',
+  onChange: () => undefined,
+  files: [],
+  onFilesChange: () => undefined,
+  onSend: () => undefined,
+  labels: DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS,
+  audioRecording: {},
+  onSendAudio: () => undefined,
+}
+
+function render(overrides: Partial<ParticipantComposerProps> = {}): string {
+  return renderToStaticMarkup(<ParticipantComposer {...BASE} {...overrides} />)
+}
+
+describe('the microphone in the composer (contract 2.2)', () => {
+  let environment: FakeRecordingControls | undefined
+
+  afterEach(() => {
+    environment?.restore()
+    environment = undefined
+  })
+
+  it('takes the place of send with the prop, an empty field and a recording browser', () => {
+    environment = installFakeRecording()
+    const markup = render()
+    expect(markup).toContain('type="button" class="cv-p-button cv-p-button--primary cv-p-composer__record"')
+    expect(markup).not.toContain('cv-p-composer__send')
+  })
+
+  it('never appears without the prop', () => {
+    environment = installFakeRecording()
+    const markup = render({ audioRecording: undefined })
+    expect(markup).not.toContain('cv-p-composer__record')
+    expect(markup).toContain('cv-p-composer__send')
+  })
+
+  it('gives way to send when there is text or an attached file', () => {
+    environment = installFakeRecording()
+    for (const overrides of [{ value: 'oi' }, { files: [new File(['x'], 'a.txt')] }]) {
+      const markup = render(overrides)
+      expect(markup).not.toContain('cv-p-composer__record')
+      expect(markup).toContain('cv-p-composer__send')
+    }
+  })
+
+  it('stays off when the browser cannot record', () => {
+    expect(render()).not.toContain('cv-p-composer__record')
+  })
+
+  it('stays off on the portal channel: the channel only switches the microphone off', () => {
+    environment = installFakeRecording()
+    expect(render({ channel: 'portal' })).not.toContain('cv-p-composer__record')
+  })
+
+  it('stays off when the host accepts no audio type or gives no way to send it', () => {
+    environment = installFakeRecording()
+    expect(render({ acceptedTypes: ['image/*'] })).not.toContain('cv-p-composer__record')
+    expect(render({ acceptedTypes: ['audio/*'] })).toContain('cv-p-composer__record')
+    expect(render({ onSendAudio: undefined })).not.toContain('cv-p-composer__record')
+  })
+
+  it('is disabled together with the composer', () => {
+    environment = installFakeRecording()
+    expect(render({ disabled: true })).toMatch(/cv-p-composer__record"[^>]*disabled=""/)
+  })
+})

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,5 @@
+import { DEFAULT_PARTICIPANT_AUDIO_LABELS, type ParticipantAudioLabels } from './participantAudioLabels'
+
 export const DEFAULT_MESSAGE_OPTIONS_LABEL = 'Message options'
 
 export type ParticipantConversationsLabels = {
@@ -65,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',
@@ -125,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
+}