@magmamath/students-features 0.9.113 → 0.9.114-rc.1

package/src/shared/components/PlayButton.tsx

@@ -0,0 +1,84 @@
+import React from 'react'
+import { ActivityIndicator } from 'react-native'
+import { Button, COLORS } from '@magmamath/react-native-ui'
+
+import { SpeakerIcon } from '../icons/SpeakerIcon'
+import { PlayIcon } from '../icons/PlayIcon'
+import { PauseIcon } from '../icons/PauseIcon'
+import { AudioStatus } from '../../features/chatbot/types/t2s.types'
+import { CONTROLS_COLORS_MAP } from '../../features/chatbot/constants'
+import { ColorScheme } from '../../features/chatbot/types/style.types'
+
+type TextToSpeechIconProps = {
+  status?: AudioStatus
+  isLoading?: boolean
+  isActive?: boolean
+  colorScheme?: ColorScheme
+  activityIndicatorColor?: string
+}
+
+const TextToSpeechIcon = ({
+  status,
+  isActive,
+  isLoading,
+  colorScheme = ColorScheme.Blue,
+  activityIndicatorColor,
+}: TextToSpeechIconProps) => {
+  if (isLoading && isActive) {
+    return (
+      <ActivityIndicator
+        color={activityIndicatorColor || CONTROLS_COLORS_MAP[colorScheme].background}
+      />
+    )
+  }
+
+  if (!isActive) {
+    return <SpeakerIcon />
+  }
+
+  if (status === 'playing') return <PauseIcon color={COLORS.NEUTRAL_1} />
+  if (status === 'paused') return <PlayIcon color={COLORS.NEUTRAL_1} />
+  return <SpeakerIcon />
+}
+
+type MessageTextToSpeechProps = {
+  state: {
+    status?: AudioStatus
+    isActive?: boolean
+    isLoading?: boolean
+    disabled?: boolean
+    isEnabled?: boolean
+  }
+  activityIndicatorColor?: string
+  colorScheme?: ColorScheme
+  onPress?: () => void
+}
+
+export const PlayButton = ({
+  state: { status, disabled, isActive, isLoading },
+  colorScheme = ColorScheme.Blue,
+  onPress,
+  activityIndicatorColor,
+  ...props
+}: MessageTextToSpeechProps) => {
+  return (
+    <Button
+      disabled={disabled}
+      isActive={isActive}
+      variant={'secondary'}
+      colorScheme={colorScheme}
+      size={'small'}
+      onPress={onPress}
+      icon={
+        <TextToSpeechIcon
+          isActive={isActive}
+          isLoading={isLoading}
+          status={status}
+          colorScheme={colorScheme}
+          activityIndicatorColor={activityIndicatorColor}
+        />
+      }
+      {...props}
+    />
+  )
+}

package/src/shared/translation/localization/ca.json

@@ -39,5 +39,22 @@
     "volume": "Volume",
     "weight": "Weight",
     "time": "Time"
+  },
+  "voice": {
+    "deleteRecording": "Delete recording?",
+    "youWontBeAbleToRecover": "You won't be able to recover this file once it's gone.",
+    "recordingDeleted": "Recording successfully deleted.",
+    "delete": "Delete",
+    "cancel": "Cancel",
+    "noMicrophoneAccess": "No microphone access.",
+    "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
+    "noMicrophoneFound": "No microphone found.",
+    "uploadFailed": "Upload failed. Please try again.",
+    "redoRecording": "Redo recording?",
+    "redo": "Redo",
+    "thisWillRemoveRecording": "This will remove your previous recording.",
+    "transcriptions": "Transcriptions",
+    "attempt": "Attempt {{number}}",
+    "transcriptNotAvailable": "Transcript not available"
   }
 }

package/src/shared/translation/localization/de.json

@@ -39,5 +39,22 @@
     "volume": "Volumen",
     "weight": "Gewicht",
     "time": "Zeit"
