@adatechnology/conversations-ui 0.9.0 → 0.11.0

package/src/participant/useParticipantAudioRecorder.ts

@@ -0,0 +1,153 @@
+import { useCallback, useMemo, type RefObject } from 'react'
+
+import { resolveRecordingFormat, type RecordingFormat } from '../audioRecorderFormat'
+import type { ParticipantAudioRecordingOptions } from './participantAudio.types'
+import { buildRecordedFile, openCaptureSession, stopStream } from './participantAudioCapture'
+import {
+  canStartRecording,
+  classifyCapture,
+  classifyMicrophoneError,
+  resolveInterruptionAction,
+  resolveRecordingLimits,
+  type RecorderStatus,
+  type RecordingLimits,
+} from './participantAudioRecorderState'
+import { useRecorderCore, type RecorderCore, type RecordedAudio } from './useParticipantAudioRecorderCore'
+import { useRecorderInterruptionListeners, useRecorderLifecycle, useRecordingClock } from './useParticipantAudioRecorderEffects'
+
+export type { RecordedAudio }
+
+export type UseParticipantAudioRecorderParams = {
+  readonly options?: ParticipantAudioRecordingOptions
+  readonly channelMaxBytes?: number
+}
+
+export type ParticipantAudioRecorder = {
+  readonly status: RecorderStatus
+  readonly elapsedMs: number
+  readonly limits: RecordingLimits
+  readonly recorded: RecordedAudio | undefined
+  readonly audioRef: RefObject<HTMLAudioElement | null>
+  readonly start: () => Promise<void>
+  readonly stop: () => void
+  readonly discard: () => void
+  readonly confirm: () => File | undefined
+}
+
+function useRecorderFinalize(core: RecorderCore): (blob: Blob, durationMs: number) => void {
+  const { statusRef, sessionRef, recordedRef, limitsRef, setRecorded, moveTo, releaseSession } = core
+  return useCallback(
+    (blob: Blob, durationMs: number): void => {
+      const format = sessionRef.current?.format
+      if (statusRef.current !== 'recording' || !format) return
+      releaseSession()
+      const event = classifyCapture({ sizeBytes: blob.size, durationMs }, limitsRef.current)
+      if (event === 'capturedReview') {
+        const file = buildRecordedFile(blob, format)
+        recordedRef.current = { file, objectUrl: URL.createObjectURL(file), durationMs }
+        setRecorded(recordedRef.current)
+      }
+      moveTo(event)
+    },
+    [statusRef, sessionRef, recordedRef, limitsRef, setRecorded, moveTo, releaseSession],
+  )
+}
+
+function useRecorderInterruption(core: RecorderCore): () => void {
+  const { statusRef, sessionRef, tokenRef, audioRef, moveTo } = core
+  return useCallback((): void => {
+    const action = resolveInterruptionAction(statusRef.current)
+    if (action === 'stop') sessionRef.current?.requestStop()
+    if (action === 'pause') audioRef.current?.pause()
+    if (action === 'cancel') {
+      tokenRef.current += 1
+      moveTo('cancel')
+    }
+  }, [statusRef, sessionRef, tokenRef, audioRef, moveTo])
+}
+
+type RecorderStartParams = {
+  readonly onInterrupt: () => void
+  readonly onStopped: (blob: Blob, durationMs: number) => void
+}
+
+function useRecorderStart(core: RecorderCore, { onInterrupt, onStopped }: RecorderStartParams): () => Promise<void> {
+  const { statusRef, tokenRef, sessionRef, setElapsedMs, moveTo } = core
+  const beginRecording = useCallback(
+    (stream: MediaStream, format: RecordingFormat): void => {
+      try {
+        sessionRef.current = openCaptureSession({ stream, format, onInterrupt, onStopped })
+      } catch {
+        stopStream(stream)
+        moveTo('microphoneUnavailable')
+        return
+      }
+      setElapsedMs(0)
+      moveTo('granted')
+    },
+    [sessionRef, setElapsedMs, onInterrupt, onStopped, moveTo],
+  )
+
+  return useCallback(async (): Promise<void> => {
+    if (!canStartRecording(statusRef.current)) return
+    const token = (tokenRef.current += 1)
+    moveTo('request')
+    const format = resolveRecordingFormat()
+    if (!format || !navigator.mediaDevices?.getUserMedia) return moveTo('microphoneUnavailable')
+    let stream: MediaStream
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+    } catch (error) {
+      if (token === tokenRef.current) moveTo(classifyMicrophoneError(error))
+      return
+    }
+    if (token !== tokenRef.current) return stopStream(stream)
+    beginRecording(stream, format)
+  }, [statusRef, tokenRef, moveTo, beginRecording])
+}
+
+type RecorderActions = Pick<ParticipantAudioRecorder, 'stop' | 'discard' | 'confirm'> & { readonly teardown: () => void }
+
+function useRecorderActions(core: RecorderCore): RecorderActions {
+  const { statusRef, tokenRef, sessionRef, recordedRef, moveTo, releaseSession, releaseRecorded } = core
+  const stop = useCallback((): void => sessionRef.current?.requestStop(), [sessionRef])
+  const discard = useCallback((): void => {
+    tokenRef.current += 1
+    releaseSession()
+    releaseRecorded()
+    moveTo('cancel')
+  }, [tokenRef, moveTo, releaseRecorded, releaseSession])
+  const confirm = useCallback((): File | undefined => {
+    if (statusRef.current !== 'review') return undefined
+    const file = recordedRef.current?.file
+    releaseRecorded()
+    moveTo('cancel')
+    return file
+  }, [statusRef, recordedRef, moveTo, releaseRecorded])
+  const teardown = useCallback((): void => {
+    tokenRef.current += 1
+    releaseSession()
+    if (recordedRef.current) URL.revokeObjectURL(recordedRef.current.objectUrl)
+    recordedRef.current = undefined
+  }, [tokenRef, recordedRef, releaseSession])
+  return { stop, discard, confirm, teardown }
+}
+
+export function useParticipantAudioRecorder({ options, channelMaxBytes }: UseParticipantAudioRecorderParams = {}): ParticipantAudioRecorder {
+  const limits = useMemo(
+    () => resolveRecordingLimits({ options, channelMaxBytes }),
+    [options?.maxDurationMs, options?.maxSizeBytes, channelMaxBytes],
+  )
+  const core = useRecorderCore(limits)
+  const onInterrupt = useRecorderInterruption(core)
+  const onStopped = useRecorderFinalize(core)
+  const start = useRecorderStart(core, { onInterrupt, onStopped })
+  const { stop, discard, confirm, teardown } = useRecorderActions(core)
+
+  useRecorderInterruptionListeners(onInterrupt)
+  useRecordingClock({ status: core.status, maxDurationMs: limits.maxDurationMs, sessionRef: core.sessionRef, setElapsedMs: core.setElapsedMs, stop })
+  useRecorderLifecycle({ status: core.status, onCaptureChange: options?.onCaptureChange, teardown })
+
+  const { status, elapsedMs, recorded, audioRef } = core
+  return { status, elapsedMs, limits, recorded, audioRef, start, stop, discard, confirm }
+}

