@magmamath/students-features 0.11.0-rc.9 → 1.0.0

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 |

package/src/features/chatbot/components/Chat/CloseButton.tsx

@@ -1,31 +0,0 @@
-import React from 'react'
-import { StyleSheet } from 'react-native'
-import { Button, ButtonColor, ButtonSize, ButtonVariant, COLORS } from '@magmamath/react-native-ui'
-import { CloseIcon } from '../../../../shared/icons/CloseIcon'
-
-type CloseButtonProps = {
-  onPress?: () => void
-}
-
-export const CloseButton = ({ onPress }: CloseButtonProps) => (
-  <Button
-    onPress={onPress}
-    style={{ button: styles.button }}
-    variant={ButtonVariant.PRIMARY}
-    size={ButtonSize.MEDIUM}
-    colorScheme={ButtonColor.WHITE}
-    raiseLevel={5}
-  >
-    <CloseIcon width={18} height={18} />
-  </Button>
-)
-
-const styles = StyleSheet.create({
-  button: {
-    width: 38,
-    height: 38,
-    borderRadius: 36,
-    paddingHorizontal: 0,
-    borderColor: COLORS.NEUTRAL_5,
-  },
-})

package/src/features/chatbot/components/Chat/GradientFade.tsx

@@ -1,43 +0,0 @@
-import React from 'react'
-import { Platform, StyleSheet, View, ViewStyle } from 'react-native'
-
-type GradientFadeProps = {
-  colors: string[]
-  locations?: number[]
-  style?: ViewStyle
-}
-
-const WebGradient = ({ colors, locations, style }: GradientFadeProps) => {
-  const stops = colors
-    .map((color, i) => {
-      const position = locations ? `${locations[i] * 100}%` : undefined
-      return position ? `${color} ${position}` : color
-    })
-    .join(', ')
-
-  return (
-    <View
-      style={[
-        StyleSheet.absoluteFill,
-        style,
-        { backgroundImage: `linear-gradient(to bottom, ${stops})` } as any,
-      ]}
-    />
-  )
-}
-
-const NativeGradient = ({ colors, locations, style }: GradientFadeProps) => {
-  const { LinearGradient } = require('expo-linear-gradient')
-  return (
-    <LinearGradient
-      colors={colors}
-      locations={locations}
-      style={[StyleSheet.absoluteFill, style]}
-    />
-  )
-}
-
-export const GradientFade = Platform.select({
-  web: WebGradient,
-  default: NativeGradient,
-})

package/src/features/chatbot/components/ChatMessage/AnimatedMessage.tsx

@@ -1,30 +0,0 @@
-import React, { PropsWithChildren, useEffect } from 'react'
-import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated'
-
-const INITIAL_OFFSET = 25
-const SPRING_CONFIG = { mass: 1.1, stiffness: 177, damping: 20 }
-
-type AnimatedMessageProps = PropsWithChildren<{ animate?: boolean }>
-
-export const AnimatedMessage = ({ children, animate = true }: AnimatedMessageProps) => {
-  const translateY = useSharedValue(animate ? INITIAL_OFFSET : 0)
-
-  useEffect(() => {
-    if (animate) {
-      translateY.value = withSpring(0, SPRING_CONFIG)
-    }
-  }, [])
-
-  const animatedStyle = useAnimatedStyle(
-    () => ({
-      transform: [{ translateY: translateY.value }],
-    }),
-    [translateY],
-  )
-
-  return (
-    <Animated.View style={[animate && animatedStyle, { alignItems: 'flex-end' }]}>
-      {children}
-    </Animated.View>
-  )
-}