@tinyweb_dev/oe-exam-sdk 0.1.2 → 0.1.4

package/dist/components/exams/take/components/speaking/renderers/SpeakingSpontaneousQARenderer.js

@@ -0,0 +1 @@
+"use client";import{jsxs as e,jsx as t}from"react/jsx-runtime";import{useState as r,useRef as n,useEffect as i,useCallback as a}from"react";import{usePresignedFileUrl as o}from"../../../../../../shared/lib/hooks";import{useSpeakingRendererSetup as s}from"../../../hooks/useSpeakingRendererSetup";import{getSpeakingLayout as d}from"../../../../../../components/themes";import l from"../SpeakingReadDisplayedContent.module.css";import c from"../../../../../../components/themes/cambridge-yle/CambridgeYlePartBanner";import u from"next/image";import h from"../../../../../../components/themes/summer-sky/assets/images/mic_ver2_icon.png";import m from"../../../../../../components/themes/summer-sky/assets/images/stop_audio_ver2_icon.png";import p from"../../../../../../components/themes/summer-sky/assets/images/audio_ver2_icon.png";import g from"../../../../../../components/themes/summer-sky/assets/images/pause_audio_ver2_icon.png";import f from"../../../../../../components/themes/summer-sky/assets/images/lock_mic_ver2_icon.png";function x({total:r,currentIndex:n,answeredIds:i,questionIds:a}){return e("div",{className:l.taskIndicator,style:{color:"#78350f",textShadow:"none",fontWeight:800},children:[e("span",{children:["Question ",n+1,"/ ",r]}),t("div",{className:"flex gap-2",children:Array.from({length:r},(e,r)=>{const o=r===n,s=i.has(a[r]);return t("div",{className:`${l.taskDot} ${o?l.taskDotActive:""} ${s&&!o?l.taskDotCompleted:""}`},r)})})]})}function v({audioUrl:o,autoPlay:s,onEnded:d,disabled:l}){const c=n(null),[u,h]=r(!1),[m,p]=r(0),[g,f]=r(0);i(()=>{const e=c.current;if(!e)return;const t=()=>p(e.currentTime),r=()=>f(e.duration),n=()=>{h(!1),d?.()},i=()=>h(!0),a=()=>h(!1);return e.addEventListener("timeupdate",t),e.addEventListener("loadedmetadata",r),e.addEventListener("ended",n),e.addEventListener("play",i),e.addEventListener("pause",a),()=>{e.removeEventListener("timeupdate",t),e.removeEventListener("loadedmetadata",r),e.removeEventListener("ended",n),e.removeEventListener("play",i),e.removeEventListener("pause",a)}},[o,d]),i(()=>{const e=c.current;e&&(e.pause(),e.currentTime=0,h(!1),p(0),f(0))},[o]),i(()=>{const e=c.current;if(!e||!s)return;let t=!1;const r=()=>{t||e.play().catch(()=>{})};return e.readyState>=3?r():e.addEventListener("canplay",r,{once:!0}),()=>{t=!0,e.removeEventListener("canplay",r)}},[o,s]);const x=a(()=>{const e=c.current;e&&(u?e.pause():((e.ended||e.currentTime>=e.duration)&&(e.currentTime=0,p(0)),e.play().catch(console.error)))},[u]),v=a(e=>{const t=c.current;if(!t)return;const r=parseFloat(e.target.value);t.currentTime=r,p(r)},[]),N=e=>`${Math.floor(e/60)}:${Math.floor(e%60).toString().padStart(2,"0")}`,w=g>0?m/g*100:0;return e("div",{className:"w-full flex items-center gap-4 rounded-full px-3 py-3",style:{maxWidth:"650px",background:"linear-gradient(135deg, #B4F0FF 0%, #7EEAFF 50%, #5FE0F5 100%)",border:"5px solid white",boxShadow:"0 4px 15px rgba(0,0,0,0.08)",borderRadius:"20px"},children:[t("audio",{ref:c,src:o,preload:"metadata"}),t("button",{onClick:l?void 0:x,disabled:l,className:"flex-shrink-0 flex items-center justify-center rounded-xl transition-all "+(l?"opacity-50 cursor-not-allowed grayscale":"hover:scale-105 active:scale-95"),style:{width:"40px",height:"40px",background:u?"linear-gradient(135deg, #FF5B7F, #FF3D6E)":"linear-gradient(135deg, #1565C0, #1E88E5)",boxShadow:u?"0 3px 8px rgba(255,61,110,0.4)":"0 3px 8px rgba(21,101,192,0.4)"},children:u?e("svg",{width:"16",height:"16",viewBox:"0 0 24 24",fill:"white",children:[t("rect",{x:"5",y:"3",width:"5",height:"18",rx:"2"}),t("rect",{x:"14",y:"3",width:"5",height:"18",rx:"2"})]}):t("svg",{width:"18",height:"18",viewBox:"0 0 24 24",fill:"white",children:t("path",{d:"M8 5v14l11-7z"})})}),e("span",{className:"flex-shrink-0 font-bold tabular-nums",style:{color:"#1A3D6D",fontSize:"16px",fontFamily:'"Quicksand", sans-serif',minWidth:"85px"},children:[N(m)," / ",N(g)]}),e("div",{className:"flex-1 relative h-2 rounded-full overflow-hidden",style:{background:"rgba(255,255,255,0.6)"},children:[t("div",{className:"absolute top-0 left-0 h-full rounded-full transition-all",style:{width:`${w}%`,background:"linear-gradient(90deg, #1565C0, #42A5F5)"}}),t("input",{type:"range",min:0,max:g||0,step:.1,value:m,onChange:l?void 0:v,disabled:l,className:"absolute inset-0 w-full h-full opacity-0 "+(l?"cursor-not-allowed":"cursor-pointer")}),t("div",{className:"absolute top-1/2 -translate-y-1/2 w-4 h-4 rounded-full border-2 border-white shadow-md pointer-events-none",style:{left:`calc(${w}% - 8px)`,background:"#1565C0"}})]})]})}function N({total:r,currentIndex:n,answeredIds:i,questionIds:a}){return e("div",{className:"flex items-center gap-2 font-bold text-[#78350f] font-['Quicksand'] z-10",children:[e("span",{className:"text-sm",children:["Question ",n+1,"/ ",r]}),t("div",{className:"flex gap-1.5",children:Array.from({length:r},(e,r)=>{const o=r===n,s=i.has(a[r]);return t("div",{className:"w-2.5 h-2.5 rounded-full "+(o?"bg-[#FF9900] scale-125 shadow-sm":s?"bg-[#16CA3B]":"bg-white/60")},r)})})]})}export function SpeakingSpontaneousQARenderer(l){const w=s({...l,maxDurationMs:6e4}),y=d(l.speakingTheme),b=w.currentQuestion?.content,{previewUrl:E}=o(b?.audioUrl??""),k=0===w.nav.currentIndex,I=w.isQuestionLocked,L=a(()=>I?"ALLOW_RECORDING":k&&!l.skipTeacherVideo&&l.waitForTeacherVideo?"WAITING_TEACHER":"DELAYING",[k,l.skipTeacherVideo,l.waitForTeacherVideo,I]),[A,T]=r(L),F=I||"ALLOW_RECORDING"===A,S=n(null),[C,_]=r(!1),[,P]=r(0),[,R]=r(0);i(()=>{const e=S.current;if(!e)return;const t=()=>{_(!0),w.onAudioPlayingChange?.(!0)},r=()=>{_(!1),w.onAudioPlayingChange?.(!1)},n=()=>{_(!1),P(0),w.onAudioPlayingChange?.(!1)},i=()=>{P(e.currentTime),e.duration&&isFinite(e.duration)&&R(e.duration)},a=()=>{e.duration&&isFinite(e.duration)&&R(e.duration)};return e.addEventListener("play",t),e.addEventListener("pause",r),e.addEventListener("ended",n),e.addEventListener("timeupdate",i),e.addEventListener("loadedmetadata",a),e.addEventListener("durationchange",a),()=>{e.removeEventListener("play",t),e.removeEventListener("pause",r),e.removeEventListener("ended",n),e.removeEventListener("timeupdate",i),e.removeEventListener("loadedmetadata",a),e.removeEventListener("durationchange",a),w.onAudioPlayingChange?.(!1)}},[w.recorder?.previewUrl]),i(()=>{T(L())},[L,w.nav.currentIndex]),i(()=>{if("DELAYING"===A&&!I){const e=setTimeout(()=>{T("PLAYING_QUESTION")},3e3);return()=>clearTimeout(e)}},[A,I]);const G=a(()=>{T("DELAYING"),l.onTeacherIntroPlayed?.()},[l.onTeacherIntroPlayed]),D=a(()=>{"PLAYING_QUESTION"!==A||I||T("ALLOW_RECORDING")},[A,I]);if(!w.currentQuestion||!b)return null;const O=new Set(l.part.questions.map(e=>e.id).filter(e=>!!l.answers[e])),W=l.part.questions.map(e=>e.id);if(l.speakingTheme&&"CAMBRIDGE_YLE"!==l.speakingTheme){const r=t(x,{total:l.part.questions.length,currentIndex:w.nav.currentIndex,answeredIds:O,questionIds:W});return t(y,{onExit:l.onExit,partName:l.part.name||`Part ${l.part.partNo}`,instruction:l.part.instructions||"LISTEN AND ANSWER",audioUrl:b.audioUrl??"",questionNumber:w.nav.questionNumberInPart,onPrev:w.handlePrev,onNext:w.handleNext,showPrev:w.nav.showPrev,showNext:w.nav.showNext,canGoPrev:w.nav.canGoPrev,canGoNext:w.nav.canGoNext,onAudioPlayingChange:w.onAudioPlayingChange,recorder:l.isReviewMode?null:w.recorder,showExistingBadge:w.showExistingBadge,headerRight:r,hideAudioBar:!0,teacherVideoUrl:l.teacherVideoUrl,waitForTeacherVideo:!(!k||l.skipTeacherVideo)&&l.waitForTeacherVideo,onTeacherVideoEnded:G,skipTeacherVideo:!k||l.skipTeacherVideo,showTeacherImage:F,isMicLockedOverride:!I&&"ALLOW_RECORDING"!==A,micLockedText:I?void 0:"PLAYING_QUESTION"===A?"Nghe câu hỏi trước khi trả lời":"DELAYING"===A?"Chuẩn bị phát audio câu hỏi...":"Hãy chờ giáo viên hoàn thành hướng dẫn",children:e("div",{className:"flex flex-col items-center justify-center h-full w-full gap-8 px-8 pb-40",children:[w.showExistingBadge&&e("div",{className:"rounded-full bg-green-500 px-4 py-1 flex items-center gap-2 text-sm font-bold text-white shadow-md border-2 border-white",children:[t("span",{className:"h-2.5 w-2.5 rounded-full bg-white animate-pulse"}),"Đã ghi âm"]}),e("h2",{className:"text-center",style:{color:"#2C38B6",fontSize:"30px",fontFamily:'"SVN-Volte Rounded", "Quicksand", sans-serif',fontWeight:600,lineHeight:"45.74px",letterSpacing:"-0.01em",maxWidth:"700px",WebkitTextStroke:"1px #ffffff",paintOrder:"stroke fill"},children:["Nghe câu hỏi, suy nghĩ và trả lời tự do",t("br",{}),"bằng tiếng Anh."]}),E&&t(v,{audioUrl:E,autoPlay:!I&&"PLAYING_QUESTION"===A,onEnded:D,disabled:"WAITING_TEACHER"===A})]})})}const Q=!I&&"ALLOW_RECORDING"!==A;return e("div",{className:"flex flex-col w-full h-full relative",style:{background:"linear-gradient(180deg, #E6F3FF 0%, #FFFFFF 100%)"},children:[e("div",{className:"relative w-full flex justify-between items-start pt-6 px-6 z-20 shrink-0",children:[t("div",{className:"flex-1"}),t("div",{className:"flex-none drop-shadow-md",children:t(c,{partNumber:l.part.partNo,questionCount:l.part.questions.length,partName:l.part.name||`Part ${l.part.partNo}`})}),t("div",{className:"flex-1 flex justify-end mt-2 z-20",children:t(N,{total:l.part.questions.length,currentIndex:w.nav.currentIndex,answeredIds:O,questionIds:W})})]}),e("div",{className:"flex-1 w-full flex flex-col items-center min-h-0 px-4 pb-6 pt-12",children:[e("div",{className:"flex-1 w-full flex flex-col justify-center items-center gap-12 min-h-0 relative mb-6",children:[w.showExistingBadge&&e("div",{className:"absolute right-4 top-0 z-10 rounded-full bg-green-500 px-4 py-1.5 flex items-center gap-2 text-sm font-bold text-white shadow-lg border-2 border-white transform -translate-y-1/2",children:[t("span",{className:"h-2.5 w-2.5 rounded-full bg-white animate-pulse"}),"Đã ghi âm"]}),e("h2",{className:"text-center z-10",style:{color:"#2C38B6",fontSize:"30px",fontFamily:'"SVN-Volte Rounded", "Quicksand", sans-serif',fontWeight:600,lineHeight:"45.74px",letterSpacing:"-0.01em",maxWidth:"700px",WebkitTextStroke:"1px #ffffff",paintOrder:"stroke fill"},children:["Nghe câu hỏi, suy nghĩ và trả lời tự do",t("br",{}),"bằng tiếng Anh."]}),E&&t(v,{audioUrl:E,autoPlay:!I&&"PLAYING_QUESTION"===A,onEnded:D,disabled:"WAITING_TEACHER"===A})]}),w.recorder&&!l.isReviewMode&&e("div",{className:"shrink-0 flex flex-col items-center z-50 gap-3",children:[t("div",{className:"bg-white rounded-[100px] shadow-[0_4px_10px_rgba(0,0,0,0.1)] whitespace-nowrap flex items-center justify-center",style:{padding:"10px 30px",color:Q?"#888":"recording"===w.recorder.status?"#FF4D4D":["recorded","uploading","uploaded"].includes(w.recorder.status)?"#16CA3B":"#343C55",fontSize:"18px",fontFamily:'"Quicksand", sans-serif',fontWeight:700,lineHeight:"100%",letterSpacing:"-0.01em"},children:Q?I?"Ấn biểu tượng Micro để trả lời":"PLAYING_QUESTION"===A?"Nghe câu hỏi trước khi trả lời":"DELAYING"===A?"Chuẩn bị phát audio câu hỏi...":"Hãy chờ giáo viên hoàn thành hướng dẫn":"recording"===w.recorder.status?"Ấn lần nữa để lưu kết quả":["recorded","uploading","uploaded"].includes(w.recorder.status)?"Câu trả lời đã được ghi nhận !":"Ấn biểu tượng Micro để trả lời"}),t("div",{className:"relative flex flex-col items-center",children:"recording"===w.recorder.status?e("div",{className:"relative flex flex-col justify-center items-center cursor-pointer drop-shadow-[0_0_15px_rgba(255,100,100,0.8)] transition-transform hover:scale-[1.05] active:scale-[0.95]",onClick:w.recorder.stopRecording,children:[t(u,{src:m,alt:"stop audio",className:"animate-pulse",style:{width:"120px",height:"120px"}}),e("span",{className:"absolute text-white text-[16px] font-bold font-['Quicksand']",style:{bottom:"30px"},children:[Math.floor(w.recorder.remainingSeconds/60),":",(w.recorder.remainingSeconds%60).toString().padStart(2,"0")]})]}):t(u,Q?{src:f,alt:"micro locked",className:"opacity-80 cursor-not-allowed",style:{width:"120px",height:"120px"}}:{src:["recorded","uploading","uploaded"].includes(w.recorder.status)?C?g:p:h,alt:"micro",className:"transition-transform cursor-pointer hover:scale-[1.05] active:scale-[0.95]",style:{width:"120px",height:"120px"},onClick:()=>{if(!Q)if("recording"===w.recorder?.status)w.recorder.stopRecording();else if("idle"===w.recorder?.status||"error"===w.recorder?.status)w.recorder.startRecording();else if("uploaded"===w.recorder?.status||"recorded"===w.recorder?.status){const e=S.current;e&&(C?e.pause():e.play().catch(console.error))}}})}),w.recorder.previewUrl&&t("audio",{ref:S,src:w.recorder.previewUrl})]})]})]})}

