@magmamath/students-features 1.7.9 → 1.7.10-rc.2

package/src/features/voice/recording/model/VoiceRecordWithTranscript.model.ts

@@ -0,0 +1,104 @@
+import { createEffect, Effect, sample } from 'effector'
+
+import { NO_AUDIO_BE_MESSAGE, VoiceRecorderState } from '../../constants'
+import { fetchTranscriptWithRetry, GetAudioFileTranscript } from '../../transcript.helpers'
+import { VoiceTranscriptPanelModel } from './VoiceTranscriptPanel.model'
+import type { VoiceRecordModel } from './VoiceRecord.model'
+import type { VoiceRecordCollectionItem } from '../../types'
+
+export type VoiceRecordWithTranscriptModelProps = {
+  recordModel: VoiceRecordModel
+  getTranscript: GetAudioFileTranscript
+}
+
+type ResultGuardSource = {
+  currentRecord: VoiceRecordCollectionItem | null
+  isDismissPending: boolean
+}
+
+// Wires the existing recording flow to the transcript panel:
+// recording starts → panel opens with the waveform; the recording is confirmed
+// (upload kicks off) → panel shows the loader; the uploaded file's transcript
+// arrives → panel shows the text. Deleting/discarding the record closes the panel.
+export class VoiceRecordWithTranscriptModel {
+  public readonly record: VoiceRecordModel
+  public readonly panel = new VoiceTranscriptPanelModel()
+
+  private readonly resolveTranscriptFx: Effect<VoiceRecordCollectionItem, string>
+
+  constructor({ recordModel, getTranscript }: VoiceRecordWithTranscriptModelProps) {
+    this.record = recordModel
+    this.resolveTranscriptFx = createEffect(async (record: VoiceRecordCollectionItem) => {
+      const upload = await record.audioUploadPromise
+      if (!upload || !upload.id) throw new Error('Audio upload did not return a file id')
+
+      const { text } = await fetchTranscriptWithRetry(getTranscript, upload.id)
+      if (text === NO_AUDIO_BE_MESSAGE) throw new Error('Transcript is not available')
+      return text
+    })
+
+    this.setupPanelLifecycle()
+    this.setupTranscriptPipeline()
+  }
+
+  private setupPanelLifecycle() {
+    sample({
+      clock: this.record.recorderModel.$voiceRecordState,
+      filter: (state) => state === VoiceRecorderState.RECORDING,
+      target: this.panel.open,
+    })
+    // startAudioUpload fires exactly when a recording was confirmed (the
+    // discard path never uploads), so it doubles as the panel's confirm clock.
+    sample({ clock: this.record.startAudioUpload, target: this.panel.confirm })
+    // The record resets as a side effect of a wrong answer (the attempt key
+    // rotates to a take with no recording). While the panel is handling its own
+    // dismissal — dimming a shown transcript, or waiting for one that is still
+    // loading — that incidental reset must not close it early; the panel owns
+    // the close.
+    sample({
+      clock: [this.record.reset, this.record.stop.done],
+      source: this.panel.$isHandlingDismissal,
+      filter: (isHandlingDismissal) => !isHandlingDismissal,
+      target: this.panel.discard,
+    })
+  }
+
+  private setupTranscriptPipeline() {
+    // A fetch result applies when the record it was fetched for is still the
+    // current one — late results from a discarded or re-recorded take are
+    // dropped. The exception is a pending dismissal: a wrong answer rotates
+    // $currentRecord away from the take it was fetched for, but that take's
+    // transcript is exactly the one the panel is waiting to show before it
+    // closes, so it must still apply.
+    const shouldApplyResult = (
+      { currentRecord, isDismissPending }: ResultGuardSource,
+      { params }: { params: VoiceRecordCollectionItem },
+    ) => isDismissPending || currentRecord === params
+
+    const resultGuardSource = {
+      currentRecord: this.record.$currentRecord,
+      isDismissPending: this.panel.$isDismissPending,
+    }
+
+    sample({
+      clock: this.record.$currentRecord.updates,
+      source: this.panel.$flags,
+      filter: (flags, record) => flags.isProcessing && Boolean(record?.audioUploadPromise),
+      fn: (_, record): VoiceRecordCollectionItem => record,
+      target: this.resolveTranscriptFx,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.done,
+      source: resultGuardSource,
+      filter: shouldApplyResult,
+      fn: (_, { result }) => result,
+      target: this.panel.complete,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.fail,
+      source: resultGuardSource,
+      filter: shouldApplyResult,
+      target: this.panel.fail,
+    })
+  }
+}

package/src/features/voice/recording/model/VoiceTranscriptPanel.model.ts