package/src/participant/useParticipantAudioRecorderCore.ts

@@ -0,0 +1,55 @@
+import { useCallback, useRef, useState, type Dispatch, type RefObject, type SetStateAction } from 'react'
+
+import type { CaptureSession } from './participantAudioCapture'
+import { reduceRecorderStatus, type RecorderEvent, type RecorderStatus, type RecordingLimits } from './participantAudioRecorderState'
+
+export type RecordedAudio = { readonly file: File; readonly objectUrl: string; readonly durationMs: number }
+
+export type RecorderCore = {
+  readonly status: RecorderStatus
+  readonly elapsedMs: number
+  readonly setElapsedMs: Dispatch<SetStateAction<number>>
+  readonly recorded: RecordedAudio | undefined
+  readonly setRecorded: (recorded: RecordedAudio | undefined) => void
+  readonly limitsRef: RefObject<RecordingLimits>
+  readonly statusRef: RefObject<RecorderStatus>
+  readonly tokenRef: RefObject<number>
+  readonly sessionRef: RefObject<CaptureSession | undefined>
+  readonly recordedRef: RefObject<RecordedAudio | undefined>
+  readonly audioRef: RefObject<HTMLAudioElement | null>
+  readonly moveTo: (event: RecorderEvent) => void
+  readonly releaseSession: () => void
+  readonly releaseRecorded: () => void
+}
+
+export function useRecorderCore(limits: RecordingLimits): RecorderCore {
+  const [status, setStatus] = useState<RecorderStatus>('idle')
+  const [elapsedMs, setElapsedMs] = useState(0)
+  const [recorded, setRecorded] = useState<RecordedAudio | undefined>()
+  const statusRef = useRef<RecorderStatus>('idle')
+  const limitsRef = useRef(limits)
+  const tokenRef = useRef(0)
+  const sessionRef = useRef<CaptureSession | undefined>(undefined)
+  const recordedRef = useRef<RecordedAudio | undefined>(undefined)
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  limitsRef.current = limits
+
+  const moveTo = useCallback((event: RecorderEvent): void => {
+    statusRef.current = reduceRecorderStatus(statusRef.current, event)
+    setStatus(statusRef.current)
+  }, [])
+  const releaseSession = useCallback((): void => {
+    sessionRef.current?.release()
+    sessionRef.current = undefined
+  }, [])
+  const releaseRecorded = useCallback((): void => {
+    if (recordedRef.current) URL.revokeObjectURL(recordedRef.current.objectUrl)
+    recordedRef.current = undefined
+    setRecorded(undefined)
+  }, [])
+
+  return {
+    status, elapsedMs, setElapsedMs, recorded, setRecorded, limitsRef, statusRef, tokenRef,
+    sessionRef, recordedRef, audioRef, moveTo, releaseSession, releaseRecorded,
+  }
+}