package/dist/components/exams/take/components/speaking/renderers/SpeakingStoryImagesRenderer.d.ts

@@ -0,0 +1,17 @@
+import type { QuestionPart } from '../../../utils/question-transformers';
+interface SpeakingStoryImagesRendererProps {
+    part: QuestionPart;
+    answers: Record<string, unknown>;
+    onAnswerChange: (questionId: string, value: unknown) => void;
+    isReviewMode?: boolean;
+    onExit: () => void;
+    onPartComplete?: () => void;
+    onPartBack?: () => void;
+    speakingTheme?: string;
+    teacherVideoUrl?: string;
+    waitForTeacherVideo?: boolean;
+    onTeacherIntroPlayed?: () => void;
+    skipTeacherVideo?: boolean;
+}
+export declare function SpeakingStoryImagesRenderer(props: SpeakingStoryImagesRendererProps): import("react").JSX.Element;
+export {};

package/dist/components/exams/take/components/speaking/renderers/SpeakingStoryImagesRenderer.js

@@ -0,0 +1 @@
+"use client";import{jsx as e,jsxs as r}from"react/jsx-runtime";import{useCallback as a,useEffect as n,useState as o}from"react";import{ResolvedImage as t}from"../../../../../../components/common/ResolvedImage";import{useSpeakingRendererSetup as i}from"../../../hooks/useSpeakingRendererSetup";import{getSpeakingLayout as s}from"../../../../../../components/themes";import l from"../SpeakingStoryImages.module.css";export function SpeakingStoryImagesRenderer(c){const m=i({...c,maxDurationMs:3e4}),h=s(c.speakingTheme),u=m.currentQuestion?.content,[g,p]=o(null),x=a(()=>p(null),[]);if(n(()=>{if(!g)return;const e=e=>{"Escape"===e.key&&x()};return window.addEventListener("keydown",e),()=>window.removeEventListener("keydown",e)},[g,x]),!m.currentQuestion||!u)return null;const N=u.audioUrl??"",v=u.images??[];return e(h,{onExit:c.onExit,partName:c.part.name||`Part ${c.part.partNo}`,instruction:c.part.instructions||"LOOK AT THE PICTURES. LISTEN AND TELL THE STORY.",audioUrl:N,questionNumber:m.nav.questionNumberInPart,onPrev:m.handlePrev,onNext:m.handleNext,showPrev:m.nav.showPrev,showNext:m.nav.showNext,canGoPrev:m.nav.canGoPrev,canGoNext:m.nav.canGoNext,onAudioPlayingChange:m.onAudioPlayingChange,recorder:c.isReviewMode?null:m.recorder,showExistingBadge:m.showExistingBadge,teacherVideoUrl:c.teacherVideoUrl,waitForTeacherVideo:c.waitForTeacherVideo,onTeacherVideoEnded:c.onTeacherIntroPlayed,skipTeacherVideo:c.skipTeacherVideo,children:r("div",{className:l.part3Container,children:[m.showExistingBadge&&r("div",{className:"absolute right-4 top-4 z-10 rounded-full bg-green-500 px-4 py-1 flex items-center gap-2 text-sm font-bold text-white shadow-md border-2 border-white",children:[e("span",{className:"h-2.5 w-2.5 rounded-full bg-white animate-pulse"}),"Đã ghi âm"]}),0===v.length?e("div",{className:l.emptyState,children:e("span",{children:"No images available"})}):e("div",{className:l.storyGrid,"data-count":v.length,children:v.map((r,a)=>e(d,{src:r,index:a,onEnlarge:()=>p(r)},`${r}-${a}`))}),g&&r("div",{className:l.lightboxBackdrop,onClick:x,role:"dialog","aria-modal":"true",children:[e("button",{type:"button",className:l.lightboxClose,onClick:x,"aria-label":"Đóng",children:"✕"}),e(t,{src:g,alt:"Story image enlarged",className:l.lightboxImage,draggable:!1})]})]})})}function d({src:a,index:n,onEnlarge:o}){return r("div",{className:l.storyFrame,children:[e("span",{className:l.storyNumber,"aria-hidden":"true",children:n+1}),e("button",{type:"button",className:l.imageBorder,onClick:o,"aria-label":`Phóng to ảnh số ${n+1}`,children:e(t,{src:a,alt:`Story image ${n+1}`,draggable:!1})})]})}

