@tinyweb_dev/oe-exam-sdk 0.1.28 → 0.1.30

package/dist/components/exams/take/utils/question-transformers.js

@@ -1 +1,1137 @@
-export function groupQuestionsByPart(t,e){const n=new Map,o=new Map;for(const e of t){const t=o.get(e.part_id)||[];t.push(e),o.set(e.part_id,t)}for(const[t,r]of o.entries()){const o=[...r].sort((t,e)=>t.question_number-e.question_number),i=o[0];if(!i)continue;const s=e?.find(e=>String(e.id)===String(t)),a=void 0!==s?.id?Number(s.id):void 0,u=s?.name?.match(/\d+/),c=u?parseInt(u[0],10):i.part_no,l=s?.group,m=Boolean(s?.isGroup)&&"DOCUMENT"===l?.type,p=s?.sections??[],d=new Set(p.map(t=>t.questionType).filter(Boolean)),g=p.length>1&&d.size>1;if(m||g){const e=`${t}_part`;n.set(e,{partId:t,partNo:c,questionType:i.question_type,questions:o,name:s?.name,instructions:s?.instructions,audioUrl:s?.audioUrl,templateOrder:a,category:s?.category,points:s?.points,isGroup:!0,group:l,sections:s?.sections,startIndex:s?.startIndex,endIndex:s?.endIndex});continue}if(!s?.sections?.length){const e=`${t}_part`;n.set(e,{partId:t,partNo:c,questionType:i.question_type,questions:o,name:s?.name,instructions:s?.instructions,audioUrl:s?.audioUrl,templateOrder:a,category:s?.category,points:s?.points,isGroup:s?.isGroup,optionMode:s?.optionMode,optionCount:s?.optionCount,viewMode:s?.viewMode,defaultValue:s?.defaultValue,multipleAnswers:s?.multipleAnswers,questionConfig:s?.questionConfig,wordBankConfig:s?.wordBankConfig,group:s?.group,startIndex:s?.startIndex,endIndex:s?.endIndex});continue}for(const[e,r]of s.sections.entries()){const i=o.filter(t=>{const e=t.question_number-1;return e>=r.startIndex&&e<=r.endIndex});if(!i.length)continue;const u=`${t}_section_${e}`,l=Boolean(r.isGroup||r.group?.type);n.set(u,{partId:t,partNo:c,questionType:r.questionType||i[0].question_type,questions:i,name:s.name,instructions:r.instructions||r.name||s.instructions,audioUrl:s.audioUrl,templateOrder:a,category:s.category,points:s.points,sectionId:r.sectionId,isGroup:l,optionMode:r.optionMode,optionCount:r.optionCount,viewMode:r.viewMode,defaultValue:r.defaultValue,multipleAnswers:r.multipleAnswers,questionConfig:r.questionConfig,wordBankConfig:r.wordBankConfig,group:r.group,startIndex:r.startIndex,endIndex:r.endIndex})}}return Array.from(n.values()).sort((t,e)=>{const n=void 0===t.templateOrder||isNaN(t.templateOrder)?1/0:t.templateOrder,o=void 0===e.templateOrder||isNaN(e.templateOrder)?1/0:e.templateOrder;return n!==o?n-o:(t.questions[0]?.question_number||0)-(e.questions[0]?.question_number||0)})}export function transformFillInBlank(t){const e=t[0],n=e?.content,o=e?.questionGroup?.payload,r=[];for(const e of t){const t=e.content,n=e.is_example||!1,o=t.question||t.blanks?.[0]?.text||"";if([...o.matchAll(/\{(\d+)\}/g)].length>1){const i=o.split("\n").filter(t=>t.trim());for(const o of i){const i=o.match(/\{(\d+)\}/);if(!i)continue;const s=parseInt(i[1],10),a=o.split(/\{\d+\}/),u=a[0]?.trim()||"",c=a[1]?.trim()||"";r.push({id:`${e.id}-blank-${s}`,questionNumber:e.question_number,textBefore:u,textAfter:c,imageUrl:t.imageUrl,hints:t.hints,isExample:n,correctAnswer:n?e.correct_answer?.answers?.[s]:void 0})}}else{const i=o.match(/^([\s\S]*?)\{0\}([\s\S]*)$/),s=i?i[1].trim():o,a=i?i[2].trim():"";r.push({id:e.id,questionNumber:e.question_number,textBefore:s,textAfter:a,imageUrl:t.imageUrl,hints:t.hints,isExample:n,correctAnswer:n?e.correct_answer?.answers?.[0]:void 0})}}return{questions:r,title:n?.title||o?.title||"",imageUrl:o?n?.imageUrl:void 0,audioUrl:n?.audioUrl,exampleText:n?.exampleText,exampleHighlight:n?.exampleHighlight,instruction:n?.instruction||"LISTEN AND WRITE",showHints:n?.showHints,groupContent:o?.content||o?.groupContent,groupTitle:o?.title,groupImageUrl:o?.mainImageUrl||o?.imageUrl}}export function transformWriteCorrectVerbForm(t){const e=t[0],n=e?.content;return{questions:t.map(t=>{const e=t.content,n=e.sentence||"",o=n.match(/^([\s\S]*?)\{0\}([\s\S]*)$/),r=o?o[1].trim():n,i=o?o[2].trim():"";return{id:t.id,questionNumber:t.question_number,textBefore:r,textAfter:i,verbHint:e.verbHint}}),title:"WRITE THE CORRECT VERB FORM",instruction:n?.instruction||"Write the correct form of the verb in parentheses."}}const t=["A","B","C","D","E","F"];export function transformChooseCorrectAnswer(e){const n=e[0]?.content,o=e[0]?.questionGroup?.payload,r=e.find(t=>t.is_example),i=e.filter(t=>!t.is_example);let s;if(r){const e=r.content,n=(e.options||[]).map((e,n)=>{const o="object"==typeof e&&null!==e,i=o&&e.id?String(e.id):`${r.id}-opt-${n}`,s=o?e.text??e.content??"":String(e),a=o?e.imageUrl:void 0;return{id:i,label:t[n]||String(n+1),text:s,...a?{imageUrl:a}:{}}}),o=r.correct_answer?.answer??r.correct_answer?.optionId;let i="";if("string"==typeof o&&o){const t=n.find(t=>t.id===o);i=t?t.id:o}else"number"==typeof o&&o>=0&&o<n.length&&(i=n[o]?.id||"");s={questionNumber:r.question_number,questionText:e.question||"",options:n,correctOptionId:i||n[0]?.id||"",optionType:e.optionType||"text",imageUrl:e.imageUrl,audioUrl:e.audioUrl}}const a=i.map(e=>{const n=e.content,o=n.optionType||"text",r=(n.options||[]).map((n,o)=>{const r="object"==typeof n&&null!==n,i=r&&n.id?String(n.id):`${e.id}-opt-${o}`,s=r?n.text??n.content??"":String(n),a=r?n.imageUrl:void 0;return{id:i,label:t[o]||String(o+1),text:s,...a?{imageUrl:a}:{}}}),i=e.correct_answer?.answer??e.correct_answer?.optionId??e.correct_answer?.optionIds,s=t=>{if(null==t)return;const e=String(t),n=r.find(t=>t.id===e);if(n)return n.id;const o=e.match(/-opt-(\d+)$/);if(o){const t=parseInt(o[1],10);if(t>=0&&t<r.length)return r[t]?.id}if("number"==typeof t&&t>=0&&t<r.length)return r[t]?.id;const i=parseInt(e,10);return!isNaN(i)&&i>=0&&i<r.length&&!e.startsWith("opt-")?r[i]?.id:e};let a=[];if(Array.isArray(i))a=i.map(s).filter(t=>Boolean(t));else{const t=s(i);t&&(a=[t])}return{id:e.id,questionNumber:e.question_number,questionText:n.question||"",options:r,correctOptionId:a[0],correctOptionIds:a,imageUrl:n.imageUrl,audioUrl:n.audioUrl,optionType:o,multipleAnswers:Boolean(n.multipleAnswers||Array.isArray(i)),explanation:e.explanation}}),u=a.some(t=>!!t.audioUrl?.trim())||!!s?.audioUrl?.trim();return{questions:a,example:s,imageUrl:n?.imageUrl,groupImageUrl:o?.mainImageUrl||o?.imageUrl,groupTitle:o?.title,groupContent:o?.content,articles:o?.articles,audioUrl:u?void 0:n?.audioUrl,instruction:n?.instruction||"CHOOSE THE CORRECT ANSWER"}}export function transformChooseTheCorrectAnswerGroup(e){const n=e[0],o=n?.content,r=Array.isArray(o?.items)?o.items:[],i=Array.isArray(n?.correct_answer?.answer)?n.correct_answer.answer:[],s=r.find(t=>t.isExample),a=r.filter(t=>!t.isExample),u=(e,n)=>(e||[]).map((e,o)=>{const r="object"==typeof e&&null!==e;return{id:r&&e.id?String(e.id):`${n}-opt-${o+1}`,label:t[o]||String(o+1),text:String(r?e.text??"":e),...r&&e.imageUrl?{imageUrl:e.imageUrl}:{}}});let c;if(s){const t=r.indexOf(s),e=u(s.content?.options,`${n.id}-ex`),o=s.correctAnswer?.answer||i[t]||e[0]?.id||"";c={questionNumber:s.questionNumber||t+1,questionText:s.content?.question||"",options:e,correctOptionId:o,optionType:s.content?.optionType||"text"}}return{questions:a.map(t=>{const e=r.indexOf(t),o=u(t.content?.options,`${n.id}-item-${e}`),s=t.correctAnswer?.answer||i[e]||"";return{id:`${n.id}-item-${e}`,questionNumber:t.questionNumber||e+1,questionText:t.content?.question||"",options:o,correctOptionId:s,correctOptionIds:s?[s]:[],optionType:t.content?.optionType||"text"}}),example:c,instruction:o?.meta?.instruction||"Choose the correct answer."}}export function transformChooseCorrectAdjective(e){return{questions:e.map(e=>{const n=e.content,o=n.sentence||"",r=o.match(/^([\s\S]*?)\{0\}([\s\S]*)$/),i=r?r[1]:o,s=r?r[2]:"";return{id:e.id,questionNumber:e.question_number,sentenceBefore:i,sentenceAfter:s,options:(n.options||[]).map((n,o)=>({id:`${e.id}-opt-${o}`,label:t[o]||String(o+1),text:n}))}}),instruction:"CHOOSE THE CORRECT ADJECTIVE"}}export function transformWriteShortLetter(t){const e=t.content;if(e.instructions?.mainInstruction||e.informations?.length)return{prompt:e.instructions?.mainInstruction||"",requirements:e.informations,minWords:e.minWords,maxWords:e.maxWords,guideImages:e.guideImages};return{prompt:e.contexts?.filter(t=>"text"===t.type).map(t=>t.text).join("\n")||"",minWords:e.minWords,maxWords:e.maxWords,guideImages:e.guideImages}}export function transformColorObjects(t){const e=t[0],n=e?.content,o=n?.colorNodes?.map(t=>({id:t.id,color:t.color,label:t.label}))||n?.hintItems||[],r=n?.regionNodes?.map(t=>({id:t.id,x:t.x,y:t.y,width:t.width,height:t.height,correctHintId:t.linkedColorNodeId}))||n?.regions||[],i=n?.instructions;return{instruction:(i&&i.length>0?i.join(" "):n?.instruction)||"READ AND COLOR THE OBJECTS",instructions:i,imageUrl:n?.backgroundImageUrl||n?.imageUrl||"",audioUrl:n?.audioUrl,hintItems:o,regions:r}}export function transformPictureChoose(e){const n=e[0]?.content;return{subQuestions:e.map(e=>{const n=e.content;return{id:e.id,questionNumber:e.question_number,imageUrl:n.imageUrl||"",questionText:n.questionText,options:(n.options||[]).map((n,o)=>({id:n.id||`${e.id}-opt-${o}`,label:t[o]||String(o+1),text:"string"==typeof n?n:n.text}))}}),instruction:n?.instruction||"LOOK AT THE PICTURE AND CHOOSE THE CORRECT ANSWER"}}export function transformPictureFillBlankChoose(e){const n=e[0]?.content;return{subQuestions:e.map(e=>{const n=e.content;return{id:e.id,questionNumber:e.question_number,imageUrl:n.imageUrl||"",question:n.question||"",options:(n.options||[]).map((n,o)=>({id:n.id||`${e.id}-opt-${o}`,label:t[o]||String(o+1),text:"string"==typeof n?n:n.text}))}}),instruction:n?.instruction||"LOOK AT THE PICTURE, FILL IN THE BLANK AND CHOOSE THE ANSWER"}}export function transformReadingPassage(e){if(function(t){const e=t[0];if(!e)return!1;const n=e.content;return void 0!==n?.question&&!n?.questions&&void 0!==e.questionGroup?.payload?.passage}(e)){const n=e[0],o=n.questionGroup?.payload||{},r=e.map(e=>{const n=e.content;return{id:e.id,questionNumber:e.question_number,questionText:n?.question||"",options:(n?.options||[]).map((n,o)=>({id:`${e.id}-opt-${o}`,label:t[o]||String(o+1),text:"string"==typeof n?n:String(n)}))}});return{passage:o.passage||"",passageTitle:o.passageTitle,passageImageUrl:o.passageImageUrl||o.mainImageUrl,instruction:o.instructions||"READ THE PASSAGE AND ANSWER QUESTIONS",questions:r}}const n=e[0],o=n?.content,r=o?.questions?.map((e,o)=>({id:e.id||`${n.id}-sq-${o}`,questionNumber:o+1,questionText:e.question,options:(e.options||[]).map((o,r)=>({id:`${e.id||n.id}-opt-${r}`,label:t[r]||String(r+1),text:o}))}))||[];return{passage:o?.passage||"",passageTitle:o?.passageTitle,passageImageUrl:o?.passageImageUrl||o?.mainImageUrl,instruction:o?.instructions?.mainInstruction||"READ THE PASSAGE AND ANSWER QUESTIONS",questions:r}}export function transformLabelPicture(t){const e=t[0],n=e?.content;return{imageUrl:n?.imageUrl||"",wordBank:n?.wordBank||[],labels:n?.labels?.map(t=>({id:t.id,number:t.number,isPreFilled:t.isPreFilled||!1,correctAnswer:t.correctAnswer}))||[],instruction:n?.instruction||"LABEL THE PICTURE"}}function e(t){return t&&"string"==typeof t.word&&!t.subQuestions}export function transformFillWordHint(t){const n=t[0],o=n?.content;if(t.length>1&&t.every(t=>e(t.content))){const e=n.questionGroup?.payload?.hintLetters||[];return{subQuestions:t.map(t=>{const e=t.content,n=e.word.replace(/\{\d+\}/,"_");return{id:t.id,questionNumber:t.question_number,imageUrl:e.imageUrl||"",word:n}}),hintLetters:e,instruction:o?.instruction||"LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER"}}if(e(o)){const t=o,e=n.questionGroup?.payload?.hintLetters||[];return{subQuestions:function(t){const e=[],n=t.split(",").map(t=>t.trim());for(const t of n){let n;const o=/\{(\d+)\}/g;for(;null!==(n=o.exec(t));){const o=parseInt(n[1],10),r=t.replace(n[0],"_");e.push({index:o,displayWord:r})}}return e.sort((t,e)=>t.index-e.index),e}(t.word).map(e=>({id:`${n.id}-blank-${e.index}`,questionNumber:n.question_number,imageUrl:t.imageUrl||"",word:e.displayWord,blankIndex:e.index})),hintLetters:e,instruction:t.instruction||"LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER"}}const r=o;return{subQuestions:r?.subQuestions?.map((t,e)=>({id:t.id,questionNumber:n.question_number+e,imageUrl:t.imageUrl||"",word:t.word||""}))||[],hintLetters:r?.hintLetters||n.questionGroup?.payload?.hintLetters||[],instruction:r?.instruction||"LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER"}}export function transformGridFill(t){const e=t[0],n=e?.content;return{grid:n?.grid||[],rows:n?.rows||0,columns:n?.columns||0,instruction:n?.instruction||"FILL IN THE MISSING WORDS",disabledCells:n?.disabledCells||[]}}export function transformAnswerTheQuestion(t){const e=t[0],n=e?.questionGroup?.payload,o=e?.content;return{questions:t.map(t=>{const e=t.content,n=t.is_example||e.isExample||!1;return{id:t.id,questionNumber:t.question_number,question:(e.question||"").replace(/\{\d+\}/g,"______"),imageUrl:e.imageUrl,prefixText:e.prefixText,suffixText:e.suffixText,suggestedAnswers:e.suggestedAnswers,isExample:n,exampleAnswer:n?t.correct_answer?.answer:void 0}}),instruction:"ANSWER THE QUESTION",imageUrl:n?.mainImageUrl||n?.imageUrl||o?.imageUrl,title:o?.title,groupContent:n?.groupContent||o?.groupContent}}export function transformTrueFalse(t){const e=t[0]?.questionGroup?.payload;return{questions:t.map(t=>{const e=t.content,n=t.is_example||e.isExample||!1,o=n&&"boolean"==typeof t.correct_answer?.answer?t.correct_answer.answer:void 0;return{id:t.id,questionNumber:t.question_number,question:e.question||"",imageUrl:e.imageUrl,isExample:n,exampleCorrectAnswer:o}}),instruction:"READ AND CHOOSE TRUE OR FALSE",imageUrl:e?.mainImageUrl||e?.imageUrl,groupContent:e?.content||e?.groupContent}}export function transformWordOrdering(t){return{questions:t.map(t=>{const e=t.content,n=t.is_example||e.isExample||!1,o=Array.isArray(t.correct_answer?.answer)?t.correct_answer.answer:Array.isArray(e.answer)?e.answer:void 0;return{id:t.id,questionNumber:t.question_number,words:e.words||[],imageUrl:e.imageUrl,isExample:n,exampleAnswer:n?o:void 0}}),instruction:"ARRANGE THE LETTERS TO MAKE A WORD"}}export function transformWordFillParagraph(t){const e=t[0],n=e?.questionGroup?.payload,o=e?.content,r=o?.title||n?.title||t.find(t=>t.content?.title)?.content?.title,i=o?.wordBank||[],s=i.map(t=>"string"==typeof t?{word:t}:t),a=o?.viewMode,u=void 0!==o?.wordBank?.[0]?.options;let c;c="EMAIL"===a?"EMAIL":a||!o?.emailFrom&&!o?.emailTo?"DEFAULT"===a?"DEFAULT":"WITH_OPTIONS"===a||u?"WITH_OPTIONS":a||0!==i.length?"WITH_WORD_BANK":"DEFAULT":"EMAIL";const l=o?.emailFrom||o?.metadata?.emailFrom,m=o?.emailTo||o?.metadata?.emailTo;return{questionId:e?.id||"",paragraph:o?.paragraph||"",title:r,imageUrl:o?.imageUrl,wordBank:s,viewMode:c,instruction:"READ AND FILL IN THE BLANKS",exampleAnswer:o?.exampleAnswer,emailFrom:l,emailTo:m}}export function transformMatchByWritingAnswer(t){const e=t[0]?.questionGroup?.payload,n=t.some(t=>!!t.content?.askerName),o=t.map(t=>{const e=t.content,n=t.is_example||e.isExample||!1;return{id:t.id,questionNumber:t.question_number,question:e.question||"",imageUrl:e.imageUrl,isExample:n,exampleAnswer:n?t.correct_answer?.answer:void 0,askerName:e.askerName,answererName:e.answererName}}),r=e?.options?.map(t=>({answer:t.answer,imageUrl:t.imageUrl||"",content:t.content||""}))||[],i=n?t[0]?.content:void 0;return{questions:o,options:r,instruction:"LOOK AND WRITE THE ANSWER",viewMode:n?"CONVERSATION":"DEFAULT",groupImageUrl:e?.groupImageUrl||"",askerName:i?.askerName,answererName:i?.answererName}}export function transformWriteSentences(t){const e=t[0],n=e?.content,o=e?.questionGroup?.payload;return{questions:t.map(t=>({id:t.id,questionNumber:t.question_number})),instruction:n?.instruction||"WRITE SENTENCES ABOUT THE PICTURE",imageUrl:o?.mainImageUrl||o?.imageUrl||n?.imageUrl,title:n?.title,groupContent:o?.groupContent||n?.groupContent}}export function transformWordFillStructuredForm(t){const e=t[0],n=e?.questionGroup?.payload;return{questions:t.map(t=>{const e=t.content,n=t.correct_answer||{};let o=e?.content||"";const r=e?.blocks;return!o&&r?.length&&(o=r.map(t=>(t.heading?`<h3>${t.heading}</h3>`:"")+(t.content||"")).join("")),{id:t.id,questionNumber:t.question_number,title:e?.title||"",imageUrl:e?.imageUrl,content:o,answers:n?.answers||{},caseSensitive:n?.caseSensitive??e?.caseSensitive??!1}}),instruction:n?.instructions||"COMPLETE THE FORM BELOW",groupTitle:n?.title,groupContent:n?.content,groupImageUrl:n?.imageUrl,audioUrl:e?.audio_url||n?.audioUrl}}export function transformListenChooseObjects(t){const e=t[0],n=e?.content,o=e?.questionGroup?.payload||{};return{audioUrl:n?.audioUrl||"",backgroundImageUrl:o.backgroundImageUrl||"",objectNodes:o.objectNodes||[],correctObjectId:e?.correctAnswer?.objectId||e?.correct_answer?.objectId||"",isBackup:n?.isBackup||!1,instruction:"LISTEN AND CHOOSE THE CORRECT OBJECT"}}export function transformListenSpeakAnswer(t){return{questions:t.map(t=>{const e=t.content,n=t.questionGroup?.payload||{};return{id:t.id,questionNumber:t.question_number,audioUrl:e?.audioUrl||"",arrowNode:e?.arrowNode,backgroundImageUrl:n.backgroundImageUrl||n.imageUrl||"",isBackup:e?.isBackup||!1}}),instruction:"LISTEN AND SPEAK YOUR ANSWER"}}
+/**
+ * Question Transformers - Transform API response to renderer props
+ *
+ * Maps backend question types to frontend renderer props.
+ * Each transformer handles specific question type data structure.
+ */
+/**
+ * Group questions by part_id AND questionGroup.id
+ * This ensures questions with different passages (different questionGroups)
+ * within the same part are properly separated.
+ *
+ * Handles template sections: parts with `sections` array are split into
+ * multiple QuestionPart entries with section-specific questionTypes.
+ * Used for Movers P8 (2 sections) and P11 (3 sections).
+ *
+ * @param questions - API questions to group
+ * @param templateParts - Optional template parts with name/instructions metadata
+ */
+export function groupQuestionsByPart(questions, templateParts) {
+    const partMap = new Map();
+    const questionsByPart = new Map();
+    for (const q of questions) {
+        const existing = questionsByPart.get(q.part_id) || [];
+        existing.push(q);
+        questionsByPart.set(q.part_id, existing);
+    }
+    for (const [partId, partQuestions] of questionsByPart.entries()) {
+        const sortedPartQuestions = [...partQuestions].sort((a, b) => a.question_number - b.question_number);
+        const firstQuestion = sortedPartQuestions[0];
+        if (!firstQuestion)
+            continue;
+        // Find template part to get name/instructions metadata
+        const templatePart = templateParts?.find((tp) => String(tp.id) === String(partId));
+        const templateOrder = templatePart?.id !== undefined ? Number(templatePart.id) : undefined;
+        // Extract partNo from template name (e.g. "Part 8") or fallback to question's part_no
+        const partNameMatch = templatePart?.name?.match(/\d+/);
+        const parsedPartNo = partNameMatch ? parseInt(partNameMatch[0], 10) : firstQuestion.part_no;
+        // IELTS Reading: a part carries a part-level DOCUMENT group (the shared
+        // passage) AND sections with mixed sub-types. Render it like TOEIC Part 7 —
+        // a single screen with the passage on the left and ALL questions on the
+        // right — so keep it whole and pass the sections through for the renderer.
+        const partLevelGroup = templatePart?.group;
+        const hasDocumentGroup = Boolean(templatePart?.isGroup) && partLevelGroup?.type === 'DOCUMENT';
+        // Mixed multi-section part (e.g. Listening SECTION 2: CHOOSE + MATCH +
+        // WORD_FILL): keep it whole and pass the sections through so the grouped
+        // renderer can stack each sub-section on one screen. Without this the part
+        // would be split into one screen per section and only the first sub-section
+        // would be reachable.
+        const templateSections = (templatePart?.sections ?? []);
+        const distinctSectionTypes = new Set(templateSections.map((s) => s.questionType).filter(Boolean));
+        const isMixedMultiSection = templateSections.length > 1 && distinctSectionTypes.size > 1;
+        if (hasDocumentGroup || isMixedMultiSection) {
+            const key = `${partId}_part`;
+            partMap.set(key, {
+                partId,
+                partNo: parsedPartNo,
+                questionType: firstQuestion.question_type,
+                questions: sortedPartQuestions,
+                name: templatePart?.name,
+                instructions: templatePart?.instructions,
+                audioUrl: templatePart?.audioUrl,
+                templateOrder,
+                category: templatePart?.category,
+                points: templatePart?.points,
+                isGroup: true,
+                group: partLevelGroup,
+                sections: templatePart?.sections,
+                startIndex: templatePart?.startIndex,
+                endIndex: templatePart?.endIndex,
+            });
+            continue;
+        }
+        // Parts without sections should render as exactly one screen per part
+        if (!templatePart?.sections?.length) {
+            const key = `${partId}_part`;
+            partMap.set(key, {
+                partId,
+                partNo: parsedPartNo,
+                questionType: firstQuestion.question_type,
+                questions: sortedPartQuestions,
+                name: templatePart?.name,
+                instructions: templatePart?.instructions,
+                audioUrl: templatePart?.audioUrl,
+                templateOrder,
+                category: templatePart?.category,
+                points: templatePart?.points,
+                isGroup: templatePart?.isGroup,
+                optionMode: templatePart?.optionMode,
+                optionCount: templatePart?.optionCount,
+                viewMode: templatePart?.viewMode,
+                defaultValue: templatePart?.defaultValue,
+                multipleAnswers: templatePart?.multipleAnswers,
+                questionConfig: templatePart?.questionConfig,
+                wordBankConfig: templatePart?.wordBankConfig,
+                group: templatePart?.group,
+                startIndex: templatePart?.startIndex,
+                endIndex: templatePart?.endIndex,
+            });
+            continue;
+        }
+        // Parts with sections should render as exactly one screen per section.
+        // Template startIndex/endIndex are stored as zero-based exam-order positions,
+        // while API question_number is one-based. Convert question_number → zero-based
+        // position before matching, otherwise mixed-section parts (e.g. IELTS Part 3)
+        // can render the wrong heading and only a tail subset of questions.
+        for (const [sectionIdx, section] of templatePart.sections.entries()) {
+            const sectionQuestions = sortedPartQuestions.filter((question) => {
+                const templatePosition = question.question_number - 1;
+                return templatePosition >= section.startIndex && templatePosition <= section.endIndex;
+            });
+            if (!sectionQuestions.length)
+                continue;
+            const key = `${partId}_section_${sectionIdx}`;
+            // A section is a grouped question when the template marks it isGroup OR it
+            // carries a nested group payload (e.g. IELTS SECTION 2 DOCUMENT/MATCH_ANSWER).
+            const sectionIsGroup = Boolean(section.isGroup || section.group?.type);
+            partMap.set(key, {
+                partId,
+                partNo: parsedPartNo,
+                questionType: section.questionType || sectionQuestions[0].question_type,
+                questions: sectionQuestions,
+                name: templatePart.name,
+                instructions: section.instructions || section.name || templatePart.instructions,
+                audioUrl: templatePart.audioUrl,
+                templateOrder,
+                category: templatePart.category,
+                points: templatePart.points,
+                sectionId: section.sectionId,
+                isGroup: sectionIsGroup,
+                optionMode: section.optionMode,
+                optionCount: section.optionCount,
+                viewMode: section.viewMode,
+                defaultValue: section.defaultValue,
+                multipleAnswers: section.multipleAnswers,
+                questionConfig: section.questionConfig,
+                wordBankConfig: section.wordBankConfig,
+                group: section.group,
+                startIndex: section.startIndex,
+                endIndex: section.endIndex,
+            });
+        }
+    }
+    // Sort by templateOrder, then by question_number of first question in group
+    return Array.from(partMap.values()).sort((a, b) => {
+        const orderA = a.templateOrder !== undefined && !isNaN(a.templateOrder) ? a.templateOrder : Infinity;
+        const orderB = b.templateOrder !== undefined && !isNaN(b.templateOrder) ? b.templateOrder : Infinity;
+        if (orderA !== orderB)
+            return orderA - orderB;
+        return (a.questions[0]?.question_number || 0) - (b.questions[0]?.question_number || 0);
+    });
+}
+export function transformFillInBlank(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    const groupPayload = firstQuestion?.questionGroup?.payload;
+    const transformed = [];
+    /** Take UI shows plain textBefore/textAfter — strip `**` so markers never leak. */
+    const stripStemBoldMarkers = (s) => s.replace(/\*\*/g, '');
+    for (const q of questions) {
+        const qContent = q.content;
+        const isExample = q.is_example || false;
+        // Support both: content.question (new) and content.blanks[0].text (legacy)
+        const text = qContent.question || qContent.blanks?.[0]?.text || '';
+        // Check for multiple placeholders: {0}, {1}, etc.
+        const placeholderMatches = [...text.matchAll(/\{(\d+)\}/g)];
+        if (placeholderMatches.length > 1) {
+            // Multi-placeholder: split into separate lines by newline or by placeholder
+            const lines = text.split('\n').filter((l) => l.trim());
+            for (const line of lines) {
+                const lineMatch = line.match(/\{(\d+)\}/);
+                if (!lineMatch)
+                    continue;
+                const blankIndex = parseInt(lineMatch[1], 10);
+                const parts = line.split(/\{\d+\}/);
+                const textBefore = stripStemBoldMarkers(parts[0]?.trim() || '');
+                const textAfter = stripStemBoldMarkers(parts[1]?.trim() || '');
+                transformed.push({
+                    id: `${q.id}-blank-${blankIndex}`,
+                    questionNumber: q.question_number,
+                    textBefore,
+                    textAfter,
+                    imageUrl: qContent.imageUrl,
+                    hints: qContent.hints,
+                    isExample,
+                    correctAnswer: isExample ? q.correct_answer?.answers?.[blankIndex] : undefined,
+                });
+            }
+        }
+        else {
+            // Single placeholder or no placeholder.
+            // Use [\s\S] so stems with newlines still match (`.` does not cross `\n`).
+            const match = text.match(/^([\s\S]*?)\{0\}([\s\S]*)$/);
+            const textBefore = stripStemBoldMarkers(match ? match[1].trim() : text);
+            const textAfter = stripStemBoldMarkers(match ? match[2].trim() : '');
+            transformed.push({
+                id: q.id,
+                questionNumber: q.question_number,
+                textBefore,
+                textAfter,
+                imageUrl: qContent.imageUrl,
+                hints: qContent.hints,
+                isExample,
+                correctAnswer: isExample ? q.correct_answer?.answers?.[0] : undefined,
+            });
+        }
+    }
+    return {
+        questions: transformed,
+        // No hardcoded fallback: the part instruction banner already states the task,
+        // so an extra "FILL IN THE BLANK" heading is redundant.
+        title: content?.title || groupPayload?.title || '',
+        // Shared header image: only meaningful for grouped parts (legacy data had the group
+        // payload merged into content). For non-grouped parts each question renders its own
+        // content.imageUrl below, so lifting the first one here would duplicate it.
+        imageUrl: groupPayload ? content?.imageUrl : undefined,
+        audioUrl: content?.audioUrl,
+        exampleText: content?.exampleText,
+        exampleHighlight: content?.exampleHighlight,
+        instruction: content?.instruction || 'LISTEN AND WRITE',
+        showHints: content?.showHints,
+        groupContent: groupPayload?.content || groupPayload?.groupContent,
+        groupTitle: groupPayload?.title,
+        groupImageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl,
+    };
+}
+export function transformWriteCorrectVerbForm(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    const transformed = questions.map((q) => {
+        const qContent = q.content;
+        const sentence = qContent.sentence || '';
+        // Parse "John {0} his homework." -> textBefore: "John", textAfter: "his homework."
+        // [\s\S] allows instruction text with newlines before the blank.
+        const match = sentence.match(/^([\s\S]*?)\{0\}([\s\S]*)$/);
+        const textBefore = match ? match[1].trim() : sentence;
+        const textAfter = match ? match[2].trim() : '';
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            textBefore,
+            textAfter,
+            verbHint: qContent.verbHint, // Pass verbHint per question
+        };
+    });
+    return {
+        questions: transformed,
+        title: 'WRITE THE CORRECT VERB FORM',
+        instruction: content?.instruction ||
+            'Write the correct form of the verb in parentheses.',
+    };
+}
+// ============================================
+// Deterministic Shuffle Utility
+// ============================================
+/**
+ * Simple hash function to create a numeric seed from a string.
+ * Used for deterministic (repeatable) shuffling based on questionId.
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash |= 0; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+}
+/**
+ * Fisher-Yates shuffle with a deterministic seed.
+ * Same seed always produces the same shuffled order.
+ * Uses a Linear Congruential Generator (LCG) for pseudo-random numbers.
+ */
+function seededShuffle(array, seed) {
+    const shuffled = [...array];
+    let currentSeed = simpleHash(seed);
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        currentSeed = (currentSeed * 1664525 + 1013904223) & 0x7fffffff; // LCG
+        const j = currentSeed % (i + 1);
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+}
+const OPTION_LABELS = ['A', 'B', 'C', 'D', 'E', 'F'];
+export function transformChooseCorrectAnswer(questions, optionsConfig) {
+    const shouldShuffleOptions = optionsConfig?.shuffleOptions ?? true;
+    const firstContent = questions[0]?.content;
+    const groupPayload = questions[0]?.questionGroup?.payload;
+    // Separate example from regular questions
+    const exampleQuestion = questions.find((q) => q.is_example);
+    const regularQuestions = questions.filter((q) => !q.is_example);
+    // Build example object if an example question exists
+    let example;
+    if (exampleQuestion) {
+        const exContent = exampleQuestion.content;
+        const exOptions = (exContent.options || []).map((opt, idx) => {
+            const isObj = typeof opt === 'object' && opt !== null;
+            const optId = isObj && opt.id ? String(opt.id) : `${exampleQuestion.id}-opt-${idx}`;
+            const optText = isObj ? (opt.text ?? opt.content ?? '') : String(opt);
+            const optImage = isObj ? opt.imageUrl : undefined;
+            return {
+                id: optId,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+                text: optText,
+                ...(optImage ? { imageUrl: optImage } : {}),
+            };
+        });
+        const exRawAns = exampleQuestion.correct_answer?.answer ?? exampleQuestion.correct_answer?.optionId;
+        let exCorrectId = '';
+        if (typeof exRawAns === 'string' && exRawAns) {
+            const match = exOptions.find((o) => o.id === exRawAns);
+            exCorrectId = match ? match.id : exRawAns;
+        }
+        else if (typeof exRawAns === 'number' && exRawAns >= 0 && exRawAns < exOptions.length) {
+            exCorrectId = exOptions[exRawAns]?.id || '';
+        }
+        example = {
+            questionNumber: exampleQuestion.question_number,
+            questionText: exContent.question || '',
+            options: exOptions,
+            correctOptionId: exCorrectId || exOptions[0]?.id || '',
+            optionType: (exContent.optionType || 'text'),
+            imageUrl: exContent.imageUrl,
+            audioUrl: exContent.audioUrl,
+        };
+    }
+    const transformed = regularQuestions.map((q) => {
+        const content = q.content;
+        const optionType = content.optionType || 'text';
+        const options = (content.options || []).map((opt, idx) => {
+            const isObj = typeof opt === 'object' && opt !== null;
+            const optId = isObj && opt.id ? String(opt.id) : `${q.id}-opt-${idx}`;
+            const optText = isObj ? (opt.text ?? opt.content ?? '') : String(opt);
+            const optImage = isObj ? opt.imageUrl : undefined;
+            return {
+                id: optId,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+                text: optText,
+                ...(optImage ? { imageUrl: optImage } : {}),
+            };
+        });
+        const rawAns = q.correct_answer?.answer ?? q.correct_answer?.optionId ?? q.correct_answer?.optionIds;
+        const findOptionId = (val) => {
+            if (val === undefined || val === null)
+                return undefined;
+            const strVal = String(val);
+            const matchedById = options.find((o) => o.id === strVal);
+            if (matchedById)
+                return matchedById.id;
+            // Handle legacy synthetic option IDs like "questionId-opt-0"
+            const optMatch = strVal.match(/-opt-(\d+)$/);
+            if (optMatch) {
+                const optIdx = parseInt(optMatch[1], 10);
+                if (optIdx >= 0 && optIdx < options.length) {
+                    return options[optIdx]?.id;
+                }
+            }
+            if (typeof val === 'number' && val >= 0 && val < options.length) {
+                return options[val]?.id;
+            }
+            const num = parseInt(strVal, 10);
+            if (!isNaN(num) && num >= 0 && num < options.length && !strVal.startsWith('opt-')) {
+                return options[num]?.id;
+            }
+            return strVal;
+        };
+        let correctOptionIds = [];
+        if (Array.isArray(rawAns)) {
+            correctOptionIds = rawAns.map(findOptionId).filter((id) => Boolean(id));
+        }
+        else {
+            const singleId = findOptionId(rawAns);
+            if (singleId)
+                correctOptionIds = [singleId];
+        }
+        // Shuffle options deterministically using questionId as seed when enabled.
+        // Since answers use optionId (not index), shuffling display order is safe.
+        const finalOptions = shouldShuffleOptions
+            ? seededShuffle(options, q.id).map((opt, idx) => ({
+                ...opt,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+            }))
+            : options;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            questionText: content.question || '',
+            options: finalOptions,
+            correctOptionId: correctOptionIds[0],
+            correctOptionIds,
+            imageUrl: content.imageUrl, // Per-question image
+            audioUrl: content.audioUrl, // Per-question audio (questionConfig includes "audio")
+            optionType: optionType,
+            multipleAnswers: Boolean(content.multipleAnswers || Array.isArray(rawAns)),
+            explanation: q.explanation,
+        };
+    });
+    // Each question can carry its own audio (questionConfig "audio"). Only fall back to the
+    // first question's audio as a part-level player when nothing has per-question audio —
+    // otherwise question 1's clip would be lifted to the top and the rest would be lost.
+    const hasPerQuestionAudio = transformed.some((q) => !!q.audioUrl?.trim()) || !!example?.audioUrl?.trim();
+    return {
+        questions: transformed,
+        example,
+        imageUrl: firstContent?.imageUrl,
+        groupImageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl,
+        groupTitle: groupPayload?.title,
+        groupContent: groupPayload?.content,
+        articles: groupPayload?.articles,
+        audioUrl: hasPerQuestionAudio ? undefined : firstContent?.audioUrl,
+        instruction: firstContent?.instruction || 'CHOOSE THE CORRECT ANSWER',
+    };
+}
+export function transformChooseTheCorrectAnswerGroup(questions) {
+    const parent = questions[0];
+    const content = parent?.content;
+    const items = Array.isArray(content?.items) ? content.items : [];
+    const parentCorrect = Array.isArray(parent?.correct_answer?.answer)
+        ? parent.correct_answer.answer
+        : [];
+    const exampleItem = items.find((item) => item.isExample);
+    const regularItems = items.filter((item) => !item.isExample);
+    const mapOptions = (options, prefix) => (options || []).map((opt, idx) => {
+        const isObj = typeof opt === 'object' && opt !== null;
+        return {
+            id: isObj && opt.id ? String(opt.id) : `${prefix}-opt-${idx + 1}`,
+            label: OPTION_LABELS[idx] || String(idx + 1),
+            text: isObj ? String(opt.text ?? '') : String(opt),
+            ...(isObj && opt.imageUrl ? { imageUrl: opt.imageUrl } : {}),
+        };
+    });
+    let example;
+    if (exampleItem) {
+        const exampleIndex = items.indexOf(exampleItem);
+        const exOptions = mapOptions(exampleItem.content?.options, `${parent.id}-ex`);
+        const exCorrect = exampleItem.correctAnswer?.answer || parentCorrect[exampleIndex] || exOptions[0]?.id || '';
+        example = {
+            questionNumber: exampleItem.questionNumber || exampleIndex + 1,
+            questionText: exampleItem.content?.question || '',
+            options: exOptions,
+            correctOptionId: exCorrect,
+            optionType: (exampleItem.content?.optionType || 'text'),
+        };
+    }
+    const transformed = regularItems.map((item) => {
+        const itemIndex = items.indexOf(item);
+        const options = mapOptions(item.content?.options, `${parent.id}-item-${itemIndex}`);
+        const correctId = item.correctAnswer?.answer || parentCorrect[itemIndex] || '';
+        return {
+            id: `${parent.id}-item-${itemIndex}`,
+            questionNumber: item.questionNumber || itemIndex + 1,
+            questionText: item.content?.question || '',
+            options,
+            correctOptionId: correctId,
+            correctOptionIds: correctId ? [correctId] : [],
+            optionType: (item.content?.optionType || 'text'),
+        };
+    });
+    return {
+        questions: transformed,
+        example,
+        instruction: content?.meta?.instruction || 'Choose the correct answer.',
+    };
+}
+export function transformChooseCorrectAdjective(questions) {
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const sentence = content.sentence || '';
+        // Parse sentence with {0} placeholder ([\s\S] crosses newlines)
+        const match = sentence.match(/^([\s\S]*?)\{0\}([\s\S]*)$/);
+        const sentenceBefore = match ? match[1] : sentence;
+        const sentenceAfter = match ? match[2] : '';
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            sentenceBefore,
+            sentenceAfter,
+            options: (content.options || []).map((opt, idx) => ({
+                id: `${q.id}-opt-${idx}`,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+                text: opt,
+            })),
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: 'CHOOSE THE CORRECT ADJECTIVE',
+    };
+}
+export function transformWriteShortLetter(question) {
+    const content = question.content;
+    // New structure: use instructions.mainInstruction as prompt, informations as requirements
+    if (content.instructions?.mainInstruction || content.informations?.length) {
+        return {
+            prompt: content.instructions?.mainInstruction || '',
+            requirements: content.informations,
+            minWords: content.minWords,
+            maxWords: content.maxWords,
+            guideImages: content.guideImages,
+        };
+    }
+    // Legacy structure: build prompt from contexts array
+    const prompt = content.contexts
+        ?.filter((c) => c.type === 'text')
+        .map((c) => c.text)
+        .join('\n') || '';
+    return {
+        prompt,
+        minWords: content.minWords,
+        maxWords: content.maxWords,
+        guideImages: content.guideImages,
+    };
+}
+export function transformColorObjects(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    // Map colorNodes to hintItems format
+    const hintItems = content?.colorNodes?.map((node) => ({
+        id: node.id,
+        color: node.color,
+        label: node.label,
+    })) ||
+        content?.hintItems ||
+        [];
+    // Map regionNodes to regions format
+    const regions = content?.regionNodes?.map((node) => ({
+        id: node.id,
+        x: node.x,
+        y: node.y,
+        width: node.width,
+        height: node.height,
+        correctHintId: node.linkedColorNodeId,
+    })) ||
+        content?.regions ||
+        [];
+    // Get raw instructions array for numbered list display
+    const instructionsArray = content?.instructions;
+    // Get instruction text (joined or single)
+    const instruction = (instructionsArray && instructionsArray.length > 0
+        ? instructionsArray.join(' ')
+        : content?.instruction) || 'READ AND COLOR THE OBJECTS';
+    return {
+        instruction,
+        instructions: instructionsArray,
+        imageUrl: content?.backgroundImageUrl || content?.imageUrl || '',
+        audioUrl: content?.audioUrl,
+        hintItems,
+        regions,
+    };
+}
+export function transformPictureChoose(questions) {
+    const firstContent = questions[0]?.content;
+    const subQuestions = questions.map((q) => {
+        const content = q.content;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            imageUrl: content.imageUrl || '',
+            questionText: content.questionText,
+            options: (content.options || []).map((opt, idx) => ({
+                id: opt.id || `${q.id}-opt-${idx}`,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+                text: typeof opt === 'string' ? opt : opt.text,
+            })),
+        };
+    });
+    return {
+        subQuestions,
+        instruction: firstContent?.instruction || 'LOOK AT THE PICTURE AND CHOOSE THE CORRECT ANSWER',
+    };
+}
+export function transformPictureFillBlankChoose(questions) {
+    const firstContent = questions[0]?.content;
+    const subQuestions = questions.map((q) => {
+        const content = q.content;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            imageUrl: content.imageUrl || '',
+            question: content.question || '',
+            options: (content.options || []).map((opt, idx) => ({
+                id: opt.id || `${q.id}-opt-${idx}`,
+                label: OPTION_LABELS[idx] || String(idx + 1),
+                text: typeof opt === 'string' ? opt : opt.text,
+            })),
+        };
+    });
+    return {
+        subQuestions,
+        instruction: firstContent?.instruction ||
+            'LOOK AT THE PICTURE, FILL IN THE BLANK AND CHOOSE THE ANSWER',
+    };
+}
+/**
+ * Detect if data uses new format (separate questions with questionGroup)
+ * New format: content has 'question' field (not 'questions' array)
+ * AND questionGroup.payload has passage
+ */
+function isNewReadingPassageFormat(questions) {
+    const first = questions[0];
+    if (!first)
+        return false;
+    const content = first.content;
+    return (content?.question !== undefined &&
+        !content?.questions &&
+        first.questionGroup?.payload?.passage !== undefined);
+}
+export function transformReadingPassage(questions) {
+    if (isNewReadingPassageFormat(questions)) {
+        // NEW FORMAT: Multiple questions with shared questionGroup.payload
+        const firstQuestion = questions[0];
+        const groupPayload = firstQuestion.questionGroup?.payload || {};
+        const transformedQuestions = questions.map((q) => {
+            const content = q.content;
+            return {
+                id: q.id,
+                questionNumber: q.question_number,
+                questionText: content?.question || '',
+                options: (content?.options || []).map((opt, idx) => ({
+                    id: `${q.id}-opt-${idx}`,
+                    label: OPTION_LABELS[idx] || String(idx + 1),
+                    text: typeof opt === 'string' ? opt : String(opt),
+                })),
+            };
+        });
+        return {
+            passage: groupPayload.passage || '',
+            passageTitle: groupPayload.passageTitle,
+            passageImageUrl: groupPayload.passageImageUrl || groupPayload.mainImageUrl,
+            instruction: groupPayload.instructions || 'READ THE PASSAGE AND ANSWER QUESTIONS',
+            questions: transformedQuestions,
+        };
+    }
+    // OLD FORMAT: Single question with embedded sub-questions in content.questions[]
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    const subQuestions = content?.questions?.map((sq, idx) => ({
+        id: sq.id || `${firstQuestion.id}-sq-${idx}`,
+        questionNumber: idx + 1,
+        questionText: sq.question,
+        options: (sq.options || []).map((opt, optIdx) => ({
+            id: `${sq.id || firstQuestion.id}-opt-${optIdx}`,
+            label: OPTION_LABELS[optIdx] || String(optIdx + 1),
+            text: opt,
+        })),
+    })) || [];
+    return {
+        passage: content?.passage || '',
+        passageTitle: content?.passageTitle,
+        passageImageUrl: content?.passageImageUrl || content?.mainImageUrl,
+        instruction: content?.instructions?.mainInstruction || 'READ THE PASSAGE AND ANSWER QUESTIONS',
+        questions: subQuestions,
+    };
+}
+export function transformLabelPicture(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    return {
+        imageUrl: content?.imageUrl || '',
+        wordBank: content?.wordBank || [],
+        labels: content?.labels?.map((l) => ({
+            id: l.id,
+            number: l.number,
+            isPreFilled: l.isPreFilled || false,
+            correctAnswer: l.correctAnswer, // From questionContent for preFilled labels
+        })) || [],
+        instruction: content?.instruction || 'LABEL THE PICTURE',
+    };
+}
+/**
+ * Detect if content uses new format (single word with {n} placeholders)
+ */
+function isNewFillWordHintFormat(content) {
+    return content && typeof content.word === 'string' && !content.subQuestions;
+}
+/**
+ * Parse word string with numbered placeholders like "c{0}t, {1}lephan"
+ * Returns array of parsed blanks with their segments
+ */
+function parseNumberedPlaceholders(word) {
+    const results = [];
+    // Split by comma to handle multiple words like "c{0}t, {1}lephan"
+    const wordSegments = word.split(',').map((s) => s.trim());
+    for (const segment of wordSegments) {
+        // Find all placeholders in this segment
+        let match;
+        const segmentRegex = /\{(\d+)\}/g;
+        while ((match = segmentRegex.exec(segment)) !== null) {
+            const placeholderIndex = parseInt(match[1], 10);
+            // Replace {n} with _ for display
+            const displayWord = segment.replace(match[0], '_');
+            results.push({
+                index: placeholderIndex,
+                displayWord,
+            });
+        }
+    }
+    // Sort by index to ensure correct order
+    results.sort((a, b) => a.index - b.index);
+    return results;
+}
+export function transformFillWordHint(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    // MULTI-QUESTION FORMAT: Multiple separate questions with same group_id
+    // Each has own id, imageUrl, and single {0} placeholder
+    if (questions.length > 1 && questions.every((q) => isNewFillWordHintFormat(q.content))) {
+        const hintLetters = firstQuestion.questionGroup?.payload?.hintLetters || [];
+        const subQuestions = questions.map((q) => {
+            const qContent = q.content;
+            // Replace {0} with underscore for display
+            const displayWord = qContent.word.replace(/\{\d+\}/, '_');
+            return {
+                id: q.id, // Use actual question ID (not synthetic)
+                questionNumber: q.question_number,
+                imageUrl: qContent.imageUrl || '',
+                word: displayWord,
+                // No blankIndex → triggers OLD FORMAT rendering (grid with individual images)
+            };
+        });
+        return {
+            subQuestions,
+            hintLetters,
+            instruction: content?.instruction ||
+                'LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER',
+        };
+    }
+    // Detect format and transform accordingly
+    if (isNewFillWordHintFormat(content)) {
+        // NEW FORMAT: Single word with {0}, {1} placeholders
+        const newContent = content;
+        // Get hintLetters from questionGroup.payload (new location)
+        const hintLetters = firstQuestion.questionGroup?.payload?.hintLetters || [];
+        // Parse the word string to extract placeholders
+        const placeholders = parseNumberedPlaceholders(newContent.word);
+        // Create sub-questions for each placeholder
+        const subQuestions = placeholders.map((p) => ({
+            id: `${firstQuestion.id}-blank-${p.index}`,
+            questionNumber: firstQuestion.question_number,
+            imageUrl: newContent.imageUrl || '',
+            word: p.displayWord,
+            blankIndex: p.index,
+        }));
+        return {
+            subQuestions,
+            hintLetters,
+            instruction: newContent.instruction ||
+                'LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER',
+        };
+    }
+    // OLD FORMAT: subQuestions array with individual images
+    const oldContent = content;
+    const subQuestions = oldContent?.subQuestions?.map((sq, idx) => ({
+        id: sq.id,
+        questionNumber: firstQuestion.question_number + idx,
+        imageUrl: sq.imageUrl || '',
+        word: sq.word || '',
+    })) || [];
+    // Try hintLetters from content first, then from questionGroup.payload
+    const hintLetters = oldContent?.hintLetters ||
+        firstQuestion.questionGroup?.payload?.hintLetters ||
+        [];
+    return {
+        subQuestions,
+        hintLetters,
+        instruction: oldContent?.instruction ||
+            'LOOK AT THE PICTURE AND FILL IN THE MISSING LETTER',
+    };
+}
+export function transformGridFill(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    return {
+        grid: content?.grid || [],
+        rows: content?.rows || 0,
+        columns: content?.columns || 0,
+        instruction: content?.instruction || 'FILL IN THE MISSING WORDS',
+        disabledCells: content?.disabledCells || [],
+    };
+}
+export function transformAnswerTheQuestion(questions) {
+    const firstQuestion = questions[0];
+    const groupPayload = firstQuestion?.questionGroup?.payload;
+    const firstContent = firstQuestion?.content;
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const isExample = q.is_example || content.isExample || false;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            question: (content.question || '').replace(/\{\d+\}/g, '______'),
+            imageUrl: content.imageUrl,
+            prefixText: content.prefixText,
+            suffixText: content.suffixText,
+            suggestedAnswers: content.suggestedAnswers,
+            isExample,
+            exampleAnswer: isExample ? q.correct_answer?.answer : undefined,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: 'ANSWER THE QUESTION',
+        imageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl || firstContent?.imageUrl,
+        title: firstContent?.title,
+        groupContent: groupPayload?.groupContent || firstContent?.groupContent,
+    };
+}
+export function transformTrueFalse(questions) {
+    const groupPayload = questions[0]?.questionGroup?.payload;
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const isExample = q.is_example || content.isExample || false;
+        const exampleCorrectAnswer = isExample && typeof q.correct_answer?.answer === 'boolean'
+            ? q.correct_answer.answer
+            : undefined;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            question: content.question || '',
+            imageUrl: content.imageUrl,
+            isExample,
+            exampleCorrectAnswer,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: 'READ AND CHOOSE TRUE OR FALSE',
+        imageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl,
+        groupContent: groupPayload?.content || groupPayload?.groupContent,
+    };
+}
+// ============================================
+// TRUE_FALSE_GROUP Transformer
+// ============================================
+export function transformTrueFalseGroup(questions) {
+    const parent = questions[0];
+    const content = parent?.content;
+    const items = Array.isArray(content?.items) ? content.items : [];
+    const parentCorrect = Array.isArray(parent?.correct_answer?.answer)
+        ? parent.correct_answer.answer
+        : [];
+    const transformed = items.map((item, index) => {
+        const isExample = item.isExample === true;
+        const exampleCorrectAnswer = isExample && typeof (item.correctAnswer?.answer ?? parentCorrect[index]) === 'boolean'
+            ? (item.correctAnswer?.answer ?? parentCorrect[index])
+            : undefined;
+        return {
+            id: `${parent.id}-item-${index}`,
+            questionNumber: item.questionNumber || index + 1,
+            question: item.content?.question || '',
+            isExample,
+            exampleCorrectAnswer,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: content?.meta?.instruction || 'READ AND CHOOSE TRUE OR FALSE',
+    };
+}
+export function transformWordOrdering(questions) {
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const isExample = q.is_example || content.isExample || false;
+        const exampleAnswer = Array.isArray(q.correct_answer?.answer)
+            ? q.correct_answer.answer
+            : Array.isArray(content.answer)
+                ? content.answer
+                : undefined;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            words: content.words || [],
+            imageUrl: content.imageUrl,
+            isExample,
+            exampleAnswer: isExample ? exampleAnswer : undefined,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: 'ARRANGE THE LETTERS TO MAKE A WORD',
+    };
+}
+export function transformWordFillParagraph(questions) {
+    const firstQuestion = questions[0];
+    const groupPayload = firstQuestion?.questionGroup?.payload;
+    const content = firstQuestion?.content;
+    // Try to find title in content of any question or fallback to group payload
+    const title = content?.title || groupPayload?.title || questions.find(q => q.content?.title)?.content?.title;
+    // Normalize wordBank: handle both string[] (legacy DB format) and WordBankItem[] formats
+    const rawWordBank = content?.wordBank || [];
+    const wordBank = rawWordBank.map((item) => typeof item === 'string' ? { word: item } : item);
+    const storedViewMode = content?.viewMode;
+    const hasOptions = content?.wordBank?.[0]?.options !== undefined;
+    let viewMode;
+    if (storedViewMode === 'EMAIL') {
+        viewMode = 'EMAIL';
+    }
+    else if (!storedViewMode && (content?.emailFrom || content?.emailTo)) {
+        // Defensive fallback: if viewMode is null/undefined but email fields are present, treat as EMAIL
+        viewMode = 'EMAIL';
+    }
+    else if (storedViewMode === 'DEFAULT') {
+        viewMode = 'DEFAULT';
+    }
+    else if (storedViewMode === 'WITH_OPTIONS' || hasOptions) {
+        viewMode = 'WITH_OPTIONS';
+    }
+    else if (!storedViewMode && rawWordBank.length === 0) {
+        viewMode = 'DEFAULT';
+    }
+    else {
+        viewMode = 'WITH_WORD_BANK';
+    }
+    const emailFrom = content?.emailFrom || content?.metadata?.emailFrom;
+    const emailTo = content?.emailTo || content?.metadata?.emailTo;
+    return {
+        questionId: firstQuestion?.id || '',
+        paragraph: content?.paragraph || '',
+        title,
+        imageUrl: content?.imageUrl,
+        wordBank,
+        viewMode,
+        instruction: 'READ AND FILL IN THE BLANKS',
+        exampleAnswer: content?.exampleAnswer,
+        emailFrom,
+        emailTo,
+    };
+}
+export function transformMatchByWritingAnswer(questions) {
+    const groupPayload = questions[0]?.questionGroup?.payload;
+    const isConversation = questions.some((q) => !!q.content?.askerName);
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const isExample = q.is_example || content.isExample || false;
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            question: content.question || '',
+            imageUrl: content.imageUrl,
+            isExample,
+            exampleAnswer: isExample ? q.correct_answer?.answer : undefined,
+            askerName: content.askerName,
+            answererName: content.answererName,
+        };
+    });
+    const options = groupPayload?.options?.map((opt) => ({
+        answer: opt.answer,
+        imageUrl: opt.imageUrl || '',
+        content: opt.content || '',
+    })) || [];
+    const firstConversationQ = isConversation
+        ? questions[0]?.content
+        : undefined;
+    return {
+        questions: transformed,
+        options,
+        instruction: 'LOOK AND WRITE THE ANSWER',
+        viewMode: isConversation ? 'CONVERSATION' : 'DEFAULT',
+        groupImageUrl: groupPayload?.groupImageUrl || '',
+        askerName: firstConversationQ?.askerName,
+        answererName: firstConversationQ?.answererName,
+    };
+}
+export function transformWriteSentences(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    const groupPayload = firstQuestion?.questionGroup?.payload;
+    return {
+        questions: questions.map((q) => ({
+            id: q.id,
+            questionNumber: q.question_number,
+        })),
+        instruction: content?.instruction || 'WRITE SENTENCES ABOUT THE PICTURE',
+        imageUrl: groupPayload?.mainImageUrl || groupPayload?.imageUrl || content?.imageUrl,
+        title: content?.title,
+        groupContent: groupPayload?.groupContent || content?.groupContent,
+    };
+}
+function normalizeWfsfBlankStyle(raw) {
+    const v = String(raw || '').toLowerCase();
+    if (v === 'letter' || v === 'box')
+        return 'letter';
+    if (v === 'phrase' || v === 'sentence')
+        return 'phrase';
+    return 'word';
+}
+function normalizeWfsfWordBank(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const bank = raw.map((entry) => {
+        if (entry == null)
+            return null;
+        if (typeof entry !== 'object' || Array.isArray(entry))
+            return null;
+        const rec = entry;
+        if (Array.isArray(rec.options)) {
+            const options = rec.options
+                .map((o) => String(o ?? '').trim())
+                .filter((o) => o.length > 0);
+            return options.length >= 2 ? { options } : null;
+        }
+        const word = String(rec.word ?? '').trim();
+        if (word) {
+            const w = rec.isExample
+                ? { word, isExample: true }
+                : { word };
+            return w;
+        }
+        return null;
+    });
+    return bank.some((e) => e != null) ? bank : undefined;
+}
+export function transformWordFillStructuredForm(questions) {
+    const firstQuestion = questions[0];
+    const groupPayload = firstQuestion?.questionGroup?.payload;
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const correctAnswer = q.correct_answer || {};
+        // Resolve content: prefer single `content` string, fallback to merging old `blocks[]`
+        let resolvedContent = content?.content || '';
+        const blocks = content?.blocks;
+        if (!resolvedContent && blocks?.length) {
+            resolvedContent = blocks
+                .map((b) => {
+                const heading = b.heading ? `<h3>${b.heading}</h3>` : '';
+                return heading + (b.content || '');
+            })
+                .join('');
+        }
+        const wordBank = normalizeWfsfWordBank(content?.wordBank);
+        const hasOptions = Boolean(wordBank?.some((e) => e != null && 'options' in e && Array.isArray(e.options)));
+        const hasWords = Boolean(wordBank?.some((e) => e != null && 'word' in e && e.word));
+        const viewMode = content?.viewMode ||
+            (hasOptions ? 'WITH_OPTIONS' : hasWords ? 'WITH_WORD_BANK' : undefined);
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            title: content?.title || '',
+            imageUrl: content?.imageUrl,
+            content: resolvedContent,
+            answers: correctAnswer?.answers || {},
+            caseSensitive: correctAnswer?.caseSensitive ?? content?.caseSensitive ?? false,
+            blankStyle: normalizeWfsfBlankStyle(content?.blankStyle),
+            ...(viewMode ? { viewMode } : {}),
+            ...(wordBank ? { wordBank } : {}),
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: groupPayload?.instructions || 'COMPLETE THE FORM BELOW',
+        groupTitle: groupPayload?.title,
+        groupContent: groupPayload?.content,
+        groupImageUrl: groupPayload?.imageUrl,
+        audioUrl: firstQuestion?.audio_url || groupPayload?.audioUrl,
+    };
+}
+export function transformListenChooseObjects(questions) {
+    const firstQuestion = questions[0];
+    const content = firstQuestion?.content;
+    const groupPayload = firstQuestion?.questionGroup?.payload || {};
+    return {
+        audioUrl: content?.audioUrl || '',
+        backgroundImageUrl: groupPayload.backgroundImageUrl || '',
+        objectNodes: (groupPayload.objectNodes || []),
+        // Backend returns correctAnswer in review mode (snake_case or camelCase)
+        correctObjectId: firstQuestion?.correctAnswer?.objectId ||
+            firstQuestion?.correct_answer?.objectId ||
+            '',
+        isBackup: content?.isBackup || false,
+        instruction: 'LISTEN AND CHOOSE THE CORRECT OBJECT',
+    };
+}
+export function transformListenSpeakAnswer(questions) {
+    const transformed = questions.map((q) => {
+        const content = q.content;
+        const groupPayload = q.questionGroup?.payload || {};
+        return {
+            id: q.id,
+            questionNumber: q.question_number,
+            audioUrl: content?.audioUrl || '',
+            arrowNode: content?.arrowNode,
+            backgroundImageUrl: groupPayload.backgroundImageUrl || groupPayload.imageUrl || '',
+            isBackup: content?.isBackup || false,
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: 'LISTEN AND SPEAK YOUR ANSWER',
+    };
+}
+export function transformWordOrderAndMatchGroup(questions) {
+    const parent = questions[0];
+    const rawContent = (parent?.content || {});
+    const rawList = parent?.wordOrderMatchList || rawContent.wordOrderMatchList || rawContent;
+    const meta = rawList.meta || rawContent.meta || {};
+    const items = Array.isArray(rawList.items)
+        ? rawList.items
+        : Array.isArray(rawContent.items)
+            ? rawContent.items
+            : [];
+    const parentCorrect = Array.isArray(parent?.correct_answer?.answer)
+        ? parent.correct_answer.answer
+        : [];
+    const matchOptions = Array.isArray(meta.matchOptions)
+        ? meta.matchOptions.map((opt) => String(opt || '').trim().toUpperCase()).filter(Boolean)
+        : ['A', 'B', 'C', 'D', 'E', 'F'];
+    const transformed = items.map((item, index) => {
+        const rawItemContent = item?.content || {};
+        const scrambledWords = Array.isArray(rawItemContent.scrambledWords)
+            ? rawItemContent.scrambledWords.map((w) => String(w || '').trim()).filter(Boolean)
+            : [];
+        const correctAnswerRaw = item?.correctAnswer || item?.correct_answer || {};
+        const answerObj = correctAnswerRaw.answer && typeof correctAnswerRaw.answer === 'object'
+            ? correctAnswerRaw.answer
+            : correctAnswerRaw && typeof correctAnswerRaw === 'object' && (correctAnswerRaw.orderedPhrase || correctAnswerRaw.matchLabel)
+                ? correctAnswerRaw
+                : parentCorrect[index] || {};
+        const orderedPhrase = typeof answerObj.orderedPhrase === 'string' ? answerObj.orderedPhrase : '';
+        const matchLabel = typeof answerObj.matchLabel === 'string' ? answerObj.matchLabel.toUpperCase() : 'A';
+        const isExample = item?.isExample === true;
+        return {
+            id: `${parent?.id || 'q'}-item-${index}`,
+            questionNumber: item.questionNumber || index + 1,
+            scrambledWords,
+            orderedPhrase,
+            matchLabel,
+            isExample,
+            points: isExample ? 0 : (typeof item.points === 'number' ? item.points : 1),
+        };
+    });
+    return {
+        questions: transformed,
+        instruction: meta.instruction ||
+            'Put the useful phrases in order, then match them to parts A–F in Exercise 4.',
+        matchOptions,
+        explanation: parent?.explanation,
+    };
+}