package/src/participant/useParticipantAudioRecorderEffects.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef, type Dispatch, type MutableRefObject, type SetStateAction } from 'react'
+
+import type { CaptureSession } from './participantAudioCapture'
+import type { RecorderStatus } from './participantAudioRecorderState'
+
+const ELAPSED_TICK_MS = 250
+
+export function useRecorderInterruptionListeners(onInterruption: () => void): void {
+  useEffect(() => {
+    const handleVisibilityChange = (): void => {
+      if (document.visibilityState === 'hidden') onInterruption()
+    }
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    window.addEventListener('pagehide', onInterruption)
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+      window.removeEventListener('pagehide', onInterruption)
+    }
+  }, [onInterruption])
+}
+
+type RecordingClockParams = {
+  readonly status: RecorderStatus
+  readonly maxDurationMs: number
+  readonly sessionRef: MutableRefObject<CaptureSession | undefined>
+  readonly setElapsedMs: Dispatch<SetStateAction<number>>
+  readonly stop: () => void
+}
+
+export function useRecordingClock({ status, maxDurationMs, sessionRef, setElapsedMs, stop }: RecordingClockParams): void {
+  useEffect(() => {
+    if (status !== 'recording') return undefined
+    const startedAt = sessionRef.current?.startedAt ?? Date.now()
+    const tick = setInterval(() => setElapsedMs(Date.now() - startedAt), ELAPSED_TICK_MS)
+    const ceiling = setTimeout(stop, maxDurationMs)
+    return () => {
+      clearInterval(tick)
+      clearTimeout(ceiling)
+    }
+  }, [status, maxDurationMs, sessionRef, setElapsedMs, stop])
+}
+
+type RecorderLifecycleParams = {
+  readonly status: RecorderStatus
+  readonly onCaptureChange: ((isCapturing: boolean) => void) | undefined
+  readonly teardown: () => void
+}
+
+export function useRecorderLifecycle({ status, onCaptureChange, teardown }: RecorderLifecycleParams): void {
+  const isCapturing = status === 'requesting' || status === 'recording' || status === 'review'
+  const reportedRef = useRef(false)
+  const onCaptureChangeRef = useRef(onCaptureChange)
+  onCaptureChangeRef.current = onCaptureChange
+
+  useEffect(() => {
+    if (reportedRef.current === isCapturing) return
+    reportedRef.current = isCapturing
+    onCaptureChangeRef.current?.(isCapturing)
+  }, [isCapturing])
+
+  useEffect(
+    () => () => {
+      teardown()
+      if (!reportedRef.current) return
+      reportedRef.current = false
+      onCaptureChangeRef.current?.(false)
+    },
+    [teardown],
+  )
+}

package/src/participant/useParticipantAudioSourceRetry.ts