+  },
+  "voice": {
+    "deleteRecording": "Aufnahme löschen?",
+    "youWontBeAbleToRecover": "Du kannst die Datei nicht wiederherstellen, wenn sie einmal gelöscht ist.",
+    "recordingDeleted": "Aufnahme gelöscht.",
+    "delete": "Löschen",
+    "cancel": "Abbrechen",
+    "noMicrophoneAccess": "Kein Mikrofon-Zugriff.",
+    "noMicrophoneAccessBySystem": "Mikrofonzugriff durch Systemeinstellungen verweigert.",
+    "noMicrophoneFound": "Kein Mikrofon gefunden.",
+    "uploadFailed": "Hochladen fehlgeschlagen. Bitte versuche es erneut.",
+    "redoRecording": "Aufnahme erneut aufnehmen?",
+    "redo": "Wiederholen",
+    "thisWillRemoveRecording": "Dadurch wird die Aufnahme entfernt.",
+    "transcriptions": "Transkriptionen",
+    "attempt": "Versuch {{number}}",
+    "transcriptNotAvailable": "Transkript nicht verfügbar"
   }
 }

package/src/shared/translation/localization/en.json

@@ -39,5 +39,22 @@
     "volume": "Volume",
     "weight": "Weight",
     "time": "Time"
+  },
+  "voice": {
+    "deleteRecording": "Delete recording?",
+    "youWontBeAbleToRecover": "You won't be able to recover this file once it's gone.",
+    "recordingDeleted": "Recording successfully deleted.",
+    "delete": "Delete",
+    "cancel": "Cancel",
+    "noMicrophoneAccess": "No microphone access.",
+    "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
+    "noMicrophoneFound": "No microphone found.",
+    "uploadFailed": "Upload failed. Please try again.",
+    "redoRecording": "Redo recording?",
+    "redo": "Redo",
+    "thisWillRemoveRecording": "This will remove your previous recording.",
+    "transcriptions": "Transcriptions",
+    "attempt": "Attempt {{number}}",
+    "transcriptNotAvailable": "Transcript not available"
   }
 }

package/src/shared/translation/localization/gb.json

@@ -39,5 +39,22 @@
     "volume": "Volume",
     "weight": "Weight",
     "time": "Time"
+  },
+  "voice": {
+    "deleteRecording": "Delete recording?",
+    "youWontBeAbleToRecover": "You won't be able to recover this file once it's gone.",
+    "recordingDeleted": "Recording successfully deleted.",
+    "delete": "Delete",
+    "cancel": "Cancel",
+    "noMicrophoneAccess": "No microphone access.",
+    "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
+    "noMicrophoneFound": "No microphone found.",
+    "uploadFailed": "Upload failed. Please try again.",
+    "redoRecording": "Redo recording?",
+    "redo": "Redo",
+    "thisWillRemoveRecording": "This will remove your previous recording.",
+    "transcriptions": "Transcriptions",
+    "attempt": "Attempt {{number}}",
+    "transcriptNotAvailable": "Transcript not available"
   }
 }

package/src/shared/translation/localization/sct.json

@@ -39,5 +39,22 @@
     "volume": "Volume",
     "weight": "Weight",
     "time": "Time"
+  },
+  "voice": {
+    "deleteRecording": "Delete recording?",
+    "youWontBeAbleToRecover": "You won't be able to recover this file once it's gone.",
+    "recordingDeleted": "Recording successfully deleted.",
+    "delete": "Delete",
+    "cancel": "Cancel",
+    "noMicrophoneAccess": "No microphone access.",
+    "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
+    "noMicrophoneFound": "No microphone found.",
+    "uploadFailed": "Upload failed. Please try again.",
+    "redoRecording": "Redo recording?",
+    "redo": "Redo",
+    "thisWillRemoveRecording": "This will remove your previous recording.",
+    "transcriptions": "Transcriptions",
+    "attempt": "Attempt {{number}}",
+    "transcriptNotAvailable": "Transcript not available"
   }
 }

package/src/shared/translation/localization/sw.json

@@ -39,5 +39,22 @@
     "volume": "Volym",
     "weight": "Vikt",
     "time": "Tid"
