@tinyweb_dev/oe-exam-sdk 0.1.28 → 0.1.29

package/dist/components/exams/take/hooks/useSpeakingConversationAudio.js

@@ -1 +1,178 @@
-import{useCallback as e,useEffect as r,useRef as t,useState as n}from"react";import{usePresignedFileUrl as u}from"../../../../shared/lib/hooks/usePresignedFileUrl";export function useSpeakingConversationAudio({interlocutorAudioUrl:a,partnerAudioUrl:i,onSequenceComplete:o}){const[c,l]=n("idle"),[d,s]=n(0),[p,y]=n(0),{previewUrl:m}=u(a??""),{previewUrl:g}=u(i??""),v=t(null),A=t(o);r(()=>{A.current=o},[o]);const E=t(m),L=t(g);r(()=>{E.current=m},[m]),r(()=>{L.current=g},[g]);const U=e(()=>{const e=v.current;e&&(e.pause(),e.src="")},[]),h=e(e=>{let r=v.current;r||(r=new Audio,v.current=r),r.src=e,r.play().catch(()=>{})},[]);r(()=>{let e=v.current;e||(e=new Audio,v.current=e);const r=()=>{l(e=>{if("playing-interlocutor"===e){const e=L.current;e?setTimeout(()=>{l("playing-partner"),h(e)},0):setTimeout(()=>{l("ready"),A.current()},0)}else"playing-partner"===e&&setTimeout(()=>{l("ready"),A.current()},0);return e})},t=()=>{e&&s(e.currentTime)},n=()=>{e&&(y(e.duration),s(0))};return e.addEventListener("ended",r),e.addEventListener("timeupdate",t),e.addEventListener("loadedmetadata",n),()=>{e.removeEventListener("ended",r),e.removeEventListener("timeupdate",t),e.removeEventListener("loadedmetadata",n)}},[h]),r(()=>(U(),l("idle"),m||g?(m?(l("playing-interlocutor"),h(m)):g&&(l("playing-partner"),h(g)),()=>{U()}):(l("ready"),void A.current())),[m,g]),r(()=>()=>{U()},[]);const T=e(()=>{U(),E.current?(l("playing-interlocutor"),h(E.current)):L.current?(l("playing-partner"),h(L.current)):(l("ready"),A.current())},[U,h]),f=e(()=>{const e=v.current;e&&(e.paused?e.play().catch(()=>{}):e.pause())},[]);return{phase:c,isPlaying:Boolean(v.current&&!v.current.paused),replayAll:T,togglePlayPause:f,currentAudioUrl:"playing-interlocutor"===c?m??"":"playing-partner"===c?g??"":"",currentTime:d,duration:p}}
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { usePresignedFileUrl } from '../../../../shared/lib/hooks/usePresignedFileUrl';
+// ============================================
+// Hook
+// ============================================
+export function useSpeakingConversationAudio({ interlocutorAudioUrl, partnerAudioUrl, onSequenceComplete, }) {
+    const [phase, setPhase] = useState('idle');
+    const [currentTime, setCurrentTime] = useState(0);
+    const [duration, setDuration] = useState(0);
+    // Resolve presigned URLs for both tracks
+    const { previewUrl: resolvedInterlocutorUrl } = usePresignedFileUrl(interlocutorAudioUrl ?? '');
+    const { previewUrl: resolvedPartnerUrl } = usePresignedFileUrl(partnerAudioUrl ?? '');
+    // Single shared audio element ref — we swap src between phases
+    const audioRef = useRef(null);
+    // Stable callback ref so we don't retrigger effects when the prop changes identity
+    const onSequenceCompleteRef = useRef(onSequenceComplete);
+    useEffect(() => {
+        onSequenceCompleteRef.current = onSequenceComplete;
+    }, [onSequenceComplete]);
+    // Refs to hold the latest resolved URLs so event handlers can read them
+    const resolvedInterlocutorUrlRef = useRef(resolvedInterlocutorUrl);
+    const resolvedPartnerUrlRef = useRef(resolvedPartnerUrl);
+    useEffect(() => {
+        resolvedInterlocutorUrlRef.current = resolvedInterlocutorUrl;
+    }, [resolvedInterlocutorUrl]);
+    useEffect(() => {
+        resolvedPartnerUrlRef.current = resolvedPartnerUrl;
+    }, [resolvedPartnerUrl]);
+    // ---------- helpers ----------
+    const stopAudio = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        audio.pause();
+        audio.src = '';
+    }, []);
+    const playUrl = useCallback((url) => {
+        let audio = audioRef.current;
+        if (!audio) {
+            audio = new Audio();
+            audioRef.current = audio;
+        }
+        audio.src = url;
+        audio.play().catch(() => {
+            // If play fails (e.g. AbortError on rapid navigation), skip to ready
+        });
+    }, []);
+    // ---------- wire ended events ----------
+    useEffect(() => {
+        let audio = audioRef.current;
+        if (!audio) {
+            audio = new Audio();
+            audioRef.current = audio;
+        }
+        const handleEnded = () => {
+            // Read the current phase from refs so the handler always sees latest value
+            setPhase((currentPhase) => {
+                if (currentPhase === 'playing-interlocutor') {
+                    const partnerUrl = resolvedPartnerUrlRef.current;
+                    if (partnerUrl) {
+                        // Schedule outside the setState callback
+                        setTimeout(() => {
+                            setPhase('playing-partner');
+                            playUrl(partnerUrl);
+                        }, 0);
+                    }
+                    else {
+                        setTimeout(() => {
+                            setPhase('ready');
+                            onSequenceCompleteRef.current();
+                        }, 0);
+                    }
+                }
+                else if (currentPhase === 'playing-partner') {
+                    setTimeout(() => {
+                        setPhase('ready');
+                        onSequenceCompleteRef.current();
+                    }, 0);
+                }
+                return currentPhase; // Don't change phase here — we do it in setTimeout
+            });
+        };
+        const handleTimeUpdate = () => {
+            if (audio)
+                setCurrentTime(audio.currentTime);
+        };
+        const handleLoadedMetadata = () => {
+            if (audio) {
+                setDuration(audio.duration);
+                setCurrentTime(0);
+            }
+        };
+        audio.addEventListener('ended', handleEnded);
+        audio.addEventListener('timeupdate', handleTimeUpdate);
+        audio.addEventListener('loadedmetadata', handleLoadedMetadata);
+        return () => {
+            audio.removeEventListener('ended', handleEnded);
+            audio.removeEventListener('timeupdate', handleTimeUpdate);
+            audio.removeEventListener('loadedmetadata', handleLoadedMetadata);
+        };
+    }, [playUrl]);
+    // ---------- start / reset when URLs change ----------
+    useEffect(() => {
+        // Reset state whenever the source keys change (question navigation)
+        stopAudio();
+        setPhase('idle');
+        if (!resolvedInterlocutorUrl && !resolvedPartnerUrl) {
+            // No audio at all — go straight to ready
+            setPhase('ready');
+            onSequenceCompleteRef.current();
+            return;
+        }
+        if (resolvedInterlocutorUrl) {
+            setPhase('playing-interlocutor');
+            playUrl(resolvedInterlocutorUrl);
+        }
+        else if (resolvedPartnerUrl) {
+            // No interlocutor audio — jump straight to partner
+            setPhase('playing-partner');
+            playUrl(resolvedPartnerUrl);
+        }
+        return () => {
+            stopAudio();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [resolvedInterlocutorUrl, resolvedPartnerUrl]);
+    // ---------- cleanup on unmount ----------
+    useEffect(() => {
+        return () => {
+            stopAudio();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // ---------- replayAll ----------
+    const replayAll = useCallback(() => {
+        stopAudio();
+        if (resolvedInterlocutorUrlRef.current) {
+            setPhase('playing-interlocutor');
+            playUrl(resolvedInterlocutorUrlRef.current);
+        }
+        else if (resolvedPartnerUrlRef.current) {
+            setPhase('playing-partner');
+            playUrl(resolvedPartnerUrlRef.current);
+        }
+        else {
+            setPhase('ready');
+            onSequenceCompleteRef.current();
+        }
+    }, [stopAudio, playUrl]);
+    // ---------- togglePlayPause ----------
+    const togglePlayPause = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        if (audio.paused) {
+            audio.play().catch(() => { });
+        }
+        else {
+            audio.pause();
+        }
+    }, []);
+    // ---------- derived values ----------
+    const isPlaying = Boolean(audioRef.current && !audioRef.current.paused);
+    const currentAudioUrl = phase === 'playing-interlocutor'
+        ? (resolvedInterlocutorUrl ?? '')
+        : phase === 'playing-partner'
+            ? (resolvedPartnerUrl ?? '')
+            : '';
+    return {
+        phase,
+        isPlaying,
+        replayAll,
+        togglePlayPause,
+        currentAudioUrl,
+        currentTime,
+        duration,
+    };
+}

package/dist/components/exams/take/hooks/useSpeakingNavigation.js

@@ -1 +1,51 @@
-import{useState as t,useCallback as n,useMemo as r}from"react";export function useSpeakingNavigation(e){const{questions:o,initialIndex:a=0}=e,[i,u]=t(a),c=o.length,s=o[i]??null,l=s?.part_no??1,g=s?.partName??"",m=r(()=>{if(!s)return 1;return o.slice(0,i).filter(t=>t.part_no===s.part_no).length+1},[i,s,o]),p=i>0,N=i<c-1,x=n(()=>{u(t=>Math.min(t+1,c-1))},[c]),P=n(()=>{u(t=>Math.max(t-1,0))},[]),f=n(t=>{t>=0&&t<c&&u(t)},[c]);return{currentIndex:i,currentQuestion:s,totalQuestions:c,currentPartNo:l,currentPartName:g,questionNumberInPart:m,canGoPrev:p,canGoNext:N,goNext:x,goPrev:P,goTo:f}}
+import { useState, useCallback, useMemo } from 'react';
+// ============================================
+// Hook
+// ============================================
+export function useSpeakingNavigation(options) {
+    const { questions, initialIndex = 0 } = options;
+    const [currentIndex, setCurrentIndex] = useState(initialIndex);
+    const totalQuestions = questions.length;
+    const currentQuestion = questions[currentIndex] ?? null;
+    const currentPartNo = currentQuestion?.part_no ?? 1;
+    const currentPartName = currentQuestion?.partName ?? '';
+    /**
+     * Compute 1-based question number within the current part.
+     * We count how many questions before currentIndex share the same part_no,
+     * then add 1.
+     */
+    const questionNumberInPart = useMemo(() => {
+        if (!currentQuestion)
+            return 1;
+        const indexWithinPart = questions
+            .slice(0, currentIndex)
+            .filter((q) => q.part_no === currentQuestion.part_no).length;
+        return indexWithinPart + 1;
+    }, [currentIndex, currentQuestion, questions]);
+    const canGoPrev = currentIndex > 0;
+    const canGoNext = currentIndex < totalQuestions - 1;
+    const goNext = useCallback(() => {
+        setCurrentIndex((prev) => Math.min(prev + 1, totalQuestions - 1));
+    }, [totalQuestions]);
+    const goPrev = useCallback(() => {
+        setCurrentIndex((prev) => Math.max(prev - 1, 0));
+    }, []);
+    const goTo = useCallback((index) => {
+        if (index >= 0 && index < totalQuestions) {
+            setCurrentIndex(index);
+        }
+    }, [totalQuestions]);
+    return {
+        currentIndex,
+        currentQuestion,
+        totalQuestions,
+        currentPartNo,
+        currentPartName,
+        questionNumberInPart,
+        canGoPrev,
+        canGoNext,
+        goNext,
+        goPrev,
+        goTo,
+    };
+}

package/dist/components/exams/take/hooks/useSpeakingRecorder.js

@@ -1 +1,406 @@
-import{useState as r,useRef as e,useEffect as n,useCallback as t}from"react";import{usePresignedFileUrl as o}from"../../../../shared/lib/hooks";import{useExamTakingApiOptional as u}from"../ExamTakingApiContext";export function useSpeakingRecorder(i){const c=i.maxDurationMs??3e4,a=Math.floor(c/1e3),d=u(),s=e(d);s.current=d;const l=e(i.onRecordingComplete),p=e(i.onError);l.current=i.onRecordingComplete,p.current=i.onError;const g=e(i.attemptId),h=e(i.questionId);g.current=i.attemptId,h.current=i.questionId;const[m,y]=r("idle"),[f,w]=r(a),[v,A]=r(0),[T,E]=r(null),[R,x]=r(null),[b,k]=r(null),[I,M]=r(!1),K=e(null),D=e(null),P=e([]),S=e(null),U=e(null),O=e(""),_=e(0),q=e(null),L=e(void 0),N=e(0),B=e(!0),V=e(""),C="undefined"!=typeof MediaRecorder,{previewUrl:F}=o(i.existingAnswerKey),G=t(()=>{S.current&&(clearInterval(S.current),S.current=null)},[]),j=t(()=>{U.current&&(U.current.startsWith("blob:")&&URL.revokeObjectURL(U.current),U.current=null)},[]),W=t(()=>{D.current&&(D.current.getTracks().forEach(r=>r.stop()),D.current=null)},[]),X=t(async(r,e,n,t)=>{if(!B.current)return;const o=t||V.current||h.current;h.current===o&&y("uploading");const u=g.current;if("mock-attempt-speaking"===u){if(await new Promise(r=>setTimeout(r,500)),!B.current)return;const r=`mock-audio-key-${o}`;return h.current===o&&(y("uploaded"),x(r)),l.current(r,o),q.current=null,void(L.current=void 0)}try{if(!s.current?.uploadAudioAnswer)throw new Error("uploadAudioAnswer is not implemented by the provided API adapter.");const n=(i=await s.current.uploadAudioAnswer({attemptId:u,questionId:o,audioBlob:r,durationMs:e}))&&"object"==typeof i&&"data"in i?i.data:i;if(!B.current)return;const t=n.audioKey??"";h.current===o&&(y("uploaded"),x(t)),l.current(t,o),q.current=null,L.current=void 0,N.current=0,s.current.realtimeGradeSingle?.({attemptId:u,questionId:o,audioKey:t}).catch(r=>{console.debug("[Realtime Grading] Skipped or failed:",r?.response?.status??r?.message)})}catch(o){if(!B.current)return;const u=o,i=u?.response?.data?.code;if("ATTEMPT_EXPIRED"===i||"ATTEMPT_NOT_IN_PROGRESS"===i){const r="ATTEMPT_EXPIRED"===i?"Bài thi đã hết giờ":"Bài thi đã được nộp.";return y("error"),k(r),M(!0),void p.current?.(r)}if("AUDIO_FILE_TOO_LARGE"===i){const r="Bài ghi âm quá dài. Vui lòng ghi âm ngắn hơn.";return y("error"),k(r),void p.current?.(r)}if(n<3){const o=1e3*Math.pow(2,n);if(await new Promise(r=>setTimeout(r,o)),!B.current)return;N.current=n+1,await X(r,e,n+1,t)}else{const r="Tải lên bản ghi âm thất bại. Vui lòng thử lại.";y("error"),k(r),p.current?.(r)}}var i},[]),z=t(async(r,e,n)=>{q.current=r,L.current=e,N.current=0,await X(r,e,0,n)},[X]),H=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);if(!C){const r="Trình duyệt này không hỗ trợ ghi âm. Vui lòng dùng Chrome, Firefox hoặc Edge.";return y("error"),k(r),void p.current?.(r)}const r=function(){if("undefined"==typeof MediaRecorder)return null;const r=["audio/webm;codecs=opus","audio/webm","audio/mp4","audio/ogg;codecs=opus","audio/ogg"];for(const e of r)if(MediaRecorder.isTypeSupported(e))return e;return null}();if(!r){const r="Trình duyệt không hỗ trợ định dạng ghi âm.";return y("error"),k(r),void p.current?.(r)}if("undefined"==typeof navigator||!navigator.mediaDevices?.getUserMedia){const r="Trình duyệt hoặc kết nối (HTTP) không hỗ trợ truy cập microphone.";return y("error"),k(r),void p.current?.(r)}try{const e=await navigator.mediaDevices.getUserMedia({audio:!0});D.current=e,O.current=r;const n=new MediaRecorder(e,{mimeType:r});K.current=n,P.current=[],n.ondataavailable=r=>{r.data.size>0&&P.current.push(r.data)},n.onstop=()=>{const r=Date.now()-_.current,e=new Blob(P.current,{type:O.current}),n=URL.createObjectURL(e),t=V.current;j(),U.current=n,E(n),y("recorded"),z(e,r,t)},n.start(),_.current=Date.now(),V.current=h.current,y("recording"),A(0),w(a),k(null),x(null),E(null),M(!1),S.current=setInterval(()=>{A(r=>r+1),w(r=>{const e=Math.max(0,r-1);return 0===e&&(G(),K.current&&"recording"===K.current.state&&K.current.stop(),W()),e})},1e3)}catch(r){W();const e=r instanceof DOMException?r.name:r?.name;let n="Không thể truy cập microphone. Vui lòng thử lại.";"NotAllowedError"===e||"PermissionDeniedError"===e?n="Vui lòng cấp quyền truy cập microphone trong cài đặt trình duyệt.":"NotFoundError"===e||"DevicesNotFoundError"===e?n="Không tìm thấy thiết bị microphone nào kết nối với máy tính.":"NotReadableError"!==e&&"TrackStartError"!==e||(n="Microphone đang được ứng dụng khác sử dụng hoặc gặp lỗi phần cứng."),y("error"),k(n),p.current?.(n)}},[C,a,i.existingAnswerKey,G,W,z,j]),$=t(()=>{G(),K.current&&"recording"===K.current.state&&K.current.stop(),W()},[G,W]),J=t(()=>{G(),W(),K.current&&"recording"===K.current.state&&K.current.stop(),K.current=null,P.current=[],q.current=null,L.current=void 0,N.current=0,j(),E(null),x(null),A(0),w(a),k(null),y("idle"),M(!1)},[G,W,j,a]),Q=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);J(),await H()},[i.existingAnswerKey,J,H]),Y=t(async()=>{const r=q.current;r&&(N.current=0,await X(r,L.current,0,V.current||void 0))},[X]);n(()=>{J()},[i.questionId]),n(()=>{"idle"===m&&F&&i.existingAnswerKey&&!T&&(E(F),U.current=F,x(i.existingAnswerKey),y("uploaded"))},[m,F,i.existingAnswerKey,T]),n(()=>(B.current=!0,()=>{B.current=!1,G(),K.current&&"recording"===K.current.state&&K.current.stop(),W(),j()}),[]);return{status:m,remainingSeconds:f,isWarning:f<=5&&"recording"===m,durationSeconds:v,previewUrl:T,uploadedKey:R,error:b,isSupported:C,isAttemptExpired:I,liveTranscript:null,startRecording:H,stopRecording:$,resetRecording:J,reRecord:Q,retryUpload:Y}}
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { usePresignedFileUrl } from '../../../../shared/lib/hooks';
+import { useExamTakingApiOptional } from '../ExamTakingApiContext';
+/** Unwrap an API response that may be either the raw value or an `{ data }` envelope. */
+function unwrapData(res) {
+    return res && typeof res === 'object' && 'data' in res
+        ? res.data
+        : res;
+}
+// ============================================
+// MIME type detection
+// ============================================
+function detectSupportedMimeType() {
+    if (typeof MediaRecorder === 'undefined')
+        return null;
+    const candidates = [
+        'audio/webm;codecs=opus',
+        'audio/webm',
+        'audio/mp4',
+        'audio/ogg;codecs=opus',
+        'audio/ogg',
+    ];
+    for (const mimeType of candidates) {
+        if (MediaRecorder.isTypeSupported(mimeType)) {
+            return mimeType;
+        }
+    }
+    return null;
+}
+// ============================================
+// Constants
+// ============================================
+const DEFAULT_MAX_DURATION_MS = 30000;
+const WARNING_THRESHOLD_SECONDS = 5;
+const MAX_AUTO_RETRIES = 3;
+// ============================================
+// Hook
+// ============================================
+export function useSpeakingRecorder(options) {
+    const maxDurationMs = options.maxDurationMs ?? DEFAULT_MAX_DURATION_MS;
+    const maxDurationSeconds = Math.floor(maxDurationMs / 1000);
+    // Injected API adapter, kept in a ref so the (stable) upload callbacks below
+    // can read the latest value without being re-created. Optional: the mic-test
+    // in the entry waiting room mounts this hook in mock mode
+    // (attemptId === 'mock-attempt-speaking'), where no real upload happens and
+    // no provider is mounted — so a missing API must not throw. Real uploads
+    // still fail closed below when the adapter is absent.
+    const api = useExamTakingApiOptional();
+    const apiRef = useRef(api);
+    apiRef.current = api;
+    // Stable callback refs — avoids re-running effects when callbacks change identity
+    const onRecordingCompleteRef = useRef(options.onRecordingComplete);
+    const onErrorRef = useRef(options.onError);
+    onRecordingCompleteRef.current = options.onRecordingComplete;
+    onErrorRef.current = options.onError;
+    // Stable option refs for use inside async callbacks
+    const attemptIdRef = useRef(options.attemptId);
+    const questionIdRef = useRef(options.questionId);
+    attemptIdRef.current = options.attemptId;
+    questionIdRef.current = options.questionId;
+    const [status, setStatus] = useState('idle');
+    const [remainingSeconds, setRemainingSeconds] = useState(maxDurationSeconds);
+    const [durationSeconds, setDurationSeconds] = useState(0);
+    const [previewUrl, setPreviewUrl] = useState(null);
+    const [uploadedKey, setUploadedKey] = useState(null);
+    const [error, setError] = useState(null);
+    const [isAttemptExpired, setIsAttemptExpired] = useState(false);
+    const mediaRecorderRef = useRef(null);
+    const mediaStreamRef = useRef(null);
+    const chunksRef = useRef([]);
+    const durationIntervalRef = useRef(null);
+    const previewUrlRef = useRef(null); // tracked for cleanup on unmount
+    const mimeTypeRef = useRef('');
+    const recordStartTimeRef = useRef(0);
+    const pendingBlobRef = useRef(null); // blob kept for retry
+    const pendingDurationMsRef = useRef(undefined);
+    const autoRetryCountRef = useRef(0);
+    const isMountedRef = useRef(true);
+    // Snapshot of questionId at the moment recording starts — survives navigation changes
+    const recordingQuestionIdRef = useRef('');
+    const isSupported = typeof MediaRecorder !== 'undefined';
+    // Fetch presigned URL for existing answer (to restore playback on navigation back)
+    const { previewUrl: existingPresignedUrl } = usePresignedFileUrl(options.existingAnswerKey);
+    // ============================================
+    // Cleanup helpers
+    // ============================================
+    const stopDurationTimer = useCallback(() => {
+        if (durationIntervalRef.current) {
+            clearInterval(durationIntervalRef.current);
+            durationIntervalRef.current = null;
+        }
+    }, []);
+    const revokePreviewUrl = useCallback(() => {
+        if (previewUrlRef.current) {
+            // Only revoke blob: URLs — presigned HTTPS URLs don't need revoking
+            if (previewUrlRef.current.startsWith('blob:')) {
+                URL.revokeObjectURL(previewUrlRef.current);
+            }
+            previewUrlRef.current = null;
+        }
+    }, []);
+    const stopMediaStream = useCallback(() => {
+        if (mediaStreamRef.current) {
+            mediaStreamRef.current.getTracks().forEach((track) => track.stop());
+            mediaStreamRef.current = null;
+        }
+    }, []);
+    // ============================================
+    // Upload helper — with auto-retry and error code handling
+    // ============================================
+    const performUpload = useCallback(async (blob, durationMs, retryCount, forQuestionId) => {
+        if (!isMountedRef.current)
+            return;
+        // Only show 'uploading' status if we're still on the same question
+        const questionId = forQuestionId || recordingQuestionIdRef.current || questionIdRef.current;
+        if (questionIdRef.current === questionId) {
+            setStatus('uploading');
+        }
+        const attemptId = attemptIdRef.current;
+        // Mock mode: skip real upload
+        if (attemptId === 'mock-attempt-speaking') {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            if (!isMountedRef.current)
+                return;
+            const mockKey = `mock-audio-key-${questionId}`;
+            if (questionIdRef.current === questionId) {
+                setStatus('uploaded');
+                setUploadedKey(mockKey);
+            }
+            onRecordingCompleteRef.current(mockKey, questionId);
+            pendingBlobRef.current = null;
+            pendingDurationMsRef.current = undefined;
+            return;
+        }
+        try {
+            if (!apiRef.current?.uploadAudioAnswer) {
+                throw new Error('uploadAudioAnswer is not implemented by the provided API adapter.');
+            }
+            const result = unwrapData(await apiRef.current.uploadAudioAnswer({ attemptId, questionId, audioBlob: blob, durationMs }));
+            if (!isMountedRef.current)
+                return;
+            const audioKey = result.audioKey ?? '';
+            // Only update UI status if we're still on the same question
+            if (questionIdRef.current === questionId) {
+                setStatus('uploaded');
+                setUploadedKey(audioKey);
+            }
+            onRecordingCompleteRef.current(audioKey, questionId);
+            pendingBlobRef.current = null;
+            pendingDurationMsRef.current = undefined;
+            autoRetryCountRef.current = 0;
+            // Fire-and-forget: trigger AI grading per-question (RECORDING mode)
+            // Non-blocking — if this fails, grading will fallback to submit time.
+            apiRef.current.realtimeGradeSingle?.({ attemptId, questionId, audioKey }).catch((gradeErr) => {
+                console.debug('[Realtime Grading] Skipped or failed:', gradeErr?.response?.status ?? gradeErr?.message);
+            });
+        }
+        catch (err) {
+            if (!isMountedRef.current)
+                return;
+            // Extract backend error code if available
+            const axiosError = err;
+            const errorCode = axiosError?.response?.data?.code;
+            // Handle fatal backend error codes
+            if (errorCode === 'ATTEMPT_EXPIRED' || errorCode === 'ATTEMPT_NOT_IN_PROGRESS') {
+                const message = errorCode === 'ATTEMPT_EXPIRED'
+                    ? 'Bài thi đã hết giờ'
+                    : 'Bài thi đã được nộp.';
+                setStatus('error');
+                setError(message);
+                setIsAttemptExpired(true);
+                onErrorRef.current?.(message);
+                return;
+            }
+            if (errorCode === 'AUDIO_FILE_TOO_LARGE') {
+                const message = 'Bài ghi âm quá dài. Vui lòng ghi âm ngắn hơn.';
+                setStatus('error');
+                setError(message);
+                onErrorRef.current?.(message);
+                return;
+            }
+            // Network / transient error — auto-retry up to MAX_AUTO_RETRIES
+            if (retryCount < MAX_AUTO_RETRIES) {
+                const backoffMs = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                if (!isMountedRef.current)
+                    return;
+                autoRetryCountRef.current = retryCount + 1;
+                await performUpload(blob, durationMs, retryCount + 1, forQuestionId);
+            }
+            else {
+                // Max retries exhausted — expose manual retry
+                const message = 'Tải lên bản ghi âm thất bại. Vui lòng thử lại.';
+                setStatus('error');
+                setError(message);
+                onErrorRef.current?.(message);
+            }
+        }
+    }, 
+    // performUpload is stable (only uses refs)
+    []);
+    const uploadBlob = useCallback(async (blob, durationMs, forQuestionId) => {
+        pendingBlobRef.current = blob;
+        pendingDurationMsRef.current = durationMs;
+        autoRetryCountRef.current = 0;
+        await performUpload(blob, durationMs, 0, forQuestionId);
+    }, [performUpload]);
+    // ============================================
+    // Actions
+    // ============================================
+    const startRecording = useCallback(async () => {
+        if (options.existingAnswerKey) {
+            setStatus('uploaded');
+            setUploadedKey(options.existingAnswerKey);
+            return;
+        }
+        if (!isSupported) {
+            const message = 'Trình duyệt này không hỗ trợ ghi âm. Vui lòng dùng Chrome, Firefox hoặc Edge.';
+            setStatus('error');
+            setError(message);
+            onErrorRef.current?.(message);
+            return;
+        }
+        const mimeType = detectSupportedMimeType();
+        if (!mimeType) {
+            const message = 'Trình duyệt không hỗ trợ định dạng ghi âm.';
+            setStatus('error');
+            setError(message);
+            onErrorRef.current?.(message);
+            return;
+        }
+        if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) {
+            const message = 'Trình duyệt hoặc kết nối (HTTP) không hỗ trợ truy cập microphone.';
+            setStatus('error');
+            setError(message);
+            onErrorRef.current?.(message);
+            return;
+        }
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            mediaStreamRef.current = stream;
+            mimeTypeRef.current = mimeType;
+            const recorder = new MediaRecorder(stream, { mimeType });
+            mediaRecorderRef.current = recorder;
+            chunksRef.current = [];
+            recorder.ondataavailable = (event) => {
+                if (event.data.size > 0) {
+                    chunksRef.current.push(event.data);
+                }
+            };
+            recorder.onstop = () => {
+                const durationMs = Date.now() - recordStartTimeRef.current;
+                const blob = new Blob(chunksRef.current, { type: mimeTypeRef.current });
+                const url = URL.createObjectURL(blob);
+                // Capture the questionId that was active when recording started
+                const snapshotQuestionId = recordingQuestionIdRef.current;
+                revokePreviewUrl();
+                previewUrlRef.current = url;
+                setPreviewUrl(url);
+                setStatus('recorded');
+                // Auto-upload after recording stops — use snapshotted questionId
+                uploadBlob(blob, durationMs, snapshotQuestionId);
+            };
+            recorder.start();
+            recordStartTimeRef.current = Date.now();
+            // Snapshot the current questionId — this won't change even if user navigates
+            recordingQuestionIdRef.current = questionIdRef.current;
+            setStatus('recording');
+            setDurationSeconds(0);
+            setRemainingSeconds(maxDurationSeconds);
+            setError(null);
+            setUploadedKey(null);
+            setPreviewUrl(null);
+            setIsAttemptExpired(false);
+            // Start duration counter — counts up (elapsed) and down (remaining)
+            durationIntervalRef.current = setInterval(() => {
+                setDurationSeconds((prev) => prev + 1);
+                setRemainingSeconds((prev) => {
+                    const next = Math.max(0, prev - 1);
+                    // Auto-stop when countdown reaches zero
+                    if (next === 0) {
+                        stopDurationTimer();
+                        if (mediaRecorderRef.current && mediaRecorderRef.current.state === 'recording') {
+                            mediaRecorderRef.current.stop();
+                        }
+                        stopMediaStream();
+                    }
+                    return next;
+                });
+            }, 1000);
+        }
+        catch (err) {
+            stopMediaStream();
+            const errName = err instanceof DOMException ? err.name : err?.name;
+            let message = 'Không thể truy cập microphone. Vui lòng thử lại.';
+            if (errName === 'NotAllowedError' || errName === 'PermissionDeniedError') {
+                message = 'Vui lòng cấp quyền truy cập microphone trong cài đặt trình duyệt.';
+            }
+            else if (errName === 'NotFoundError' || errName === 'DevicesNotFoundError') {
+                message = 'Không tìm thấy thiết bị microphone nào kết nối với máy tính.';
+            }
+            else if (errName === 'NotReadableError' || errName === 'TrackStartError') {
+                message = 'Microphone đang được ứng dụng khác sử dụng hoặc gặp lỗi phần cứng.';
+            }
+            setStatus('error');
+            setError(message);
+            onErrorRef.current?.(message);
+        }
+    }, [isSupported, maxDurationSeconds, options.existingAnswerKey, stopDurationTimer, stopMediaStream, uploadBlob, revokePreviewUrl]);
+    const stopRecording = useCallback(() => {
+        stopDurationTimer();
+        if (mediaRecorderRef.current && mediaRecorderRef.current.state === 'recording') {
+            mediaRecorderRef.current.stop();
+        }
+        stopMediaStream();
+    }, [stopDurationTimer, stopMediaStream]);
+    const resetRecording = useCallback(() => {
+        stopDurationTimer();
+        stopMediaStream();
+        if (mediaRecorderRef.current && mediaRecorderRef.current.state === 'recording') {
+            mediaRecorderRef.current.stop();
+        }
+        mediaRecorderRef.current = null;
+        chunksRef.current = [];
+        pendingBlobRef.current = null;
+        pendingDurationMsRef.current = undefined;
+        autoRetryCountRef.current = 0;
+        revokePreviewUrl();
+        setPreviewUrl(null);
+        setUploadedKey(null);
+        setDurationSeconds(0);
+        setRemainingSeconds(maxDurationSeconds);
+        setError(null);
+        setStatus('idle');
+        setIsAttemptExpired(false);
+    }, [stopDurationTimer, stopMediaStream, revokePreviewUrl, maxDurationSeconds]);
+    const reRecord = useCallback(async () => {
+        if (options.existingAnswerKey) {
+            setStatus('uploaded');
+            setUploadedKey(options.existingAnswerKey);
+            return;
+        }
+        resetRecording();
+        await startRecording();
+    }, [options.existingAnswerKey, resetRecording, startRecording]);
+    const retryUpload = useCallback(async () => {
+        const blob = pendingBlobRef.current;
+        if (!blob)
+            return;
+        autoRetryCountRef.current = 0;
+        await performUpload(blob, pendingDurationMsRef.current, 0, recordingQuestionIdRef.current || undefined);
+    }, [performUpload]);
+    // ============================================
+    // Reset when questionId changes (navigating to next question)
+    // ============================================
+    useEffect(() => {
+        resetRecording();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [options.questionId]);
+    // ============================================
+    // Restore playback from existing answer when navigating back
+    // ============================================
+    useEffect(() => {
+        if (status === 'idle' && existingPresignedUrl && options.existingAnswerKey && !previewUrl) {
+            setPreviewUrl(existingPresignedUrl);
+            previewUrlRef.current = existingPresignedUrl;
+            setUploadedKey(options.existingAnswerKey);
+            setStatus('uploaded');
+        }
+    }, [status, existingPresignedUrl, options.existingAnswerKey, previewUrl]);
+    // ============================================
+    // Cleanup on unmount
+    // ============================================
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+            stopDurationTimer();
+            if (mediaRecorderRef.current && mediaRecorderRef.current.state === 'recording') {
+                mediaRecorderRef.current.stop();
+            }
+            stopMediaStream();
+            revokePreviewUrl();
+        };
+        // Only run on unmount — deps intentionally empty
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const isWarning = remainingSeconds <= WARNING_THRESHOLD_SECONDS && status === 'recording';
+    return {
+        status,
+        remainingSeconds,
+        isWarning,
+        durationSeconds,
+        previewUrl,
+        uploadedKey,
+        error,
+        isSupported,
+        isAttemptExpired,
+        liveTranscript: null,
+        startRecording,
+        stopRecording,
+        resetRecording,
+        reRecord,
+        retryUpload,
+    };
+}