@@ -0,0 +1,42 @@
+import { useEffect, useRef, type SyntheticEvent } from 'react'
+
+import type { PlayerContext } from './participantAudioPlayerState'
+
+export type UseParticipantAudioSourceRetryParams = {
+  readonly context: PlayerContext
+  readonly url: string | undefined
+  readonly onSourceError: (() => Promise<string | undefined>) | undefined
+}
+
+/** One retry with a fresh URL when the signed one expired, resuming from the same position. */
+export function useParticipantAudioSourceRetry({ context, url, onSourceError }: UseParticipantAudioSourceRetryParams) {
+  const { audioRef, update } = context
+  const canRetryRef = useRef(true)
+  const resumeAtRef = useRef<number | undefined>(undefined)
+
+  useEffect(() => {
+    const audio = audioRef.current
+    const resumeAt = resumeAtRef.current
+    if (!audio || resumeAt === undefined || !url) return
+    resumeAtRef.current = undefined
+    audio.currentTime = resumeAt
+    Promise.resolve(audio.play()).catch(() => update({ isPlaying: false }))
+  }, [url, audioRef, update])
+
+  function allowRetry(): void {
+    canRetryRef.current = true
+  }
+
+  function handleError(event: SyntheticEvent<HTMLAudioElement>): void {
+    if (!onSourceError || !canRetryRef.current) return update({ hasFailed: true, isPlaying: false })
+    canRetryRef.current = false
+    resumeAtRef.current = event.currentTarget.currentTime
+    onSourceError().then((fresh) => {
+      if (fresh && fresh !== url) return
+      resumeAtRef.current = undefined
+      update({ hasFailed: true, isPlaying: false })
+    })
+  }
+
+  return { handleError, allowRetry }
+}

package/src/participant/useParticipantSendAudio.test.tsx

@@ -0,0 +1,85 @@
+import { act } from 'react'
+
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test'
+
+import { setupDom, type DomHarness } from '../domHarness.test-helper'
+import type { ParticipantSendContent } from './participantDrafts'
+import { useParticipantSendAudio } from './useParticipantSendAudio'
+
+let harness: DomHarness
+let sendAudio: (file: File) => void
+let calls: ParticipantSendContent[]
+let releases: Array<() => void>
+
+function Probe() {
+  sendAudio = useParticipantSendAudio((content) => {
+    calls.push(content)
+    return new Promise<void>((resolve) => releases.push(resolve))
+  })
+  return null
+}
+
+beforeAll(async () => {
+  harness = await setupDom()
+})
+
+afterAll(() => harness.teardown())
+
+function mountProbe(): void {
+  calls = []
+  releases = []
+  harness.mount(<Probe />)
+}
+
+const audio = (name: string) => new File(['x'], name, { type: 'audio/ogg' })
+
+describe('useParticipantSendAudio', () => {
+  it('sends the file alone, as a message of its own', () => {
+    mountProbe()
+    const file = audio('a.ogg')
+    sendAudio(file)
+    expect(calls).toEqual([{ files: [file] }])
+  })
+
+  it('ignores a second synchronous send of the same file', () => {
+    mountProbe()
+    const file = audio('a.ogg')
+    sendAudio(file)
+    sendAudio(file)
+    expect(calls).toHaveLength(1)
+  })
+
+  it('lets another recording through while the first is still uploading, and the same one again once it settled', async () => {
+    mountProbe()
+    const first = audio('a.ogg')
+    sendAudio(first)
+    sendAudio(audio('b.ogg'))
+    expect(calls).toHaveLength(2)
+    await act(async () => releases[0]?.())
+    sendAudio(first)
+    expect(calls).toHaveLength(3)
+  })
+
+  it('a send that throws (for example randomUUID in an insecure context) is contained and frees the file for a retry', async () => {
+    const unhandled: unknown[] = []
+    const onUnhandled = (reason: unknown): void => void unhandled.push(reason)
+    process.on('unhandledRejection', onUnhandled)
+    let attempts = 0
+    function Throwing() {
+      sendAudio = useParticipantSendAudio(async () => {
+        attempts += 1
+        throw new Error('crypto.randomUUID is not a function')
+      })
+      return null
+    }
+    harness.mount(<Throwing />)
+    const file = audio('a.ogg')
+    sendAudio(file)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    sendAudio(file)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    process.off('unhandledRejection', onUnhandled)
+    expect(unhandled).toEqual([])
+    expect(attempts).toBe(2)
+  })
+})

package/src/participant/useParticipantSendAudio.ts