package/dist/components/exams/take/components/speaking/renderers/index.d.ts

@@ -0,0 +1,13 @@
+export { SpeakingCompareImagesRenderer } from './SpeakingCompareImagesRenderer';
+export { SpeakingStoryImagesRenderer } from './SpeakingStoryImagesRenderer';
+export { SpeakingOddOneOutRenderer } from './SpeakingOddOneOutRenderer';
+export { SpeakingQuestionListRenderer } from './SpeakingQuestionListRenderer';
+export { SpeakingChooseObjectsRenderer } from './SpeakingChooseObjectsRenderer';
+export { SpeakingChooseAnswerGroupRenderer } from './SpeakingChooseAnswerGroupRenderer';
+export { SpeakingDragObjectsRenderer } from './SpeakingDragObjectsRenderer';
+export { SpeakingListenAndSpeakAnswerRenderer } from './SpeakingListenAndSpeakAnswerRenderer';
+export { SpeakingDescribeImageRenderer } from './SpeakingDescribeImageRenderer';
+export { SpeakingInfoExchangeRenderer } from './SpeakingInfoExchangeRenderer';
+export { SpeakingReadDisplayedContentRenderer } from './SpeakingReadDisplayedContentRenderer';
+export { SpeakingSpontaneousQARenderer } from './SpeakingSpontaneousQARenderer';
+export { SpeakingQuestionRenderer } from './SpeakingQuestionRenderer';

package/dist/components/exams/take/components/speaking/renderers/index.js

@@ -0,0 +1 @@
+export{SpeakingCompareImagesRenderer}from"./SpeakingCompareImagesRenderer";export{SpeakingStoryImagesRenderer}from"./SpeakingStoryImagesRenderer";export{SpeakingOddOneOutRenderer}from"./SpeakingOddOneOutRenderer";export{SpeakingQuestionListRenderer}from"./SpeakingQuestionListRenderer";export{SpeakingChooseObjectsRenderer}from"./SpeakingChooseObjectsRenderer";export{SpeakingChooseAnswerGroupRenderer}from"./SpeakingChooseAnswerGroupRenderer";export{SpeakingDragObjectsRenderer}from"./SpeakingDragObjectsRenderer";export{SpeakingListenAndSpeakAnswerRenderer}from"./SpeakingListenAndSpeakAnswerRenderer";export{SpeakingDescribeImageRenderer}from"./SpeakingDescribeImageRenderer";export{SpeakingInfoExchangeRenderer}from"./SpeakingInfoExchangeRenderer";export{SpeakingReadDisplayedContentRenderer}from"./SpeakingReadDisplayedContentRenderer";export{SpeakingSpontaneousQARenderer}from"./SpeakingSpontaneousQARenderer";export{SpeakingQuestionRenderer}from"./SpeakingQuestionRenderer";