@@ -0,0 +1,131 @@
+import { combine, createEvent, createStore, Event, sample } from 'effector'
+import { delay } from 'patronum'
+
+import { VOICE_TRANSCRIPT_PANEL, VoicePanelPhase } from '../../constants'
+import { DropdownModel } from '../../playing/model/Dropdown.model'
+
+type PhaseFlags = {
+  isOpen: boolean
+  isRecording: boolean
+  isProcessing: boolean
+  isDone: boolean
+}
+
+// Phase machine for the recording-flow panel: open → RECORDING (waveform),
+// confirm → PROCESSING (loader), complete/fail → DONE (transcript text).
+// The transcript shows inside a collapsible dropdown (same UX as the playing
+// side): collapsed to a short preview by default, expandable via the caret.
+// Transcript fetching itself is wired externally
+// (see VoiceRecordWithTranscriptModel).
+export class VoiceTranscriptPanelModel {
+  public readonly reset = createEvent()
+
+  public readonly dropdown = new DropdownModel()
+
+  public readonly open = createEvent()
+  public readonly confirm = createEvent()
+  public readonly complete = createEvent<string>()
+  public readonly fail = createEvent()
+  public readonly discard = createEvent()
+  // Ask the panel to dismiss itself gracefully — dim the transcript, linger,
+  // then close (vs. discard, which closes immediately). Wired to a wrong answer
+  // by the consumer; the panel itself stays domain-agnostic and owns the timing.
+  public readonly requestDismiss = createEvent()
+
+  public readonly $phase = createStore<VoicePanelPhase | null>(null)
+  public readonly $transcript = createStore('')
+  public readonly $hasError = createStore(false)
+  public readonly $isDimmed = createStore(false)
+  // A dismissal asked for while the transcript is still loading: there is
+  // nothing to dim yet, so we remember it and run the dismissal once the
+  // transcript resolves into the DONE phase.
+  public readonly $isDismissPending = createStore(false)
+
+  // True while the panel owns its own dismissal — either already dimming a
+  // shown transcript, or waiting for an in-flight transcript before it can.
+  // The consumer reads this so an incidental record reset can't close the
+  // panel out from under a dismissal in progress.
+  public readonly $isHandlingDismissal = combine(
+    this.$isDimmed,
+    this.$isDismissPending,
+    (isDimmed, isDismissPending) => isDimmed || isDismissPending,
+  )
+
+  public readonly $flags = this.$phase.map(
+    (phase): PhaseFlags => ({
+      isOpen: phase !== null,
+      isRecording: phase === VoicePanelPhase.RECORDING,
+      isProcessing: phase === VoicePanelPhase.PROCESSING,
+      isDone: phase === VoicePanelPhase.DONE,
+    }),
+  )
+
+  constructor() {
+    this.setupPhaseTransitions()
+    this.setupDelayedDismissal()
+  }
+
+  // The event passes through only while the panel is in the given phase —
+  // e.g. a transcript that arrives after a discard must not reopen the panel
+  private allowInPhase<T>(clock: Event<T>, phase: VoicePanelPhase): Event<T> {
+    return sample({
+      clock,
+      source: this.$phase,
+      filter: (currentPhase) => currentPhase === phase,
+      fn: (_, payload: T) => payload,
+    })
+  }
+
+  private setupPhaseTransitions() {
+    const confirmed = this.allowInPhase(this.confirm, VoicePanelPhase.RECORDING)
+    const completed = this.allowInPhase(this.complete, VoicePanelPhase.PROCESSING)
+    const failed = this.allowInPhase(this.fail, VoicePanelPhase.PROCESSING)
+
+    this.$phase
+      .on(this.open, () => VoicePanelPhase.RECORDING)
+      .on(confirmed, () => VoicePanelPhase.PROCESSING)
+      .on(completed, () => VoicePanelPhase.DONE)
+      .on(failed, () => VoicePanelPhase.DONE)
+      .reset(this.reset)
+
+    this.$transcript.on(completed, (_, transcript) => transcript).reset(this.reset)
+    this.$hasError.on(failed, () => true).reset(this.reset)
+
+    sample({ clock: this.discard, target: this.reset })
+    sample({ clock: this.reset, target: this.dropdown.reset })
+  }
+
+  private setupDelayedDismissal() {
+    const beginDismissal = createEvent()
+
+    // Transcript already shown → dim and dismiss right away.
+    const dismissWhileDone = this.allowInPhase(this.requestDismiss, VoicePanelPhase.DONE)
+
+    // Transcript still loading → there is nothing to dim, so defer the request.
+    const dismissWhileProcessing = this.allowInPhase(this.requestDismiss, VoicePanelPhase.PROCESSING)
+    this.$isDismissPending.on(dismissWhileProcessing, () => true).reset([this.reset, this.open])
+
+    // A deferred request fires the moment the transcript resolves into DONE.
+    const deferredDismiss = sample({
+      clock: this.$phase.updates,
+      source: this.$isDismissPending,
+      filter: (isDismissPending, phase) => isDismissPending && phase === VoicePanelPhase.DONE,
+      fn: () => undefined,
+    })
+
+    sample({ clock: [dismissWhileDone, deferredDismiss], target: beginDismissal })
+
+    this.$isDimmed.on(beginDismissal, () => true).reset([this.reset, this.open])
+
+    const dismissTimeout = delay({
+      source: beginDismissal,
+      timeout: VOICE_TRANSCRIPT_PANEL.WRONG_ANSWER_DISMISS_DELAY_MS,
+    })
+    // The phase guard drops the timer if the panel was already discarded or a
+    // new recording started during the linger window
+    sample({
+      clock: this.allowInPhase(dismissTimeout, VoicePanelPhase.DONE),
+      target: this.reset,
+    })
+  }
+}