@@ -0,0 +1,28 @@
+import { useCallback, useRef } from 'react'
+
+import type { ParticipantSendContent } from './participantDrafts'
+
+/**
+ * Sends a recorded audio as its own message through the attachment path. The file itself is the
+ * lock: send generates a new client id per call, so the server idempotency would not stop a double tap.
+ */
+export function useParticipantSendAudio(send: (content: ParticipantSendContent) => Promise<unknown>): (file: File) => void {
+  const sendRef = useRef(send)
+  sendRef.current = send
+  const inFlightRef = useRef(new Set<File>())
+
+  return useCallback((file: File): void => {
+    const inFlight = inFlightRef.current
+    if (inFlight.has(file)) return
+    inFlight.add(file)
+    void (async () => {
+      try {
+        await sendRef.current({ files: [file] })
+      } catch {
+        // the send path reports its own failures; a throw before it (insecure context) must not become an unhandled rejection
+      } finally {
+        inFlight.delete(file)
+      }
+    })()
+  }, [])
+}

package/src/participant/useParticipantThreadController.ts

@@ -13,6 +13,7 @@ import { findFailedEntry, hasSendingEntry, type ParticipantSendAction } from './
 import type { ParticipantSendStates, ParticipantSendStatesAction } from './participantSendStates'
 import { useParticipantConversationView } from './useParticipantConversationView'
 import { useParticipantDraft } from './useParticipantDraft'
+import { useParticipantSendAudio } from './useParticipantSendAudio'
 import { useParticipantThread, type UseParticipantThreadResult } from './useParticipantThread'
 import { useParticipantThreadScroll } from './useParticipantThreadScroll'
 
@@ -53,6 +54,7 @@ export type ParticipantThreadCoreProps = Pick<
   | 'onLoadOlder'
   | 'pendingActions'
   | 'perspective'