package/dist/components/exams/take/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useExamTimer } from './useExamTimer';
+export { useAutoSave } from './useAutoSave';

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

@@ -0,0 +1 @@
+export{useExamTimer}from"./useExamTimer";export{useAutoSave}from"./useAutoSave";

package/dist/components/exams/take/hooks/useAnswerAutosave.d.ts

@@ -0,0 +1,27 @@
+import type { ExamTakingAnswerValue, ExamTakingSdkApi } from '../../../../api/exam-taking';
+export interface UseAnswerAutosaveOptions {
+    /** API adapter; autosave is skipped when `saveAnswers` is undefined. */
+    api: ExamTakingSdkApi;
+    /** Active attempt id, or null while loading. */
+    attemptId: string | null;
+    /** Whether autosave is active (attempt loaded & not submitting). */
+    enabled: boolean;
+    /** Debounce window before a pending change is flushed to the server. */
+    debounceMs?: number;
+    /** Notified when a save fails so the host can surface a toast. */
+    onSaveError?: (error: unknown) => void;
+}
+export interface UseAnswerAutosaveResult {
+    /** Queue a single answer change; debounced + flushed on tab hide/unload. */
+    queueAnswer: (questionId: string, answer: ExamTakingAnswerValue) => void;
+    /** Force an immediate flush of all pending answers (e.g. before submit). */
+    flushNow: () => Promise<void>;
+    /** `true` when there are unsaved answers buffered locally. */
+    hasPendingRef: React.MutableRefObject<boolean>;
+}
+/**
+ * Buffers answer changes and persists them in debounced batches. Ports the host
+ * app's resilience: a `keepalive` flush on tab hide / page unload and a retry on
+ * the `online` event so answers survive refreshes and flaky networks.
+ */
+export declare function useAnswerAutosave({ api, attemptId, enabled, debounceMs, onSaveError, }: UseAnswerAutosaveOptions): UseAnswerAutosaveResult;

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

@@ -0,0 +1 @@
+"use client";import{useCallback as e,useEffect as r,useRef as n}from"react";export function useAnswerAutosave({api:t,attemptId:i,enabled:s,debounceMs:u=800,onSaveError:c}){const a=n(new Map),o=n(!1),d=n(null),w=n(c);w.current=c;const v=e(async e=>{if(!i||!t.saveAnswers||0===a.current.size)return;const r=Array.from(a.current.entries()).map(([e,r])=>({questionId:e,answer:r}));a.current.clear(),o.current=!1;try{await t.saveAnswers({attemptId:i,answers:r,keepalive:e})}catch(e){r.forEach(({questionId:e,answer:r})=>a.current.set(e,r)),o.current=!0,w.current?.(e)}},[t,i]),m=e(()=>v(!1),[v]),l=e((e,r)=>{s&&(a.current.set(e,r),o.current=!0,d.current&&clearTimeout(d.current),d.current=setTimeout(()=>{v(!1)},u))},[u,v,s]);return r(()=>{if(!s)return;const e=()=>{v(!0)},r=()=>{"hidden"===document.visibilityState&&e()},n=()=>{o.current&&v(!1)};return document.addEventListener("visibilitychange",r),window.addEventListener("pagehide",e),window.addEventListener("online",n),()=>{document.removeEventListener("visibilitychange",r),window.removeEventListener("pagehide",e),window.removeEventListener("online",n),d.current&&clearTimeout(d.current)}},[v,s]),{queueAnswer:l,flushNow:m,hasPendingRef:o}}

package/dist/components/exams/take/hooks/useAttemptSubmit.d.ts

@@ -0,0 +1,29 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+export interface UseAttemptSubmitOptions {
+    /** API adapter. */
+    api: ExamTakingSdkApi;
+    /** Flush pending answers before submitting (e.g. from `useAnswerAutosave`). */
+    flushAnswers?: () => Promise<void>;
+    /** Notified on success with the submit result + pending grading answer ids. */
+    onSubmitted?: (result: SubmittedSummary) => void;
+    /** Notified when submission fails. */
+    onError?: (error: unknown) => void;
+}
+export interface SubmittedSummary {
+    attemptId: string;
+    pendingAnswerIds: string[];
+    manualReviewAnswerIds: string[];
+    autoGradedCount: number;
+}
+export interface UseAttemptSubmitResult {
+    /** Submit the attempt (flushes answers first); guards against double submit. */
+    submit: (attemptId: string) => Promise<void>;
+    /** `true` while a submit request is in flight. */
+    isSubmitting: boolean;
+}
+/**
+ * Submits an attempt with the host app's guarantees: flush any buffered answers
+ * first, prevent concurrent submits, and surface the pending/auto-graded answer
+ * ids so the caller can route to the review screen with the right context.
+ */
+export declare function useAttemptSubmit({ api, flushAnswers, onSubmitted, onError, }: UseAttemptSubmitOptions): UseAttemptSubmitResult;

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

@@ -0,0 +1 @@
+"use client";import{useCallback as t,useState as e}from"react";export function useAttemptSubmit({api:n,flushAnswers:a,onSubmitted:i,onError:s}){const[r,u]=e(!1);return{submit:t(async t=>{if(!r){u(!0);try{a&&await a();const s="object"==typeof(e=await n.submitAttempt(t))&&null!==e&&"data"in e?e.data:e??{};i?.({attemptId:t,pendingAnswerIds:s.pendingAnswerIds??[],manualReviewAnswerIds:s.manualReviewAnswerIds??[],autoGradedCount:s.autoGradedCount??0})}catch(t){s?.(t),u(!1)}var e}},[n,a,r,s,i]),isSubmitting:r}}

package/dist/components/exams/take/hooks/useAutoSave.d.ts

@@ -0,0 +1,20 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+import type { QuestionPart } from '../utils/question-transformers';
+interface UseAutoSaveOptions {
+    /** Injected API adapter (replaces the host app's `attemptsApi`). */
+    api: ExamTakingSdkApi;
+    attemptId: string;
+    parts: QuestionPart[];
+    intervalMs?: number;
+    onSaveStart?: () => void;
+    onSaveSuccess?: () => void;
+    onSaveError?: (error: Error) => void;
+}
+interface UseAutoSaveReturn {
+    isSaving: boolean;
+    lastSavedAt: Date | null;
+    lastError: Error | null;
+    saveNow: () => Promise<void>;
+}
+export declare function useAutoSave(options: UseAutoSaveOptions): UseAutoSaveReturn;
+export {};

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

@@ -0,0 +1 @@
+import{useState as t,useEffect as r,useRef as e,useCallback as a}from"react";import{useExamTakingStore as n}from"../../../../shared/lib/stores/examTakingStore";import{transformAnswersForSubmission as s}from"../utils/answer-transformers";export function useAutoSave(i){const o=n(),[l,u]=t(!1),[c,S]=t(null),v=e(null),m=i.intervalMs??3e4,p=a(async()=>{if(l||o.isSubmitting||!o.isDirty)return;if(0!==Object.keys(o.answers).length){u(!0),i.onSaveStart?.();try{const t=s(o.answers,i.parts);if(0===t.length)return void o.markSaved();await(i.api.saveAnswers?.({attemptId:i.attemptId,answers:t})),o.markSaved(),S(null),i.onSaveSuccess?.()}catch(t){const r=t;S(r),i.onSaveError?.(r)}finally{u(!1)}}},[i.api,i.attemptId,i.onSaveStart,i.onSaveSuccess,i.onSaveError,l,o.isSubmitting,o.isDirty,o.answers]);return r(()=>(v.current&&clearInterval(v.current),v.current=setInterval(async()=>{!o.isDirty||o.isSubmitting||l||await p()},m),()=>{v.current&&(clearInterval(v.current),v.current=null)}),[m,o.isDirty,o.isSubmitting,l,p]),{isSaving:l,lastSavedAt:o.lastSavedAt,lastError:c,saveNow:p}}