package/src/features/voice/transcript.helpers.ts

@@ -0,0 +1,37 @@
+import {
+  NO_AUDIO_BE_MESSAGE,
+  TRANSCRIPT_MAX_RETRIES,
+  TRANSCRIPT_RETRY_INTERVAL_MS,
+  TranscriptionStatus,
+} from './constants'
+import type { AudioTranscriptResponse } from './types'
+
+export type TranscriptResult = { text: string; language?: string }
+export type GetAudioFileTranscript = (audioFileId: string) => Promise<AudioTranscriptResponse>
+
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// Polls the transcript endpoint until the BE finishes processing. FAILED and
+// exhausted retries both resolve to the NO_AUDIO sentinel — same contract the
+// playing side relies on.
+export const fetchTranscriptWithRetry = async (
+  getTranscript: GetAudioFileTranscript,
+  audioFileId: string,
+): Promise<TranscriptResult> => {
+  for (let attempt = 0; attempt < TRANSCRIPT_MAX_RETRIES; attempt++) {
+    const response = await getTranscript(audioFileId)
+
+    if (response.status === TranscriptionStatus.COMPLETED) {
+      return { text: response.text, language: response.language }
+    }
+
+    if (response.status === TranscriptionStatus.FAILED) {
+      return { text: NO_AUDIO_BE_MESSAGE }
+    }
+
+    if (attempt < TRANSCRIPT_MAX_RETRIES - 1) {
+      await delay(TRANSCRIPT_RETRY_INTERVAL_MS)
+    }
+  }
+  return { text: NO_AUDIO_BE_MESSAGE }
+}

package/src/features/voice/types.ts

@@ -1,7 +1,12 @@
 import { WithAbortSignal } from 'src/types/common.types'
+import { TranscriptionStatus } from './constants'
 import { getAvailableInputs } from './helpers'
 import { VoiceRecordModel } from './recording/model/VoiceRecord.model'
 import { AxiosResponse } from 'axios'
+
+// The enum moved to constants.ts (jest-safe import chain for transcript helpers);
+// re-exported here to keep the public surface unchanged.
+export { TranscriptionStatus }
 import type {
   GoogleTranslateProps as GoogleTranslatePayload,
   GoogleTranslateResponse,
@@ -60,12 +65,6 @@ export type VoiceRecorderApi = {
   deleteAudioFile: (audioFileId: string) => Promise<void>
 }
 
-export enum TranscriptionStatus {
-  PENDING = 'pending',
-  COMPLETED = 'completed',
-  FAILED = 'failed',
-}
-
 export type AudioTranscriptResponse = {
   text: string
   language: string

package/src/i18n/.generated/schema.json

@@ -73,9 +73,9 @@
       "errorTitle": "Something went wrong",
       "fast": "Fast!",
       "incorrect": "INCORRECT — ANSWER: {{answer}}",
-      "masteryGrowing": "Growing",
-      "masteryLearning": "Learning",
-      "masteryMastered": "Mastered",
+      "masteryGrowing": "Familiar",
+      "masteryLearning": "New",
+      "masteryMastered": "Automatic",
       "masteryStrong": "Strong",
       "multiplication": "Multiplication",
       "notStarted": "New",
@@ -98,7 +98,7 @@
   "teacher": {
     "fluency": {
       "allPupils": "All students",
-      "average": "Average",
+      "average": "Progress",
       "avgTimeTitle": "Avg Time / Student",
       "factFluency": "Fact Fluency",
       "factsGridLabel": "{{cols}}×{{rows}} facts",
@@ -108,7 +108,7 @@
       "noFactsPracticed": "No facts practiced yet",
       "noStudents": "This class has no students",
       "noStudentsFound": "No students match your search",
-      "overallMastery": "Overall mastery",
+      "overallMastery": "Automaticity progress",
       "progressDeveloping": "Developing",
       "progressFluent": "Fluent",
       "progressLearning": "Learning",
@@ -140,6 +140,7 @@
     "noMicrophoneAccess": "No microphone access.",
     "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
     "noMicrophoneFound": "No microphone found.",
+    "preparingTranscript": "Preparing transcript",
     "recordingDeleted": "Recording successfully deleted.",
     "redo": "Redo",
     "redoRecording": "Redo recording?",