+  },
+  "voice": {
+    "deleteRecording": "Radera inspelningen?",
+    "youWontBeAbleToRecover": "Du kommer inte att kunna återställa filen när den väl är borta.",
+    "recordingDeleted": "Inspelningen raderad.",
+    "delete": "Radera",
+    "cancel": "Avbryt",
+    "noMicrophoneAccess": "Ingen mikrofonåtkomst.",
+    "noMicrophoneAccessBySystem": "Mikrofonåtkomst nekad av systeminställningar.",
+    "noMicrophoneFound": "Ingen mikrofon hittades.",
+    "uploadFailed": "Uppladdning misslyckades. Försök igen.",
+    "redoRecording": "Spela in igen?",
+    "redo": "Gör om",
+    "thisWillRemoveRecording": "Detta tar bort inspelningen.",
+    "transcriptions": "Transkriptioner",
+    "attempt": "Försök {{number}}",
+    "transcriptNotAvailable": "Transkript inte tillgängligt"
   }
 }

package/src/types/common.types.ts

@@ -4,5 +4,6 @@ export type Size = {
   width: number
   height: number
 }
+export type WithAbortSignal<T> = T & { signal?: AbortSignal }
 
 export type ColorValue = (typeof COLORS)[keyof typeof COLORS]

package/dist/commonjs/features/chatbot/TTS_HIGHLIGHTING.md