package/dist/components/exams/take/hooks/useExamCountdown.d.ts

@@ -0,0 +1,22 @@
+export interface UseExamCountdownOptions {
+    /** Total duration of the attempt in minutes. */
+    durationMinutes: number;
+    /** ISO timestamp marking when the attempt started. */
+    startedAt: string | null | undefined;
+    /** Whether the countdown is active (e.g. attempt loaded & not submitted). */
+    enabled: boolean;
+    /** Fired exactly once when remaining time reaches zero. */
+    onExpire: () => void;
+}
+export interface UseExamCountdownResult {
+    /** Whole seconds remaining (clamped at 0). */
+    remainingSeconds: number;
+    /** `true` once the countdown has reached zero. */
+    isExpired: boolean;
+}
+/**
+ * Drives the exam timer. Computes remaining seconds from `startedAt + duration`
+ * so the value stays correct across tab refreshes, and invokes `onExpire` once
+ * when time runs out (mirrors the host app's auto-submit trigger).
+ */
+export declare function useExamCountdown({ durationMinutes, startedAt, enabled, onExpire, }: UseExamCountdownOptions): UseExamCountdownResult;

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

@@ -0,0 +1 @@
+"use client";import{useEffect as e,useRef as t,useState as r}from"react";export function useExamCountdown({durationMinutes:n,startedAt:o,enabled:c,onExpire:u}){const[a,i]=r(0),s=t(!1),d=t(u);return d.current=u,e(()=>{if(!c||!o)return;const e=new Date(o).getTime()+6e4*n;s.current=!1;const t=()=>{const t=Math.max(0,Math.floor((e-Date.now())/1e3));i(t),t<=0&&!s.current&&(s.current=!0,d.current())};t();const r=setInterval(t,1e3);return()=>clearInterval(r)},[n,c,o]),{remainingSeconds:a,isExpired:s.current}}

package/dist/components/exams/take/hooks/useExamTimer.d.ts

@@ -0,0 +1,21 @@
+export type WarningLevel = 'none' | 'warning' | 'critical';
+export interface WarningThreshold {
+    seconds: number;
+    level: WarningLevel;
+    callback?: () => void;
+}
+interface UseExamTimerOptions {
+    onTimeExpired: () => void;
+    /** @deprecated Use warningThresholds[] instead */
+    onWarningThreshold?: () => void;
+    /** @deprecated Use warningThresholds[] instead */
+    warningThresholdSeconds?: number;
+    /** Multiple warning thresholds for TOEIC (15min + 5min). Highest severity wins. */
+    warningThresholds?: WarningThreshold[];
+}
+interface UseExamTimerReturn {
+    remainingSeconds: number;
+    warningLevel: WarningLevel;
+}
+export declare function useExamTimer(options: UseExamTimerOptions): UseExamTimerReturn;
+export {};

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

@@ -0,0 +1 @@
+import{useEffect as n,useRef as e}from"react";import{useExamTakingStore as r}from"../../../../shared/lib/stores/examTakingStore";export function useExamTimer(t){const i=r(),c=e(null),o=e(!1),s=(()=>{const n=t.warningThresholds??[];if(0===n.length&&void 0!==t.warningThresholdSeconds){const n=[];return t.onWarningThreshold&&n.push({seconds:t.warningThresholdSeconds,level:"critical",callback:t.onWarningThreshold}),n}return n})(),l=e(new Set),a=e(t.onTimeExpired);a.current=t.onTimeExpired,n(()=>{if(!i.isInitialized)return;c.current&&clearInterval(c.current),o.current=!1,l.current=new Set;const n=()=>{const n=i.syncRemainingSeconds();for(const e of s)n<=e.seconds&&!l.current.has(e.seconds)&&(l.current.add(e.seconds),e.callback?.());n<=0&&(c.current&&(clearInterval(c.current),c.current=null),o.current||(o.current=!0,a.current()))};c.current=setInterval(n,1e3);const e=()=>{"visible"===document.visibilityState&&n()};return document.addEventListener("visibilitychange",e),window.addEventListener("focus",e),()=>{c.current&&(clearInterval(c.current),c.current=null),document.removeEventListener("visibilitychange",e),window.removeEventListener("focus",e)}},[i.isInitialized]);const u=function(n,e){let r="none";for(const t of e)if(n<=t.seconds&&"none"!==t.level){if("critical"===t.level)return"critical";"warning"===t.level&&(r="warning")}return r}(i.remainingSeconds,s);return{remainingSeconds:i.remainingSeconds,warningLevel:u}}

package/dist/components/exams/take/hooks/useProctoringCamera.d.ts

@@ -0,0 +1,19 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+interface UseProctoringCameraProps {
+    /** Injected API adapter (replaces the host app's `attemptsApi`). */
+    api: ExamTakingSdkApi;
+    attemptId: string | null;
+    intervalMs?: number;
+    /**
+     * Gate camera capture. The host app previously gated on
+     * `NEXT_PUBLIC_ENABLE_PROCTORING_CAMERA`; expose it as a prop so the SDK does
+     * not read host env vars. Defaults to `false` (disabled).
+     */
+    enabled?: boolean;
+}
+export declare function useProctoringCamera({ api, attemptId, intervalMs, enabled, }: UseProctoringCameraProps): {
+    isCameraActive: boolean;
+    cameraError: string;
+    snapshotCount: number;
+};
+export {};

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

@@ -0,0 +1 @@
+import{useEffect as e,useRef as r,useState as t}from"react";export function useProctoringCamera({api:n,attemptId:a,intervalMs:o=1e4,enabled:c=!1}){const[i,u]=t(!1),[l,s]=t(null),[d,m]=t(0),p=r(null),h=r(null),g=r(null);return e(()=>{if("undefined"==typeof window)return;if(!c)return;let e=!0;return(async()=>{try{const r=await navigator.mediaDevices.getUserMedia({video:{facingMode:"user"},audio:!1});if(!e)return void r.getTracks().forEach(e=>e.stop());h.current=r;const t=document.createElement("video");t.srcObject=r,t.muted=!0,t.playsInline=!0,t.onloadedmetadata=()=>{e&&(t.play().catch(console.error),u(!0),s(null))},p.current=t}catch(r){console.error("Camera permission denied or error:",r),e&&(u(!1),s(r.message||"Camera access denied"))}})(),()=>{e=!1,h.current&&(h.current.getTracks().forEach(e=>e.stop()),h.current=null),u(!1),p.current=null}},[c]),e(()=>{if(!a||!i||!p.current)return void(g.current&&(clearInterval(g.current),g.current=null));return g.current=setInterval(async()=>{const e=p.current;if(e&&e.videoWidth)try{const r=document.createElement("canvas");r.width=e.videoWidth,r.height=e.videoHeight;const t=r.getContext("2d");if(!t)return;t.drawImage(e,0,0,r.width,r.height),r.toBlob(async e=>{if(e)try{await(n.uploadProctoringSnapshot?.({attemptId:a,imageBlob:e})),m(e=>e+1)}catch(e){console.error("Failed to upload proctoring snapshot:",e)}},"image/jpeg",.6)}catch(e){console.error("Error in capture process:",e)}},o),()=>{g.current&&(clearInterval(g.current),g.current=null)}},[n,a,i,o]),{isCameraActive:i,cameraError:l,snapshotCount:d}}