+  | 'onSendAudio'
 >
 
 type BuildPendingActionsParams = {
@@ -71,25 +73,35 @@ function buildPendingActions({ thread, dispatchSend, handleEdit, onRetryPending
   }
 }
 
+type BuildEditHandlerParams = {
+  readonly sendEntries: Parameters<typeof findFailedEntry>[0]
+  readonly dispatchSend: (action: ParticipantSendAction) => void
+  readonly restoreFromEntry: (entry: NonNullable<ReturnType<typeof findFailedEntry>>) => void
+}
+
+function buildEditHandler({ sendEntries, dispatchSend, restoreFromEntry }: BuildEditHandlerParams): (clientMessageId: string) => void {
+  return (clientMessageId) => {
+    const entry = findFailedEntry(sendEntries, clientMessageId)
+    if (!entry) return
+    restoreFromEntry(entry)
+    dispatchSend({ type: 'discarded', clientMessageId })
+  }
+}
+
 export function useParticipantThreadController(params: ParticipantThreadControllerParams): ParticipantThreadCoreProps {
   const { api, subject, conversation, draftsRef } = params
   const { draft, setText, setFiles, takeForSend, restoreFromEntry } = useParticipantDraft(draftsRef, subject)
   const { thread, items, sendEntries, dispatchSend } = useParticipantConversationView(params)
   const resolveAttachmentUrl = useMemo(() => bindAttachmentUrlResolver(api), [api])
   const { scroll, newMessagesCount } = useParticipantThreadScroll(items, params.perspective)
+  const handleSendAudio = useParticipantSendAudio(thread.send)
+  const handleEdit = buildEditHandler({ sendEntries, dispatchSend, restoreFromEntry })
 
   function handleSend(): void {
     const content = takeForSend()
     if (content) void thread.send(content)
   }
 
-  function handleEdit(clientMessageId: string): void {
-    const entry = findFailedEntry(sendEntries, clientMessageId)
-    if (!entry) return
-    restoreFromEntry(entry)
-    dispatchSend({ type: 'discarded', clientMessageId })
-  }
-
   return {
     conversation,
     items,
@@ -108,5 +120,6 @@ export function useParticipantThreadController(params: ParticipantThreadControll
     onLoadOlder: () => void thread.loadOlder(),
     pendingActions: buildPendingActions({ thread, dispatchSend, handleEdit, onRetryPending: params.onRetryPending }),
     perspective: params.perspective,
+    onSendAudio: handleSendAudio,
   }
 }

package/src/participant/useStableAttachmentUrl.ts

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { ParticipantAttachment } from '@adatechnology/conversation-contracts'
+
+import type { ResolveParticipantAttachmentUrl } from './ParticipantAttachmentItem'
+import { isSafeAttachmentUrl } from './participantAttachmentUrl'
+
+export type StableAttachmentUrl = {
+  readonly status: 'pending' | 'ready' | 'failed'
+  readonly url: string | undefined
+  /** Asks the host for a fresh URL (the signed one expired); resolves undefined when it cannot. */
+  readonly resolveAgain: () => Promise<string | undefined>
+}
+
+export type StableAttachmentUrlParams = {
+  readonly attachment: ParticipantAttachment
+  readonly resolveAttachmentUrl: ResolveParticipantAttachmentUrl
+}
+
+type ResolvedState = Pick<StableAttachmentUrl, 'status' | 'url'>
+
+export const ATTACHMENT_URL_RETRY_DELAY_MS = 1000
+
+const PENDING_STATE: ResolvedState = { status: 'pending', url: undefined }
+
+async function resolveSafely({ attachment, resolveAttachmentUrl }: StableAttachmentUrlParams): Promise<string | undefined> {
+  try {
+    const resolved = await resolveAttachmentUrl(attachment, 'inline')
+    return isSafeAttachmentUrl(resolved) ? resolved.trim() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Resolves once per `attachment.id`: a refreshed conversation hands over a new object and URL, and swapping `src` restarts the audio. */
+export function useStableAttachmentUrl(params: StableAttachmentUrlParams): StableAttachmentUrl {
+  const latest = useRef(params)
+  const currentId = useRef(params.attachment.id)
+  const [state, setState] = useState<ResolvedState>(PENDING_STATE)
+  const { id } = params.attachment
+
+  useEffect(() => {
+    latest.current = params
+  })
+
+  useEffect(() => {
+    currentId.current = id
+    setState(PENDING_STATE)
+    let retryTimer: ReturnType<typeof setTimeout> | undefined
+    const settle = (url: string | undefined): void => {
+      if (currentId.current === id) setState(url ? { status: 'ready', url } : { status: 'failed', url: undefined })
+    }
+    resolveSafely(latest.current).then((url) => {
+      if (url || currentId.current !== id) return settle(url)
+      retryTimer = setTimeout(() => void resolveSafely(latest.current).then(settle), ATTACHMENT_URL_RETRY_DELAY_MS)
+    })
+    return () => {
+      currentId.current = ''
+      clearTimeout(retryTimer)
+    }
+  }, [id])
+
+  const resolveAgain = useCallback(async (): Promise<string | undefined> => {
+    const requestedId = currentId.current
+    const url = await resolveSafely(latest.current)
+    if (url && currentId.current === requestedId) setState({ status: 'ready', url })
+    return url
+  }, [])
+
+  return { ...state, resolveAgain }
+}

package/src/participant/useTranscriptionOverflow.ts

@@ -0,0 +1,25 @@
+import { useEffect, useRef, useState, type RefObject } from 'react'
+
+export type TranscriptionOverflow = {
+  readonly textRef: RefObject<HTMLParagraphElement | null>
+  readonly isOverflowing: boolean
+}
+
+/** Measures the clamped paragraph; nothing is claimed before layout exists (server render, first paint). */
+export function useTranscriptionOverflow(text: string, isExpanded: boolean): TranscriptionOverflow {
+  const textRef = useRef<HTMLParagraphElement | null>(null)
+  const [isOverflowing, setIsOverflowing] = useState(false)
+
+  useEffect(() => {
+    const element = textRef.current
+    if (!element || isExpanded) return undefined
+    const measure = (): void => setIsOverflowing(element.scrollHeight > element.clientHeight)
+    measure()
+    if (typeof ResizeObserver === 'undefined') return undefined
+    const observer = new ResizeObserver(measure)
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [text, isExpanded])
+
+  return { textRef, isOverflowing }
+}

package/src/participant/useTranscriptionReadyAnnouncement.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from 'react'
+
+import type { ParticipantTranscription } from '@adatechnology/conversation-contracts'
+
+import { useAnnounceCopy } from './ParticipantCopyAnnouncer'
+
+export type TranscriptionReadyAnnouncementParams = {
+  readonly attachmentId: string
+  readonly status: ParticipantTranscription['status'] | undefined
+  readonly text: string
+}
+
+/** Speaks through the thread's existing live region, only for a pending to ready change seen by this mount. */
+export function useTranscriptionReadyAnnouncement({ attachmentId, status, text }: TranscriptionReadyAnnouncementParams): void {
+  const announce = useAnnounceCopy()
+  const previous = useRef({ attachmentId, status })
+
+  useEffect(() => {
+    const before = previous.current
+    previous.current = { attachmentId, status }
+    if (before.attachmentId !== attachmentId) return
+    if (before.status === 'pending' && status === 'ready') announce(text)
+  }, [announce, attachmentId, status, text])
+}