@@ -1,120 +0,0 @@
-# TTS Word-by-Word Highlighting
-
-## Overview
-
-Word-by-word text highlighting synchronized with text-to-speech playback in the chatbot. The feature is optional and enabled via `isWordHighlightEnabled` config flag.
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  1. User clicks TTS button on a message                         │
-│                           ↓                                     │
-│  2. Text is converted to SSML with word marks                   │
-│     "Hello world" → <speak><mark name="w_0"/>Hello              │
-│                            <mark name="w_1"/>world</speak>      │
-│                           ↓                                     │
-│  3. Google TTS API returns audio + timepoints                   │
-│     [{ markName: "w_0", timeSeconds: 0.0 },                     │
-│      { markName: "w_1", timeSeconds: 0.5 }]                     │
-│                           ↓                                     │
-│  4. Audio plays, onTimeUpdate fires via RAF loop                │
-│                           ↓                                     │
-│  5. Current time → find matching timepoint → word index         │
-│                           ↓                                     │
-│  6. $highlightedWordIndex updates → UI re-renders highlighted   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Usage
-
-```tsx
-// In students-web model setup
-chatModel.bot.setUpT2S({
-  audioProvider: createT2SAudioProvider(),
-  textSanitizer: removeKatexPartFromTextToSpeech,
-  isWordHighlightEnabled: true,
-})
-```
-
-## Architecture
-
-### ChatTTSModel (ChatTTSModel.ts)
-
-Handles TTS playback and word highlighting. Key design decisions:
-
-- **Map-based cache** — `audioCache: Map<string, AudioCache>` stores both `audioPath` and `timepoints` per message. When highlighting is off, `timepoints` is `[]`. Cache lives for the model's lifetime (cleared when user leaves the problem).
-- **`fetchAudio()` method** — encapsulates API call + audioContent decoding. Highlight vs non-highlight differences are ternaries (SSML vs plain text, `enableTimePointing`).
-- **`play()` is linear** — cache lookup → fetch if miss → store → activate highlight if enabled → play audio. No branching between highlight/non-highlight paths.
-- **Pause/resume guards** — `wordHighlightEnabled` check before toggling `setIsActive(false)`/`setIsActive(true)` on pause/resume.
-- **`wordHighlightEnabled` (private)** — stored result of `!!isWordHighlightEnabled && !!audioProvider.onTimeUpdate`. Set once at `setConfig`.
-- **`isWordHighlightEnabled` (public getter)** — read-only access for external consumers (e.g. `Chat.tsx`).
-
-### AudioProvider type
-
-```typescript
-type AudioProvider = {
-  play: (audioPath: string, onPlaybackComplete: () => void) => Promise<void>
-  pause: () => void
-  resume: () => void
-  stop: () => void
-  onTimeUpdate?: OnTimeUpdate  // optional — presence enables highlight capability
-}
-```
-
-`onTimeUpdate` is optional. It's the mechanism that syncs audio playback time with word highlights via a RAF loop. If the provider doesn't have it, highlighting won't activate even if `isWordHighlightEnabled: true`.
-
-### ChatTTSHighlightModel (ChatTTSHighlightModel.ts)
-
-Manages highlight state using Effector stores with declarative reset. Receives `OnTimeUpdate` callback directly (not the whole `AudioProvider`).
-
-- **`$isActive`** — gates `$highlightedWordIndex` computation. Toggled on pause/resume without resetting timepoints.
-- **`$highlightedWordIndex`** — derived store, returns `-1` when inactive or no match. Parses mark name via `WORD_MARK_REGEX`.
-- **`activate(timepoints, onTimeUpdate)`** — sets timepoints, enables highlighting, registers time update callback. Only triggers store updates when the highlighted word actually changes (`lastMark` comparison).
-- **`deactivate(onTimeUpdate)`** — stops listening, resets all state via declarative `.reset()` chain.
-- **All stores use `.reset(this.reset)`** — single `reset` event clears `$time`, `$timepoints`, and `$isActive`.
-
-### Helpers (helpers/ttsHighlight.ts)
-
-- **`textToSSML(text)`** — converts plain text to SSML with `<mark>` tags for word timing.
-- **`findCurrentMark(timepoints, time)`** — iterates backwards through timepoints to find the current mark. Efficient for linear playback.
-
-### Constants (constants.ts)
-
-- **`WORD_MARK_REGEX`** — `/^w_(\d+)$/` — extracts word index from mark names like `w_0`, `w_1`.
-
-### Naming conventions
-
-| Name | Scope | Purpose |
-|------|-------|---------|
-| `wordHighlight` | public instance | `ChatTTSHighlightModel` instance on `ChatTTSModel` |
-| `wordHighlightEnabled` | private field | Whether highlighting is active (set once at config) |
-| `isWordHighlightEnabled` | public getter | Read-only access to `wordHighlightEnabled` for external consumers |
-| `isWordHighlightEnabled` | T2SConfig field | Config flag passed to `setUpT2S()` |
-
-## Data Flow
-
-```
-AudioProvider.onTimeUpdate(callback)
-       ↓
-ChatTTSHighlightModel.activate(timepoints, onTimeUpdate)
-       ↓
-RAF loop → audio.currentTime → findCurrentMark() → only updates when mark changes
-       ↓
-$highlightedWordIndex = parse mark name "w_N" → N (or -1 if inactive/no match)
-       ↓
-Chat.tsx: model.t2s.isWordHighlightEnabled && isPlayingMessage ? highlightedWordIndex : -1
-       ↓
-ChatMessage → MessageContent → TTSHighlightRenderer({ text, highlightedIndex })
-```
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `model/ChatTTSModel.ts` | `ChatTTSModel` — TTS playback, caching, highlight orchestration |
-| `model/ChatTTSHighlightModel.ts` | Highlight state — timepoints, current time, `$isActive`, derived word index |
-| `helpers/ttsHighlight.ts` | `textToSSML` + `findCurrentMark` — SSML conversion and playback position lookup |
-| `constants.ts` | `WORD_MARK_REGEX` and audio config defaults |
-| `types/t2s.types.ts` | `AudioProvider`, `OnTimeUpdate`, `AudioStatus`, `AudioCache`, `TTSHighlightRendererProps` types |
-| `components/Chat/Chat.tsx` | Reads `isWordHighlightEnabled` and `$highlightedWordIndex`, passes to messages |

package/dist/module/features/chatbot/TTS_HIGHLIGHTING.md