package/dist/components/exams/take/hooks/useProctoringSnapshot.d.ts

@@ -0,0 +1,25 @@
+import type { ExamTakingSdkApi } from '../../../../api/exam-taking';
+export interface UseProctoringSnapshotOptions {
+    /** API adapter; snapshots are skipped when `uploadProctoringSnapshot` is undefined. */
+    api: ExamTakingSdkApi;
+    /** Active attempt id, or null while loading. */
+    attemptId: string | null;
+    /** Whether proctoring is active (attempt loaded, room requires proctoring). */
+    enabled: boolean;
+    /** Interval between snapshot uploads in milliseconds. */
+    intervalMs?: number;
+    /** Notified when a snapshot capture/upload fails (best-effort logging). */
+    onError?: (error: unknown) => void;
+}
+export interface UseProctoringSnapshotResult {
+    /** Attach to a `<video>` element rendering the proctoring webcam stream. */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** `true` once the webcam stream is live and snapshots are being captured. */
+    isActiveRef: React.MutableRefObject<boolean>;
+}
+/**
+ * Captures periodic webcam snapshots and uploads them for proctoring. Owns the
+ * camera stream lifecycle (request on enable, stop on cleanup) and encodes
+ * frames off a hidden canvas, mirroring the host app's proctoring loop.
+ */
+export declare function useProctoringSnapshot({ api, attemptId, enabled, intervalMs, onError, }: UseProctoringSnapshotOptions): UseProctoringSnapshotResult;

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

@@ -0,0 +1 @@
+"use client";import{useEffect as t,useRef as e}from"react";export function useProctoringSnapshot({api:r,attemptId:n,enabled:a,intervalMs:i=6e4,onError:o}){const c=e(null),s=e(!1),u=e(o);return u.current=o,t(()=>{if(!a||!n||!r.uploadProctoringSnapshot)return;if("undefined"==typeof navigator||!navigator.mediaDevices?.getUserMedia)return;let t=null,e=null,o=!1;const d=async()=>{const t=c.current;if(!t||0===t.videoWidth||!r.uploadProctoringSnapshot)return;const e=document.createElement("canvas");e.width=t.videoWidth,e.height=t.videoHeight;const a=e.getContext("2d");if(!a)return;a.drawImage(t,0,0,e.width,e.height);const i=await new Promise(t=>e.toBlob(t,"image/jpeg",.7));if(i)try{await r.uploadProctoringSnapshot({attemptId:n,imageBlob:i})}catch(t){u.current?.(t)}};return(async()=>{try{if(t=await navigator.mediaDevices.getUserMedia({video:!0,audio:!1}),o)return void t.getTracks().forEach(t=>t.stop());c.current&&(c.current.srcObject=t,await c.current.play().catch(()=>{})),s.current=!0,d(),e=setInterval(()=>{d()},i)}catch(t){u.current?.(t)}})(),()=>{o=!0,s.current=!1,e&&clearInterval(e),t&&t.getTracks().forEach(t=>t.stop())}},[r,n,a,i]),{videoRef:c,isActiveRef:s}}

package/dist/components/exams/take/hooks/useSpeakingConversationAudio.d.ts

@@ -0,0 +1,19 @@
+export type ConversationPlaybackPhase = 'idle' | 'playing-interlocutor' | 'playing-partner' | 'ready';
+export interface UseSpeakingConversationAudioOptions {
+    /** S3 key or direct URL for the interlocutor's audio */
+    interlocutorAudioUrl?: string;
+    /** S3 key or direct URL for the partner's audio */
+    partnerAudioUrl?: string;
+    /** Called once when the full sequence has finished */
+    onSequenceComplete: () => void;
+}
+export interface UseSpeakingConversationAudioReturn {
+    phase: ConversationPlaybackPhase;
+    isPlaying: boolean;
+    replayAll: () => void;
+    togglePlayPause: () => void;
+    currentAudioUrl: string;
+    currentTime: number;
+    duration: number;
+}
+export declare function useSpeakingConversationAudio({ interlocutorAudioUrl, partnerAudioUrl, onSequenceComplete, }: UseSpeakingConversationAudioOptions): UseSpeakingConversationAudioReturn;

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

@@ -0,0 +1 @@
+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}}

package/dist/components/exams/take/hooks/useSpeakingNavigation.d.ts

@@ -0,0 +1,37 @@
+import type { ApiQuestion } from '../utils/question-transformers';
+/**
+ * A speaking question enriched with part metadata.
+ * Extends ApiQuestion with part display info and a stable exam-wide index.
+ */
+export interface SpeakingQuestion extends ApiQuestion {
+    partName: string;
+    /** 0-based index within the full flattened exam question list */
+    questionIndex: number;
+}
+export interface UseSpeakingNavigationOptions {
+    questions: SpeakingQuestion[];
+    initialIndex?: number;
+}
+export interface UseSpeakingNavigationReturn {
+    /** 0-based index of the currently displayed question */
+    currentIndex: number;
+    /** Currently displayed question, or null if questions list is empty */
+    currentQuestion: SpeakingQuestion | null;
+    /** Total number of questions across all parts */
+    totalQuestions: number;
+    /** part_no of the current question */
+    currentPartNo: number;
+    /** Display name of the current part (e.g. "Part 1") */
+    currentPartName: string;
+    /**
+     * 1-based question number within the current part.
+     * Used for "CÂU HỎI SỐ [N]" display label.
+     */
+    questionNumberInPart: number;
+    canGoPrev: boolean;
+    canGoNext: boolean;
+    goNext: () => void;
+    goPrev: () => void;
+    goTo: (index: number) => void;
+}
+export declare function useSpeakingNavigation(options: UseSpeakingNavigationOptions): UseSpeakingNavigationReturn;

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

@@ -0,0 +1 @@
+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}}

package/dist/components/exams/take/hooks/useSpeakingRecorder.d.ts

@@ -1,8 +1,48 @@
-export type SpeakingRecorderStatus = 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
-export declare function useSpeakingRecorder(_options?: unknown): {
-    status: SpeakingRecorderStatus;
-    previewUrl: string;
+export type RecordingStatus = 'idle' | 'recording' | 'recorded' | 'uploading' | 'uploaded' | 'error';
+export interface UseSpeakingRecorderOptions {
+    /** Attempt ID — needed for upload endpoint */
+    attemptId: string;
+    /** Question ID — needed for upload endpoint */
+    questionId: string;
+    /** Max recording duration in ms (default: 30000) */
+    maxDurationMs?: number;
+    /** Called with S3 key when upload completes */
+    onRecordingComplete: (audioKey: string, forQuestionId?: string) => void;
+    /** Called on any non-retryable error */
+    onError?: (error: string) => void;
+    /** Existing S3 key from a previous recording (used to restore playback on navigation) */
+    existingAnswerKey?: string;
+}
+export interface UseSpeakingRecorderReturn {
+    /** Current recording status */
+    status: RecordingStatus;
+    /** Countdown while recording (counts down from maxDurationMs/1000) */
     remainingSeconds: number;
+    /** True when remainingSeconds <= 5 */
+    isWarning: boolean;
+    /** Elapsed seconds while recording */
+    durationSeconds: number;
+    /** Local blob URL for playback preview (available after recording stops) */
+    previewUrl: string | null;
+    /** Uploaded S3 key (available after upload completes) */
+    uploadedKey: string | null;
+    /** Error message if status === 'error' */
+    error: string | null;
+    /** Whether the browser supports MediaRecorder API */
+    isSupported: boolean;
+    /** True when attempt has expired — caller should redirect */
+    isAttemptExpired: boolean;
+    /** Live transcript text (STREAMING mode only — null in RECORDING mode) */
+    liveTranscript: string | null;
+    /** Start recording. Requests microphone permission if not granted. */
     startRecording: () => Promise<void>;
+    /** Stop recording. Automatically triggers upload. */
     stopRecording: () => void;
-};
+    /** Discard current recording and reset to idle */
+    resetRecording: () => void;
+    /** Re-record: discard current recording and start a new one */
+    reRecord: () => Promise<void>;
+    /** Retry upload with the existing blob (no re-record required) */
+    retryUpload: () => Promise<void>;
+}
+export declare function useSpeakingRecorder(options: UseSpeakingRecorderOptions): UseSpeakingRecorderReturn;

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

@@ -1 +1 @@
-"use client";import{useRef as e,useState as r}from"react";export function useSpeakingRecorder(t){const n=e(null),a=e([]),[o,c]=r("idle"),[i,s]=r(null);return{status:o,previewUrl:i,remainingSeconds:0,startRecording:async()=>{const e=await navigator.mediaDevices.getUserMedia({audio:!0});a.current=[];const r=new MediaRecorder(e);n.current=r,r.ondataavailable=e=>a.current.push(e.data),r.onstop=()=>{e.getTracks().forEach(e=>e.stop()),s(URL.createObjectURL(new Blob(a.current,{type:"audio/webm"}))),c("recorded")},r.start(),c("recording")},stopRecording:()=>n.current?.stop()}}
+import{useState as r,useRef as e,useEffect as n,useCallback as t}from"react";import{usePresignedFileUrl as u}from"../../../../shared/lib/hooks";import{useExamTakingApi as o}from"../ExamTakingApiContext";export function useSpeakingRecorder(i){const c=i.maxDurationMs??3e4,a=Math.floor(c/1e3),d=o(),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),m=e(i.questionId);g.current=i.attemptId,m.current=i.questionId;const[h,y]=r("idle"),[w,f]=r(a),[A,v]=r(0),[R,T]=r(null),[E,x]=r(null),[I,b]=r(null),[K,M]=r(!1),k=e(null),P=e(null),D=e([]),S=e(null),U=e(null),O=e(""),_=e(0),q=e(null),L=e(void 0),B=e(0),V=e(!0),C=e(""),G="undefined"!=typeof MediaRecorder,{previewUrl:j}=u(i.existingAnswerKey),N=t(()=>{S.current&&(clearInterval(S.current),S.current=null)},[]),F=t(()=>{U.current&&(U.current.startsWith("blob:")&&URL.revokeObjectURL(U.current),U.current=null)},[]),W=t(()=>{P.current&&(P.current.getTracks().forEach(r=>r.stop()),P.current=null)},[]),X=t(async(r,e,n,t)=>{if(!V.current)return;const u=t||C.current||m.current;m.current===u&&y("uploading");const o=g.current;if("mock-attempt-speaking"===o){if(await new Promise(r=>setTimeout(r,500)),!V.current)return;const r=`mock-audio-key-${u}`;return m.current===u&&(y("uploaded"),x(r)),l.current(r,u),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:o,questionId:u,audioBlob:r,durationMs:e}))&&"object"==typeof i&&"data"in i?i.data:i;if(!V.current)return;const t=n.audioKey??"";m.current===u&&(y("uploaded"),x(t)),l.current(t,u),q.current=null,L.current=void 0,B.current=0,s.current.realtimeGradeSingle?.({attemptId:o,questionId:u,audioKey:t}).catch(r=>{console.debug("[Realtime Grading] Skipped or failed:",r?.response?.status??r?.message)})}catch(u){if(!V.current)return;const o=u,i=o?.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"),b(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"),b(r),void p.current?.(r)}if(n<3){const u=1e3*Math.pow(2,n);if(await new Promise(r=>setTimeout(r,u)),!V.current)return;B.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"),b(r),p.current?.(r)}}var i},[]),z=t(async(r,e,n)=>{q.current=r,L.current=e,B.current=0,await X(r,e,0,n)},[X]),$=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);if(!G){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"),b(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"),b(r),void p.current?.(r)}try{const e=await navigator.mediaDevices.getUserMedia({audio:!0});P.current=e,O.current=r;const n=new MediaRecorder(e,{mimeType:r});k.current=n,D.current=[],n.ondataavailable=r=>{r.data.size>0&&D.current.push(r.data)},n.onstop=()=>{const r=Date.now()-_.current,e=new Blob(D.current,{type:O.current}),n=URL.createObjectURL(e),t=C.current;F(),U.current=n,T(n),y("recorded"),z(e,r,t)},n.start(),_.current=Date.now(),C.current=m.current,y("recording"),v(0),f(a),b(null),x(null),T(null),M(!1),S.current=setInterval(()=>{v(r=>r+1),f(r=>{const e=Math.max(0,r-1);return 0===e&&(N(),k.current&&"recording"===k.current.state&&k.current.stop(),W()),e})},1e3)}catch(r){W();const e=r instanceof DOMException&&("NotAllowedError"===r.name||"PermissionDeniedError"===r.name)?"Vui lòng cấp quyền truy cập microphone trong trình duyệt.":"Không thể truy cập microphone. Vui lòng thử lại.";y("error"),b(e),p.current?.(e)}},[G,a,i.existingAnswerKey,N,W,z,F]),H=t(()=>{N(),k.current&&"recording"===k.current.state&&k.current.stop(),W()},[N,W]),J=t(()=>{N(),W(),k.current&&"recording"===k.current.state&&k.current.stop(),k.current=null,D.current=[],q.current=null,L.current=void 0,B.current=0,F(),T(null),x(null),v(0),f(a),b(null),y("idle"),M(!1)},[N,W,F,a]),Q=t(async()=>{if(i.existingAnswerKey)return y("uploaded"),void x(i.existingAnswerKey);J(),await $()},[i.existingAnswerKey,J,$]),Y=t(async()=>{const r=q.current;r&&(B.current=0,await X(r,L.current,0,C.current||void 0))},[X]);n(()=>{J()},[i.questionId]),n(()=>{"idle"===h&&j&&i.existingAnswerKey&&!R&&(T(j),U.current=j,x(i.existingAnswerKey),y("uploaded"))},[h,j,i.existingAnswerKey,R]),n(()=>(V.current=!0,()=>{V.current=!1,N(),k.current&&"recording"===k.current.state&&k.current.stop(),W(),F()}),[]);return{status:h,remainingSeconds:w,isWarning:w<=5&&"recording"===h,durationSeconds:A,previewUrl:R,uploadedKey:E,error:I,isSupported:G,isAttemptExpired:K,liveTranscript:null,startRecording:$,stopRecording:H,resetRecording:J,reRecord:Q,retryUpload:Y}}

package/dist/components/exams/take/hooks/useSpeakingRendererSetup.d.ts

@@ -0,0 +1,39 @@
+import { type SpeakingQuestion } from './useSpeakingNavigation';
+import type { QuestionPart } from '../utils/question-transformers';
+export interface UseSpeakingRendererSetupOptions {
+    part: QuestionPart;
+    answers: Record<string, unknown>;
+    onAnswerChange: (questionId: string, value: unknown) => void;
+    onPartComplete?: () => void;
+    onPartBack?: () => void;
+    maxDurationMs?: number;
+    hasMic?: boolean;
+    initialQuestionIndex?: number;
+    currentQuestionIndex?: number;
+}
+export declare function useSpeakingRendererSetup({ part, answers, onAnswerChange, onPartComplete, onPartBack, maxDurationMs, hasMic, initialQuestionIndex, currentQuestionIndex, }: UseSpeakingRendererSetupOptions): {
+    nav: {
+        showPrev: boolean;
+        showNext: boolean;
+        canGoPrev: boolean;
+        canGoNext: boolean;
+        currentIndex: number;
+        currentQuestion: SpeakingQuestion | null;
+        totalQuestions: number;
+        currentPartNo: number;
+        currentPartName: string;
+        questionNumberInPart: number;
+        goNext: () => void;
+        goPrev: () => void;
+        goTo: (index: number) => void;
+    };
+    recorder: import("./useSpeakingRecorder").UseSpeakingRecorderReturn;
+    currentQuestion: SpeakingQuestion;
+    handleNext: () => void;
+    handlePrev: () => void;
+    showExistingBadge: boolean;
+    isRecordingInProgress: boolean;
+    isQuestionLocked: boolean;
+    isPostRecordingDelayActive: boolean;
+    onAudioPlayingChange: (playing: boolean) => void;
+};

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

@@ -0,0 +1 @@
+import{useEffect as e,useMemo as r,useCallback as t,useRef as n,useState as o}from"react";import{toast as i}from"../../../../shared/lib/toast";import{useExamTakingStore as s}from"../../../../shared/lib/stores/examTakingStore";import{useSpeakingNavigation as a}from"./useSpeakingNavigation";import{useSpeakingRecorder as c}from"./useSpeakingRecorder";export function useSpeakingRendererSetup({part:u,answers:d,onAnswerChange:m,onPartComplete:l,onPartBack:p,maxDurationMs:x=3e4,hasMic:g=!0,initialQuestionIndex:v=0,currentQuestionIndex:h}){const P=r(()=>u.questions.map((e,r)=>({...e,partName:u.name||`Part ${e.part_no}`,questionIndex:r})),[u.questions,u.name]),I=a({questions:P,initialIndex:v});e(()=>{void 0!==h&&h>=0&&h!==I.currentIndex&&I.goTo(h)},[h,I.currentIndex,I]);const N=I.currentQuestion,{attemptId:G}=s(),f=N?d[N.id]:void 0,k=!!f,w=c({attemptId:G??"",questionId:N?.id??"",maxDurationMs:x,existingAnswerKey:g?f:void 0,onRecordingComplete:(e,r)=>{const t=r||N?.id;t&&m(t,e)},onError:e=>i.error(e)});e(()=>{g&&w.isAttemptExpired&&i.error("Bài thi đã hết giờ hoặc đã được nộp.")},[g,w.isAttemptExpired]);const A=g&&"recording"===w.status,T=n(A),q=n(null),[Q,R]=o(!1);e(()=>{g?(T.current&&!A&&(R(!0),q.current&&clearTimeout(q.current),q.current=setTimeout(()=>{R(!1),q.current=null},500)),A&&q.current&&(clearTimeout(q.current),q.current=null,R(!1)),T.current=A):R(!1)},[g,A]),e(()=>()=>{q.current&&clearTimeout(q.current)},[]);const[S,C]=o(!1),D=t(e=>{C(e)},[]);e(()=>{C(!1)},[N?.id]);const E=A||Q||S,{setIsNavDisabled:b}=s();e(()=>(b(E),()=>b(!1)),[E,b]);const y=t(()=>{E||(I.canGoNext?I.goNext():l?.())},[I,E,l]),B=t(()=>{E||(I.canGoPrev?I.goPrev():p?.())},[I,E,p]),M=r(()=>({...I,showPrev:I.canGoPrev||!!p,showNext:I.canGoNext||!!l,canGoPrev:!E&&(I.canGoPrev||!!p),canGoNext:!E&&(I.canGoNext||!!l)}),[I,E,p,l]),K=!(!f||g&&"idle"!==w.status);return{nav:M,recorder:g?w:null,currentQuestion:N,handleNext:y,handlePrev:B,showExistingBadge:K,isRecordingInProgress:A,isQuestionLocked:k,isPostRecordingDelayActive:Q,onAudioPlayingChange:D}}

package/dist/components/exams/take/hooks/useToeicAudio.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook to manage TOEIC audio playback state across questions
+ *
+ * Features:
+ * - Track current audio URL for the part
+ * - Pause audio when switching questions
+ * - Reset audio state when part changes
+ * - Provide audio loading state
+ */
+export declare function useToeicAudio(): {
+    currentAudioUrl: string;
+    isPlayingPartAudio: boolean;
+    isAudioLoading: boolean;
+    setPartAudio: (audioUrl: string | null) => void;
+    setAudioLoading: (loading: boolean) => void;
+    setAudioPlaying: (playing: boolean) => void;
+};

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

@@ -0,0 +1 @@
+import{useState as i,useCallback as o}from"react";export function useToeicAudio(){const[t,u]=i(null),[r,n]=i(!1),[d,e]=i(!1);return{currentAudioUrl:t,isPlayingPartAudio:r,isAudioLoading:d,setPartAudio:o(i=>{u(i),n(!1),e(!1)},[]),setAudioLoading:o(i=>{e(i)},[]),setAudioPlaying:o(i=>{n(i)},[])}}

package/dist/components/exams/take/index.d.ts

@@ -3,4 +3,12 @@ export type { ExamTakingPageContainerProps } from './ExamTakingPageContainer';
 export { GenericQuestionRenderer } from './GenericQuestionRenderer';
 export type { GenericQuestionRendererProps } from './GenericQuestionRenderer';
 export type { ExamTakingPart } from './exam-taking.utils';
-export type { ExamTakingAnswerValue, ExamTakingAttempt, ExamTakingQuestion, ExamTakingQuestionsResult, ExamTakingSdkApi, ExamTakingTemplatePart, SaveExamTakingAnswersInput } from './types';
+export type { ExamTakingAnswerValue, ExamTakingAttempt, ExamTakingQuestion, ExamTakingQuestionsResult, ExamTakingSdkApi, ExamTakingTemplatePart, SaveExamTakingAnswersInput } from '../../../api/exam-taking';
+export { useExamCountdown } from './hooks/useExamCountdown';
+export type { UseExamCountdownOptions, UseExamCountdownResult } from './hooks/useExamCountdown';
+export { useAnswerAutosave } from './hooks/useAnswerAutosave';
+export type { UseAnswerAutosaveOptions, UseAnswerAutosaveResult } from './hooks/useAnswerAutosave';
+export { useProctoringSnapshot } from './hooks/useProctoringSnapshot';
+export type { UseProctoringSnapshotOptions, UseProctoringSnapshotResult } from './hooks/useProctoringSnapshot';
+export { useAttemptSubmit } from './hooks/useAttemptSubmit';
+export type { UseAttemptSubmitOptions, UseAttemptSubmitResult, SubmittedSummary } from './hooks/useAttemptSubmit';

package/dist/components/exams/take/index.js

@@ -1 +1 @@
-export{ExamTakingPageContainer}from"./ExamTakingPageContainer";export{GenericQuestionRenderer}from"./GenericQuestionRenderer";
+export{ExamTakingPageContainer}from"./ExamTakingPageContainer";export{GenericQuestionRenderer}from"./GenericQuestionRenderer";export{useExamCountdown}from"./hooks/useExamCountdown";export{useAnswerAutosave}from"./hooks/useAnswerAutosave";export{useProctoringSnapshot}from"./hooks/useProctoringSnapshot";export{useAttemptSubmit}from"./hooks/useAttemptSubmit";

package/dist/components/exams/take/types/speaking-cue-card.types.d.ts

@@ -0,0 +1,10 @@
+export interface SpeakingCueCardContent {
+    /** Rich text HTML content of the cue card — generated by Tiptap Editor */
+    cueCardHtml: string;
+    /** Preparation time in seconds (default: 60) */
+    prepTimeSeconds?: number;
+    /** Max speaking time in seconds (default: 120) */
+    speakingTimeSeconds?: number;
+    /** Backup question flag */
+    isBackup?: boolean;
+}

package/dist/components/exams/take/types/speaking-cue-card.types.js

@@ -0,0 +1 @@
+export{};