@@ -1,120 +0,0 @@
-# TTS Word-by-Word Highlighting
-
-## Overview
-
-Word-by-word text highlighting synchronized with text-to-speech playback in the chatbot. The feature is optional and enabled via `isWordHighlightEnabled` config flag.
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  1. User clicks TTS button on a message                         │
-│                           ↓                                     │
-│  2. Text is converted to SSML with word marks                   │
-│     "Hello world" → <speak><mark name="w_0"/>Hello              │
-│                            <mark name="w_1"/>world</speak>      │
-│                           ↓                                     │
-│  3. Google TTS API returns audio + timepoints                   │
-│     [{ markName: "w_0", timeSeconds: 0.0 },                     │
-│      { markName: "w_1", timeSeconds: 0.5 }]                     │
-│                           ↓                                     │
-│  4. Audio plays, onTimeUpdate fires via RAF loop                │
-│                           ↓                                     │
-│  5. Current time → find matching timepoint → word index         │
-│                           ↓                                     │
-│  6. $highlightedWordIndex updates → UI re-renders highlighted   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Usage
-
-```tsx
-// In students-web model setup
-chatModel.bot.setUpT2S({
-  audioProvider: createT2SAudioProvider(),
-  textSanitizer: removeKatexPartFromTextToSpeech,
-  isWordHighlightEnabled: true,
-})
-```
-
-## Architecture
-
-### ChatTTSModel (ChatTTSModel.ts)
-
-Handles TTS playback and word highlighting. Key design decisions:
-
-- **Map-based cache** — `audioCache: Map<string, AudioCache>` stores both `audioPath` and `timepoints` per message. When highlighting is off, `timepoints` is `[]`. Cache lives for the model's lifetime (cleared when user leaves the problem).
-- **`fetchAudio()` method** — encapsulates API call + audioContent decoding. Highlight vs non-highlight differences are ternaries (SSML vs plain text, `enableTimePointing`).
-- **`play()` is linear** — cache lookup → fetch if miss → store → activate highlight if enabled → play audio. No branching between highlight/non-highlight paths.
-- **Pause/resume guards** — `wordHighlightEnabled` check before toggling `setIsActive(false)`/`setIsActive(true)` on pause/resume.
-- **`wordHighlightEnabled` (private)** — stored result of `!!isWordHighlightEnabled && !!audioProvider.onTimeUpdate`. Set once at `setConfig`.
-- **`isWordHighlightEnabled` (public getter)** — read-only access for external consumers (e.g. `Chat.tsx`).
-
-### AudioProvider type
-
-```typescript
-type AudioProvider = {
-  play: (audioPath: string, onPlaybackComplete: () => void) => Promise<void>
-  pause: () => void
-  resume: () => void
-  stop: () => void
-  onTimeUpdate?: OnTimeUpdate  // optional — presence enables highlight capability
-}
-```
-
-`onTimeUpdate` is optional. It's the mechanism that syncs audio playback time with word highlights via a RAF loop. If the provider doesn't have it, highlighting won't activate even if `isWordHighlightEnabled: true`.
-
-### ChatTTSHighlightModel (ChatTTSHighlightModel.ts)
-
-Manages highlight state using Effector stores with declarative reset. Receives `OnTimeUpdate` callback directly (not the whole `AudioProvider`).
-
-- **`$isActive`** — gates `$highlightedWordIndex` computation. Toggled on pause/resume without resetting timepoints.
-- **`$highlightedWordIndex`** — derived store, returns `-1` when inactive or no match. Parses mark name via `WORD_MARK_REGEX`.
-- **`activate(timepoints, onTimeUpdate)`** — sets timepoints, enables highlighting, registers time update callback. Only triggers store updates when the highlighted word actually changes (`lastMark` comparison).
-- **`deactivate(onTimeUpdate)`** — stops listening, resets all state via declarative `.reset()` chain.
-- **All stores use `.reset(this.reset)`** — single `reset` event clears `$time`, `$timepoints`, and `$isActive`.
-
-### Helpers (helpers/ttsHighlight.ts)
-
-- **`textToSSML(text)`** — converts plain text to SSML with `<mark>` tags for word timing.
-- **`findCurrentMark(timepoints, time)`** — iterates backwards through timepoints to find the current mark. Efficient for linear playback.
-
-### Constants (constants.ts)
-
-- **`WORD_MARK_REGEX`** — `/^w_(\d+)$/` — extracts word index from mark names like `w_0`, `w_1`.
-
-### Naming conventions
-
-| Name | Scope | Purpose |
-|------|-------|---------|
-| `wordHighlight` | public instance | `ChatTTSHighlightModel` instance on `ChatTTSModel` |
-| `wordHighlightEnabled` | private field | Whether highlighting is active (set once at config) |
-| `isWordHighlightEnabled` | public getter | Read-only access to `wordHighlightEnabled` for external consumers |
-| `isWordHighlightEnabled` | T2SConfig field | Config flag passed to `setUpT2S()` |
-
-## Data Flow
-
-```
-AudioProvider.onTimeUpdate(callback)
-       ↓
-ChatTTSHighlightModel.activate(timepoints, onTimeUpdate)
-       ↓
-RAF loop → audio.currentTime → findCurrentMark() → only updates when mark changes
-       ↓
-$highlightedWordIndex = parse mark name "w_N" → N (or -1 if inactive/no match)
-       ↓
-Chat.tsx: model.t2s.isWordHighlightEnabled && isPlayingMessage ? highlightedWordIndex : -1
-       ↓
-ChatMessage → MessageContent → TTSHighlightRenderer({ text, highlightedIndex })
-```
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `model/ChatTTSModel.ts` | `ChatTTSModel` — TTS playback, caching, highlight orchestration |
-| `model/ChatTTSHighlightModel.ts` | Highlight state — timepoints, current time, `$isActive`, derived word index |
-| `helpers/ttsHighlight.ts` | `textToSSML` + `findCurrentMark` — SSML conversion and playback position lookup |
-| `constants.ts` | `WORD_MARK_REGEX` and audio config defaults |
-| `types/t2s.types.ts` | `AudioProvider`, `OnTimeUpdate`, `AudioStatus`, `AudioCache`, `TTSHighlightRendererProps` types |
-| `components/Chat/Chat.tsx` | Reads `isWordHighlightEnabled` and `$highlightedWordIndex`, passes to messages |

package/src/features/chatbot/TTS_HIGHLIGHTING.md

@@ -1,120 +0,0 @@
-# TTS Word-by-Word Highlighting
-
-## Overview
-
-Word-by-word text highlighting synchronized with text-to-speech playback in the chatbot. The feature is optional and enabled via `isWordHighlightEnabled` config flag.
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  1. User clicks TTS button on a message                         │
-│                           ↓                                     │
-│  2. Text is converted to SSML with word marks                   │
-│     "Hello world" → <speak><mark name="w_0"/>Hello              │
-│                            <mark name="w_1"/>world</speak>      │
-│                           ↓                                     │
-│  3. Google TTS API returns audio + timepoints                   │
-│     [{ markName: "w_0", timeSeconds: 0.0 },                     │
-│      { markName: "w_1", timeSeconds: 0.5 }]                     │
-│                           ↓                                     │
-│  4. Audio plays, onTimeUpdate fires via RAF loop                │
-│                           ↓                                     │
-│  5. Current time → find matching timepoint → word index         │
-│                           ↓                                     │
-│  6. $highlightedWordIndex updates → UI re-renders highlighted   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Usage
-
-```tsx
-// In students-web model setup
-chatModel.bot.setUpT2S({
-  audioProvider: createT2SAudioProvider(),
-  textSanitizer: removeKatexPartFromTextToSpeech,
-  isWordHighlightEnabled: true,
-})
-```
-
-## Architecture
-
-### ChatTTSModel (ChatTTSModel.ts)
-
-Handles TTS playback and word highlighting. Key design decisions:
-
-- **Map-based cache** — `audioCache: Map<string, AudioCache>` stores both `audioPath` and `timepoints` per message. When highlighting is off, `timepoints` is `[]`. Cache lives for the model's lifetime (cleared when user leaves the problem).
-- **`fetchAudio()` method** — encapsulates API call + audioContent decoding. Highlight vs non-highlight differences are ternaries (SSML vs plain text, `enableTimePointing`).
-- **`play()` is linear** — cache lookup → fetch if miss → store → activate highlight if enabled → play audio. No branching between highlight/non-highlight paths.
-- **Pause/resume guards** — `wordHighlightEnabled` check before toggling `setIsActive(false)`/`setIsActive(true)` on pause/resume.
-- **`wordHighlightEnabled` (private)** — stored result of `!!isWordHighlightEnabled && !!audioProvider.onTimeUpdate`. Set once at `setConfig`.
-- **`isWordHighlightEnabled` (public getter)** — read-only access for external consumers (e.g. `Chat.tsx`).
-
-### AudioProvider type
-
-```typescript
-type AudioProvider = {
-  play: (audioPath: string, onPlaybackComplete: () => void) => Promise<void>
-  pause: () => void
-  resume: () => void
-  stop: () => void
-  onTimeUpdate?: OnTimeUpdate  // optional — presence enables highlight capability
-}
-```
-
-`onTimeUpdate` is optional. It's the mechanism that syncs audio playback time with word highlights via a RAF loop. If the provider doesn't have it, highlighting won't activate even if `isWordHighlightEnabled: true`.
-
-### ChatTTSHighlightModel (ChatTTSHighlightModel.ts)
-
-Manages highlight state using Effector stores with declarative reset. Receives `OnTimeUpdate` callback directly (not the whole `AudioProvider`).
-
-- **`$isActive`** — gates `$highlightedWordIndex` computation. Toggled on pause/resume without resetting timepoints.
-- **`$highlightedWordIndex`** — derived store, returns `-1` when inactive or no match. Parses mark name via `WORD_MARK_REGEX`.
-- **`activate(timepoints, onTimeUpdate)`** — sets timepoints, enables highlighting, registers time update callback. Only triggers store updates when the highlighted word actually changes (`lastMark` comparison).
-- **`deactivate(onTimeUpdate)`** — stops listening, resets all state via declarative `.reset()` chain.
-- **All stores use `.reset(this.reset)`** — single `reset` event clears `$time`, `$timepoints`, and `$isActive`.
-
-### Helpers (helpers/ttsHighlight.ts)
-
-- **`textToSSML(text)`** — converts plain text to SSML with `<mark>` tags for word timing.
-- **`findCurrentMark(timepoints, time)`** — iterates backwards through timepoints to find the current mark. Efficient for linear playback.
-
-### Constants (constants.ts)
-
-- **`WORD_MARK_REGEX`** — `/^w_(\d+)$/` — extracts word index from mark names like `w_0`, `w_1`.
-
-### Naming conventions
-
-| Name | Scope | Purpose |
-|------|-------|---------|
-| `wordHighlight` | public instance | `ChatTTSHighlightModel` instance on `ChatTTSModel` |
-| `wordHighlightEnabled` | private field | Whether highlighting is active (set once at config) |
-| `isWordHighlightEnabled` | public getter | Read-only access to `wordHighlightEnabled` for external consumers |
-| `isWordHighlightEnabled` | T2SConfig field | Config flag passed to `setUpT2S()` |
-
-## Data Flow
-
-```
-AudioProvider.onTimeUpdate(callback)
-       ↓
-ChatTTSHighlightModel.activate(timepoints, onTimeUpdate)
-       ↓
-RAF loop → audio.currentTime → findCurrentMark() → only updates when mark changes
-       ↓
-$highlightedWordIndex = parse mark name "w_N" → N (or -1 if inactive/no match)
-       ↓
-Chat.tsx: model.t2s.isWordHighlightEnabled && isPlayingMessage ? highlightedWordIndex : -1
-       ↓
-ChatMessage → MessageContent → TTSHighlightRenderer({ text, highlightedIndex })
-```
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `model/ChatTTSModel.ts` | `ChatTTSModel` — TTS playback, caching, highlight orchestration |
-| `model/ChatTTSHighlightModel.ts` | Highlight state — timepoints, current time, `$isActive`, derived word index |
-| `helpers/ttsHighlight.ts` | `textToSSML` + `findCurrentMark` — SSML conversion and playback position lookup |
-| `constants.ts` | `WORD_MARK_REGEX` and audio config defaults |
-| `types/t2s.types.ts` | `AudioProvider`, `OnTimeUpdate`, `AudioStatus`, `AudioCache`, `TTSHighlightRendererProps` types |
-| `components/Chat/Chat.tsx` | Reads `isWordHighlightEnabled` and `$highlightedWordIndex`, passes to messages |